orientation-standardizer

name	orientation-standardizer
description	Converts NIfTI medical images to RAS+ (Right-Anterior-Superior) orientation. Ensures consistent coordinate system across all images in a dataset.
version	0.1.0
author	Medical AI Team <[e-mail]>
license	MIT
tags	["preprocessing","orientation","nifti","spatial"]
maturity	stable
category	preprocessing
requires_extras	["core"]

Orientation Standardizer

Overview

This skill converts NIfTI medical images from any orientation to the standard RAS+ (Right-Anterior-Superior) coordinate system. RAS+ is the canonical orientation used by many neuroimaging tools and deep learning frameworks.

Use this skill when you need to:

• Standardize image orientations before feeding into a model
• Ensure consistent coordinate systems across a dataset
• Prepare images for registration or multi-modal fusion

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 input NIfTI file (.nii or .nii.gz)

Options

Option	Default	Description
--output, -o	required	Output file path for reoriented image
--verbose, -v	false	Enable verbose logging to stderr
--version	-	Show version and exit
--help	-	Show help message

Input Schema

• File type: NIfTI (.nii or .nii.gz)
• Requirements:
  • Must be a valid NIfTI file readable by nibabel
  • Must contain valid affine transformation matrix
  • File must exist at specified path

Output Schema

Console Output (JSON)

{
  "success": true,
  "result": {
    "input_path": "string - path to input file",
    "output_path": "string - path to output file",
    "original_orientation": "string - 3-letter code (e.g., LPS, LAS)",
    "target_orientation": "string - always RAS",
    "original_affine": "array - 4x4 affine matrix as flat list",
    "new_affine": "array - 4x4 affine matrix as flat list",
    "shape": "array - image dimensions [x, y, z]",
    "voxel_sizes": "array - voxel dimensions [dx, dy, dz]"
  },
  "metadata": {
    "timestamp": "ISO 8601 timestamp",
    "duration_ms": "integer - processing time",
    "version": "string - skill version"
  }
}

Error Output

{
  "success": false,
  "error": "string - error message",
  "error_type": "string - file_not_found | validation_error | runtime_error"
}

Exit Codes

Code	Meaning
0	Success - image converted and saved
1	Validation error - invalid NIfTI file or missing required args
2	Runtime error - file not found, I/O error, conversion failed
3	Usage error - incorrect CLI usage

Examples

Basic usage

./scripts/main.py /path/to/input.nii.gz --output /path/to/output_ras.nii.gz

Output:

{
  "success": true,
  "result": {
    "input_path": "/path/to/input.nii.gz",
    "output_path": "/path/to/output_ras.nii.gz",
    "original_orientation": "LPS",
    "target_orientation": "RAS",
    "shape": [256, 256, 150],
    "voxel_sizes": [1.0, 1.0, 1.0]
  },
  "metadata": {
    "timestamp": "2024-01-15T10:30:00.123456",
    "duration_ms": 245,
    "version": "0.1.0"
  }
}

With verbose output

./scripts/main.py /path/to/input.nii --output /path/to/output_ras.nii.gz --verbose

Stderr:

Input: /path/to/input.nii
Original orientation: LPS
Target orientation: RAS
Output: /path/to/output_ras.nii.gz
Processing completed in 245ms

Error handling - file not found

./scripts/main.py /nonexistent/file.nii.gz --output /tmp/out.nii.gz

Output:

{
  "success": false,
  "error": "Input path not found: /nonexistent/file.nii.gz",
  "error_type": "file_not_found"
}

Exit code: 2

Error handling - invalid NIfTI

./scripts/main.py /path/to/corrupted.nii.gz --output /tmp/out.nii.gz

Output:

{
  "success": false,
  "error": "Unable to load image: invalid header",
  "error_type": "validation_error"
}

Exit code: 1

References

• Orientation Guide - Detailed explanation of coordinate systems
• NIfTI Standard - Official NIfTI format specification
• Nibabel Documentation - Python library for neuroimaging data

Disclaimer

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

Limitations

• Only supports NIfTI format (not DICOM, NRRD, etc.)
• Does not modify the actual image data, only the orientation metadata
• Very large images may require significant memory for processing

Changelog

0.1.0 (2024-01-15)

• Initial release
• RAS+ orientation conversion
• Full error handling and validation
• JSON output with metadata