Module msmv 

Maximum Spherical Mean Value (mSMV) background field removal

mSMV removes the residual harmonic background field near the brain boundary — the dominant source of QSM shadow artifacts — using the maximum-value corollary of Green’s theorem, and does so without eroding the brain mask.

Two ways to use it (the prefilter flag)

In the original work mSMV is a refinement applied after a primary background removal, and that is its intended use:

let (local, m) = bgremove::vsharp(&total, &mask, &grid, &VsharpParams::default(), |_,_| {});
let (refined, _) = bgremove::msmv(&local, &m, &grid, &MsmvParams::refine(), |_,_| {});

It composes with any harmonic BFR that leaves a boundary shadow — sharp, resharp, vsharp, pdf, lbv. (It is redundant after ismv, which is already iterative SMV.) In this mode set MsmvParams::prefilter = false (via MsmvParams::refine) so mSMV does only the boundary correction on the already-local field.

With prefilter = true (the default, matching the QSM-CI submission) mSMV is a self-contained total→local BFR: it first does its own SMV primary removal, then the boundary correction. Run standalone it is only as strong as one non- deconvolved SMV pass, so prefer the refinement mode above for real pipelines.

The two internal steps:

1. SMV primary removal (only if prefilter): RDF_s = mask·(RDF − SMV(RDF)) (radius radius mm). When prefilter is false the input field is taken as the local field directly.
2. Boundary shadow correction: iteratively detect boundary voxels whose residual field exceeds an adaptive threshold t and strip it with a minimum-radius SMV.

Units

mSMV’s shadow-detection threshold is defined in radians and capped at 0.01·B0/3 rad. The library carries fields in ppm, so this port converts ppm→rad with rad = ppm · 2π · γ · B0 · TE (γ in MHz/T), runs the filter, then converts back. TE only sets the operating point of the radian threshold; the filter is otherwise a (thresholded) linear high-pass.

The optional vessel-protection step (which needs an R2* map) is omitted, per the upstream behaviour when R2* is unavailable.

Reference: Roberts, A.G., et al. (2024). “Maximum spherical mean value (mSMV) filtering for whole-brain quantitative susceptibility mapping.” Magnetic Resonance in Medicine, 91(4):1586-1597. https://doi.org/10.1002/mrm.29963

Reference implementation: https://github.com/agr78/mSMV (msmv.m, MEDI SMV helpers)

Structs

MsmvParams

Parameters for msmv.

Constants

GYRO_MHZ_T 🔒

Proton gyromagnetic ratio in MHz/T (matches the QSM-CI recon.m constant).

Functions

msmv

mSMV background field removal (SMV primary removal + boundary shadow correction).