LoaderPlugin

Loads 3D files into the viewer. Supports programmatic loading from URL or File, drag-and-drop onto the canvas, and progressive LOD streaming for chunked manifests.

Usage

Load after the viewer is ready:

await viewer.ready();
await viewer.loadPlugin(new LoaderPlugin());

const loader = viewer.pluginManager.getPlugin("loader") as LoaderPlugin;
await loader.loadGlb("/models/engine.glb");

Service dependencies: loader, lod. Drag-and-drop is wired to the renderer's canvas on activate.

Supported file types via drag-and-drop and loadFromUrl: glb, gltf, obj, stl, ply, fbx, e57, las, laz, step.

Public API

Method	Description
loadFile(file: File)	Load from a browser File (used by drag-drop).
loadFromUrl(url, type?)	Load from a URL. Type is detected from the extension if omitted.
loadGlb(url, options?)	Load GLB/GLTF as a single THREE.Object3D. Loads companion edge lines unless disabled.
loadChunkedModel(manifestUrl, options?)	Load a spatial chunk manifest. Returns a ChunkedModelHandle.

GlbLoadOptions

Field	Type	Description
loadEdges	boolean	If false, skip companion .edges.json lookup. Default true.
edgesJsonUrl	string	Override the edge data URL. Default: same path as model with .edges.json extension.
disableMatrixAutoUpdate	boolean	Set matrixAutoUpdate = false on all meshes after load. Recommended for large static models.

ChunkedLoadOptions

Passed through to LoaderService.loadChunkedModel. Common fields: lod0ActivationPixels, maxFetchInFlight, lod0EvictDelayMs, onChunkLoaded.

ChunkedModelHandle

Returned by loadChunkedModel:

{
  root: THREE.Group;
  update(camera: THREE.Camera): void;  // Call each frame to drive LOD switching
  setMoving(moving: boolean): void;
  setSelectedMesh(mesh: THREE.Object3D | null): void;
  setClippingPlane(plane: THREE.Plane | null): void;
  dispose(): void;
}

Events

Event	Payload
loader:ready	{ formats }
file:loading-started	{ file }
file:loading-progress	{ file, progress }
file:loaded	{ file, object }
file:loading-error	{ file, error }
model:loaded	{ model, fileSpec }
model:unloaded	{ model }
model:edges-loaded	{ scene, appliedCount }
model:edges-failed	{ url, reason }

Example

const loader = viewer.pluginManager.getPlugin("loader") as LoaderPlugin;

viewer.eventBus.on("file:loading-progress", ({ progress }) => {
  console.log(`${Math.round(progress * 100)}%`);
});

const model = await loader.loadGlb("/models/assembly.glb", {
  disableMatrixAutoUpdate: true,
});

const handle = await loader.loadChunkedModel("/chunks/manifest.json");
viewer.addFrameCallback((camera) => handle.update(camera));