[ITEP-83027] Controller with Analytics only mode (open-edge-platform#884)

Author: dmytroye

Makefile

@@ -56,6 +56,7 @@ CONTROLLER_METRICS_EXPORT_INTERVAL_S ?= 60
 CONTROLLER_ENABLE_TRACING ?= false
 CONTROLLER_TRACING_ENDPOINT ?= otel-collector.scenescape.intel.com:4317
 CONTROLLER_TRACING_SAMPLE_RATIO ?= 1.0
+CONTROLLER_ENABLE_ANALYTICS_ONLY ?= false
 
 # ========================= Default Target ===========================
 
@@ -576,6 +577,7 @@ $(DLSTREAMER_SAMPLE_VIDEOS): ./dlstreamer-pipeline-server/convert_video_to_ts.sh
 	@echo "CONTROLLER_ENABLE_TRACING=$(CONTROLLER_ENABLE_TRACING)" >> $@
 	@echo "CONTROLLER_TRACING_ENDPOINT=$(CONTROLLER_TRACING_ENDPOINT)" >> $@
 	@echo "CONTROLLER_TRACING_SAMPLE_RATIO=$(CONTROLLER_TRACING_SAMPLE_RATIO)" >> $@
+	@echo "CONTROLLER_ENABLE_ANALYTICS_ONLY=$(CONTROLLER_ENABLE_ANALYTICS_ONLY)" >> $@
 # ======================= Secrets Management =========================
 
 .PHONY: init-secrets

controller/docs/user-guide/How-to-configure-tracker.md

@@ -2,6 +2,8 @@
 
 This document guides users and developers on configuring the tracker for specific use cases during Intel® SceneScape deployment.
 
+**Note:** Tracker configuration is not needed when running the Scene Controller in analytics-only mode (`--analytics-only` flag or `CONTROLLER_ENABLE_ANALYTICS_ONLY=true`), as tracking is performed by a separate Tracker service.
+
 ## Tracker Configuration with Time-Based Parameters
 
 ### Enabling Time-Based Parameters

controller/docs/user-guide/get-started.md

@@ -5,7 +5,7 @@
 - The hardware platform must be at least a 10th Generation Intel® Core™ i5 Processor or Intel® Xeon® Scalable processor, with at least 8+GB of RAM and 64+GB of storage.
 - [How to build Scene Controller from source](How-to-build-source.md)
 
-## Running the service using Docker Compose
+## Running the service using Docker
 
 - **Navigate to the Directory**:
 
@@ -16,7 +16,7 @@
 - **Generate secrets**:
 
   ```bash
-  make build-secrets
+  make init-secrets
   ```
 
 - **Start the service**:
@@ -63,3 +63,55 @@
 - **Access scene controller output through MQTT**:
   - Refer to [scene-controller-api.yaml](api-docs/scene-controller-api.yaml) on how to access scene controller output
   - Refer to [scene controller sequence diagram](overview.md#sequence-diagram-scene-controller-workflow)
+
+## Running in Analytics-Only Mode
+
+Analytics-only mode allows the Scene Controller to consume tracked objects from a separate Tracker service via MQTT instead of performing tracking internally. This is useful for distributed deployments where tracking and analytics are handled by separate services.
+
+- **Enable analytics-only mode**:
+
+  Add the `--analytics-only` flag to the docker run command:
+
+  ```bash
+  docker run --rm \
+  --init \
+  --network scenescape \
+  -v scenescape_vol-media:/home/scenescape/SceneScape/media \
+  -v $(pwd)/controller/config/tracker-config.json:/home/scenescape/SceneScape/tracker-config.json \
+  -v $(pwd)/manager/secrets/certs/scenescape-ca.pem:/run/secrets/certs/scenescape-ca.pem:ro \
+  -v $(pwd)/manager/secrets/django:/run/secrets/django:ro \
+  -v $(pwd)/manager/secrets/controller.auth:/run/secrets/controller.auth:ro \
+  --name scene \
+  scenescape-controller \
+  controller \
+  --broker broker.scenescape.intel.com \
+  --ntp ntpserv \
+  --analytics-only
+  ```
+
+  Alternatively, use the environment variable:
+
+  ```bash
+  docker run --rm \
+  --init \
+  --network scenescape \
+  -e CONTROLLER_ENABLE_ANALYTICS_ONLY=true \
+  -v scenescape_vol-media:/home/scenescape/SceneScape/media \
+  -v $(pwd)/controller/config/tracker-config.json:/home/scenescape/SceneScape/tracker-config.json \
+  -v $(pwd)/manager/secrets/certs/scenescape-ca.pem:/run/secrets/certs/scenescape-ca.pem:ro \
+  -v $(pwd)/manager/secrets/django:/run/secrets/django:ro \
+  -v $(pwd)/manager/secrets/controller.auth:/run/secrets/controller.auth:ro \
+  --name scene \
+  scenescape-controller \
+  controller \
+  --broker broker.scenescape.intel.com \
+  --ntp ntpserv
+  ```
+
+- **Note**: In analytics-only mode (experimental feature):
+  - The tracker is not initialized
+  - Camera and scene detection data processing is skipped
+  - The controller subscribes to tracked object data from MQTT topics published by the Tracker service
+  - Analytics processing (regions, tripwires, sensors) continues to function normally
+  - Child scenes are not supported in analytics-only mode
+  - Sensors in Scene not supported and attribute persistence across moving objects not supported on data/scene MQTT topic (data avaliable on events topic).

controller/docs/user-guide/overview.md

@@ -34,6 +34,8 @@ To deploy the scene controller service, refer to the [Get started](get-started.m
 
 `--visibility_topic`: Specifies the topic for publishing visibility information, which includes the visibility of objects in cameras. Options are `unregulated`, `regulated`, or `none`.
 
+`--analytics-only`: Enables analytics-only mode (experimental feature). In this mode, the Scene Controller consumes tracked objects from a separate Tracker service via MQTT instead of performing tracking internally. The tracker is not initialized, and camera/scene data processing is skipped. Child scenes are not supported. This mode can also be enabled via the `CONTROLLER_ENABLE_ANALYTICS_ONLY` environment variable set to `true`.
+
 ### Tracker Configuration
 
 For details on how to configure the tracker, see [How to configure tracker](./How-to-configure-tracker.md).

controller/src/controller-cmd

@@ -1,12 +1,13 @@
 #!/usr/bin/env python3
 
-# SPDX-FileCopyrightText: (C) 2024 - 2025 Intel Corporation
+# SPDX-FileCopyrightText: (C) 2024 - 2026 Intel Corporation
 # SPDX-License-Identifier: Apache-2.0
 
 import argparse
 import os
 
 from controller.scene_controller import SceneController
+from controller.controller_mode import ControllerMode
 from controller.observability import metrics, tracing
 
 def build_argparser():
@@ -43,10 +44,16 @@ def build_argparser():
   parser.add_argument("--visibility_topic", help="Which topic to publish visibility on."
                       "Valid options are 'unregulated', 'regulated', or 'none'",
                       default="regulated")
+  parser.add_argument("--analytics-only", action="store_true",
+                      default=os.getenv("CONTROLLER_ENABLE_ANALYTICS_ONLY") == "true",
+                      help="Enable analytics-only mode. Use this when running a separate Tracker service that publishes tracking data to MQTT.")
   return parser
 
 def main():
   args = build_argparser().parse_args()
+
+  ControllerMode.initialize(analytics_only=args.analytics_only)
+
   metrics.init()
   tracing.init()
   controller = SceneController(args.rewriteBadTime, args.rewriteAllTime,

controller/src/controller/controller_mode.py

@@ -0,0 +1,74 @@
+# SPDX-FileCopyrightText: (C) 2026 Intel Corporation
+# SPDX-License-Identifier: Apache-2.0
+
+from scene_common import log
+
+class ControllerMode:
+  """
+  Static namespace for managing controller's mode.
+
+  Usage:
+      # Initialize once at startup
+      ControllerMode.initialize(analytics_only=True)
+
+      # Access anywhere in the codebase
+      if ControllerMode.isAnalyticsOnly():
+          # analytics-only mode
+      else:
+          # default mode
+  """
+
+  _initialized = False
+  _analytics_only = False
+
+  @classmethod
+  def initialize(cls, analytics_only=False):
+    """
+    Initialize the controller mode. Should be called once at startup.
+
+    Args:
+        analytics_only: If True, controller runs in analytics-only mode
+                      (no tracking, consumes already-tracked objects)
+    """
+    if cls._initialized:
+      log.warning("ControllerMode already initialized. Ignoring re-initialization.")
+      return
+
+    cls._analytics_only = analytics_only
+    cls._initialized = True
+
+    if analytics_only:
+      log.info("Controller mode: ANALYTICS-ONLY (tracker disabled)")
+    else:
+      log.info("Controller mode: DEFAULT (tracker enabled)")
+
+  @classmethod
+  def isAnalyticsOnly(cls):
+    """
+    Check if controller is running in analytics-only mode.
+
+    Returns:
+        bool: True if analytics-only mode is enabled, False otherwise
+    """
+    if not cls._initialized:
+      log.warning("ControllerMode not initialized. Defaulting to default mode.")
+      return False
+    return cls._analytics_only
+
+  @classmethod
+  def isInitialized(cls):
+    """
+    Check if the controller mode has been initialized.
+
+    Returns:
+        bool: True if initialized, False otherwise
+    """
+    return cls._initialized
+
+  @classmethod
+  def reset(cls):
+    """
+    Reset the singleton state.
+    """
+    cls._initialized = False
+    cls._analytics_only = False

controller/src/controller/detections_builder.py

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: (C) 2024 - 2025 Intel Corporation
+# SPDX-FileCopyrightText: (C) 2024 - 2026 Intel Corporation
 # SPDX-License-Identifier: Apache-2.0
 
 import numpy as np
@@ -91,7 +91,7 @@ def computeCameraBounds(scene, aobj, obj_dict):
   camera_bounds = {}
   for cameraID in obj_dict['visibility']:
     bounds = None
-    if aobj and hasattr(aobj.vectors[0].camera, 'cameraID') \
+    if aobj and len(aobj.vectors) > 0 and hasattr(aobj.vectors[0].camera, 'cameraID') \
           and cameraID == aobj.vectors[0].camera.cameraID:
       bounds = getattr(aobj, 'boundingBoxPixels', None)
     elif scene: