Get Started with Scene Controller#

Prerequisites#

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

Run the service using Docker#

Navigate to the Directory:
```
cd scenescape
```
Generate secrets:
```
make init-secrets
```

Start the service: Start the service using docker run:

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)/controller/config/reid-config.json:/home/scenescape/SceneScape/reid-config.json \
-v $(pwd)/controller/config/pose-adjustment-route.json:/home/scenescape/SceneScape/pose-adjustment-route.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 \
--tracker_config_file /home/scenescape/SceneScape/tracker-config.json \
--reid_config_file /home/scenescape/SceneScape/reid-config.json \
--ntp ntpserv

Note: The scene service depends on the broker,web and ntpservservices. Before starting this container, ensure that:
- The broker service at broker.scenescape.intel.com is up and reachable.
- The web service at https://web.scenescape.intel.com:443 is accessible.
- The ntpserv service at udp://<host-ip>:123 whihc maps to port 123/udp inside the container.
Verify the service: Check that the service is running:
```
docker ps
```
Stop the service:
```
docker stop scene
```
Access scene controller output through MQTT:
- Refer to scene-controller-api.yaml on how to access scene controller output
- Refer to scene controller sequence diagram

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:

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:

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
- camera_bounds are computed via projection for objects that include a size field in the incoming tracker MQTT data; projected=true entries appear in the regulated output
- 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 available on events topic)
- The following object fields are not available on event topic: similarity, entered, exited
- The following object fields are not available on data/regulated topic: similarity

Enabling Pose Adjustment#

When using a pose estimation model (e.g. yolo11n-pose) in the DL Streamer video pipeline, the Scene Controller can use pose keypoints to refine bounding boxes for supported detection types before projecting them into world coordinates. This improves localization accuracy. The feature is disabled by default.

Enable pose adjustment via CLI flag:

Add the --pose-adjustment flag to the docker run command:

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)/controller/config/reid-config.json:/home/scenescape/SceneScape/reid-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 \
--tracker_config_file /home/scenescape/SceneScape/tracker-config.json \
--reid_config_file /home/scenescape/SceneScape/reid-config.json \
--pose_adjustment_config_file /home/scenescape/SceneScape/pose-adjustment-route.json \
--ntp ntpserv \
--pose-adjustment