Dicom Toolbox

A Dicom toolbox built ontop of the pydicom library.

Available Functions

>>> from pymedphys.dcm import (
...     anonymise_dicom,
...     extract_dose,
...     extract_iec_patient_coords,
...     extract_iec_fixed_coords,
...     extract_dicom_patient_coords,
...     load_dose_from_dicom,
...     load_xyz_from_dicom,
...     find_dose_within_structure,
...     create_dvh,
...     get_structure_aligned_cube)

API

pymedphys.dcm.anonymise_dicom(dcm, delete_private_tags=True, tags_to_keep=None, ignore_unknown_tags=False)[source]

A simple tool to anonymise a DICOM file.

Parameters:
dcm

The DICOM file to be anonymised. dcm must represent a valid DICOM file in the form of a pydicom FileDataset - ordinarily returned by pydicom.dcmread().

delete_private_tags

A boolean to flag whether or not to remove all private (non-standard) DICOM tags from the DICOM file. These may also contain identifying information. Defaults to True.

tags_to_keep

A sequence of DICOM tags to exclude from anonymisation. Empty by default.

ignore_unknown_tags

If pydicom has updated its DICOM dictionary, this function will raise an error since a new identifying tag may have been introduced. Set to True to ignore this error. Defaults to False.

Returns:
dcm_out

An anonymised copy of the input DICOM file as a pydicom FileDataset

Raises:
TypeError

If dcm is not an instance of pydicom.dataset.FileDataset

pymedphys.dcm.extract_dose(dcm)[source]

Extract the dose grid of a DICOM RT Dose file along with dose units, dose type, dose summation type and heterogeneity correction technique.

Parameters:
dcm

A pydicom Dataset - ordinarily returned by pydicom.dcmread(). Must represent a valid DICOM RT Dose file.

Returns:
Dose(values, units, type, summation, heterogeneity_correction)

A namedtuple containing the following fields:

values

A 3D numpy array containing the dose grid’s values in units specified by dose_units.

units

A string indicating whether the dose grid values are in units of Gray (“GY”) or are relative to the implicit reference value (“RELATIVE”).

type

A string indicating whether dose is physical, biological or differences between desired and planned dose values.

summation

A string indicating whether the calculation scope of the dose grid. See Notes.

heterogeneity correction

A list of patient heterogeneity characteristics for which the dose was calculated. Multiple entries may exist if beams in the plan have differing correction techniques.

Notes

This section heavily draws from DICOM PS3.3 2018c - Information Object Definitions [1]

Possible values of type:

type Description
PHYSICAL Physical dose
EFFECTIVE Physical dose corrected for biological effect
ERROR Difference between desired and planned dose

Possible values of summation_type:

summation Dose is calculated for:
PLAN All fraction groups of the RT Plan
MULTI_PLAN Multiple RT plans
FRACTION A single fraction group of the RT Plan
BEAM One or more beams of the RT Plan
BRACHY One or more Brachy Application Setups within the RT Plan
FRACTION_SESSION A single session of a single Fraction Group
BEAM_SESSION A single session of one or more beams
BRACHY_SESSION A single session of one or more Brachy Application Setups
CONTROL_POINT One or more control points within a beam for a single fraction
RECORD The RT Beams Treatment Record

Possible values of heterogeneity_correction:

heterogeneity_correction Dose is calculated using:
IMAGE Unaltered image data
ROI_OVERRIDE Image data where one or more ROIs override density
WATER The entire volume treated as water equivalent
UNKNOWN The TissueHeterogeneityCorrection tag of the DICOM file is empty

References

[1](1, 2) “C8.8.3 RT Dose Module”, DICOM PS3.3 2018c - Information Object Definitions http://dicom.nema.org/medical/dicom/2018c/output/chtml/part03/sect_C.8.8.3.html
pymedphys.dcm.extract_iec_patient_coords(dcm)[source]

Returns the x, y and z coordinates of a DICOM RT Dose file’s dose grid in the IEC patient coordinate system

Parameters:
dcm

A pydicom Dataset - ordinarily returned by pydicom.dcmread(). Must represent a valid DICOM RT Dose file.

Returns:
Coords(x, y, z)

A namedtuple containing three ndarrays corresponding to the x, y and z coordinates of the DICOM RT Dose file’s dose grid in the IEC patient coordinate system [1]:

x

An ndarray of coordinates corresponding to the patient’s left-right axis and increasing to the left hand side of the patient.

y

An ndarray of coordinates corresponding to the patient’s superoinferior axis and increasing toward the head of the patient.

z

An ndarray of coordinates corresponding to the patient’s anteroposterior axis and increasing to the anterior side of the patient.

Notes

Supported scan orientations [2]:

Orientation ImageOrientationPatient
Feet First Decubitus Left [0, 1, 0, 1, 0, 0]
Feet First Decubitus Right [0, -1, 0, -1, 0, 0]
Feet First Prone [1, 0, 0, 0, -1, 0]
Feet First Supine [-1, 0, 0, 0, 1, 0]
Head First Decubitus Left [0, -1, 0, 1, 0, 0]
Head First Decubitus Right [0, 1, 0, -1, 0, 0]
Head First Prone [-1, 0, 0, 0, -1, 0]
Head First Supine [1, 0, 0, 0, 1, 0]

References

[1](1, 2) “IEC 61217:2.0 Radiotherapy equipment – Coordinates, movements and scales”
[2](1, 2) O. McNoleg, “Generalized coordinate transformations for Monte Carlo (DOSXYZnrc and VMC++) verifications of DICOM compatible radiotherapy treatment plans”, arXiv:1406.0014, Table 1, https://arxiv.org/ftp/arxiv/papers/1406/1406.0014.pdf
pymedphys.dcm.extract_iec_fixed_coords(dcm)[source]

Returns the x, y and z coordinates of a DICOM RT Dose file’s dose grid in the IEC fixed coordinate system.

Parameters:
dcm

A pydicom Dataset - ordinarily returned by pydicom.dcmread(). Must represent a valid DICOM RT Dose file.

Returns:
Coords(x, y, z)

A namedtuple containing three ndarrays corresponding to the x, y and z coordinates of the DICOM RT Dose file’s dose grid in the IEC fixed coordinate system [1]:

x

An np.ndarray of coordinates on the horizontal plane that runs orthogonal to the gantry axis of rotation. The x axis increases towards a viewer’s right hand side when facing the gantry standing at the isocentre. The isocentre has an x value of 0.

y

An np.ndarray of coordinates on the horizontal plane that runs parallel to the gantry axis of rotation. The positive direction of the y axis travels from the isocentre to the gantry. The isocentre has a y value of 0.

z

An np.ndarray of coordinates aligned vertically and passing through the isocentre. The positive direction of the z axis travels upwards and the isocentre has a z value of 0.

Notes

Supported scan orientations [2]:

Orientation ImageOrientationPatient
Feet First Decubitus Left [0, 1, 0, 1, 0, 0]
Feet First Decubitus Right [0, -1, 0, -1, 0, 0]
Feet First Prone [1, 0, 0, 0, -1, 0]
Feet First Supine [-1, 0, 0, 0, 1, 0]
Head First Decubitus Left [0, -1, 0, 1, 0, 0]
Head First Decubitus Right [0, 1, 0, -1, 0, 0]
Head First Prone [-1, 0, 0, 0, -1, 0]
Head First Supine [1, 0, 0, 0, 1, 0]

References

[1](1, 2) “IEC 61217:2.0 Radiotherapy equipment – Coordinates, movements and scales”
[2](1, 2) O. McNoleg, “Generalized coordinate transformations for Monte Carlo (DOSXYZnrc and VMC++) verifications of DICOM compatible radiotherapy treatment plans”, arXiv:1406.0014, Table 1, https://arxiv.org/ftp/arxiv/papers/1406/1406.0014.pdf
pymedphys.dcm.extract_dicom_patient_coords(dcm)[source]

Returns the x, y and z coordinates of a DICOM RT Dose file’s dose grid in the DICOM patient coordinate system

Parameters:
dcm

A pydicom Dataset - ordinarily returned by pydicom.dcmread(). Must represent a valid DICOM RT Dose file.

Returns:
Coords(x, y, z)

A namedtuple containing three ndarrays corresponding to the x, y and z coordinates of the DICOM RT Dose file’s dose grid in the DICOM patient coordinate system [1]:

x

An ndarray of coordinates corresponding to the patient’s left-right axis and increasing to the left hand side of the patient.

y

An ndarray of coordinates corresponding to the patient’s anteroposterior axis and increasing to the posterior side of the patient.

z

An ndarray of coordinates corresponding to the patient’s superoinferior axis and increasing toward the head of the patient.

Notes

Supported scan orientations [2]:

Orientation ImageOrientationPatient
Feet First Decubitus Left [0, 1, 0, 1, 0, 0]
Feet First Decubitus Right [0, -1, 0, -1, 0, 0]
Feet First Prone [1, 0, 0, 0, -1, 0]
Feet First Supine [-1, 0, 0, 0, 1, 0]
Head First Decubitus Left [0, -1, 0, 1, 0, 0]
Head First Decubitus Right [0, 1, 0, -1, 0, 0]
Head First Prone [-1, 0, 0, 0, -1, 0]
Head First Supine [1, 0, 0, 0, 1, 0]

References

[1](1, 2) “C.7.6.2.1.1 Image Position and Image Orientation”, “DICOM PS3.3 2016a - Information Object Definitions”, http://dicom.nema.org/MEDICAL/dicom/2016a/output/chtml/part03/sect_C.7.6.2.html#sect_C.7.6.2.1.1
[2](1, 2) O. McNoleg, “Generalized coordinate transformations for Monte Carlo (DOSXYZnrc and VMC++) verifications of DICOM compatible radiotherapy treatment plans”, arXiv:1406.0014, Table 1, https://arxiv.org/ftp/arxiv/papers/1406/1406.0014.pdf
pymedphys.dcm.load_dose_from_dicom(dcm, set_transfer_syntax_uid=True, reshape=True)[source]

Extract the dose grid from a DICOM RT Dose file.

Deprecated since version 0.5.0: load_dose_from_dicom will be removed in a future version of PyMedPhys. It is replaced by extract_dose, which provides additional dose-related information and conforms to a new coordinate system handling convention.

pymedphys.dcm.load_xyz_from_dicom(dcm)[source]

Extract the coordinates of a DICOM RT Dose file’s dose grid.

Deprecated since version 0.5.0: load_xyz_from_dicom will be removed in a future version of PyMedPhys. It is replaced by extract_dicom_patient_coords, extract_iec_patient_coords and extract_iec_fixed_coords, which explicitly work in their respective coordinate systems.

pymedphys.dcm.find_dose_within_structure(structure, dcm_struct, dcm_dose)[source]
pymedphys.dcm.create_dvh(structure, dcm_struct, dcm_dose)[source]
pymedphys.dcm.get_structure_aligned_cube(x0: numpy.ndarray, structure_name: str, dcm_struct: pydicom.dataset.FileDataset, quiet=False, niter=10)[source]

Align a cube to a dicom structure set.

Designed to allow arbitrary references frames within a dicom file to be extracted via contouring a cube.

Parameters:
x0

A 3x3 array with each row defining a 3-D point in space. These three points are used as initial conditions to search for a cube that fits the contours. Choosing initial values close to the structure set, and in the desired orientation will allow consistent results. See examples within pymedphys.geometry.cubify_cube_definition on what the effects of each of the three points are on the resulting cube.

structure_name

The DICOM label of the cube structure

dcm_struct

The pydicom reference to the DICOM structure file.

quiet : bool

Tell the function to not print anything. Defaults to False.

Returns:
cube_definition_array

Four 3-D points the define the vertices of the cube.

vectors

The vectors between the points that can be used to traverse the cube.

Examples

>>> import numpy as np
>>> import pydicom
>>> from pymedphys.dcm import get_structure_aligned_cube
>>>
>>> struct_path = 'data/srs/max_structure_set.dcm'
>>> dcm_struct = pydicom.dcmread(struct_path, force=True)
>>>
>>> x0 = np.array([
...     -270, -35, -20,
...     -270, 30, -20,
...     -260, -35, 40
... ])
>>>
>>> structure_name = 'ANT Box'
>>> cube_definition_array, vectors = get_structure_aligned_cube(
...     x0, structure_name, dcm_struct, quiet=True, niter=1)
>>> np.round(cube_definition_array)
array([[-276.,  -31.,  -16.],
       [-275.,   29.,  -17.],
       [-266.,  -31.,   43.],
       [-217.,  -32.,  -26.]])
>>>
>>> np.round(vectors, 1)
array([[ 0.7, 59.9, -0.5],
       [ 9.7,  0.4, 59.1],
       [59.1, -0.8, -9.7]])