Viewer Integration Guide

This document outlines some more advanced aspects of page integration with Marmoset Viewer, and is intended for those with some web development experience. Artists wishing to get started with basic use should see the Getting Started with Marmoset Viewer tutorial, or look for answers to common questions on the Support page. This document does not cover these basic subjects, but rather describes the full javascript interface for developing with Marmoset viewer on the web. So basically, here be dragons, albeit fairly friendly ones.

If you’re a web developer working with Marmoset Viewer, and you still have questions after reading this document, please let us know at info@marmoset.co. We’d be happy to offer advice and consider feature requests for future versions.

Contents

Source

Marmoset Viewer comes in the form of a single javascript library which should be linked into your page as an external script:

This marmoset.js file contains all the necessary interfaces for creating and manipulating viewer elements. All classes and functions are contained within the “marmoset” namespace object – no other global symbols are altered or affected by the inclusion of marmoset.js. The library file also contains a short comment header at the top outlining license terms and conditions, as well as a build date stamp. Give it a quick read and make sure it’s to your liking.

Embed Utility

Marmoset Viewer comes with an embed utility for simple use cases. It has options for sizing and resizing, full-page rendering, basic formatting, and more. A simple embed call looks something like this:

When successful, embed() will append a viewer instance to the document body through a call to appendChild. Depending on the options present in paramObject, the rest of the document may also be further formatted. A WebViewer instance is returned (see also the “Direct Creation” section below).

The second parameter to embed() is a javascript object with several optional members present. These members are as follows:

Direct Creation

Marmoset Viewer can also be used directly, without use of the embed utility, for greater control. One can create viewer instances without attaching them to the document by simply allocating a new WebViewer:

The WebViewer constructor takes an initial numeric width and height, as well as a URL to the mview file to be used. WebViewer instances created in this way do not initially load the full mview scene, nor do they create a WebGL context or allocate much memory. A newly created viewer is in the “unloaded” state, where the model preview image is visible behind the “play” button.

During this step a WebViewer will attempt a partial-range GET request on the mview URL in order to load and display the model preview thumbnail (typically fetching less than 64 KB); it will not load the entire mview package. Preview thumbnails will not load correctly if the server hosting the mview package doesn’t support the “Accept-Ranges” and “Content-Length” HTTP headers. In this case, a placeholder gradient will be visible instead.

A viewer instance won’t be visible on the page until it is attached to the DOM, which may be done through reference to its “domRoot” member:

A viewer instance may be instructed to load its scene data and begin rendering, akin to the user pressing the “play” button, through a call to loadScene():

As scene loading occurs asynchronously, the WebViewer class provides a callback mechanism for triggering actions upon a successful scene load. One may place such a callback in the “onLoad” member, and it will be run at the conclusion of the scene loading process:

If dynamic resizing of the viewer context is needed, it may be done through a call to resize(). Note that this should not be done while the viewer is in fullscreen mode:

The WebViewer class contains several other methods and members not documented here. At this time we do not recommend using these undocumented symbols for anything other than experimentation, as they may be subject to change in the future.

Unloading

Marmoset Viewer instances may be returned to the “unloaded” state, which frees the entire scene and WebGL context from memory and once again displays the scene preview thumbnail behind the “play” button. This can be useful for managing memory use and performance in dynamic galleries or pages with many viewer contexts active.

Third Party Logos

The use of third-party “host” logos is supported, allowing you to brand viewer instances with your logo should you desire. This is accomplished by setting image and link URLs before any viewer instances are created:

Any third party logos specified in this way will interact properly with the rest of the Viewer user interface – being displayed in the correct location, hidden at appropriate times, given mouseover transparency effects, and so on. Note that logo art will be displayed at half size, allowing for support of high-DPI displays.

Extracting Thumbnails

The marmoset library allows for quick extraction of thumbnail images from mview files, should this be necessary for dynamic galleries or the like. This is done through an asynchronous call to fetchThumbnail():

This function takes four parameters, the last two of which are optional. The first is simply the URL to the mview package from which the thumbnail image is to be fetched. The second parameter, “onLoad”, is a callback function which will run once the image is successfully loaded (it will be passed the resulting Image object). The third parameter, “onError”, is another callback that is run if the thumbnail fetch fails for any reason. The onError callback may be null or undefined if you don’t wish to use it. The final parameter, “img”, is an optional Image object into which the thumbnail will be placed. If “img” is null or undefined, a new Image object will be created.

Thumbnail image resolutions may vary somewhat, depending on when the mview package was exported. Typically they are rendered with a wide field of view to a wide aspect ratio, to allow them to cleanly clip horizontally for a variety of sizes. You may find it necessary to clip or resize the image yourself once it is fetched, depending on your needs.

Thumbnail fetching will only transfer a small subset of the data in the mview package (on the order of 64 KB per request), so this call can be made efficiently many times per page. This depends on successful use of the “Accept-Ranges” and “Content-Length” HTTP headers. Calls to fetchThumbnail will fail if the hosting server does not support these protocols.

Compositing

Marmoset Viewer can be configured in a few ways to better composite into certain pages and web applications. For example, transparent background compositing can be enabled by setting a flag before any viewer instances are created:

The user interface can also be removed entirely, leaving a bare 3D view with no controls for layer views, help, fullscreen, and so on. This is similarly enabled with a global flag set before viewer instances are created:

Mirroring

Marmoset Viewer will, as necessary and when invoked, pull some user interface images from Marmoset’s server (these files reside in viewer.marmoset.co/main/data). If you wish to mirror marmoset.js and its UI data on your own servers instead of hotlinking them, you will need to manually direct the marmoset library to the new data locale in your page source:

Ensure that any data locale changes take place before any viewer instances are created. If you do decide to mirror any Marmoset files, you should take steps to update them regularly, as we frequently release updates and improvements to the library. We would recommend against mirroring unless your development needs dictate it.

More Questions?

We’d like to hear from you! We are making an effort work with web developers using Marmoset Viewer, and we’d be happy to help and offer advice should you need it. Please send any questions, concerns, or introductions to us at info@marmoset.co.