s6.vision.trajectory

Trajectory helpers for tracking predicted motion over time.

Maintains bounded world-space tracking state and predicts the next frame by linearly extrapolating the latest accepted motion. TrajectoryV2 can track either a single 3D point or an arbitrary set of 3D points summarized as a spherical tracking volume.

class s6.vision.trajectory.TrackingFrame(*, location: Vector3D, velocity: Vector3D, timestamp: float)

Bases: BaseModel

Single tracking state sample.

location

3D position in world coordinates.

Type:

s6.schema.primitives.Vector3D

velocity

3D velocity estimate in world coordinates.

Type:

s6.schema.primitives.Vector3D

timestamp

Capture time in seconds (monotonic or epoch).

Type:

float

location: Vector3D

velocity: Vector3D

timestamp: float

class s6.vision.trajectory.TrackingFrameV2(*, location: Vector3D, points: List[Vector3D] = None, volume_radius: float = 0.0, displacement: Vector3D, smoothed_displacement: Vector3D, velocity: Vector3D, acceleration: Vector3D, timestamp: float)

Bases: BaseModel

Single tracking sample for linear spherical-volume prediction.

location

Center of the tracked spherical volume.

Type:

Vector3D

points

Ordered world-space points enclosed by the tracking volume.

Type:

list[Vector3D]

volume_radius

Radius of the enclosing spherical tracking volume.

Type:

float

displacement

Center delta from the previous sample.

Type:

Vector3D

smoothed_displacement

Low-pass filtered center displacement used for forward prediction.

Type:

Vector3D

velocity

Finite-difference center velocity estimate.

Type:

Vector3D

acceleration

Finite-difference center acceleration estimate.

Type:

Vector3D

timestamp

Capture time in seconds.

Type:

float

location: Vector3D

points: List[Vector3D]

volume_radius: float

displacement: Vector3D

smoothed_displacement: Vector3D

velocity: Vector3D

acceleration: Vector3D

timestamp: float

clone() → TrackingFrameV2

Return a deep copy of the sample.

translated(displacement: Vector3D, *, timestamp: float | None = None) → TrackingFrameV2

Return a copy of the sample translated by displacement.

class s6.vision.trajectory.TrackingRoiV2(*, center: Vector2D, projected_center: Vector2D, radius: float, projected_radius_x: float, projected_radius_y: float, box: BoundingBox2D, timestamp: float, source_timestamp: float, volume_radius: float)

Bases: BaseModel

Projected 2D tracking ROI derived from a tracked 3D sphere.

center: Vector2D

projected_center: Vector2D

radius: float

projected_radius_x: float

projected_radius_y: float

box: BoundingBox2D

timestamp: float

source_timestamp: float

volume_radius: float

class s6.vision.trajectory.TrajectoryDiagnosticsV2(*, displacement: Vector3D, velocity: Vector3D, acceleration: Vector3D, missed_frames: int, last_update_valid: bool, prediction_ema_active: bool, last_timestamp: float | None = None, tracked_point_count: int, volume_radius: float)

Bases: BaseModel

Current tracker diagnostics snapshot.

displacement: Vector3D

velocity: Vector3D

acceleration: Vector3D

missed_frames: int

last_update_valid: bool

prediction_ema_active: bool

last_timestamp: float | None

tracked_point_count: int

volume_radius: float

class s6.vision.trajectory.Trajectory(*, frames: List[TrackingFrame] = None, maxlen: int = 20)

Bases: BaseModel

Legacy fixed-size trajectory buffer with simple kinematics.

Holds recent TrackingFrame samples up to maxlen and provides velocity/acceleration estimates and constant‑acceleration prediction of the next state.

Notes

TrajectoryV2 is the preferred API for pipeline tracking work. This legacy helper is retained for lower-level compatibility until any remaining direct call sites are retired.

frames: List[TrackingFrame]

maxlen: int

property last_timestamp: float | None

Timestamp of the most recent sample, or None if empty.

property last_location: Vector3D | None

Location of the most recent sample, or None if empty.

add(location: Vector3D, timestamp: float) → None

Append an observation and update the velocity estimate.

Parameters:

• location (s6.schema.primitives.Vector3D) – Observed 3D location in world coordinates.

• timestamp (float) – Observation time in seconds.

Notes

The latest velocity is computed by finite difference of the last two locations. When the trajectory is empty, velocity is initialised to zero. A minimum dt of 1e-6 is enforced to avoid division by zero.

estimate_velocity() → Vector3D | None

Return the latest velocity estimate.

Returns:

Latest velocity if at least two samples exist, otherwise None.

Return type:

Vector3D | None

estimate_acceleration() → Vector3D | None

Estimate instantaneous acceleration from recent samples.

Uses two consecutive velocity estimates whose times are associated with segment midpoints: v_{n-1} between (n-2, n-1) and v_n between (n-1, n). Acceleration is the finite difference dv/dt between the velocity midpoints.

Returns:

Acceleration estimate if at least three samples exist, otherwise None.

Return type:

Vector3D | None

predict_next(dt: float | None = None, timestamp: float | None = None) → TrackingFrame | None

Predict the next state under constant acceleration.

Parameters:

• dt (float, optional) – Time step in seconds to advance from the last sample. If omitted, the last observed step duration is used.

• timestamp (float, optional) – Absolute target timestamp in seconds. When provided, dt is inferred as timestamp - last_timestamp.

Returns:

Predicted sample at the next time step, or None if no samples are available.

Return type:

TrackingFrame | None

Notes

Constant‑acceleration kinematics are applied:

• x_next = x + v*dt + 0.5*a*dt^2

• v_next = v + a*dt

A minimum step dt >= 1e-6 is enforced when computing from timestamps. When only a single sample exists, velocity is assumed zero.

class s6.vision.trajectory.TrajectoryV2(*, frames: List[TrackingFrameV2] = None, maxlen: int = 20, jitter_velocity_threshold: float | None = None, acceleration_rejection_threshold: float | None = None, displacement_ema_alpha: float = 0.4, volume_padding: float = 0.0, max_prediction_misses: int | None = 20, max_prediction_age_sec: float | None = None, missed_frames: int = 0, last_update_valid: bool = False, prediction_dt: float = 0.0, predicted: TrackingFrameV2 | None = None)

Bases: BaseModel

Fixed-size trajectory buffer with linear prediction semantics.

TrajectoryV2 tracks the center of an enclosing spherical 3D volume built from one or more world-space points. Prediction intentionally uses the last known center velocity only, which keeps ROI extrapolation stable across short solve failures. Optionally, observations whose instantaneous acceleration spike exceeds a configured threshold can be rejected and treated as held misses. While misses stay within the configured age and frame-count limits, the tracker keeps the last predicted sphere fixed instead of extrapolating it farther.

frames: List[TrackingFrameV2]

maxlen: int

jitter_velocity_threshold: float | None

acceleration_rejection_threshold: float | None

displacement_ema_alpha: float

volume_padding: float

max_prediction_misses: int | None

max_prediction_age_sec: float | None

missed_frames: int

last_update_valid: bool

prediction_dt: float

predicted: TrackingFrameV2 | None

property last_timestamp: float | None

Timestamp of the latest sample, if present.

property last_location: Vector3D | None

Center location of the latest sample, if present.

property last_points: List[Vector3D]

Ordered points from the latest sample, or an empty list.

property last_frame: TrackingFrameV2 | None

Return a copy of the most recent sample.

property is_prediction_ema_active: bool

Return whether prediction currently uses EMA-smoothed displacement.

property predicted_frame: TrackingFrameV2 | None

Return the cached next-frame prediction, if available.

property predicted_point: Vector3D | None

Return the cached next-frame predicted center, if available.

property predicted_points: List[Vector3D]

Return the cached ordered predicted points, or an empty list.

property diagnostics: TrajectoryDiagnosticsV2

Return the current tracker diagnostics snapshot.

property current_displacement: Vector3D

Return the latest accepted displacement, or zero if empty.

property current_velocity: Vector3D

Return the latest accepted velocity, or zero if empty.

property current_acceleration: Vector3D

Return the latest accepted acceleration, or zero if empty.

reset() → None

Clear accepted samples and prediction state.

update(observation: Vector3D | Sequence[Vector3D] | None, timestamp: float | None, *, valid: bool = True) → TrackingFrameV2 | None

Process one frame update and refresh next-frame prediction.

Parameters:

• observation (Vector3D | Sequence[Vector3D] | None) – Observed tracked point set, or None when the frame is invalid.

• timestamp (float | None) – Observation time in seconds.

• valid (bool, optional) – Whether this frame should be incorporated into the trajectory.

add(location: Vector3D, timestamp: float) → TrackingFrameV2

Compatibility shim for appending a valid observation.

estimate_velocity() → Vector3D | None

Return the latest velocity estimate, if present.

estimate_acceleration() → Vector3D | None

Return the latest acceleration estimate, if present.

predict_next(dt: float | None = None, timestamp: float | None = None) → TrackingFrameV2 | None

Predict the next sample using the latest velocity only.

Parameters:

• dt (float, optional) – Time delta in seconds. Ignored when timestamp is provided.

• timestamp (float, optional) – Absolute target time in seconds.

current_tracking_frame(*, extrapolate: bool = True, timestamp: float | None = None) → TrackingFrameV2 | None

Return the current tracking frame for downstream consumers.

current_tracking_roi(camera: Camera, *, extrapolate: bool = True, timestamp: float | None = None, image_shape: Tuple[int, int] | None = None) → TrackingRoiV2 | None

Return the projected 2D ROI for the current tracking frame.

latest_or_predicted_frame(timestamp: float | None = None) → TrackingFrameV2 | None

Return the predicted sample for timestamp or the latest sample.

latest_or_predicted_location(timestamp: float | None = None) → Vector3D | None

Return the predicted location for timestamp or the latest sample.