@inweb/viewer-three 26.10.6 → 26.12.0

package/src/Viewer/loaders/RangesLoader.ts

@@ -0,0 +1,105 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2002-2025, Open Design Alliance (the "Alliance").
+// All rights reserved.
+//
+// This software and its documentation and related materials are owned by
+// the Alliance. The software may only be incorporated into application
+// programs owned by members of the Alliance, subject to a signed
+// Membership Agreement and Supplemental Software License Agreement with the
+// Alliance. The structure and organization of this software are the valuable
+// trade secrets of the Alliance and its suppliers. The software is also
+// protected by copyright law and international treaty provisions. Application
+// programs incorporating this software must include the following statement
+// with their copyright notices:
+//
+//   This application incorporates Open Design Alliance software pursuant to a
+//   license agreement with Open Design Alliance.
+//   Open Design Alliance Copyright (C) 2002-2025 by Open Design Alliance.
+//   All rights reserved.
+//
+// By use of this software, its documentation or related materials, you
+// acknowledge and accept the above terms.
+///////////////////////////////////////////////////////////////////////////////
+
+class FetchError extends Error {
+  public status: number;
+
+  constructor(status: number, message: string) {
+    super(message);
+    this.name = "FetchError";
+    this.status = status;
+  }
+}
+
+export interface Range {
+  offset: number;
+  length: number;
+}
+
+export class RangesLoader {
+  private requestHeader: HeadersInit;
+  private withCredentials: boolean;
+  private abortSignal: AbortSignal | undefined;
+
+  constructor() {
+    this.requestHeader = {};
+    this.withCredentials = false;
+    this.abortSignal = undefined;
+  }
+
+  setRequestHeader(requestHeader: HeadersInit) {
+    this.requestHeader = requestHeader;
+  }
+
+  setWithCredentials(withCredentials: boolean) {
+    this.withCredentials = withCredentials;
+  }
+
+  setAbortSignal(abortSignal: AbortSignal) {
+    this.abortSignal = abortSignal;
+  }
+
+  async load(url: string, ranges: Range[]): Promise<ArrayBuffer> {
+    const init: RequestInit = {
+      headers: {
+        ...this.requestHeader,
+        Range: "bytes=" + ranges.map((x) => `${x.offset}-${x.offset + x.length - 1}`).join(","),
+      },
+      credentials: this.withCredentials ? "include" : "same-origin",
+      signal: this.abortSignal,
+    };
+
+    const response = await fetch(url, init);
+    if (!response.ok) {
+      throw new FetchError(response.status, `Failed to fetch "${url}", status ${response.status}`);
+    }
+
+    if (response.status !== 206) {
+      const arrayBuffer = await response.arrayBuffer();
+      return this.extractRanges(arrayBuffer, ranges);
+    }
+
+    return response.arrayBuffer();
+  }
+
+  // ===================== AI-CODE-START ======================
+  // Source: Claude Sonnet 4.5
+  // Date: 2025-28-10
+  // Reviewer: roman.mochalov@opendesign.com
+  // Issue: CLOUD-5933
+
+  extractRanges(arrayBuffer: ArrayBuffer, ranges: Range[]): ArrayBuffer {
+    const totalLength = ranges.reduce((sum, range) => sum + range.length, 0);
+    const result = new Uint8Array(totalLength);
+
+    let offset = 0;
+    for (const range of ranges) {
+      const chunk = new Uint8Array(arrayBuffer, range.offset, range.length);
+      result.set(chunk, offset);
+      offset += range.length;
+    }
+
+    return result.buffer;
+  }
+  // ===================== AI-CODE-END ======================
+}

package/src/Viewer/loaders/index.ts

@@ -23,7 +23,7 @@
 
 import { ILoadersRegistry, loadersRegistry } from "@inweb/viewer-core";
 
-import { GLTFFileLoader } from "./GLTFFileLoader";
+import { GLTFFileDynamicLoader } from "./GLTFFileDynamicLoader";
 import { GLTFCloudDynamicLoader } from "./GLTFCloudDynamicLoader";
 
 /**
@@ -33,29 +33,30 @@ import { GLTFCloudDynamicLoader } from "./GLTFCloudDynamicLoader";
  *
  * 1. Define a loader class implements {@link ILoader}.
  * 2. Define a constructor with a `viewer` parameter.
- * 3. Override {@link ILoader.isSupport} and сheck if the loader can load the specified file.
+ * 3. Override {@link ILoader.isSupport} and check if the loader can load the specified file.
  * 4. Override {@link ILoader.load} and define the logic for loading the scene from the file.
  *
  *    The loader should do:
  *
  *    - Load raw data from file and convert it to the `Three.js` scene.
  *    - Add scene to the viewer `scene`.
- *    - Create `ModelImpl` for the scene and to the viewer `models` list.
+ *    - Create `ModelImpl` instance with unique model ID add it to the viewer `models` list.
  *    - Synchronize viewer options and overlay.
  *    - Update the viewer.
  *
  *    The loader must emit events:
  *
- *    - `geometryprogress` - during loading. If progress is not supported, emit it once with a value of 100%
- *         after the load is complete.
+ *    - `geometryprogress` - during loading (or once at 100% when complete).
  *    - `databasechunk` - when scene is loaded and ready to render.
  * 5. Override {@link ILoader.dispose} and release loader resources, if required.
- * 6. Register loader provider in the loaders registry by calling the {@link loaders.registerLoader}.
+ * 6. Use `this.abortController` (defined in `Loader` class) to abort loading raw data.
+ * 7. Register loader provider in the loaders registry by calling the {@link loaders.registerLoader}.
  *
  * @example Implementing a custom loader.
  *
  * ```javascript
- * import { loaders, Loader, ModelImpl, Viewer } from "@inweb/viewer-three";
+ * import { Scene } from "three";
+ * import { Loader, loaders, ModelImpl, Viewer } from "@inweb/viewer-three";
  *
  * class MyLoader extends Loader {
  *   public viewer: Viewer;
@@ -66,18 +67,19 @@ import { GLTFCloudDynamicLoader } from "./GLTFCloudDynamicLoader";
  *   }
  *
  *   override isSupport(file, format): Boolean {
- *     // place custom logic here
- *     return ...;
+ *     // check if this loader supports the file source and format
+ *     return type file === "string" && format === "myformat";
  *   }
  *
- *   override load(file, format, params): Promise<this> {
+ *   override load(file, format, params = {}): Promise<this> {
+ *      // load raw data from file (custom loading logic)
+ *     const data = await fetch(file).then((result) => result.arrayBuffer());
  *
- *     // place custom loading logic here
- *     const scene = ...;
+ *     // convert raw data to the Three.js scene (custom parsing logic)
+ *     const scene = this.parse(data);
  *
  *     const modelImpl = new ModelImpl(scene);
- *     modelImpl.loader = this;
- *     modelImpl.viewer = this.viewer;
+ *     modelImpl.id = params.modelId;
  *
  *     this.viewer.scene.add(scene);
  *     this.viewer.models.push(modelImpl);
@@ -86,11 +88,17 @@ import { GLTFCloudDynamicLoader } from "./GLTFCloudDynamicLoader";
  *     this.viewer.syncOverlay();
  *     this.viewer.update();
  *
+ *     this.viewer.emitEvent({ type: "geometryprogress", data: 1, file });
  *     this.viewer.emitEvent({ type: "databasechunk", data: scene, file });
  *
  *     return Promise.resove(this);
  *   };
- * }
+ *
+ *   private parse(data: ArrayBuffer): Scene {
+ *     // custom parsing logic
+ *     return new Scene();
+ *   }
+ *  }
  *
  * loaders.registerLoader("MyLoader", (viewer) => new MyLoader(viewer));
  * ```
@@ -99,5 +107,5 @@ export const loaders: ILoadersRegistry = loadersRegistry("threejs");
 
 // build-in loaders
 
-loaders.registerLoader("gltf-file", (viewer: any) => new GLTFFileLoader(viewer));
+loaders.registerLoader("gltf-file", (viewer: any) => new GLTFFileDynamicLoader(viewer));
 loaders.registerLoader("gltf-cloud", (viewer: any) => new GLTFCloudDynamicLoader(viewer));

package/src/Viewer/measurement/Snapper.ts

@@ -0,0 +1,208 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2002-2025, Open Design Alliance (the "Alliance").
+// All rights reserved.
+//
+// This software and its documentation and related materials are owned by
+// the Alliance. The software may only be incorporated into application
+// programs owned by members of the Alliance, subject to a signed
+// Membership Agreement and Supplemental Software License Agreement with the
+// Alliance. The structure and organization of this software are the valuable
+// trade secrets of the Alliance and its suppliers. The software is also
+// protected by copyright law and international treaty provisions. Application
+// programs incorporating this software must include the following statement
+// with their copyright notices:
+//
+//   This application incorporates Open Design Alliance software pursuant to a
+//   license agreement with Open Design Alliance.
+//   Open Design Alliance Copyright (C) 2002-2025 by Open Design Alliance.
+//   All rights reserved.
+//
+// By use of this software, its documentation or related materials, you
+// acknowledge and accept the above terms.
+///////////////////////////////////////////////////////////////////////////////
+
+import {
+  Camera,
+  EdgesGeometry,
+  Intersection,
+  Line3,
+  MathUtils,
+  Object3D,
+  Plane,
+  Raycaster,
+  Vector2,
+  Vector3,
+  WebGLRenderer,
+} from "three";
+
+const DESKTOP_SNAP_DISTANCE = 10;
+const MOBILE_SNAP_DISTANCE = 50;
+
+const _vertex = new Vector3();
+const _start = new Vector3();
+const _end = new Vector3();
+const _line = new Line3();
+const _center = new Vector3();
+const _projection = new Vector3();
+
+export class Snapper {
+  public camera: Camera;
+  public renderer: WebGLRenderer;
+  public canvas: HTMLCanvasElement;
+  private raycaster: Raycaster;
+  private detectRadiusInPixels: number;
+  private edgesCache: WeakMap<any, EdgesGeometry>;
+
+  constructor(camera: Camera, renderer: WebGLRenderer, canvas: HTMLCanvasElement) {
+    this.camera = camera;
+    this.renderer = renderer;
+    this.canvas = canvas;
+
+    this.raycaster = new Raycaster();
+    this.detectRadiusInPixels = this.isMobile() ? MOBILE_SNAP_DISTANCE : DESKTOP_SNAP_DISTANCE;
+    this.edgesCache = new WeakMap();
+  }
+
+  isMobile(): boolean {
+    if (typeof navigator === "undefined") return false;
+
+    // ===================== AI-CODE-START ======================
+    // Source: Claude Sonnet 4
+    // Date: 2025-09-09
+    // Reviewer: roman.mochalov@opendesign.com
+    // Issue: CLOUD-5799
+
+    return /Android|webOS|iPhone|iPad|iPod|BlackBerry|Opera Mini|Opera Mobi|IEMobile/i.test(navigator.userAgent);
+
+    // ===================== AI-CODE-END ======================
+  }
+
+  getMousePosition(event: MouseEvent, target: Vector2): Vector2 {
+    return target.set(event.clientX, event.clientY);
+  }
+
+  getPointerIntersects(mouse: Vector2, objects: Object3D[]): Array<Intersection<Object3D>> {
+    const rect = this.canvas.getBoundingClientRect();
+    const x = ((mouse.x - rect.left) / rect.width) * 2 - 1;
+    const y = (-(mouse.y - rect.top) / rect.height) * 2 + 1;
+
+    const coords = new Vector2(x, y);
+    this.raycaster.setFromCamera(coords, this.camera);
+
+    this.raycaster.params = {
+      Mesh: {},
+      Line: { threshold: 0.05 },
+      Line2: { threshold: 0.05 },
+      LOD: {},
+      Points: { threshold: 0.01 },
+      Sprite: {},
+    };
+
+    let intersects = this.raycaster.intersectObjects(objects, false);
+
+    (this.renderer.clippingPlanes || []).forEach((plane: Plane) => {
+      intersects = intersects.filter((intersect) => plane.distanceToPoint(intersect.point) >= 0);
+    });
+
+    return intersects;
+  }
+
+  getDetectRadius(point: Vector3): number {
+    const camera: any = this.camera;
+
+    // ===================== AI-CODE-START ======================
+    // Source: Gemini 2.5 Pro
+    // Date: 2025-08-27
+    // Reviewer: roman.mochalov@opendesign.com
+    // Issue: CLOUD-5799
+    // Notes: Originally AI-generated, modified manually
+
+    if (camera.isOrthographicCamera) {
+      const fieldHeight = (camera.top - camera.bottom) / camera.zoom;
+
+      const canvasHeight = this.canvas.height;
+      const worldUnitsPerPixel = fieldHeight / canvasHeight;
+
+      return this.detectRadiusInPixels * worldUnitsPerPixel;
+    }
+
+    if (camera.isPerspectiveCamera) {
+      const distance = camera.position.distanceTo(point);
+      const fieldHeight = 2 * Math.tan(MathUtils.degToRad(camera.fov * 0.5)) * distance;
+
+      const canvasHeight = this.canvas.height;
+      const worldUnitsPerPixel = fieldHeight / canvasHeight;
+
+      return this.detectRadiusInPixels * worldUnitsPerPixel;
+    }
+
+    // ===================== AI-CODE-END ======================
+
+    return 0.1;
+  }
+
+  getSnapPoint(mouse: Vector2, objects: Object3D[]): Vector3 {
+    const intersections = this.getPointerIntersects(mouse, objects);
+    if (intersections.length === 0) return undefined;
+
+    // ===================== AI-CODE-START ======================
+    // Source: Gemini 2.5 Pro
+    // Date: 2025-08-20
+    // Reviewer: roman.mochalov@opendesign.com
+    // Issue: CLOUD-5799
+    // Notes: Originally AI-generated, modified manually
+
+    const object: any = intersections[0].object;
+    const intersectionPoint = intersections[0].point;
+    const localPoint = object.worldToLocal(intersectionPoint.clone());
+
+    let snapPoint: Vector3;
+    let snapDistance = this.getDetectRadius(intersectionPoint);
+
+    const geometry = object.geometry;
+
+    const positions = geometry.attributes.position.array;
+    for (let i = 0; i < positions.length; i += 3) {
+      _vertex.set(positions[i], positions[i + 1], positions[i + 2]);
+      const distance = _vertex.distanceTo(localPoint);
+      if (distance < snapDistance) {
+        snapDistance = distance;
+        snapPoint = _vertex.clone();
+      }
+    }
+    if (snapPoint) return object.localToWorld(snapPoint);
+
+    let edges = this.edgesCache.get(geometry);
+    if (!edges) {
+      edges = new EdgesGeometry(geometry);
+      this.edgesCache.set(geometry, edges);
+    }
+
+    const edgePositions = edges.attributes.position.array;
+    for (let i = 0; i < edgePositions.length; i += 6) {
+      _start.set(edgePositions[i], edgePositions[i + 1], edgePositions[i + 2]);
+      _end.set(edgePositions[i + 3], edgePositions[i + 4], edgePositions[i + 5]);
+      _line.set(_start, _end);
+
+      _line.getCenter(_center);
+      const centerDistance = _center.distanceTo(localPoint);
+      if (centerDistance < snapDistance) {
+        snapDistance = centerDistance;
+        snapPoint = _center.clone();
+        continue;
+      }
+
+      _line.closestPointToPoint(localPoint, true, _projection);
+      const lineDistance = _projection.distanceTo(localPoint);
+      if (lineDistance < snapDistance) {
+        snapDistance = lineDistance;
+        snapPoint = _projection.clone();
+      }
+    }
+    if (snapPoint) return object.localToWorld(snapPoint);
+
+    // ===================== AI-CODE-END ======================
+
+    return intersectionPoint.clone();
+  }
+}

package/src/Viewer/measurement/UnitConverter.ts

@@ -0,0 +1,47 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2002-2025, Open Design Alliance (the "Alliance").
+// All rights reserved.
+//
+// This software and its documentation and related materials are owned by
+// the Alliance. The software may only be incorporated into application
+// programs owned by members of the Alliance, subject to a signed
+// Membership Agreement and Supplemental Software License Agreement with the
+// Alliance. The structure and organization of this software are the valuable
+// trade secrets of the Alliance and its suppliers. The software is also
+// protected by copyright law and international treaty provisions. Application
+// programs incorporating this software must include the following statement
+// with their copyright notices:
+//
+//   This application incorporates Open Design Alliance software pursuant to a
+//   license agreement with Open Design Alliance.
+//   Open Design Alliance Copyright (C) 2002-2025 by Open Design Alliance.
+//   All rights reserved.
+//
+// By use of this software, its documentation or related materials, you
+// acknowledge and accept the above terms.
+///////////////////////////////////////////////////////////////////////////////
+
+// Model units for the user to choose from.
+
+export const ModelUnits = {
+  Meters: { name: "Meters", type: "m", scale: 1.0 },
+  Centimeters: { name: "Centimeters", type: "cm", scale: 0.01 },
+  Millimeters: { name: "Millimeters", type: "mm", scale: 0.001 },
+  Feet: { name: "Feet", type: "ft", scale: 0.3048 },
+  Inches: { name: "Inches", type: "in", scale: 0.0254 },
+  Yards: { name: "Yards", type: "yd", scale: 0.9144 },
+  Kilometers: { name: "Kilometers", type: "km", scale: 1000.0 },
+  Miles: { name: "Miles", type: "mi", scale: 1609.344 },
+  Micrometers: { name: "Micrometers", type: "µm", scale: 0.000001 },
+  Mils: { name: "Mils", type: "mil", scale: 0.0000254 },
+  MicroInches: { name: "Micro-inches", type: "µin", scale: 0.0000000254 },
+  Default: { name: "File units", type: "unit", scale: 1.0 },
+};
+
+// Convert distance from unit to unit.
+
+export function convertUnits(fromUnits: string, toUnits: string, distance: number) {
+  const fromFactor = 1 / (ModelUnits[fromUnits] || ModelUnits.Default).scale;
+  const toFactor = (ModelUnits[toUnits] || ModelUnits.Default).scale || 1;
+  return distance * fromFactor * toFactor;
+}

package/src/Viewer/measurement/UnitFormatter.ts

@@ -0,0 +1,95 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2002-2025, Open Design Alliance (the "Alliance").
+// All rights reserved.
+//
+// This software and its documentation and related materials are owned by
+// the Alliance. The software may only be incorporated into application
+// programs owned by members of the Alliance, subject to a signed
+// Membership Agreement and Supplemental Software License Agreement with the
+// Alliance. The structure and organization of this software are the valuable
+// trade secrets of the Alliance and its suppliers. The software is also
+// protected by copyright law and international treaty provisions. Application
+// programs incorporating this software must include the following statement
+// with their copyright notices:
+//
+//   This application incorporates Open Design Alliance software pursuant to a
+//   license agreement with Open Design Alliance.
+//   Open Design Alliance Copyright (C) 2002-2025 by Open Design Alliance.
+//   All rights reserved.
+//
+// By use of this software, its documentation or related materials, you
+// acknowledge and accept the above terms.
+///////////////////////////////////////////////////////////////////////////////
+
+import { ModelUnits } from "./UnitConverter";
+
+// Returns a standard string representation of the display unit.
+
+export function getDisplayUnit(units: string) {
+  return (ModelUnits[units] || ModelUnits.Default).type;
+}
+
+// ===================== AI-CODE-START ======================
+// Source: Claude Sonnet 4.5
+// Date: 2025-10-08
+// Reviewer: roman.mochalov@opendesign.com
+// Issue: CLOUD-5963
+
+// Calculates recommended precision for small values (|value| < 1) to avoid showing "0.00".
+
+export function calculatePrecision(value: number) {
+  const distance = Math.abs(value);
+
+  if (distance >= 1000) return 0;
+  if (distance >= 10) return 1;
+  if (distance >= 0.1) return 2;
+  if (distance >= 0.001) return 3;
+
+  return distance > 0 ? Math.floor(-Math.log10(distance)) + 1 : 2;
+}
+
+// Calculates the minimal distance for the sepecified precision.
+
+export function calculateDistance(precision: any): number {
+  let digits: number;
+
+  if (precision === "Auto") digits = 2;
+  else if (Number.isFinite(precision)) digits = precision;
+  else digits = parseFloat(precision);
+
+  if (!Number.isFinite(digits) || digits < 0) digits = 2;
+  else if (digits > 10) digits = 10;
+
+  return Math.pow(10, -digits);
+}
+
+// ===================== AI-CODE-END ======================
+
+// Formats a distance with units.
+
+function formatNumber(distance: number, digits: number, precision: any) {
+  let result = distance.toFixed(digits);
+  if (precision === "Auto") result = result.replace(/\.0+$/, "").replace(/\.$/, "");
+  if (+result !== distance) result = "~ " + result;
+  return result;
+}
+
+export function formatDistance(distance: number, units: string, precision: any = 2) {
+  let digits: number;
+
+  if (precision === "Auto") digits = calculatePrecision(distance);
+  else if (Number.isFinite(precision)) digits = precision;
+  else digits = parseFloat(precision);
+
+  if (!Number.isFinite(digits)) digits = 2;
+  else if (digits < 0) digits = 0;
+  else if (digits > 10) digits = 10;
+
+  if (ModelUnits[units]) {
+    return formatNumber(distance, digits, precision) + " " + ModelUnits[units].type;
+  } else if (units) {
+    return formatNumber(distance, digits, precision) + " " + units;
+  } else {
+    return formatNumber(distance, digits, precision);
+  }
+}

package/src/Viewer/models/IModelImpl.ts

@@ -22,18 +22,23 @@
 ///////////////////////////////////////////////////////////////////////////////
 
 import { Box3, Object3D } from "three";
-import { ILoader, IViewer } from "@inweb/viewer-core";
+import { IInfo, IModel } from "@inweb/viewer-core";
 
 /**
- * Model interface.
+ * Basic model implementation.
  */
-export interface IModelImpl {
-  handle: string;
+export interface IModelImpl extends IModel {
   scene: Object3D;
-  loader: ILoader;
-  viewer: IViewer;
 
-  dispose(): void;
+  getUnits(): string;
+
+  getUnitScale(): number;
+
+  getUnitString(): string;
+
+  getPrecision(): number;
+
+  getInfo(): IInfo;
 
   getExtents(target: Box3): Box3;
 
@@ -41,10 +46,14 @@ export interface IModelImpl {
 
   getVisibleObjects(): Object3D[];
 
-  hasObject(objects: Object3D): boolean;
+  hasObject(object: Object3D): boolean;
+
+  hasHandle(handle: string): boolean;
 
   getOwnObjects(objects: Object3D | Object3D[]): Object3D[];
 
+  getOwnHandles(handles: string | string[]): string[];
+
   getObjectsByHandles(handles: string | string[]): Object3D[];
 
   getHandlesByObjects(objects: Object3D | Object3D[]): string[];