Speckle Impl Viewer

speckle-impl-viewer

Quick Reference

Installation

npm install --save @speckle/viewer

The package is written in TypeScript and provides full type definitions.

Architecture Overview

Viewer Lifecycle

1. Create container element  -->  HTML div with explicit dimensions
2. new Viewer(container, params)  -->  Construct viewer instance
3. await viewer.init()  -->  Initialize WebGL context and assets
4. viewer.createExtension(...)  -->  Register required extensions
5. await viewer.loadObject(loader)  -->  Load 3D model data
6. viewer.on(event, handler)  -->  Subscribe to viewer events
7. viewer.dispose()  -->  Release all GPU resources on cleanup

Critical Warnings

NEVER call loadObject(), createExtension(), or any other viewer method before await viewer.init() completes. The viewer internals are NOT ready until init resolves. Calling methods before init causes silent failures or runtime errors.

NEVER omit viewer.dispose() when removing the viewer from the DOM. Failing to dispose causes GPU memory leaks that accumulate across page navigations in SPAs.

NEVER pass an empty string as the auth token in SpeckleLoader when loading private models. An empty token causes the loader to silently load zero objects with no error. ALWAYS provide a valid personal access token for private resources.

NEVER create extensions before calling await viewer.init(). Extensions depend on viewer internals that are initialized during init().

ALWAYS set explicit dimensions (width + height) on the container element. A zero-size container causes the WebGL context to fail silently.

ALWAYS call viewer.resize() when the container element changes size dynamically (e.g., window resize, panel toggle). The viewer does NOT detect container size changes automatically.

Viewer Class

Constructor

new Viewer(container: HTMLElement, params: ViewerParams)

ViewerParams

interface ViewerParams {
  showStats: boolean;              // Display performance stats panel
  environmentSrc: Asset;           // HDRI environment map URL for IBL lighting
  verbose: boolean;                // Enable debug logging
  restrictInputToCanvas: boolean;  // Limit input handling to canvas element only
}

Use DefaultViewerParams for sensible defaults (stats off, verbose off, default HDRI, canvas restriction off).

Core Methods

Accessors

SpeckleLoader and UrlHelper

Loading Workflow

import { SpeckleLoader, UrlHelper } from "@speckle/viewer";

// Step 1: Resolve project/model URL to resource URLs
const urls = await UrlHelper.getResourceUrls(
  "https://app.speckle.systems/projects/PROJECT_ID/models/MODEL_ID"
);

// Step 2: Load each resource
for (const url of urls) {
  const loader = new SpeckleLoader(viewer.getWorldTree(), url, authToken);
  await viewer.loadObject(loader, true);
}

SpeckleLoader Constructor

new SpeckleLoader(worldTree: WorldTree, url: string, authToken: string)

UrlHelper

UrlHelper.getResourceUrls(speckleUrl: string): Promise<string[]>

Accepts a Speckle project/model URL and returns an array of resource URLs suitable for SpeckleLoader. ALWAYS use this method -- NEVER construct resource URLs manually.

Loader Events

enum LoaderEvent {
  LoadProgress = 'load-progress',    // { progress: number; id: string }
  LoadCancelled = 'load-cancelled',  // string
  LoadWarning = 'load-warning'       // { message: string }
}

ViewerEvent

Extensions

All extensions inherit from Extension. Create them via viewer.createExtension() AFTER init.

Extension Base Class

abstract class Extension {
  protected viewer: IViewer;
  get enabled(): boolean;
  set enabled(value: boolean);
  get inject(): Array<Constructor<Extension>>;  // Declare dependencies
  onEarlyUpdate(deltaTime?: number): void;
  onLateUpdate(deltaTime?: number): void;
  onRender(): void;
  onResize(): void;
}

CameraController

Controls camera navigation: orbit, pan, zoom, fly modes.

Camera events: Stationary, Dynamic, FrameUpdate, ProjectionChanged.

SelectionExtension

Handles object picking and selection highlighting.

Automatically listens to ObjectClicked, ObjectDoubleClicked, and PointerMove events.

FilteringExtension

Controls object visibility, isolation, and color filtering.

DiffExtension

Visual comparison between two model versions.

VisualDiffMode: PLAIN or COLORED. DiffResult contains unchanged, added, removed, modified arrays of TreeNode.

MeasurementsTool

Interactive distance and area measurements.

MeasurementType: PERPENDICULAR, POINTTOPOINT, AREA, POINT.

SectionTool

Section plane/box for cutting through models.

Events: SectionToolEvent.DragStart, SectionToolEvent.DragEnd, SectionToolEvent.Updated (payload: Plane[]).

Custom Extensions

import { Extension, IViewer } from "@speckle/viewer";

class MyExtension extends Extension {
  // Declare dependencies on other extensions
  get inject() {
    return [CameraController]; // Auto-injected by viewer
  }

  // Lifecycle hooks
  onEarlyUpdate(deltaTime?: number): void {
    // Called before viewer update each frame
  }

  onLateUpdate(deltaTime?: number): void {
    // Called after viewer update each frame
  }

  onRender(): void {
    // Called after each render pass
  }

  onResize(): void {
    // Called when viewport resizes
  }
}

// Register with viewer
const myExt = viewer.createExtension(MyExtension);

ALWAYS declare dependencies via the inject getter. The viewer resolves and injects them automatically. NEVER manually instantiate extensions with new.

Rendering Pipeline

The viewer uses a custom WebGL rendering pipeline built on Three.js internals. Access via viewer.getRenderer():

• Scene management and material overrides
• Custom render passes
• Shadow configuration
• Post-processing effects

This is an advanced API. ALWAYS use extensions for standard interactions. Only use SpeckleRenderer when built-in extensions do not cover your use case.

Reference Links

• references/methods.md -- Complete API signatures for Viewer, extensions, types
• references/examples.md -- Working code examples from setup to rendering
• references/anti-patterns.md -- What NOT to do, with explanations

Official Sources

• https://docs.speckle.systems/developers/viewer/viewer-api.md
• https://docs.speckle.systems/developers/viewer/basic-setup.md
• https://docs.speckle.systems/developers/viewer/extensions/
• https://docs.speckle.systems/developers/viewer/loader-api.md