Getting started with the Dimensions 3D Viewer

Getting Started

The Dimensions 3D Viewer can be integrated easily using the Dimensions Tag and a few lines of Javascript.

Be sure to add the scripts mentioned in the article linked above before proceeding with the instructions below.

You should have a container marked with the correct attributes that tell the Tag where to embed the Viewer within your page. This article explains it in detail. Here's a quick example:

<div
   id="my-3d-viewer"
   data-d8s-type="3d"
   data-d8s-id="my-product"
></div>

* The "my-product" ID attribute refers to the SKU identifier used when creating the Product details in Dimensions. Set it to the one you'd like show

Configuration

The Viewer offers several parameters that help customize it to your requirements.

Viewer parameters can be set during initialization or using the update method. Next, we'll take a look at both.

Initialization

<html> 
   <head>
     ...
   </head>
 
   <body>
      .... 
      <script>
        const d8sApi = initDimensions({
           account: "my-account-name", 
           viewers: ["3D"],
           
            threeDViewer: {
                 viewer: {
                    controls: {
                      position: "flex-start",
                    },
                 },
             },
        });
      </script>
   </body> 
</html>

The threeDViewer.viewer properties are passed to the 3D Viewer when its rendered onto the page.

In this example, we're setting the position of the controls shown on the bottom of the viewer, moving them to the left:

Update

Once the Viewer is rendered, it is still possible to affect the various parameters that control the behavior and look&feel:

 <script>
     const d8sApi = initDimensions({ ... });

     d8sApi.update3d(
                document.getElementById("my-3d-viewer"),
                { 
                    controls: { 
                      position: "center" 
                    } 
                } 
      );
 </script>

Result:

The update method expects to receive the container hosting the viewer as the first parameter. The second parameter is the object containing the viewer properties to update.

Note: There is no need to pass any of the params that were passed during initialization - the Viewer will merge the updated ones with those received before.

Reference

The following parameters control the behavior and look&feel of the Viewer. The values shown here are the defaults used:

{   
  //automatically show the iframe
  autoShow: true,
  
  //show the progress bar when loading
  showLoadingProgress: true,

  controls: {
     //show the controls at the bottom of the viewer
     enabled: true,
  
     //where to place the button controls (css justify-content value)
     position: "flex-end",

     //whether to show the zoom +,- buttons
     zoom: true,

     //whether to allow mouse scroll-wheel zoom
     mouseZoom: true,

     //allow orbit controls rotate,
     rotate: true,
     
     //allow orbit controls pan,
     pan: true, 
  },

  rotation: {
     //whether to enable rotation of the model
     enabled: true,
    
     //auto rotate speed
     speed: 2,

    //turn off rotation when user starts to interact with the model
    offOnInteraction: false,  
  },

  ar: {
     //whether to show the AR view button
     enabled: true,
     
     //placement to use for (Android-only) AR viewer: "floor" or "wall" 
     placement: "floor",
     
     //A name for the model. If present, it will be displayed in the UI (Android-only). The name will be truncated with ellipses after 60 characters.
     title: "",

     //A URL for an external webpage. If present, a button will be surfaced in the UI (Android-only) that intents to this URL when clicked.
     link: "",
     
     //Whether the model is resizable inside the (Android-only) AR view
     resizable: true,

     //a function that renders a custom overlay for the AR-QR code
     customArQrRenderer: null,
  },  


  styles: {
    //"light", "dark", { custom }
    theme: "light",
  },
}

Theme Reference

The Viewer has two built-in themes: light & dark.

Light Theme

The light theme is appropriate to use when the hosting site/app uses a light background. It is used by default.

These are its values:

{
   "bgPrimary": "#FFF",
   "bgSecondary": "#D1D6E0",
   "primary": "#000",
   "secondary": "#888686",
   "progress": "#3348c5",
   "border": "#D1D6E0",
   "borderHover": "#000",
   "overlay": "rgba(10,12,15,0.25)",
   "shadow": "rgba(33, 32, 32, 0.75)",
   "bgHotspot": "#b4c9f3",
}

Dark Theme

The dark theme is appropriate to use when the hosting site/app uses a dark background.

These are its values:

{
   "bgPrimary": "#000",
   "bgSecondary": "#12171d",
   "primary": "#FFF",
   "secondary": "#dddddd",
   "progress": "#0d9aff",
   "border": "#3D475C",
   "borderHover": "#FFF",
   "overlay": "rgba(10,12,15,0.25)",
   "shadow": "rgba(204,202,202,0.75)",
   "bgHotspot": "#255ccc",
}

Custom

In case you'd like to change any or all of the colors used by the Viewer's theme, it's possible to pass an overriding object with the desired values to the styles.theme configuration parameter.

When passing a subset of the theme values, they will be merged with the light theme.