dcmqi (DICOM for Quantitative Imaging)

When parameterizing the conversion of DICOM Segmentation objects using a JSON file, the segmentAttributes field follows a specific nested array structure. This structure maps metadata to the input files and their internal labels:

1. Outer Array: The entries in the outer ordered array correspond to the input segmentation files passed to the converter.
2. Inner Array: For each input file, the inner array contains metadata entries. These entries are indexed by the labels found within that specific segmentation file.

Common Configuration Patterns

• Single file with a single label: The outer array has one entry, and the inner array has one entry.
• Single file with multiple labels: The outer array has one entry, and the inner array contains multiple entries (one for each label in the file).
• Multiple files with one label each: The outer array contains multiple entries (one per file), and each inner array contains exactly one entry.

You can use the dcmqi webapp to help generate these JSON files or to verify your configuration.

When converting a sparse labelmap (where some slice positions are missing) to a dense ITK image grid, segimage2itkimage reconstructs the grid based on the available frame positions:

• Missing Border Frames: If frames are missing at the edges of the volume, the output grid shrinks to span only the encoded frames. The outermost encoded frame becomes the first/last slice. While world coordinates are preserved, the grid dimensions will not match the original input volume.
• Missing Interior Frames: Missing slices within the volume are filled with a value. The fill value is the Pixel Padding Value if present; otherwise, it defaults to 0.

Warning Scenarios:

• If there is no Pixel Padding Value, interior frames are missing, and a real segment uses pixel value 0, the missing positions are filled with 0. This makes the filled-in positions indistinguishable from that segment in the output image.
• If the Pixel Padding Value is invalid for the pixel data type (e.g., a value > 255 for an 8-bit labelmap), it is ignored with a warning, and the fill value falls back to 0.

In a labelmap, the background is identified specifically by the Pixel Padding Value (0028,0120). This value represents the Segment Number treated as background.

Behavioral rules for the background segment:

• JSON Metadata: The background segment is omitted from the JSON metadata file. It does not appear in the segment list.
• Pixel Values: The pixels for the background are written to the output image unchanged. Typically, this value is 0.
• Non-zero Padding: If the Pixel Padding Value is set to a non-zero value, the segment is still omitted from the JSON, but the pixels retain that non-zero value in the output image. This may cause issues with consuming applications that expect background to be 0.
• Type vs. Padding: If a segment is typed as Background (DCM, 125040) but is not designated by the Pixel Padding Value, it is treated as an ordinary segment. It will be included in the JSON metadata, and a warning will be logged.

In a DICOM Labelmap segmentation, the pixel value 0 is treated as the background.

When itkimage2segimage encounters pixel value 0 (either from input label 0 or empty areas), it automatically configures the following to ensure DICOM compliance:

1. Background Segment: Creates a segment with Segment Number 0, labeled Background, with Type Code DCM, 125040 and a black Recommended Display CIELab value.
2. Pixel Padding Value: Sets Pixel Padding Value (0028,0120) = 0 in the General Equipment Module. This is critical because a segment is only treated as background if the Pixel Padding Value matches its Segment Number.

Note:

• If the segmentation is "total" (every pixel is covered by a foreground segment and no 0 values exist), no background segment or Pixel Padding Value is written.
• Binary segmentations do not support a background segment or Pixel Padding Value; label-0 pixels simply belong to no segment.

The --useLabelIDAsSegmentNumber option determines how the Segment Numbers in the resulting DICOM object are assigned relative to the input ITK image label IDs.

Behavior by Output Type

Binary Segmentations (Default)

• Option OFF (Default): Segments are numbered sequentially starting from 1 based on the order they are processed (command-line order and ascending label order within files). Original label IDs are lost.
• Option ON: The input label ID is used directly as the Segment Number.
  • Constraint: Because DICOM binary segmentations require consecutive numbers starting at 1 (1, 2, 3... N), this option only works if your label IDs are exactly 1, 2, 3, ... N. If there are gaps or the sequence doesn't start at 1, the conversion will fail.
  • Use Case: Use this to ensure Segment Numbers match label IDs when the input file processing order differs from the label ID order.

Labelmap Segmentations (--segmentationType labelmap)

• Option OFF (Default): Pixel values are renumbered 1 ... N to be consecutive. Original label IDs are lost.
• Option ON: The input label ID becomes both the Segment Number and the pixel value.
  • Gaps: Unlike binary mode, gaps are allowed (e.g., labels {1, 5, 100} are valid).
  • Constraint: Each label ID must be positive and unique across all input files.

Summary Table

# To preserve non-consecutive label IDs in a labelmap
itkimage2segimage --segmentationType labelmap --useLabelIDAsSegmentNumber metadata.json image.nii.gz

Use the util/multiframe-validation tooling to verify dcmqi's support for multiframe source images against real-world data from the Imaging Data Commons (IDC). This tool complements the standard CI test suite by using third-party tools (highdicom) and real clinical geometry (gaps, large slice counts, non-matching grids) to ensure dcmqi correctly interprets Enhanced objects as written by other producers.

Validation Workflow

1. Download an IDC segmentation and its referenced image series.
2. Convert the segmentation to ITK using segimage2itkimage (yielding label images and metadata JSON).
3. Convert the classic series into a Legacy Converted Enhanced image using highdicom.
4. Run itkimage2segimage twice on the ITK input: once against the classic series and once against the multiframe image.
5. Compare the resulting segmentations to ensure they denote the same source images via frame references.

# Example of running the full validation script
export DCMQI_BIN=/path/to/dcmqi-build/bin
export PYTHON=/path/to/python-with-highdicom

./validate_idc_case.sh /tmp/case1 <SEG-SeriesInstanceUID>