Module bfrnet 

BFRnet deep-learning background field removal (onnx feature).

BFRnet is a 3D dual-frequency octave-convolution U-Net that predicts the background field from a masked total field; the local tissue field is total − background, re-masked. Everything is in ppm — the network never sees TE/B0/B0-direction. This mirrors the QSM-CI ONNX port (faithful to the authors’ MATLAB predict to |Δ| ≈ 1e-7).

The whole volume runs in one pass, as the authors run it. Its activations scale with the volume: a 184×256×128 scan needs more than a 32-bit (WASM) heap holds. bfrnet_tiled runs it patch by patch instead, with memory bounded by the patch; see it for what that costs.

Weights are not bundled; the caller passes the exported bfrnet.onnx bytes (see crate::models).

Reference pipeline

From Zhu et al., Z Med Phys 2023 (doi:10.1016/j.zemedi.2022.08.001), Methods:

• Training data: 1 mm isotropic 3T (96 subjects, 64³ patches) with simulated healthy and hemorrhage sources.
• In-vivo test inputs: best-path unwrapping (Laplacian unwrapping for the hemorrhage patient), FSL bet2 -f 0.2 (-w 2) mask eroded by 3 voxels, total field from a fit of the unwrapped phase against TE; iLSQR after BFRnet.
• Resolution: “we have only evaluated testing datasets with 1 mm³ isotropic image resolution since this matches the training datasets. BFRnet’s application on total field maps of other image resolutions may need retraining” (Discussion). The authors’ BFRnet_demo.m does not resample.

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, BFRnet (bfrnet) (QSMxT/QSM-CI#316; the fixture is regenerated in Actions by tests/data/dl_field_qsmci_small.py): NRMSE 2.1e-4 %, max |Δ| 1.6e-7 ppm (measured 2026-10-30): float32 rounding. The box is one of the original wrapper’s 128³ patches, so it runs whole there, as bfrnet does here; on volumes larger than 128³ the wrapper tiles and this does not (0.56 % apart on QSM-CI’s 128×160×96 case).

Pipeline rules

The facts above that a configuration can depart from are published as rules in crate::pipeline::rules::RULES (each with its strength, basis, reason and source): bfrnet.mask-bet.

Functions

bfrnet

Run BFRnet on a total field map.

bfrnet_tiled

BFRnet patch by patch: each core block of the background field is predicted from a patch with halo voxels of context on every side (zero outside the volume), padded to a multiple of 8, so peak memory follows the patch, not the volume.