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
Normalization: norm, norm2, maxnorm
Background: ssmin, invert
Enhancement: lmax, clahe

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	size: [7, 7], sigma: 1.0	Gaussian low-pass smoothing. Reduces high-frequency noise while preserving large-scale intensity. Uses a finite (FIR) kernel.
median	size: [5, 5]	Replaces each pixel with its neighbourhood median. Removes salt-and-pepper noise and hot pixels without blurring edges.
norm	size: [7, 7], max_gain: 1.0	Range normalize: subtracts the local minimum then divides by the local range (max − min). Maps each pixel to [0, 1] relative to its neighbourhood. Good general-purpose contrast equalization.
norm2	size: [7, 7], max_gain: 1.0	Smoothed range normalize: like norm, but box-smooths both the min and max envelopes before normalizing. More robust to single-pixel noise spikes.
maxnorm	size: [7, 7], max_gain: 1.0	Background normalize: divides by the smoothed local minimum (background level). Equalizes illumination gradients — particles come out as values > 1, background → 1. Max gain limits amplification in dark regions.
ssmin	size: [7, 7]	SSMin (sliding minimum background subtraction). Median-smooths, extracts the local minimum (background envelope), box-smooths it, and subtracts. Removes slowly-varying background (laser sheet profile, reflections). Output clipped to ≥ 0.
lmax	size: [7, 7]	Morphological dilation (local maximum). Replaces each pixel with the maximum in its neighbourhood. Useful for expanding bright features and peak detection.
invert	(none)	Inverts intensity: output = max(image) − pixel. For background-oriented schlieren (BOS) or shadowgraph where particles are dark on a bright background.
clahe	clip_limit: 2.0, tile_grid_size: [8, 8]	Contrast Limited Adaptive Histogram Equalization. Enhances local contrast in tiles, useful for images with uneven illumination or very low contrast.

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
    size: [7, 7]            # [int, int]: kernel [h, w] (odd only)
    sigma: 1.0              # float: std dev in pixels
  - type: median
    size: [5, 5]            # [int, int]: kernel [h, w] (odd only)
  - type: norm              # Range normalize
    size: [7, 7]
    max_gain: 1.0           # float: max amplification in low-contrast regions
  - type: norm2             # Smoothed range normalize
    size: [7, 7]
    max_gain: 1.0
  - type: maxnorm           # Background normalize
    size: [7, 7]
    max_gain: 1.0
  - type: ssmin             # Subtract background
    size: [7, 7]
  - type: lmax              # Local maximum (dilation)
    size: [7, 7]
  - type: invert            # Invert (max - pixel)
  - type: clahe             # Adaptive histogram equalization
    clip_limit: 2.0
    tile_grid_size: [8, 8]

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

Parameter Quick Reference

Filter	Type	Parameter	Default
time	Temporal	(none)	-
pod	Temporal	(none)	-
gaussian	Spatial	size, sigma	[7,7], 1.0
median	Spatial	size	[5, 5]
norm	Spatial	size, max_gain	[7,7], 1.0
norm2	Spatial	size, max_gain	[7,7], 1.0
maxnorm	Spatial	size, max_gain	[7,7], 1.0
ssmin	Spatial	size	[7, 7]
lmax	Spatial	size	[7, 7]
invert	Spatial	(none)	-
clahe	Spatial	clip_limit, tile_grid_size	2.0, [8,8]

Next: PIV Processing

Configure cross-correlation parameters for vector field computation.

Continue to PIV Processing