@inweb/viewer-core 26.10.6 → 26.12.0

package/lib/viewer/IViewer.d.ts

@@ -4,8 +4,10 @@ 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";
+import { IInfo } from "./IInfo";
 /**
  * Viewer core interface.
  */
@@ -50,6 +52,14 @@ export interface IViewer extends IEventEmitter, ICommandService {
      * - wheel
      */
     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.
      *
@@ -71,6 +81,10 @@ export interface IViewer extends IEventEmitter, ICommandService {
      * List of names of available components.
      */
     components: string[];
+    /**
+     * Statistical information about the GPU memory and the rendering process.
+     */
+    info: IInfo;
     /**
      * Initializes the viewer it with the specified canvas. Call {@link dispose | dispose()} to release
      * allocated resources.
@@ -134,14 +148,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}
@@ -150,23 +166,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.
@@ -178,6 +197,7 @@ export interface IViewer extends IEventEmitter, ICommandService {
     open(file: FileSource, params: {
         format?: string;
         mode?: string;
+        modelId?: string;
         requestHeader?: HeadersInit;
         withCredentials?: boolean;
     }): Promise<this>;
@@ -214,19 +234,41 @@ 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.
      *
@@ -302,6 +344,8 @@ export interface IViewer extends IEventEmitter, ICommandService {
     resetActiveDragger(): void;
     /**
      * 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/lib/viewer/Info.d.ts

@@ -0,0 +1,10 @@
+import { IInfo, IMemoryInfo, IPerformanceInfo, IRenderInfo, ISceneInfo, ISystemInfo } from "./IInfo";
+export declare class Info implements IInfo {
+    performance: IPerformanceInfo;
+    render: IRenderInfo;
+    scene: ISceneInfo;
+    optimizedScene: ISceneInfo;
+    memory: IMemoryInfo;
+    system: ISystemInfo;
+    constructor();
+}

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.6",
+  "version": "26.12.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.6",
-    "@inweb/eventemitter2": "~26.10.6"
+    "@inweb/client": "~26.12.0",
+    "@inweb/eventemitter2": "~26.12.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,10 +32,13 @@ 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";
 export * from "./viewer/CanvasEvents";
+export * from "./viewer/IInfo";
+export * from "./viewer/Info";
 export * from "./viewer/IViewer";
 export * from "./viewer/IViewpoint";
 export * from "./viewer/ViewerEvents";

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";
   }