segmentation-mask-qc

name	segmentation-mask-qc
description	Validates segmentation masks in NIfTI format by checking label values, detecting empty masks, finding connected components, and identifying small spurious regions.
version	0.1.0
author	Medical AI Team <[e-mail]>
license	MIT
tags	["segmentation","validation","quality-control","mask-inspection","nifti"]
maturity	stable
category	quality-control
requires_extras	["core"]

Overview

The segmentation-mask-qc skill validates the quality and integrity of segmentation masks stored in NIfTI format. It performs comprehensive quality checks to ensure:

• Label values are within expected ranges
• No labels are completely empty (zero voxels)
• Connected components are identified for each label
• Small spurious regions are detected and flagged
• Overall mask statistics are computed

This skill is essential for preprocessing segmentation data before training AI models or evaluating model predictions, ensuring data quality and identifying potential annotation errors.

Installation

pip install -r requirements.txt

Or install the specific dependencies:

pip install nibabel>=5.0.0 numpy>=1.20.0 scipy>=1.9.0

Dependencies:

• Python >= 3.10
• nibabel >= 5.0.0
• numpy >= 1.20.0
• scipy >= 1.9.0

Usage

python scripts/main.py MASK_PATH [--output PATH] [--min-component-size N] [--verbose]

Arguments

Argument	Required	Description
mask_path	Yes	Path to NIfTI segmentation mask file

Options

Option	Default	Description
--output, -o	stdout	Output file path for JSON report
--min-component-size	10	Minimum component size (voxels) to consider valid
--expected-labels	auto	Comma-separated list of expected label values
--verbose, -v	false	Enable verbose logging to stderr
--version	-	Show version and exit
--help, -h	-	Show help message and exit

Input Schema

The script takes a path to a NIfTI file containing a segmentation mask. The mask should contain integer label values where 0 represents background.

Output Schema

{
  "success": true,
  "result": {
    "valid": true,
    "label_count": 3,
    "unique_labels": [0, 1, 2],
    "empty_labels": [],
    "small_components": [],
    "component_summary": [
      {"label": 1, "component_count": 2, "total_voxels": 1500},
      {"label": 2, "component_count": 1, "total_voxels": 800}
    ],
    "issues": []
  },
  "metadata": {
    "timestamp": "2024-01-15T10:30:00Z",
    "duration_ms": 125,
    "mask_shape": [256, 256, 128],
    "voxel_size": [1.0, 1.0, 1.0]
  }
}

Output Fields

Field	Type	Description
success	boolean	Whether the script completed successfully
result.valid	boolean	Whether the mask passed all validation checks
result.label_count	integer	Number of unique labels (excluding background)
result.unique_labels	array[integer]	All unique label values found
result.empty_labels	array[integer]	Labels in expected_labels that have zero voxels
result.small_components	array[object]	Components smaller than min_component_size
result.component_summary	array[object]	Summary of components per label
result.issues	array[string]	List of validation issues (empty if valid)
metadata.timestamp	string	ISO 8601 timestamp of execution
metadata.duration_ms	integer	Execution time in milliseconds
metadata.mask_shape	array[integer]	Shape of the mask array
metadata.voxel_size	array[float]	Voxel dimensions in mm

Exit Codes

Code	Meaning
0	Success and mask is valid
1	Validation issues found (mask has problems)
2	Runtime error (file not found, invalid format, etc.)
3	Usage error (missing required arguments)

Examples

Basic usage

python scripts/main.py /path/to/segmentation.nii.gz

Output:

{
  "success": true,
  "result": {
    "valid": true,
    "label_count": 3,
    "unique_labels": [0, 1, 2, 3],
    "empty_labels": [],
    "small_components": [],
    "component_summary": [
      {"label": 1, "component_count": 1, "total_voxels": 2500},
      {"label": 2, "component_count": 2, "total_voxels": 1200},
      {"label": 3, "component_count": 1, "total_voxels": 800}
    ],
    "issues": []
  },
  "metadata": {
    "timestamp": "2024-01-15T10:30:00Z",
    "duration_ms": 125
  }
}

With output file and custom threshold

python scripts/main.py /path/to/segmentation.nii.gz \
  --output qc_report.json \
  --min-component-size 50

Check with expected labels

python scripts/main.py /path/to/segmentation.nii.gz \
  --expected-labels 1,2,3 \
  --verbose

Check script version

python scripts/main.py --version

Validation Rules

The skill performs the following validation checks:

1. Label Value Validation: Checks that all label values are non-negative integers
2. Empty Label Detection: Identifies expected labels that have zero voxels
3. Connected Component Analysis: Finds all connected components per label (26-connectivity for 3D)
4. Small Component Detection: Flags components smaller than the threshold as potential artifacts
5. Mask Statistics: Computes total voxels per label and component counts

For detailed validation rules, see references/segmentation-validation.md.

References

• NIfTI Format Specification
• Segmentation Validation Guidelines
• Connected Components in Medical Images
• MONAI Segmentation Best Practices

Limitations

• Only supports 3D NIfTI images (single volumes)
• Uses 26-connectivity for 3D component labeling
• Assumes integer label values (not probabilistic masks)
• Background label (0) is excluded from component analysis

Disclaimer

For Research Use Only - This tool is intended for research and development purposes. It is not intended for clinical use or diagnostic purposes. Always verify results with qualified medical personnel before any clinical application.

Changelog

0.1.0 (2024-01-15)

• Initial release
• Label value validation
• Empty label detection
• Connected component analysis (3D, 26-connectivity)
• Small component detection
• Configurable minimum component size
• JSON output format support
• Verbose logging mode