Getting Started

Paragram enables you to embed high-fidelity, fully configurable 3D models into your website. Here you'll learn the basics of integrating the Paragram Viewer into your website.


What is the Paragram Viewer?

The Paragram Viewer is simply an HTML iframe that acts as a window into your 3D scene. The Viewer handles all of the cross-platform user interaction such as rotating and zooming, and can also be interacted with via our client-side APIs.


How Does Configuration Work?

We build all of the logic that defines how your 3D model can be configured - whether that's showing/hiding parts of the model, changing materials or even enabling/disabling options based on advanced rules. Once the configuration has been set up, our client-side APIs can be used to configure the 3D model in a simple and intuitive way.


Client-Side APIs

Our client-side APIs allow you to interact with and configure your 3D model using simple Javascript.

  • Viewer API - The Paragram Viewer API allows you to configure your 3D model programmatically with methods such as selectOption and unselectOption.
  • Viewer UI - The Paragram Viewer UI allows you to configure your 3D model visually by automatically building a user interface and placing it within your webpage.

Embedding the Paragram Viewer

You can embed the Paragram Viewer anywhere that supports an HTML iframe. The Viewer will automatically fill the iframe responsively, so be sure to define its width and height.

<iframe src="path/to/your/viewer" style="width:100%; height:100vh;"></iframe>

URL Parameters

You can customize the appearance of the iframe with the following URL parameters:

Parameter Values Description
uiLoader 1 or 0 Enable or disable the default loading bar
uiConfiguration 1 or 0 Enable or disable the default configuration UI
uiResetControls 1 or 0 Enable or disable the default "reset controls" button
uiAR 1 or 0 Enable or disable the default "augmented reality" button

Using the Viewer API

The Paragram Viewer API allows you to configure your 3D model programmatically using simple Javascript.


Add the Viewer API script tag to your HTML page

Include a <script> tag referring to the Paragram Viewer API script. We recommend adding this element somewhere in the <body> element of the page.

<script src="https://code.paragram.io/1.2.10/ParagramViewerAPI.js"></script>

Instantiate the Viewer API

Instantiate the ParagramViewerAPI, passing in a query selector for your iframe element.

<script>
  const api = new ParagramViewerAPI('#viewerFrame');
</script>
          
<iframe id="viewerFrame" src="path/to/your/iframe.html"></iframe>

Configure the 3D Model

Use the selectOption and unselectOption methods to configure the 3D model.

api.selectOption('someOptionGroupID', 'someOptionID');
api.unselectOption('someOptionGroupID', 'someOptionID'); // only necessary for "select multiple" fields


Listen to Viewer Events

The Paragram Viewer API triggers custom events such as paragramViewerLoaded and paragramViewerStateChanged that can be useful for performing actions when the Viewer is finished loading or the configuration state has changed.

window.addEventListener('paragramViewerLoaded', function() {
  document.querySelector('#customLoadingSpinner').remove();
});

Viewer API Reference


Methods


api.selectOption(optionGroupID, optionID)

Use this method to select an option. Typically you will call this method in the onchange event of a checkbox or radio input on your webpage.


api.unselectOption(optionGroupID, optionID)

Use this method to unselect an option. This is only applicable to "select multiple" option groups. Typically you will call this method in the onchange event of a checkbox input on your webpage.


api.transitionControls(controlsID)

Use this method to initiate a transition to a different camera controller.


api.resetControls()

Use this method to reset to the default camera view.


api.showSpatialUI()

Use this method to show spatial UI elements (e.g. annotations).


api.hideSpatialUI()

Use this method to hide spatial UI elements (e.g. annotations).


api.getImageDataURL(callback)

Use this method to generate a base64 encoded image. The returned image data is a JPEG with 80% quality.


Text Personalizations


api.setTextPersonalizationValue(optionGroupId, value)

Use this method to set the value of a text personalization.


api.setTextPersonalizationFont(optionGroupId, fontName)

Use this method to set the font family of a text personalization. fontName must match a font enabled in your viewer.


api.setTextPersonalizationFontSize(optionGroupId, fontSize)

Use this method to set the font size of a text personalization. fontSize must be a number representing pixels.


api.setTextPersonalizationTextAlign(optionGroupId, textAlign)

Use this method to set the horizontal alignment of a text personalization. Valid values are left, right, center, start, and end.


api.setTextPersonalizationTextBaseline(optionGroupId, textBaseline)

Use this method to set the vertical alignment of a text personalization. Valid values are top, bottom, middle, ideographic, and hanging.


Events


paragramViewerLoadingProgress

This event fires when loading progress changes. loadingProgress is a value from 0 to 1.

window.addEventListener('paragramViewerLoadingProgress', (e) => {
  console.log(e.detail.loadingProgress);
});

paragramViewerLoaded

This event fires when loading is complete.

window.addEventListener('paragramViewerLoaded', () => {
  console.log('Paragram viewer loaded!');
});

paragramViewerControlsChanged

This event fires when the camera controller changes. This can be used, for example, to display a "reset controls" button when the user leaves the default camera view.

window.addEventListener('paragramViewerControlsChanged', (e) => {
  console.log(e.detail.controlsIndex);
});

paragramViewerAnnotationSelected

This event fires when an annotation is selected. The optionGroupId and optionId associated with the annotation is provided in the event detail object.

window.addEventListener('paragramViewerAnnotationSelected', (e) => {
  console.log(e.detail.optionGroupId, e.detail.optionId);
});

Using the Viewer UI

The Paragram Viewer UI is an optional script you can include that automatically builds a simple configuration UI in your webpage.


Add the Viewer UI script tag to your HTML page

Include a <script> tag referring to the Paragram Viewer UI script. Be sure to include this after the Paragram Viewer API script.

<script src="https://code.paragram.io/1.2.10/ParagramViewerAPI.js"></script>
<script src="https://code.paragram.io/1.2.10/ParagramViewerUI.js"></script>

Instantiate the Viewer UI

Instantiate the ParagramViewerUI, passing in a query selector for a container element as well as the ParagramViewerAPI instance.

<script>
  const api = new ParagramViewerAPI('#viewerFrame');
  const ui = new ParagramViewerUI('#paragramUIContainer', api);
</script>

<iframe id="viewerFrame" src="path/to/your/iframe.html"></iframe>
<div id="paragramUIContainer"></div>