@inweb/viewer-three 26.5.0 → 26.5.1

package/lib/Viewer/Viewer.d.ts

@@ -1,8 +1,7 @@
 import { Box3, Object3D, OrthographicCamera, PerspectiveCamera, Scene, Vector3, WebGLRenderer } from "three";
-import { GLTF } from "three/examples/jsm/loaders/GLTFLoader.js";
 import { EventEmitter2 } from "@inweb/eventemitter2";
 import { Assembly, Client, Model, File } from "@inweb/client";
-import { CanvasEventMap, IComponent, IDragger, IOptions, IViewer, IViewpoint, Options, OptionsEventMap, ViewerEventMap } from "@inweb/viewer-core";
+import { CanvasEventMap, FileSource, IComponent, IDragger, ILoader, IOptions, IViewer, IViewpoint, Options, OptionsEventMap, ViewerEventMap } from "@inweb/viewer-core";
 import { IMarkup, IWorldTransform } from "@inweb/markup";
 /**
  * 3D viewer powered by {@link https://threejs.org/ | Three.js}.
@@ -17,7 +16,8 @@ export declare class Viewer extends EventEmitter2<ViewerEventMap & CanvasEventMa
     helpers: Scene | undefined;
     camera: PerspectiveCamera | OrthographicCamera | undefined;
     renderer: WebGLRenderer | undefined;
-    models: Array<GLTF>;
+    models: Array<Object3D>;
+    loaders: Array<ILoader>;
     selected: Array<Object3D>;
     extents: Box3;
     target: Vector3;
@@ -49,17 +49,35 @@ export declare class Viewer extends EventEmitter2<ViewerEventMap & CanvasEventMa
     syncOptions(options?: IOptions): void;
     loadReferences(model: Model | File | Assembly): Promise<this>;
     /**
-     * Loads a file from Open Cloud Server into the viewer.
+     * Loads a file into the viewer.
      *
-     * The file geometry data on the server must be converted to `glTF` format.
+     * The viewer must be {@link initialize | initialized} before opening the file. Otherwise, `open()` does
+     * nothing.
      *
-     * This method requires a `Client` instance to be specified when creating the viewer to load model
-     * reference files from the Open Cloud Server. For a standalone viewer instance use
-     * {@link openGltfFile | openGltfFile()}.
+     * This method requires a `Client` instance to be specified to load file from the Open Cloud Server.
+     * The file geometry data on the Open Cloud Server must be converted into a format siutable for the
+     * viewer, otherwise an exception will be thrown.
+     *
+     * For files from Open Cloud Server, the default model will be loaded. If there is no default model,
+     * first availiable model will be loaded. If no models are found in the file, an exception will be
+     * thrown.
+     *
+     * The file extension is used to determine the file format. For a `ArrayBuffer`, `Blob` 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.
      *
      * 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.
      *
+     * To open a large files, enable {@link IOptions.enablePartialMode | partial streaming} mode before
+     * opening. For example:
+     *
+     * ```javascript
+     * viewer.options.enableStreamingMode = true;
+     * viewer.options.enablePartialMode = true;
+     * await viewer.open(file);
+     * ```
+     *
      * Fires:
      *
      * - {@link OpenEvent | open}
@@ -70,37 +88,23 @@ export declare class Viewer extends EventEmitter2<ViewerEventMap & CanvasEventMa
      * - {@link GeometryEndEvent | geometryend}
      * - {@link GeometryErrorEvent | geometryerror}
      *
-     * @param file - File, assembly or specific model to load. If a `File` instance with multiple models is
-     *   specified, the default model will be loaded. If there is no default model, first availiable model
-     *   will be loaded.
-     */
-    open(file: Model | File | Assembly): Promise<this>;
-    cancel(): this;
-    /**
-     * Loads a `glTF` file into the viewer.
-     *
-     * 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.
+     * @param file - File to load.
+     * @param params - Loading parameters.
+     * @param params.format - File format string. Required when loading a file as `ArrayBuffer`, `Blob` or
+     *   `Data URL`.
+     * @param params.mode - File opening mode. Can be one of:
      *
-     * Fires:
+     *   - `open` - Unloads an open file and opens a new one. This is default mode.
+     *   - `append` - Appends a file to an already open file.
      *
-     * - {@link OpenEvent | open}
-     * - {@link GeometryStartEvent | geometrystart}
-     * - {@link GeometryProgressEvent | geometryprogress}
-     * - {@link DatabaseChunkEvent | databasechunk}
-     * - {@link GeometryEndEvent | geometryend}
-     * - {@link GeometryErrorEvent | geometryerror}
-     *
-     * @param file - File URL or binary data buffer to load.
-     * @param externalData - External resource map such as binary data buffers or images. Each resource
-     *   should be represented by a `uri` and a corresponding resource URL, or
+     * @param params.externalFiles - External resource map such as binary data buffers or textures. Each
+     *   resource should be represented by a `uri` and a corresponding resource URL, or
      *   {@link https://developer.mozilla.org/docs/Web/API/File | Web API File} object, or
-     *   {@link https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer | ArrayBuffer}
+     *   {@link https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer | ArrayBuffer},
      *   or {@link https://developer.mozilla.org/docs/Web/API/Blob/Blob | Blob}, or
      *   {@link https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/Data_URIs | Data URL} string,
-     * @param params - Loader parameters.
-     * @param params.path - The base path from which to find subsequent glTF resources such as textures and
-     *   .bin data files. If not defined, the base path of the file URL will be used.
+     * @param params.path - The base path from which additional resources will be loaded. If not defined,
+     *   the base path of the file URL will be used.
      * @param params.requestHeader - The
      *   {@link https://developer.mozilla.org/docs/Glossary/Request_header | request header} used in HTTP
      *   request.
@@ -110,49 +114,28 @@ export declare class Viewer extends EventEmitter2<ViewerEventMap & CanvasEventMa
      *   authorization headers or TLS client certificates. See
      *   {@link https://developer.mozilla.org/docs/Web/API/XMLHttpRequest/withCredentials | XMLHttpRequest.withCredentials}.
      */
-    openGltfFile(file: string | globalThis.File | ArrayBuffer | Blob, externalData?: Map<string, string | globalThis.File | ArrayBuffer | Blob>, params?: {
+    open(file: FileSource, params?: {
+        format?: string;
+        mode?: string;
         path?: string;
+        externalFiles?: Map<string, string | globalThis.File | ArrayBuffer | Blob>;
         requestHeader?: HeadersInit;
         crossOrigin?: string;
         withCredentials?: boolean;
     }): Promise<this>;
     /**
-     * Appends a `glTF` file to the existing opened file.
+     * Deprecated since `26.4`. Use {@link open | open()} instead.
      *
-     * Fires:
-     *
-     * - {@link OpenEvent | open}
-     * - {@link GeometryStartEvent | geometrystart}
-     * - {@link GeometryProgressEvent | geometryprogress}
-     * - {@link DatabaseChunkEvent | databasechunk}
-     * - {@link GeometryEndEvent | geometryend}
-     * - {@link GeometryErrorEvent | geometryerror}
+     * @deprecated
+     */
+    openGltfFile(file: any, externalFiles: any, params?: any): Promise<this>;
+    /**
+     * Deprecated since `26.4`. Use {@link open | open()} instead.
      *
-     * @param file - File URL or binary data buffer to load.
-     * @param externalData - External resource map such as binary data buffers or images. Each resource
-     *   should be represented by a `uri` and a corresponding resource URL, or
-     *   {@link https://developer.mozilla.org/docs/Web/API/File | Web API File} object, or
-     *   {@link https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer | ArrayBuffer}
-     *   or {@link https://developer.mozilla.org/docs/Web/API/Blob/Blob | Blob}, or
-     *   {@link https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/Data_URIs | Data URL} string,
-     * @param params - Loader parameters.
-     * @param params.path - The base path from which to find subsequent glTF resources such as textures and
-     *   .bin data files.
-     * @param params.requestHeader - The
-     *   {@link https://developer.mozilla.org/docs/Glossary/Request_header | request header} used in HTTP
-     *   request.
-     * @param params.crossOrigin - The crossOrigin string to implement CORS for loading the url from a
-     *   different domain that allows CORS. Default is `anonymous`.
-     * @param params.withCredentials - Whether the XMLHttpRequest uses credentials such as cookies,
-     *   authorization headers or TLS client certificates. See
-     *   {@link https://developer.mozilla.org/docs/Web/API/XMLHttpRequest/withCredentials | XMLHttpRequest.withCredentials}.
+     * @deprecated
      */
-    loadGltfFile(file: string | globalThis.File | ArrayBuffer | Blob, externalData?: Map<string, string | globalThis.File | ArrayBuffer | Blob>, params?: {
-        path?: string;
-        requestHeader?: HeadersInit;
-        crossOrigin?: string;
-        withCredentials?: boolean;
-    }): Promise<this>;
+    loadGltfFile(file: any, externalFiles: any, params?: any): Promise<this>;
+    cancel(): this;
     clear(): this;
     syncOverlay(): void;
     clearOverlay(): void;

package/lib/Viewer/loaders/GLTFFileLoader.d.ts

@@ -0,0 +1,9 @@
+import { Loader } from "@inweb/viewer-core";
+import { Viewer } from "../Viewer";
+import { GLTFLoadParams } from "./GLTFLoadingManager";
+export declare class GLTFFileLoader extends Loader {
+    viewer: Viewer;
+    constructor(viewer: Viewer);
+    isSupport(file: any, format?: string): boolean;
+    load(buffer: any, format?: string, params?: GLTFLoadParams): Promise<this>;
+}

package/lib/Viewer/loaders/GLTFLoadingManager.d.ts

@@ -1,11 +1,17 @@
 import { LoadingManager } from "three";
+export type GLTFFileSource = string | globalThis.File | ArrayBuffer | Blob;
+export type GLTFLoadParams = {
+    path?: string;
+    externalFiles?: Map<string, GLTFFileSource>;
+    requestHeader?: HeadersInit;
+    crossOrigin?: string;
+    withCredentials?: boolean;
+};
 export declare class GLTFLoadingManager extends LoadingManager {
     path: string;
     resourcePath: string;
     fileURL: string;
     dataURLs: Map<any, any>;
-    constructor(file: string | globalThis.File | ArrayBuffer | Blob, externalData?: Map<string, string | File | ArrayBuffer | Blob>, params?: {
-        path?: string;
-    });
+    constructor(file: GLTFFileSource, params?: GLTFLoadParams);
     dispose(): void;
 }

package/lib/Viewer/loaders/GLTFModelLoader.d.ts

@@ -0,0 +1,8 @@
+import { Loader } from "@inweb/viewer-core";
+import { Viewer } from "../Viewer";
+export declare class GLTFModelLoader extends Loader {
+    viewer: Viewer;
+    constructor(viewer: Viewer);
+    isSupport(model: any): boolean;
+    load(model: any): Promise<this>;
+}

package/lib/Viewer/loaders/index.d.ts

@@ -0,0 +1,67 @@
+import { ILoadersRegistry } from "@inweb/viewer-core";
+/**
+ * Viewer loaders registry. Use this registry to register custom loaders.
+ *
+ * To implement custom loader:
+ *
+ * 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.
+ * 4. Override {@link ILoader.load} and define the logic for loading the model from the file.
+ *
+ *    The loader should do:
+ *
+ *    - Load model from file. The model must be a Three.js object of type `Object3D` or a descendant of it.
+ *    - Add model to the viewer `scene` and `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.
+ *    - `databasechunk` - when model 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}.
+ *
+ * @example Implementing a custom loader.
+ *
+ * ```javascript
+ * import { Loader } from "@inweb/viewer-core";
+ * import { loaders, Viewer } from "@inweb/viewer-three";
+ *
+ * class MyLoader extends Loader {
+ *   public viewer: Viewer;
+ *
+ *   constructor(viewer: Viewer) {
+ *     super();
+ *     this.viewer = viewer;
+ *   }
+ *
+ *   override isSupport(file, format): Boolean {
+ *     // place custom logic here
+ *     return ...;
+ *   }
+ *
+ *   override load(file, format, params): Promise<this> {
+ *
+ *     // place custom loading logic here
+ *     const model = ...;
+ *
+ *     this.viewer.scene.add(model);
+ *     this.viewer.models.push(model);
+ *
+ *     this.viewer.syncOptions();
+ *     this.viewer.syncOverlay();
+ *     this.viewer.update();
+ *
+ *     this.viewer.emitEvent({ type: "databasechunk", data: model, file });
+ *
+ *     return Promise.resove(this);
+ *   };
+ * }
+ *
+ * loaders.registerLoader("MyLoader", (viewer) => new MyLoader(viewer));
+ * ```
+ */
+export declare const loaders: ILoadersRegistry;

package/lib/index-umd.d.ts

@@ -0,0 +1 @@
+export * from "./index";

package/lib/index.d.ts

@@ -1,6 +1,8 @@
+export * from "./Viewer/draggers";
+export * from "./Viewer/commands";
+export * from "./Viewer/components";
+export * from "./Viewer/loaders";
+export * from "./Viewer/loaders/GLTFLoadingManager";
+export * from "./Viewer/Viewer";
 export * from "@inweb/viewer-core";
 export * from "@inweb/markup";
-export { draggers } from "./Viewer/draggers";
-export { commands } from "./Viewer/commands";
-export { components } from "./Viewer/components";
-export { Viewer } from "./Viewer/Viewer";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inweb/viewer-three",
-  "version": "26.5.0",
+  "version": "26.5.1",
   "description": "JavaScript library for rendering CAD and BIM files in a browser using Three.js",
   "homepage": "https://cloud.opendesign.com/docs/index.html",
   "license": "SEE LICENSE IN LICENSE",
@@ -13,14 +13,17 @@
     "three",
     "three.js"
   ],
-  "sideEffects": false,
+  "sideEffects": [
+    "dist/plugins/**/*"
+  ],
   "main": "dist/viewer-three.js",
   "module": "dist/viewer-three.module.js",
   "types": "lib/index.d.ts",
   "files": [
     "dist",
     "lib/**/*.d.ts",
-    "src"
+    "src",
+    "plugins"
   ],
   "scripts": {
     "build": "rollup -c rollup.config.js",
@@ -28,10 +31,10 @@
     "docs": "typedoc"
   },
   "dependencies": {
-    "@inweb/client": "~26.5.0",
-    "@inweb/eventemitter2": "~26.5.0",
-    "@inweb/markup": "~26.5.0",
-    "@inweb/viewer-core": "~26.5.0"
+    "@inweb/client": "~26.5.1",
+    "@inweb/eventemitter2": "~26.5.1",
+    "@inweb/markup": "~26.5.1",
+    "@inweb/viewer-core": "~26.5.1"
   },
   "devDependencies": {
     "@types/three": "^0.173.0",

package/{src/Viewer → plugins}/components/AxesHelperComponent.ts

@@ -22,11 +22,9 @@
 ///////////////////////////////////////////////////////////////////////////////
 
 import { AxesHelper, Vector3 } from "three";
+import { IComponent, components, Viewer } from "@inweb/viewer-three";
 
-import { IComponent } from "@inweb/viewer-core";
-import type { Viewer } from "../Viewer";
-
-export class AxesHelperComponent implements IComponent {
+class AxesHelperComponent implements IComponent {
   private viewer: Viewer;
   private axesHelper1: AxesHelper;
   private axesHelper2: AxesHelper;
@@ -71,3 +69,5 @@ export class AxesHelperComponent implements IComponent {
     this.viewer.helpers.add(this.axesHelper2);
   };
 }
+
+components.registerComponent("AxesHelperComponent", (viewer) => new AxesHelperComponent(viewer));

package/{src/Viewer → plugins}/components/ExtentsHelperComponent.ts

@@ -22,11 +22,9 @@
 ///////////////////////////////////////////////////////////////////////////////
 
 import { Box3, Box3Helper } from "three";
+import { IComponent, components, Viewer } from "@inweb/viewer-three";
 
-import { IComponent } from "@inweb/viewer-core";
-import type { Viewer } from "../Viewer";
-
-export class ExtentsHelperComponent implements IComponent {
+class ExtentsHelperComponent implements IComponent {
   private viewer: Viewer;
   private boxHelper: Box3Helper;
 
@@ -56,3 +54,5 @@ export class ExtentsHelperComponent implements IComponent {
     this.viewer.helpers.add(this.boxHelper);
   };
 }
+
+components.registerComponent("ExtentsHelperComponent", (viewer) => new ExtentsHelperComponent(viewer));

package/{src/Viewer → plugins}/components/LightHelperComponent.ts

@@ -22,11 +22,9 @@
 ///////////////////////////////////////////////////////////////////////////////
 
 import { DirectionalLightHelper, Sphere } from "three";
+import { IComponent, components, Viewer } from "@inweb/viewer-three";
 
-import { IComponent } from "@inweb/viewer-core";
-import type { Viewer } from "../Viewer";
-
-export class LightHelperComponent implements IComponent {
+class LightHelperComponent implements IComponent {
   private viewer: Viewer;
   private lightHelpers: DirectionalLightHelper[];
 
@@ -67,3 +65,5 @@ export class LightHelperComponent implements IComponent {
     });
   };
 }
+
+components.registerComponent("LightHelperComponent", (viewer) => new LightHelperComponent(viewer));

package/plugins/loaders/IFCX/IFCXLoader.ts

@@ -0,0 +1,71 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2002-2024, 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-2024 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 { FileLoader, Loader, Scene } from "three";
+import { parse, clear } from "./render.js";
+
+class IFCXLoader extends Loader<Scene> {
+  override load(
+    url: string,
+    onLoad: (data: Scene) => void,
+    onProgress?: (event: ProgressEvent) => void,
+    onError?: (err: unknown) => void
+  ) {
+    const manager = this.manager;
+
+    manager.itemStart(url);
+
+    const _onLoad = (scene: Scene) => {
+      onLoad(scene);
+      manager.itemEnd(url);
+    };
+
+    const _onError = (e: unknown) => {
+      if (onError) onError(e);
+      else console.error(e);
+      manager.itemError(url);
+      manager.itemEnd(url);
+    };
+
+    const loader = new FileLoader(this.manager);
+
+    loader.setPath(this.path);
+    loader.setResponseType("json");
+    loader.setRequestHeader(this.requestHeader);
+    loader.setWithCredentials(this.withCredentials);
+
+    loader.load(url, (json) => this.parse(json, _onLoad, _onError), onProgress, onError);
+  }
+
+  parse(json: any, onLoad: (scene: Scene) => void, onError: (err: unknown) => void) {
+    try {
+      onLoad(parse(json));
+    } catch (e) {
+      onError(e);
+    } finally {
+      clear();
+    }
+  }
+}
+
+export { IFCXLoader };