@inweb/viewer-core 26.10.6 → 26.12.0

package/src/viewer/IInfo.ts

@@ -0,0 +1,196 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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.
+///////////////////////////////////////////////////////////////////////////////
+
+/**
+ * Perfomance metrics.
+ */
+export interface IPerformanceInfo {
+  /**
+   * Frames Per Second: the measure of rendering performance and smoothness.
+   */
+  fps: number;
+
+  /**
+   * The time it takes to render a single frame.
+   */
+  frameTime: number;
+
+  /**
+   * The time from loading the file to the first frame being rendered on screen.
+   */
+  timeToFirstRender: number;
+
+  /**
+   * The total file loading time.
+   */
+  loadTime: number;
+}
+
+/**
+ * Render related metrics.
+ */
+export interface IRenderInfo {
+  /**
+   * The current width and height of the rendering canvas.
+   */
+  viewport: { width: number; height: number };
+
+  /**
+   * The current anti-aliasing technique being used.
+   */
+  antialiasing: string;
+
+  /**
+   * The number of draw calls of the current frame.
+   */
+  drawCalls: number;
+
+  /**
+   * The number of rendered triangle primitives of the current frame.
+   */
+  triangles: number;
+
+  /**
+   * The number of rendered point primitives of the current frame.
+   */
+  points: number;
+
+  /**
+   * The number of rendered line primitives of the current frame.
+   */
+  lines: number;
+}
+
+/**
+ * Scene related metrics.
+ */
+export interface ISceneInfo {
+  /**
+   * The total number of objects in the scene graph.
+   */
+  objects: number;
+
+  /**
+   * The total number of triangles in the entire scene.
+   */
+  triangles: number;
+
+  /**
+   * The total number of point primitives in the scene.
+   */
+  points: number;
+
+  /**
+   * The total number of lines in the scene.
+   */
+  lines: number;
+
+  /**
+   * The total number of edges in the scene.
+   */
+  edges: number;
+}
+
+/**
+ * Memory related metrics.
+ */
+export interface IMemoryInfo {
+  /**
+   * The number of unique geometries and the memory they consume.
+   */
+  geometries: number;
+  geometryBytes: number;
+
+  /**
+   * The number of textures and the memory they consume.
+   */
+  textures: number;
+  textureBytes: number;
+
+  /**
+   * The number of unique materials in use.
+   */
+  materials: number;
+
+  /**
+   * An estimation of the total VRAM being used by the WebGL context.
+   */
+  totalEstimatedGpuBytes: number;
+
+  // The currently active segment of JS heap, in bytes. This feature
+  // is not standardized. We do not recommend using non-standard features
+  // in production, as they have limited browser support, and may change
+  // or be removed.
+
+  usedJSHeapSize: number;
+}
+
+/**
+ * System information.
+ */
+export interface ISystemInfo {
+  /**
+   * Renderer string of the graphics driver.
+   */
+  webglRenderer: string;
+
+  /**
+   * Vendor string of the graphics driver.
+   */
+  webglVendor: string;
+}
+
+/**
+ * The statistical information about the scene, GPU memory and the rendering process.
+ */
+export interface IInfo {
+  /**
+   * Perfomance metrics.
+   */
+  performance: IPerformanceInfo;
+
+  /**
+   * Render related metrics.
+   */
+  render: IRenderInfo;
+
+  /**
+   * Scene related metrics.
+   */
+  scene: ISceneInfo;
+
+  /**
+   * Scene related metrics after optimization.
+   */
+  optimizedScene: ISceneInfo;
+
+  /**
+   * Memory related metrics.
+   */
+  memory: IMemoryInfo;
+
+  /**
+   * System information.
+   */
+  system: ISystemInfo;
+}

package/src/viewer/IViewer.ts

@@ -27,8 +27,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.
@@ -78,6 +80,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.
    *
@@ -101,6 +113,11 @@ export interface IViewer extends IEventEmitter, ICommandService {
    */
   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.
@@ -169,14 +186,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 +204,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 +237,7 @@ export interface IViewer extends IEventEmitter, ICommandService {
     params: {
       format?: string;
       mode?: string;
+      modelId?: string;
       requestHeader?: HeadersInit;
       withCredentials?: boolean;
     }
@@ -259,21 +282,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 +405,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/Info.ts

@@ -0,0 +1,82 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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 { IInfo, IMemoryInfo, IPerformanceInfo, IRenderInfo, ISceneInfo, ISystemInfo } from "./IInfo";
+
+export class Info implements IInfo {
+  public performance: IPerformanceInfo; // animate
+  public render: IRenderInfo; // render
+  public scene: ISceneInfo; // databasechunk
+  public optimizedScene: ISceneInfo; // databasechunk
+  public memory: IMemoryInfo; // databasechunk
+  public system: ISystemInfo; // initialize, options, resize
+
+  constructor() {
+    this.performance = {
+      fps: 0,
+      frameTime: 0,
+      timeToFirstRender: 0,
+      loadTime: 0,
+    };
+
+    this.render = {
+      viewport: { width: 0, height: 0 },
+      antialiasing: "",
+      drawCalls: 0,
+      triangles: 0,
+      points: 0,
+      lines: 0,
+    };
+
+    this.scene = {
+      objects: 0,
+      triangles: 0,
+      points: 0,
+      lines: 0,
+      edges: 0,
+    };
+
+    this.optimizedScene = {
+      objects: 0,
+      triangles: 0,
+      points: 0,
+      lines: 0,
+      edges: 0,
+    };
+
+    this.memory = {
+      geometries: 0,
+      geometryBytes: 0,
+      textures: 0,
+      textureBytes: 0,
+      materials: 0,
+      totalEstimatedGpuBytes: 0,
+      usedJSHeapSize: 0,
+    };
+
+    this.system = {
+      webglRenderer: "",
+      webglVendor: "",
+    };
+  }
+}

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.
    */