Reference Source
public class | source

Viewer

The 3D Viewer at the heart of the xeokit SDK.

Constructor Summary

Public Constructor
public

Member Summary

Public Members
public

The Viewer's Camera. This is also found on Scene#camera.

public

The Viewer's CameraControl, which controls the Scene's Camera with mouse, touch and keyboard input.

public

The Viewer's CameraFlightAnimation, which is used to fly the Scene's Camera to given targets.

public get

capabilities: {astcSupported: boolean, etc1Supported: boolean, pvrtcSupported: boolean, etc2Supported: boolean, dxtSupported: boolean, bptcSupported: boolean}: *

Returns the capabilities of this Viewer.

public

The Viewer's ID.

public
this member was deprecated.

The Viewer's current language setting.

public

The viewer's locale service.

This is configured via the Viewer's constructor.

since 2.0
public

Metadata about the Scene and the models and objects within it.

public

The Viewer's Scene.

Method Summary

Public Methods
public

Enter snapshot mode.

public

Destroys this Viewer.

public

Exits snapshot mode.

public

error(msg: String)

Logs an error message to the JavaScript developer console, prefixed with the ID of this Viewer.

public

fire(event: String, value: Object)

Fires an event at this Viewer.

public

getSnapshot(params: *): String

Gets a snapshot of this Viewer's Scene as a Base64-encoded image.

Usage:

const imageData = viewer.getSnapshot({
   width: 500,
   height: 500,
   format: "png"
});
public

async getSnapshotWithPlugins(params: *): Promise

Gets a snapshot of this Viewer's Scene as a Base64-encoded image which includes the HTML elements created by various plugins.

The snapshot image is composed of an image of the viewer canvas, overlaid with an image of the HTML container element belonging to each installed Viewer plugin. Each container element is only rendered once, so it's OK for plugins to share the same container.

public

log(msg: String)

Logs a message to the JavaScript developer console, prefixed with the ID of this Viewer.

public

off(event: *)

Unsubscribes from an event fired at this Viewer.

public

on(event: String, callback: Function)

Subscribes to an event fired at this Viewer.

Public Constructors

public constructor(cfg: Object) source

Params:

NameTypeAttributeDescription
cfg Object

Viewer configuration.

cfg.id String
  • optional

Optional ID for this Viewer, defaults to the ID of Viewer#scene, which xeokit automatically generates.

cfg.canvasId String
  • optional

ID of an existing HTML canvas for the Viewer#scene - either this or canvasElement is mandatory. When both values are given, the element reference is always preferred to the ID.

cfg.canvasElement HTMLCanvasElement
  • optional

Reference of an existing HTML canvas for the Viewer#scene - either this or canvasId is mandatory. When both values are given, the element reference is always preferred to the ID.

cfg.keyboardEventsElement HTMLElement
  • optional

Optional reference to HTML element on which key events should be handled. Defaults to the HTML Document.

cfg.spinnerElementId String
  • optional

ID of existing HTML element to show the Spinner - internally creates a default element automatically if this is omitted.

cfg.passes Number
  • optional
  • default: 1

The number of times the Viewer#scene renders per frame.

cfg.clearEachPass Boolean
  • optional
  • default: false

When doing multiple passes per frame, specifies if to clear the canvas before each pass (true) or just before the first pass (false).

cfg.preserveDrawingBuffer Boolean
  • optional
  • default: true

Whether or not to preserve the WebGL drawing buffer. This needs to be true for Viewer#getSnapshot to work.

cfg.transparent Boolean
  • optional
  • default: true

Whether or not the canvas is transparent.

cfg.premultipliedAlpha Boolean
  • optional
  • default: false

Whether or not you want alpha composition with premultiplied alpha. Highlighting and selection works best when this is false.

cfg.gammaInput Boolean
  • optional
  • default: true

When true, expects that all textures and colors are premultiplied gamma.

cfg.gammaOutput Boolean
  • optional
  • default: false

Whether or not to render with pre-multiplied gama.

cfg.gammaFactor Number
  • optional
  • default: 2.2

The gamma factor to use when rendering with pre-multiplied gamma.

cfg.backgroundColor Number[]
  • optional
  • default: [1,1,1]

Sets the canvas background color to use when transparent is false.

cfg.backgroundColorFromAmbientLight Boolean
  • optional
  • default: true

When transparent is false, set this true to derive the canvas background color from AmbientLight#color, or false to set the canvas background to backgroundColor.

cfg.units String
  • optional
  • default: "meters"

The measurement unit type. Accepted values are "meters", "metres", , "centimeters", "centimetres", "millimeters", "millimetres", "yards", "feet" and "inches".

cfg.scale Number
  • optional
  • default: 1

The number of Real-space units in each World-space coordinate system unit.

cfg.origin Number[]
  • optional
  • default: [0,0,0]

The Real-space 3D origin, in current measurement units, at which the World-space coordinate origin [0,0,0] sits.

cfg.saoEnabled Boolean
  • optional
  • default: false

Whether to enable Scalable Ambient Obscurance (SAO) effect. See SAO for more info.

cfg.antialias Boolean
  • optional
  • default: true

Whether to enable anti-aliasing.

cfg.alphaDepthMask Boolean
  • optional
  • default: true

Whether writing into the depth buffer is enabled or disabled when rendering transparent objects.

cfg.entityOffsetsEnabled Boolean
  • optional
  • default: false

Whether to enable Entity#offset. For best performance, only set this true when you need to use Entity#offset.

cfg.pickSurfacePrecisionEnabled Boolean
  • optional
  • default: false

Whether to enable full-precision accuracy when surface picking with Scene#pick. Note that when true, this configuration will increase the amount of browser memory used by the Viewer. The pickSurfacePrecision option for Scene#pick only works if this is set true.

cfg.logarithmicDepthBufferEnabled Boolean
  • optional
  • default: false

Whether to enable logarithmic depth buffer. When this is true, you can set huge values for Perspective#far and Ortho#far, to push the far clipping plane back so that it does not clip huge models.

cfg.colorTextureEnabled Boolean
  • optional
  • default: true

Whether to enable base color texture rendering.

cfg.pbrEnabled Boolean
  • optional
  • default: false

Whether to enable physically-based rendering.

cfg.localeService LocaleService
  • optional
  • default: null

Optional locale-based translation service.

cfg.dtxEnabled Boolean
  • optional
  • default: false

Whether to enable data texture-based (DTX) scene representation within the Viewer. When this is true, the Viewer will use data textures to store geometry on the GPU for triangle meshes that don't have textures. This gives a much lower memory footprint for these types of model element. This mode may not perform well on low-end GPUs that are optimized to use textures to hold geometry data. Works great on most medium/high-end GPUs found in desktop computers, including the nVIDIA and Intel HD chipsets. Set this false to use the default vertex buffer object (VBO) mode for storing geometry, which is the standard technique used in most graphics engines, and will work adequately on most low-end GPUs.

cfg.numCachedSectionPlanes number
  • optional
  • default: 0

Enhances the efficiency of SectionPlane creation by proactively allocating Viewer resources for a specified quantity of SectionPlanes. Introducing this parameter streamlines the initial creation speed of SectionPlanes, particularly up to the designated quantity. This parameter internally configures renderer logic for the specified number of SectionPlanes, eliminating the need for setting up logic with each SectionPlane creation and thereby enhancing responsiveness. It is important to consider that each SectionPlane impacts rendering performance, so it is recommended to set this value to a quantity that aligns with your expected usage.

Throw:

String

Throws an exception when both canvasId or canvasElement are missing or they aren't pointing to a valid HTMLCanvasElement.

Public Members

public camera: Camera source

The Viewer's Camera. This is also found on Scene#camera.

Properties:

NameTypeAttributeDescription
camera *

public cameraControl: CameraControl source

The Viewer's CameraControl, which controls the Scene's Camera with mouse, touch and keyboard input.

Properties:

NameTypeAttributeDescription
cameraControl *

public cameraFlight: CameraFlightAnimation source

The Viewer's CameraFlightAnimation, which is used to fly the Scene's Camera to given targets.

Properties:

NameTypeAttributeDescription
cameraFlight *

public get capabilities: {astcSupported: boolean, etc1Supported: boolean, pvrtcSupported: boolean, etc2Supported: boolean, dxtSupported: boolean, bptcSupported: boolean}: * source

Returns the capabilities of this Viewer.

Return:

{astcSupported: boolean, etc1Supported: boolean, pvrtcSupported: boolean, etc2Supported: boolean, dxtSupported: boolean, bptcSupported: boolean}

public id: String | Number source

The Viewer's ID.

Properties:

NameTypeAttributeDescription
id *

public language: String source

this member was deprecated.

The Viewer's current language setting.

Properties:

NameTypeAttributeDescription
language *

public localeService: LocaleService since 2.0 source

The viewer's locale service.

This is configured via the Viewer's constructor.

By default, this service will be an instance of LocaleService, which will just return null translations for all given strings and phrases.

Properties:

NameTypeAttributeDescription
localeService *

public metaScene: MetaScene source

Metadata about the Scene and the models and objects within it.

Properties:

NameTypeAttributeDescription
metaScene *

public scene: Scene source

The Viewer's Scene.

Properties:

NameTypeAttributeDescription
scene *

Public Methods

public beginSnapshot() source

Enter snapshot mode.

Switches rendering to a hidden snapshot canvas.

Exit snapshot mode using Viewer#endSnapshot.

public destroy() source

Destroys this Viewer.

public endSnapshot() source

Exits snapshot mode.

Switches rendering back to the main canvas.

public error(msg: String) source

Logs an error message to the JavaScript developer console, prefixed with the ID of this Viewer.

Params:

NameTypeAttributeDescription
msg String

The error message

public fire(event: String, value: Object) source

Fires an event at this Viewer.

Params:

NameTypeAttributeDescription
event String

Event name

value Object

Event parameters

public getSnapshot(params: *): String source

Gets a snapshot of this Viewer's Scene as a Base64-encoded image.

Usage:

const imageData = viewer.getSnapshot({
   width: 500,
   height: 500,
   format: "png"
});

Params:

NameTypeAttributeDescription
params *
  • optional

Capture options.

params.width Number
  • optional

Desired width of result in pixels - defaults to width of canvas.

params.height Number
  • optional

Desired height of result in pixels - defaults to height of canvas.

params.format String
  • optional
  • default: "jpeg"

Desired format; "jpeg", "png" or "bmp".

params.includeGizmos Boolean
  • optional
  • default: false

When true, will include gizmos like SectionPlane in the snapshot.

Return:

String

String-encoded image data URI.

public async getSnapshotWithPlugins(params: *): Promise source

Gets a snapshot of this Viewer's Scene as a Base64-encoded image which includes the HTML elements created by various plugins.

The snapshot image is composed of an image of the viewer canvas, overlaid with an image of the HTML container element belonging to each installed Viewer plugin. Each container element is only rendered once, so it's OK for plugins to share the same container.

Usage:

viewer.getSnapshotWithPlugins({
   width: 500,
   height: 500,
   format: "png"
}).then((imageData)=>{

});

Params:

NameTypeAttributeDescription
params *
  • optional

Capture options.

params.width Number
  • optional

Desired width of result in pixels - defaults to width of canvas.

params.height Number
  • optional

Desired height of result in pixels - defaults to height of canvas.

params.format String
  • optional
  • default: "jpeg"

Desired format; "jpeg", "png" or "bmp".

params.includeGizmos Boolean
  • optional
  • default: false

When true, will include gizmos like SectionPlane in the snapshot.

Return:

Promise

Promise which returns a string-encoded image data URI.

public log(msg: String) source

Logs a message to the JavaScript developer console, prefixed with the ID of this Viewer.

Params:

NameTypeAttributeDescription
msg String

The message

public off(event: *) source

Unsubscribes from an event fired at this Viewer.

Params:

NameTypeAttributeDescription
event *

public on(event: String, callback: Function) source

Subscribes to an event fired at this Viewer.

Params:

NameTypeAttributeDescription
event String

The event

callback Function

Callback fired on the event