Motion API

MotionEstimator

`trackers.motion.estimator.MotionEstimator`

Estimates camera motion between consecutive video frames.

Uses sparse optical flow (Lucas-Kanade) to track feature points and computes the geometric transformation between frames. Accumulates transformations to maintain a consistent world coordinate system relative to the first frame.

Parameters:

Name	Type	Description	Default
`max_points`	`int`	Maximum number of feature points to track. More points increase accuracy but reduce speed. Default: 200.	`200`
`min_distance`	`int`	Minimum distance between detected feature points. Larger values spread points more evenly. Default: 15.	`15`
`block_size`	`int`	Size of the averaging block for corner detection. Larger values make detection less sensitive to noise. Default: 3.	`3`
`quality_level`	`float`	Quality threshold for corner detection (0-1). Higher values detect fewer, stronger corners. Default: 0.01.	`0.01`
`ransac_reproj_threshold`	`float`	RANSAC inlier threshold in pixels. Points with reprojection error below this are considered inliers. Default: 3.0.	`3.0`

Example

import cv2
from trackers.motion import MotionEstimator

estimator = MotionEstimator()

cap = cv2.VideoCapture("video.mp4")
while True:
    ret, frame = cap.read()
    if not ret:
        break

    # Get transformation for this frame
    coord_transform = estimator.update(frame)

    # Transform trajectory points from world to frame coordinates
    frame_points = coord_transform.abs_to_rel(world_trajectory)

`update(frame)`

Process a new frame and return the coordinate transformation.

The returned transformation converts between: - Absolute coordinates: Position relative to the first frame - Relative coordinates: Position in the current frame

Parameters:

Name	Type	Description	Default
`frame`	`ndarray`	Current video frame (BGR or grayscale).	required

Returns:

Type	Description
`CoordinatesTransformation`	`CoordinatesTransformation` for converting between absolute and relative coordinates. Returns `IdentityTransformation` for the first frame or if motion estimation fails.

`reset()`

Reset the estimator state.

Call this when starting a new video or when you want to reset the world coordinate system to the current frame.

MotionAwareTraceAnnotator

`trackers.annotators.trace.MotionAwareTraceAnnotator`

Draws object trajectories with camera motion compensation.

This annotator maintains a history of object positions in world coordinates and draws them as trajectories (traces) on each frame. When used with camera motion compensation, trajectories appear stable even when the camera moves.

The API is compatible with supervision annotators, using the same color resolution strategy and position anchoring.

Parameters:

Name	Type	Description	Default
`color`	`Color \| ColorPalette \| None`	The color to draw the trace. Can be a single `Color` or a `ColorPalette`. Defaults to `ColorPalette.DEFAULT`.	`None`
`position`	`Position \| None`	The anchor position on the bounding box for the trace point. Defaults to `Position.CENTER`.	`None`
`trace_length`	`int`	Maximum number of points to store per trajectory. Defaults to `30`.	`30`
`thickness`	`int`	Line thickness for drawing traces. Defaults to `2`.	`2`
`color_lookup`	`ColorLookup \| None`	Strategy for mapping colors to annotations. Options are `INDEX`, `CLASS`, `TRACK`. Defaults to `ColorLookup.TRACK`.	`None`

Example

import cv2
import supervision as sv
from inference import get_model

from trackers import (
    ByteTrackTracker,
    MotionAwareTraceAnnotator,
    MotionEstimator,
)

model = get_model("rfdetr-nano")
tracker = ByteTrackTracker()
motion_estimator = MotionEstimator()
trace_annotator = MotionAwareTraceAnnotator()

cap = cv2.VideoCapture("moving_camera.mp4")
while True:
    ret, frame = cap.read()
    if not ret:
        break

    coord_transform = motion_estimator.update(frame)

    result = model.infer(frame)[0]
    detections = sv.Detections.from_inference(result)
    detections = tracker.update(detections)

    frame = trace_annotator.annotate(
        scene=frame,
        detections=detections,
        coord_transform=coord_transform,
    )

`annotate(scene, detections, custom_color_lookup=None, coord_transform=None)`

Draw motion-compensated trace paths on the scene.

Updates internal trajectory storage with new detection positions (converted to world coordinates), then draws all trajectories transformed back to frame coordinates.

Parameters:

Name	Type	Description	Default
`scene`	`ndarray`	The image on which traces will be drawn. Modified in place.	required
`detections`	`Detections`	Detections with `tracker_id` field populated.	required
`custom_color_lookup`	`ndarray \| None`	Optional custom color lookup array to override the default color mapping strategy.	`None`
`coord_transform`	`CoordinatesTransformation \| None`	Coordinate transformation for the current frame. If None, uses identity transformation (no motion compensation).	`None`

Returns:

Type	Description
`ndarray`	The annotated image.

Raises:

Type	Description
`ValueError`	If detections don't have tracker_id field.

`reset()`

Clear all stored trajectories.

Call this when switching videos or when you want to reset trajectory history.

`clear_tracker(tracker_id)`

Clear the trajectory for a specific tracker ID.

Parameters:

Name	Type	Description	Default
`tracker_id`	`int`	The tracker ID to clear.	required

CoordinatesTransformation

`trackers.motion.transformation.CoordinatesTransformation`

Bases: ABC

Abstract base class for coordinate transformations.

Subclasses implement specific transformation types that convert points between absolute (world) and relative (frame) coordinates.

`abs_to_rel(points)` `abstractmethod`

Transform points from absolute (world) to relative (frame) coordinates.

Parameters:

Name	Type	Description	Default
`points`	`ndarray`	Array of shape `(N, 2)` containing `(x, y)` coordinates in absolute/world space.	required

Returns:

Type	Description
`ndarray`	Array of shape `(N, 2)` containing `(x, y)` coordinates
`ndarray`	in relative/frame space.

`rel_to_abs(points)` `abstractmethod`

Transform points from relative (frame) to absolute (world) coordinates.

Parameters:

Name	Type	Description	Default
`points`	`ndarray`	Array of shape `(N, 2)` containing `(x, y)` coordinates in relative/frame space.	required

Returns:

Type	Description
`ndarray`	Array of shape `(N, 2)` containing `(x, y)` coordinates
`ndarray`	in absolute/world space.

IdentityTransformation

`trackers.motion.transformation.IdentityTransformation`

Bases: CoordinatesTransformation

No-op transformation where absolute and relative coordinates are identical.

Used for the first frame (before any camera motion is detected) or when motion estimation fails.

`abs_to_rel(points)`

Return points unchanged.

`rel_to_abs(points)`

Return points unchanged.

HomographyTransformation

`trackers.motion.transformation.HomographyTransformation`

Bases: CoordinatesTransformation

Full perspective transformation using a 3x3 homography matrix.

Supports rotation, translation, scaling, and perspective changes. This is the most general transformation type, suitable for any camera motion.

The homography matrix maps points from the first frame (absolute) to the current frame (relative). The inverse matrix is computed automatically for the reverse transformation.

Parameters:

Name	Type	Description	Default
`homography_matrix`	`ndarray`	3x3 homography matrix that transforms points from absolute (first frame) coordinates to relative (current frame) coordinates.	required

Raises:

Type	Description
`ValueError`	If the matrix is not 3x3.

Example

import numpy as np

from trackers import HomographyTransformation

homography_matrix = np.array([
    [1.0, 0.0, 10.0],
    [0.0, 1.0, 20.0],
    [0.0, 0.0, 1.0],
])
transform = HomographyTransformation(homography_matrix)

world_points = np.array([[100, 200], [300, 400]])
frame_points = transform.abs_to_rel(world_points)

`abs_to_rel(points)`

Transform from absolute (world) to relative (frame) coordinates.

`rel_to_abs(points)`

Transform from relative (frame) to absolute (world) coordinates.

Motion API

MotionEstimator

trackers.motion.estimator.MotionEstimator

update(frame)

reset()

MotionAwareTraceAnnotator

trackers.annotators.trace.MotionAwareTraceAnnotator

annotate(scene, detections, custom_color_lookup=None, coord_transform=None)

reset()

clear_tracker(tracker_id)

CoordinatesTransformation

trackers.motion.transformation.CoordinatesTransformation

abs_to_rel(points) abstractmethod

rel_to_abs(points) abstractmethod

IdentityTransformation

trackers.motion.transformation.IdentityTransformation

abs_to_rel(points)

rel_to_abs(points)

HomographyTransformation

trackers.motion.transformation.HomographyTransformation

abs_to_rel(points)

rel_to_abs(points)

`trackers.motion.estimator.MotionEstimator`

`update(frame)`

`reset()`

`trackers.annotators.trace.MotionAwareTraceAnnotator`

`annotate(scene, detections, custom_color_lookup=None, coord_transform=None)`

`reset()`

`clear_tracker(tracker_id)`

`trackers.motion.transformation.CoordinatesTransformation`

`abs_to_rel(points)` `abstractmethod`

`rel_to_abs(points)` `abstractmethod`

`trackers.motion.transformation.IdentityTransformation`

`abs_to_rel(points)`

`rel_to_abs(points)`

`trackers.motion.transformation.HomographyTransformation`

`abs_to_rel(points)`

`rel_to_abs(points)`