NAV Navigation
JavaScript

2D viewer 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.

Obtain viewer2d token url from REST API

POST /beta/viewer2d/access

Example

    POST https://api.bimsync.com/beta/viewer2d/access?project_id=dabc6dfce6e849bfada976d9fa9e294a

    {
      "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9....",
      "url": "https://api.bimsync.com/beta/viewer2d/svg?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9....",
      "modelId": "195ee1a5a5e845faa591d5efd9b6b321"
    }

    POST https://api.bimsync.com/beta/viewer2d/access?model_id=dabc6dfce6e849bfada976d9fa9e294a

    {
      "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9....",
      "url": "https://api.bimsync.com/beta/viewer2d/svg?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9....",
      "modelId": "dabc6dfce6e849bfada976d9fa9e294a"
    }

Creates a 2d-viewer access token. The token will expire after 60 minutes.

Query Parameters

project_id string The ID of the project
model_id string The ID of the model
revision_id integer The revision number

project_id or model_id have to be set. If no model_id is provided, bimsync will guess which model to return based on the content. If no revision_id is provided, the latest revision will be used. The response will contain the active model and revision ids.

Initialize

The Viewer 2D API can be automatically initialized by using the DOM data API or manually initialized in JavaScript.

DOM Data API

Add the Viewer2D framework

<script src="https://api.bimsync.com/1.0/js/viewer2d.js"></script>

Create a Viewer 2D element

<div id="viewer-2d" data-viewer2d="svg" data-url="https://api.bimsync.com/beta/viewer2d/svg?token=eyJ0eX..."></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.bimsync.com/1.0/js/viewer2d.js"></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.bimsync.com/beta/viewer2d/svg?token=eyJyZX..." style="height: 100%; width:100%;"></div>
        </body>
    </html>
  1. Create a viewer access token by using the POST /beta/viewer2d/access resources described above.

  2. Add the Viewer 2D framework to you application:

  3. 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.

Note Nothing will be displayed until you use the showStorey Note If you are using the Viewer 3D and want a predefined 2d-3d integration you can use our Viewer widget API. For a complete example see this demo

JavaScript

  1. Create a viewer access token by using the POST /beta/viewer2d/access resources above

  2. Create a DIV element which will contain the 2D-viewer.

  3. Follow the pattern in the snippet below to initialize:

Note that nothing will be displayed until you use the showStorey Note if you are using the 3d-viewer and want a predefined 2d-3d integration you can use our viewer-ui-plugin. For a complete example see this demo

Create DIV element

        <div id="viewer-2d"></div>

Follow the pattern from script below to initialize

        <script src="https://api.bimsync.com/1.0/js/viewer2d.js"></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.bimsync.com/beta/viewer2d/svg?token=eyJ0eX...');
            }
        </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.bimsync.com/1.0/js/viewer2d.js"></script> 
        </head>
        <body style="height: 100%;">
            <script type="text/javascript">
                $(function(){
                    var viewer2dUrl = "https://api.bimsync.com/beta/viewer2d/svg?token=eyJyZXZpc2lvbi1pZCI6I...RGUUTsaPaxJ";
                    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.bimsync.com/beta/viewer2d/svg?token=eyJyZXZpc2lvbi1pZCI6I...RGUUTsaPaxJ');

Setting options when using data attribute initialization:

    <div id="viewer-2d" data-viewer2d="svg" data-url="https://api.bimsync.com/beta/viewer2d/svg?token=eyJ0eX..."
	    data-enable-viewpoint="true"></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

Adds an image to specified location.

Parameters:

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 });

addMarker

Add a marker to specific location.

Parameters:

Example:



    id = $('#viewer-2d').viewer2d('addMarker',  { id: 'P325', x:1.45, y:0.34, color: '#aaaaaa', text: 'Test', data: { owner: 'Jan Erik' } });

clearColors

Clear colors on all objects.

Example:



    $('#viewer-2d').viewer2d('clearColors');

clearImages

Clear all images.

Example:



    $('#viewer-2d').viewer2d('clearImages');

clearMarkers

Clear all markers.

Example:



    $('#viewer-2d').viewer2d('clearMarkers');

getBoundingBox

Get bounding box for a set of objects. Currently only spaces is supported.

Parameters:

Examples:



    $('#viewer-2d').viewer2d('getBoundingBox', '123456');
    $('#viewer-2d').viewer2d('getBoundingBox', ['123456', '234567']);

getOffset

Get the viewer Z-axis offset.

Example:



    $('#viewer-2d').viewer2d('getOffset');

This method is deprecated and will always return a zero offset:

    {
        z: 0
    }

getSpaces

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:

Examples:

    // Get all spaces from first loaded model
    $('#viewer-2d').viewer2d('getSpaces');

    // Get all spaces
    $('#viewer-2d').viewer2d('getSpaces', { all: true });

    // Get all visible spaces
    $('#viewer-2d').viewer2d('getSpaces', { all: true, visible: true });

    // Get spaces for a specific building
    $('#viewer-2d').viewer2d('getSpaces', { buildingId: '0.wskqcff1ik' });

    // Get spaces for a specific storey
    $('#viewer-2d').viewer2d('getSpaces', { storeyId: "72150032" });

The result will be something like this:

    [
        {
            "id": "2776903120",
            "guid": "3gw3QKdmzBThLITx3QSRY2", // Available for revisions imported after 11.5.2017
            "name": "1E16"
            "longName": "CENTRAL WAITING", // Available for revisions imported after 11.5.2017
            "storey": "First Floor"
            "storeyId": "2776903125"
            "boundingBox": {  // Available for options.visible only
                    height: 10.2760009765625
                    width: 4.792999267578125
                    x: -50.61149978637695
                    y: -48.75149917602539
            }
        }
     ]

getStoreyByElevation

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:

Example:



    // Get storey by elevation
    storey = $('#viewer-2d').viewer2d('getStoreyByElevation', 3.2);
 
The result will be something like this:

    {
        "id": "2777293459",
        "guid": "3eM8WbY_59RR5TDWs3wwJP", // Available for revisions imported after 11.5.2017
        "name": "2. floor",
        "elevation": "2.77"
    }

getStoreysByElevation

Gets storeys from all models at a given elevation.

Parameters:

Example:



    // Get storeys by elevation
    storeys = $('#viewer-2d').viewer2d('getStoreysByElevation', 3.2);

The result will be something like this:

    [
      {
        "id": "2777293459",
        "guid": "3eM8WbY_59RR5TDWs3wwJP", // Available for revisions imported after 11.5.2017
        "name": "2. floor",
        "elevation": "2.77"
      },
      {
        "id": "1579293459",
        "guid": "5aa9WbY_59RR5TDWs3wwJP", // Available for revisions imported after 11.5.2017
        "name": "3. floor",
        "elevation": "2.5"
      }
    ]

getStoreys

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:

Examples:



    // Get all storeys from first loaded model
    storeys = $('#viewer-2d').viewer2d('getStoreys');

    // Get all storeys
    storeys = $('#viewer-2d').viewer2d('getStoreys', { all: true });

    // Get all visible storeys
    storeys = $('#viewer-2d').viewer2d('getStoreys', { all: true, visible: true });

    // Get storeys for a given building
    storeys = $('#viewer-2d').viewer2d('getStoreys', { buildingId: '0.aqifqv5mjx7' });


The result will be something like this:

    [
        {
            "elevation": "-2.77",
            "id": "2776903120",
            "guid": "3eM8WbY_59RR5TDWs3wwJP", // Available for revisions imported after 11.5.2017
            "name": "basement"
        }
    ]

getViewpoint

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.

Examples:

viewpoint = $('#viewer-2d').viewer2d('getViewpoint');

rotation = Math.atan2(viewpoint.direction.x, viewpoint.direction.y) * 180 / Math.PI;

The result will be something like this:

{
  location: {
    x: 1, 
    y: 2,
    z: 34
  },
  direction: {
    x: 0.39,
    y: 0.9,
    z: 0
  }
}

hideStorey

Hide a storey.

Parameters:

Example:



    $('#viewer-2d').viewer2d('hideStorey', '18320028');

hideStoreys

Hide all storeys.

Example:



    $('#viewer-2d').viewer2d('hideStoreys');

hideViewpoint

Hides the viewpoint. Use showViewpoint to make it visible.

Examples:



    $('#viewer-2d').viewer2d('hideViewpoint');

loadUrl

Load the contents of a viewer-2d access token.

Parameters:

Example:



    $('#viewer-2d').viewer2d('loadUrl', 'https://api.bimsync.com/beta/viewer2d/svg?token=eyJ0eX...', { append: true });

lookAt

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:

Examples:



    $('#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 } });

lookAtBoundingBox

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:

Examples:



    $('#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 });

moveTo

Moves viewpoint to specified location.

Parameters:

Example:


removeMarker

Remove a marker.

Parameters:

Example:



    $('#viewer-2d').viewer2d('removeMarker',  'P325');

screenshot

Get a 2D screenshot in PNG format.

Parameters:

Examples:



    $('#viewer-2d').viewer2d('screenshot', { width: 1024, height: 768 }, function(image) {
      $element.attr('src', image);
    });

select

Select an object visually in the 2D viewer.

Parameters:

Example:



    $('#viewer-2d').viewer2d('select', '123456');

setColor

Apply a color to an object.

Parameters:

Examples:



    $('#viewer-2d').viewer2d('setColor', '20640', 'red');

    $('#viewer-2d').viewer2d('setColor', '20640', 'rgba(150, 255, 50, 0.5)');

    $('#viewer-2d').viewer2d('setColor', ['20640', '34234'], 'red');

setSpaceNames

Change the names being displayed for spaces.

Parameters:

Example:



    $('#viewer-2d').viewer2d('setSpaceNames', {
      '123456789': {
        name: '001.001'
        longName: 'Kitchen'
      },
      '987654321': {
        name: '001.002'
        longName: 'Living room'
      }
      });

setSpaceNameFormat

Set the format for space names.

Parameters:

Example:



    $('#viewer-2d').viewer2d('setSpaceNameFormat', 'long');

setTransformation

Set model transformation.

Parameters:

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);

setViewpoint

Set the location and orientation of the viewpoint.

Parameters:

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} });

showStorey

Make a storey visible in the view.

Parameters:

Example:



    var storey = $('#viewer-2d').viewer2d('storeyByElevation', 3.2);
    $('#viewer-2d').viewer2d('showStorey', storey.id);

showViewpoint

Show the viewpoint. Use hideViewpoint to hide the viewpoint.

Example:



    $('#viewer-2d').viewer2d('showViewpoint');

unloadModel

Unload model from viewer.

Parameters:

Example:



    $('#viewer-2d').viewer2d('unloadModel', '817accd43bf24915b8491085e40b6d8c');

Events

The events created by the viewer are custom jQuery events. Attach a handler to an event with jQuery.bind.

viewer2d.click

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.

Example:



    $('#viewer-2d').bind('viewer2d.click', function(event, location, id) {
        console.log('viewer2d.click', 'location', location, 'id', id);
    });

viewer2d.contextmenu

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.

Example:



    $('#viewer-2d').bind('viewer2d.contextmenu', function(event, location, id) {
        console.log('viewer2d.contextmenu', 'location', location, 'id', id);
    });

viewer2d.dblclick

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.

Example:



    $('#viewer-2d').bind('viewer2d.dblclick', function(event, location, id) {
        console.log('viewer2d.dblclick', 'location', location, 'id', id);
    });

viewer2d.load

Triggered when viewer and content is completely loaded.

Callback parameters

modelId String ID of model

Example:



    $('#viewer-2d').bind('viewer2d.load', function(event, modelId) {
        console.log("Viewer2D model loaded", modelId);
    });

viewer2d.loadfail

Triggered when model load fails.

Callback parameters

modelId String ID of model

Example:



    $('#viewer-2d').bind('viewer2d.loadfail', function(event, modelId) {
        console.log("Viewer2D model load failed", modelId);
    });

viewer2d.loadstart

Triggered when model load is started.

Callback parameters

modelId String ID of model

Example:



    $('#viewer-2d').bind('viewer2d.loadstart', function(event, modelId) {
        console.log("Viewer2D model load started", modelId);
    });

viewer2d.markerclick

Triggered when the user clicks on a marker. Returning false from the event handler will cancel the default viewer behavior.

Callback Parameters

marker Object The object passed as input when adding the marker.

Example:



    marker = $('#viewer-2d').viewer2d('addMarker',  { id: 42, x:1.45, y:0.34, color: 'yellow', text: 'Remove door' });
    $('#viewer-2d').bind('viewer2d.markerclick', function(event, marker) {
        console.log('Viewer2D marker clicked', marker.id);
    });

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.

Example


viewer2d.unload

Triggered when viewer and content is unloaded.

Callback parameters

modelId String ID of model

Example:



    $('#viewer-2d').bind('viewer2d.unload', function(event, modelId) {
        console.log("Viewer2D model unloaded", modelId);
    });

viewer2d.viewpoint

Triggered when the current viewpoint is changed by user events (e.g. mouse drags).

Callback Parameters

viewpoint Object A viewpoint