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/certs/scenescape-reid.crt:/run/secrets/certs/scenescape-reid.crt:ro \
  -v $(pwd)/manager/secrets/certs/scenescape-reid.key:/run/secrets/certs/scenescape-reid.key:ro \
  -v $(pwd)/manager/secrets/django:/run/secrets/django:ro \
  -v $(pwd)/manager/secrets/controller.auth:/run/secrets/controller.auth:ro \
  --name scene \
  intel/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.

  • For Extended ReID, a vector database is reachable at the shared defaults (reid.scenescape.intel.com:55555, TLS). Mount the shared scenescape-reid client certs as shown above. Select the backend with REID_DATABASE (VDMS or QDRANT). See How to enable re-identification.

• 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

Tracker + Analytics (no local Controller tracker)

For deployments where a separate Tracker publishes tracks on MQTT, run the Analytics microservice with the Tracker (for example make demo-tracker / --profile tracker). Do not use the former Controller --analytics-only flag — it has been removed. Controller-proper stacks use --profile controller (Scene Controller + Analytics).

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/certs/scenescape-reid.crt:/run/secrets/certs/scenescape-reid.crt:ro \
  -v $(pwd)/manager/secrets/certs/scenescape-reid.key:/run/secrets/certs/scenescape-reid.key:ro \
  -v $(pwd)/manager/secrets/django:/run/secrets/django:ro \
  -v $(pwd)/manager/secrets/controller.auth:/run/secrets/controller.auth:ro \
  --name scene \
  intel/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
  

  Alternatively, use the environment variable:

  docker run --rm \
  --init \
  --network scenescape \
  -e CONTROLLER_ENABLE_POSE_ADJUSTMENT=true \
  -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/certs/scenescape-reid.crt:/run/secrets/certs/scenescape-reid.crt:ro \
  -v $(pwd)/manager/secrets/certs/scenescape-reid.key:/run/secrets/certs/scenescape-reid.key:ro \
  -v $(pwd)/manager/secrets/django:/run/secrets/django:ro \
  -v $(pwd)/manager/secrets/controller.auth:/run/secrets/controller.auth:ro \
  --name scene \
  intel/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
  

• Configure label routing via pose-adjustment-route.json:

  {
    "person": ["human", "pedestrian"]
  }
  

• Note: This feature requires the DL Streamer video pipeline to use a pose estimation model (e.g. yolo11n-pose) that provides keypoint data. See the DL Streamer Pipeline Server documentation for pipeline setup instructions.