Viewer 2D API
Getting started
The Viewer 2D API allows to embed a 2D viewer in your web applications.
Dependencies
Bimsync Viewer 2D requires jQuery 1.x to run.
Initialize
The Viewer 2D API can be automatically initialized by using the DOM data API or manually initialized in JavaScript.
Note In the example below, nothing will be displayed until you use the showStorey
Note If you are using the Viewer 3D API and want a predefined 2D/3D integration you can use our Viewer Widget API.
DOM Data API
Add the Viewer2D framework
<script src="https://api.catenda.com/js/v1/viewer2d"></script>
Create a Viewer 2D element
<div id="viewer-2d" data-viewer2d="svg" data-url="https://api.catenda.com/v2/projects/dabc6df.../viewer2d/geometry?token=410c0aa7..."></div>
Example
<!DOCTYPE html>
<html style="height: 100%;">
<head>
<script src="//cdnjs.cloudflare.com/ajax/libs/jquery/2.1.1/jquery.min.js"></script>
<script src="https://api.catenda.com/js/v1/viewer2d"></script>
</head>
<body style="height: 100%;">
<script type="text/javascript">
$(function(){
var $viewer2d = $('#viewer-2d');
$viewer2d.bind('loaded', function(event) {
var storeys = $viewer2d.viewer2d('getStoreys');
$.each(storeys, function(i, storey) {
console.log(storey.name, storey.id);
});
var storeyByElevation = $viewer2d.viewer2d('getStoreyByElevation', 3.2);
$viewer2d.viewer2d('showStorey', storeyByElevation.id);
});
});
</script>
<div id="viewer-2d" data-viewer2d="svg" data-url="https://api.catenda.com/v2/projects/dabc6df.../viewer2d/geometry?token=410c0aa7..." style="height: 100%; width:100%;"></div>
</body>
</html>
-
Create a viewer access token by using the POST v2/projects/:project/viewer2d/token described in the Bimsync REST API.
-
Add the Viewer 2D framework to you application.
-
Create a Viewer 2D element. The data attribute data-viewer2d="svg" must be included. The data attribute data-url must be the url field from a viewer access token.
JavaScript
-
Create a viewer access token by using the POST v2/projects/:project/viewer2d/token described in the Bimsync REST API.
-
Create a DIV element which will contain the 2D-viewer.
Create DIV element
<div id="viewer-2d"></div>
- Follow the pattern in the snippet below to initialize:
Follow the pattern from script below to initialize
<script src="https://api.catenda.com/js/v1/viewer2d"></script>
<script type="text/javascript">
// Load the Viewer 2D API
bimsync.loadViewer2d();
// Set a callback to run when the Viewer API is loaded
bimsync.setOnViewer2dLoadCallback(createViewer2d);
// Callback that loads a viewer access token URL
function createViewer2d() {
$('#viewer-2d').viewer2d('loadUrl', 'https://api.catenda.com/v2/projects/dabc6df.../viewer2d/geometry?token=410c0aa7...');
}
</script>
Example
<!DOCTYPE html>
<html style="height: 100%;">
<head>
<script src="//cdnjs.cloudflare.com/ajax/libs/jquery/2.1.1/jquery.min.js"></script>
<script src="https://api.catenda.com/js/v1/viewer2d"></script>
</head>
<body style="height: 100%;">
<script type="text/javascript">
$(function(){
var viewer2dUrl = "https://api.catenda.com/v2/projects/dabc6df.../viewer2d/geometry?token=410c0aa7...";
var $viewer2d = $('#viewer-2d');
bimsync.loadViewer2d();
bimsync.setOnViewer2dLoadCallback(function() {
$viewer2d.viewer2d('loadUrl', viewer2dUrl);
});
$viewer2d.bind('loaded', function(event) {
var storeys = $viewer2d.viewer2d('getStoreys');
$.each(storeys, function(i, storey) {
console.log(storey.name, storey.id);
});
var storeyByElevation = $viewer2d.viewer2d('getStoreyByElevation', 3.2);
$viewer2d.viewer2d('showStorey', storeyByElevation.id);
});
});
</script>
<div id="viewer-2d" style="height: 100%; width:100%;"></div>
</body>
</html>
Options
All options can be set using data attributes on the viewer element, or passed as an object when initializing with JavaScript.
Options
var options = {
showViewpoint: Boolean // Set the viewpoint to be hidden or visible, default is true
selectColor: String // Set the color of selected objects, default is '#A7F555'
};
Setting options when using JavaScript initialization:
$('#viewer-2d').viewer2d({
showViewpoint: true,
selectColor: 'RoyalBlue'
});
$('#viewer-2d').viewer2d('loadUrl', 'https://api.catenda.com/v2/projects/dabc6df.../viewer2d/geometry?token=410c0aa7...');
Setting options when using data attribute initialization:
<div id="viewer-2d" data-viewer2d="svg" data-enable-viewpoint="true"
data-url="https://api.catenda.com/v2/projects/dabc6df.../viewer2d/geometry?token=410c0aa7...">
</div>
Methods
All methods are invoked by calling the method viewer2d on the result of a jQuery/$ function call. The first argument to the viewer2d method must be the method name.
addImage
Example:
$('#viewer-2d').viewer2d('addImage',{
url: 'https://cdn.pixabay.com/photo/2016/08/25/07/30/red-1618916_1280.png',
x: 20,
y: 30,
width: 1.45,
height: 0.34
});
Adds an image to specified location.
Parameters:
- object
- id - string - (optional, autogenerated if not present)
- url - string
- x - double
- y - double
- width - double
- height - double
- rotate - boolean - (optional, when present it rotates the image if the model rotates)
addMarker
Example:
var id = $('#viewer-2d').viewer2d('addMarker', {
id: 'P325',
x:1.45,
y:0.34,
color: '#aaaaaa',
text: 'Test',
data: { owner: 'Jan Erik' },
clickable: true,
draggable: false
});
Add a marker to specific location.
Properties
Name | Type | Description |
---|---|---|
marker | MarkerParams | The parameters to add a new Marker |
Returns
Type | Description |
---|---|
string | The id of the new Marker |
clearColors
Example:
$('#viewer-2d').viewer2d('clearColors');
Clear colors on all objects.
clearImages
Example:
$('#viewer-2d').viewer2d('clearImages');
Clear all images.
clearMarkers
Example:
$('#viewer-2d').viewer2d('clearMarkers');
Clear all markers.
getBoundingBox
Examples:
$('#viewer-2d').viewer2d('getBoundingBox', '123456');
$('#viewer-2d').viewer2d('getBoundingBox', ['123456', '234567']);
Get bounding box for a set of objects. Currently only spaces are supported.
Parameters:
- objectId - string or array of string
getOffset
Example:
$('#viewer-2d').viewer2d('getOffset');
The method is deprecated and will always return a zero offset:
{
z: 0
}
Get the viewer Z-axis offset.
getSpaces
Examples:
// Get all spaces from first loaded model
var spaces = $('#viewer-2d').viewer2d('getSpaces');
console.log(spaces);
// Get all spaces
var spaces = $('#viewer-2d').viewer2d('getSpaces', { all: true });
console.log(spaces);
// Get all visible spaces
var spaces = $('#viewer-2d').viewer2d('getSpaces', { all: true, visible: true });
console.log(spaces);
// Get spaces for a specific building
var spaces = $('#viewer-2d').viewer2d('getSpaces', { buildingId: '0.wskqcff1ik' });
console.log(spaces);
// Get spaces for a specific storey
var spaces = $('#viewer-2d').viewer2d('getSpaces', { storeyId: "72150032" });
console.log(spaces);
Example output
[
{
id: "2776903120",
guid: "3gw3QKdmzBThLITx3QSRY2",
name: "1E16"
longName: "CENTRAL WAITING",
storey: "First Floor"
storeyId: "2776903125"
boundingBox: {
height: 10.2760009765625
width: 4.792999267578125
x: -50.61149978637695
y: -48.75149917602539
}
}
]
Returns an array of space objects.
Due to backward compatibility we will only add spaces from the first loaded model. Add the all flag to the options to get spaces from all models.
Parameters:
- object
- all - boolean (optional) Get spaces from all models.
- buildingId - string (optional) Get spaces for a specific building.
- storeyId - string (optional) Get spaces for a specific storey.
- visible - boolean (optional) Filter query to only include spaces visible in the viewer. This can be combined with other options.
getStoreyByElevation
Example:
var storey = $('#viewer-2d').viewer2d('getStoreyByElevation', 3.2);
console.log(storey);
Example output:
{
id: "2777293459",
guid: "3eM8WbY_59RR5TDWs3wwJP",
name: "2. floor",
elevation: "2.77"
}
Gets the storey at a given elevation. This will only give the storey for the first model loaded. Use getStoreysByElevation to get storeys for all models.
Parameters:
- elevation - Double
getStoreysByElevation
Example:
var storeys = $('#viewer-2d').viewer2d('getStoreysByElevation', 3.2);
console.log(storeys);
Example output:
[
{
id: "2777293459",
guid: "3eM8WbY_59RR5TDWs3wwJP",
name: "2. floor",
elevation: "2.77"
},
{
id: "1579293459",
guid: "5aa9WbY_59RR5TDWs3wwJP",
name: "3. floor",
elevation: "2.5"
}
]
Gets storeys from all models at a given elevation.
Parameters:
- elevation - Double
getStoreys
Examples:
// Get all storeys from first loaded model
var storeys = $('#viewer-2d').viewer2d('getStoreys');
console.log(storeys);
// Get all storeys
var storeys = $('#viewer-2d').viewer2d('getStoreys', { all: true });
console.log(storeys);
// Get all visible storeys
var storeys = $('#viewer-2d').viewer2d('getStoreys', { all: true, visible: true });
console.log(storeys);
// Get storeys for a given building
var storeys = $('#viewer-2d').viewer2d('getStoreys', { buildingId: '0.aqifqv5mjx7' });
console.log(storeys);
Example output:
[
{
elevation: "-2.77",
id: "2776903120",
guid: "3eM8WbY_59RR5TDWs3wwJP",
name: "basement"
}
]
Returns an array of storey objects. Due to backward compatibility we will only include storeys from the first loaded model. Use the all flag to the options to get storeys from all models.
Parameters:
- object
- buildingId - string (optional) Get storeys for a specific building.
- all - boolean (optional) Get storeys from all models.
- visible - boolean (optional) Filter query to only include storeys visible in the viewer. This can be combined with other options.
getViewpoint
Example
var viewpoint = $('#viewer-2d').viewer2d('getViewpoint');
console.log(viewpoint);
Example output:
{
location: {
x: 1,
y: 2,
z: 34
},
direction: {
x: 0.39,
y: 0.9,
z: 0
}
}
Get the viewpoint. Viewpoint is the red arrow which shows where you are looking from.
The height (location.z) is the height of the active storey. The direction is in the horizontal plane (xy), facing in the direction of the arrow.
hideStorey
Example:
$('#viewer-2d').viewer2d('hideStorey', '18320028');
Hide a storey.
Parameters:
- storeyId - string - The id of the storey
hideStoreys
Example:
$('#viewer-2d').viewer2d('hideStoreys');
Hide all storeys.
hideViewpoint
Example:
$('#viewer-2d').viewer2d('hideViewpoint');
Hides the viewpoint. Use showViewpoint to make it visible.
loadUrl
Example:
$('#viewer-2d').viewer2d(
'loadUrl',
'https://api.catenda.com/v2/projects/dabc6df.../viewer2d/geometry?token=410c0aa7...',
{ append: true }
);
Load the contents of a viewer-2d access token.
Parameters:
- url - String
- options
- append - boolean (optional, default is false) - If append is set to true, the model will be appended to the existing models in the viewer. If set to false, all existing models will be removed before the model is loaded.
- modelId - String (optional) - The modelId is used to identify the loaded model. Removal of a single model will require the modelId. If not present, a random id will be assigned.
- modelName - String (optional) - The name of the model. This can be used to store a user friendly name of the model.
lookAt
Example:
$('#viewer-2d').viewer2d('lookAt', '123456');
$('#viewer-2d').viewer2d('lookAt', ['123456', '234567']);
$('#viewer-2d').viewer2d('lookAt', ['123456', '234567'], { retainStoreys: true });
$('#viewer-2d').viewer2d('lookAt', ['123456', '234567'], { retainStoreys: true, expand: 1.8 });
$('#viewer-2d').viewer2d('lookAt', ['123456', '234567'], { retainStoreys: true, expand: { x: 2, y: 3 } });
Move given objects into view.
If any of the objects are visible, we will retain the current storeys. Otherwise we will change to the storeys matching the lowest elevation of the objects. If you always want to retain the current storeys you can set the retainStoreys option to true.
Parameters:
- objectId - string or array of string
- options
- retainStoreys - boolean (optional) Always retain current storeys. Default is false.
- expand - numbers or vector - Expand the view to include some of the area surrounding the objects. Unit is in meters.
lookAtBoundingBox
Example:
$('#viewer-2d').viewer2d(
'lookAtBoundingBox',
{
min: { x: -50.6115, y: -58.1927 },
max: { x: 1.648, y: 7.6145 }
}
);
$('#viewer-2d').viewer2d(
'lookAtBoundingBox',
{
min: { x: -50.6115, y: -58.1927, z: 2.1 },
max: { x: 1.648, y: 7.6145, z: 3.1 }
},
{
retainStoreys: true
}
);
Set view to a bounding box.
The retainStoreys option works as in lookAt when z is present. If z is absent, the storeys will be retained.
Parameters:
-
boundingBox
- min
- x - numbers
- y - numbers
- z - numbers - optional
- max
- x - numbers
- y - numbers
- z - numbers - optional
- min
-
options
- retainStoreys - boolean (optional) Retain current storeys. Default is false if z is present and true if z is absent.
moveTo
Moves viewpoint to specified location.
Parameters:
- x - double
- y - double
removeMarker
Example:
$('#viewer-2d').viewer2d('removeMarker', 'P325');
Remove a marker.
Parameters:
- id - string - marker id
screenshot
Example:
$('#viewer-2d').viewer2d('screenshot', { width: 1024, height: 768 }, function(image) {
$element.attr('src', image);
});
Get a 2D screenshot in PNG format.
Parameters:
-
options
- width - width of the screenshot,
- height - height of the screenshot
-
callback - method - returns the image produced
select
Example:
$('#viewer-2d').viewer2d('select', '123456');
Select an object visually in the 2D viewer.
Parameters:
- objectId - string - This will only work for objects visible in 2D.
setColor
Example:
$('#viewer-2d').viewer2d('setColor', '20640', 'red');
$('#viewer-2d').viewer2d('setColor', '20640', 'rgba(150, 255, 50, 0.5)');
$('#viewer-2d').viewer2d('setColor', ['20640', '34234'], 'red');
Apply a color to an object.
Parameters:
- objectId - string or array of strings (spaces and objects visible in 2D)
- color - string
setSpaceNames
Example:
$('#viewer-2d').viewer2d(
'setSpaceNames',
{
'123456789': {
name: '001.001'
longName: 'Kitchen'
},
'987654321': {
name: '001.002'
longName: 'Living room'
}
}
);
Change the names being displayed for spaces.
Parameters:
- names - object Map from object ID to an object containing name and/or longname values.
setSpaceNameFormat
Example:
$('#viewer-2d').viewer2d('setSpaceNameFormat', 'long');
Set the format for space names.
Parameters:
- format - { 'regular', 'long' } Display regular or long name for spaces
setTransformation
Example:
var transform = {
position: {
x: 2.0,
y: 1.0,
z: 3.4
},
rotation: {
centerOfRotation: {
x: 1.0,
y: 0.0
},
angle: 3.14 // radians
}
};
$('#viewer-2d').viewer2d('setTransformation', modelId, transform);
Set model transformation.
Parameters:
- modelId - String
- transform - Object
setViewpoint
Examples:
$('#viewer-2d').viewer2d('setViewpoint', {location: {x: 1, y: 2}});
$('#viewer-2d').viewer2d('setViewpoint', {location: {x: 1, y: 2}, direction: 90});
$('#viewer-2d').viewer2d('setViewpoint', {location: {x: 1, y: 2}, direction: {x: 0.39, y: 0.92} });
Set the location and orientation of the viewpoint.
Parameters:
- object
- location - { x, y }
- direction - numbers in degrees or normalized vector { x, y }
showStorey
Example:
var storey = $('#viewer-2d').viewer2d('storeyByElevation', 3.2);
$('#viewer-2d').viewer2d('showStorey', storey.id);
Make a storey visible in the view.
Parameters:
- id - String
showViewpoint
Example:
$('#viewer-2d').viewer2d('showViewpoint');
Show the viewpoint. Use hideViewpoint to hide the viewpoint.
unloadModel
Example:
$('#viewer-2d').viewer2d('unloadModel', '817accd43bf24915b8491085e40b6d8c');
Unload model from viewer.
Parameters:
- modelId - String - This should match the modelId specified in loadUrl.
Types
Marker interface
Properties
Name | Type | Description |
---|---|---|
id | string | A unique identifier. |
x | number | Marker X axis position. |
y | number | Marker Y axis position |
icon | Icon | Optional. Marker icon. |
color | string | Optional. Marker color. |
text | string | Optional. A text label to the marker. |
data | any | Optional. User data associated with the marker. |
Icon interface
Properties
Name | Type | Description |
---|---|---|
url | string | The URL of the image. |
size | Size | The size of the image. |
anchor | Point | The point of the image that will correspond to the marker position. |
Point interface
Properties
Name | Type | Description |
---|---|---|
x | number | The X coordinate. |
y | number | The Y coordinate. |
Size interface
Properties
Name | Type | Description |
---|---|---|
width | number | The width. |
height | number | The height. |
Events
The events created by the viewer are custom jQuery events. Attach a handler to an event with jQuery.bind.
viewer2d.click
Example:
$('#viewer-2d').bind('viewer2d.click', function(event, location, id) {
console.log('viewer2d.click', 'location', location, 'id', id);
});
Triggered when the user clicks inside the viewer. Returning false from the event handler will cancel the default viewer behavior.
Callback Parameters
location | Object | Global coordinate of the cursor. Z value is the height of the intersection plane. |
id | String | Id of the object below the cursor. Undefined if no objects are below the cursors. |
viewer2d.contextmenu
Example:
$('#viewer-2d').bind('viewer2d.contextmenu', function(event, location, id) {
console.log('viewer2d.contextmenu', 'location', location, 'id', id);
});
Triggered when the user summons the context menu (e.g. by right-clicking).
Callback Parameters
location | Object | Global coordinate of the cursor. Z value is the height of the intersection plane. |
id | String | Id of the object below the cursor. Undefined if no objects are below the cursor. |
viewer2d.dblclick
Example:
$('#viewer-2d').bind('viewer2d.dblclick', function(event, location, id) {
console.log('viewer2d.dblclick', 'location', location, 'id', id);
});
Triggered when the user double-clicks inside the viewer. Returning false from the event handler will cancel the default viewer behavior.
Callback Parameters
location | Object | Global coordinate of the cursor. Z value is the height of the intersection plane. |
id | String | Id of the object below the cursor. Undefined if no objects are below the cursors. |
viewer2d.load
Example:
$('#viewer-2d').bind('viewer2d.load', function(event, modelId) {
console.log("Viewer2D model loaded", modelId);
});
Triggered when viewer and content is completely loaded.
Callback parameters
modelId | String | ID of model |
viewer2d.loadfail
Example:
$('#viewer-2d').bind('viewer2d.loadfail', function(event, modelId) {
console.log("Viewer2D model load failed", modelId);
});
Triggered when model load fails.
Callback parameters
modelId | String | ID of model |
viewer2d.loadstart
Example:
$('#viewer-2d').bind('viewer2d.loadstart', function(event, modelId) {
console.log("Viewer2D model load started", modelId);
});
Triggered when model load is started.
Callback parameters
modelId | String | ID of model |
viewer2d.markerclick
Example:
var marker = $('#viewer-2d').viewer2d('addMarker', {
id: 42,
x:1.45,
y:0.34,
color: 'yellow',
text: 'Remove door',
clickable: true
});
$('#viewer-2d').bind('viewer2d.markerclick', function(event, marker) {
console.log('Marker clicked', marker.id);
});
Triggered when the user clicks on a marker. The marker must be created as clickable
.
Returning false from the event handler will cancel the default viewer behavior.
Callback Parameters
Name | Type | Description |
---|---|---|
marker | Marker | The clicked marker |
viewer2d.markerhover
Example:
var marker = $('#viewer-2d').viewer2d('addMarker', {
id: 42,
x:1.45,
y:0.34,
color: 'yellow',
text: 'Remove door',
clickable: true
});
$('#viewer-2d').bind('viewer2d.markerhover', function(event, marker) {
console.log('Hovered over marker', marker.id);
});
Triggered when the user hovers over a marker.
Returning false from the event handler will cancel the default viewer behavior.
Callback Parameters
marker | [Marker](#marker-interface) | The hovered marker. |
viewer2d.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. |
viewer2d.unload
Example:
$('#viewer-2d').bind('viewer2d.unload', function(event, modelId) {
console.log("Viewer2D model unloaded", modelId);
});
Triggered when viewer and content is unloaded.
Callback parameters
modelId | String | ID of model |
viewer2d.viewpoint
Triggered when the current viewpoint is changed by user events (e.g. mouse drags).
Callback Parameters
viewpoint | Object | A viewpoint |