Viewer API 1.2

We recently started proper versioning of our Viewer API, so you can know that the version you’re using will always behave the same way regardless of updates (except in the case of an urgent bug fix or big changes to the viewer code itself).

You can subscribe to the Viewer API Change Log and you can always find the latest version on the Documentation page.

This post will go through some of the changes in version 1.2.x and discuss some use cases and examples.

New Annotation Events

• annotationMouseEnter
• annotationMouseLeaves
• annotationSelect

These events fire when your mouse starts hovering over an annotation, stops hovering over an annotation, and when you select an annotation. A use case could be a more robust version of our Annotation Sync experiment, where your page reacts in more ways to a user’s interaction with annotations. They look something like this:

api.addEventListener('annotationMouseEnter', function(index) {
    console.log('Mouse entered annotation #' + (index + 1));
});
api.addEventListener('annotationMouseLeave', function(index) {
    console.log('Mouse left annotation #' + (index + 1));
});
api.addEventListener('annotationSelect', function(index) {
    if (index > -1) {
        console.log('Selected annotation #' + (index + 1));
    } else {
        console.log('Unselected annoation');
    }
});

New Camera Movement Events

• cameraStart
• cameraStop

These events fire when the camera starts moving and when it stops moving. A use case could be taking a screenshot or overlaying extra information on the screen only when the user is not moving the model. They look something like this:

api.addEventListener('camerastart', function() {
    console.log('Camera started moving');
});
api.addEventListener('camerastop', function() {
    console.log('Camera stopped moving');
});

New Viewer Events

• viewerstart
• viewerstop

These events fire when the viewer is started or stopped, whether that’s done manually by the user clicking the Play button and Stop button or programmatically through the stop() and start() API methods. This means you can always know the current state of the viewer and react accordingly.

Updated click event

The click event now fires with null values when clicking on nothing, so you can know if a user clicked the background, but still know the 2D position of the click on the screen. A possible use case is overlaying your own content or notes on top of the viewer. It looks like this:

api.addEventListener('click', function(e) {
    if (e.position3D) {
        console.log('You clicked the object!');
    } else {
        console.log('You clicked nothing!')
    }
}, { pick: 'slow' });

New unselectAnnotation method

The unselectAnnotation() method unselects current selected annotation. This means you can dismiss any annotation tooltips that might be open. For example, you could add a button to your site:

document.getElementById('unselect-annotation').addEventListener('click', function() {
    api.unselectAnnotation();
    console.log('Unselected annotation');
});

Demos

Here’s a simple application using all of these new features to display information about what’s happening in the viewer. You can download the source files here.



Here’s a fancier example use case for the click event combined with the translate() method. Click the blue door to open and close the cabinet.

We hope these new additions to the Viewer API will be helpful in your projects. If you need help or want to share your work, you can always reach out on the forum or contact support. We can’t wait to see what you build!