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.

• Overview
  • Direct Embed
  • Javascript Embed
  • Configuration
• API
• Examples
• Additional Information

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.3.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.3.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.

API

Global Object

Available through window.arcsineImaging after the initial script loads.

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

Array of initialized viewer objects.

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

ArcsineViewer Instance

Element containing this viewer.

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.

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

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

Returns the current viewpoint being projected onto the model.

Returns an array of available viewpoints for this model.

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

Viewpoint Instance

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.

Viewpoint's vertical field of view in radians.

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

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

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

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

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

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>

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.

Copyright

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.