three-cad-viewer 4.1.2 → 4.2.0

package/dist/scene/nestedgroup.d.ts

@@ -2,12 +2,13 @@ import * as THREE from "three";
 import { BoundingBox } from "./bbox.js";
 import { ObjectGroup, isObjectGroup } from "./objectgroup.js";
 import { MaterialFactory } from "../rendering/material-factory.js";
-import type { ZebraColorScheme, ZebraMappingMode, Shapes, ColorValue } from "../core/types";
+import type { ZebraColorScheme, ZebraMappingMode, StudioTextureMapping, Shapes, ColorValue, MaterialAppearance, MaterialXMaterial, TextureEntry } from "../core/types";
 interface ShapeData {
     vertices: Float32Array | number[][];
     normals: Float32Array | number[][];
     triangles: Uint32Array | number[][];
     edges?: Float32Array | number[][];
+    uvs?: Float32Array | number[];
 }
 interface EdgeData {
     edges: Float32Array | number[][];
@@ -44,6 +45,7 @@ interface ShapeEntry {
         width: number;
         height: number;
     };
+    material?: string;
 }
 type GroupsMap = Record<string, ObjectGroup | CompoundGroup>;
 /**
@@ -56,32 +58,6 @@ declare class CompoundGroup extends THREE.Group {
     /** Type guard property following Three.js convention */
     readonly isCompoundGroup = true;
 }
-/**
- * Manages hierarchical 3D geometry rendering from tessellated CAD data.
- *
- * NestedGroup is the central scene graph manager that:
- * - Parses Shapes data into Three.js geometry
- * - Creates ObjectGroup instances for individual shapes, edges, and vertices
- * - Maintains a flat `groups` map for path-based access
- * - Handles materials, transparency, and clipping planes
- *
- * ## Architecture
- * ```
- * NestedGroup (manager)
- *   └── rootGroup (THREE.Group)
- *         └── CompoundGroup (per assembly)
- *               └── ObjectGroup (per shape/edge/vertex)
- *                     └── THREE.Mesh / LineSegments2
- * ```
- *
- * ## Key Methods
- * - `render()`: Build geometry from Shapes data
- * - `setTransparent()`: Toggle transparency mode
- * - `setClipPlanes()`: Apply clipping planes
- * - `groups[path]`: Access ObjectGroup by path
- *
- * @internal - This is an internal class used by Viewer
- */
 declare class NestedGroup {
     shapes: Shapes;
     width: number;
@@ -103,6 +79,16 @@ declare class NestedGroup {
     groups: GroupsMap;
     clipPlanes: THREE.Plane[] | null;
     materialFactory: MaterialFactory;
+    texturesTable: Record<string, TextureEntry> | null;
+    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;
+    private _studioMaterialCache;
+    /** Sharing keys of materials that have textures (for UV generation on cache hits) */
+    private _texturedMaterialKeys;
+    private _isStudioMode;
     /**
      * Create a NestedGroup for rendering CAD geometry.
      * @param shapes - The tessellated shape data to render.
@@ -121,6 +107,26 @@ declare class NestedGroup {
      * Dispose of all resources and clean up memory.
      */
     dispose(): void;
+    /**
+     * 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;
     /**
      * Check if array is nested (number[][]).
      */
@@ -272,6 +278,37 @@ declare class NestedGroup {
      * Set the mapping mode for zebra stripes.
      */
     setZebraMappingMode(flag: ZebraMappingMode): void;
+    /**
+     * 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
+     */
+    enterStudioMode(textureMapping?: StudioTextureMapping): Promise<string[]>;
+    /**
+     * Leave Studio mode: restore CAD materials on all ObjectGroups.
+     * Does NOT clear the material cache (allows fast re-entry).
+     */
+    leaveStudioMode(): void;
+    /**
+     * Clear cached Studio materials so they are rebuilt on next enterStudioMode.
+     */
+    clearStudioMaterialCache(): void;
+    /**
+     * Set edge visibility across all ObjectGroups while in Studio mode.
+     * @param visible - Whether edges should be visible
+     */
+    setStudioShowEdges(visible: boolean): void;
+    /**
+     * Dispose all Studio mode resources (material cache + texture cache).
+     */
+    private _disposeStudioResources;
 }
 /**
  * Type guard to check if an object is a CompoundGroup instance.

package/dist/scene/objectgroup.d.ts

@@ -69,9 +69,17 @@ declare 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;
+    private _cadFrontMaterial;
+    private _cadBackMaterial;
+    private _cadOriginalColor;
+    private _cadOriginalBackColor;
+    private _isStudioMode;
+    private _cadEdgesVisible;
     /**
      * Create an ObjectGroup for managing a CAD object's visual representation.
      * @param opacity - Default opacity value (0.0 to 1.0).
@@ -86,6 +94,10 @@ declare class ObjectGroup extends THREE.Group {
      * Get the zebra tool, creating it on first access.
      */
     get zebra(): ZebraTool;
+    /**
+     * Whether this ObjectGroup is currently in Studio mode.
+     */
+    get isStudioMode(): boolean;
     /**
      * Dispose of all resources and clean up memory.
      * Releases geometry, materials, children, and zebra tool.
@@ -252,6 +264,41 @@ declare class ObjectGroup extends THREE.Group {
      * Set the mapping mode for zebra stripes.
      */
     setZebraMappingMode(value: ZebraMappingMode): void;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
 }
 /**
  * Type guard to check if an object is an ObjectGroup instance.

package/dist/three-cad-viewer.css

@@ -4,6 +4,7 @@
   --tcv-font-color: #333;
   --tcv-bg-color: #fff;
   --tcv-bg-overlay-color: rgba(255, 255, 255, 0.7);
+  --tcv-bg-overlay-rest-color: rgba(255, 255, 255, 0.14);
   --tcv-bg-highlight-color: #ddd;
   --tcv-bg-pressed-color: #eee;
   --tcv-bg-pressed-border-color: #bbb;
@@ -63,6 +64,7 @@
   --tcv-font-color: #ddd;
   --tcv-bg-color: #444;
   --tcv-bg-overlay-color: rgba(68, 68, 68, 0.7);
+  --tcv-bg-overlay-rest-color: rgba(68, 68, 68, 0.14);
   --tcv-bg-highlight-color: rgb(104, 104, 104);
   --tcv-bg-pressed-color: rgb(94, 94, 94);
   --tcv-bg-pressed-border-color: #999;
@@ -258,6 +260,7 @@ input[type="radio"] {
 
 
 .tcv_cad_viewer {
+  --tcv-ui-row-gap: 8px;
   margin: 0;
   display: flex;
   flex-direction: column;
@@ -292,7 +295,7 @@ input[type="radio"] {
 
 .tcv_cad_tree_toggles {
   text-align: right;
-  margin-right: 0px;
+  padding: 0 4px;
   margin-bottom: 3px;
 }
 
@@ -310,6 +313,7 @@ input[type="radio"] {
 .tcv_cad_tree_glass {
   border: none !important;
   height: fit-content;
+  background-color: var(--tcv-bg-overlay-rest-color);
 }
 
 .tcv_cad_tree_glass:hover {
@@ -321,8 +325,6 @@ input[type="radio"] {
   height: 146px;
   font-family: sans-serif;
   font-size: 12px;
-  border-style: solid;
-  border-width: 1px;
   overflow: hidden;
   user-select:text;
 }
@@ -353,12 +355,38 @@ input[type="radio"] {
   font-weight: bold;
   margin-left: 4px;
   padding-bottom: 4px;
+}
+
+.tcv_toggle_tools {
+  vertical-align: middle;
+  display: inline-block;
+  width: 0.8rem;
+  cursor: pointer;
+}
+
+.tcv_toggle_tools_wrapper {
+  display: none;
+  margin-left: 4px;
+  cursor: pointer;
+}
+
+.tcv_tools_label {
+  font-size: 12px;
+  font-family: sans-serif;
+  font-weight: bold;
+  margin-left: 4px;
+  padding-bottom: 4px;
   vertical-align: middle;
   user-select: none;
 }
 
 .tcv_cad_info_glass {
   display: none;
+  border: none !important;
+  background: var(--tcv-bg-overlay-rest-color);
+}
+
+.tcv_cad_info_glass:hover {
   background: var(--tcv-bg-overlay-color);
 }
 
@@ -474,7 +502,7 @@ th {
 
 .tcv_cad_animation {
   height: 36px;
-  background-color: var(--tcv-bg-overlay-color);
+  background-color: var(--tcv-bg-overlay-rest-color);
   border: none;
   margin: 0;
   padding: 0px;
@@ -484,9 +512,13 @@ th {
   z-index: 100;
 }
 
+.tcv_cad_animation:hover {
+  background-color: var(--tcv-bg-overlay-color);
+}
+
 .tcv_cad_zscale {
   height: 36px;
-  background-color: var(--tcv-bg-overlay-color);
+  background-color: var(--tcv-bg-overlay-rest-color);
   border: none;
   margin: 0;
   padding: 0px;
@@ -497,6 +529,10 @@ th {
   align-content: center;
 }
 
+.tcv_cad_zscale:hover {
+  background-color: var(--tcv-bg-overlay-color);
+}
+
 .tcv_cad_tools {
   height: 38px;
   background-color: var(--tcv-bg-overlay-color);
@@ -552,7 +588,7 @@ th {
 }
 
 .tcv_box_content {
-  overflow: scroll;
+  overflow: auto;
   height: 100%;
   /* margin: 0px 0px 0px 4px; */
   padding-top: 2px;
@@ -658,7 +694,10 @@ input[type="button"] {
   /* margin-bottom: 6px; */
   background-color: transparent;
   color: var(--tcv-font-color);
-  font-size: 14px;
+  font-size: 12px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
 }
 
 .tcv_tab:hover {
@@ -776,47 +815,60 @@ input[type="button"] {
 }
 
 .tcv_slider_group {
-  margin-bottom: 10px;
+  margin-bottom: var(--tcv-ui-row-gap);
+}
+
+.tcv_slider_group > div {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+}
+
+.tcv_slider_group > div:first-child {
+  align-items: flex-end;
+}
+
+.tcv_slider_group .tcv_label {
+  margin-bottom: 0;
 }
 
 .tcv_material_ambientlight {
   margin-top: 4px;
 }
 
-.tcv_cad_clip_container {
-  margin-top: 14px;
-  overflow: hidden;
+.tcv_cad_material_container .tcv_studio_slider_group {
+  width: 60%;
 }
 
-.tcv_cad_material_container {
+.tcv_cad_clip_container,
+.tcv_cad_material_container,
+.tcv_cad_zebra_container,
+.tcv_cad_studio_container {
   overflow: hidden;
+  padding: 0 4px;
 }
 
-.tcv_cad_zebra_container {
-  overflow: hidden;
+.tcv_cad_clip_container .tcv_label,
+.tcv_cad_material_container .tcv_label,
+.tcv_cad_zebra_container .tcv_label,
+.tcv_cad_studio_container .tcv_label {
+  margin-left: 0;
+  margin-right: 0;
 }
 
-.tcv_zebra_stripe_count {
-  margin-top: 20px;
-}
 
 .tcv_zebra_radio {
-  margin-top: 8px;
-  margin-bottom: 4px;
+  margin-bottom: var(--tcv-ui-row-gap);
   margin-left: -3px;
 }
 
-.tcv_zebra_mapping {
-  margin-top: 8px;
-  margin-bottom: 4px;
-}
-
 .tcv_clip_checks {
-  margin-top: 20px;
+  margin-top: var(--tcv-ui-row-gap);
 }
 
 .tcv_clip_input {
-  width: 25%;
+  width: 36px;
+  flex-shrink: 0;
   border: 1px solid #d3d3d3;
   background-color: var(--tcv-bg-overlay-color);
   color: var(--tcv-font-color);
@@ -825,10 +877,11 @@ input[type="button"] {
 .tcv_clip_slider {
   -webkit-appearance: none;
   appearance: none;
-  width: 60%;
+  flex: 1;
+  min-width: 0;
   height: 5px;
   border-radius: 2px;
-  background: #d3d3d3;
+  background: #a0a0a0;
   outline: none;
   opacity: 0.7;
   -webkit-transition: 0.2s;
@@ -860,7 +913,6 @@ input[type="button"] {
 }
 
 .tcv_lbl_norm_plane1 {
-  margin-top: 20px;
   color: var(--tcv-x-color);
 }
 
@@ -955,6 +1007,126 @@ input[type="button"] {
   font-size: 12px;
 }
 
+.tcv_studio_select {
+  font-family: sans-serif;
+  font-size: 13px;
+  padding: 2px 4px;
+  border: 1px solid #d3d3d3;
+  border-radius: 3px;
+  background-color: var(--tcv-bg-overlay-color);
+  color: var(--tcv-font-color);
+  width: 55%;
+  flex-shrink: 0;
+  margin-left: auto;
+  outline: none;
+}
+
+.tcv_studio_texture_mapping {
+  width: auto;
+}
+
+.tcv_studio_select:hover {
+  opacity: 1;
+}
+
+.tcv_studio_select option {
+  background-color: var(--tcv-bg-color);
+  color: var(--tcv-font-color);
+}
+
+.tcv_studio_row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: var(--tcv-ui-row-gap);
+}
+
+.tcv_studio_row > .tcv_label {
+  margin-left: 0;
+  padding-bottom: 0;
+  flex-shrink: 0;
+}
+
+.tcv_studio_slider_group {
+  display: flex;
+  align-items: center;
+  width: 55%;
+  flex-shrink: 0;
+  margin-left: auto;
+  gap: 4px;
+}
+
+.tcv_studio_slider_group > .tcv_clip_slider {
+  flex: 1;
+  width: auto;
+  min-width: 0;
+}
+
+.tcv_studio_slider_group > .tcv_clip_input {
+  width: 36px;
+  flex-shrink: 0;
+}
+
+.tcv_studio_checks {
+  display: flex;
+  gap: 16px;
+  margin-top: var(--tcv-ui-row-gap);
+  margin-bottom: var(--tcv-ui-row-gap);
+}
+
+.tcv_studio_4k_row {
+  /* Align checkbox with the slider/dropdown column (45% label + 55% control) */
+  margin-left: 45%;
+  gap: 4px;
+}
+
+.tcv_studio_group_spacer {
+  height: calc(var(--tcv-ui-row-gap) * 0.6);
+}
+
+.tcv_studio_info {
+  font-size: 12px;
+  margin-top: 8px;
+  color: var(--tcv-font-color);
+  opacity: 0.7;
+  font-style: italic;
+}
+
+.tcv_warning_banner {
+  position: absolute;
+  top: 4px;
+  left: 50%;
+  transform: translateX(-50%);
+  z-index: 100;
+  background: #e8a735;
+  color: #000;
+  padding: 4px 12px;
+  border-radius: 4px;
+  font-size: 12px;
+  line-height: 1.4;
+  max-width: 80%;
+  text-align: center;
+  pointer-events: auto;
+  box-shadow: 0 1px 4px rgba(0,0,0,0.3);
+}
+
+.tcv_studio_spinner {
+  display: none;
+  width: 8px;
+  height: 8px;
+  border: 2px solid var(--tcv-font-color);
+  border-top-color: transparent;
+  border-radius: 50%;
+  animation: tcv_spin 0.7s linear infinite;
+  opacity: 0.6;
+  float: left;
+  margin-top: 5px;
+}
+
+@keyframes tcv_spin {
+  to { transform: rotate(360deg); }
+}
+
 .tcv_filter_menu {
   position: relative;
 }
@@ -1253,4 +1425,142 @@ input[type="button"] {
 
 .tcv_angle_val {
     text-align: right;
+}
+
+/* MATERIAL EDITOR PANEL */
+
+.tcv_mat_editor {
+    position: absolute;
+    top: 8px;
+    right: 8px;
+    width: 250px;
+    max-height: calc(100% - 16px);
+    display: flex;
+    flex-direction: column;
+    background-color: var(--tcv-bg-overlay-rest-color);
+    border: 1px solid lightgray;
+    border-radius: 6px;
+    font-family: sans-serif;
+    font-size: 13px;
+    color: var(--tcv-font-color);
+    user-select: none;
+    z-index: 10;
+    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
+}
+
+.tcv_mat_editor:hover {
+    background-color: var(--tcv-bg-overlay-color);
+}
+
+.tcv_mat_editor_titlebar {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 4px 6px;
+    border-bottom: 1px solid lightgray;
+    background-color: var(--tcv-bg-overlay-color);
+    border-radius: 5px 5px 0 0;
+    flex-shrink: 0;
+    cursor: move;
+}
+
+.tcv_mat_editor_titlebar_btns {
+    display: flex;
+    gap: 2px;
+    flex-shrink: 0;
+}
+
+.tcv_mat_editor_title {
+    font-weight: bold;
+    font-size: 12px;
+}
+
+.tcv_mat_editor_close {
+    cursor: pointer;
+}
+
+.tcv_mat_editor_path {
+    padding: 3px 6px;
+    font-size: 11px;
+    color: var(--tcv-font-color);
+    opacity: 0.7;
+    border-bottom: 1px solid lightgray;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    flex-shrink: 0;
+    user-select: text;
+}
+
+.tcv_mat_editor_content {
+    padding: 6px;
+    overflow-y: auto;
+    flex: 1;
+    min-height: 0;
+}
+
+.tcv_mat_editor_section {
+    font-size: 11px;
+    font-weight: bold;
+    text-transform: uppercase;
+    letter-spacing: 0.5px;
+    color: var(--tcv-font-color);
+    opacity: 0.6;
+    margin-top: 8px;
+    margin-bottom: 4px;
+    padding-bottom: 2px;
+    border-bottom: 1px solid var(--tcv-bg-overlay-color);
+}
+
+.tcv_mat_editor_section:first-child {
+    margin-top: 0;
+}
+
+.tcv_mat_editor_row {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    margin-bottom: 5px;
+}
+
+.tcv_mat_editor_label {
+    font-size: 12px;
+    color: var(--tcv-font-color);
+    flex-shrink: 0;
+    max-width: 45%;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+
+/* Reuse tcv_studio_slider_group layout for slider + value */
+.tcv_mat_editor_slider_group {
+    display: flex;
+    align-items: center;
+    width: 52%;
+    flex-shrink: 0;
+    margin-left: auto;
+    gap: 4px;
+}
+
+/* Sliders reuse tcv_clip_slider class (set in JS) */
+.tcv_mat_editor_slider_group > .tcv_clip_slider {
+    flex: 1;
+    width: auto;
+    min-width: 0;
+}
+
+/* Value inputs reuse tcv_clip_input class (set in JS) */
+.tcv_mat_editor_slider_group > .tcv_clip_input {
+    width: 36px;
+    flex-shrink: 0;
+}
+
+.tcv_mat_editor_changed {
+    color: #cc3333 !important;
+}
+
+.tcv_mat_editor_toggle.tcv_active {
+    background-color: var(--tcv-bg-overlay-color);
+    border-radius: 6px;
 }