three-cad-viewer 4.1.2 → 4.2.0

package/dist/ui/display.d.ts

@@ -19,6 +19,7 @@ export interface DisplayOptions {
     explodeTool: boolean;
     zscaleTool: boolean;
     zebraTool: boolean;
+    studioTool: boolean;
     glass: boolean;
     tools: boolean;
     cadWidth: number;
@@ -27,6 +28,8 @@ export interface DisplayOptions {
     treeHeight?: number;
     theme: ThemeInput;
     pinning: boolean;
+    canvas?: HTMLCanvasElement;
+    gl?: WebGLRenderingContext | WebGL2RenderingContext;
 }
 /**
  * Options for setSizes method
@@ -100,17 +103,33 @@ declare class Display {
     cadTree: HTMLElement;
     cadTreeScrollContainer: HTMLElement;
     cadTreeToggles: HTMLElement;
+    cadClipToggles: HTMLElement;
+    cadMaterialToggles: HTMLElement;
+    cadZebraToggles: HTMLElement;
+    cadStudioToggles: HTMLElement;
     cadClip: HTMLElement;
     cadMaterial: HTMLElement;
     cadZebra: HTMLElement;
+    cadStudio: HTMLElement;
+    private _spinnerEl;
+    private _warningBannerEl;
+    private _warningBannerTimer;
+    private _spinnerCount;
+    private _matEditorPath;
+    private _matEditorClones;
+    private _savedMatEditorChanges;
+    private _matEditorDragAbort;
+    private _matEditorInputAbort;
     cadInfo: HTMLElement;
     cadAnim: HTMLElement;
+    private _animWasVisible;
     cadTools: HTMLElement;
     cadHelp: HTMLElement;
     tabTree: HTMLElement;
     tabClip: HTMLElement;
     tabMaterial: HTMLElement;
     tabZebra: HTMLElement;
+    tabStudio: HTMLElement;
     tickValueElement: HTMLElement;
     tickInfoElement: HTMLElement;
     distanceMeasurementPanel: HTMLElement;
@@ -130,6 +149,12 @@ declare class Display {
     zebraCountSlider: Slider | undefined;
     zebraOpacitySlider: Slider | undefined;
     zebraDirectionSlider: Slider | undefined;
+    studioEnvIntensitySlider: Slider | undefined;
+    studioExposureSlider: Slider | undefined;
+    studioEnvRotationSlider: Slider | undefined;
+    studioShadowIntensitySlider: Slider | undefined;
+    studioShadowSoftnessSlider: Slider | undefined;
+    studioAOIntensitySlider: Slider | undefined;
     viewer: Viewer;
     state: ViewerState;
     measureTools: boolean;
@@ -147,6 +172,7 @@ declare class Display {
     lastPlaneState: boolean;
     help_shown: boolean;
     info_shown: boolean;
+    tools_shown: boolean;
     _info: Info;
     _events: StoredEvent[];
     _unsubscribers: (() => void)[];
@@ -174,6 +200,10 @@ declare class Display {
     private setupCheckEvent;
     private setupClickEvent;
     private setupRadioEvent;
+    /**
+     * Wire a select element's change event
+     */
+    private setupSelectEvent;
     /**
      * Get a DOM element by class name (internal use only).
      * @param name - Name of the DOM element class
@@ -346,6 +376,19 @@ declare class Display {
      * Show or hides ZScale tool
      */
     showZScaleTool: (flag: boolean) => void;
+    /**
+     * Deactivate any running tool and hide tool buttons for Studio mode.
+     * Called when entering Studio mode.
+     * @internal
+     */
+    private _deactivateToolsForStudio;
+    /**
+     * Restore tool button visibility after leaving Studio mode.
+     * Respects original feature flags (measureTools, selectTool).
+     * Does not auto-activate any tool.
+     * @internal
+     */
+    private _restoreToolsAfterStudio;
     /**
      * Checkbox Handler for setting the clip planes parameter
      */
@@ -395,6 +438,14 @@ declare class Display {
      * Switch to a tab (internal, called by activeTab subscription).
      */
     private switchToTab;
+    /** Show the toolbar spinner (ref-counted for overlapping async ops). */
+    private _showSpinner;
+    /** Hide the toolbar spinner (only when all pending ops complete). */
+    private _hideSpinner;
+    /** Show a warning banner in the viewport. Auto-hides after 8 seconds. */
+    private _showWarningBanner;
+    /** Hide the warning banner. */
+    private _hideWarningBanner;
     /**
      * Toggle visibility of the clipping tab
      */
@@ -404,10 +455,82 @@ declare class Display {
      * Translates button codes to CollapseState and calls viewer
      */
     handleCollapseNodes: (e: Event) => void;
+    /**
+     * Reset clip planes to default normals and slider positions
+     */
+    handleClipReset: (_e: Event) => void;
     /**
      * Reset material values to original values
      */
     handleMaterialReset: (_e: Event) => void;
+    /**
+     * Reset zebra tool to default settings
+     */
+    handleZebraReset: (_e: Event) => void;
+    /**
+     * Handler for Studio environment dropdown change
+     */
+    handleStudioEnvironment: (e: Event) => void;
+    /**
+     * Handler for Studio env intensity slider change.
+     * Slider range 0-200 with percentage=true, so value arrives as 0-2.
+     */
+    handleStudioEnvIntensity: (value: number) => void;
+    handleStudioEnvRotation: (value: number) => void;
+    /**
+     * Handler for Studio background dropdown change.
+     * Validates against the StudioBackground union before setting state.
+     */
+    handleStudioBackground: (e: Event) => void;
+    /**
+     * Handler for Studio tone mapping dropdown change.
+     * Validates against the StudioToneMapping union before setting state.
+     */
+    handleStudioToneMapping: (e: Event) => void;
+    /**
+     * Handler for Studio exposure slider change.
+     * Slider range 0-200 with percentage=true, so value arrives as 0-2.
+     */
+    handleStudioTextureMapping: (e: Event) => void;
+    handleStudioExposure: (value: number) => void;
+    handleStudioShadowIntensity: (value: number) => void;
+    handleStudioShadowSoftness: (value: number) => void;
+    /**
+     * Handler for Studio AO intensity slider change.
+     * Slider range 0-30, divided by 10 → state gets 0-3.0.
+     * A value of 0 disables AO.
+     */
+    handleStudioAOIntensity: (value: number) => void;
+    /**
+     * Handler for Studio 4K env maps checkbox change.
+     * Shows a "Loading…" indicator while the new resolution downloads.
+     */
+    handleStudio4kEnvMaps: (e: Event) => void;
+    /**
+     * Reset Studio tab values to defaults.
+     * Delegates to viewer.resetStudio() (same pattern as handleMaterialReset -> resetMaterial()).
+     */
+    handleStudioReset: (_e: Event) => void;
+    handleMatEditorToggle: (_e: Event) => void;
+    private _showMatEditorHint;
+    private openMatEditor;
+    closeMatEditor(): void;
+    /** Dispose all cloned materials, restoring originals first (call on Studio mode exit) */
+    disposeMatEditorClones(): void;
+    /** Save material editor property deltas so they survive a Studio mode leave/enter cycle. */
+    private _saveMatEditorChanges;
+    /** Reapply saved material editor changes after re-entering Studio mode. */
+    private _reapplyMatEditorChanges;
+    /**
+     * Called by viewer.ts when the selected object changes.
+     * Updates or closes the material editor if it's open.
+     */
+    onSelectionChanged(newObjectId: string | null): void;
+    handleMatEditorReset: (_e: Event) => void;
+    /** Make the material editor dialog draggable by its titlebar */
+    private _initMatEditorDrag;
+    private _buildMatEditorContent;
+    private _buildMatEditorRow;
     /**
      * Set zebra stripe count in the UI
      */
@@ -456,6 +579,21 @@ declare class Display {
      * Called from updateUI after viewer options are applied to state.
      */
     syncZebraSlidersFromState(): void;
+    /**
+     * Sync Studio slider/control UI from current state values.
+     */
+    syncStudioSlidersFromState(): void;
+    /**
+     * Ensure the environment dropdown can display a custom HDR URL.
+     * If envName isn't already an option, adds a "Custom HDR" entry.
+     * Removes stale custom entries when switching back to a built-in preset.
+     */
+    private _syncEnvDropdown;
+    /**
+     * Enable/disable the 4K checkbox based on whether the current environment
+     * is a Poly Haven preset (resolution-switchable) or a custom URL / "studio".
+     */
+    private _update4kCheckboxEnabled;
     /**
      * Refresh clipping plane position
      */
@@ -517,6 +655,15 @@ declare class Display {
      * Toggle info dialog visibility
      */
     toggleInfo: () => void;
+    /**
+     * Show or hide tools panel (tabs + content) in glass mode.
+     * Also toggles the orientation marker and animation/explode slider.
+     */
+    showToolsPanel: (flag: boolean) => void;
+    /**
+     * Toggle tools panel visibility
+     */
+    toggleToolsPanel: () => void;
     /**
      * Auto collapse tree nodes when cad width < 600
      */

package/dist/utils/decode-instances.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Decode the compressed/instanced shape format.
+ *
+ * The instanced format wraps a standard Shapes object:
+ * ```
+ * { instances: [ { vertices: {shape,dtype,buffer,codec}, ... }, ... ],
+ *   shapes:    { version, parts, loc, name, id, bb, ... } }
+ * ```
+ *
+ * Each instance contains base64-encoded geometry buffers. Parts reference
+ * instances via `"shape": { "ref": N }`. After decoding, the result is a
+ * standard Shapes tree with TypedArrays — identical to the existing format.
+ */
+import type { Shapes } from "../core/types.js";
+/** A single base64-encoded buffer entry. */
+interface EncodedBuffer {
+    shape: number[];
+    dtype: "float32" | "int32" | "uint32";
+    buffer: string;
+    codec: "b64";
+}
+/** An encoded geometry instance (all 9 buffer fields + optional uvs). */
+interface EncodedInstance {
+    vertices: EncodedBuffer;
+    triangles: EncodedBuffer;
+    normals: EncodedBuffer;
+    edges: EncodedBuffer;
+    obj_vertices: EncodedBuffer;
+    face_types: EncodedBuffer;
+    edge_types: EncodedBuffer;
+    triangles_per_face: EncodedBuffer;
+    segments_per_edge: EncodedBuffer;
+    uvs?: EncodedBuffer;
+}
+/** Top-level structure of the instanced format. */
+interface InstancedData {
+    instances: EncodedInstance[];
+    shapes: Shapes;
+}
+/**
+ * Walk the shapes tree and decode any inline encoded buffers found in
+ * part.shape objects. This handles edge/vertex-only objects that embed
+ * encoded buffers directly (not via instance refs).
+ */
+declare function decodeInlineBuffers(shapes: Shapes): void;
+/**
+ * Type guard: check if data is in the instanced format.
+ * Detected by the presence of an `instances` array and a `shapes` object.
+ */
+declare function isInstancedFormat(data: unknown): data is InstancedData;
+/**
+ * Decode the instanced format into a standard Shapes object.
+ *
+ * 1. Decode all instance buffers from base64 → TypedArrays
+ * 2. Walk the shapes tree and replace { ref: N } with decoded instances
+ * 3. Return the unwrapped Shapes object
+ */
+declare function decodeInstancedFormat(data: InstancedData): Shapes;
+export { isInstancedFormat, decodeInstancedFormat, decodeInlineBuffers };
+export type { InstancedData, EncodedBuffer, EncodedInstance };

package/dist/utils/utils.d.ts

@@ -40,6 +40,16 @@ interface MaterialLike {
     emissiveMap?: Disposable | null;
     alphaMap?: Disposable | null;
     bumpMap?: Disposable | null;
+    transmissionMap?: Disposable | null;
+    clearcoatMap?: Disposable | null;
+    clearcoatRoughnessMap?: Disposable | null;
+    clearcoatNormalMap?: Disposable | null;
+    thicknessMap?: Disposable | null;
+    specularIntensityMap?: Disposable | null;
+    specularColorMap?: Disposable | null;
+    sheenColorMap?: Disposable | null;
+    sheenRoughnessMap?: Disposable | null;
+    anisotropyMap?: Disposable | null;
 }
 interface MeshLike {
     geometry?: GeometryLike | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "three-cad-viewer",
-  "version": "4.1.2",
+  "version": "4.2.0",
   "type": "module",
   "description": "WebGL-based CAD viewer built on Three.js with clipping planes, measurement tools, and tree navigation",
   "repository": {
@@ -49,7 +49,9 @@
   "author": "Bernhard Walter",
   "license": "MIT",
   "dependencies": {
-    "three": "0.180.0"
+    "three": "0.183.0",
+    "n8ao": "1.10.1",
+    "postprocessing": "6.38.3"
   },
   "devDependencies": {
     "@babel/core": "^7.28.0",

package/src/_version.ts

@@ -1 +1 @@
-export const version: string = "4.1.2";
+export const version: string = "4.2.0";

package/src/camera/camera.ts

@@ -73,6 +73,14 @@ const cameraUp: Record<UpMode, [number, number, number]> = {
 class Camera {
   private static readonly DISTANCE_FACTOR = 5;
 
+  /**
+   * Near plane factor: near = max(0.1, NEAR_FACTOR * distance).
+   * With far = 100 * distance, this gives a far/near ratio of 10,000:1,
+   * which is comfortable for 24-bit depth buffers and avoids z-fighting
+   * on large models (e.g. toycar at ~1100 unit bounding radius).
+   */
+  private static readonly NEAR_FACTOR = 0.01;
+
   target: THREE.Vector3;
   ortho: boolean;
   up: UpMode;
@@ -83,6 +91,14 @@ class Camera {
   oCamera!: THREE.OrthographicCamera; // Initialized in constructor
   camera!: THREE.PerspectiveCamera | THREE.OrthographicCamera; // Set in constructor
 
+  /**
+   * Compute the near clipping plane from the bounding radius.
+   * Keeps the far/near ratio bounded for depth buffer precision.
+   */
+  private static _computeNear(distance: number): number {
+    return Math.max(0.1, Camera.NEAR_FACTOR * distance);
+  }
+
   /**
    * Create a combined camera (orthographic and perspective).
    * @param width - canvas width.
@@ -120,12 +136,10 @@ class Camera {
 
     this.camera_distance = Camera.DISTANCE_FACTOR * distance;
 
-    this.pCamera = new THREE.PerspectiveCamera(
-      fov,
-      aspect,
-      0.1,
-      100 * distance,
-    );
+    const near = Camera._computeNear(distance);
+    const far = 100 * distance;
+
+    this.pCamera = new THREE.PerspectiveCamera(fov, aspect, near, far);
     this.pCamera.up.set(...cameraUp[this.up]);
     this.pCamera.lookAt(this.target);
 
@@ -137,8 +151,8 @@ class Camera {
       pSize[0],
       pSize[1],
       -pSize[1],
-      0.1,
-      100 * distance,
+      near,
+      far,
     );
     this.oCamera.up.set(...cameraUp[this.up]);
     this.oCamera.lookAt(this.target);
@@ -148,12 +162,15 @@ class Camera {
   }
 
   /**
-   * Update the far clipping plane for both cameras.
-   * @param distance - The new bounding radius to base the far plane on.
+   * Update the near/far clipping planes for both cameras.
+   * @param distance - The new bounding radius to base the clipping planes on.
    */
   updateFarPlane(distance: number): void {
+    const near = Camera._computeNear(distance);
     const far = 100 * distance;
+    this.pCamera.near = near;
     this.pCamera.far = far;
+    this.oCamera.near = near;
     this.oCamera.far = far;
     this.camera.updateProjectionMatrix();
   }