> This page is for Firmware, version 4.0 (default).
> For other versions, use one of these documentation indexes:
> - 4.0 (default): https://docs.ouster.com/sensor-docs/firmware/4.0/llms.txt
> - 3.2: https://docs.ouster.com/sensor-docs/firmware/3.2/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ouster.com/sensor-docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ouster.com/sensor-docs/_mcp/server.

# Zone Monitor

> On-sensor real-time monitoring of user-defined 3D zones without external processing.

Zone Monitor provides real-time point cloud monitoring on the sensor without external processing. It monitors user-defined 3D volumes, called zones, and reports whether each zone meets its configured trigger condition.

A zone can be defined from an STL mesh rendered by the sensor or from a pre-rendered Zone Render Binary (`.zrb`) bounds map. Zones are organized into a Zone Set Configuration, which also defines metadata such as coordinate frames, the sensor-to-body transform, power-on live zones, and trigger thresholds.

The sensor can actively monitor up to 16 **live** zones at a time, selected from an **active** set of up to 128 zones. Live zone updates are sent with small UDP packets that contain zone status and statistics. When live zones are changed through the API, updates typically appear in one or two frames, depending on whether the newly selected zones are already cached in DRAM or must be loaded from disk.

## Getting Started

Zone Monitor supports up to 128 3D zones of any shape or size, with the ability to actively monitor 16 zones simultaneously.

### Defining Zones

Each zone is defined as a 3D volume in **STL format**. These can be authored using tools like Blender or other 3D modeling software capable of exporting STL meshes.

![STL file creation in Blender](/sensor-docs/_fern-files/_img/fe57eaa0063ad4a34f20f7fb8d72a43af39e56117d0044834a575cdcecf5947f.webp)

> **Info**
>
> For programmatic zone generation via Python, see the SDK documentation.

### Deployment Workflow

1. Create one or more `.stl` files defining your zone volumes.
2. Create a `metadata.json` file describing zone configuration (thresholds, coordinate frames, etc.).
3. Package the STL files and metadata into a single `.zip` archive.
4. Upload the `.zip` file to the Zone Monitoring configuration page in the sensor web UI.
5. Click **Apply and Reinit**.
6. Navigate to the Sensor page in the Configuration tab and set the **ZM UDP Port** to any non-zero value to enable Zone Monitor data transmission.

![Zone Monitoring configuration page](/sensor-docs/_fern-files/_img/387742857db83034099f3bd0f21a64b4650507d54a4d990caef60eec4166668e.webp)

![Setting ZM UDP Port to enable Zone Monitoring](/sensor-docs/_fern-files/_img/9f60dd5f9e1adfe392d8a9243743221eac19f2776c28e3210d3b88669eb26eeb.webp)

### Zone Monitor API Commands

Once Zone Monitor is enabled and active, you can send API requests to the sensor through the Documentation page on the sensor dashboard. Available operations include:

**Get Zone Monitor Status** -- Retrieves the current state of Zone Monitor, including whether it is enabled and which zones are active.

![Testing the get zone monitor status API command](/sensor-docs/_fern-files/_img/3af805278bea293ede1d7831f55a204dfaa04a4e93cb73aa5d62b6997595022e.webp)

![Zone monitor status enabled](/sensor-docs/_fern-files/_img/4c6823ade05edfdfad80fce67b51c641cbf680f81b172b84a860a24aed300851.webp)

**Set Live IDs** -- Selects which zone IDs are actively monitored. Up to 16 zones can be live at a time. After sending the request, the sensor begins monitoring only the specified zone IDs.

![Testing the set live IDs API request](/sensor-docs/_fern-files/_img/ec30a8028b5cb21d0d220c41fdf707abf2acd52602e4ea3d5091e03900814337.webp)

![Setting selective live zones](/sensor-docs/_fern-files/_img/d55d861434df048ef81afbafb1caf65e1fee2eaad951226457e99ee28f09d702.webp)

**Set Zone Configuration** -- Configures individual zone parameters including trigger type (occupancy or vacancy), point count threshold, and frame count threshold. These parameters can only be changed on the staged Zone Configuration and then applied via the `Apply & Reinit` button.

![Testing the set zone configuration API request](/sensor-docs/_fern-files/_img/fee2902548e91a4c292c214db7333a5d0e6dd1d641b075a92c63810ba2ccbb56.webp)

![Setting zone configuration](/sensor-docs/_fern-files/_img/9d97509be5af93b049c84885490b022f94d21f3d3f6e3965974a8d08e092db4b.webp)

> **Info**
>
> For zone visualization and advanced configuration workflows, see the SDK documentation.

## Zone Set Configuration

A Zone Set Configuration consists of:

* A JSON metadata file that describes zones, thresholds, coordinate frames, defaults, and checksums.
* A collection of zone files, either source STL meshes or pre-rendered `.zrb` files.

Upload the configuration as a single ZIP archive through the web UI, or upload the individual files through the HTTP API. After upload, the sensor validates the configuration and reports errors before applying invalid inputs.

![Zone Monitor configuration upload](/sensor-docs/_fern-files/_img/146d6669562d7dcb1952189344e93b7731c5deb18cbdeb528858578b8328c4e3.webp)

### Configuration Flow

```mermaid
---
config:
  flowchart:
    curve: basis
    nodeSpacing: 24
    rankSpacing: 32
    padding: 8
    subGraphTitleMargin:
      top: 6
      bottom: 4
  themeCSS: |
    .nodeLabel,
    .edgeLabel,
    .cluster-label .nodeLabel,
    .cluster-label .nodeLabel p {
      font-size: 0.875rem !important;
    }
    .cluster-label .nodeLabel,
    .cluster-label .nodeLabel p {
      font-weight: 500 !important;
      color: #6b7280 !important;
      fill: #6b7280 !important;
    }
    .dark .cluster-label .nodeLabel,
    .dark .cluster-label .nodeLabel p {
      color: #9ca3af !important;
      fill: #9ca3af !important;
    }
---
flowchart TD
    subgraph Configuration
      upload@{ shape: rounded, label: "Upload Zone Set Config" } --> apply@{ shape: rounded, label: "Apply" }
      apply --> validation@{ shape: diamond, label: "Config<br />Validation" }
      validation -->|Invalid| upload
    end
    subgraph Initialization
      validation -->|Valid| reinit@{ shape: rounded, label: "Sensor Reinits" }
      reinit --> zoneType@{ shape: diamond, label: "STL/ZRB<br />defined?" }
      zoneType -->|ZRB-defined| zrbValid@{ shape: diamond, label: "ZRB<br />Valid?" }
      zoneType -->|STL-defined| stlRendered@{ shape: diamond, label: "STL<br />Rendered?" }
      stlRendered -->|Yes AND Current| replace@{ shape: rounded, label: "Replace ACTIVE Set" }
      stlRendered -->|No or Stale| render@{ shape: rounded, label: "Render Zones" }
    end
    zrbValid ---->|No| disabled@{ shape: rounded, label: "ZM DISABLED" }
    zrbValid -->|Yes| replace
    render -->|Success| replace
    render ---->|Failure| disabled
    replace --> enabled@{ shape: rounded, label: "ZM ENABLED with ACTIVE set" }
    classDef zmError fill:#fee2e2,stroke:#fca5a5,color:#b91c1c,stroke-width:2px
    classDef zmSuccess fill:#dcfce7,stroke:#86efac,color:#166534,stroke-width:2px
    class disabled zmError
    class enabled zmSuccess
```

1. Upload the Zone Set Configuration and apply it.
2. The sensor validates the uploaded Zone Set Configuration.
   * If validation fails, the sensor refuses to apply the configuration and reports an error.
   * If validation passes, the Zone Set is staged and the sensor reinitializes.
3. After reinitialization, the sensor checks the Zone Set's current state:
   * If zones are STL-defined:
     * ZRBs are reused when they are present and current for the sensor and its configuration.
     * Missing or outdated ZRBs are rendered from scratch.
   * If zones are ZRB-defined:
     * Contents are validated against known sensor properties and the current configuration.
4. The validated and rendered Zone Set replaces the Live Set, and Zone Monitor is enabled.

Rendering time depends on STL complexity, field-of-view coverage, and configured lidar resolution.

![Zone rendering progress](/sensor-docs/_fern-files/_img/aab11bb99bb1c878bd24879d0717a3704504690f0fb7a8b87c4d3c1d0ba5ce9d.webp)

### Configuration Summary

When a Zone Set Configuration passes sanity checks, the web UI displays the active configuration details.

![Zone Set details](/sensor-docs/_fern-files/_img/4dec4a678a618a8694a88b3ebd1fccc8459fdbd1dc3e18d98f9797a395306436.webp)

| Field                    | Description                                                                                            |
| ------------------------ | ------------------------------------------------------------------------------------------------------ |
| Power-on Live IDs        | Zones that are monitored automatically when the sensor boots with Zone Monitor enabled.                |
| Sensor to Body Transform | A 4x4 matrix that defines the sensor position relative to zones that use the `BODY` coordinate frame.  |
| Zone ID                  | Index of the zone in the active configuration.                                                         |
| Label                    | User-defined label. The sensor does not parse this value.                                              |
| Power-on Live            | Whether the zone is loaded and monitored on boot.                                                      |
| STL                      | Source STL filename, when the zone is STL-defined.                                                     |
| ZRB                      | Whether a rendered ZRB is present. For STL-defined zones, this indicates that rendering has completed. |
| Coordinate Frame         | `SENSOR` uses the sensor as origin. `BODY` applies the sensor-to-body transform before rendering.      |
| Mode                     | Zone Monitoring mode, such as occupancy (`OCC`) or vacancy (`VAC`).                                    |
| Frame Count              | Number of consecutive triggering frames required before the zone asserts.                              |
| Point Count              | Point-count threshold used to classify a frame as triggering.                                          |
| Zone Set Hash            | Sensor-calculated hash used to identify the active Zone Set in UDP update packets.                     |
| Zone Set Validity        | Whether the Zone Set is valid.                                                                         |

## ZRB File Format

The Zone Render Binary (`.zrb`) format stores sensor-rendered zone bounds. It is designed to be:

* **Traceable**: consistent with the original user inputs.
* **Auditable**: parseable into a visual output.
* **Performant**: fast for the sensor to load.

ZRB files include integrity checks that bind them to the user inputs, sensor configuration, and optical characteristics. On boot, the sensor verifies ZRB integrity using hashes.

| Rendering flow       | Validation coverage                                                                                            | Failure action                                                     |
| -------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| On-sensor rendering  | Source inputs, such as STL files and metadata, the lidar configuration, and ZRB integrity remain unchanged.    | The sensor invalidates the cache and re-renders the zone.          |
| Off-sensor rendering | The ZRB is valid for the specific sensor and lidar mode, and the file remains intact after upload and storage. | The sensor reports a boot failure that requires user intervention. |

## Enabling Zone Monitor

A valid Zone Set Configuration is required before Zone Monitor can run. Once a valid configuration has been uploaded, Zone Monitor output is enabled by configuring one or both of the following:

* A ZONE16 lidar profile, such as `RNG15_RFL8_NIR8_ZONE16` or `RNG19_RFL8_SIG16_NIR16_ZONE16`.
* A Zone Monitor UDP destination address and port for Zone Monitor Update packets.

![ZONE16 lidar profile and Zone Monitor UDP settings](/sensor-docs/_fern-files/_img/6b34f21df85b33b4621c23dad9d82ecee89395752c2f2b9c920dc5e1fdc1ed3f.webp)

After enabling the outputs and applying the configuration, the sensor reinitializes. When it reaches the `RUNNING` state, it begins monitoring the configured live zones.

> **Note**
>
> If the sensor detects a misconfiguration before rendering, it reports an upfront error. If it detects a rendering-time misconfiguration, such as a zone that does not intersect the field of view, the sensor transitions to the `HALTED` state.

## Validating Operation

After applying a Zone Set Configuration:

1. Query the rendered ZRBs and visualize them in the SDK to confirm field-of-view coverage, geometry, and orientation.
2. Record the sensor-calculated Zone Set hash.
3. If Zone Monitor UDP packets are enabled, verify that the packet hash matches the recorded Zone Set hash.
4. Verify that the expected Zone IDs are being monitored.

![Zone Monitor status](/sensor-docs/_fern-files/_img/d96d8913585bda9c5b71590055066339017afd4c6a895d746efd90e3f7ebc34d.webp)

> **Note**
>
> Zone IDs are not directly encoded in lidar pixels. ZONE16 lidar profiles use a bit flag to indicate whether a pixel is inside each monitored live slot. The user controls which Zone ID is assigned to each slot.

When changing the live set through API calls, monitor the Zone Monitor Update packets to verify that the updated Zone IDs are reflected. The UDP packets typically reflect the new live zones one or two frames after the command is received.

## Expected Sensor Behavior

When Zone Monitor is enabled:

* Zone Monitor Update UDP packets are transmitted immediately after each frame completes.
* Pre-rendered ZRB files are rejected unless they match the current sensor configuration, including serial number, internally derived transforms and constants, and resolution settings.
* ZRB files with checksums that do not match known values and file contents are rejected.
* Rendering is aborted if any defined zone does not intersect the sensor field of view. This can catch azimuth masking, incorrect extrinsics, or mismatched STL coordinate frames.
* Zone Monitor does not start without a valid Zone Set Configuration.

## Output Products

Zone Monitor provides two output products:

* **Zone Monitor Update UDP packets** report trigger status and statistics for up to 16 live zone slots.
* **ZONE16 lidar profiles** add a 16-bit per-pixel field that indicates which live zone slots contain the pixel.

### Zone Monitor Update UDP Packet

Each update packet contains 16 zone slots. User-selected live zones are sequentially packed at the beginning of the structure. Each slot reports trigger status and statistics for one live zone.

Use the packet hash and Zone IDs to verify that alerts correspond to the expected active Zone Set.

Zone metadata provides context for trigger interpretation:

* Elevated occlusion count may indicate that the sensor window is contaminated or that the zone is obstructed.
* Point count and range data can help estimate the size and proximity of triggering objects.
* Triggered frame count provides hysteresis and short-term trigger history.
* A sudden increase in invalid points for a ground-facing sensor may indicate that the sensor mount has shifted and the sensor is pointing toward the sky.

#### Packet Header

| Field         |      Bits | Description                                                              |
| ------------- | --------: | ------------------------------------------------------------------------ |
| Packet header | 96 or 256 | User-selected `STANDARD` or `FUSA` packet header. Packet type is `0x03`. |

#### Measurement Header

```mermaid
---
title: "Zone Monitor Update — Measurement Header"
---
packet-beta
+32: "Timestamp L"
+32: "Timestamp H"
+32: "Hash 0"
+32: "Hash 1"
+32: "Hash 2"
+32: "Hash 3"
+32: "Hash 4"
+32: "Hash 5"
+32: "Hash 6"
+32: "Hash 7"
```

| Word | Field                | Bits | Description                                                                                                                                               |
| ---- | -------------------- | ---: | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0-1  | Timestamp            |   64 | Unix timestamp. Deterministic with the last valid timestamp in the frame.                                                                                 |
| 2-9  | Active Zone Set hash |  256 | Cryptographic hash of all zone configs in the active set and output product hashes. Used to verify that configuration data has not changed on the sensor. |

#### Zone Data

The following data structure is repeated 16 times. Slots for live zones being monitored are populated with the zone ID and corresponding data. Fields for inactive slots are all zeros.

```mermaid
---
title: "Zone Slot (repeats × 16)"
---
packet-beta
+1: "Act."
+7: "Reserved"
+8: "Zone ID"
+8: "Errors"
+2: "Reserved"
+2: "Trig Type"
+3: "Reserved"
+1: "T.S."
+24: "Triggered Frames"
+8: "Reserved"
+20: "Zone Count"
+12: "Reserved"
+20: "Occlusion Count"
+12: "Reserved"
+20: "Invalid Count"
+12: "Reserved"
+20: "Max Count"
+12: "Reserved"
+16: "Min Range"
+16: "Reserved"
+16: "Max Range"
+16: "Reserved"
+16: "Mean Range"
+16: "Reserved"
```

| Word | Field            | Bits | Description                                                                                                                                          |
| ---- | ---------------- | ---: | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0    | Live Zone Valid  |    1 | True for live zones, regardless of trigger state. Empty slots are `0`.                                                                               |
| 0    | Reserved         |    7 | `0x0`                                                                                                                                                |
| 0    | Zone ID          |    8 | Index of the ROM config file. `255` indicates an inactive zone slot.                                                                                 |
| 0    | Error Flags      |    8 | Reserved for future use.                                                                                                                             |
| 0    | Reserved         |    2 | `0x0`                                                                                                                                                |
| 0    | Trigger Type     |    2 | `0x0`: Inactive. `0x1`: Occupancy. `0x2`: Non-occupancy.                                                                                             |
| 0    | Reserved         |    3 | `0x0`                                                                                                                                                |
| 0    | Trigger Status   |    1 | `0x0`: Zone has not met all triggering thresholds. `0x1`: Zone is triggered.                                                                         |
| 1    | Triggered Frames |   24 | Saturating count of consecutively triggered frames. Resets on trigger deassertion.                                                                   |
| 1    | Reserved         |    8 | `0x0`                                                                                                                                                |
| 2    | Zone Count       |   20 | Saturating latest count of points in the zone. Updates every frame, regardless of trigger status.                                                    |
| 2    | Reserved         |   12 | `0x0`                                                                                                                                                |
| 3    | Occlusion Count  |   20 | Saturating count of valid points below the near-bounds range.                                                                                        |
| 3    | Reserved         |   12 | `0x0`                                                                                                                                                |
| 4    | Invalid Count    |   20 | Saturating count of monitored pixels with zero range, including non-detections, invalid data from errors, skipped columns, or azimuth-masked pixels. |
| 4    | Reserved         |   12 | `0x0`                                                                                                                                                |
| 5    | Max Count        |   20 | Total pixels monitored by the zone for the lased portion of the frame. This can be affected by azimuth masking.                                      |
| 5    | Reserved         |   12 | `0x0`                                                                                                                                                |
| 6    | Min Range        |   16 | Minimum range. Range statistics use 1 mm per LSB with 8 mm effective resolution.                                                                     |
| 6    | Reserved         |   16 | `0x0`                                                                                                                                                |
| 7    | Max Range        |   16 | Maximum range. Range statistics use 1 mm per LSB with 8 mm effective resolution.                                                                     |
| 7    | Reserved         |   16 | `0x0`                                                                                                                                                |
| 8    | Mean Range       |   16 | Mean range. Range statistics use 1 mm per LSB with 8 mm effective resolution.                                                                        |
| 8    | Reserved         |   16 | `0x0`                                                                                                                                                |

#### Packet Footer

| Field            | Bits | Description       |
| ---------------- | ---: | ----------------- |
| Packet signature |  256 | Packet signature. |

### ZONE16 Lidar Profiles

ZONE16 lidar profiles add a 16-bit per-pixel field that identifies which live zone slots contain the pixel. This is useful for:

* Highlighting points in the point cloud that encroach on a defined zone.
* Filtering the point cloud to reduce downstream processing.
* Validating zone geometry against the rendered point cloud.

## Trigger Definition

Zone triggers are based on three parameters:

* **Trigger Type**: occupancy or vacancy.
* **Point Count Threshold**: point count required for a frame to be considered triggering.
* **Frame Count Threshold**: number of consecutive triggering frames required before the zone status asserts.

A point is counted as inside a zone when its range is within the boundaries defined by the ZRB lookup table. Specifically, the range must be greater than or equal to the near range and less than or equal to the far range.

For each frame, all pixels are checked against the zone's lookup table:

* An occupancy zone has a triggering frame when the point count meets or exceeds the Point Count Threshold.
* A vacancy zone has a triggering frame when the point count is below the Point Count Threshold.
* The zone status becomes triggered when the number of consecutive triggering frames meets or exceeds the Frame Count Threshold.

## Statistics

### Triggering Statistics

**Triggered Frames**: A saturating count of consecutively triggered frames. The count resets when the trigger condition deasserts.

### Point Counting Statistics

**Zone Count**: A saturating count of the total points currently inside the zone. This count updates every frame, regardless of trigger status.

**Occlusion Count**: A saturating count of valid points detected below the configured near-bounds range, indicating potential occlusion.

**Max Count**: A precomputed value representing the total number of pixels monitored by the zone. This is calculated during rendering and stored in the ZRB.

**Invalid Count**: A saturating count of monitored pixels with zero range. This includes non-detections, invalid data from errors, skipped columns, and pixels excluded by azimuth masking.

### Range Measurement Statistics

**Min Range**: Minimum detected range of points inside the zone.

**Max Range**: Maximum detected range of points inside the zone.

**Mean Range**: Average range of points inside the zone.

All range statistics are reported with an underlying resolution of 1 mm per LSB and an effective resolution of 8 mm.