Documentation (v1)

Updated 16 February 2021

You are viewing documentation for a previous version of the Arcsine Viewer SDK (versions 1.X.X). View the current version.


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.


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.


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


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=""></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 = '';
sdkScript.defer = true;

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

// Load the script

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(() => {

  // Now you can control the viewer with API methods.


You can define a custom configuration with HTML attributes.

  auto-slideshow-order="[1, 2, 3]"

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.

Default: 0
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


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.


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, the 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.

Viewpoint Framing

Field of view and lens shift can be configured for individual viewpoints. This can be useful in certain situations if you need to fit page content next to certain viewpoints while maintaining a large canvas for transitions.
Framing will only be applied after you transition to the viewpoint so applying new framing to the current viewpoint will not take immediate affect. Use the initialFov, initialShiftX and initialShiftY configuration options to apply framing to the initial viewpoint.

fov : Number

Viewpoint's vertical field of view in radians.

setFov(fov: Number)

Set the viewpoint's fov. Valid range is (0, π) radians.

shiftX : Number

Viewpoint's horizontal lens shift. This is a 2D offset applied to the camera frame.

setShiftX(shiftX: Number)

Set the viewpoint's horizontal lens shift. Valid range is [-0.5, 0.5].

shiftY : Number

Viewpoint's vertical lens shift. This is a 2D offset applied to the camera frame.

setShiftY(shiftY: Number)

Set viewpoint's vertical lens shift. Valid range is [-0.5, 0.5].


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

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

<div id="button-container">


// 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 => {

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

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

  // Fetch the viewpoint's associated button.
  button.innerHTML =;

  // Animated transition to this viewpoint.
  button.addEventListener('click', () => {


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

  viewpoints.forEach(vp => {

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


Additional Information

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.


All models and photographs appearing on this site are the property of Arcsine Imaging, LLC. They are protected by U.S. Copyright Laws, and are not to be downloaded or reproduced in any way without the written permission of Arcsine Imaging, LLC.