DICOM Module

Summary

A DICOM toolbox. Available functions include:

>>> from pymedphys.dicom import (
...
...     # Anonymisation functions
...     anonymise_dataset,
...     anonymise_file,
...     anonymise_directory,
...     is_anonymised_dataset,
...     is_anonymised_file,
...     is_anonymised_directory,
...
...     # Coordinate functions
...     coords_from_xyz_axes,
...     xyz_axes_from_dataset,
...
...     # Dose related functions
...     create_dvh,
...     dose_from_dataset,
...     find_dose_within_structure,
...     )

API

Anonymisation

A suite of functions related to DICOM dataset anonymisation.

pymedphys.dicom.anonymise_dataset(ds, replace_values=True, keywords_to_leave_unchanged=(), delete_private_tags=True, delete_unknown_tags=None, copy_dataset=True)[source]

A simple tool to anonymise a DICOM dataset.

Parameters:
  • ds (pydicom.dataset.Dataset) – The DICOM dataset to be anonymised.
  • replace_values (bool, optional) – If set to True, DICOM tags will be anonymised using dummy “anonymous” values. This is often required for commercial software to successfully read anonymised DICOM files. If set to False, anonymised tags are simply given empty string values. Defaults to True.
  • keywords_to_leave_unchanged (sequence, optional) – A sequence of DICOM keywords (corresponding to tags) to exclude from anonymisation. Private and unknown tags can be supplied. Empty by default.
  • 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.
  • delete_unknown_tags (bool, pseudo-optional) – If left as the default value of None and ds contains tags that are not present in PyMedPhys` copy of pydicom’s DICOM dictionary, anonymise_dataset() will raise an error. The user must then either pass True or False to proceed. If set to True, all unrecognised tags that haven’t been listed in keywords_to_leave_unchanged will be deleted. If set to False, these tags are simply ignored. Pass False with caution, since unrecognised tags may contain identifying information.
  • copy_dataset (bool, optional) – If True, then a copy of ds is returned.
Returns:

ds_anon – An anonymised version of the input DICOM dataset.

Return type:

pydicom.dataset.Dataset

pymedphys.dicom.anonymise_file(dicom_filepath, delete_original_file=False, anonymise_filename=True, replace_values=True, keywords_to_leave_unchanged=(), delete_private_tags=True, delete_unknown_tags=None)[source]

A simple tool to anonymise a DICOM file.

Parameters:
  • dicom_filepath (str) – The path to the DICOM file to be anonymised.
  • delete_original_file (bool, optional) – If True and anonymisation completes successfully, then the original DICOM is deleted. Defaults to False.
  • anonymise_filename (bool, optional) –

    If True, the DICOM filename is replaced by a filename of the form:

    ”<2 char DICOM modality>.<SOP Instance UID>_Anonymised.dcm”.

    E.g.: “RP.2.16.840.1.113669.[…]_Anonymised.dcm”

    This ensures that the filename contains no identifying information. If set to False, anonymise_file() simply appends “_Anonymised” to the original DICOM filename. Defaults to True.

  • replace_values (bool, optional) – If set to True, DICOM tags will be anonymised using dummy “anonymous” values. This is often required for commercial software to successfully read anonymised DICOM files. If set to False, anonymised tags are simply given empty string values. Defaults to True.
  • keywords_to_leave_unchanged (sequence, optional) – A sequence of DICOM keywords (corresponding to tags) to exclude from anonymisation. Private and unknown tags can be supplied. Empty by default.
  • 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.
  • delete_unknown_tags (bool, pseudo-optional) – If left as the default value of None and ds contains tags that are not present in PyMedPhys` copy of pydicom’s DICOM dictionary, anonymise_dataset() will raise an error. The user must then either pass True or False to proceed. If set to True, all unrecognised tags that haven’t been listed in keywords_to_leave_unchanged will be deleted. If set to False, these tags are simply ignored. Pass False with caution, since unrecognised tags may contain identifying information.
pymedphys.dicom.anonymise_directory(dicom_dirpath, delete_original_files=False, anonymise_filenames=True, replace_values=True, keywords_to_leave_unchanged=(), delete_private_tags=True, delete_unknown_tags=None)[source]

A simple tool to anonymise all DICOM files in a directory and its subdirectories.

Parameters:
  • dicom_dirpath (str) – The path to the directory containing DICOM files to be anonymised.
  • delete_original_files (bool, optional) – If set to True and anonymisation completes successfully, then the original DICOM files are deleted. Defaults to False.
  • anonymise_filenames (bool, optional) –

    If True, the DICOM filenames are replaced by filenames of the form:

    ”<2 char DICOM modality>.<SOP Instance UID>_Anonymised.dcm”.

    E.g.: “RP.2.16.840.1.113669.[…]_Anonymised.dcm”

    This ensures that the filenames contain no identifying information. If False, anonymise_directory() simply appends “_Anonymised” to the original DICOM filenames. Defaults to True.

  • replace_values (bool, optional) – If set to True, DICOM tags will be anonymised using dummy “anonymous” values. This is often required for commercial software to successfully read anonymised DICOM files. If set to False, anonymised tags are simply given empty string values. Defaults to True.
  • keywords_to_leave_unchanged (sequence, optional) – A sequence of DICOM keywords (corresponding to tags) to exclude from anonymisation. Private and unknown tags can be supplied. Empty by default.
  • 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.
  • delete_unknown_tags (bool, pseudo-optional) – If left as the default value of None and ds contains tags that are not present in PyMedPhys` copy of pydicom’s DICOM dictionary, anonymise_dataset() will raise an error. The user must then either pass True or False to proceed. If set to True, all unrecognised tags that haven’t been listed in keywords_to_leave_unchanged will be deleted. If set to False, these tags are simply ignored. Pass False with caution, since unrecognised tags may contain identifying information.
pymedphys.dicom.is_anonymised_dataset(ds, ignore_private_tags=False)[source]

Check whether a DICOM dataset has been (fully) anonymised.

This function specifically checks whether the dataset has been anonymised using a PyMedPhys anonymiser. It is very likely that it will return False for an anonymous dataset that was anonymised using a different tool.

Parameters:
  • ds (pydicom.dataset.Dataset) – The DICOM dataset to check for anonymity
  • ignore_private_tags (bool, optional) – If set to False, is_anonymised_dataset() will return False if any private (non-standard) DICOM tags exist in ds. Set to True to ignore private tags when checking for anonymity. Do so with caution, since private tags may contain identifying information. Defaults to False.
Returns:

is_anonymisedTrue if ds has been anonymised, False otherwise.

Return type:

bool

pymedphys.dicom.is_anonymised_file(filepath, ignore_private_tags=False)[source]

Check whether a DICOM file has been (fully) anonymised.

This function specifically checks whether the DICOM file has been anonymised using a PyMedPhys anonymiser. It is very likely that it will return False for an anonymous DICOM file that was anonymised using a different tool.

Parameters:
  • filepath (str) – The path to the DICOM file to check for anonymity.
  • ignore_private_tags (bool, optional) – If set to False, is_anonymised_file() will return False if any private (non-standard) DICOM tags exist in the DICOM file. Set to True to ignore private tags when checking for anonymity. Do so with caution, since private tags may contain identifying information. Defaults to False.
Returns:

is_anonymisedTrue if the DICOM dataset read from filepath has been anonymised, False otherwise.

Return type:

bool

pymedphys.dicom.is_anonymised_directory(dirpath, ignore_private_tags=False)[source]

Check whether all DICOM files in a directory have been (fully) anonymised.

This function specifically checks whether the DICOM files have been anonymised using a PyMedPhys anonymiser. It is very likely that it will return False for an anonymous DICOM file that was anonymised using a different tool.

Parameters:
  • dirpath (str) – The path to the directory containing DICOM files to check for anonymity.
  • ignore_private_tags (bool, optional) – If set to False, is_anonymised_directory() will return False if any private (non-standard) DICOM tags exist in any of the DICOM files in dirpath. Set to True to ignore private tags when checking for anonymity. Do so with caution, since private tags may contain identifying information. Defaults to False.
Returns:

is_anonymisedTrue if all of the DICOM datasets read from dirpath have been anonymised, False otherwise.

Return type:

bool

Coordinates

A suite of functions assist with coordinate handling for DICOM datasets of a relevant modality, such as ‘CT’ or ‘RTDOSE’.

pymedphys.dicom.coords_from_xyz_axes(xyz_axes)[source]

Converts a set of x, y and z axes of a regular grid (e.g. a DICOM pixel array) into an array of three grids whose voxels correspond to and contain the x, y, and z coordinates of the original grid.

Parameters:xyz_axes (tuple) – A tuple containing three ndarrays corresponding to the x, y and z axes of a given 3D grid - usually a DICOM dataset’s pixel array.
Returns:coords – An array containing three grids consisting of the x, ‘y` and z coordinates of the corresponding grid (e.g. DICOM dataset’s pixel array) from which the original axes were extracted.
Return type:ndarray
pymedphys.dicom.xyz_axes_from_dataset(ds, coord_system='DICOM')[source]

Returns the x, y and z axes of a DICOM dataset’s pixel array in the specified coordinate system.

For DICOM RT Dose datasets, these are the x, y, z axes of the dose grid.

Parameters:
  • ds (pydicom.dataset.Dataset) – A DICOM dataset that contains pixel data. Supported modalities include ‘CT’ and ‘RTDOSE’.
  • coord_system (str, optional) –

    The coordinate system in which to return the x, y and z axes of the DICOM dataset. The accepted, case-insensitive values of coord_system are:

    ’DICOM’ or ‘d’:
    Return axes in the DICOM coordinate system.
    ’patient’, ‘IEC patient’ or ‘p’:
    Return axes in the IEC patient coordinate system.
    ’fixed’, ‘IEC fixed’ or ‘f’:
    Return axes in the IEC fixed coordinate system.
Returns:

A tuple containing three ndarrays corresponding to the x, y and z axes of the DICOM dataset’s pixel array in the specified coordinate system.

Return type:

(x, y, z)

Notes

Supported scan orientations [1]:

Orientation ds.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]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

Dose

A suite of functions for manipulating dose in a DICOM context.

pymedphys.dicom.create_dvh(structure, dcm_struct, dcm_dose)[source]
pymedphys.dicom.dose_from_dataset(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: dose_from_dataset will be removed in a future version of PyMedPhys in favour of a new & improved API.

pymedphys.dicom.find_dose_within_structure(structure_name, dcm_struct, dcm_dose)[source]

RT Structure

A suite of functions that apply specifically to DICOM RT Structure sets

pymedphys.dicom.get_structure_aligned_cube(structure_name: str, dcm_struct: pydicom.dataset.FileDataset, quiet=False, niter=10, x0=None)[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:
  • 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.
  • x0 (np.ndarray, optional) – 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. By default, this parameter is defined using the min/max values of the contour structure.
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.geometry import get_structure_aligned_cube
>>>
>>> struct_path = 'packages/pymedphys_dicom/tests/data/struct/example_structures.dcm'
>>> dcm_struct = pydicom.dcmread(struct_path, force=True)
>>> structure_name = 'ANT Box'
>>> cube_definition_array, vectors = get_structure_aligned_cube(
...     structure_name, dcm_struct, quiet=True, niter=1)
>>> np.round(cube_definition_array)
array([[-266.,  -31.,   43.],
       [-266.,   29.,   42.],
       [-207.,  -31.,   33.],
       [-276.,  -31.,  -16.]])
>>>
>>> np.round(vectors, 1)
array([[  0.7,  59.9,  -0.5],
       [ 59.2,  -0.7,  -9.7],
       [ -9.7,  -0.4, -59.2]])