> ## Documentation Index
> Fetch the complete documentation index at: https://docs.speckle.systems/llms.txt
> Use this file to discover all available pages before exploring further.

# Viewer

> The Speckle Viewer API

## Constructors

### constructor

```typescript theme={null}
new Viewer(container: HTMLElement, params: ViewerParams)
```

**Parameters**

* **container**: [*HTMLElement*](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement)
* **params**: [*ViewerParams*](#viewer)

**Returns**: [***Viewer***](#viewer)

## Accessors

### Utils

```typescript theme={null}
get Utils(): Utils
```

**Returns**: [***Utils***](#utilsinterface)

### World

```typescript theme={null}
get World(): World
```

**Returns**: [***World***](#worldclass)

## Methods

### cancelLoad

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
dispose(): void
```

Disposes the viewer instance

**Returns**: *void*

### getContainer

```typescript theme={null}
getContainer(): HTMLElement
```

Gets HTML container used at viewer initialisation

**Returns**: [***HTMLElement***](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement)

### getExtension

```typescript theme={null}
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

```typescript theme={null}
getObjectProperties(resourceURL?: string): Promise<PropertyInfo[]>
```

Returns [*PropertyInfo*](#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\[\]*](#propertyinfo)

### getRenderer

```typescript theme={null}
getRenderer(): SpeckleRenderer
```

Gets the [*SpeckleRenderer*](/developers/viewer/speckle-renderer-api) instance associated with the viewer.

**Returns**: [*SpeckleRenderer*](/developers/viewer/speckle-renderer-api)

### getViews

```typescript theme={null}
getViews(): SpeckleView[]
```

Gets all the current [*SpeckleView*](#speckleview) instances.

**Returns**: [*SpeckleView\[\]*](#speckleview)

### getWorldTree

```typescript theme={null}
getWorldTree(): WorldTree
```

Gets the [*WorldTree*](/developers/viewer/world-tree-api) instance associated with the viewer.

**Returns**: [*WorldTree\[\]*](/developers/viewer/world-tree-api)

### hasExtension

```typescript theme={null}
hasExtension<T extends Extension>(type: Constructor<T>): boolean
```

Returns `true` if specified extension type exists, `false` otherwise

**Returns**: *boolean*

### init

```typescript theme={null}
init(): Promise<void>
```

Initializes the viewer asynchronously and loads required assets.

**Returns**: *Promise\< void >*

### loadObject

```typescript theme={null}
loadObject(loader: SpeckleLoader, autoFit?: boolean): Promise<void>
```

Loads an object using the specified loader.

**Parameters**

* **loader**: [*SpeckleLoader*](/developers/viewer/loader-api)
* *(optional)* **autoFit**: *boolean* - Whether to automatically fit the view to the loaded object

**Returns**: *Promise\< void >*

### on

```typescript theme={null}
on<T extends ViewerEvent>(
  eventType: T,
  handler: (arg: ViewerEventPayload[T]) => void
): void
```

Subscribes handlers to [*ViewerEvent*](/developers/viewer/viewer-api#viewerevent)s.

**Parameters**

* **eventType**: The [*ViewerEvent*](/developers/viewer/viewer-api#viewerevent) the handler needs to register to
* **handler**: The event handler

**Returns**: *void*

### query

```typescript theme={null}
query<T extends Query>(query: T): QueryArgsResultMap[T['operation']]
```

General purpose mechanism for getting spatial information from the viewer.

**Parameters**

* **query**: The [*Query*](#query) to run

**Returns**: [*QueryResult*](#queryresult)

### requestRender

```typescript theme={null}
requestRender(flags?: number): void
```

Requests the viewer to render one or more frames.

**Parameters**

* *(optional)* **flags**: [*UpdateFlags*](/developers/viewer/viewer-api#updateflags). If no flags are provided it defaults to *UpdateFlags.RENDER*.

**Returns**: *void*

### resize

```typescript theme={null}
resize(): void
```

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

**Returns**: *void*

### screenshot

```typescript theme={null}
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

```typescript theme={null}
setLightConfiguration(config: LightConfiguration): void
```

Applies the provided [*LightConfiguration*](/developers/viewer/viewer-api#lightconfiguration).

**Returns**: *void*

### unloadAll

```typescript theme={null}
unloadAll(): Promise<void>
```

Unloads and disposes everything that's currently loaded.

**Returns**: \_Promise\< void > \_

### unloadObject

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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*](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent) piggybacked.
* **hits**: The array of hits sorted by distance, where closest is first. *node* is the intersected [*TreeNode*](/developers/viewer/world-tree-api#treenode) and *point* is it's point of intersection.

### SpeckleView

```typescript theme={null}
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

```typescript theme={null}
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*](/developers/viewer/viewer-api#worldclass) center.

### UpdateFlags

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
interface ViewerParams {
  showStats: boolean;
  environmentSrc: Asset;
  verbose: boolean;
  restrictInputToCanvas: boolean;
}
```

* **showStats**: Displays a [stats](https://github.com/mrdoob/stats.js) 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

```typescript theme={null}
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*

<Warning>
  For correct asset caching use need to use unique asset ids!
</Warning>

### WorldClass

```typescript theme={null}
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

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