Crate qsm_core 

QSM-Core

A Rust library for Quantitative Susceptibility Mapping (QSM) of the brain.

QSM-Core reconstructs magnetic susceptibility maps from MRI phase data: brain extraction, phase unwrapping, background field removal, dipole inversion, and susceptibility source separation.

Which API should I use?

The crate offers two entry points at different levels:

• pipeline — the high-level API. Describe a scan with [ScanMetadata] and a [QsmPipelineConfig], then call the run_* stage functions. This is the easiest way to go from phase data to a susceptibility map and the recommended starting point.
• Algorithm building blocks — the low-level API. Each algorithm (bgremove::vsharp(), inversion::tv_admm(), …) is a plain function taking a Grid, a *Params struct, and (for iterative methods) a progress callback. Use these when you want to wire stages together yourself.

use qsm_core::{Grid, bet, unwrap, bgremove, inversion};
use qsm_core::bet::BetParams;
use qsm_core::bgremove::VsharpParams;
use qsm_core::inversion::TvParams;

let grid = Grid::new(128, 128, 64, 1.0, 1.0, 1.0);
let bdir = (0.0, 0.0, 1.0);

let mask = bet::run_bet(magnitude, &grid, &BetParams::default(), |_, _| {});
let unwrapped = unwrap::laplacian_unwrap(phase, &mask, &grid);
let (local, eroded) = bgremove::vsharp(&unwrapped, &mask, &grid, &VsharpParams::default(), |_, _| {});
let chi = inversion::tv_admm(&local, &eroded, &grid, bdir, &TvParams::default(), |_, _| {});

Modules

High-level pipeline

• pipeline — config-driven full reconstruction

Algorithm building blocks

• bet — brain extraction (BET)
• unwrap — phase unwrapping (ROMEO, Laplacian)
• bgremove — background field removal (V-SHARP, SHARP, RESHARP, PDF, iSMV, mSMV, LBV, HARPERELLA)
• inversion — dipole inversion (TKD, TSVD, Tikhonov, TV, NLTV, RTS, MEDI, iLSQR, TGV)
• separation — paramagnetic/diamagnetic source separation (χ-separation, R2*-QSM, WaveSep)
• swi — susceptibility weighted imaging (CLEAR-SWI)
• fieldmap — multi-echo phase combination and B0 field mapping
• r2star — R2*/T2* mapping (ARLO)
• mask — mask thresholding and morphology
• homogeneity — receive-field bias correction

Core types & I/O

• Grid — 3D volume descriptor shared by every algorithm
• io — NIfTI read/write

Feature Flags

• parallel — enables Rayon-based multi-threading for FFT and iterative solvers
• simd — enables SIMD acceleration via the wide crate

Algorithms

Stage	Methods
Brain extraction	BET
Phase unwrapping	ROMEO, Laplacian
Background removal	V-SHARP, SHARP, RESHARP, PDF, iSMV, LBV, SDF
Dipole inversion	TKD, TSVD, Tikhonov, TV-ADMM, NLTV, RTS, MEDI, TGV, iLSQR
Combined unwrap+BFR	HARPERELLA, iHARPERELLA
SWI	CLEAR-SWI
Separation	Chi-separation (Shin 2021 iLSQR-initialized, MEDI-based)
Multi-echo	MCPC-3D-S, R2*/T2* (ARLO), bias correction
Utilities	Frangi vesselness, surface curvature, Otsu thresholding, QSMART

Modules

bet

Brain extraction.

bgremove

Background field removal methods

crop

Scan geometry from the NIfTI affine: B0 direction, obliquity, and resampling to an axial grid.

denoise

MP-PCA denoising for multi-volume data (e.g. multi-echo magnitude).

fieldmap

Multi-echo phase combination and B0 field mapping.

geometry

Scan geometry derived from the NIfTI affine, and resampling to an axial grid.

homogeneity

Receive-field (B1−) bias correction for magnitude images.

inversion

Dipole inversion methods for QSM

io

NIfTI file I/O for WASM

mask

Brain-mask thresholding and morphology.

models

Registry of deep-learning QSM models and their downloadable ONNX weights.

pipeline

QSM pipeline stages and utilities

r2star

R2*/T2* mapping from multi-echo magnitude (ARLO).

relaxometry

R2/T2 mapping from multi-echo spin-echo (EPG), and R2’ = R2* − R2.

separation

Susceptibility source separation

swi

Susceptibility Weighted Imaging (SWI)

unring

Gibbs-ringing removal (Kellner 2016 subvoxel shifts) for k-space-truncated images. Complementary to denoise: unringing removes truncation ringing, MP-PCA removes random noise. Recommended before R2*/R2 fitting.

unwrap

Phase unwrapping methods

Macros

maybe_par_chunks

Parallel or sequential (immutable) chunks iterator.

maybe_par_chunks_mut

Parallel or sequential chunks iterator.

maybe_par_iter

Parallel or sequential immutable iterator over a slice.

maybe_par_iter_mut

Parallel or sequential mutable iterator over a slice.

maybe_par_map_init

Parallel or sequential map with a reusable mutable state produced by $init.

Structs

Grid

A 3D volume grid with dimensions and voxel sizes.