dicomhandler package

Submodules

dicomhandler.dicom_info module

Build and handle DICOM radiotherapy files.

Python tool for integrating and processing DICOM information of radiotherapy structures.

It allows to modify the structures (expand, contract, rotate, translate) and to obtain statistics from these modifications without the need to use CT or MRI images and to create new DICOM files with this information, which are compatible with the commercial of treatment planning systems such as Eclipse and Brainlab Elements.

It is possible to extract the information from the structures in an easy excelable form.

class dicomhandler.dicom_info.DicomInfo(*args)

Bases: object

Build an object containing DICOM files.

Allows to integrate the characteristics and properties of the different DICOM files, which have complementary information of each patient.

Note

Important: DicomInfo does not allow to merge information from different patients. Only one RS, RP and RD is accepted per patient, per instantiation.

The files accepted are:

  • Structures: RS.dcm.

  • Treatment plan: RP.dcm.

  • Treatment dose: RD.dcm.

Methods

add_margin(struct, margin)

Allows to expand or subtract margin for a single structure.

anonymize(name=True, birth=True, operator=True, creation=True)

Allows to overwrite the patient’s information.

mlc_to_csv(path_or_buff)

Creates DICOM MLC information in csv-able form.

move(struct, value, key, *args)

Allows to move all the points for a single structure.

struct_to_csv(path_or_buff, names)

Creates DICOM structure information in csv-able form.

summarize_to_dataframe(self, area)

Reports the main information of plan and MLC.

Returns

pydicom.dataset.FileDataset

DicomInfo object with DICOM properties.

pandas.core.frame.DataFrame

DataFrame reports with specific information and metrics from DICOM files.

add_margin(struct, margin)

Expand or contract a structure a specified margin.

Allow to expand or subtract margins for a single structure.

The margin is calculated by the distance between the mean centre \((x_{mean}, y_{mean}, z_{mean})\) for each point \((x_0, y_0, z_0)\) of each its slice plus (minus) the desired amount to add (subtract) margins.

The calculation is performed by solving the parametrized equation for the point \((x, y, z)\) along the normal vector to the tangent plane to the surface of the contour at point \((x_0, y_0, z_0)\).

This parametrized equation is \(t = \pm \frac{margin}{2*distance}\), where \(distance\) is the Euclidean distance between \((x_0, y_0, z_0)\) and \((x_{mean}, y_{mean}, z_{mean})\).

Thus,

  • \(x = 2(x_0-x_{mean})t + x_0\).

  • \(y = 2(y_0-y_{mean})t + y_0\).

  • \(z = 2(z_0-z_{mean})t + z_0\).

Parameters

structstr

Name of the structure to modify the margin.

marginfloat

The expansion (positive) or substraction (negative) in mm.

Returns

pydicom.dataset.FileDataset

Object with DICOM properties of the structure.

Raises

TypeError

If the margin is not float.

ValueError

If the contour is empty or if its name is not founded.

References

Examples

>>> # Add 0.7 mm to the tumor.
>>> dicom.add_margin('1 GTV', 0.7)
>>> # Subtract 1.2 mm to the tumor.
>>> dicom.add_margin('1 GTV', -1.2)
anonymize(name=True, birth=True, operator=True, creation=True)

Protect the sensitive personal information from files.

In many cases, it is important to anonymize the patient information for research and statistics. anonymize method allows to overwrite the name, birth date of the patient, the operator’s name and the creation of the plan.

By default, it modifies a DICOM object with the following values:

  • Patient Name: ‘PatientName’

  • Patient Birth Date: ‘19720101’

  • Operators Name: ‘OperatorName’

  • Instance Creation Date: ‘19720101’

Parameters

namebool, default True

Anonymize the patient name.

birthbool, default True

Anonymize the patient birth date.

operatorbool, default True

Anonymize the operator name.

creationbool, default True

Anonymize the instance creation date.

Returns

pydicom.dataset.FileDataset

Object with DICOM properties of the anonymized files.

Examples

>>> # Anonymize name, birthdate, operator.
>>> # No anonymize creation date.
>>> dicom = dicom.anonymize(creation=False)
mlc_to_csv(path_or_buff=None)

Create an csv file with the information of the plan file.

The information of the multileaf collimator (MLC) positions, control points, gantry angles, gantry orientation and table angle are reported in a comma-separated values (csv) file or in a text file (txt) for numerical simulations. The file can be created in any path or by buffer. The information contains the principal components necessary for Monte Carlo simulations for radiotherapy.

Parameters

path_or_buffstr, pathlib.Path or StringIO, default=None

Path or buffer to write the information from a dataframe.

Returns

csv file

csv file with MLC description.

Raises

ValueError

If the plan is not loaded. If the file has not a name. If the file has not a .csv o .txt extension.

References

Examples

>>> # Extract MLC positions and checkpoints from a path.
>>> dicom.mlc_to_csv(path_or_buff='output.csv')
>>> # Extract MLC positions and checkpoints from a buffer.
>>> dicom.struct_to_csv(path_or_buff=StringIO())
move(struct, value, key, *args)

Moves a structure for a reference point.

Allow to rotate and translate all the points for a single structure.

The transformations are defined at the origin. For that reason it is necessary to bring the coordinates to the origin before rotating. You can rotate an arbritrary structure (organ at risk, lesion or support structure) in any of the 3 degrees of freedom: roll, pitch, or yaw with the angle (in degrees) or translate (in mm) in x, y or z axis of your choice.

Note

Additional advantage: You can accumulate rotations and traslations to study any combination.

Parameters

structstr

Name of the structure to rotate.

valuefloat or int

Value could be positive or negative. For rotation, maximum angle allowed 360º. For translation, maximum shift allowed 1000 mm.

keystr

Direction of rotation (‘roll’, ‘pitch’ or ‘yaw’). Direction of translation (‘x’, ‘y’ or ‘z’).

*argslist, optional

Origin in a list of float elements [x, y, z]. By default, it is considered the isocenter of the structure file (last structure in RS DICOM called Coord 1). If not is able this structure, you can add an arbritrarly point.

Returns

pydicom.dataset.FileDataset

Object with DICOM properties of the moved structure.

Raises

TypeError

If the angle is not float or int.

ValueError

If you select an incorrect rotation key, incorrect name or if you type an origin point with no float.

References

Examples

>>> # rotate tumor 1.0 degree in yaw in isocenter.
>>> moved = dicom.move('1 GTV', 1.0, 'yaw')
>>> # rotate lesion 1.0 degree in roll in [0.0, 0.0, 0.0].
>>> iso = [0.0, 0.0, 0.0]
>>> dicom.move('1 GTV', 1.0, 'yaw', iso)
>>> # translate tumor 1.0 mm in x in isocenter.
>>> moved = dicom.move('1 GTV', 1.0, 'x')
struct_to_csv(path_or_buff=None, names=None)

Create an csv file with the information of the structure file.

The information of the Cartesian coordinates (relative positions) for all or some structures is extracted in a comma-separated values (csv) file or in a text file (txt) for pos-processing. The file can be created in any path or by buffer.

Note

Important: For all structures, it could be a slow process to take couple of minutes. The structure BODY or OUTER CONTOUR contains a lot of points.

Parameters

path_or_buffstr, pathlib.Path or StringIO, default=None

Path or buffer to write the information from a dataframe.

nameslist, default=None

List of strings, with the name of the structures to create the csv file. By default all structures.

Returns

csv file

csv file with the coordinates of the selected structures.

Raises

ValueError

If the name of the structures are not in the files. If the file has not a name. If the file has not a .csv o .txt extension.

References

Examples

>>> # Extract the coordinates of the structures Eye Right,
>>> # using path
>>> dicom.struct_to_csv(path_or_buff='output.csv', ['Eye Right'])
>>> # using buffer
>>> dicom.struct_to_csv(path_or_buff=StringIO(), ['Eye Right'])
>>> # Extract the coordinates of the all structures.
>>> dicom.struct_to_csv(path_or_buff='output.csv')
summarize_to_dataframe(area=False)

Report the main information of the radiotherapy plan.

The information of the prescribed dose, reference points in targets, dose to references points, the mass centre and distance to isocenter for each target are summarized in a dataframe.

Also, this method calculates the areas of multileaf collimator (MLC) modulation. The objective of this method is to describe the movements of the gantry and MLC during irradiation. The output is a dataframe with six columns:

  • The code of the beam.

  • The code of the checkpoint.

  • The total area that is under irradiation.

  • The gantry angle.

  • The gantry direction

  • The table angle.

The total area is calculated as the sum of the areas defined between the opposite pair of leaves.

Note

It is necessary to include the plan file.

Every beam is contains information with the same machine for a patient, so the number of leaves of the machine is the same for every beam.

Parameters

areasbool, default=False

Areas defined the information reported. By default, the dataframe corresponds to general RTPlan information. If areas is True, the dataframe corresponds to the MLC areas.

Returns

pandas.core.frame.DataFrame

Dataframe with information.

Raises

ValueError

If plan dicom and struct dicom are not present. If the modality is not RTPlan or if the number of leaves varies from each checkpoint.

TypeError

The direction of gantry is not a string.

Examples

>>> # Obtain dataframe for plan information.
>>> import pydicom
>>> import os
>>> # Import the class from the dicomhandler.
>>> import dicomhandler.dicom_info as dh
>>> # Construct the object.
>>> file = os.listdir(os.chdir('path_of_DICOM_files'))
>>> plan = pydicom.dcmread(file[0], force = True)
>>> struct = pydicom.dcmread(file[1], force = True)
>>> dicom = dh.DicomInfo(struct, plan)
>>> # Obtain dataframe with general plan information.
>>> dicom.summarize_to_dataframe(area = False)
>>> # Or, to obtain dataframe with MLC areas.
>>> dicom.summarize_to_dataframe(area = True)

dicomhandler.report module

Report to extract complementary information.

Allows to compare distances from two structures.

dicomhandler.report.report(dicom1, dicom2, struct)

Report metrics from structures.

This function reports the maximum, minimum, mean, standard deviation and variance of: radius between each point of a structure and its centre of mass and the distances between two structures (the same name) in different positions. It is reported the distance between the centres of mass of the two structures.

The report is in a dataframe.

Parameters

dicom1pydicom.dataset.FileDataset

First DICOM file with structures.

dicom2pydicom.dataset.FileDataset

Second DICOM file with structures.

name_structstr

The name of the structure.

Returns

pandas.core.frame.DataFrame

dataframe with statistics.

Raises

ValueError

If you type a wrong name or if the name does not match between two DICOM files.

Examples

>>> # Import report.
>>> import dicomhandler.report as rp
>>> # Report for the original and displaced lesion.
>>> rp(dicom, moved, 'tumor')

Module contents

__init__ module of dicomhandler package.

It contains the version attribute of the package to be used as release version in the documentation (see release variable at docs/source/conf.py).