DICOM Toolbox

A Dicom toolbox built ontop of the pydicom library.

Available Functions

>>> from pymedphys.dicom import (
...     anonymise_dicom_dataset,
...     extract_iec_patient_xyz,
...     extract_iec_fixed_xyz,
...     extract_dicom_patient_xyz,
...     load_dose_from_dicom,
...     load_xyz_from_dicom,
...     find_dose_within_structure,
...     create_dvh,
...     get_structure_aligned_cube)

API

pymedphys.dicom.anonymise_dicom_dataset(ds, replace_values=True, delete_private_tags=True, keywords_to_keep=None, ignore_unknown_tags=False, copy=True)[source]

A simple tool to anonymise a DICOM file.

Parameters:
ds

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

replace_values : bool, optional

If set to True, anonymised tag values will be replaced with dummy “anonymous” values. This is often required for successful reading of anonymised DICOM files in commercial software. If set to False, anonymised tags are simply given empty string values. Defaults to True.

delete_private_tags : bool, optional

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.

keywords_to_keep : sequence, optional

A sequence of DICOM keywords (corresponding to tags) to exclude from anonymisation. Empty by default.

ignore_unknown_tags : bool, optional

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:
ds_anon

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

Raises:
ValueError

Raised if ignore_unknown_tags is set to False and unrecognised, non-private DICOM tags are detected in ds

pymedphys.dicom.extract_iec_patient_xyz(ds)[source]

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

Parameters:
ds

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

Returns:
(x, y, z)

A tuple 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 corresponds to the patient’s left-right axis and increases toward the left hand side of the patient.

y corresponds to the patient’s superoinferior axis and increases toward the head of the patient.

z corresponds to the patient’s anteroposterior axis and increases 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.dicom.extract_iec_fixed_xyz(ds)[source]

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

Parameters:
ds

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

Returns:
(x, y, z)

A tuple 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.dicom.extract_dicom_patient_xyz(ds)[source]

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

Parameters:
ds

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

Returns:
(x, y, z)

A tuple 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 corresponds to the patient’s left-right axis and increases to the left hand side of the patient.

y corresponds to the patient’s anteroposterior axis and increases toward the posterior side of the patient.

z corresponds to the patient’s superoinferior axis and increases 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.dicom.load_dose_from_dicom(ds, 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.dicom.load_xyz_from_dicom(ds)[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.dicom.find_dose_within_structure(structure, dcm_struct, dcm_dose)[source]
pymedphys.dicom.create_dvh(structure, dcm_struct, dcm_dose)[source]
pymedphys.dicom.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.dicom import get_structure_aligned_cube
>>>
>>> struct_path = 'tests/data/dicom_struct/example_structures.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]])