This module is used for running and managing the DEBIsim simulation pipeline and its various blocks. To learn more about using the DEBISim pipeline for data simulation, see Using DEBISim - Operation and Features.
| __init__() | Constructor |
| run_bag_generator() | Runs the Virtual Bag Generator block of the DEBISim pipeline. |
| run_fwd_model() | Runs the X-ray Forward modelling block of the DEBISim pipeline. |
| run_decomposer() | Runs the DE Decomposition block of the DEBISim pipeline |
| run_reconstructor() | Runs the reconstructor block of the DEBISim pipeline |
| create_random_simulation_instance() | Creates a random simulation instance using BaggageCreator3D |
| create_simulation_from_sl_file() | Creates simulaiton instance by reading in a shape list |
| generate_polychromatic_ct_projection() | Generate polychromatic projection for a single spectrum |
| save_dect_ground_truth_images() | Save the ground truth label/coefficient images |
| f_loc | dictionary containing file/directory locations for current simulation |
| gt_image_3d | Ground truth label image for the 3D virtual bag |
| image_shape_3d | dimensions of the baggage volume |
| keV_range | the keV range for the Xray spectrum |
| material_curve | 2D array containing attenuation curves of all the materials in the bag |
| maxkV | maximum keV value used for simulation |
| mu | instance of the MuDatabaseHandler() used by the pipeline toi mangae material properties |
| reconstruction_geometry | dictionary of reconstruction paprameters used by ScannerTemplate() in the pipeline. |
| scale | image scale |
| scanner_geometry | dictionary of machine geometry specifications used by ScannerTemplate() in the pipeline. |
| scanner | The scanner model used in the pipeline in the form of an instance of ScannerTemplate() . |
| sf_obj_list | Shape List for the simulation instance |
| slh | ShapeListHandle() object for the class |
| xray_source_model | dictionary of Xray source specifications used in initialization: {‘num_spectra’: number of spectra, ‘dosage’: list of dosage counts for each spectra, ‘spectrum’: list of path for each spectrum file (For format, see ./include/spectra/), ‘kVp’: list of tube voltages for each spectrum} |
| Desc. | Constructor for the DEBISimPipeline() Class. |
| Args. | sim_path: file, str - The path to simulation directory - when the simulation is complete this directory will be populated with the subdirectories images/, sinograms/ and ground_truth/ containing the simulated data. |
| scanner_model: obj - An instance of the ScannerTemplate where the scanner specifications are given. | |
| xray_source_model: dict - dictionary for the xray source specifications. See Module Description for details. | |
| mu_handler: obj - A MuDatabaseHandler object (optional) | |
| Return | - |
| Desc. | Runs the Virtual Bag generator block of the DEBISim pipeline. It can be run in two modes: (i) mode="randomized" which creates a randomized virtual bag using specifications from bag_creator_dict, (ii) mode='manual' which creates a virtual bag by reading a Shape List given by sf_file. |
| Args. | mode: str, options: {'randomized' | 'manual} - the mode in which the Virtual bag generator is run. |
| bag_creator_dict: dict - arguments for randomized baggage generation using BaggageImage3D(). | |
| sf_file: file, str or list - SL instance or file-path of the SL file for manual mode. | |
| sim_args: dict - additional optional arguments for methods: self.create_random_simulation_instance() or self.read_simulation_from_sf_file(). | |
| Return | - |
| Desc. | Runs the X-ray forward Modelling block of the DEBISim pipeline. Generates polychromatic projections for the virtual bag by iterating the function self.generate_polychromatic_ct_projection() over all the spectra in the model. |
| Args. | add_poisson_noise: bool - Set to True if Poisson noise is to be added. |
| add_system_noise: bool - Set to True if Gaussian shot noise is to be added. | |
| system_gain: float - Gain for Gaussian shot noise | |
| Return |
| Desc. | Runs the DE decompostion block in the DEBISim pipeline. The type of decomposition algorithm used is selected using the argument type and the decomposition parameters are fed in using decomposer_args. |
| Args. | type: str: options {'cdm' | 'sirz' | 'lutd'} - Option for decomposition algorithm. |
| decomposer_args: dict - Decomposition arguments for the selected decomposer - see the arguments for each algorithm in the Python API. | |
| basis_fn: 2-tuple of functions - substitute basis functions for Compton-PE bases if another set of bases is to be used. | |
| Return | - |
| Desc. | Runs the Reconstructor block in the DEBISim pipeline. reconstructs all the projections/line-integrals generated by the previous blocks and saves them in the /images/ folder of the working directory. |
| Args. | img_type: str: options {'HU' | 'MHU' | 'LAC'} - unit for reconstructed image: 'HU' - Hounsfield units, 'MHU' - Modified Hounsfield Units, 'LAC'- CT attenuation units in 1/cm. |
| recon: str, options: {'fbp' | 'sirt'} - Reconstruction algorithm | |
| Return | - |
| Desc. | Create a random simulation phantom from the randomized BaggageCreator3D. The functions also allows spawning randmized objects over a prior image. |
| Args. | baggage_creator_args: dict - arguments to run the BaggageImage3D.create_random_object_list() function. |
| prior_image: 3D ndarray of float - Prior image if needs to be included | |
| prior_list: list - Shape List of objects in the prior image | |
| save_images: list of str, options: {‘gt’, ‘compton’, ‘pe’, ‘zeff’, ‘lac_1’, ‘lac_2’} - ground truth images to save | |
| Return |
| Desc. | Function to initialize simulation by reading a shape list from a previously saved shape list. The function can voxelize a ground truth image from the shape list as long as it does not contain liquids or sheet objects, otherwise, gt_image needs to be provided. |
| Args. | sf_file: file, str or list - SL instance or file-path of the SL file. |
| gt_image: 3D ndarray of float - GT Label image corresponding to the shape file | |
| save_images: list of str, options: {‘gt’, ‘compton’, ‘pe’, ‘zeff’, ‘lac_1’, ‘lac_2’} - ground truth images to save | |
| Return |
| Desc. | Generate polyenergetic sinogram for the ground truthlabel image. The ground truth image must be generated prior to calling this function. The function generates the noisy polychromatic sinogram for the specified spectrum in the Xray source model dictionary, self.xray_source_model and saves it in the sino/ folder in the simulation directory. |
| Args. | add_poisson_noise: bool - Set to True if Poisson noise is to be added. |
| add_system_noise: bool - Set to True if Gaussian shot noise is to be added. | |
| system_gain: float - Gain for Gaussian shot noise | |
| spectrum: int - index of the spectrum as specified in self.xray_source_model. | |
| Return |
| Desc. | Save 3D image files generated by the phantom voxelizer as .fits.gz files. |
| Args. | images: list - The ground truth images to be saved. Options = {‘gt’, ‘compton’, ‘pe’, ‘zeff’, ‘lac_1’, ‘lac_2’} |
| Return |
This module is used for creating randomized baggage datasets from the DEBISim simulation pipeline. To learn more about using DEBISim dataset generation, see Using DEBISim - Operation and Features.
| Desc. | Function to generate a randomized baggage Dataset using the DEBISim pipeline - works by iterating the pipeline for randomized baggage generation. |
| Args. | num_bags: int - number of baggage instances to generate. |
| sim_dir: file, str - simulation directory | |
| scanner: obj - scanner model defined using ScannerTemplate() | |
| xray_src_mdl: dict - dictionary for Xray source specifications: { ‘num_spectra’ - No of X-ray sources/spectra, ‘kVp’ - peak kV voltage for the X-ray source(s), ‘spectra’ - file paths for the each of theX-ray spectra. The spectrum files must contain a N x 2 array with the keV values in the first column and normalized photon distribution in the 2nd column. See ./include/spectra/ for reference, ‘dosage’ - dosage count for eachsource } | |
| bag_creator_args: dict - The baggage creation arguments - this dictionary contains the input arguments to the method self.create_random_object_list() for BaggageImage3D() | |
| decomposer: obj - class object(s) for the DE Decompostion block, for e.g., CDMDecomposer(). | |
| decomposer_args: dict - Input arguments for the specified decomposer(s) | |
| performs_sirz: dict - Set to True if one of the specified decomposers performs SIRZ decomposition. | |
| img_suffixes: dict - suffixes for the image names for each of the saved image data. Default: img_suffixes = dict(cdm=[‘c’, ‘pe’, ‘z’], sirz=[‘ze’, ‘rho’]) | |
| Return | - |