Tracks
A track represents a single detected object moving through a camera’s field of view over time. The state machine creates a track when an object is first detected and maintains it as new detections arrive.
Track state object
Every signal delivered to your workflow includes a track_state object with the full current state of the track:
{
"track_state": {
"track_id": "019bb7ea-4050-7e9b-8761-f8df773fd3e5",
"tag": "forklift",
"datasource_id": "507eaeca-cc89-4501-9e0d-0d062a8f355d",
"datasource_name": "Op 120",
"device_id": "41",
"site_id": "3",
"site_name": "Mid-Range Engine Plant CMEP",
"first_seen": "2026-01-13T15:12:52.005Z",
"last_seen": "2026-01-13T15:18:52.005Z",
"track_age": "360.000",
"detection_count": 43,
"position": { ... },
"motion": { ... },
"zones": { ... },
"interactions": [ ... ]
}
}
Key track fields
| Field | Description |
|---|
track_id | Unique identifier for this track (UUID) |
tag | Object type detected (e.g., “forklift”, “person”, “amr”) |
datasource_id | Camera/data source UUID |
datasource_name | Human-readable camera name |
site_id / site_name | The site where this camera is located |
track_start | When the track was first created in the system |
first_seen | When the state machine first saw this track. Usually the same as track_start, but can differ if the system restarted. |
last_seen | Timestamp of the most recent detection received — updates with every track_updated signal |
track_age | Duration of the track in seconds |
detection_count | Number of individual detections in this track |
Position
The track’s current position includes both pixel and geo-referenced coordinates:
{
"position": {
"pix": { "x": 902, "y": 448 },
"geo": { "lon": -85.950773951, "lat": 39.130477131 },
"polygon": {
"coordinates": [[[867, 397], [937, 397], [937, 499], [867, 499], [867, 397]]]
}
}
}
pix — pixel coordinates of the object’s center in the camera framegeo — geographic longitude/latitude (if camera is geo-calibrated)polygon — the bounding box of the detected object
Motion
Velocity and distance metrics in both pixel and geographic units:
{
"motion": {
"pix": {
"velocity": 6.52,
"distance": 438.77,
"instantaneous_velocity": 10.7,
"instantaneous_direction": 86.3,
"sample_count": 41
},
"geo": {
"velocity": 0.23,
"distance": 16.57,
"instantaneous_velocity": 1.5,
"instantaneous_direction": 86.3,
"sample_count": 41
}
}
}
| Field | Description |
|---|
velocity | Rolling average speed (px/s or m/s) |
distance | Total distance traveled |
instantaneous_velocity | Speed between the two most recent detections |
instantaneous_direction | Direction of travel in degrees (0-360) between the two most recent detections |
sample_count | Number of detection pairs used for calculation |
Geographic motion fields (geo) are only populated when the camera is geo-calibrated. Otherwise they will be null.
Zones
A zone is a defined polygon region within a camera’s field of view. Zones are configured in the Worlds platform and represent areas of interest — loading bays, walkways, restricted areas, intersections, etc.
Active zones
The zones.active object contains every zone the track currently intersects:
{
"zones": {
"active": {
"79": {
"zone_id": "79",
"zone_name": "op120-zone",
"entered_at": "2026-01-13T15:12:52.005Z",
"dwell_time": 360,
"detection_count": 43,
"intersection": {
"current_percent": 59.25,
"avg_percent": 21.17,
"sample_count": 43
},
"motion": {
"pix": { "velocity": 6.52, "distance": 438.77 },
"geo": { "velocity": 0.23, "distance": 16.57 }
}
}
}
}
}
Key zone fields
| Field | Description |
|---|
zone_id / zone_name | Zone identifier and human-readable name |
entered_at | When the track first entered this zone |
dwell_time | How long the track has been in this zone (seconds) |
detection_count | Number of detections while in this zone |
intersection.current_percent | How much of the object’s bounding box overlaps the zone right now (0–100%) |
intersection.avg_percent | Average intersection over the track’s time in this zone |
motion | Per-zone velocity and distance (may differ from overall track motion) |
Zone history
When a track exits a zone, it moves from zones.active to zones.history:
{
"zones": {
"history": [
{
"zone_id": "42",
"zone_name": "Loading Bay 1",
"entered_at": "2026-01-13T15:10:00.000Z",
"exited_at": "2026-01-13T15:12:30.000Z",
"dwell_time": 150,
"motion": { ... }
}
]
}
}
Zone sequence
The zones.sequence array records the order in which zones were entered:
{
"zones": {
"sequence": [
{ "zone_id": "42", "entered_at": "2026-01-13T15:10:00.000Z" },
{ "zone_id": "79", "entered_at": "2026-01-13T15:12:52.005Z" }
]
}
}
Interactions (batch mode only)
When the trigger is configured for batch mode, the state machine calculates interactions between tracks. For each detection, it looks at a 1-second window before and after and identifies other tracks whose bounding boxes were nearby.
{
"interactions": [
{
"track_id": "other-track-uuid",
"tag": "Vehicle",
"first_interaction_at": "2026-01-15T10:00:10.000Z",
"last_interaction_at": "2026-01-15T10:00:25.000Z",
"total_duration": 15.0,
"proximity": {
"interaction_count": 20,
"pix": { "min": 15.0, "avg": 30.5, "min_at": "2026-01-15T10:00:15.000Z" },
"geo": { "min": 0.5, "avg": 1.2, "min_at": "2026-01-15T10:00:15.000Z" }
},
"overlap": {
"overlap_count": 5,
"max_overlap_percent": 0.35,
"max_overlap_at": "2026-01-15T10:00:20.000Z",
"total_overlap_duration": 3.0
}
}
]
}
| Field | Description |
|---|
proximity.pix.min | Closest pixel distance between bounding box edges |
proximity.geo.min | Closest geographic distance in meters |
overlap.max_overlap_percent | Maximum bounding box overlap as a percentage |
overlap.total_overlap_duration | Total seconds the bounding boxes overlapped |
total_duration | Total time the two tracks were interacting |
In streaming mode, the interactions array is always empty. Interaction calculation requires looking at all detections in a time window, which is only possible after the track has expired in batch processing.
Zone state
In addition to track-level zone data, the state machine also produces zone state — an aggregate view of what’s happening in a specific zone. This is available when the trigger is configured with signal type Zone State.
{
"zone_state": {
"zone_id": "92",
"zone_name": "Aisle-Zone-West",
"datasource_id": "2ba0f384-...",
"datasource_name": "Shortblock_LB1 - West View",
"active_tracks": {
"track-uuid-1": {
"tag": "forklift",
"entered_at": "2026-02-19T18:35:59.803Z",
"dwell_time": 25.0,
"detection_count": 7,
"intersection": { "current_percent": 45.3, "avg_percent": 82.3 },
"motion": { "pix": { "velocity": 40.8, "instantaneous_velocity": 10.7 } }
}
},
"track_count": 4,
"updated_at": "2026-02-19T18:36:40.464Z",
"trigger_track_id": "track-uuid-2",
"trigger_tag": "tugger"
}
}
| Field | Description |
|---|
active_tracks | Map of all tracks currently in the zone, with per-track metrics |
track_count | Total number of active tracks in the zone |
trigger_track_id | The track that caused this zone update |
trigger_tag | Object type of the trigger track |
