pytomography.metadata#

This module contains classes pertaining to metadata in PyTomography. Metadata classes contain required information for interpretting data; for example, metadata corresponding to an object (with object data stored in a torch.Tensor) contains the voxel spacing and voxel dimensions.

Subpackages#

Submodules#

Package Contents#

Classes#

ObjectMeta

Parent class for all different types of Object Space Metadata. In general, while this is fairly similar for all imaging modalities, required padding features/etc may be different for different modalities.

ProjMeta

Parent class for all different types of Projection Space Metadata. Implementation and required parameters will differ significantly between different imaging modalities.

SPECTObjectMeta

Metadata for object space in SPECT imaging

SPECTProjMeta

Metadata for projection space in SPECT imaging

SPECTPSFMeta

Metadata for PSF correction. PSF blurring is implemented using Gaussian blurring with \(\sigma(r) = f(r,p)\) where \(r\) is the distance from the detector, \(\sigma\) is the width of the Gaussian blurring at that location, and \(f(r,p)\) is the sigma_fit function which takes in additional parameters \(p\) called sigma_fit_params. (By default, sigma_fit is a linear curve). As such, \(\frac{1}{\sigma\sqrt{2\pi}}e^{-r^2/(2\sigma(r)^2)}\) is the point spread function. Blurring is implemented using convolutions with a specified kernel size.

PETLMProjMeta

Metadata required for PET listmode modeling. PET listmode projection actually requires two different projectors: the system matrix that projects to all detected crystal pair LORs (which is denoted as \(H\)) and the system matrix that projects to all valid LORs (denoted as \(\tilde{H}\)). The system matrix \(H\) is used for forward/back projection in reconstruction algorithms, while \(\tilde{H}\) is used for computing the normalization image \(\tilde{H}^T 1\).

PETTOFMeta

Class for PET time of flight metadata. Contains information such as spatial binning and resolution.

class pytomography.metadata.ObjectMeta(dr, shape)[source]#

Parent class for all different types of Object Space Metadata. In general, while this is fairly similar for all imaging modalities, required padding features/etc may be different for different modalities.

__repr__()[source]#

Return repr(self).

class pytomography.metadata.ProjMeta(angles)[source]#

Parent class for all different types of Projection Space Metadata. Implementation and required parameters will differ significantly between different imaging modalities.

__repr__()[source]#

Return repr(self).

class pytomography.metadata.SPECTObjectMeta(dr, shape)[source]#

Bases: pytomography.metadata.metadata.ObjectMeta

Metadata for object space in SPECT imaging

Parameters:
  • dr (list[float]) – List of 3 elements specifying voxel dimensions in cm.

  • shape (list[int]) – List of 3 elements [Lx, Ly, Lz] specifying the length of each dimension.

compute_padded_shape()[source]#

Computes the padded shape of an object required when rotating the object (to avoid anything getting cut off).

Return type:

list

class pytomography.metadata.SPECTProjMeta(projection_shape, angles, radii=None)[source]#

Bases: pytomography.metadata.metadata.ProjMeta

Metadata for projection space in SPECT imaging

Parameters:
  • projection_shape (Sequence) – 2D shape of each projection

  • angles (Sequence) – The angles for each 2D projection

  • radii (Sequence, optional) – Specifies the radial distance of the detector corresponding to each angle in angles; only required in certain cases (i.e. PSF correction). Defaults to None.

compute_padded_shape()[source]#

Computes the padded shape of an object required when rotating the object (to avoid anything getting cut off).

Return type:

list

class pytomography.metadata.SPECTPSFMeta(sigma_fit_params, sigma_fit=lambda r, a, b: ..., kernel_dimensions='2D', min_sigmas=3)[source]#

Metadata for PSF correction. PSF blurring is implemented using Gaussian blurring with \(\sigma(r) = f(r,p)\) where \(r\) is the distance from the detector, \(\sigma\) is the width of the Gaussian blurring at that location, and \(f(r,p)\) is the sigma_fit function which takes in additional parameters \(p\) called sigma_fit_params. (By default, sigma_fit is a linear curve). As such, \(\frac{1}{\sigma\sqrt{2\pi}}e^{-r^2/(2\sigma(r)^2)}\) is the point spread function. Blurring is implemented using convolutions with a specified kernel size.

Parameters:
  • sigma_fit_params (float) – Parameters to the sigma fit function

  • sigma_fit (function) – Function used to model blurring as a function of radial distance. Defaults to a 2 parameter linear model.

  • kernel_dimensions (str) – If ‘1D’, blurring is done seperately in each axial plane (so only a 1 dimensional convolution is used). If ‘2D’, blurring is mixed between axial planes (so a 2D convolution is used). Defaults to ‘2D’.

  • min_sigmas (float, optional) – This is the number of sigmas to consider in PSF correction. PSF are modelled by Gaussian functions whose extension is infinite, so we need to crop the Gaussian when computing this operation numerically. Note that the blurring width is depth dependent, but the kernel size used for PSF blurring is constant. As such, this parameter is used to fix the kernel size such that all locations have at least min_sigmas of a kernel size.

__repr__()[source]#

Return repr(self).

class pytomography.metadata.PETLMProjMeta(detector_ids, scanner_LUT, tof_meta=None, weights=None, detector_ids_sensitivity=None, weights_sensitivity=None)[source]#

Metadata required for PET listmode modeling. PET listmode projection actually requires two different projectors: the system matrix that projects to all detected crystal pair LORs (which is denoted as \(H\)) and the system matrix that projects to all valid LORs (denoted as \(\tilde{H}\)). The system matrix \(H\) is used for forward/back projection in reconstruction algorithms, while \(\tilde{H}\) is used for computing the normalization image \(\tilde{H}^T 1\). :param detector_ids: \(N \times 2\) (non-TOF) or \(N \times 3\) (TOF) tensor that provides detector ID pairs (and TOF bin) for coincidence events. This information is used to construct \(H\). :type detector_ids: torch.Tensor :param scanner_LUT: scanner lookup table that provides spatial coordinates for all detector ID pairs :type scanner_LUT: torch.Tensor :param tof_meta: PET time-of-flight metadata used to modify \(H\) for time of flight projection. If None, then time of flight is not used. Defaults to None. :type tof_meta: PETTOFMeta | None, optional :param weights: weights used to scale projections after forward projection and before back projection; these modify the system matrix \(H\). While such weights can be used to apply attenuation/normalization correction, they aren’t required in the absence of randoms/scatter; these correction need only be performed using weights_sensitivity. If provided, these weights must have the number of elements as the first dimension of detector_ids. If none, then no scaling is done. Defaults to None. :type weights: torch.tensor | None, optional :param detector_ids_sensitivity: valid detector ids used to generate the sensitivity image \(\tilde{H}^T 1\). As such, these are used to construct \(\tilde{H}\). If None, then assumes all detector ids (specified by scanner_LUT) are valid. Defaults to None. :type detector_ids_sensitivity: torch.tensor | None, optional :param weights_sensitivity: weights used for scaling projections in the computation of the sensitivity image, if the weights are given as \(w\) then the sensitivty image becomes \(\tilde{H}^T w\); these modify the system matrix \(\tilde{H}\). These weights are used for attenuation/normalization correction. If detector_ids_sensitivity is provided, then weights_sensitivity should have the same shape. If detector_ids_sensitivity is not provided, then weights_sensitivity should be the same length as all possible combinations of detectors in the scanner_LUT. If None, then no scaling is performed. Defaults to None. :type weights_sensitivity: torch.tensor | None, optional

Parameters:
  • detector_ids (torch.Tensor) –

  • scanner_LUT (torch.Tensor) –

  • tof_meta (pytomography.metadata.PET.pet_tof_metadata.PETTOFMeta | None) –

  • weights (torch.tensor | None) –

  • detector_ids_sensitivity (torch.tensor | None) –

  • weights_sensitivity (torch.tensor | None) –

class pytomography.metadata.PETTOFMeta(num_bins, bin_width, fwhm, n_sigmas=3, bin_type='symmetric')[source]#

Class for PET time of flight metadata. Contains information such as spatial binning and resolution.

Parameters:
  • num_bins (int) – Number of bins used to discretize time of flight data

  • bin_width (float) – Bin width of time of flight bins in mm.

  • fwhm (float) – FWHM corresponding to TOF uncertainty in mm.

  • n_sigmas (float) – Number of sigmas to consider when using TOF projection. Defaults to 3.

  • bin_type (str, optional) – How the bins are arranged. Currently, the only option is symmetry, which means the bins are distributed symmetrically (evenly on each side) between the center of all LOR pairs. Defaults to ‘symmetric’.