Skip to content

API Reference

motionflow.process_video

motionflow.api.process_video(input, output=None, method=Method.FARNEBACK, viz=VizStyle.HSV, blend=0.0, stride=1, normalize=NormalizeMode.PER_FRAME, max_flow=None, smooth=0, codec='auto', fps=None, device='auto', model_size=ModelSize.LARGE, quiver_step=16, on_progress=None)

Process a video and write an optical flow visualisation.

This is the primary entry point for the Python API. All CLI options map directly to arguments here.

Parameters:

Name Type Description Default
input Path | str

Path to the input video.

 required
output Path | str | None

Output path. Defaults to <input_stem>_flow.<ext>.

 None
method str | Method

Optical flow algorithm. See :class:~motionflow.types.Method.

 FARNEBACK
viz str | VizStyle

Visualisation style. See :class:~motionflow.types.VizStyle.

 HSV
blend float

Opacity of original frame composited over flow visualisation. 0.0 is pure flow, 1.0 is pure original. Only applies when viz is not "quiver" or "blend".

 0.0
stride int

Compute flow every N frames. Frames in between repeat the last computed flow.

 1
normalize str | NormalizeMode

Flow magnitude normalisation strategy. "global" requires a full first pass through the video.

 PER_FRAME
max_flow float | None

Manual magnitude cap. Overrides normalize.

 None
smooth int

Temporal smoothing window in frames. 0 disables smoothing.

 0
codec str

FourCC codec string for the output file.

 'auto'
fps float | None

Output frames per second. Preserves the source FPS if None.

 None
device str

Compute device for deep methods ("auto", "cuda", "mps", "cpu").

 'auto'
model_size str | ModelSize

Model size for RAFT/SEA-RAFT ("small" or "large").

 LARGE
quiver_step int

Grid spacing in pixels for quiver arrows.

 16
on_progress Callable[[int, int], None] | None

Optional callback (current_frame, total_frames) called after each output frame is written.

 None

Returns:

Type Description
Path

Path to the written output video.

motionflow.types

motionflow.types.Method

Bases: str, Enum

Optical flow estimation method.

motionflow.types.VizStyle

Bases: str, Enum

Flow visualisation style.

motionflow.types.NormalizeMode

Bases: str, Enum

Flow magnitude normalisation strategy.

motionflow.types.ModelSize

Bases: str, Enum

Model size for deep learning methods.

motionflow.viz

motionflow.viz.flow_to_hsv(flow, max_flow=None)

Render flow as an HSV colour wheel image.

Hue encodes direction, brightness encodes magnitude.

Parameters:

Name Type Description Default
flow ndarray

Flow array of shape (H, W, 2) with (dx, dy) components.

 required
max_flow float | None

Magnitude used to normalise brightness. Computed per-frame if None.

 None

Returns:

Type Description
ndarray

BGR image of shape (H, W, 3).

motionflow.viz.flow_to_heatmap(flow, max_flow=None)

Render flow magnitude as a heatmap (COLORMAP_INFERNO).

Direction information is discarded.

Parameters:

Name Type Description Default
flow ndarray

Flow array of shape (H, W, 2).

 required
max_flow float | None

Magnitude cap for normalisation. Computed per-frame if None.

 None

Returns:

Type Description
ndarray

BGR image of shape (H, W, 3).

motionflow.viz.flow_to_quiver(flow, frame, step=16, scale=1.0, color=(0, 255, 0), thickness=1)

Render flow as arrow overlays on the original frame.

Parameters:

Name Type Description Default
flow ndarray

Flow array of shape (H, W, 2).

 required
frame ndarray

BGR source frame of shape (H, W, 3).

 required
step int

Grid spacing in pixels between arrow origins.

 16
scale float

Arrow length multiplier.

 1.0
color tuple[int, int, int]

BGR arrow colour.

 (0, 255, 0)
thickness int

Arrow line thickness.

 1

Returns:

Type Description
ndarray

BGR image with arrows overlaid.

motionflow.viz.flow_to_blend(flow, frame, alpha=0.5, max_flow=None)

Blend HSV flow visualisation with the original frame.

Parameters:

Name Type Description Default
flow ndarray

Flow array of shape (H, W, 2).

 required
frame ndarray

BGR source frame of shape (H, W, 3).

 required
alpha float

Weight of the original frame (0 = pure flow, 1 = pure original).

 0.5
max_flow float | None

Normalisation cap for flow visualisation.

 None

Returns:

Type Description
ndarray

BGR blended image of shape (H, W, 3).

motionflow.viz.visualize_flow(flow, style, frame=None, blend=0.0, max_flow=None, quiver_step=16)

Dispatch flow visualisation to the appropriate renderer.

Parameters:

Name Type Description Default
flow ndarray

Flow array of shape (H, W, 2).

 required
style VizStyle

Visualisation style to use.

 required
frame ndarray | None

Original BGR frame. Required for quiver and blend styles, and when blend > 0 for any other style.

 None
blend float

When > 0 and style is not quiver or blend, composites the flow visualisation over frame at this opacity.

 0.0
max_flow float | None

Normalisation cap.

 None
quiver_step int

Grid spacing for quiver arrows.

 16

Returns:

Type Description
ndarray

BGR visualised image.

motionflow.methods

motionflow.methods.base.FlowEstimator

Bases: ABC

Abstract base for all optical flow estimators.

Subclasses must implement :meth:estimate. The estimator is also callable, delegating to :meth:estimate.

estimate(prev, curr) abstractmethod

Estimate optical flow between two consecutive BGR frames.

Parameters:

Name Type Description Default
prev ndarray

Previous frame as a BGR uint8 array of shape (H, W, 3).

 required
curr ndarray

Current frame as a BGR uint8 array of shape (H, W, 3).

 required

Returns:

Type Description
ndarray

Flow array of shape (H, W, 2) with (dx, dy) displacement
ndarray

components in pixels.

motionflow.methods.classical.FarnebackFlow

Bases: FlowEstimator

Dense optical flow via Gunnar Farneback's polynomial expansion.

This is the default method — no additional dependencies required.

Parameters:

Name Type Description Default
pyr_scale float

Scale between pyramid levels. 0.5 halves each level.

 0.5
levels int

Number of pyramid levels.

 3
winsize int

Averaging window size. Larger values increase robustness to noise and fast motion but blur flow boundaries.

 15
iterations int

Iterations per pyramid level.

 3
poly_n int

Pixel neighbourhood for polynomial expansion (typically 5 or 7).

 5
poly_sigma float

Gaussian sigma for polynomial expansion smoothing.

 1.2
flags int

Extra flags passed to cv2.calcOpticalFlowFarneback.

 0

motionflow.methods.classical.TVL1Flow

Bases: FlowEstimator

Dense optical flow via the TV-L1 variational method.

Produces sharper motion boundaries than Farneback at the cost of speed.

Requires opencv-contrib-python-headless on PyPI (or plain opencv on conda-forge, which includes contrib by default).

Parameters:

Name Type Description Default
tau float

Time step of the numerical scheme.

 0.25
lambda_ float

Weight of the data term.

 0.15
theta float

Weight of the regularisation term.

 0.3
scales_number int

Number of scales in the pyramid.

 5
warps int

Number of warpings per scale.

 5
epsilon float

Stopping criterion threshold.

 0.01
iterations int

Maximum number of iterations per scale.

 300

motionflow.methods.classical.LucasKanadeFlow

Bases: FlowEstimator

Sparse optical flow via Lucas-Kanade with pyramidal refinement.

Tracks a regular grid of Shi-Tomasi corners. Untracked pixels are set to zero, producing a sparse flow field suited for quiver visualisation.

Parameters:

Name Type Description Default
grid_step int

Spacing in pixels between candidate tracking points.

 16
max_corners int

Maximum number of corners to detect per frame.

 500
quality_level float

Minimum corner quality (0–1).

 0.01
min_distance float

Minimum distance between corners in pixels.

 10.0
win_size tuple[int, int]

Search window size for LK tracker (width, height).

 (21, 21)
max_level int

Maximum pyramid level.

 3

motionflow.methods.deep.RAFTFlow

Bases: FlowEstimator

Dense optical flow via RAFT (Recurrent All-Pairs Field Transforms).

Uses the torchvision implementation with pretrained weights. Weights are downloaded automatically on first use and cached by torchvision — no manual step required.

Reference: Teed & Deng, ECCV 2020. https://arxiv.org/abs/2003.12039

Parameters:

Name Type Description Default
size str

Model variant — "large" for best accuracy or "small" for speed.

 'large'
device str

Compute device. "auto" selects CUDA > MPS > CPU.

 'auto'
iters int

Number of refinement iterations (higher = more accurate, slower).

 20

motionflow.methods.deep.SEARaftFlow

Bases: FlowEstimator

Dense optical flow via SEA-RAFT (Simple, Efficient, Accurate RAFT).

SEA-RAFT is at least 2.3x faster than prior methods at comparable accuracy. Architecture files are vendored locally; weights are downloaded from HuggingFace and cached in ~/.cache/motionflow/weights/.

First-time setup required — run once before using this method:

.. code-block:: bash

motionflow setup-vendors

If weights are not cached locally, motionflow will prompt before downloading.

Reference: Wang et al., ECCV 2024 (Best Paper candidate). https://arxiv.org/abs/2405.14793

Parameters:

Name Type Description Default
size str

Model variant — "large" or "medium".

 'large'
device str

Compute device. "auto" selects CUDA > MPS > CPU.

 'auto'

motionflow.methods.deep.NeuFlowV2Flow

Bases: FlowEstimator

Dense optical flow via NeuFlow v2.

NeuFlow v2 is optimised for efficiency, running 5–110x faster than heavyweight methods at comparable accuracy, originally targeting edge devices.

First-time setup required — run once before using this method:

.. code-block:: bash

motionflow setup-vendors

Weights are downloaded from GitHub releases and cached in ~/.cache/motionflow/weights/. If not cached, motionflow will prompt before downloading.

Reference: Zhang et al., 2024. https://arxiv.org/abs/2408.10161

Parameters:

Name Type Description Default
device str

Compute device. "auto" selects CUDA > MPS > CPU.

 'auto'

motionflow.methods.make_estimator(method, device='auto', model_size='large')

Construct a flow estimator by name.

Parameters:

Name Type Description Default
method Method | str

Flow method identifier (see :class:~motionflow.types.Method).

 required
device str

Compute device for deep methods. "auto" picks the best available (CUDA > MPS > CPU).

 'auto'
model_size ModelSize | str

Model size for RAFT and SEA-RAFT ("small"/"medium" or "large").

 'large'

Returns:

Type Description
FlowEstimator

A configured :class:FlowEstimator instance ready to call.

Raises:

Type Description
ValueError

For unknown method strings.
RuntimeError

When required dependencies are missing.