# SPDX-FileCopyrightText: (C) 2025 Intel Corporation
# SPDX-License-Identifier: Apache-2.0

asyncapi: "2.6.0"
info:
  title: Scenescape MQTT API - Scene Controller Service
  version: "1.0.0"
  description: |
    The Scene Controller service is responsible for real-time multi-camera object tracking.

    Flow Description:
    - The Scene Controller `subscribes` to camera data from `scenescape/data/camera/{camera_id}`.
    - 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).

    Sensor correlation, regulated (rate-controlled) output, and region/tripwire event publishing
    are owned by the Analytics service, which consumes `scenescape/data/scene/{scene_id}/{thing_type}`
    and `scenescape/data/sensor/{sensor_id}`. See the Analytics service API spec
    (analytics-service-api.yaml) for those channel definitions.

channels:
  scenescape/data/camera/{camera_id}:
    parameters:
      camera_id:
        description: Camera identifier
        schema:
          type: string
    subscribe:
      summary: Scene Controller subscribes to live camera data
      message:
        payload:
          type: object
          properties:
            timestamp:
              type: string
              format: date-time
            debug_timestamp_end:
              type: string
              format: date-time
            debug_mac:
              type: string
            id:
              type: string
            objects:
              type: object
              additionalProperties:
                type: array
                items:
                  type: object
            rate:
              type: number
              minimum: 0
            intrinsics:
              type: object
              properties:
                fx:
                  type: number
                fy:
                  type: number
                cx:
                  type: number
                cy:
                  type: number
            distortion:
              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/data/scene/{scene_id}/{thing_type}:
    parameters:
      scene_id:
        description: Scene identifier
        schema:
          type: string
      thing_type:
        description: Type of object (e.g., person, car)
        schema:
          type: string
    publish:
      summary: Scene Controller publishes unregulated track data
      message:
        payload:
          type: object
          properties:
            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`, `metadata`, and more.
              items:
                type: object
