Analytics Service Data Formats#

Message Formats Overview#

Message Format

Direction

MQTT Topic

Data Scene Input Message Format

Subscribe

scenescape/data/scene/{scene_id}/{thing_type}

Sensor Input Message Format

Subscribe

scenescape/data/sensor/{sensor_id}

Regulated Scene Output Message Format

Publish

scenescape/regulated/scene/{scene_id}

Region Event Output Message Format

Publish

scenescape/event/region/{scene_id}/{region_id}/{event_type}

Tripwire Event Output Message Format

Publish

scenescape/event/tripwire/{scene_id}/{tripwire_id}/{event_type}

The Analytics service consumes the Scene Controller’s unregulated per-category output (scenescape/data/scene/{scene_id}/{thing_type}, see Scene Controller Data Formats) together with raw sensor readings, and adds region, tripwire, and sensor-correlation analytics on top before republishing regulated and event output.

Data Scene Input Message Format#

Published by the Scene Controller on scenescape/data/scene/{scene_id}/{thing_type}. See Data Scene Output Message Format and Common Output Track Fields for the full field reference; the Analytics service adds regions and sensors to each object before republishing. External observation source_id is preserved in regulated and event output; it is provenance, not a geometric camera-visibility claim. Platform cameras (mounts and intrinsics used for 3D frustum rendering) are likewise preserved across regulated republish. See the linked common output fields for source_id semantics.

Sensor Input Message Format#

The Analytics service subscribes to the MQTT topic scenescape/data/sensor/{sensor_id} and receives scalar sensor readings from physical or virtual sensors. Messages are validated against the singleton definition in metadata.schema.json.

Sensor data is used to tag tracked objects that are within the sensor’s configured measurement area. A wide variety of sensor types are supported — environmental sensors (temperature, humidity, air quality), as well as attribute sensors such as badge readers that associate a discrete identifier with a presence event.

Sensor Message Fields#

Field

Type

Required

Description

id

string

Yes

Sensor identifier; must match the provisioned sensor ID in Scenescape

timestamp

string (ISO 8601 UTC)

Yes

Acquisition time of the reading

value

any

Yes

Sensor reading — numeric scalar, string, boolean, or any JSON value

subtype

string

No

Sensor subtype hint (e.g. "temperature", "humidity")

rate

number ≥ 0

No

Rate at which the sensor is producing readings (readings per second)

The id field must match the last path segment of the MQTT topic: scenescape/data/sensor/{sensor_id}.

Example Sensor Input Message#

Environmental Sensor (Temperature Reading)

{
  "id": "temperature1",
  "timestamp": "2022-09-19T21:33:09.832Z",
  "value": 22.5
}

Published to topic: scenescape/data/sensor/temperature1

The value field carries the scalar reading (degrees Celsius in this case). Other environmental sensors such as humidity or air-quality monitors follow the same structure, differing only in the id and the unit of the value.

Other Sensor Types

The singleton schema is intentionally generic — value is untyped and accepts any JSON value. This makes it suitable for attribute sensors beyond simple scalars. For example:

  • Badge / access-control sensors — value holds a string badge identifier (e.g. "BADGE-00421"), allowing the Analytics service to associate a personnel ID with an object track inside the sensor’s measurement area.

  • Boolean presence sensors — value is true/false (e.g. a beam-break or pressure mat).

  • Light sensors — value is a numeric lux reading; see Controlling Scene Lighting with Physical Light Sensors for a complete integration guide.

For a broader description of how singleton sensors work and how the tagged data appears on scene objects, see Singleton Sensor Data in the integration guide.

Regulated Scene Output Message Format#

The cameras list includes configured cameras and their latest valid per-message poses. Entries with pose_provenance.class of live drive live camera movement in the 3D UI; calibration entries do not overwrite unsaved camera edits. Invalid extrinsics are logged and leave the last valid pose (or configured pose) intact. Live poses also apply to projected camera bounds without changing stored calibration. Missing or empty object visibility is filled using the latest valid observation poses before events are evaluated; nonempty producer visibility is preserved. Each regulated publication reprojects camera bounds for all cached categories against the same observation poses, including categories absent from that input frame.

Each runtime Cam retains one effective pose, its pose_locked flag, and pose_provenance (class + origin), for every perceptual modality registered as a camera (RGB, depth, LiDAR/radar detectors, and similar). Durable calibration belongs to Manager, not a second runtime pose. When unlocked, Analytics accepts MQTT observation extrinsics and optics (intrinsics / distortion / resolution) on the same ephemeral path as Controller and retains an accepted live observation (pose and its MQTT optics) across configuration refreshes. Optics-only MQTT updates do not stamp pose_provenance; extrinsics do (class: live). Intrinsics provenance is not covered — pose_provenance must not be read as authorship of MQTT or Manager optics (see ADR 18). Before the first observation it uses stored calibration (class: calibration, with origin from Manager calibration_origin, or unknown when untagged). When locked, observation extrinsics and optics are ignored and stored calibration reloads on refresh. External-source publishers keep a separate ephemeral TTL pose/intrinsics cache (ADR 16) and are not covered by pose_locked / regulated pose_provenance today.

Locking resets the effective pose when configuration refreshes; unlocking starts from calibration until the next valid observation. Saving calibration alone while unlocked does not reset a live pose. Visibility, projected bounds, and published camera poses use one atomic observation snapshot. Live poses do not expire on missing or invalid input. Removing a camera, moving it to another scene, or restarting the process discards its live pose. See Camera Pose Lock and ADR 18 for configuration and provenance details.

Each camera entry contains id, translation, rotation, scale, pose_locked, and pose_provenance. The deprecated dynamic_pose flag remains as an alias of pose_provenance.class === "live" during migration; new consumers must use pose_provenance. Published rotation is always a normalized quaternion in [x, y, z, w] order, mapping camera-local axes into the scene coordinate system. Configured and incoming intrinsic XYZ Euler rotations (degrees) remain supported as inputs and are converted to quaternions for publication. Consumers must not interpret the published rotation as Euler angles; display-specific conversion belongs in the client. Translation and scale retain their existing scene units and per-axis conventions.

Published on MQTT topic: scenescape/regulated/scene/{scene_id}

The Analytics service publishes regulated (rate-controlled) tracking results aggregating all object categories into a single message. This is the primary output topic for downstream applications.

Regulated Scene Top-Level Fields#

Field

Type

Description

id

string

Scene identifier (UUID)

timestamp

string (ISO 8601 UTC)

Publication timestamp

name

string

Scene name

scene_rate

number

Regulated publication rate in Hz

rate

object

Map of camera IDs to their current framerates (e.g. {"cam1": 10.0})

cameras

array

Effective poses with pose_locked and pose_provenance (see schema below)

objects

array

Tracked objects; see Common Output Track Fields

Machine-readable contract: analytics/schema/regulated-scene.schema.json.

Example Regulated Scene Message#

This example shows Scene Controller input, including its legacy metadata.reid embedding pass-through. With Tracker input, embeddings are published only in reid_sighting for reid-service; Analytics does not copy sightings into regulated output or events. Analytics combines Tracker positions with reid-service identity decisions without querying the descriptor store or matching embeddings.

{
  "id": "302cf49a-97ec-402d-a324-c5077b280b7b",
  "timestamp": "2026-03-26T20:48:50.149Z",
  "name": "Queuing",
  "scene_rate": 38.8,
  "rate": {
    "atag-qcam1": 9.998,
    "atag-qcam2": 10.018
  },
  "cameras": [
    {
      "id": "atag-qcam1",
      "translation": [1.2, 3.4, 2.5],
      "rotation": [0.0, 0.0, 0.0, 1.0],
      "scale": [1.0, 1.0, 1.0],
      "pose_locked": true,
      "pose_provenance": {
        "class": "calibration",
        "origin": "manager.rest"
      },
      "dynamic_pose": false
    }
  ],
  "objects": [
    {
      "id": "0c373dbf-2a1d-49b7-ba2d-48711d189971",
      "category": "person",
      "type": "person",
      "confidence": 0.998,
      "translation": [2.204, 3.29, 0.0],
      "size": [0.5, 0.5, 1.85],
      "velocity": [-0.489, 0.25, 0.0],
      "rotation": [0, 0, 0, 1],
      "visibility": ["atag-qcam1", "atag-qcam2"],
      "metadata": {
        "age": { "label": "41", "model_name": "age_gender" },
        "gender": {
          "label": "Male",
          "model_name": "age_gender",
          "confidence": 0.963
        },
        "reid": {
          "embedding_vector": "<embedding_dimensions-element float array>",
          "embedding_dimensions": 256,
          "model_name": "torch-jit-export"
        }
      },
      "camera_bounds": {
        "atag-qcam2": {
          "x": 760,
          "y": 49,
          "width": 191,
          "height": 375,
          "projected": false
        }
      },
      "regions": {
        "ee94126c-1c5a-4ee0-ab5d-0819ba3fc9b4": {
          "entered": "2026-03-26T20:48:46.344Z"
        }
      },
      "sensors": {
        "temperature_1": [
          ["2026-03-26T20:48:45.629Z", 79],
          ["2026-03-26T20:48:46.630Z", 14]
        ]
      },
      "similarity": null,
      "reid_state": "pending_collection",
      "first_seen": "2026-03-26T20:48:42.857Z"
    }
  ]
}

Region Event Output Message Format#

Published on MQTT topic: scenescape/event/region/{scene_id}/{region_id}/{event_type}

The Analytics service publishes an event when the set of tracked objects inside a region of interest changes. The {event_type} segment is typically objects.

Region Event Top-Level Fields#

Field

Type

Description

timestamp

string (ISO 8601 UTC)

Event timestamp

scene_id

string

Scene identifier (UUID)

scene_name

string

Scene name

region_id

string

Region identifier (UUID)

region_name

string

Region name

counts

object

Map of category to object count currently inside the region (e.g. {"person": 2})

objects

array

Tracked objects currently inside the region (see Common Output Track Fields)

entered

array

Objects that entered the region during this cycle; Empty when no entry occurred

exited

array

Objects that exited the region during this cycle; Empty when no exit occurred

metadata

object

Region geometry: title, uuid, points (polygon vertices in metres), area ("poly"), fromSensor (boolean)

Example Region Event Message#

{
  "timestamp": "2026-03-26T20:53:32.045Z",
  "scene_id": "302cf49a-97ec-402d-a324-c5077b280b7b",
  "scene_name": "Queuing",
  "region_id": "ee94126c-1c5a-4ee0-ab5d-0819ba3fc9b4",
  "region_name": "region_2",
  "counts": {
    "person": 2
  },
  "objects": [
    {
      "id": "2d3c96d9-24bd-498b-ba1f-2fd54ab6c25b",
      "category": "person",
      "type": "person",
      "confidence": 0.999,
      "translation": [2.557, 3.678, 0.0],
      "size": [0.5, 0.5, 1.85],
      "velocity": [-0.118, 0.186, 0.0],
      "rotation": [0, 0, 0, 1],
      "visibility": ["atag-qcam1", "atag-qcam2"],
      "camera_bounds": {
        "atag-qcam2": {
          "x": 799,
          "y": 14,
          "width": 169,
          "height": 397,
          "projected": false
        }
      },
      "sensors": {
        "temperature_1": [["2026-03-26T20:53:29.761Z", 48]]
      },
      "similarity": null,
      "first_seen": "2026-03-26T20:53:25.339Z"
    }
  ],
  "entered": [
    {
      "id": "2d3c96d9-24bd-498b-ba1f-2fd54ab6c25b",
      "category": "person",
      "type": "person",
      "confidence": 0.999,
      "translation": [2.557, 3.678, 0.0],
      "size": [0.5, 0.5, 1.85],
      "velocity": [-0.118, 0.186, 0.0],
      "rotation": [0, 0, 0, 1],
      "visibility": ["atag-qcam1", "atag-qcam2"],
      "similarity": null,
      "first_seen": "2026-03-26T20:53:25.339Z"
    }
  ],
  "exited": [
    {
      "object": {
        "id": "bbd07321-dbb9-4384-bf1b-4eb5d9a0aa05",
        "category": "person",
        "type": "person",
        "confidence": 0.98,
        "translation": [0.893, 5.709, 0.0],
        "size": [0.5, 0.5, 1.85],
        "velocity": [0.005, -0.012, 0.0],
        "rotation": [0, 0, 0, 1],
        "visibility": ["atag-qcam2"],
        "regions": {},
        "similarity": null,
        "first_seen": "2026-03-26T20:53:06.647Z",
        "camera_bounds": {
          "atag-qcam2": {
            "x": 180,
            "y": 115,
            "width": 166,
            "height": 400,
            "projected": false
          }
        }
      },
      "dwell": 5.297
    }
  ],
  "metadata": {
    "title": "region_2",
    "uuid": "ee94126c-1c5a-4ee0-ab5d-0819ba3fc9b4",
    "points": [
      [0.77, 6.528],
      [1.286, 2.363],
      [4.961, 1.101],
      [3.394, 4.828],
      [1.923, 6.261]
    ],
    "area": "poly",
    "fromSensor": false
  }
}

Note on entered vs exited element shape: In region events, entered elements are bare track objects, while exited elements are wrapped as {"object": <track>, "dwell": <seconds>} where dwell is the time in seconds the object spent inside the region.

Tripwire Event Output Message Format#

Published on MQTT topic: scenescape/event/tripwire/{scene_id}/{tripwire_id}/{event_type}

The Analytics service publishes an event when a tracked object crosses a tripwire. The {event_type} segment is typically objects. Each crossing object carries a direction field (1 or -1) indicating which side of the wire it crossed toward.

Tripwire Event Top-Level Fields#

Field

Type

Description

timestamp

string (ISO 8601 UTC)

Event timestamp

scene_id

string

Scene identifier (UUID)

scene_name

string

Scene name

tripwire_id

string

Tripwire identifier (UUID)

tripwire_name

string

Tripwire name

counts

object

Map of category to crossing object count (e.g. {"person": 1})

objects

array

Objects that triggered the event; each carries a direction field in addition to Common Output Track Fields

entered

array

Always empty ([]) in tripwire events; crossing objects appear in objects with a direction field instead

exited

array

Always empty ([]) in tripwire events

metadata

object

Tripwire geometry: title, points (array of [x, y] coordinates in metres), uuid

Example Tripwire Event Message#

{
  "timestamp": "2026-03-26T20:51:39.241Z",
  "scene_id": "302cf49a-97ec-402d-a324-c5077b280b7b",
  "scene_name": "Queuing",
  "tripwire_id": "5fc8df22-0497-411c-9a62-90218cb20d7d",
  "tripwire_name": "tripwire_1",
  "counts": {
    "person": 1
  },
  "objects": [
    {
      "id": "d62d8bbf-9008-40f5-84f8-9faca9e03d90",
      "category": "person",
      "type": "person",
      "confidence": 0.999,
      "translation": [1.043, 3.542, 0.0],
      "size": [0.5, 0.5, 1.85],
      "velocity": [0.374, -0.824, 0.0],
      "rotation": [0, 0, 0, 1],
      "visibility": ["atag-qcam1", "atag-qcam2"],
      "camera_bounds": {
        "atag-qcam2": {
          "x": 796,
          "y": 175,
          "width": 257,
          "height": 504,
          "projected": false
        }
      },
      "similarity": null,
      "first_seen": "2026-03-26T20:51:37.336Z",
      "direction": -1
    }
  ],
  "entered": [],
  "exited": [],
  "metadata": {
    "title": "tripwire_1",
    "points": [
      [3.745, 6.082],
      [0.878, 3.573]
    ],
    "uuid": "5fc8df22-0497-411c-9a62-90218cb20d7d"
  }
}