Viewer

The Speckle Viewer API

Constructors

constructor

new Viewer(container: HTMLElement, params: ViewerParams)

Parameters:

• container: HTMLElement
• params: ViewerParams

Returns: Viewer

Accessors

Utils

get Utils(): Utils

Returns: Utils

World

get World(): World

Returns: World

Methods

cancelLoad

cancelLoad(url: string, unload?: boolean): Promise<void>

Cancels any ongoing loading operations, with the option of unloading an current progress

Parameters:

• url: string
• (optional) unload: boolean

Returns: A promise which resolves when the operation completes

createExtension

createExtension<T extends Extension>(type: new () => T): T

Creates and registers the extension of the specified type constructor

Parameters:

• type: Extension subclass

Returns: The extension instance

dispose

dispose(): void

Disposes the viewer instance

Returns: void

getContainer

getContainer(): HTMLElement

Gets HTML container used at viewer initialisation

Returns: HTMLElement

getExtension

getExtension<T extends Extension>(type: new () => T): T

Gets the extension of type T registered with the viewer.

Returns: Extension subclass, undefined if it does not exist

getObjectProperties

getObjectProperties(resourceURL?: string): Promise<PropertyInfo[]>

Returns PropertyInfo objects for all loaded objects. Properties are automatically extracted and cached when models are loaded.

Parameters:

• (optional) resourceURL: The resource URL to get properties for. If omitted, returns properties for all loaded resources.

Returns: PropertyInfo[]

getRenderer

getRenderer(): SpeckleRenderer

Gets the SpeckleRenderer instance associated with the viewer.

Returns: SpeckleRenderer

getViews

getViews(): SpeckleView[]

Gets all the current SpeckleView instances.

Returns: SpeckleView[]

getWorldTree

getWorldTree(): WorldTree

Gets the WorldTree instance associated with the viewer.

Returns: WorldTree[]

hasExtension

hasExtension<T extends Extension>(type: Constructor<T>): boolean

Returns true if specified extension type exists, false otherwise

Returns: boolean

init

init(): Promise<void>

Initializes the viewer asynchronously and loads required assets.

Returns: Promise< void >

loadObject

loadObject(loader: SpeckleLoader, autoFit?: boolean): Promise<void>

Loads an object using the specified loader.

Parameters:

• loader: SpeckleLoader
• (optional) autoFit: boolean - Whether to automatically fit the view to the loaded object

Returns: Promise< void >

on

on<T extends ViewerEvent>(
  eventType: T,
  handler: (arg: ViewerEventPayload[T]) => void
): void

Subscribes handlers to ViewerEvents.

Parameters:

• eventType: The ViewerEvent the handler needs to register to
• handler: The event handler

Returns: void

query

query<T extends Query>(query: T): QueryArgsResultMap[T['operation']]

General purpose mechanism for getting spatial information from the viewer.

Parameters:

• query: The Query to run

Returns: QueryResult

requestRender

requestRender(flags?: number): void

Requests the viewer to render one or more frames.

Parameters:

• (optional) flags: UpdateFlags. If no flags are provided it defaults to UpdateFlags.RENDER.

Returns: void

resize

resize(): void

Resize the viewer manually. The dimensions will be inherited from the container.

Returns: void

screenshot

screenshot(): Promise<string>

Takes a snapshot of the current viewer camera view and returns it as a base64 encoded string.

Returns: A promise which resolves to a base64 encoded image.

setLightConfiguration

setLightConfiguration(config: LightConfiguration): void

Applies the provided LightConfiguration.

Returns: void

unloadAll

unloadAll(): Promise<void>

Unloads and disposes everything that’s currently loaded.

Returns: _Promise< void > _

unloadObject

unloadObject(url: string): Promise<void>

Unloads and disposes the specified resource associated with the provided url.

Parameters:

• url: The resource id to unload.

Returns: _Promise< void > _

Typedefs

LightConfiguration

interface LightConfiguration {
  enabled?: boolean
  castShadow?: boolean
  intensity?: number
  color?: number
  indirectLightIntensity?: number
  shadowcatcher?: boolean
}

• enabled: Enables direct lighting (sun).
• castShadow: Enables shadows.
• intensity: Direct light(sun) intensity.
• color: Direct light(sun) color.
• indirectLightIntensity: Indirect IBL intensity.
• shadowcatcher: Enables The Shadowcatcher. 🛸

ObjectLayers

enum ObjectLayers {
  STREAM_CONTENT_MESH = 10,
  STREAM_CONTENT_LINE = 11,
  STREAM_CONTENT_POINT = 12,
  STREAM_CONTENT_TEXT = 13,
  STREAM_CONTENT_POINT_CLOUD = 14,

  NONE = 0,
  STREAM_CONTENT = 1,
  PROPS = 2,
  SHADOWCATCHER = 3,
  OVERLAY = 4,
  MEASUREMENTS = 5
}

All the layers the viewer uses for rendering objects and props. Rendering order generally follows the order of layers values. The same layers are also used for raycasting, where they are all enabled by default except STREAM_CONTENT_POINT which is disabled

PropertyInfo

interface PropertyInfo {
  key: string
  objectCount: number
  type: 'number' | 'string' | 'boolean'
  path: string[]
  concatenatedPath: string
  name: string
}

• key: Property identifier, flattened (e.g., "level.name").
• objectCount: Total number of objects that have this property.
• type: The property value type - numeric, string, or boolean.
• path: Property path as an array (e.g., ["level", "name"]).
• concatenatedPath: Full property path, same as key.
• name: The property name (last segment of path, e.g., "name").

NumericPropertyInfo

interface NumericPropertyInfo extends PropertyInfo {
  type: 'number'
  min: number
  max: number
  valueGroups: Array<{ value: number; id: string }>
  passMin: number | null
  passMax: number | null
}

Extended property info for numeric properties, includes min/max range and all value-to-object mappings.

StringPropertyInfo

interface StringPropertyInfo extends PropertyInfo {
  type: 'string'
  valueGroups: Array<{ value: string; ids: string[] }>
}

Extended property info for string properties, includes value groups mapping string values to object IDs.

BooleanPropertyInfo

interface BooleanPropertyInfo extends PropertyInfo {
  type: 'boolean'
  valueGroups: Array<{ value: boolean; ids: string[] }>
}

Extended property info for boolean properties, includes value groups mapping boolean values to object IDs.

SelectionEvent

type SelectionEvent = {
  multiple: boolean
  event?: PointerEvent
  hits: Array<{
    node: TreeNode
    point: Vector3
  }>
}

Payload for ViewerEvent.ObjectClicked and ViewerEvent.ObjectDoubleClicked.

• multiple: Whether this is a multiple selection or not.
• event: The browser PointerEvent piggybacked.
• hits: The array of hits sorted by distance, where closest is first. node is the intersected TreeNode and point is it’s point of intersection.

SpeckleView

type SpeckleView = SpeckleObject & {
  origin: Vector3Like
  target: Vector3Like
  name?: string
  upDirection?: Vector3Like
  forwardDirection?: Vector3Like
}

• origin: The origin (location) of the view
• target: The point where the view is “looking at”.
• (optional) name: Human readable name
• (optional) upDirection: The view’s basis up
• (optional) name: The view’s basis forward

SunLightConfiguration

interface SunLightConfiguration extends LightConfiguration {
  elevation?: number
  azimuth?: number
  radius?: number
}

• elevation: Sun elevation in polar coordinates.
• azimuth: Sun azimuth in polar coordinates.
• radius: Sun distance from World center.

UpdateFlags

enum UpdateFlags {
  RENDER = 0b1,
  SHADOWS = 0b10,
  CLIPPING_PLANES = 0b100,
  RENDER_RESET = 0b1000
}

Specifies which rendering aspects need to be updated. UpdateFlags work by bit masking. So if you want multiple flags, you need to OR them.

UtilsInterface

interface Utils {
  screenToNDC(x: number, y: number, width?: number, height?: number): { x: number; y: number }
  NDCToScreen(x: number, y: number, width?: number, height?: number): { x: number; y: number }
}

Two utilities that help you move values form NDC to Screen space and back.

ViewerEvent

enum ViewerEvent {
  ObjectClicked = 'object-clicked',
  ObjectDoubleClicked = 'object-doubleclicked',
  LoadComplete = 'load-complete',
  UnloadComplete = 'unload-complete',
  UnloadAllComplete = 'unload-all-complete',
  FilteringStateSet = 'filtering-state-set',
  LightConfigUpdated = 'light-config-updated'
}

All the events the viewer can emit.

ViewerEventPayload

interface ViewerEventPayload {
  [ViewerEvent.ObjectClicked]: SelectionEvent | null
  [ViewerEvent.ObjectDoubleClicked]: SelectionEvent | null
  [ViewerEvent.LoadComplete]: string
  [ViewerEvent.UnloadComplete]: string
  [ViewerEvent.UnloadAllComplete]: void
  [ViewerEvent.FilteringStateSet]: FilteringState
  [ViewerEvent.LightConfigUpdated]: LightConfiguration
}

Mapping of viewer events to event handler argument types

ViewerParams

interface ViewerParams {
  showStats: boolean
  environmentSrc: Asset
  verbose: boolean
  restrictInputToCanvas: boolean
}

• showStats: Displays a stats panel.
• environmentSrc: The URL of the image used for indirect IBL.
• verbose: Enables viewer logs.
• restrictInputToCanvas: Restricts all input listening, especially keyboard, to the viewer’s rendering canvas

Asset

enum AssetType {
  TEXTURE_8BPP = 'png',
  TEXTURE_HDR = 'hdr',
  TEXTURE_EXR = 'exr',
  FONT_JSON = 'font-json'
}

interface Asset {
  id: string
  src: string
  type: AssetType
}

• id: Mandatory id of the asset.
• src: The URL of the asset. Supports inline base64 encoded assets
• type: AssetType
  For correct asset caching use need to use unique asset ids!

WorldClass

class World {
  readonly worldBox: Box3
  get worldSize(): Box3
  get worldOrigin(): Vector3

  expandWorld(box: Box3)
  reduceWorld(box: Box3)
  updateWorld()
  resetWorld()
  getRelativeOffset(offsetAmount: number = 0.001): number

Utility class for keeping track of the total dimensions of loaded objects. It’s mostly used for informative purposes

Constants

DefaultViewerParams

const DefaultViewerParams: ViewerParams = {
  showStats: false,
  verbose: false,
  environmentSrc: {
    id: 'defaultHDRI',
    src: defaultHdri,
    type: AssetType.TEXTURE_EXR
  },
  restrictInputToCanvas: false
}