Get Started#

This page is the entry point for running the Scene Understanding Service. Pick one of the two deployment paths and follow the linked guide.

Before You Begin#

  • Confirm that your machine meets the System Requirements.

  • Make sure you have a reachable Scenescape deployment (MQTT broker + REST API). The service is an event consumer — it needs Scenescape to produce meaningful output.

  • Prepare your two config files (scene-config.yaml and rules.yaml). The service ships with samples under configs/; review the Configuration Guide before editing them.

Configure the Service#

All runtime behavior is driven by two YAML files in a single directory (/app/configs by default, or set CONFIG_DIR). The image bakes in working samples so it starts out-of-the-box; supply your own files via a read-only volume mount (e.g. -v ./configs:/app/configs:ro) to override them — no code changes required.

  1. scene-config.yaml — how the service connects to Scenescape and what it watches:

    • scenescape_api — Scenescape REST base URL (used for zone auto-discovery).

    • mqtt — broker host/port, TLS, and the Scenescape topic patterns to subscribe to.

    • scenes — the scenes/cameras to track, and a mapping of zone names (must match Scenescape region names) to zone types (HIGH_VALUE, CHECKOUT, EXIT, RESTRICTED).

    • seaweedfs / alert_service (optional) — evidence-frame storage and the downstream alert endpoint.

  2. rules.yaml — how events are interpreted. This is where you adapt the service to your use case without touching code:

    • rules — each rule has a trigger, conditions, and actions (alert to raise an alert, or escalate to invoke a service).

    • variables / session_flags / settings — tunable thresholds, flags, and session knobs.

    • services — named escalation services (e.g. behavioral analysis) that rules can invoke.

A minimal scene-config.yaml looks like this:

scenescape_api:
  base_url: https://web.scenescape.intel.com
  verify_ssl: false

scenes:
  - scene_name: example-scene
    cameras:
      - example-camera1
    zones:
      zone1: HIGH_VALUE
      zone2: CHECKOUT

mqtt:
  host: broker.scenescape.intel.com
  port: 1883
  use_tls: false

A few identity/credential settings are supplied via environment variables (STORE_ID, SCENESCAPE_API_USER, SCENESCAPE_API_PASSWORD, ALERT_SERVICE_URL). MQTT and the Scenescape API URL are configured in scene-config.yaml, not through environment variables.

See the Configuration Guide for the full field list, TLS setup, and how to disable behavioral analysis.

Choose Deployment Path#

Use the Docker path for the simplest setup with a released image. For local development or source builds, follow the linked guides below.

Run with a released Docker image#

The container exposes the API on host port 8082 and reads config from /app/configs. Use a versioned image tag instead of latest for reproducible deployments.

The service must be on the same Docker network as your Scenescape deployment so it can resolve the MQTT broker and REST API hostnames. Attach it with --network, matching the network name of your Scenescape stack (the default compose deployment creates scenescape_scenescape; run docker network ls to confirm).

docker run --rm -p 8082:8082 \
  --network scenescape_scenescape \
  -v "$PWD/configs:/app/configs:ro" \
  intel/scene-understanding-service:<RELEASE_TAG>

If your Scenescape deployment uses TLS for the MQTT broker (the default deployment does), set mqtt.use_tls: true in scene-config.yaml and mount the Scenescape certificates so the service can authenticate:

docker run --rm -p 8082:8082 \
  --network scenescape_scenescape \
  -v "$PWD/configs:/app/configs:ro" \
  -v "$PWD/secrets:/app/secrets:ro" \
  intel/scene-understanding-service:<RELEASE_TAG>

Then verify:

curl --noproxy '*' http://127.0.0.1:8082/health

For compose-based deployments and a complete production setup, see Run with Docker Compose.

For local development and source builds#

Use those guides when you need to work from the repo, run with uv, or build a custom image.

Verify#

Once the service is running:

curl --noproxy '*' http://127.0.0.1:8082/health

Expected response:

{"status": "healthy"}

Service readiness (includes runtime stats):

curl --noproxy '*' http://127.0.0.1:8082/api/v1/sus/status

Next Steps#