NAV Navigation
jQuery

Viewer 3D API

Deprecation notice

We are unifying all our APIs under one host, api.catenda.com. We'll be updating the docs in the coming days to reflect the new URL mappings. Existing URLs pointing to https://api.bimsync.com or https://opencde.bimsync.com will continue to work until the sunset date of June 1st 2025.

The old -> new mappings by API are as follows:

Getting started

The Viewer 3D API allows developers to embed the Bimsync 3D viewer in their applications.

Release channels

We use release channels to slowly roll out updates to the Viewer 3D API.

Which channel should I use?

How to specify channel

You can select the channel to use by passing a query parameter to the URL when loading the Viewer 3D API:

<script src="https://api.catenda.com/js/v1/viewer3d"></script>

or

<script src="https://api.catenda.com/js/v1/viewer3d?release=stable"></script>

<script src="https://api.catenda.com/js/v1/viewer3d?release=beta"></script>

<script src="https://api.catenda.com/js/v1/viewer3d?release=dev"></script>

Dependencies

The Viewer 3D API requires jQuery 1.x to run.

Getting started

By using the Data API you can display models without writing any JavaScript. To have full control of the viewer, you need to use JavaScript and the jQuery API.

Data API

The Data API can be used to embed Bimsync models on web pages that are generated server side.

  1. Create a Viewer3D token using the Bimsync REST API on your backend service.

  2. Add the Bimsync Viewer3D script to the web page.

<script src="https://api.catenda.com/js/v1/viewer3d"></script>
  1. Add a <div> element to the web page. Set the attribute data-viewer to webgl and the attribute data-url to the token URL.
<div data-viewer="webgl" data-url="https://api.catenda.com/v2/projects/978720ca.../viewer3d/data?token=8958f669f..."></div>

To enable the Viewer Widget API, add the data attribute data-ui to the viewer element. See the Viewer Widget API documentation for more info.

jQuery API

Using the jQuery API with Javascript lets you have full control of the viewer.

  1. Add the Bimsync Viewer3D script to the web page.
<script src="https://api.catenda.com/js/v1/viewer3d"></script>
  1. Add a <div> element to the web page. Give the element an id attribute.
<div id="viewer"></div>
  1. Add a <script> element to initialize the viewer. Use a selector to find the div element and initialize the viewer by calling the jQuery plugin function viewer.
<script>
    bimsync.load();
    bimsync.setOnLoadCallback(function () {
      $('#viewer').viewer();
    });
</script>
  1. Load models into the viewer.

See the Viewer Widget API documentation on how to enable the Viewer Widget API.

Loading models

The Viewer3D API supports two types of models, BIM models and point clouds. BIM models are created from IFC files, while point clouds are created from E57 or LAS files. The file is automatically processed into a format supported by the viewer when it is uploaded to the Model section or Document section in Bimsync.

Loading Bimsync Models

To load BIM models from the Models section in Bimsync you use the loadModelsFromToken Viewer3D API method. loadModelsFromToken allows you to load multiple models in one API call.

  1. Create a Viewer3D token using the Bimsync REST API.

  2. Pass the url field from the JSON response to loadModelsFromToken.

$('#viewer').viewer('loadModelsFromToken', 'https://api.catenda.com/v2/projects/978720ca.../viewer3d/data?token=8958f669f...');

See loadModelsFromToken for more information.

Loading Bimsync Documents

To load BIM models or point clouds from the Documents section in Bimsync you use the loadModel Viewer3D API method.

  1. Locate the document using the Bimsync REST API.

The JSON response should contain a document field with an additionalFormats field. Ensure that additionalFormats contains an entry with mediaType set to either application/vnd.bimsync.scene for BIM models, or application/vnd.bimsync.pointcloud for point clouds.

  1. Create a download token using the Bimsync REST API.

Set the format query parameter to either application/vnd.bimsync.scene for BIM models, or application/vnd.bimsync.pointcloud for point clouds.

  1. Pass the url field from the JSON response to loadModel.

Set the modelType option to either bim for BIM models, or point-cloud for point clouds.

$('#viewer').viewer('loadModel', 'https://api.catenda.com/v2/download?token=8958f669f...', {
  modelType: 'bim'
});

$('#viewer').viewer('loadModel', 'https://api.catenda.com/v2/download?token=8958f669f...', {
  modelType: 'point-cloud' 
});

See loadModel for more information.

Options

var options = {
    defaultColor: String or Number,                   // Any valid CSS color, default: '#101010'
    selectedColor: String or Number,                  // Any valid CSS color, default: '#a7f555'
    translucentOpacity: Number,                       // Default: 0.05
    fieldOfView: Number,                              // Number in degrees, default: 60
    enableTouch: Boolean,                             // Default: false
    navigationOrbitSphereColor: String or Number,     // Any valid CSS color, default: '#b1d059'
    enableClippingPlaneWidget: Boolean,               // Default: false
    activeClippingPlaneBorderColor: String or Number, // Any valid CSS color, default: '#a7f555',
    textRenderMode: 'canvas' or 'dom'                 // Default: 'canvas'
}

Setting options when using JavaScript initialization:

$('#viewer-container').viewer({
    defaultColor: 'red',
    selectedColor: 'blue',
    translucentOpacity: 0.05,
    enableTouch: true,
    enableClippingPlaneWidget: true,
    textRenderMode: 'dom'
});
$('#viewer-container').viewer('loadUrl', 'https://api.catenda.com/v2/projects/978720ca.../viewer3d/data?token=8958f669f...');

Setting options when using data attribute initialization:

<div data-viewer="webgl" data-default-color="#22ff22" data-enable-touch="true" data-translucent-opacity="0.1"
     data-url="https://api.catenda.com/v2/projects/978720ca.../viewer3d/data?token=8958f669f...">
</div>

All options can be set using data attributes on the viewer element, or passed as an object when initializing with JavaScript.

defaultColor

The default color for objects that has no color specified.

selectedColor

The color of selected objects.

translucentOpacity

The opacity of translucent objects.

fieldOfView

The camera field of view.

enableTouch

Enables touch support.

enableClippingPlaneWidget

Enables a clipping plane widget that makes viewing and selecting clipping planes easier. The widget will only appear when there exists at least one clipping plane.

textRenderMode

Set text render mode. In canvas mode, text is rendered as a texture on a sprite in the viewer canvas. In dom mode, text is rendered using HTML elements. dom mode produces a higher quality text.

canvas mode is the default mode for backward compatibility.

Methods

All methods are invoked by calling the method viewer on the result of a jQuery/$ function call. The first argument to the viewer method must be the method name.

Chaining and callbacks

In the Bimsync Viewer 3D API all methods are chainable. This design decision causes the API to be rather callback heavy. A pattern being used is that the same method can be used to both set and get a value from the viewer. The value will then be returned using a callback function. When calling callbacks, the this value will be set to the viewer's DOM element.

Example

Given a viewer initialized using the DOM API:

<div class="viewer" data-viewer="webgl" data-url="https://api.catenda.com/v2/projects/978720ca.../viewer3d/data?token=8958f669f..."></div>

The following chained method calls will isolate object id '1':

$('.viewer').viewer('hideAll').viewer('show', '1')

The following takes a screenshot of an isolated object and resets the view:

$('.viewer').viewer('hideAll')
            .viewer('show', '1')
            .viewer('screenshot', function(screenshot) {
    $('img').attr('src', screenshot);
    $(this).viewer('showAll');
});

dispose

Disposes the Viewer3D instance and releases all associated WebGL resources.

Parameters: None

show

Makes a hidden or translucent object visible.

Parameters:

showAll

Makes all objects visible.

Parameters: None

hide

Makes object hidden.

Parameters:

hideAll

Hides all objects.

Parameters: None

translucent

Makes object translucent.

Parameters:

translucentAll

Make all objects translucent.

Parameters: None

opaque

Makes object opaque.

Parameters:

opaqueAll

Make all objects opaque.

Parameters: None

select

Marks object as selected.

Parameters:

deselect

Removes object from selected set.

Parameters:

deselectAll

Clears selected set.

Parameters: None

loadModelsFromToken

Example:

$('.viewer').viewer('loadModelsFromToken', 'https://api.catenda.com/v2/projects/978720ca.../viewer3d/data?token=8958f669f...');

// Query - single object
$('.viewer').viewer('loadModelsFromToken', 'https://api.catenda.com/v2/projects/978720ca.../viewer3d/data?token=8958f669f...', {
  query: { objectId: 123251972852 }
});

// Query - multiple objects
$('.viewer').viewer('loadModelsFromToken', 'https://api.catenda.com/v2/projects/978720ca.../viewer3d/data?token=8958f669f...', {
  query: { objectId: { $in : [ 123251972852, 123251836942 ] } }
});

Load one or more models from the Models section in Bimsync into the viewer. The models are selected by creating a Viewer3D token from Bimsync REST API.

You can limit the response by providing a query option. The query supports the same query language as the IFC resources in Bimsync REST API

See Loading models for more information on how to load models from Bimsync.

Parameters:

loadModel

Example:

// BIM model
$('.viewer').viewer('loadModel', 'https://api.catenda.com/v2/download?token=8958f669f...', {
  modelType: 'bim',
  modelId: '453760b9-7776-4e96-81e3-25de402cf8d4'
});

// Point cloud model
$('.viewer').viewer('loadModel', 'https://api.catenda.com/v2/download?token=8958f669f...', {
  modelType: 'point-cloud',
  modelId: ''5618e8c8-8665-47d6-9feb-1ebf31370795'
});

Load a model into the viewer.

See Loading models for more information on how to load models from Bimsync.

Parameters:

showModel

Makes a hidden model visible.

Parameters:

hideModel

Hides a model.

Parameters:

unloadModel

Unloads a model.

Parameters:

transformModel

Example:

// Move the model along the x-axis, scale it in y-direction, rotate it around the z-axis
$('.viewer').viewer('transformModel', 'dabc6dfce6e849bfada976d9fa9e294a', {
    position: {x: 1, y: 0, z: 0},
    scale: {x: 1, y: 1.5, z: 1},
    rotation: {x: 0, y: 0, z: 1, angle: 1.57}
});

Moves, scales and rotates a model.

Parameters:

getGrids

Example:

var grids = $('.viewer').viewer('getGrids');
console.log(grids);

$('.viewer').viewer('getGrids', function(grids) {
    console.log(grids);
    // This will print information of all grids.
});

Returns an array of grids.

Example output:

[
  {
    "id": "1234",
    "name": "ROAD-1",
    "type": "alignment",
    "modelId": "3fc118f1-55cf-41a1f",
    "axes": [
      {
        "id": "197217583953",
        "length": 40.245330797054265
      }
    ]
  },
  {
    "id": "5678",
    "name": "ROAD-2",
    "type": "alignment",
    "modelId": "3fc118f1-55cf-41a1f",
    "axes": [
      {
        "id": "197217583954",
        "length": 219.14744797126792
      }
    ]
  }
]

getGridAxisState

Example:

var grids = $('.viewer').viewer('getGridAxisState', '12345');
console.log(grids);
// This will print the state of grid axis with ID '12345'

Returns the state of a grid axis.

Example output:

{
  "visible": true,
  "extrudeCurve": false
}

Parameters:

setGridAxisState

Example:

$('.viewer').viewer('setGridAxisState', '12345', { visible: true, extrudeCurve: false });
// This will disable extrusion and set visibility of grid axis with ID '12345'. 

Sets the state of an axis.

Parameters:

State fields:

calculatePointOnAxis

Example:

var point = $('.viewer').viewer('calculatePointOnAxis', '12345', 3.2);
console.log(grids);
// This will print the point at distance 3.2 along axis '12345'

Calculates the position and direction of a point on an axis, by distance from the start.

Example output:

{
  "location": {
    "x": 1892167.7040417693,
    "y": 3126832.9894373063,
    "z": 3.53
  },
  "direction": {
    "x": -0.467451240524306,
    "y": 0.8840188559823187,
    "z": 0
  }
}

Parameters:

enableMeasure

Example:

$('.viewer').viewer('enableMeasure', {
  mode: 'dimension'
});

Enable measure mode. If mode is omitted from parameters, the previously used measure mode will be activated. Default measure mode is 'laser'.

Parameters:

disableMeasure

Example:

$('.viewer').viewer('disableMeasure')

Disable measure mode.

clearMeasure

Example:

$('.viewer').viewer('clearMeasure')

Clear measures.

setRenderSettings

Example:

$('.viewer').viewer('setRenderSettings', { renderMode: 'incremental' });
// Enable incremental rendering.
$('.viewer').viewer('setRenderSettings', { renderMode: 'regular' });
// Disable incremental rendering.
$('.viewer').viewer('setRenderSettings', { pixelRatio: 'window.devicePixelRatio' });
// Set pixel ratio to match device pixel ratio.
$('.viewer').viewer('setRenderSettings', { depthBuffer: 'logarithmic' });
// Enable logarithmic depth buffer.

Sets the render settings of the 3D viewer.

Parameters:

State fields:

getRenderSettings

Example:

var settings = $('.viewer').viewer('getRenderSettings');
console.log(settings);
// This will print all render settings.

Returns the render settings, such as render mode, pixel ratio and shading.

Example output:

{
  "renderMode": "incremental",
  "pixelRatio": 1,
  "depthBuffer": "standard",
  "shading": "regular"
}

setCameraSettings

Example:

$('.viewer').viewer('setCameraSettings', { fov: 65, near: 0.1, far: 10000 });
// This will set the field of view to 65, near plane to 0.1 and far plane (view distance) to 10000.

Sets the camera settings of the 3D viewer.

Parameters:

State fields:

getCameraSettings

Example:

var settings = $('.viewer').viewer('getCameraSettings');
console.log(settings);
// This will print all camera settings.

Returns the camera settings, such as field of view and clipping plane parameters.

Example output:

{
  "fov": 60,
  "near": 0.1,
  "far": 5000
}

setMeasureSettings

Example:

$('.viewer').viewer('setMeasureSettings', { labelMode: 'segmentLength' });
// This will set the measurement label mode to display segment lengths.

Sets the camera settings of the 3D viewer.

Parameters:

State fields:

getMeasureSettings

Example:

var settings = $('.viewer').viewer('getMeasureSettings');
console.log(settings);
// This will print all measure settings.

Returns the measure settings, which define how measurements are displayed.

Example output:

{
  "appendMeasures": true,
  "conversionFactor": 1000,
  "decimals": 0,
  "labelMode": "segmentLength",
  "opacity": 1
}

setAppearanceSettings

Example:

$('.viewer').viewer('setAppearanceSettings', { selectedColor: '#f94a9d' });
// This will set the selection color to pink.
$('.viewer').viewer('setAppearanceSettings', { selectedColor: $.fn.viewer.defaults.selectedColor });
// This will reset the selection color.

Sets the appearance settings of the 3D viewer.

Parameters:

Settings fields:

transitionSettings

Example:

$('.viewer').viewer('transitionSettings', {
  duration: 500,
  easing: 'QuadraticInOut'
})

Set camera transition settings. Controls camera transition animations triggered by calls to lookAt, lookAtBoundingBox or viewpoint.

The viewer is initialized with the following transition settings:

{ duration: 0, easing: 'LinearNone' }

Parameters:

Settings fields:

Easing functions:

The following easing functions are available:

viewpoint

Example:

// Get current viewpoint
$('.viewer').viewer('viewpoint', null, function(viewpoint) {
    console.log(viewpoint);
});

// Set predefined viewpoint - available 'home', 'top', 'left', 'right', 'front', 'back'
$('.viewer').viewer('viewpoint', 'top');

// Set perspective viewpoint
$('.viewer').viewer('viewpoint', {
    direction: {
        x: 0,
        y: -1,
        z: 0
    },
    location: {
        x: 0,
        y: 100,
        z: 0,
    },
    up: {
        x: 0,
        y: 0,
        z: 1
    },
    fov: 50,
    type: 'perspective'
});

// Set orthogonal viewpoint
$('.viewer').viewer('viewpoint', {
    direction: {
        x: 0,
        y: 0,
        z: -1
    },
    location: {
        x: 7
        y: 2.5
        z: 17
    },
    up: {
        x: 0,
        y: 0,
        z: 1
    },
    viewToWorldScale: 14,
    type: 'orthogonal'
});

Get and set current viewpoint.

Parameters:

clippingPlanes

Example:

var clippingPlanes = [
  {
    location: {
      x: 6.9000000953674245,
      y: 2.4132123330870963,
      z: 4.384152126303485
    },
    direction: {
      x: 0,
      y: 0,
      z: 1
    }
  },
  {
    location: {
      x: 6.9000000953674245,
      y: 2.4132123333570963,
      z: 1.6841521263034842
    },
    direction: {
      x: 0,
      y: 0,
      z: -1
    }
  }
];

// Set
$('.viewer').viewer('clippingPlanes', clippingPlanes);
    
// Get
$('.viewer').viewer('clippingPlanes', null, function(clippingPlanes) {
    console.log(clippingPlanes);
});

Set or get clipping planes. The viewer can display up to six clipping planes.

To select a clipping plane you have to hold down the Shift key while clicking on the plane. When the plane is selected you should be able to move it using the mouse.

Parameters:

clippingPlaneWidgetViewport

Example:

$('.viewer').viewer('clippingPlaneWidgetViewport', {x: 0, y: 300, width: 150, height: 150});

Set the position and size og the clipping plane widget. Note that the enableClippingPlaneWidget option have to be set to true to get this to work.

Parameters:

Viewport fields:

images

Example:

// Set image
$('.viewer').viewer('images', [{
    url: 'http://example.com/example.jpg'),
    size: {width: 200, height: 100},
    transform: {
        position: {x: 100, y: 50, z: 0},
        rotation: {x: 0, y: 0, z: 1, angle: Math.PI / 2}
    }
}]);

Set or get images. Images are displayed on a plane defined by a size and transformation. If not transformed, the image will be placed with its center in the origin (0, 0, 0) facing up (position Z-axis). Supported formats are PNG, JPG, GIF and DDS. Size and transform position is defined in meters.

Parameters:

section

Example

// Create clipping planes above and below objects
$('.viewer').viewer('section', [ '1', '2' ], ['top', 'bottom']);

Create clipping planes relative to the axis aligned bounding box of the provide objects.

Parameters:

screenshot

Example:

$('.viewer').viewer('screenshot', function(screenshot) {
    $('img').attr('src', screenshot);
});

Create a screenshot as base64 encoded PNG.

Parameters:

color

Example

// RGB
$('.viewer').viewer('color', '#FF0000', [ '1', '2' ]);

// RGBA
$('.viewer').viewer('color', '#FF0000A0', [ '1', '2' ]);

// Get colors
$('.viewer').viewer('color', null, [ '1', '2' ], function(colors) {
   console.log(colors);
});

Example output

{
    '1': {
        color: {r: 1.0, g: 0.0, b: 0.0},
        opacity: 1.0
        style: '#FF0000FF
    },
    '2': {
        color: {r: 1.0, g: 0.0, b: 0.0},
        opacity: 1.0
        style: '#FF0000FF
    },
}

Get and set custom object color.

Setting a custom object color will override the appearance of an object.

To get the currently set custom object color, you pass a callback that accepts an object. The keys of the object will be ids and the values will contain the color data. The argument will only contain values for ids that has a custom color currently set. The callback will be called with an empty object ({}) if no ids have custom color.

Parameters:

resetColors

Resets colors to the defaults.

Parameters: None

lookAt

Example:

// Use current camera direction
$('.viewer').viewer('lookAt', [ '18439659', '18439683', '18439751', '18439776' ]);

// Use predefined direction - available 'home', 'top', 'left', 'right', 'front', 'back'
$('.viewer').viewer('lookAt', [ '18439659', '18439683', '18439751', '18439776' ], 'top');

Move given objects into view. An optional predefined camera direction can be provided.

Parameters:

boundingBox

Example:

$('.viewer').viewer('boundingBox', [ '18439659', '18439683', '18439751', '18439776' ], function(boundingbox) {
    console.log(boundingbox);
});

Calculate the axis aligned bounding box of one or more objects. If the id is null the bounding box of all objects is returned. The bounding box will have the shape

{
  min: {
    x: ...
    y: ...
    z: ...
  },
  max: {
    x: ...
    y: ...
    z: ...
  }
}

Parameters:

lookAtBoundingBox

Example:

// Get boundingbox of given objects
$('.viewer').viewer('boundingBox', [ '18439659', '18439683', '18439751', '18439776' ], function(boundingBox) {
    // Use current camera direction
    $('.viewer').viewer('lookAtBoundingBox', boundingBox);

    // Use predefined direction - available 'home', 'top', 'left', 'right', 'front', 'back'
    $('.viewer').viewer('lookAtBoundingBox', boundingBox, 'top');
});

// Get model bounding box
$('.viewer').viewer('modelInfo', 'ce168045...', function(modelInfos) {
    $('.viewer').viewer('lookAtBoundingBox', modelInfos[0].boundingBox);
});

Move bounding box into view. An optional predefined camera direction can be provided.

Parameters:

each

Calls a function for each object.

Parameters:

For all objects in viewer:

All objects of a specific model:

eachSelected

Example:

$('.viewer').viewer('eachSelected', function(id) {
    $(this).viewer('hide', id);
});

Calls a function for each selected object.

Parameters:

objectInfo

Example:

$('.viewer').viewer('getProducts', ['18439659'], function(products) {
    console.log(products[0]);
});

Returns the product entity for one or more object.

Querying information for unknown ids will result in the product being null. If id is not provided, the method will return products for all loaded objects.

Parameters:

objectInfo

Example:

$('.viewer').viewer('objectInfo', ['18439659', 'UNKNOWN_ID'], function(info) {
    console.log(info[0]);
    // info[1] will be null
});

Returns information for one or more objects. Each info object contains the following properties:

Querying information for unknown ids will result in the info object being null. If id is not provided, the method will return info for all objects.

Parameters:

modelInfo

Example:

$('.viewer').viewer('modelInfo', function(modelInfos) {
    console.log(modelInfos);
    // This will print model info for all loaded models
});

$('.viewer').viewer('modelInfo', 'ce168045...', function(modelInfos) {
    console.log(modelInfos[0]);
    // This will print model info for the given model id

    $('.viewer').viewer('lookAtBoundingBox', modelInfos[0].boundingBox);
});

Returns an array of model info objects. For now the modelId and the model boundingBox are returned.

Note that this method only returns information about loaded models.

Parameters:

keyDown

Example:

// When the user press the 'w' key, move forward
$('.viewer').viewer('keyDown', {moveForward: true});

// The camera will now move straight ahead until
$('.viewer').viewer('keyDown', {moveForward: false});

Move camera using one or more of the the following keywords:

Parameters:

resetKeyDown

Example:

// If the current browser window loose focus, keyup events may not trigger.
// To avoid moving after loosing focus on the window, trigger:
$(window).bind('blur', function() {
    $(viewer).viewer('resetKeyDown');
});

Mark all keys as being released.

Parameters: None

Example:

$('.viewer').viewer('navigate', { moveForward: 1.5, rotateRight: 0.5});

Another example:

var randomMovement = function() {
    var sin = Math.sin(Math.random() * Math.PI);
    var cos = Math.cos(Math.random() * Math.PI);
    $('.viewer').viewer('navigate', { moveForward: sin, rotateRight: cos });
    setTimeout(randomMovement, 200);
}
randomMovement();

Navigate in one of the directions listed in the keydown method.

Parameters:

stopNavigation

Example:

// Start movement
$('.viewer').viewer('navigate', { moveForward: 1.5, rotateRight: 0.5});

// Stop movement
$('.viewer').viewer('stopNavigation');

Stops the movement started by the navigate method.

Parameters: None

Sets the current navigation mode.

Parameters:

Predefined modes

The following predefined modes are available.

Custom modes

The navigation mode can be customized by specifying an object containing a list of event/action pairs per device. The available devices are 'mouse', 'touch' and 'keyboard'. Passing an empty object ({}) will disable all navigation.

Download example

The source code for the definition of the predefined modes is available for download here.

Download example

Event matching

Example

Given the following definition:
    'mouse': [
      {
        'event': 'click',
        'action': 'click',
      },
      {
        'event': 'click',
        'action': 'select',
        'filter': {
          'button': 0
        }
      }
    ]
If a user clicks in the viewer with the left button (button 0) both event/action pairs will be executed. Clicking with the right button (button 2) will only execute the first.

When an event is triggered by a device, all event/action pairs are evaluated to find the actions to be executed. The event name must match the triggered event and if filter is specified, all filters must match the event state.

Filters

The following filters are available:

Event execution

    'mouse': [
      {
        'event': 'click',
        'action': 'click',
        'filter': {
          'button': 0
        }
      },
      {
        'event': 'click',
        'action': 'select',
        'filter': {
          'button': 0
        }
      }
    ]

All actions that match an event are executed in the order specified in the device list. If an action is cancelled (e.g. a viewer.click event handler returns false) when executed, the rest of the matching actions will not be executed.

In the example below, the click action will be run before the select action. Cancelling the viewer.click event will stop the select action from executing.

Action parameters

Each event/action pair can optionally contain the following action parameters passed as properties on the event/action pair object.

Mouse events

Touch events

Keyboard events

Actions

walkSpeed

Example:

$('.viewer').viewer('walkSpeed', 3.0);

Sets the walk speed used when navigating with the keyboard controls.

Parameters:

elevationSpeed

Example:

$('.viewer').viewer('elevationSpeed', 1.0);

Sets the vertical movement speed used when navigating with the keyboard controls.

Parameters:

rotationSpeed

Example:

$('.viewer').viewer('rotationSpeed', 50.0);

Sets the rotation speed (in degrees/sec) used when navigating with the keyboard controls.

Parameters:

fieldOfView

Example:

$('.viewer').viewer('fieldOfView', 50.0);

Sets the camera field of view angle in degrees.

Parameters:

addShape

Example:

$('.viewer').viewer('addShape', {
  type: 'sphere',
  position: { x: 0,y: 0,z: 0 },
  radius: 10
});

Add a shape at the given position

Parameters:

removeShape

Remove the give shape

Parameters:

clearShapes

Remove all added shapes

getTool

Example:

$('.viewer').viewer('getTool', function(tool) {
    console.log(tool);
});

Returns the currently active tool.

Parameters:

setTool

Example:

$('.viewer').viewer('setTool', 'laser-measure');
// This will enable the "laser-measure" tool.

Set the currently active tool.

Parameters:

Types

MeasureEnableParameters interface

Properties

Name Type Description
mode 'laser' or 'dimension' Optional. Measure mode.

ShapeParams3D interface

CircleShapeParams

Name Type Description
id string Optional. Id
type 'circle' Type of shape
position Vector3 The center of the circle
radius number The radius of the circle
color string Optional. The color of the shape
onClick () => void Optional. Event fired when shape is clicked

SphereShapeParams

Name Type Description
id string Optional. Id
type 'sphere' Type of shape
position Vector3 The center of the sphere
radius number The radius of the sphere
color string Optional. The color of the shape
onClick () => void Optional. Event fired when shape is clicked

BoxShapeParams

Name Type Description
id string Optional. Id
type 'box' Type of shape
position Vector3 The center position of the box
extents Vector3 The width, height and depth of the box
color string Optional. The color of the shape
onClick () => void Optional. Event fired when shape is clicked

Events

$('.viewer').bind('viewer.select', function(event, selected) {
    console.log(selected);
});

The events created by the viewer are custom jQuery events. Attach a handler to an event with jQuery.bind.

viewer.load

Triggered when viewer and content is completely loaded.

Callback parameters

None

viewer.error

Triggered when something goes wrong.

Callback parameters

type String

Error types:

viewer.select

Triggered when the set of selected objects is changed by user events (e.g. mouse clicks).

Callback Parameters

selected Array Set of selected object IDs. If no objects are selected the array is empty.

viewer.viewpoint

Triggered when the current viewpoint is changed by user events (e.g. mouse drags).

Callback Parameters

viewpoint Object A viewpoint

viewer.click

Triggered when the user clicks inside the viewer. Returning false from the event handler will cancel the default viewer behavior.

Callback Parameters

id String Id of the object below the cursor. Undefined if no objects are below the cursors.
intersects Object Position of the object below the cursor, and a direction vector perpendicular to the surface of the object. Undefined if no objects are below the cursors.

viewer.doubleclick

Triggered when the user doubleclick clicks inside the viewer. Returning false from the event handler will cancel the default viewer behavior.

Callback Parameters

id String Id of the object below the cursor. Undefined if no objects are below the cursors.
intersects Object Position of the object below the cursor, and a direction vector perpendicular to the surface of the object. Undefined if no objects are below the cursors.

viewer.contextmenu

Triggered when the user summons the context menu (e.g. by right-clicking).

Callback Parameters

id String Id of the object below the cursor. Undefined if no objects are below the cursors.
intersects Object Position of the object below the cursor, and a direction vector perpendicular to the surface of the object. Undefined if no objects are below the cursors.