@inweb/viewer-visualize/src/Viewer/Loaders/index.ts

JavaScript library for rendering CAD and BIM files in a browser using VisualizeJS

///////////////////////////////////////////////////////////////////////////////
// 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 { ILoadersRegistry, loadersRegistry } from "@inweb/viewer-core";

import { VSFFileLoader } from "./VSFFileLoader";
import { VSFCloudLoader } from "./VSFCloudLoader";

import { VSFXFileLoader } from "./VSFXFileLoader";
import { VSFXCloudLoader } from "./VSFXCloudLoader";
import { VSFXCloudStreamingLoader } from "./VSFXCloudStreamingLoader";
import { VSFXCloudPartialLoader } from "./VSFXCloudPartialLoader";

/**
 * 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 check 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 data from file into the buffer. The model data must be a `VSFX` format.
 *    - Parse data buffer with the `VisualizeJS` viewer instance.
 *    - Create `ModelImpl` instance with unique model ID add it to the viewer `models` list.
 *    - Synchronize viewer styles, options and overlay.
 *    - Update the viewer.
 *
 *    The loader must emit events:
 *
 *    - `geometryprogress` - during loading (or once at 100% when complete).
 *    - `databasechunk` - when model is loaded and ready to render.
 * 5. Override {@link ILoader.dispose} and release loader resources, if required.
 * 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 { Loader, loaders, Viewer } from "@inweb/viewer-visualize";
 *
 * class MyLoader extends Loader {
 *   public viewer: Viewer;
 *
 *   constructor(viewer: Viewer) {
 *     super();
 *     this.viewer = viewer;
 *   }
 *
 *   override isSupport(file, format): Boolean {
 *     // check if this loader supports the file source and format
 *     return type file === "string" && format === "myformat";
 *   }
 *
 *   override load(file, format, params): Promise<this> {
 *    // load VSFX data from file (custom loading logic)
 *     const data = await fetch(file).then((result) => result.arrayBuffer());
 *
 *     const modelImpl = new ModelImpl();
 *     modelImpl.id = params.modelId;
 *
 *     this.viewer.visViewer().parseVsfx(new Uint8Array(data));
 *     this.viewer.models.push(modelImpl);
 *
 *     this.viewer.syncOptions();
 *     this.viewer.syncOverlay();
 *
 *     this.viewer.emitEvent({ type: "geometryprogress", data: 1, file });
 *     this.viewer.emitEvent({ type: "databasechunk", data, file });
 *
 *     this.viewer.update(true);
 *
 *     return Promise.resove(this);
 *   };
 * }
 *
 * loaders.registerLoader("MyLoader", (viewer) => new MyLoader(viewer));
 * ```
 */
export const loaders: ILoadersRegistry = loadersRegistry("visualizejs");

// build-in loaders

loaders.registerLoader("vsf-file", (viewer: any) => new VSFFileLoader(viewer));
loaders.registerLoader("vsf-cloud", (viewer: any) => new VSFCloudLoader(viewer));

loaders.registerLoader("vsfx-file", (viewer: any) => new VSFXFileLoader(viewer));
loaders.registerLoader("vsfx-cloud", (viewer: any) => new VSFXCloudLoader(viewer));
loaders.registerLoader("vsfx-cloud-streaming", (viewer: any) => new VSFXCloudStreamingLoader(viewer));
loaders.registerLoader("vsfx-cloud-partial", (viewer: any) => new VSFXCloudPartialLoader(viewer));