DICOM Module

Summary

A DICOM toolbox.

API

Anonymisation

pymedphys.dicom.anonymise(ds, replace_values=True, keywords_to_leave_unchanged=(), delete_private_tags=True, delete_unknown_tags=None, copy_dataset=True)

A simple tool to anonymise a DICOM dataset.

You can find the list of DICOM keywords that are included in default anonymisation here. These were drawn from DICOM Supp 142

We do not yet claim conformance to any DICOM Application Level Confidentiality Profile, but plan to be in a position to do so in the not-to-distant future.

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

Dose

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

pymedphys.dicom.zyx_and_dose_from_dataset(dataset)

pymedphys.dicom.depth_dose(depths, dose_dataset: pydicom.dataset.Dataset, plan_dataset: pydicom.dataset.Dataset)

Interpolates dose for defined depths within a DICOM dose dataset.

Since the DICOM dose dataset is in CT coordinates the corresponding DICOM plan is also required in order to calculate the conversion between CT coordinate space and depth.

Currently, depth_dose() only supports a dose_dataset for which the patient orientation is HFS and that any beams in plan_dataset have gantry angle equal to 0 (head up). Depth is assumed to be purely in the y axis direction in DICOM coordinates.

Parameters:

• depths (numpy.ndarray) – An array of depths to interpolate within the DICOM dose file. 0 is defined as the surface of the phantom using either the SurfaceEntryPoint parameter or a combination of SourceAxisDistance, SourceToSurfaceDistance, and IsocentrePosition.
• dose_dataset (pydicom.dataset.Dataset) – The RT DICOM dose dataset to be interpolated
• plan_dataset (pydicom.dataset.Dataset) – The RT DICOM plan used to extract surface parameters and verify gantry angle 0 beams are used.

pymedphys.dicom.profile(displacements, depth, direction, dose_dataset: pydicom.dataset.Dataset, plan_dataset: pydicom.dataset.Dataset)

Interpolates dose for cardinal angle horizontal profiles within a DICOM dose dataset.

Since the DICOM dose dataset is in CT coordinates the corresponding DICOM plan is also required in order to calculate the conversion between CT coordinate space and depth and horizontal displacement.

Currently, profile() only supports a dose_dataset for which the patient orientation is HFS and that any beams in plan_dataset have gantry angle equal to 0 (head up). Depth is assumed to be purely in the y axis direction in DICOM coordinates.

Parameters:

• displacements (numpy.ndarray) – An array of displacements to interpolate within the DICOM dose file. 0 is defined in the DICOM z or x directions based either upon the SurfaceEntryPoint or the IsocenterPosition depending on what is available within the DICOM plan file.
• depth (float) – The depth at which to interpolate within the DICOM dose file. 0 is defined as the surface of the phantom using either the SurfaceEntryPoint parameter or a combination of SourceAxisDistance, SourceToSurfaceDistance, and IsocentrePosition.
• direction (str, one of ('inplane', 'inline', 'crossplane', 'crossline')) –

  Corresponds to the axis upon which to apply the displacements.

  • ’inplane’ or ‘inline’ converts to DICOM z direction
  • ’crossplane’ or ‘crossline’ converts to DICOM x direction

• dose_dataset (pydicom.dataset.Dataset) – The RT DICOM dose dataset to be interpolated
• plan_dataset (pydicom.dataset.Dataset) – The RT DICOM plan used to extract surface and isocentre parameters and verify gantry angle 0 beams are used.

pymedphys.dicom.dicom_dose_interpolate(interp_coords, dicom_dose_dataset: pydicom.dataset.Dataset)

Interpolates across a DICOM dose dataset.

Parameters:

• interp_coords (tuple(z, y, x)) – A tuple of coordinates in DICOM order, z axis first, then y, then x where x, y, and z are DICOM axes.
• dose (pydicom.Dataset) – An RT DICOM Dose object