flutter3d
Showcase Changelog 62 packages API reference

Lights in lumens and lux

since 0.7.0 Shading and materials

LightNode.intensity is in photometric units: lux for a directional light, candela for a point, spot or area light. A lamp off a datasheet is typed in as it is rated instead of tuned by eye, and Photometric.fromLumens turns a box's lumens into candela. The camera's exposure then turns those absolute values into a picture.

Step 1: A sky in lux #

A directional light has no position and no falloff, so its intensity is the illuminance a facing surface reads, anywhere in the scene. Overcast daylight is about ten thousand lux.

// A directional light has no falloff, so its intensity is what a surface
// facing it reads: lux is the unit its own datasheet would give.
_sky = LightNode(name: 'sky', intensity: overcastLux)
  ..setLocalForward(Vector3(-0.3, -0.7, -0.5));

Step 2: A lamp in lumens #

A point lamp spreads its flux over the whole sphere around it, so Photometric.fromLumens divides by 4π: an 800 lumen bulb is about 64 candela.

// An 800 lm bulb is the ordinary sixty-watt incandescent it replaced.
_lamp = LightNode(
  name: 'lamp',
  type: LightType.point,
  intensity: Photometric.fromLumens(lampLumens),
  range: 8.0,
)..setPosition(1.6, 1.2, 1.0);

Step 3: Expose for the light #

Ten thousand lux and sixty-four candela are real amounts of light, so the camera is set as it would be outdoors on an overcast day: metered for the sky, about EV100 12. Under that sky the bulb barely shows, as a bulb does in daylight; pull the sky slider down to a few hundred lux to see it.

// Lux and candela are absolute, so the camera has to be set for them as a
// photographer would be: metered once for the overcast sky the page opens
// under, plus the scene's flat ambient (in the engine's pre-1.0 unit), and
// then left alone. About EV100 12, f/4 at roughly a two-hundred-and-fiftieth;
// the sliders then brighten and darken the picture, as the weather would.
static final PhysicalCamera _camera = PhysicalCamera.metered(
  10000.0 + 0.06 * LightNode.legacyUnit,
);

@override
RenderSettings settings(DemoContext context) =>
    RenderSettings(camera: _camera);

Step 4: Move the sliders #

Both lights are recomputed every frame from whichever unit their slider is in, so raising the lux slider is the same as raising the sun outside a window.

_sky.intensity = overcastLux;
_lamp.intensity = Photometric.fromLumens(lampLumens);

Step 5: What round-trips #

The sky's intensity is its lux as it was typed, and Photometric.toLumens is the inverse of fromLumens. Reading the lights back should return the exact numbers the sliders set, and that is what this page checks.

const double epsilon = 1e-6;
if ((_sky.intensity - overcastLux).abs() > epsilon) {
  throw StateError('the sky intensity does not convert back to its lux');
}
if ((Photometric.toLumens(_lamp.intensity) - lampLumens).abs() > epsilon) {
  throw StateError('the lamp intensity does not convert back to lumens');
}
if (frame.drawCalls < 1) {
  throw StateError('the ball was not drawn');
}