Viewer Widget
Use the Viewer Widget API to include the Viewer Widget in your 3D viewer instance. The widget is useful for basic embedded viewer functionality. For more advanced usage make use of the Viewer APIs.
Installation
Follow the same installation steps when using jQuery with the following changes to include the Viewer Widget in your project.
- In step 4, provide the viewer-ui option to include the Viewer Widget.
bimsync.load(["viewer-ui"]);- In step 6, after loading a model initialize the Viewer Widget by invoking the viewerUI method on the jQuery object for the div where the 3D viewer instance is attached.
$("#viewer-3d")
.viewer("loadModelsFromToken", tokenUrl3d)
.then(() => {
$("#viewer-3d").viewerUI();
});Usage
<html>
<head>
<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
<script src="https://api.catenda.com/js/v1/viewer2d"></script>
<script src="https://api.catenda.com/js/v1/viewer3d"></script>
<style>
#viewer-2d {
height: 50%;
width: 100%;
}
#viewer-3d {
height: 50%;
width: 100%;
}
</style>
</head>
<body>
<div id="viewer-3d"></div>
<div id="viewer-2d"></div>
<script type="text/javascript">
let loadedViewersCount = 0;
bimsync.setOnViewer2dLoadCallback(onViewersLoaded);
bimsync.setOnLoadCallback(onViewersLoaded);
bimsync.loadViewer2d();
bimsync.load(["viewer-ui"]);
function onViewersLoaded() {
if (++loadedViewersCount < 2) return;
const projectId = "YOUR_CATENDA_PROJECT_ID";
const token = "YOUR_3D_VIEWER_TOKEN";
const tokenUrl2d = `https://api.catenda.com/v2/projects/${project}/viewer2d/geometry?token=${token}`;
const tokenUrl3d = `https://api.catenda.com/v2/projects/${project}/viewer3d/data?token=${token}`;
const viewer2dOptions = {
hoverSpaces: false,
showViewpoint: false,
selectColor: "#ff0000"
};
const viewer3dOptions = {
textRenderMode: "dom"
};
const widgetOptions = {
enableContextMenu: true,
enableKeyboard: true,
enableJoystick: true,
enableViewer2dIntegration: true,
joystickHidden: false,
joystickPosition: "middle-right",
lockStoreyMode: true,
showViewer2dStoreySelect: true,
viewer2dId: "viewer-2d"
};
$("#viewer-2d").viewer2d();
$("#viewer-2d")
.viewer2d("loadUrlPromise", tokenUrl2d)
.then(() => {
const storeys = $("#viewer-2d").viewer2d("getStoreys");
if (storeys.length > 0) {
$("#viewer-2d").viewer2d("showStorey", storeys[1].id);
}
});
$("#viewer-3d").viewer(viewer3dOptions);
$("#viewer-3d")
.viewer("loadModelsFromToken", tokenUrl3d)
.then(() => {
$("#viewer-3d").viewerUI(widgetOptions);
});
}
</script>
</body>
</html>Options
Adjust the default behavior of the Viewer Widget by providing an options object when creating a Viewer Widget instance.
Properties
Name | Type | Default | Description |
|---|---|---|---|
enableContextMenu | Boolean | false | Enable context menu features |
enableJoystick | Boolean | true | Enable joystick widget |
enableKeyboard | Boolean | false | Enable keyboard shortcuts and navigation |
enableViewer2dIntegration | Boolean | false | Enable Viewer2D integration |
joystickBorderOffset | String | '20px' | Joystick border offset |
joystickColor | String | 'blue' | Valid RGB value for color ofjoystick wdiget |
joystickHidden | Boolean | true | Hide joystick widget |
joystickPosition | String | 'bottom-center' | Position of joystick widget |
joystickRotationClamp | Number | 2 | Joystick rotation clamp |
joystickSize | Number | 100 | Size of joystick widget |
lockStoreyMode | Boolean | false | Lock storey mode |
showViewer2dLockedNavigationToggle | Boolean | false | Show Viewer2D locked navigation toggle |
showViewer2dStoreySelect | Boolean | false | Show Viewer2D storey select |
spacesVisible | Boolean | false | Show spaces |
viewer2dId | String | null | DOM element id of 2D Viewer instance |
translations | Object | {} | Translations for the Viewer Widget |
joystickPosition
Valid values are:
- 'middle-left'
- 'bottom-left'
- 'bottom-center'
- 'bottom-right'
- 'middle-right'
translations
Translations for the Viewer Widget.
Name | Default | Description |
|---|---|---|
addClippingPlane | Add clipping plane | Add a clipping plane |
defaultBuildingName | (unknown building) | Default building name |
defaultModelName | (unknown model) | Default model name |
hide | Hide | Hide selected models |
hideOthers | Hide others | Hide all models except selected |
isolate | Isolate | Isolate selected models |
loading | Loading... | Loading models |
lookAt | Look at | Look at selected models |
makeTranslucent | Make translucent | Make selected models translucent |
noModelsLoaded | No models loaded. | No models loaded |
removeClippingPlanes | Remove clipping planes | Remove all clipping planes |
sectionTopAndBottom | Section top and bottom | Section top and bottom |
showAll | Show all | Show all models |
Methods
hideJoyStick
Hides the joystick.
Usage
$("#viewer-3d").viewerUI("hideJoystick");joystickPosition
Sets the joystick position.
Usage
const position = "bottom-center";
$("#viewer-3d").viewerUI("joystickPosition", position);Parameters
position
Position of the joystick.
Type | Required |
|---|---|
String | Yes |
Valid values are:
- 'middle-left'
- 'bottom-left'
- 'bottom-center'
- 'bottom-right'
- 'middle-right'
set2dLockedNavigationMode
Set the 2D locked navigation mode. When enabled, the cursor will be in the center of the 2D scene.
Usage
const isLocked = true;
$("#viewer-3d").viewerUI("set2dLockedNavigationMode", isLocked);Parameters
isLocked
Positions the cursor in the center of the 2D scene.
Type | Required |
|---|---|
Boolean | Yes |
set2dLockStoreyMode
Set the 2D lock storey mode. When disabled, the 2D viewer storey selection will follow the 3D viewer.
Usage
const isLocked = false;
$("#viewer-3d").viewerUI("set2dLockStoreyMode", isLocked);Parameters
isLocked
Is the 2D lock storey mode enabled.
Type | Required |
|---|---|
Boolean | Yes |
setSpaces
Set the space ids to be considered when spacesVisible option is false.
Usage
const spaceIds = ["space-1", "space-2"];
$("#viewer-3d").viewerUI("setSpaces", spaceIds);Parameters
spaceIds
List of spaceIds
Type | Required |
|---|---|
Array[String] | Yes |
setSpacesVisible
Set spaces visibility.
Usage
const areSpacesVisible = true;
$("#viewer-3d").viewerUI("setSpacesVisible", areSpacesVisible);Parameters
areSpacesVisible
Are spaces visible.
Type | Required |
|---|---|
Boolean | Yes |
showJoyStick
Displays the joystick if enabled.
Usage
$("#viewer-3d").viewerUI("showJoystick");updateJoystickOptions
Sets the joystick options.
Usage
const options = {
joystickBorderOffset: "20px",
joystickColor: "blue",
joystickHidden: false,
joystickPosition: "bottom-center",
joystickRotationClamp: 0.5,
joystickSize: 200
};
$("#viewer-3d").viewerUI("updateJoystickOptions", options);Parameters
options
Options for the joystick.
Type | Required |
|---|---|
Object | Yes |
Properties
Name | Type | Description |
|---|---|---|
joystickBorderOffset | String | Margin from edge of viewport |
joystickColor | String | Color of the joystick |
joystickHidden | Boolean | Is the joystick hidden |
joystickPosition | String | Position of the joystick |
joystickRotationClamp | Number | Speed of scene navigation, valid value between 0 and 1 |
joystickSize | Number | Size of the joystick in pixels |
joystickPosition
Valid values are:
- 'middle-left'
- 'bottom-left'
- 'bottom-center'
- 'bottom-right'
- 'middle-right'