Python Documentation

VICTRE PIPELINE

Author: Miguel A. Lago

miguel.lago@fda.hhs.gov

DISCLAIMER

This software and documentation (the “Software”) were developed at the Food and Drug Administration (FDA) by employees of the Federal Government in the course of their official duties. Pursuant to Title 17, Section 105 of the United States Code, this work is not subject to copyright protection and is in the public domain. Permission is hereby granted, free of charge, to any person obtaining a copy of the Software, to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, or sell copies of the Software or derivatives, and to permit persons to whom the Software is furnished to do so. FDA assumes no responsibility whatsoever for use by other parties of the Software, its source code, documentation or compiled executables, and makes no guarantees, expressed or implied, about its quality, reliability, or any other characteristic. Further, use of this code in no way implies endorsement by the FDA or confers any advantage in regulatory decisions. Although this software can be redistributed and/or modified freely, we ask that any derivative works bear some notice that they are derived from it, and any modified versions bear some notice that they have been modified.

More information: https://github.com/DIDSR/VICTRE_PIPELINE

class Victre.Pipeline.Pipeline(ips={'cpu': 'localhost', 'gpu': 'localhost'}, seed=None, results_folder='./results', phantom_file=None, spectrum_file='./Victre/projection/spectrum/W28kVp_Rh50um_Be1mm.spc', lesion_file=None, materials=None, roi_sizes=None, arguments_generation={}, arguments_spiculated={}, arguments_mcgpu={}, arguments_recon={}, arguments_cluster={}, flatfield_DBT=None, flatfield_DM=None, density=None, verbosity=True)

Object constructor for the Victre pipeline class

Parameters

  • ips – Dictionary with two IP addresses to run the pipeline: “gpu” for the projection process. “cpu” for the reconstruction.

  • seed – Random seed used to generate or read the phantom

  • results_folder – Path to folder to be used when saving the results

  • phantom_file – Path to file containing the phantom to be loaded

  • spectrum_file – Path to file containing the spectrum used to project in MCGPU

  • lesion_file – Path to file containing the lesion to be inserted (in HDF5 format)

  • materials – Dictionary including the materials to be used during projection

  • roi_sizes – Dictionary with the ROI sizes for the extraction

  • arguments_generation – Arguments to be overriden for the breast phantom generation

  • arguments_mcgpu – Arguments to be overridden for the projection in MCGPU

  • arguments_recon – Arguments to be overridden for the reconstruction algorithm

  • flatfield_DBT – Path to the flatfield file for the DBT reconstruction

  • flatfield_DM – Path to the flatfield file for the digital mammography

  • density – [EXPERIMENTAL] Percentage of dense tissue of the phantom to be generated, this will adjust the compression thickness too

  • verbosity – True will output the progress of each process and steps

Returns

None

add_absent_ROIs(lesion_type, n=1, locations=None, roi_sizes=None, save_locations=True)

Adds the specified number of lesion-absent regions of interest.

Parameters

  • lesion_type – Constant with the desired lesion type. Check available lesion types and materials in the Constants file.

  • n – Number of lesions to be added

  • locations – List of coordinates in the voxel/phantom space where the lesions will be inserted. If not specified, random locations will be generated.

  • roi_sizes – Size of the region of interest to be calculated to avoid overlapping with other tissues and check out of bounds locations

Returns

None. A location file will be saved inside the phantom folder with the corresponding seed. Negative lesion type means absent ROI.

compress_phantom(thickness=None)

Runs the FEBio compression.

Parameters

thickness – Specifies the objective thickness for the phantom to be compressed (in cm)

Returns

None. A phantom file will be saved inside the results folder with the corresponding raw phantom. Two files will be generated: pc_SEED.raw.gz with the raw data, and pc_SEED.mhd with the information about the raw data.

crop(size=None)

Runs breast phantom cropping.

Returns

None. A phantom file will be saved inside the results folder with the corresponding raw phantom. Two files will be generated: pc_SEED_crop.raw.gz with the raw data, and pc_SEED_crop.mhd with the information about the raw data.

generate_phantom()

Runs breast phantom generation.

Returns

None. A phantom file will be saved inside the results folder with the corresponding raw phantom. Two files will be generated: p_SEED.raw.gz with the raw data, and p_SEED.mhd with the information about the raw data.

generate_spiculated(seed=None, size=None)

Generates a spiculated mass using the breastMass software

Parameters

  • seed – Seed to be used when generating the mass

  • size – Size of the mass to be used in the breastMass config file

Returns

None. The result is saved in the lesions subfolder

get_coordinates_dbt(vx_location)

Method to get the corresponding coordinates in the DBT volume from the voxelized coordinates

Parameters

vx_location – Coordinates in the voxel/phantom space

Returns

Coordinates in the DBT space

get_coordinates_dm(vx_location)

Method to get the corresponding coordinates in the DM volume from the voxelized coordinates

Parameters

vx_location – Coordinates in the voxel/phantom space

Returns

Coordinates in the DM space

static get_folder_contents(folder)

Gets a list of files in the given folder

Parameters

folder – Path to the folder to be processed

Returns

List with files inside the given folder

insert_lesions(lesion_type=None, n=-1, lesion_file=None, lesion_size=None, locations=None, roi_sizes=None, save_phantom=True)

Inserts the specified number of lesions in the phantom.

Parameters

  • lesion_type – Constant with the desired lesion type. Check available lesion types and materials in the Constants file.

  • n – Number of lesions to be added

  • lesion_file – Path to file including the lesion to be inserted (in HDF5 format). If specified, it will overrite the lesion file specified in the constructor.

  • lesion_size – If lesion_file is a raw file, lesion_size indicates the size of this file

  • locations – List of coordinates in the voxel/phantom space where the lesions will be inserted. If not specified, random locations will be generated.

  • roi_sizes – Size of the region of interest to be calculated to avoid overlapping with other tissues and check out of bounds locations

Returns

None. A phantom file will be saved inside the results folder with the corresponding raw phantom. Three files will be generated: pcl_SEED.raw.gz with the raw data, pcl_SEED.mhd with the information about the raw data, and pcl_SEED.loc with the voxel coordinates of the lesion centers.

project(flatfield_correction=True, clean=True, do_flatfield=0, for_presentation=False)

Method that runs MCGPU to project the phantom.

Parameters

  • flatfield_correction – If True, the projections will be corrected using a given flatfield. It will be generated if not found and not given.

  • clean – If True, it will delete the contents of the output folder before projecting.

  • do_flatfield – If > 0, it will generate an empty flat field projection.

reconstruct()

Method that runs the reconstruction code for the DBT volume

save_DICOM(modality='dbt')

Saves the DM or DBT images in DICOM format. If present, lesion location will be stored in a custom tag 0x009900XX where XX is the lesion number.

Parameters

modality – Modality to save: dbt or dm

save_ROIs(roi_sizes=None, clean=True, save_folder=None)

Saves the generated ROIs (absent and present) in RAW and HDF5 formats

Parameters

  • roi_sizes – Size of the ROIs for the defined lesion types

  • clean – If True, the existing ROI folder will be deleted