three-cad-viewer 4.3.5 → 4.3.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "three-cad-viewer",
-  "version": "4.3.5",
+  "version": "4.3.7",
   "type": "module",
   "description": "WebGL-based CAD viewer built on Three.js with clipping planes, measurement tools, and tree navigation",
   "repository": {
@@ -15,8 +15,7 @@
     "dist/three-cad-viewer.esm.js.map",
     "dist/three-cad-viewer.esm.min.js",
     "dist/three-cad-viewer.js",
-    "dist/three-cad-viewer.min.js",
-    "src"
+    "dist/three-cad-viewer.min.js"
   ],
   "main": "dist/three-cad-viewer.js",
   "module": "dist/three-cad-viewer.esm.js",

package/src/_version.ts

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

package/src/camera/camera.ts

@@ -1,445 +0,0 @@
-import * as THREE from "three";
-import type { Vector3Tuple, QuaternionTuple } from "three";
-import type { UpDirection } from "../core/types";
-import { logger } from "../utils/logger.js";
-
-type CameraDirection = "iso" | "front" | "rear" | "left" | "right" | "top" | "bottom";
-
-interface DirectionConfig {
-  pos: THREE.Vector3;
-  quat: THREE.Quaternion | null;
-}
-
-type DirectionMap = Record<CameraDirection, DirectionConfig>;
-
-type UpMode = "y_up" | "z_up" | "legacy";
-
-const defaultDirections: Record<UpMode, DirectionMap> = {
-  y_up: {
-    // compatible to fusion 360
-    iso: { pos: new THREE.Vector3(1, 1, 1), quat: null },
-    front: { pos: new THREE.Vector3(0, 0, 1), quat: null },
-    rear: { pos: new THREE.Vector3(0, 0, -1), quat: null },
-    left: { pos: new THREE.Vector3(-1, 0, 0), quat: null },
-    right: { pos: new THREE.Vector3(1, 0, 0), quat: null },
-    top: { pos: new THREE.Vector3(0, 1, 0), quat: null },
-    bottom: { pos: new THREE.Vector3(0, -1, 0), quat: null },
-  },
-  z_up: {
-    // compatible to FreeCAD, OnShape
-    iso: { pos: new THREE.Vector3(1, -1, 1), quat: null },
-    front: { pos: new THREE.Vector3(0, -1, 0), quat: null },
-    rear: { pos: new THREE.Vector3(0, 1, 0), quat: null },
-    left: { pos: new THREE.Vector3(-1, 0, 0), quat: null },
-    right: { pos: new THREE.Vector3(1, 0, 0), quat: null },
-    top: { pos: new THREE.Vector3(0, 0, 1), quat: new THREE.Quaternion(0, 0, 0, 1) },
-    bottom: { pos: new THREE.Vector3(0, 0, -1), quat: new THREE.Quaternion(1, 0, 0, 0) },
-  },
-  legacy: {
-    // legacy Z up
-    iso: { pos: new THREE.Vector3(1, 1, 1), quat: null },
-    front: { pos: new THREE.Vector3(1, 0, 0), quat: null },
-    rear: { pos: new THREE.Vector3(-1, 0, 0), quat: null },
-    left: { pos: new THREE.Vector3(0, 1, 0), quat: null },
-    right: { pos: new THREE.Vector3(0, -1, 0), quat: null },
-    top: { pos: new THREE.Vector3(0, 0, 1), quat: null },
-    bottom: { pos: new THREE.Vector3(0, 0, -1), quat: null },
-  },
-};
-
-const cameraUp: Record<UpMode, [number, number, number]> = {
-  y_up: [0, 1, 0],
-  z_up: [0, 0, 1],
-  legacy: [0, 0, 1],
-};
-
-/**
- * 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
- */
-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;
-  yaxis: THREE.Vector3;
-  zaxis: THREE.Vector3;
-  camera_distance: number;
-  pCamera!: THREE.PerspectiveCamera; // Initialized in constructor
-  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.
-   * @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
-  ) {
-    const mapping: Record<string, UpMode> = {
-      Y: "y_up",
-      Z: "z_up",
-      L: "legacy",
-    };
-    this.target = new THREE.Vector3(...target);
-    this.ortho = ortho;
-    this.up = mapping[up] || "z_up";
-    this.yaxis = new THREE.Vector3(0, 1, 0);
-    this.zaxis = new THREE.Vector3(0, 0, 1);
-
-    // define the perspective camera
-
-    const aspect = width / height;
-
-    // 22 is a good compromise
-    const fov = 22;
-
-    this.camera_distance = Camera.DISTANCE_FACTOR * 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);
-
-    // define the orthographic camera
-    const pSize = this.projectSize(distance, aspect);
-
-    this.oCamera = new THREE.OrthographicCamera(
-      -pSize[0],
-      pSize[0],
-      pSize[1],
-      -pSize[1],
-      near,
-      far,
-    );
-    this.oCamera.up.set(...cameraUp[this.up]);
-    this.oCamera.lookAt(this.target);
-
-    this.camera = ortho ? this.oCamera! : this.pCamera!;
-    this.camera.up.set(...cameraUp[this.up]);
-  }
-
-  /**
-   * 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();
-  }
-
-  /**
-   * 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 {
-    this.camera_distance = Camera.DISTANCE_FACTOR * distance;
-  }
-
-  /**
-   * Remove assets.
-   */
-  dispose(): void {
-    // Cameras are simple objects; no explicit cleanup needed.
-    // The Camera instance itself will be garbage collected.
-  }
-
-  /**
-   * Get the current camera.
-   * @returns Camera object.
-   */
-  getCamera(): THREE.PerspectiveCamera | THREE.OrthographicCamera {
-    return this.camera;
-  }
-
-  /**
-   * Set the lookAt point for the camera to the provided target.
-   */
-  lookAtTarget(): void {
-    this.camera.lookAt(this.target);
-  }
-
-  /**
-   * Update current camera's projection matrix.
-   */
-  updateProjectionMatrix(): void {
-    this.camera.updateProjectionMatrix();
-  }
-
-  /**
-   * Switch between orthographic and perspective camera.
-   * @param ortho_flag - true for orthographic camera, else perspective camera.
-   */
-  switchCamera(ortho_flag: boolean): void {
-    const p0 = this.getPosition().clone();
-    const z0 = this.getZoom();
-    const q0 = this.getQuaternion().clone();
-
-    if (ortho_flag) {
-      this.camera = this.oCamera;
-      this.ortho = true;
-    } else {
-      this.camera = this.pCamera;
-      this.ortho = false;
-    }
-
-    this.setPosition(p0, false);
-    this.setZoom(z0);
-    this.setQuaternion(q0);
-
-    this.updateProjectionMatrix();
-  }
-
-  /**
-   * 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] {
-    let w: number, h: number;
-    if (aspect < 1) {
-      w = frustum;
-      h = w / aspect;
-    } else {
-      h = frustum;
-      w = h * aspect;
-    }
-    return [w, h];
-  }
-
-  /**
-   * 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 = null,
-    quaternion: THREE.Quaternion | null = null,
-    zoom: number | null = null
-  ): void {
-    if (position != null) {
-      const cameraPosition = relative
-        ? position
-            .clone()
-            .normalize()
-            .multiplyScalar(this.camera_distance)
-            .add(this.target)
-        : position;
-
-      this.camera.position.set(...cameraPosition.toArray());
-    }
-
-    if (quaternion != null) {
-      this.camera.quaternion.set(...quaternion.toArray());
-    }
-
-    if (zoom != null) {
-      this.setZoom(zoom);
-    }
-
-    this.updateProjectionMatrix();
-  }
-
-  /**
-   * Move the camera to a given preset.
-   * @param dir - can be "iso", "top", "bottom", "front", "rear", "left", "right"
-   */
-  presetCamera(dir: CameraDirection, zoom: number | null = null): void {
-    if (zoom == null) {
-      zoom = this.camera.zoom;
-    }
-    // For the default directions quaternion can be ignored, it will be reset automatically
-    this.setupCamera(true, defaultDirections[this.up][dir].pos, null, zoom);
-    this.lookAtTarget();
-
-    const quat = defaultDirections[this.up][dir].quat;
-    if (quat != null) {
-      this.setQuaternion(quat);
-    }
-  }
-
-  /**
-   * Return current zoom value.
-   * @returns zoom value.
-   */
-  getZoom(): number {
-    if (this.ortho) {
-      return this.camera.zoom;
-    } else {
-      const p = this.camera.position.clone().sub(this.target);
-      return this.camera_distance / p.length();
-    }
-  }
-
-  /**
-   * Set zoom value.
-   * @param val - float zoom value.
-   */
-  setZoom(val: number): void {
-    if (this.ortho) {
-      this.camera.zoom = val;
-    } else {
-      this.camera.position
-        .sub(this.target)
-        .setLength(this.camera_distance / val)
-        .add(this.target);
-    }
-
-    this.updateProjectionMatrix();
-  }
-
-  /**
-   * Get the current camera position.
-   * @returns camera position.
-   */
-  getPosition(): THREE.Vector3 {
-    return this.camera.position;
-  }
-
-  /**
-   * 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 {
-    if (Array.isArray(position) && position.length === 3) {
-      this.setupCamera(relative, new THREE.Vector3(...position));
-    } else if (position instanceof THREE.Vector3) {
-      this.setupCamera(relative, position);
-    } else {
-      logger.error("wrong type for position", position);
-    }
-  }
-
-  /**
-   * Get the current camera quaternion.
-   * @returns camera quaternion.
-   */
-  getQuaternion(): THREE.Quaternion {
-    return this.camera.quaternion;
-  }
-
-  /**
-   * Set camera quaternion.
-   * @param quaternion - quaternion as 4 dim Array or as Quaternion.
-   */
-  setQuaternion(quaternion: QuaternionTuple | THREE.Quaternion): void {
-    if (Array.isArray(quaternion) && quaternion.length === 4) {
-      this.setupCamera(false, null, new THREE.Quaternion(...quaternion));
-    } else if (quaternion instanceof THREE.Quaternion) {
-      this.setupCamera(false, null, quaternion);
-    } else {
-      logger.error("wrong type for quaternion", quaternion);
-    }
-
-    this.updateProjectionMatrix();
-  }
-
-  /**
-   * Get the current camera rotation.
-   * @returns camera rotation.
-   */
-  getRotation(): THREE.Euler {
-    return this.camera.rotation;
-  }
-
-  /**
-   * Get the visible area dimensions at the target plane.
-   * @returns The visible width and height.
-   */
-  getVisibleArea(): { width: number; height: number } {
-    if (this.ortho && this.oCamera) {
-      const height = (this.oCamera.top - this.oCamera.bottom) / this.oCamera.zoom;
-      const width = (this.oCamera.right - this.oCamera.left) / this.oCamera.zoom;
-      return { width, height };
-    } else if (this.pCamera) {
-      const distance = this.pCamera.position.distanceTo(this.target);
-      const vFOV = (this.pCamera.fov * Math.PI) / 180;
-      const height = 2 * Math.tan(vFOV / 2) * distance;
-      const width = height * this.pCamera.aspect;
-      return { width, height };
-    }
-    return { width: 0, height: 0 };
-  }
-
-  /**
-   * 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 {
-    const aspect = width / height;
-    const pSize = this.projectSize(distance, aspect);
-
-    if (this.oCamera) {
-      this.oCamera.left = -pSize[0];
-      this.oCamera.right = pSize[0];
-      this.oCamera.top = pSize[1];
-      this.oCamera.bottom = -pSize[1];
-    }
-
-    if (this.pCamera) {
-      this.pCamera.aspect = aspect;
-    }
-
-    if (this.camera) {
-      this.camera.updateProjectionMatrix();
-    }
-  }
-}
-
-export { Camera };
-export type { CameraDirection, UpMode };

package/src/camera/controls/CADOrbitControls.ts

@@ -1,241 +0,0 @@
-/**
- * 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 { MOUSE, Quaternion, Vector3, Camera } from "three";
-import { KeyMapper, isOrthographicCamera, isPerspectiveCamera } from "../../utils/utils.js";
-
-// State constants matching OrbitControls internal state
-const STATE = {
-  NONE: -1,
-  ROTATE: 0,
-  DOLLY: 1,
-  PAN: 2,
-};
-
-class CADOrbitControls extends OrbitControls {
-  quaternion0: Quaternion;
-  private _horizontalRotate: boolean;
-  private _verticalRotate: boolean;
-  private _onCADPointerDown?: (event: PointerEvent) => void;
-  private _onCADPointerUp?: () => void;
-
-  // Expose internal properties for type safety
-  declare state: number;
-  declare _sphericalDelta: { theta: number; phi: number };
-  declare zoom0: number;
-  declare target0: Vector3;
-  declare position0: Vector3;
-  declare _onMouseDown: (event: MouseEvent) => void;
-  declare _handleMouseDownRotate: (event: MouseEvent) => void;
-  declare _handleMouseDownDolly: (event: MouseEvent) => void;
-  declare _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 = null) {
-    super(object, domElement!);
-
-    /**
-     * Saved quaternion for reset (in addition to position/target/zoom).
-     */
-    this.quaternion0 = this.object.quaternion.clone();
-
-    // Rotation axis restriction flags (set via modifier keys)
-    this._horizontalRotate = true; // meta key restricts to horizontal only
-    this._verticalRotate = true; // ctrl key restricts to vertical only
-
-    // Add pointer event listeners for modifier key detection
-    if (domElement) {
-      this._onCADPointerDown = this._handleCADPointerDown.bind(this);
-      this._onCADPointerUp = this._handleCADPointerUp.bind(this);
-      domElement.addEventListener("pointerdown", this._onCADPointerDown);
-      domElement.addEventListener("pointerup", this._onCADPointerUp);
-      domElement.addEventListener("pointercancel", this._onCADPointerUp);
-    }
-
-    // Override the parent's _onMouseDown which was bound in parent constructor
-    this._onMouseDown = this._handleMouseDown.bind(this);
-  }
-
-  /**
-   * Handle pointer down to check modifier keys for rotation restriction.
-   */
-  private _handleCADPointerDown(event: PointerEvent): void {
-    // Check modifier keys for rotation restriction
-    // ctrl: restrict to vertical rotation only (horizontalRotate = false)
-    // meta: restrict to horizontal rotation only (verticalRotate = false)
-    this._horizontalRotate = !KeyMapper.get(event, "ctrl");
-    this._verticalRotate = !KeyMapper.get(event, "meta");
-  }
-
-  /**
-   * Handle pointer up to reset rotation restrictions.
-   */
-  private _handleCADPointerUp(): void {
-    this._horizontalRotate = true;
-    this._verticalRotate = true;
-  }
-
-  /**
-   * Override dispose to clean up our event listeners.
-   */
-  dispose(): void {
-    if (this.domElement && this._onCADPointerDown && this._onCADPointerUp) {
-      this.domElement.removeEventListener("pointerdown", this._onCADPointerDown);
-      this.domElement.removeEventListener("pointerup", this._onCADPointerUp);
-      this.domElement.removeEventListener("pointercancel", this._onCADPointerUp);
-    }
-    super.dispose();
-  }
-
-  /**
-   * 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(event: MouseEvent): void {
-    let mouseAction: number;
-
-    switch (event.button) {
-      case 0:
-        mouseAction = this.mouseButtons.LEFT!;
-        break;
-      case 1:
-        mouseAction = this.mouseButtons.MIDDLE!;
-        break;
-      case 2:
-        mouseAction = this.mouseButtons.RIGHT!;
-        break;
-      default:
-        mouseAction = -1;
-    }
-
-    switch (mouseAction) {
-      case MOUSE.DOLLY:
-        if (this.enableZoom === false) return;
-        this._handleMouseDownDolly(event);
-        this.state = STATE.DOLLY;
-        break;
-
-      case MOUSE.ROTATE:
-        // Check if shift key (via KeyMapper) is pressed for pan
-        if (KeyMapper.get(event, "shift")) {
-          if (this.enablePan === false) return;
-          this._handleMouseDownPan(event);
-          this.state = STATE.PAN;
-        } else {
-          // ctrl and meta are handled for rotation restriction in _handleCADPointerDown
-          if (this.enableRotate === false) return;
-          this._handleMouseDownRotate(event);
-          this.state = STATE.ROTATE;
-        }
-        break;
-
-      case MOUSE.PAN:
-        // For right mouse button, check if any modifier for rotate
-        if (
-          KeyMapper.get(event, "ctrl") ||
-          KeyMapper.get(event, "meta") ||
-          KeyMapper.get(event, "shift")
-        ) {
-          if (this.enableRotate === false) return;
-          this._handleMouseDownRotate(event);
-          this.state = STATE.ROTATE;
-        } else {
-          if (this.enablePan === false) return;
-          this._handleMouseDownPan(event);
-          this.state = STATE.PAN;
-        }
-        break;
-
-      default:
-        this.state = STATE.NONE;
-    }
-  }
-
-  /**
-   * Override _rotateLeft to respect horizontal rotation restriction.
-   */
-  _rotateLeft(angle: number): void {
-    if (this._horizontalRotate) {
-      this._sphericalDelta.theta -= angle;
-    }
-  }
-
-  /**
-   * Override _rotateUp to respect vertical rotation restriction.
-   */
-  _rotateUp(angle: number): void {
-    if (this._verticalRotate) {
-      this._sphericalDelta.phi -= angle;
-    }
-  }
-
-  /**
-   * Save the current state including quaternion.
-   */
-  saveState(): void {
-    super.saveState();
-    this.quaternion0.copy(this.object.quaternion);
-  }
-
-  /**
-   * Reset to saved state including quaternion.
-   */
-  reset(): void {
-    this.target.copy(this.target0);
-    this.object.position.copy(this.position0);
-    this.object.quaternion.copy(this.quaternion0);
-
-    if (isPerspectiveCamera(this.object) || isOrthographicCamera(this.object)) {
-      this.object.zoom = this.zoom0;
-      this.object.updateProjectionMatrix();
-    }
-    this.dispatchEvent({ type: "change" });
-
-    this.update();
-
-    this.state = -1; // STATE.NONE
-  }
-
-  /**
-   * Rotate camera left (around the up axis).
-   * Programmatic rotation bypasses modifier key restrictions.
-   */
-  rotateLeft(angle: number): void {
-    // Bypass restriction for programmatic rotation
-    this._sphericalDelta.theta -= angle;
-  }
-
-  /**
-   * Rotate camera up (around the right axis).
-   * Programmatic rotation bypasses modifier key restrictions.
-   */
-  rotateUp(angle: number): void {
-    // Bypass restriction for programmatic rotation
-    this._sphericalDelta.phi -= angle;
-  }
-}
-
-export { CADOrbitControls };