| name | intensity-normalizer |
| description | Normalizes medical image intensities using various methods (z-score, min-max,
percentile, window-level). Essential preprocessing step for consistent analysis
across different scanners and protocols.
|
| version | 0.1.0 |
| author | Medical AI Team <team@example.com> |
| license | MIT |
| tags | ["preprocessing","intensity","normalization","nifti","dicom"] |
| maturity | stable |
| category | preprocessing |
| requires_extras | ["core"] |
Intensity Normalizer
Overview
This skill normalizes medical image intensities using multiple standard methods. Intensity normalization is critical for medical image analysis because different scanners, protocols, and acquisition parameters can produce vastly different intensity ranges even for the same tissue type.
Use this skill when you need to:
- Standardize intensities across multiple scans for comparison or aggregation
- Prepare images for machine learning models that expect normalized inputs
- Apply CT window/level settings for visualization or analysis
- Remove scanner-specific intensity biases
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 image file (NIfTI, NRRD, or other supported formats) |
Options
| Option | Default | Description |
|---|
--output, -o | stdout | Output file path for normalized image |
--method | z-score | Normalization method: z-score, min-max, percentile, window-level |
--percentile-low | 1 | Lower percentile for percentile method (0-100) |
--percentile-high | 99 | Upper percentile for percentile method (0-100) |
--window-center | 0 | Window center for window-level method (HU units) |
--window-width | 400 | Window width for window-level method (HU units) |
--exclude-background | false | Exclude background (zero) values from normalization |
--verbose, -v | false | Enable verbose logging |
--version | - | Show version and exit |
--help | - | Show help message |
Input Schema
Takes a file path to a medical image file. Supported formats include:
- NIfTI (.nii, .nii.gz)
- NRRD (.nrrd)
- Analyze (.img, .hdr)
- MINC (.mnc)
The image should contain numeric intensity values (typically int16, int32, float32, or float64).
Output Schema
{
"success": true,
"result": {
"input_path": "string - original input path",
"output_path": "string - path to normalized image",
"method": "string - normalization method used",
"input_stats": {
"mean": "float - mean intensity before normalization",
"std": "float - standard deviation before normalization",
"min": "float - minimum intensity",
"max": "float - maximum intensity",
"nonzero_count": "integer - number of non-zero voxels"
},
"output_stats": {
"mean": "float - mean intensity after normalization",
"std": "float - standard deviation after normalization",
"min": "float - minimum intensity",
"max": "float - maximum intensity"
},
"parameters": {
"method-specific parameters used"
}
},
"metadata": {
"timestamp": "ISO 8601 timestamp",
"duration_ms": "integer - processing time",
"version": "string - skill version"
}
}
Exit Codes
| Code | Meaning |
|---|
| 0 | Success |
| 1 | Validation error (invalid method, bad parameters) |
| 2 | Runtime error (file not found, read/write error) |
| 3 | Usage error (missing required arguments) |
Examples
Basic z-score normalization
./scripts/main.py /path/to/image.nii.gz --output normalized.nii.gz
Output:
{
"success": true,
"result": {
"input_path": "/path/to/image.nii.gz",
"output_path": "normalized.nii.gz",
"method": "z-score",
"input_stats": {
"mean": 1234.5,
"std": 456.7,
"min": 0,
"max": 4095,
"nonzero_count": 125000
},
"output_stats": {
"mean": 0.0,
"std": 1.0,
"min": -2.69,
"max": 6.26
}
}
}
Min-max normalization
./scripts/main.py /path/to/image.nii.gz --output normalized.nii.gz --method min-max
Percentile normalization with custom percentiles
./scripts/main.py /path/to/image.nii.gz -o normalized.nii.gz \
--method percentile \
--percentile-low 0.5 \
--percentile-high 99.5 \
--exclude-background
CT window-level normalization (lung window)
./scripts/main.py /path/to/ct_scan.nii.gz -o lung_window.nii.gz \
--method window-level \
--window-center -600 \
--window-width 1500
Verbose output
./scripts/main.py /path/to/image.nii.gz -o normalized.nii.gz --verbose
Stderr output:
Input file: /path/to/image.nii.gz
Method: z-score
Input shape: (256, 256, 128)
Input stats: mean=1234.5, std=456.7, min=0, max=4095
Output written to: normalized.nii.gz
Processing completed in 245ms
Normalization Methods
Z-score (Standard Score)
Transforms intensities to have zero mean and unit variance:
x_normalized = (x - mean) / std
Best for: General purpose normalization, machine learning inputs.
Min-Max
Scales intensities to [0, 1] range:
x_normalized = (x - min) / (max - min)
Best for: Visualization, algorithms expecting [0, 1] range.
Percentile
Clips values to specified percentiles, then scales to [0, 1]:
x_clipped = clip(x, percentile_low, percentile_high)
x_normalized = (x_clipped - p_low) / (p_high - p_low)
Best for: Robust normalization, handling outliers.
Window-Level (CT specific)
Applies CT window/level transformation:
x_normalized = (x - (center - width/2)) / width
Values outside [0, 1] after transformation are clipped.
Best for: CT scan visualization and analysis with specific tissue windows.
References
Limitations
- Does not handle multi-channel images (e.g., RGB)
- Background exclusion treats all zeros as background
- Window-level method assumes Hounsfield units for CT
- Large images may require significant memory
Disclaimer
For research use only. This skill is not intended for clinical diagnosis or treatment. Always validate outputs and comply with applicable regulations.
Changelog
0.1.0 (2026-03-15)
- Initial release
- Z-score, min-max, percentile, and window-level methods
- NIfTI and other nibabel-supported formats
- Background exclusion option
- Comprehensive statistics output
