Build Applications with Scenescape#
This guide explains how to build an application on Scenescape data: subscribe to scene updates and spatial events over MQTT, discover identifiers over the REST API, and deploy the bundled sample application.
Prerequisites#
Deploy Scenescape before connecting an application. Follow the Deployment Guide to prepare images and choose Docker Compose or Kubernetes. For the sample application below, use Deploy Scenescape on Docker or Deploy the Demo.
A running deployment alone does not produce object data. Configure a scene and active camera or sensor inputs, or use the demo’s bundled scenes and video sources.
Concepts and Integration Interfaces#
MQTT is the shared transport for camera and sensor inputs, tracked-object data, scene updates, and spatial analytics events. Applications subscribe through the broker and parse JSON payloads using the Controller Data Formats and Analytics Data Formats. Use the REST API over HTTPS for configuration and discovery.
Topic |
What your application needs to know |
Learn more |
|---|---|---|
Scenes and coordinates |
A scene represents a physical space with a shared coordinate system. Cameras and sensors contribute data to that space. |
|
Cameras and sensors |
Input pipelines publish detections or readings; calibration places camera detections in scene coordinates. |
|
Object tracking |
The Scene Controller combines detections into tracked objects and publishes per-category scene updates. |
|
Spatial analytics |
Analytics publishes rate-controlled scene updates and events for regions of interest (ROIs) and tripwires. ROIs describe areas; tripwires detect boundary crossings. |
Configure Spatial Analytics, Work with Spatial Analytics Data |
REST API |
Discover scene, region, and tripwire identifiers and manage configuration over HTTPS. REST is not the live object-data stream. |
Connect Your Application#
Use the REST API or web UI to identify the scenes, regions, and tripwires your application needs. See REST API Authentication.
Connect an MQTT client over TLS to a reachable Scenescape broker endpoint. Within the Docker network, the bundled broker is
broker.scenescape.intel.comon port1883; this listener uses TLS despite the port number. A client outside that network needs an explicitly configured, reachable endpoint, not the container hostname.Subscribe to the topics needed by your application:
Data
MQTT topic
Payload reference
Rate-controlled scene state
scenescape/regulated/scene/{scene_id}ROI events, such as occupancy updates
scenescape/event/region/{scene_id}/{region_id}/{event_type}Objects currently inside an ROI
scenescape/data/region/{scene_id}/{region_id}/{thing_type}Tripwire crossing events
scenescape/event/tripwire/{scene_id}/{tripwire_id}/{event_type}Unregulated, per-category tracked objects
scenescape/data/scene/{scene_id}/{thing_type}Tripwires are event-only: there is no
scenescape/data/tripwire/...topic. Use the tripwire event topic above for crossing notifications.Replace
{scene_id},{region_id},{tripwire_id}, and{thing_type}with values from your deployment. Find scene, region, and tripwire identifiers in the Scenescape web UI (open a scene and use the Regions and Tripwires tabs) or through the REST API; see Discovering Existing ROIs and Tripwires via API. MQTT+matches one topic level and#matches the remaining levels. The sample uses wildcards to monitor multiple scenes; production applications should narrow subscriptions to their intended scope.Handle incoming messages in your application and implement your business logic. For discovery requests, event payloads, and Python and JavaScript examples, see Work with Spatial Analytics Data.
Example: Deploy the Sample Application#
The repository includes a Node-RED sample application under sample_data/sample_app. Its bundled flows subscribe to:
scenescape/regulated/scene/#for object counts by category.scenescape/event/region/+/#for ROI occupancy.scenescape/event/tripwire/+/#for tripwire crossing events.
The flows aggregate these messages into a dashboard. This demonstrates how to consume Scenescape output without modifying its services.
1. Prepare Scenescape#
Complete the Docker deployment and configure active inputs, or follow Deploy the Demo for ready-made scenes and video sources.
The sample’s Compose file joins the existing Docker network scenescape_scenescape. A Scenescape deployment creates this network using the default Compose project name scenescape. If you use another project name, update the sample’s Compose network configuration to match your deployment before starting it. The bundled sample deployment does not target Kubernetes.
Port 1880 on the host must be available.
2. Start the Application#
From the Scenescape repository root:
make sample-app-up
This builds the sample’s container image and starts Node-RED in the background. Alternatively, run make up from sample_data/sample_app.
Check the container status and logs from the repository root:
docker compose -f sample_data/sample_app/compose.app.yml ps
docker compose -f sample_data/sample_app/compose.app.yml logs --tail=100 nodered
3. Open and Configure Node-RED#
Open these URLs in a web browser:
Editor:
http://<HOST-IP>:1880Dashboard:
http://<HOST-IP>:1880/dashboard
Replace <HOST-IP> with the Docker host’s address, or use localhost when browsing on that host.
Warning
The sample publishes the Node-RED HTTP port on all host interfaces and does not configure editor authentication. Restrict access to a trusted development environment. The bundled MQTT TLS configuration also disables server-certificate verification; it is not a production-ready security configuration.
In the editor, open a Scenes, ROIs, or Tripwire MQTT input node and edit its shared Scenescape-broker connection:
Confirm the broker is
broker.scenescape.intel.com, port1883, with TLS enabled.Configure its TLS settings to trust your deployment’s CA certificate, generated at
manager/secrets/certs/scenescape-ca.pem, and enable server-certificate verification. Make the CA available to Node-RED through its TLS configuration; do not copy private keys into the flows.If your broker enforces authentication, enter a dedicated application’s MQTT credentials in the connection’s security settings.
Save the settings and click Deploy.
Follow the Hardening Guide before exposing either the application or broker beyond the trusted deployment network.
4. Verify Data Arrives#
In the editor, confirm the MQTT input nodes report a connected status. Open the dashboard and check that scenes and object counts update while inputs are active.
To see ROI occupancy and tripwire events, configure spatial analytics and ensure tracked objects enter the regions or cross the tripwires. A connected MQTT client alone does not guarantee these events will be generated.
If no data appears, check the Node-RED logs, broker connection settings, active input pipelines, and topic identifiers. See Troubleshooting.
5. Stop the Application#
From the repository root:
make sample-app-down
Alternatively, run make down from sample_data/sample_app. This stops the sample without stopping Scenescape. Node-RED data is retained in the sample’s named Docker volume.