Class: xViewer

xViewer

This is the main and the only class you need to load and render IFC models in wexBIM format. This viewer is part of xBIM toolkit which can be used to create wexBIM files from IFC, ifcZIP and ifcXML. WexBIM files are highly optimalized for transmition over internet and rendering performance. Viewer uses WebGL technology for hardware accelerated 3D rendering and SVG for certain kinds of user interaction. This means that it won't work with obsolete and non-standard-compliant browsers like IE10 and less.

Constructor

new xViewer(canvas)

This is constructor of the xBIM Viewer. It gets HTMLCanvasElement or string ID as an argument. Viewer will than be initialized in the context of specified canvas. Any other argument will throw exception.

Parameters:
Name Type Description
canvas string | HTMLCanvasElement

string ID of the canvas or HTML canvas element.

Members

background :Array.<Number>

Array of four integers between 0 and 255 representing RGBA colour components. This defines background colour of the viewer. You can change this value at any time with instant efect.

Type:
  • Array.<Number>

camera :string

Type of camera to be used. Available values are 'perspective' and 'orthogonal' You can change this value at any time with instant efect.

Type:
  • string

clippingPlane :Array.<Number>

Clipping plane [a, b, c, d] defined as normal equation of the plane ax + by + cz + d = 0. [0,0,0,0] is for no clipping plane.

Type:
  • Array.<Number>

highlightingColour :Array.<Number>

Array of four integers between 0 and 255 representing RGBA colour components. This defines colour for highlighted elements. You can change this value at any time with instant efect.

Type:
  • Array.<Number>

lightA :Array.<Number>

Array of four floats. It represents Light A's position XYZ and intensity I as [X, Y, Z, I]. Intensity should be in range 0.0 - 1.0.

Type:
  • Array.<Number>

lightB :Array.<Number>

Array of four floats. It represents Light B's position XYZ and intensity I as [X, Y, Z, I]. Intensity should be in range 0.0 - 1.0.

Type:
  • Array.<Number>

Switch between different navidation modes for left mouse button. Allowed values: 'pan', 'zoom', 'orbit' (or 'fixed-orbit') , 'free-orbit' and 'none'. Default value is 'orbit';

Type:
  • String

orthogonalCamera :OrthogonalCamera

This is a structure that holds settings of orthogonal camera. You can modify this but it is not necessary because sensible values are defined when geometry model is loaded with load() method. If you want to change these values you have to do it after geometry is loaded.

Type:

perspectiveCamera :PerspectiveCamera

This is a structure that holds settings of perspective camera.

Type:

renderingMode :String

Switch between different rendering modes. Allowed values: 'normal', 'x-ray'. Default value is 'normal'; Only products with state set to state.HIGHLIGHTED or xState.XRAYVISIBLE will be rendered highlighted or in a normal colours. All other products will be rendered semitransparent and singlesided.

Type:
  • String

Methods

(static) check() → {Prerequisities}

This is a static function which should always be called before xViewer is instantiated. It will check all prerequisities of the viewer and will report all issues. If Prerequisities.errors contain any messages viewer won't work. If Prerequisities.warnings contain any messages it will work but some functions may be restricted or may not work or it may have poor erformance.

Returns:
Type
Prerequisities

addPlugin(plugin)

Adds plugin to the viewer. Plugins can implement certain methods which get called in certain moments in time like before draw, after draw etc. This makes it possible to implement functionality tightly integrated into xViewer like navigation cube or others.

Parameters:
Name Type Description
plugin object

plug-in object

clip(pointopt, normalopt)

Use this method to clip the model. If you call the function with no arguments interactive clipping will start. This is based on SVG overlay so SVG support is necessary for it. But as WebGL is more advanced technology than SVG it is sound assumption that it is present in the browser. Use xViewer.check() to make sure it is supported at the very beginning of using of xViewer. Use unclip() method to unset clipping plane.

Parameters:
Name Type Attributes Description
point Array.<Number> <optional>

point in clipping plane

normal Array.<Number> <optional>

normal pointing to the halfspace which will be hidden

Fires:

defineStyle(index, colour)

Use this function to define up to 224 optional styles which you can use to change appearance of products and types if you pass the index specified in this function to setState() function.

Parameters:
Name Type Description
index Number

Index of the style to be defined. This has to be in range 0 - 224. Index can than be passed to change appearance of the products in model

colour Array.<Number>

Array of four numbers in range 0 - 255 representing RGBA colour. If there are less or more numbers exception is thrown.

draw()

This is a static draw method. You can use it if you just want to render model once with no navigation and interaction. If you want interactive model call start() method. Frame event is fired when draw call is finished.

Fires:

getCameraPosition()

Use this method get actual camera position.

getClip() → {Array.<Array.<Number>>}

This method can be used to get parameter of the current clipping plane. If no clipping plane is active this returns [[0,0,0],[0,0,0]];

Returns:

Point and normal defining current clipping plane

Type
Array.<Array.<Number>>

getModelState(id) → {Array}

Gets complete model state and style. Resulting object can be used to restore the state later on.

Parameters:
Name Type Description
id Number

Model ID which you can get from loaded event.

Returns:
  • Array representing model state in compact form suitable for serialization
Type
Array

getProductType(prodID) → {Number}

Parameters:
Name Type Description
prodID Number

Product ID. You can get this value either from semantic structure of the model or by listening to pick event.

Returns:

Product type ID. This is either null if no type is identified or one of type ids.

Type
Number

getState(id)

Use this function to get state of the products in the model. You can compare result of this function with one of values from xState enumeration. 0xFF is the default value.

Parameters:
Name Type Description
id Number

Id of the product. You would typicaly get the id from pick event or similar event.

getStyle(id)

Use this function to get overriding colour style of the products in the model. The number you get is the index of your custom colour which you have defined in defineStyle() function. 0xFF is the default value.

Parameters:
Name Type Description
id Number

Id of the product. You would typicaly get the id from pick event or similar event.

load(model, tag)

This method is used to load model data into viewer. Model has to be either URL to wexBIM file or Blob or File representing wexBIM file binary data. Any other type of argument will throw an exception. Region extend is determined based on the region of the model Default view if 'front'. If you want to define different view you have to set it up in handler of loaded event.
You can load more than one model if they occupy the same space, use the same scale and have unique product IDs. Duplicated IDs won't affect visualization itself but would cause unexpected user interaction (picking, zooming, ...)

Parameters:
Name Type Description
model String | Blob | File

Model has to be either URL to wexBIM file or Blob or File representing wexBIM file binary data.

tag Any

[optional] - Tag to be used to identify the model in loaded event.

Fires:

off(eventName, callback)

Use this method to unregisted handlers from events. You can add event handlers by calling the on() method.

Parameters:
Name Type Description
eventName String

Name of the event

callback Object

Handler to be removed

on(eventName, callback)

Use this method to register to events of the viewer like pick, mouseDown, loaded and others. You can define arbitrary number of event handlers for any event. You can remove handler by calling off() method.

Parameters:
Name Type Description
eventName String

Name of the event you would like to listen to.

callback Object

Callback handler of the event which will consume arguments and perform any custom action.

removePlugin(plugin)

Removes plugin from the viewer. Plugins can implement certain methods which get called in certain moments in time like before draw, after draw etc. This makes it possible to implement functionality tightly integrated into xViewer like navigation cube or others.

Parameters:
Name Type Description
plugin object

plug-in object

resetStates(hideSpacesopt)

Use this function to reset state of all products to 'UNDEFINED' which means visible and not highlighted. You can use optional hideSpaces parameter if you also want to show spaces. They will be hidden by default.

Parameters:
Name Type Attributes Default Description
hideSpaces Bool <optional>
true

Default state is UNDEFINED which would also show spaces. That is often not desired so it can be excluded with this parameter.

resetStyles()

Use this function to reset appearance of all products to their default styles.

restoreModelState(id, state)

Restores model state from the data previously captured with getModelState() function

Parameters:
Name Type Description
id Number

ID of the model

state Array

State of the model as obtained from getModelState() function

set(settings)

This method can be used for batch setting of viewer members. It doesn't check validity of the input.

Parameters:
Name Type Description
settings Object

Object containing key - value pairs

setCameraPosition(coordinates)

Use this method to set position of camera. Use it after setCameraTarget() to get desired result.

Parameters:
Name Type Description
coordinates Array.<Number>

3D coordinates of the camera in WCS

setCameraTarget(prodId) → {Bool}

This method sets navigation origin to the centroid of specified product's bounding box or to the center of model if no product ID is specified. This method doesn't affect the view itself but it has an impact on navigation. Navigation origin is used as a center for orbiting and it is used if you call functions like show() or {@link xViewer#zoomTo zoomTo()}.

Parameters:
Name Type Description
prodId Number

[optional] Product ID. You can get ID either from semantic structure of the model or from pick event.

Returns:

True if the target exists and is set, False otherwise

Type
Bool

setState(state, target)

You can use this function to change state of products in the model. State has to have one of values from xState enumeration. Target is either enumeration from xProductType or array of product IDs. If you specify type it will effect all elements of the type.

Parameters:
Name Type Description
state Number

One of xState enumeration values.

target Array.<Number> | Number

Target of the change. It can either be array of product IDs or product type from xProductType.

setStyle(style, target)

Use this method for restyling of the model. This doesn't change the default appearance of the products so you can think about it as an overlay. You can remove the overlay if you set the style to xState.UNSTYLED value. You can combine restyling and hiding in this way. Use defineStyle() to define styling first.

Parameters:
Name Type Description
style

style defined in defineStyle() method

target Array.<Number> | Number

Target of the change. It can either be array of product IDs or product type from xProductType.

show(type)

Use this function to show default views.

Parameters:
Name Type Description
type String

Type of view. Allowed values are 'top', 'bottom', 'front', 'back', 'left', 'right'. Directions of this views are defined by the coordinate system. Target and distance are defined by setCameraTarget() method to certain product ID or to the model extent if setCameraTarget() is called with no arguments.

start(id)

Use this function to start animation of the model. If you start animation before geometry is loaded it will wait for content to render it. This function is bound to browser framerate of the screen so it will stop consuming any resources if you switch to another tab.

Parameters:
Name Type Description
id Number

[optional] - Optional ID of the model to be stopped. You can get this ID from loaded event.

stop(id)

Use this function to stop animation of the model. User will still be able to see the latest state of the model. You can switch animation of the model on again by calling start().

Parameters:
Name Type Description
id Number

[optional] - Optional ID of the model to be stopped. You can get this ID from loaded event.

stopClipping()

This method is only active when interactive clipping is active. It stops interactive clipping operation.

unclip()

This method will cancel any clipping plane if it is defined. Use clip() method to define clipping by point and normal of the plane or interactively if you call it with no arguments.

Fires:

unload(modelId)

Unloads model from the GPU. This action is not reversable.

Parameters:
Name Type Description
modelId Number

ID of the model which you can get from loaded event.

zoomTo(idopt) → {Bool}

Use this method to zoom to specified element. If you don't specify a product ID it will zoom to full extent.

Parameters:
Name Type Attributes Description
id Number <optional>

Product ID

Returns:

True if target exists and zoom was successfull, False otherwise

Type
Bool

Events

clipped

Occurs when model is clipped. This event has empty object.

Type:
  • object

dblclick

Occurs when user double clicks on model.

Type:
  • object
Parameters:
Name Type Description
id Number

product ID of the element or null if there wasn't any product under mouse

error

Occurs when viewer encounters error. You should listen to this because it might also report asynchronous errors which you would miss otherwise.

Type:
  • object
Parameters:
Name Type Description
message string

Error message

fps

Occurs after every 30th frame in animation. Use this event if you want to report FPS to the user. It might also be interesting performance measure.

Type:
  • Number

frame

Occurs after every frame in animation. Don't do anything heavy weighted in here as it will happen about 60 times in a second all the time.

Type:
  • object

loaded

Occurs when geometry model is loaded into the viewer. This event returns object containing ID of the model. This ID can later be used to unload or temporarily stop the model.

Type:
  • object
Parameters:
Name Type Description
id Number

model ID

tag Any

tag which was passed to 'xViewer.load()' function

mouseDown

Occurs when mousedown event happens on underlying canvas.

Type:
  • object
Parameters:
Name Type Description
id Number

product ID of the element or null if there wasn't any product under mouse

pick

Occurs when user click on model.

Type:
  • object
Parameters:
Name Type Description
id Number

product ID of the element or null if there wasn't any product under mouse

unclipped

Occurs when clipping of the model is dismissed. This event has empty object.

Type:
  • object