mbircone.preprocess

Functions:

`NSI_load_scans_and_params`(config_file_path, ...)	Load the object scan, blank scan, dark scan, view angles, defective pixel information, and geometry parameters from an NSI dataset directory.
`transmission_CT_compute_sino`(obj_scan, ...)	Given a set of object scans, blank scan, and dark scan, compute the sinogram data with the steps below:
`calc_background_offset`(sino[, option, ...])	Given a sinogram, automatically calculate the background offset based on the selected option.
`calc_weights`(sino, weight_type[, ...])	Compute the weights used in MBIR reconstruction.
`calc_weights_mar`(sino, angles, ...[, beta, ...])	Compute the weights used for reducing metal artifacts in MBIR reconstruction.
`interpolate_defective_pixels`(sino, ...)	This function interpolates defective sinogram entries with the mean of neighboring pixels.
`correct_tilt`(sino[, weights, tilt_angle])	Correct the sinogram data (and sinogram weights if provided) according to the rotation axis tilt.

mbircone.preprocess.NSI_load_scans_and_params(config_file_path, geom_report_path, obj_scan_path, blank_scan_path, dark_scan_path, defective_pixel_path, downsample_factor=[1, 1], crop_region=[(0, 1), (0, 1)], view_id_start=0, view_angle_start=0.0, view_id_end=None, subsample_view_factor=1)[source]

Load the object scan, blank scan, dark scan, view angles, defective pixel information, and geometry parameters from an NSI dataset directory.

The scan images will be (optionally) cropped and downsampled.

A subset of the views may be selected based on user input. In that case, the object scan images and view angles corresponding to the subset of the views will be returned.

This function is specific to NSI datasets.

Arguments specific to file paths:

config_file_path (string): Path to NSI configuration file. The filename extension is ‘.nsipro’.

geom_report_path (string): Path to “Geometry Report.rtf” file. This file contains more accurate information regarding the coordinates of the first detector row and column.

obj_scan_path (string): Path to an NSI radiograph directory.

blank_scan_path (string): Path to a blank scan image, e.g. ‘dataset_path/Corrections/gain0.tif’

dark_scan_path (string): Path to a dark scan image, e.g. ‘dataset_path/Corrections/offset.tif’

defective_pixel_path (string): Path to the file containing defective pixel information, e.g. ‘dataset_path/Corrections/defective_pixels.defect’

Arguments specific to radiograph downsampling and cropping:

downsample_factor ([int, int]): [Default=[1,1]] Down-sample factors along the detector rows and channels respectively. By default no downsampling will be performed.

In case where the scan size is not divisible by downsample_factor, the scans will be first truncated to a size that is divisible by downsample_factor, and then downsampled.
crop_region ([(float, float),(float, float)] or [float, float, float, float]): [Default=[(0, 1), (0, 1)]]. Two fractional points [(row0, row1), (col0, col1)] defining the bounding box that crops the scans, where 0<=row0<=row1<=1 and 0<=col0<=col1<=1. By default no cropping will be performed.
row0 and row1 defines the cropping factors along the detector rows. col0 and col1 defines the cropping factors along the detector channels.
:       (0,0)--------------------------(0,1)
:         |  (row0,col0)---------------+     |
:         |     |                  |     |
:         |     | (Cropped Region) |     |
:         |     |                  |     |
:         |     +---------------(row1,col1)  |
:       (1,0)--------------------------(1,1)
For example, crop_region=[(0.25,0.75), (0,1)] will crop out the middle half of the scan image along the vertical direction.

Arguments specific to view subsampling:

view_id_start (int): [Default=0] view id corresponding to the first view.

view_angle_start (float): [Default=0.0] view angle in radian corresponding to the first view.

view_id_end (int): [Default=None] view id corresponding to the last view. If None, this will be equal to the total number of object scan images in obj_scan_path.

subsample_view_factor (int): [Default=1]: view subsample factor. By default no view subsampling will be performed.

For example, with subsample_view_factor=2, every other view will be loaded.

Returns:

6-element tuple containing –

obj_scan (ndarray, float): 3D object scan with shape (num_views, num_det_rows, num_det_channels)
blank_scan (ndarray, float): 3D blank scan with shape (1, num_det_rows, num_det_channels)
dark_scan (ndarray, float): 3D dark scan with shape (1, num_det_rows, num_det_channels)
angles (ndarray, double): 1D view angles array in radians in the interval \([0,2\pi)\).
geo_params: MBIRCONE format geometric parameters containing the following entries:
- dist_source_detector: Distance between the X-ray source and the detector in units of \(ALU\).
- magnification: Magnification of the cone-beam geometry defined as (source to detector distance)/(source to center-of-rotation distance).
- delta_det_channel: Detector channel spacing in \(ALU\).
- delta_det_row: Detector row spacing in \(ALU\).
- det_channel_offset: Distance in \(ALU\) from center of detector to the source-detector line along a row.
- det_row_offset: Distance in \(ALU\) from center of detector.
- rotation_offset: Distance in \(ALU\) from source-detector line to axis of rotation in the object space.
- num_det_channels: Number of detector channels.
- num_det_rows: Number of detector rows.
- rotation_axis_tilt: angle between the rotation axis and the detector columns in units of radians.
defective_pixel_list (list(tuple)): A list of tuples containing indices of invalid sinogram pixels, with the format (detector_row_idx, detector_channel_idx).

mbircone.preprocess.calc_background_offset(sino, option=0, edge_width=9)[source]

Given a sinogram, automatically calculate the background offset based on the selected option. Available options are:

Option 0: Calculate the background offset using edge_width pixels along the upper, left, and right edges of a median sinogram view.

Parameters:

sino (float, ndarray) – Sinogram data with 3D shape (num_views, num_det_rows, num_det_channels).
option (int, optional) – [Default=0] Option of algorithm used to calculate the background offset.
edge_width (int, optional) – [Default=9] Width of the edge regions in pixels. It must be an odd integer >= 3.

Returns:

offset (float) – Background offset value.

mbircone.preprocess.calc_weights(sino, weight_type, defective_pixel_list=None)[source]

Compute the weights used in MBIR reconstruction.

Parameters:

sino (float, ndarray) – Sinogram data with either 3D shape (num_views, num_det_rows, num_det_channels).
weight_type (string) – Type of noise model used for data
- weight_type = ‘unweighted’ => return numpy.ones(sino.shape).
- weight_type = ‘transmission’ => return numpy.exp(-sino).
- weight_type = ‘transmission_root’ => return numpy.exp(-sino/2).
- weight_type = ‘emission’ => return 1/(numpy.absolute(sino) + 0.1).
defective_pixel_list (list(tuple)) – A list of tuples containing indices of invalid sinogram pixels, with the format (view_idx, row_idx, channel_idx) or (row_dix, channel_idx). The corresponding weights of invalid sinogram entries are set to 0.0.

Returns:

(float, ndarray) – Weights used in mbircone reconstruction, with the same array shape as sino.

Raises:

Exception – Raised if weight_type is not one of the above options.

mbircone.preprocess.calc_weights_mar(sino, angles, dist_source_detector, magnification, init_recon, metal_threshold, beta=2.0, gamma=4.0, defective_pixel_list=None, delta_det_channel=1.0, delta_det_row=1.0, delta_pixel_image=None, det_channel_offset=0.0, det_row_offset=0.0, rotation_offset=0.0, image_slice_offset=0.0, num_threads=None, verbose=0, lib_path='/home/docs/.cache/mbircone')[source]

Compute the weights used for reducing metal artifacts in MBIR reconstruction. For more information please refer to the [theory] section in readthedocs.

Required arguments:

sino (ndarray): Sinogram data with 3D shape (num_det_rows, num_det_channels).
angles (ndarray): 1D array of view angles in radians.
dist_source_detector (float): Distance between the X-ray source and the detector in units of \(ALU\).
magnification (float): Magnification of the cone-beam geometry defined as (source to detector distance)/(source to center-of-rotation distance).
init_recon (ndarray): Initial reconstruction used to identify metal voxels.
metal_threshold (float): Threshold value in units of \(ALU^{-1}\) used to identify metal voxels. Any voxels in init_recon with an attenuation coefficient larger than metal_threshold will be identified as a metal voxel.

Optional arguments specific to MAR data weights:

beta (float, optional): [Default=2.0] Scalar value in range \(>0\).

A larger beta improves the noise uniformity, but too large a value may increase the overall noise level.
gamma (float, optional): [Default=4.0] Scalar value in range \(>1\).

A larger gamma reduces the weight of sinogram entries with metal, but too large a value may reduce image quality inside the metal regions.
defective_pixel_list (optional, list(tuple)): [Default=None] A list of tuples containing indices of invalid sinogram pixels, with the format (view_idx, row_idx, channel_idx).

weights=0.0 for invalid sinogram entries.

Optional arguments inherited from cone3D.project:

delta_det_channel (float, optional): [Default=1.0] Detector channel spacing in \(ALU\).
delta_det_row (float, optional): [Default=1.0] Detector row spacing in \(ALU\).
delta_pixel_image (float, optional): [Default=None] Image pixel spacing in \(ALU\).

If None, automatically set to delta_pixel_detector/magnification.
det_channel_offset (float, optional): [Default=0.0] Distance in \(ALU\) from center of detector to the source-detector line along a row.
det_row_offset (float, optional): [Default=0.0] Distance in \(ALU\) from center of detector to the source-detector line along a column.
rotation_offset (float, optional): [Default=0.0] Distance in \(ALU\) from source-detector line to axis of rotation in the object space.

This is normally set to zero.
image_slice_offset (float, optional): [Default=0.0] Vertical offset of the image in units of \(ALU\).
num_threads (int, optional): [Default=None] Number of compute threads requested when executed.

If None, num_threads is set to the number of cores in the system.
verbose (int, optional): [Default=1] Possible values are {0,1,2}, where 0 is quiet, 1 prints minimal reconstruction progress information, and 2 prints the full information.
lib_path (str, optional): [Default=~/.cache/mbircone] Path to directory containing library of forward projection matrices.

Returns:: (ndarray) – Weights used in mbircone reconstruction, with the same array shape as sino.

mbircone.preprocess.correct_tilt(sino, weights=None, tilt_angle=0.0)[source]

Correct the sinogram data (and sinogram weights if provided) according to the rotation axis tilt.

Parameters:

sino (float, ndarray) – Sinogram data with 3D shape (num_views, num_det_rows, num_det_channels).
weights (float, ndarray) – Weights used in mbircone reconstruction, with the same array shape as sino.
tilt_angle (optional, float) – tilt angle between the rotation axis and the detector columns in unit of radians.

Returns:

A numpy array containing the corrected sinogram data if weights is None.
A tuple (sino, weights) if weights is not None

mbircone.preprocess.interpolate_defective_pixels(sino, defective_pixel_list)[source]

This function interpolates defective sinogram entries with the mean of neighboring pixels.

Parameters:

sino (ndarray, float) – Sinogram data with 3D shape (num_views, num_det_rows, num_det_channels).
defective_pixel_list (list(tuple)) – A list of tuples containing indices of invalid sinogram pixels, with the format (detector_row_idx, detector_channel_idx) or (view_idx, detector_row_idx, detector_channel_idx).

Returns:

2-element tuple containing –

sino (ndarray, float): Corrected sinogram data with shape (num_views, num_det_rows, num_det_channels).
defective_pixel_list (list(tuple)): Updated defective_pixel_list with the format (detector_row_idx, detector_channel_idx) or (view_idx, detector_row_idx, detector_channel_idx).

mbircone.preprocess.transmission_CT_compute_sino(obj_scan, blank_scan, dark_scan, defective_pixel_list=None)[source]

Given a set of object scans, blank scan, and dark scan, compute the sinogram data with the steps below:

sino = -numpy.log((obj_scan-dark_scan) / (blank_scan-dark_scan)).

Identify the invalid sinogram entries. The invalid sinogram entries are indentified as the union of defective pixel entries (speicified by defective_pixel_list) and sinogram entries with values of inf or Nan.

Parameters:

obj_scan (ndarray, float) – 3D object scan with shape (num_views, num_det_rows, num_det_channels).
blank_scan (ndarray, float) – [Default=None] 3D blank scan with shape (num_blank_scans, num_det_rows, num_det_channels). When num_blank_scans>1, the pixel-wise mean will be used as the blank scan.
dark_scan (ndarray, float) – [Default=None] 3D dark scan with shape (num_dark_scans, num_det_rows, num_det_channels). When num_dark_scans>1, the pixel-wise mean will be used as the dark scan.
defective_pixel_list (optional, list(tuple)) – A list of tuples containing indices of invalid sinogram pixels, with the format (view_idx, row_idx, channel_idx) or (detector_row_idx, detector_channel_idx). If None, then the defective pixels will be identified as sino entries with inf or Nan values.

Returns:

2-element tuple containing –

sino (ndarray, float): Sinogram data with shape (num_views, num_det_rows, num_det_channels).
defective_pixel_list (list(tuple)): A list of tuples containing indices of invalid sinogram pixels, with the format (view_idx, row_idx, channel_idx) or (detector_row_idx, detector_channel_idx).