Dicomhandler is a Python tool for integrating DICOM information and processing DICOM 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 objects with this information, which are compatible with the commercial systems of treatment planning such as Eclipse and Brainlab Elements. It is possible to extract the information from the structures in an easy csv-able form.
Dicomhandler uses DICOM files that belongs to different stages of treatment planning (structures, dose, and plan), by grouping the files of a patient in a single object. DICOM objects have to be created with Pydicom. Also, it allows for the extraction of related information, such as the Cartesian coordinates of structures and multileaf collimator (MLC) positions for each control point in the treatment plan. This is achieved by using the DicomInfo class. It receives as input the DICOM radiotherapy structures (RS), dose (RD), and plan (RP) files (or a subset of these) and constructs a single object that contains all the information for a patient.
Dicomhandler is built on NumPy. NumPy provides an efficient implementation of numerical computations in a high-level language like Python but completely compiled in C, resulting in a significant improvement in speed and code that is clear and easy to maintain.
- Features
- Examples
- Access
- Open and run the project
- Libraries and pre-requisites
- Authors
- License
- Project Status
- Room for Improvement
- Acknowledgements
- More information for potential applications
- Expressions of gratitude
The functionalities provided by the package could be divided into three main categories.
-
File transformation: To modify the files’ information in some meaningful way.
-
Format conversion: DICOM files are neither optimized for data analysis, nor straightforward review by clinical staff, but for hardware. For that reason, the package provides means for both scientific manipulation of data and effortless conversion to clinical-friendly formats.
-
Report data: To summarize different DICOM files, or even about the comparison between files.
It is required to operate on a DICOM object by Pydicom. You can use the DICOM files examples by default in the repository).
You can construct an object with different DICOM files from the same patient as:
di = DicomInfo(dicom_structure, dicom_plan)You can choose the information that it has to be anonymized:
di.anonymize(name=True, birth=True, operator=False, creation=False)You can expand or subtract margins for a single structure. If you want to expand, the input parameter must be positive. Otherwise, negative.
expanded = di.add_margin('5 GTV', 1.5)
contracted = di.add_margin('5 GTV', -1.5)You can rotate or translate a structure (organ or lesion) in an specific direction with respect to an arbitary point or to the isocentre. The keys are: roll, pitch, and yaw (for rotations) and x, y, and z (for translations).
For the isocenter:
di_rotated = di.move('5 GTV', 0.5, 'pitch')
di_translated = di.move('5 GTV', 1.0, 'x')Or for an arbritary point:
di_rotated = di.move('5 GTV', 0.5, 'pitch', [4.0, -50.0, 20.0])
di_translated = di.move('5 GTV', 1.0, 'x', [4.0, -50.0, 20.0])A dataframe is generated with the main information of the plan, relevant for clinical statistics. Also, you can obtain the calculated areas of multileaf collimator (MLC) modulation.
To obtain general plan information:
di.summarize_to_dataframe(area=False)To obtain the MLC areas:
di.summarize_to_dataframe(area=True)A csv file is generated with some information.
The output file provides the information on the coordinates (x, y, z) of all or some structures of a patient. By default the report is generated for all structures.
For all structures this process takes several minutes.
di.struct_to_csv(path_or_buff='output.csv')Or you can select some structures to obtain the csv file in a particular path:
di.struct_to_csv(path_or_buff='output.csv', names=['Structure1', 'Structure2'])Or in buffer:
di.struct_to_csv(path_or_buff=StringIO(), names=['Structure1', 'Structure2'])Also, the output file can provide the information of gantry angle, gantry direction, table angles, and MLC positions for each checkpoint.
di.mlc_to_csv(path_or_buff="output.csv")Or in buffer:
di.mlc_to_csv(path_or_buff=StringIO())We encourage the practice of using virtual environments to avoid dependency incompatibilities. The most convenient way to do this, is by using virtualenv, virtualenvwrapper, and pip.
After setting up and activating the virtualenv, run the following command:
pip install dicomhandlerIn case you’d like to be able to update the package code occasionally with the latest bug fixes and improvements, see the source code, or even make your own changes, you can always clone the code directly from the repository:
git clone https://github.com/alxrojas/dicomhandler
cd dicomhandler
pip install -e .Run the project as:
from dicomhandler.dicom_info import DicomInfo
from dicomhandler.report import reportThe dependencies of the package, that will be automatically installed with the software, are the following:
This project is licensed under (MIT) - Look the file LICENSE.md for details.
Version 0.0.1a1 is complete
For future work and improvement:
- A method to provide the assignment of variable margin to a lesion.
- A method to evaluate the dose-volume histogram for the displaced structures.
- The possibility to deform structures.
Many thanks to
- Daniel Venencia, PhD. and Instituto Zunino to provide the resources and the access to data.
- Juan Cabral, PhD. to evaluate and review this project.
- Beltrán et al. Radiat and Onc (2012)
- Rojas López et al. Phys Med (2021)
- Venencia et al. J Rad in Pract (2022)
- Zhang et al. SpringerPlus (2016)
- Tell others about this project.
- Cite our project in your paper.
- Invite someone from the team a beer or a coffee.
- Give thanks publicly.