dicompare

dicompare is a DICOM validation tool designed to ensure compliance with study-specific imaging protocols and domain-specific guidelines while preserving data privacy. It provides multiple interfaces, including support for validation directly in the browser at dicompare-web.vercel.app, leveraging WebAssembly (WASM), Pyodide, and the underlying pip package dicompare. dicompare is suitable for multi-site studies and clinical environments without requiring software installation or external data uploads.

dicompare supports DICOM session validation against templates based on:

• Reference sessions: JSON schema files can be generated based on a reference MRI scanning session;
• [TESTING] domain guidelines: Flexible guidelines for specific domains (currently QSM);
• [FUTURE] landmark studies: Schema files based on landmark studies such as the HCP, ABCD, and UK BioBank projects.

Command-line interface (CLI) and application programming interface (API)

While you can run dicompare in your browser now without any installation, you may also use the underlying dicompare pip package if you wish to use the command-line interface (CLI) or application programming interface (API).

pip install dicompare

Command-line interface (CLI)

The package provides a unified dicompare command with two subcommands:

• dicompare build: Generate a JSON schema from a reference DICOM session
• dicompare check: Validate DICOM sessions against a JSON schema

1. Build a JSON schema from a reference session

dicompare build /path/to/dicom/session schema.json

This creates a JSON schema describing the session based on default reference fields present in the data.

2. Check a DICOM session against a schema

dicompare check /path/to/dicom/session schema.json

The tool will output a compliance summary, indicating deviations from the schema.

3. Check with report output

dicompare check /path/to/dicom/session schema.json compliance_report.json

This saves the compliance report to a JSON file.

4. Automatic acquisition mapping

dicompare check /path/to/dicom/session schema.json --auto-yes

Use --auto-yes or -y to automatically map acquisitions without interactive prompts.

Python API

The dicompare package provides a comprehensive Python API for programmatic schema generation, validation, and DICOM processing.

Loading DICOM data

Load a DICOM session:

from dicompare import load_dicom_session

session_df = load_dicom_session(
    session_dir="/path/to/dicom/session",
    show_progress=True
)

Load individual DICOM files:

from dicompare import load_dicom

dicom_data = load_dicom(
    dicom_paths=["/path/to/file1.dcm", "/path/to/file2.dcm"],
    show_progress=True
)

Load Siemens .pro files:

from dicompare import load_pro_session

pro_session = load_pro_session(
    session_dir="/path/to/pro/files",
    show_progress=True
)

Build a JSON schema

from dicompare import load_dicom_session, build_schema, make_json_serializable
from dicompare.config import DEFAULT_SETTINGS_FIELDS
import json

# Load the reference session
session_df = load_dicom_session(
    session_dir="/path/to/dicom/session",
    show_progress=True
)

# Build the schema
json_schema = build_schema(session_df)

# Save the schema
serializable_schema = make_json_serializable(json_schema)
with open("schema.json", "w") as f:
    json.dump(serializable_schema, f, indent=4)

Validate a session against a JSON schema

from dicompare import (
    load_schema,
    load_dicom_session,
    check_acquisition_compliance,
    map_to_json_reference,
    assign_acquisition_and_run_numbers
)

# Load the JSON schema
reference_fields, json_schema, validation_rules = load_schema(json_schema_path="schema.json")

# Load the input session
in_session = load_dicom_session(
    session_dir="/path/to/dicom/session",
    show_progress=True
)

# Assign acquisition and run numbers
in_session = assign_acquisition_and_run_numbers(in_session)

# Map acquisitions to schema
session_map = map_to_json_reference(in_session, json_schema)

# Check compliance for each acquisition
compliance_summary = []
for ref_acq_name, schema_acq in json_schema["acquisitions"].items():
    if ref_acq_name not in session_map:
        continue

    input_acq_name = session_map[ref_acq_name]
    acq_validation_rules = validation_rules.get(ref_acq_name) if validation_rules else None

    results = check_acquisition_compliance(
        in_session,
        schema_acq,
        acquisition_name=input_acq_name,
        validation_rules=acq_validation_rules
    )
    compliance_summary.extend(results)

# Display results
for entry in compliance_summary:
    print(entry)

Additional utilities

Assign acquisition and run numbers:

from dicompare import assign_acquisition_and_run_numbers

session_df = assign_acquisition_and_run_numbers(session_df)

Get DICOM tag information:

from dicompare import get_tag_info, get_all_tags_in_dataset

# Get info about a specific tag
tag_info = get_tag_info("EchoTime")
print(tag_info)  # {'tag': '(0018,0081)', 'name': 'Echo Time', 'type': 'float'}

# Get all tags in a dataset
all_tags = get_all_tags_in_dataset(dicom_metadata)