Connecting to Output

LidarHub Output

The following section describes the Ouster Gemini Detect JSON data streams exposed via MQTT Publishers, TCP Relay Servers and Web Socket 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, TCP Servers and Web Socket 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/Web Socket 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": [
    {
      "ahead_id": 1096,
      "behind_id": null,
      "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,
      "total_chained_object_length": 0.92849,
      "update_ts": 1663175920076580,
      "user_defined_classification": null,
      "user_defined_classification_ts": 0,
      "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
      }
    },
    {
      "ahead_id": null,
      "behind_id": 1094,
      "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",
      "total_chained_object_length": 0.92849,
      "update_ts": 1663175920076580,
      "user_defined_classification": null,
      "user_defined_classification_ts": 0,
      "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	|id_desc|
uuid	string	|uuid_desc|
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_desc|
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_desc|
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	|dimensions_desc|
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.
ahead_id	int	Id of the associated object in front of this object. Set to null if there is no associated object. Typically will be the object id of the cab in a tractor-trailer.
behind_id	int	Id of the associated object behind this object. Set to null if there is no associated object. Typically will be the object id of the trailer in a tractor-trailer.
total_chained_object_length	float	This field represents the total calculated length of an object and any trailers or other objects physically attached to it, forming a “chain.”
user_defined_classification	string	This field contains the custom classification assigned to the object based on the “User-Defined Classification” rules. If no user-defined classification applies, this field may be empty.
user_defined_classification_ts	int	Timestamp of the current object user-defined classification. 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": [
        {
          "ahead_id": 1096,
          "behind_id": null,
          "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,
          "total_chained_object_length": 0.92849,
          "update_ts": 1663176519190541,
          "user_defined_classification": null,
          "user_defined_classification_ts": 0,
          "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": [
        {
          "ahead_id": 1096,
          "behind_id": null,
          "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",
          "total_chained_object_length": 0.92849,
          "update_ts": 1663176519190541,
          "user_defined_classification": null,
          "user_defined_classification_ts": 0,
          "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
          }
        },
        {
          "ahead_id": null,
          "behind_id": null,
          "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",
          "total_chained_object_length": 0.92849,
          "update_ts": 1663176519186659,
          "user_defined_classification": null,
          "user_defined_classification_ts": 0,
          "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	|zone_id_desc|
name	string	|zone_name_desc|
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": "",
    "running_containers": []
  },
  "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,
    "websocket_servers": 1,
    "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)
lidars[].age_of_last_update	int	Used to determine if a telemetry update has been received for the lidar sensor (seconds)
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
solutions_agent.running_containers	array	Array of currently running Gemini Detect Docker Containers
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`.weboscket_servers	int	Number of configured Web Socket 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, Web Socket 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,
    "websocket_server_connections": 0,
    "websocket_server_mbps": 0,
    "websocket_server_bytes": 0,
    "websocket_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.websocket_server_connections	int	Number of Web Socket clients connected to Lidar Hub Web Socket Servers
lidar_hub.websocket_server_mbps	float	Web Socket Megabits/Second of last timeseries
lidar_hub.websocket_server_bytes	int	Web Socket total Bytes of last timeseries
lidar_hub.websocket_server_entries	int	Web Socket 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, Web Socket 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, Web Socket 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, Web Socket 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

Event Server Payloads

This document describes the output payload structures used by the Ouster Event Server for different event types.

Common Event Payload Structure

All events share a common base structure with event-specific data in the event_data field.

Base Payload Fields

Field	Type	Description
event_id	String (UUID)	Unique identifier for the entire duration of the event
status	String	Event status: “Oneshot”, “Start”, “Active”, or “Ended”
module	Object	Information about the event type that generated the event
module.id	String	Unique identifier of the event instance
module.name	String	Human-readable name of the event instance
module.type	String	Type of the event instance (e.g., “SpeedFilter”)
device_id	String	LidarHub device identifier (obtained from LidarHub)
site_name	String	Name of the site, configurable through the Event Config
transmit_timestamp	Number	Timestamp when event payload was transmitted (microseconds since Jan. 1, 1970)
source_timestamp	Number	Timestamp of the perception data that generated this event (microseconds since Jan. 1, 1970)
start_timestamp	Number	Timestamp when event criteria was first met (microseconds since Jan. 1, 1970)
latest_timestamp	Number	Timestamp when event criteria was last met (microseconds since Jan. 1, 1970)
offender	Object/null	Object that triggered the event (null for event types that do not have a single object associated with the Event)
zone	Object/null	Event Zone where the event occurred (null if not associated with a specific zone)
zone.name	String	|zone_name_desc|
zone.id	Number	|zone_id_desc|
zone.tags	Array[String]	Optional zone tags associated with the zone
event_data	Object/null	Data specific to the event type (null for event types that do not provide additional data)

Offender Object Structure

When present, the offender object contains information about the detected object:

Field	Type	Description
classification	String	|classification_desc|
sub_classification	String	|sub_classification_desc|
creation_timestamp	Number	Epoch timestamp when object was created in Perception
dimensions	Object	|dimensions_desc|
dimensions.height	Number	|dimensions_height_desc|
dimensions.length	Number	|dimensions_length_desc|
dimensions.width	Number	|dimensions_width_desc|
dwell_duration	Number	Duration the object has been in current zone (seconds)
heading	Number	Positive rotation about the z-axis (right-hand rule)
id	Number	|id_desc|
latitude	Number	Latitude coordinate of the object
longitude	Number	Longitude coordinate of the object
position	Object	Current XYZ location of the object in the world reference frame (measured in meters)
position.x	Number	Value relative to the x-axis
position.y	Number	Value relative to the y-axis
position.z	Number	Value relative to the z-axis
speed	Number	Object speed in m/s
uuid	String (UUID)	|uuid_desc|

Base Payload Example

{
    "device_id": "*ABCDEFGHIJKL",
    "event_data": {},
    "event_id": "ee77f2a5-772c-5a9a-97ee-efba6f6b7f55",
    "latest_timestamp": 1725642398584995,
    "module": {
        "id": "ee77f2a5-772c-5a9a-97ee-efba6f6b7f55",
        "name": "ee77f2a5-772c-5a9a-97ee-efba6f6b7f55",
        "type": "SpeedFilter"
    },
    "offender": {
        "classification": "LARGE_VEHICLE",
        "creation_timestamp": 1725642398584995,
        "dimensions": {
            "height": 0.0,
            "length": 0.0,
            "width": 0.0
        },
        "dwell_duration": 0.0,
        "heading": 0.0,
        "id": 1,
        "latitude": 0.0,
        "longitude": 0.0,
        "position": {
            "x": 0.0,
            "y": 0.0,
            "z": 0.0
        },
        "speed": 0.0,
        "sub_classification": "Trailer",
        "uuid": "ee77f2a5-772c-5a9a-97ee-efba6f6b7f55"
    },
    "site_name": "Ouster Detect Site",
    "source_timestamp": 1725642398584995,
    "start_timestamp": 1725642398584995,
    "status": "Active",
    "transmit_timestamp": 1725642398584995,
    "zone": {
        "id": 123,
        "name": "Zone Name",
        "tags": [
            "tag1",
            "tag2"
        ]
    }
}

Event Type-Specific Event Data

The following sections detail the event_data structure for each event type.

Speed Filter Event Data Fields

Field	Type	Description
max_speed	Number	Maximum speed recorded during the event in m/s
distance_traveled	Number	Distance traveled during the speeding event in meters

Intrusion Module Event Data Fields

Field	Type	Description
previous_zones	Array[String]	List of warning zones the object was previously in

Location Presence Event Data Fields

Field	Type	Description
total_occupants	Number	Total number of occupants in the zone
occupancies	Object	Number of occupants per classification
occupancies.LARGE_VEHICLE	Number	Count of large vehicles
occupancies.VEHICLE	Number	Count of vehicles
occupancies.PERSON	Number	Count of people
occupancies.BICYCLE	Number	Count of bicycles
occupancies.UNKNOWN	Number	Count of unknown objects
occupancies.PROSPECT	Number	Count of prospect objects
occupancy_metrics	Object/null	Zone Occupancy Analytics - Metrics analyzing density, queue formation, and space utilization within the monitored zone. Provides both absolute measurements and normalized ratios for cross-zone comparison.
occupancy_metrics.object_length	Number	Total Object Length (meters) - Cumulative length of all detected objects in the zone. Sum of individual object dimensions along their length axis.
occupancy_metrics.queue_length	Number	Queue Length (meters) - End-to-end distance from the zone’s reference point to the furthest object edge, following the actual queue path through all objects and gaps. Measures real-world queue span including object spacing.
occupancy_metrics.zone_length	Number	Zone Length (meters) - Estimated effective zone length (perimeter / 2). Provides baseline for ratio calculations. Estimation error approximately equals zone width.
occupancy_metrics.object_length_ratio	Number	Object Length Ratio - Proportion of zone length occupied by objects (object_length / zone_length).
occupancy_metrics.queue_length_ratio	Number	Queue Length Ratio - Proportion of zone length occupied by traffic queue (queue_length / zone_length). Indicates queue saturation level; values >1.0 signal queue spillover beyond monitored area.
occupancy_metrics.area_occupancy_ratio	Number	Area Occupancy Ratio - Proportion of zone area covered by object boxes using geometric intersection analysis. Accounts for object width/orientation; provides comprehensive 2D density measurement ranging from 0.0 to 1.0.

Note

The offender field is null for this event type as it tracks zone occupancy rather than specific objects.

Visit Fanout Event Data Fields

This event type does not provide additional event data. It will be null.

Object Proximity Monitor Event Data Fields

Field	Type	Description
defender	Object	The second object involved in the proximity event
separation	Number	Current distance between objects in meters

The defender object has the same structure as the offender object (see Offender Object Structure).

Object Queue Monitor Event Data Fields

This event type does not provide additional event data for visualization data.

Note

Both offender and zone fields are null for this event type as it tracks zone occupancy patterns rather than specific objects or zones.

Location Occupied Check Event Data Fields

Note

The offender field is null for this event type as it works with PointCountVisits rather than tracked objects.

Health Monitor

Provides system health status and monitoring information from LidarHub.

Note

This event type has a different payload structure. The following fields are not applicable and are omitted:

• status

• start_timestamp

• latest_timestamp

• offender

• zone

Complete Example

{
    "event_id": "ee77f2a5-772c-5a9a-97ee-efba6f6b7f55",
    "module": {
        "id": "health_monitor_module_id",
        "name": "Health Monitor",
        "type": "HealthMonitor"
    },
    "device_id": "*ABCDEFGHIJKL",
    "site_name": "Ouster Detect Site",
    "transmit_timestamp": 1725642398584995,
    "source_timestamp": 1725642398584995,
    "event_data": {
        "compute": {
            "cpu_temperature_deg_c": 44,
            "cpu_utilization": 23,
            "disk_utilization": 62.64,
            "health": "ONLINE",
            "memory_utilization": 20.07
        },
        "sensors": [
            {
                "health": "ONLINE",
                "host": "10.48.20.128",
                "name": "OS1-682419000042",
                "position": {
                    "x": -75.715364373,
                    "y": 45.403305557,
                    "z": 2.921724557876587
                },
                "serial_number": "682419000042"
            }
        ],
        "software": [
            {
                "health": "ONLINE",
                "name": "lidar-hub",
                "software_version": "2.8.0-alpha.13",
                "up_time": 5326
            },
            {
                "health": "ONLINE",
                "name": "perception_server",
                "software_version": "2.8.0-alpha.13",
                "up_time": 435037
            },
            {
                "health": "ONLINE",
                "name": "event_zone_server",
                "software_version": "2.8.0-alpha.13",
                "up_time": 435037
            },
            {
                "health": "ONLINE",
                "name": "event_server",
                "software_version": "2.8.0-alpha.13",
                "up_time": 428228
            }
        ],
        "system_health": "ONLINE",
        "timestamp": 1756833460892358
    }
}