DICOM

Summary

A DICOM toolbox.

API

Anonymisation

This is the legacy interface. It does not implement a DICOM confidentiality profile, and each call emits an AnonymisationLimitationWarning describing its limitations; this is not a deprecation. Read its limitations in DICOM de-identification before sharing output.

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

Replace the values of a fixed list of identifying attributes in a DICOM dataset.

The default list of keywords is here. It was drawn from DICOM Supplement 142, an earlier version of the attribute confidentiality profile in DICOM PS3.15 Annex E. It contains no UIDs and omits most RT attributes, so Study, Series, SOP Instance, and Frame of Reference UIDs keep their original values, as do attributes such as RT Plan Label, ROI Name, Beam Name, Treatment Machine Name, and RT Plan Date. Nested sequences are processed, but reference sequences on the list, such as Referenced Image Sequence, are replaced with a single empty item by default.

The output can still identify patients; review it before sharing it. See DICOM de-identification for these and other limitations.

We do not claim conformance to any DICOM Application Level Confidentiality Profile.

Parameters:

• ds (pydicom.dataset.Dataset) – The DICOM dataset to be anonymised.

• replace_values (bool, optional) – If True (the default), each listed attribute that has a value is given a fixed dummy value for its value representation, for example ANONYMOUS^PATIENT for person names, ANON for code strings such as Patient’s Sex (not a permitted value), and a single empty item for sequences. Some commercial software needs values to read the file. If False, the values are emptied instead, and OB and OW values become two zero bytes.

• 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 (the default), a modified copy of ds is returned and ds is unchanged. If False, ds is modified in place and None is returned.

• replacement_strategy (dict (keys are VR, value is dispatch function), optional) – If left as the default value of None, the hardcode replacement strategy is used.

• identifying_keywords (list, optional) – If left as None, the default values for/list of identifying keywords are used

Returns:

ds_anon – The modified copy of ds, or None if copy_dataset is False.

Return type:

pydicom.dataset.Dataset or None

class pymedphys.dicom.AnonymisationLimitationWarning

pymedphys.dicom.anonymise has known limitations.

This is not a deprecation warning. No replacement is available yet, so pymedphys.dicom.anonymise is not scheduled for removal.

Dose

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

pymedphys.dicom.zyx_and_dose_from_dataset(dataset)

Return a DICOM RT Dose grid with ascending (z, y, x) DICOM axes.

Parameters:

dataset (pydicom.dataset.Dataset) – An RT Dose dataset whose Image Orientation (Patient) is one of the eight supported transverse cardinal orientations (head or feet first; supine, prone, or decubitus left or right).

Returns:

• coords (tuple of numpy.ndarray) – The (z, y, x) DICOM axes of the dose grid, each strictly ascending.

• dose (numpy.ndarray) – The dose, indexed dose[i_z, i_y, i_x] at (z[i_z], y[i_y], x[i_x]).

Notes

The pixel array is reordered to match the axes: an axis the scanner stored in descending order (for example x for head first prone, or z for feet first) is flipped, and for decubitus orientations, whose rows run along x, rows and columns are swapped. For head first supine with increasing slice offsets the dose is the pixel array unchanged. Head first supine grids with decreasing slice offsets are reversed in z.

Accepted direction cosines within 1e-4 of a supported cardinal orientation are snapped to it for axis extraction; the positional effect grows with grid extent. The rearrangement itself does not resample dose or move voxels. Keep the returned coordinates and dose together when indexing or plotting. Gamma calculated with this pair as its reference has the same shape and index order as the returned dose, which can differ from pixel_array. To recover raw storage order, apply the inverse reversals and dimension permutation to the result.

pymedphys.dicom.depth_dose(depths, dose_dataset, plan_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 IsocenterPosition.

• 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, plan_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 IsocenterPosition.

• 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)

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.

• dicom_dose_dataset (pydicom.Dataset) – An RT DICOM Dose object