svmbir

Functions:

recon(sino, angles[, geometry])

Compute 3D MBIR reconstruction using multi-resolution SVMBIR algorithm.

project(image, angles, num_channels[, geometry])

Compute 3D forward-projection.

backproject(sino, angles, **kwargs)

Compute 3D back-projection.

sino_sort(sino, angles[, weights])

Sort sinogram views (and sinogram weights if provided) so that view angles are in monotonically increasing order on the interval \([0,2\pi)\).

calc_weights(sino, weight_type)

Compute the weights used in MBIR reconstruction.

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

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

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

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

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

Compute the automatic value of sigma_p for use in proximal map estimation.

svmbir.recon(sino, angles, geometry='parallel', **kwargs)[source]

Compute 3D MBIR reconstruction using multi-resolution SVMBIR algorithm.

Parameters:
  • sino (ndarray) – 3D sinogram array with shape (num_views, num_slices, num_channels).

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

  • geometry (string) – [Default=’parallel’] Scanner geometry: ‘parallel’, ‘fan-curved’, or ‘fan-flat’. Note for fan geometries the dist_source_detector and magnification arguments must be specified.

  • dist_source_detector (float) – (Required for fan beam geometries only) Distance from X-ray focal spot to detectors, in \(ALU\).

  • magnification (float) – (Required for fan beam geometries only) Magnification factor = dist_source_detector/dist_source_isocenter.

  • weights (ndarray, optional) – [Default=None] 3D weights array with same shape as sino.

  • weight_type (string, optional) – [Default=”unweighted”] Type of noise model used for data. If the weights array is not supplied, then the function svmbir.calc_weights is used to set weights using specified weight_type parameter. Option “unweighted” corresponds to unweighted reconstruction; Option “transmission” is the correct weighting for transmission CT with constant dosage; Option “transmission_root” is commonly used with transmission CT data to improve image homogeneity; Option “emission” is appropriate for emission CT data.

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

  • prox_image (ndarray, optional) – [Default=None] 3D proximal map input image with shape (num_slices,num_rows,num_cols). If prox_image is supplied, then the proximal map prior model is used, and the qGGMRF parameters are ignored.

  • init_proj (None, optional) – [Default=None] Initial value of forward projection of the init_image. This can be used to reduce computation for the first iteration when using the proximal map option.

  • num_rows (int, optional) – [Default=None] Integer number of rows in reconstructed image. If None, automatically set.

  • num_cols (int, optional) – [Default=None] Integer number of columns in reconstructed image. If None, automatically set.

  • roi_radius (float, optional) – [Default=None] Scalar value of radius of reconstruction in \(ALU\). If None, automatically set with auto_roi_radius(). Pixels outside the radius roi_radius in the \((x,y)\) plane are disregarded in the reconstruction.

  • delta_channel (float, optional) – [Default=1.0] Scalar value of detector channel spacing in \(ALU\).

  • delta_pixel (float, optional) – Scalar value of the spacing between image pixels in the 2D slice plane in \(ALU\). Defaults to delta_channel for parallel beam geometry, and delta_channel/magnification for fan beam geometries.

  • center_offset (float, optional) – [Default=0.0] Scalar value of offset from center-of-rotation.

  • sigma_y (float, optional) – [Default=None] Scalar value of noise standard deviation parameter. If None, automatically set with auto_sigma_y.

  • snr_db (float, optional) – [Default=30.0] Scalar value that controls assumed signal-to-noise ratio of the data in dB. Ignored if sigma_y is not None.

  • sigma_x (float, optional) – [Default=None] Scalar value \(>0\) that specifies the qGGMRF scale parameter. Ignored if prox_image is not None. If None and prox_image is also None, automatically set with auto_sigma_x. Regularization should be controled with the sharpness parameter, but sigma_x can be set directly by expert users.

  • sigma_p (float, optional) – [Default=None] Scalar value \(>0\) that specifies the proximal map parameter. If None, automatically set with auto_sigma_p. Regularization should be controled with the sharpness parameter, but sigma_p can be set directly by expert users.

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

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

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

  • b_interslice (float, optional) – [Default=1.0] Non-negative scalar value that specifies the interslice regularization. The default value of 1.0 should be fine for most applications. However, b_interslice can be increased to values \(>1\) in order to increase regularization along the slice axis.

  • sharpness (float, optional) – [Default=0.0] Scalar value that controls level of sharpness. sharpness=0.0 is neutral; sharpness>0 increases sharpness; sharpness<0 reduces sharpness. 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] Boolean value that determines if positivity constraint is enforced. The positivity parameter defaults to True; however, it should be changed to False when used in applications that can generate negative image values.

  • relax_factor (float, optional) – [Default=1.0] Relaxation factor for pixel update. Valid range (0,2.0]. Values in (0,1) produce under-relaxation (smaller step size); Values in (1,2] produce over-relaxation.

  • max_resolutions (int, optional) – [Default=None] Integer >=0 that specifies the maximum number of grid resolutions used to solve MBIR reconstruction problem. If None, automatically set with auto_max_resolutions to 0 if inital image is provided and 2 otherwise.

  • stop_threshold (float, optional) – [Default=0.02] Scalar valued stopping threshold in percent. If stop_threshold=0.0, then run max iterations.

  • max_iterations (int, optional) – [Default=100] Integer valued specifying the maximum number of iterations. The value of max_iterations may need to be increased for reconstructions with limited tilt angles or high regularization.

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

  • delete_temps (bool, optional) – [Default=True] Delete temporary files used in computation.

  • svmbir_lib_path (string, optional) – [Default=’~/.cache/svmbir’] Path to directory containing library of forward projection matrices.

  • object_name (string, optional) – [Default=’object’] Specifies filenames of cached files. Can be changed suitably for running multiple instances of reconstructions. Useful for building multi-process and multi-node functionality on top of svmbir.

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

Returns:

3D numpy array – 3D reconstruction with shape (num_slices,num_rows,num_cols) in units of \(ALU^{-1}\).

svmbir.project(image, angles, num_channels, geometry='parallel', **kwargs)[source]

Compute 3D forward-projection.

Parameters:
  • image (ndarray) – 3D numpy array of image being projected. The image shape is (num_slices,num_rows,num_cols). The output will contain ‘num_slices’ projections. Note the image is considered 0 outside the ‘roi_radius’ (disregarded pixels).

  • angles (ndarray) – 1D numpy array of view angles in radians. ‘angles[k]’ is the angle in radians for view \(k\).

  • num_channels (int) – Number of sinogram channels.

  • geometry (string) – [Default=’parallel’] Scanner geometry: ‘parallel’, ‘fan-curved’, or ‘fan-flat’. Note for fan geometries the dist_source_detector and magnification arguments must be specified.

  • dist_source_detector (float) – (Required for fan beam geometries only) Distance from X-ray focal spot to detectors, in \(ALU\).

  • magnification (float) – (Required for fan beam geometries only) Magnification factor = dist_source_detector/dist_source_isocenter.

  • delta_channel (float, optional) – [Default=1.0] Scalar value of detector channel spacing in \(ALU\).

  • delta_pixel (float, optional) – Scalar value of the spacing between image pixels in the 2D slice plane in \(ALU\). Defaults to delta_channel for parallel beam geometry, and delta_channel/magnification for fan beam geometries.

  • center_offset (float, optional) – [Default=0.0] Offset from center-of-rotation in ‘fractional number of channels’ units.

  • roi_radius (float, optional) – [Default=None] Radius of relevant image region in \(ALU\). Pixels outside the radius are disregarded in the forward projection. If not given, the value is set with auto_roi_radius().

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

  • svmbir_lib_path (string, optional) – [Default=’~/.cache/svmbir’] Path to directory containing library of projection matrices and temp files.

  • delete_temps (bool, optional) – [Default=True] Delete any temporary files generated during computation. Unused for cython version.

  • object_name (string, optional) – [Default=’object’] Specifies base filename of temporary files. Unused for cython version.

  • verbose (int, optional) – [Default=1] Level of printed status output. {0,1,2} Set to 0 for quiet mode.

Returns:

ndarray – 3D numpy array containing projection with shape (num_views, num_slices, num_channels).

svmbir.backproject(sino, angles, **kwargs)[source]

Compute 3D back-projection.

Parameters:
  • sino (ndarray) – 3D numpy array of input sinogram with shape (num_views,num_slices,num_channels).

  • angles (ndarray) – 1D numpy array of view angles in radians. ‘angles[k]’ is the angle in radians for view \(k\).

  • num_rows (int, optional) – [Default=num_channels] Integer number of output image rows.

  • num_cols (int, optional) – [Default=num_channels] Integer number of output image columns.

  • geometry (string) – [Default=’parallel’] Scanner geometry: ‘parallel’, ‘fan-curved’, or ‘fan-flat’. Note for fan geometries the dist_source_detector and magnification arguments must be specified.

  • dist_source_detector (float) – (Required for fan beam geometries only) Distance from X-ray focal spot to detectors, in \(ALU\).

  • magnification (float) – (Required for fan beam geometries only) Magnification factor = dist_source_detector/dist_source_isocenter.

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

  • delta_pixel (float, optional) – Scalar value of the spacing between image pixels in the 2D slice plane in \(ALU\). Defaults to delta_channel for parallel beam geometry, and delta_channel/magnification for fan beam geometries.

  • center_offset (float, optional) – [Default=0.0] Offset from center-of-rotation in ‘fractional number of channels’ units.

  • roi_radius (float, optional) – [Default=None] Radius of relevant image region in \(ALU\). Pixels outside the radius are disregarded in the forward projection. If not given, the value is set with auto_roi_radius().

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

  • svmbir_lib_path (string, optional) – [Default=’~/.cache/svmbir’] Path to directory containing library of projection matrices and temp files.

  • delete_temps (bool, optional) – [Default=True] Delete any temporary files generated during computation. Unused for cython version.

  • object_name (string, optional) – [Default=’object’] Specifies base filename of temporary files. Unused for cython version.

  • verbose (int, optional) – [Default=1] Level of printed status output. {0,1,2} Set to 0 for quiet mode.

Returns:

ndarray – 3D numpy array containing back projected image (num_slices,num_rows,num_cols).

svmbir.sino_sort(sino, angles, weights=None)[source]
Sort sinogram views (and sinogram weights if provided) so that view angles are in monotonically increasing order on the interval \([0,2\pi)\).

This function can be used to preprocess the sinogram data so that svmbir reconstruction is faster. The function may create additional arrays that increase memory usage.

Parameters:
  • sino (ndarray) – 3D numpy array of unsorted sinogram data with shape (num_views, num_slices, num_channels)

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

  • weights (ndarray, optional) – [Default=None] 3D unsorted array of weights with same shape as sino.

Returns:

  • A tuple (sino, angles) when weights=None

  • A tuple (sino, angles, weights) if weights is not None.

The arrays are sorted along the view axis so that they have monotone increasing view angles in the interval \([0,2\pi)\).

svmbir.calc_weights(sino, weight_type)[source]

Compute the weights used in MBIR reconstruction.

Parameters:
  • sino (ndarray) – 3D numpy array of sinogram data with shape (num_views,num_slices,num_channels).

  • weight_type (string) – Type of noise model used for data.

    If weight_type=”unweighted” => weights = numpy.ones_like(sino)

    If weight_type=”transmission” => weights = numpy.exp(-sino)

    If weight_type=”transmission_root” => weights = numpy.exp(-sino/2)

    If weight_type=”emission” => weights = 1/(numpy.abs(sino) + 0.1)

Returns:

ndarray – 3D numpy array of weights with same shape as sino.

Raises:

Exception – Description

svmbir.auto_sigma_x(sino, magnification=1.0, delta_channel=1.0, sharpness=0.0)[source]

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

Parameters:
  • sino (ndarray) – 3D numpy array of sinogram data with shape (num_views,num_slices,num_channels).

  • magnification (float) – (fan beam geometries only) Magnification factor = dist_source_detector/dist_source_isocenter.

  • delta_channel (float, optional) – [Default=1.0] Scalar value of detector channel spacing in \(ALU\).

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

Returns:

float – Automatic value of regularization parameter.

svmbir.auto_sigma_y(sino, weights, magnification=1.0, delta_channel=1.0, delta_pixel=1.0, snr_db=30.0)[source]

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

Parameters:
  • sino (ndarray) – 3D numpy array of sinogram data with shape (num_views,num_slices,num_channels).

  • weights (ndarray) – 3D numpy array of weights with same shape as sino. The parameters weights should be the same values as used in svmbir reconstruction.

  • magnification (float) – (fan beam geometries only) Magnification factor = dist_source_detector/dist_source_isocenter.

  • delta_channel (float, optional) – [Default=1.0] Scalar value of detector channel spacing in \(ALU\).

  • delta_pixel (float, optional) – [Default=1.0] Scalar value of pixel spacing in \(ALU\).

  • snr_db (float, optional) – [Default=30.0] Scalar value that controls assumed signal-to-noise ratio of the data in dB.

Returns:

ndarray – Automatic values of regularization parameter.

svmbir.auto_sigma_p(sino, magnification=1.0, delta_channel=1.0, sharpness=0.0)[source]

Compute the automatic value of sigma_p for use in proximal map estimation.

Parameters:
  • sino (ndarray) – 3D numpy array of sinogram data with shape (num_views,num_slices,num_channels).

  • magnification (float) – (fan beam geometries only) Magnification factor = dist_source_detector/dist_source_isocenter.

  • delta_channel (float, optional) – [Default=1.0] Scalar value of detector channel spacing in \(ALU\).

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

Returns:

float – Automatic value of regularization parameter.