svmbir¶
Functions:
|
Compute 3D MBIR reconstruction using multi-resolution SVMBIR algorithm. |
|
Compute 3D forward-projection. |
|
Compute 3D back-projection. |
|
Sort sinogram views (and sinogram weights if provided) so that view angles are in monotonically increasing order on the interval \([0,2\pi)\). |
|
Compute the weights used in MBIR reconstruction. |
|
Compute the automatic value of |
|
Compute the automatic value of |
|
Compute the automatic value of |
- 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
andmagnification
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 functionsvmbir.calc_weights
is used to set weights using specifiedweight_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
forparallel
beam geometry, anddelta_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, butsigma_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, butsigma_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 ifsigma_x
is not None in qGGMRF mode, or ifsigma_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
andmagnification
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
forparallel
beam geometry, anddelta_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
andmagnification
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
forparallel
beam geometry, anddelta_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.