three-cad-viewer 3.6.3 → 4.1.1

package/Readme.md

@@ -1,10 +1,20 @@
 # A threejs based CAD viewer
 
-## Overview
+A CAD viewer component based on three.js. The CAD viewer can visualize low level `threejs` objects (tessellated objects)
+
+![three-js-cad-viewer](overview.png)
 
-The CAD viewer can visualize low level `threejs` objects (tessellated objects)
+⇒ [Live Examples](https://bernhard-42.github.io/three-cad-viewer/example.html)
 
-[Live Examples](https://bernhard-42.github.io/three-cad-viewer/example.html)
+## Getting started
+
+1. [Install yarn](https://classic.yarnpkg.com/en/docs/install) on your system (ie. `npm i -g yarn`) if not already done;
+2. Clone the repository: `git clone https://github.com/bernhard-42/three-cad-viewer.git && cd three-cad-viewer`;
+3. Run `yarn install` to install dependencies
+4. Start web server: `yarn run start` and go to the page displayed in the logs (ie. `127.0.0.1:8080`)
+5. Build project: `yarn run clean; yarn run build; yarn run docs`;
+
+## Overview
 
 ### Shape and Shapes
 
@@ -40,14 +50,6 @@ The value 2 is reserved for nodes and shows a mixed state, i.d. some of the chil
 
 For the `States` object, see [Class States](https://bernhard-42.github.io/three-cad-viewer/global.html#States)
 
-### Getting started
-
-1. [Install yarn](https://classic.yarnpkg.com/en/docs/install) on your system (ie. `npm i -g yarn`) if not already done;
-2. Clone the repository: `git clone https://github.com/bernhard-42/three-cad-viewer.git && cd three-cad-viewer`;
-3. Run `yarn install` to install dependencies
-4. Start web server: `yarn run start` and go to the page displayed in the logs (ie. `127.0.0.1:8080`)
-5. Build project: `yarn run clean; yarn run build; yarn run docs`;
-
 ## Skeleton:
 
 ```html
@@ -68,24 +70,24 @@ For the `States` object, see [Class States](https://bernhard-42.github.io/three-
         theme: "browser",
         pinning: true,
         keymap: {
-          "shift": "shiftKey",
-          "ctrl": "ctrlKey",
-          "meta": "metaKey"
-        }
+          shift: "shiftKey",
+          ctrl: "ctrlKey",
+          meta: "metaKey",
+        },
       };
 
       const renderOptions = {
         ambientIntensity: 1.0,
         directIntensity: 1.1,
-        metalness: 0.30,
+        metalness: 0.3,
         roughness: 0.65,
         edgeColor: 0x707070,
         defaultOpacity: 0.5,
         normalLen: 0,
       };
       const viewerOptions = {
-        "target":[0,0,0], 
-        "up": "Z"
+        target: [0, 0, 0],
+        up: "Z",
       };
 
       const shapes = {
@@ -98,36 +100,40 @@ For the `States` object, see [Class States](https://bernhard-42.github.io/three-
             name: "Workplane(Solid)",
             shape: {
               vertices: [
-                -0.5, -0.5, -0.5, -0.5, -0.5, 0.5, -0.5, 0.5, -0.5, -0.5, 0.5, 0.5,
-                0.5, -0.5, -0.5, 0.5, -0.5, 0.5, 0.5, 0.5, -0.5, 0.5, 0.5, 0.5, -0.5,
-                -0.5, -0.5, 0.5, -0.5, -0.5, -0.5, -0.5, 0.5, 0.5, -0.5, 0.5, -0.5,
-                0.5, -0.5, 0.5, 0.5, -0.5, -0.5, 0.5, 0.5, 0.5, 0.5, 0.5, -0.5, -0.5,
-                -0.5, -0.5, 0.5, -0.5, 0.5, -0.5, -0.5, 0.5, 0.5, -0.5, -0.5, -0.5,
-                0.5, -0.5, 0.5, 0.5, 0.5, -0.5, 0.5, 0.5, 0.5, 0.5,
+                -0.5, -0.5, -0.5, -0.5, -0.5, 0.5, -0.5, 0.5, -0.5, -0.5, 0.5,
+                0.5, 0.5, -0.5, -0.5, 0.5, -0.5, 0.5, 0.5, 0.5, -0.5, 0.5, 0.5,
+                0.5, -0.5, -0.5, -0.5, 0.5, -0.5, -0.5, -0.5, -0.5, 0.5, 0.5,
+                -0.5, 0.5, -0.5, 0.5, -0.5, 0.5, 0.5, -0.5, -0.5, 0.5, 0.5, 0.5,
+                0.5, 0.5, -0.5, -0.5, -0.5, -0.5, 0.5, -0.5, 0.5, -0.5, -0.5,
+                0.5, 0.5, -0.5, -0.5, -0.5, 0.5, -0.5, 0.5, 0.5, 0.5, -0.5, 0.5,
+                0.5, 0.5, 0.5,
               ],
               triangles: [
-                1, 2, 0, 1, 3, 2, 5, 4, 6, 5, 6, 7, 11, 8, 9, 11, 10, 8, 15, 13, 12,
-                15, 12, 14, 19, 16, 17, 19, 18, 16, 23, 21, 20, 23, 20, 22,
+                1, 2, 0, 1, 3, 2, 5, 4, 6, 5, 6, 7, 11, 8, 9, 11, 10, 8, 15, 13,
+                12, 15, 12, 14, 19, 16, 17, 19, 18, 16, 23, 21, 20, 23, 20, 22,
               ],
               normals: [
-                -1.0, -0.0, 0.0, -1.0, -0.0, 0.0, -1.0, -0.0, 0.0, -1.0, -0.0, 0.0,
-                1.0, 0.0, -0.0, 1.0, 0.0, -0.0, 1.0, 0.0, -0.0, 1.0, 0.0, -0.0, 0.0,
-                -1.0, -0.0, 0.0, -1.0, -0.0, 0.0, -1.0, -0.0, 0.0, -1.0, -0.0, -0.0,
-                1.0, 0.0, -0.0, 1.0, 0.0, -0.0, 1.0, 0.0, -0.0, 1.0, 0.0, -0.0, -0.0,
-                -1.0, -0.0, -0.0, -1.0, -0.0, -0.0, -1.0, -0.0, -0.0, -1.0, 0.0, 0.0,
-                1.0, 0.0, 0.0, 1.0, 0.0, 0.0, 1.0, 0.0, 0.0, 1.0,
+                -1.0, -0.0, 0.0, -1.0, -0.0, 0.0, -1.0, -0.0, 0.0, -1.0, -0.0,
+                0.0, 1.0, 0.0, -0.0, 1.0, 0.0, -0.0, 1.0, 0.0, -0.0, 1.0, 0.0,
+                -0.0, 0.0, -1.0, -0.0, 0.0, -1.0, -0.0, 0.0, -1.0, -0.0, 0.0,
+                -1.0, -0.0, -0.0, 1.0, 0.0, -0.0, 1.0, 0.0, -0.0, 1.0, 0.0,
+                -0.0, 1.0, 0.0, -0.0, -0.0, -1.0, -0.0, -0.0, -1.0, -0.0, -0.0,
+                -1.0, -0.0, -0.0, -1.0, 0.0, 0.0, 1.0, 0.0, 0.0, 1.0, 0.0, 0.0,
+                1.0, 0.0, 0.0, 1.0,
               ],
               edges: [
-                -0.5, -0.5, -0.5, -0.5, -0.5, 0.5, -0.5, -0.5, 0.5, -0.5, 0.5, 0.5,
-                -0.5, 0.5, -0.5, -0.5, 0.5, 0.5, -0.5, -0.5, -0.5, -0.5, 0.5, -0.5,
-                0.5, -0.5, -0.5, 0.5, -0.5, 0.5, 0.5, -0.5, 0.5, 0.5, 0.5, 0.5, 0.5,
-                0.5, -0.5, 0.5, 0.5, 0.5, 0.5, -0.5, -0.5, 0.5, 0.5, -0.5, -0.5, -0.5,
-                -0.5, 0.5, -0.5, -0.5, -0.5, -0.5, 0.5, 0.5, -0.5, 0.5, -0.5, 0.5,
-                -0.5, 0.5, 0.5, -0.5, -0.5, 0.5, 0.5, 0.5, 0.5, 0.5,
+                -0.5, -0.5, -0.5, -0.5, -0.5, 0.5, -0.5, -0.5, 0.5, -0.5, 0.5,
+                0.5, -0.5, 0.5, -0.5, -0.5, 0.5, 0.5, -0.5, -0.5, -0.5, -0.5,
+                0.5, -0.5, 0.5, -0.5, -0.5, 0.5, -0.5, 0.5, 0.5, -0.5, 0.5, 0.5,
+                0.5, 0.5, 0.5, 0.5, -0.5, 0.5, 0.5, 0.5, 0.5, -0.5, -0.5, 0.5,
+                0.5, -0.5, -0.5, -0.5, -0.5, 0.5, -0.5, -0.5, -0.5, -0.5, 0.5,
+                0.5, -0.5, 0.5, -0.5, 0.5, -0.5, 0.5, 0.5, -0.5, -0.5, 0.5, 0.5,
+                0.5, 0.5, 0.5,
               ],
               obj_vertices: [
-                -0.5, -0.5, 0.5, -0.5, -0.5, -0.5, -0.5, 0.5, 0.5, -0.5, 0.5, -0.5,
-                0.5, -0.5, 0.5, 0.5, -0.5, -0.5, 0.5, 0.5, 0.5, 0.5, 0.5, -0.5,
+                -0.5, -0.5, 0.5, -0.5, -0.5, -0.5, -0.5, 0.5, 0.5, -0.5, 0.5,
+                -0.5, 0.5, -0.5, 0.5, 0.5, -0.5, -0.5, 0.5, 0.5, 0.5, 0.5, 0.5,
+                -0.5,
               ],
               face_types: [0, 0, 0, 0, 0, 0],
               edge_types: [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
@@ -154,7 +160,14 @@ For the `States` object, see [Class States](https://bernhard-42.github.io/three-
         name: "Group",
         id: "/Group",
         normal_len: 0,
-        bb: { xmin: -0.5, xmax: 0.5, ymin: -0.5, ymax: 0.5, zmin: -0.5, zmax: 0.5 },
+        bb: {
+          xmin: -0.5,
+          xmax: 0.5,
+          ymin: -0.5,
+          ymax: 0.5,
+          zmin: -0.5,
+          zmax: 0.5,
+        },
       };
 
       // 1) get the container
@@ -166,9 +179,66 @@ For the `States` object, see [Class States](https://bernhard-42.github.io/three-
       // 3) Create the CAD viewer
       const viewer = new Viewer(display, viewerOptions, nc);
       // or viewer.clear() if the viewer exists
-      
+
       // 4) Render the shapes and provide states for the navigation tree in this viewer
       viewer.render(shapes, renderOptions, viewerOptions);
+
+      // 5) Dynamically add a second box offset by 2 units along X.
+      //    addPart(parentPath, partData) builds the absolute path from the
+      //    parent and the part's name: "/Group" + "/" + "Box2" = "/Group/Box2"
+      const newPart = {
+        version: 3,
+        name: "Box2",
+        type: "shapes",
+        subtype: "solid",
+        shape: {
+          vertices: [
+            1.5, -0.5, -0.5, 1.5, -0.5, 0.5, 1.5, 0.5, -0.5, 1.5, 0.5, 0.5, 2.5,
+            -0.5, -0.5, 2.5, -0.5, 0.5, 2.5, 0.5, -0.5, 2.5, 0.5, 0.5, 1.5,
+            -0.5, -0.5, 2.5, -0.5, -0.5, 1.5, -0.5, 0.5, 2.5, -0.5, 0.5, 1.5,
+            0.5, -0.5, 2.5, 0.5, -0.5, 1.5, 0.5, 0.5, 2.5, 0.5, 0.5, 1.5, -0.5,
+            -0.5, 2.5, -0.5, -0.5, 1.5, 0.5, -0.5, 2.5, 0.5, -0.5, 1.5, -0.5,
+            0.5, 2.5, -0.5, 0.5, 1.5, 0.5, 0.5, 2.5, 0.5, 0.5,
+          ],
+          triangles: [
+            1, 2, 0, 1, 3, 2, 5, 4, 6, 5, 6, 7, 11, 8, 9, 11, 10, 8, 15, 13, 12,
+            15, 12, 14, 19, 16, 17, 19, 18, 16, 23, 21, 20, 23, 20, 22,
+          ],
+          normals: [
+            -1, 0, 0, -1, 0, 0, -1, 0, 0, -1, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0,
+            1, 0, 0, 0, -1, 0, 0, -1, 0, 0, -1, 0, 0, -1, 0, 0, 1, 0, 0, 1, 0,
+            0, 1, 0, 0, 1, 0, 0, 0, -1, 0, 0, -1, 0, 0, -1, 0, 0, -1, 0, 0, 1,
+            0, 0, 1, 0, 0, 1, 0, 0, 1,
+          ],
+          edges: [
+            1.5, -0.5, -0.5, 1.5, -0.5, 0.5, 1.5, -0.5, 0.5, 1.5, 0.5, 0.5, 1.5,
+            0.5, -0.5, 1.5, 0.5, 0.5, 1.5, -0.5, -0.5, 1.5, 0.5, -0.5, 2.5,
+            -0.5, -0.5, 2.5, -0.5, 0.5, 2.5, -0.5, 0.5, 2.5, 0.5, 0.5, 2.5, 0.5,
+            -0.5, 2.5, 0.5, 0.5, 2.5, -0.5, -0.5, 2.5, 0.5, -0.5, 1.5, -0.5,
+            -0.5, 2.5, -0.5, -0.5, 1.5, 0.5, -0.5, 2.5, 0.5, -0.5, 1.5, -0.5,
+            0.5, 2.5, -0.5, 0.5, 1.5, 0.5, 0.5, 2.5, 0.5, 0.5,
+          ],
+          obj_vertices: [
+            1.5, -0.5, 0.5, 1.5, -0.5, -0.5, 1.5, 0.5, 0.5, 1.5, 0.5, -0.5, 2.5,
+            -0.5, 0.5, 2.5, -0.5, -0.5, 2.5, 0.5, 0.5, 2.5, 0.5, -0.5,
+          ],
+          face_types: [0, 0, 0, 0, 0, 0],
+          edge_types: [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+          triangles_per_face: [2, 2, 2, 2, 2, 2],
+          segments_per_edge: [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1],
+        },
+        state: [1, 1],
+        color: "#5b9bd5",
+        alpha: 1.0,
+        renderback: false,
+      };
+      viewer.addPart("/Group", newPart); // creates "/Group/Box2"
+
+      // 6) Remove the part again by absolute path
+      viewer.removePart("/Group/Box2");
+
+      // 7) Update an existing part's geometry (see "Dynamic Scene Updates" below)
+      viewer.updatePart("/Group/Box2", updatedPartData);
     </script>
   </head>
 
@@ -178,11 +248,108 @@ For the `States` object, see [Class States](https://bernhard-42.github.io/three-
 </html>
 ```
 
+## Dynamic Scene Updates
+
+After the initial `viewer.render()`, parts can be added, removed, or updated without re-rendering the entire scene.
+
+### addPart / removePart
+
+`addPart(parentPath, partData)` creates new Three.js objects (meshes, edges, clipping stencils) from the part data and inserts them into the scene graph and navigation tree. `removePart(path)` disposes the Three.js objects and removes the part from the scene.
+
+```js
+viewer.addPart("/Group", partData);    // creates "/Group/PartName"
+viewer.removePart("/Group/PartName");
+```
+
+### updatePart
+
+`updatePart(path, partData)` updates an existing part's geometry without tearing down and recreating the Three.js objects. When the mesh topology is unchanged (same number of vertices, triangles, and edge segments), vertex positions, normals, and edge coordinates are written directly into the existing GPU buffers — this is significantly faster than a remove/add cycle. When the topology differs (e.g. a re-tessellation changed the face or edge count), `updatePart` automatically falls back to a batched `removePart` + `addPart` so the caller does not need to handle this case.
+
+```js
+viewer.updatePart("/Group/PartName", updatedPartData);
+```
+
+### Batching
+
+Each of the three methods individually recomputes the bounding box, rebuilds clipping stencils, and (for add/remove) rebuilds the navigation tree. In a loop over N parts this becomes the dominant cost. All three methods accept an optional `{ skipBounds: true }` parameter that defers this work. Call `updateBounds()` once after the loop to perform a single recomputation for the entire batch:
+
+```js
+for (const part of partsToUpdate) {
+  viewer.updatePart(`/Group/${part.name}`, part, { skipBounds: true });
+}
+for (const part of partsToAdd) {
+  viewer.addPart("/Group", part, { skipBounds: true });
+}
+for (const path of pathsToRemove) {
+  viewer.removePart(path, { skipBounds: true });
+}
+viewer.updateBounds();
+```
+
+Add, remove, and update calls can be freely mixed within a single batch.
+
+### ensureStencilSize
+
+`updateBounds()` rebuilds clipping stencils whenever the scene's bounding box grows beyond the region that stencils were previously built for. This rebuild is the most expensive part of the bounds update. When the maximum extent of the geometry is known upfront (e.g. the full parameter range of a slider), call `ensureStencilSize()` once after the initial render to pre-size the stencil region. All subsequent `updateBounds()` calls whose geometry stays within this region will skip the stencil rebuild entirely:
+
+```js
+viewer.render(shapes, renderOptions, viewerOptions);
+
+viewer.ensureStencilSize({
+  xmin: -200, xmax: 200,
+  ymin: -200, ymax: 200,
+  zmin: 0,    zmax: 300,
+});
+
+// All updates within these bounds are now stencil-rebuild-free
+```
+
+## Keyboard Shortcuts
+
+The keymap serves two purposes:
+
+- **Modifier keys** (`shift`, `ctrl`, `meta`, `alt`) remap which physical modifier key is used for mouse interactions (e.g. shift-click to isolate, ctrl-rotate). Values are DOM event properties like `"shiftKey"`, `"ctrlKey"`, `"metaKey"`, `"altKey"`.
+- **Action shortcuts** map single keys (with or without Shift) to toolbar buttons, camera presets, tab switches, and animation control. Only plain keys are supported — Ctrl/Alt/Meta combinations are reserved for modifier-based mouse interactions.
+
+Click on the viewer to give it focus, then press shortcut keys to trigger actions. Button tooltips show `[key]` suffixes when shortcuts are configured.
+
+The default keymap:
+
+```javascript
+keymap: {
+  // Modifier keys (remap physical keys for mouse interactions)
+  shift: "shiftKey", ctrl: "ctrlKey", meta: "metaKey", alt: "altKey",
+  // Toggle buttons
+  axes: "a", axes0: "A", grid: "g", gridxy: "G",
+  perspective: "p", transparent: "t", blackedges: "b",
+  explode: "x", zscale: "L",
+  distance: "D", properties: "P", select: "S",
+  // Execute buttons
+  reset: "R", resize: "r",
+  iso: "0", front: "1", rear: "2", top: "3", bottom: "4", left: "5", right: "6",
+  // Help
+  help: "h",
+  // Animation
+  play: " ", stop: "Escape",
+  // Tab selection
+  tree: "T", clip: "C", material: "M", zebra: "Z",
+}
+```
+
+Pass a partial keymap to override individual bindings — unspecified keys keep their defaults:
+
+```javascript
+const displayOptions = {
+  keymap: { axes: "q", reset: "!" },  // only these two change
+};
+```
+
 ## Examples
 
 To understand the data format, a look at the simple 1 unit sized box might be helpful:
 
 - [1 unit sized box source code](https://github.com/bernhard-42/three-cad-viewer/blob/master/examples/box1.js)
+- [addPart / removePart demo](https://github.com/bernhard-42/three-cad-viewer/blob/master/example-add-remove-part.html) — dynamically adding and removing shapes and subtrees after render
 
 ## APIs of Viewer, Display, Camera and Controls
 
@@ -190,6 +357,63 @@ To understand the data format, a look at the simple 1 unit sized box might be he
 
 Back to [Github repo](https://github.com/bernhard-42/three-cad-viewer)
 
+## Utilities
+
+### Logger
+
+Control log verbosity with the built-in logger:
+
+```javascript
+import { logger } from "three-cad-viewer";
+
+// Default level is "warn" (only warnings and errors shown)
+logger.setLevel("debug"); // Enable all logging
+logger.setLevel("info"); // Info, warnings, and errors
+logger.setLevel("warn"); // Warnings and errors (default)
+logger.setLevel("error"); // Only errors
+logger.setLevel("silent"); // Disable all logging
+```
+
+### GPU Resource Tracker
+
+Track GPU resource allocation to inspect current state or detect memory leaks:
+
+```javascript
+import { gpuTracker } from "three-cad-viewer";
+
+// Check resource counts at any time
+console.log(gpuTracker.summary);
+// { geometry: 5, material: 10, texture: 1, total: 16 }
+
+// Log details of allocated resources
+gpuTracker.details();
+```
+
+For detailed allocation info with stack traces:
+
+```javascript
+// Enable debug mode BEFORE creating the viewer
+gpuTracker.enableDebug();
+
+const display = new Display(container, displayOptions);
+const viewer = new Viewer(display, viewerOptions, nc);
+viewer.render(shapes, renderOptions, viewerOptions);
+
+// Inspect current allocations
+gpuTracker.details();
+// [1] geometry: BufferGeometry (shape) for /Assembly/Part1
+//     Created at: 1234.56ms
+//     Stack:
+//       at NestedGroup.renderShape (nestedgroup.ts:425)
+//       ...
+
+// After disposal, any remaining resources are potential leaks
+viewer.dispose();
+gpuTracker.details();
+```
+
+The tracker is also available globally in the browser console as `window.tcv_gpu`.
+
 ## Development
 
 Run a web server in watch and debug mode

package/dist/_version.d.ts

@@ -0,0 +1 @@
+export declare const version: string;

package/dist/camera/camera.d.ts

@@ -0,0 +1,150 @@
+import * as THREE from "three";
+import type { Vector3Tuple, QuaternionTuple } from "three";
+import type { UpDirection } from "../core/types";
+type CameraDirection = "iso" | "front" | "rear" | "left" | "right" | "top" | "bottom";
+type UpMode = "y_up" | "z_up" | "legacy";
+/**
+ * Manages orthographic and perspective cameras for the viewer.
+ *
+ * Camera wraps both camera types and provides:
+ * - Seamless switching between orthographic and perspective
+ * - Preset positions (iso, front, top, etc.)
+ * - Support for Y-up and Z-up coordinate systems
+ * - Synchronized position/zoom across camera types
+ *
+ * ## Coordinate Systems
+ * Supports three modes via `up` parameter:
+ * - `"Y"`: Y-up (Fusion 360 compatible)
+ * - `"Z"`: Z-up (FreeCAD, OnShape compatible)
+ * - Legacy Z-up mode
+ *
+ * @internal - This is an internal class used by Viewer
+ */
+declare class Camera {
+    private static readonly DISTANCE_FACTOR;
+    target: THREE.Vector3;
+    ortho: boolean;
+    up: UpMode;
+    yaxis: THREE.Vector3;
+    zaxis: THREE.Vector3;
+    camera_distance: number;
+    pCamera: THREE.PerspectiveCamera;
+    oCamera: THREE.OrthographicCamera;
+    camera: THREE.PerspectiveCamera | THREE.OrthographicCamera;
+    /**
+     * Create a combined camera (orthographic and perspective).
+     * @param width - canvas width.
+     * @param height - canvas height.
+     * @param distance - distance from the lookAt point.
+     * @param target - target (Vector3) to look at.
+     * @param ortho - flag whether the initial camera should be orthographic.
+     * @param up - Z or Y to define whether Z or Y direction is camera up.
+     */
+    constructor(width: number, height: number, distance: number, target: Vector3Tuple, ortho: boolean, up: UpDirection);
+    /**
+     * Update the far clipping plane for both cameras.
+     * @param distance - The new bounding radius to base the far plane on.
+     */
+    updateFarPlane(distance: number): void;
+    /**
+     * Recalculate camera_distance from a new bounding radius.
+     * Uses the same factor as the constructor so that zoom 1.0 frames the scene.
+     * @param distance - The new bounding radius (bb_radius).
+     */
+    updateCameraDistance(distance: number): void;
+    /**
+     * Remove assets.
+     */
+    dispose(): void;
+    /**
+     * Get the current camera.
+     * @returns Camera object.
+     */
+    getCamera(): THREE.PerspectiveCamera | THREE.OrthographicCamera;
+    /**
+     * Set the lookAt point for the camera to the provided target.
+     */
+    lookAtTarget(): void;
+    /**
+     * Update current camera's projection matrix.
+     */
+    updateProjectionMatrix(): void;
+    /**
+     * Switch between orthographic and perspective camera.
+     * @param ortho_flag - true for orthographic camera, else perspective camera.
+     */
+    switchCamera(ortho_flag: boolean): void;
+    /**
+     * Calculate projected size for orthographic camera.
+     * @param frustum - View frustum size.
+     * @param aspect - Viewer aspect ratio (width / height).
+     * @returns Width and height [w, h] for the orthographic camera.
+     */
+    projectSize(frustum: number, aspect: number): [number, number];
+    /**
+     * Setup the current camera.
+     * @param relative - flag whether the position is a relative (e.g. [1,1,1] for iso) or absolute point.
+     * @param position - the camera position (relative or absolute).
+     * @param quaternion - the camera rotation expressed by a quaternion.
+     * @param zoom - zoom value.
+     */
+    setupCamera(relative: boolean, position?: THREE.Vector3 | null, quaternion?: THREE.Quaternion | null, zoom?: number | null): void;
+    /**
+     * Move the camera to a given preset.
+     * @param dir - can be "iso", "top", "bottom", "front", "rear", "left", "right"
+     */
+    presetCamera(dir: CameraDirection, zoom?: number | null): void;
+    /**
+     * Return current zoom value.
+     * @returns zoom value.
+     */
+    getZoom(): number;
+    /**
+     * Set zoom value.
+     * @param val - float zoom value.
+     */
+    setZoom(val: number): void;
+    /**
+     * Get the current camera position.
+     * @returns camera position.
+     */
+    getPosition(): THREE.Vector3;
+    /**
+     * Set camera position.
+     * @param position - position as 3 dim Array [x,y,z] or as Vector3.
+     * @param relative - flag whether the position is a relative (e.g. [1,1,1] for iso) or absolute point.
+     */
+    setPosition(position: Vector3Tuple | THREE.Vector3, relative: boolean): void;
+    /**
+     * Get the current camera quaternion.
+     * @returns camera quaternion.
+     */
+    getQuaternion(): THREE.Quaternion;
+    /**
+     * Set camera quaternion.
+     * @param quaternion - quaternion as 4 dim Array or as Quaternion.
+     */
+    setQuaternion(quaternion: QuaternionTuple | THREE.Quaternion): void;
+    /**
+     * Get the current camera rotation.
+     * @returns camera rotation.
+     */
+    getRotation(): THREE.Euler;
+    /**
+     * Get the visible area dimensions at the target plane.
+     * @returns The visible width and height.
+     */
+    getVisibleArea(): {
+        width: number;
+        height: number;
+    };
+    /**
+     * Update camera dimensions when viewport size changes.
+     * @param distance - Distance used for orthographic frustum calculation.
+     * @param width - New viewport width in pixels.
+     * @param height - New viewport height in pixels.
+     */
+    changeDimensions(distance: number, width: number, height: number): void;
+}
+export { Camera };
+export type { CameraDirection, UpMode };

package/dist/camera/controls/CADOrbitControls.d.ts

@@ -0,0 +1,91 @@
+/**
+ * CADOrbitControls - Extended OrbitControls for CAD applications
+ *
+ * Adds:
+ * - Public rotateLeft/rotateUp methods for programmatic rotation
+ * - Quaternion-based saveState/reset
+ * - Modifier key rotation restrictions (ctrl: vertical only, meta: horizontal only)
+ *
+ * Internal OrbitControls methods/properties used (see three-augmentation.d.ts):
+ * - _onMouseDown: Replaced to customize modifier key behavior (shift=pan, ctrl/meta=rotate with axis lock)
+ * - _handleMouseDownRotate: Called to initialize rotation state
+ * - _handleMouseDownDolly: Called to initialize dolly/zoom state
+ * - _handleMouseDownPan: Called to initialize pan state
+ * - _sphericalDelta: Modified in _rotateLeft/_rotateUp overrides to implement axis locking
+ * - state: Set to track current interaction mode (ROTATE/DOLLY/PAN/NONE)
+ */
+import { OrbitControls } from "three/examples/jsm/controls/OrbitControls.js";
+import { Quaternion, Vector3, Camera } from "three";
+declare class CADOrbitControls extends OrbitControls {
+    quaternion0: Quaternion;
+    private _horizontalRotate;
+    private _verticalRotate;
+    private _onCADPointerDown?;
+    private _onCADPointerUp?;
+    state: number;
+    _sphericalDelta: {
+        theta: number;
+        phi: number;
+    };
+    zoom0: number;
+    target0: Vector3;
+    position0: Vector3;
+    _onMouseDown: (event: MouseEvent) => void;
+    _handleMouseDownRotate: (event: MouseEvent) => void;
+    _handleMouseDownDolly: (event: MouseEvent) => void;
+    _handleMouseDownPan: (event: MouseEvent) => void;
+    /**
+     * Constructs CAD-enhanced orbit controls.
+     *
+     * @param object - The camera to control.
+     * @param domElement - The HTML element for event listeners.
+     */
+    constructor(object: Camera, domElement?: HTMLElement | null);
+    /**
+     * Handle pointer down to check modifier keys for rotation restriction.
+     */
+    private _handleCADPointerDown;
+    /**
+     * Handle pointer up to reset rotation restrictions.
+     */
+    private _handleCADPointerUp;
+    /**
+     * Override dispose to clean up our event listeners.
+     */
+    dispose(): void;
+    /**
+     * Custom mouse down handler for rotation restriction via modifier keys.
+     *
+     * Original OrbitControls: ctrl/meta/shift + left mouse = pan
+     * CADOrbitControls: ctrl = vertical rotate only, meta = horizontal rotate only,
+     *                   shift = pan (via KeyMapper)
+     */
+    private _handleMouseDown;
+    /**
+     * Override _rotateLeft to respect horizontal rotation restriction.
+     */
+    _rotateLeft(angle: number): void;
+    /**
+     * Override _rotateUp to respect vertical rotation restriction.
+     */
+    _rotateUp(angle: number): void;
+    /**
+     * Save the current state including quaternion.
+     */
+    saveState(): void;
+    /**
+     * Reset to saved state including quaternion.
+     */
+    reset(): void;
+    /**
+     * Rotate camera left (around the up axis).
+     * Programmatic rotation bypasses modifier key restrictions.
+     */
+    rotateLeft(angle: number): void;
+    /**
+     * Rotate camera up (around the right axis).
+     * Programmatic rotation bypasses modifier key restrictions.
+     */
+    rotateUp(angle: number): void;
+}
+export { CADOrbitControls };