@inweb/viewer-core 26.10.5 → 26.11.0

package/lib/viewer/ViewerEvents.d.ts

@@ -19,7 +19,7 @@ export interface AnimateEvent {
     time: DOMHighResTimeStamp;
 }
 /**
- * Event that fires when model loading has been canceled.
+ * Event that fires when file loading has been canceled.
  *
  * @event
  */
@@ -207,7 +207,7 @@ export interface GeometryChunkEvent {
     buffer?: Uint8Array | ArrayBuffer;
 }
 /**
- * Event that fires after model has been successfully loaded.
+ * Event that fires after file has been successfully loaded.
  *
  * @event
  */
@@ -261,7 +261,7 @@ export interface GeometryErrorEvent {
     buffer?: Uint8Array | ArrayBuffer;
 }
 /**
- * Event that measures the progress of the model loading.
+ * Event that measures the progress of the file loading.
  *
  * @event
  */
@@ -290,7 +290,7 @@ export interface GeometryProgressEvent {
     buffer?: Uint8Array | ArrayBuffer;
 }
 /**
- * Event that fires before the model loads.
+ * Event that fires before the file loads.
  *
  * @event
  */
@@ -373,7 +373,7 @@ export interface IsolateEvent {
     type: "isolate";
 }
 /**
- * Event that fires before model open.
+ * Event that fires before file open.
  *
  * @event
  */
@@ -383,13 +383,13 @@ export interface OpenEvent {
      */
     type: "open";
     /**
-     * File to load.
+     * File opening mode.
      */
-    file: File | Assembly | Model | string | globalThis.File | ArrayBuffer;
+    mode: string;
     /**
-     * Model from file to load. Only defined when loading a file from the Open Cloud Server.
+     * File to load.
      */
-    model?: Model;
+    file: File | Assembly | Model | string | globalThis.File | ArrayBuffer;
     /**
      * Deprecated since `26.4`. Use {@link file} instead.
      *
@@ -487,9 +487,29 @@ export interface SelectEvent {
     /**
      * Selection set (viewer dependent).
      */
-    data: any;
+    data?: any;
     /**
-     * Handles of selected entities.
+     * Handles of selected objects.
+     */
+    handles: string[];
+}
+/**
+ * Event that fires after viewer selection changes. Uses model prefix to avoid handle collisions in
+ * assemblies (multi-model scenes).
+ *
+ * @event
+ */
+export interface Select2Event {
+    /**
+     * Event type.
+     */
+    type: "select2";
+    /**
+     * Selection set (viewer dependent).
+     */
+    data?: any;
+    /**
+     * Handles of selected objects with model prefix in format "model:handle".
      */
     handles: string[];
 }
@@ -683,7 +703,7 @@ export interface ViewerEventMap {
      */
     animate: AnimateEvent;
     /**
-     * Event that fires when model loading has been canceled.
+     * Event that fires when file loading has been canceled.
      */
     cancel: CancelEvent;
     /**
@@ -735,7 +755,7 @@ export interface ViewerEventMap {
      */
     geometrychunk: GeometryChunkEvent;
     /**
-     * Event that fires after model has been successfully loaded.
+     * Event that fires after file has been successfully loaded.
      */
     geometryend: GeometryEndEvent;
     /**
@@ -743,11 +763,11 @@ export interface ViewerEventMap {
      */
     geometryerror: GeometryErrorEvent;
     /**
-     * Event that measures the progress of the model loading.
+     * Event that measures the progress of the file loading.
      */
     geometryprogress: GeometryProgressEvent;
     /**
-     * Event that fires before the model opens.
+     * Event that fires before the file opens.
      */
     geometrystart: GeometryStartEvent;
     /**
@@ -767,7 +787,7 @@ export interface ViewerEventMap {
      */
     isolate: IsolateEvent;
     /**
-     * Event that fires before model opens.
+     * Event that fires before file opens.
      */
     open: OpenEvent;
     /**
@@ -790,6 +810,10 @@ export interface ViewerEventMap {
      * Event that fires when the selection changes.
      */
     select: SelectEvent;
+    /**
+     * Event that fires when the selection changes.
+     */
+    select2: Select2Event;
     /**
      * Event that fires after selected objects becomes visible.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inweb/viewer-core",
-  "version": "26.10.5",
+  "version": "26.11.0",
   "description": "3D CAD and BIM data Viewer core",
   "homepage": "https://cloud.opendesign.com/docs/index.html",
   "license": "SEE LICENSE IN LICENSE",
@@ -26,7 +26,7 @@
     "test": "karma start karma.conf.js"
   },
   "dependencies": {
-    "@inweb/client": "~26.10.5",
-    "@inweb/eventemitter2": "~26.10.5"
+    "@inweb/client": "~26.11.0",
+    "@inweb/eventemitter2": "~26.11.0"
   }
 }

package/src/commands/ICommands.ts

@@ -28,12 +28,13 @@ import { IViewer } from "../viewer/IViewer";
  */
 export interface ICommandService {
   /**
-   * Executes the command denoted by the given command ID.
+   * Executes the command denoted by the given command ID. If the command is not found, tries to set
+   * active dragger with the specified name.
    *
-   * @param id - ID of the command to execute.
+   * @param id - Command ID or dragger name.
    * @param args - Parameters passed to the command handler function.
-   * @returns Returns the result of the command handler function. Returns `undefined` when the command
-   *   doesn't exists.
+   * @returns Returns the result of the command handler function or new active dragger instance. Returns
+   *   `undefined` if neither the command nor the dragger exists.
    */
   executeCommand(id: string, ...args: any[]): any;
 }

package/src/index.ts

@@ -32,6 +32,7 @@ export * from "./components/IComponents";
 export * from "./loaders/ILoader";
 export * from "./loaders/Loader";
 export * from "./loaders/Loaders";
+export * from "./models/IModel";
 export * from "./options/IOptions";
 export * from "./options/Options";
 export * from "./options/OptionsEvents";

package/src/loaders/ILoader.ts

@@ -28,7 +28,7 @@ import type { IViewer } from "../viewer/IViewer";
  * Defines the file source to load into the viewer:
  *
  * - `File`, `Assembly` or `Model` instance from the Open Cloud Server
- * - File `URL` string
+ * - `URL` string
  * - {@link https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/Data_URIs | Data URL} string
  * - {@link https://developer.mozilla.org/docs/Web/API/File | Web API File} object
  * - {@link https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer | ArrayBuffer}

package/src/loaders/Loader.ts

@@ -43,4 +43,13 @@ export class Loader implements ILoader {
   cancel(): void {
     this.abortController.abort();
   }
+
+  extractFileName(file: FileSource): string {
+    const regex = /[^/\\?#:]+(?=\?|#|$)/;
+
+    if (typeof file === "string") return (file.match(regex) || [])[0];
+    else if (file instanceof globalThis.File) return (file.name.match(regex) || [])[0];
+
+    return undefined;
+  }
 }

package/src/models/IModel.ts

@@ -0,0 +1,44 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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 interface.
+ */
+export interface IModel {
+  /**
+   * Unique model ID, used as a model prefix when selecting objects in assemblies (multi-model scenes).
+   * Can be:
+   *
+   * - `file ID` - when loading a file from Open Cloud Server.
+   * - `assembly ID` - when loading an assembly from Open Cloud Server.
+   * - `model ID` - when loading a model of the file/assembly from Open Cloud Server.
+   * - `file name` - when loading from local File or URL.
+   * - `user defined` - when loading from ArrayBuffer or Data URL.
+   */
+  id: string;
+
+  /**
+   * Disposes the model and releases allocated resources.
+   */
+  dispose(): void;
+}

package/src/options/IOptions.ts

@@ -212,14 +212,45 @@ export interface IOptions {
   geometryType?: string;
 
   /**
-   * Ruler unit.
+   * Unit of measurement for the ruler tool (distance measurements).
    *
-   * Available values: Default, Millimeters, Centimeters, Meters, Feet, Inches, Yards, Kilometers, Miles,
-   * Micrometers, MicroInches
+   * When set to `Default`, the ruler uses the file's native units. Otherwise, distances are
+   * automatically converted to the specified unit.
+   *
+   * Available values:
+   *
+   * - `Default` - Use file's native units (recommended)
+   * - `Millimeters` - Metric: 0.001 m
+   * - `Centimeters` - Metric: 0.01 m
+   * - `Meters` - Metric: 1 m (base unit)
+   * - `Kilometers` - Metric: 1000 m
+   * - `Micrometers` - Metric: 0.000001 m
+   * - `Inches` - Imperial: 0.0254 m
+   * - `Feet` - Imperial: 0.3048 m
+   * - `Yards` - Imperial: 0.9144 m
+   * - `Miles` - Imperial: 1609.344 m
+   * - `Mils` - Imperial: 0.0000254 m
+   * - `MicroInches` - Imperial: 0.0000000254 m
    *
    * @defaultValue "Default"
    */
-  rulerUnit: string;
+  rulerUnit?: string;
+
+  /**
+   * Number of decimal places to display in ruler measurements.
+   *
+   * Controls the precision of distance values shown by the ruler tool. Higher values provide more
+   * precision but may clutter the display with unnecessary digits.
+   *
+   * Available values:
+   *
+   * - `Default` - Use file's native units precision, if supported, otherwise use 2 digits.
+   * - `Auto` - Automatically choose precision based on distance value.
+   * - `0`...`10` - Use specified number of decimal places (range 0-10, inclusive).
+   *
+   * @defaultValue 2
+   */
+  rulerPrecision?: any;
 
   /**
    * Camera projection mode:
@@ -267,6 +298,7 @@ export function defaultOptions(): IOptions {
     enableGestures: true,
     geometryType: "vsfx",
     rulerUnit: "Default",
+    rulerPrecision: 2,
     cameraMode: "perspective",
   };
 }

package/src/options/Options.ts

@@ -343,6 +343,15 @@ export class Options implements IOptions {
     this.change();
   }
 
+  get rulerPrecision(): any {
+    return this._data.rulerPrecision;
+  }
+
+  set rulerPrecision(value: any) {
+    this._data.rulerPrecision = value;
+    this.change();
+  }
+
   get cameraMode(): CameraMode {
     return this._data.cameraMode || "perspective";
   }

package/src/viewer/IViewer.ts

@@ -27,7 +27,8 @@ import { ICommandService } from "../commands/ICommands";
 import { IOptions } from "../options/IOptions";
 import { IDragger } from "../draggers/IDraggers";
 import { IComponent } from "../components/IComponents";
-import { FileSource } from "../loaders/ILoader";
+import { FileSource, ILoader } from "../loaders/ILoader";
+import { IModel } from "../models/IModel";
 import { IViewpoint } from "./IViewpoint";
 
 /**
@@ -78,6 +79,16 @@ export interface IViewer extends IEventEmitter, ICommandService {
    */
   canvasEvents: string[];
 
+  /**
+   * List of active loaders used to load models into the viewer.
+   */
+  loaders: ILoader[];
+
+  /**
+   * List of models loaded into the viewer.
+   */
+  models: IModel[];
+
   /**
    * List of names of available draggers.
    *
@@ -169,14 +180,16 @@ export interface IViewer extends IEventEmitter, ICommandService {
    * thrown.
    *
    * For URLs, the file extension is used to determine the file format. For a `ArrayBuffer` and `Data
-   * URL`, a file format must be specified using `params.format` parameter (see below). If no appropriate
-   * loader is found for the specified format, an exception will be thrown.
+   * URL`, a file format must be specified using `params.format` parameter. If no appropriate loader is
+   * found for the specified format, an exception will be thrown.
    *
    * If there was an active dragger before opening the file, it will be deactivated. After opening the
    * file, you must manually activate the required dragger.
    *
    * Fires:
    *
+   * - {@link CancelEvent | cancel}
+   * - {@link ClearEvent | clear}
    * - {@link OpenEvent | open}
    * - {@link GeometryStartEvent | geometrystart}
    * - {@link GeometryProgressEvent | geometryprogress}
@@ -185,23 +198,26 @@ export interface IViewer extends IEventEmitter, ICommandService {
    * - {@link GeometryEndEvent | geometryend}
    * - {@link GeometryErrorEvent | geometryerror}
    *
-   * @param file - File to load. Can be one of:
+   * @param file - File to load. Can be:
    *
    *   - `File`, `Assembly` or `Model` instance from the Open Cloud Server
-   *   - File `URL` string
+   *   - `URL` string
    *   - {@link https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/Data_URIs | Data URL} string
    *   - {@link https://developer.mozilla.org/docs/Web/API/File | Web API File} object
    *   - {@link https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer | ArrayBuffer}
    *       object
    *
    * @param params - Loading parameters.
-   * @param params.format - File format string. Required when loading a file as `ArrayBuffer` or `Data *
-   *   URL`.
-   * @param params.mode - File opening mode. Viewer specific. Can be one of:
+   * @param params.format - File format. Required when loading a file as `ArrayBuffer` or `Data URL`.
+   * @param params.mode - File opening mode. Can be one of:
    *
-   *   - `open` - Unloads an open file and opens a new one. This is default mode.
-   *   - `append` - Appends a file to an already open file. This mode is not supported for all formats.
+   *   - `file` - Single file mode. Unloads an open file and opens a new one. This is default mode.
+   *   - `assembly` - Assembly mode. Appends a file to an already open file (). This mode is not supported
+   *       for all viewers.
    *
+   * @param params.modelId - Unique model ID in the assembly (multi-model scene). Used as a model prefix
+   *   when selecting objects (see {@link getSelected2}). Must not contain the ":" (colon). Required when
+   *   loading a file as `ArrayBuffer` or `Data URL`.
    * @param params.requestHeader - The
    *   {@link https://developer.mozilla.org/docs/Glossary/Request_header | request header} used in HTTP
    *   request.
@@ -215,6 +231,7 @@ export interface IViewer extends IEventEmitter, ICommandService {
     params: {
       format?: string;
       mode?: string;
+      modelId?: string;
       requestHeader?: HeadersInit;
       withCredentials?: boolean;
     }
@@ -259,21 +276,45 @@ export interface IViewer extends IEventEmitter, ICommandService {
   clearSlices(): void;
 
   /**
-   * Returns a list of original handles for the selected objects.
+   * Returns a list of original handles for the selected objects. To avoid handle collisions in
+   * assemblies (multi-model scenes), use {@link getSelected2} instead.
+   *
+   * @returns The list of original object handles.
    */
   getSelected(): string[];
 
   /**
-   * Selects the objects by original handles.
+   * Returns a list of original handles for the selected objects in assemblies (multi-model scenes).
+   *
+   * @returns The list of original object handles with model prefix in format "model:handle".
+   */
+  getSelected2(): string[];
+
+  /**
+   * Selects the objects by original handles. To avoid handle collisions in assemblies (multi-model
+   * scenes), use {@link setSelected2} instead.
    *
    * Fires:
    *
    * - {@link SelectEvent | select}
+   * - {@link Select2Event | select2}
    *
    * @param handles - The list of original handles.
    */
   setSelected(handles?: string[]): void;
 
+  /**
+   * Selects the objects by original handles in assemblies (multi-model scenes).
+   *
+   * Fires:
+   *
+   * - {@link SelectEvent | select}
+   * - {@link Select2Event | select2}
+   *
+   * @param handles - The list of original handles with model prefix in format "model:handle".
+   */
+  setSelected2(handles?: string[]): void;
+
   /**
    * Unselects all objects.
    *
@@ -358,6 +399,8 @@ export interface IViewer extends IEventEmitter, ICommandService {
 
   /**
    * Returns the component reference, or `null` if there is no component with the specified name.
+   *
+   * @param name - Component name. Can be one of the {@link components} list.
    */
   getComponent(name: string): IComponent | null;
 

package/src/viewer/ViewerEvents.ts

@@ -45,7 +45,7 @@ export interface AnimateEvent {
 }
 
 /**
- * Event that fires when model loading has been canceled.
+ * Event that fires when file loading has been canceled.
  *
  * @event
  */
@@ -254,7 +254,7 @@ export interface GeometryChunkEvent {
 }
 
 /**
- * Event that fires after model has been successfully loaded.
+ * Event that fires after file has been successfully loaded.
  *
  * @event
  */
@@ -317,7 +317,7 @@ export interface GeometryErrorEvent {
 }
 
 /**
- * Event that measures the progress of the model loading.
+ * Event that measures the progress of the file loading.
  *
  * @event
  */
@@ -351,7 +351,7 @@ export interface GeometryProgressEvent {
 }
 
 /**
- * Event that fires before the model loads.
+ * Event that fires before the file loads.
  *
  * @event
  */
@@ -445,7 +445,7 @@ export interface IsolateEvent {
 }
 
 /**
- * Event that fires before model open.
+ * Event that fires before file open.
  *
  * @event
  */
@@ -456,14 +456,14 @@ export interface OpenEvent {
   type: "open";
 
   /**
-   * File to load.
+   * File opening mode.
    */
-  file: File | Assembly | Model | string | globalThis.File | ArrayBuffer;
+  mode: string;
 
   /**
-   * Model from file to load. Only defined when loading a file from the Open Cloud Server.
+   * File to load.
    */
-  model?: Model;
+  file: File | Assembly | Model | string | globalThis.File | ArrayBuffer;
 
   /**
    * Deprecated since `26.4`. Use {@link file} instead.
@@ -576,10 +576,33 @@ export interface SelectEvent {
   /**
    * Selection set (viewer dependent).
    */
-  data: any;
+  data?: any;
 
   /**
-   * Handles of selected entities.
+   * Handles of selected objects.
+   */
+  handles: string[];
+}
+
+/**
+ * Event that fires after viewer selection changes. Uses model prefix to avoid handle collisions in
+ * assemblies (multi-model scenes).
+ *
+ * @event
+ */
+export interface Select2Event {
+  /**
+   * Event type.
+   */
+  type: "select2";
+
+  /**
+   * Selection set (viewer dependent).
+   */
+  data?: any;
+
+  /**
+   * Handles of selected objects with model prefix in format "model:handle".
    */
   handles: string[];
 }
@@ -798,7 +821,7 @@ export interface ViewerEventMap {
   animate: AnimateEvent;
 
   /**
-   * Event that fires when model loading has been canceled.
+   * Event that fires when file loading has been canceled.
    */
   cancel: CancelEvent;
 
@@ -863,7 +886,7 @@ export interface ViewerEventMap {
   geometrychunk: GeometryChunkEvent;
 
   /**
-   * Event that fires after model has been successfully loaded.
+   * Event that fires after file has been successfully loaded.
    */
   geometryend: GeometryEndEvent;
 
@@ -873,12 +896,12 @@ export interface ViewerEventMap {
   geometryerror: GeometryErrorEvent;
 
   /**
-   * Event that measures the progress of the model loading.
+   * Event that measures the progress of the file loading.
    */
   geometryprogress: GeometryProgressEvent;
 
   /**
-   * Event that fires before the model opens.
+   * Event that fires before the file opens.
    */
   geometrystart: GeometryStartEvent;
 
@@ -903,7 +926,7 @@ export interface ViewerEventMap {
   isolate: IsolateEvent;
 
   /**
-   * Event that fires before model opens.
+   * Event that fires before file opens.
    */
   open: OpenEvent;
 
@@ -932,6 +955,11 @@ export interface ViewerEventMap {
    */
   select: SelectEvent;
 
+  /**
+   * Event that fires when the selection changes.
+   */
+  select2: Select2Event;
+
   /**
    * Event that fires after selected objects becomes visible.
    */