# Viewer

Constructors

constructor

Accessors

Utils	World

Methods

cancelLoad	createExtension	dispose	getContainer
getExtension	getObjectProperties	getRenderer	getViews
getWorldTree	hasExtension	init	loadObject
on	query	requestRender	resize
screenshot	setLightConfiguration	unloadAll	unloadObject

Typedefs

Asset	LightConfiguration	ObjectLayers	PropertyInfo
SelectionEvent	SpeckleView	SunLightConfiguration	UpdateFlags
Utils	ViewerEvent	ViewerEventPayload	ViewerParams
World

Constructors

# constructor

new Viewer(container: HTMLElement, params: ViewerParams)

Parameters

container: HTMLElement (opens new window)
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 (opens new window)

# 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, bypassCache?: boolean): Promise<PropertyInfo[]>

Goes through all objects and builds PropertyInfo objects asynchronously.

WARNING

When executing for a very large number of objects, this method can take long to finish

Parameters

resourceURL: The id of the node where to start building properties.
(optional) bypassCache: Enabled the use of the property cache. Default false

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: Loader, zoomToObject?: boolean): Promise<void>

Loads objects asynchronously using a Loader.

Parameters

loader: The Loader instance used in loading.
(optional) zoomToObject: Enabled zooming in on the loaded object after loading finishes. Default true

Returns: Promise< void >

# on

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

1
2
3
4

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;
}

1
2
3
4
5
6
7
8

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,
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

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";
}

1
2
3
4
5

key: Property identifier, flattened.
objectCount: Total number of objects that have this property.
type: If the property is numeric or string based.

# SelectionEvent

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

1
2
3
4
5
6
7
8

Payload for ViewerEvent.ObjectClicked and ViewerEvent.ObjectDoubleClicked.

multiple: Whether this is a multiple selection or not.
event: The browser PointerEvent (opens new window) 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 = {
  name: string;
  id: string;
  view: Record<string, unknown>;
};

1
2
3
4
5

name: Human readable name.
id: View's speckle id.
view: View's associated speckle data .

# SunLightConfiguration

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

1
2
3
4
5

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

# UpdateFlags

enum UpdateFlags {
  RENDER = 1,
  SHADOWS = 2,
}

1
2
3
4

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 };
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

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

# ViewerEvent

enum ViewerEvent {
  ObjectClicked = "object-clicked",
  ObjectDoubleClicked = "object-doubleclicked",
  DownloadComplete = "download-complete",
  LoadComplete = "load-complete",
  LoadProgress = "load-progress",
  UnloadComplete = "unload-complete",
  LoadCancelled = "load-cancelled",
  UnloadAllComplete = "unload-all-complete",
  Busy = "busy",
  FilteringStateSet = "filtering-state-set",
  LightConfigUpdated = "light-config-updated",
}

1
2
3
4
5
6
7
8
9
10
11
12
13

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.Busy]: boolean
  [ViewerEvent.FilteringStateSet]: FilteringState
  [ViewerEvent.LightConfigUpdated]: LightConfiguration
}

1
2
3
4
5
6
7
8
9
10

Mapping of viewer events to event handler argument types

# ViewerParams

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

1
2
3
4
5

showStats: Displays a stats (opens new window) panel.
environmentSrc: The URL of the image used for indirect IBL.
verbose: Enables viewer logs.

# Asset

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

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

1
2
3
4
5
6
7
8
9
10
11
12

id: Mandatory id of the asset.
src: The URL of the asset. Supports inline base64 encoded assets
type: AssetType

WARNING

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

1
2
3
4
5
6
7
8
9
10

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

← TopLevelAccelerationStructure WorldTree →