Connecting to Output

Terminology

The following section describes the Ouster Gemini Detect JSON data streams exposed via MQTT Publishers and TCP Relay Servers (see JSON Data Streams w/Down-sampling, Batching & Field Mapping). These definitions represent a single message, but since batching is inherent to the MQTT Publishers and TCP Servers, messges are wrapped in a JSON array with the data stream name as the field name. This wrapping is enabled by default, but can be overridden by setting “return_as_array” = false for the specific MQTT Publisher/TCP Relay Server configuration. Please note that a malformed JSON message will be received if “return_as_array” is disabled and batching returns more than one message.

Available JSON Streams

object_list
occupations
clusters
diagnostics
aggregation_realtime
aggregation_timeseries

Introduction of Terms

lidar frame: The point cloud data for one revolution for a single lidar sensor.
frame: The output from multiple unique lidar frames (i.e., one lidar frame from Lidar A, one lidar frame from Lidar B). The perception system calculates the object list and occupations on a single frame.
object: A moving entity in the scene which Gemini Detect is tracking over time. An object consists of a position, orientation, velocity, dimensions, and classification but also contains historic data such as how long we’ve been tracking it or what the initial position was when we saw it. An object is associated over time by it’s object id or UUID. More details about what’s contained in an object is listed in Object List Data.
event zone: A user-defined area where object information is desired.
occupation: An object within an event zone at a specific instant in time.
diagnostics: Time-based snapshots of the internal state of perception.
alerts: Error conditions where Gemini Detect is operating outside the desired state.
aggregation: Real-time and time-based aggregates of zone occupations by object classification.

Object List Data

The object list data contains information about all the moving objects in the scene.

Example Batching of one or more Frame(s) in a single Message

{
  "object_list": [
    {...},
    {...},
    {...}
  ]
}

Example Frame

{
  "frame_count": 226599,
  "timestamp": 1663175920089867
  "objects": [
    {
      "classification": "PERSON",
      "classification_confidence": 0,
      "classification_ts": 1663175901389312,
      "creation_ts": 1663175901389312,
      "dimensions": {
        "height": 0.6693140268325806,
        "length": 0.44045835733413696,
        "width": 0.24217760562896729
      },
      "distance_to_primary_sensor": 1.8241156339645386,
      "frame_count": 188,
      "heading": 17.792495727539062,
      "id": 1094,
      "initial_position": {
        "x": 0.866864025592804,
        "y": -1.3293535709381104,
        "z": 1.1521248817443848
      },
      "num_failed_returns": 0,
      "num_points": 1052,
      "num_points_from_primary_sensor": 706,
      "orientation": {
        "qw": 0.9879699945449829,
        "qx": 0,
        "qy": 0,
        "qz": 0.15464559197425842
      },
      "position": {
        "x": 0.9670451879501343,
        "y": -1.5673401355743408,
        "z": 1.0692270994186401
      },
      "position_uncertainty": {
        "x": 0.00872983346207417,
        "y": 0.00872983346207417,
        "z": 0.03328978381826185
      },
      "primary_sensor": "992251000353",
      "sub_classification": "",
      "sub_classification_confidence": 0,
      "sub_classification_ts": 0,
      "update_ts": 1663175920076580,
      "uuid": "74b4e42e-1989-40d0-91d6-ae498b173001",
      "velocity": {
        "x": -0.03508763682949244,
        "y": 0.01674633024355329,
        "z": 0.029468615562023993
      },
      "velocity_uncertainty": {
        "x": 0.7745966692414834,
        "y": 0.7745966692414834,
        "z": 0.8143665760550121
      }
    },
    {
      "classification": "UNKNOWN",
      "classification_confidence": 0,
      "creation_ts": 1663175902884161,
      "dimensions": {
        "height": 0.5432571172714233,
        "length": 0.48804545402526855,
        "width": 0.20569449663162231
      },
      "distance_to_primary_sensor": 1.8241156339645386,
      "frame_count": 171,
      "heading": -89.16230010986328,
      "id": 1096,
      "initial_position": {
        "x": 0.9158645868301392,
        "y": -1.8394945859909058,
        "z": 0.7948745489120483
      },
      "num_points": 539,
      "num_points_from_primary_sensor": 706,
      "orientation": {
        "qw": 0.7122570276260376,
        "qx": 0,
        "qy": 0,
        "qz": -0.7019187808036804
      },
      "position": {
        "x": 0.7764403223991394,
        "y": -1.7604234218597412,
        "z": 0.9274996519088745
      },
      "position_uncertainty": {
        "x": 0.00872983346207417,
        "y": 0.00872983346207417,
        "z": 0.03328978381826185
      },
      "primary_sensor": "992251000353",
      "update_ts": 1663175920076580,
      "uuid": "b3caf8eb-8e23-47fe-a839-999f354ae4a0",
      "velocity": {
        "x": -0.10920844900324483,
        "y": 0.31853616628659553,
        "z": 0.10758132742665225
      },
      "velocity_uncertainty": {
        "x": 0.7745966692414834,
        "y": 0.7745966692414834,
        "z": 0.8143665760550121
      }
    }
  ]
}

JSON Field Definitions

Object List Data Description
Field	Format	Definition
frame_count	int	Number of frames since perception started outputting data. This count should always be sequential.
timestamp	int	Timestamp of when the last point cloud arrived which contributed to the object list. Units in microseconds since Jan. 1, 1970.
objects	array	Array of object (s) visible to perception for the current frame

object

An object visible to perception for the current frame.

Object List Data Description
Field	Format	Definition
id	int	Unique number identifying object in current running instance of perception. If perception restarts, this count will reset.
uuid	string	Unique UUID for objects over all running instances. If perception restarts, objects in the new running instance will have unique UUID’s relative to all other running instances.
primary_sensor	string	Serial number of the primary lidar sensor with the most points on object.
distance_to_primary_sensor	float	Distance in meters from the primary lidar sensor.
num_points_from_primary_sensor	int	Number of points on object from the primary lidar sensor.
num_points	int	Number of points belonging to the object.
num_failed_returns	int	Number of failed returns in the point cloud for the object.
classification	string	Classification of the object 1 of 6 classes: PERSON, BICYCLE, VEHICLE, LARGEVEHICLE, UNKNOWN, or PROSPECT.
classification_confidence	float	Number between 0 and 1 representing the system’s confidence in the assigned classification. 0 represents no confidence. 1 represents fully confident.
classification_ts	int	Timestamp of the current object classification. Units in microseconds since Jan. 1, 1970.
sub_classification	string	Sub-Classification of the object (only available from DL models). 1 of 6 classes: pedestrian, car, truck, bicycle, bus or trailer.
sub_classification_confidence	float	Number between 0 and 1 representing the system’s confidence in the assigned sub-classification. 0 represents no confidence. 1 represents fully confident.
sub_classification_ts	int	Timestamp of the current object sub-classification. Units in microseconds since Jan. 1, 1970.
initial_position	vector	Initial XYZ location of the object in the first frame it was visible in the field of view of the lidars. This position is either in respect to the world reference frame (measured in meters), or are geo-coordinates when a World has been defined and “convert_to_geo_coordinates” = true.
position	vector	Current XYZ location of the object in the world reference frame (measured in meters), or the geo-coordinates when a World has been defined and “convert_to_geo_coordinates” = true.
position_uncertainty	vector	Estimated variance of the position measurement. Units in meters^2.
velocity	vector	Current rate of change in the XYZ position of the object. Velocity is in the world reference frame. Units are in m/s.
velocity_uncertainty	vector	Estimated variance of the velocity measurement. Units in (m/s)^2.
orientation	orientation	Quaternion representing the orientation of the object with respect to the world reference frame.
heading	float	Positive rotation about the z-axis (right-hand rule), or the degrees from True North when a World has been defined and “convert_to_geo_coordinates” = true. Measured off of the positive x-axis.
dimension	dimensions	Length, width, height of the bounding box enclosing all points on the object. Length is the extents along the x-axis, width the extents along the y-axis, height along the z-axis. Axis referenced are the axis of the object with x pointing in the direction of motion, y pointing perpendicular to the left, and z pointing up (right-hand rule).
frame_count	int	Number of frames an object has been visible for. This number and the creation_ts number both represent the duration the object has been in the sytem’s field of view.
creation_ts	int	Timestamp when the object was first visible in the system’s field of view. This point in time will be before the object was tracked and classified. This number and frame_count both represent the duration the object has been in the sytem’s field of view. Units in microseconds since Jan. 1, 1970.
update_ts	int	Timestamp the object was last updated. For objects the system has measured in the current frame, this timestamp will be the same as the timestamp at the root level. For objects the system has not measured in the current frame, this timestamp will stay at the timestamp when the object was last measured and lag behind the timestamp at the root level. An object will be considered measured when the lidars have captured a minimum number of points on the target. Units in microseconds since Jan. 1, 1970.

vector

The initial_position, position, position_uncertainty, velocity, velocity_uncertainty values are all objects with XYZ points and formated as follows.

Vector Description
Field	Format	Definition
x	float	Value relative to the x-axis, or the longitude when a World has been defined and “convert_to_geo_coordinates” = true (geo-coordinates apply to position and position_uncertainty ONLY).
y	float	Value relative to the y-axis, or the latitude when a World has been defined and “convert_to_geo_coordinates” = true (geo-coordinates apply to position and position_uncertainty ONLY).
z	float	Value relative to the z-axis

orientation

The orientation is in unit quaternion and formated as follows.

Orientation Description
Field	Format	Definition
qw	float	Angle of rotation around the axis.
qx	float	Quaternion X Value
qy	float	Quaternion Y Value
qz	float	Quaternion Z Value

dimensions

The dimensions are in unit meters and formatted as follows.

Dimensions Description
Field	Format	Definition
length	float	Object length along the x-axis in meters
width	float	Object width along the y-axis in meters
height	float	Object height along the z-axis in meters

Occupation Data

The occupation data contains information about all objects which intersect an Event Zone.

Example Batching of one or more Frame(s) in a single Message

{
  "occupations": [
    {...},
    {...},
    {...}
  ]
}

Example Frame

{
  "timestamp": 1663176519190541,
  "occupations": [
    {
      "id": 1658947733821,
      "name": "Desk",
      "num_objects": 1,
      "num_points": 100,
      "objects": [
        {
          "classification": "PERSON",
          "classification_confidence": 0,
          "classification_ts": 1663175901389312,
          "creation_ts": 1663175901389312,
          "dimensions": {
            "height": 1.0555479526519775,
            "length": 0.713068962097168,
            "width": 0.6797903776168823
          },
          "distance_to_primary_sensor": 1.8241156339645386,
          "frame_count": 6169,
          "heading": 239.63951110839844,
          "id": 1094,
          "initial_position": {
            "x": 0.866864025592804,
            "y": -1.3293535709381104,
            "z": 1.1521248817443848
          },
          "num_failed_returns": 0,
          "num_points": 2353,
          "num_points_from_primary_sensor": 706,
          "orientation": {
            "qw": -0.4972730875015259,
            "qx": 0,
            "qy": 0,
            "qz": 0.8675940632820129
          },
          "position": {
            "x": 1.423563003540039,
            "y": -1.1258434057235718,
            "z": 1.4065864086151123
          },
          "position_uncertainty": {
            "x": 0.0087298334620742,
            "y": 0.0087298334620742,
            "z": 0.03328978381826278
          },
          "primary_sensor": "992251000353",
          "sub_classification": "",
          "sub_classification_confidence": 0,
          "sub_classification_ts": 0,
          "update_ts": 1663176519190541,
          "uuid": "74b4e42e-1989-40d0-91d6-ae498b173001",
          "velocity": {
            "x": -0.07373628162375315,
            "y": 0.17994346251739213,
            "z": 0.05531235350852935
          },
          "velocity_uncertainty": {
            "x": 0.7745966692415875,
            "y": 0.7745966692415875,
            "z": 0.8143665760552492
          }
        }
      ]
    },
    {
      "id": 1659039089180,
      "name": "Coffee Station",
      "num_objects": 0,
      "num_points": 0,
      "objects": []
    },
    {
      "id": 1659467677889,
      "name": "Office",
      "num_objects": 2,
      "num_points": -1,
      "objects": [
        {
          "classification": "PERSON",
          "classification_confidence": 0,
          "creation_ts": 1663175901389312,
          "dimensions": {
            "height": 1.0555479526519775,
            "length": 0.713068962097168,
            "width": 0.6797903776168823
          },
          "distance_to_primary_sensor": 1.8241156339645386,
          "frame_count": 6169,
          "heading": 239.63951110839844,
          "id": 1094,
          "initial_position": {
            "x": 0.866864025592804,
            "y": -1.3293535709381104,
            "z": 1.1521248817443848
          },
          "num_points": 2353,
          "num_points_from_primary_sensor": 706,
          "orientation": {
            "qw": -0.4972730875015259,
            "qx": 0,
            "qy": 0,
            "qz": 0.8675940632820129
          },
          "position": {
            "x": 1.423563003540039,
            "y": -1.1258434057235718,
            "z": 1.4065864086151123
          },
          "position_uncertainty": {
            "x": 0.0087298334620742,
            "y": 0.0087298334620742,
            "z": 0.03328978381826278
          },
          "primary_sensor": "992251000353",
          "update_ts": 1663176519190541,
          "uuid": "74b4e42e-1989-40d0-91d6-ae498b173001",
          "velocity": {
            "x": -0.07373628162375315,
            "y": 0.17994346251739213,
            "z": 0.05531235350852935
          },
          "velocity_uncertainty": {
            "x": 0.7745966692415875,
            "y": 0.7745966692415875,
            "z": 0.8143665760552492
          }
        },
        {
          "classification": "UNKNOWN",
          "classification_confidence": 0,
          "creation_ts": 1663176266987224,
          "dimensions": {
            "height": 0.4143267869949341,
            "length": 0.47537946701049805,
            "width": 0.21244263648986816
          },
          "distance_to_primary_sensor": 1.8241156339645386,
          "frame_count": 2515,
          "heading": -27.986698150634766,
          "id": 1097,
          "initial_position": {
            "x": 1.0187989473342896,
            "y": -2.223712205886841,
            "z": 0.8246035575866699
          },
          "num_points": 427,
          "num_points_from_primary_sensor": 706,
          "orientation": {
            "qw": 0.9703238010406494,
            "qx": 0,
            "qy": 0,
            "qz": -0.24180926382541656
          },
          "position": {
            "x": 0.9871895909309387,
            "y": -2.073474645614624,
            "z": 0.806154191493988
          },
          "position_uncertainty": {
            "x": 0.0087298334620742,
            "y": 0.0087298334620742,
            "z": 0.03328978381826278
          },
          "primary_sensor": "992251000353",
          "update_ts": 1663176519186659,
          "uuid": "9d0c0960-41db-4aec-91f0-9ab961435418",
          "velocity": {
            "x": 0.023203769245295436,
            "y": 0.08712463675627366,
            "z": 0.0022661226717978836
          },
          "velocity_uncertainty": {
            "x": 0.7745966692415875,
            "y": 0.7745966692415875,
            "z": 0.8143665760552492
          }
        }
      ]
    }
  ],
}

JSON Field Definitions

Occupations Data Description
Field	Format	Definition
timestamp	int	Timestamp of when the last point cloud arrived which contributed to the object list. Units in microseconds since Jan. 1, 1970.
occupations	array	Array of Event Zones occupations (s) for the current frame

occupations

Occupations for a given Event Zone for the current frame.

Occupations Data Description
Field	Format	Definition
id	int	Event Zone unique identifier
name	string	Event Zone human-readable name
num_objects	int	Number of objects occupying the Event Zone for the current frame
num_points	int	Number of points occupying the Event Zone for the current frame. A value of -1 indicates point count is disabled for the given Event Zone.
objects	array	Object List Data for the objects occupying the Event Zone for the current frame

Clusters

Clusters contains summary information about each moving cluster in the scene.

Example Batching of one or more Frame(s) in a single Message

{
  "clusters": [
    {...},
    {...},
    {...}
  ]
}

Example Frame

{
  "timestamp": 1711227039549025,
  "clusters": [
    {
      "primary_sensor": "992144000616",
      "distance_to_primary_sensor": 4.379119873046875,
      "num_points_from_primary_sensor": 23,
      "num_points": 30,
      "position": {
        "x": 0.9018294811248779,
        "y": -4.280246257781982,
        "z": 1.217104196548462
        },
      "orientation": {
        "qw": 0.9920055270195007,
        "qx": 0,
        "qy": 0,
        "qz": 0.1261943131685257
      },
      "heading": 14.499475752803729,
      "dimensions": {
        "length": 0.3176957368850708,
        "width": 0.18461894989013672,
        "height": 0.3064082860946655
      },
      "creation_ts": 1711227039549025
    },
    {
      "primary_sensor": "992144000616",
      "distance_to_primary_sensor": 1.542967677116394,
      "num_points_from_primary_sensor": 377,
      "num_points": 429,
      "position": {
        "x": 0.8063753843307495,
        "y": -1.3227678537368774,
        "z": 1.1185648441314697
      },
      "orientation": {
        "qw": 0.9989724159240723,
        "qx": 0,
        "qy": 0,
        "qz": -0.04532269760966301
      },
      "heading": -5.195334386220284,
      "dimensions": {
        "length": 0.40606147050857544,
        "width": 0.1962677240371704,
        "height": 0.5081561803817749
      },
      "creation_ts": 1711227039549025
    }
  ]
}

JSON Field Definitions

Clusters Description
Field	Format	Definition
timestamp	int	Timestamp of when the last point cloud arrived which contributed to the cluster list. Units in microseconds since Jan. 1, 1970.
clusters	array	Array of cluster (s) visible to perception for the current frame

cluster

A cluster visible to perception for the current frame.

Cluster Data Description
Field	Format	Definition
primary_sensor	string	Serial number of the primary lidar sensor with the most points on cluster.
distance_to_primary_sensor	float	Distance in meters from the primary lidar sensor.
num_points_from_primary_sensor	int	Number of points on cluster from the primary lidar sensor.
num_points	int	Number of points belonging to the cluster.
position	vector	Current XYZ location of the cluster in the world reference frame, or the geo-coordinates when a World has been defined and “convert_to_geo_coordinates” = true.
orientation	orientation	Quaternion representing the orientation of the cluster with respect to the world reference frame.
heading	float	Positive rotation about the z-axis (right-hand rule), or the degrees from True North when a World has been defined and “convert_to_geo_coordinates” = true. Measured off of the positive x-axis.
dimension	dimensions	Length, width, height of the bounding box enclosing all points on the cluster. Length is the extents along the x-axis, width the extents along the y-axis, height along the z-axis. Axis referenced are the axis of the cluster with x pointing in the direction of motion, y pointing perpendicular to the left, and z pointing up (right-hand rule).
creation_ts	int	Timestamp when the object was first visible in the system’s field of view. This point in time will be before the object was tracked and classified. This number and frame_count both represent the duration the object has been in the sytem’s field of view. Units in microseconds since Jan. 1, 1970.

Processed Output

Diagnostics Attributes

Compute device, lidar sensor and software Attributes will be published to the Gemini Portal when any value changes. The current attribute and telemetry diagnostics values can also be requested at any time via the Lidar Hub’s /diagnostics REST API resource.

Example Batching of one or more Frame(s) in a single Message

{
  "diagnostics": [
    {...},
    {...},
    {...}
  ]
}

Example Frame

{
  "hardware_id": "*1234567890",
  "customer_id": "73bbb8a6-ffd7-4898-a8dd-8003441ec724",
  "label": "Site A",
  "latitude": 37.76466741329934,
  "longitude": -122.4136976526134,
  "azimuth": 57.6,
  "compute": {
    "host_name": "CATALYST-PRO-01",
    "mac_address": "FF:FF:FF:FF:FF:FF",
    "architecture": "x86_64",
    "is_arm": false,
    "has_gpu": false,
    "os_version": "",
    "last_upgrade": "",
    "last_upgrade_timestamp": 0,
    "total_cpu_cores": 16,
    "total_memory": 33354051584,
    "total_disk_space": 982141468672,
    "boot_timestamp": 1702226939,
    "health": "ONLINE"
  },
  "lidars": [
    {
      "model": "OS1",
      "serial_number": "992144000616",
      "hostname": "os-992144000616.local.",
      "ip_address": 255.255.255.255,
      "node_id": "",
      "beam_configuration": "128",
      "firmware": {
        "version": "v2.3.1",
        "image": "ousteros-image-prod-aries-v2.5.3+20240111055903"
      },
      "position": {
        "x": -122.4136976526134,
        "y": 37.76466741329934,
        "z": 3.42
      },
      "connection_status": "connected",
      "status": "RUNNING",
      "is_ml": false,
      "host_health": "ONLINE",
      "health": "ONLINE"
    }
  ],
  "nodes": [
    {
      "hostname": "NODE-A,
      "id": "ABCD1234EFGH5678",
      "license": "none",
      "position": {
        "x": 12.37,
        "y": -8.97,
        "z": 0.01
      },
      "perception_client": "connected",
      "port": 1234,
      "raw_frame_client": "connected",
      "rest_client": "connected",
      "host_health": "ONLINE",
      "health": "ONLINE"
    }
  ],
  "solutions_agent": {
    "software_version": "2.2.0",
    "package_version": "2.2.0-1,
    "is_running": true,
    "is_software_repository_available": true,
    "software_repository_version": ""
  },
  "perception_server": {
    "software_version": "2.2.0",
    "settings_version": 5,
    "is_ml": false,
    "is_aggreagtor": false,
    "is_running": true,
    "is_paused": false,
    "license": "none",
    "num_inclusion_zones": 0,
    "num_exclusion_zones": 0,
    "configuration": {
    },
    "extrinsics": {
    }
  },
  "event_zone_server": {
    "software_version": "2.2.0",
    "settings_version": "1.0.0",
    "is_running": true,
    "license": "none",
    "num_event_zones": 0,
    "configuration": {
    },
    "event_zones": {
    }
  },
  "lidar_hub": {
    "software_version": "2.2.0",
    "settings_version": "2.2.0.1",
    "license": "none",
    "is_running": true,
    "diagnostics_enabled": true,
    "aggregation_enabled": false,
    "mqtt_publishers": 0,
    "tcp_relay_servers": 2,
    "datarecorders": [
    ],
    "configuration": {
    },
    "is_scout": false
  },
  "health": "ONLINE",
  "is_scout": false,
  "diagnostics_version": 2.2.0
}

JSON Field Definitions

JSON Field Definitions
Field	Format	Description
`hardware_id`	`string`	identifying ID of Edge Device (MAC Address or Agent Locking Code)
`customer_id`	`string`	Your Gemini Portal Customer ID (provided by Ouster)
`label`	`string`	User-defined label displayed in the Gemini Portal and used as an MQTT Publisher configuration variable
`latitude`	`float`	Lidar Hub world latitude
`longitude`	`float`	Lidar Hub world longitude
`azimuth`	`float`	Lidar Hub world azimuth
`compute`	`object`	Compute Device details
`compute.host_name`	`string`	Host name of the compute device
`compute.mac_address`	`string`	MAC Address of the compute device
`compute.architecture`	`string`	Compute device CPU architecture (x86_64, aarch64)
`compute.is_arm`	`bool`	Indicator if the compute device CPU architecture is identified as ARM
`compute.has_gpu`	`bool`	Indicator if at least one compute device GPU has been detected
`compute.os_version	`string`	Operating system of the compute device
`compute.last_upgrade`	`string`	Description of last OS upgrade performed on the compute device
`compute.last_upgrade_timestamp`	`int`	Timestamp of last OS upgrade performed on the compute device (microseconds since Jan. 1, 1970)
`compute.total_cpu_cores`	`int`	Number of CPU cores on the compute device
`compute.total_memory`	`int`	Total memory installed in compute device (bytes)
`compute.total_disk_space`	`int`	Total storage installed in compute device (bytes)
`compute.boot_timestamp`	`int`	System boot time (seconds since Jan. 1, 1970)
`compute.health`	`int`	Determined health of the compute device (ONLINE / WARNING / OFFLINE)
`lidars`	`array`	Array of active Lidar sensors
`lidars[].model`	`string`	Lidar sensor model
`lidars[].serial_number`	`string`	Lidar sensor serial number
`lidars[].hostname`	`string`	Lidar sensor host name
`lidars[].ip_address`	`string`	Lidar sensor IP Address
`lidars[].beam_configuration`	`string`	Lidar sensor beam configuration as reported by the firmware
`lidars[].firmware`	`object`	Lidar Firmware details
`lidars[].firmware.version`	`string`	Lidar sensor firmware version as reported by the firmware
`lidars[].firmware.image`	`string`	Lidar sensor firmware image as reported by the firmware
`lidars[].position`	`object`	Lidar sensor position (geo-coordinates if Lidar Hub world is set, otherwise cartesian coordinates in the world reference frame)
`lidars[].position.x`	`float`	x cartesian coordinates or longitude
`lidars[].position.y`	`float`	x cartesian coordinates or latitude
`lidars[].position.z`	`float`	height in meters
`lidars[].connection_status`	`string`	Lidar sensor connection status
`lidars[].status`	`string`	Lidar sensor status as reported by the firmware
`lidars[].is_ml`	`string`	Indicator if sensor is being used for ML Perception
`lidars[].host_health`	`string`	Health of the lidar sensor’s host
`lidars[].health`	`string`	Determined health of the lidar sensor (ONLINE / WARNING / OFFLINE)
`nodes`	`array`	Array of active Leaf Nodes for Aggregator when Distributed Perception in use
`nodes[].host_name`	`string`	Host name of the Leaf Node compute device
`nodes[].id`	`string`	Leaf Node ID when sensor is running as part a Distributed Perception Aggregator
`nodes[].license`	`string`	Leaf Node license details
`nodes[].position`	`object`	Leaf Node position (geo-coordinates if Lidar Hub world is set, otherwise cartesian coordinates in the world reference frame)
`nodes[].position.x`	`float`	x cartesian coordinates or longitude
`nodes[].position.y`	`float`	x cartesian coordinates or latitude
`nodes[].position.z`	`float`	height in meters
`nodes[].perception_client`	`string`	Indicator of connectivity w/Perception Aggregator
`nodes[].port`	`string`	Perception Aggregator listening port
`nodes[].raw_frame_client`	`string`	Perception Aggregator’s web socket connection status to the Leaf Node
`nodes[].rest_client`	`string`	Perception Aggregator’s REST API connection status to the Leaf Node
`nodes[].host_health`	`string`	Health of the Perception Aggregator
`nodes[].health`	`string`	Determined health of the Leaf Node (ONLINE / WARNING / OFFLINE)
`solutions_agent	`object`	Ouster Solutions Agent details
`solutions_agent.software_version`	`string`	Ouster Solutions Agent software version
`solutions_agent.package_version`	`string`	Ouster Solutions Agent package version (DEB/RPM/etc.)
`solutions_agent.is_running`	`bool`	Indication if the Ouster Solutions Agent is running
`solutions_agent.is_software_repository_available`	`bool`	Indicator if registry.ouster.com is available
`solutions_agent.software_repository_version`	`string`	Latest package version available in registry.ouster.com
`perception_server`	`object`	Perception Server details
`perception_server.software_version`	`string`	Perception Server software version
`perception_server.settings_version`	`string`	Perception Server settings version
`perception_server.is_ml`	`bool`	Indication if the Perception Server is running ML Perception
`perception_server.is_aggregator`	`bool`	Indication if the Perception Server is running as a Distributed Perception Aggregator
`perception_server.is_running`	`bool`	Indication if the Perception Server is running
`perception_server.is_paused`	`bool`	Indication if the Perception Server is paused on a replay
`perception_server.license`	`string`	Perception Server license details
`perception_server.num_inclusion_zones`	`int`	Number of Perception Server inclusion zones
`perception_server.num_exclusion_zones`	`int`	Number of Perception Server exclusion zones
`perception_server.configuration`	`object`	Perception Server configuration
`perception_server.extrinsics`	`object`	Perception Server extrinsics
`event_zone_server`	`object`	Event Zone Server details
`event_zone_server.software_version`	`string`	Event Zone Server software version
`event_zone_server.settings_version`	`string`	Event Zone Server settings version
`event_zone_server.is_running`	`bool`	Indication if the Event Zone Server is running
`event_zone_server.license`	`string`	Event Zone Server license details
`event_zone_server.num_event_zones	`int`	Number of Event Zone Server event zones
`event_zone_server.configuration`	`object`	Event Zone Server configuration
`event_zone_server.event_zones`	`object`	Event Zone Server Event Zones
`lidar_hub`	`object`	Lidar Hub details
`lidar_hub.software_version`	`string`	Lidar Hub software version
`lidar_hub.settings_version`	`string`	Lidar Hub settings version
`lidar_hub.license`	`string`	Lidar Hub license details
`lidar_hub.is_running`	`bool`	Indication if the Lidar Hub is running
`lidar_hub.diagnostics_enabled`	`bool`	Indication if Diagnostics are enabled
`lidar_hub.aggregation_enabled`	`bool`	Indication if Aggregation is enabled
`lidar_hub.mqtt_publishers`	`int`	Number of configured MQTT publishers
lidar_hub`.tcp_relay_servers	`int`	Number of configured TCP Relay Servers
`lidar_hub.datarecorders`	`list`	List of configured Data Recorders
`lidar_hub.configuration`	`object`	Lidar Hub configuration
`lidar_hub.is_scout`	`bool`	Indication if Lidar Hub is running as a Scout (standalone w/out a Perception Server)
`health`	`string`	Determined health of the Perception System (ONLINE / WARNING / OFFLINE)
`is_scout`	`bool`	Indication if Lidar Hub is running as a Scout (standalone w/out a Perception Server)
`diagnostics_version`	`string`	Version of this message

Diagnostics Telemetry

Compute device, lidar sensor and software Telemetry will be generated at the diagnostics_interval_secs and published to the Gemini Portal and an internal memory-based broker for consumption by MQTT Publishers, TCP Relay Servers and Data Recorders. The current attribute and telemetry diagnostics values can also be requested at any time via the Lidar Hub’s /diagnostics REST API resource.

Example Batching of one or more Frame(s) in a single Message

{
  "diagnostics": [
    {...},
    {...},
    {...}
  ]
}

Example Frame

{
  "hardware_id": "*1234567890",
  "latitude": 37.76466741329934,
  "longitude": -122.4136976526134,
  "azimuth": 57.6,
  "compute": {
    "cpu_utilization": 19.6,
    "cpu_core_utilization": [
        18.9,
        18.7,
        21.9,
        16.8,
        19.3,
        16.9,
        27.6,
        16.9
    ],
    "cpu_temperature_deg_c": 73,
    "cpu_core_temperature_deg_c": [
        73,
        72,
        69,
        70
    ],
    "gpu_utilization": 0,
    "gpu_temperature_deg_c": 0,
    "available_memory": 18890395648,
    "available_disk_space": 762672287744
  },
  "lidars": [
    {
      "model": "OS1",
      "serial_number": "992144000616",
      "firmware": {
        "input_current_ma": 704,
        "input_voltage_mv": 24044,
        "internal_temperature_deg_c": 0,
        "phase_lock_status": "DISABLED",
        "timestamp_ns": 1727503038782740
      },
      "position": {
        "x": -122.4136976526134,
        "y": 37.76466741329934,
        "z": 3.42
      },
      "num_background_points": 83010,
      "num_foreground_points": 416,
      "num_failed_points": 865,
      "num_no_return_points": 46781,
      "num_zone_filtered_points": 4,
      "num_ground_points": 0,
      "num_clusters": 6,
      "num_filtered_clusters": 0,
      "percentage_incomplete_frames": 0,
      "tilt_since_reset": 0.08322851640914329
    }
  ],
  "nodes": [
  ],
  "solutions_agent": { },
  "perception_server": {
    "up_time": 0,
    "num_objects": 0,
    "num_websocket_clients": 3,
    "num_tcp_clients": 3,
    "largest_arrival_delta": 134,
    "lowest_frame_rate": 5.979538020892506,
    "mean_frame_rate": 10.872046880266147,
    "benchmarks": [
    ],
    "timestamp": 1660673730063520
  },
  "event_zone_server": {
    "up_time": 0,
    "num_occupations": 0,
    "num_websocket_clients": 2,
    "num_tcp_clients": 2,
    "timestamp": 1660673730110978
  },
  "lidar_hub": {
    "up_time": 338111.726481,
    "cloud_ingress_mbps": 0.0000176,
    "cloud_ingress_bytes": 132,
    "cloud_ingress_entries": 1,
    "cloud_egress_mbps": 0.0030373333333333333,
    "cloud_egress_bytes": 22780,
    "cloud_egress_entries": 6,
    "mqtt_publishers_connected": 4,
    "mqtt_publishers_mbps": 0.0028957333333333333,
    "mqtt_publishers_bytes": 21718,
    "mqtt_publishers_entries": 4,
    "tcp_relay_server_connections": 0,
    "tcp_relay_server_mbps": 0,
    "tcp_relay_server_bytes": 0,
    "tcp_relay_server_entries": 0,
    "datarecorders_disk_bytes": 10573,
    "datarecorders_disk_entries": 3,
    "timestamp": 1710781920008258
  },
  "timestamp": 1660698930000000,
  "is_scout": false,
  "diagnostics_version": "2.0.0"
}

JSON Field Definitions

JSON Field Definitions
Field	Format	Description
`hardware_id`	`string`	MAC Address of the compute device (MAC Address or Agent Locking Code)
`latitude`	`float`	Lidar Hub world latitude
`longitude`	`float`	Lidar Hub world longitude
`azimuth`	`float`	Lidar Hub world azimuth
`compute`	`object`	Compute Device details
`compute.cpu_utilization`	`float`	Total CPU utilization across all cores
`compute.cpu_core_utilization`	`list`	CPU utilization by core
`compute.cpu_temperature_deg_c`	`float`	Average CPU temperature across all cores
`compute.cpu_core_temperature_deg_c`	`list`	CPU temperature by core
`compute.gpu_utilization`	`float`	Total GPU utilization across all cores
`compute.gpu_temperature_deg_c`	`float`	Average GPU temperature across all cores
`compute.available_memory`	`int`	Available memory on the compute device (bytes)
`compute.available_disk_space`	`int`	Available storage on the compute device (bytes)
`lidars`	`array`	Array of active Lidar sensors
`lidars[].model`	`string`	Lidar sensor model
`lidars[].serial_number`	`string`	Lidar senor serial number
`lidars[].firmware`	`object`	Lidar Firmware details
`lidars[].firmware.input_current_ma`	`int`	Lidar sensor input current as reported by the firmware (milliamps)
`lidars[].firmware.input_voltage_mv`	`int`	Lidar sensor input voltage as reported by the firmware (millivolts)
lidars[].firmware`.internal_temperature_deg_c	`int`	Lidar sensor internal temperature as reported by the firmware (degrees celsius)
`lidars[].firmware.phase_lock_status`	`string`	Lidar sensor phase lock status as reported by the firmware
`lidars[].firmware.timestamp_ns`	`int`	Timestamp of these values as reported by the firmware (nanoseconds since Jan. 1, 1970)
`lidars[].position`	`object`	Lidar sensor position (geo-coordinates if Lidar Hub world is set, otherwise cartesian coordinates in the world reference frame)
`lidars[].position.x`	`float`	x cartesian coordinates or longitude
`lidars[].position.y`	`float`	x cartesian coordinates or latitude
`lidars[].position.z`	`float`	height in meters
`lidars[].num_background_points`	`int`	Number of background points for the last frame
`lidars[].num_foreground_points`	`int`	Number of foreground points for the last frame
`lidars[].num_failed_points`	`int`	Number of failed points for the last frame
`lidars[].num_no_return_points`	`int`	Number of points not returned for the last frame
`lidars[].num_zone_filtered_points`	`int`	Number of points filted by inclusion and exclusion zones for the last frame
`lidars[].num_ground_points`	`int`	Number of points filtered as ground points for the last frame
`lidars[].num_clusters`	`int`	Number of clusters detected for the last frame
`lidars[].num_filtered_clusters`	`int`	Number of clusters remaining after filtering and merging for the last frame
`lidars[].percentage_incomplete_frames`	`float`	Percentage of incomplete frames
`lidars[].tilt_since_reset`	`float`	Change in sensor tilt since last reset
`nodes`	`array`	Array of active Leaf Nodes for Aggregator when Distributed Perception in use
`solutions_agent`	`object`	Ouster Solutions Agent details
`perception_server`	`object`	Perception Server details
`perception_server.up_time`	`int`	Perception Server run time since last started
`perception_server.num_objects`	`int`	Number of objects currently being tracked by the Perception Server
`perception_server.num_websocket_clients`	`int`	Number of web socket clients connected to the Perception Server
`perception_server.num_tcp_clients`	`int`	Number of TCP clients connected to the Perception Server
`perception_server.largest_arrival_delta`	`float`	Difference between all the arrival times of all the sensors
`perception_server.lowest_frame_rate`	`float`	The longest time to process a frame in the last 10 seconds
`perception_server.mean_frame_rate`	`float`	The average time to process a frame
`perception_server.benchmarks`	`array`	Perception Server benchmark statistics
`perception_server.timestamp`	`int`	Timestamp of these values (microseconds since Jan. 1, 1970)
`event_zone_server`	`object`	Event Zone Server details
`event_zone_server.up_time`	`int`	Event Zone Server run time since last started
`event_zone_server.num_occupations`	`int`	Number of objects currently being positioned inside event zone(s)
`event_zone_server.num_websocket_clients`	`int`	Number of web socket clients connected to the Event Zone Server
`event_zone_server.num_tcp_clients`	`int`	Number of TCP clients connected to the Event Zone Server
`event_zone_server.timestamp`	`int`	Timestamp of these values (microseconds since Jan. 1, 1970)
`lidar_hub`	`object`	Lidar Hub details
`lidar_hub.up_time`	`int`	Lidar Hub run time since last started
`lidar_hub.cloud_ingress_mbps`	`float`	Cloud inbound Megabits/Second of last timeseries
`lidar_hub.cloud_ingress_bytes`	`int`	Cloud inbound total Bytes of last timeseries
`lidar_hub.cloud_ingress_entries`	`int`	Cloud inbound total Entries of last timeseries
`lidar_hub.cloud_egress_mbps`	`float`	Cloud outbound Megabits/Second of last timeseries
`lidar_hub.cloud_egress_bytes`	`int`	Cloud outbound total Bytes of last timeseries
`lidar_hub.cloud_egress_entries`	`int`	Cloud outbound total Entries of last timeseries
`lidar_hub.mqtt_publishers_connected`	`int`	Number of configured MQTT publishers connected to their endpoint
`lidar_hub.mqtt_publishers_mbps`	`float`	MQTT Megabits/Second of last timeseries
`lidar_hub.mqtt_publishers_bytes`	`int`	MQTT total Bytes of last timeseries
`lidar_hub.mqtt_publishers_entries`	`int`	MQTT total Entries of last timeseries
`lidar_hub.tcp_relay_server_connections`	`int`	Number of TCP clients connected to Lidar Hub TCP Relay Servers
`lidar_hub.tcp_relay_server_mbps`	`float`	TCP Megabits/Second of last timeseries
`lidar_hub.tcp_relay_server_bytes`	`int`	TCP total Bytes of last timeseries
`lidar_hub.tcp_relay_server_entries`	`int`	TCP total Entries of last timeseries
`lidar_hub.datarecorders_disk_bytes`	`int`	Data Recorder total Bytes of last timeseries
`lidar_hub.datarecorders_disk_entries`	`int`	Data Recorder total Entries of last timeseries
`lidar_hub.timestamp`	`int`	Timestamp of these values (microseconds since Jan. 1, 1970)
`timestamp`	`int`	Timestamp of this message (microseconds since Jan. 1, 1970)
`is_scout`	`bool`	Indication if Lidar Hub is running as a Scout (standalone w/out a Perception Server)
`diagnostics_version`	`string`	Version of this message

Dignostics Alerts

Lidar sensor and software Alerts will be published when first detected and when any update is reported to the internal memory-based broker for consumption by MQTT Publishers, TCP Relay Servers and Data Recorders.

Example

{
  "alerts": [
    {
      "active": true,
      "category": "SHOT_LIMITING",
      "cursor": 2833,
      "alert_code": "0x0100000f",
      "level": "WARNING",
      "source_info": "OS1-992144000616",
      "id": 13962805723535194000,
      "msg": "Shot limiting mode is active. Laser power is partially attenuated;
             please see user guide for heat sinking requirements.",
      "msg_verbose": "Shot limiting has started.",
      "first_occurred": 0,
      "last_occurred": 0,
      "active_count": 0
    },
    {
      "active": true,
      "category": "UDP_TRANSMISSION",
      "cursor": 2822,
      "alert_code": "0x01000016",
      "level": "WARNING",
      "source_info": "OS1-992144000616",
      "id": 11061546793406626000,
      "msg": "Could not send lidar data UDP packet to host; check that network is up.",
      "msg_verbose": "Failed to send lidar UDP data to destination host 10.0.0.39:34642",
      "first_occurred": 0,
      "last_occurred": 0,
      "active_count": 0
    }
  ]
}

JSON Field Definitions

JSON Field Definitions
Field	Format	Description
`alerts`	`array`	Array of active alerts
`alerts[].active`	`bool`	Indication if the alert is still active
`alerts[].category`	`string`	Alert category (application specific)
`alerts[].cursor`	`int`	Alert cursor (lidar only)
`alerts[].alert_code`	`string`	Alert code (application specific - hex)
`alerts[].level`	`string`	Alert level (application specific)
`alerts[].source_info`	`string`	Alert source information (application specific)
`alerts[].id`	`int`	Unique alert ID (application specific)
`alerts[].msg`	`int`	Alert message
`alerts[].msg_verbose`	`int`	Additional alert details (if any)
`alerts[].first_occurred`	`int`	First occurrence of the alert code (micro/nano seconds since Jan. 1, 1970)
`alerts[].last_occurred`	`int`	Last occurrence of the alert code (micro/nano seconds since Jan. 1, 1970)
`alerts[].active_count`	`int`	Total occurrences of the alert code

Aggregation RealTime Events

Event Zone real-time occupancy events will be generated in real-time and published at transmit_realtime_hertz to the internal memory-based broker for consumption by the Gemini Portal, MQTT Publishers, TCP Relay Servers and Data Recorders.

Example Batching of one or more Frame(s) in a single Message

{
  "aggregation_realtime": [
    {...},
    {...},
    {...}
  ]
}

Example Frame

{
  "timestamp": 1711227039549025,
  "aggregation_realtime": [
    {
      "id": 1659467677889,
      "name": "Office",
      "timestamp": 1660664443771926,
      "current_point_count": 350,
      "classification_metrics": [
        {
          "description": "ALL",
          "active_occupants": 115,
          "total_visitors": 1200,
          "total_visits": 1275,
          "last_update": 1660664443771926,
          "sub_classification_metrics": []
        },
        {
          "description": "PERSON",
          "active_occupants": 105,
          "total_visitors": 1160,
          "total_visits": 1235,
          "last_update": 1660664443771926,
          "sub_classification_metrics": [
            {
              "description": "pedestrian",
              "active_occupants": 105,
              "total_visitors": 1160,
              "total_visits": 1235,
              "last_update": 1660664443771926
            }
          ]
        }
      ]
    },
    {
      "id": 1658947733821,
      "name": "Desk",
      "timestamp": 1660664443771926,
      "current_point_count": -1,
      "classification_metrics": [
        {
          "description": "ALL",
          "active_occupants": 1,
          "total_visitors": 1,
          "total_visits": 2,
          "last_update": 1660664443771926,
          "sub_classification_metrics": []
        },
        {
          "description": "PERSON",
          "active_occupants": 1,
          "total_visitors": 1,
          "total_visits": 2,
          "last_update": 1660664443771926,
          "sub_classification_metrics": [
            {
              "description": "pedestrian",
              "active_occupants": 1,
              "total_visitors": 1,
              "total_visits": 2,
              "last_update": 1660664443771926
            }
          ]
        },
        {
          "description": "UNKNOWN",
          "active_occupants": 1,
          "total_visitors": 1,
          "total_visits": 1,
          "last_update": 1660664443771926,
          "sub_classification_metrics": []
        }
      ]
    }
  ]
}

JSON Field Definitions

Aggregation Real-Time Description
Field	Format	Definition
`timestamp`	`int`	Timestamp of when the update was generated. Units in microseconds since Jan. 1, 1970.
`aggregation_realtime`	`array`	Array of Event Zone real-time occupancy updates

realtime update

Real-time occupancy for a given Event Zone.

JSON Field Definitions
Field	Format	Description
`id`	`int`	Event Zone ID
`name`	`string`	Event Zone name
`timestamp`	`int`	Timestamp of the real-time event (microseconds since Jan. 1, 1970)
`current_point_count`	`int`	Number of points currently occupying the zone (-1 indicates this feature is disabled)
`classification_metrics`	`array`	Array of object classifications occupying the zone
`classification_metrics.description`	`string`	Object classification name (“ALL” indicates an aggregate of all classifications)
`classification_metrics.active_occupants`	`int`	Number of objects currently occupying the zone
`classification_metrics.total_visitors`	`int`	Total unique visitors that visited the zone at least once. Uniqueness is defined by each object’s uuid.
`classification_metrics.total_visits`	`int`	Total visits to the zone.
`classification_metrics.last_update`	`int`	Last zone update (microseconds since Jan. 1, 1970)
`classification_metrics.sub_classification_metrics`	`array`	Optional array of object sub-classifications occupying the zone. ML Perception required.
`classification_metrics.sub_classification_metrics.description`	`string`	Object sub-classification name
`classification_metrics.sub_classification_metrics.active_occupants`	`int`	Number of objects currently occupying the zone
`classification_metrics.sub_classification_metrics.total_visitors`	`int`	Total unique visitors that visited the zone at least once. Uniqueness is defined by each object’s uuid.
`classification_metrics.sub_classification_metrics.total_visits`	`int`	Total visits to the zone.
`classification_metrics.sub_classification_metrics.last_update`	`int`	Last zone update (microseconds since Jan. 1, 1970)

Aggregation TimeSeries Aggregates

Zone timeseries aggregates will be generated every timeseries_secs and published at transmit_timeseries_hertz to the internal memory-based broker for consumption by the Gemini Portal, MQTT Publishers, TCP Relay Servers and Data Recorders.

Example Batching of one or more Frame(s) in a single Message

{
  "aggregation_timeseries": [
    {...},
    {...},
    {...}
  ]
}

Example Frame

{
   "timestamp": 1711227039549025,
   "aggregation_timeseries": [
       {
       "id": 1659467677889,
       "name": "Office",
       "timestamp": 1660664440000000,
       "current_point_count": 350,
       "current_max_point_count": 870,
       "current_avg_point_count": 125,
       "overall_max_point_count": 1190,
       "overall_avg_point_count": 85,
       "classification_metrics": [
         {
           "description": "ALL",
           "active_occupants": 1,
           "max_active_occupants": 1,
           "avg_active_occupants": 1,
           "total_visitors": 5,
           "total_visits": 5,
           "new_visitors": 1,
           "new_visits": 1,
           "departed_visitors": 0,
           "current_max_speed": 0.227,
           "current_avg_speed": 0.122,
           "overall_max_speed": 0.22669327197460112,
           "overall_avg_speed": 0.122,
           "current_avg_dwell": 0,
           "overall_avg_dwell": 0,
           "last_update": 1660664449970829,
           "sub_classification_metrics": []
         },
         {
           "description": "PERSON",
           "active_occupants": 1,
           "max_active_occupants": 1,
           "avg_active_occupants": 1,
           "total_visitors": 5,
           "total_visits": 5,
           "new_visitors": 1,
           "new_visits": 1,
           "departed_visitors": 0,
           "current_max_speed": 0.227,
           "current_avg_speed": 0.122,
           "overall_max_speed": 0.22669327197460112,
           "overall_avg_speed": 0.122,
           "current_avg_dwell": 0,
           "overall_avg_dwell": 0,
           "last_update": 1660664449970829,
           "sub_classification_metrics": [
             {
               "description": "pedestrian",
               "active_occupants": 1,
               "max_active_occupants": 1,
               "avg_active_occupants": 1,
               "total_visitors": 5,
               "total_visits": 5,
               "new_visitors": 1,
               "new_visits": 1,
               "departed_visitors": 0,
               "current_max_speed": 0.227,
               "current_avg_speed": 0.122,
               "overall_max_speed": 0.22669327197460112,
               "overall_avg_speed": 0.122,
               "current_avg_dwell": 0,
               "overall_avg_dwell": 0,
               "last_update": 1660664449970829
             }
           ]
         }
       ]
     },
     {
       "id": 1658947733821,
       "name": "Desk",
       "timestamp": 1660664440000000,
       "current_point_count": -1,
       "current_max_point_count": -1,
       "current_avg_point_count": 0,
       "overall_max_point_count": -1,
       "overall_avg_point_count": 0,
       "classification_metrics": [
         {
           "description": "ALL",
           "active_occupants": 1,
           "max_active_occupants": 1,
           "avg_active_occupants": 1,
           "total_visitors": 5,
           "total_visits": 5,
           "new_visitors": 1,
           "new_visits": 1,
           "departed_visitors": 0,
           "current_max_speed": 0.227,
           "current_avg_speed": 0.122,
           "overall_max_speed": 0.22669327197460112,
           "overall_avg_speed": 0.122,
           "current_avg_dwell": 0,
           "overall_avg_dwell": 0,
           "last_update": 1660664449970829,
           "sub_classification_metrics": []
         },
         {
           "description": "PERSON",
           "active_occupants": 1,
           "max_active_occupants": 1,
           "avg_active_occupants": 1,
           "total_visitors": 5,
           "total_visits": 5,
           "new_visitors": 1,
           "new_visits": 1,
           "departed_visitors": 0,
           "current_max_speed": 0.227,
           "current_avg_speed": 0.122,
           "overall_max_speed": 0.22669327197460112,
           "overall_avg_speed": 0.122,
           "current_avg_dwell": 0,
           "overall_avg_dwell": 0,
           "last_update": 1660664449970829,
           "sub_classification_metrics": [
             {
               "description": "pedestrian",
               "active_occupants": 1,
               "max_active_occupants": 1,
               "avg_active_occupants": 1,
               "total_visitors": 5,
               "total_visits": 5,
               "new_visitors": 1,
               "new_visits": 1,
               "departed_visitors": 0,
               "current_max_speed": 0.227,
               "current_avg_speed": 0.122,
               "overall_max_speed": 0.22669327197460112,
               "overall_avg_speed": 0.122,
               "current_avg_dwell": 0,
               "overall_avg_dwell": 0,
               "last_update": 1660664449970829,
             }
           ]
         }
       ]
     },
     {
       "id": 0,
       "name": "Edge-FF:FF:FF:FF:FF:FF",
       "timestamp": 1660664440000000,
       "classification_metrics": [
         {
           "description": "ALL",
           "active_occupants": 1,
           "max_active_occupants": 1,
           "avg_active_occupants": 1,
           "total_visitors": 5,
           "total_visits": 5,
           "new_visitors": 1,
           "new_visits": 1,
           "departed_visitors": 0,
           "current_max_speed": 0.227,
           "current_avg_speed": 0.124,
           "overall_max_speed": 0.22669327197460112,
           "overall_avg_speed": 0.124,
           "current_avg_dwell": 0,
           "overall_avg_dwell": 0,
           "last_update": 1660664449970829,
           "sub_classification_metrics": []
         },
         {
           "description": "PERSON",
           "active_occupants": 1,
           "max_active_occupants": 1,
           "avg_active_occupants": 1,
           "total_visitors": 1,
           "total_visits": 1,
           "new_visitors": 1,
           "new_visits": 1,
           "departed_visitors": 0,
           "current_max_speed": 0.227,
           "current_avg_speed": 0.124,
           "overall_max_speed": 0.22669327197460112,
           "overall_avg_speed": 0.124,
           "current_avg_dwell": 0,
           "overall_avg_dwell": 0,
           "last_update": 1660664449970829,
           "sub_classification_metrics": [
             {
               "description": "pedestrian",
               "active_occupants": 1,
               "max_active_occupants": 1,
               "avg_active_occupants": 1,
               "total_visitors": 1,
               "total_visits": 1,
               "new_visitors": 1,
               "new_visits": 1,
               "departed_visitors": 0,
               "current_max_speed": 0.227,
               "current_avg_speed": 0.124,
               "overall_max_speed": 0.22669327197460112,
               "overall_avg_speed": 0.124,
               "current_avg_dwell": 0,
               "overall_avg_dwell": 0,
               "last_update": 1660664449970829
             }
           ]
         }
       ]
     }
   ]
 }

JSON Field Definitions

Aggregation Timeseries Description
Field	Format	Definition
timestamp	int	Timestamp of when the update was generated. Units in microseconds since Jan. 1, 1970.
aggregation_timeseries	array	Array of Event Zone timeseries aggregates

timeseries aggregates

Timeseries aggregates for a given Event Zone.

JSON Field Definitions
Field	Format	Description
`id`	`int`	Event Zone ID
`name`	`string`	Event Zone name
`current_point_count`	`int`	Number of points currently occupying the zone (-1 indicates this feature is disabled)
`current_max_point_count`	`int`	Maximum number of points occupying the zone in this timeseries (-1 indicates this feature is disabled)
`current_avg_point_count`	`float`	Average number of points occupying the zone in this timeseries
`overall_max_point_count`	`int`	Maximum number of points occupying the zone (-1 indicates this feature is disabled)
`overall_avg_point_count`	`float`	Average number of points occupying the zone
`timestamp`	`int`	Timestamp of the timeseries aggregate (microseconds since Jan. 1, 1970)
`classification_metrics`	`array`	Array of object classifications occupying the zone
`classification_metrics.description`	`string`	Object classification name (“ALL” is an aggregate of all classifications)
`classification_metrics.active_occupants`	`int`	Number of objects currently occupying the zone
`classification_metrics.max_active_occupants`	`int`	Maximum number of objects occupying the zone in this timeseries
`classification_metrics.avg_active_occupants`	`int`	Average number of objects occupying the zone in this timeseries
`classification_metrics.total_visitors`	`int`	Total unique visitors to the zone. Uniqueness is defined by each object’s uuid.
`classification_metrics.total_visits`	`int`	Total visits to the zone
`classification_metrics.new_visitors`	`int`	New unique visitors to the zone in this timeseries. Uniqueness is defined by each object’s uuid.
`classification_metrics.new_visits`	`int`	New visits to the zone in this timeseries
`classification_metrics.departed_visitors`	`int`	Total unique visitors that left the zone in this timeseries. Uniqueness is defined by each object’s uuid.
`classification_metrics.current_max_speed`	`float`	Maximum speed observed in the zone in this timeseries
`classification_metrics.current_avg_speed`	`float`	Average speed observed in the zone in this timeseries
`classification_metrics.overall_max_speed`	`float`	Maximum speed observed in the zone
`classification_metrics.overall_avg_speed`	`float`	Average speed observed in the zone
`classification_metrics.current_avg_dwell`	`float`	Average dwell observed in the zone in this timeseries
`classification_metrics.overall_avg_dwell`	`float`	Average dwell observed in the zone
`classification_metrics.last_update`	`int`	Last zone update (microseconds since Jan. 1, 1970)
`classification_metrics.sub_classification_metrics`	`array`	Optional array of object sub-classifications occupying the zone. ML Perception required.
`classification_metrics.sub_classification_metrics.description`	`string`	Object sub-classification name
`classification_metrics.sub_classification_metrics.active_occupants`	`int`	Number of objects currently occupying the zone
`classification_metrics.sub_classification_metrics.max_active_occupants`	`int`	Maximum number of objects occupying the zone in this timeseries
`classification_metrics.sub_classification_metrics.avg_active_occupants`	`int`	Average number of objects occupying the zone in this timeseries
`classification_metrics.sub_classification_metrics.total_visitors`	`int`	Total unique visitors to the zone. Uniqueness is defined by each object’s uuid.
`classification_metrics.sub_classification_metrics.total_visits`	`int`	Total visits to the zone
`classification_metrics.sub_classification_metrics.new_visitors`	`int`	New unique visitors to the zone in this timeseries. Uniqueness is defined by each object’s uuid.
`classification_metrics.sub_classification_metrics.new_visits`	`int`	New visits to the zone in this timeseries
`classification_metrics.sub_classification_metrics.departed_visitors`	`int`	Total unique visitors that left the zone in this timeseries. Uniqueness is defined by each object’s uuid.
`classification_metrics.sub_classification_metrics.current_max_speed`	`float`	Maximum speed observed in the zone in this timeseries
`classification_metrics.sub_classification_metrics.current_avg_speed`	`float`	Average speed observed in the zone in this timeseries
`classification_metrics.sub_classification_metrics.overall_max_speed`	`float`	Maximum speed observed in the zone
`classification_metrics.sub_classification_metrics.overall_avg_speed`	`float`	Average speed observed in the zone
`classification_metrics.sub_classification_metrics.current_avg_dwell`	`float`	Average dwell observed in the zone in this timeseries
`classification_metrics.sub_classification_metrics.overall_avg_dwell`	`float`	Average dwell observed in the zone
`classification_metrics.sub_classification_metrics.last_update`	`int`	Last zone update (microseconds since Jan. 1, 1970)

Aggregation Alerts

The Aggregation module will generate real-time alerts whenever the occupancy of a zone exceeds a pre-defined Zone Alert condition set in a zone’s metadata. These alerts can be polled at any time via the Lidar Hub’s /event_zones/alerts REST API resource.

Example

"alert": [
  {
    "id": 1234567890,
    "name": "Warning Zone",
    "severity": "WARNING",
    "occupancy": 3,
    "message": "Zone is not empty"
  },
  {
    "id": 0987654321,
    "name": "Crosswalk Zone",
    "severity": "MAJOR",
    "occupancy": 1,
    "message": "Vehicle detected in crosswalk!"
  }
]

JSON Field Definitions

Alerts Description
Field	Format	Definition
`alert`	`array`	Array of real-time occupancy alerts
`alert[].id`	`string`	Event Zone ID
`alert[].name`	`string`	Event Zone name
`alert[].severity`	`string`	Severity of the event
`alert[].occupancy`	`int`	Current occupancy of the Event Zone
`alert[].message`	`string`	Message associated with the alert