Analytics Service Data Formats#
Message Formats Overview#
Message Format |
Direction |
MQTT Topic |
|---|---|---|
Subscribe |
|
|
Subscribe |
|
|
Publish |
|
|
Publish |
|
|
Publish |
|
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 |
|---|---|---|---|
|
string |
Yes |
Sensor identifier; must match the provisioned sensor ID in Scenescape |
|
string (ISO 8601 UTC) |
Yes |
Acquisition time of the reading |
|
any |
Yes |
Sensor reading — numeric scalar, string, boolean, or any JSON value |
|
string |
No |
Sensor subtype hint (e.g. |
|
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 —
valueholds 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 —
valueistrue/false(e.g. a beam-break or pressure mat).Light sensors —
valueis 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 |
|---|---|---|
|
string |
Scene identifier (UUID) |
|
string (ISO 8601 UTC) |
Publication timestamp |
|
string |
Scene name |
|
number |
Regulated publication rate in Hz |
|
object |
Map of camera IDs to their current framerates (e.g. |
|
array |
Effective poses with |
|
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 |
|---|---|---|
|
string (ISO 8601 UTC) |
Event timestamp |
|
string |
Scene identifier (UUID) |
|
string |
Scene name |
|
string |
Region identifier (UUID) |
|
string |
Region name |
|
object |
Map of category to object count currently inside the region (e.g. |
|
array |
Tracked objects currently inside the region (see Common Output Track Fields) |
|
array |
Objects that entered the region during this cycle; Empty when no entry occurred |
|
array |
Objects that exited the region during this cycle; Empty when no exit occurred |
|
object |
Region geometry: |
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
enteredvsexitedelement shape: In region events,enteredelements are bare track objects, whileexitedelements are wrapped as{"object": <track>, "dwell": <seconds>}wheredwellis 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 |
|---|---|---|
|
string (ISO 8601 UTC) |
Event timestamp |
|
string |
Scene identifier (UUID) |
|
string |
Scene name |
|
string |
Tripwire identifier (UUID) |
|
string |
Tripwire name |
|
object |
Map of category to crossing object count (e.g. |
|
array |
Objects that triggered the event; each carries a |
|
array |
Always empty ( |
|
array |
Always empty ( |
|
object |
Tripwire geometry: |
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"
}
}