fw-gear-rtstruct-to-nifti 0.2.4

Flywheel Gear for converting RTStruct ROIs to NIfTI

rtstruct-to-nifti (RTStruct to NIfTI)

Overview

RTStructs, or radiotherapy structure sets, are DICOM IODs specific to radiotherapy that includes contour data for ROIs. The rtstruct-to-nifti gear is provided so that these ROIs can be converted to NIfTI files.

Summary

This Flywheel Gear converts RTStruct closed contour ROIs to NIfTI masks.

Cite

No citations noted.

License

License: MIT

Classification

Category: Converter

Gear Level:

• Project
• Subject
• Session
• Acquisition
• Analysis

---

[[TOC]]

---

Inputs

• rtstruct
  • Name: rtstruct
  • Type: DICOM file
  • Optional: False
  • Description: RTStruct file with one or more closed contour ROIs
• source_dicom
  • Name: source_dicom
  • Type: DICOM file
  • Optional: True
  • Description: Optional: Source DICOM connected to RTStruct
  • Notes: A source DICOM file is required for the gear to run. If not provided as input, the gear will search the session container for a DICOM that corresponds with the inputted RTStruct. If a source DICOM is not identified (or more than one is identified), the gear will fail and log instructions to re-run the gear with source_dicom explicitly inputted into the gear.

Config

• debug
  • Name: debug
  • Type: boolean
  • Description: Log debug messages
  • Default: False
• percent-check
  • Name: percent-check
  • Type: string
  • Description: Whether to include a processing step that calculates percent of pixel within contour and drops pixels less than 50% within the contour. Intended for aTMTV-created RTStructs, not recommended for MIM-created RTStructs. If 'auto', gear will search DICOM tags and attempt to identify correct setting. Options are 'auto', 'on', 'off'. (WARNING - Large contours may greatly increase processing time)
  • Default: "auto"
• save-binary-masks
  • Name: save-binary-masks
  • Type: boolean
  • Description: Whether to save as binary masks (only 0s and 1s) or bitmasks (sums of powers of two).
  • Default: True
• save-combined-output
  • Name: save-combined-output
  • Type: string enum
  • Description: Whether to save the RTStruct ROIs as individual files by label, combined, or both.
  • Default: "individual"

Outputs

Files

• Individual ROI Mask(s)
  • Name: ROI_<label>_<filename>.nii.gz
  • Type: Compressed NIfTI
  • Optional: True
  • Description: Individual ROI masks, with one label per file
  • Notes: Outputted if save-combined-output is "individual" or "both". If save-binary-masks is True, binary masks are outputted. If save-binary-masks is False, foreground voxel values are bitmasked.
• Combined ROI Mask
  • Name: ROI_ALL_<filename>.nii.gz
  • Type: Compressed NIfTI
  • Optional: True
  • Description: Combined ROI mask, with all labels represented
  • Notes: Outputted if save-combined-output is "combined" or "both". Foreground voxel values are bitmasked so that individual labels can be identified.
• ROI Info CSV
  • Name: <filename>_ROI_info.csv
  • Type: CSV
  • Optional: False
  • Description: CSV file with ROI labels, reference numbers, foreground voxel values, number of voxels, and volume(mm^3).
  • Notes: If save-combined-output is "both" and save-binary-masks is True, foreground voxel value will correspond with the bitmasked values as seen in the combined ROI file; all individual binary masks will have a foreground voxel value of 1.

Metadata

No metadata is created or modified by this gear.

Pre-requisites

Prerequisite Gear Runs

No prerequisite gear runs are required by this gear.

Prerequisite Files

An ohif_config.json file may be needed at the project level to correctly overlay the created NIfTI mask on the source DICOM. Instructions on how to create an ohif_config.json file can be found here.

The viewer configuration option to add to the ohif_config.json file is {"useRadiologyOrientationForNiftiOverDicomOverlay": true}.

Prerequisite Metadata

Prerequisite metadata are not required by this gear.

Usage

Description

This gear takes as input an RTStruct with one or more closed contour ROIs. It provides as output NIfTI file representations of these segmentations. These output files can be multiple files representing each individual label and/or a file that combines all labels into a single mask.

File Specifications

This gear can be run on an RTStruct with one or more closed contour ROIs, where the source DICOM is either found in the same session container as the inputted RTStruct or inputted explicitly.

Workflow

graph LR;
    A[RTStruct]:::input --> E;
    B[Source DICOM]:::input -.->|optional| E((rtstruct-to-nifti));

    E:::gear --> F[ROI info CSV file]:::container;
    E -.->|if save-combined-output is<br />individual or both| G[NIfTI masks for individual labels]
    E -.->|if save-combined-output is<br />combined or both| H[NIfTI mask with multiple labels]


    classDef container fill:#57d,color:#fff
    classDef input fill:#7a9,color:#fff
    classDef gear fill:#659,color:#fff

Description of workflow

1. Upload RTStruct to acquisition container
2. Upload source DICOM to acquisition container within the same session as the RTStruct
3. Select RTStruct as input to gear
4. Gear places output in acquisition container

Use Cases

Use Case 1: RTStruct with gear-identified source DICOM

Conditions:

• RTStruct and source DICOM are uploaded to the same session container
• Exactly one DICOM within the session container matches the RTStruct

After inputting the RTStruct and beginning the gear run, the gear will search for the source DICOM within the session container. The gear will then utilize the source DICOM as needed in conjunction with the RTStruct to create the NIfTI mask output.

Use Case 2: RTStruct with inputted source DICOM

Conditions:

• RTStruct and source DICOM are uploaded to Flywheel
• Source DICOM is not in the same session container, or multiple DICOMs in the session container match the RTStruct

The RTStruct and source DICOM must both be provided as inputs. The gear will utilize the inputted source DICOM instead of searching for the file within the session container.

Use Case 3: Configuring the Flywheel Viewer for Overlay

Conditions:

• rtstruct-to-nifti gear has been run successfully
• NIfTI mask is displaying in the viewer in neurological orientation
• Source DICOM is displaying in the viewer in radiological orientation

The Flywheel viewer may display the NIfTI mask overlay as mirrored compared to the DICOM due to opposing orientations. To correctly view the NIfTI mask overlaid on the DICOM, create (or modify) your ohif_config.json file at the project level as described here to include {"useRadiologyOrientationForNiftiOverDicomOverlay": true}.

Logging

This gear logs information about the gear run, including configuration settings, labels found within the RTStruct, and files saved. If the gear run encounters a known error, the gear logs what occurred and, if applicable, what to do to fix the error in a subsequent run.

FAQ

FAQ.md

Contributing

[For more information about how to get started contributing to that gear, checkout CONTRIBUTING.md.]