LightProbeDesc

The LightProbeDesc class represents a light probe Descriptor that provides Image-Based Lighting using Spherical Harmonics. It achieves realistic indirect lighting using pre-computed environment lighting data.

Common Properties

visible

Type: boolean | undefined

Description: Controls the visibility of the object.

Default: true

Example:

{
  visible: false,
  lightProbe: { ... }
}

LightProbe Properties

lightProbe

Type: object | undefined

Description: Configuration options for the light probe.

intensity

Type: number | undefined

Description: Specifies the intensity of the light probe. Higher values result in brighter light.

Default: 1

Example:

{
  lightProbe: {
    intensity: 1.0,
  }
}

sh

Type: SphericalHarmonics3 | undefined

Description: Directly specifies a Three.js SphericalHarmonics3 object. Contains spherical harmonics coefficients. You can use the coefficients property or set the coefficient array with the set() method.

Default: undefined

Example:

import * as THREE from "three";

const nightCoefficients = [
  new THREE.Vector3(0.22, 0.22, 0.28),
  new THREE.Vector3(0.15, 0.15, 0.20),
  // ... 9 coefficients total (3rd-order spherical harmonics)
];

const sh = new THREE.SphericalHarmonics3();
sh.coefficients = nightCoefficients;

{
  lightProbe: {
    sh: sh,
    intensity: 0.05
  }
}

coefficients

Type: number[][] | undefined

Description: Specifies spherical harmonics coefficients as an array. Each element is a 3-element array of [R, G, B]. This can be used as an alternative to sh for setting coefficients.

Note

If both sh and coefficients are specified, coefficients takes precedence.

Default: undefined

Example:

{
  lightProbe: {
    coefficients: [
      [0.5, 0.5, 0.5],
      [0.2, 0.2, 0.2],
      // ... other coefficients
    ],
  }
}

Usage Examples

Basic Usage (Night Scene)

import ThreeView from "@navaramap/three";
import { LightProbeDesc } from "@navaramap/three_default_descs";
import * as THREE from "three";

const view = new ThreeView();
await view.init();

// Pre-computed spherical harmonics coefficients for night
const NIGHT_SH_COEFFICIENTS = [
  [0.22, 0.22, 0.28],
  [0.15, 0.15, 0.20],
  // ... other coefficients
];

// Add a light probe Descriptor
const lightProbe = view.addLight<LightProbeDesc>({
  lightProbe: {
    sh: new THREE.SphericalHarmonics3().set(NIGHT_SH_COEFFICIENTS),
    intensity: 0.05
  }
});

Dynamic Intensity Update

// Update the light probe intensity based on sun position
view.atmosphere.on("sunChanged", () => {
  const isAtNight = view.atmosphere.isAtNight(view.camera.positionECEF);

  lightProbe.update({
    visible: isAtNight,
    lightProbe: {
      intensity: isAtNight ? 0.05 : 0
    }
  });
});

About Spherical Harmonics

Spherical Harmonics is a mathematical technique for efficiently representing environment lighting:

• Compresses an environment map into a compact set of coefficients
• Fast lighting computation suitable for real-time rendering
• Used for approximating indirect lighting and ambient occlusion

Typically, 3rd-order spherical harmonics (9 coefficients) are used.

Notes

• Light probes are primarily used for representing indirect lighting.
• They are effective for reproducing specific lighting environments such as night scenes.
• Spherical harmonics coefficients need to be pre-computed or measured.
• Combined with SkyLightProbeDesc, more dynamic environment lighting can be achieved.