OpenKSpace

A Rust library and CLI for Cartesian MRI k-space reconstruction from ISMRMRD .h5 files.

See CHANGELOG.md for version history.

Features

I/O

ISMRMRD HDF5 reader with full AcquisitionHeader parsing
Automatic extraction of noise and calibration scans
Auto-detection of 2D vs 3D encoding from the data

Calibration passes

Noise pre-whitening via per-coil noise covariance + Cholesky (Kellman & McVeigh 2005)
Navigator-echo phase correction (removes N/2 ghosting)
Readout oversampling removal (image-domain crop after IFFT)
Partial-Fourier along ky via homodyne reconstruction (Noll 1991; McGibney 1993)

Reconstruction strategies (pluggable via the `ReconStrategy` trait)

Strategy	Description
`ifft-rss`	Centred IFFT + root-sum-of-squares coil combination
`grappa`	k-space GRAPPA with ACS-fit convolution kernel (Griswold 2002)
`sense`	Image-domain SENSE unfold, ridge-stabilised (Pruessmann 1999), with optional g-factor map output
`cs`	L1-wavelet compressed sensing via FISTA (Lustig 2007; Beck & Teboulle 2009)

SENSE coil-sensitivity maps can be estimated with either

Walsh (eigenvector method, Walsh 2000), or
ESPIRiT (auto-calibrating, Uecker 2014).

All strategies work on both 2D multi-slice and 3D Cartesian data. For 3D acquisitions with ky-only undersampling, parallel-imaging reconstructions decouple along kz via a 1-D IFFT, reducing the problem to independent per-slice unfolds.

Output

PNG image output with percentile contrast windowing (default)
NIfTI-1 single-file volume (.nii) for downstream analysis tools; select with --format nifti or --format both
Optional g-factor PNG output for SENSE (linear window [1, p99])

Usage

openkspace info  <file.h5>                   # print header metadata
openkspace probe <file.h5>                   # scan acquisition index ranges
openkspace recon <file.h5>                   # reconstruct all slices -> recon_out/
    [--out <dir>]                            # output directory (default: recon_out/)
    [--slice <N>]                            # reconstruct one slice only
    [--fft auto|2d|3d]                       # FFT mode (default: auto)
    [--strategy ifft-rss|grappa|sense|cs]    # reconstruction strategy
    [--no-prewhiten]                         # skip noise pre-whitening
    [--no-phasecorr]                         # skip navigator phase correction
    [--no-oversampling-removal]              # keep 2x kx samples
    [--no-partial-fourier]                   # skip homodyne
    [--no-crop]                              # keep full oversampled FOV
    [--pct-low <f>] [--pct-high <f>]         # contrast window percentiles
    [--format png|nifti|both]                # output format (default: png)

  GRAPPA:
    [--grappa-kernel-ky <k>] [--grappa-kernel-kx <k>]
    [--grappa-ridge <lam>]

  SENSE:
    [--sense-maps walsh|espirit]
    [--sense-walsh-window <w>] [--sense-walsh-iters <n>]
    [--espirit-kernel <k>] [--espirit-threshold <f>] [--espirit-iters <n>]
    [--sense-ridge <lam>]
    [--sense-gfactor]                        # compute g-factor
    [--write-gfactor]                        # also emit g-factor PNGs

  CS:
    [--cs-iters <n>] [--cs-lambda <f>]

Examples

# Plain IFFT + RSS
openkspace recon data.h5 --slice 15

# GRAPPA
openkspace recon data.h5 --strategy grappa

# SENSE with ESPIRiT maps and g-factor output
openkspace recon data.h5 --strategy sense \
    --sense-maps espirit --write-gfactor

# Compressed sensing
openkspace recon data.h5 --strategy cs --cs-iters 120 --cs-lambda 0.01

Workspace layout

Crate	Description
`openkspace-io`	ISMRMRD reader, acquisition structs, calibration scan extraction
`openkspace-recon`	Reconstruction math: FFT, coil combination, prewhitening, phase correction, GRAPPA, SENSE, ESPIRiT, Walsh, CS
`openkspace-cli`	`openkspace` command-line binary

Building

Requires Rust 1.75+ and HDF5 system libraries.

cargo build --release
cargo test

The openkspace binary is produced at target/release/openkspace.

Validation

A Python harness in scripts/ compares the Rust reconstruction against a reference on a per-slice basis using SSIM. It supports both ISMRMRD and FastMRI files (format is auto-detected). See scripts/README.md for details.

./scripts/validate.sh path/to/file.h5 --slice 15

On the NYU/Meta FastMRI multicoil knee corpus (652 files, slices 0-35 each), the IFFT+RSS+center-crop pipeline achieves SSIM = 1.0000 against the reconstruction_rss ground truth bundled in each file, confirming bit-exact agreement between the Rust implementation and the reference reconstruction.

Citation

If you use OpenKSpace in research, please cite the underlying algorithm paper for whichever reconstruction method you invoked (see CREDITS.md) and, optionally, this repository.

License

Apache-2.0. See LICENSE.

openkspace-recon 0.2.0