The Dimensions 3D Viewer provides a client-side (JS) API to support developers seeking to implement a product configuration experience in their web applications.
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
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.
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