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.
JS
bimsync.load(["viewer-ui"]);
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.
JS
$("#viewer-3d")
  .viewer("loadModelsFromToken", tokenUrl3d)
  .then(() => {
    $("#viewer-3d").viewerUI();
  });
$("#viewer-3d")
  .viewer("loadModelsFromToken", tokenUrl3d)
  .then(() => {
    $("#viewer-3d").viewerUI();
  });
﻿
Usage
HTML
<html>
  <head>
    <script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
    <script src="https://api.bimsync.com/js/v1/viewer2d"></script>
    <script src="https://api.bimsync.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>
<html>
  <head>
    <script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
    <script src="https://api.bimsync.com/js/v1/viewer2d"></script>
    <script src="https://api.bimsync.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
JS
$("#viewer-3d").viewerUI("hideJoystick");
$("#viewer-3d").viewerUI("hideJoystick");
﻿
joystickPosition
Sets the joystick position.
Usage
JS
const position = "bottom-center";
$("#viewer-3d").viewerUI("joystickPosition", position);
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
JS
const isLocked = true;
$("#viewer-3d").viewerUI("set2dLockedNavigationMode", isLocked);
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
JS
const isLocked = false;
$("#viewer-3d").viewerUI("set2dLockStoreyMode", isLocked);
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
JS
const spaceIds = ["space-1", "space-2"];
$("#viewer-3d").viewerUI("setSpaces", spaceIds);
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
JS
const areSpacesVisible = true;
$("#viewer-3d").viewerUI("setSpacesVisible", areSpacesVisible);
const areSpacesVisible = true;
$("#viewer-3d").viewerUI("setSpacesVisible", areSpacesVisible);
﻿
Parameters
areSpacesVisible
Are spaces visible.
Type
Required
Boolean
Yes
showJoyStick
Displays the joystick if enabled.
Usage
JS
$("#viewer-3d").viewerUI("showJoystick");
$("#viewer-3d").viewerUI("showJoystick");
﻿
updateJoystickOptions
Sets the joystick options.
Usage
JS
const options = {
  joystickBorderOffset: "20px",
  joystickColor: "blue",
  joystickHidden: false,
  joystickPosition: "bottom-center",
  joystickRotationClamp: 0.5,
  joystickSize: 200,
};
$("#viewer-3d").viewerUI("updateJoystickOptions", options);
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'
﻿

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

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

Type	Required
String	Yes

Type	Required
Boolean	Yes

Type	Required
Boolean	Yes

Type	Required
Array[String]	Yes

Type	Required
Boolean	Yes

Type	Required
Object	Yes

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

Updated 18 Jun 2024

Did this page help you?

Using jQuery