dicomparser module¶

Class that parses and returns formatted DICOM RT data.

class dicompylercore.dicomparser.DicomParser(dataset)[source]¶

Bases: object

Parses DICOM / DICOM RT files.

CalculatePlaneThickness(planesDict)[source]¶: Calculates the plane thickness for each structure.

CalculateStructureVolume(coords, thickness)[source]¶

Calculates the volume of the given structure.

Parameters

coords (dict) – Coordinates of each plane of the structure
thickness (float) – Thickness of the structure

GetContourPoints(array)[source]¶: Parses an array of xyz points & returns a array of point dicts.

GetDVHs()[source]¶: Returns cumulative dose-volume histograms (DVHs).

GetDefaultImageWindowLevel()[source]¶: Determine the default window/level for the DICOM image.

GetDemographics()[source]¶: Return the patient demographics from a DICOM file.

GetDoseData()[source]¶: Return the dose data from a DICOM RT Dose file.

GetDoseGrid(z=0, threshold=0.5)[source]¶

Return the 2d dose grid for the given slice position (mm).

Parameters

z – Slice position in mm.
threshold – Threshold in mm to determine the max difference from z to the closest dose slice without using interpolation.

Returns

An numpy 2d array of dose points.

GetFrameOfReferenceUID()[source]¶: Determine the Frame of Reference UID of the current file.

GetImage(window=0, level=0, size=None, background=False, frames=0)[source]¶: Return the image from a DICOM image storage file.

GetImageData()[source]¶: Return the image data from a DICOM file.

GetImageLocation()[source]¶: Calculate the location of the current image slice.

GetImageOrientationType()[source]¶: Get the orientation of the current image slice.

GetIsodosePoints(z=0, level=100, threshold=0.5)[source]¶

Return points for the given isodose level and slice position: from the dose grid.

Parameters

z – Slice position in mm.
threshold – Threshold in mm to determine the max difference from z to the closest dose slice without using interpolation.
level – Isodose level in scaled form (multiplied by self.ds.DoseGridScaling)

Returns

An array of tuples representing isodose points.

GetLUTValue(data, window, level)[source]¶: Apply the RGB Look-Up Table for the data and window/level value.

GetNumberOfFrames()[source]¶: Return the number of frames in a DICOM image file.

GetPatientToPixelLUT()[source]¶: Get the image transformation matrix from the DICOM standard Part 3 Section C.7.6.2.1.1

GetPlan()[source]¶: Returns the plan information.

GetReferencedBeamNumber()[source]¶: Return the referenced beam number (if it exists) from RT Dose.

GetReferencedBeamsInFraction(fx=0)[source]¶: Return the referenced beams from the specified fraction.

GetReferencedRTPlan()[source]¶: Return the SOP Class UID of the referenced RT plan.

GetReferencedSeries()[source]¶: Return the SOP Class UID of the referenced series.

GetReferencedStructureSet()[source]¶: Return the SOP Class UID of the referenced structure set.

GetRescaleInterceptSlope()[source]¶: Return the rescale intercept and slope if present.

GetSOPClassUID()[source]¶: Determine the SOP Class UID of the current file.

GetSOPInstanceUID()[source]¶: Determine the SOP Class UID of the current file.

GetSeriesDateTime()[source]¶: Return the series date/time information.

GetSeriesInfo()[source]¶: Return the series information of the current file.

GetStructureCoordinates(roi_number)[source]¶: Get the list of coordinates for each plane of the structure.

GetStructureInfo()[source]¶: Return the patient demographics from a DICOM file.

GetStructures()[source]¶: Returns a dictionary of structures (ROIs).

GetStudyInfo()[source]¶: Return the study information of the current file.

HasDVHs()[source]¶: Returns whether dose-volume histograms (DVHs) exist.

InterpolateDosePlanes(uplane, lplane, fz)[source]¶

Interpolates a dose plane between two bounding planes at the given: relative location.

Parameters

uplane – Upper dose plane boundary.
uplane – Lower dose plane boundary.
fz – Fractional distance from the bottom to the top, where the new plane is located. E.g. if fz = 1, the plane is at the upper plane, fz = 0, it is at the lower plane.

Returns

An numpy 2d array of the interpolated dose plane.

dvh module¶

Class that stores dose volume histogram (DVH) data.

class dicompylercore.dvh.DVH(counts, bins, dvh_type='cumulative', dose_units='Gy', volume_units='cm3', rx_dose=None, name=None, color=None, notes=None)[source]¶

Bases: object

Class that stores dose volume histogram (DVH) data.

absolute_dose(rx_dose=None, dose_units='Gy')[source]¶

Return an absolute dose DVH.

Parameters

rx_dose (number, optional) – Prescription dose value used to normalize dose bins
dose_units (str, optional) – Units for the absolute dose

Raises

AttributeError – Description

absolute_volume(volume, volume_units='cm3')[source]¶

Return an absolute volume DVH.

Parameters

volume (number) – Absolute volume of the structure
volume_units (str, optional) – Units for the absolute volume

bincenters¶: Return a numpy array containing the bin centers.

compare(dvh)[source]¶

Compare the DVH properties with another DVH.

Parameters: dvh (DVH) – DVH instance to compare against
Raises: AttributeError – If DVHs do not have equivalent dose & volume units

cumulative¶: Return a cumulative DVH from a differential DVH.

describe()[source]¶: Describe a summary of DVH statistics in a text based format.

differential¶: Return a differential DVH from a cumulative DVH.

dose_constraint(volume, volume_units=None)[source]¶

Calculate the maximum dose that a specific volume receives.

i.e. D90, D100 or D2cc

Parameters: volume (number) – Volume used to determine the maximum dose that the volume receives. Can either be in relative or absolute volume units.
Returns: Dose in self.dose_units units.
Return type: number

classmethod from_data(data, binsize=1)[source]¶

Initialization for a DVH from raw data.

Parameters

data (iterable or numpy array) – An iterable of dose data that is used to create the histogram
binsize (int, optional) – Bin width size (in cGy used to create the histogram)

classmethod from_dicom_dvh(dataset, roi_num, rx_dose=None, name=None, color=None)[source]¶: Initialization for a DVH from a pydicom RT Dose DVH sequence.

max¶: Return the maximum dose.

mean¶: Return the mean dose.

min¶: Return the minimum dose.

plot()[source]¶: Plot the DVH using Matplotlib if present.

relative_dose(rx_dose=None)[source]¶

Return a relative dose DVH based on a prescription dose.

Parameters: rx_dose (number, optional) – Prescription dose value used to normalize dose bins
Raises: AttributeError – Raised if prescription dose was not present either during class initialization or passed via argument.

relative_volume¶: Return a relative volume DVH.

statistic(name)[source]¶

Return a DVH dose or volume statistic.

Parameters: name (str) – DVH statistic in the form of D90, D100, D2cc, V100 or V20Gy, etc.
Returns: Value from the dose or volume statistic calculation.
Return type: number

volume¶: Return the volume of the structure.

volume_constraint(dose, dose_units=None)[source]¶

Calculate the volume that receives at least a specific dose.

i.e. V100, V150 or V20Gy

Parameters: dose (number) – Dose value used to determine minimum volume that receives this dose. Can either be in relative or absolute dose units.
Returns: Volume in self.volume_units units.
Return type: number

class dicompylercore.dvh.DVHValue(value, units='')[source]¶

Bases: object

Class that stores DVH values with the appropriate units.

dvhcalc module¶

Calculate dose volume histogram (DVH) from DICOM RT Structure/Dose data.

dicompylercore.dvhcalc.calculate_contour_dvh(mask, doseplane, maxdose, dd, id, structure)[source]¶: Calculate the differential DVH for the given contour and dose plane.

dicompylercore.dvhcalc.calculate_dvh(structure, dose, limit=None, calculate_full_volume=True, use_structure_extents=False, interpolation_resolution=None, interpolation_segments_between_planes=0, callback=None)[source]¶

Calculate the differential DVH for the given structure and dose grid.

Parameters

structure (dict) – A structure (ROI) from an RT Structure Set parsed using DicomParser
dose (DicomParser) – A DicomParser instance of an RT Dose
limit (int, optional) – Dose limit in cGy as a maximum bin for the histogram.
calculate_full_volume (bool, optional) – Calculate the full structure volume including contours outside of the dose grid.
use_structure_extents (bool, optional) – Limit the DVH calculation to the in-plane structure boundaries.
interpolation_resolution (float, optional) – Resolution in mm to interpolate the structure and dose data to.
interpolation_segments_between_planes (integer, optional) – Number of segments to interpolate between structure slices.
callback (function, optional) – A function that will be called at every iteration of the calculation.

dicompylercore.dvhcalc.calculate_plane_histogram(plane, doseplane, dosegridpoints, maxdose, dd, id, structure, hist)[source]¶: Calculate the DVH for the given plane in the structure.

dicompylercore.dvhcalc.dosegrid_extents_indices(extents, dd, padding=1)[source]¶

Determine dose grid extents from structure extents as array indices.

Parameters

extents (list) – Structure extents in patient coordintes: [xmin, ymin, xmax, ymax]. If an empty list, no structure extents will be used in the calculation.
dd (dict) – Dose data from dicomparser.GetDoseData.
padding (int, optional) – Pixel padding around the structure extents.

Returns

Dose grid extents in pixel coordintes as array indices: [xmin, ymin, xmax, ymax].

Return type

list

dicompylercore.dvhcalc.dosegrid_extents_positions(extents, dd)[source]¶

Determine dose grid extents in patient coordinate indices.

Parameters

extents (list) – Dose grid extents in pixel coordintes: [xmin, ymin, xmax, ymax].
dd (dict) – Dose data from dicomparser.GetDoseData.

Returns

Dose grid extents in patient coordintes: [xmin, ymin, xmax, ymax].

Return type

list

dicompylercore.dvhcalc.get_contour_mask(dd, id, dosegridpoints, contour)[source]¶: Get the mask for the contour with respect to the dose plane.

dicompylercore.dvhcalc.get_dvh(structure, dose, roi, limit=None, calculate_full_volume=True, use_structure_extents=False, interpolation_resolution=None, interpolation_segments_between_planes=0, thickness=None, callback=None)[source]¶

Calculate a cumulative DVH in Gy from a DICOM RT Structure Set & Dose.

Parameters

structure (pydicom Dataset) – DICOM RT Structure Set used to determine the structure data.
dose (pydicom Dataset) – DICOM RT Dose used to determine the dose grid.
roi (int) – The ROI number used to uniquely identify the structure in the structure set.
limit (int, optional) – Dose limit in cGy as a maximum bin for the histogram.
calculate_full_volume (bool, optional) – Calculate the full structure volume including contours outside of the dose grid.
use_structure_extents (bool, optional) – Limit the DVH calculation to the in-plane structure boundaries.
interpolation_resolution (float, optional) – Resolution in mm to interpolate the structure and dose data to.
interpolation_segments_between_planes (integer, optional) – Number of segments to interpolate between structure slices.
thickness (float, optional) – Structure thickness used to calculate volume of a voxel.
callback (function, optional) – A function that will be called at every iteration of the calculation.

dicompylercore.dvhcalc.get_interpolated_dose(dose, z, resolution, extents)[source]¶

Get interpolated dose for the given z, resolution & array extents.

Parameters

dose (DicomParser) – A DicomParser instance of an RT Dose.
z (float) – Index in mm of z plane of dose grid.dose
resolution (float) – Interpolation resolution less than or equal to dose grid pixel spacing.
extents (list) – Dose grid index extents.

Returns

Interpolated dose grid with a shape larger than the input dose grid.

Return type

ndarray

dicompylercore.dvhcalc.get_resampled_lut(index_extents, extents, new_pixel_spacing, min_pixel_spacing)[source]¶

Determine the patient to pixel LUT based on new pixel spacing.

Parameters

index_extents (list) – Dose grid extents as array indices.
extents (list) – Dose grid extents in patient coordinates.
new_pixel_spacing (float) – New pixel spacing in mm
min_pixel_spacing (float) – Minimum pixel spacing used to determine the new pixel spacing

Returns

A tuple of lists (x, y) of patient to pixel coordinate mappings.

Return type

tuple

Raises

AttributeError – Raised if the new pixel_spacing is not a factor of the minimum pixel spacing.

Notes

The new pixel spacing must be a factor of the original (minimum) pixel spacing. For example if the original pixel spacing was 3 mm, the new pixel spacing should be: 3 / (2^n) mm, where n is an integer.

Examples

Original pixel spacing: 3 mm, new pixel spacing: 0.375 mm Derived via: (3 / 2^16) == 0.375

dicompylercore.dvhcalc.interpolate_between_planes(planes, n=2)[source]¶

Interpolate n additional structure planes (segments) in between planes.

Parameters

planes (dict) – RT Structure plane data from dicomparser.GetStructureCoordinates.
n (int, optional) – Number of planes to interpolate in between the existing planes.

Returns

Plane data with additional keys representing interpolated planes.

Return type

dict

dicompylercore.dvhcalc.structure_extents(coords)[source]¶

Determine structure extents in patient coordinates.

Parameters: coords (dict) – Structure coordinates from dicomparser.GetStructureCoordinates.
Returns: Structure extents in patient coordintes: [xmin, ymin, xmax, ymax].
Return type: list