RT-Utils

A minimal Python library for DICOM RT Struct manipulation

RT-Utils reads and writes the DICOM RT Structure Set, the file a treatment planning system stores contoured anatomy in. It turns an RTStruct into a NumPy mask you can compute on, and turns a mask back into a conformant RTStruct a planning system or viewer will open.

from rt_utils import RTStructBuilder

rtstruct = RTStructBuilder.create_new(dicom_series_path="./series")
rtstruct.add_roi(mask=mask_from_your_model, name="GTV", color=[255, 0, 255])
rtstruct.save("structures")

Install it with:

pip install rt-utils

---

Start here

Quickstart

Create a structure set, add an ROI and read one back: the whole round trip in a few lines.

Quickstart

Mask layout

What (Rows, Columns, Slices) means, and why an ROI comes back rotated when it is ignored. Read this before your first add_roi.

Mask layout

User guide

Creating, reading, editing and merging structure sets; NIfTI conversion; contours given as coordinates; smoothing.

Creating structure sets

API reference

Every public class and function, generated from the docstrings in the source.

API reference

What it does

Task	How
Turn a segmentation into an RTStruct	RTStruct.add_roi
Turn an RTStruct ROI into a mask	RTStruct.get_roi_mask_by_name
Convert a NIfTI segmentation onto the series grid	rt_utils.nifti.nifti_to_mask()
Write contours you already have in patient or pixel coordinates	RTStruct.add_roi_from_coordinates
Remove a structure	RTStruct.delete_roi
Combine two structure sets for one series	RTStructMerger.merge_rtstructs

What it does not do

RT-Utils is deliberately small. It does not plan, does not compute dose, and does not resample images. A few limits are worth knowing before you start:

• One frame of reference and one image series per structure set. A structure set spanning several series is only partly supported. See Troubleshooting.

• Nested contours (a hole inside a structure) are written as nested closed contours. Viewers that cannot draw those need use_pin_hole=True.

• Reading requires the image series the structures were drawn on. The contours name their slices by identifier, and the geometry comes from the images.

Citing

If RT-Utils contributes to published work, please cite the JOSS paper. See Citing RT-Utils.