mbircone.cone3D

Functions:

auto_image_size(num_det_rows, ...)

Compute the automatic image array size for use in MBIR reconstruction.

auto_sigma_p(sino, magnification[, ...])

Compute the automatic value of sigma_p for use in MBIR reconstruction with proximal map prior.

auto_sigma_x(sino, magnification[, ...])

Compute the automatic value of sigma_x for use in MBIR reconstruction with qGGMRF prior.

auto_sigma_y(sino, magnification, weights[, ...])

Compute the automatic value of sigma_y for use in MBIR reconstruction.

auto_sigma_x_denoise(img_noisy[, sharpness, ...])

Given a noisy image, estimate the standard deviation of its Gaussian prior.

auto_sigma_w_denoise(img_noisy[, gauss_sigma])

Given a noisy image, estimate the standard deviation of its noise.

calc_weights(sino, weight_type)

Compute the weights used in MBIR reconstruction.

create_image_params_dict(num_image_rows, ...)

Allocate image parameters as required by cone3D.recon and cone3D.project.

create_sino_params_dict(...[, ...])

Allocate sinogram parameters as required by cone3D.recon and cone3D.project.

project(image, angles, num_det_rows, ...[, ...])

Compute 3D cone beam forward projection.

recon(sino, angles, dist_source_detector, ...)

Compute 3D cone beam MBIR reconstruction

denoise(img_noisy[, sharpness, sigma_x, ...])

Perform denoising using a proximal map with a qGGMRF objective function.
mbircone.cone3D.auto_image_size(num_det_rows, num_det_channels, delta_det_channel, delta_det_row, delta_pixel_image, magnification)[source]

Compute the automatic image array size for use in MBIR reconstruction.

Parameters:

  • num_det_rows (int) – Number of rows in sinogram data.

  • num_det_channels (int) – Number of channels in sinogram data.

  • 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) – Image pixel spacing in \(ALU\).

  • magnification (float) – Magnification of the cone-beam geometry defined as (source to detector distance)/(source to center-of-rotation distance).

Returns:

(int, 3-tuple) – Default values for num_image_rows, num_image_cols, num_image_slices for the inputted image measurements.

mbircone.cone3D.auto_sigma_p(sino, magnification, delta_pixel_detector=1.0, sharpness=0.0)[source]

Compute the automatic value of sigma_p for use in MBIR reconstruction with proximal map prior.

Parameters:

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

  • magnification (float) – Magnification of the cone-beam geometry defined as (source to detector distance)/(source to center-of-rotation distance).

  • delta_pixel_detector (float, optional) – [Default=1.0] Detector pixel spacing in \(ALU\).

  • sharpness (float, optional) – [Default=0.0] Controls level of sharpness. sharpness=0.0 is neutral; sharpness>0 increases sharpness; sharpness<0 reduces sharpness

Returns:

(float) – Automatic value of proximal map prior model regularization parameter.

mbircone.cone3D.auto_sigma_w_denoise(img_noisy, gauss_sigma=2.0)[source]

Given a noisy image, estimate the standard deviation of its noise.

The input image will be smoothed by a Gaussian filter, and the std-dev of the noise is estimated by the std-dev of the residual image between the noisy image and the smoothed image.

Parameters:

  • img_noisy (float, ndarray) – Noisy image with 3D shape (num_slices, num_rows, num_cols)

  • gauss_sigma (float, optional) – [Default=2.0] std-dev of Gaussian filter used to smooth the input image.

mbircone.cone3D.auto_sigma_x(sino, magnification, delta_pixel_detector=1.0, sharpness=0.0)[source]

Compute the automatic value of sigma_x for use in MBIR reconstruction with qGGMRF prior.

Parameters:

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

  • magnification (float) – Magnification of the cone-beam geometry defined as (source to detector distance)/(source to center-of-rotation distance).

  • delta_pixel_detector (float, optional) – [Default=1.0] Detector pixel spacing in \(ALU\).

  • sharpness (float, optional) – [Default=0.0] Controls level of sharpness. sharpness=0.0 is neutral; sharpness>0 increases sharpness; sharpness<0 reduces sharpness

Returns:

(float) – Automatic value of qGGMRF prior model regularization parameter.

mbircone.cone3D.auto_sigma_x_denoise(img_noisy, sharpness=0.0, gauss_sigma=2.0)[source]

Given a noisy image, estimate the standard deviation of its Gaussian prior.

The image will be smoothed by a Gaussian filter, and the std-dev of the Gaussian prior is estimated as a fraction of the smoothed image.

Parameters:

  • img_noisy (float, ndarray) – Noisy image with 3D shape (num_slices, num_rows, num_cols)

  • sharpness (float, optional) – [Default=0.0] Controls level of sharpness. sharpness=0.0 is neutral; sharpness>0 increases sharpness; sharpness<0 reduces sharpness.

  • gauss_sigma (float, optional) – [Default=2.0] std-dev of Gaussian filter used to smooth the input image.

mbircone.cone3D.auto_sigma_y(sino, magnification, weights, snr_db=40.0, delta_pixel_image=1.0, delta_pixel_detector=1.0)[source]

Compute the automatic value of sigma_y for use in MBIR reconstruction.

Parameters:

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

  • magnification (float) – Magnification of the cone-beam geometry defined as (source to detector distance)/(source to center-of-rotation distance).

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

  • snr_db (float, optional) – [Default=40.0] Assumed signal-to-noise ratio of the data in \(dB\).

  • delta_pixel_image (float, optional) – [Default=1.0] Image pixel spacing in \(ALU\).

  • delta_pixel_detector (float, optional) – [Default=1.0] Detector pixel spacing in \(ALU\).

Returns:

(float) – Automatic value of forward model regularization parameter sigma_y.

mbircone.cone3D.calc_weights(sino, weight_type)[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) or 4D shape (num_time_points, 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).

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.cone3D.create_image_params_dict(num_image_rows, num_image_cols, num_image_slices, delta_pixel_image=1.0, image_slice_offset=0.0)[source]

Allocate image parameters as required by cone3D.recon and cone3D.project.

Parameters:

  • num_image_rows (int) – Number of rows in image region.

  • num_image_cols (int) – Number of columns in image region.

  • num_image_slices (int) – Number of slices in image region.

  • delta_pixel_image (float, optional) – [Default=1.0] Image pixel spacing in \(ALU\).

  • image_slice_offset (float, optional) – [Default=0.0] Vertical offset of the image in units of \(ALU\).

Returns:

(dict) – Parameters specifying the location and dimensions of a 3D density image.

mbircone.cone3D.create_sino_params_dict(dist_source_detector, magnification, num_views, num_det_rows, num_det_channels, det_channel_offset=0.0, det_row_offset=0.0, rotation_offset=0.0, delta_det_channel=1.0, delta_det_row=1.0)[source]

Allocate sinogram parameters as required by cone3D.recon and cone3D.project.

Parameters:

  • 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).

  • num_views (int) – Number of views in sinogram data

  • num_det_rows (int) – Number of rows in sinogram data

  • num_det_channels (int) – Number of channels in sinogram data

  • 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.

  • 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\).

Returns:

(dict) – Parameters specifying the location and dimensions of the X-ray source and detector.

mbircone.cone3D.denoise(img_noisy, sharpness=0.0, sigma_x=None, sigma_w=None, init_image=None, p=1.2, q=2.0, T=1.0, num_neighbors=6, positivity=True, stop_threshold=0.2, max_iterations=100, verbose=1)[source]

Perform denoising using a proximal map with a qGGMRF objective function. This denoiser internally uses ICD to approximate the solution to the proximal map.

Parameters:

  • img_noisy (float, ndarray, optional) – [Default=0.0] Initial value of reconstruction image, specified by a 3D numpy array with shape (num_img_slices, num_img_rows, num_img_cols).

  • sharpness (float, optional) – [Default=0.0] Sharpness of the denoised image. sharpness=0.0 is neutral; sharpness>0 increases sharpness; sharpness<0 reduces sharpness. Used to calculate sigma_x. Ignored if sigma_x is not None.

  • sigma_x (float, optional) – [Default=None] qGGMRF prior model regularization parameter. If None, automatically set with cone3D.auto_sigma_x_denoise as a function of sharpness.

  • sigma_w (float, optional) – [Default=None] Noise std-dev. If None, automatically set with cone3D.auto_sigma_w_denoise.

  • init_image (float, ndarray, optional) – [Default=0.0] Initial value of denoised image, specified by either a scalar value or a 3D numpy array with shape (num_img_slices, num_img_rows, num_img_cols). If None, img_noisy will be used as the initial value.

  • p (float, optional) – [Default=1.2] Scalar value in range \([1,2]\) that specifies qGGMRF shape parameter.

  • q (float, optional) – [Default=2.0] Scalar value in range \([p,1]\) that specifies qGGMRF shape parameter.

  • T (float, optional) – [Default=1.0] Scalar value \(>0\) that specifies the qGGMRF threshold parameter.

  • num_neighbors (int, optional) – [Default=6] Possible values are \({26,18,6}\). Number of neighbors in the qGGMRF neighborhood. More neighbors results in a better regularization but a slower denoising.

  • positivity (bool, optional) – [Default=True] Determines if positivity constraint will be enforced.

  • stop_threshold (float, optional) – [Default=0.2] Relative update stopping threshold, in percent, where relative update is given by (average value change) / (average voxel value).

  • max_iterations (int, optional) – [Default=100] Maximum number of iterations before stopping.

  • verbose (int, optional) – [Default=1] Possible values are {0,1,2}, where 0 is quiet, 1 prints minimal denoising progress information, and 2 prints the full information.

Returns:

(float, ndarray) – 3D denoised image with shape (num_img_slices, num_img_rows, num_img_cols) in units of \(ALU^{-1}\).

mbircone.cone3D.project(image, angles, num_det_rows, num_det_channels, dist_source_detector, magnification, 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=1, lib_path='/home/docs/.cache/mbircone')[source]

Compute 3D cone beam forward projection.

Parameters:

  • image (float, ndarray) – 3D image to be projected, with shape (num_img_slices, num_img_rows, num_img_cols).

  • angles (float, ndarray) – 1D array of view angles in radians.

  • num_det_rows (int) – Number of rows in sinogram data.

  • num_det_channels (int) – Number of channels in sinogram data.

  • 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).

  • 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:

(float, ndarray) – 3D sinogram with shape (num_views, num_det_rows, num_det_channels).

mbircone.cone3D.recon(sino, angles, dist_source_detector, magnification, weights=None, weight_type='unweighted', init_image=0.0, prox_image=None, num_image_rows=None, num_image_cols=None, num_image_slices=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, sigma_y=None, snr_db=40.0, sigma_x=None, sigma_p=None, p=1.2, q=2.0, T=1.0, num_neighbors=6, sharpness=0.0, positivity=True, max_resolutions=None, stop_threshold=0.2, max_iterations=100, NHICD=False, num_threads=None, verbose=1, lib_path='/home/docs/.cache/mbircone')[source]

Compute 3D cone beam MBIR reconstruction

Parameters:

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

  • angles (float, 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).

  • weights (float, ndarray, optional) – [Default=None] 3D weights array with same shape as sino. If weights is not supplied, then cone3D.calc_weights is used to set weights using weight_type. weights=0.0 indicates an invalid sinogram entry in sino.

  • weight_type (string, optional) – [Default=’unweighted’] Type of noise model used for data.

    • 'unweighted' corresponds to unweighted reconstruction;

    • 'transmission' is the correct weighting for transmission CT with constant dosage;

    • 'transmission_root' is commonly used with transmission CT data to improve image homogeneity;

    • 'emission' is appropriate for emission CT data.

  • init_image (float, ndarray, optional) – [Default=0.0] Initial value of reconstruction image, specified by either a scalar value or a 3D numpy array with shape (num_img_slices, num_img_rows, num_img_cols).

  • prox_image (float, ndarray, optional) – [Default=None] 3D proximal map input image with shape (num_img_slices, num_img_rows, num_img_cols).

  • num_image_rows (int, optional) – [Default=None] Number of rows in reconstructed image. If None, automatically set by cone3D.auto_image_size.

  • num_image_cols (int, optional) – [Default=None] Number of columns in reconstructed image. If None, automatically set by cone3D.auto_image_size.

  • num_image_slices (int, optional) – [Default=None] Number of slices in reconstructed image. If None, automatically set by cone3D.auto_image_size.

  • 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\).

  • sigma_y (float, optional) – [Default=None] Forward model regularization parameter. If None, automatically set with cone3D.auto_sigma_y.

  • snr_db (float, optional) – [Default=40.0] Assumed signal-to-noise ratio of the data in \(dB\). Ignored if sigma_y is not None.

  • sigma_x (float, optional) – [Default=None] qGGMRF prior model regularization parameter. If None, automatically set with cone3D.auto_sigma_x as a function of sharpness. If prox_image is given, sigma_p is used instead of sigma_x in the reconstruction.

  • sigma_p (float, optional) – [Default=None] Proximal map regularization parameter. If None, automatically set with cone3D.auto_sigma_p as a function of sharpness. Ignored if prox_image is None.

  • p (float, optional) – [Default=1.2] Scalar value in range \([1,2]\) that specifies qGGMRF shape parameter.

  • q (float, optional) – [Default=2.0] Scalar value in range \([p,1]\) that specifies qGGMRF shape parameter.

  • T (float, optional) – [Default=1.0] Scalar value \(>0\) that specifies the qGGMRF threshold parameter.

  • num_neighbors (int, optional) – [Default=6] Possible values are \({26,18,6}\). Number of neighbors in the qGGMRF neighborhood. More neighbors results in a better regularization but a slower reconstruction.

  • sharpness (float, optional) – [Default=0.0] Sharpness of reconstruction. sharpness=0.0 is neutral; sharpness>0 increases sharpness; sharpness<0 reduces sharpness. Used to calculate sigma_x and sigma_p. Ignored if sigma_x is not None in qGGMRF mode, or if sigma_p is not None in proximal map mode.

  • positivity (bool, optional) – [Default=True] Determines if positivity constraint will be enforced.

  • max_resolutions (int, optional) – [Default=None] Integer \(\geq 0\) that specifies the maximum number of grid resolutions used to solve MBIR reconstruction problem. If None, automatically set by cone3D.auto_max_resolutions.

  • stop_threshold (float, optional) – [Default=0.2] Relative update stopping threshold, in percent, where relative update is given by (average value change) / (average voxel value).

  • max_iterations (int, optional) – [Default=100] Maximum number of iterations before stopping.

  • NHICD (bool, optional) – [Default=False] If True, uses non-homogeneous ICD updates.

  • num_threads (int, optional) – [Default=None] Number of compute threads requested when executed. If None, this 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:

(float, ndarray) – 3D reconstruction image with shape (num_img_slices, num_img_rows, num_img_cols) in units of \(ALU^{-1}\).