@inweb/viewer-three 26.10.6 → 26.11.0

package/src/Viewer/loaders/GLTFBinaryExtension.ts

@@ -0,0 +1,91 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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.
+///////////////////////////////////////////////////////////////////////////////
+
+// ===================== AI-CODE-FILE ======================
+// Source: Claude Sonnet 4.5
+// Date: 2025-28-10
+// Reviewer: roman.mochalov@opendesign.com
+// Issue: CLOUD-5933
+// Notes: Originally AI-generated, modified manually
+// =========================================================
+
+const BINARY_EXTENSION_HEADER_MAGIC = "glTF";
+const BINARY_EXTENSION_HEADER_LENGTH = 12;
+const BINARY_EXTENSION_CHUNK_TYPES = { JSON: 0x4e4f534a, BIN: 0x004e4042 };
+
+export class GLTFBinaryExtension {
+  public content: string;
+  public body: ArrayBuffer;
+
+  constructor(data: ArrayBuffer) {
+    const headerView = new DataView(data, 0, BINARY_EXTENSION_HEADER_LENGTH);
+    const textDecoder = new TextDecoder();
+
+    const magic = textDecoder.decode(new Uint8Array(data.slice(0, 4)));
+
+    if (magic !== BINARY_EXTENSION_HEADER_MAGIC) {
+      this.content = textDecoder.decode(data);
+      return;
+    }
+
+    const header = {
+      magic,
+      version: headerView.getUint32(4, true),
+      length: headerView.getUint32(8, true),
+    };
+
+    if (header.magic !== BINARY_EXTENSION_HEADER_MAGIC) {
+      throw new Error("Unsupported glTF-Binary header.");
+    }
+
+    if (header.version < 2.0) {
+      throw new Error("Legacy binary file detected.");
+    }
+
+    const chunkContentsLength = header.length - BINARY_EXTENSION_HEADER_LENGTH;
+    const chunkView = new DataView(data, BINARY_EXTENSION_HEADER_LENGTH);
+    let chunkIndex = 0;
+
+    while (chunkIndex < chunkContentsLength) {
+      const chunkLength = chunkView.getUint32(chunkIndex, true);
+      chunkIndex += 4;
+
+      const chunkType = chunkView.getUint32(chunkIndex, true);
+      chunkIndex += 4;
+
+      if (chunkType === BINARY_EXTENSION_CHUNK_TYPES.JSON) {
+        const contentArray = new Uint8Array(data, BINARY_EXTENSION_HEADER_LENGTH + chunkIndex, chunkLength);
+        this.content = textDecoder.decode(contentArray);
+      } else if (chunkType === BINARY_EXTENSION_CHUNK_TYPES.BIN) {
+        const byteOffset = BINARY_EXTENSION_HEADER_LENGTH + chunkIndex;
+        this.body = data.slice(byteOffset, byteOffset + chunkLength);
+      }
+
+      chunkIndex += chunkLength;
+    }
+
+    if (typeof this.content === "undefined") {
+      throw new Error("JSON content not found.");
+    }
+  }
+}

package/src/Viewer/loaders/GLTFCloudDynamicLoader.ts

@@ -22,27 +22,28 @@
 ///////////////////////////////////////////////////////////////////////////////
 
 import { Group } from "three";
-import { ILoader, LoadParams } from "@inweb/viewer-core";
+import { Loader, LoadParams } from "@inweb/viewer-core";
 
 import { Viewer } from "../Viewer";
 import { DynamicModelImpl } from "./DynamicGltfLoader/DynamicModelImpl";
 import { DynamicGltfLoader } from "./DynamicGltfLoader/DynamicGltfLoader.js";
 import { GltfStructure } from "./DynamicGltfLoader/GltfStructure.js";
 
-export class GLTFCloudDynamicLoader implements ILoader {
+export class GLTFCloudDynamicLoader extends Loader {
   public viewer: Viewer;
   public gltfLoader: DynamicGltfLoader;
   public requestId = 0;
 
   constructor(viewer: Viewer) {
+    super();
     this.viewer = viewer;
   }
 
-  dispose() {
+  override dispose() {
     if (this.gltfLoader) this.gltfLoader.clear();
   }
 
-  isSupport(file: any): boolean {
+  override isSupport(file: any): boolean {
     return (
       typeof file === "object" &&
       typeof file.database === "string" &&
@@ -52,7 +53,7 @@ export class GLTFCloudDynamicLoader implements ILoader {
     );
   }
 
-  async load(model: any, format?: string, params?: LoadParams): Promise<this> {
+  override async load(model: any, format?: string, params: LoadParams = {}): Promise<this> {
     const scene = new Group();
 
     this.gltfLoader = new DynamicGltfLoader(this.viewer.camera, scene, this.viewer.renderer);
@@ -60,13 +61,11 @@ export class GLTFCloudDynamicLoader implements ILoader {
     this.gltfLoader.setVisibleEdges(this.viewer.options.edgeModel);
     // this.gltfLoader.setMaxConcurrentChunks(this.viewer.options.maxConcurrentChunks);
 
-    this.gltfLoader.addEventListener("databasechunk", (data) => {
-      const modelImpl = new DynamicModelImpl(scene);
-      modelImpl.loader = this;
-      modelImpl.viewer = this.viewer;
-      modelImpl.gltfLoader = this.gltfLoader;
-      modelImpl.modelId = model.id;
+    const modelImpl = new DynamicModelImpl(scene);
+    modelImpl.id = model.file.id;
+    modelImpl.gltfLoader = this.gltfLoader;
 
+    this.gltfLoader.addEventListener("databasechunk", (data) => {
       this.viewer.scene.add(scene);
       this.viewer.models.push(modelImpl);
 
@@ -77,11 +76,6 @@ export class GLTFCloudDynamicLoader implements ILoader {
       this.viewer.emitEvent({ type: "databasechunk", data: scene, file: model.file, model });
     });
 
-    this.gltfLoader.addEventListener("geometryprogress", (data) => {
-      const progress = data.loaded / data.total;
-      this.viewer.emitEvent({ type: "geometryprogress", data: progress, file: model.file, model });
-    });
-
     this.gltfLoader.addEventListener("geometryerror", (data) => {
       this.viewer.emitEvent({ type: "geometryerror", data, file: model.file, model });
     });
@@ -93,7 +87,7 @@ export class GLTFCloudDynamicLoader implements ILoader {
     const loadController = {
       loadJson: async () => {
         const progress = (progress: number) => {
-          this.viewer.emitEvent({ type: "geometryprogress", data: progress, file: model });
+          this.viewer.emitEvent({ type: "geometryprogress", data: progress, file: model.file, model });
         };
 
         const arrayBuffer = await model.downloadResource(
@@ -127,7 +121,7 @@ export class GLTFCloudDynamicLoader implements ILoader {
       baseUrl: () => Promise.resolve(`${model.httpClient.serverUrl}${model.path}/`),
     };
 
-    const structure = new GltfStructure(model.id, loadController);
+    const structure = new GltfStructure(modelImpl.id, loadController);
 
     await this.gltfLoader.loadStructure(structure);
     await this.gltfLoader.loadNodes();
@@ -135,7 +129,7 @@ export class GLTFCloudDynamicLoader implements ILoader {
     return this;
   }
 
-  cancel() {
+  override cancel() {
     if (this.gltfLoader) this.gltfLoader.abortLoading();
   }
 }

package/src/Viewer/loaders/GLTFFileDynamicLoader.ts

@@ -0,0 +1,145 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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 { FileLoader, Group, LoaderUtils } from "three";
+import { Loader } from "@inweb/viewer-core";
+
+import { Viewer } from "../Viewer";
+import { DynamicModelImpl } from "./DynamicGltfLoader/DynamicModelImpl";
+import { DynamicGltfLoader } from "./DynamicGltfLoader/DynamicGltfLoader.js";
+import { GltfStructure } from "./DynamicGltfLoader/GltfStructure.js";
+import { GLTFLoadingManager, GLTFLoadParams } from "./GLTFLoadingManager";
+import { GLTFBinaryExtension } from "./GLTFBinaryExtension";
+import { RangesLoader } from "./RangesLoader";
+
+export class GLTFFileDynamicLoader extends Loader {
+  public viewer: Viewer;
+  private gltfLoader: DynamicGltfLoader;
+  private manager: GLTFLoadingManager;
+  private gltf: any;
+  private bin: ArrayBuffer;
+
+  constructor(viewer: Viewer) {
+    super();
+    this.viewer = viewer;
+  }
+
+  override dispose() {
+    if (this.gltfLoader) this.gltfLoader.clear();
+    if (this.manager) this.manager.dispose();
+  }
+
+  override isSupport(file: any, format?: string): boolean {
+    return (
+      (typeof file === "string" || file instanceof globalThis.File || file instanceof ArrayBuffer) &&
+      /(gltf|glb)$/i.test(format)
+    );
+  }
+
+  override async load(file: any, format?: string, params?: GLTFLoadParams): Promise<this> {
+    this.manager = new GLTFLoadingManager(file, params);
+
+    const scene = new Group();
+
+    this.gltfLoader = new DynamicGltfLoader(this.viewer.camera, scene, this.viewer.renderer);
+    this.gltfLoader.memoryLimit = this.viewer.options.memoryLimit;
+    this.gltfLoader.visibleEdges = this.viewer.options.edgeModel;
+
+    const modelImpl = new DynamicModelImpl(scene);
+    modelImpl.id = params.modelId || this.extractFileName(file);
+    modelImpl.gltfLoader = this.gltfLoader;
+
+    this.gltfLoader.addEventListener("databasechunk", () => {
+      this.viewer.scene.add(scene);
+      this.viewer.models.push(modelImpl);
+
+      this.viewer.syncOptions();
+      this.viewer.syncOverlay();
+      this.viewer.update();
+
+      this.viewer.emitEvent({ type: "databasechunk", data: scene, file });
+    });
+
+    this.gltfLoader.addEventListener("geometryerror", (data) => {
+      this.viewer.emitEvent({ type: "geometryerror", data, file });
+    });
+
+    this.gltfLoader.addEventListener("update", (data) => {
+      this.viewer.update();
+    });
+
+    const loadController = {
+      loadJson: async () => {
+        const loader = new FileLoader(this.manager);
+        loader.setPath(this.manager.path);
+        loader.setRequestHeader((params.requestHeader as any) || {});
+        loader.setWithCredentials(params.withCredentials || loader.withCredentials);
+        loader.setResponseType("arraybuffer");
+
+        const progress = (event: ProgressEvent) => {
+          const { lengthComputable, loaded, total } = event;
+          const progress = lengthComputable ? loaded / total : 1;
+          this.viewer.emitEvent({ type: "geometryprogress", data: progress, file });
+        };
+
+        const data = await loader.loadAsync(this.manager.fileURL, progress);
+
+        const extension = new GLTFBinaryExtension(data as ArrayBuffer);
+        this.gltf = JSON.parse(extension.content);
+        this.bin = extension.body;
+
+        return this.gltf;
+      },
+
+      loadBinaryData: (ranges, uri = "") => {
+        const loader = new RangesLoader();
+        loader.setRequestHeader((params.requestHeader as any) || {});
+        loader.setWithCredentials(params.withCredentials || false);
+        loader.setAbortSignal(this.gltfLoader.abortController.signal);
+
+        if (this.bin) return loader.extractRanges(this.bin, ranges);
+
+        const path = this.manager.path || this.manager.resourcePath;
+        const url = LoaderUtils.resolveURL(uri, path);
+
+        return loader.load(this.manager.resolveURL(url), ranges);
+      },
+
+      baseUrl: () => {
+        const path = this.manager.path || this.manager.resourcePath;
+        return Promise.resolve(path);
+      },
+    };
+
+    const structure = new GltfStructure(modelImpl.id, loadController);
+
+    await this.gltfLoader.loadStructure(structure);
+    await this.gltfLoader.loadNodes();
+
+    return this;
+  }
+
+  override cancel() {
+    if (this.gltfLoader) this.gltfLoader.abortLoading();
+  }
+}

package/src/Viewer/loaders/GLTFLoadingManager.ts

@@ -21,16 +21,17 @@
 // acknowledge and accept the above terms.
 ///////////////////////////////////////////////////////////////////////////////
 
+import { LoadParams } from "@inweb/viewer-core";
 import { LoadingManager, LoaderUtils } from "three";
 
 export type GLTFFileSource = string | globalThis.File | ArrayBuffer;
 
-export type GLTFLoadParams = {
+export type GLTFLoadParams = LoadParams & {
+  requestHeader?: HeadersInit;
+  withCredentials?: boolean;
   path?: string;
   externalFiles?: Map<string, GLTFFileSource>;
   crossOrigin?: string;
-  requestHeader?: HeadersInit;
-  withCredentials?: boolean;
 };
 
 export class GLTFLoadingManager extends LoadingManager {
@@ -72,6 +73,6 @@ export class GLTFLoadingManager extends LoadingManager {
   }
 
   dispose() {
-    this.dataURLs.forEach(URL.revokeObjectURL);
+    this.dataURLs.forEach((dataURL) => URL.revokeObjectURL(dataURL));
   }
 }

package/src/Viewer/loaders/RangesLoader.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.
+///////////////////////////////////////////////////////////////////////////////
+
+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 Error(`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));