Tracks & Zones

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 frame
geo — 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": { ... }
      }
    ]
  }
}

History is useful for checks like zone sequence validation (did the track visit zones in a specific order?) and historical velocity analysis.

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" }
    ]
  }
}

This is used by the zone sequence check to detect wrong-way travel or validate that objects follow expected paths.

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

Interactions are used by Type III checks for use cases like safety near-miss detection, PPE compliance, and tailgating.

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

Zone state is used with the Zone Activity Check for use cases like congestion and congregation where you care about aggregate zone activity rather than individual track behavior.

Getting Started

Concepts

Workflow Guides

Advanced

Tracks

Track state object

Key track fields

Position

Motion

Zones

Active zones

Key zone fields

Zone history

Zone sequence

Interactions (batch mode only)

Zone state

​Tracks

​Track state object

​Key track fields

​Position

​Motion

​Zones

​Active zones

​Key zone fields

​Zone history

​Zone sequence

​Interactions (batch mode only)

​Zone state

Tracks

Track state object

Key track fields

Position

Motion

Zones

Active zones

Key zone fields

Zone history

Zone sequence

Interactions (batch mode only)

Zone state