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:
- https://api.bimsync.com/v2/... -> https://api.catenda.com/v2/...
- https://api.bimsync.com/js/... -> https://api.catenda.com/js/...
- https://api.bimsync.com/oauth/... -> https://api.catenda.com/oauth/...
- https://api.bimsync.com/oauth2/... -> https://api.catenda.com/oauth2/...
- https://opencde.bimsync.com/... -> https://api.catenda.com/opencde/...
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?
- Stable channel: The stable channel is fully tested and should be the default channel for production ready applications. It is updated every 4 to 5 weeks.
- Beta channel: The beta channel should be used to test upcoming updates.
- Development channel: The development channel can be used to try out what we are working on right now. It is regularly updated and can be subject to bugs. Don't use the development channel in production ready applications.
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:
- Stable channel: Default channel. Either ommit the parameter or use
release=stable
.
<script src="https://api.catenda.com/js/v1/viewer3d"></script>
or
<script src="https://api.catenda.com/js/v1/viewer3d?release=stable"></script>
- Beta channel: Use
release=beta
.
<script src="https://api.catenda.com/js/v1/viewer3d?release=beta"></script>
- Development channel: Use
release=dev
.
<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.
-
Create a Viewer3D token using the Bimsync REST API on your backend service.
-
Add the Bimsync Viewer3D script to the web page.
<script src="https://api.catenda.com/js/v1/viewer3d"></script>
- Add a
<div>
element to the web page. Set the attributedata-viewer
towebgl
and the attributedata-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.
- Add the Bimsync Viewer3D script to the web page.
<script src="https://api.catenda.com/js/v1/viewer3d"></script>
- Add a
<div>
element to the web page. Give the element anid
attribute.
<div id="viewer"></div>
- Add a
<script>
element to initialize the viewer. Use a selector to find thediv
element and initialize the viewer by calling the jQuery plugin functionviewer
.
<script>
bimsync.load();
bimsync.setOnLoadCallback(function () {
$('#viewer').viewer();
});
</script>
- 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.
-
Create a Viewer3D token using the Bimsync REST API.
-
Pass the
url
field from the JSON response toloadModelsFromToken
.
$('#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.
- 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.
- 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.
- Pass the
url
field from the JSON response toloadModel
.
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:
- id - String or Array
showAll
Makes all objects visible.
Parameters: None
hide
Makes object hidden.
Parameters:
- id - String or Array
hideAll
Hides all objects.
Parameters: None
translucent
Makes object translucent.
Parameters:
- id - String or Array
translucentAll
Make all objects translucent.
Parameters: None
opaque
Makes object opaque.
Parameters:
- id - String or Array
opaqueAll
Make all objects opaque.
Parameters: None
select
Marks object as selected.
Parameters:
- id - String or Array
deselect
Removes object from selected set.
Parameters:
- id - String or Array
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:
- url - String
- optional options - Object
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:
- url - String
- optional options - Object
showModel
Makes a hidden model visible.
Parameters:
- id - String
hideModel
Hides a model.
Parameters:
- id - String
unloadModel
Unloads a model.
Parameters:
- id - String
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:
- id - String
- transform - Object
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:
- id - string - Grid axis ID.
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 - object
State fields:
- visible: Boolean - Visibility of the axis
- extrudeCurve: Boolean - Whether or not the axis curve should be extruded
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:
- id - String - Grid axis ID
- distance - Number - Distance along the axis curve
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:
- parameters - MeasureEnableParameters
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 - object
State fields:
- depthBuffer: Whether to use normal or logarithmic depth buffer, which offers better precision at the cost of performance
- pixelRatio: Number - The ratio between physical and logical pixels
- renderMode: String - Defines how the scene is rendered (in one frame, or incrementally). Possible values: 'regular' | 'incremental'
- shading: String - Shading mode. Possible values: 'regular' | 'sketch' | 'hidden-line' | 'ssao'
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 - object
State fields:
- fov: Number - Field of view (in degrees)
- near: Number - Distance to the near clipping plane (minimum view distance)
- far: Number - Distance to the far clipping plane (maximum view distance)
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 - object
State fields:
- appendMeasures: Boolean - Append to list of existing measures when using
addMeasure
method - conversionFactor: Number - Conversion factor applied to measure values
- decimals: Number - Number of decimals to display for measure values
- labelMode: String - Display mode for measure labels. Possible values: 'pointDistance' | 'segmentLength' | 'segmentIndex'
- numberFormatter: (number) => string - Custom number formatter function for measure values
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 - object
Settings fields:
- defaultColor: string | number - The default color for objects that has no color specified.
- selectedColor: string | number - The color of selected objects.
- translucentOpacity: number - The opacity of translucent objects.
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 - Object
Settings fields:
- duration - Number - animation duration in milliseconds
- easing - String - name of easing function
Easing functions:
The following easing functions are available:
- LinearNone
- QuadraticIn
- QuadraticOut
- QuadraticInOut
- CubicIn
- CubicOut
- CubicInOut
- QuarticIn
- QuarticOut
- QuarticInOut
- QuinticIn
- QuinticOut
- QuinticInOut
- SinusoidalIn
- SinusoidalOut
- SinusoidalInOut
- ExponentialIn
- ExponentialOut
- ExponentialInOut
- CircularIn
- CircularOut
- CircularInOut
- ElasticIn
- ElasticOut
- ElasticInOut
- BackIn
- BackOut
- BackInOut
- BounceIn
- BounceOut
- BounceInOut
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:
- viewpoint - String or Object
- optional callback - Function(Object viewpoint)
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:
- clippingPlanes - Array
- optional callback - Function(Array clippingPlanes)
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 - object
Viewport fields:
- x - Number - widget x-coordinate
- y - Number - widget y-coordinate
- width - Number - width of the widget
- height - Number - height of the widget
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:
- images - Array
- optional callback - Function(Array images)
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:
- id - String or Array
- planes - Array containg one or more of 'top', 'bottom', 'left', 'right', 'front', 'back'
screenshot
Example:
$('.viewer').viewer('screenshot', function(screenshot) {
$('img').attr('src', screenshot);
});
Create a screenshot as base64 encoded PNG.
Parameters:
- callback - Function(String screenshot)
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:
- color - String or null
- id - String or Array
- optional callback - Function(Object colors)
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:
- id - String or Array
- optional direction - String
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:
- id - String or Array
- callback - Function(Object boundingbox)
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:
- boundingBox - Object
- optional direction - String
each
Calls a function for each object.
Parameters:
For all objects in viewer:
- callback - Function(String id)
All objects of a specific model:
- modelId - String
- callback - Function(String id)
eachSelected
Example:
$('.viewer').viewer('eachSelected', function(id) {
$(this).viewer('hide', id);
});
Calls a function for each selected object.
Parameters:
- callback - Function(String id)
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:
- optional id - String or Array
- callback - Function
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:
- id - String - id of the object
- modelId - String - id of the model the object belongs to.
- triangleCount - Number - number of triangles
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:
- optional id - String or Array
- callback - Function(Array info)
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:
- optional modelId - String or Array
- callback - Function(Array modelInfos)
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:
- moveForward
- moveBackward
- moveLeft
- moveRight
- moveUp
- moveDown
- rotateUp
- rotateDown
- rotateLeft
- rotateRight
Parameters:
- Object - Object where fields are keywords with a boolean specifiying if it is pressed
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
navigate
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:
- Object - Object where keys are one of the values listed in the keydown method, and the value is a number specifiying the movement force/speed
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
navigationMode
Sets the current navigation mode.
Parameters:
- mode - String or object
Predefined modes
The following predefined modes are available.
- 'orbit' - default mode - orbit camera around a point on drag
- 'pan' - pan camera on drag
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.
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:
- button: 0 (left button), 1 (middle button), 2 (right button)
- shiftKey: true, false
- ctrlKey: true, false
- metaKey: true, false
- pointers: number of pointers active in touch events
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.
- scale: Action multiplier. Default value is 1.0. Can be used to control sensitivity or invert the action direction by using a negative value.
Mouse events
- 'click'
- 'doubleClick'
- 'wheel'
- 'drag'
Touch events
- 'tap'
- 'doubleTap'
- 'longPress'
- 'pan'
- 'pinch'
Keyboard events
- 'rotateLeft'
- 'rotateRight'
- 'rotateUp'
- 'rotateDown'
- 'moveForward'
- 'moveBackward'
- 'moveLeft'
- 'moveRight'
- 'moveUp'
- 'moveDown'
Actions
- 'click'
- 'doubleClick'
- 'contextMenu'
- 'select'
- 'fitToView'
- 'zoom'
- 'zoomMove'
- 'rotateZ'
- 'rotateX'
- 'moveForward'
- 'moveLeft'
- 'moveUp'
- 'orbit'
- 'pan'
- 'pivot'
walkSpeed
Example:
$('.viewer').viewer('walkSpeed', 3.0);
Sets the walk speed used when navigating with the keyboard controls.
Parameters:
- speed - Double, value in m/s
elevationSpeed
Example:
$('.viewer').viewer('elevationSpeed', 1.0);
Sets the vertical movement speed used when navigating with the keyboard controls.
Parameters:
- speed - Double, value in m/s
rotationSpeed
Example:
$('.viewer').viewer('rotationSpeed', 50.0);
Sets the rotation speed (in degrees/sec) used when navigating with the keyboard controls.
Parameters:
- speed - Double, number of degrees to rotate per second
fieldOfView
Example:
$('.viewer').viewer('fieldOfView', 50.0);
Sets the camera field of view angle in degrees.
Parameters:
- fieldofview - Double, field of view angle in degrees
addShape
Example:
$('.viewer').viewer('addShape', {
type: 'sphere',
position: { x: 0,y: 0,z: 0 },
radius: 10
});
Add a shape at the given position
Parameters:
- parameters - ShapeParams3D
removeShape
Remove the give shape
Parameters:
- id - id of the shape to be removed
clearShapes
Remove all added shapes
getTool
Example:
$('.viewer').viewer('getTool', function(tool) {
console.log(tool);
});
Returns the currently active tool.
Parameters:
- callback - Function
setTool
Example:
$('.viewer').viewer('setTool', 'laser-measure');
// This will enable the "laser-measure" tool.
Set the currently active tool.
Parameters:
- tool - string - The name of the tool. Possible values: 'create-plane', 'dimension-measure', 'laser-measure', 'point-measure', 'select'
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:
- 'no-webgl' - WebGL is not supported or disabled
- 'load-failed' - Loading failed
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. |