Documentation

Updated 26 October 2020

Overview

The viewer consists of a 3D scene with a model of the object to view, select viewpoints to view the model from, and optionally, navigation UI elements that control movement between viewpoints. A viewer instance can be embedded directly through HMTL, or through our Javascript SDK, with customization available in both methods.

Viewpoints

Each viewpoint defines the virtual camera position relative to the model. It aligns exactly with the one of the product photos. Selecting a viewpoint will move the camera to view the object from the specified angle.

There are two types of viewpoints: outer and detail. Users can freely move from one outer viewpoint to another by dragging the camera through the scene. Detail viewpoints are focused on one point of the model and have to be zoomed out to move to other viewpoints. Users can navigate to detail viewpoints from outer ones by clicking on the plus buttons that appear when zooming or by double clicking the model.

Navigation

By default a thumbnail navigation slider is enabled underneath the viewer to guide user's movement between viewpoints.

Auto-slideshow

The auto-slideshow is an animation that will cycle through viewpoints after the model loads with customizable 3D movements on each "slide". Once the user initializes a click or touch event on the viewer the slideshow will stop, and the model will become freely interactable. By default there is no slideshow configured.

Direct Embed

Include the SDK script:

<script defer src="https://cdn.arcsineimaging.com/scripts/1.0.2/sdk.bundle.js"></script>

A viewer can be embedded directly in HTML without any scripting.

<div arcsine-viewer="your-project-id"></div>

This will load a model with the default configuration. The viewer will scale to the size of its container element so make sure this has a non-zero width and height.

Javascript Embed

Start by creating the SDK script and waiting for it to load.


// Create the script
const sdkScript = document.createElement('script');

sdkScript.src = 'https://cdn.arcsineimaging.com/scripts/1.0.2/sdk.bundle.js';
sdkScript.defer = true;

sdkScript.onload = () => {
  // window.arcsineImaging is now defined.
  // API code goes here.
};

// Load the script
document.head.appendChild(sdkScript);

When the SDK loads, the Javascript API is accessible under window.arcsineImaging.

To initialize a viewer:


const viewer = window.arcsineImaging.createViewer(document.getElementById('viewer-container'), {
  id: 'your-project-id',
  initialViewpoint: 1,
  autoLoad: false
});

To load the model:


// Load is asynchronous and returns a promise.
viewer.load().then(() => {
  console.log('loaded!');

  // Now you can control the viewer with API methods.
});

Configuration

You can define a custom configuration with HTML attributes.

<div
  arcsine-viewer="your-project-id"
  initial-viewpoint="1"
  navigation="none"
  auto-slideshow-order="[1, 2, 3]"
>
</div>

All elements with the arcsine-viewer attribute set will be automatically targeted by the SDK script and populated with a viewer instance. You can configure the viewer by setting these additional HTML attributes.

HTML Javascript Description
arcsine-viewer id The ID of your project.

This configuration option is required
initial-viewpoint initialViewpoint The ID of the initial viewpoint. Currently detail viewpoints are unsupported for this option and may not render correctly.

Default: true
auto-load autoLoad Whether the model should load automatically. If false the model won't load until the container element receives a click event. The placeholder image will be shown in its place.

Default: true
navigation-order navigationOrder Array of viewpoint IDs to include in the navigation bar in the order they appear from left to right. ex. [3, 1, 0, 5]

Default: Every viewpoint ordered by ID
navigation navigation The type of viewpoint navigation bar to display. Currently thumbnails or none are supported.

Default: thumbnails
transition-duration transitionDuration Duration in milliseconds of viewpoint transitions initiated by user interaction.

Default: 1200
auto-slideshow-order autoSlideshowOrder Array of viewpoint IDs to transition through. ex. [1, 2, 3, 4]

Default: No slideshow configured.
auto-slideshow-durations autoSlideshowDurations Array of durations in milliseconds for each viewpoint transition in the slideshow to take. ex. [600, 800, 500, 500]
Pass a single value to apply it to every slide, ex. 1000

Default: Value configured in transition-duration
auto-slideshow-delays autoSlideshowDelay Array of times in milliseconds representing how long to dwell on each viewpoint. ex. [1000, 2000, 3000, 1000]
Pass a single value to apply it to every slide, ex. 1000

Default: 2000
auto-slideshow-orbit-angles autoSlideshowOrbitAngles Array of directions (in degrees clockwise from up) to orbit towards when a slide is active. Use 0 for no rotation. ex. [0, 90, 180, 270, 360] would rotate [none, right, down, left, up].
Pass a single value to apply it to every slide, ex. 95

Default: 0
auto-slideshow-ken-burns autoSlideshowKenBurns Array of booleans that define whether the camera should slowly dolly in while a slide is active. ex. [false, true, false, false]
Pass a single value to apply it to every slide, ex. true

Default: false
auto-slideshow-repeat autoSlideshowRepeat Whether to restart the slideshow when it reaches the last viewpoint in its auto-slideshow-order.

Default: false

Supported Browsers

Unsupported browsers (IE11 & older) will show a simplified, non-3D experience. We query the browser's feature set to determine compatibility. You can use window.arcsineImaging.isSupportedBrowser before loading a viewer to implement special behavior in this case.


Global Object

Available through window.arcsineImaging after the initial script loads.


createViewer(container: HTMLElement, options: Object): ArcsineViewer

Initialize a viewer embed inside of the passed container. The viewer will scale to the size of the container.


viewers : [ArcsineViewer]

Array of initialized viewer objects.


isSupportedBrowser : Boolean

Whether the client’s browser contains every feature needed to display the viewer.


ArcsineViewer Instance


element: HTMLElement

Element containing this viewer.

load(): Promise

Asynchronously load the model’s assets. This is called automatically if autoLoad is set to true.
setViewpointById, getViewpointById, getCurrentViewpoint and getViewpoints can only be called after the returned Promise resolves.


getViewpointById(id: Number): Viewpoint

Returns the viewpoint with the passed ID or null if none match.


setViewpointById(id: Number): Promise

Perform an animated transition to passed viewpoint ID. The returned promise resolves when the transition is complete.


getCurrentViewpoint(): Viewpoint

Returns the current viewpoint being projected onto the model.


getViewpoints(): [Viewpoint]

Returns an array of available viewpoints for this model.


resize()

Resizes the underlying <canvas> to fit the viewer's parent element.


addEventListener(eventName: String, listener: Function)
removeEventListener(eventName: String, listener: Function)
Event Name Listener Argument Fired When
viewer-ready None Viewer is fully loaded and interactable. As a convenience, an arcsine-viewer-ready class will be added to the viewer's container element when this event is fired.
viewpoint-id-changed id : Number Transition to new viewpoint finishes
auto-slideshow-finished None Auto slideshow stops playing

Viewpoint Instance

id : Number

detail : Boolean

Whether this is a cropped, zoomed-in viewpoint.


Examples

Initializing a viewer with dynamically created custom buttons that control the current viewpoint.


<div id="viewer-container" style="width: 600px; height: 400px;">
</div>

<div id="button-container">
</div>


<script>

// Initialize viewer that will wait for a load() call to fetch assets
//
const viewer = window.arcsineImaging.createViewer(document.getElementById('viewer-container'), {
  id: 'your-project-id',
  initialViewpoint: 0,
  autoLoad: false
});

const buttonContainer = document.getElementById('button-container');

const highlightViewpoint = (id) => {
  buttonContainer.querySelectorAll('button').forEach(el => {
    el.classList.remove('active');
  });

  const button = buttonContainer.querySelector('button[data-viewpoint="' + id + '"]');
  button.classList.add('active');
};


const createButton = (viewpoint) => {
  const button = document.createElement('button');

  // Fetch the viewpoint's associated button.
  button.innerHTML = viewpoint.id;
  button.setAttribute('data-viewpoint', viewpoint.id);

  // Animated transition to this viewpoint.
  button.addEventListener('click', () => {
    viewer.setViewpointById(viewpoint.id);
  });

  buttonContainer.appendChild(button);
}

// Large web requests for textures/model begin here
//
viewer.load().then(() => {
  const viewpoints = viewer.getViewpoints();

  viewpoints.forEach(vp => {
    createButton(vp);
  });

  // Bind to viewpoint-id-changed so highlighted button will update when user
  // interacts with the model.
  viewer.addEventListener('viewpoint-id-changed', highlightViewpoint);
});

</script>