> ## Documentation Index
> Fetch the complete documentation index at: https://docs.worlds.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Tracks & Zones

> Understanding the core data structures in Worlds detection workflows

## 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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                                |

<Note>
  Geographic motion fields (`geo`) are only populated when the camera is geo-calibrated. Otherwise they will be `null`.
</Note>

## 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:

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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.

```json theme={null}
{
  "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](/nodes/type-3-track-interaction) for use cases like safety near-miss detection, PPE compliance, and tailgating.

<Note>
  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.
</Note>

## 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**.

```json theme={null}
{
  "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](/nodes/zone-activity-check) for use cases like congestion and congregation where you care about aggregate zone activity rather than individual track behavior.