# Viewer
# Constructors
constructor |
---|
# Accessors
Utils | World |
---|
# Methods
# 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
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;
}
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,
}
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";
}
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;
}>;
};
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>;
};
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;
}
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 = 0b1,
SHADOWS = 0b10,
CLIPPING_PLANES = 0b100,
RENDER_RESET = 0b1000
}
2
3
4
5
6
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 };
}
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",
}
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
}
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;
}
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
}
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
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