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(), bet::FslLeftRightOrder::Radiological, |_, _| {});
let unwrapped = unwrap::laplacian_unwrap(phase, &mask, &grid, unwrap::LaplacianSolver::Dct);
let (local, eroded) = bgremove::vsharp(&unwrapped, &mask, &grid, &VsharpParams::default(), |_, _| {}).unwrap();
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, best path, PRELUDE)
• bgremove — background field removal (V-SHARP, SHARP, RESHARP, PDF, iSMV, LBV, HARPERELLA)
• inversion — dipole inversion (TKD, TSVD, Tikhonov, TV, NLTV, RTS, MEDI incl. MEDI-mSMV, iLSQR, STAR-QSM, TGV)
• separation — paramagnetic/diamagnetic source separation (χ-separation, R2*-QSM, WaveSep)
• swi — susceptibility weighted imaging (CLEAR-SWI, SMWI)
• complex — real/imaginary input to magnitude/phase
• 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, best path (3D-SRNCP), PRELUDE
Background removal	V-SHARP, SHARP, RESHARP, PDF, iSMV, LBV, SDF
Dipole inversion	TKD, TSVD, Tikhonov, TV-ADMM, NLTV, RTS, MEDI, TGV, iLSQR, STAR-QSM
Combined unwrap+BFR	HARPERELLA, iHARPERELLA
SWI	CLEAR-SWI
Separation	Chi-separation (Shin 2021 iLSQR-initialized, MEDI-based)
Input	Real/imaginary to magnitude/phase (slice-chopping correction)
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

complex

Real/imaginary input: conversion to magnitude and phase.

constants

Physical constants (gyromagnetic ratio). Physical constants shared across the crate.

crop

Cropping reconstruction to the region that carries signal, and putting the answer back.

denoise

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

error

InputError: what an algorithm returns instead of panicking when it is handed input it cannot process. The error an algorithm returns when it is handed input it cannot process.

fieldmap

Multi-echo phase combination and B0 field mapping.

geometry

Scan geometry from the NIfTI affine: B0 direction, obliquity, 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.

motion

Retrospective motion correction: co-register a series of repeats, runs or echoes onto one of them, in the complex domain, and re-derive B0 for each.

pipeline

QSM pipeline stages and utilities

r2star

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

registration

Rigid-body (6-DOF) registration between two volumes: recovering the transform that geometry can already apply.

relaxometry

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

segment

Anatomical segmentation.

separation

Susceptibility source separation

swi

Susceptibility Weighted Imaging (CLEAR-SWI) and Susceptibility Map-Weighted Imaging (SMWI)

unring

Gibbs-ringing removal by subvoxel shifts for k-space-truncated images: Bautista et al.’s 3-D method for 3-D acquisitions (the default), Kellner et al.’s 2-D method for 2-D multi-slice acquisitions (MRtrix3’s implementation), and DIPY’s 2-D implementation as a parity option. See GibbsMode. 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.

Enums

EchoTime

Which echo time a method converts the field from ppm to radians at.