API Reference: X-ray Forward Modelling Block

Scanner Geometry Module, ScannerTemplate
Attenuation Data Module, MuDatabaseHandler

Scanner Geometry Module, ScannerTemplate

See Forward Model for the description and usage of the module.

Methods:

__init__()	Constructor
set_recon_geometry()	Creates geometric model based on specifications provided during intialization
run_fwd_projector()	Perform forward projection on input 3D data to generate X-ray projection data()
reconstruct_data()	Reconstructs 3D volumetric image from input projection data
projn_generator()	Runs forward projector on a volume to generate its projection

Attributes:

recon_geometry	dictionary for reconstruction geometry
machine_geometry	dictionary for machine geometry
recon_params	dictionary for user-specified reconst. parameters
proj_geom	ASTRA object created by the class instance
vecs	array of vectors specifying position of each CT detector in the frame of reference of the isocenter.

Method Descriptions:

def __init__(self,geometry=‘cone’,scan=‘spiral’, machine_dict=None, recon=‘fbp’, recon_dict=None)

Desc.:	Constructor for ScannerTemplate(). The dictionary specifications in machine_dict, recon_dict must match the type of scanner geometry. The different supported types are ‘cone’-Cone Beam CT, ‘parallel’- Parallel Beam CT and ‘fan’ - Fan Beam CT. Models can be constructed for both circular and helical motion paths for data acquisition (through argument scan). Image Reconstruction can be done using either wFBP (using FreeCT_wFBP) or SIRT (ASTRA).
Args.:	geometry: {‘cone’\| ‘parallel’ \| ‘fan’}, str - type of scanner geometry (Limited support for ‘fan’ or ‘parallel’ in this version)
	scan: {‘spiral’, ‘circular’}, str - Scanner data acquisition path
	machine_dict: dict - dictionary for machine geometry
	recon: {‘fbp’ \| ‘sirt’}, str - Type of reconstruction algorithm used
	recon_dict: dict - dictionary for reconstruction parameters.
Return:	-

def set_recon_geometry(self)

Desc.:	Sets up CT Scanner geometry as per the input arguments and specifications during initialization.
Args.:	-
Returns.:	-

def run_fwd_projector(self, vol_data, verbose=False)

Desc.:	Forward the input 3D volume to create X-ray projection data for the scanner. The function is overloaded to support the different scanner geometries.
Args.:	vol_data: 3D ndarray of float - 3D volumetric image to be projected dim.: gantry_diameter x gantry_diametry x no_of_slices)
	verbose: bool - Set to True to print results on the terminal
Return:	projection data (dim.: n_rows x n_cols x (n_views*n_rot))

def reconstruct_data(self, sino)

This function operates differently for different scanner geometries as shown ahead:

(for 3D-SIRT) def reconstruct_data(self, sino, n_iter=100, sino_mask=None)

Desc.:	For recon=‘sirt’ and scan=‘circular’. Run SIRT3D algorithm to reconstruct volume from projection data for CBCT. For details of the algorithm see ASTRA’s SIRT3D_CUDA algorithm.
Args.:	sino: 3D ndarray of float - input projection data
	n_iter: int - number of iterations for SIRT
	sino_mask: 3D ndarray of bool - portion of the sinogram to skip
Return:	reconstructed 3D image

def reconstruct_data(self, data, full_range=False, flags=’’,show_plots=False, append_air_turns=False, full_range=False, clip_for_annotation=True)


Desc.:	For recon=‘fbp’ and scan=‘spiral’. Runs FreeCT wFBP algorithm on data. Takes in three turns of data, returns only the reconstruction for the central turn if the full_range option is not turned on. For details of the algorithm, check \reconstructor\FreeCT\ and the paper [4] [5]
Args.:	data: 3D ndarray of float32 - sinogram data of the dimensions n_channels x n_rows x n_views
	flags: dict - flags for running fct_wfbp
	full_range: bool - whether cover full range skip the padding turns
	append_air_turns: bool -add additional turns to avoid cropped reconstructions
	show_plots: bool - display reconstructed image after operation
	clip_for_annotation: bool -crops image to align with theground truth label image
Return:	reconstructed data, (row x column x z)

[4]. J. Hoffman, S. Young, F. Noo, M. McNitt-Gray, “Technical Note: FreeCT_wFBP: A robust, efficient, open-source implementation of weighted filtered backprojection for helical, fan-beam CT,” Med. Phys., vol. 43, no. 3, pp. 1411-1420, Feb. 2016.

[5]. K. Stierstorfer, A. Rauscher, J. Boese, H. Bruder, S. Schaller, and T. Flohr, “Weighted FBP—a simple approximate 3D FBP algorithm for multislice spiral CT with good dose usage for arbitrary pitch,” Phys. Med. Biol., vol. 49, no. 11, pp. 2209–2218, Jun. 2004.

def projn_generator(self, vol_data):


Desc.	Function that runs that forward model projector to create CT projections of input volumetric data.
Args.	vol_data: 3D torch.Tensor - 3D volumetric image
Return	projn: 2D/3D torch.Tensor- torch Tensor represent representing the X-ray projection (this is raw projection - not log attenuation)

Attenuation Data Module, MuDatabaseHandler

See Forward Model for its description.

Methods

__init__()	Constructor
create_compound_mu()	Create attenuation data for a compound specified by its molecular formula and density in g/cc
create_targets_mu()	Create attenuation data for a target material specified by its molecular formula and density in g/cc
create_mixture_mu()	Create attenuation data for a target material specified by its molecular formula and density in g/cc
material()	Get attenuation data for a specified material
calculate_lac_hu_values()	Calculate the LAC / Hounsfeld for a given material and spectral model

Attributes

element	dictionary of periodic leement from Z = 1-100
compound	dictionary of current compounds retained by the mu_handler
target	dictionary of current targets retained by the mu_handler
curr_compounds_list	list of compounds currently saved in DEBISim
curr_targets_list	list of compounds currently saved in DEBISim
elements_list	list of the atomic symbols of all elements
f_loc	dictionary of dbase file locations in DEBiSim
kev_range	Current Energy range for attenuation curves (default: 10 - 161 keV with 1 keV)
materials_list	list of all saved materials including elements, compounds and targets

Method Description

def __init__(self)

Desc.	Constructor for MuDatabaseHandler().
Args.	-
Return	-

def create_compound_mu(self, compound_formula, compound_name, density)

Desc.	Generate Attenuation data for a given compound specified by its chemical formula and density
Args.	compound_formula: str - Molecular formula for a compound, specify in expanded form with element number followed by subscript, for e.g., for milk of magnesia (Mg(OH)_2), specify compound_formula=‘MgO2H2’
	compound_name: str - Name to be assigned to the material
	density: float - Density of the compound in g/cm^2
Return	-

def create_targets_mu(self, target_formula, target_name, density)

Desc.	Generate Attenuation data for a given target specified by its chemical formula and density
Args.	target_formula: str - Molecular formula for a target, specify in expanded form with element number followed by subscript, for e.g., for milk of magnesia (Mg(OH)_2), specify target_formula=‘MgO2H2’
	target_name: str - Name to be assigned to the material
	density: float - Density of the target in g/cm^2
Return	-

def create_mixture_mu(self, mixture_name, component_list, is_target=True)

Desc.	Generate Attenuation data for a given mixture of compounds
Args.	mixture_name: str - Name assigned to the material
	component_list: list - List of tuples of the components of the mixture in the form: (formula, fraction, density in g/cc)
	is_target: bool - set to True if the material is a target
Return	-

def material(self, mat, prop=None)

Desc.	Function to read material / material properties.
Args.	mat: str - material name
	prop: str - material property: {‘compton’, ‘pe’, ‘z’, ‘mu’, ‘density’}
Return	material dictionary or property value

def calculate_lac_hu_values(self, mat, spectrum_list)


Desc.	Calculate the LAC and HU values for the given material and spectrum
Args.	mat: str - material name
	spectrum_list: 1D array of float or list - spectrum array or list of 1D spectra
Return