Module swi 

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

calculate_swi implements CLEAR-SWI (Eckstein et al. 2021), as CLEARSWI.jl does with its default options. All echoes contribute:

1. Magnitude. The echoes are combined (MagCombine; root-sum-of-squares by default), divided by a receive-sensitivity estimate from the first echo (Sensitivity; the CLEAR bias-field estimate of get_sensitivity) and scaled with a softplus curve (softplus_scaling) whose offset is half the 80th intensity percentile.
2. Phase. Each echo is unwrapped (SwiUnwrap; Laplacian by default), high-pass filtered in-plane (highpass_filter) and the echoes are combined into a frequency map by weighted averaging of φ/TE (B0WeightType; mag·TE, the phase-SNR weighting, by default). With SwiUnwrap::Romeo the echoes are unwrapped together and the combined frequency map is filtered instead.
3. Phase mask. The filtered phase is mapped to [0, 1] (create_phase_mask; a tanh sigmoid by default), and SWI = magnitude × phase mask.

A single echo is the special case without combination: the filtered phase itself drives the phase mask, and the magnitude is that echo’s magnitude.

create_mip gives the minimum-intensity projection (7 slices by default).

SMWI (calculate_smwi) builds the same kind of [0, 1] mask from a susceptibility map instead of from filtered phase, which avoids the blooming and residual-wrap artifacts a phase mask inherits from the non-local dipole field.

References: Eckstein, K., Bachrata, B., Hangel, G., Widhalm, G., Enzinger, C., Barth, M., Trattnig, S., Robinson, S.D. (2021). “Improved susceptibility weighted imaging at ultra-high field using bipolar multi-echo acquisition and optimized image processing: CLEAR-SWI.” NeuroImage 237, 118175. https://doi.org/10.1016/j.neuroimage.2021.118175

Gho, S.-M., et al. (2014). “Susceptibility map-weighted imaging (SMWI) for neuroimaging.” Magnetic Resonance in Medicine, 72:337-346. https://doi.org/10.1002/mrm.24920

Nam, Y., et al. (2017). “Imaging of nigrosome 1 in substantia nigra at 3T using multiecho susceptibility map-weighted imaging (SMWI).” Journal of Magnetic Resonance Imaging, 46:528-536. https://doi.org/10.1002/jmri.25553

Reference implementations: https://github.com/korbinian90/CLEARSWI.jl (SWI; calculateSWI with default Options), https://github.com/kschan0214/sepia (SMWI, misc/swi_smwi/smwi)

Differences from CLEARSWI.jl

• Laplacian unwrapping uses laplacian_unwrap with the DCT solver, whose discrete Laplacian accounts for the voxel size and the matrix size of each axis. MriResearchTools’ laplacianunwrap uses eigenvalues p² + q² + t² (p = 1..N) in index units, which weights the axes by matrix size rather than by voxel spacing. The difference is a smooth field that the high-pass filter largely removes.
• Quantiles for the softplus offset and the rescaling phase masks use the same block sampling as MriResearchTools’ estimatequantile; the brain-agnostic mask comes from [robust_mask].
• The rescaling phase masks (PhaseScaling::Positive and friends) clamp the rescaled value to [0, 1] before raising it to strength, so a value beyond the 1st/99th-percentile extrapolation cannot exceed 1 (or go negative under a non-integer power).

Agreement with CLEARSWI.jl

tests/clearswi_parity.rs (measured 2026-11-02) runs a 20×20×14 three-echo phantom through CLEARSWI.jl 0949bc5 in the verified QSM-CI Julia image (QSMxT/QSM-CI#299; the fixture is regenerated in Actions by tests/data/clearswi_small.jl):

• Matched to rounding: the phase mask’s mask ([robust_mask]) is identical; the SWI magnitude is 2e-14 % from CLEARSWI.jl’s without sensitivity correction (RSS and softplus) and 2e-14 % with the CLEAR sensitivity estimate (get_sensitivity); after unwrapping (given the true phase, CLEARSWI.jl’s own steps: highpass_filter’s masked smoothing, the echo combination and the phase mask) the combined filtered phase is 2e-14 % and the phase mask 4e-15 % from CLEARSWI.jl’s. The 4.4 % (sensitivity) and 1.9 % (masked smoothing) measured before were the port errors in the NaN box filter and box_segment that astewartau/QSM.rs#355 fixed for makehomogeneous (#319), which shares both.
• The deliberate unwrapping difference (above) cannot be avoided by the input: MriResearchTools’ laplacianunwrap does not return even a phase without wraps unchanged (it adds a smooth field of 0.09–0.20 rad standard deviation per echo there), where the DCT solver returns it up to a constant. End to end, this alone puts the phase mask 2.1 % from CLEARSWI.jl’s without wraps and 3.8 % with wraps across the brain (the filtered phase 17 % and 43 %): the high-pass filter does not remove all of it.

Structs

Mip

A minimum-intensity projection, and the geometry it actually lives on.

SmwiParams

SMWI algorithm parameters

SwiParams

CLEAR-SWI parameters. The defaults are CLEARSWI.jl’s Options() defaults.

SwiResult

CLEAR-SWI and the images it was made from.

Enums

MagCombine

Magnitude echo combination for SWI

PhaseScaling

Phase mask scaling type

Sensitivity

Receive-sensitivity correction of the combined SWI magnitude

SmwiContrast

Which susceptibility sources the weighting mask suppresses

SwiUnwrap

Phase unwrapping for SWI

Functions

average_echoes

Average a multi-echo volume over its echoes

calculate_smwi

Calculate SMWI from magnitude and a susceptibility map

calculate_swi

CLEAR-SWI from multi-echo (or single-echo) phase and magnitude.

combine_magnitude

Combine the magnitude echoes for SWI.

create_mip

Minimum intensity projection along the z-axis.

create_phase_mask

Create the SWI phase mask from filtered phase

default_sensitivity_sigma_mm 🔒

CLEARSWI.jl’s default sensitivity sigma: 7 mm, or the median field of view if smaller.

estimate_quantile 🔒

estimate_quantiles 🔒

MriResearchTools’ estimatequantile: quantiles ps of a block sample of data, with Julia’s default (type 7, linear) interpolation. NaN if data holds no finite value.

fill_selected 🔒

Set the voxels whose pos equals positive to value.

highpass_filter

High-pass filter by subtracting a masked Gaussian-smoothed version

median 🔒

Median of v (reordered in place), or None if empty.

mip_geometry

Geometry of a sliding projection over window slices, without computing one.

rescale_selected 🔒

CLEARSWI.jl’s robustrescale(x[sel], new_min, new_max) .^ strength on the voxels whose pos equals positive: the 1st and 99th percentiles, extrapolated to 0 % and 100 %, map to new_min and new_max. Clamped to [0, 1] before the power.

sample 🔒

MriResearchTools’ sample: up to 1e5 finite values taken as √n evenly spaced blocks of √n consecutive values, so a quantile of a large volume is cheap and deterministic.

softplus_scaling

Softplus magnitude scaling for enhanced contrast

susceptibility_mask

Build the SMWI weighting mask from a susceptibility map

swi_magnitude

The SWI magnitude: combined echoes, sensitivity-corrected, softplus-scaled.

swi_phase

The high-pass filtered, echo-combined phase that drives the SWI phase mask.