three-cad-viewer 4.3.2 → 4.3.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "three-cad-viewer",
-  "version": "4.3.2",
+  "version": "4.3.5",
   "type": "module",
   "description": "WebGL-based CAD viewer built on Three.js with clipping planes, measurement tools, and tree navigation",
   "repository": {
@@ -8,6 +8,7 @@
     "url": "https://github.com/bernhard-42/three-cad-viewer"
   },
   "files": [
+    "README.md",
     "dist/**/*.d.ts",
     "dist/three-cad-viewer.css",
     "dist/three-cad-viewer.esm.js",

package/src/_version.ts

@@ -1 +1 @@
-export const version: string = "4.3.2";
+export const version: string = "4.3.5";

package/src/core/studio-manager.ts

@@ -540,7 +540,7 @@ class StudioManager {
       light.target.position.copy(bboxCenter);
 
       light.castShadow = true;
-      const frustumSize = maxExtent * 4.0;
+      const frustumSize = maxExtent * 6.0;
       light.shadow.camera.left = -frustumSize;
       light.shadow.camera.right = frustumSize;
       light.shadow.camera.top = frustumSize;

package/src/core/types.ts

@@ -625,27 +625,29 @@ export interface MaterialAppearance {
  *
  * This format is produced by the threejs-materials Python library, which catalogs
  * PBR materials from ambientCG, GPUOpen, PolyHaven, and PhysicallyBased.
- * The `properties` dict uses simplified property names (e.g., "color", "roughness",
- * "normal") where each entry has an optional `value` (scalar or color array in
- * linear RGB) and/or `texture` (inline data URI).
+ * `values` contains scalar properties (e.g., color as linear RGB array,
+ * roughness as float).  `textures` contains texture references (inline data URIs
+ * or file paths) keyed by property name.
  *
- * Detected by the presence of the `properties` key.
+ * Detected by the presence of the `values` key.
  * Extra keys from threejs-materials (id, name, source, url, license) pass through
  * harmlessly and are not part of this interface.
  */
 export interface MaterialXMaterial {
-  /** Material properties from threejs-materials. Each key maps to { value?, texture? } */
-  properties: Record<string, { value?: unknown; texture?: string }>;
+  /** Scalar PBR property values (e.g., color, metalness, roughness). */
+  values: Record<string, unknown>;
+  /** Texture map references keyed by property name (e.g., color, normal). */
+  textures: Record<string, string>;
   /** Optional texture tiling [u, v], default [1, 1]. Applied to all textures. */
   textureRepeat?: [number, number];
 }
 
 /**
  * Type guard to check if a material entry is a threejs-materials format dict.
- * Detected by the presence of the `properties` key.
+ * Detected by the presence of the `values` key.
  */
 export function isMaterialXMaterial(m: unknown): m is MaterialXMaterial {
-  return typeof m === "object" && m !== null && "properties" in m;
+  return typeof m === "object" && m !== null && "values" in m;
 }
 
 // =============================================================================
@@ -854,7 +856,7 @@ export interface Shapes {
   /** User-defined material library (root node).
    *  Values can be:
    *  - string: builtin preset reference (e.g., "builtin:car-paint")
-   *  - MaterialXMaterial: threejs-materials format (detected by `properties` key)
+   *  - MaterialXMaterial: threejs-materials format (detected by `values` key)
    *  - MaterialAppearance: preset with overrides (e.g., { builtin: "acrylic-clear", color: "#55a0e3" })
    */
   materials?: Record<string, string | MaterialXMaterial | MaterialAppearance> | undefined;

package/src/rendering/material-factory.ts

@@ -478,10 +478,12 @@ class MaterialFactory {
     }
 
     // --- Anisotropy (brushed metal) ---
-    // Skipped: anisotropic reflections require tangent vectors on the mesh.
-    // CAD tessellation never provides tangents, so Three.js falls back to
-    // screen-space derivative tangents which produce visible diamond-shaped
-    // facet artifacts on coarse meshes.
+    if (def.anisotropy !== undefined && def.anisotropy > 0) {
+      material.anisotropy = def.anisotropy;
+      if (def.anisotropyRotation !== undefined) {
+        material.anisotropyRotation = def.anisotropyRotation;
+      }
+    }
 
     // --- Textures ---
     // Resolve all texture references via TextureCache.
@@ -501,14 +503,16 @@ class MaterialFactory {
    * "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 values - Scalar PBR values from threejs-materials
+   * @param textures - Texture map references 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
    */
   async createStudioMaterialFromMaterialX(
-    properties: Record<string, { value?: unknown; texture?: string }>,
+    values: Record<string, unknown>,
+    textures: Record<string, string>,
     textureRepeat: [number, number] | undefined,
     textureCache: TextureCacheInterface | null,
     label?: string,
@@ -524,36 +528,31 @@ class MaterialFactory {
     };
 
     // Warn once if displacement data is present (not supported in Studio)
-    if (properties.displacement?.texture || properties.displacementScale?.value !== undefined) {
+    if (textures.displacement || values.displacementScale !== undefined) {
       logger.warn("Displacement not supported by the Studio");
     }
 
-    for (const [key, prop] of Object.entries(properties)) {
-      if (prop.value === undefined) continue;
-
+    for (const [key, value] of Object.entries(values)) {
       // Skip displacement properties (not supported, would waste GPU memory)
       if (key === "displacement" || key === "displacementScale" || key === "displacementBias") continue;
 
-      // Skip anisotropy — requires tangent vectors that CAD meshes don't have
-      if (key === "anisotropy" || key === "anisotropyRotation") continue;
-
       // Color arrays → THREE.Color (already linear, no sRGB conversion)
-      if (COLOR_ARRAY_KEYS.has(key) && Array.isArray(prop.value)) {
-        const [r, g, b] = prop.value as number[];
+      if (COLOR_ARRAY_KEYS.has(key) && Array.isArray(value)) {
+        const [r, g, b] = value as number[];
         matOptions[key] = new THREE.Color(r, g, b);
-      } else if ((key === "normalScale" || key === "clearcoatNormalScale") && Array.isArray(prop.value)) {
-        matOptions[key] = new THREE.Vector2(prop.value[0], prop.value[1]);
-      } else if (key === "iridescenceThicknessRange" && Array.isArray(prop.value)) {
-        matOptions[key] = prop.value;
+      } else if ((key === "normalScale" || key === "clearcoatNormalScale") && Array.isArray(value)) {
+        matOptions[key] = new THREE.Vector2(value[0], value[1]);
+      } else if (key === "iridescenceThicknessRange" && Array.isArray(value)) {
+        matOptions[key] = value;
       } else {
-        matOptions[key] = prop.value;
+        matOptions[key] = value;
       }
     }
 
     // --- Handle transmission ---
-    const transmissionVal = properties.transmission?.value;
-    const opacityVal = properties.opacity?.value;
-    const transparentVal = properties.transparent?.value;
+    const transmissionVal = values.transmission;
+    const opacityVal = values.opacity;
+    const transparentVal = values.transparent;
     if (typeof transmissionVal === "number" && transmissionVal > 0) {
       matOptions.transparent = false;
       matOptions.opacity = 1.0;
@@ -571,9 +570,7 @@ class MaterialFactory {
     // --- Resolve textures ---
     let hasTextures = false;
     if (textureCache) {
-      for (const [key, prop] of Object.entries(properties)) {
-        if (!prop.texture) continue;
-
+      for (const [key, textureRef] of Object.entries(textures)) {
         const mapName = PROPERTY_TO_MAP[key];
         if (!mapName) continue;
 
@@ -584,7 +581,7 @@ class MaterialFactory {
         const roleForCache = colorSpace === THREE.SRGBColorSpace
           ? "baseColorTexture"
           : "normalTexture";
-        const tex = await textureCache.get(prop.texture, roleForCache);
+        const tex = await textureCache.get(textureRef, roleForCache);
         if (tex) {
           if (textureRepeat) {
             tex.repeat.set(textureRepeat[0], textureRepeat[1]);
@@ -594,7 +591,6 @@ class MaterialFactory {
           hasTextures = true;
         }
       }
-
     }
 
     // Enable alpha cutout when an alphaMap is present
@@ -719,9 +715,8 @@ class MaterialFactory {
     const sheenRoughnessTex = await resolve(def.sheenRoughnessMap, "sheenRoughnessTexture");
     if (sheenRoughnessTex) material.sheenRoughnessMap = sheenRoughnessTex;
 
-    // Anisotropy texture skipped — CAD meshes lack tangent vectors.
-    // const anisotropyTex = await resolve(def.anisotropyMap, "anisotropyTexture");
-    // if (anisotropyTex) material.anisotropyMap = anisotropyTex;
+    const anisotropyTex = await resolve(def.anisotropyMap, "anisotropyTexture");
+    if (anisotropyTex) material.anisotropyMap = anisotropyTex;
   }
 
   /**

package/src/rendering/studio-floor.ts

@@ -77,7 +77,7 @@ class StudioFloor {
    * Create a shadow-receiving plane at the floor position.
    */
   private _createShadowPlane(zPosition: number, sceneSize: number): void {
-    const floorSize = sceneSize * 4;
+    const floorSize = sceneSize * 6;
 
     const geometry = new THREE.PlaneGeometry(floorSize, floorSize);
     const material = new THREE.ShadowMaterial({ opacity: 0.5, depthWrite: false });

package/src/scene/clipping.ts

@@ -154,6 +154,16 @@ class CenteredPlane extends THREE.Plane {
     const z = this.distanceToPoint(new THREE.Vector3(0, 0, 0));
     this.constant = z - c + value;
   }
+
+  /**
+   * Clone this CenteredPlane.
+   * Overrides THREE.Plane.clone() which calls `new this.constructor()` without
+   * arguments, causing `center` to be undefined during shadow map generation.
+   */
+  // @ts-expect-error -- THREE.Plane.clone() returns `this`, but we need a concrete CenteredPlane
+  clone(): CenteredPlane {
+    return new CenteredPlane(this.normal.clone(), this.centeredConstant, [...this.center]);
+  }
 }
 
 // ============================================================================

package/src/scene/nestedgroup.ts

@@ -142,12 +142,9 @@ function materialHasTexture(def: MaterialAppearance): boolean {
   return false;
 }
 
-/** Check whether a threejs-materials entry has texture references in its properties. */
+/** Check whether a threejs-materials entry has texture references. */
 function materialXHasTextures(entry: MaterialXMaterial): boolean {
-  for (const [, prop] of Object.entries(entry.properties)) {
-    if (prop.texture) return true;
-  }
-  return false;
+  return Object.keys(entry.textures).length > 0;
 }
 
 class NestedGroup {
@@ -322,7 +319,7 @@ class NestedGroup {
         return null;
       }
 
-      // MaterialXMaterial entry: object with `properties` key
+      // MaterialXMaterial entry: object with `values` key
       if (isMaterialXMaterial(entry)) {
         this.resolvedMaterialX.set(tag, entry);
         return entry;
@@ -339,12 +336,16 @@ class NestedGroup {
           );
           return null;
         }
-        const resolved: MaterialAppearance = { ...preset, ...appearance };
+        // Strip preset color unless the user explicitly provides one,
+        // so the leaf node's CAD color is used as fallback.
+        const { color: presetColor, ...presetRest } = preset;
+        const resolved: MaterialAppearance = "color" in appearance
+          ? { ...preset, ...appearance }
+          : { ...presetRest, ...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;
     }
@@ -1253,7 +1254,8 @@ class NestedGroup {
           if (resolved && isMaterialXMaterial(resolved)) {
             // --- threejs-materials path ---
             studioMaterial = await this.materialFactory.createStudioMaterialFromMaterialX(
-              resolved.properties,
+              resolved.values,
+              resolved.textures,
               resolved.textureRepeat,
               this._textureCache as TextureCacheInterface,
             );
@@ -1339,6 +1341,20 @@ class NestedGroup {
         studioBack = cachedBack as THREE.MeshPhysicalMaterial;
       }
 
+      // Compute tangents for anisotropic materials (required by Three.js)
+      if (
+        studioMaterial instanceof THREE.MeshPhysicalMaterial &&
+        studioMaterial.anisotropy > 0 &&
+        obj.shapeGeometry?.getAttribute("uv") != null &&
+        obj.shapeGeometry.getAttribute("tangent") == null
+      ) {
+        try {
+          obj.shapeGeometry.computeTangents();
+        } catch {
+          logger.debug(`Studio "${path}": tangent computation failed, anisotropy may have artifacts`);
+        }
+      }
+
       // Apply to ObjectGroup
       obj.enterStudioMode(
         studioMaterial instanceof THREE.MeshPhysicalMaterial ? studioMaterial : null,