Image Pre-Processing

Build filter stacks to improve correlation quality. Test interactively with side-by-side raw vs. processed comparison.

Overview

Filters are applied sequentially from top to bottom. Temporal filters should precede spatial filters. All changes auto-save to config.yaml.

Temporal Filters

Operate across multiple frames (batches) to remove persistent features.

time -- Subtract local minimum across batch
pod -- SVD-based background removal (Mendez et al.)

Spatial Filters

Operate per-frame via scipy.ndimage.

Smoothing: gaussian, median
Contrast: clip, norm, maxnorm, lmax
Correction: invert, sbg, levelize

Temporal Filters

Require batch processing. Set batch size via the Batch Size input (appears when temporal filters are in the stack). Frame A and Frame B channels are processed independently.

Filter	Parameters	Algorithm	Removes
time	None	Subtract per-pixel minimum over batch	Static backgrounds, reflections
pod	None (auto mode detection)	SVD decomposition; auto-detect noise threshold; subtract signal modes	Coherent structures, time-varying backgrounds

Spatial Filters

Applied per-frame after temporal filters. Kernel sizes are auto-adjusted to be odd.

Filter	Parameters	Description
gaussian	sigma: 1.0 (float)	Gaussian blur. Reduces high-frequency noise.
median	size: [5, 5] ([h, w])	Median filter. Removes salt-and-pepper noise, preserves edges.
clip	n: 2.0 (float) or threshold: [lo, hi]	Clip intensities. Auto mode: median +/- n*std.
norm	size: [7, 7], max_gain: 1.0	Local contrast normalisation (subtract sliding min, divide by range).
maxnorm	size: [7, 7], max_gain: 1.0	Similar to norm with smoothed contrast field.
lmax	size: [7, 7]	Morphological dilation (local maximum). Enhances bright features.
invert	offset: 255 (int)	Invert intensities: output = offset - input.
sbg	bg: /path/to/bg.tif	Subtract reference background image.
levelize	white: /path/to/white.tif	Divide by white reference to correct uneven illumination.

GUI Workflow

The ImagePairViewer displays raw and processed images side-by-side with synchronised zoom/pan.

Workflow

Add filters from the dropdown. They appear as expandable cards in the filter stack.
Configure parameters for each filter. Reorder with up/down arrows, remove with delete.
Click Test Filters to apply the stack to the current frame (or batch for temporal filters).
Compare raw vs. processed. Zoom into regions of interest.
Use playback controls to verify consistency across frames.

Spatial-only stacks

Near-instant results -- only the current frame is processed.

With temporal filters

Processes the full batch. Progress indicator shown during computation.

Recommended order: Temporal filters first (time, pod) for background removal, then spatial filters for noise reduction and contrast enhancement.

YAML Reference

filters:
  # Temporal (require batch processing)
  - type: time
  - type: pod

  # Spatial (per-frame, order matters)
  - type: gaussian
    sigma: 1.0              # float: std dev in pixels
  - type: median
    size: [5, 5]            # [int, int]: kernel [h, w]
  - type: clip
    n: 2.0                  # float: std devs for auto threshold
    # threshold: [10, 250]  # Alternative: explicit [min, max]
  - type: norm
    size: [7, 7]
    max_gain: 1.0           # float: max normalisation gain
  - type: maxnorm
    size: [7, 7]
    max_gain: 1.0
  - type: lmax
    size: [7, 7]
  - type: invert
    offset: 255
  - type: sbg
    bg: /path/to/background.tif
  - type: levelize
    white: /path/to/white_ref.tif

batches:
  size: 30                  # Frames per batch (for temporal filters)

Parameter Quick Reference

Filter	Type	Parameter	Default
time	Temporal	(none)	-
pod	Temporal	(none)	-
gaussian	Spatial	sigma	1.0
median	Spatial	size	[5, 5]
clip	Spatial	n / threshold	2.0 / null
norm	Spatial	size, max_gain	[7,7], 1.0
maxnorm	Spatial	size, max_gain	[7,7], 1.0
lmax	Spatial	size	[7, 7]
invert	Spatial	offset	255
sbg	Spatial	bg	null
levelize	Spatial	white	null

Next: PIV Processing

Configure cross-correlation parameters for vector field computation.

Continue to PIV Processing