Scene Understanding Service#

GitHub Readme Scenescape

Scene Understanding Service is a generic microservice for multi-scene behavioral analysis. It subscribes to Scenescape MQTT topics to consume scene events and track objects across configured scenes and zones, applies a declarative rule engine to interpret those events, and routes the resulting alerts to a downstream alert service. Because all behavior is defined through configuration rather than code, the service is not tied to any single use case — suspicious activity detection (loitering, checkout bypass, concealment, restricted-zone violations) is just one example, and the same engine can power other scene-understanding scenarios. It is designed to be dropped into any Scenescape-based deployment by supplying two YAML config files — no code changes required.

Use Cases#

  • Generic scene understanding: consume Scenescape events and apply declarative, zone-based behavioral rules for any domain.

  • Retail loss prevention: loitering, repeated high-value-zone visits, checkout bypass, and concealment detection.

  • Restricted-area monitoring: alert when an object enters a zone it should not be in.

  • Any Scenescape deployment that needs declarative, zone-based behavioral rules with optional pose/VLM escalation.

Key Capabilities#

  • Multi-scene, multi-camera object tracking driven entirely by Scenescape MQTT.

  • Declarative YAML rule engine — thresholds and rules change without code edits.

  • Optional behavioral-analysis escalation (pose + VLM) over MQTT.

  • Zone auto-discovery from the Scenescape REST API at startup.

  • Per-person session state machine (zone visits, dwell time, flags).

  • Optional SeaweedFS evidence-frame capture and alert routing.

  • Self-contained image: ships with sample config and runs standalone.

Configuration Surface#

All runtime behavior is driven by two YAML files mounted at /app/configs (override with CONFIG_DIR):

  • scene-config.yaml — Scenescape connection (MQTT + REST), scenes, cameras, and zones.

  • rules.yaml — declarative rule definitions, thresholds, session flags, and escalation services.

See the Configuration Guide for the full field list.

Next Steps#