`pytomography.io.SPECT.dicom`#

Module Contents#

Functions#

`parse_projection_dataset`(ds)	Gets projections with corresponding radii and angles corresponding to projection data from a DICOM file.
`get_metadata`(file[, index_peak])	Gets PyTomography metadata from a .dcm file.
`get_projections`(file[, index_peak, index_time, ...])	Gets projections from a .dcm file.
`get_energy_window_bounds`(file_NM, idx)	Get the energy window bounds from a DICOM file corresponding to energy window index idx.
`get_window_width`(ds, index)	Computes the width of an energy window corresponding to a particular index in the DetectorInformationSequence DICOM attribute.
`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_energy_window_scatter_estimate_projections`(file, ...)	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. This is seperate from `get_energy_window_scatter_estimate` as it allows a user to input projecitons that are already loaded/modified. This is useful for when projection data gets mixed for reconstructing multiple bed positions.
`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_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`.
`bilinear_transform`(HU, a1, a2, b1, b2)	Function used to convert between Hounsfield Units at an effective CT energy and linear attenuation coefficient at a given SPECT radionuclide energy. It consists of two distinct linear curves in regions \(HU<0\) and \(HU \geq 0\).
`get_HU2mu_conversion`(files_CT, E_SPECT)	Obtains the HU to mu conversion function that converts CT data to the required linear attenuation value in units of 1/cm required for attenuation correction in SPECT/PET imaging.
`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_affine_spect_projections`(filename)	Computes an affine matrix corresponding the coordinate system of a SPECT DICOM file of projections.
`load_multibed_projections`(files_NM)	This function loads projection data from each of the files in files_NM; for locations outside the FOV in each projection, it appends the data from the adjacent projection (it uses the midway point between the projection overlap).
`stitch_multibed`(recons, files_NM[, ...])	Stitches together multiple reconstructed objects corresponding to different bed positions.
`get_aligned_rtstruct`(file_RT, file_NM, ...[, ...])	Loads an RT struct file and aligns it with SPECT projection data corresponding to `file_NM`.
`get_aligned_nifti_mask`(file_nifti, file_NM, ...[, ...])	Loads an RT struct file and aligns it with SPECT projection data corresponding to `file_NM`.
`get_FOV_mask_from_projections`(file_NM[, projections, ...])
`get_mean_stray_radiation_counts`(file_blank, file_NM[, ...])
`get_mean_stray_radiation_counts_MEW_scatter`(...[, ...])
`save_dcm`(save_path, object, file_NM[, recon_name, ...])	Saves the reconstructed object object to a series of DICOM files in the folder given by save_path. Requires the filepath of the projection data file_NM to get Study information.
`get_starguide_projections`(files_NM[, index_peak])	Obtain projections from the sequence of files corresponding to a single starguide acquisition; there should be 12 files (one for each head position). The projections are sorted by energy window.
`get_starguide_metadata`(files_NM[, index_peak, ...])	Obtains the metadata for a Starguide SPECT acquisition.
`get_starguide_affine_CT`(files_CT)	Obtain the affine matrix for a Starguide CT acquisition.
`get_starguide_affine_NM`(files_NM)	Obtain the affine matrix for a Starguide NM acquisition.
`get_starguide_attenuation_map_from_CT_slices`(files_CT, ...)	Obtain the attenuation map for a Starguide SPECT acquisition from a sequence of CT files.
`print_energy_window_info`(file_NM)	A helper function to trints the energy window information for a given NM file.

pytomography.io.SPECT.dicom.parse_projection_dataset(ds)[source]#

Gets projections with corresponding radii and angles corresponding to projection data from a DICOM file.

Parameters:: ds (Dataset) – pydicom dataset object.
Returns:: Returns (i) projection data (ii) angles (iii) radii and (iv) flags for whether or not multiple energy windows/time slots were detected.
Return type:: (torch.tensor[EWindows, TimeWindows, Ltheta, Lr, Lz], np.array, np.array)

pytomography.io.SPECT.dicom.get_metadata(file, index_peak=0)[source]#

Gets PyTomography metadata from a .dcm file.

Parameters:

file (str) – Path to the .dcm file of SPECT projection data.
index_peak (int) – EnergyWindowInformationSequence index corresponding to the photopeak. Defaults to 0.

Returns:

Required metadata information for reconstruction in PyTomography.

Return type:

(ObjectMeta, ProjMeta)

pytomography.io.SPECT.dicom.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.dicom.get_energy_window_bounds(file_NM, idx)[source]#

Get the energy window bounds from a DICOM file corresponding to energy window index idx.

Parameters:

file_NM (str) – File to get energy window bounds from.
idx (int) – Index of the energy window

Returns:

Lower and upper bounds

Return type:

tuple[float, float]

pytomography.io.SPECT.dicom.get_window_width(ds, index)[source]#

Computes the width of an energy window corresponding to a particular index in the DetectorInformationSequence DICOM attribute.

Parameters:

ds (Dataset) – DICOM dataset.
index (int) – Energy window index corresponding to the DICOM dataset.

Returns:

Range of the energy window in keV

Return type:

float

pytomography.io.SPECT.dicom.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.dicom.get_energy_window_scatter_estimate_projections(file, projections, 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. This is seperate from get_energy_window_scatter_estimate as it allows a user to input projecitons that are already loaded/modified. This is useful for when projection data gets mixed for reconstructing multiple bed positions.

Parameters:

file (str) – Filepath of the DICOM file
projections (torch.Tensor) – Loaded projection data
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.
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.
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.dicom.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.dicom.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.dicom.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.dicom.bilinear_transform(HU, a1, a2, b1, b2)[source]#

Function used to convert between Hounsfield Units at an effective CT energy and linear attenuation coefficient at a given SPECT radionuclide energy. It consists of two distinct linear curves in regions \(HU<0\) and \(HU \geq 0\).

Parameters:

HU (float) – Hounsfield units at CT energy
a1 (float) – Fit parameter 1
a2 (float) – Fit parameter 2
b1 (float) – Fit parameter 3
b2 (float) – Fit parameter 4

Returns:

Linear attenuation coefficient at SPECT energy

Return type:

float

pytomography.io.SPECT.dicom.get_HU2mu_conversion(files_CT, E_SPECT)[source]#

Obtains the HU to mu conversion function that converts CT data to the required linear attenuation value in units of 1/cm required for attenuation correction in SPECT/PET imaging.

Parameters:

files_CT (Sequence[str]) – CT data files
CT_kvp (float) – kVp value for CT scan
E_SPECT (float) – Energy of photopeak in SPECT scan

Returns:

Conversion function from HU to mu.

Return type:

function

pytomography.io.SPECT.dicom.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.dicom._get_affine_spect_projections(filename)[source]#

Computes an affine matrix corresponding the coordinate system of a SPECT DICOM file of projections.

Parameters:

ds (Dataset) – DICOM dataset of projection data
filename (str) –

Returns:

Affine matrix

Return type:

np.array

pytomography.io.SPECT.dicom.load_multibed_projections(files_NM)[source]#

This function loads projection data from each of the files in files_NM; for locations outside the FOV in each projection, it appends the data from the adjacent projection (it uses the midway point between the projection overlap).

Parameters:: files_NM (str) – Filespaths for each of the projections
Returns:: Tensor of shape [N_bed_positions, N_energy_windows, Ltheta, Lr, Lz].
Return type:: torch.Tensor

pytomography.io.SPECT.dicom.stitch_multibed(recons, files_NM, return_stitching_weights=False)[source]#

Stitches together multiple reconstructed objects corresponding to different bed positions.

Parameters:

recons (torch.Tensor[n_beds, Lx, Ly, Lz]) – Reconstructed objects. The first index of the tensor corresponds to different bed positions
files_NM (list) – List of length n_beds corresponding to the DICOM file of each reconstruction
return_stitching_weights (bool) – If true, instead of returning stitched reconstruction, instead returns the stitching weights (and z location in the stitched image) for each bed position (this is used as a tool for uncertainty estimation in multi bed positions). Defaults to False

Returns:

Stitched together DICOM file. Note the new z-dimension size \(L_z'\).

Return type:

torch.Tensor[Lx, Ly, Lz’]

pytomography.io.SPECT.dicom.get_aligned_rtstruct(file_RT, file_NM, dicom_series_path, rt_struct_name, cutoff_value=0.5, shape=None)[source]#

Loads an RT struct file and aligns it with SPECT projection data corresponding to file_NM.

Parameters:

file_RT (str) – Filepath of the RT Struct file
file_NM (str) – Filepath of the NM file (used to align the RT struct)
dicom_series_path (str) – Filepath of the DICOM series linked to the RTStruct file (required for loading RTStructs).
rt_struct_name (str) – Name of the desired RT struct.
cutoff_value (float, optional) – After interpolation is performed to align the mask in the new frame, mask voxels with values less than this are excluded. Defaults to 0.5.

Returns:

RTStruct mask aligned with SPECT data.

Return type:

torch.Tensor

pytomography.io.SPECT.dicom.get_aligned_nifti_mask(file_nifti, file_NM, dicom_series_path, mask_idx, cutoff_value=0.5, shape=None)[source]#

Loads an RT struct file and aligns it with SPECT projection data corresponding to file_NM.

Parameters:

file_nifti (str) – Filepath of the nifti file containing the reconstruction mask
file_NM (str) – Filepath of the NM file (used to align the RT struct)
dicom_series_path (str) – Filepath of the DICOM series linked to the RTStruct file (required for loading RTStructs).
mask_idx (str) – Integer in nifti mask corresponding to ROI.
cutoff_value (float, optional) – After interpolation is performed to align the mask in the new frame, mask voxels with values less than this are excluded. Defaults to 0.5.

Returns:

RTStruct mask aligned with SPECT data.

Return type:

torch.Tensor

pytomography.io.SPECT.dicom.get_FOV_mask_from_projections(file_NM, projections=None, contraction=1)[source]#

pytomography.io.SPECT.dicom.get_mean_stray_radiation_counts(file_blank, file_NM, index_peak=None)[source]#

pytomography.io.SPECT.dicom.get_mean_stray_radiation_counts_MEW_scatter(file_blank, file_NM, index_peak, index_lower, index_upper=None, weighting_lower=0.5, weighting_upper=0.5)[source]#

pytomography.io.SPECT.dicom.save_dcm(save_path, object, file_NM, recon_name='pytomo_recon', return_ds=False, single_dicom_file=False, scale_by_number_projections=False)[source]#

Saves the reconstructed object object to a series of DICOM files in the folder given by save_path. Requires the filepath of the projection data file_NM to get Study information.

Parameters:

object (torch.Tensor) – Reconstructed object of shape [Lx,Ly,Lz].
save_path (str) – Location of folder where to save the DICOM output files.
file_NM (str) – File path of the projection data corresponding to the reconstruction.
recon_name (str) – Type of reconstruction performed. Obtained from the recon_method_str attribute of a reconstruction algorithm class.
return_ds (bool) – If true, returns the DICOM dataset objects instead of saving to file. Defaults to False.
single_dicom_file (bool) –
scale_by_number_projections (bool) –

Return type:

None

pytomography.io.SPECT.dicom.get_starguide_projections(files_NM, index_peak=None)[source]#

Obtain projections from the sequence of files corresponding to a single starguide acquisition; there should be 12 files (one for each head position). The projections are sorted by energy window.

Parameters:

files_NM (Sequence[str]) – Sequence of files corresponding to the acquisition (one file for each head)
index_peak (int | None, optional) – Photopeak index; if None then returns all energy peaks. Defaults to None.

Returns:

StarGuide projeciton data

Return type:

torch.Tensor

pytomography.io.SPECT.dicom.get_starguide_metadata(files_NM, index_peak=0, nearest_theta=1.0)[source]#

Obtains the metadata for a Starguide SPECT acquisition.

Parameters:

files_NM (Sequence[str]) – Sequence of NM files for a StarGuide acqusition
index_peak (int, optional) – Photopeak index for reconstruction. Defaults to 0.
nearest_theta (float, optional) – Nearest theta to round angles to. Defaults to 1.0.

Returns:

Object meta and projection data for the acquisition.

Return type:

Sequence

pytomography.io.SPECT.dicom.get_starguide_affine_CT(files_CT)[source]#

Obtain the affine matrix for a Starguide CT acquisition.

Parameters:: files_CT (Sequence[str]) – Files corresponding to the CT acquisition
Returns:: Affine matrix for the CT acquisition
Return type:: np.array

pytomography.io.SPECT.dicom.get_starguide_affine_NM(files_NM)[source]#

Obtain the affine matrix for a Starguide NM acquisition.

Parameters:: files_NM (Sequence[str]) – Files corresponding to the NM acquisition
Returns:: Affine matrix for the NM acquisition
Return type:: np.array

pytomography.io.SPECT.dicom.get_starguide_attenuation_map_from_CT_slices(files_CT, files_NM, index_peak=0, mode='constant', E_SPECT=None)[source]#

Obtain the attenuation map for a Starguide SPECT acquisition from a sequence of CT files.

Parameters:

files_CT (Sequence[str]) – CT files corresponding to the acquisition
files_NM (Sequence[str]) – NM files corresponding to the acquisition
index_peak (int, optional) – Index corresponding to photopeak. Defaults to 0.
mode (str, optional) – Mode for the affine matrix. Defaults to “constant”.
E_SPECT (float | None, optional) – Energy of SPECT; this overrights the energy from index_peak if provided. Defaults to None.

Returns:

Attenuation map in units of 1/cm

Return type:

torch.Tensor

pytomography.io.SPECT.dicom.print_energy_window_info(file_NM)[source]#

A helper function to trints the energy window information for a given NM file. :param file_NM: Filepath of the NM file :type file_NM: str

Parameters:: file_NM (str) –

pytomography.io.SPECT.dicom#

Module Contents#

Functions#

This Page

`pytomography.io.SPECT.dicom`#