19 Feb 2016

Playing with the new Viewer Markup API

Default blog image

The latest release of the viewer API is coming with a 2D markup feature that allows you to draw svg shapes on top of your 2d/3d models, potentially save the markup information you created and restore them at a later time.

There is a tutorial here that illustrates the basics of how to work with those markups. However I found it lacks a bit of information and some parts are not completely up-to-date yet, hence this post trying to bring a complement.

First of all the markups is an API-only feature, meaning there is no UI provided out of the box by the viewer to create and manipulate the markups, so you will have to create your own (alternatively get somebody to do it for you - manager saying). This might be a bit of work depending what kind of feature you want to expose to your users. I'm planning to have a custom panel that lets me test all - or most - of the features provided by the Markup API, so better spend a bit of time having a convenient UI.

What the doc doesn't say is that the markup extension isn't part of the viewer3d.js, so you have to include an extra script before attempting to use it:


https://autodeskviewer.com/viewers/2.2/extensions/MarkupsCore.min.js (minified version)

You then need to explicitly load the extension in the viewer as parameter when creating the viewer object with options or at a later stage:

1 viewer.loadExtension("Autodesk.Viewing.MarkupsCore");
3 var markupsExtension = viewer.getExtension(
4   "Autodesk.Viewing.MarkupsCore");

You are now all set to start using the extension object by invoking its methods. See there for the complete Markups Core API reference

How the API is working? Well you have two modes: Edit and View. In edit mode the user can draw markups onto the screen, your app can then ask the extension to save the current state of the markups as a string. In view mode your app can load previously created markups from the strings into named layers and then toggle ON or OFF those layers at will. Storage of that markup information is upon your responsibility. It is also important to mention that while in edit mode you cannot load previous markups and while in view mode you cannot create new markups, this is as-designed. Finally, while in view mode the extension maintains a stack of actions that allows to easily undo/redo the actions a user may perform: creating markup, moving, resizing, deleting, ...

For more details on how to perform those actions, you can refer to the tutorial mentioned above. One modification to take into account is that methods enterViewMode and leaveViewMode have been renamed respectively show and hide. You however still have methods enterEditMode and leaveEditMode

At the time of this writing, I was not able to modify the svg style of the markups, so width, stroke style and colour stick to the default values. I'm working on it and will update the code when I can sort it out...

That's it, most what the API offers now it doable from my custom panel, it can save current markups to named layer and while in view mode you can toggle those layers visibility. It's a demo sample, so it does not persist the layers across sessions or if you unload the extension but from there it would be easily extensible to save that to a database.

Here is how it looks when loaded in the viewer and a link where you can test it live. The next step will be to create my own custom kind of markup (custom EditMode, as mentioned by the tutorial). Stay tuned ...

Screen Shot 2016-02-19 at 10.43.01
Complete code with all source files is available from Autodesk.ADN.Viewing.Extension.Markup

Related Article