API reference

Reading & writing

Read a flow field from any supported source.

Dispatches on file extension, then magic bytes:

• .flo — Middlebury
• .png — KITTI 16-bit flow
• .pfm — Sintel / FlyingThings
• .npy / .npz — saved numpy arrays
• .flo5 / .h5 — Spring (requires h5py)

Non-path inputs (numpy arrays, torch tensors, existing Flow objects) are normalized via :func:flowiz.core.as_flow.

Write a flow field, choosing the format from path's extension.

Supports .flo (Middlebury), .png (KITTI 16-bit), and .npy.

Convert a torch tensor to a :class:Flow (or list, if batched).

Accepts (H, W, 2), (2, H, W), or a batched (N, 2, H, W) / (N, H, W, 2) tensor. Batched inputs return a list of flows. The tensor is detached and moved to CPU automatically.

A dense 2D optical flow field.

Attributes:

Name	Type	Description
data	ndarray	(H, W, 2) float32 array, [..., 0] = u (horizontal), [..., 1] = v (vertical).
valid	Optional[ndarray]	optional (H, W) bool mask of valid pixels. None means all pixels valid.
source	Optional[str]	provenance string (a file path, or "tensor"/"array").

angle property

Per-pixel flow direction in radians, atan2(v, u) in [-pi, pi].

magnitude property

Per-pixel flow magnitude sqrt(u**2 + v**2).

max_magnitude()

Largest magnitude over valid pixels (0.0 for an empty field).

Visualization

Optical flow colorization.

The color mapping is the Baker et al. / Middlebury color wheel, implemented to be bit-compatible (within +-1 LSB) with the widely used flow_vis package so that flowiz output matches figures across the literature. See tests/test_parity.py for the guardrail.

colorize(flow, *, max_flow=None, saturate=True, mask_invalid=True, convention='middlebury', legend=False)

Colorize a flow field into an (H, W, 3) uint8 RGB image.

Parameters:

Name	Type	Description	Default
flow	Any	a :class:Flow, numpy array (H, W, 2)/(2, H, W), or torch tensor.	required
max_flow	Optional[float]	normalization magnitude. None normalizes by this frame's max magnitude (default, matches flow_vis). A float fixes the normalizer, which is what you want for temporally consistent video (see :func:colorize_sequence).	None
saturate	bool	when max_flow is a float, clip magnitudes above it instead of letting them wrap darker.	True
mask_invalid	bool	render pixels flagged invalid (by the flow's valid mask or by NaN / >1e9 sentinels) as black.	True
convention	Convention	"middlebury" (default) or "hsv".	'middlebury'
legend	bool	overlay the color-wheel key in the bottom-right corner.	False

colorize_sequence(flows, *, max_flow='sequence', **kwargs)

Colorize many flows with a shared normalizer (flicker-free video).

max_flow="sequence" (default) computes one normalizer from the max magnitude across every frame — the fix for v2's per-frame flicker. Pass a float to fix it explicitly, or None to fall back to per-frame maxima.

flow_to_angle(flow, *, cmap='hsv')

Direction map as an (H, W, 3) uint8 RGB image (angle -> hue).

flow_to_magnitude(flow, *, cmap='magma', max_flow=None)

Magnitude heatmap as an (H, W, 3) uint8 RGB image.

flow_to_uv(flow)

Split flow into a normalized (H, W, 2) uint8 UV image (u, v channels).

make_colorwheel() cached

Return the (55, 3) uint8 Middlebury color wheel.

Cached — v2 rebuilt this on every frame.

wheel_legend(size=128) cached

Render the color-wheel key as an (size, size, 4) RGBA uint8 image.

Pixels outside the unit disk are transparent.

Colorize many flows with a shared normalizer (flicker-free video).

max_flow="sequence" (default) computes one normalizer from the max magnitude across every frame — the fix for v2's per-frame flicker. Pass a float to fix it explicitly, or None to fall back to per-frame maxima.

Split flow into a normalized (H, W, 2) uint8 UV image (u, v channels).

Magnitude heatmap as an (H, W, 3) uint8 RGB image.

Direction map as an (H, W, 3) uint8 RGB image (angle -> hue).

Vector (quiver) overlays on top of a colorized flow field.

quiver(flow, *, background=None, step=16, scale=1.0, color=(255, 255, 255), max_flow=None)

Draw flow vectors on a grid over a background image.

Uses matplotlib's quiver for anti-aliased arrows and returns an (H, W, 3) uint8 RGB image the same size as the input flow.

Parameters:

Name	Type	Description	Default
flow	Any	flow input (Flow / array / tensor).	required
background	Optional[ndarray]	RGB image to draw on. Defaults to the colorized flow.	None
step	int	grid spacing in pixels between sampled vectors.	16
scale	float	multiplier on arrow length.	1.0
color	tuple[int, int, int]	RGB arrow color.	(255, 255, 255)
max_flow	Optional[float]	passed through to the default colorized background.	None

Render the color-wheel key as an (size, size, 4) RGBA uint8 image.

Pixels outside the unit disk are transparent.

Return the (55, 3) uint8 Middlebury color wheel.

Cached — v2 rebuilt this on every frame.

Metrics

End-point error between a predicted and ground-truth flow.

EPE is the per-pixel Euclidean distance ||pred - gt||. Summary statistics are computed over pixels valid in both inputs.

KITTI Fl outlier rate (percent).

A pixel is an outlier when its EPE exceeds 3 px and exceeds 5% of the ground-truth magnitude. Returns the percentage of outliers over valid px.

Per-pixel EPE rendered as an (H, W, 3) uint8 heatmap.

Build a prediction | ground-truth | error-map figure — the paper money shot.

Normalizes both flow panels by a shared max_flow so colors are comparable. Annotates EPE / Fl-score in the suptitle. Returns the matplotlib Figure and, if save is given, writes it to disk.

Bases: NamedTuple

End-point-error summary over valid pixels.

Batch & video

Convert flow files to PNG images.

Parameters:

Name	Type	Description	Default
files	Sequence[str]	input flow paths.	required
outdir	Optional[str]	output directory (created if needed). None writes alongside each input as <name>.png.	None
mode	str	rgb | uv | mag | angle.	'rgb'
workers	int	process-pool size for parallel conversion.	1
progress	Optional[Callable[[str], None]]	optional callback invoked with each output path as it lands.	None
**kwargs	Any	forwarded to :func:colorize for mode="rgb".	{}

Compile flow files into a video (.mp4/.webm/.gif by extension).

Parameters:

Name	Type	Description	Default
files	Sequence[str]	input flow file paths (any supported format). Sorted naturally.	required
output	str	output video path; the container is inferred from the suffix.	required
fps	int	frames per second.	24
normalize	str	"sequence" normalizes every frame by the sequence-wide max magnitude (flicker-free — the default). "frame" normalizes each frame independently (v2 behavior). Ignored if max_flow set.	'sequence'
max_flow	Optional[float]	explicit fixed normalizer; overrides normalize.	None
quality	int	imageio quality (0-10) for lossy codecs.	8
progress	Optional[Any]	optional callable invoked once per frame (e.g. a Rich task update) — receives the 1-based frame index.	None