MedImages.jl

A comprehensive Julia library for standardized 3D and 4D medical imaging data handling

Overview

MedImages.jl provides a standardized framework for handling 3D and 4D medical imaging data. The metadata structure is loosely based on the BIDS format¹.

This project aims to create a unified approach to medical image processing across various modalities including CT, MRI, and PET scans. Currently, ultrasonography support is not included, and we welcome contributors with expertise in this area.

Features & Development Roadmap

Feature Category	Status	Description
Data Structure Design	✅	Core data structures for medical imaging standardization
Data Loading	✅	Support for common medical imaging formats
Spatial Transformations	🚧	Advanced spatial processing with metadata preservation
Persistence Layer	🚧	Efficient storage and retrieval mechanisms

Data Structure Design

The core architecture manages these key components:

Component	Includes
Voxel data	Multidimensional arrays
Spatial metadata	• Origin coordinates • Orientation information • Spacing/resolution data
Image classification	• Primary type (CT/MRI/PET/label maps) • Subtype (e.g., MRI: ADC/DWI/T2) • Voxel data type (e.g., Float32)
Study metadata	• Acquisition date/time • Patient identifiers • Study/Series UIDs • Study descriptions • Original filenames
Display properties	• Color mappings for labels • Window/level values for CT scans
Clinical data	• Patient demographics • Contrast administration status
Additional metadata	Stored in extensible dictionaries

Data Loading Capabilities

Format	Implementation	Status
NIfTI	via Nifti.jl	✅
DICOM	via Dicom.jl	✅
MHA	direct implementation	🚧

Spatial Transformations

Our spatial processing framework preserves metadata while enabling:

• Orientation standardization to a common reference frame (e.g., RAS)
• Spacing/resolution adjustment with appropriate interpolation methods
• Cross-modality resampling for multi-modal registration
• Region-of-interest operations (cropping, dilation) with origin adjustments

Persistence Layer

Feature	Description	Status
HDF5-based storage	Arrays with metadata attributes	✅
Device-agnostic I/O	Operations for CPU/GPU	🚧
Format conversion	Exporting to standard medical formats	🚧

Development Status

This project is under active development. The spatial transformation components present the most significant challenges due to numerous edge cases. We're exploring solutions based on packages like MetaArrays.jl.

Component	Status	Priority
Core data structures	✅ Complete	High
Format loading/saving	✅ Complete	High
Spatial transformations	🚧 In progress	High
GPU compatibility	🚧 In progress	Medium
Ultrasonography support	📋 Planned	Low

Quick Start with Docker

The easiest way to get started is using Docker with GPU support for benchmarks.

Prerequisites

• Docker with NVIDIA GPU support (for GPU benchmarks)
• Or Docker without GPU (CPU-only mode available)

Build and Run

# Build the Docker image
make build

# Start interactive Julia REPL (with GPU)
make shell

# Start interactive Julia REPL (CPU only)
make shell-cpu

Run Tests

# Run the full test suite
make test

# Run tests in CPU-only mode
make test-cpu

Run Benchmarks

# Run GPU benchmarks (uses synthetic data)
make benchmark

# Run CPU-only benchmarks
make benchmark-cpu

# Custom benchmark options
make benchmark-custom ARGS="--size 64 --iterations 5"

Verify Setup

# Check CUDA/GPU availability
make check-cuda

# Check Python/SimpleITK setup
make check-python

# Run quick start verification
./scripts/quick-start.sh

Test Data

Test data files are expected in test_data/:

• volume-0.nii.gz - Primary NIfTI test file
• synthethic_small.nii.gz - Synthetic test file
• ScalarVolume_0/ - DICOM test directory

# Check test data availability
./scripts/check-test-data.sh

# Download benchmark data from TCIA
make download-data

# Convert DICOM to NIfTI for benchmarks
make convert-data

Note: Benchmarks use synthetic data by default (make benchmark). Real data download is only needed for make benchmark-full.

All Make Commands

make help  # Show all available commands

Contributing

Contributions are welcome! If you have expertise in medical imaging, particularly ultrasonography, or experience with the technical challenges described above, please consider getting involved.

References

[1] Gorgolewski, K.J., Auer, T., Calhoun, V.D. et al. The brain imaging data structure, a format for organizing and describing outputs of neuroimaging experiments. Sci Data 3, 160044 (2016). https://www.nature.com/articles/sdata201644