Preprocess utilities

The preprocess module provides scanner-specific preprocessing and more general preprocessing to compute and correct the sinogram data. See demo_nsi.py in the mbirjax_applications repo for example uses.

NorthStar Instrument (NSI) functions

Functions:

compute_sino_and_params(dataset_dir[, ...])	Load NSI sinogram data and prepare all needed arrays and parameters for a ConeBeamModel reconstruction.
load_scans_and_params(dataset_dir[, ...])	Load the object scan, blank scan, dark scan, view angles, defective pixel information, and geometry parameters from an NSI scan directory.

mbirjax.preprocess.nsi.compute_sino_and_params(dataset_dir, downsample_factor=(1, 1), subsample_view_factor=1, crop_pixels_sides=None, crop_pixels_top=None, crop_pixels_bottom=None)

Load NSI sinogram data and prepare all needed arrays and parameters for a ConeBeamModel reconstruction.

This function computes the sinogram and geometry parameters from an NSI scan directory containing scan data and parameters. More specifically, the function performs the following operations in a single easy-to-use manner:

1. Loads the object, blank, and dark scans, as well as the geometry parameters from an NSI dataset directory.

2. Computes the sinogram from object, blank, and dark scans.

3. Replaces defective pixels with interpolated values.

4. Performs background offset correction to the sinogram from the edge pixels.

5. Corrects sinogram data to account for detector rotation.

Parameters:

• dataset_dir (string) – Path to an NSI scan directory. The directory is assumed to have the following structure:

  • *.nsipro (NSI config file)

  • Geometry*.rtf (geometry report)

  • Radiographs*/ (directory containing all radiograph images)

  • **/gain0.tif (blank scan image)

  • **/offset.tif (dark scan image)

  • **/*.defect (defective pixel information)

• downsample_factor ((int, int), optional) – If scan size is not divisible by downsample_factor, the scans will be first truncated to a size that is divisible by downsample_factor.

• subsample_view_factor (int, optional) – View subsample factor. By default no view subsampling will be performed.

• crop_pixels_sides (int, optional) – The number of pixels to crop from each side of the sinogram. Defaults to None, in which case the NSI config file is used.

• crop_pixels_top (int, optional) – The number of pixels to crop from top of the sinogram. Defaults to None, in which case the NSI config file is used.

• crop_pixels_bottom (int, optional) – The number of pixels to crop from bottom of the sinogram. Defaults to None, in which case the NSI config file is used.

Returns:

tuple –

[sinogram, cone_beam_params, optional_params]

sino (jax array): 3D sinogram data with shape (num_views, num_det_rows, num_det_channels). cone_beam_params (dict): Required parameters for the ConeBeamModel constructor. optional_params (dict): Additional ConeBeamModel parameters to be set using set_params().

Example

# Get data and recon parameters
sino, cone_beam_params, optional_params = mbirjax.preprocess.NSI.compute_sino_and_params(dataset_dir, downsample_factor=downsample_factor, subsample_view_factor=subsample_view_factor)

# Create the model and set the parameters
ct_model = mbirjax.ConeBeamModel(**cone_beam_params)
ct_model.set_params(**optional_params)
ct_model.set_params(sharpness=sharpness, verbose=1)

# Compute sinogram weights and do the reconstruction
weights = ct_model.gen_weights(sino, weight_type='transmission_root')
recon, recon_params = ct_model.recon(sino, weights=weights)

mbirjax.preprocess.nsi.load_scans_and_params(dataset_dir, view_id_start=0, view_id_end=None, subsample_view_factor=1)

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

This function loads the sinogram data and parameters from an NSI scan directory for users who would prefer to implement custom preprocessing of the data.

Parameters:

• dataset_dir (string) – Path to an NSI scan directory. The directory is assumed to have the following structure:

  • *.nsipro (NSI config file)

  • Geometry*.rtf (geometry report)

  • Radiographs*/ (directory containing all radiograph images)

  • **/gain0.tif (blank scan image)

  • **/offset.tif (dark scan image)

  • **/*.defect (defective pixel information)

• view_id_start (int, optional) – view index corresponding to the first view.

• view_id_end (int, optional) – view index corresponding to the last view. If None, this will be equal to the total number of object scan images in obj_scan_dir.

• subsample_view_factor (int, optional) – view subsample factor.

Returns:

tuple –

[obj_scan, blank_scan, dark_scan, cone_beam_params, optional_params, defective_pixel_list]

obj_scan (jax array): 3D object scan with shape (num_views, num_det_rows, num_det_channels). blank_scan (jax array): 3D blank scan with shape (1, num_det_rows, num_det_channels). dark_scan (jax array): 3D dark scan with shape (1, num_det_rows, num_det_channels). nsi_params (dict): Required parameters needed for convert_nsi_to_mbirjax_params(). defective_pixel_array (ndarray): An nx2 array containing indices of invalid sinogram pixels, with the format (detector_row_idx, detector_channel_idx).

General preprocess functions

Functions:

compute_sino_transmission(obj_scan, ...[, ...])	Compute sinogram from object, blank, and dark scans.
estimate_background_offset(sino[, edge_width])	Estimate background offset of a sinogram using JAX for GPU acceleration.
interpolate_defective_pixels(sino[, ...])	Interpolates defective sinogram entries with the mean of neighboring pixels.
correct_det_rotation(sino[, weights, ...])	Correct sinogram data and weights to account for detector rotation.
multi_threshold_otsu(image[, classes])	Segments an image into several different classes using Otsu's method.
export_recon_to_hdf5(recon, filename[, ...])	This function writes a reconstructed image to an HDF5 file.

mbirjax.preprocess.compute_sino_transmission(obj_scan, blank_scan, dark_scan, defective_pixel_array=(), batch_size=90)

Compute sinogram from object, blank, and dark scans.

This function computes sinogram by taking the negative log of the attenuation estimate. It can also take in a list of defective pixels and correct those pixel values. The invalid sinogram entries are the union of defective pixel entries 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_array (optional, ndarray) – 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 invalid pixels will be identified as sino entries with inf or Nan values.

• batch_size (int) – Size of view batch to use in passing data to gpu.

Returns:

- **sino* (ndarray, float)* – Sinogram data with shape (num_views, num_det_rows, num_det_channels).

mbirjax.preprocess.correct_det_rotation(sino, weights=None, det_rotation=0.0)

Correct sinogram data and weights to account for detector rotation.

This function can be used to rotate sinogram views when the axis of rotation is not exactly aligned with the detector columns.

Parameters:

• sino (float, ndarray) – Sinogram data with 3D shape (num_views, num_det_rows, num_det_channels).

• weights (float, ndarray) – Sinogram weights, with the same array shape as sino.

• det_rotation (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

mbirjax.preprocess.estimate_background_offset(sino, edge_width=9)

Estimate background offset of a sinogram using JAX for GPU acceleration.

Parameters:

• sino (numpy.ndarray) – Sinogram data with shape (num_views, num_det_rows, num_det_channels).

• edge_width (int, optional) – Width of the edge regions in pixels. Must be an integer >= 1. Defaults to 9.

Returns:

offset (float) – Background offset value.

mbirjax.preprocess.export_recon_to_hdf5(recon, filename, recon_description='', delta_pixel_image=1.0, alu_description='')

This function writes a reconstructed image to an HDF5 file.

Optimal parameters can be used to store a description of the reconstruction and the pixels spacing.

Parameters:

• recon (float, ndarray) – 3D reconstructed reconstruction to be saved.

• filename (string) – Fully specified path to save the HDF5 file.

• recon_description (string, optional) – Description of CT reconstruction.

• delta_pixel_image (float, optional) – Image pixel spacing in arbitrary length units.

• alu_description (string, optional) – Description of the arbitrary length units for pixel spacing. Example: “1 ALU = 5 mm”.

mbirjax.preprocess.interpolate_defective_pixels(sino, defective_pixel_array=())

Interpolates defective sinogram entries with the mean of neighboring pixels.

Parameters:

• sino (jax array, float) – Sinogram data with 3D shape (num_views, num_det_rows, num_det_channels).

• defective_pixel_array (jax array) – 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 (jax array, 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).

mbirjax.preprocess.multi_threshold_otsu(image, classes=2)

Segments an image into several different classes using Otsu’s method.

Parameters:

• image (ndarray) – Input image in ndarray of float type.

• classes (int, optional) – Number of classes to threshold (i.e., number of resulting regions). Default is 2.

Returns:

list – List of threshold values that divide the image into the specified number of classes.