swarmsort.data_classes module

SwarmSort Data Classes

This module defines the core data structures used throughout SwarmSort for representing detections and tracked objects.

Classes:: Detection: Input detection with position, confidence, and optional features TrackedObject: Output tracked object with full tracking state information

Note

PendingDetection is defined in track_state.py to keep internal tracking state management consolidated in one place.

class swarmsort.data_classes.Detection(position, confidence, bbox=None, embedding=None, class_id=None, id=None)[source]

Bases: object

Input detection representing a single object observation.

A Detection represents a single object detection from a computer vision model, containing its position, confidence score, and optional features like bounding box and embedding vector for appearance-based matching.

position

2D position [x, y] in world/image coordinates

Type:: np.ndarray

confidence

Detection confidence score, typically in range [0, 1]

Type:: float

bbox

Bounding box as [x1, y1, x2, y2]

Type:: np.ndarray, optional

embedding

Feature vector for appearance matching

Type:: np.ndarray, optional

class_id

Object class identifier

Type:: int, optional

id

Unique detection identifier

Type:: str, optional

Example

>>> import numpy as np
>>> detection = Detection(
...     position=np.array([100.0, 150.0], dtype=np.float32),
...     confidence=0.95,
...     bbox=np.array([90, 140, 110, 160], dtype=np.float32)
... )

bbox: ndarray | None = None

class_id: int | None = None

confidence: float

embedding: ndarray | None = None

id: str | None = None

position: ndarray

class swarmsort.data_classes.TrackedObject(id, position, velocity, confidence, age, hits, time_since_update, state, bbox=None, class_id=None, predicted_position=None, embedding_score=None)[source]

Bases: object

Output tracked object representing a track’s current state.

A TrackedObject represents the current state of a tracked object, including its position, motion, confidence, and tracking statistics. This is the main output type returned by SwarmSortTracker.update().

id

Unique track identifier, assigned when track is created

Type:: int

position

Current 2D position [x, y] estimate

Type:: np.ndarray

velocity

Current velocity [vx, vy] estimate from Kalman filter

Type:: np.ndarray

confidence

Most recent detection confidence associated with this track

Type:: float

age

Number of frames since track was created

Type:: int

hits

Total number of successful detection associations

Type:: int

time_since_update

Frames since last successful detection association

Type:: int

state

Track state (0: Tentative, 1: Confirmed, 2: Deleted)

Type:: int

bbox

Most recent bounding box [x1, y1, x2, y2]

Type:: np.ndarray, optional

class_id

Object class identifier

Type:: int, optional

Example

>>> # TrackedObject is typically created by the tracker
>>> tracked_objects = tracker.update(detections)
>>> for obj in tracked_objects:
...     print(f"Track {obj.id} at position {obj.position}")
...     print(f"  Velocity: {obj.velocity}")
...     print(f"  Age: {obj.age}, Hits: {obj.hits}")

age: int

bbox: ndarray | None = None

class_id: int | None = None

confidence: float

embedding_score: float | None = None

hits: int

id: int

position: ndarray

predicted_position: ndarray | None = None

state: int

time_since_update: int

velocity: ndarray