Documentation

Updated 24 June 2021

Overview

The Arcsine viewer represents an interactive 3D scene containing a model to view, select camera viewpoints to view the model from, and floating buttons to navigate to certain viewpoints. The viewer also handles a number of user input events to enable intuitive movement through this scene.

A key element of the viewer that distiguishes this technology from other 3D viewers is the notion of viewpoints. Each viewpoint defines a virtual camera position that perfectly aligns the camera's view of the model to a specific product photo. Selecting a viewpoint, through either interaction or code, will move the camera to view the object from the specified angle. Viewpoint data isn't loaded until it is viewed for the first time.

To use the viewer, an instance of it can be embedded directly through HTML, or through our Javascript SDK, with customization available in both methods.

Direct Embed

Include the SDK script:

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

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

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

All elements with the arcsine-viewer attribute set will be automatically targeted by the SDK script and populated with a viewer instance. This example 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 including the SDK script:

<script src="https://cdn.arcsineimaging.com/scripts/2.0.1/sdk.bundle.js"></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',
});

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

Direct embeds can be customized with HTML attributes while Javascript embeds use an options hash. These two examples are equivalent.

<div
  id="viewer-container"
  arcsine-viewer="your-project-id"
  initial-viewpoint="1"
  navigation="none"
>
</div>
const viewer = window.arcsineImaging.createViewer(document.getElementById('viewer-container'), {
  id: 'your-project-id',
  initialViewpoint: 1,
  navigation: 'none'
});

This table provides an overview of viewer configuration options, their Javascript property name, corresponding HTML attribute, and default values.

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

This configuration option is required
initialViewpoint initial-viewpoint The ID of the initial viewpoint.

Default: 0
initialAnimation initial-animation Type of animation to play when the viewer loads. Currently slideshow, turntable, scroll and none are supported. This should be used in combination with an animation configuration.

Default: none
autoLoad auto-load 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
navigationOrder navigation-order 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 Type of viewpoint navigation bar to display. Currently thumbnails or none are supported.

Default: thumbnails
expandable expandable Whether to include UI to expand the viewer to fill the browser window.

Default: true
backgroundOpacity background-opacity Background fill color overlay opacity. Valid range is [0.0, 1.0]

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

Default: 1200
animations See animations documentation.
viewpointFraming See viewpoint framing documentation.

Animations

Animations make it possible to move the camera to different viewpoints without direct user interaction. Currently there are three kinds of animations: turntable, slideshow, and scroll, each described below.

Animations are configured through the animations property. The animation set to play once the viewer loads can be configured through the initialAnimation property. Once the user initializes a click or touch event on the viewer the animation will stop, and the model will become freely interactable.

Multiple animations can be configured and controlled at runtime through the viewer.stopAnimation() and viewer.startAnimation() API calls.

const viewer = window.arcsineImaging.createViewer(document.getElementById('viewer-container'), {
  id: 'your-project-id',
  initialAnimation: 'turntable',
  animations: {
    turntable: {
      // options
    },
    slideshow: {
      // options
    },
    scroll: {
      // options
    }
  }
});

Turntable

The turntable animation will rotate the model around the scene's vertical axis at a constant speed. This animation will only play if the current viewpoint is an outer type.

{
  turntable: {
    speed: 0.5,              // Speed of the rotation. Negative values are counter-clockwise, positive are clockwise.
                             // Valid range is [-1.0, 1.0].
                             // Default: 0.25

    startingViewpointId: 0,  // Viewpoint to transition to when starting the turntable animation.
                             // Default: Value configured in `initialViewpoint`
  }
}

Slideshow

The slideshow animation will cycle through viewpoints and perform customizable 3D movements on each "slide".

{
  slideshow: {
    repeat: false,                // Whether to restart the slideshow when it reaches the last viewpoint in the sequence.
    sequence: [
      {
        viewpointId: 0,           // Active viewpoint for this slide.
                                  // Required.

        slideDuration: 2000,      // Time in milliseconds representing how long to dwell on each viewpoint.
                                  // Default: 2000

        zoom: true,               // Define whether the camera should slowly dolly in while a slide is active.
                                  // Default: true

        orbitAngle: 270,          // Direction of orbit in degrees clockwise from up. Valid range is [-360, 360]. Pass 0 to disable.
                                  // Default: 0

        transitionDuration: 1500  // Duration in milliseconds for transition to the next viewpoint in the sequence.
                                  // Default: Value configured in top-level `transitionDuration`
      }

      //
      // Additional steps in the slideshow sequence.
      //
    ]
  }
}

Scroll Experimental

This is an experimental feature and the API may be subject to change in future releases.

The scroll animation will cycle through viewpoints and perform interpolated 3D movements based on the user's scroll position. It is usually used with a viewer styled with position: sticky; pointer-events: none; so that animations stay within the viewport and aren't disabled by touch events while scrolling. The animation is active when the top of the passed in boundingElement is above the top of the browser's viewport.

<!-- (scroll-animation-bounds height) = (viewer height) + (sum of sequence heights) -->

<div id="scroll-animation-bounds" style="height: 2100px; position: relative;">
  <div id="viewer-root" style="height: 600px; position: sticky;"></div>
</div>
{
  scroll: {
    boundingElement: document.getElementById('scroll-animation-bounds'),
    sequence: [
      {
        viewpointId: 1,        // Active viewpoint for this portion of the scroll animation.
                               // Required.

        orbitAngle: 90,        // Direction of orbit in degrees clockwise from up. Valid range is [-360, 360]. Pass 0 to disable.
                               // Default: 0

        orbitDistance: 25,     // Distance to orbit in degrees.
                               // Default: 0

        zoomDistance: 0.5,      // Distance in centimeters to dolly forward/backwards.
                               // Default: 0

        height: 500            // Vertical scroll distance in CSS pixels wherein this viewpoint will be shown.
                               // Required.
      },
      {
        viewpointId: 2,
        height: 500
      },
      {
        viewpointId: 3,
        height: 500
      }
    ]
  }
}


Viewpoint Framing

Viewpoint framing allows for viewpoints to be repositioned to better fit alongside page content, while maintaining the size and position of the viewer. This provides tighter control over how 3D content fits on the page as the viewer animates. Field of view is used to set the zoom of the viewpoint and the X & Y shifts control the pan. This feature is only available when using a Javascript embed. The viewpointFraming property can be used to customize framing before the viewer loads.

const viewer = window.arcsineImaging.createViewer(document.getElementById('viewer-container'), {
  id: 'your-project-id',
  viewpointFraming: {
    0: {                // Viewpoint ID for which the framing values will apply.

      fov: 2.0,         // Zooms camera to 200% of the viewpoint's intrinsic field of view.
                        // Valid range [0.25, 2.5]
                        // Default: 1.0

      shiftX: 0.5,      // Shifts camera right by 50% of viewport width.
                        // Valid range [-1.0, 1.0]
                        // Default: 0.0

      shiftY: -0.1      // Shifts camera down by 10% of viewport height.
                        // Valid range [-1.0, 1.0]
                        // Default: 0.0
    },
    4: {                // Additional viewpoints can be configured
                        // Omitted viewpoints or properties will retain their default values.
      shiftX: 0.1
      shiftY: 0.4
    }
  }
});

Additionally, viewport framing can be globally configured at runtime with viewer.enableViewpointFraming() and viewer.disableViewpointFraming(), or configured at the viewpoint level with viewpoint.setFov(), viewpoint.setShiftX(), and viewpoint.setShiftY().

API

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.
All API methods aside from addEventListener and removeEventListener 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.


startAnimation(animationType: String)

Begin playing the animation specified by the passed animationType. If no animation is configured for this type nothing will play. Any animation that is currently running will stop unless the passed animationType is already playing.


stopAnimation()

Stop any animation that is currently running.


enableViewpointFraming()

Enable viewpoint framing for all viewpoints. Viewpoint framing is enabled by default.


disableViewpointFraming()

Disable viewpoint framing for all viewpoints.


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

Viewpoint Instance

id : Number
type : String

String in the set: { outer, detail, posed-outer }


Viewpoint Framing

Note that viewpoint framing will only be applied after you transition to the viewpoint so applying new framing to the current viewpoint will not take immediate effect.

setFov(scale: Number)

Scale the viewpoint's intrinsic field of view by the passed value. Valid range is [0.25, 2.5].


setShiftX(shiftX: Number)

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


setShiftY(shiftY: Number)

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


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.

Previous Versions

Unless otherwise noted this documentation is valid for Arcsine Viewer SDK versions 2.X.X. See the the v1 docs for information on previous versions.

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.