three-cad-viewer 4.1.2 → 4.2.0

package/src/scene/objectgroup.ts

@@ -99,10 +99,20 @@ class ObjectGroup extends THREE.Group {
   vertexFocusSize: number;
   edgeFocusWidth: number;
   shapeGeometry?: THREE.BufferGeometry | null;
+  /** Material tag from shapes data, used for Studio mode material lookup */
+  materialTag: string;
   minZ?: number;
   height?: number;
   private _zebra: ZebraTool | null;
 
+  // Studio mode state
+  private _cadFrontMaterial: ColoredMaterial | null;
+  private _cadBackMaterial: ColoredMaterial | null;
+  private _cadOriginalColor: THREE.Color | null;
+  private _cadOriginalBackColor: THREE.Color | null;
+  private _isStudioMode: boolean;
+  private _cadEdgesVisible: boolean | null;
+
   /**
    * Create an ObjectGroup for managing a CAD object's visual representation.
    * @param opacity - Default opacity value (0.0 to 1.0).
@@ -145,6 +155,15 @@ class ObjectGroup extends THREE.Group {
     this.edgeFocusWidth = 5; // Size of the edges when highlighted
 
     this._zebra = null; // Lazy-initialized zebra tool
+    this.materialTag = "";
+
+    // Studio mode state
+    this._cadFrontMaterial = null;
+    this._cadBackMaterial = null;
+    this._cadOriginalColor = null;
+    this._cadOriginalBackColor = null;
+    this._isStudioMode = false;
+    this._cadEdgesVisible = null;
   }
 
   /**
@@ -157,6 +176,13 @@ class ObjectGroup extends THREE.Group {
     return this._zebra;
   }
 
+  /**
+   * Whether this ObjectGroup is currently in Studio mode.
+   */
+  get isStudioMode(): boolean {
+    return this._isStudioMode;
+  }
+
   /**
    * Dispose of all resources and clean up memory.
    * Releases geometry, materials, children, and zebra tool.
@@ -175,6 +201,13 @@ class ObjectGroup extends THREE.Group {
       this._zebra.dispose();
       this._zebra = null;
     }
+    // Release studio material references (do NOT dispose -- NestedGroup owns them)
+    this._cadFrontMaterial = null;
+    this._cadBackMaterial = null;
+    this._cadOriginalColor = null;
+    this._cadOriginalBackColor = null;
+    this._isStudioMode = false;
+    this._cadEdgesVisible = null;
   }
 
   /**
@@ -427,7 +460,11 @@ class ObjectGroup extends THREE.Group {
   setBlackEdges(flag: boolean): void {
     if (this.edgeMaterial && !this.edgeMaterial.vertexColors) {
       const color = flag ? 0x000000 : this.edge_color;
-      this.originalColor = new THREE.Color(color);
+      // Only update originalColor for edge-only objects (no face mesh).
+      // For face+edge objects, originalColor tracks the face color.
+      if (!this.front) {
+        this.originalColor = new THREE.Color(color);
+      }
       this.edgeMaterial.color = new THREE.Color(color);
       this.edgeMaterial.needsUpdate = true;
     }
@@ -469,7 +506,12 @@ class ObjectGroup extends THREE.Group {
    */
   setShapeVisible(flag: boolean): void {
     if (this.front) {
-      this.front.material.visible = flag;
+      if (this._isStudioMode) {
+        // Studio materials are shared — use mesh.visible for per-object visibility
+        this.front.visible = flag;
+      } else {
+        this.front.material.visible = flag;
+      }
     }
     for (const clippingGroup of this.clipping.values()) {
       const child0 = clippingGroup.children[0];
@@ -488,7 +530,11 @@ class ObjectGroup extends THREE.Group {
       }
     }
     if (this.back && this.renderback) {
-      this.back.material.visible = flag;
+      if (this._isStudioMode) {
+        this.back.visible = flag;
+      } else {
+        this.back.material.visible = flag;
+      }
     }
   }
 
@@ -508,12 +554,17 @@ class ObjectGroup extends THREE.Group {
    * Set visibility of back faces.
    */
   setBackVisible(flag: boolean): void {
-    if (
-      this.back &&
-      this.front &&
-      this.front.material.visible
-    ) {
-      this.back.material.visible = this.renderback || flag;
+    if (this.back && this.front) {
+      const frontVisible = this._isStudioMode
+        ? this.front.visible
+        : this.front.material.visible;
+      if (frontVisible) {
+        if (this._isStudioMode) {
+          this.back.visible = this.renderback || flag;
+        } else {
+          this.back.material.visible = this.renderback || flag;
+        }
+      }
     }
   }
 
@@ -522,10 +573,13 @@ class ObjectGroup extends THREE.Group {
    */
   getVisibility(): boolean {
     if (this.front) {
+      const frontVisible = this._isStudioMode
+        ? this.front.visible
+        : this.front.material.visible;
       if (this.edgeMaterial) {
-        return this.front.material.visible || this.edgeMaterial.visible;
+        return frontVisible || this.edgeMaterial.visible;
       } else {
-        return this.front.material.visible;
+        return frontVisible;
       }
     } else if (this.edgeMaterial) {
       return this.edgeMaterial.visible;
@@ -677,6 +731,127 @@ class ObjectGroup extends THREE.Group {
   setZebraMappingMode(value: ZebraMappingMode): void {
     this.zebra.setMappingMode(value);
   }
+
+  // ===========================================================================
+  // Studio Mode
+  // ===========================================================================
+
+  /**
+   * Enter Studio mode: swap CAD materials for pre-built Studio materials.
+   *
+   * The caller (NestedGroup) is responsible for resolving material tags and
+   * building MeshPhysicalMaterial instances via MaterialFactory. ObjectGroup
+   * just receives the finished materials and performs the swap.
+   *
+   * On first call, saves the current CAD material references so they can be
+   * restored by `leaveStudioMode()`. Copies the `material.visible` flag from
+   * CAD to Studio material to preserve tree-view hide/show state. Updates
+   * `originalColor` / `originalBackColor` so highlight/unhighlight works
+   * correctly in Studio mode.
+   *
+   * @param studioFront - Studio material for front face, or null if this object has no front mesh
+   * @param studioBack - Studio material for back face, or null if back face should not be swapped
+   */
+  enterStudioMode(
+    studioFront: THREE.MeshPhysicalMaterial | null,
+    studioBack: THREE.MeshPhysicalMaterial | null,
+  ): void {
+    if (this._isStudioMode) return;
+
+    // --- Save CAD state ---
+    if (this.front) {
+      this._cadFrontMaterial = this.front.material;
+    }
+    if (this.back) {
+      this._cadBackMaterial = this.back.material;
+    }
+    // Save original colors used by highlight/unhighlight
+    this._cadOriginalColor = this.originalColor ? this.originalColor.clone() : null;
+    this._cadOriginalBackColor = this.originalBackColor ? this.originalBackColor.clone() : null;
+
+    // Save edge visibility state
+    this._cadEdgesVisible = this.edgeMaterial ? this.edgeMaterial.visible : null;
+
+    // --- Swap front material ---
+    if (this.front && studioFront) {
+      // Transfer per-object visibility to mesh.visible (NOT material.visible)
+      // because studio materials are shared across objects via cache.
+      // Writing to a shared material's .visible would affect all users.
+      this.front.visible = this.front.material.visible;
+      this.front.material = studioFront;
+      // Update originalColor to studio material's color for correct highlight
+      this.originalColor = studioFront.color;
+    }
+
+    // --- Swap back material ---
+    if (this.back && studioBack && this.renderback) {
+      // Same: per-object visibility via mesh.visible, not shared material
+      this.back.visible = this.back.material.visible;
+      this.back.material = studioBack;
+      // Update originalBackColor for correct highlight on back face
+      this.originalBackColor = studioBack.color;
+    }
+
+    this._isStudioMode = true;
+  }
+
+  /**
+   * Leave Studio mode: restore CAD materials.
+   *
+   * Copies `material.visible` from Studio back to CAD material to preserve
+   * any visibility changes made while in Studio mode (e.g., tree-view toggle).
+   * Restores `originalColor` / `originalBackColor` to CAD material colors.
+   * Restores edge visibility to the state saved when entering Studio mode.
+   */
+  leaveStudioMode(): void {
+    if (!this._isStudioMode) return;
+
+    // --- Restore front material ---
+    if (this.front && this._cadFrontMaterial) {
+      // Copy visibility from mesh.visible back to CAD material
+      // (studio mode uses mesh.visible for per-object visibility)
+      this._cadFrontMaterial.visible = this.front.visible;
+      this.front.material = this._cadFrontMaterial;
+      this.front.visible = true; // Reset mesh visibility
+    }
+
+    // --- Restore back material ---
+    if (this.back && this._cadBackMaterial && this.renderback) {
+      // Copy visibility from mesh.visible back to CAD material
+      this._cadBackMaterial.visible = this.back.visible;
+      this.back.material = this._cadBackMaterial;
+      this.back.visible = true; // Reset mesh visibility
+    }
+
+    // --- Restore original colors for highlight ---
+    if (this._cadOriginalColor) {
+      this.originalColor = this._cadOriginalColor.clone();
+    }
+    if (this._cadOriginalBackColor) {
+      this.originalBackColor = this._cadOriginalBackColor.clone();
+    }
+
+    // --- Restore edge visibility ---
+    if (this.edgeMaterial && this._cadEdgesVisible !== null) {
+      this.edgeMaterial.visible = this._cadEdgesVisible;
+    }
+
+    this._isStudioMode = false;
+  }
+
+  /**
+   * Toggle edge visibility while in Studio mode.
+   *
+   * Only affects edges (not vertices). Should only be called while in
+   * Studio mode; the saved CAD edge visibility is not affected.
+   *
+   * @param visible - Whether edges should be visible
+   */
+  setStudioShowEdges(visible: boolean): void {
+    if (this.edgeMaterial) {
+      this.edgeMaterial.visible = visible;
+    }
+  }
 }
 
 /**

package/src/scene/orientation.ts

@@ -191,8 +191,20 @@ class OrientationMarker {
    */
   render(renderer: THREE.WebGLRenderer): void {
     if (this.ready && this.scene && this.camera) {
+      // Rendering the corner marker mutates renderer state (viewport/scissor/scissor test).
+      // Preserve and restore those values so downstream renders are not clipped or offset.
+      const prevViewport = renderer.getViewport(new THREE.Vector4());
+      const prevScissor = renderer.getScissor(new THREE.Vector4());
+      const prevScissorTest = renderer.getScissorTest();
+
+      // Draw marker in its small corner viewport.
       renderer.setViewport(0, 0, this.width, this.height);
       renderer.render(this.scene, this.camera);
+
+      // Restore previous state for the main scene / shared render pipeline.
+      renderer.setViewport(prevViewport);
+      renderer.setScissor(prevScissor);
+      renderer.setScissorTest(prevScissorTest);
     }
   }
 

package/src/scene/render-shape.ts

@@ -167,6 +167,7 @@ class ShapeRenderer {
       }
       const vertices = shape.vertices;
       const normals = shape.normals;
+      const uvs = shape.uvs instanceof Float32Array ? shape.uvs : null;
       // Determine format and validate
       let current = 0;
       if (hasTrianglesPerFace(shape)) {
@@ -186,6 +187,7 @@ class ShapeRenderer {
 
           const vecs = new Float32Array(triangles.length * 3);
           const norms = new Float32Array(triangles.length * 3);
+          const uvArr = uvs ? new Float32Array(triangles.length * 2) : null;
           for (let i = 0; i < triangles.length; i++) {
             const s = triangles[i];
             vecs[3 * i] = vertices[3 * s];
@@ -194,6 +196,22 @@ class ShapeRenderer {
             norms[3 * i] = normals[3 * s];
             norms[3 * i + 1] = normals[3 * s + 1];
             norms[3 * i + 2] = normals[3 * s + 2];
+            if (uvs && uvArr) {
+              uvArr[2 * i] = uvs[2 * s];
+              uvArr[2 * i + 1] = uvs[2 * s + 1];
+            }
+          }
+          const newShapeObj: Shape = {
+            triangles: [...Array(triangles.length).keys()],
+            vertices: Array.from(vecs),
+            normals: Array.from(norms),
+            edges: [],
+            obj_vertices: [],
+            edge_types: [],
+            face_types: [shape.face_types[j]],
+          };
+          if (uvArr) {
+            newShapeObj.uvs = Array.from(uvArr);
           }
           const new_shape: Shapes = {
             version: 2,
@@ -206,23 +224,18 @@ class ShapeRenderer {
             type: "shapes",
             color: part.color,
             alpha: part.alpha,
-            renderback: true,
+            renderback: part.subtype !== "solid",
             state: [1, 3],
             accuracy: part.accuracy,
             bb: null,
-            shape: {
-              triangles: [...Array(triangles.length).keys()],
-              vertices: Array.from(vecs),
-              normals: Array.from(norms),
-              edges: [],
-              obj_vertices: [],
-              edge_types: [],
-              face_types: [shape.face_types[j]],
-            },
+            shape: newShapeObj,
           };
           if (part.texture) {
             new_shape.texture = part.texture;
           }
+          if (part.material) {
+            new_shape.material = part.material;
+          }
           new_shape.geomtype = shape.face_types[j];
           new_shape.subtype = part.subtype;
           new_shape.exploded = true;
@@ -241,6 +254,7 @@ class ShapeRenderer {
 
           const vecs = new Float32Array(triangles.length * 3);
           const norms = new Float32Array(triangles.length * 3);
+          const uvArr = uvs ? new Float32Array(triangles.length * 2) : null;
           for (let i = 0; i < triangles.length; i++) {
             const s = triangles[i];
             vecs[3 * i] = vertices[3 * s];
@@ -249,6 +263,22 @@ class ShapeRenderer {
             norms[3 * i] = normals[3 * s];
             norms[3 * i + 1] = normals[3 * s + 1];
             norms[3 * i + 2] = normals[3 * s + 2];
+            if (uvs && uvArr) {
+              uvArr[2 * i] = uvs[2 * s];
+              uvArr[2 * i + 1] = uvs[2 * s + 1];
+            }
+          }
+          const newShapeObj2: Shape = {
+            triangles: [...Array(triangles.length).keys()],
+            vertices: Array.from(vecs),
+            normals: Array.from(norms),
+            edges: [],
+            obj_vertices: [],
+            edge_types: [],
+            face_types: [shape.face_types[j]],
+          };
+          if (uvArr) {
+            newShapeObj2.uvs = Array.from(uvArr);
           }
           const new_shape: Shapes = {
             version: 2,
@@ -261,23 +291,18 @@ class ShapeRenderer {
             type: "shapes",
             color: part.color,
             alpha: part.alpha,
-            renderback: true,
+            renderback: part.subtype !== "solid",
             state: [1, 3],
             accuracy: part.accuracy,
             bb: null,
-            shape: {
-              triangles: [...Array(triangles.length).keys()],
-              vertices: Array.from(vecs),
-              normals: Array.from(norms),
-              edges: [],
-              obj_vertices: [],
-              edge_types: [],
-              face_types: [shape.face_types[j]],
-            },
+            shape: newShapeObj2,
           };
           if (part.texture) {
             new_shape.texture = part.texture;
           }
+          if (part.material) {
+            new_shape.material = part.material;
+          }
           new_shape.geomtype = shape.face_types[j];
           new_shape.subtype = part.subtype;
           new_shape.exploded = true;
@@ -468,6 +493,7 @@ class ShapeRenderer {
       edge_types: number[] | Uint8Array | Uint32Array;
       triangles_per_face?: number[] | Uint32Array;
       segments_per_edge?: number[] | Uint32Array;
+      uvs?: number[] | Float32Array;
     }
 
     // Shape interface matches MutableShape - we cast to allow reassignment
@@ -490,9 +516,12 @@ class ShapeRenderer {
     // Only flatten if it's actually nested (no segments_per_edge means nested format)
     if (s.edges != null && !(s.edges instanceof Float32Array)) {
       if (s.segments_per_edge !== undefined) {
-        // Binary format with flat edges - convert directly
         if (!Array.isArray(s.edges[0])) {
+          // Flat number[] — convert directly
           s.edges = new Float32Array(s.edges as number[]);
+        } else {
+          // Nested number[][] with segments_per_edge — flatten then convert
+          s.edges = new Float32Array(flatten(s.edges as number[][], 1));
         }
       }
       // If no segments_per_edge, leave as number[][] for _decompose
@@ -522,6 +551,11 @@ class ShapeRenderer {
       s.obj_vertices = new Float32Array(s.obj_vertices as number[]);
     }
 
+    // uvs: flat number[] -> Float32Array (2 floats per vertex)
+    if (s.uvs != null && !(s.uvs instanceof Float32Array)) {
+      s.uvs = new Float32Array(s.uvs as number[]);
+    }
+
     // face_types: number[] -> Uint32Array
     if (s.face_types != null && !(s.face_types instanceof Uint32Array)) {
       s.face_types = new Uint32Array(s.face_types);

package/src/types/n8ao.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Minimal type declarations for n8ao.
+ *
+ * n8ao does not ship TypeScript types. This provides just enough
+ * typing to suppress TS7016 during builds while keeping the actual
+ * N8AOPostPass usage typed as `any` (the API is untyped upstream).
+ */
+declare module "n8ao" {
+  import type { Scene, Camera } from "three";
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  export class N8AOPostPass {
+    enabled: boolean;
+    camera: Camera;
+    configuration: {
+      aoRadius: number;
+      distanceFalloff: number;
+      intensity: number;
+      halfRes: boolean;
+      depthAwareUpsampling: boolean;
+      gammaCorrection: boolean;
+      [key: string]: unknown;
+    };
+    constructor(scene: Scene, camera: Camera, width: number, height: number);
+    setQualityMode(mode: "Low" | "Medium" | "High" | "Ultra"): void;
+    setSize(width: number, height: number): void;
+  }
+}