nifti-header-checker

name	nifti-header-checker
description	Validates NIfTI file headers for integrity and consistency. Checks header structure, dimension consistency, orientation matrix, data type support, and file size expectations.
version	0.1.0
author	Medical AI Team <[e-mail]>
license	MIT
tags	["nifti","validation","qc","header","neuroimaging"]
maturity	stable
category	foundation
requires_extras	["core"]

NIfTI Header Checker

Overview

This skill validates NIfTI (Neuroimaging Informatics Technology Initiative) file headers to ensure data integrity and consistency before processing. It performs comprehensive checks on the header structure, dimension metadata, orientation matrix (affine transform), data type compatibility, and file size expectations.

Use this skill when you need to:

• Validate NIfTI files before processing in a pipeline
• Detect corrupted or malformed NIfTI files
• Verify header-data consistency
• Extract header metadata for quality control reports
• Check orientation and dimension information

Installation

pip install -r requirements.txt

Dependencies:

• nibabel >= 4.0.0
• numpy >= 1.20.0

Usage

./scripts/main.py [OPTIONS] INPUT_PATH

Arguments

Argument	Required	Description
input_path	Yes	Path to NIfTI file (.nii or .nii.gz)

Options

Option	Default	Description
--output, -o	stdout	Output file path
--format	json	Output format: json, ndjson
--verbose, -v	false	Enable verbose logging
--strict	false	Enable strict validation mode
--version	-	Show version and exit
--help	-	Show help message

Input Schema

Takes a file path to a NIfTI file:

• File extension: .nii or .nii.gz
• File must exist and be readable
• File must be a valid NIfTI format

Output Schema

{
  "success": "boolean - whether validation completed",
  "result": {
    "file_path": "string - input file path",
    "file_size_bytes": "integer - file size in bytes",
    "header": {
      "magic": "string - NIfTI magic string",
      "version": "string - NIfTI version",
      "datatype": "string - data type code",
      "bitpix": "integer - bits per pixel",
      "dim": "array - dimensions [x, y, z, t, ...]",
      "pixdim": "array - voxel sizes [x, y, z, t, ...]",
      "qform_code": "integer - quaternion transform code",
      "sform_code": "integer - affine transform code",
      "intent_code": "integer - intent type",
      "intent_name": "string - intent description"
    },
    "validation": {
      "header_valid": "boolean - header structure is valid",
      "dimension_consistent": "boolean - header dims match data shape",
      "orientation_valid": "boolean - affine matrix is valid",
      "datatype_supported": "boolean - data type is supported",
      "file_size_valid": "boolean - file size matches expectations",
      "issues": ["array of validation issue strings"]
    },
    "affine": {
      "matrix": "4x4 array - affine transformation matrix",
      "orientation": "string - orientation code (e.g., RAS)",
      "voxel_sizes": "array - [dx, dy, dz] in mm"
    }
  },
  "metadata": {
    "timestamp": "ISO 8601 timestamp",
    "duration_ms": "integer - processing time",
    "version": "string - skill version"
  }
}

Exit Codes

Code	Meaning
0	Success - file is valid
1	Validation error - file has issues
2	Runtime error - file not found, I/O error
3	Usage error - invalid arguments

Examples

Basic usage

./scripts/main.py /path/to/volume.nii.gz

Output:

{
  "success": true,
  "result": {
    "file_path": "/path/to/volume.nii.gz",
    "file_size_bytes": 524288,
    "header": {
      "magic": "n+1",
      "version": "1.0",
      "datatype": "NIFTI_TYPE_FLOAT32",
      "bitpix": 32,
      "dim": [3, 256, 256, 150, 1, 1, 1, 1],
      "pixdim": [1.0, 1.0, 1.0, 2.0, 1.0, 1.0, 1.0, 1.0],
      "qform_code": 1,
      "sform_code": 1,
      "intent_code": 0,
      "intent_name": ""
    },
    "validation": {
      "header_valid": true,
      "dimension_consistent": true,
      "orientation_valid": true,
      "datatype_supported": true,
      "file_size_valid": true,
      "issues": []
    },
    "affine": {
      "matrix": [[...]],
      "orientation": "RAS",
      "voxel_sizes": [1.0, 1.0, 2.0]
    }
  },
  "metadata": {
    "timestamp": "2024-01-15T10:30:00",
    "duration_ms": 45,
    "version": "0.1.0"
  }
}

With output file and verbose mode

./scripts/main.py /path/to/volume.nii.gz --output report.json --verbose

Strict validation mode

./scripts/main.py /path/to/volume.nii.gz --strict

In strict mode, additional checks are performed:

• Non-zero qform/sform codes required
• Positive voxel sizes required
• Warning-level issues become errors

Check multiple files (with ndjson output)

for f in *.nii.gz; do
  ./scripts/main.py "$f" --format ndjson
done

Validation Rules

Header Validity

• Magic string must be "n+1" or "ni1"
• Version must be valid (1.0 or 2.0)
• Data type code must be recognized

Dimension Consistency

• Header dim[1:ndim+1] must match actual data shape
• Number of dimensions (dim[0]) must be 3 or 4

Orientation Matrix

• Affine matrix must be 4x4
• Determinant must be non-zero (invertible)
• Rotation component should be approximately orthogonal

Data Type Support

• Must be a standard NIfTI data type
• Common types: UINT8, INT16, INT32, FLOAT32, FLOAT64

File Size

• For .nii files: header (352) + data size
• For .nii.gz files: compressed, size check is informational

References

• NIfTI-1 Format Specification
• Nibabel Documentation
• NIfTI Orientation Guide

Disclaimer

For research use only. This skill is not intended for clinical use.

Changelog

0.1.0 (2024-01-15)

• Initial release
• Header structure validation
• Dimension consistency check
• Affine matrix validation
• Data type verification
• File size check
• JSON output with full header info