three-cad-viewer 4.1.2 → 4.2.0

package/dist/core/viewer.d.ts

@@ -4,7 +4,7 @@ declare global {
         THREE?: typeof THREE;
     }
 }
-import { NestedGroup } from "../scene/nestedgroup.js";
+import { NestedGroup, ObjectGroup } from "../scene/nestedgroup.js";
 import { Grid } from "../scene/grid.js";
 import { AxesHelper } from "../scene/axes.js";
 import { OrientationMarker } from "../scene/orientation.js";
@@ -23,7 +23,7 @@ import { PickedObject, Raycaster } from "../rendering/raycast.js";
 import { ViewerState } from "./viewer-state.js";
 import type { Display } from "../ui/display.js";
 import type { Vector3Tuple, QuaternionTuple } from "three";
-import { CollapseState, type ZebraColorScheme, type ZebraMappingMode, type NotificationCallback, type RenderOptions, type ViewerOptions, type Shapes, type VisibilityState, type ActiveTab, type Axis, type ClipIndex, type ThemeInput, type BoundingBoxFlat, type Keymap } from "./types.js";
+import { CollapseState, type ZebraColorScheme, type ZebraMappingMode, type StudioToneMapping, type StudioTextureMapping, type StudioBackground, type NotificationCallback, type RenderOptions, type ViewerOptions, type Shapes, type VisibilityState, type ActiveTab, type Axis, type ClipIndex, type ThemeInput, type BoundingBoxFlat, type Keymap } from "./types.js";
 /**
  * Material settings for the viewer.
  */
@@ -97,6 +97,8 @@ interface DisplayOptionsInternal {
     zebraTool?: boolean;
     glass?: boolean;
     tools?: boolean;
+    canvas?: HTMLCanvasElement;
+    gl?: WebGLRenderingContext | WebGL2RenderingContext;
     keymap?: KeymapConfig;
     [key: string]: unknown;
 }
@@ -161,6 +163,8 @@ declare class Viewer {
     ready: boolean;
     display: Display;
     renderer: THREE.WebGLRenderer;
+    private _externalGl;
+    onAfterRender: (() => void) | null;
     mouse: THREE.Vector2;
     cadTools: Tools;
     animation: Animation;
@@ -199,6 +203,9 @@ declare class Viewer {
     expandedNestedGroup: NestedGroup | null;
     compactNestedGroup: NestedGroup | null;
     raycaster: Raycaster | null;
+    private _studioManager;
+    /** Environment manager — proxied from StudioManager for display.ts access. */
+    get envManager(): import("../index.js").EnvironmentManager;
     zScale: number;
     clipNormal0: Vector3Tuple | null;
     clipNormal1: Vector3Tuple | null;
@@ -379,7 +386,7 @@ declare class Viewer {
     toggleGroup(expanded: boolean): void;
     /**
      * Set the active sidebar tab.
-     * @param tabName - Tab name: "tree", "clip", "material", or "zebra"
+     * @param tabName - Tab name: "tree", "clip", "material", "zebra", or "studio"
      * @param notify - whether to send notification or not.
      */
     setActiveTab(tabName: ActiveTab, notify?: boolean): void;
@@ -525,7 +532,7 @@ declare class Viewer {
      * @param nodeType - node type
      * @param tree - whether from tree
      */
-    handlePick: (path: string, name: string, meta: boolean, shift: boolean, _alt: boolean, point: THREE.Vector3 | null, nodeType?: string | null, tree?: boolean) => void;
+    handlePick: (path: string, name: string, meta: boolean, shift: boolean, alt: boolean, point: THREE.Vector3 | null, nodeType?: string | null, tree?: boolean) => void;
     setPickHandler(flag: boolean): void;
     /**
      * Find the shape that was double clicked and send notification
@@ -749,6 +756,11 @@ declare class Viewer {
      * @param value - The mapping mode ("reflection", "normal").
      */
     setZebraMappingMode: (value: ZebraMappingMode) => void;
+    /**
+     * Resets zebra tool settings to defaults: count=9, opacity=1, direction=0,
+     * colorScheme=blackwhite, mappingMode=reflection.
+     */
+    resetZebra: () => void;
     /**
      * Gets the current stripe count value.
      * @returns The stripe count (2-50).
@@ -774,6 +786,173 @@ declare class Viewer {
      * @returns The mapping mode ("reflection", "normal").
      */
     getZebraMappingMode: () => ZebraMappingMode;
+    /**
+     * Sets the studio environment preset.
+     * @param value - The environment name ("studio", "neutral", "outdoor", "none", or custom HDR URL).
+     * @param notify - Whether to notify about the changes.
+     * @public
+     */
+    setStudioEnvironment: (value: string, notify?: boolean) => void;
+    /**
+     * Sets the studio environment intensity.
+     * @param value - The environment intensity (0-3).
+     * @param notify - Whether to notify about the changes.
+     * @public
+     */
+    setStudioEnvIntensity: (value: number, notify?: boolean) => void;
+    /**
+     * Sets the background mode for Studio mode.
+     * @param value - The background mode ("grey", "white", "gradient", "environment", or "transparent").
+     * @param notify - Whether to notify about the changes.
+     * @public
+     */
+    setStudioBackground: (value: StudioBackground, notify?: boolean) => void;
+    /**
+     * Sets the tone mapping mode for Studio mode.
+     * @param value - The tone mapping mode ("neutral", "ACES", or "none").
+     * @param notify - Whether to notify about the changes.
+     * @public
+     */
+    setStudioToneMapping: (value: StudioToneMapping, notify?: boolean) => void;
+    /**
+     * Sets the exposure value for Studio mode.
+     * @param value - The exposure value (0-2).
+     * @param notify - Whether to notify about the changes.
+     * @public
+     */
+    setStudioExposure: (value: number, notify?: boolean) => void;
+    /**
+     * Sets whether 4K environment maps are used (default: 2K).
+     * @param value - True for 4K, false for 2K.
+     * @param notify - Whether to notify about the changes.
+     * @public
+     */
+    setStudio4kEnvMaps: (value: boolean, notify?: boolean) => void;
+    /**
+     * Gets whether 4K environment maps are enabled.
+     * @returns True for 4K, false for 2K.
+     * @public
+     */
+    getStudio4kEnvMaps: () => boolean;
+    /**
+     * Sets the environment rotation for Studio mode.
+     * @param value - The rotation in degrees (0-360).
+     * @param notify - Whether to notify about the changes.
+     * @public
+     */
+    setStudioEnvRotation: (value: number, notify?: boolean) => void;
+    /**
+     * Gets the current environment rotation for Studio mode.
+     * @returns The rotation in degrees (0-360).
+     * @public
+     */
+    getStudioEnvRotation: () => number;
+    /**
+     * Sets the texture mapping mode for Studio mode.
+     * @param value - The texture mapping mode ("triplanar" or "parametric").
+     * @param notify - Whether to notify about the changes.
+     * @public
+     */
+    setStudioTextureMapping: (value: StudioTextureMapping, notify?: boolean) => void;
+    /**
+     * Gets the current texture mapping mode for Studio mode.
+     * @returns The texture mapping mode ("triplanar" or "parametric").
+     * @public
+     */
+    getStudioTextureMapping: () => StudioTextureMapping;
+    /**
+     * Gets the current studio environment preset.
+     * @returns The environment name ("studio", "neutral", "outdoor", "none", or custom HDR URL).
+     * @public
+     */
+    getStudioEnvironment: () => string;
+    /**
+     * Gets the current studio environment intensity.
+     * @returns The environment intensity (0-3).
+     * @public
+     */
+    getStudioEnvIntensity: () => number;
+    /**
+     * Gets the current background mode for Studio mode.
+     * @returns The background mode ("grey", "white", "gradient", "environment", or "transparent").
+     * @public
+     */
+    getStudioBackground: () => StudioBackground;
+    /**
+     * Gets the current tone mapping mode for Studio mode.
+     * @returns The tone mapping mode ("neutral", "ACES", or "none").
+     * @public
+     */
+    getStudioToneMapping: () => StudioToneMapping;
+    /**
+     * Gets the current exposure value for Studio mode.
+     * @returns The exposure value (0-3).
+     * @public
+     */
+    getStudioExposure: () => number;
+    /**
+     * Sets the shadow intensity in Studio mode.
+     * A value of 0 disables shadows; values > 0 enable them at that darkness.
+     * @param value - The shadow intensity (0-1).
+     * @param notify - Whether to notify about the changes.
+     * @public
+     */
+    setStudioShadowIntensity: (value: number, notify?: boolean) => void;
+    /**
+     * Gets the current shadow intensity in Studio mode.
+     * @returns The shadow intensity (0-1). 0 means shadows are off.
+     * @public
+     */
+    getStudioShadowIntensity: () => number;
+    /**
+     * Sets the shadow softness in Studio mode.
+     * Controls PCSS penumbra width (virtual light source size).
+     * @param value - The shadow softness (0-1).
+     * @param notify - Whether to notify about the changes.
+     * @public
+     */
+    setStudioShadowSoftness: (value: number, notify?: boolean) => void;
+    /**
+     * Gets the current shadow softness in Studio mode.
+     * @returns The shadow softness (0-1).
+     * @public
+     */
+    getStudioShadowSoftness: () => number;
+    /**
+     * Sets the ambient occlusion intensity in Studio mode.
+     * A value of 0 disables AO; values > 0 enable it at that intensity.
+     * @param value - The AO intensity (0-3.0).
+     * @param notify - Whether to notify about the changes.
+     * @public
+     */
+    setStudioAOIntensity: (value: number, notify?: boolean) => void;
+    /**
+     * Gets the current ambient occlusion intensity in Studio mode.
+     * @returns The AO intensity value (0.5-3.0).
+     * @public
+     */
+    getStudioAOIntensity: () => number;
+    /**
+     * Returns whether Studio mode is currently active.
+     * @returns True if Studio mode is active and the viewer has rendered content.
+     * @public
+     */
+    get isStudioActive(): boolean;
+    /**
+     * Get the ObjectGroup and path for the currently selected object in Studio mode.
+     * Returns null if nothing is selected, Studio mode is inactive, or the
+     * selection is a CompoundGroup (assembly node) rather than a leaf object.
+     */
+    getSelectedObjectGroup(): {
+        object: ObjectGroup;
+        path: string;
+    } | null;
+    /** Enter Studio mode. Called by display.ts switchToTab(). @internal */
+    enterStudioMode: () => Promise<void>;
+    /** Leave Studio mode. Called by display.ts switchToTab(). @internal */
+    leaveStudioMode: () => void;
+    /** Reset Studio settings to defaults. @public */
+    resetStudio: () => void;
     /**
      * Get ortho value as property (for ViewerLike interface compatibility).
      */
@@ -1157,6 +1336,11 @@ declare class Viewer {
      * @param notify - whether to send notification or not.
      */
     setClipSlider: (index: 0 | 1 | 2, value: number, notify?: boolean) => void;
+    /**
+     * Resets clip planes to default normals and slider positions.
+     * Normals reset to -X, -Y, -Z; sliders to gridSize/2; checkboxes unchecked.
+     */
+    resetClip: () => void;
     /**
      * Replace CadView with an inline png image of the canvas.
      *
@@ -1266,11 +1450,21 @@ declare class Viewer {
      */
     showHelp: (flag: boolean) => void;
     /**
-     * Show/hide the info panel.
-     * @param flag - whether to show the info panel
+     * Collapse or expand the info panel in glass mode.
+     * @param flag - true to show, false to collapse
      * @public
      */
+    showInfoPanel: (flag: boolean) => void;
+    /**
+     * @deprecated Use showInfoPanel() instead.
+     */
     showInfo: (flag: boolean) => void;
+    /**
+     * Collapse or expand the tools panel (tabs + content) in glass mode.
+     * @param flag - true to show, false to collapse
+     * @public
+     */
+    showToolsPanel: (flag: boolean) => void;
     /**
      * Show/hide the pinning button.
      * @param flag - whether to show the pinning button

package/dist/index.d.ts

@@ -10,15 +10,17 @@ import "../css/treeview.css";
 import "../css/tools.css";
 import { Viewer } from "./core/viewer.js";
 import { Display } from "./ui/display.js";
+import { EnvironmentManager } from "./rendering/environment.js";
 import { Timer } from "./utils/timer.js";
 import { logger } from "./utils/logger.js";
 import { gpuTracker } from "./utils/gpu-tracker.js";
 import { version } from "./_version.js";
-export { Viewer, Display, Timer, logger, gpuTracker, version };
+export { Viewer, Display, EnvironmentManager, Timer, logger, gpuTracker, version };
+export { MATERIAL_PRESETS, MATERIAL_PRESET_NAMES } from "./rendering/material-presets.js";
 export type { LogLevel } from "./utils/logger.js";
 export type { ResourceType, TrackedResource, ResourceSummary } from "./utils/gpu-tracker.js";
 export type { Vector3Tuple, QuaternionTuple } from "three";
-export type { ThemeInput, Theme, ControlType, UpDirection, AnimationMode, ActiveTab, ZebraColorScheme, ZebraMappingMode, ShapeType, ShapeSubtype, Axis, ClipIndex, ColorValue, RGBColor, AxisColors, AxisColorsFlatArray, } from "./core/types.js";
+export type { ThemeInput, Theme, ControlType, UpDirection, AnimationMode, ActiveTab, ZebraColorScheme, ZebraMappingMode, ShapeType, ShapeSubtype, Axis, ClipIndex, ColorValue, RGBColor, RGBAColor, AxisColors, AxisColorsFlatArray, } from "./core/types.js";
 export { CLIP_INDICES, isClipIndex, CollapseState } from "./core/types.js";
 export type { StateChange, StateSubscriber, GlobalStateSubscriber, } from "./core/types.js";
 export type { BoundingBox, BoundingSphere, BoundingBoxFlat, } from "./core/types.js";
@@ -30,4 +32,7 @@ export type { Texture, Shape, ShapeBinary, ShapeNested, Location, VisibilityValu
 export { isShapeBinaryFormat, hasTrianglesPerFace, hasSegmentsPerEdge, } from "./core/types.js";
 export type { DomEventCallback } from "./core/types.js";
 export type { ColoredMaterial } from "./core/types.js";
+export type { MaterialAppearance, MaterialXMaterial, TextureEntry, StudioOptions, StudioBackground, StudioModeOptions, StudioEnvironment, StudioToneMapping, StudioTextureMapping, } from "./core/types.js";
+export { isMaterialXMaterial } from "./core/types.js";
+export { isInstancedFormat, decodeInstancedFormat } from "./utils/decode-instances.js";
 export type { SubscribeOptions } from "./core/types.js";

package/dist/rendering/environment.d.ts

@@ -0,0 +1,239 @@
+import * as THREE from "three";
+import type { StudioEnvironment, StudioBackground } from "../core/types.js";
+import { type LightDetectionResult } from "./light-detection.js";
+/**
+ * Configuration options for EnvironmentManager.
+ */
+interface EnvironmentManagerOptions {
+    /** Override URLs for the "neutral" and "outdoor" HDR presets */
+    presetUrls?: Partial<Record<string, string>>;
+}
+/**
+ * Manages environment maps for Studio mode.
+ *
+ * Handles three tiers of environment sources:
+ * - **Tier 1 "studio"**: Procedural RoomEnvironment (bundled, zero network)
+ * - **Tier 2 "neutral"/"outdoor"**: HDR presets loaded from configurable CDN URLs
+ * - **Tier 3 custom URL**: User-provided HDR URL (same loading path as Tier 2)
+ *
+ * The environment map is used for IBL (image-based lighting) via
+ * `scene.environment`. The scene background is configurable via the
+ * `backgroundMode` parameter in `apply()` (grey, white, gradient,
+ * blurred environment, or transparent).
+ *
+ * Features:
+ * - PMREM generation and caching for all tiers
+ * - In-flight promise deduplication (prevents duplicate loads on rapid switching)
+ * - Lazy PMREMGenerator creation
+ * - Fallback to "studio" on HDR load failure
+ * - GPU resource tracking via gpuTracker
+ */
+declare class EnvironmentManager {
+    /** Cached PMREM render targets keyed by environment name or URL */
+    private _cache;
+    /** Cached light detection results keyed by environment name or URL */
+    private _lightDetectionCache;
+    /** In-flight load promises keyed by environment name or URL */
+    private _inflight;
+    /** Lazily-created PMREMGenerator instance */
+    private _pmremGenerator;
+    /** Resolved preset URLs (defaults merged with user overrides) */
+    private _presetUrls;
+    /** Whether 4K env maps are enabled (default false = 2K) */
+    private _use4k;
+    /** User-provided URL overrides from constructor */
+    private _userOverrides;
+    /** HDRLoader instance (created lazily on first HDR load) */
+    private _hdrLoader;
+    /** The last loaded PMREM texture (stateful — used by apply() for IBL) */
+    private _currentTexture;
+    /** Whether this manager has been disposed */
+    private _disposed;
+    /**
+     * Ortho env background workaround.
+     *
+     * Three.js cannot render PMREM/cubemap textures as scene.background with
+     * orthographic cameras (renders as a tiny rectangle). We work around this by
+     * rendering the env map to a render target using a virtual perspective camera,
+     * then setting that 2D texture as scene.background. A 2D texture background
+     * renders as a fullscreen quad regardless of camera projection, and the
+     * transmission pass (glass refraction) also sees it correctly.
+     */
+    private _bgScene;
+    private _bgCamera;
+    private _bgRenderTarget;
+    private _orthoEnvMainScene;
+    /** Whether the env background feature is active (ortho + environment background). */
+    private _envBackgroundActive;
+    /**
+     * Deferred-apply state: if apply() was called with backgroundMode "environment"
+     * while _currentTexture was null, store the arguments so loadEnvironment() can
+     * re-apply once the texture is ready.
+     */
+    private _deferredApply;
+    constructor(options?: EnvironmentManagerOptions);
+    /**
+     * Load or retrieve an environment map.
+     *
+     * Resolves the environment name to a loading strategy:
+     * - `"studio"` -- procedural RoomEnvironment via PMREMGenerator.fromScene()
+     * - `"neutral"` / `"outdoor"` -- HDR preset from configured CDN URL
+     * - `"none"` -- returns null (caller should call `remove()` instead)
+     * - Any other string -- treated as a custom HDR URL
+     *
+     * Results are cached. If a load is already in flight for the same key,
+     * the existing promise is returned (no duplicate loads).
+     *
+     * @param name - Environment preset name or custom HDR URL
+     * @param renderer - WebGL renderer (needed for PMREMGenerator)
+     * @returns PMREM texture, or null for "none"
+     */
+    loadEnvironment(name: StudioEnvironment | string, renderer: THREE.WebGLRenderer): Promise<THREE.Texture | null>;
+    /**
+     * Apply the current environment map to the scene.
+     *
+     * Sets `scene.environment` for PBR/IBL reflections and configures
+     * `scene.background` according to the selected background mode:
+     * - `"grey"`: Neutral grey color (default, clean product-shot look)
+     * - `"white"`: Pure white background (e-commerce / documentation style)
+     * - `"gradient"`: Radial vignette gradient (light grey center → darker edges)
+     * - `"environment"`: Blurred, dimmed PMREM environment as backdrop
+     *   (color-matched to IBL, eliminates edge-glow artifacts on reflective objects)
+     * - `"transparent"`: No background (canvas alpha shows through)
+     *
+     * @param scene - The Three.js scene to apply the environment to
+     * @param envIntensity - Environment intensity multiplier (0-3, default 1.0)
+     * @param backgroundMode - Background mode
+     * @param upIsZ - Whether the scene uses Z-up coordinates (default true)
+     * @param ortho - Whether the camera is orthographic (env background falls back to gradient)
+     * @param envRotationDeg - Environment map rotation in degrees (default 0)
+     */
+    apply(scene: THREE.Scene, envIntensity: number, backgroundMode?: StudioBackground, upIsZ?: boolean, ortho?: boolean, envRotationDeg?: number): void;
+    /**
+     * Remove environment map from the scene.
+     *
+     * Clears `scene.environment`, `scene.background`, and resets
+     * environment/background properties to defaults.
+     *
+     * @param scene - The Three.js scene to clear
+     */
+    remove(scene: THREE.Scene): void;
+    /**
+     * Switch between 2K and 4K environment map resolution.
+     *
+     * Rebuilds preset URLs, evicts cached HDR presets (so they reload at
+     * the new resolution), and reloads the current environment if one is
+     * active.
+     *
+     * @param use4k - True for 4K, false for 2K
+     * @param currentEnvName - The currently active environment name (to reload)
+     * @param renderer - WebGL renderer (needed for reload)
+     * @returns Promise that resolves when the new texture is ready
+     */
+    setUse4kEnvMaps(use4k: boolean, currentEnvName: string, renderer: THREE.WebGLRenderer): Promise<THREE.Texture | null>;
+    /** Whether 4K env maps are currently enabled. */
+    get use4kEnvMaps(): boolean;
+    /**
+     * Whether an environment name is a Poly Haven preset (resolution-switchable).
+     * Returns false for "studio", "none", and custom URLs.
+     */
+    isPreset(name: string): boolean;
+    /**
+     * Whether the render-to-texture env background path is currently active.
+     * When true, the caller must call updateEnvBackground() each frame.
+     */
+    get isEnvBackgroundActive(): boolean;
+    /**
+     * Get cached light detection result for an environment.
+     *
+     * @param envName - Environment name or URL (same key used in loadEnvironment)
+     * @returns Detection result, or null if not yet analyzed
+     */
+    getLightDetection(envName: string): LightDetectionResult | null;
+    /**
+     * Update the env background render target (ortho camera workaround).
+     *
+     * Renders the PMREM env map to a 2D render target using a fixed-FOV virtual
+     * perspective camera whose quaternion is synced with the main camera. The
+     * resulting 2D texture is set as the main scene's background, giving a
+     * world-space environment that tracks camera orbit — matching how
+     * scene.environment (IBL reflections) already behaves.
+     *
+     * Called every frame from the render loop when isEnvBackgroundActive is true.
+     * Only active in ortho mode (perspective uses native cubemap background).
+     *
+     * @param renderer - WebGL renderer
+     * @param mainCamera - The active camera whose orientation to match
+     */
+    updateEnvBackground(renderer: THREE.WebGLRenderer, mainCamera?: THREE.Camera): void;
+    /**
+     * Dispose all cached resources.
+     *
+     * Disposes all cached PMREM render targets (and their textures) and
+     * the PMREMGenerator. After disposal, this manager cannot be used again.
+     *
+     * Call this on `viewer.dispose()`, NOT on `viewer.clear()` --
+     * the EnvironmentManager survives shape data clearing because
+     * environments are independent of shape data.
+     */
+    dispose(): void;
+    /**
+     * Set up the env background: a separate scene with the PMREM texture
+     * as background and a fixed-FOV virtual perspective camera for rendering
+     * to a 2D target. Used only for ortho cameras (perspective uses native
+     * cubemap background).
+     */
+    private _setupEnvBackground;
+    /**
+     * Tear down the env background state.
+     */
+    private _teardownEnvBackground;
+    /**
+     * Resolve environment name to an HDR URL, if applicable.
+     *
+     * Returns null for "studio" (uses RoomEnvironment, no URL).
+     * Returns the preset URL for "neutral"/"outdoor".
+     * Returns the name itself for custom URLs.
+     */
+    private _resolveUrl;
+    /**
+     * Get or create the PMREMGenerator (lazy initialization).
+     */
+    private _ensurePmremGenerator;
+    /**
+     * Get or create the HDRLoader (lazy initialization).
+     */
+    private _ensureHdrLoader;
+    /**
+     * Internal load dispatcher.
+     *
+     * Routes to RoomEnvironment generation or HDR loading based on the name.
+     * On HDR failure, falls back to "studio" (RoomEnvironment).
+     */
+    private _load;
+    /**
+     * Generate PMREM texture from the procedural RoomEnvironment.
+     *
+     * This is synchronous (no network), fast (~70ms), and always available.
+     */
+    private _loadRoomEnvironment;
+    /**
+     * Load an HDR file and generate a PMREM texture from it.
+     *
+     * Uses HDRLoader to fetch the .hdr file, then PMREMGenerator.fromEquirectangular()
+     * to create the PMREM cubemap. The source equirectangular texture is disposed
+     * after PMREM generation. The PMREM texture itself serves as both the IBL
+     * environment and the background (in "environment" mode).
+     *
+     * @param url - URL of the .hdr file
+     * @param cacheKey - Cache key for the resulting PMREM render target
+     * @param renderer - WebGL renderer for PMREMGenerator
+     * @returns PMREM texture
+     * @throws If the HDR file cannot be loaded
+     */
+    private _loadHdr;
+}
+/** Dispose lazy-cached gradient textures (called from EnvironmentManager.dispose). */
+declare function disposeGradientTextures(): void;
+export { EnvironmentManager, disposeGradientTextures };
+export type { EnvironmentManagerOptions };

package/dist/rendering/light-detection.d.ts

@@ -0,0 +1,44 @@
+/**
+ * HDR environment map light source detection.
+ *
+ * Analyzes equirectangular HDR pixel data to find dominant light sources
+ * (softboxes in studio HDRs, sun in outdoor HDRs). Returns direction,
+ * intensity, and color for up to 2 lights, used to create shadow-casting
+ * DirectionalLights in Studio mode.
+ *
+ * Algorithm: downsample to 128x64 luminance grid → threshold at 10x median
+ * → flood-fill cluster → convert centroids to 3D direction vectors.
+ * Runs ~5-10ms on CPU, no GPU readback needed.
+ */
+/** A detected dominant light source from HDR analysis. */
+export interface DetectedLight {
+    /** Unit direction vector toward the light source (Y-up, before Z-up rotation). */
+    direction: [number, number, number];
+    /** Relative intensity (normalized, 0-1 range). */
+    intensity: number;
+    /** Linear RGB color of the light source (0-1 range). */
+    color: [number, number, number];
+}
+/** Result of light detection analysis. */
+export interface LightDetectionResult {
+    /** Detected light sources (0-2 entries). */
+    lights: DetectedLight[];
+    /** Whether the result came from actual HDR analysis (true) or a fallback (false). */
+    wasAnalyzed: boolean;
+}
+/**
+ * Detect dominant light sources from equirectangular HDR pixel data.
+ *
+ * @param data - Raw pixel data (Uint16Array for HalfFloat, or Float32Array)
+ * @param width - HDR image width in pixels
+ * @param height - HDR image height in pixels
+ * @returns Detection result with up to 2 lights
+ */
+export declare function detectDominantLights(data: Uint16Array | Float32Array, width: number, height: number): LightDetectionResult;
+/**
+ * Return hardcoded fallback lights for procedural RoomEnvironment.
+ *
+ * The RoomEnvironment has no raw HDR data to analyze. A single top-front
+ * light direction approximates its primary illumination.
+ */
+export declare function getDefaultLights(): LightDetectionResult;