three-cad-viewer 4.1.2 → 4.3.0

package/src/scene/clipping.ts

@@ -272,6 +272,20 @@ 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.
  */
@@ -566,6 +580,50 @@ class Clipping extends THREE.Group {
     }
   };
 
+  /**
+   * 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 {
+    return {
+      planeConstants: [
+        this.clipPlanes[0].centeredConstant,
+        this.clipPlanes[1].centeredConstant,
+        this.clipPlanes[2].centeredConstant,
+      ],
+      helperVisible: this.planeHelpers?.visible ?? false,
+      planesVisible: this._planeMeshGroup?.children.length
+        ? this._planeMeshGroup.children[0].material.visible
+        : false,
+    };
+  }
+
+  /**
+   * 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 {
+    // Restore plane positions
+    for (const i of CLIP_INDICES) {
+      this.setConstant(i, state.planeConstants[i]);
+    }
+
+    // Restore plane helper visibility
+    if (this.planeHelpers) {
+      this.planeHelpers.visible = state.helperVisible;
+    }
+
+    // Restore stencil plane mesh visibility
+    this.setVisible(state.planesVisible);
+  }
+
   /**
    * Clean up resources.
    * Note: We don't null out arrays/references as GC handles cleanup when the Clipping object is collected.
@@ -579,3 +637,4 @@ class Clipping extends THREE.Group {
 }
 
 export { Clipping };
+export type { ClippingState };

package/src/scene/nestedgroup.ts

@@ -10,16 +10,26 @@ import { gpuTracker } from "../utils/gpu-tracker.js";
 import type {
   ZebraColorScheme,
   ZebraMappingMode,
+  StudioTextureMapping,
   Shapes,
   ColorValue,
   ColoredMaterial,
+  MaterialAppearance,
+  MaterialXMaterial,
 } from "../core/types";
+import { isMaterialXMaterial } from "../core/types";
+import { MATERIAL_PRESETS } from "../rendering/material-presets.js";
+import { logger } from "../utils/logger.js";
+import { TextureCache } from "../rendering/texture-cache.js";
+import type { TextureCacheInterface } from "../rendering/material-factory.js";
+import { applyTriplanarMapping } from "../rendering/triplanar.js";
 
 interface ShapeData {
   vertices: Float32Array | number[][];
   normals: Float32Array | number[][];
   triangles: Uint32Array | number[][];
   edges?: Float32Array | number[][];
+  uvs?: Float32Array | number[];
 }
 
 interface EdgeData {
@@ -57,6 +67,7 @@ interface ShapeEntry {
   geomtype?: number | null;
   subtype?: string | null;
   texture?: { image: TextureData; width: number; height: number };
+  material?: string;
 }
 
 interface ShapeTree {
@@ -113,6 +124,32 @@ class CompoundGroup extends THREE.Group {
  *
  * @internal - This is an internal class used by Viewer
  */
+
+/** Texture field names on MaterialAppearance that require UV coordinates. */
+const TEXTURE_FIELDS = [
+  "map", "normalMap", "aoMap",
+  "metalnessMap", "roughnessMap", "emissiveMap", "transmissionMap",
+  "clearcoatMap", "clearcoatRoughnessMap", "clearcoatNormalMap",
+  "thicknessMap", "specularIntensityMap", "specularColorMap",
+  "sheenColorMap", "sheenRoughnessMap", "anisotropyMap",
+] as const;
+
+/** Check whether a resolved MaterialAppearance references any texture. */
+function materialHasTexture(def: MaterialAppearance): boolean {
+  for (const f of TEXTURE_FIELDS) {
+    if ((def as Record<string, unknown>)[f]) return true;
+  }
+  return false;
+}
+
+/** Check whether a threejs-materials entry has texture references in its properties. */
+function materialXHasTextures(entry: MaterialXMaterial): boolean {
+  for (const [, prop] of Object.entries(entry.properties)) {
+    if (prop.texture) return true;
+  }
+  return false;
+}
+
 class NestedGroup {
   shapes!: Shapes;
   width: number;
@@ -134,6 +171,15 @@ class NestedGroup {
   groups!: GroupsMap; // Initialized to {} in constructor
   clipPlanes: THREE.Plane[] | null;
   materialFactory: MaterialFactory;
+  materialsTable: Record<string, string | MaterialXMaterial | MaterialAppearance> | null;
+  resolvedMaterials: Map<string, MaterialAppearance>;
+  /** Cache for threejs-materials entries resolved from the materials table */
+  resolvedMaterialX: Map<string, MaterialXMaterial>;
+  private _textureCache: TextureCache | null;
+  private _studioMaterialCache: Map<string, THREE.MeshPhysicalMaterial | THREE.MeshBasicMaterial>;
+  /** Sharing keys of materials that have textures (for UV generation on cache hits) */
+  private _texturedMaterialKeys: Set<string>;
+  private _isStudioMode: boolean;
 
   /**
    * Create a NestedGroup for rendering CAD geometry.
@@ -181,6 +227,14 @@ class NestedGroup {
 
     this.clipPlanes = null;
 
+    this.materialsTable = null;
+    this.resolvedMaterials = new Map();
+    this.resolvedMaterialX = new Map();
+    this._textureCache = null;
+    this._studioMaterialCache = new Map();
+    this._texturedMaterialKeys = new Set();
+    this._isStudioMode = false;
+
     this.materialFactory = new MaterialFactory({
       defaultOpacity: opacity,
       metalness: metalness,
@@ -202,6 +256,110 @@ class NestedGroup {
       deepDispose(this.rootGroup);
       this.rootGroup = null;
     }
+    this._disposeStudioResources();
+    this.resolvedMaterials.clear();
+    this.resolvedMaterialX.clear();
+    this.materialsTable = null;
+  }
+
+  /**
+   * Resolve a material tag to its definition.
+   *
+   * Returns either a MaterialAppearance (for builtin presets) or a
+   * MaterialXMaterial (for threejs-materials entries). The caller must check the
+   * return type to determine which factory method to use.
+   *
+   * Resolution order:
+   * 1. Check caches (resolvedMaterials / resolvedMaterialX)
+   * 2. Look up in root-level `materials` table:
+   *    - string starting with "builtin:" → MATERIAL_PRESETS lookup
+   *    - object with `properties` key → threejs-materials entry
+   * 3. Direct lookup in MATERIAL_PRESETS by tag name
+   * 4. No match → warning, return null
+   *
+   * @param tag - The material tag from a leaf node
+   * @param objectPath - The object path (for warning messages)
+   * @returns Resolved material definition or null if not found
+   */
+  resolveMaterialTag(
+    tag: string,
+    objectPath: string,
+  ): MaterialAppearance | MaterialXMaterial | null {
+    // Empty string is equivalent to no tag -- skip silently
+    if (tag === "") {
+      return null;
+    }
+
+    // Check caches
+    const cachedPreset = this.resolvedMaterials.get(tag);
+    if (cachedPreset !== undefined) return cachedPreset;
+
+    const cachedMX = this.resolvedMaterialX.get(tag);
+    if (cachedMX !== undefined) return cachedMX;
+
+    // 1. Look up in user-defined materials table
+    if (this.materialsTable && tag in this.materialsTable) {
+      const entry = this.materialsTable[tag];
+
+      // String entry: "builtin:<preset-name>"
+      if (typeof entry === "string") {
+        if (entry.startsWith("builtin:")) {
+          const presetName = entry.slice(8);
+          const preset = MATERIAL_PRESETS[presetName];
+          if (preset) {
+            const resolved = { ...preset };
+            this.resolvedMaterials.set(tag, resolved);
+            return resolved;
+          }
+          logger.warn(
+            `Unknown builtin preset '${presetName}' referenced by '${tag}' on '${objectPath}'`,
+          );
+          return null;
+        }
+        logger.warn(
+          `Invalid material string '${entry}' for tag '${tag}' (expected "builtin:" prefix)`,
+        );
+        return null;
+      }
+
+      // MaterialXMaterial entry: object with `properties` key
+      if (isMaterialXMaterial(entry)) {
+        this.resolvedMaterialX.set(tag, entry);
+        return entry;
+      }
+
+      // MaterialAppearance entry: object with `builtin` key (preset + overrides)
+      if (typeof entry === "object" && "builtin" in entry) {
+        const appearance = entry as MaterialAppearance;
+        const presetName = appearance.builtin!;
+        const preset = MATERIAL_PRESETS[presetName];
+        if (!preset) {
+          logger.warn(
+            `Unknown builtin preset '${presetName}' referenced by '${tag}' on '${objectPath}'`,
+          );
+          return null;
+        }
+        const resolved: MaterialAppearance = { ...preset, ...appearance };
+        this.resolvedMaterials.set(tag, resolved);
+        return resolved;
+      }
+
+      // Should not happen with current type, but guard anyway
+      logger.warn(`Unrecognised material entry for tag '${tag}' on '${objectPath}'`);
+      return null;
+    }
+
+    // 2. Direct lookup in built-in presets (leaf tag matches preset name)
+    const preset = MATERIAL_PRESETS[tag];
+    if (preset) {
+      const resolved = { ...preset };
+      this.resolvedMaterials.set(tag, resolved);
+      return resolved;
+    }
+
+    // 3. No match
+    logger.warn(`Unknown material tag '${tag}' on object '${objectPath}'`);
+    return null;
   }
 
   /**
@@ -469,6 +627,15 @@ class NestedGroup {
         new THREE.BufferAttribute(normals, 3),
       );
       shapeGeometry.setIndex(new THREE.BufferAttribute(triangles, 1));
+      if (shape.uvs && shape.uvs.length > 0) {
+        const uvArray = shape.uvs instanceof Float32Array
+          ? shape.uvs
+          : new Float32Array(shape.uvs);
+        shapeGeometry.setAttribute(
+          "uv",
+          new THREE.BufferAttribute(uvArray, 2),
+        );
+      }
       group.shapeGeometry = shapeGeometry;
 
       frontMaterial = this.materialFactory.createFrontFaceMaterial(
@@ -798,12 +965,21 @@ class NestedGroup {
         group.add(this.renderLoop(shape));
       } else {
         const entry = shape as ShapeEntry;
+        // Propagate material tag from shapes data to local ShapeEntry
+        const materialTag = (shape as Shapes).material;
+        if (materialTag != null) {
+          entry.material = materialTag;
+        }
         const has_texture = entry.texture != null;
         const texture = has_texture ? entry.texture!.image : null;
         const width = has_texture ? entry.texture!.width : null;
         const height = has_texture ? entry.texture!.height : null;
         const objectGroup = _render(entry, texture, width, height);
         this.groups[entry.id] = objectGroup;
+        // Store material tag on ObjectGroup for Studio mode lookup
+        if (entry.material !== undefined && entry.material !== null) {
+          objectGroup.materialTag = entry.material;
+        }
         group.add(objectGroup);
       }
     }
@@ -817,6 +993,9 @@ class NestedGroup {
     if (this.shapes.format == "GDS") {
       this.instances = this.shapes.instances || null;
     }
+    this.materialsTable = this.shapes.materials || null;
+    this.resolvedMaterials.clear();
+    this.resolvedMaterialX.clear();
     this.rootGroup = this.renderLoop(this.shapes);
     return this.rootGroup;
   }
@@ -1018,6 +1197,219 @@ class NestedGroup {
   setZebraMappingMode(flag: ZebraMappingMode): void {
     this._traverse("setZebraMappingMode", flag);
   }
+
+  // ===========================================================================
+  // Studio Mode
+  // ===========================================================================
+
+  /**
+   * Enter Studio mode: build and apply studio materials to all ObjectGroups.
+   *
+   * Material resolution per ObjectGroup:
+   * 1. Resolve the material tag via `resolveMaterialTag()`
+   *    - MaterialXMaterial  → `createStudioMaterialFromMaterialX`
+   *    - MaterialAppearance → `createStudioMaterial` (builtin presets)
+   *    - null (no tag)      → fallback plastic-glossy preset tinted with CAD color
+   * 2. Cache by sharing key for reuse across objects with the same tag+color
+   * 3. Clone BackSide variant for renderback objects
+   * 4. Auto-generate box-projected UVs when textured but geometry has no UVs
+   */
+  async enterStudioMode(textureMapping: StudioTextureMapping = "triplanar"): Promise<string[]> {
+    // Create TextureCache lazily
+    if (!this._textureCache) {
+      this._textureCache = new TextureCache();
+    }
+    // Track material tags that failed to resolve
+    const unresolvedTags = new Set<string>();
+
+    // Iterate all ObjectGroups with front meshes
+    for (const path in this.groups) {
+      const obj = this.groups[path];
+      if (!(obj instanceof ObjectGroup)) continue;
+      if (!obj.front) continue;
+
+      // Determine material tag, leaf color, and leaf alpha
+      const tag = obj.materialTag || "";
+      const leafColor = obj.originalColor
+        ? "#" + obj.originalColor.getHexString()
+        : "#707070";
+      const leafAlpha = obj.alpha;
+
+      // Compute sharing key
+      const sharingKey = `${tag}:${leafColor}:${leafAlpha}`;
+
+      // Check cached material for this key
+      let studioMaterial = this._studioMaterialCache.get(sharingKey);
+
+      if (!studioMaterial) {
+        // Resolve the tag
+        const resolved = tag ? this.resolveMaterialTag(tag, path) : null;
+        if (tag && !resolved) {
+          unresolvedTags.add(tag);
+        }
+
+        // Per-object try/catch: a single failure should not abort the rest
+        try {
+          if (resolved && isMaterialXMaterial(resolved)) {
+            // --- threejs-materials path ---
+            studioMaterial = await this.materialFactory.createStudioMaterialFromMaterialX(
+              resolved.properties,
+              resolved.textureRepeat,
+              this._textureCache as TextureCacheInterface,
+            );
+            if (materialXHasTextures(resolved)) {
+              this._texturedMaterialKeys.add(sharingKey);
+            }
+          } else {
+            // --- Builtin preset path (or fallback) ---
+            let materialDef: MaterialAppearance;
+            if (resolved) {
+              materialDef = resolved;
+            } else if (leafAlpha < 1) {
+              // Fallback for transparent objects: acrylic-clear with
+              // transmission matching the CAD alpha, tinted with CAD color
+              const { color: _, ...acrylicClear } = MATERIAL_PRESETS["acrylic-clear"];
+              materialDef = { ...acrylicClear, transmission: 1 - leafAlpha };
+            } else {
+              // Fallback: plastic-glossy tinted with CAD color
+              const { color: _, ...plasticGlossy } = MATERIAL_PRESETS["plastic-glossy"];
+              materialDef = plasticGlossy;
+            }
+            studioMaterial = await this.materialFactory.createStudioMaterial({
+              materialDef,
+              fallbackColor: leafColor,
+              fallbackAlpha: leafAlpha,
+              textureCache: this._textureCache as TextureCacheInterface,
+            });
+            if (materialHasTexture(materialDef)) {
+              this._texturedMaterialKeys.add(sharingKey);
+            }
+          }
+        } catch (err) {
+          logger.warn(
+            `Studio material creation failed for "${path}" (tag="${tag}"), skipping`,
+            err,
+          );
+          continue;
+        }
+
+        this._studioMaterialCache.set(sharingKey, studioMaterial);
+      }
+
+      // Triplanar mapping for textured materials.
+      // "triplanar" mode: always use triplanar for textured materials
+      // "parametric" mode: triplanar only when geometry has no UVs (fallback)
+      const textured = this._texturedMaterialKeys.has(sharingKey);
+      const hasUVs = obj.shapeGeometry?.getAttribute("uv") != null;
+      const needsTriplanar =
+        textured &&
+        obj.shapeGeometry != null &&
+        (textureMapping === "triplanar" || !hasUVs);
+
+      if (textured) {
+        logger.debug(`Studio "${path}": ${needsTriplanar ? "using triplanar" : "using parametric UVs"}`);
+      }
+
+      if (needsTriplanar && studioMaterial instanceof THREE.MeshPhysicalMaterial) {
+        const triKey = `${sharingKey}:tri:${path}`;
+        let triMat = this._studioMaterialCache.get(triKey);
+        if (!triMat) {
+          triMat = studioMaterial.clone();
+          applyTriplanarMapping(triMat as THREE.MeshPhysicalMaterial, obj.shapeGeometry!);
+          this._studioMaterialCache.set(triKey, triMat);
+        }
+        studioMaterial = triMat;
+      }
+
+      // Build back-face variant if needed
+      let studioBack: THREE.MeshPhysicalMaterial | null = null;
+      if (obj.renderback && studioMaterial instanceof THREE.MeshPhysicalMaterial) {
+        const backKey = needsTriplanar
+          ? `${sharingKey}:tri:${path}:back`
+          : `${sharingKey}:back`;
+        let cachedBack = this._studioMaterialCache.get(backKey);
+        if (!cachedBack) {
+          cachedBack = studioMaterial.clone();
+          cachedBack.side = THREE.BackSide;
+          if (needsTriplanar && obj.shapeGeometry) {
+            applyTriplanarMapping(cachedBack as THREE.MeshPhysicalMaterial, obj.shapeGeometry);
+          }
+          this._studioMaterialCache.set(backKey, cachedBack);
+        }
+        studioBack = cachedBack as THREE.MeshPhysicalMaterial;
+      }
+
+      // Apply to ObjectGroup
+      obj.enterStudioMode(
+        studioMaterial instanceof THREE.MeshPhysicalMaterial ? studioMaterial : null,
+        studioBack,
+      );
+    }
+
+    this._isStudioMode = true;
+    return [...unresolvedTags];
+  }
+
+  /**
+   * Leave Studio mode: restore CAD materials on all ObjectGroups.
+   * Does NOT clear the material cache (allows fast re-entry).
+   */
+  leaveStudioMode(): void {
+    for (const path in this.groups) {
+      const obj = this.groups[path];
+      if (!(obj instanceof ObjectGroup)) continue;
+      obj.leaveStudioMode();
+    }
+    this._isStudioMode = false;
+  }
+
+  /**
+   * Clear cached Studio materials so they are rebuilt on next enterStudioMode.
+   */
+  clearStudioMaterialCache(): void {
+    for (const [, material] of this._studioMaterialCache) {
+      material.dispose();
+    }
+    this._studioMaterialCache.clear();
+    this._texturedMaterialKeys.clear();
+  }
+
+  /**
+   * Set edge visibility across all ObjectGroups while in Studio mode.
+   * @param visible - Whether edges should be visible
+   */
+  setStudioShowEdges(visible: boolean): void {
+    for (const path in this.groups) {
+      const obj = this.groups[path];
+      if (!(obj instanceof ObjectGroup)) continue;
+      obj.setStudioShowEdges(visible);
+    }
+  }
+
+  /**
+   * Dispose all Studio mode resources (material cache + texture cache).
+   */
+  private _disposeStudioResources(): void {
+    // Leave studio mode if still active
+    if (this._isStudioMode) {
+      this.leaveStudioMode();
+    }
+
+    // Dispose cached studio materials
+    for (const [, material] of this._studioMaterialCache) {
+      material.dispose();
+    }
+    this._studioMaterialCache.clear();
+    this._texturedMaterialKeys.clear();
+
+    // Dispose texture cache
+    if (this._textureCache) {
+      this._textureCache.disposeFull();
+      this._textureCache = null;
+    }
+
+    this._isStudioMode = false;
+  }
 }
 
 /**