pytomography.io.SPECT#

Input/output functions for the SPECT imaging modality. Currently, the data types supported are SIMIND and DICOM files.

Submodules#

Package Contents#

Functions#

get_attenuation_map(headerfile[, smi_index_22])

Opens attenuation data from SIMIND output

get_projections(file[, index_peak, index_time, ...])

Gets projections from a .dcm file.

get_attenuation_map_from_file(file_AM)

Gets an attenuation map from a DICOM file. This data is usually provided by the manufacturer of the SPECT scanner.

get_attenuation_map_from_CT_slices(files_CT[, ...])

Converts a sequence of DICOM CT files (corresponding to a single scan) into a torch.Tensor object usable as an attenuation map in PyTomography.

get_energy_window_scatter_estimate(file, index_peak, ...)

Gets an estimate of scatter projection data from a DICOM file using either the dual energy window (index_upper=None) or triple energy window method.

get_psfmeta_from_scanner_params(collimator_name, ...)

Obtains SPECT PSF metadata given a unique collimator code and photopeak energy of radionuclide. For more information on collimator codes, see the "external data" section of the readthedocs page.

CT_to_mumap(CT, files_CT, file_NM[, index_peak, ...])

Converts a CT image to a mu-map given SPECT projection data. The CT data must be aligned with the projection data already; this is a helper function for get_attenuation_map_from_CT_slices.

subsample_amap(amap, N)

Subsamples 3D attenuation map by averaging over N x N x N regions

subsample_projections_and_modify_metadata(object_meta, ...)

Subsamples SPECT projection and modifies metadata accordingly
pytomography.io.SPECT.get_attenuation_map(headerfile, smi_index_22=3)[source]#

Opens attenuation data from SIMIND output

Parameters:

  • headerfile (str) – Path to header file

  • smi_index_22 (int, optional) – Value of provided in the simind simulation tag: “ in:x22,<idx>x “ where <idx> is 3 (mu) or 5 (mu-castor). You can check what value this is by default (if you did not provide it) by looking at simind.ini in the simind/smc_dir folder. Defaults to 3.

Returns:

Tensor containing attenuation map required for attenuation correction in SPECT/PET imaging.

Return type:

torch.Tensor[batch_size, Lx, Ly, Lz]

pytomography.io.SPECT.get_projections(file, index_peak=None, index_time=None, use_FOV_mask=False)[source]#

Gets projections from a .dcm file.

Parameters:

  • file (str) – Path to the .dcm file of SPECT projection data.

  • index_peak (int) – If not none, then the returned projections correspond to the index of this energy window. Otherwise returns all energy windows. Defaults to None.

  • index_time (int) – If not none, then the returned projections correspond to the index of the time slot in gated SPECT. Otherwise returns all time slots. Defaults to None

  • use_FOV_mask (bool) – If true, then use ta field of view mask obtained from DICOM file. Defaults to False.

Returns:

(SPECTObjectMeta, SPECTProjMeta, torch.Tensor[…, Ltheta, Lr, Lz]) where … depends on if time slots are considered.

Return type:

Sequence[pytomography.metadata.SPECT.SPECTObjectMeta, pytomography.metadata.SPECT.SPECTProjMeta, torch.Tensor]

pytomography.io.SPECT.get_attenuation_map_from_file(file_AM)[source]#

Gets an attenuation map from a DICOM file. This data is usually provided by the manufacturer of the SPECT scanner.

Parameters:

file_AM (str) – File name of attenuation map

Returns:

Tensor of shape [batch_size, Lx, Ly, Lz] corresponding to the atteunation map in units of cm:math:^{-1}

Return type:

torch.Tensor

pytomography.io.SPECT.get_attenuation_map_from_CT_slices(files_CT, file_NM=None, index_peak=0, mode='constant', HU2mu_technique='from_table', E_SPECT=None, output_shape=None)[source]#

Converts a sequence of DICOM CT files (corresponding to a single scan) into a torch.Tensor object usable as an attenuation map in PyTomography.

Parameters:

  • files_CT (Sequence[str]) – List of all files corresponding to an individual CT scan

  • file_NM (str) – File corresponding to raw PET/SPECT data (required to align CT with projections). If None, then no alignment is done. Defaults to None.

  • index_peak (int, optional) – Index corresponding to photopeak in projection data. Defaults to 0.

  • mode (str) – Mode for affine transformation interpolation

  • HU2mu_technique (str) – Technique to convert HU to attenuation coefficients. The default, ‘from_table’, uses a table of coefficients for bilinear curves obtained for a variety of common radionuclides. The technique ‘from_cortical_bone_fit’ looks for a cortical bone peak in the scan and uses that to obtain the bilinear coefficients. For phantom scans where the attenuation coefficient is always significantly less than bone, the cortical bone technique will still work, since the first part of the bilinear curve (in the air to water range) does not depend on the cortical bone fit. Alternatively, one can provide an arbitrary function here which takes in a 3D scan with units of HU and converts to mu.

  • E_SPECT (float) – Energy of the photopeak in SPECT scan; this overrides the energy in the DICOM file, so should only be used if the DICOM file is incorrect. Defaults to None.

  • output_shape (tuple) – Shape of the output attenuation map. If None, then the shape is determined by the NM file.

Returns:

Tensor of shape [Lx, Ly, Lz] corresponding to attenuation map.

Return type:

torch.Tensor

pytomography.io.SPECT.get_energy_window_scatter_estimate(file, index_peak, index_lower, index_upper=None, weighting_lower=0.5, weighting_upper=0.5, proj_meta=None, sigma_theta=0, sigma_r=0, sigma_z=0, N_sigmas=3, return_scatter_variance_estimate=False, use_FOV_mask=False)[source]#

Gets an estimate of scatter projection data from a DICOM file using either the dual energy window (index_upper=None) or triple energy window method.

Parameters:

  • file (str) – Filepath of the DICOM file

  • index_peak (int) – Index of the EnergyWindowInformationSequence DICOM attribute corresponding to the photopeak.

  • index_lower (int) – Index of the EnergyWindowInformationSequence DICOM attribute corresponding to lower scatter window.

  • index_upper (int) – Index of the EnergyWindowInformationSequence DICOM attribute corresponding to upper scatter window. Defaults to None (dual energy window).

  • weighting_lower (float) – Weighting of the lower scatter window. Defaults to 0.5.

  • weighting_upper (float) – Weighting of the upper scatter window. Defaults to 0.5.

  • return_scatter_variance_estimate (bool) – If true, then also return the variance estimate of the scatter. Defaults to False.

  • use_FOV_mask (bool) – If true, then use ta field of view mask obtained from DICOM file. Defaults to False.

  • sigma_theta (float) –

  • sigma_r (float) –

  • sigma_z (float) –

  • N_sigmas (int) –

Returns:

Tensor corresponding to the scatter estimate.

Return type:

torch.Tensor[Ltheta,Lr,Lz]

pytomography.io.SPECT.get_psfmeta_from_scanner_params(collimator_name, energy_keV, min_sigmas=3, material='lead', intrinsic_resolution=0, intrinsic_resolution_140keV=None, shape='gaussian')[source]#

Obtains SPECT PSF metadata given a unique collimator code and photopeak energy of radionuclide. For more information on collimator codes, see the “external data” section of the readthedocs page.

Parameters:

  • collimator_name (str) – Code for the collimator used.

  • energy_keV (float) – Energy of the photopeak

  • min_sigmas (float) – Minimum size of the blurring kernel used. Fixes the convolutional kernel size so that all locations have at least min_sigmas in dimensions (some will be greater)

  • material (str) – Material of the collimator.

  • intrinsic_resolution (float) – Intrinsic resolution (FWHM) of the scintillator crystals. Note that most scanners provide the intrinsic resolution at 140keV only; if you only have access to this, you should use the intrinsic_resolution_140keV argument of this function. Defaults to 0.

  • intrinsic_resolution_140keV (float | None) – Intrinsic resolution (FWHM) of the scintillator crystals at an energy of 140keV. The true intrinsic resolution is calculated assuming the resolution is proportional to E^(-1/2). If provided, then intrinsic_resolution is ignored. Defaults to None.

  • shape (str, optional) – Shape of the PSF. Defaults to ‘gaussian’, in which case sigma is the sigma of the Gaussian. Can also be ‘square’ for square collimators, in this case sigma is half the diameter of the bore.

Returns:

PSF metadata.

Return type:

SPECTPSFMeta

pytomography.io.SPECT.CT_to_mumap(CT, files_CT, file_NM, index_peak=0, technique='from_table', E_SPECT=None)[source]#

Converts a CT image to a mu-map given SPECT projection data. The CT data must be aligned with the projection data already; this is a helper function for get_attenuation_map_from_CT_slices.

Parameters:

  • CT (torch.tensor) – CT object in units of HU

  • files_CT (Sequence[str]) – Filepaths of all CT slices

  • file_NM (str) – Filepath of SPECT projectio ndata

  • index_peak (int, optional) – Index of EnergyInformationSequence corresponding to the photopeak. Defaults to 0.

  • technique (str, optional) – Technique to convert HU to attenuation coefficients. The default, ‘from_table’, uses a table of coefficients for bilinear curves obtained for a variety of common radionuclides. The technique ‘from_cortical_bone_fit’ looks for a cortical bone peak in the scan and uses that to obtain the bilinear coefficients. For phantom scans where the attenuation coefficient is always significantly less than bone, the cortical bone technique will still work, since the first part of the bilinear curve (in the air to water range) does not depend on the cortical bone fit. Alternatively, one can provide an arbitrary function here which takes in a 3D scan with units of HU and converts to mu.

  • E_SPECT (float) – Energy of the photopeak in SPECT scan; this overrides the energy in the DICOM file, so should only be used if the DICOM file is incorrect. If None, then the energy is obtained from the DICOM file.

Returns:

Attenuation map in units of 1/cm

Return type:

torch.tensor

pytomography.io.SPECT.subsample_amap(amap, N)[source]#

Subsamples 3D attenuation map by averaging over N x N x N regions

Parameters:

  • amap (torch.Tensor) – Original attenuation map

  • N (int) – Factor to reduce by

Returns:

Subsampled attenuation map

Return type:

torch.Tensor

pytomography.io.SPECT.subsample_projections_and_modify_metadata(object_meta, proj_meta, projections, N_pixel=1, N_angle=1, N_angle_start=0)[source]#

Subsamples SPECT projection and modifies metadata accordingly

Parameters:

  • object_meta (ObjectMeta) – Object metadata

  • proj_meta (SPECTProjMeta) – Projection metadata

  • projections (torch.Tensor) – Projections to subsample

  • N_pixel (int) – Pixel reduction factor (1 means no reduction). Defaults to 1.

  • N_angle (int) – Angle reduction factor (1 means no reduction). Defaults to 1.

  • N_angle_start (int) – Angle index to start at. Defaults to 0.

Returns:

Modified object metadata, modified projection metadata, subsampled projections

Return type:

Sequence