DICOM Splitter

Overview

Summary

DICOM Splitter is a Flywheel Gear that splits DICOM archives by default into separate archives based on localizers and unique SeriesInstanceUIDs, with optional splits by geometry, orientation, or varying field values.

The main use cases for this gear are if

• There are one or more localizers (scouts, etc.) mixed in with primary images
• There are multiple Series in one archive.
• The archive is multiphasic with respect to slice location (geometry split)
• The archive has non uniform image orientations (geometry split)
• Some field varies across the archive and you have reason to the archive based on that field (group_by split)

The gear is set to do the first two above by default, i.e. it will extract a localizer(s) from the archive, and it will extract each unique SeriesInstanceUID into its own archive.

Version 2.0.0 Breaking Change

Note that versions of this gear prior to version 2.0.0 are named splitter. On the release of version 2.0.0, the gear was renamed to dicom-splitter and all package names, import statements, and other references were modified to reflect this rename. Any software that depends on dicom-splitter should be updated with this breaking change in mind.

License

License: MIT

Classification

Category: Utility

Gear Level:

• Project
• Subject
• Session
• Acquisition
• Analysis

[[TOC]]

Inputs

• dicom
  • Name: dicom
  • Type: DICOM file
  • Optional: false
  • Description: DICOM file to be checked

Configuration

• debug

  • Name: debug
  • Type: boolean
  • Default: False
  • Description: Include debug output.

• delete_input

  • Name: delete_input
  • Type: boolean
  • Default: True
  • Description: Delete input on successful split. Default True.

• extract_localizer

  • Name: extract_localizer
  • Type: boolean
  • Default: True
  • Description: If true and DICOM archive contains embedded localizer images (ImageType = Localizer), the embedded images will be saved as their own DICOM archive.
  • Note: Localizer extraction is not attempted if archive is successfully split by geometry.

• filter_archive

  • Name: filter_archive
  • Type: boolean
  • Default: True
  • Description: Whether to filter out invalid DICOM files from an input DICOM zip archive. DICOM files must have all required file meta tags to be considered valid.

• group_by

  • Name: group_by
  • Type: string
  • Default: "SeriesInstanceUID"
  • Description: Comma-separated tags to group DICOM frames by.
  • Note: To skip group_by split, set value to empty string.

• max_geometric_splits

  • Name: max_geometric_splits
  • Type: integer
  • Default: -1
  • Description: Maximum number of splits to perform by image orientation and/or position. -1 skips geometric split; set to value greater than 0 to attempt split by geometry.
  • Note: As of version 2.1.0, group_by split is attempted before geometric split, and if group_by split is successful, the geometric split will not be attempted. To enforce splitting by geometry instead of by tag, set group_by to "" and max_geometric_splits to a value greater than 1 (suggested value 4, previous default).

• tag

  • Name: tag
  • Type: string
  • Default: "dicom-splitter"
  • Description: The tag to be added to files upon run completion.
  • Note: Previous versions (<2.0.0) had "splitter" as default.

• tag-single-output

  • Name: tag-single-output
  • Type: string
  • Default: ""
  • Description: In addition to the tag applied to all files above, apply a second tag to a single output so that a downstream gear rule can run on the acquisition once splitter finishes. Default empty, no tag will be applied.

• zip-single-dicom

  • Name: zip-single-dicom
  • Type: string
  • Default: "match"
  • Description: Zip single dicom outputs.

Outputs

Files

The gear will output nothing if no splitting action was taken. Otherwise it will output a variable number of archives depending on the input and configuration named with the following pattern:

series-<SeriesNumber>_<Modality>_<SeriesDescription>_<GroupByTags>[_localizer], where

• SeriesNumber is the value of the SeriesNumber tag across the archive. By default the largest sized archive (by number of slices) will retain the original SeriesNumber and additional archives will be incremented by 1000 + i, where i is the index of the archive in a list of total archives.
• SeriesDescription is the value of the SeriesDescription tag across the archive
• GroupByTags is an underscore separated list of all tags appearing in the group_by list, and their corresponding value in that archive. Tags "SeriesInstanceUID" and "SeriesNumber" are not included even if they appear in the group_by list.
• Modality is the value of the Modality tag across the archive
• If the series is a localizer, _localizer will be appended.

As of version 2.1.0, if the input DICOM file is a zip archive that contains non-DICOM files, if the gear is configured with filter_archive as True, the gear will attempt to filter out the non-DICOM files and output a corrected archive even if the DICOM archive is not otherwise split.

SeriesInstanceUID handling

When an archive is split into multiple output archives, each resulting series must be uniquely identifiable. The gear handles the SeriesInstanceUID tag as follows:

• New SeriesInstanceUID generated (default): When the archive is split (by localizer, geometry, or by a group_by tag other than SeriesInstanceUID), each output archive receives a newly generated, unique SeriesInstanceUID. This ensures the split series are treated as distinct series downstream.
• Original SeriesInstanceUID preserved: When group_by includes SeriesInstanceUID (the default configuration), each group already corresponds to a distinct, valid SeriesInstanceUID, so the original value is retained for every output archive rather than regenerated.
• Extracted localizers: A localizer extracted via extract_localizer always receives a newly generated SeriesInstanceUID, so it never shares a UID with the primary series it was separated from.

Whenever a new SeriesInstanceUID is generated, the original SeriesInstanceUID and SeriesNumber values are preserved in each affected instance's OriginalAttributesSequence (the DICOM modified-attributes audit trail), so the provenance of the split is retained. The SeriesNumber of a newly generated series is also offset (original SeriesNumber + 1000) to avoid collisions with the source series.

Pre-requisites

No prerequisites gear runs are required before running dicom-splitter.

Usage

Workflow

flowchart LR
    A[DICOM input file]:::input --> G((DICOM Splitter)):::gear
    G --> C[Splits archives by localizers and SeriesInstanceUIDs,
    with optional geometry, orientation, or field-based grouping]:::split
    C --> D[If no split occurs, no output is generated.
    Otherwise, archives follow this naming pattern:
    series-SeriesNumber_Modality_SeriesDescription_GroupByTags_localizer.
    SeriesNumber is incremented by 1000 + i for additional archives.]:::output

    classDef input fill:#222b45,stroke:#4a5568,stroke-width:2px,color:#ffffff;
    classDef gear fill:#1d4ed8,stroke:#1e3a8a,stroke-width:2px,color:#ffffff;
    classDef split fill:#4ade80,stroke:#15803d,stroke-width:2px,color:#000000;
    classDef output fill:#facc15,stroke:#b45309,stroke-width:2px,color:#000000;

Synergy with Other Gears

The dicom-splitter gear is primarily designed to be used when the DICOM file first gets ingested to Flywheel.

The dicom-splitter gear is a good candidate to be run as one of a series of gear rules (more here).

Contributing

For more information about how to get started contributing to that gear, check out CONTRIBUTING.md.