DICOM — PyMedPhys

Toggle navigation sidebar
Toggle in-page Table of Contents

# DICOM

## 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, replacement_strategy=None, identifying_keywords=None)

  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 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 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.

    - 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 – 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, 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 `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, 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 `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)

  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