@headless-three/renderer 0.1.7 → 0.1.9

package/dist/lights.js

@@ -3,39 +3,39 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.extractLights = extractLights;
 exports.extractAmbientLight = extractAmbientLight;
 exports.extractAmbientIntensity = extractAmbientIntensity;
+exports.extractLightProbe = extractLightProbe;
 const color_1 = require("./color");
-function extractLights(scene) {
+const layers_1 = require("./layers");
+const math_1 = require("./math");
+const objects_1 = require("./objects");
+const MAX_NATIVE_LIGHTS = 64;
+const MAX_SHADOW_CASCADES = 4;
+function extractLights(scene, camera) {
     const lights = [];
-    visitLights(scene, lights);
+    visitLights(scene, camera, lights);
+    assertSupportedLightCount(lights);
     return lights.length > 0 ? lights : undefined;
 }
-function visitLights(object, lights) {
+function visitLights(object, camera, lights) {
     if (!object)
         return;
-    if (object.visible === false)
+    if (optionalBoolean(object.visible, 'object.visible') === false)
         return;
-    if (object.isLight === true) {
+    if (object.isLight === true && (0, layers_1.objectLayersMatchCamera)(object, camera)) {
         const light = extractLight(object);
         if (light)
             lights.push(light);
     }
-    const children = Array.isArray(object.children) ? object.children : [];
-    for (const child of children) {
-        visitLights(child, lights);
+    for (const child of (0, objects_1.objectChildren)(object)) {
+        visitLights(child, camera, lights);
     }
 }
 function extractLight(light) {
-    const color = (0, color_1.colorLikeToArray)(light.color) ?? [1, 1, 1, 1];
-    const intensity = Number.isFinite(light.intensity) ? light.intensity : 1;
+    const color = (0, color_1.validatedColorLikeToArray)(light.color, 'light.color') ?? [1, 1, 1, 1];
+    const intensity = finiteNumberOrDefault(light.intensity, 'light.intensity', 1);
     if (light.isDirectionalLight === true) {
-        const pos = light.matrixWorld
-            ? [light.matrixWorld.elements[12], light.matrixWorld.elements[13], light.matrixWorld.elements[14]]
-            : [0, 10, 0];
-        let targetPos = [0, 0, 0];
-        if (light.target?.matrixWorld) {
-            const te = light.target.matrixWorld.elements;
-            targetPos = [te[12], te[13], te[14]];
-        }
+        const pos = positionFromMatrix(light.matrixWorld, 'DirectionalLight.matrixWorld', [0, 10, 0]);
+        const targetPos = positionFromMatrix(lightTargetMatrix(light, 'DirectionalLight.target'), 'DirectionalLight.target.matrixWorld', [0, 0, 0]);
         const direction = [
             targetPos[0] - pos[0],
             targetPos[1] - pos[1],
@@ -54,56 +54,31 @@ function extractLight(light) {
             position: pos,
             direction,
         };
-        if (light.castShadow === true) {
-            const shadow = light.shadow;
-            const mapSize = shadow?.mapSize;
-            const size = Math.max(32, Math.floor(mapSize?.x ?? mapSize?.width ?? 512));
-            const cam = shadow?.camera;
+        if (optionalBoolean(light.castShadow, 'light.castShadow') === true) {
             out.castShadow = true;
-            out.shadowMapSize = size;
-            if (Number.isFinite(shadow?.bias))
-                out.shadowBias = shadow.bias;
-            if (Number.isFinite(shadow?.normalBias))
-                out.shadowNormalBias = shadow.normalBias;
-            if (cam) {
-                if (Number.isFinite(cam.left))
-                    out.shadowCameraLeft = cam.left;
-                if (Number.isFinite(cam.right))
-                    out.shadowCameraRight = cam.right;
-                if (Number.isFinite(cam.top))
-                    out.shadowCameraTop = cam.top;
-                if (Number.isFinite(cam.bottom))
-                    out.shadowCameraBottom = cam.bottom;
-                if (Number.isFinite(cam.near))
-                    out.shadowCameraNear = cam.near;
-                if (Number.isFinite(cam.far))
-                    out.shadowCameraFar = cam.far;
-            }
+            applyShadowOptions(out, light);
         }
         return out;
     }
     if (light.isPointLight === true) {
-        const pos = light.matrixWorld
-            ? [light.matrixWorld.elements[12], light.matrixWorld.elements[13], light.matrixWorld.elements[14]]
-            : [0, 0, 0];
-        return {
+        const pos = positionFromMatrix(light.matrixWorld, 'PointLight.matrixWorld', [0, 0, 0]);
+        const out = {
             lightType: 'point',
             color: [color[0], color[1], color[2]],
             intensity,
             position: pos,
-            distance: Number.isFinite(light.distance) ? light.distance : 0,
-            decay: Number.isFinite(light.decay) ? light.decay : 2,
+            distance: nonNegativeFiniteNumberOrDefault(light.distance, 'PointLight.distance', 0),
+            decay: nonNegativeFiniteNumberOrDefault(light.decay, 'PointLight.decay', 2),
         };
+        if (optionalBoolean(light.castShadow, 'light.castShadow') === true) {
+            out.castShadow = true;
+            applyShadowOptions(out, light);
+        }
+        return out;
     }
     if (light.isSpotLight === true) {
-        const pos = light.matrixWorld
-            ? [light.matrixWorld.elements[12], light.matrixWorld.elements[13], light.matrixWorld.elements[14]]
-            : [0, 0, 0];
-        let targetPos = [0, 0, 0];
-        if (light.target?.matrixWorld) {
-            const te = light.target.matrixWorld.elements;
-            targetPos = [te[12], te[13], te[14]];
-        }
+        const pos = positionFromMatrix(light.matrixWorld, 'SpotLight.matrixWorld', [0, 0, 0]);
+        const targetPos = positionFromMatrix(lightTargetMatrix(light, 'SpotLight.target'), 'SpotLight.target.matrixWorld', [0, 0, 0]);
         const direction = [
             targetPos[0] - pos[0],
             targetPos[1] - pos[1],
@@ -115,24 +90,52 @@ function extractLight(light) {
             direction[1] /= len;
             direction[2] /= len;
         }
-        return {
+        const out = {
             lightType: 'spot',
             color: [color[0], color[1], color[2]],
             intensity,
             position: pos,
             direction,
-            distance: Number.isFinite(light.distance) ? light.distance : 0,
-            decay: Number.isFinite(light.decay) ? light.decay : 2,
-            angle: Number.isFinite(light.angle) ? light.angle : Math.PI / 3,
-            penumbra: Number.isFinite(light.penumbra) ? light.penumbra : 0,
+            distance: nonNegativeFiniteNumberOrDefault(light.distance, 'SpotLight.distance', 0),
+            decay: nonNegativeFiniteNumberOrDefault(light.decay, 'SpotLight.decay', 2),
+            angle: spotAngleOrDefault(light.angle),
+            penumbra: normalizedFiniteNumberOrDefault(light.penumbra, 'SpotLight.penumbra', 0),
+        };
+        if (optionalBoolean(light.castShadow, 'light.castShadow') === true) {
+            out.castShadow = true;
+            applyShadowOptions(out, light);
+        }
+        return out;
+    }
+    if (light.isRectAreaLight === true) {
+        const matrix = matrixElementsOrUndefined(light.matrixWorld, 'RectAreaLight.matrixWorld');
+        const pos = matrix ? [matrix[12], matrix[13], matrix[14]] : [0, 0, 0];
+        let direction = [0, 0, -1];
+        if (matrix) {
+            direction = [-matrix[8], -matrix[9], -matrix[10]];
+        }
+        const len = Math.sqrt(direction[0] ** 2 + direction[1] ** 2 + direction[2] ** 2);
+        if (len > 0) {
+            direction[0] /= len;
+            direction[1] /= len;
+            direction[2] /= len;
+        }
+        return {
+            lightType: 'rectArea',
+            color: [color[0], color[1], color[2]],
+            intensity,
+            position: pos,
+            direction,
+            width: positiveFiniteNumberOrDefault(light.width, 'RectAreaLight.width', 10),
+            height: positiveFiniteNumberOrDefault(light.height, 'RectAreaLight.height', 10),
         };
     }
     if (light.isHemisphereLight === true) {
-        const groundColor = (0, color_1.colorLikeToArray)(light.groundColor) ?? [0.04, 0.02, 0.0, 1];
+        const groundColor = (0, color_1.validatedColorLikeToArray)(light.groundColor, 'HemisphereLight.groundColor') ?? [0.04, 0.02, 0.0, 1];
         let direction = [0, 1, 0];
-        if (light.matrixWorld) {
-            const e = light.matrixWorld.elements;
-            const ux = e[4], uy = e[5], uz = e[6];
+        const matrix = matrixElementsOrUndefined(light.matrixWorld, 'HemisphereLight.matrixWorld');
+        if (matrix) {
+            const ux = matrix[4], uy = matrix[5], uz = matrix[6];
             const ulen = Math.sqrt(ux * ux + uy * uy + uz * uz);
             if (ulen > 0) {
                 direction = [ux / ulen, uy / ulen, uz / ulen];
@@ -149,10 +152,332 @@ function extractLight(light) {
     // AmbientLight is handled separately
     return null;
 }
-function extractAmbientLight(scene) {
+function positionFromMatrix(matrix, label, fallback) {
+    const elements = matrixElementsOrUndefined(matrix, label);
+    return elements ? [elements[12], elements[13], elements[14]] : fallback;
+}
+function matrixElementsOrUndefined(matrix, label) {
+    return matrix ? (0, math_1.matrixElements)(matrix, label) : undefined;
+}
+function lightTargetMatrix(light, label) {
+    const target = light.target;
+    if (target == null)
+        return undefined;
+    if (typeof target !== 'object' || Array.isArray(target)) {
+        throw new TypeError(`${label} must be an object.`);
+    }
+    return target.matrixWorld;
+}
+function applyShadowOptions(out, light) {
+    const shadow = light.shadow;
+    assertShadowContainerLike(shadow);
+    const mapSize = shadowMapSizeOrDefault(shadow?.mapSize, light);
+    out.shadowMapSize = Math.max(mapSize.width, mapSize.height);
+    out.shadowMapWidth = mapSize.width;
+    out.shadowMapHeight = mapSize.height;
+    optionalBoolean(shadow?.autoUpdate, 'light.shadow.autoUpdate');
+    optionalBoolean(shadow?.needsUpdate, 'light.shadow.needsUpdate');
+    validateShadowObjectState(shadow?.map, 'light.shadow.map');
+    validateShadowObjectState(shadow?.mapPass, 'light.shadow.mapPass');
+    if (shadow?.matrix != null)
+        (0, math_1.matrixElements)(shadow.matrix, 'light.shadow.matrix');
+    const bias = optionalFiniteNumber(shadow?.bias, 'light.shadow.bias');
+    const normalBias = optionalFiniteNumber(shadow?.normalBias, 'light.shadow.normalBias');
+    const radius = optionalNonNegativeFiniteNumber(shadow?.radius, 'light.shadow.radius');
+    const intensity = optionalNonNegativeFiniteNumber(shadow?.intensity, 'light.shadow.intensity');
+    const blurSamples = optionalNonNegativeFiniteNumber(shadow?.blurSamples, 'light.shadow.blurSamples');
+    if (bias !== undefined)
+        out.shadowBias = bias;
+    if (normalBias !== undefined)
+        out.shadowNormalBias = normalBias;
+    if (radius !== undefined)
+        out.shadowRadius = radius;
+    if (intensity !== undefined)
+        out.shadowIntensity = intensity;
+    if (blurSamples !== undefined)
+        out.shadowBlurSamples = blurSamples;
+    const cam = shadow?.camera;
+    if (cam != null) {
+        assertPlainObject(cam, 'light.shadow.camera');
+        const bounds = shadowCameraOrthoBounds(cam, out);
+        const clipDistances = shadowCameraClipDistances(cam, out);
+        if (bounds.shadowCameraLeft !== undefined)
+            out.shadowCameraLeft = bounds.shadowCameraLeft;
+        if (bounds.shadowCameraRight !== undefined)
+            out.shadowCameraRight = bounds.shadowCameraRight;
+        if (bounds.shadowCameraTop !== undefined)
+            out.shadowCameraTop = bounds.shadowCameraTop;
+        if (bounds.shadowCameraBottom !== undefined)
+            out.shadowCameraBottom = bounds.shadowCameraBottom;
+        if (clipDistances.shadowCameraNear !== undefined)
+            out.shadowCameraNear = clipDistances.shadowCameraNear;
+        if (clipDistances.shadowCameraFar !== undefined)
+            out.shadowCameraFar = clipDistances.shadowCameraFar;
+    }
+    applyShadowCascadeOptions(out, light);
+}
+function shadowCameraClipDistances(camera, light) {
+    const near = optionalFiniteNumber(camera.near, 'light.shadow.camera.near');
+    const far = optionalFiniteNumber(camera.far, 'light.shadow.camera.far');
+    if (near !== undefined && near < 0) {
+        throw new TypeError('light.shadow.camera.near must be non-negative.');
+    }
+    if (near === 0 && (light.lightType === 'point' || light.lightType === 'spot')) {
+        throw new TypeError('light.shadow.camera.near must be positive for point and spot shadows.');
+    }
+    if (far !== undefined && far <= 0) {
+        throw new TypeError('light.shadow.camera.far must be positive.');
+    }
+    const effectiveNear = near ?? 0.5;
+    const effectiveFar = far ?? defaultShadowCameraFar(light);
+    if (effectiveFar <= effectiveNear) {
+        if (far !== undefined) {
+            throw new TypeError('light.shadow.camera.far must be greater than light.shadow.camera.near.');
+        }
+        throw new TypeError('light.shadow.camera.near must be less than the effective light.shadow.camera.far.');
+    }
+    return { shadowCameraNear: near, shadowCameraFar: far };
+}
+function defaultShadowCameraFar(light) {
+    return light.lightType === 'point' && light.distance !== undefined && light.distance > 0
+        ? light.distance
+        : 500;
+}
+function shadowCameraOrthoBounds(camera, light) {
+    const left = optionalFiniteNumber(camera.left, 'light.shadow.camera.left');
+    const right = optionalFiniteNumber(camera.right, 'light.shadow.camera.right');
+    const top = optionalFiniteNumber(camera.top, 'light.shadow.camera.top');
+    const bottom = optionalFiniteNumber(camera.bottom, 'light.shadow.camera.bottom');
+    if (light.lightType === 'directional') {
+        const effectiveLeft = left ?? -5;
+        const effectiveRight = right ?? 5;
+        const effectiveTop = top ?? 5;
+        const effectiveBottom = bottom ?? -5;
+        if (effectiveRight <= effectiveLeft) {
+            if (right !== undefined) {
+                throw new TypeError('light.shadow.camera.right must be greater than light.shadow.camera.left.');
+            }
+            throw new TypeError('light.shadow.camera.left must be less than the effective light.shadow.camera.right.');
+        }
+        if (effectiveTop <= effectiveBottom) {
+            if (top !== undefined) {
+                throw new TypeError('light.shadow.camera.top must be greater than light.shadow.camera.bottom.');
+            }
+            throw new TypeError('light.shadow.camera.bottom must be less than the effective light.shadow.camera.top.');
+        }
+    }
+    return {
+        shadowCameraLeft: left,
+        shadowCameraRight: right,
+        shadowCameraTop: top,
+        shadowCameraBottom: bottom,
+    };
+}
+function shadowMapSizeOrDefault(mapSize, light) {
+    if (mapSize != null) {
+        assertPlainObject(mapSize, 'light.shadow.mapSize');
+    }
+    const width = shadowMapSizeComponent(mapSize, 'x', 'width');
+    const height = shadowMapSizeComponent(mapSize, 'y', 'height');
+    const resolvedWidth = Math.max(32, Math.floor(width ?? height ?? 512));
+    const resolvedHeight = Math.max(32, Math.floor(height ?? width ?? 512));
+    if (light.isPointLight === true && resolvedWidth !== resolvedHeight) {
+        throw new Error(`Non-square PointLight shadow map sizes are not supported by @headless-three/renderer yet (${resolvedWidth}x${resolvedHeight}). Use square point-light shadow maps until rectangular cube-face shadows are supported.`);
+    }
+    return { width: resolvedWidth, height: resolvedHeight };
+}
+function assertShadowContainerLike(shadow) {
+    if (shadow == null)
+        return;
+    assertPlainObject(shadow, 'light.shadow');
+}
+function validateShadowObjectState(value, label) {
+    if (value == null)
+        return;
+    assertPlainObject(value, label);
+}
+function assertPlainObject(value, label) {
+    if (value !== null && typeof value === 'object' && !Array.isArray(value))
+        return;
+    throw new TypeError(`${label} must be an object.`);
+}
+function shadowMapSizeComponent(mapSize, vectorKey, dimensionKey) {
+    if (!mapSize)
+        return undefined;
+    const vectorValue = mapSize[vectorKey];
+    if (vectorValue != null)
+        return optionalPositiveFiniteNumber(vectorValue, `light.shadow.mapSize.${vectorKey}`);
+    return optionalPositiveFiniteNumber(mapSize[dimensionKey], `light.shadow.mapSize.${dimensionKey}`);
+}
+function applyShadowCascadeOptions(out, light) {
+    const cascadeHints = shadowCascadeHints(light);
+    if (!cascadeHints)
+        return;
+    const { value: cascades, label } = cascadeHints;
+    if (!Array.isArray(cascades)) {
+        throw new TypeError(`${label} must be an array of shadow cascade hint objects.`);
+    }
+    if (cascades.length < 2)
+        return;
+    const splits = [];
+    const bounds = [];
+    for (let i = 0; i < cascades.length; i += 1) {
+        const rawCascade = cascades[i];
+        if (!rawCascade || typeof rawCascade !== 'object') {
+            throw new TypeError(`shadowCascades[${i}] must be an object with finite left, right, top, bottom, near, and far values.`);
+        }
+        const cascade = rawCascade;
+        const label = `shadowCascades[${i}]`;
+        const left = requiredFiniteNumber(cascade.left, `${label}.left`);
+        const right = requiredFiniteNumber(cascade.right, `${label}.right`);
+        const top = requiredFiniteNumber(cascade.top, `${label}.top`);
+        const bottom = requiredFiniteNumber(cascade.bottom, `${label}.bottom`);
+        const near = requiredFiniteNumber(cascade.near, `${label}.near`);
+        const far = requiredFiniteNumber(cascade.far, `${label}.far`);
+        if (bounds.length / 6 >= MAX_SHADOW_CASCADES) {
+            throw new Error(`Directional shadow cascade hints support at most ${MAX_SHADOW_CASCADES} valid cascades in @headless-three/renderer. Reduce light.userData.headlessThreeRenderer.shadowCascades or render separate shadow passes.`);
+        }
+        bounds.push(left, right, top, bottom, near, far);
+        const split = shadowCascadeSplit(cascade, label);
+        if (split !== undefined)
+            splits.push(split);
+    }
+    const count = bounds.length / 6;
+    if (count >= 2) {
+        out.shadowCascadeBounds = bounds;
+        out.shadowCascadeSplits = splits.slice(0, count - 1);
+    }
+}
+function shadowCascadeHints(light) {
+    const userData = light.userData;
+    if (userData != null && (typeof userData !== 'object' || Array.isArray(userData))) {
+        throw new TypeError('light.userData must be an object.');
+    }
+    const modernHints = userData?.headlessThreeRenderer;
+    if (modernHints != null) {
+        assertPlainObject(modernHints, 'light.userData.headlessThreeRenderer');
+        if (modernHints.shadowCascades != null) {
+            return {
+                value: modernHints.shadowCascades,
+                label: 'light.userData.headlessThreeRenderer.shadowCascades',
+            };
+        }
+        if (modernHints.cascades != null) {
+            return {
+                value: modernHints.cascades,
+                label: 'light.userData.headlessThreeRenderer.cascades',
+            };
+        }
+    }
+    const legacyHints = userData?.headlessRenderer;
+    if (legacyHints != null) {
+        assertPlainObject(legacyHints, 'light.userData.headlessRenderer');
+        if (legacyHints.shadowCascades != null) {
+            return {
+                value: legacyHints.shadowCascades,
+                label: 'light.userData.headlessRenderer.shadowCascades',
+            };
+        }
+        if (legacyHints.cascades != null) {
+            return {
+                value: legacyHints.cascades,
+                label: 'light.userData.headlessRenderer.cascades',
+            };
+        }
+    }
+    const shadowCascades = light.shadow?.cascades;
+    return shadowCascades != null
+        ? { value: shadowCascades, label: 'light.shadow.cascades' }
+        : null;
+}
+function shadowCascadeSplit(cascade, label) {
+    if (cascade.split != null)
+        return optionalFiniteNumber(cascade.split, `${label}.split`);
+    if (cascade.distance != null)
+        return optionalFiniteNumber(cascade.distance, `${label}.distance`);
+    return optionalFiniteNumber(cascade.farDistance, `${label}.farDistance`);
+}
+function finiteNumberOrDefault(value, label, fallback) {
+    if (value == null)
+        return fallback;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    throw new TypeError(`${label} must be a finite number.`);
+}
+function nonNegativeFiniteNumberOrDefault(value, label, fallback) {
+    const number = finiteNumberOrDefault(value, label, fallback);
+    if (number < 0) {
+        throw new TypeError(`${label} must be non-negative.`);
+    }
+    return number;
+}
+function positiveFiniteNumberOrDefault(value, label, fallback) {
+    const number = finiteNumberOrDefault(value, label, fallback);
+    if (number <= 0) {
+        throw new TypeError(`${label} must be positive.`);
+    }
+    return number;
+}
+function normalizedFiniteNumberOrDefault(value, label, fallback) {
+    const number = finiteNumberOrDefault(value, label, fallback);
+    if (number < 0 || number > 1) {
+        throw new TypeError(`${label} must be between 0 and 1.`);
+    }
+    return number;
+}
+function spotAngleOrDefault(value) {
+    const angle = finiteNumberOrDefault(value, 'SpotLight.angle', Math.PI / 3);
+    if (angle < 0 || angle > Math.PI / 2) {
+        throw new TypeError('SpotLight.angle must be between 0 and Math.PI / 2.');
+    }
+    return angle;
+}
+function optionalFiniteNumber(value, label) {
+    if (value == null)
+        return undefined;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    throw new TypeError(`${label} must be a finite number.`);
+}
+function optionalNonNegativeFiniteNumber(value, label) {
+    const number = optionalFiniteNumber(value, label);
+    if (number === undefined)
+        return undefined;
+    if (number < 0) {
+        throw new TypeError(`${label} must be non-negative.`);
+    }
+    return number;
+}
+function optionalBoolean(value, label) {
+    if (value == null)
+        return undefined;
+    if (typeof value === 'boolean')
+        return value;
+    throw new TypeError(`${label} must be a boolean.`);
+}
+function optionalPositiveFiniteNumber(value, label) {
+    const number = optionalFiniteNumber(value, label);
+    if (number === undefined)
+        return undefined;
+    if (number <= 0) {
+        throw new TypeError(`${label} must be positive.`);
+    }
+    return number;
+}
+function requiredFiniteNumber(value, label) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    throw new TypeError(`${label} must be a finite number.`);
+}
+function assertSupportedLightCount(lights) {
+    if (lights.length > MAX_NATIVE_LIGHTS) {
+        throw new Error(`More than ${MAX_NATIVE_LIGHTS} visible non-ambient lights are not supported by @headless-three/renderer yet (${lights.length} found). Keep the closest/brightest ${MAX_NATIVE_LIGHTS} lights, bake lighting, or render separate passes until native light arrays are expanded.`);
+    }
+}
+function extractAmbientLight(scene, camera) {
     let color = null;
-    visitForAmbient(scene, (light) => {
-        const c = (0, color_1.colorLikeToArray)(light.color) ?? [1, 1, 1, 1];
+    visitForAmbient(scene, camera, (light) => {
+        const c = (0, color_1.validatedColorLikeToArray)(light.color, 'AmbientLight.color') ?? [1, 1, 1, 1];
         if (!color) {
             color = [c[0], c[1], c[2]];
         }
@@ -164,23 +489,94 @@ function extractAmbientLight(scene) {
     });
     return color;
 }
-function extractAmbientIntensity(scene) {
+function extractAmbientIntensity(scene, camera) {
     let intensity = 0;
-    visitForAmbient(scene, (light) => {
-        intensity += Number.isFinite(light.intensity) ? light.intensity : 1;
+    visitForAmbient(scene, camera, (light) => {
+        intensity += finiteNumberOrDefault(light.intensity, 'AmbientLight.intensity', 1);
     });
     return intensity > 0 ? intensity : undefined;
 }
-function visitForAmbient(object, callback) {
+function extractLightProbe(scene, camera) {
+    const coefficients = new Array(27).fill(0);
+    let found = false;
+    visitForLightProbe(scene, camera, (light) => {
+        const source = light.sh?.coefficients;
+        if (source == null)
+            return;
+        if (!Array.isArray(source)) {
+            throw new TypeError('LightProbe.sh.coefficients must be an array of 9 coefficients.');
+        }
+        if (source.length < 9) {
+            throw new TypeError('LightProbe.sh.coefficients must contain 9 coefficients.');
+        }
+        const intensity = finiteNumberOrDefault(light.intensity, 'LightProbe.intensity', 1);
+        for (let i = 0; i < 9; i += 1) {
+            const coefficient = coefficientToRgb(source[i], `LightProbe.sh.coefficients[${i}]`);
+            if (!coefficient)
+                continue;
+            coefficients[i * 3] += coefficient[0] * intensity;
+            coefficients[i * 3 + 1] += coefficient[1] * intensity;
+            coefficients[i * 3 + 2] += coefficient[2] * intensity;
+        }
+        found = true;
+    });
+    return found ? coefficients : null;
+}
+function visitForLightProbe(object, camera, callback) {
+    if (!object)
+        return;
+    if (optionalBoolean(object.visible, 'object.visible') === false)
+        return;
+    if (object.isLightProbe === true && (0, layers_1.objectLayersMatchCamera)(object, camera))
+        callback(object);
+    for (const child of (0, objects_1.objectChildren)(object)) {
+        visitForLightProbe(child, camera, callback);
+    }
+}
+function coefficientToRgb(value, label) {
+    if (!value)
+        return null;
+    const maybeArrayLike = value;
+    if (Array.isArray(value) || (ArrayBuffer.isView(value) && typeof maybeArrayLike.length === 'number')) {
+        const array = value;
+        return [
+            requiredFiniteRgbComponent(array[0], `${label}[0]`),
+            requiredFiniteRgbComponent(array[1], `${label}[1]`),
+            requiredFiniteRgbComponent(array[2], `${label}[2]`),
+        ];
+    }
+    const v = value;
+    if ('r' in v || 'g' in v || 'b' in v) {
+        return [
+            requiredFiniteRgbComponent(v.r, `${label}.r`),
+            requiredFiniteRgbComponent(v.g, `${label}.g`),
+            requiredFiniteRgbComponent(v.b, `${label}.b`),
+        ];
+    }
+    if ('x' in v || 'y' in v || 'z' in v) {
+        return [
+            requiredFiniteRgbComponent(v.x, `${label}.x`),
+            requiredFiniteRgbComponent(v.y, `${label}.y`),
+            requiredFiniteRgbComponent(v.z, `${label}.z`),
+        ];
+    }
+    return null;
+}
+function requiredFiniteRgbComponent(value, label) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new TypeError(`${label} must be a finite number.`);
+    }
+    return value;
+}
+function visitForAmbient(object, camera, callback) {
     if (!object)
         return;
-    if (object.visible === false)
+    if (optionalBoolean(object.visible, 'object.visible') === false)
         return;
-    if (object.isAmbientLight === true)
+    if (object.isAmbientLight === true && (0, layers_1.objectLayersMatchCamera)(object, camera))
         callback(object);
-    const children = Array.isArray(object.children) ? object.children : [];
-    for (const child of children) {
-        visitForAmbient(child, callback);
+    for (const child of (0, objects_1.objectChildren)(object)) {
+        visitForAmbient(child, camera, callback);
     }
 }
 //# sourceMappingURL=lights.js.map