Skip to main content

Jewellery and Diamonds

Plugins, notes and guidelines for diamond and jewellery rendering for e-commerce websites.

Model preparation

Before moving to the rendering part, there are a few things to note white preparing the 3D models for jewellery. We recommend using blender for importing, assigning materials, configuring diamond geometries, and optimisation.

Some key points to consider are:

  • Keep the poly/tri count to small numbers(<100k triangles is ideal) without sacrificing quality for universal web rendering
  • All individual diamond geometry/mesh should be a separate node, with same/different materials.
  • Use GLTF DRACO compression to reduce the model size. Note: This is done automatically in our sandbox editor.
  • Don't use ultra-high resolution textures (>4096).
  • Use instanced geometries wherever possible.
  • Don't apply 'mirror' operations on diamond geometries while duplicating/instancing them (Duplicate and move/rotate/scale them). Mirroring will cause issues with the diamond rendering while computing internal refraction when using the same cacheKey

Configuring diamond geometries

Diamonds can be marked in the sandbox editor with a cacheKey. Material Library support(coming soon) will make this easier.

For more granular control it is possible to mark the diamond materials in the GLTF with a custom extension. For blender we have an open source add-on to add details while exporting GLTF files. It can be downloaded separately from:

The below tutorial explains how to use blender to prepare 3d models and configure diamonds for best visual results and performance using this addon.


Make sure the normals in the geometries are correct and pointing outside the mesh.

Diamond Rendering

DiamondPlugin adds the functionality for importing, rendering, managing and exporting diamond materials in the viewer. DiamondMaterial is designed for high quality diamond stone rendering but it is also used to render a variety of gem stones and glass objects with realtime simulation of light rays optimised for total internal reflection and refraction. While being very versatile, at the moment it is limited to convex shaped geometries for accurate results.

To use this add the plugin after viewer initialisation:

import { 
DiamondPlugin, //...
} from "webgi";
... // your code
const viewer = ...
... // viewer setup and other plugins.
const diamondPlugin = await viewer.addPlugin(DiamondPlugin);

Environment Map

All diamond materials can use a separate environment map than the rest of the scene. This is a recommended option as diamonds generally need a more vibrant environment to have the shine than metals. To set an environment map only for diamonds in the scene:

// First import the env map
const diamondEnvMap = await viewer.getManager().importer.importSinglePath<ITexture>('')
diamondPlugin.envMap = diamondEnvMap

// if a separate envMap is specified it is also possible to set the envMapRotation
diamondPlugin.envMapRotation = Math.PI / 2.0

Environment map intensity

Since its possible(and recommended) to load a separate environment map, the envMapIntensity is tracked(and serialised) separately for each material. The scene setting will not work for diamonds, and must be set separately for each instance of DiamondMaterial.

Material Properties

  • Color - Color or tint of the material
  • Refractive Index - This takes the physical refractive index of the material. Diamond stones generally have the value of 2.4 but it can vary for different stone types. It's possible to simulate simple refractive glass material by setting this in range 1.4-1.7. Check this chart for a list of values for different elements
  • Dispersion - This value controls how much the light is dispersed into R, G and B components. Keep this value very low to get small but noticeable highlights
  • Transmission - It is possible to simulate limited transparency/transmission through the object. This uses a screen space refraction technique and may have some limitations. When used properly it can add another level of realism to the models.
  • Oriented Lighting - If set to 1.0, the environment map is oriented to the model top. This is useful when same lighting(and cuts) is expected irrespective for the model position and rotation. (like when a diamond ring is standing vs kept on the ground)
  • Absorption - Controls how much the light is absorbed while travelling inside the material.

cacheKey and normalMapRes

DiamondMaterial internally uses some acceleration data structures for high performance. With this, it is possible to render 100s of objects at once without losing any performance, given that the number of unique model shapes is small. It is recommended to use meshes with the same geometry instance in the model so that similar diamonds are grouped, which also reduces the model size. But, sometimes it is not possible to use the same instance, even though the diamond shape is same. For this, it is required to set a unique cacheKey value for the material or the object. The same value must be used on all objects with the same shape, this groups the objects and the resources are shared. It is possible to set the normalMapRes parameter to control the quality of the simulation and therefore the cuts. 512 is generally a good value, but can be set to 1024 if the number of gemstones are limited or 256 for a lot of small gemstones.


All individual diamonds must be a separate object/mesh, so that light simulation can be done separately for each.

DiamondPlugin API

Using the DiamondPlugin, it is possible to prepare diamond meshes and create custom materials for the diamond gemstones.

Converting to a diamond material and mesh

makeDiamond is a function that converts any material assigned on an object to a DiamondMaterial and replaces it on all the meshes using the material. Usage:

{normalMapRes: 256, cacheKey:'_')[0].split('-')[1]},
{isDiamond: true, color: 0xa1a1f0, refractiveIndex: 2.4}

Assigning an existing diamond material

Diamond materials can be created using our editor and downloaded as a .dmat file. These files can be loaded and assigned to any object to render the gemstones properly. The mesh needs to be prepared before setting the material. Usage:

// Load the material from a file
// This would be an instance of `DiamondMaterial`
const dMat = await viewer

// Find the mesh
const mesh = viewer.scene.findObjectsByName('diamond')[0];

// Prepare the meshes where the material needs to be applied.
.prepareDiamondMesh(mesh, { cacheKey: "d1", normalMapRes: 512 });

// Assign the material

Diamond meshes needs to be prepared once. If the prepareDiamondMesh is called multiple times for the same mesh and the same parameters, it will not do the computation again.


If a mesh with a DiamondMaterial is not prepared, it will appear black without a warning.

Metallic Rendering

All metals in a jewellery model must use a Standard or Physical material. This is called Principled BSDF in Blender or more generally PBR (Physically based rendering). For metallic objects, the metalness property must be set to 1.0 to get the correct rendering.

All Physical materials use the scene environment map, rotation and intensity values. While possible, it is not recommended to set the envMap property separately for metallic objects and the same global is used.

Metals look good with Screen Space Reflection turned ON, with which we can see self reflections and showing indirect light from nearby objects.

Anisotropic Metals.

See AnisotropyPlugin Documentation coming soon.

Jewellery engraving

Coming soon.