three-cad-viewer 4.1.2 → 4.2.0

package/dist/rendering/material-factory.d.ts

@@ -1,6 +1,6 @@
 import * as THREE from "three";
 import { LineMaterial } from "three/examples/jsm/lines/LineMaterial.js";
-import type { ColorValue } from "../core/types.js";
+import type { ColorValue, MaterialAppearance } from "../core/types.js";
 /**
  * Options for MaterialFactory constructor
  */
@@ -60,6 +60,27 @@ interface TextureMaterialOptions {
     texture: THREE.Texture;
     visible?: boolean;
 }
+/**
+ * Interface for the TextureCache dependency.
+ * The actual TextureCache class is defined in texture-cache.ts.
+ * We depend only on its get() method for loose coupling.
+ */
+interface TextureCacheInterface {
+    get(ref: string, textureRole: string): Promise<THREE.Texture | null>;
+}
+/**
+ * Options for Studio mode materials.
+ */
+interface StudioMaterialOptions {
+    /** Resolved MaterialAppearance definition (already looked up from materials table / presets) */
+    materialDef: MaterialAppearance;
+    /** Fallback CSS hex color from the leaf node (e.g., "#cc0000") */
+    fallbackColor: ColorValue;
+    /** Fallback alpha from the leaf node (0-1) */
+    fallbackAlpha: number;
+    /** TextureCache for resolving texture references */
+    textureCache: TextureCacheInterface | null;
+}
 /**
  * Options for updating factory settings
  */
@@ -122,10 +143,64 @@ declare class MaterialFactory {
      * Create a basic material for texture-mapped surfaces.
      */
     createTextureMaterial({ texture, visible }: TextureMaterialOptions, label?: string): THREE.MeshBasicMaterial;
+    /**
+     * Create a Studio mode material from a resolved MaterialAppearance.
+     *
+     * Always creates MeshPhysicalMaterial (except when `unlit: true`, which
+     * uses MeshBasicMaterial). MeshPhysicalMaterial is a superset of
+     * MeshStandardMaterial; when advanced features are off (transmission=0,
+     * clearcoat=0, sheen=0, etc.), the shader compiles to essentially the
+     * same cost.
+     *
+     * @param options - Studio material options
+     * @param label - Optional label for GPU tracking
+     * @returns Configured MeshPhysicalMaterial (or MeshBasicMaterial if unlit)
+     */
+    createStudioMaterial({ materialDef, fallbackColor, fallbackAlpha, textureCache }: StudioMaterialOptions, label?: string): Promise<THREE.MeshPhysicalMaterial | THREE.MeshBasicMaterial>;
+    /**
+     * Create a Studio mode material from a threejs-materials format entry.
+     *
+     * threejs-materials `properties` uses simplified property names (e.g., "color",
+     * "roughness", "normal") where each entry has an optional `value` (scalar or
+     * [r,g,b] array in **linear RGB**) and/or `texture` (inline data URI).
+     *
+     * @param properties - Material properties from threejs-materials
+     * @param textureRepeat - Optional [u, v] texture tiling applied to all loaded textures
+     * @param textureCache - TextureCache for resolving data URI textures
+     * @param label - Optional label for GPU tracking
+     * @returns Configured MeshPhysicalMaterial
+     */
+    createStudioMaterialFromMaterialX(properties: Record<string, {
+        value?: unknown;
+        texture?: string;
+    }>, textureRepeat: [number, number] | undefined, textureCache: TextureCacheInterface | null, label?: string): Promise<THREE.MeshPhysicalMaterial>;
+    /**
+     * Apply alpha mode settings to a material.
+     *
+     * - OPAQUE: fully opaque, no transparency
+     * - MASK: alpha testing with cutoff threshold
+     * - BLEND: standard alpha blending
+     * - Default (no alphaMode): transparent: true (current viewer behavior)
+     */
+    private _applyAlphaMode;
+    /**
+     * Resolve and apply texture references from a MaterialAppearance onto a
+     * MeshPhysicalMaterial via the TextureCache.
+     *
+     * Color-data textures (base color, emissive, sheen color, specular color)
+     * are requested with SRGBColorSpace. All other textures (normal, metallic-
+     * roughness, occlusion, roughness maps, transmission, thickness) are
+     * requested with LinearSRGBColorSpace (the default).
+     *
+     * The metallicRoughnessTexture is a single combined texture where
+     * B channel = metalness and G channel = roughness. It is assigned to
+     * both metalnessMap and roughnessMap on the material.
+     */
+    private _applyStudioTextures;
     /**
      * Update global settings.
      */
     update(options: UpdateOptions): void;
 }
 export { MaterialFactory };
-export type { MaterialFactoryOptions, UpdateOptions };
+export type { MaterialFactoryOptions, UpdateOptions, StudioMaterialOptions, TextureCacheInterface };

package/dist/rendering/material-presets.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Built-in material presets for Studio mode.
+ *
+ * 31 presets organized by category: metals (polished & matte/brushed),
+ * plastics, glass & transparent, rubber & elastomers, painted surfaces,
+ * and natural/other materials.
+ *
+ * These are pure data definitions — no textures, no runtime cost.
+ * The `builtin` field is intentionally omitted; it is used by user-defined
+ * materials to reference these presets, not by presets themselves.
+ *
+ * All color values are in sRGB color space (0-1 per channel).
+ * The material factory converts sRGB to linear when creating Three.js materials.
+ * Presets with neutral color (plastics, paints) rely on the leaf node's
+ * color field for the actual tint via fallback in the material factory.
+ *
+ */
+import type { MaterialAppearance } from "../core/types.js";
+/**
+ * Built-in material presets keyed by preset name.
+ *
+ * Usage: look up a preset by the `material` tag on a leaf node, or via
+ * `"builtin:<name>"` strings in the materials table.
+ */
+export declare const MATERIAL_PRESETS: Record<string, MaterialAppearance>;
+/**
+ * Sorted list of all built-in material preset names.
+ *
+ * Useful for UI dropdowns, validation, and programmatic enumeration.
+ * Derived from MATERIAL_PRESETS keys at module load time.
+ */
+export declare const MATERIAL_PRESET_NAMES: string[];

package/dist/rendering/room-environment.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Clean room environment for Studio mode PMREM generation.
+ *
+ * Based on Three.js RoomEnvironment (which is based on Google model-viewer's
+ * EnvironmentScene), but with the 6 decorative boxes removed and an infinity
+ * cove (quarter-cylinder) at all wall-floor junctions for a clean cyclorama.
+ */
+import { Scene } from "three";
+declare class CleanRoomEnvironment extends Scene {
+    constructor();
+    dispose(): void;
+}
+export { CleanRoomEnvironment };

package/dist/rendering/studio-composer.d.ts

@@ -0,0 +1,130 @@
+/**
+ * StudioComposer -- postprocessing pipeline for Studio mode.
+ *
+ * Wraps the pmndrs EffectComposer to provide:
+ * - Scene rendering (RenderPass)
+ * - Screen-space ambient occlusion (N8AOPostPass)
+ * - Screen-space shadow mask (BasicShadowMap + KawaseBlurPass)
+ * - Tone mapping + sRGB output + antialiasing (ToneMappingEffect + SMAAEffect)
+ *
+ * Tone mapping is handled by the postprocessing ToneMappingEffect, which uses
+ * Three.js's own GLSL tone mapping functions (via #include <tonemapping_pars_fragment>).
+ * The renderer's toneMapping must be set to NoToneMapping (the postprocessing
+ * library's documented requirement). Exposure is controlled via
+ * renderer.toneMappingExposure, which the GLSL functions read automatically.
+ *
+ * Background protection: solid-color backgrounds are excluded from tone mapping.
+ * The RenderPass skips the background (ignoreBackground), the FBO is cleared to
+ * transparent, and the EffectPass alpha-blends its output onto a pre-cleared
+ * canvas that already has the correct background color.
+ *
+ * Shadow mask: BasicShadowMap produces sharp shadow boundaries at 4096×4096.
+ * A half-resolution ShadowMaterial override pass captures the mask, which is
+ * then blurred via KawaseBlurPass and composited by ShadowMaskEffect before
+ * tone mapping. The floor keeps its own ShadowMaterial reading the shadow map
+ * directly (sharp but clean).
+ *
+ * Only instantiated when Studio mode is active. Non-Studio rendering
+ * bypasses this entirely and uses direct `renderer.render()`.
+ */
+import * as THREE from "three";
+import type { StudioToneMapping } from "../core/types.js";
+declare class StudioComposer {
+    private _composer;
+    private _renderPass;
+    private _n8aoPass;
+    private _toneMappingEffect;
+    private _effectPass;
+    private _renderer;
+    private _scene;
+    private _camera;
+    /** Solid background color to protect from tone mapping, or null. */
+    private _bgProtectColor;
+    private _shadowMaskRT;
+    private _blurredObjectMaskRT;
+    private _blurredFloorMaskRT;
+    private _blurPass;
+    private _shadowMaskMaterial;
+    private _shadowMaskEffect;
+    private _shadowMaskEnabled;
+    private _width;
+    private _height;
+    private _receiveShadowState;
+    private _savedIntensities;
+    private _savedVisibility;
+    /**
+     * Create the postprocessing pipeline.
+     *
+     * @param renderer - WebGL renderer
+     * @param scene    - Scene to render
+     * @param camera   - Active camera (perspective or orthographic)
+     * @param width    - Canvas width in pixels
+     * @param height   - Canvas height in pixels
+     */
+    constructor(renderer: THREE.WebGLRenderer, scene: THREE.Scene, camera: THREE.Camera, width: number, height: number);
+    /**
+     * Enable or disable solid-background protection.
+     *
+     * When a solid color is set, the RenderPass skips the scene background
+     * (ignoreBackground=true), the FBO is cleared to transparent, and the
+     * canvas is pre-cleared with the correct color. The EffectPass then
+     * alpha-blends its output so background pixels (alpha=0) show the
+     * canvas clear color underneath.
+     *
+     * Pass null to disable protection (for gradient/environment backgrounds).
+     */
+    setBackgroundProtect(color: THREE.Color | null): void;
+    setAOEnabled(flag: boolean): void;
+    setAOIntensity(value: number): void;
+    /**
+     * Set the tone mapping algorithm and exposure.
+     *
+     * @param mode     - One of "neutral", "ACES", "none"
+     * @param exposure - Exposure multiplier (0 to 2, default 1.0)
+     */
+    setToneMapping(mode: StudioToneMapping, exposure: number): void;
+    /**
+     * Enable or disable the screen-space shadow mask pipeline.
+     *
+     * When enabled, creates half-resolution render targets and a KawaseBlurPass.
+     * When disabled, disposes those resources and disables the mask effect.
+     */
+    setShadowMaskEnabled(enabled: boolean): void;
+    /**
+     * Set shadow blur softness. Uses a fixed HUGE kernel with continuous scale.
+     *
+     * @param softness - 0 (sharpest) to 1 (softest)
+     */
+    setShadowSoftness(softness: number): void;
+    /**
+     * Set the intensity of the object shadow mask overlay.
+     *
+     * @param intensity - 0 (no shadow) to 1 (full shadow)
+     */
+    setShadowMaskIntensity(intensity: number): void;
+    setCamera(camera: THREE.Camera): void;
+    setSize(width: number, height: number): void;
+    /**
+     * Render one frame through the postprocessing pipeline.
+     *
+     * When shadow mask is enabled, runs a 3-phase pipeline:
+     * 1. Render shadow mask (ShadowMaterial override) to half-res RT
+     * 2. Blur via KawaseBlurPass
+     * 3. Composite via ShadowMaskEffect in the main EffectPass
+     *
+     * When background protection is active, pre-clears the canvas with the
+     * solid background color before compositing the tone-mapped scene on top
+     * via alpha blending.
+     */
+    render(deltaTime?: number): void;
+    /**
+     * Render a shadow mask to the half-resolution render target.
+     *
+     * @param mode - "objects" renders only objects (floor hidden),
+     *               "floor" renders only the floor (objects hidden)
+     * @internal
+     */
+    private _renderShadowMask;
+    dispose(): void;
+}
+export { StudioComposer };

package/dist/rendering/studio-floor.d.ts

@@ -0,0 +1,53 @@
+import * as THREE from "three";
+/**
+ * Studio floor — shadow-catching ground plane for Studio mode.
+ *
+ * Uses ShadowMaterial which is fully transparent except where shadows
+ * are cast, providing a natural grounding effect without obscuring
+ * the background (like KeyShot's Ground material or Fusion 360's
+ * ground plane).
+ *
+ * The floor is added to the scene via its `group` property.
+ * Shadow plane visibility is toggled via `setShadowsEnabled()`.
+ */
+declare class StudioFloor {
+    /** The Group to add to the scene. Contains the shadow plane. */
+    readonly group: THREE.Group;
+    /** Shadow-receiving plane (ShadowMaterial) */
+    private _shadowPlane;
+    /** Whether shadows are currently enabled */
+    private _shadowsEnabled;
+    constructor();
+    /**
+     * Create or recreate the floor for the given scene bounds.
+     *
+     * Call this when the bounding box changes (new shapes loaded).
+     *
+     * @param zPosition - Z coordinate for the floor (typically bbox.min.z)
+     * @param sceneSize - Approximate scene size (max extent) for sizing the floor
+     */
+    configure(zPosition: number, sceneSize: number): void;
+    /**
+     * Toggle shadow plane visibility.
+     *
+     * @param enabled - Whether to show the shadow plane
+     */
+    setShadowsEnabled(enabled: boolean): void;
+    /**
+     * Set the ground shadow opacity (how dark the shadow appears on the floor).
+     * This supplements `light.shadow.intensity` which controls shadow darkness
+     * on lit materials; the ground plane ShadowMaterial needs its own opacity.
+     *
+     * @param intensity - Shadow intensity 0-1
+     */
+    setShadowIntensity(intensity: number): void;
+    /** Dispose all GPU resources. */
+    dispose(): void;
+    /**
+     * Create a shadow-receiving plane at the floor position.
+     */
+    private _createShadowPlane;
+    /** Remove and dispose the current shadow plane. */
+    private _clearCurrent;
+}
+export { StudioFloor };

package/dist/rendering/texture-cache.d.ts

@@ -0,0 +1,142 @@
+import * as THREE from "three";
+import type { TextureEntry } from "../core/types.js";
+/** Names of all supported builtin procedural textures */
+declare const BUILTIN_NAMES: readonly ["brushed", "knurled", "sandblasted", "hammered", "checker", "wood-dark", "leather", "fabric-weave"];
+/**
+ * Texture fields that carry sRGB color data.
+ *
+ * When a texture is used for one of these roles, its `colorSpace` must be set
+ * to `SRGBColorSpace` so Three.js applies the sRGB-to-linear decode on
+ * sampling. All other texture roles (normal, metallic-roughness, occlusion,
+ * thickness, transmission, roughness maps) remain `LinearSRGBColorSpace`.
+ */
+declare const SRGB_TEXTURE_ROLES: Set<string>;
+/**
+ * Manages loading, caching, and lifecycle of all Studio mode textures.
+ *
+ * The TextureCache is the **sole owner** of all THREE.Texture objects used by
+ * Studio mode. Materials reference textures but never dispose them directly.
+ * Only TextureCache.dispose() / disposeFull() disposes GPU texture resources.
+ *
+ * Resolution order for texture reference strings:
+ * 1. `builtin:` prefix -- procedural texture from the persistent builtin cache
+ * 2. Key in the root-level `textures` table -- embedded data or URL
+ * 3. `data:` prefix -- treat as data URI, load directly
+ * 4. Otherwise -- treat as URL, resolve relative to HTML page
+ *
+ * Features:
+ * - Two-tier caching: user textures (disposed on clear) + builtin textures
+ *   (persistent, only disposed on viewer teardown)
+ * - In-flight promise deduplication (no duplicate loads for the same key)
+ * - Correct colorSpace assignment per texture semantic role
+ * - GPU resource tracking via gpuTracker
+ */
+declare class TextureCache {
+    /** User textures cache (disposed on clear/dispose, rebuilt per shape data) */
+    private _cache;
+    /** Built-in procedural textures (persistent, only disposed via disposeFull) */
+    private _builtinCache;
+    /** In-flight load promises keyed by cache key */
+    private _inflight;
+    /** Root-level textures table from shape data */
+    private _texturesTable;
+    /** THREE.TextureLoader instance (created lazily) */
+    private _textureLoader;
+    /** Whether this cache has been fully disposed */
+    private _disposed;
+    /**
+     * Set or update the root-level textures table.
+     *
+     * Called when new shape data is loaded. The table maps string keys to
+     * TextureEntry objects (embedded base64 data or URL references).
+     *
+     * @param table - The textures table from root Shapes node, or undefined to clear
+     */
+    setTexturesTable(table: Record<string, TextureEntry> | undefined): void;
+    /**
+     * Resolve a texture reference string and return a cached or newly loaded
+     * THREE.Texture with the correct colorSpace set.
+     *
+     * @param ref - Texture reference string (builtin name, table key, data URI, or URL)
+     * @param textureRole - The texture role name (MaterialAppearance field name or proxy role)
+     *   (e.g. "baseColorTexture", "normalTexture"). Used to determine colorSpace.
+     * @returns The resolved THREE.Texture, or null if the reference is invalid
+     *   or loading fails
+     */
+    get(ref: string, textureRole: string): Promise<THREE.Texture | null>;
+    /**
+     * Check whether a texture reference string would resolve to a builtin texture.
+     */
+    isBuiltin(ref: string): boolean;
+    /**
+     * Dispose user textures (called on viewer.clear() when shape data is replaced).
+     *
+     * Disposes all textures in the user cache and clears in-flight promises.
+     * The builtin procedural texture cache is preserved.
+     */
+    dispose(): void;
+    /**
+     * Dispose all textures including builtin procedural textures.
+     *
+     * Called on viewer.dispose() when the viewer is fully torn down.
+     * After this call, the TextureCache cannot be used again.
+     */
+    disposeFull(): void;
+    /**
+     * Get or generate a builtin procedural texture.
+     *
+     * Builtin textures are cached in the persistent `_builtinCache` and survive
+     * `dispose()` calls. They are only freed via `disposeFull()`.
+     */
+    private _getBuiltin;
+    /**
+     * Load a texture from the root-level textures table entry.
+     *
+     * Handles both embedded (base64 data) and URL-referenced entries.
+     */
+    private _getFromTable;
+    /**
+     * Load a texture from a data URI string.
+     */
+    private _getFromDataUri;
+    /**
+     * Load a texture from a URL (resolved relative to the HTML page).
+     */
+    private _getFromUrl;
+    /**
+     * Load a texture from a source (URL or data URI), cache it, and return it.
+     *
+     * Deduplicates in-flight loads for the same cache key.
+     *
+     * @param cacheKey - Key for the user cache
+     * @param source - URL or data URI to load from
+     * @param colorSpace - Color space to assign to the loaded texture
+     * @returns The loaded texture, or null on failure
+     */
+    private _loadAndCache;
+    /**
+     * Perform the actual texture load via THREE.TextureLoader.
+     *
+     * THREE.TextureLoader handles both URLs and data URIs.
+     */
+    private _doLoad;
+    /**
+     * Get or create the THREE.TextureLoader (lazy initialization).
+     */
+    private _ensureTextureLoader;
+    /**
+     * Convert a format string (e.g. "png", "jpg", "webp") to a MIME type.
+     */
+    private _formatToMime;
+}
+/**
+ * Get the correct color space for a Three.js material map property name.
+ *
+ * sRGB maps (color data): map, emissiveMap, sheenColorMap, specularColorMap
+ * Linear maps (non-color data): everything else (normalMap, roughnessMap, etc.)
+ *
+ * @param mapName - Three.js material property name (e.g., "map", "normalMap")
+ * @returns THREE.SRGBColorSpace or THREE.LinearSRGBColorSpace
+ */
+declare function getColorSpaceForMap(mapName: string): THREE.ColorSpace;
+export { TextureCache, SRGB_TEXTURE_ROLES, BUILTIN_NAMES, getColorSpaceForMap };

package/dist/rendering/triplanar.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Triplanar texture mapping for MeshPhysicalMaterial.
+ *
+ * Replaces standard UV-based texture sampling with model-space triplanar
+ * projection via `material.onBeforeCompile`. Eliminates seams on curved
+ * surfaces (cylinders, cones, etc.) and maintains uniform texture scale
+ * regardless of object proportions.
+ *
+ * All coordinates are in **model space** to match the geometry's bounding box.
+ * `transformed` (model-space position) and `objectNormal` (model-space normal)
+ * are used — NOT the view-space `transformedNormal`.
+ *
+ * NOTE: `onBeforeCompile` receives shaders BEFORE `#include` resolution.
+ * Therefore we replace `#include <chunk_name>` directives with inline GLSL
+ * that uses triplanar sampling, rather than replacing expanded texture2D calls.
+ *
+ * Handles: map, normalMap, roughnessMap, metalnessMap, emissiveMap, aoMap,
+ *          clearcoatNormalMap, alphaMap.
+ */
+import * as THREE from "three";
+/**
+ * Apply triplanar texture mapping to a MeshPhysicalMaterial.
+ *
+ * Modifies the material's shader via `onBeforeCompile` so that all texture
+ * lookups use model-space triplanar projection instead of UV coordinates.
+ * The material should be a **clone** (not shared) because `onBeforeCompile`
+ * and `customProgramCacheKey` are set on it.
+ *
+ * Bounding box of the geometry determines coordinate normalization: the
+ * texture tiles once across the largest dimension with uniform scale,
+ * preserving aspect ratio. `textureRepeat` on the material's textures
+ * (if set) is respected via the triplanarRepeat uniform.
+ *
+ * @param material - Material clone to modify
+ * @param geometry - Geometry for bounding box computation
+ */
+export declare function applyTriplanarMapping(material: THREE.MeshPhysicalMaterial, geometry: THREE.BufferGeometry): void;

package/dist/scene/animation.d.ts

@@ -17,7 +17,7 @@ declare class Animation {
     mixer: THREE.AnimationMixer | null;
     clip: THREE.AnimationClip | null;
     clipAction: THREE.AnimationAction | null;
-    clock: THREE.Clock;
+    clock: THREE.Timer;
     duration: number | null;
     speed: number | null;
     repeat: boolean | null;

package/dist/scene/clipping.d.ts

@@ -68,6 +68,19 @@ interface NestedGroupLike {
 interface ClippingOptions {
     onNormalChange?: (index: ClipIndex, normalArray: Vector3Tuple) => void;
 }
+/**
+ * Saved clipping state for mode transitions (e.g., entering/leaving Studio mode).
+ * Captures only Clipping-internal state; renderer flags and ViewerState keys
+ * are managed by the caller.
+ */
+interface ClippingState {
+    /** Centered constant (position) for each of the 3 clip planes */
+    planeConstants: [number, number, number];
+    /** Whether the plane helper meshes (translucent colored rectangles) are visible */
+    helperVisible: boolean;
+    /** Whether the stencil plane meshes (solid colored caps) are visible */
+    planesVisible: boolean;
+}
 /**
  * Manages clipping planes, stencil rendering, and plane visualization.
  */
@@ -149,6 +162,23 @@ declare class Clipping extends THREE.Group {
      * @param flag - True to show, false to hide.
      */
     setVisible: (flag: boolean) => void;
+    /**
+     * Save the current clipping state for later restoration.
+     * Captures plane positions, helper visibility, and stencil plane visibility.
+     * Used by Studio mode to snapshot clipping state before disabling clipping.
+     *
+     * Note: `renderer.localClippingEnabled` and `clipPlaneHelpers` ViewerState
+     * are managed by the caller (Display/Viewer layer), not captured here.
+     */
+    saveState(): ClippingState;
+    /**
+     * Restore a previously saved clipping state.
+     * Re-applies plane positions, helper visibility, and stencil plane visibility.
+     * Used by Studio mode when leaving to restore the clipping configuration.
+     *
+     * @param state - The state previously captured by `saveState()`.
+     */
+    restoreState(state: ClippingState): void;
     /**
      * Clean up resources.
      * Note: We don't null out arrays/references as GC handles cleanup when the Clipping object is collected.
@@ -156,3 +186,4 @@ declare class Clipping extends THREE.Group {
     dispose(): void;
 }
 export { Clipping };
+export type { ClippingState };