Getting started with the Dimensions 3D Product Configurator API

The Dimensions 3D Viewer provides a client-side (JS) API to support developers seeking to implement a product configuration experience in their web applications.

Explore Live Demo

If you're not familiar yet with how to get started with the viewer go ahead and read this article first: Getting started with the Dimensions 3D Viewer.

Once you have the viewer set up on your page and loading a model, you can make changes to colors, textures and parameters.

Here's the basic code to get the model showing on your page:

<body>
   <div id="three-d-viewer"
      style="height: 400px" 
      data-d8s-type="3d"
      data-d8s-id="prod-identifier"> 
</div>


<script>
     const d8sApi = initDimensions({
          account: "my-account-name", 
          viewers: ["3D"],
     });
</script>

</body>

The tag takes care of rendering the viewer inside the three-d-viewer container.

Texture configuration

Texture configuration uses two parts:

textures

Is an array of objects containing the information to set on a mesh. The object isn't referring to a specific mesh.

currentTexture

Is an array of objects that map the name of the mesh in the model with the texture information index found in the textures array discussed above.

Let's start with a simple example of changing the color of a material that's part of the model.

Note: You do need to know how the 3D model is structured and the names of the meshes in order to apply these changes.

d8sApi.update3d(
  //the container of the 3D viewer:
  document.getElementById("three-d-viewer"), 

  //the configuration to update the viewer with:
  {
    productConfigs: [
      {
         materialParams: {
           color: ["rosybrown"] 
         }
      }
    ],
    activeConfigs: [
      { mesh: "myMesh", configIndex: 0 }
    ]
  }
);

In the code sample above, we're only setting the material color of the mesh called: "myMesh". to the string "rosybrown".

Note: The color value can be Hexadecimal, RGB string, X11 color name, HSL string

Explore Live Demo

Advanced Example

Let's take a look at a more advanced example - changing texture maps:

d8sApi.update3d(
  document.getElementById("three-d-viewer"), 
  {
    productConfigs: [
      {
        url: "https://mysite.com/data/textures/brushed_base.jpg",
        roughnessUrl: "https://mysite.com/data/textures/brushed-roughness.jpg",
        normalUrl: "https://mysite.com/data/textures/brushed-normal.jpg",
        textureParams: {
          repeat: 4,
        },
        materialParams: {
         opacity: 1,
         bumpScale: 0.7,
         normalScale: 0.5,
         roughness: 1.2,     
        },
    ],
    activeConfigs: [
      { mesh: "myMesh", configIndex: 0 }
    ]
  }
);

In the sample above we're instructing the viewer to change several maps by loading external map files (images) that will be applied.

In addition, we're setting the repeat value to ensure the textures look right.

Additionally, we set new values for several material properties such as opacity, bumpScale, etc.

See the reference below for the list of textures and values that can be set.

Mesh Nesting

It's common for the mesh to be several levels deep within the hierarchy of the model's structure. In order to support this, the name of the mesh may contain dot notation to determine the path to the mesh object. For example:

 activeConfigs: [
      { mesh: "scene1.global.mesh1.mesh2", configIndex: 0 }
    ]

This example will set the texture at index 0 on the 'mesh2' object whose parent is 'mesh1' and so on.

Explore Live Demo

Reference

Maps

url: string - replace the color map.
roughnessUrl: string - replace the roughness map
normalUrl: string - replace the normal map
alphaUrl: string - replace the alpha map

textureParams

repeat: number - sets the texture repeat value

materialParams

Any material single value property that's allowed by three.js. Common properties are: bumpScale, normalScale, roughness, metalness, opacity, etc.

meshParams

visible: boolean - show/hide the mesh