s6.vision.trajectory¶

Kinematic trajectory model for 3D tracking.

Maintains a bounded backlog of state samples and provides simple velocity and acceleration estimates, along with constant‑acceleration prediction of the next state. Timestamps are floats (seconds) from a monotonic or epoch clock; choose a consistent source for best results.

Key concepts¶

  • Frames store a location and the latest velocity estimate.

  • Velocity is computed from the last two locations using finite difference.

  • Acceleration is computed from two consecutive velocity estimates whose times are associated with segment midpoints.

  • Next state prediction uses constant‑acceleration kinematics.

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.Trajectory(*, frames: List[TrackingFrame] = None, maxlen: int = 20)

Bases: BaseModel

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.

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.