Module iqfm 

iQFM single-step deep-learning tissue-field mapping (onnx feature).

iQFM (Gao 2022) is the local (tissue) field output of the same network as iQSM — a learnable-Laplacian “LoT” front-end + U-Net that maps raw wrapped MRI phase (radians) straight to the background-removed local field (ppm), folding phase unwrapping and background-field removal into one network. It is the iQFM head of the authors’ repo (weights iQFM_40_v2.pth + LoTLayer_lfs_40_v2.pth), the sibling of the χ head used by [super::iqsm].

The exported graph, the four+border inputs, the preprocessing (phase sign, sphere erosion, centre-pad to /16, mask, crop) and the multi-echo combination (IqsmEchoWeighting) are identical to iQSM — only the trained weights and the meaning of the output (local field vs susceptibility) differ. So the Rust glue simply runs iQSM’s exact pipeline with the iqfm.onnx bytes.

Weights are not bundled; the caller passes the exported iqfm.onnx bytes.

Reference pipeline

Identical to iQSM: the authors run iQFM through the same run_iqsm (sunhongfu/iQSM inference.py:139-237), which requires a brain mask for the iQFM output (README).

Agreement with the original

tests/models_onnx/field.rs runs it on a 36×32×28 box of in-vivo data (1 mm, 2.89 T, across the brain’s edge) against its original’s verified QSM-CI entry, iQFM bb163ef (iqfm) (QSMxT/QSM-CI#316; the fixture is regenerated in Actions by tests/data/dl_field_qsmci_small.py): per echo, NRMSE 2.8e-3 to 6.8e-3 %, max |Δ| up to 4.0e-6 ppm: float32 rounding.

The original runs one echo at a time and combines the echoes afterwards. As for iQSM, the authors’ MATLAB echo fit (sunhongfu/iQSM_Plus legacy/matlab/iQFM.m:263-270, and the iQFM output of sunhongfu/iQSM legacy/matlab/demo_multi_echo.m:152-160) weights by mag·TE², an option here, and their Python driver (sunhongfu/iQSM run.py:170, app.py:416) by (mag·TE)², the inverse-variance weight and the default (IqsmEchoWeighting). On the box’s first and third echoes the driver’s combination is (mag·TE)² of its per-echo outputs to 5e-6 %, and the two weightings differ by 3.4 % NRMSE; iqfm_multi_echo matches the MATLAB fit of the original’s per-echo outputs to 2.7e-3 % (measured 2026-10-30), and with the Python weighting their (mag·TE)² combination to 2.7e-3 % (measured 2026-10-31).

Functions

iqfm

Run iQFM on a single echo of wrapped phase; returns the local field (ppm), masked, column-major (nx,ny,nz). See super::iqsm::iqsm for the argument semantics — they are shared verbatim (only the network and its output differ).

iqfm_multi_echo

Multi-echo iQFM: reconstruct each echo and combine them with weighting (default (magnitude·TE)², the inverse-variance weight; see IqsmEchoWeighting), exactly as super::iqsm::iqsm_multi_echo, whole-volume or tiled (tile).