[DOCS] ITEP-88358 Unify and expose documentation of Scene Controller message formats (#1247 cherry-pick)

docs/user-guide/additional-resources/convert-object-detections-to-normalized-image-space.md

@@ -54,7 +54,7 @@ Detection metadata is usually provided in pixel units. Here is an example of a d
 {
    "objects":[
       {
-         "type":"person",
+         "category":"person",
          "bounding_box":{
             "top":157,
             "left":221,
@@ -74,7 +74,7 @@ The output will look something like this, where the values are now floating poin
 {
    "objects":[
       {
-         "type":"person",
+         "category":"person",
          "bounding_box":{
             "x":-0.21945553,
             "y":-0.27470306,

docs/user-guide/api-docs/api.yaml

@@ -8,7 +8,7 @@ info:
   title: "SceneScape REST API"
   license:
     name: License
-    url: "https://github.com/open-edge-platform/scenescape/blob/main/LICENSES/Apache-2.0.txt"
+    url: "https://github.com/open-edge-platform/scenescape/blob/release-2026.0/LICENSES/Apache-2.0.txt"
 
 host: "<user-defined>"
 basePath: "/api/v1"

docs/user-guide/index.md

@@ -40,7 +40,9 @@ Figure 1: Architecture Diagram
 
 ### **Scene Controller**
 
-Maintains the current state of the scene, including tracked objects, cameras, and sensors. For more information, refer to [Scene Controller Microservice](./microservices/controller/controller.md).
+Processes input metadata from camera pipelines and sensors, performs multi-camera and multi-object tracking, maintains and updates the current state of the scene, and produces tracked objects and scene analytics events. For more information, refer to [Scene Controller Microservice](./microservices/controller/controller.md).
+
+For details on the controller input and output message formats, see [Scene Controller Message Formats](./microservices/controller/data_formats.md).
 
 ### **Deep Learning Streamer Pipeline Server**
 

docs/user-guide/microservices/controller/_assets/scene-controller-api.yaml

@@ -10,13 +10,11 @@ info:
 
     Flow Description:
     - The Scene Controller `subscribes` to camera data from `scenescape/data/camera/{camera_id}`.
+    - It also `subscribes` to external `sensor data` from `scenescape/data/sensor/{sensor_id}` to enhance scene awareness.
     - It processes live camera detections into `scene objects`.
     - It `publishes` unregulated tracking results to `scenescape/data/scene/{scene_id}/{thing_type}` for each object type (e.g., person, vehicle).
     - It `publishes` regulated (filtered or validated) track results to `scenescape/regulated/scene/{scene_id}`.
-    - It also `subscribes` to external `sensor data` from `scenescape/data/sensor/{sensor_id}` to enhance scene awareness.
-    - Based on scene and sensor inputs, it **detects events** and **publishes** event notifications to `scenescape/event/{region_type}/{scene_id}/{region_id}/{event_type}` and `scenescape/region/<region_id>`.
-
-    These interactions follow a request/response communication pattern and will eventually be transitioned to REST API calls.
+    - Based on scene and sensor inputs, it **detects events** and **publishes** event notifications to `scenescape/event/{region_type}/{scene_id}/{region_id}/{event_type}`.
 
 channels:
   scenescape/data/camera/{camera_id}:
@@ -42,21 +40,40 @@ channels:
             id:
               type: string
             objects:
-              type: array
-              items:
-                type: object
+              type: object
+              additionalProperties:
+                type: array
+                items:
+                  type: object
             rate:
-              type: string
+              type: number
+              minimum: 0
             intrinsics:
-              type: array
-              items:
-                type: array
+              type: object
+              properties:
+                fx:
+                  type: number
+                fy:
+                  type: number
+                cx:
+                  type: number
+                cy:
+                  type: number
             distortion:
-              type: array
-              items:
-                type: array
-            frame_rate:
-              type: string
+              type: object
+              description: >-
+                Lens distortion coefficients keyed by name.
+              properties:
+                k1:
+                  type: number
+                k2:
+                  type: number
+                p1:
+                  type: number
+                p2:
+                  type: number
+                k3:
+                  type: number
 
   scenescape/regulated/scene/{scene_id}:
     parameters:
@@ -73,21 +90,25 @@ channels:
             timestamp:
               type: string
               format: date-time
-            objects:
-              type: array
-              items:
-                type: object
             id:
               type: string
             name:
               type: string
             scene_rate:
-              type: float
+              type: number
+              minimum: 0
             rate:
-              type: string
-            last:
-              type: string
-              format: date-time
+              type: object
+              additionalProperties:
+                type: number
+            objects:
+              type: array
+              description: >-
+                Array of tracked scene objects. Each object includes fields such as
+                `id`, `translation`, `velocity`, `visibility`, `regions`, `sensors`,
+                `metadata`, and more.
+              items:
+                type: object
 
   scenescape/data/scene/{scene_id}/{thing_type}:
     parameters:
@@ -108,8 +129,22 @@ channels:
             timestamp:
               type: string
               format: date-time
+            id:
+              type: string
+            name:
+              type: string
+            rate:
+              type: number
+              minimum: 0
+            unique_detection_count:
+              type: integer
+              minimum: 0
             objects:
               type: array
+              description: >-
+                Array of tracked scene objects. Each object includes fields such as
+                `id`, `translation`, `velocity`, `visibility`, `regions`, `sensors`,
+                `metadata`, and more.
               items:
                 type: object
 
@@ -140,10 +175,53 @@ channels:
             timestamp:
               type: string
               format: date-time
+            scene_id:
+              type: string
+            scene_name:
+              type: string
+            region_id:
+              type: string
+              description: Present in region events
+            region_name:
+              type: string
+              description: Present in region events
+            tripwire_id:
+              type: string
+              description: Present in tripwire events
+            tripwire_name:
+              type: string
+              description: Present in tripwire events
+            counts:
+              type: object
+              additionalProperties:
+                type: integer
             objects:
               type: array
               items:
                 type: object
+            entered:
+              type: array
+              items:
+                type: object
+              description: >-
+                Objects that entered the region during this cycle. In region events, each element is a bare
+                track object. In tripwire events, this array is always empty. It may be
+                empty in region events when no entry has occurred.
+            exited:
+              type: array
+              items:
+                type: object
+              description: >-
+                Objects that exited the region during this cycle. In region events, each element is shaped as
+                {"object": <track>, "dwell": <seconds>}. In tripwire events, this
+                array is always empty. It may be empty in region events when no exit
+                has occurred.
+            metadata:
+              type: object
+              description: >-
+                The region or tripwire geometry. Region events include: title, uuid, points
+                (polygon vertices), area, fromSensor. Tripwire events include: title,
+                uuid, points (two endpoints).
 
   scenescape/data/sensor/{sensor_id}:
     parameters:
@@ -160,5 +238,13 @@ channels:
             timestamp:
               type: string
               format: date-time
-            sensor_type:
+            id:
               type: string
+            value:
+              description: >-
+                Sensor reading — numeric scalar, string, boolean, or any JSON value.
+            subtype:
+              type: string
+            rate:
+              type: number
+              minimum: 0

docs/user-guide/microservices/controller/controller.md

@@ -57,6 +57,10 @@ For detailed configuration guidance:
 - Tracker configuration: See [How to Configure the Tracker](./how-to-configure-tracker.md)
 - Re-ID configuration: See [Extended Re-ID](./Extended-ReID.md)
 
+## Input/Output Message Formats
+
+For details on the MQTT message formats accepted and produced by the Scene Controller, see [SceneScape Controller Data Formats](./data_formats.md).
+
 ## Architecture
 
 ![SceneScape architecture diagram](./_assets/architecture.png)
@@ -76,6 +80,7 @@ _Figure 2: Scene Controller Sequence diagram_
 - [Get Started Guide](./get-started.md)
 - [How to Configure the Tracker](./how-to-configure-tracker.md)
 - [Extended Re-ID](./Extended-ReID.md)
+- [Data Formats](./data_formats.md)
 - [API Reference](./api-reference.md)
 
 <!--hide_directive
@@ -86,6 +91,7 @@ get-started.md
 how-to-configure-tracker.md
 Extended-ReID.md
 API Reference <api-reference.md>
+data_formats.md
 
 :::
 hide_directive-->