dicom-series-inspector

name	dicom-series-inspector
description	Validates DICOM series consistency by checking SeriesInstanceUID, ImageOrientationPatient, slice spacing uniformity, and detecting missing slices.
version	0.1.0
author	Medical AI Team <[e-mail]>
license	MIT
tags	["dicom","validation","quality-control","series-inspection"]
maturity	stable
category	foundation
requires_extras	["core","dicom"]

Overview

The dicom-series-inspector skill validates the consistency and integrity of DICOM series. It performs comprehensive checks on a directory of DICOM files to ensure:

• All files belong to the same series (SeriesInstanceUID consistency)
• Image orientation is consistent across all slices
• Slice spacing is uniform (detects gaps or overlaps)
• No slices are missing from the series
• All required DICOM tags are present

This skill is essential for preprocessing medical imaging data before feeding it into AI/ML pipelines, ensuring data quality and preventing downstream errors.

Installation

pip install -r requirements.txt

Or install the specific dependencies:

pip install pydicom>=2.3.0 numpy>=1.20.0

Dependencies:

• Python >= 3.10
• pydicom >= 2.3.0
• numpy >= 1.20.0

Usage

python scripts/main.py [OPTIONS] DICOM_DIR

Arguments

Argument	Required	Description
dicom_dir	Yes	Path to directory containing DICOM files

Options

Option	Default	Description
--output, -o	stdout	Output file path for JSON report
--format	json	Output format: json, ndjson, csv
--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 directory path containing DICOM files. It recursively scans for files and attempts to parse them as DICOM.

Output Schema

{
  "success": true,
  "result": {
    "series_uid": "1.2.840.113619.2.55.3.604688690.789.1234567890.123",
    "slice_count": 128,
    "consistent": true,
    "issues": [],
    "metadata": {
      "modality": "CT",
      "patient_id": "ANON123",
      "study_date": "20240115",
      "manufacturer": "SIEMENS",
      "image_count": 128,
      "slice_thickness": 1.0,
      "spacing_between_slices": 1.0
    }
  },
  "metadata": {
    "timestamp": "2024-01-15T10:30:00Z",
    "duration_ms": 245
  }
}

Output Fields

Field	Type	Description
success	boolean	Whether the script completed successfully
result.series_uid	string	The SeriesInstanceUID
result.slice_count	integer	Number of valid DICOM slices found
result.consistent	boolean	Whether the series passed all validation checks
result.issues	array[string]	List of validation issues (empty if consistent)
result.metadata	object	Extracted DICOM metadata
metadata.timestamp	string	ISO 8601 timestamp of execution
metadata.duration_ms	integer	Execution time in milliseconds

Exit Codes

Code	Meaning
0	Success and series is consistent
1	Validation error (series is inconsistent)
2	Runtime error (file not found, permission denied, etc.)
3	Usage error (missing required arguments)

Examples

Basic usage

python scripts/main.py /path/to/dicom/series

Output:

{
  "success": true,
  "result": {
    "series_uid": "1.2.840.113619.2.55.3.604688690.789.1234567890.123",
    "slice_count": 128,
    "consistent": true,
    "issues": [],
    "metadata": {
      "modality": "CT",
      "patient_id": "ANON123",
      "study_date": "20240115"
    }
  },
  "metadata": {
    "timestamp": "2024-01-15T10:30:00Z",
    "duration_ms": 245
  }
}

With output file

python scripts/main.py /path/to/dicom/series --output report.json

Verbose mode

python scripts/main.py /path/to/dicom/series --verbose

Check series version

python scripts/main.py --version

Validation Rules

The skill performs the following validation checks:

1. SeriesInstanceUID Consistency: All files must have the same SeriesInstanceUID
2. ImageOrientationPatient Consistency: All slices must have the same orientation
3. Slice Spacing Uniformity: Spacing between slices should be consistent
4. Missing Slice Detection: Detects gaps in slice positions
5. Required Tags: Verifies presence of essential DICOM tags

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

References

• DICOM Standard
• Validation Rules
• pydicom Documentation

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
• Basic DICOM series validation
• SeriesInstanceUID consistency check
• ImageOrientationPatient validation
• Slice spacing uniformity check
• Missing slice detection
• Required DICOM tags verification
• JSON output format support