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.

docker run --rm -p 8082:8082 \
  -v "$PWD/configs:/app/configs: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#