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/...
Viewer Widget API v1.0
Getting started
The Viewer Widget API allows developers to add predefined widgets
- keyboard navigation
- joystick navigation
- a context menu
- viewer-2d integration
to their viewer app.
Dependencies
Viewer Widget API requires jQuery 1.x to run.
Initialize
Viewer Widget API can either be automatically initialized by using the DOM data API or manually initialized in JavaScript.
DOM Data API
Add viewer framework
<script type="text/javascript" src="https://api.catenda.com/1.0/js/viewer.js"></script>
Create a viewer instance
<div data-viewer="webgl" data-url="https://api.catenda.com/v2/projects/978720ca.../viewer3d/data?token=8958f669f..."
data-ui
data-enable-joystick="true"
data-enable-context-menu="true"
data-viewer2d-id="viewer-2d"
data-enable-viewer2d-integration="true"
data-show-viewer2d-storey-select="true">
</div>
-
Create a viewer access token by using the POST v2/projects/:project/viewer3d/token resources in the Catenda REST API.
-
Add the viewer framework to you application:
-
Create a viewer instance, and add the data attribute data-ui.
JavaScript
Create a DIV container
<div id="viewer-container">
<div id="viewer"></div>
</div>
Viewer-2d integration with the storey select enabled
<!-- If you are using the viewer-2d integration with the storey-select enabled, be sure to put the viewer-2d element in a container as well. -->
<div id="viewer-2d-container">
<div id="viewer-2d"></div>
</div>
Follow the below snippet to initialize
<script type="text/javascript" src="https://api.catenda.com/1.0/js/viewer.js"></script>
// Include viewer 2D script if 2D is used
<script type="text/javascript" src="https://api.catenda.com/1.0/js/viewer2d.js"></script>
<script type="text/javascript">
var loadedViewers = 0;
bimsync.setOnLoadCallback(viewerLoaded);
bimsync.setOnViewer2dLoadCallback(viewerLoaded);
// When loading the Viewer API, include a parameter ['viewer-ui']
bimsync.load(['viewer-ui']);
bimsync.loadViewer2d();
// Callback that loads a viewer access token URL and initializes the UI widget
function viewerLoaded() {
if (++loadedViewers < 2) {
return;
}
//Load the 3D geometry
const url3d = 'https://api.catenda.com/v2/projects/xxx/viewer3d/data?token=xxx';
$('#viewer').viewer('loadUrl', url3d);
// Load the 2D geometry
const url2d = 'https://api.catenda.com/v2/projects/xxx/viewer2d/geometry?token=xxx';
$('#viewer-2d').viewer2d('loadUrl', url2d);
// Initialize the viewer UI widget with desired options
$('#viewer').viewerUI({
enableJoystick: true,
joystickHidden: false,
enableContextMenu: true,
viewer2dId: 'viewer-2d',
enableViewer2dIntegration: true,
showViewer2dStoreySelect: true
// ...
});
}
</script>
-
Create a viewer access token by using the POST v2/projects/:project/viewer3d/token resources in the Catenda REST API.
-
Create a DIV container element which will contain the viewer element. If you are not using the joystick navigation, you can skip the container.
If you are using the viewer-2d integration with the storey select enabled, be sure to put the viewer-2d element in a container as well.
Options
var options = {
enableKeyboard: Boolean, // Default false
enableJoystick: Boolean, // Default true
joystickHidden: Boolean, // Default true
joystickColor: String, // Default 'blue', accepts any valid CSS color
joystickPosition: String, // Default 'bottom-center'.
joystickRotationClamp: Number, // Default 2, rotation speed is divided by this number
joystickBorderOffset: String, // Default '20px', accepts any valid CSS style
joystickSize: Integer, // Default 100, size in px
spacesVisible: Boolean, // Default false, note that you have to use the setSpaces method for this to work
viewer2dId: String, // Default null
enableViewer2dIntegration: Boolean, // Default false
showViewer2dStoreySelect: Boolean // Default false
enableContextMenu: Boolean, // Default false
translations: Object // Default { showAll: "Show all", hide: "Hide", hideOthers: "Hide others", makeTranslucent: "Make translucent", isolate: "Isolate", lookAt: "Look at", removeClippingPlanes: "Remove Clipping Planes", addClippingPlane: "Add clipping plane", sectionTopAndBottom: "Section top and bottom", noModelsLoaded: "No models loaded.", loading: "Loading...", defaultBuildingName: "(unknown building)", defaultModelName: "(unknown model)" }
};
enableKeyboard
This enables keyboard shortcuts and navigation in the viewer.
Shortcuts:
g : show
shift + g, o : show all
h : hide
del : remove selected clipping plane, or hide selected
shift + h : hide others
t : make translucent
shift + t, i : make others translucent
l : look at
Navigation:
w, up : move foreward
s, down : move backward
a, left : move left
d, right : move right
x, shift + up : move up
c, shift + down : move down
q, ins : rotate left
e, home : rotate right
r, pageup : rotate up
f, pagedown : rotate down
enableJoystick
Enables joystick navigation. The joystick can be used to navigate in the viewer on touch screens, or with the mouse.
joystickHidden
Wheter the joystick should be default hidden or not.
joystickColor
The color of the joystick widget. Any valid CSS color should work.
joystickPosition
The default position of the joystick. Possible values: 'middle-left', 'bottom-left', 'bottom-center', 'bottom-right', 'middle-right'
joystickRotationClamp
The rotation speed is originally set using the $('.viewer').viewer('rotationspeed', 50.0);
method.
To use a different rotation speed when navigating with the joystick, this number can be set to something other than 1.
The base rotation speed when navigating with the joystick will be the viewers rotation speed divided by this number.
joystickBorderOffset
Used to adjust the position the joystick, i.e. move it a bit farther from the border.
joystickSize
The px size of the joystick widget. Defaults to 100
spacesVisible
Wheter or not spaces should be shown.
To get this to work you have to use the setSpaces method first to let the widget know the ids of the spaces.
If spacesVisible is set to false
, spaces will be hidden, and remain hidden when the user triggers a show all event.
For an example of how to find the spaces in the first place, see the setSpaces method below.
viewer2dId
If you want to enable viewer-2d integration, you have to specify the id of the viewer-2d element.
enableViewer2dIntegration
Enables the 2d - 3d integration when it is set to true.
Note: you also have to specify the id of the 2d-viewer element.
showViewer2dStoreySelect
If this is set to true, a storey dropup will be added to the 2d-container.
Note: you also have to specify the id of the 2d-viewer element.
enableContextMenu
When enabled, a dropdown menu should appear when right-clicking in the viewer. From the context menu you should be able to show, hide, make translucent and add/remove clipping planes.
translations
Translate the context menu.
// Example norwegian translation:
$('#viewer').viewerUI({
// ...
enableContextMenu: true,
translations: {
showAll: "Vis alle",
hide: "Skjul",
hideOthers: "Skjul andre",
makeTranslucent: "Sett gjennomsiktig",
isolate: "Isoler",
lookAt: "Se på",
removeClippingPlanes: "Fjern klippeplan",
addClippingPlane: "Legg til klippeplan",
sectionTopAndBottom: "Klipp top og bunn"
}
});
Methods
All methods are invoked by calling the method viewerUI on the result of a jQuery/$ function call. The first argument to the viewerUI method must be the method name.
showJoystick
Shows the joystick. Joystick must be enabled for this to work.
Parameters: None
hideJoystick
Hides the joystick
Parameters: None
joystickPosition
Sets the position of the joystick.
Parameters:
- position - String - Possible values: 'middle-left', 'bottom-left', 'bottom-center', 'bottom-right', 'middle-right'
updateJoystickOptions
Updates the options, and redraws the joystick.
Parameters:
- options - Object - an object with the options to be updated.
setSpaces
Example
POST https://api.catenda.com/1.0/revision/products?model_id=ebad2a8ffc1d44ab86341a6d3d98e87e
{
"type": [ "IfcSpace" ]
}
By default the viewer will display spaces. If you want to hide the spaces, and make sure they remain hidden when you trigger a show all event, you can use this method to let the viewer know the objectIds of the spaces. You also have to make sure the showSpaces option is set to false.
To find the spaces you may use Query /ifc/products resources in the Catenda REST API with the type options set to "IfcSpace":
This will return an Array of IfcSpace objects, extract all the objectId
values and put them in an array. Use the array as input in this method.
Parameters:
- id - String or Array
setSpacesVisible
Sets the spacesVisible option. If true spaces will be shown, if false spaces will be hidden even when a show all event is triggered.
Parameters:
- visible - Boolean
set2dLockedNavigationMode
If 2d integration is activated, this will lock the cursor of the 2d-viewer in the center of the 2d-viewer.
Parameters:
- on/off - Boolean
set2dLockStoreyMode
If 2d integration is activated and the storey select is shown, this will make sure that the selected 2d storey do not change when navigating in 3d.
Parameters:
- on/off - Boolean