skrt.dicom_writer module

Class DicomWriter for writing data in DICOM format.

DICOM writing is supported for instances of:

  • skrt.dose.Dose;

  • skrt.image.Image;

  • skrt.simulation.SyntheticImage.

class skrt.dicom_writer.DicomWriter(outdir=None, data=None, affine=None, overwrite=True, header_source=None, orientation=None, patient_id=None, patient_position=None, modality=None, root_uid=None, header_extras=None, source_type=None, outname=None, use_image_header=True)

Bases: object

Class to help with writing data in DICOM format.

DICOM writing is supported for instances of:

  • skrt.dose.Dose;

  • skrt.image.Image;

  • skrt.structures.StructureSet.

Methods:

  • _init__() : Create instance of DicomWriter class.

  • add_image_info() : Add image information to file dataset.

  • add_structure_set_info() : Add structure-set information to file dataset.

  • create_file_dataset() : Create new pydicom.dataset.FileDataset object.

  • get_file_dataset() : Retrive pydicom.dataset.FileDataset from source.

  • get_media_storage_sop_class_uid() : Determine uid given modality.

  • get_path_with_timestamp() : Obtain path to file with timestamped name.

  • initialise_outdir() : Initialis directory for writing output.

  • new_rt_roi_observation() : Create new pydicom.dataset.Dataset object representing an RT ROI observation.

  • new_roi_contour() : Create new pydicom.dataset.Dataset object representing an ROI contour.

  • set_data_and_time() : Set current date and time.

  • set_geometry_and_scaling() : Add geometry and scaling to dataset.

  • set_image() : Add to dataset information for full (3d) image.

  • set_image_slice() : Add to dataset information for (2d) image slice.

  • set_structure_set() : Add to dataset information for structure set.

  • update_dataset() : Make arbitrary updates to dataset.

  • write() : Write data in DICOM format.

__init__(outdir=None, data=None, affine=None, overwrite=True, header_source=None, orientation=None, patient_id=None, patient_position=None, modality=None, root_uid=None, header_extras=None, source_type=None, outname=None, use_image_header=True)

Create instance of DicomWriter class.

Parameters:

outdirstr/pathlib.Path, default=None

Path to directory where data are to be written.

datanumpy.array/skrt.structures.StructureSet, default=None

Data to be written in DICOM format. For source type “Dose” or “Image”, this should be image-type data, stored in a numpy array. For source type “StructureSet”, this should be a skrt.structures.StructureSet object.

affine4x4 array, default=None

Array containing the affine matrix associated with image-type data.

overwritebool, default=True

If True, delete any pre-existing DICOM files from output directory before writing.

header_sourcestr/pydicom.dataset.FileDataset/None, default=None

Source from which to create DICOM header. This can be: (a) a path to a dicom file, which will be used as the header; (b) a path to a directory containing dicom files, where

the first file alphabetically will be used as the header;

  1. a pydicom.dataset.FileDataset object;

  2. None, in which case a header will be created from scratch, inculding new UIDs.

orientation6-element list, default=None

Direction cosines indicating image orientation. If None, set to standard DICOM-style orientation, [1, 0, 0, 0, 1, 0], such that [column, row, slice] correspond to the axes [x, y, z].

patient_idstr, default=None

Patient identifier.

patient_positionstr, default=None

Indicator of patient position relative to imaging equipment. Examples include: “HFS” (head first, supine), “FFP” (feet first, prone), “FFS” (feet first, supine). If None, use “HFS”.

modalitystr, default=None

Modality of data collection. Supported modalities are ‘CT’ and ‘RTDOSE’. If None, the modality is taken to be ‘CT’.

root_uidstr, default=None

Root to be used in Globally Unique Identifiers (GUIDs). This should uniquely identify the institution or group generating the GUID. If None, the value of pydicom.uid.PYDICOM_ROOT_UID is used.

A unique root identifier can be obtained free of charge from Medical Connections: https://www.medicalconnections.co.uk/FreeUID/

header_extrasdict, default=None

Dictionary of attribute-value pairs for applying arbitary updates to a pydicom.dataset.FileDataset.

source_typestr, default=None

Name of the class for which the DicomWriter instance is created. This affects the information included when a pydicom.dataset.FileDataset is created from scratch. Values of source_type for which relevant behaviour is implemented are:

  • ‘Dose’;

  • ‘Image’;

  • ‘StructureSet’.

outnamestr, default=None

Name to use for output file for Dose and StructureSet. If None, a name including modality and timestamp is generated. This parameter is disregarded for Images, where names correspond to sequential numbering.

add_image_info()

Add image-specfic information to own file dataset.

add_structure_set_info()

Add structure-set-specfic information to own file dataset.

create_file_dataset()

Create new pydicom.dataset.FileDataset object.

generate_shortened_uid(max_length=55)

Return shortened UID.

UIDs generated by pydicom.uid.generate_uid() are up to 64 characters. Some UIDs need to have additional characters appended, for example to identify image slices. This can result in UIDs that are longer than is allowed by the DICOM standard. To avoid this, the initial UIDs may be shortened.

Parameter:

max_lengthint, default=-10

Length to which UID should be shortened. If the UID initially generated is shorter than this, then it’s returned unchanged.

get_file_dataset()

Attempt to retrieve pydicom.dataset.FileDataset from source.

get_media_storage_sop_class_uid()

Map to media storage SOP class UID for selected modalities.

Note that in general the mapping between modality and media storage SOP class UID is one to many.

get_path_with_timestamp(check_interval=0.5)

Obtain path to file with timestamped name.

The timestamp is iteratively updated to ensure that any existing file isn’t overwritten.

Parameter:

check_interval: float, default=0.5

Interval in seconds to pause before updating timestamp.

initialise_outdir()

Prepare directory where output data are to be written.

If the output directory doesn’t exist then it is created. If overwrite is True and the output directory contains DICOM files, these are deleted.

new_roi_contour(number, roi, image)

Create dataset representing an ROI contour.

Parameters:

numberint

Integer identifying ROI.

roiskrt.structures.ROI

ROI object for which contour data are to be stored.

image

new_rt_roi_observation(number, name)

Create dataset representing an RT ROI observation.

Parameters:

number

name

set_date_and_time()

Obtain current time and store formatted values for date and time.

set_geometry_and_scaling()

Add to dataset information relating to geometry and scaling.

set_image()

Add to dataset information for full (3d) image.

set_image_slice(idx=0)

Add to dataset information for (2d) image slice.

Parameters:

idxint, default=0

Slice array index.

set_referenced_frame_of_reference_sequence(image)

Set attributes for referenced frame of reference sequence.

Parameter:

imageskrt.image.Image

Image from which attributes of referenced frame of reference are to be determined. If no associated DICOM dataset can be loaded for this image, then self.dset.ReferencedFrameOfReferenceSequence is set as an empty sequence.

set_structure_set()

Add to dataset information for structure set.

The contour data saved is all that’s needed for scikit-rt. Several DICOM sequences are left empty, or partially populated, which outside of scikit-rt may sometimes cause problems.

update_dataset()

Make arbitary updates to dataset, based on self.header_extras.

write()

Write data in DICOM format.