MREG Optical Flow Toolkit (v6, full)

High-quality, 3D TV-L1 optical-flow analysis for fMRI/MREG volumes. This toolkit assumes you filter temporally outside the code.

Contents

• mreg_of/ (package)
  • preprocess.py, tvl1_3d.py, metrics.py
  • run_of.py, autotune.py, merge_flows.py, avg_flow.py, quiver_vis.py
• requirements.txt

See our previous messages for usage examples (or ask me to paste them again). Units

Flow fields (u,v,w) are in voxel units per frame by default.

Use the --to_mm flag (with the NIfTI affine) to convert to mm per frame.

Add --per_second --tr [--stride k] to convert to mm/s.

Script summaries & options run_of.py — compute flows python -m mreg_of.run_of --in_nifti INPUT.nii.gz --out_dir OUT [--mask_nifti MASK.nii.gz] [--zscore] [--crop_to_mask] [--levels 4] [--warps 3] [--iters 40] [--lambda_data 12.0] [--tv_weight 0.5] [--tau 0.08] [--sigma 0.08] [--theta 0.5] [--sigma_grad 0.7] [--flow_clip 5.0] [--t_from 0] [--t_to TMAX] [--stride 1] [--save_mode perframe|stack]

Outputs per-pair flow_tXXXXX_dtYY.nii.gz (X,Y,Z,3) and speed_*.nii.gz or a single flow_stack.nii.gz.

Key params

Pyramid: --levels (depth), --warps (per level), --iters (per warp)

Data/regularization: --lambda_data, --tv_weight

Optimization: --tau, --sigma, --theta, --sigma_grad, --flow_clip

Preprocess: --zscore, --crop_to_mask

Range: --t_from, --t_to, --stride

autotune.py — hyperparameter search python -m mreg_of.autotune --in_nifti INPUT.nii.gz --out_json params.json [--mask_nifti MASK.nii.gz] [--zscore] [--t_samples 8] [--stride 1] [--levels 3] [--warps 2] [--iters 25] [--ds_factor 2] [--seed 0]

Optimizes a small grid by objective = median photometric error + TV + speed prior (95th percentile near 0.05–2.0 vox/frame).

merge_flows.py — stack per-frame flows python -m mreg_of.merge_flows --flows_glob "OUT/flow_t*_dt01.nii.gz" --out_path OUT/flow_stack.nii.gz

avg_flow.py — average flow & speed python -m mreg_of.avg_flow --flows_glob "OUT/flow_t*_dt01.nii.gz" --out_dir OUT/avg [--flow_stack OUT/flow_stack.nii.gz] [--to_mm] [--per_second] [--tr 0.1] [--stride 1]

quiver_vis.py — masked quiver visualization python -m mreg_of.quiver_vis --flow_nifti OUT/avg/avg_flow_vox.nii.gz --out_png OUT/avg/quiver_x.png --axis x --index 40 --step 4 --mask_nifti MASK.nii.gz [--mask_erode 2] [--clip_background_to_mask] [--auto_scale --q 0.95 --target 0.7] [--to_mm] [--per_second --tr 0.1 --stride 1] [--ref_nifti INPUT.nii.gz]

Strict masking before/after decimation; --mask_erode helps remove edge bleed. --auto_scale sizes arrows by the 95th-percentile length.

Typical pipeline

Filter NIfTI (outside this toolkit).

Compute flows (example):

python -m mreg_of.run_of --in_nifti filtered.nii.gz --mask_nifti brain_mask.nii.gz
--out_dir OUT --levels 4 --warps 3 --iters 40
--lambda_data 10 --tv_weight 0.6 --sigma_grad 0.7 --flow_clip 5
--zscore --stride 1 --save_mode perframe

Average:

python -m mreg_of.avg_flow --flows_glob "OUT/flow_t*_dt01.nii.gz"
--out_dir OUT/avg --to_mm --per_second --tr 0.1

Visualize:

python -m mreg_of.quiver_vis --flow_nifti OUT/avg/avg_flow_mm_per_s.nii.gz
--out_png OUT/avg/quiver_x.png --axis x --index 40 --step 4
--mask_nifti brain_mask.nii.gz --mask_erode 1 --clip_background_to_mask
--auto_scale --q 0.95 --target 0.6

Troubleshooting

NaNs/overflows → increase --sigma_grad, reduce --tau/--sigma, lower --flow_clip

Arrows outside mask → resample mask to flow grid; use --mask_erode; add --clip_background_to_mask

Tiny arrows → --auto_scale or --scale

Slow/heavy → lower --levels, --warps, --iters or use --crop_to_mask