Skip to content

nabu.reconstruction.cone

source module nabu.reconstruction.cone

Classes

  • ConebeamReconstructor — A reconstructor for cone-beam geometry using the astra toolbox.

  • NumpyConebeamReconstructor — Initialize a cone beam reconstructor. This reconstructor works on slabs of data, meaning that one partial volume is obtained from one stack of sinograms. To reconstruct a full volume, the reconstructor must be called on a series of sinograms stacks, with an updated "relative_z_position" each time.

Functions

source class ConebeamReconstructor(sinos_shape, source_origin_dist, origin_detector_dist, angles=None, volume_shape=None, rot_center=None, relative_z_position=None, pixel_size=None, padding_mode='zeros', filter_name=None, slice_roi=None, cuda_options=None, extra_options=None)

A reconstructor for cone-beam geometry using the astra toolbox.

Initialize a cone beam reconstructor. This reconstructor works on slabs of data, meaning that one partial volume is obtained from one stack of sinograms. To reconstruct a full volume, the reconstructor must be called on a series of sinograms stacks, with an updated "relative_z_position" each time.

Parameters

  • sinos_shape : tuple — Shape of the sinograms stack, in the form (n_sinos, n_angles, prj_width)

  • source_origin_dist : float — Distance, in pixel units, between the beam source (cone apex) and the "origin". The origin is defined as the center of the sample

  • origin_detector_dist : float — Distance, in pixel units, between the center of the sample and the detector.

  • angles : array, optional — Rotation angles in radians. If provided, its length should be equal to sinos_shape[1].

  • volume_shape : tuple of int, optional — Shape of the output volume slab, in the form (n_z, n_y, n_x). If not provided, the output volume slab shape is (sinos_shape[0], sinos_shape[2], sinos_shape[2]).

  • rot_center : float, optional — Rotation axis position. Default is (detector_width - 1)/2.0

  • relative_z_position : float, optional — Position of the central slice of the slab, with respect to the full stack of slices. By default it is set to zero, meaning that the current slab is assumed in the middle of the stack

  • axis_correction : array, optional — Array of the same size as the number of projections. Each corresponds to a horizontal displacement.

  • pixel_size : float or tuple, optional — Size of the pixel. Possible options: - Nothing is provided (default): in this case, all lengths are normalized with respect to the pixel size, i.e 'source_origin_dist' and 'origin_detector_dist' should be expressed in pixels (and 'pixel_size' is set to 1). - A scalar number is provided: in this case it is the spacing between two pixels (in each dimension) - A tuple is provided: in this case it is the spacing between two pixels in both dimensions, vertically then horizontally, i.e (detector_spacing_y, detector_spacing_x)

  • scale_factor : float, optional — Post-reconstruction scale factor.

  • padding_mode : str, optional — How to pad the data before applying FDK. By default this is done by astra with zero-padding. If padding_mode is other than "zeros", it will be done by nabu and the padded data is passed to astra where no additional padding is done. Beware that in its current implementation, this option almost doubles the memory needed.

  • slice_roi — Whether to reconstruct only a region of interest for each horizontal slice. This parameter must be in the form (start_x, end_x, start_y, end_y) with no negative values. Note that the current implementation just crops the final reconstructed volume, i.e there is no speed or memory benefit.

  • use_astra_fdk : bool — Whether to use the native Astra Toolbox FDK implementation. If set to False, the cone-beam pre-weighting and projections padding/filtering is done by nabu. Note that this parameter is automatically set to False if padding_mode != "zeros".

References

[1] Aarle, Wim & Palenstijn, Willem & Cant, Jeroen & Janssens, Eline & Bleichrodt, Folkert & Dabravolski, Andrei & De Beenhouwer, Jan & Batenburg, Kees & Sijbers, Jan. (2016). Fast and flexible X-ray tomography using the ASTRA toolbox. Optics Express. 24. 25129-25147. 10.1364/OE.24.025129.

Notes

This reconstructor is using the astra toolbox [1]. Therefore the implementation uses Astra's reference frame, which is centered on the sample (source and detector move around the sample). For more information see Fig. 2 of paper [1].

To define the cone-beam geometry, two distances are needed: - Source-origin distance (hereby d1) - Origin-detector distance (hereby d2)

The magnification at distance d2 is m = 1+d2/d1, so given a detector pixel size p_s, the sample voxel size is p_s/m.

To make things simpler, this class internally uses a different (but equivalent) geometry: - d2 is set to zero, meaning that the detector is (virtually) moved to the center of the sample - The detector is "re-scaled" to have a pixel size equal to the voxel size (p_s/m)

Having the detector in the same plane as the sample center simplifies things when it comes to slab-wise reconstruction: defining a volume slab (in terms of z_min, z_max) is equivalent to define the detector bounds, like in parallel geometry.

Methods

  • reset_rot_center

  • reconstruct — sinos: numpy.ndarray or cupy array Sinograms, with shape (n_sinograms, n_angles, width) output: cupy array, optional Output array. If not provided, a new numpy array is returned relative_z_position: int, optional Position of the central slice of the slab, with respect to the full stack of slices. By default it is set to zero, meaning that the current slab is assumed in the middle of the stack

source method ConebeamReconstructor.reset_rot_center(rot_center)

source method ConebeamReconstructor.reconstruct(sinos, output=None, relative_z_position=None)

sinos: numpy.ndarray or cupy array Sinograms, with shape (n_sinograms, n_angles, width) output: cupy array, optional Output array. If not provided, a new numpy array is returned relative_z_position: int, optional Position of the central slice of the slab, with respect to the full stack of slices. By default it is set to zero, meaning that the current slab is assumed in the middle of the stack

source class NumpyConebeamReconstructor(sinos_shape, source_origin_dist, origin_detector_dist, angles=None, volume_shape=None, rot_center=None, relative_z_position=None, pixel_size=None, padding_mode='zeros', filter_name=None, slice_roi=None, cuda_options=None, extra_options=None)

Bases : ConebeamReconstructor

Initialize a cone beam reconstructor. This reconstructor works on slabs of data, meaning that one partial volume is obtained from one stack of sinograms. To reconstruct a full volume, the reconstructor must be called on a series of sinograms stacks, with an updated "relative_z_position" each time.

Parameters

  • sinos_shape : tuple — Shape of the sinograms stack, in the form (n_sinos, n_angles, prj_width)

  • source_origin_dist : float — Distance, in pixel units, between the beam source (cone apex) and the "origin". The origin is defined as the center of the sample

  • origin_detector_dist : float — Distance, in pixel units, between the center of the sample and the detector.

  • angles : array, optional — Rotation angles in radians. If provided, its length should be equal to sinos_shape[1].

  • volume_shape : tuple of int, optional — Shape of the output volume slab, in the form (n_z, n_y, n_x). If not provided, the output volume slab shape is (sinos_shape[0], sinos_shape[2], sinos_shape[2]).

  • rot_center : float, optional — Rotation axis position. Default is (detector_width - 1)/2.0

  • relative_z_position : float, optional — Position of the central slice of the slab, with respect to the full stack of slices. By default it is set to zero, meaning that the current slab is assumed in the middle of the stack

  • axis_correction : array, optional — Array of the same size as the number of projections. Each corresponds to a horizontal displacement.

  • pixel_size : float or tuple, optional — Size of the pixel. Possible options: - Nothing is provided (default): in this case, all lengths are normalized with respect to the pixel size, i.e 'source_origin_dist' and 'origin_detector_dist' should be expressed in pixels (and 'pixel_size' is set to 1). - A scalar number is provided: in this case it is the spacing between two pixels (in each dimension) - A tuple is provided: in this case it is the spacing between two pixels in both dimensions, vertically then horizontally, i.e (detector_spacing_y, detector_spacing_x)

  • scale_factor : float, optional — Post-reconstruction scale factor.

  • padding_mode : str, optional — How to pad the data before applying FDK. By default this is done by astra with zero-padding. If padding_mode is other than "zeros", it will be done by nabu and the padded data is passed to astra where no additional padding is done. Beware that in its current implementation, this option almost doubles the memory needed.

  • slice_roi — Whether to reconstruct only a region of interest for each horizontal slice. This parameter must be in the form (start_x, end_x, start_y, end_y) with no negative values. Note that the current implementation just crops the final reconstructed volume, i.e there is no speed or memory benefit.

  • use_astra_fdk : bool — Whether to use the native Astra Toolbox FDK implementation. If set to False, the cone-beam pre-weighting and projections padding/filtering is done by nabu. Note that this parameter is automatically set to False if padding_mode != "zeros".

References

[1] Aarle, Wim & Palenstijn, Willem & Cant, Jeroen & Janssens, Eline & Bleichrodt, Folkert & Dabravolski, Andrei & De Beenhouwer, Jan & Batenburg, Kees & Sijbers, Jan. (2016). Fast and flexible X-ray tomography using the ASTRA toolbox. Optics Express. 24. 25129-25147. 10.1364/OE.24.025129.

Notes

This reconstructor is using the astra toolbox [1]. Therefore the implementation uses Astra's reference frame, which is centered on the sample (source and detector move around the sample). For more information see Fig. 2 of paper [1].

To define the cone-beam geometry, two distances are needed: - Source-origin distance (hereby d1) - Origin-detector distance (hereby d2)

The magnification at distance d2 is m = 1+d2/d1, so given a detector pixel size p_s, the sample voxel size is p_s/m.

To make things simpler, this class internally uses a different (but equivalent) geometry: - d2 is set to zero, meaning that the detector is (virtually) moved to the center of the sample - The detector is "re-scaled" to have a pixel size equal to the voxel size (p_s/m)

Having the detector in the same plane as the sample center simplifies things when it comes to slab-wise reconstruction: defining a volume slab (in terms of z_min, z_max) is equivalent to define the detector bounds, like in parallel geometry.

Attributes

  • implementation — A simpler wrapper of astra cone-beam reconstruction, using astra's new built-in data splitting for FDK/BP3D when it doesn't fit in GPU memory. It's meant to reconstruct a single, huge numpy array. The class name is somewhat misleading: the final BP3D step is done on GPU, but all the rest is done on CPU.

Methods

source method NumpyConebeamReconstructor.reconstruct(sinos, output=None, relative_z_position=None)

source selection_is_centered(size, start, stop)

Return True if (start, stop) define a selection that is centered on the middle of the array.

source roi_is_centered(shape, slice_)

Return True if "slice_" define a selection that is centered on the middle of the array.

source fdk_preweighting(d_sinos, proj_geom, relative_z_position=0.0, cor_shift=0.0)

source get_fdk_weights(sinos_shape, source_origin_distance, origin_detector_distance, cor_shift=0, du=1, dv=1, normalize=True, zshift=0)

Get the FDK weights in the radio domain.

Parameters

  • sinos_shape : tuple of int — Shape of the sinograms stack, in the form (n_sinograms, n_angles, n_x). The detector shape is (n_z, n_x) = (n_sinograms, n_x)

  • source_origin_distance — Distance (positive) between X-ray focal point and "origin" (sample)

  • origin_detector_distance — Distance (positive) between "origin" (sample) and detector

  • cor_shift — Shift (signed) between center of detector, and projection of center of rotation

  • du : float — Horizontal pixel size

  • dv : float — Vertical pixel size

  • zshift — Current sample elevation, i.e coordinate in v of the projection of center of sample onto the detector

Returns

  • weights : numpy.ndarray — FDK pre-weights, to be applied through a multiplication of each radio image.

Notes

The parameters 'source_detector_distance', 'source_origin_distance', 'du', 'dv', 'zshift' and 'cor_shift' (!) need to be provided with the same physical length unit. All can be expressed in voxel units (i.e du = dv = 1) - the normalization should then be done at another stage.