DicomRTTool 4.0.0

Services for reading DICOM files, RT structures, and dose files, as well as tools for converting numpy prediction masks back to an RT structure.

DicomRTTool

Published! See the Technical Note and please cite it if you find this work useful. DOI: https://doi.org/10.1016/j.prro.2021.02.003

Convert DICOM images and RT structures into NIfTI files, NumPy arrays, and SimpleITK image handles — and convert prediction masks back into RT structures.

Installation

pip install DicomRTTool

For the interactive image viewer (requires matplotlib):

pip install "DicomRTTool[viewer]"

Supported Python versions: 3.10, 3.11, 3.12, 3.13.

Quick Start

from pathlib import Path

from DicomRTTool.ReaderWriter import DicomReaderWriter, ROIAssociationClass

dicom_path = Path("/path/to/dicom")
reader = DicomReaderWriter(description="Examples", arg_max=True)
reader.walk_through_folders(dicom_path)

# Inspect available ROIs.
all_rois = reader.return_rois(print_rois=True)

# Define target ROIs with optional name aliases.
contour_names = ["tumor"]
associations = [ROIAssociationClass("tumor", ["tumor_mr", "tumor_ct"])]
reader.set_contour_names_and_associations(
    contour_names=contour_names,
    associations=associations,
)

# Load images and masks for the first index that contains all target ROIs.
reader.set_index(reader.indexes_with_contours[0])
reader.get_images_and_mask()

image_numpy   = reader.ArrayDicom          # NumPy image array
mask_numpy    = reader.mask                # NumPy mask array
image_handle  = reader.dicom_handle        # SimpleITK Image
mask_handle   = reader.annotation_handle   # SimpleITK Image

Reading extra DICOM tags

from pydicom.tag import Tag

plan_keys  = {"MyNamedRTPlan": Tag((0x300a, 0x002))}
image_keys = {"MyPatientName": "0010|0010"}

reader = DicomReaderWriter(
    description="Examples",
    arg_max=True,
    plan_pydicom_string_keys=plan_keys,
    image_sitk_string_keys=image_keys,
)

Resetting state between uses

DicomReaderWriter instances can be reused across multiple corpora; call the appropriate reset method before walking a fresh folder tree or swapping target ROIs:

reader.reset()        # wipe everything (images, RTs, masks, cached UIDs)
reader.reset_rts()    # clear ROI bookkeeping only; keep loaded images
reader.reset_mask()   # re-allocate an empty mask after changing Contour_Names

Writing predictions back to an RT structure

import numpy as np

# 4-channel one-hot prediction matching the loaded image shape:
# (slices, rows, cols, num_classes + 1) — channel 0 is background.
predictions = np.zeros((*reader.ArrayDicom.shape, 3), dtype=np.float32)
# ... populate `predictions` from your model ...

reader.prediction_array_to_RT(
    prediction_array=predictions,
    output_dir="/path/to/output",
    ROI_Names=["organ_a", "organ_b"],
)

What's new in v4.0

• Python 3.10+ required (3.8 / 3.9 are end-of-life).
• Public state-reset API: reset(), reset_rts(), reset_mask() — replaces the v3 __reset__ / __reset_mask__ / __reset_RTs__ accessors.
• Deprecated v3 names removed: down_folder → walk_through_folders, where_are_RTs → where_is_ROI, with_annotations → prediction_array_to_RT, plus the __set_iteration__ and __set_description__ setters renamed to set_iteration / set_description. See CHANGELOG.md for the full list and migration notes.
• Excel → CSV for both bulk-export helpers, dropping the openpyxl dependency: characterize_data_to_excel is now characterize_data_to_csv, and write_parallel(excel_file=…) is now write_parallel(index_file=…) accepting a .csv path.
• struct_pydicom_string_keys plumbing finally works — historically the parameter was accepted but the values never reached the parsed RT records.
• Architecture: the original ReaderWriter.py god-class has been partly extracted into a new internal _internal/ package. The public DicomReaderWriter API is unchanged.
• Hermetic test suite: every DICOM file the tests need is generated in a tmp directory at session start from analytical primitives. No external corpus, no network, no caches — the full suite runs in ~6 seconds and validates against analytically-known volume truth.
• Tooling: ruff replaces flake8; PyPI Trusted Publishing replaces the PYPI_TOKEN secret; CI matrix expanded to ubuntu + windows × four Python versions; pre-commit config added.

License

GPL-3.0-or-later

Citation

If you find this code useful, please reference the publication and the GitHub page.