Controlling Scene Lighting with Physical Light Sensors#

SceneScape automatically adjusts 3D scene lighting based on real-time data from physical light sensors via MQTT, creating a digital twin that reflects actual lighting conditions.

Setup#

Create a Singleton Sensor#

In the SceneScape UI, create a new sensor with:

  • Sensor ID: Must match your publisher config (e.g., warehouse_01_light)

  • Type: Environmental

  • Area: scene (required; see note below)

Important: Only sensors with area=”scene” control scene lighting. Localized sensors (area=”circle” or “poly”) tag objects but don’t affect ambient illumination.

Sensor identification: The 3D viewer identifies light sensors by subtype: "light" in the message payload, or by the sensor ID ending with _light (e.g., warehouse_01_light).

Configure Your Sensor Publisher#

Publish to: scenescape/data/sensor/{sensor_id}

Message format:

{
  "id": "warehouse_01_light",
  "timestamp": "<ISO 8601 UTC timestamp>",
  "value": 425,
  "subtype": "light"
}

The value field must be in lux (SI unit for illuminance).

Light Intensity Conversion#

Lux values convert to scene intensity: intensity = value / 500 (clamped to 0.1-3.0 range)

  • 500 lux → 1.0 intensity (normal lighting)

  • 250 lux → 0.5 intensity (dim)

  • 1000 lux → 2.0 intensity (bright)

Usage#

Start your sensor publisher and open the 3D scene viewer. The lighting automatically adjusts based on sensor values.

Manual Control#

The 3D viewer includes a GUI slider for manual light control:

  • Range: 0.1 to 3.0

  • Default: 1.0 (normal lighting)

  • Behavior: Sensor values automatically override manual settings when new data arrives

Typical lux values:

Lux

Environment

Intensity

100

Dim room

0.2

400

Indoor

0.8

500

Office

1.0

1000

Bright

2.0

Troubleshooting#

Scene not changing:

  • Verify sensor area=”scene” in SceneScape UI

  • Check sensor ID matches publisher exactly (case-sensitive)

  • View browser console (F12) for error messages

Wrong lighting levels:

  • Calibrate analog sensors against a reference lux meter

  • Verify sensor reports actual lux values

  • Check sensor placement (avoid direct sunlight)

Multiple sensors:

  • Scene sensors (area=”scene”) control ambient lighting

  • Localized sensors (area=”circle”/”poly”) tag objects only

  • Most recent scene sensor value is applied