A complete, runnable example project containing this component is available on GitHub: https://github.com/maanHimself/ijewel-viewer-react-example
### 1. Update `package.json`
Add the following lines to your `dependencies`:
``` json
{
"dependencies": {
// ... other dependencies
"@ijewel3d/mini-viewer": "https://releases.ijewel3d.com/libs/web/ijewel3d-mini-viewer-0.6.17.tgz",
"@types/webgi": "https://releases.ijewel3d.com/libs/webgi-v0/bundle-types-0.22.0.tgz"
}
}
```
### 2. Install Dependencies
``` Bash
npm install
```
### 3. Add WebGI Script
Add the WebGI script before your React app bundle loads.
```html
```
### 4. Usage
Import the `ViewerComponent` from the library and use it in your React application. Provide the necessary props to load your model.
``` typescript
import { ViewerComponent } from "@ijewel3d/mini-viewer";
import { useEffect, useState } from "react";
import type { ViewerApp } from "webgi";
function App() {
const [modelId,] = useState("Ep9bWZIlTSG6_8DH7QDc1w"); // Replace with your actual model ID
const [viewer , setViewer] = useState
Design Your Wedding Band
{price ? `$${price.totalUsd.toFixed(2)}` : 'Loading...'}
:::details NextJS Example
```typescript
useEffect(() => {
const webgiScript = document.createElement("script");
webgiScript.src = "https://releases.ijewel3d.com/libs/webgi-v0/bundle-0.22.0.js";
webgiScript.async = true;
webgiScript.onload = () => {
const script = document.createElement("script");
script.src = "https://releases.ijewel3d.com/libs/mini-viewer/0.6.8/bundle.nowebgi.iife.js";
script.async = true;
script.onload = () => {
//set it to true during development to bypass cors.
const useProxy = false;
const baseName = 'yourBaseName';
const basePath = "https://assets." + baseName + ".ijewel3d.com";
const proxyUrl = useProxy ? "https://cors-proxy.r2cache.com/" : "";
// @ts-ignore
ijewelViewer.setupIjewelDriveViewer({
basePath: proxyUrl + basePath,
ijewelViewerOptions: {
showCard: true,
showLogo: true,
},
}, document.getElementById("wrapper"));
};
document.body.appendChild(script);
};
document.body.appendChild(webgiScript);
}, []);
```
:::
## Parameters
| Parameter | Type | Description | Default |
|--------------------------|--------------|-------------------------------------------------------------------------------------------------------------------------------------|---------------|
| `basePath` | string | The base URL path where your assets are stored. | N/A |
| `model` (Optional) | string | The relative path to the 3D model file inside your iJewel Drive. For instance, if your model is located in a folder named `3dFolder` and the file is called `model.glb`, you would specify the path as `/3dFolder/model.glb`. This path is relative to the `basePath` provided in the configuration. It can be left undefined and the model will be taken from the query parameter `path` inside your iJewel Drive. | N/A |
| `target` | HTMLElement | (Optional) The HTML element where the viewer will be rendered. | null |
| `ijewelViewerOptions` | object | An object with viewer options such as showLogo, logoScale, etc. | N/A |
| `useMetaConfig` | boolean | Whether to use the saved meta configuration file for the 3d model. | true |
| `useFolderConfig` | boolean | Whether to use the parent folder configuration file. | false |
| `useDefaultConfig` | boolean | Whether to use the main default configuration file. | true |
## Setting the Model Path via URL Query Parameter
You can use the query parameter `path` to tell the viewer which model to load. The path to the model should be in Base64 format and relative to the root folder in your iJewel Drive.
For example:
```
www.yourwebsite.com/?path=L3Rlc3QvcmluZy5nbGI
```
In this example, the Base64-encoded string `L3Rlc3QvcmluZy5nbGI` decodes to `/test/ring.glb`, which is the path to the 3D model, once you initilize iJewel Viewer, it will refer to this path to know which model to load.
:::details
Alternatively, you can directly set the model path using the model property in the `setupIjewelDriveViewer` method. This provides a flexible way to specify the model path either through the URL or within your JavaScript code.
:::
:::info
Once you call `setupIjewelDriveViewer` with the correct model path, it will take care of loading the specified 3D model along with all its associated settings. This includes any predefined configurations, materials, and environment settings that have been saved with the model. This seamless integration ensures consistency and ease of access to your models. You can edit your models directly in the drive, save your changes, and see those updates reflected instantly on your website.
:::
## Cross-Origin Resource Sharing (CORS)
CORS is setup on the iJewel Drive to make sure only you can host the models on your domain.
When connecting to your iJewel Drive and loading models, you may encounter Cross-Origin Resource Sharing (CORS) errors in the console. These issues arise because your domain hadn't been whitelisted, please reach to us so we can configure our servers to allow CORS for your domain.
::: tip
For development and staging, a CORS-proxy can be used. Check the pre-configured sample in your iJewel Drive instance on how to use it. Note that this would disable the caching of the files on the CDN and adds a rate limit to the number of requests along with some other checks. Therefore, make sure to disable the flag when using in production to make the viewer running smoothly.
:::
---
# Tutorial - Embed iJewel3D Drive in your website
::: danger Warning
This page is exclusively for iJewel Drive instances created before March 2025.
For new accounts and instances, check the page at [Connect to iJewel Drive](../tutorial-embed-drive.md).
:::
A step by step tutorial on how to embed 3D Models hosting in your iJewel Drive instance to your website.
## Step 1: Set the Base Path and Container Element
Use the following HTML code to embed the 3D viewer:
- Replace `baseName` with your actual base name in the code.
- Identify where to specify the container HTML element. Set this element to embed the viewer correctly.
for more information about the code refer [Connect to iJewel Drive](./connect-to-drive)
```html
What is Playground?
Overview of the platform, features, and what you can do with it
Quick Start
Get up and running in minutes — from first login to your first render
Importing Your First Model
Step-by-step guide to importing your 3D jewelry model into the scene
UI Overview
Left panel, canvas, right panel, toolbar — learn the full interface layout
With iJewel Playground, users can import 3D models, assign materials, set up lighting, apply advanced post processing effects, and create interactive configurators.
Today, thousands of professionals across 60+ countries rely on it daily to visualize, customize, and share their creations with clients.
 ## Key Features ### Real-time Photorealistic 3D Visualization One of the most important features of iJewel Playground is that it is purpose built for real time visualization of luxury products. High-end categories such as jewelry, watches, premium accessories, and automobiles demand exceptional attention to detail in their digital representation. Playground delivers on this need with its rich suite of materials, advanced lighting options, dynamic animations, and powerful post-processing tools, ensuring every product is showcased with unmatched realism and sophistication Instantly preview jewelry and luxury designs with uncompromising realism. Diamonds sparkle, metals shine, and lighting reacts naturally—giving clients a true-to-life experience without hours of offline rendering. ### Intuitive UI/UX Designed for ease of use, the interface is simple enough for first time users yet powerful enough for professionals. Complex 3D workflows are streamlined into clear steps, making it easy to focus on creativity rather than technical hurdles. ### Rich Material Library Access a rich collection of pre built materials designed specifically for jewelry and luxury products including precious metals, antique finishes, diamonds, gemstones, precious stones, car paints, fine fabrics (satin, velvet, cotton, and more), wood, leathers, and many others. Beyond the library, users can also create and fine tune custom materials, giving them complete control over every detail of their designs. ### Extensive Scene Presets Save time with ready to use environments and lighting setups. From elegant studio backdrops to dramatic HDR scenes, complete 3D stages, backgrounds, and ground settings, Playground’s scene presets make it effortless to showcase luxury products under the perfect conditions. With just a few clicks, you can craft unique atmospheres that reflect your brand’s identity and elevate the visual storytelling of your creations. --- # Quick Start  To quickly create a realistic render and get a felling of the workflow in iJewel Playground, follow these simple steps: * Pick one of the sample models * **Apply materials** from metal, diamond, gem, and PBR presets, or customize your own. * **Choose HDR lighting** for a realistic environment reflection and mood. * **Configure the scene** Backgrounds, ground reflections, shadows, and camera setups. * **Adjust Post processing** Apply filters such as reflections, bloom, tone-mapping, ambient occlusion and more. * **Export & share** Download images, videos, or scene presets to showcase your work. Here is a [Quick Introduction Video](https://www.youtube.com/watch?v=P0R38Y2S-b0) --- # Importing Your First Model You can import files into Playground in two simple ways: 1. Drag your file directly into the **Main Canvas Area**. 2. Browse & Select - Click the **Import File** button in the toolbar or editor UI. - Select the file from your local computer.  ::: tip Playground also provides a few **sample models** for a quick start. Perfect for testing workflows before importing your own designs.  ::: --- # UI Overview The iJewel Playground interface is designed to give you both **speed** and **control** while working with your 3D models. Whether you're a beginner or a professional 3D artist, this page will help you understand where everything is and how the interface is organized. ## Interface Layout The Playground is divided into **three main areas**:  1. Left Panel — Presets & quick settings for fast, professional results 2. Canvas (Center) — The live 3D viewport where your models are displayed 3. Right Panel — Professional tools with full control over every setting ::: tip The **left panel** is designed for speed — ready-made presets you can apply with one click. The **right panel** is for precision — complete control over every detail. Both panels work together to give you the perfect balance between convenience and customization. ::: --- ## Canvas (3D Viewport) The canvas is the central area where your 3D model is displayed in real-time. ### Welcome Screen When no model is loaded, you'll see the welcome screen with options to get started:  - **Drag and drop** a 3D file directly onto the canvas - **Select local file** from the right panel to browse your files - **Load a sample** — click one of the sample models at the bottom to start experimenting right away ### Navigation Controls Once a model is loaded, you can navigate the 3D scene: | Action | Mouse | Touch (Mobile/Tablet) | |---|---|---| | **Rotate** | Click & drag | Drag with one finger | | **Zoom** | Scroll wheel | Pinch with two fingers | | **Reposition** | Hold `Shift` + drag | Drag with two fingers | ### Selecting Objects To select an object, simply **click on it**. The selected object will be highlighted with an **orange outline**. Once selected, you can apply materials, add configurators, and adjust settings for that specific object.  ::: tip Click on **empty space** to deselect the current object. ::: ### Canvas Toolbar The toolbar is located on the right side of the canvas, providing quick access to common actions: 
Fullscreen
Expand the viewer to fill the screen
Reset Settings
Remove all custom settings and start fresh
Delete Scene
Clear everything from the canvas
Fit Object to Scene
Auto-frame the selected object or entire scene
Loop Camera Views
Play your saved camera view animation
GLTF Animation
Play animations imported from other software (Blender, etc.)
Auto Rotate
Simple 360° rotation of the model
Capture Snapshot
Download a PNG of exactly what you see — no UI elements
Export GLB
Download all objects and settings as a GLB file
Add Configurator
Appears when an object is selected and has no configurator yet
Edit Configurator
Appears when an object is selected and already has a configurator
HDR Metal
HDRI environment maps optimized for metal reflections — gold, silver, platinum
HDR Gem
HDRI environment maps for diamond sparkle, fire, and brilliance
Background
Solid colors, gradients, and specialty jewelry backgrounds
Scene Presets
Complete setups with HDRI, background, ground & tonemapping — one click
Stage
Professional platforms, display stands, ring boxes, cone stands, snow globes
Ground
Shadow presets — soft shadows, contact shadows, reflective surfaces
Pose
Compute Stable Pose — ring lying flat, standing, or custom angle
Export
Quick image & video export — PNG, JPEG, WebP, MP4 up to 4K
Batch Render
Render multiple outputs at once for batch production
Embed
Generate embed code for your website or e-commerce platform
Branding Settings
Logo, watermark, and brand customization for embeds
Advanced Settings
Environment rotation, intensity, SSBevel shortcut
TryOn
Virtual try-on for rings using AR camera
How it works
Click any object on the canvas → material category icons appear at the top of the left panel → browse and click to apply materials instantly.
Metals
Gold, white gold, rose gold, silver, platinum, antique finishes, enamel, and more
Gems & Diamonds
Diamonds (with/without dispersion), emeralds, sapphires, rubies, fancy colors, inclusions, iridescent
Ceramics
Ceramic finishes in various colors and textures
Pearls
Beautiful pearl presets with realistic iridescence and luster
Other Materials
Turquoise, malachite, lapis lazuli, jasper, carbon, coral, enamel, fabric, leather, marble, wood, and more
Free vs Premium vs Advance
Free
Gems & Materials Basic, Gems Inclusions Basic
Premium
Gems & Materials Extended, Gems Inclusions Basic
Advance
Gems & Materials All, Gems Inclusions All
Materials marked with a 💎 icon require a Premium or Advance plan. See pricing details.
Viewer
Renderer quality & scale, Camera & Field of View, Drop Options
Picking
Hierarchy, Material Library, Diamonds, Transform Controls, Picker, UV Unwrapping, Widgets
Scene
Background / Environment, Ground, Lights, Cameras, HDRi Ground, Gradient SVG
Anti-aliasing
Progressive, Temporal AA, Velocity Buffer (TAA)
Post Processing
SSR, Tonemapping, Bloom, Depth of Field, SSAO, SSBevel, Vignette, LUT & more
Export
Asset Export (GLB), Video Export, Image Export, S3 Connection, Share Link
Animations
GLTF Animations, Camera Views, Viewer Animations, Physics, Pose Plugin
Modifiers
Object Rotations, Extrude Tube Shapes, Simple Text, Parallax, Simplify Modifier
Configurators
KHR Material Variants, Material Configurator, Switch Node
Plugins
Full Screen, Loading Screen, Model Stage, Rhino 3dm Loader, CSS3D Renderer & more
Extras
Virtual Cameras, Rainbow Diamond Coloring, Snow Fall Particles, Wave Ground
Remove Image
Delete the current image from this input
Download Image
Save the current image to your computer
Set/Replace Image
Upload a new image from your computer to replace the current one
From URL
Load an image from a web URL
Cancel
Close the menu without making changes
.glb
3D Models
Import .glb files via drag & drop — your 3D jewelry models with geometry and materials
.pmat
.dmat
.dmat
Materials
Import custom PBR materials (.pmat) and diamond materials (.dmat) — apply or save to library
.vjson
.json
.json
Scene Settings
Import complete scene configurations or individual setting presets
Optimization Guidelines
Best practices for preparing your 3D models for optimal performance in Playground
.OBJ / .OBJ + .MTL
.GLB / .GLTF
.3DM (Rhino)
.FBX
.STL
::: tip Recommended Format for Jewelry
For **jewelry workflows**, the **3DM format** is highly recommended. It supports layers, which Playground reads automatically — based on standard naming conventions, default materials are applied instantly, letting you view your jewelry in a photorealistic way right from the start.
:::
::: warning STL Limitations
**STL format** does not support materials, making it unsuitable unless your model uses only a single material. Additionally, STL files often have unsmoothed normals, which can reduce the visual quality of jewelry models.
:::
---
## Import Methods
You can import files into Playground in two ways:
### 1. Drag & Drop
Drag your file(s) directly into the **Main Canvas Area**. When you first open Playground, the welcome screen provides a clear drop zone:
### 2. Browse & Select
Click the **Import File** button in the toolbar to open a file dialog and select the file(s) from your computer.
::: tip
- You can **drag & drop multiple files** at once to import them together.
- Drop a **folder or zipped folder** with multiple 3D files — Playground will automatically process its contents (including subfolders).
- For **OBJ + MTL** files, make sure both are dropped together to correctly apply material data.
:::
---
## Drop Options
Before importing, you can configure how models are placed in the scene. These settings are located in **Viewer → Drop Options**.
Auto Scale
Automatically adjusts the model's proportions (defined by Auto Radius) to fit the scene.
Auto Radius
Defines the radius by which the model proportions will be scaled.
Auto Center
Ensures the model is positioned at the exact center of the canvas.
✅ Auto Scale OFF — correct alignment
❌ Auto Scale ON — misalignment
See the [Quick Start](./quick-start) guide for more details.
---
## Import Options for Jewelry
Once a jewelry model is imported, Playground will prompt you with a few options to help you get started faster.
### 1. Default Materials
Based on the **layer/material names** assigned in the imported file, Playground will attempt to assign default materials automatically. Click **Yes** to apply the suggested materials.
::: info Default Material Mapping
- `Metal 01`, `Metal 02`, ... → Assigned default **Metal** materials
- `Gem 01`, `Gem 02`, ... → Assigned default **Gem** materials
:::
---
### 2. HDR Map for Gem/Metal
If a model has both **gem/diamond** and **metal** materials, Playground will prompt you to apply a **separate HDR environment map** for each category.
::: tip Recommendation
It is generally recommended to use a **separate HDR environment map** for gems/diamonds and metals. This allows finer control over the look and realism of your jewelry.
:::
---
### 3. Default Material Configurator
If default layers are assigned for **metals** and/or **gems/diamonds**, Playground will prompt you to create a **material configurator** — enabling interactive switching of gem and metal materials in the embedded viewer.
::: tip Editing Configurator
The default configurator can be **edited later** if you wish to change materials or modify the configurator settings. See [Material Configurator](./material-configurator) for details.
:::
::: info
These **Import Options** appear as pop-up prompts immediately after adding a new model, before it is fully loaded into the **Scene Hierarchy**.
:::
---
## Related Pages
- **[Import Materials](./import-materials)** — Load saved PBR and diamond material presets
- **[Import Scene Settings](./import-scene-settings)** — Apply complete scene configurations
- **[FAQ: Importing Models](./faq-import)** — Common questions about importing
---
# Import Materials
iJewel Playground allows you to import your own custom materials and use them alongside the built-in material library. The supported formats are **`.pmat`** (PBR Material) and **`.dmat`** (Diamond Material).
## Supported Formats
| Format | Description |
|---|---|
| `.pmat` | PBR material file — used for metals, ceramics, pearls, etc. |
| `.dmat` | Diamond material file — used for diamonds and other gemstones |
## Two Ways to Import Materials
There are two ways to add a custom material in Playground: **apply directly to an object** or **add to the material library** for reuse across projects.
---
### Method 1 — Apply Directly to an Object
Use this method when you want to quickly apply a material to a specific object without saving it to the library.
1. **[Select an object](./ui-overview#selecting-objects)** on the canvas
2. **Drag and drop** your `.pmat` or `.dmat` file onto the 3D canvas
3. A popup will appear asking: **"Apply material to the selected object?"** — click **Yes** or **No**
4. A second popup will appear asking: **"Apply to all objects using this material?"** — click **Yes** or **No**
::: tip Selective Material Application
These two popups give you precise control over where the material is applied. By answering **Yes** to the first and **No** to the second, you can apply the material **only to the selected object** — even if other objects in the scene share the same original material. This effectively separates the material, allowing different objects to have different looks.
:::
---
### Method 2 — Add to Material Library
Use this method when you want to save a material for reuse across multiple projects. Once added, the material stays in your library and is available anytime.
1. **[Select an object](./ui-overview#selecting-objects)** on the canvas — this opens the material library in the left panel
2. Navigate to the appropriate material category (Metals, Gems, Ceramics, Pearls, or Other)
3. Click the **circle with a plus icon** at the very beginning of the material list
4. Choose the `.pmat` or `.dmat` file you want to upload
5. The material will appear in the library with an **automatically generated preview** thumbnail
To apply the material, simply **click on its icon** in the library — it will be applied to the currently selected object. To remove a material from the library, click the **cross icon** at the top-right corner of its thumbnail.
::: tip
Materials added to the library are persistent — you can use them in other projects without needing to import them again.
:::
::: warning Premium & Advance
Saving custom materials to the library requires a paid plan. **Premium** allows up to **5 saved materials**, and **Advance** allows up to **100**. See [pricing details](https://ijewel.design/pricing) for more information.
:::
---
## Related Pages
- **[UI Overview](./ui-overview)** — Learn about the interface layout, panels, and navigation
- **[Importing 3D Models](./import-models)** — How to bring your 3D designs into Playground
- **[UI Overview — Material Library](./ui-overview#left-panel-—-material-library)** — Browse the built-in material categories
- **[UI Overview — Material Configurator](./ui-overview#material-configurator-canvas)** — Create interactive material switching for your clients
- **[Import Scene Settings](./import-scene-settings)** — Import `.vjson` and `.json` scene configuration files
- **[Export Models](./export-models)** — Export your scene as `.glb`, including materials and settings
- **[Export Materials](./export-materials)** — Export `.pmat` and `.dmat` material files
- **[Export Scene Settings](./export-scene-settings)** — Export `.vjson` and `.json` scene configuration files
---
# Import Scene Settings
iJewel Playground allows you to import scene settings files to quickly apply preconfigured environments, lighting, post-processing, and more. This is especially useful when you want to reuse a look you've already perfected or share setups between projects.
## Supported Formats
| Format | Description |
|---|---|
| `.vjson` | Complete scene configuration — contains all settings: HDR maps, background, ground, post-processing, tonemapping, camera, and more |
| `.json` | Partial settings — contains only specific settings, for example only ground or only tonemapping |
::: info What's inside a .vjson file?
A `.vjson` file is a full snapshot of your scene configuration. It includes everything: environment HDR maps, background color/gradient, ground settings, light positions, post-processing effects (bloom, SSAO, SSR, etc.), tonemapping, anti-aliasing, and camera parameters. Importing one instantly recreates the entire look of a scene.
:::
---
## Two Ways to Import Settings
There are two ways to use settings files: **apply directly to the current scene** or **save to the preset library** for reuse.
---
### Method 1 — Apply Directly to the Current Scene
Use this method when you want to quickly load settings into your active scene.
1. Open your project in Playground
2. **Drag and drop** your `.vjson` or `.json` file onto the 3D canvas
3. The settings are **applied immediately** — you will see the scene update in real-time
::: tip
This is the fastest way to switch between different scene looks. Just drag a different `.vjson` file to instantly change the entire atmosphere of your scene.
:::
---
### Method 2 — Save to Scene Presets Library
Use this method when you want to save a `.vjson` file for reuse across multiple projects. Once added, the preset stays in your library and is available anytime.
1. Open the [left panel](./ui-overview#left-panel-—-presets-quick-settings) and go to the **Scene Presets** tab: Scene PresetsGround tab on the left panel and click the plus icon, just like with Scene Presets. Other partial `.json` files (tonemapping, etc.) can only be applied via drag & drop.
:::
---
## Related Pages
- **[UI Overview](./ui-overview)** — Learn about the interface layout and panels
- **[UI Overview — Left Panel](./ui-overview#left-panel-—-presets-quick-settings)** — Scene Presets and other quick settings
- **[Import Materials](./import-materials)** — Import custom `.pmat` and `.dmat` files
- **[Importing 3D Models](./import-models)** — Bring your 3D designs into Playground
- **[Renderer Settings](./renderer-settings)** — Configure render quality and scale
- **[Export Models](./export-models)** — Export your scene as `.glb`, including settings
- **[Export Scene Settings](./export-scene-settings)** — Export `.vjson` and `.json` scene configuration files
---
# Coming Soon...
---
# Exporting
Everything you create in Playground can be exported. Download 3D models, save custom materials for reuse, back up your scene settings, render high-resolution images and videos, or share an interactive 3D viewer link with your clients.
---
## 3D
Export your full scene as a file.
---
## Materials
Save individual materials for reuse.
.pmat
PBR Materials
Metals, ceramics, pearls — save and reuse across projects
.dmat
Diamond Materials
Diamonds and other gemstones with dispersion & brilliance
.vjson
Scene Settings
HDR, background, ground, post-processing — entire scene look in one file
.json
Partial Settings
Export only specific settings — ground, tonemapping, or other individual presets
.webp
Images
High-resolution renders up to 4K with transparent background support
.mp4
Videos
Turntable, camera views, and 360° rotation videos up to 4K
3D Viewer Link
Generate a shareable link to an interactive 3D viewer for clients and partners
Embed
Embed an interactive 3D viewer directly into your website or e-commerce platform
Export GLB button on the [canvas toolbar](./ui-overview#canvas-toolbar) — this immediately downloads your scene as a `.glb` file with current settings.
---
### Method 2 — Left Panel Export
For a quick export with the option to enable compression:
1. Open the Export tab on the [left panel](./ui-overview#left-panel-—-presets-quick-settings)
2. Enable **Compress** if you want to reduce the file size (uses DRACO compression)
3. Click **Download .glb**
::: tip
Use the left panel export when you need a smaller file for web embedding or sharing. DRACO compression significantly reduces file size with minimal quality loss.
:::
---
### Method 3 — Right Panel (Advanced Export)
For full control over what's included in the exported file, use the **Asset Export** section on the [right panel](./ui-overview#right-panel-—-professional-tools):
1. Open the Export tab on the right panel
2. Go to the **Asset Export → GLB Export** section
3. Enter a **file name** at the top
4. Configure export options (see below)
5. Click **Export GLB**
#### Export Options
DRACO Compress
Applies DRACO compression to reduce file size. Useful for web delivery and embedding.
Scene Settings
Include all scene configuration (HDR, background, ground, post-processing, etc.) in the exported file. Disable if you only need the 3D geometry and materials.
Embed Image Previews
Embeds preview images of materials and scene inside the GLB file.
Only Visible
Exports only objects that are currently visible in the Hierarchy. Hidden objects are excluded from the file. This is useful for splitting one scene into multiple files — hide/show different parts and export separately.
Encrypt
Protects the file with a password. When enabled, a password input field appears. This password will be required every time someone tries to load the file.
Compress HDR env maps
Compresses the HDR environment maps included in the file to reduce overall size.
Convert to indexed
Converts geometry to indexed format for better performance and smaller file size.
Ignore invalid animations
Skips any animations that may cause export errors, ensuring a clean export.
Protecting Your Designs
Jewelry designs are often unique and commercially valuable. The Encrypt option lets you protect your GLB files with a password — anyone trying to open the file will need to enter it first. This adds an extra layer of security when sharing files with clients, manufacturers, or partners.
Picking tab on the [right panel](./ui-overview#right-panel-—-professional-tools)
3. In the **Picker** section, find the **Physical Material** settings
4. Scroll down to the bottom
5. Click **Download .pmat**
---
## Exporting a Diamond Material (.dmat)
To export a diamond material:
1. **[Select the object](./ui-overview#selecting-objects)** that has the diamond material
2. Open the Picking tab on the [right panel](./ui-overview#right-panel-—-professional-tools)
3. In the **Picker** section, find the **Diamond Material** settings
4. Scroll down to the bottom
5. Click **Download .dmat**
---
## Related Pages
- **[Import Materials](./import-materials)** — Import `.pmat` and `.dmat` files back into Playground
- **[UI Overview](./ui-overview)** — Interface layout, panels, and navigation
- **[Export Models](./export-models)** — Export your full scene as a `.glb` file
- **[Export Scene Settings](./export-scene-settings)** — Export `.vjson` and `.json` scene configuration files
- **[Custom PBR Materials](./coming-soon)** — Create your own PBR materials from scratch
- **[Custom Diamond Materials](./coming-soon)** — Create your own diamond materials
---
# Export Scene Settings
iJewel Playground allows you to export your scene settings as standalone files. This is useful for backing up your scene look, transferring configurations between projects, or sharing presets with colleagues.
## Export Formats
| Format | Description |
|---|---|
| `.vjson` | Complete scene configuration — all settings: HDR maps, background, ground, post-processing, tonemapping, material configurators, and more |
| `.json` | Individual setting — only a specific plugin or parameter (e.g., ground, tonemapping, camera) |
---
## Exporting All Scene Settings (.vjson)
There are two ways to export a complete `.vjson` file with all your scene settings.
### Method 1 — Left Panel (Quick Export)
The fastest way to export all scene settings:
1. Open the Export tab on the [left panel](./ui-overview#left-panel-—-presets-quick-settings)
2. Find the **Scene Settings** section
3. Click **Download VJSON**
This saves all settings currently applied in your scene — background, ground, shadows, tonemapping, post-processing, material configurators, and everything else — as a single `.vjson` file.
---
### Method 2 — Right Panel (Advanced Export)
For more control over exactly what to include in the exported file:
1. Open the Export tab on the [right panel](./ui-overview#right-panel-—-professional-tools)
2. Go to the **Asset Export** section
3. Open **Preset Config Export**
4. Click **Plugins** to see the full list of what can be included or excluded
Here you can individually toggle which settings to include in the `.vjson` export. For example, you can exclude material configurators, remove a specific HDR map, or keep only the post-processing settings — giving you full control over what goes into the file.
#### Quick Actions
Select None
Deselect all plugins — start from scratch and manually pick only what you need
Select All
Select all plugins — export everything
Export Plugins
Export only the currently selected plugins as a `.vjson` file
Export All Viewer Config Editor
Export the complete viewer configuration including all settings and plugins
Scene for ground settings, or Post Processing for effects)
2. Find the specific setting (e.g., Ground, Tonemapping, SSR, etc.)
3. Click the **three dots** (⋮) next to the setting name
4. Select **Download preset** from the menu
5. The `.json` file with that specific setting will be downloaded
### What can be exported as individual .json?
You can export presets for almost any setting in the right panel, including:
- **Scene:** Ground, Progressive Shadow, Background
- **Post Processing:** Screen Space Reflection (SSR), Tonemapping, Bloom, Depth of Field, SSAO, SSBevel, Vignette
- **Viewer:** Renderer settings, Camera settings
- **Anti-aliasing:** TAA, Progressive AA
::: tip
Individual `.json` presets can be imported back by drag & drop onto the canvas. Ground `.json` files can also be [saved to the library](./import-scene-settings#method-2-—-save-to-scene-presets-library) for quick reuse.
:::
---
## Related Pages
- **[Import Scene Settings](./import-scene-settings)** — Import `.vjson` and `.json` files back into Playground
- **[UI Overview](./ui-overview)** — Interface layout and panels
- **[Export Models](./export-models)** — Export your scene as a `.glb` file
- **[Export Materials](./export-materials)** — Export `.pmat` and `.dmat` material files
- **[Renderer Settings](./renderer-settings)** — Configure render quality and scale
---
# Export Images
iJewel Playground makes it easy to save high-resolution images of your jewelry renders in multiple formats. There are two ways to export images — a quick method and an advanced method.
## Quick Export (Camera Icon)
The fastest way to capture an image is using the **camera icon** in the floating Quick Actions panel on the canvas.
- Click the **camera icon** to instantly save a **PNG** snapshot of your current view.
::: tip
This is perfect for quick captures during your design process. The image is saved at the current canvas resolution — make sure to adjust your [Renderer Settings](./renderer-settings.md) first if you need higher quality.
:::
## Advanced Export (Export Tab)
For more control over format, resolution, and file naming, use the **Export Tab** in the Editor UI Panel.
### Steps
1. Open the **Export** tab in the right-side Editor UI Panel.
2. Choose your desired format:
- **PNG** — Lossless quality, supports transparency. Best for product images.
- **JPEG** — Smaller file size, no transparency. Good for web and social media.
- **WEBP** — Modern format with excellent compression. Ideal for websites and e-commerce.
3. Enter a **file name** for your export.
4. Click **Download**.
## Export from the Left Menu
You can also export images from the **left-side Presets Panel**:
1. Set the desired **width** and **height** for your output resolution.
2. Select the output **format** (PNG, JPEG, or WEBP).
3. Click **Download**.
::: tip Higher Quality Exports
For the best quality exports, increase the **width and height** values before downloading. This produces sharper images suitable for print, catalogs, or high-DPI displays.
:::
## Transparent Background
To export an image with a transparent background (PNG format only), you need to configure several settings before exporting:
1. Go to [Background / Environment](./background-environment) and set the **Background Color** alpha channel to `0` (fully transparent)
2. Go to [Ground](./ground) and uncheck **Visible** to hide the ground plane
3. Disable [Progressive Shadow](./progressive-shadow) if it is enabled
4. Choose **PNG** as the export format (JPEG and WEBP do not support transparency)
5. Export the image
::: tip
This is especially useful for e-commerce product listings and marketing materials where you need the jewelry on a clean, transparent background that can be composited onto any backdrop.
:::
---
## Recommended Settings by Use Case
| Use Case | Format | Suggested Resolution |
|---|---|---|
| E-commerce product listing | PNG or WEBP | 1000×1000 px or higher |
| Social media | JPEG or WEBP | 1080×1080 px |
| Print catalog | PNG | 2000×2000 px or higher |
| Website banner | WEBP | 1920×600 px |
---
# Export Videos
iJewel Playground allows you to record and export videos of your jewelry models — perfect for product showcases, social media, and e-commerce listings. You can create turntable animations, camera path recordings, and 360° spins.
## Turntable Video (Left Menu)
The left-side Presets Panel provides a quick way to export turntable videos.
### Steps
1. Set the **resolution** (width and height) for your video output.
2. Configure the **FPS** (frames per second) — higher FPS results in smoother playback.
3. Set the **duration** of the video.
4. Click **Download**.
The rendering process will begin, indicated by a **red border on the canvas**.
::: warning
Keep the browser tab open until the rendering process is complete. Closing or switching away from the tab may interrupt the export.
:::
## Advanced Recording (Right Panel)
The **Export** section in the right-side Editor UI Panel offers multiple recording modes for different types of video output.
### Recording Modes
| Mode | Description |
|---|---|
| **Standard Recording** | Records whatever is happening on the canvas in real time — ideal for custom interactions and walkthroughs. |
| **Camera Views** | Records a sequence based on your saved camera view positions. |
| **360° Animation** | Automatically rotates the model clockwise for a full 360° turntable video. |
| **360° Animation (CCW)** | Same as above, but rotates counterclockwise. |
### Steps
1. Open the **Export** tab in the Editor UI Panel.
2. Select your desired **recording mode**.
3. Customize your settings:
- **Resolution** — Output width and height in pixels.
- **FPS** — Frames per second (24 or 30 recommended for smooth playback).
- **Duration** — Length of the video in seconds.
4. Click **Record**.
5. Wait for the recording to finish — a **red indicator** will appear on the canvas during the process.
::: tip
For e-commerce and social media, a **360° animation** at 5–10 seconds duration with 30 FPS is a great starting point. It gives customers a complete view of the product in a short, engaging clip.
:::
::: tip Video file too large?
See [Reducing the Video File Size](#reducing-the-video-file-size) below - a few settings can shrink a 33 MB export to under 1 MB.
:::
## Recommended Settings by Use Case
| Use Case | Mode | FPS | Duration |
|---|---|---|---|
| Product listing | 360° Animation | 30 | 5–8 sec |
| Social media reel | 360° Animation | 30 | 5–15 sec |
| Client presentation | Camera Views | 24–30 | 10–20 sec |
| Custom walkthrough | Standard Recording | 30 | As needed |
## Reducing the Video File Size
Is your exported video too large? The compression settings are located on the [right panel](./ui-overview#right-panel-—-professional-tools), inside the Export tab: set **Mime type** to *MP4 Video (ffmpeg)* and expand **FFmpeg Options (Advanced)** - highlighted below.
The two settings that matter for file size are **crf** and **preset**. Raise the crf (higher = smaller file) and set the preset to `veryfast` - this alone can shrink a 30+ MB export to a fraction of its size.
Pick your goal:
| Goal | Settings | Approx. size (10-sec video) |
|---|---|---|
| Best quality (larger file) | crf `18`, preset `veryfast` | ~4.5 MB |
| Balanced (recommended for web) | crf `23`, preset `veryfast` | ~2 MB |
| Smallest file | crf `28`, preset `veryfast` | ~1 MB |
Exact sizes vary with the scene, the resolution, and the duration. If the file is still too large, keep raising the crf (it goes up to `51`) and lower the export resolution.
What each option does:
| Option | What it does |
|---|---|
| **imageType** | The format of the frames captured from the canvas before they are encoded into the video (`jpeg`, `png`, or `webp`). |
| **bitrate** | A fixed target for the amount of data per second of video. When active, it makes the output size predictable. |
| **crf** | Constant Rate Factor, the quality control. Lower values give better quality, higher values give stronger compression. Range `0`–`51`. |
| **pixFmt** | The pixel format of the encoded video. `yuv420p` is compatible with all common browsers and players. |
| **preset** | The encoding speed vs. compression trade-off. Faster presets encode quicker but compress less thoroughly. |
| **colorTrc** / **colorSpace** | Color metadata written into the video, so the exported colors match what you see in the viewer. |
Every scene is different, so feel free to play around: export a short test clip, check the size and quality, and adjust the crf up or down until you are happy with the result.
---
# Scene Basics
A scene in iJewel Playground consists of your 3D model together with everything that defines how it looks — background, lighting, ground, shadows, camera, and materials. Understanding these building blocks helps you create professional jewelry visualizations.
## What Makes Up a Scene
Every scene has three core components:
**3D Objects** — your imported jewelry model, organized as a [hierarchy](./hierarchy) of mesh nodes (containing actual geometry) and transform nodes (containing position, rotation, scale). Multiple meshes can share the same material, and objects can be nested inside parent groups.
**Materials** — define the visual appearance of each object. By default, Playground assigns a Physical (PBR) Material for realistic rendering. You can convert objects to Diamond Material for gemstones. See [Picking → Physical Material](./picking#physical-material) and [Picking → Diamond Material](./picking#diamond-material).
**Scene Settings** — everything else: background color, environment maps, ground, shadows, post-processing, lighting, and camera configuration. These are managed primarily through the Scene tab on the right panel.
---
## Scene Tab Sections
The Scene tab on the right panel contains the following sections:
Background / Environment
Background color, environment maps (HDRI), and intensity settings. Read more →
Progressive Shadow
Soft, progressively refined shadows beneath the model
Ground
Ground plane visibility, reflections, and shadow settings
Scene
General scene settings and configuration
Gradient SVG
Custom gradient backgrounds using SVG
Lights
Add and configure directional, spot, and point lights in the scene
Cameras (Loaded)
Camera presets loaded from the model file
HDRi Ground
Use the HDRI environment map as a projected ground plane
Generate Geometry
Create simple primitive shapes (spheres, cubes, planes) directly in the scene
Scene Hierarchy
Browse all objects, select by name, and hide/show individual parts
Picking
Object properties, materials, diamonds, and all interactive controls
Transform Controls
Move, rotate, and scale objects with interactive gizmos and keyboard shortcuts
Renderer Settings
Configure render quality, resolution scale, and performance options
Scene tab on the right panel.
---
## Scene Tab Sections
The Scene tab on the right panel contains the following sections:
Background / Environment
Background color, environment maps (HDRI), and intensity settings. Read more →
Progressive Shadow
Soft, progressively refined shadows beneath the model
Ground
Ground plane visibility, reflections, and shadow settings
Scene
General scene settings and configuration
Gradient SVG
Custom gradient backgrounds using SVG
Lights
Add and configure directional, spot, and point lights in the scene
Cameras (Loaded)
Camera presets loaded from the model file
HDRi Ground
Use the HDRI environment map as a projected ground plane
Generate Geometry
Create simple primitive shapes (spheres, cubes, planes) directly in the scene
Scene Hierarchy
Browse all objects, select by name, and hide/show individual parts
Picking
Object properties, materials, diamonds, and all interactive controls
Transform Controls
Move, rotate, and scale objects with interactive gizmos and keyboard shortcuts
Renderer Settings
Configure render quality, resolution scale, and performance options
Viewer tab, in the **Renderer** section at the top.
---
## Settings
Mode
Dropdown — controls the rendering mode for the viewport. Full enables all effects for the highest quality preview and exports
Scale
Slider — resolution multiplier for the 3D canvas (default:
1.000). Increasing the value enhances both the real-time viewing quality and the resolution of exported images and videos. Higher values produce sharper, more detailed renders — ideal for close-up jewelry shots where every facet mattersCustom Canvas Size
Set exact canvas dimensions (width × height in pixels). Useful when you need renders at specific dimensions — square images for e-commerce listings, wide formats for banners, or standard resolutions like 1920×1080
Picking tab. It is the first section you see when you open this tab.
Click on the **Hierarchy** section header to expand the full tree view of your scene.
---
## Selecting Objects
Clicking on an **object name** in the hierarchy selects that object in the scene. The selected object will be highlighted in the 3D viewport, and its properties will become available for editing.
This is particularly useful when:
- An object is **hard to click** in the viewport because it's small or hidden behind other objects
- You need to select a **parent group** rather than an individual mesh
- You want to quickly navigate between different parts of a complex model
::: tip
You can also select objects by clicking directly on them in the 3D viewport. See [Selecting Objects](./ui-overview#selecting-objects) for more details.
:::
---
## Hiding and Showing Objects
Each object in the hierarchy has a **checkbox** next to its name. Toggling this checkbox controls the object's visibility:
- **Checked** — the object is visible in the scene
- **Unchecked** — the object is hidden from the scene
Click on name
Select the object — it gets highlighted in the viewport and its properties become editable
Toggle checkbox
Show or hide the object in the scene — hidden objects disappear from the viewport
Toggle parent
Hiding a parent object also hides all of its children at once
Picking icon to open it.
The tab contains the following sections:
Hierarchy
Tree view of all objects in the scene — select and hide objects. Read more →
Material Library
Browse and apply preset materials — metals, ceramics, pearls, and more. Import custom materials →
Diamonds
HDRI environment map for diamonds, Environment Rotation, and support for multiple HDRI maps per scene
Transform Controls
Move, rotate, and scale objects directly in the viewport. Read more →
Picker
All properties of the currently selected object — name, visibility, transform, material, and more
UV Unwrapping (xAtlas)
View and edit UV coordinates for texture mapping
Widgets
Additional visual helpers and interactive controls
Make Diamond
Convert the object's material from Physical Material to Diamond Material, enabling diamond-specific rendering with light dispersion and brilliance
Clear Cache
Clear the cached diamond rendering data to force a fresh recalculation
Make Standard
Convert the object back from Diamond Material to a regular Physical Material
Auto Instance Diamonds (dev)
Developer utility for automatically instancing diamond objects
Clear Cache
Clear the cached diamond rendering data to force a fresh recalculation
Enabled
Checkbox — when enabled, clicking on objects in the canvas selects them. Disable to prevent accidental selection
AutoFocus
Checkbox — when enabled, the camera automatically zooms in on the object when you click on it
Visible
Checkbox — show or hide the object in the 3D canvas. Same as toggling visibility in the Hierarchy
Pick/Focus
Button — zoom the camera to focus on the selected object
Pick Parent
Button — select the parent object of the current selection in the hierarchy
Name
Text input — the name of the selected object. You can rename it here
Casts Shadow
Whether this object casts shadows onto other objects and the ground
Receive Shadow
Whether this object receives shadows from other objects
Frustum culled
Whether the object is culled when outside the camera's view frustum
Render Order
Controls the rendering order — useful for overlapping transparent objects
Position
X, Y, Z coordinates — move the object to an exact position in the scene
Rotation
X, Y, Z angles — rotate the object around each axis
Scale
X, Y, Z values — resize the object along each axis
Auto Scale
Automatically scale the object to fit the scene proportionally
Auto Center
Move the object to the center of the scene
Pivot to Node Center
Reset the object's pivot point to the center of its bounding box
Rotate X +90 / −90
Rotate the object 90° around the X axis
Rotate Y +90 / −90
Rotate the object 90° around the Y axis
Rotate Z +90 / −90
Rotate the object 90° around the Z axis
Center Geometry
Move the geometry to center
Center Geometry (keep position)
Center the geometry while keeping the object's world position
Compute vertex normals
Recalculate vertex normals for smooth shading
Compute vertex tangents
Recalculate tangents needed for normal mapping
Normalize normals
Ensure all normals are unit length for correct lighting
Convert to non-indexed
Convert the geometry from indexed to non-indexed format
Remove Material
Remove the material assigned to this object
Duplicate Object
Create a copy of the selected object in the scene
Wrap in Parent
Create a new parent group and place the selected object inside it
Delete Object
Remove the selected object from the scene entirely
Picking tab, in the **Transform Controls** section.
---
## How to Enable
1. Open the **Picking** tab on the right panel
2. Find the **Transform Controls** section
3. Check the **Enable** checkbox
4. Select any object in the scene
Once enabled and an object is selected, a 3D gizmo with colored arrows will appear on the object in the viewport. You can click and drag these arrows to transform the object.
To disable Transform Controls, simply uncheck the **Enable** checkbox — the gizmo will disappear from the viewport.
---
## Settings
Mode
Choose the transformation type: Translate (move), Rotate, or Scale
Space
World — axes are aligned with the scene. Local — axes are aligned with the object's own orientation
Size
Adjust the size of the gizmo arrows in the viewport — make them bigger or smaller for comfort
Show X
Show or hide the X axis (red arrow)
Show Y
Show or hide the Y axis (green arrow)
Show Z
Show or hide the Z axis (blue arrow)
Q
Toggle Space between World and Local
W
Switch to Translate mode
E
Switch to Rotate mode
R
Switch to Scale mode
X
Toggle Show X axis on/off
Y
Toggle Show Y axis on/off
Z
Toggle Show Z axis on/off
Ctrl+Z
Undo the last transformation (Cmd+Z on Mac)
Scene tab on the [right panel](./ui-overview#right-panel-—-professional-tools).
---
## Scene Tab Sections
Background / Environment
Background color, images, HDRI environment maps, intensity and rotation settings. Read more →
Progressive Shadow
Soft directional shadow beneath the model with adjustable focus, spread, color, and direction. Read more →
Ground
Ground plane with shadow, material, and blending options. Can be disabled for floating objects. Read more →
Scene
Contains the Clear Scene button — removes all objects and resets the scene. Same as the Clear Scene button on the toolbar. Use with caution: this action cannot be undone
Gradient SVG
Create custom gradient backgrounds using SVG. Read more →
Lights
Add and configure directional, ambient, point, and spot lights in the scene. Read more →
Cameras (Loaded)
Cameras imported from your 3D software — activate to use custom camera paths and animations. Read more →
HDRi Ground
Use the HDRI environment map as a projected ground plane. Read more →
Generate Geometry
Create simple primitive shapes (spheres, cubes, planes) directly in the scene. Read more →
Background / Environment
Background color, HDRI maps, environment intensity and rotation
Progressive Shadow
Soft directional shadow with adjustable focus, spread, and color
Ground
Ground plane, shadows, material, blending, and floating object mode
Gradient SVG
Create custom gradient backgrounds with two colors
Renderer Settings
Configure render quality, resolution scale, and performance options
Lights
Directional, ambient, point, and spot lights in the scene
Cameras (Loaded)
Imported cameras, camera paths, and animation playback
HDRi Ground
Project the HDRI environment map as a ground surface
Generate Geometry
Create primitive shapes like planes, spheres, boxes, and more
Scene tab. It is the first section at the top.
---
## Background
### Color
Choose a background color for your scene using the color picker. This color is visible behind your 3D model and in renders.
### Image
Upload a custom background image from your computer. This image will be displayed behind the 3D model instead of the solid color.
### Env Map BG
When enabled, the Environment Map (HDRI) is also used as the background image. This creates a seamless look where the reflections on the model match the visible background.
### Bg Intensity
Controls the brightness of the background. Increase to make the background brighter, decrease to darken it. This only affects the visual background — not the lighting on the model.
---
## Environment Map (HDRI)
The Environment Map is an HDRI image that wraps around the entire scene and provides realistic lighting and reflections on your model. This is the primary light source for PBR materials — metals, ceramics, and pearls all react to the environment map. **Changing the HDRI map dramatically changes how your model looks** — different maps produce completely different reflections, highlights, and overall mood.
You can load a custom HDRI map by uploading it in this section, or choose from the large library of ready-made HDRI presets on the [left panel](./ui-overview#left-panel-—-presets-quick-settings). The library includes many presets specifically optimized for jewelry rendering — the first preset is designed for metals.
::: tip
For creating custom HDRI maps, you can use the [iJewel HDRI Editor](https://editor.hdrmap.com/#) — a dedicated tool for building environment lighting setups from scratch.
:::
---
## Environment Settings
Env Rotation
Rotate the environment map along three axes. Changing the rotation changes where highlights and reflections appear on the model. Also available in Advanced Settings on the left panel
Env Intensity
Controls the brightness of the environment lighting on the model. Reduce to dim the reflections, increase to make them stronger. Also available in Advanced Settings on the left panel
Environment 1
A second environment map slot. Useful when you want different objects in the same scene to use different HDRI maps — for example, a separate environment for pearls
Fixed Env Direction
When enabled, the environment stays fixed while you rotate the model — reflections shift as the model turns. When disabled, the environment rotates together with the model, keeping reflections in the same relative position
Scene tab, in the **Progressive Shadow** section.
---
## Enabling Progressive Shadow
Check the **Enable** checkbox to activate the Progressive Shadow. A directional light will be created in the scene, and a shadow will appear beneath your model. Uncheck to disable.
---
## Directional Light Settings
Once enabled, you can configure the directional light that casts the shadow:
### Visibility & Intensity
Visible
Checkbox — show or hide the directional light helper in the viewport
Intensity
Slider — controls the strength of the directional light
Color
Color picker — choose the color of the shadow. Use darker colors for subtle shadows or try colored shadows for creative effects
Focus
Slider — controls how tight the shadow area is. Higher focus produces a more concentrated shadow beneath the model
Spread
Slider — controls the softness of the shadow edges. Higher spread produces a softer, more diffused shadow
Distance Scale
Slider — adjusts the distance of the light from the model
Direction
Three inputs (X, Y, Z) — set the direction the light comes from. This changes where the shadow falls relative to the model
Radius
Slider — the radius of the shadow map area
First Stone Size
Slider — size of the first shadow cascade step
Bias
Slider — shadow bias to reduce shadow acne artifacts
Normal Bias
Slider — normal-based bias for further artifact reduction
Scene tab, in the **Ground** section (the third section from the top).
---
## Visible
Check or uncheck the **Visible** checkbox to show or hide the ground plane. When disabled, the model appears to float — useful for pendants, earrings, or any jewelry that should look suspended rather than resting on a surface.
---
## Ground Settings
Size
Slider — controls the size of the ground plane. Increase for a larger visible floor area
Render to Depth
When enabled, the ground plane blends into the background. This helps create a seamless transition between the floor surface and the background color or image
Limit Camera
Prevents the camera from going below the floor level. When enabled, users cannot rotate the view to see the underside of the ground — keeping the presentation clean and professional
Tone Map
Applies tone mapping to the ground plane
Shadow Frames
Controls the number of frames used for shadow calculation. More frames produce a softer, smoother shadow but take longer to compute
Color
Color picker — sets the color of the shadow light
Intensity
Slider — controls the strength of the light. Higher intensity produces a darker, more visible shadow
Direction
Three inputs (X, Y, Z) — sets the direction the light comes from, which determines where the shadow falls relative to the model
Radius
Slider — the radius of the shadow map area
Bias
Slider — shadow bias to reduce visual artifacts (shadow acne)
Focus
Slider — controls how tight the shadow area is. Higher focus produces a more concentrated shadow beneath the model
Spread
Slider — controls the softness of the shadow edges. Higher spread produces a softer, more diffused shadow
Opacity
Slider — controls the transparency of the ground shadow. Lower opacity creates a softer, more subtle shadow. Use this when you want a gentle shadow hint rather than a solid dark shadow beneath the model
Scene tab, in the **Gradient SVG** section.
---
## How It Works
The Gradient SVG tool generates an SVG gradient image and places it into the **Image** slot in the [Background / Environment](./background-environment) section. When you enable **Apply to Background**, any changes you make to the gradient are immediately visible in the viewport.
To see your gradient in real time, make sure the **Apply to Background** checkbox at the bottom of the section is checked. All changes to colors, angle, and positions will update the background automatically.
---
## Settings
Enabled
Checkbox — enable or disable the Gradient SVG tool
Type
Dropdown — choose the gradient type: Linear (straight gradient from one side to another) or Radial (circular gradient from center outward)
Position 1
Two values — the starting position of the first color stop in the gradient
Position 2
Two values — the ending position of the second color stop in the gradient
Angle
Slider — rotation angle of the gradient in degrees (0–360). Only applies to Linear type
Color 1
Color picker — the first gradient color
Color 2
Color picker — the second gradient color
Apply to Background
Checkbox — when enabled, the generated SVG gradient is automatically applied to the scene background. All changes are visible in real time
Refresh SVG
Button — manually regenerate and apply the SVG gradient
Scene tab, in the **HDRi Ground** section.
::: info
HDRi Ground uses whatever HDRI map is currently loaded in the [Background / Environment](./background-environment) section. If no HDRI map is set, enabling HDRi Ground will have no visible effect.
:::
---
## Enabled
Check or uncheck the **Enabled** checkbox to toggle the HDRi Ground on or off. When enabled, the HDRI environment map wraps around the scene as a sphere, and the ground becomes part of that sphere — creating a seamless environment where the background and floor are one continuous image.
---
## Settings
World Radius
Controls the size of the HDRI sphere surrounding the scene. A larger radius pushes the environment further away, while a smaller radius brings it closer to the model
Tripod Height
Adjusts the vertical offset of the HDRI projection — similar to the height at which the original HDRI photo was captured. Change this to align the horizon line with your model's ground level
Origin Position (X, Y, Z)
Three inputs that shift the center point of the HDRI sphere in 3D space. Use this to reposition the environment relative to your model if the default alignment doesn't look right
Scene tab, in the **Generate Geometry** section.
---
## Available Shapes
The section provides six buttons, each generating a different primitive shape:
Generate Plane
A flat rectangular surface — useful for floors, walls, or material previews
Generate Sphere
A round shape — great for testing reflections and material properties
Generate Box
A cube — a simple shape for testing materials on flat surfaces and edges
Generate Circle
A flat circular disc
Generate Torus
A donut-shaped ring — particularly useful for previewing ring materials and finishes
Generate Cylinder
A cylindrical tube — good for testing materials on curved and flat surfaces together
Scene tab, in the **Cameras (Loaded)** section.
::: info
This section will be empty if your model file does not contain any cameras. To use loaded cameras, you need to export cameras from your 3D software together with the model.
:::
---
## How It Works
By default, iJewel Playground uses its own viewport camera — the one that lets you orbit, zoom, and pan around the model freely. When you load a model that contains a camera, it appears as an object in this section. You can then **activate** that camera to switch from the default viewport to the imported camera's point of view.
### Tutorial: Creating a Camera Path and Rendering It in Playground
This tutorial walks through the full workflow for camera animations: you start by creating a camera path in **Blender** — setting up keyframes, defining the movement curve, and configuring the animation timeline. Then you export the scene (model + camera) as a `.glb` file and import it into **iJewel Playground**. Once loaded, you activate the imported camera and use the export tools to render the final video directly in the browser.
---
## Camera Properties
When you expand a loaded camera, it shows properties similar to a regular object:
Visible
Checkbox — show or hide the camera helper in the viewport
Pick/Focus
Button — zoom the viewport to focus on the camera object
Pick Parent
Button — select the parent object in the hierarchy
Name
Text input — the name of the camera (imported from your 3D software)
Position
Three inputs (X, Y, Z) — the camera's position in the scene
Rotation
Three inputs (X, Y, Z) — the camera's rotation angles
Scale
Three inputs (X, Y, Z) — the camera's scale
Render Order
Controls the rendering order
Activate Main
Switch from the default viewport to this loaded camera. The button changes to Deactivate Main once active. While activated, you can no longer orbit or pan — you see only through this camera
Scene tab, in the **Cameras (Loaded)** section.
::: info
This section will be empty if your model file does not contain any cameras. To use loaded cameras, you need to export cameras from your 3D software together with the model.
:::
---
## How It Works
By default, iJewel Playground uses its own viewport camera — the one that lets you orbit, zoom, and pan around the model freely. When you load a model that contains a camera, it appears as an object in this section. You can then **activate** that camera to switch from the default viewport to the imported camera's point of view.
### Tutorial: Creating a Camera Path and Rendering It in Playground
This tutorial walks through the full workflow for camera animations: you start by creating a camera path in **Blender** — setting up keyframes, defining the movement curve, and configuring the animation timeline. Then you export the scene (model + camera) as a `.glb` file and import it into **iJewel Playground**. Once loaded, you activate the imported camera and use the export tools to render the final video directly in the browser.
---
## Camera Properties
When you expand a loaded camera, it shows properties similar to a regular object:
Visible
Checkbox — show or hide the camera helper in the viewport
Pick/Focus
Button — zoom the viewport to focus on the camera object
Pick Parent
Button — select the parent object in the hierarchy
Name
Text input — the name of the camera (imported from your 3D software)
Position
Three inputs (X, Y, Z) — the camera's position in the scene
Rotation
Three inputs (X, Y, Z) — the camera's rotation angles
Scale
Three inputs (X, Y, Z) — the camera's scale
Render Order
Controls the rendering order
Activate Main
Switch from the default viewport to this loaded camera. The button changes to Deactivate Main once active. While activated, you can no longer orbit or pan — you see only through this camera
Scene tab, in the **Lights** section.
The section provides four buttons to add different types of lights:
Add Directional Light
Parallel light rays from a specific direction — like sunlight. Best for consistent shadows
Add Ambient Light
Uniform light that illuminates all objects equally from all directions — fills in dark areas without casting shadows
Add Point Light
Light that emits from a single point in all directions — like a light bulb. Useful for localized highlights
Add Spot Light
Cone-shaped light that emits from a point in a specific direction — like a flashlight or stage spotlight
Enabled
Checkbox — turn the light on or off without removing it
Color
Color picker — sets the color of the light
Intensity
Slider — controls the brightness of the light
Rotation
Three inputs (X, Y, Z) — controls the direction the light points
Position
Three inputs (X, Y, Z) — position of the light in the scene
Shadow Enabled
Checkbox — enable or disable shadow casting from this light
Shadow Map Size
Controls the resolution of the shadow map — higher values produce sharper shadows
Shadow Bias
Slider — adjusts shadow bias to reduce shadow acne artifacts
Shadow Normal Bias
Slider — normal-based bias for further artifact reduction
Shadow Radius
Slider — controls the softness of the shadow edges
Shadow First Doom
Advanced shadow rendering parameter
Enabled
Checkbox — turn the light on or off
Color
Color picker — sets the color of the ambient light
Intensity
Slider — controls the brightness of the ambient light
Enabled
Checkbox — turn the light on or off
Color
Color picker — sets the color of the light
Intensity
Slider — controls the brightness of the light
Distance
Slider — maximum distance the light reaches. Objects beyond this distance are not illuminated
Decay
Slider — how quickly the light dims with distance. Higher values make the light fall off faster
Position
Three inputs (X, Y, Z) — position of the light in the scene
Shadow Enabled
Checkbox — enable or disable shadow casting
Shadow Map Size
Three inputs — resolution of the shadow map
Shadow Bias
Slider — adjusts shadow bias to reduce artifacts
Shadow Radius
Slider — controls the softness of the shadow edges
Enabled
Checkbox — turn the light on or off
Color
Color picker — sets the color of the light
Intensity
Slider — controls the brightness of the light
Angle
Slider — controls the width of the spotlight cone in degrees
Penumbra
Slider — controls the softness of the spotlight edge. Higher values create a gradual fade at the cone edges
Rotation
Three inputs (X, Y, Z) — controls the direction the spotlight points
Position
Three inputs (X, Y, Z) — position of the light in the scene
Shadow Enabled
Checkbox — enable or disable shadow casting
Shadow Map Size
Two inputs — resolution of the shadow map
Shadow Bias
Slider — adjusts shadow bias to reduce artifacts
Shadow Radius
Slider — controls the softness of the shadow edges
Scene tab, in the **Lights** section.
The section provides four buttons to add different types of lights:
Add Directional Light
Parallel light rays from a specific direction — like sunlight. Best for consistent shadows
Add Ambient Light
Uniform light that illuminates all objects equally from all directions — fills in dark areas without casting shadows
Add Point Light
Light that emits from a single point in all directions — like a light bulb. Useful for localized highlights
Add Spot Light
Cone-shaped light that emits from a point in a specific direction — like a flashlight or stage spotlight
Enabled
Checkbox — turn the light on or off without removing it
Color
Color picker — sets the color of the light
Intensity
Slider — controls the brightness of the light
Rotation
Three inputs (X, Y, Z) — controls the direction the light points
Position
Three inputs (X, Y, Z) — position of the light in the scene
Shadow Enabled
Checkbox — enable or disable shadow casting from this light
Shadow Map Size
Controls the resolution of the shadow map — higher values produce sharper shadows
Shadow Bias
Slider — adjusts shadow bias to reduce shadow acne artifacts
Shadow Normal Bias
Slider — normal-based bias for further artifact reduction
Shadow Radius
Slider — controls the softness of the shadow edges
Shadow First Doom
Advanced shadow rendering parameter
Enabled
Checkbox — turn the light on or off
Color
Color picker — sets the color of the ambient light
Intensity
Slider — controls the brightness of the ambient light
Enabled
Checkbox — turn the light on or off
Color
Color picker — sets the color of the light
Intensity
Slider — controls the brightness of the light
Distance
Slider — maximum distance the light reaches. Objects beyond this distance are not illuminated
Decay
Slider — how quickly the light dims with distance. Higher values make the light fall off faster
Position
Three inputs (X, Y, Z) — position of the light in the scene
Shadow Enabled
Checkbox — enable or disable shadow casting
Shadow Map Size
Three inputs — resolution of the shadow map
Shadow Bias
Slider — adjusts shadow bias to reduce artifacts
Shadow Radius
Slider — controls the softness of the shadow edges
Enabled
Checkbox — turn the light on or off
Color
Color picker — sets the color of the light
Intensity
Slider — controls the brightness of the light
Angle
Slider — controls the width of the spotlight cone in degrees
Penumbra
Slider — controls the softness of the spotlight edge. Higher values create a gradual fade at the cone edges
Rotation
Three inputs (X, Y, Z) — controls the direction the spotlight points
Position
Three inputs (X, Y, Z) — position of the light in the scene
Shadow Enabled
Checkbox — enable or disable shadow casting
Shadow Map Size
Two inputs — resolution of the shadow map
Shadow Bias
Slider — adjusts shadow bias to reduce artifacts
Shadow Radius
Slider — controls the softness of the shadow edges
Anti-aliasing tab.
---
## How the Three Sections Work Together
Each anti-aliasing method targets a specific use case:
Progressive
Multi-frame accumulation for still images. The renderer takes multiple samples over time and averages them to eliminate aliasing. Best for final image exports where you can wait a few seconds for the render to converge. Read more →
Temporal AA
Real-time anti-aliasing for interactive use and animations. Blends the current frame with previous frames to smooth edges while you rotate, zoom, or play animations. Keeps the viewport clean without the wait time of Progressive. Read more →
Velocity Buffer (TAA)
Motion-aware temporal anti-aliasing that uses per-pixel velocity data to reduce ghosting artifacts when objects or the camera move. An advanced complement to Temporal AA for scenes with animation. Read more →
Progressive
Multi-frame accumulation — Frame count & Jitter
Temporal AA
Real-time anti-aliasing — Feedback & Stable Noise
Velocity Buffer (TAA)
Motion-aware anti-aliasing to reduce ghosting
---
## Related Pages
- **[Renderer Settings](./renderer-settings)** — Resolution and quality configuration
- **[Export Images](./export-images)** — Image export settings and quality tips
- **[Export Videos](./export-videos)** — Video export settings
- **[FAQ: Rendering & Performance](./faq-rendering)** — Common rendering questions
---
# Progressive
Progressive anti-aliasing works by rendering multiple frames of the same view and accumulating (averaging) them together. Each frame uses a slightly different sub-pixel offset, so fine details and edges are sampled at many positions — the result is a smooth, high-quality image with no jagged edges. This is the primary quality setting for **still image exports**.
## Where to Find It
This section is located on the [right panel](./ui-overview#right-panel-—-professional-tools), inside the Anti-aliasing tab, in the **Progressive** section.
---
## How It Works
When the scene is idle (no camera movement, no animation playing), Playground begins accumulating frames in the background. You'll notice the image gradually becomes sharper and smoother over a few seconds — this is the progressive render converging. Once the set number of frames has been reached, the image is fully resolved.
Any interaction (rotating, zooming, panning) resets the accumulation and it starts over. This is normal — Progressive is designed for the **final still result**, not for real-time interaction.
---
## Settings
Frame count
The number of frames to accumulate before the render is considered complete. Higher values produce smoother results but take longer. Default is 32. Common values: 4–8 for fast previews, 16–32 for high-quality exports, 64+ for maximum quality
Jitter
When enabled, each accumulated frame uses a slightly randomized sub-pixel offset. This prevents structured aliasing patterns and produces a more natural, film-like anti-aliasing. Enabled by default — recommended to keep it on
Quick preview
Frame count: 4–8. Fast convergence, good enough for checking composition and lighting
Image export
Frame count: 16–32. Good balance of quality and speed for final renders
Video export
Frame count: 4–8. Each video frame must converge separately, so high values dramatically increase render time. For video, rely on Temporal AA for smoothing between frames
Maximum quality
Frame count: 64+. Use for hero shots or print-quality renders where every pixel matters
Anti-aliasing tab, in the **Temporal AA** section.
---
## How It Works
Each rendered frame is compared to the previous frame. Pixels that haven't changed much are blended together (using the **Feedback** values), which smooths out aliasing and reduces temporal flickering — the shimmering you sometimes see on thin edges or detailed geometry when the camera moves.
The trade-off is **ghosting**: if the feedback is too high, moving objects can leave faint trails because the renderer holds on to old frame data too long. The Feedback parameters let you control this balance.
---
## Settings
Enabled
Toggles Temporal AA on or off. When enabled, the renderer blends consecutive frames to reduce aliasing in real time. Recommended to keep enabled for interactive work and video exports
Feedback
Two values that control how much of the previous frame is blended into the current frame. The first value (0.88 by default) controls the blending weight for most pixels. The second value (0.97 by default) controls the blending for high-confidence pixels. Higher values produce smoother results but increase ghosting on moving objects. Lower values reduce ghosting but allow more aliasing/flickering
Stable Noise
(Use Total Frame Count)
(Use Total Frame Count)
When enabled, the noise pattern used for rendering effects (like screen-space reflections and ambient occlusion) is tied to the total accumulated frame count rather than being re-randomized each frame. This produces more stable, consistent noise that Temporal AA can smooth out more effectively — reducing the "crawling" noise artifacts you may see on metallic or glossy surfaces
First value (0.88)
General blending factor. At 0.88, each new frame contributes about 12% new data while 88% comes from the history buffer. Lowering this (e.g., to 0.5–0.7) makes the image more responsive but noisier. Raising it (e.g., to 0.95) makes it smoother but increases ghosting
Second value (0.97)
High-confidence blending factor applied to pixels where the renderer is very sure the data is correct (no disocclusion, no major change). This higher value allows those stable areas to accumulate more temporal data for maximum smoothness
Anti-aliasing tab, in the **Velocity Buffer (TAA)** section.
---
## How It Works
Without a velocity buffer, Temporal AA assumes that each pixel in the current frame corresponds to the same screen position in the previous frame. This works well when the scene is still, but during camera rotation or object animation, pixels shift — and the old frame data at that position is no longer valid. This mismatch causes **ghosting** (faint trails behind moving edges).
The Velocity Buffer solves this by computing a **motion vector** for every pixel — a 2D offset describing where that pixel was in the previous frame. Temporal AA then uses these vectors to look up the correct historical data, producing clean anti-aliasing even during motion.
---
## Settings
Enabled
Toggles the Velocity Buffer on or off. When enabled, the renderer generates per-pixel motion vectors each frame, which Temporal AA uses for motion-compensated reprojection. This reduces ghosting during camera movement and object animation
Post Processing tab.
---
## Sections
Screen Space Reflections (SSR)
Real-time reflections on glossy and metallic surfaces
Tonemapping
Exposure, contrast, saturation, and color mapping modes
Outline
Selection highlight and object outline settings
Chromatic Aberration
Lens color fringing effect for a cinematic look
Filmic Grain
Analog film grain noise for a warmer, organic feel
Look Up Tables (LUT)
Custom color grading presets via .cube files
Vignette
Darkened edges for a focused center look
Depth of Field
Selective focus with background blur
Screen Space Ambient Occlusion (SSAO)
Contact shadows in crevices — enabled by default
Screen Space Bevel
Edge softening without modifying geometry
Bloom
Glow effect around bright areas
Screen Space Global Illumination (SSGI)
Indirect light bouncing between surfaces
Screen Space Contact Shadows
Fine shadows between close surfaces
---
## Related Pages
- **[Anti-aliasing](./anti-aliasing)** — Progressive, Temporal AA, and Velocity Buffer settings
- **[Renderer Settings](./renderer-settings)** — Resolution and quality configuration
- **[Export Images](./export-images)** — Image export settings
- **[Export Videos](./export-videos)** — Video export settings
---
# Screen Space Reflections (SSR)
Screen Space Reflections adds real-time reflections of the surrounding environment onto your 3D objects. This is especially visible on metallic surfaces — polished gold, silver, and platinum will reflect the ground, nearby objects, and the environment, making the render look more realistic and grounded.
## Where to Find It
This section is located on the [right panel](./ui-overview#right-panel-—-professional-tools), inside the Post Processing tab. It is the first section at the top.
::: info
SSR can only reflect what is currently visible on screen. Off-screen objects fall back to environment map reflections.
:::
---
## Settings
Enabled
Checkbox — toggles SSR on or off
Intensity
Slider — overall strength of reflections. Default 1.00
Boost
Three values (RGB) — per-channel reflection intensity boost. Default 1.00 / 1.00 / 1.00
Object Radius
Slider — maximum ray travel distance. Default 1.00
Auto Radius
Checkbox — automatically calculates optimal radius based on scene size. Recommended to keep enabled
Power
Slider — reflection falloff curve. Higher = sharper falloff at grazing angles. Default 1.10
Tolerance
Slider — depth matching precision. Higher = fewer gaps but potential artifacts. Default 0.50
Step Count
Slider — ray marching steps. More steps = more accurate but slower. Default 16
Low Quality Frames
Slider — number of lower-quality frames during camera movement for better responsiveness. Default 0
Ignore Front Rays
Checkbox — ignores camera-facing rays to prevent self-reflection artifacts. Enabled by default
Mask Front Rays Factor
Slider — masking strength for front-facing rays. Default -0.20
Post Processing tab, in the **Tonemapping** section.
---
## Mode
The **Mode** dropdown selects the tonemapping algorithm. Each mode produces a different color response.
ACESFilmic
Default. Cinematic colors with natural highlight rolloff. Recommended for most jewelry renders
Linear
No tonemapping — raw HDR values. Useful for post-production color grading
Reinhard
Classic curve — softer, less contrasty than ACES
Cineon
Kodak film response — warm, slightly desaturated analog film look
Uncharted 2
Filmic curve — good balance between contrast and highlight detail
AgX
Modern approach — handles bright saturated areas better than ACES, prevents color burn-out
Tonemap Background
Checkbox — applies tonemapping to the background as well. When off, only the 3D model is affected
Clip Background
Key setting for transparent exports. Removes the background and sets alpha to 0 — export as PNG to get a transparent image
Exposure
Slider — overall brightness. Default 1.00
Saturation
Slider — color intensity. Increase for more vivid rose gold or colored gemstones. Default 1.00
Contrast
Slider — difference between light and dark areas. A common adjustment is bumping this to 1.01–1.05 for a more polished look. Default 1.00
Render Depth
Checkbox — shows a black-and-white depth visualization instead of the color render. Useful for previewing Depth of Field ranges or creating depth maps for compositing
Post Processing tab, in the **Outline** section.
---
## How It Works
When you select an object in the viewport, Playground draws a colored outline along its edges so you can see what is selected. If you **disable** the outline, selecting still works — you just won't see the colored border.
---
## Settings
Enable
Checkbox — toggles the outline on or off. When disabled, objects are still selectable but without the colored border
Highlight
Checkbox — when enabled, the entire area of the selected object is filled with the outline color, not just the border. Use Transparency to control how visible this fill is
Intensity
Slider — controls how strong/visible the outline color is. Default 2.00
Transparency
Slider — controls the opacity of the highlight fill when Highlight is enabled. Lower values make the fill more see-through. Default 1.00
Color
Color picker — choose the outline color. Change this if you prefer a different selection color for your workflow. Default is orange (0xf36c00)
Post Processing tab, in the **Chromatic Aberration** section.
---
## Settings
Enable
Checkbox — toggles the chromatic aberration effect on or off
Intensity
Slider — controls the strength of the color fringing. Keep it low (around 0.05–0.15) for a subtle photographic touch. Higher values create a more dramatic, stylized effect. Default 0.10
Post Processing tab, in the **Filmic Grain** section.
---
## Settings
Enable
Checkbox — toggles the filmic grain effect on or off
Multiply
Checkbox — when enabled, the grain is blended using multiply mode, which darkens the image slightly and makes the grain more visible in bright areas
Intensity
Slider — controls how strong the grain effect is. Keep it low for a subtle film look, increase for a more stylized vintage feel
Post Processing tab, in the **Look Up Tables (LUT)** section.
---
## How It Works
1. Export a snapshot of your scene from Playground
2. Open it in Photoshop and adjust curves, levels, filters — any color grading you want
3. Save the adjustments as a `.cube` LUT file
4. Import the `.cube` file into Playground via the LUT section
5. The color grading is applied to the entire render in real time
You can apply LUTs globally or to specific parts of the scene (metals, diamonds, ground) using the separate LUT input slots.
---
## Settings
Enable
Checkbox — toggles the LUT effect on or off
LUT Background
Checkbox — when enabled, the LUT is also applied to the background. When disabled, only the 3D model is color-graded
Intensity
Slider — controls the strength of the LUT effect. At 1.0 the LUT is fully applied, at 0 it has no effect. Use intermediate values to blend between the original and graded look
LUT
Input — the main LUT slot. Upload a .cube file to apply your color grading preset to the entire render
LUT 1
Input — additional LUT slot for applying a different color grading to specific materials
LUT 2
Input — additional LUT slot for applying a different color grading to specific materials
Post Processing tab, in the **Vignette** section.
---
## Settings
Enable
Checkbox — toggles the vignette effect on or off
Power
Slider — controls the strength and spread of the vignette. Higher values create a more pronounced darkening at the edges
Color
Color picker — sets the vignette color. Default is black, but you can choose any color for a stylized look
Post Processing tab, in the **Depth of Field** section.
---
## How to Set the Focus Point
1. Enable **Enable Edit** checkbox in the Depth of Field section
2. Click directly on the object in the canvas where you want the focus to be — the focal point is set automatically
3. Once the focus is set, disable **Enable Edit** to return to normal object selection on the canvas
---
## Settings
Enable
Checkbox — toggles the depth of field effect on or off
Depth Range
Slider — controls the range of the in-focus zone. A smaller range means a narrower area stays sharp
Near Blur Scale
Slider — controls how strong the blur is for objects closer to the camera than the focal point
Far Blur Scale
Slider — controls how strong the blur is for objects further from the camera than the focal point
Enable Edit
Checkbox — when enabled, click on the canvas to set the focal point. Disable after setting focus to resume normal object selection
Post Processing tab, in the **SS Ambient Occlusion** section.
---
## Settings
Enable
Checkbox — toggles SSAO on or off. Enabled by default
Enable Cavity
Checkbox — enables cavity occlusion, which adds extra detail shadows in fine surface crevices
Cavity Brightness
Slider — adjusts the brightness of cavity shadows
Intensity
Slider — controls how strong the ambient occlusion effect is. Default: 0.25
Radius
Slider — sets the sampling radius for occlusion. Larger radius = wider, softer shadows. Default: 1.0
Bias
Slider — offsets the occlusion calculation to reduce self-shadowing artifacts
Fall-Off
Slider — controls how quickly the occlusion fades with distance
Num Samples
Slider — number of sampling points per pixel. More samples = smoother result but slower performance
Smooth Enabled
Checkbox — applies smoothing to the occlusion result for a softer look
Auto Radius
Checkbox — automatically calculates the optimal radius based on the scene. Enable this if you're unsure about manual radius settings
H Sharpness
Number input — controls the sharpness of the occlusion edges
Post Processing tab, in the **Screen Space Bevel** section.
### Before / After
---
## Settings
Enable
Checkbox — toggles the global SSB effect on or off. Disabling this turns off SSB for all materials
SS Bevel
Checkbox — enables the screen-space bevel calculation
SS Bevel Radius
Slider — controls how wide the bevel effect is on edges. Higher values create a more visible edge rounding
Post Processing tab, in the **Bloom** section.
### Before / After
---
## Settings
Enable
Checkbox — toggles the bloom effect on or off
Threshold
Slider — brightness threshold above which bloom is applied. Only pixels brighter than this value will glow
Soft Threshold
Slider — softens the threshold transition so bloom fades in gradually rather than appearing abruptly
Intensity
Slider — controls how strong the bloom glow is
Interference
Slider — adds a color interference pattern to the bloom for a more complex optical effect
Radius
Slider — controls how far the bloom glow spreads from bright areas
Power
Slider — adjusts the falloff curve of the bloom. Higher values concentrate the glow closer to bright areas
Debug
Checkbox — shows a debug view where the screen turns black and only the bloom-affected areas are visible. Use this to see exactly where bloom appears and adjust settings accordingly. Disable when done
Post Processing tab, in the **SS Global Illumination** section.
---
## Settings
Enable
checkbox
Toggles the SSGI effect on or off
Intensity
slider
How strong the indirect lighting effect is
Power
slider
Falloff curve — higher values concentrate the effect closer to surfaces
Auto Radius
checkbox
Automatically calculates the optimal sampling radius
Object Radius
slider
How far indirect light can travel between surfaces
Tolerance
slider
Depth tolerance for ray matching — reduces artifacts on thin geometry
Bias
slider
Offsets ray origin to reduce self-illumination artifacts
Fall-Off
slider
How quickly the indirect lighting fades with distance
Ray Count
slider
Rays per pixel — more rays = smoother result but slower
Step Count
slider
Steps per ray — more steps = more precise tracing
Smooth Enabled
checkbox
Smooths the GI result for a softer, less noisy look
Render In Camera
checkbox
Calculates GI from the camera's perspective
GI Enabled
checkbox
Toggles the GI calculation independently from the main Enable
Post Processing tab, in the **Screen Space Contact Shadows** section.
---
## Settings
Enable
checkbox
Toggles Screen Space Contact Shadows on or off
Radius
slider
Max distance for contact shadows — keep small for realistic results
Intensity
slider
How dark the contact shadows are
Tolerance
slider
Depth comparison tolerance — reduces false shadows on flat surfaces
Debug Only SSCS
checkbox
Shows only contact shadows — use to fine-tune, then disable
Step Count
slider
Ray marching steps — more steps = more precise but slower
The Animations tab provides tools for controlling all types of motion in your scene — imported glTF animation playback, camera path transitions, scroll-driven interactions, physics simulations, and object posing.
## Where to Find It
This section is located on the [right panel](./ui-overview#right-panel-—-professional-tools), accessible via the Animations tab.
---
## Sections
glTF Animation
Playback of animations embedded in your glTF/GLB file
Camera Views
Save camera positions and animate transitions between them
Viewer Animations
Create dynamic scenes by combining environment, lighting, and post-processing animations
Scrollable Camera Views Preview
Scroll-driven camera transitions for product landing pages
Physics
Gravity, collisions, and gyroscope-driven motion for realistic interactions
---
## Related Pages
- **[Export Videos](./export-videos)** — Export animations as video files
- **[Post Processing](./post-processing)** — Visual effects applied to your renders
---
# glTF Animation
This section controls playback of animations embedded in your glTF/GLB file. If you created an animation in your 3D software (Blender, 3ds Max, Maya) and exported it with the file, you can play it back and adjust its speed directly in Playground.
This is useful for product showcase animations — a ring rotating to show all angles, a pendant swinging, or a bracelet clasp opening and closing. You prepare the animation in your 3D software, export it as glTF/GLB, and then control the playback here.
## Where to Find It
This section is located on the [right panel](./ui-overview#right-panel-—-professional-tools), inside the Animations tab, in the **glTF Animation** section.
You can also start and stop the animation using the Play glTF Animation button on the top toolbar.
---
## Settings
Animation State
read-only
Displays the current animation state
Animation Time
read-only
Displays the current playback time position
Animation Duration
read-only
Displays the total duration of the animation
Loop
checkbox
Repeats the animation continuously after it finishes
Time Scale
slider
Scales the overall animation time
Speed
slider
Controls the playback speed
Animate on Scroll
checkbox
Ties animation progress to page scroll position
Animate on Drag
checkbox
Ties animation progress to mouse/touch drag on the canvas
Drag Axis
select
Drag direction — horizontal or vertical
Autoplay on Load
checkbox
Starts the animation automatically when the scene loads
Sync Max Duration
checkbox
Synchronizes all animations to the longest duration
Play
Stop
Reset
::: tip Key Settings
**Loop**, **Time Scale**, and **Speed** are the most commonly adjusted parameters. Loop repeats the animation continuously, while Time Scale and Speed control how fast it plays. Use **Play**, **Stop**, and **Reset** for direct playback control.
:::
---
## Video Tutorials
### Professional Diamond Ring Animation — Blender to iJewel Playground
### How to Create Beautiful Ring Animation — Blender to iJewel Playground
### How to Create Beautiful Pendant Swing Animation — Blender + iJewel Playground
---
## Related Pages
- **[Export Videos](./export-videos)** — Export your animations as video files
- **[Animations](./animations)** — Overview of all animation sections
---
# Camera Views
Camera Views lets you save specific camera positions and animate smooth transitions between them. This is one of the most important features for presenting jewelry — you can set up a front view, a top-down angle, a close-up on the stone, and then animate between them with a single click.
You can use Camera Views in two ways: save a single position as a "home" angle that viewers can always return to, or create a sequence of multiple views to showcase your piece from every angle with cinematic transitions.
## Where to Find It
This section is located on the [right panel](./ui-overview#right-panel-—-professional-tools), inside the Animations tab, in the **Camera Views** section.
You can also use the Loop Camera Views button on the top toolbar to start looping through all saved positions.
---
## How to Create Camera Views — Step by Step
### Step 1: Position Your Camera
Navigate in the canvas to find the angle you want to save. You can rotate the model by dragging, zoom in/out with scroll, and hold **Shift + drag** to pan left/right. For more details on canvas navigation, see [UI Overview](./ui-overview).
### Step 2: Save the Position
In the Camera Views section, click the **Add Current View** button. A new entry called "Camera View" will appear at the top of the list. This saves the exact camera position, target, and orientation.
### Step 3: Review the Saved View
Click on the saved view to expand it. You will see the stored coordinates (Position, Target, Quaternion, Up), plus Duration, Name, and three action buttons: **Focus View**, **Delete View**, and **Update View**.
Click **Focus View** to fly the camera to this saved position. The transition speed depends on the **Duration** setting — if you want an instant jump with no animation, set Duration to **0**.
### Step 4: Add More Views
Rotate your model to a new angle (for example, a top-down view) and click **Add Current View** again. A second Camera View entry will appear. Repeat this for as many views as you need — front, side, top, close-up on a detail, etc.
### Step 5: Animate Between Views
Click the **Animate All Views** button in the main settings. The camera will smoothly transition through all saved positions in order.
To fine-tune the animation, adjust these key settings:
- **Duration** — increase for slower, more cinematic transitions
- **Ease** — controls the acceleration curve. **easeInOutSine** is the most popular choice for smooth, natural motion
- **Interpolation** — **Spherical** is the most commonly used for camera movements
- **Loop All Views** — enable to loop continuously, so the last view transitions back to the first
---
## Use Cases
**Single view as a home position** — If you want your product page to always start from a specific angle, save just one Camera View. Users can rotate the model freely, and the scene can always snap back to this starting position.
**Multiple views for product showcase** — Create 3–4 or more Camera Views to highlight different details of your jewelry: front face, top-down, side profile, close-up on the setting. Use **Animate All Views** or **Loop All Views** to present them as a guided tour.
---
## Per-View Buttons
Each saved Camera View has three action buttons:
Focus View
Delete View
Update View
- **Focus View** — Flies the camera to this saved position
- **Delete View** — Permanently removes this view
- **Update View** — Overwrites the saved coordinates with the current canvas position
::: warning
**Delete View** and **Update View** are irreversible. There is no undo — once you delete or update a view, the previous data is gone.
:::
---
## General Settings
Loop All Views
checkbox
Loops the animation continuously — the last view transitions back to the first
View Pause Time
input
How long the camera pauses at each view before moving to the next
Ease
select
Transition easing curve. Recommended: easeInOutSine for smooth, natural motion
Duration
slider
Transition time between views. Increase for slower, more cinematic movement
Rotation Offset
slider
Adds a rotation offset to the camera path
Interpolation
select
Camera path interpolation method. Recommended: Spherical
Seek on Scroll
checkbox
Ties the camera view transition to page scroll position
Animate All Views
Record All Views
Add Current View
Focus Next
Focus Previous
- **Animate All Views** — Plays the full transition sequence through all saved views
- **Record All Views** — Records the camera view animation as an MP4 video and downloads it to your computer. This is the same as **Export → Video Export → Record Camera Views**
- **Add Current View** — Saves the current canvas camera position as a new view
- **Focus Next** — Jumps to the next saved view
- **Focus Previous** — Jumps to the previous saved view
---
## Common Mistakes
::: danger Changing Field of View breaks Camera Views
If you change the **Field of View** setting in **Viewer → Camera**, all previously saved Camera Views will become inaccurate — the framing and zoom will shift. You will need to delete and re-create your Camera Views after changing Field of View. Always set your Field of View **before** creating Camera Views.
:::
---
## Video Tutorial
### iJewel3D Video Rendering — Camera Paths & Animated Lightmaps
---
## Related Pages
- **[Export Videos](./export-videos)** — Export camera view animations as video files
- **[Animations](./animations)** — Overview of all animation sections
- **[FAQ: Cameras & Animations](./faq-cameras)** — Common questions about cameras and camera paths
- **[Cameras (Loaded)](./cameras-loaded)** — Working with cameras imported from 3D software
---
# Viewer Animations
Viewer Animations lets you create dynamic, cinematic scenes by combining multiple visual effects into a single animation sequence. You can animate environment rotation, background color, lighting intensity, post-processing effects, and camera properties — all at the same time or in a carefully timed sequence.
This is one of the most powerful tools for creating professional jewelry presentations. By layering a few animation blocks — spinning the environment for moving reflections on metal, rotating the diamond light map for sparkle, and shifting the background color — you can turn a static 3D model into a living, cinematic preview.
You can also use these animations as **animated product images** — for example, when a customer hovers over your ring on a product page, the static thumbnail can transition into a looping video that showcases sparkling diamonds and moving reflections. Record the animation using [Export Videos](./export-videos) and embed it as a hover-triggered video on your website.
## Where to Find It
This section is located on the [right panel](./ui-overview#right-panel-—-professional-tools), inside the Animations tab, in the **Viewer Animations** section.
---
## How to Create an Animation — Step by Step
### Step 1: Add a New Animation Block
In the Viewer Animations section, click the **Add Animation** button at the bottom of the panel. A new collapsible tab labeled "Animation" will appear.
### Step 2: Choose a Property
Expand the new animation tab and select the property you want to animate from the **Property** dropdown. For example, choose **Environment Rotation** to make reflections move across your jewelry's metal surface.
### Step 3: Configure the Settings
Set your desired values:
- **From / To** — the start and end values for the animation (for colors, use the color pickers)
- **Duration** — animation length in milliseconds (e.g., `3000` = 3 seconds)
- **Ease** — the speed curve (e.g., `easeInOutSine` for a smooth start and finish)
- **Repeat Type** — what happens when the animation ends (Loop, Mirror, or Reverse)
Make sure the **updateScene** and **updateViewer** checkboxes are enabled — without them, the animation will not be visible.
### Step 4: Play the Animation
Click the **Animate** button at the top of the panel to start the animation. You should see the effect in real time on your model.
### Step 5: Add More Effects
Repeat Steps 1–3 to add more animation blocks. For example, add a second block for **Diamond Env Map Rotation** and a third for **Background Color**. Enable **Run in Parallel** to play them all at the same time.
---
## Popular Animation Examples
Here are four commonly used animations for jewelry presentations.
### Diamond Env Map Rotation
The signature jewelry animation. Rotates the environment map only for Diamond materials, making the gemstone facets sparkle and shift with light. Combine this with Environment Rotation for the most realistic result — the metal and the stone animate independently.
### Environment Rotation
Rotates the HDRI map around your model, making reflections glide across polished metal surfaces. Set **From** to `0` and **To** to `6.28` for a full 360° loop. Use **Mirror** repeat type for a seamless back-and-forth motion.
### Background Color
Smoothly transitions the scene background between two colors — for example, from warm ivory to cool grey. This creates a subtle atmospheric shift that enhances the cinematic feel of your presentation.
### Tonemap Exposure
Dynamically adjusts the exposure level of the final image. This can simulate a "reveal" effect — starting dim and fading up to full brightness, or creating a dramatic spotlight moment.
---
## Pro Tip: The Perfect Jewelry Preview
To create a professional, cinematic product preview, set up three animation blocks:
1. **Diamond Env Map Rotation** — for sparkling gemstone fire
2. **Environment Rotation** — for moving reflections on metal
3. **Background Color** — for a soft atmospheric color shift
Enable **Run in Parallel**, set all three to the same **Duration** (e.g., `5000` ms), and use **Mirror** as the Repeat Type. Your scene will come to life with smooth, looping motion that showcases your jewelry from its best angle.
---
## Video Tutorial
This tutorial covers both Camera Views and Viewer Animations in one walkthrough:
### iJewel3D Video Rendering — Camera Paths & Animated Lightmaps
---
## Master Controls & Animation List
The buttons at the top of the panel control all animation blocks simultaneously:
Animate
Animate Reverse
Stop
- **Animate** — Starts all animation blocks from top to bottom
- **Animate Reverse** — Plays all animations in reverse (from end value back to start value)
- **Stop** — Immediately stops all active animations
You can create an unlimited number of animation blocks for a single scene. Each block appears as a collapsible tab.
Add Animation
button
Creates a new animation block at the bottom of the list
Run in Parallel
checkbox
When enabled, all animations play simultaneously. When disabled, they play sequentially (first finishes, then second starts, etc.)
Each animation block contains the following parameters:
From / To
input
Start and end values for the animation. For colors, a color picker is shown
Duration
input
Animation length in milliseconds (e.g.,
3000 = 3 seconds)Ease
select
Speed curve for the animation. Recommended: easeInOutSine for smooth motion
Repeat Type
select
Behavior after the animation ends — Loop (restart from beginning), Mirror (reverse back and forth), or Reverse (play backwards continuously)
updateScene
checkbox
Calculates the scene changes. Must be enabled for the animation to work
updateViewer
checkbox
Renders the visual output. Must be enabled for the animation to be visible
updateCamera
checkbox
Enable only when animating camera properties (FOV, Depth of Field). Not needed for environment or post-processing animations
Background Color
Smooth transition between two background colors (use From/To color pickers)
Environment Rotation
Rotates the HDRI environment map, making reflections move across metal surfaces. Use values
0 to 6.28 for a full 360° rotationEnvironment Intensity
Changes the overall scene brightness (from 0 to 1 and above)
Fixed Env Map Direction
Locks the environment map direction during rotation
Directional Light Color / Direction
Animate the color and direction of the directional light source
Diamond Env Map Rotation
Rotates the environment map only for Diamond materials, creating a sparkling "fire" effect inside gemstone facets. Use values
0 to 6.28 for a full rotationTonemap Exposure
Animate the exposure level of the final image
Tonemap Saturation
Animate the color saturation of the scene
Tonemap Contrast
Animate the contrast level of the frame
Tonemap Tone Mapping
Switch between different tone mapping algorithms
Camera FOV
Animate the field of view for a dolly zoom or push-in/pull-out effect
Depth of Field
Animate Focal Point, Blur Scale, and Focal Depth Range to smoothly shift focus between foreground and background
Chromatic Aberration
Add a color fringing lens effect for a cinematic look
Filmic Grain
Animate film grain intensity for a movie-like visual style
Bloom (Intensity, Radius, Power)
Animate the soft glow around bright areas of the scene
SSR (Intensity, Boost)
Animate Screen Space Reflections intensity in real time
Vignette (Color, Power)
Animate the edge darkening to draw focus to the center of the frame
Scrollable Camera Views Preview controls how the camera behaves when the user scrolls the page. Instead of clicking buttons to transition between views, the camera position is tied directly to the scroll position — as the user scrolls down, the camera smoothly moves through all saved [Camera Views](./camera-views).
This is especially useful for product landing pages where you want the 3D model to animate cinematically as the visitor scrolls through the page content.
## Where to Find It
This section is located on the [right panel](./ui-overview#right-panel-—-professional-tools), inside the Animations tab, in the **Scrollable Camera Views Preview** section.
---
## Settings
Enabled
checkbox
Toggles scroll-driven camera control on or off
Ease
select
Easing function that controls how the camera accelerates and decelerates. Default: easeInOutSine for smooth, natural motion
Interpolation
select
Camera path interpolation method. Spherical moves the camera along an arc around the object, preserving distance and preventing the camera from clipping through models
Enable Damping
checkbox
Adds inertia to the camera movement. When enabled, the camera doesn't stop instantly after scrolling — it smoothly glides to its final position
Damping
slider
Damping coefficient (default:
0.040). Lower values create a smoother, more "buttery" glide after scrolling stops. Higher values make the camera respond more immediatelyInit Anim Time
slider
Duration (in seconds) of the initial animation when the page first loads or the scene first appears (default:
1.000)Canvas on Top
checkbox
When enabled, the 3D canvas renders above other page elements. Useful for debugging layer overlap issues
The Physics section controls the physics engine for your scene. It enables gravity, collisions, and inertia for objects, making interactions with jewelry and scene elements feel realistic and dynamic.
A common use case in iJewel is **gyroscope-driven motion** — when a customer tilts their phone, the physics engine "pushes" objects in the scene. Pendants start swinging, stones catch the light from different angles, and the jewelry feels like it's physically in the viewer's hands.
## Where to Find It
This section is located on the [right panel](./ui-overview#right-panel-—-professional-tools), inside the Animations tab, in the **Physics** section.
---
## Settings
Enabled
checkbox
Global physics toggle. When disabled, all objects remain static. When enabled, physics laws apply — objects with mass can fall, collide, and respond to forces
Step Count
input
Number of physics calculations per frame (default:
100). Higher values produce more accurate simulations but increase CPU loadDelta
input
Time step for each physics calculation (default:
0.10). Controls how fast time flows in the physics simulation
Step
Make Root Bodies
- **Step** — Manually advances the physics simulation by one step. Useful for debugging to see exactly where objects will move next
- **Make Root Bodies** — Automatically creates physics bodies for the root objects of your model. This turns regular 3D objects into physical entities with mass that can collide and interact with each other
---
## Related Pages
- **[Viewer Animations](./viewer-animations)** — Create dynamic scenes with combined visual effects
- **[Animations](./animations)** — Overview of all animation sections
- **[Camera Views](./camera-views)** — Save camera positions and animate transitions
---
# Materials
Materials define how every surface in your scene looks — the color, reflectivity, roughness, and transparency of metals, gemstones, ceramics, pearls, and more. iJewel Playground uses two specialized material types: **Physical Material (PBR)** for opaque surfaces like metals and ceramics, and **Diamond Material** for gemstones with ray-traced refraction and sparkle.
You can start from scratch by adjusting every parameter manually, or use one of the 300+ ready-made presets from the built-in library to get professional results instantly.
## Where to Find It
Materials can be accessed in two ways:
1. **Left panel — Material Presets** — Click on any object in the canvas, then browse the preset library tabs (Metals, Gems, Ceramics, Pearls, Other) to apply a preset with one click
2. **Right panel — Picking** — Select an object in the canvas while in Picking mode to open its full material editor (Physical Material or Diamond Material)
---
## Sections
PBR Materials
Physical material editor for metals, ceramics, glass, and all opaque surfaces
Diamond Materials
Specialized shader for diamonds, emeralds, sapphires, and all gemstones
Material Presets
300+ ready-made materials from the built-in library
Material Configurator
Create interactive material variations for your embedded viewer
---
## Related Pages
- **[Export Materials](./export-materials)** — Save and share material presets
- **[Import Materials](./import-materials)** — Load saved material presets
- **[FAQ: Materials & Diamonds](./faq-materials)** — Common questions about materials
- **[Post Processing](./post-processing)** — Visual effects applied to the final render
---
# PBR Materials
Physical Materials (PBR) control how surfaces look in your scene — their color, reflectivity, roughness, transparency, and more. This is the most detailed material editor in iJewel Playground and it uses a physically-based rendering model to produce realistic results.
Every metal, stone setting, enamel, ceramic, or glass surface in your jewelry model is controlled through this panel.
## How to Open
1. Click on any object in the canvas to select it
2. Go to the Picking tab on the [right panel](./ui-overview#right-panel-—-professional-tools)
3. The Picker will show the material name, and the **Physical Material** section will open below with all its settings
::: tip Merging Materials
You can rename a material in the **name** field. If you select a different object and rename its material to the **same name**, both objects will share the same material — any change to one will apply to both. This is useful when applying library presets to multiple objects at once.
:::
---
## Physical Material
These are the top-level settings that appear when you expand the Physical Material section.
name
input
Material name. Rename for convenience (e.g., "Metal", "Pearl") or to merge materials by giving them the same name
wireframe
checkbox
Shows the polygon structure of the mesh instead of the solid surface
vertexColors
checkbox
Enables vertex color data from the model. Usually black by default — rarely needs to be changed
color
color picker
The base color of the material. Use the color picker or enter a hex value directly. The format is
0x followed by 6 hex digits (e.g., 0xe5b377 for gold) — keep the 0x prefix and change only the last 6 characters
Custom color applied to metal
Gold metal material
map
image
Texture map applied on top of the base color. Requires UV unwrapping on the model. If your model has no UVs, enable Triplanar mapping below — seamless textures will wrap automatically
Texture map on surface
Wood texture with Triplanar
roughness
slider
How rough or smooth the surface is.
0 = mirror-like, 1 = completely mattemetalness
slider
How metallic the surface is.
1 = fully metallic (gold, silver), 0 = non-metallic (ceramic, plastic)roughnessMap
image
Texture that controls roughness variation across the surface. When added, a roughnessMap Sampler section appears for positioning
metalnessMap
image
Texture that controls metalness variation across the surface. When added, a metalnessMap Sampler appears
Roughness: 0
Roughness: 1
Metalness: 0
Roughness: 0.25, Metalness: 0.80
Roughness map applied
bumpScale
slider
Controls the intensity of the bump effect
bumpMap
image
Black-and-white texture for surface bumps. When added, a bumpMap Sampler appears
normalMap
image
Purple-tinted normal map for detailed surface normals. Adds normalMap Sampler, normalScale (two inputs for X/Y strength), and normalMapType (Tangent Space)
displacementMap
image
Displacement texture that actually moves vertices. Adds displacementMap Sampler and displacementScale
Bump map on metal surface
sheen
slider
Intensity of the sheen effect
sheenColorMap
image
Texture controlling the sheen color across the surface
sheenRoughness
slider
Roughness of the sheen layer
sheenRoughnessMap
image
Texture controlling sheen roughness across the surface
clearcoat
slider
Intensity of the clearcoat layer.
0 = off, 1 = full reflective coatingclearcoat-Roughness
slider
Roughness of the clearcoat layer itself
clearcoatMap
image
Texture controlling clearcoat intensity across the surface
clearcoatRoughnessMap
image
Texture controlling clearcoat roughness across the surface
clearcoatNormalMap
image
Normal map for the clearcoat layer specifically
Clearcoat: 0
Clearcoat: 1
emissive
color picker
The color of the emitted light
emissiveIntensity
input
Brightness of the emission. Higher values create a stronger glow
emissiveMap
image
Texture controlling which parts of the surface emit light. When added, a Map Sampler appears
ior
slider
Index of Refraction — how much light bends when passing through. Glass ≈ 1.5, Diamond ≈ 2.42, Water ≈ 1.33
transmission
slider
How much light passes through the material.
1 = fully transparent, 0 = opaquethickness
input
The virtual thickness of the material, affecting how much light is absorbed
transmissionMap
image
Texture controlling transmission across the surface
thicknessMap
image
Texture controlling thickness variation across the surface
attenuationDistance
input
Distance at which light is fully absorbed by the material's color
attenuationColor
color picker
The color that light takes on as it passes through the material
Glass material with refraction
opacity
slider
Overall transparency of the object.
1.0 = fully visible, 0 = invisibletransparent
checkbox
Enables transparency rendering. Must be checked for opacity to take effect
depthFunc
select
Depth comparison function (default: LessEqual). Rarely needs to be changed
depthTest
checkbox
Whether to test against the depth buffer when rendering
depthWrite
checkbox
Whether to write to the depth buffer
colorWrite
checkbox
Whether to write color data to the frame buffer
alphaTest
slider
Alpha cutoff threshold. Pixels with alpha below this value are discarded
alphaHash
checkbox
Enables alpha hashing for order-independent transparency
dithering
checkbox
Adds dithering to reduce color banding artifacts
Blending
select
Blending mode (default: None)
alphaMap
image
Texture that controls transparency across the surface
Render to Depth
checkbox
Renders the material to the depth buffer
Inverse AlphaMap
checkbox
Inverts the alpha map values
Polygon Offset
checkbox
Enables polygon offset to prevent z-fighting between overlapping surfaces
Polygon Offset Factor
slider
Scale factor for the polygon offset
Polygon Offset Units
slider
Unit offset for the polygon offset
aoMapIntensity
slider
Strength of the ambient occlusion map
aoMap
image
Ambient occlusion texture
lightMapIntensity
slider
Strength of the light map
lightMap
image
Pre-baked lighting texture
Intensity
slider
Strength of the iridescent effect
IOR
slider
Index of refraction for the thin film layer
Thickness0
slider
Minimum thin film thickness. Adjust together with Thickness1 to control the color range
Thickness1
slider
Maximum thin film thickness
iridescenceMap
image
Texture controlling where iridescence appears on the surface
iridescenceThicknessMap
image
Texture controlling thickness variation for the iridescent layer
Override Environment
checkbox
Enables a custom environment map for this material only
Environment Intensity
slider
Brightness of the custom environment for this material
Environment Map
select
Choose from environment maps added to the scene
Side
select
Which side of the polygons to render. Double is most common. Use Front or Back for special effects
flatShading
checkbox
Disables smooth shading and shows flat polygon faces instead
Mesh count
read-only
Number of meshes using this material
Download pmat
Exports the current material as a **.pmat** file. You can save your custom material settings and reuse them later or share them with others.
---
## LUT
Apply a per-material Look Up Table for color grading. This works the same way as the global [LUT post-processing effect](./lut), but applies only to this specific material.
Enabled
checkbox
Toggles the per-material LUT
index
select
Select which LUT to apply from the available presets
Anisotropy — brushed metal reflections
Enabled
checkbox
Toggles the anisotropy effect
Factor
slider
Strength of the anisotropic stretch.
0 = uniform, 1 = fully stretchedNoise
slider
Adds randomness to the anisotropy direction
Texture
image
Direction map that controls the anisotropy direction per pixel
Mode
select
Anisotropy calculation mode (default: DIRECTION)
Triplanar mapping — no UV required
Enabled
checkbox
Toggles triplanar mapping on or off
Fix to Object
checkbox
Locks the texture to the object so it doesn't shift when the object moves
Scale
slider
Size of the projected texture. Smaller values = larger texture pattern
Blend
slider
How smoothly the three projection directions blend into each other
Offset
slider
Shifts the texture position
Enabled
checkbox
Toggles the thin film layer effect
Intensity
slider
Strength of the thin film effect
Base Layer
4 inputs
Base layer parameters (4 values)
Noise Layer
4 inputs
Noise layer parameters (4 values)
Noise Params
4 inputs
Additional noise parameters (4 values)
Enabled
checkbox
Toggles the layered material effect
cutoff
slider
Controls the threshold between the base material and the layered color. Adjust to control how much of the secondary color appears
color
color picker
The secondary color that appears in crevices and recesses
roughness
slider
Roughness of the secondary layer
Scale
slider
Scale of the pattern used to distribute the secondary layer
StepSize
slider
Controls the sharpness of the transition between layers
metalness
slider
Metalness of the secondary layer
LayeredMaterial — oxidized bronze effect
Remove Material
Duplicate Object
Wrap in Parent
Delete Object
- **Remove Material** — Strips the material from the selected object
- **Duplicate Object** — Creates a copy of the selected object
- **Wrap in Parent** — Wraps the selected object inside a new parent group
- **Delete Object** — Permanently removes the selected object from the scene
::: warning
**Delete Object** is irreversible. There is no undo — the object and its data will be permanently removed.
:::
---
## Physics
Per-object physics body settings. See the [Physics](./physics) page for global physics configuration.
---
## Transform Animation
Per-object transform animation settings for position, rotation, and scale keyframes.
---
## Video Tutorial
---
## Related Pages
- **[Material Presets](./material-presets)** — Browse and apply ready-made material presets from the library
- **[Diamond Materials](./diamond-materials)** — Material settings specific to gemstones and diamonds
- **[FAQ: Materials & Diamonds](./faq-materials)** — Common questions about materials
- **[Look Up Tables (LUT)](./lut)** — Global LUT post-processing
- **[Screen Space Bevel](./screen-space-bevel)** — Global SSBevel post-processing
- **[Bloom](./bloom)** — Global Bloom post-processing
---
# Diamond Materials
Diamond Material is a specialized shader designed for rendering gemstones — diamonds, emeralds, sapphires, rubies, and other precious stones. Unlike [PBR Materials](./pbr-materials), which simulate opaque surfaces, Diamond Material uses ray-traced refraction and dispersion to produce realistic sparkle, fire, and brilliance inside the stone.
How your gemstone looks depends heavily on the **HDRI environment map** assigned to it. Different HDRI maps produce dramatically different sparkle patterns, so try several options from the Gems library on the left panel or create your own. All images on this page use the **Gem001** HDRI map.
::: warning My diamond doesn't look right?
If your diamond looks white, flat, or lacks sparkle, the most common cause is the wrong HDRI environment map. See [FAQ: Materials & Diamonds](./faq-materials) for troubleshooting steps and video tutorials on fixing common diamond issues.
:::
## Gem Shapes
If your scene contains multiple diamond shapes (round, pear, oval, princess, marquise, emerald, etc.), each shape **must be on a separate material layer**. For example, round diamonds should be on a "Gem 01" layer, pear shapes on a "Gem 02" layer, and so on. If different shapes share the same material layer, you won't be able to adjust settings per shape, and some stones may render incorrectly.
### Video Tutorial — Fixing Diamond Rendering
### Shape Examples
Round
Pear
Oval
Princess
Marquise
Emerald
Picking tab on the [right panel](./ui-overview#right-panel-—-professional-tools)
3. The Picker will show the material name, and the **Diamond Material** section will open below with all its settings
If your object does not have a Diamond Material yet, you can assign one in two ways:
1. **From the Gems library** — Open the Gems tab on the left panel and select any gem preset to apply it to the selected object
2. **From Picking → Diamonds** — Go to the Picking panel, find the **Diamonds** section, and click **Make Diamond**. This converts the Physical Material on the selected object into a Diamond Material
---
## Diamond Material
name
input
Material name. Works the same as in PBR Materials — rename for convenience or give two objects the same name to merge their materials
wireframe
checkbox
Shows the polygon structure of the gemstone mesh
Environment
select
Select which environment map to use for this gemstone. If you have added multiple environments to the Diamonds section, you can assign different HDRIs to different stones
Color
color picker
The base color of the gemstone. White (
0xffffff) for a classic diamond, or any color for colored gemstones like emerald, sapphire, or ruby
Emerald green color applied to diamond
Env Intensity
slider
Controls the overall brightness of the gemstone. Default is around
1.30. Increase for a brighter, more vivid stone; decrease for a subtler look
Env Intensity: 0.84 — slightly dimmer stone
Env Rotation Offset
slider
Rotates the HDRI map around the gemstone. Use this to find the perfect lighting angle — rotate until you see the most beautiful sparkle and fire for your current camera position
Env Rotation Offset X/Y/Z
slider
Fine-tune the environment map rotation on individual axes. Useful when one specific diamond has a bright overexposed spot — adjust these to shift the HDRI and fix it
Dispersion
slider
Adds rainbow color separation (chromatic dispersion) — the colorful "fire" effect you see in real diamonds when light splits into its spectral colors
Dispersion enabled — rainbow fire effect
Absorption
slider
Intensifies the selected Color for colored gemstones. Only visible when the stone has a non-white color — higher values produce a deeper, more saturated tint
Absorption — intensified color on a tinted stone
Refractive Index
slider
Controls the depth and brilliance of the stone. Default is
2.60. Lower values create a shallower, less brilliant look. Increase or decrease depending on the stone shape and cut — unusual or custom cuts may need adjustmentGamma
slider
Contrast adjustment for the gemstone's internal colors. Default is
1.00. Increase to boost contrast and make colors more vivid, decrease for a softer lookRGB Boost
3 inputs
Boost individual Red, Green, and Blue channels. An alternative to the Color picker for adding specific tints — can produce brighter, more saturated color effects
RGB Boost: 2.0 / 2.0 / 2.0 — brighter, saturated tint
Transmission
slider
Makes the stone transparent, allowing the metal prongs and setting behind it to show through. This creates beautiful color reflections inside the gemstone from the surrounding metal
Transmission — metal prongs visible through the stone
Reflectivity
slider
Controls how much the surface of the gemstone reflects light. Higher values create a more mirror-like top surface
Ray Bounces
slider
Number of times light bounces inside the stone. Default is
4–5. Increase up to 16 for more realistic results on certain cuts
Ray Bounces: 12 — more realistic brilliance
Diamond Oriented Lighting
slider
Changes the orientation of the environment map relative to the stone
Mesh count
read-only
Number of meshes using this diamond material
uuid
read-only
Unique identifier for this material
Download .dmat
Exports the current diamond material as a **.dmat** file. You can save your custom gemstone settings and reuse them later. See [Export Materials](./export-materials) for more details.
---
## LUT
Apply a per-material Look Up Table for color grading. See the [Look Up Tables (LUT)](./lut) page for a full overview of how LUT works.
---
## ThinFilmLayer
Adds a thin film interference effect that creates rainbow-like color shifting on the stone's surface. See [PBR Materials — ThinFilmLayer](./pbr-materials#thinfilmlayer) for settings details.
---
## Flat Material
Renders the gemstone without any lighting calculations — a flat, unlit appearance.
---
## Bloom
Per-material Bloom toggle. Allows you to enable or disable the [Bloom](./bloom) post-processing effect for this specific gemstone.
---
## Inclusions
Enabled
checkbox
Toggles inclusions on or off
VariableBlur
slider
Controls the blur amount applied to inclusion textures
VariableParam1
slider
First variable parameter for inclusion rendering
VariableParam2
slider
Second variable parameter for inclusion rendering
blurRadius
slider
Radius of the blur applied to inclusions
ClampHDR
checkbox
Clamps HDR values in the inclusion rendering
SurfaceScale
slider
Scale of the surface texture for inclusions
Color Map Scale
slider
Scale of the color map used for inclusions
BumpScale
slider
Intensity of the bump effect from inclusion textures
InclusionScale
slider
Scale of the inclusion pattern inside the stone
IncNormalScale
slider
Scale of the inclusion normal map effect
InclusionRoughnessMap
image
Roughness texture for the inclusion areas
InclusionMap
image
Main inclusion texture — black-and-white map that defines where inclusions appear inside the stone
Surface Roughness
slider
Roughness of the stone's surface (not the internal inclusions)
RoughnessMap
image
Surface roughness texture map
normalMap
image
Normal map for surface detail on the stone
InclusionNormalMap
image
Normal map specifically for inclusions — adds additional surface detail to the inclusion areas
Map
image
General texture map for the gemstone surface
Remove Material
Duplicate Object
Wrap in Parent
Delete Object
- **Remove Material** — Strips the material from the selected object
- **Duplicate Object** — Creates a copy of the selected object
- **Wrap in Parent** — Wraps the selected object inside a new parent group
- **Delete Object** — Permanently removes the selected object from the scene
---
## Physics
Per-object physics body settings. See the [Physics](./physics) page for global physics configuration.
---
## Transform Animation
Per-object transform animation settings for position, rotation, and scale keyframes.
---
## Diamond Close-Up Views
Front
Side
Back
iJewel Playground includes a library of 300+ ready-made materials that you can apply to any object with a single click. The presets are professionally configured and cover the most common jewelry materials — from yellow and white gold to emeralds, sapphires, pearls, and ceramics.
## How to Use
1. Click on any object in the canvas to select it
2. On the left panel, browse the material categories using the tabs at the top
3. Click on any preset thumbnail to apply it instantly to the selected object
## Categories
The library is organized into five tabs:
Metals
Gold (yellow, white, rose), silver, platinum, palladium, brass, copper, bronze, titanium, and more. Applies a PBR Material
Gems
Diamonds (white, colored), emeralds, sapphires, rubies, amethyst, topaz, and many more. Applies a Diamond Material
Ceramics
Ceramic, marble, enamel, and other non-metallic surfaces. Applies a PBR Material with clearcoat
Pearls
Pearl materials with iridescence and soft sheen effects. Applies a PBR Material with iridescence
Other
Wood, leather, fabric, glass, rubber, and other specialized surfaces
The Material Configurator lets you create interactive material variations for your 3D model. When embedded in the [iJewel Viewer](../viewer/introduction), your customers can switch between different metals, gemstone colors, ceramics, pearls, and any other materials — directly on your product page.
When you add a configurator, a UI bar appears at the bottom of the canvas. The lower bar shows the configuration name (e.g., "Metal"), and the upper bar displays the available material variants as clickable thumbnails.
---
## Adding a Material Configurator — Step by Step
### Step 1: Select the Object
Click on the object in the canvas that you want to add material variations to. The object will be highlighted.
### Step 2: Open the Configurator
At the top of the canvas, click the **Add Configurator** button. A material library panel will appear with tabs for different categories (Metals, Gems, Ceramics, Pearls, Other).
### Step 3: Choose Materials
Click on any material to add it as a variant — it will instantly appear in the configurator bar at the bottom of the canvas. You can add as many variants as you want — there is no limit. Click on a selected material again to remove it.
### Step 4: Done
The configuration name is automatically taken from the material name of the selected object. You can now click on different variants in the bottom bar to preview how each material looks on your model.
---
## Adding Gem Variations
The process works the same for gemstones. Select a gem object, click **Add Configurator**, and the library will automatically open to the **Gems** tab (since the selected object already has a [Diamond Material](./diamond-materials)). Choose your gem variants the same way.
---
## Adding Custom Materials
If you've created a custom material in the [PBR Materials](./pbr-materials) or [Diamond Materials](./diamond-materials) editor (for example, a specific color or texture), you can add it as a variant too:
1. Make sure your object is still selected
2. Make all the material changes you need in the Picking panel
3. At the bottom of the canvas, click the **+** button (Add Current Material) — the last button in the configurator bar
This adds your current custom material as a new variant.
---
## Editing the Configuration Name
The configuration name appears in the lower bar on the canvas (e.g., "Metal", "Gem"). To change it:
1. Enter Edit mode — either click the **Edit Configurator** button at the top of the canvas (after selecting the object), or right-click on the configuration name and choose **Edit**
2. Change the name in the input field at the top of the material library panel
---
## Editing Variant Names
Each material variant has a name that appears as a tooltip on hover. To rename a variant:
1. Hover over the variant thumbnail in the configurator bar
2. A tooltip with the variant name will appear — move your cursor to the right side of the tooltip
3. Click the **pencil icon** to edit the name
---
## Removing a Material Variant
There are two ways to remove a variant from the configurator:
**Method 1** — Right-click on the variant thumbnail in the configurator bar and click **Delete**
**Method 2** — Enter Edit mode and click on the material in the library to deselect it
---
## Deleting an Entire Configuration
To remove the entire configurator from an object:
---
## Right Panel Controls
You can also manage the configurator from the right panel. Select an object and go to the **Configurator** tab to find the **Material Configurator** section.
The right panel provides additional buttons:
Clear Variations
Remove Completely
Add Variation
Refresh UI
Apply All
- **Clear Variations** — Removes all material variations from the selected configurator
- **Remove Completely** — Deletes the entire configurator from the object
- **Add Variation** — Adds the material currently applied to the object (the one you edited in the [Picking](./pbr-materials) panel) as a new variant
- **Refresh UI** — Refreshes the configurator UI on the canvas
- **Apply All** — Applies changes to all configurator entries
---
## Downloading & Importing Configurations
### Download a Configuration Preset
To save your configurator setup for reuse across other scenes:
1. Go to the **Configurator** tab on the right panel
2. Find the **Material Configurator** section
3. Click the **three dots** (⋯) next to the section title
4. Click **Download Preset**
A `.json` file will be downloaded to your computer containing all your material configurations.
### Import a Configuration Preset
To apply a saved configuration to a new scene:
1. Open the new scene in Playground
2. Drag and drop the `.json` file into the canvas
The configurator will automatically apply to objects that have matching material names. This is why it's important to keep consistent material names across your models.
::: warning Material names must match
The configurator links to objects by their **material name** (the `name` field in [PBR Materials](./pbr-materials#physical-material) or [Diamond Materials](./diamond-materials#diamond-material)). If you rename a material after creating a configurator, the link will break and the configurator will stop working. Always set your material names before creating configurations.
:::
---
## Video Tutorial
### Transfer Configurator Between Projects
---
## Related Pages
- **[PBR Materials](./pbr-materials)** — Physical material editor for metals, ceramics, and surfaces
- **[Diamond Materials](./diamond-materials)** — Diamond material editor for gemstones
- **[Material Presets](./material-presets)** — Browse the built-in material library
- **[Export Scene Settings](./export-scene-settings)** — Export full scene settings including configurator data
- **[Import Scene Settings](./import-scene-settings)** — Import scene configurations
- **[FAQ: Materials & Diamonds](./faq-materials)** — Common questions about materials
---
# Material Configurator
The Material Configurator lets you create interactive material variations for your 3D model. When embedded in the [iJewel Viewer](../viewer/introduction), your customers can switch between different metals, gemstone colors, ceramics, pearls, and any other materials — directly on your product page.
When you add a configurator, a UI bar appears at the bottom of the canvas. The lower bar shows the configuration name (e.g., "Metal"), and the upper bar displays the available material variants as clickable thumbnails.
---
## Adding a Material Configurator — Step by Step
### Step 1: Select the Object
Click on the object in the canvas that you want to add material variations to. The object will be highlighted.
### Step 2: Open the Configurator
At the top of the canvas, click the **Add Configurator** button. A material library panel will appear with tabs for different categories (Metals, Gems, Ceramics, Pearls, Other).
### Step 3: Choose Materials
Click on any material to add it as a variant — it will instantly appear in the configurator bar at the bottom of the canvas. You can add as many variants as you want — there is no limit. Click on a selected material again to remove it.
### Step 4: Done
The configuration name is automatically taken from the material name of the selected object. You can now click on different variants in the bottom bar to preview how each material looks on your model.
---
## Adding Gem Variations
The process works the same for gemstones. Select a gem object, click **Add Configurator**, and the library will automatically open to the **Gems** tab (since the selected object already has a [Diamond Material](./diamond-materials)). Choose your gem variants the same way.
---
## Adding Custom Materials
If you've created a custom material in the [PBR Materials](./pbr-materials) or [Diamond Materials](./diamond-materials) editor (for example, a specific color or texture), you can add it as a variant too:
1. Make sure your object is still selected
2. Make all the material changes you need in the Picking panel
3. At the bottom of the canvas, click the **+** button (Add Current Material) — the last button in the configurator bar
This adds your current custom material as a new variant.
---
## Editing the Configuration Name
The configuration name appears in the lower bar on the canvas (e.g., "Metal", "Gem"). To change it:
1. Enter Edit mode — either click the **Edit Configurator** button at the top of the canvas (after selecting the object), or right-click on the configuration name and choose **Edit**
2. Change the name in the input field at the top of the material library panel
---
## Editing Variant Names
Each material variant has a name that appears as a tooltip on hover. To rename a variant:
1. Hover over the variant thumbnail in the configurator bar
2. A tooltip with the variant name will appear — move your cursor to the right side of the tooltip
3. Click the **pencil icon** to edit the name
---
## Removing a Material Variant
There are two ways to remove a variant from the configurator:
**Method 1** — Right-click on the variant thumbnail in the configurator bar and click **Delete**
**Method 2** — Enter Edit mode and click on the material in the library to deselect it
---
## Deleting an Entire Configuration
To remove the entire configurator from an object:
---
## Right Panel Controls
You can also manage the configurator from the right panel. Select an object and go to the **Configurator** tab to find the **Material Configurator** section.
The right panel provides additional buttons:
Clear Variations
Remove Completely
Add Variation
Refresh UI
Apply All
- **Clear Variations** — Removes all material variations from the selected configurator
- **Remove Completely** — Deletes the entire configurator from the object
- **Add Variation** — Adds the material currently applied to the object (the one you edited in the [Picking](./pbr-materials) panel) as a new variant
- **Refresh UI** — Refreshes the configurator UI on the canvas
- **Apply All** — Applies changes to all configurator entries
---
## Downloading & Importing Configurations
### Download a Configuration Preset
To save your configurator setup for reuse across other scenes:
1. Go to the **Configurator** tab on the right panel
2. Find the **Material Configurator** section
3. Click the **three dots** (⋯) next to the section title
4. Click **Download Preset**
A `.json` file will be downloaded to your computer containing all your material configurations.
### Import a Configuration Preset
To apply a saved configuration to a new scene:
1. Open the new scene in Playground
2. Drag and drop the `.json` file into the canvas
The configurator will automatically apply to objects that have matching material names. This is why it's important to keep consistent material names across your models.
::: warning Material names must match
The configurator links to objects by their **material name** (the `name` field in [PBR Materials](./pbr-materials#physical-material) or [Diamond Materials](./diamond-materials#diamond-material)). If you rename a material after creating a configurator, the link will break and the configurator will stop working. Always set your material names before creating configurations.
:::
---
## Video Tutorial
### Transfer Configurator Between Projects
---
## Related Pages
- **[PBR Materials](./pbr-materials)** — Physical material editor for metals, ceramics, and surfaces
- **[Diamond Materials](./diamond-materials)** — Diamond material editor for gemstones
- **[Material Presets](./material-presets)** — Browse the built-in material library
- **[Export Scene Settings](./export-scene-settings)** — Export full scene settings including configurator data
- **[Import Scene Settings](./import-scene-settings)** — Import scene configurations
- **[FAQ: Materials & Diamonds](./faq-materials)** — Common questions about materials
---
# Material Configurator
The Material Configurator lets you create interactive material variations for your 3D model. When embedded in the [iJewel Viewer](../viewer/introduction), your customers can switch between different metals, gemstone colors, ceramics, pearls, and any other materials — directly on your product page.
When you add a configurator, a UI bar appears at the bottom of the canvas. The lower bar shows the configuration name (e.g., "Metal"), and the upper bar displays the available material variants as clickable thumbnails.
---
## Adding a Material Configurator — Step by Step
### Step 1: Select the Object
Click on the object in the canvas that you want to add material variations to. The object will be highlighted.
### Step 2: Open the Configurator
At the top of the canvas, click the **Add Configurator** button. A material library panel will appear with tabs for different categories (Metals, Gems, Ceramics, Pearls, Other).
### Step 3: Choose Materials
Click on any material to add it as a variant — it will instantly appear in the configurator bar at the bottom of the canvas. You can add as many variants as you want — there is no limit. Click on a selected material again to remove it.
### Step 4: Done
The configuration name is automatically taken from the material name of the selected object. You can now click on different variants in the bottom bar to preview how each material looks on your model.
---
## Adding Gem Variations
The process works the same for gemstones. Select a gem object, click **Add Configurator**, and the library will automatically open to the **Gems** tab (since the selected object already has a [Diamond Material](./diamond-materials)). Choose your gem variants the same way.
---
## Adding Custom Materials
If you've created a custom material in the [PBR Materials](./pbr-materials) or [Diamond Materials](./diamond-materials) editor (for example, a specific color or texture), you can add it as a variant too:
1. Make sure your object is still selected
2. Make all the material changes you need in the Picking panel
3. At the bottom of the canvas, click the **+** button (Add Current Material) — the last button in the configurator bar
This adds your current custom material as a new variant.
---
## Editing the Configuration Name
The configuration name appears in the lower bar on the canvas (e.g., "Metal", "Gem"). To change it:
1. Enter Edit mode — either click the **Edit Configurator** button at the top of the canvas (after selecting the object), or right-click on the configuration name and choose **Edit**
2. Change the name in the input field at the top of the material library panel
---
## Editing Variant Names
Each material variant has a name that appears as a tooltip on hover. To rename a variant:
1. Hover over the variant thumbnail in the configurator bar
2. A tooltip with the variant name will appear — move your cursor to the right side of the tooltip
3. Click the **pencil icon** to edit the name
---
## Removing a Material Variant
There are two ways to remove a variant from the configurator:
**Method 1** — Right-click on the variant thumbnail in the configurator bar and click **Delete**
**Method 2** — Enter Edit mode and click on the material in the library to deselect it
---
## Deleting an Entire Configuration
To remove the entire configurator from an object:
---
## Right Panel Controls
You can also manage the configurator from the right panel. Select an object and go to the **Configurator** tab to find the **Material Configurator** section.
The right panel provides additional buttons:
Clear Variations
Remove Completely
Add Variation
Refresh UI
Apply All
- **Clear Variations** — Removes all material variations from the selected configurator
- **Remove Completely** — Deletes the entire configurator from the object
- **Add Variation** — Adds the material currently applied to the object (the one you edited in the [Picking](./pbr-materials) panel) as a new variant
- **Refresh UI** — Refreshes the configurator UI on the canvas
- **Apply All** — Applies changes to all configurator entries
---
## Downloading & Importing Configurations
### Download a Configuration Preset
To save your configurator setup for reuse across other scenes:
1. Go to the **Configurator** tab on the right panel
2. Find the **Material Configurator** section
3. Click the **three dots** (⋯) next to the section title
4. Click **Download Preset**
A `.json` file will be downloaded to your computer containing all your material configurations.
### Import a Configuration Preset
To apply a saved configuration to a new scene:
1. Open the new scene in Playground
2. Drag and drop the `.json` file into the canvas
The configurator will automatically apply to objects that have matching material names. This is why it's important to keep consistent material names across your models.
::: warning Material names must match
The configurator links to objects by their **material name** (the `name` field in [PBR Materials](./pbr-materials#physical-material) or [Diamond Materials](./diamond-materials#diamond-material)). If you rename a material after creating a configurator, the link will break and the configurator will stop working. Always set your material names before creating configurations.
:::
---
## Video Tutorial
### Transfer Configurator Between Projects
---
## Related Pages
- **[PBR Materials](./pbr-materials)** — Physical material editor for metals, ceramics, and surfaces
- **[Diamond Materials](./diamond-materials)** — Diamond material editor for gemstones
- **[Material Presets](./material-presets)** — Browse the built-in material library
- **[Export Scene Settings](./export-scene-settings)** — Export full scene settings including configurator data
- **[Import Scene Settings](./import-scene-settings)** — Import scene configurations
- **[FAQ: Materials & Diamonds](./faq-materials)** — Common questions about materials
---
# Object Configurator
The Object Configurator in Playground allows you to create interactive **object variations** — letting end users switch between different design options (e.g., ring heads, pendant shapes, or bracelet links) directly in the embedded 3D viewer.
## How It Works
The Object Configurator operates by **toggling visibility** of objects within a single scene. All object variations are loaded into the scene at once, but only one is visible at a time. When the user selects a different option, the current object is hidden and the selected one is revealed.
**Example:** A ring with 5 different head designs — all 5 heads are present in the scene, but only the selected one is displayed. Switching between options is instant.
::: info
Because all variations must be included in a single file, this approach results in **larger file sizes**. The more object variations you add, the heavier the scene becomes.
:::
## Video Tutorial
Watch how to set up an Object Configurator in Playground step by step:
---
## When to Use
The Playground Object Configurator is suitable for:
- **Quick prototyping** — testing how different design options look together
- **Simple configurations** — a small number of variations (2–5 options)
- **Internal previews** — sharing design alternatives with your team before publishing
---
## Advanced: Ring Configurator on iJewel3D Platform
For production use and customer-facing configurators, we recommend the **Ring Configurator** available on the iJewel3D Platform.
Instead of loading all variations into one heavy file, the Platform Configurator uses an **anchor-based system**:
- **Components are separate files** — each head and shank is an independent, lightweight 3D model
- **Anchors define placement** — components snap together automatically at predefined anchor points
- **Files are swapped dynamically** — only the currently selected combination is loaded, keeping performance optimal
- **Hundreds of combinations** — mix and match heads, shanks, diamond shapes, carat sizes, and materials
This results in **significantly smaller file sizes** and a smoother user experience, especially for catalogs with many variations.
::: tip Getting Started with Ring Configurator
The Ring Configurator documentation covers everything from preparing 3D components to embedding the final configurator on your website:
**[Ring Configurator Documentation →](https://docs.ijewel3d.com/ring-configurator/introduction.html)**
:::
---
## Related Pages
- **[Material Configurator](./material-configurator)** — Switch materials (metals, gems, textures) interactively
- **[Ring Configurator (Platform)](https://docs.ijewel3d.com/ring-configurator/introduction.html)** — Advanced anchor-based configurator for production use
---
# Modifiers — Object Rotation
The Object Rotation modifier duplicates an object around a circle using instanced copies. Because it creates instances (not full copies), your scene stays lightweight and fast — even with dozens of duplicates. This is especially useful for creating chain links, repeating gemstone patterns, halo settings, and other circular arrangements common in jewelry design.
## Where to Find It
This section is located on the [right panel](./ui-overview#right-panel-—-professional-tools), inside the Picking tab, in the **Modifiers** section. Select an object in the canvas to see the modifier controls.
---
## Settings
Enable
Checkbox — activates the Object Rotation modifier on the selected object
Rotation Count
Slider — the total number of instances placed around the circle. Higher values produce a denser ring of copies
Axis
Select (X / Y / Z) — the axis around which the copies are rotated. Choose the axis that matches your model's orientation — for example, Y for a ring viewed from above
Rotation Skip
Input — comma-separated list of instance numbers to skip (e.g.,
0,1,3,5,7). Skipped positions will be empty, allowing you to create patterns with gaps. Instance numbering starts at 0
Make sure your object's pivot point is at the center of the scene, not inside the object itself. If the pivot is inside the object, all copies will stack on top of each other instead of spreading around a circle.
Picking tab, find the **Hierarchy** section, and click on the parent object's name in the hierarchy tree. This selects the parent along with all child objects beneath it.
### Step 2: Set the Rotation Count
Enable the modifier and set the **Rotation Count** to the total number of positions you need.
### Step 3: Use Rotation Skip
In the **Rotation Skip** field, enter the instance numbers you want to hide, separated by commas. For example, if you have 30 total positions and want diamonds only at even-numbered positions, enter all the odd numbers: `1,3,5,7,9,11,13,15,17,19,21,23,25,27,29`. Instance numbering starts at `0`.
The skipped instances will be removed, creating a pattern where only certain positions show the full parent-child group.
---
## Video Tutorial
### Object Rotation Modifier
---
## Related Pages
- **[Scene Basics](./scene)** — Overview of working with 3D objects
- **[Scene Hierarchy](./hierarchy)** — Understanding parent-child relationships
- **[Transform Controls](./transform-controls)** — Moving, rotating, and scaling objects
- **[PBR Materials](./pbr-materials)** — Physical material editor for metals and surfaces
- **[Diamond Materials](./diamond-materials)** — Diamond material editor for gemstones
---
# Modifiers — Object Rotation
The Object Rotation modifier duplicates an object around a circle using instanced copies. Because it creates instances (not full copies), your scene stays lightweight and fast — even with dozens of duplicates. This is especially useful for creating chain links, repeating gemstone patterns, halo settings, and other circular arrangements common in jewelry design.
## Where to Find It
This section is located on the [right panel](./ui-overview#right-panel-—-professional-tools), inside the Picking tab, in the **Modifiers** section. Select an object in the canvas to see the modifier controls.
---
## Settings
Enable
Checkbox — activates the Object Rotation modifier on the selected object
Rotation Count
Slider — the total number of instances placed around the circle. Higher values produce a denser ring of copies
Axis
Select (X / Y / Z) — the axis around which the copies are rotated. Choose the axis that matches your model's orientation — for example, Y for a ring viewed from above
Rotation Skip
Input — comma-separated list of instance numbers to skip (e.g.,
0,1,3,5,7). Skipped positions will be empty, allowing you to create patterns with gaps. Instance numbering starts at 0
Make sure your object's pivot point is at the center of the scene, not inside the object itself. If the pivot is inside the object, all copies will stack on top of each other instead of spreading around a circle.
Picking tab, find the **Hierarchy** section, and click on the parent object's name in the hierarchy tree. This selects the parent along with all child objects beneath it.
### Step 2: Set the Rotation Count
Enable the modifier and set the **Rotation Count** to the total number of positions you need.
### Step 3: Use Rotation Skip
In the **Rotation Skip** field, enter the instance numbers you want to hide, separated by commas. For example, if you have 30 total positions and want diamonds only at even-numbered positions, enter all the odd numbers: `1,3,5,7,9,11,13,15,17,19,21,23,25,27,29`. Instance numbering starts at `0`.
The skipped instances will be removed, creating a pattern where only certain positions show the full parent-child group.
---
## Video Tutorial
### Object Rotation Modifier
---
## Related Pages
- **[Scene Basics](./scene)** — Overview of working with 3D objects
- **[Scene Hierarchy](./hierarchy)** — Understanding parent-child relationships
- **[Transform Controls](./transform-controls)** — Moving, rotating, and scaling objects
- **[PBR Materials](./pbr-materials)** — Physical material editor for metals and surfaces
- **[Diamond Materials](./diamond-materials)** — Diamond material editor for gemstones
---
# Rainbow Diamond Coloring
Rainbow Diamond Coloring creates a smooth, seamless color gradient across a series of diamonds. The gradient loops perfectly — the first color flows into the last without any visible break, producing a beautiful infinite rainbow effect. This feature is located in the **Extras** tab on the right panel.
---
## Step-by-Step Guide
### Step 1: Prepare Your Model
Before using this feature, your diamonds must be named correctly in your 3D software. Each diamond should have a consistent name prefix followed by a sequential number — for example:
`gem001`, `gem002`, `gem003`, … `gem040`
The numbering must be sequential so the gradient follows the correct order around the model. This is the only preparation needed — once the names are in order, you're ready to go.
### Step 2: Apply a Diamond Material
Select one of the gem objects in the canvas and apply a [Diamond Material](./diamond-materials) to it. Make sure all the diamonds in the sequence share the same material layer.
### Step 3: Open the Extras Tab
Go to the Extras tab on the right panel and find the **Rainbow Diamond Coloring** section.
### Step 4: Set the Object Name Prefix
In the **Object Name Prefix** field, enter only the name part without the numbers. For example, if your diamonds are named `gem001` through `gem040`, type just `gem`.
### Step 5: Set the Count
In the **Count** field, enter the total number of diamonds in your sequence. For example, `40` if you have `gem001` to `gem040`.
### Step 6: Set the Loops
In the **Loops** field, choose how many times the color gradient should repeat across the full sequence. For example, `1` loop means one full rainbow cycle across all diamonds, `2` loops means the gradient repeats twice.
### Step 7: Choose the Starting Color
Click on the color picker and select the starting color for your gradient. The gradient will automatically generate a full rainbow cycle starting from this color. Red is a common choice for a classic rainbow effect.
### Step 8: Apply
Click the **Color All Items** button. The rainbow gradient will instantly be applied across all your diamonds in sequence.
---
## Settings
Object Name Prefix
Input — the shared name prefix of your diamond objects, without the sequential numbers (e.g.,
gem for gem001–gem040)Count
Input — the total number of diamonds in the sequence
Loops
Input — how many times the full color cycle repeats across all diamonds.
1 produces a single seamless rainbow, higher values create a tighter repeating patternColor
Color picker — the starting color for the gradient. The gradient generates a full hue cycle from this color
Color All Items
Button — applies the rainbow gradient to all diamonds matching the prefix
Extras tab, in the **Snow Fall Particles** section.
---
## Settings
enabled
Checkbox — activates the snowfall effect in the scene
Bounds size
Slider — the size of the area where particles are generated. Increase to spread snowflakes across a wider area, decrease to concentrate them around the model
Particle size
Slider — the size of individual snowflake particles. Smaller values create fine, delicate snow; larger values produce bigger, more visible flakes
Particle speed
Slider — how fast the particles fall. Lower values create a gentle, slow drift; higher values make the snow fall more rapidly
Bottom clamp
Slider — the lowest point where particles disappear. Adjust this so snowflakes vanish near the ground level rather than falling through it
Paused
Checkbox — pauses the animation. The snowflakes freeze in place, which can be useful for taking still screenshots with snow visible
Extras tab, in the **Wave Ground** section.
---
## Settings
enabled
Checkbox — activates the wave animation on the ground plane
Noise scale
Slider — controls the scale of the wave pattern. Lower values create large, broad waves; higher values produce smaller, more detailed ripples
Amplitude
Slider — the height of the waves. Higher values create more pronounced, dramatic waves; lower values produce a subtle, gentle surface motion
Paused
Checkbox — pauses the wave animation. The ground freezes in its current shape, useful for still renders with a wavy surface
Plugins tab, in the **Rhino 3dm Loader** section. This section is always visible, but its settings are used when working with `.3dm` files imported from Rhino.
---
## Settings
importMaterials
Checkbox — imports materials defined in the Rhino file. Enabled by default
forceLayerMaterials
Checkbox — forces materials to follow Rhino layer assignments instead of per-object materials. Enabled by default
replaceWithInstancedMesh
Checkbox — replaces duplicate geometry with instanced meshes for better performance. Disabled by default
hideLineMesh
Checkbox — hides line meshes (curves, edges, wireframes) that may be exported from Rhino. Enable this to remove unwanted lines from the viewport. Enabled by default
hidePointMesh
Checkbox — hides point meshes (control points, construction dots) that may be present in the Rhino file. Enable this to keep the viewport clean. Enabled by default
loadUserDataStrings
Checkbox — loads custom user data strings attached to objects in the Rhino file. Enabled by default
Importing Models
File formats, cameras from Blender, scaling, multi-model scenes
Materials & Diamonds
Textures, engravings, diamond sparkle, material variations
Exporting Images & Videos
Transparent backgrounds, resolution, export speed, formats
Cameras & Animation
Camera paths, Blender import, turntable, animation playback
Scene, Lighting & Environment
HDRI setup, shadows, backgrounds, gradients, ground plane
Rendering & Performance
Blur during interaction, quality settings, mobile issues
Playground & the iJewel Platform
Projects, settings transfer, VJSON, pricing, platform integration
What file formats does iJewel Playground support?
iJewel Playground supports **GLB**, **GLTF**, **3DM** (Rhino), **FBX**, and **OBJ** formats. For the best results — including full PBR materials, textures, and animations — use **GLB/GLTF**. This is the recommended format for all major 3D software (Blender, 3ds Max, Maya, Cinema 4D, Rhino).Can I use texture maps or vertex colors from other software?
Yes. All major 3D programs (Maya, 3ds Max, Blender, Rhino) export GLTF/GLB with PBR material and texture support. iJewel Playground will read the PBR material information and apply it correctly. For the best texture/animation fidelity, always export as GLB or GLTF rather than OBJ or FBX.My model appears black or dark after loading. What's wrong?
This usually means the model is missing an environment map. By default, Playground applies a lighting environment, but if your model was exported without materials or with incorrect settings, it may appear dark. Try the following: 1. Go to **Scene → Background / Environment** and make sure an HDRI environment map is loaded 2. Check that your model's materials exported correctly from your 3D software 3. If you're loading a jewelry model with diamonds, make sure diamond layers have unique names — Playground uses layer/material names to assign diamond materialsHow do I import a camera from Blender?
Export your Blender scene as a **GLB file with cameras included** (check the camera export option in Blender's GLTF export settings). When you load this GLB into Playground, the camera will appear in **Scene → [Cameras (Loaded)](./cameras-loaded)**. From there, select the camera and click **Activate Main** to switch to it. Make sure to **bake the animation as keyframes** before exporting.My camera animation from Blender doesn't play in Playground. What am I doing wrong?
When creating camera animations in Blender, make sure to: 1. **Bake the animation as keyframes** — constraints and drivers don't export to GLTF 2. **Export as GLB with cameras enabled** in the export settings 3. In Playground, go to **Scene → Cameras (Loaded)**, select the camera, and click **Activate Main** 4. Play the animation using the **GLTF Animation** controlsHow do I align an imported model from Rhino/Matrix with a Blender camera animation?
You have two options: 1. Export the 3DM from Rhino/Matrix and convert it to GLB in Playground. Then edit this GLB in Blender to add the camera animation, and export as GLB with animations 2. Export only the camera as a separate GLB from Blender, then drag and drop both files (the 3DM model and the camera GLB) into Playground one by oneHow can I scale or reposition my imported model?
1. Select your model — click on it in the viewport or find it in the [Hierarchy](./hierarchy) 2. Go to [Transform Controls](./transform-controls) and enable the gizmo 3. Switch the **Mode** to Scale (or Translate/Rotate) and use the gizmo handles to adjust You can also type exact values in the **Position**, **Rotation**, and **Scale** fields in the [Picking](./picking) panel.Can I import multiple models into the same scene?
Yes. Simply drag and drop additional files into Playground or use the import button. Each new model is added to the existing scene. You can then reposition them using [Transform Controls](./transform-controls).How should I name layers in Blender/Rhino for automatic material assignment?
iJewel uses layer/material names to automatically assign materials. The recommended naming convention is: layers named **Metal** (or Metal Yellow Gold, Metal Rose Gold, etc.) for metal parts, and **Diamond** (or Diamond Round, Diamond Princess, etc.) for diamond/gem parts — each unique diamond cut should have a unique layer name. ::: tip Video Tutorial Watch the [Layer Naming in Blender](https://www.youtube.com/watch?v=8sfDdlF4F9I) tutorial. For Rhino, see the [Preparing 3D Models](https://docs.ijewel3d.com/batchx/prepare-3dmodels.html#assigning-layers-to-objects-in-rhino) guide. :::My model file is too large. How can I reduce it?
Drop your model into Playground, then export it as GLB from the **Export** tab with **compression enabled**. This will apply Draco compression and can significantly reduce file size. You can also check individual texture sizes in **Picking → Physical Material** — large texture maps are often the main contributor to file size.How do I change the rotation of a brushed metal texture?
Go to **Picking → Physical Material → Map Sampler** and adjust the **Rotation** property. The Map Sampler settings are available for any texture map (albedo, roughness, metalness, normal, etc.). Note that your model needs proper UV coordinates for this to work — make sure the Triplanar extension is disabled. ::: tip Video Tutorial Watch [Fix Brushed Textures | UV Unwrap Solution](https://www.youtube.com/watch?v=4zqofmJTq64) if your brushed textures look incorrect — this covers UV unwrapping and disabling Triplanar. :::How do I get a deeper/clearer engraving?
Use the **Simple Text** modifier along with **Parallax Mapping**: 1. Go to **Modifiers → Simple Text → Add Text** and type your engraving. Make sure to click **Apply** 2. Enable **Modifiers → Parallax Mapping** 3. To control the depth, adjust **bumpScale** in **Picking → Physical Material → Bump/Normal**My diamond looks white/plain instead of sparkly. What's wrong?
This is typically caused by a missing or inappropriate environment map for the diamond material. Try: 1. Make sure an HDRI environment map is loaded in **Scene → Background / Environment** 2. Check the **Gem Env** setting — if it's set to None, the diamond won't reflect anything. Select an appropriate diamond environment map 3. Adjust the **Bloom** parameters in **Post Processing** — this adds the sparkle/glow effect 4. Try adjusting **envRotation** values in the diamond material settingsCan I apply a different HDRI specifically for diamonds?
Yes. You can set separate environment map slots for Gem/Diamond materials. Additionally, you can create a custom HDR map specifically optimized for diamond sparkle. ::: tip Video Tutorial Watch [Creating Custom HDR for Diamonds](https://www.youtube.com/watch?v=D5BV9S5izG0) for a detailed walkthrough. :::Why do my diamonds have pixelated seams?
Pixelated seams on diamonds are usually related to **normal map resolution**. The diamond mesh may have low-resolution normals or overlapping/broken geometry. Check the following: 1. Make sure your diamond mesh has clean, non-overlapping geometry 2. Check that normals are correct — avoid modifiers like mirroring that can create overlapping meshes 3. Use the diamond models provided by iJewel, which are optimized for the rendererUnnatural black shadows appear inside my marquise-cut diamond. How do I fix this?
This is often caused by **incorrect normals** or **broken/overlapping meshes** in the diamond geometry. This can happen when you use modifiers like mirroring in 3D software. Try: 1. Recalculate normals in your 3D software before exporting — see the [Fix Wrong Normals](https://www.youtube.com/watch?v=iivi9HyJpWU) tutorial 2. Check for overlapping or intersecting geometry 3. Try different HDRI environments — some environment maps produce better results with certain cuts 4. Use the diamond models provided by iJewel, which are verified to work correctlyHow can I reduce diamond sparkle frequency in videos?
Diamond sparkle is mainly controlled by the **Gem HDR environment maps**. To reduce sparkle frequency: 1. Try using different HDRI maps in the Gem Env setting 2. Adjust the **Bloom** parameters in Post Processing 3. Modify the **envRotation** values in the diamond materialCan I apply a different HDRI to diamonds and metal separately?
Yes. In Playground, you can set separate environment map slots for **Metal** and **Gem/Diamond** materials. Go to **Scene → Background / Environment** and look for the Metal Env and Gem Env options. This lets you use a studio HDRI for metal reflections and a different, more sparkly HDRI for diamond refraction.How do I create material variations and save them?
1. Click on an object in the viewport to select it 2. In the **Configurator** tab, click **Add Variation** — this adds a material variation icon 3. Modify the material properties (color, roughness, metalness, etc.) for each variation 4. Repeat for multiple objects and variations 5. To save all variations, click the three dots (⋯) above the Material Configurator UI and click **Download Preset** — this saves to a JSON file that can be reused across models with matching object/material names ::: tip Video Tutorials - Watch [Transfer Configurator Between Projects](https://www.youtube.com/watch?v=c_cph8q_vA8) for reusing material configurations - Watch [Quick Material Export & Import Tutorial](https://www.youtube.com/watch?v=59dNYczASqU) for downloading, exporting, and applying materials to ring components and gemstones :::My model's file size is too large because of textures. How do I check which textures are heavy?
Go to **Picking → Physical Material** and check the different texture maps (Albedo, Roughness, Metalness, Normal, etc.). You can download individual texture images to check their sizes. Large texture maps are usually the main contributor to file size — consider reducing their resolution before re-importing.The model looks fine in Playground but terrible in Shopify. Why?
Shopify's default 3D viewer does not support iJewel's advanced lighting, diamond rendering, or post-processing effects. To get the same quality on your website, embed your model using the [iJewel Viewer SDK](../viewer/introduction) or use [iframe embedding](../integrations/shopify-embedding).How do I export an image with a transparent background?
Follow these steps: 1. Go to **Post Processing → Tonemapping** and set **Clip Background** to true (or set **Background Alpha** to 0) 2. Go to **Scene → Ground** and uncheck **Visible** (or set **Render to Depth** to false) 3. Go to **Scene → Progressive Shadow** and disable it 4. Choose **PNG** as the export format (JPG does not support transparency) 5. Export the image from the **Export** tab See the full guide in [Export Images — Transparent Background](./export-images#transparent-background). ::: tip Video Tutorial Watch [How to Make Pure White and Transparent Background](https://www.youtube.com/watch?v=GCJIOmcEaPo) for a step-by-step visual guide. :::My exported image is blurry despite using high settings. What's wrong?
::: tip Video Tutorial Watch the [Common Export Issues](https://www.youtube.com/watch?v=UT4p-IFrbjI) tutorial for solutions to frequent export problems. Also see [Resolution & Export from Playground](https://www.youtube.com/watch?v=FAqfTMBAaBA) for a complete guide on resolution and export settings. ::: Try these steps: 1. Instead of using Scale, set a **custom resolution** in **Viewer → Renderer** — type the exact pixel dimensions you need 2. Try the **Tiled Export** option in **Export → Image Export** which can produce higher-quality results at large resolutions 3. Check that **Depth of Field** is disabled in Post Processing — this effect intentionally blurs parts of the image 4. Make sure **Anti-Aliasing** (TAA/Progressive) is set to a sufficient number of framesWhat is the maximum export resolution?
The maximum resolution depends on your device's GPU capabilities. Most devices support up to **2160px** in the standard export mode. For higher resolutions (3000×3000px and above), use the **Tiled Export** feature in **Export → Image Export**, which renders the image in tiles and stitches them together.Video export takes 10+ minutes. How can I speed it up?
Long export times are usually caused by high anti-aliasing settings with custom backgrounds. To speed things up: 1. Reduce the **Progressive** frame count in **Anti-Aliasing** settings to something like 4 or 8 (instead of 16 or 32) 2. Lower the export resolution 3. Reduce the **FPS** — 24 fps is often sufficient for smooth turntable animations 4. Don't close the browser tab during export — wait until iJewel finishes converting frames to video. You can monitor the progress in the browser consoleWhat are the best settings for video export?
There's no single "best" setting — it depends on your use case: - **Turntable product shots**: 24–30 FPS, 4–8 AA Progressive frames, 1080p or 1440p resolution - **Camera path animations**: match the FPS to your original animation (usually 24 or 30), higher AA for final renders - **Quick previews**: 24 FPS, low AA, 720p You can find all these options in **Export → Video Export**. ::: tip Video Tutorial Watch [Resolution & Export from Playground](https://www.youtube.com/watch?v=FAqfTMBAaBA) for a walkthrough of resolution and export settings. :::How do I set the speed and direction of a turntable video?
Go to **Export → Video Export** where you'll find controls for turntable rotation speed, direction (clockwise or anticlockwise), and total rotation angle. ::: tip Video Tutorial Watch [Perfect 360° Turntable In 2 Minutes](https://www.youtube.com/watch?v=304Hzog-7bg) for a quick guide on setting up turntable animations. :::Can I export 360 still frames instead of an MP4 video?
Currently, only MP4 video export is available. PNG sequence export is planned for a future release.Can I change the export format from PNG to JPEG for quick snapshots?
Yes. In the export options, you can choose between PNG and JPEG formats. PNG is the default because it supports transparency, but JPEG produces smaller files and is faster for quick captures.How do I render a ring on a hand model?
You can import a hand 3D model alongside your ring and position them together in Playground. A free downloadable hand model (Blender file) is available in the description of this tutorial: ::: tip Video Tutorial Watch the [Ring on Hand Model](https://www.youtube.com/watch?v=TJNWi6AgZk0) tutorial — includes a free hand model download link in the video description. :::Can I add my company logo to exported videos?
This feature is not available in Playground at the moment. You would need to add your logo in a video editing tool after exporting. This feature is planned for a future update.Can I remove the encryption from an exported file?
Yes. Open the encrypted file in Playground (you'll need the password), then re-export it from the **Export** tab with the encryption checkbox unchecked.How do I import a camera path from Blender?
1. Create your camera animation in Blender with keyframes 2. **Bake the animation** — constraints and drivers don't export to GLTF format 3. Export as **GLB with cameras enabled** (check the camera option in Blender's GLTF export dialog) 4. Drop the GLB file into Playground 5. Go to **Scene → [Cameras (Loaded)](./cameras-loaded)**, select your camera, and click **Activate Main** 6. Play the animation with the **GLTF Animation** controls See the full tutorial on the [Cameras (Loaded)](./cameras-loaded#tutorial-creating-a-camera-path-and-rendering-it-in-playground) page.My camera animation from Blender doesn't play. What's wrong?
The most common causes: 1. The animation wasn't **baked as keyframes** — Blender constraints (Track To, Follow Path) don't export to GLTF 2. The camera wasn't included in the GLTF export settings 3. You haven't activated the camera — go to **Scene → Cameras (Loaded)**, select it, and click **Activate Main** 4. The animation player is paused — check the GLTF Animation controlsHow do I align a Rhino/Matrix model with a Blender camera path?
Two approaches: 1. **Convert first**: Export 3DM from Rhino → convert to GLB in Playground → edit in Blender (add camera animation) → export as GLB with animations → load into Playground 2. **Load separately**: Export camera-only GLB from Blender, then drag both the 3DM model file and the camera GLB into Playground one by oneHow do I create a turntable animation?
For a simple turntable, use the built-in turntable recording feature in **Export → Video Export**. You can set rotation speed, direction, and angle there. For more complex turntable animations with custom speeds or easing, create the camera path in Blender and import it as described above. ::: tip Video Tutorial Watch [Perfect 360° Turntable In 2 Minutes](https://www.youtube.com/watch?v=304Hzog-7bg) for a quick guide on creating turntable animations. :::How do I create a pendant animation?
Create the pendant swing/movement animation in Blender, export as GLB with animations, and load into Playground. You can then play the animation back and record it. ::: tip Video Tutorial Watch the [Pendant Animation](https://www.youtube.com/watch?v=VQa6D33y8IA) tutorial for a complete walkthrough. :::Can I create a shadow rotation animation (shadows moving around the model)?
Yes. The best approach is to create **directional lights in Blender**, animate them to rotate around the model while keeping the target on the jewelry, and export as GLB with animations. In Playground, this will appear as GLTF Animations that you can play back.How do I save and reuse a camera position?
You can use **[Camera Views](./camera-views)** to save and switch between fixed camera angles. This is also useful for taking snapshots from specific positions. See the full [Camera Views documentation](./camera-views) for a step-by-step guide. ::: tip Video Tutorial Watch the [Camera Views](https://www.youtube.com/watch?v=jdePxecZRkQ) tutorial for setting up and using saved camera positions. ::: You can also export camera settings as part of a **scene preset**. Go to the scene settings and use the **Download Preset** option from the three dots menu (⋯). This saves a JSON/VJSON file that includes camera position, rotation, and other settings. Drop this file back into Playground to restore the same camera angle.How can I create an environment map rotation animation?
Playground supports environment map rotation animations. You can create them in the **Animation** tab using the environment rotation animation feature. ::: tip Video Tutorial Watch the [Environment Map Rotation Animation](https://drive.google.com/file/d/17VxPoCluLMtVONHQqjuMCrXoiFRMOStO/view?usp=sharing) guide for a step-by-step walkthrough. :::Can I use poses to set consistent angles across different models?
Poses are currently not saved between sessions. Each model has different proportions, so the same transform values (rotation/position) produce different results on different models. For consistent angles, use the **camera position** values instead — these are independent of the model and can be saved as presets.How do I set up an HDRI environment?
Go to **Scene → [Background / Environment](./background-environment)** and load an HDRI map. You can use the built-in presets or upload your own `.hdr` or `.exr` file. The environment map controls both the background appearance and the lighting/reflections on your model. Adjust **Intensity** and **Rotation** to fine-tune the look. You can also create your own custom HDRI maps using the [HDRI Editor](https://editor.hdrmap.com/#).How do I make the background transparent?
1. Go to **Post Processing → Tonemapping** and set **Clip Background** to true (or set Background Alpha to 0) 2. Disable **Scene → Ground → Visible** 3. Disable **Scene → Progressive Shadow** 4. Export as **PNG** (not JPG — JPG doesn't support transparency) See the full guide in [Export Images — Transparent Background](./export-images#transparent-background). ::: tip Video Tutorial Watch [How to Make Pure White and Transparent Background](https://www.youtube.com/watch?v=GCJIOmcEaPo) for a step-by-step walkthrough. :::I get a message "Background must be same as environment." What does this mean?
This message comes from the **HDRi Ground** plugin. It appears when the background texture is not the same as the environment texture. To fix it, make sure both are set to the same HDRI map, or simply confirm the dialog to sync them. If you see this message even when they seem equal, try updating to the latest Playground version.How do I remove the ground plane?
Go to **Scene → [Ground](./ground)** and uncheck the **Visible** checkbox. This removes the ground so your model appears to float — useful for pendants, earrings, or any suspended jewelry.How do I fix the ground position? It moves when I import new models.
The ground adjusts automatically to match the model's position. To lock it at a specific height, go to **Scene → [Ground](./ground) → Height** and set the value manually. This keeps the ground at a fixed level regardless of what you import.Why do shadows rotate with my model during turntable recording?
By default, progressive shadows are baked and move with the scene. To get shadows that stay fixed while the model rotates: 1. Create **directional lights in Blender** with animated rotation (keeping the target on the jewelry) 2. Export as GLB with animations 3. In Playground, these will appear as GLTF Animations — play them during recording Alternatively, you can disable baked shadows on the ground and use real-time shadows from scene lights, though this requires more setup. ::: tip Video Tutorial Watch [How to Create Custom Shadows](https://www.youtube.com/watch?v=269LnNYZDh0) for a complete guide on shadow customization. :::Can I disable baked shadows and use real-time shadows instead?
Yes. Disable baked shadows on the ground from **Scene → Ground** settings (uncheck shadow-related options). Then add lights in **Scene → [Lights](./lights)** with shadow casting enabled. When moving a light, the scene will re-render automatically with updated shadows.How do I use a custom background image?
Go to **Scene → [Background / Environment](./background-environment)** and upload an image file. Note that background images may scale differently on different screen sizes. For consistent results across devices, use a square or wide-aspect image and test at your target resolution.My custom background image turns grayscale or black after saving. Why?
This is a known issue in some versions. Try: 1. Re-uploading the background image after loading your model 2. Making sure **Tonemapping** settings aren't affecting the background color 3. Updating to the latest Playground versionWhat's the difference between Tonemapping and Clip Background?
**Tonemapping** adjusts the color grading and exposure of the entire render (similar to a photo filter). **Clip Background** is a boolean setting within Tonemapping that controls whether the background is rendered or made transparent. When Clip Background is enabled, the background becomes transparent for export — the model itself is still tonemapped normally.How do I create a custom gradient background?
Use the **[Gradient SVG](./gradient-svg)** section in the Scene tab. Enable it, choose between Linear or Radial gradient type, pick two colors, and adjust the angle and positions. You can also apply the gradient to the scene background with the **Apply to Background** checkbox. ::: tip Video Tutorial Watch [How to Change Background & Ground Color](https://www.youtube.com/watch?v=q989o_dq7yo) for a visual guide on changing background and ground colors. :::Why is my model blurry while rotating or zooming?
During interaction (orbiting, zooming, panning), Playground renders at a lower quality for responsiveness and then refines the image once you stop. This is normal behavior — the final high-quality render appears after you release the mouse. If the blur persists after interaction stops, check: 1. **Renderer → Scale** — make sure it's set to 1 or higher (lower values reduce resolution for performance) 2. **Anti-Aliasing** settings — increase TAA/Progressive frame count for sharper results 3. **Depth of Field** in Post Processing — disable it if you don't need selective focusHow do I improve overall render quality?
Several settings affect render quality: 1. **Renderer → Scale** — set to 1 for native resolution, or higher for supersampling 2. **Renderer → Mode** — use the highest quality mode available 3. **Anti-Aliasing (TAA)** — increase Progressive frame count (8–16 gives good results) 4. **SSAO** (Screen Space Ambient Occlusion) — adds subtle shadows in crevices 5. **SSR** (Screen Space Reflections) — improves reflection accuracy 6. **Bloom** — adds glow to bright areas (especially useful for diamonds) See [Renderer Settings](./renderer-settings) for a full explanation of quality modes. ::: tip Video Tutorial Watch [Resolution & Export from Playground](https://www.youtube.com/watch?v=FAqfTMBAaBA) for a visual walkthrough of resolution and quality settings. :::The render looks different on mobile vs desktop. Why?
Mobile devices have lower GPU power and memory, so Playground may automatically reduce quality settings. Additionally: 1. Screen size and pixel density differ — the same resolution looks different on a phone vs a monitor 2. iOS has a ~350–400 MB memory limit for WebGL — exceeding it causes the page to refresh 3. Touch interactions (drag vs scroll) may behave differently than mouse controls 4. Some post-processing effects may be disabled automatically on lower-end devicesMy page refreshes/crashes on iOS when loading complex models. What's happening?
iOS Safari has a strict memory limit for WebGL content (approximately 350–400 MB, depending on the iPhone model). When your scene exceeds this, iOS force-refreshes the page. To stay within limits: 1. Use smaller texture maps — resize textures to 1024×1024 or lower for mobile 2. Reduce the number of diamonds — configure **cache keys** to reuse diamond rendering resources 3. Lower the Renderer Scale on mobile 4. Use compressed GLB files (with Draco compression)What does the Renderer Scale setting do?
**Scale** controls the internal rendering resolution relative to the canvas size. A scale of 1 means native resolution. Scale 0.5 renders at half resolution (faster but blurrier). Scale 2 renders at double resolution (sharper but slower). For final exports, use Scale 1 or higher. For real-time preview, Scale 0.5–1 is usually sufficient. See [Renderer Settings](./renderer-settings) for more details.Anti-aliasing breaks when playing model animation. Is this a known issue?
Yes, this can happen because TAA (Temporal Anti-Aliasing) relies on accumulating multiple frames. During animation playback, the scene changes every frame, which prevents proper accumulation. Try: 1. Increasing the **Progressive** frame count in Anti-Aliasing settings 2. For final video exports, Playground renders each frame with full AA — so the exported video will look better than the real-time previewHow do I record high-quality videos without quality depending on my device?
Use Playground's built-in video export (**Export → Video Export**) rather than screen recording. The built-in exporter renders each frame at full quality regardless of your device's real-time performance — it captures frames one by one, so even a slower device produces the same quality output (it just takes longer).Is iJewel Playground a CAD program?
No. Playground is a real-time **3D rendering and visualization editor** — not a modeling tool. For a full overview of all iJewel products, watch the [iJewel Products Overview](https://www.youtube.com/watch?v=PLP0K2F1hQI) video. It's designed for creating/editing materials, optimizing models, setting up lighting and camera angles, and exporting images, videos, or viewer-ready files. You can move and transform objects, and generate simple primitives (sphere, box, torus, etc.), but it's not a replacement for 3D modeling software like Blender, Rhino, or 3ds Max.Is Playground free to use?
Playground has a **Free** tier with basic features. **Premium** (5 library slots) and **Advance** (100 library slots) tiers unlock additional features like higher export resolutions, more material presets, and advanced post-processing. For commercial use, a subscription-based license is required. See [License and Pricing](../introduction/license) for details.How do I reopen a project I previously saved on the iJewel platform?
Open Playground from the iJewel platform and load the saved project — it reopens with your model and settings. If your version doesn't list the project directly, download its GLB file and drag it into Playground.My Playground settings don't transfer when I save a model to the iJewel platform. Why?
When you export a GLB from Playground, some advanced settings (post-processing, certain plugin configurations) may not be preserved in the GLB format. For full settings transfer: 1. Export the **scene settings as VJSON** from the Export tab — this captures all environment, lighting, and plugin settings 2. Keep both the GLB model and the VJSON together when saving to the platform 3. Alternatively, save directly from Playground if that option is available in your versionHow do I save and reuse scene settings across different models?
1. Set up your scene the way you want (lighting, environment, shadows, post-processing) 2. Go to the **Export** tab and download the scene preset as a **VJSON** file 3. For a new model, drop the model into Playground first, then drag and drop the VJSON file — it will apply all saved settings You can also download individual presets (materials only, animations only) using the three dots menu (⋯) above specific UI sections.My zoom limits reset after saving. How do I fix this?
Zoom limits and camera constraints are stored as part of the camera/viewer settings. When exporting, make sure to include camera settings in your VJSON export. If the issue persists, set the zoom limits again in Playground and save.Can I save files larger than 50 MB in Playground?
There is a file size limit for saving directly from Playground to the iJewel platform. For larger files: 1. Export the GLB to your local computer first (no size limit for local download) 2. Compress the file by enabling **Draco compression** in the export options 3. Check texture sizes — large textures are usually the main contributor. Reduce texture resolution in **Picking → Physical Material**How does Playground fit into the iJewel platform?
**Playground** is the 3D editor inside the **iJewel platform** — it's where you open 3D files and configure materials, lighting, cameras, and export images/videos. The wider platform is where those configured models are managed, hosted, embedded on websites, shared via links, or served through the viewer SDK.How do I match a camera position from my 3D software to Playground?
Go to the camera settings in Playground (available in the viewer/camera controls) and manually set the **Position** and **Rotation** values to match your 3D software. You can also export the camera from your 3D software as part of a GLB file, and it will appear in **Scene → [Cameras (Loaded)](./cameras-loaded)**.Can I use Playground with multiple objects and create a configurator?
Yes. Load multiple objects into the scene, then use the **Configurator** tab to set up material variations for each object. Click on an object, add variations with **Add Variation**, and configure each one. When exported, the configurator data can be used with the iJewel Viewer SDK to build interactive product configurators on your website.
#### `enterSetupMode(options?): boolean`
Suspends try-on and shows the reference finger cylinder, the center-line plane and a transform gizmo. Returns `false` if the plugin is currently running or starting.
| Option | Type | Default | Description |
|---|---|---|---|
| `showGizmos` | `boolean` | `true` | Show and enable the transform gizmo. Set it to `false` to create the gizmo hidden and disabled; it reappears on the next transform-mode change. |
#### `exitSetupMode(): boolean`
Leaves setup mode and restores the camera position saved on entry.
#### `inSetupMode: boolean`
Whether setup mode is currently active.
See [Prepare a Try-On Project](./prepare-model.md) for the full authoring workflow, including exporting the resulting JSON.
### Prepare a configurator ring
A Ring Configurator or Wedding Band Builder builds its ring at runtime, so hand
the assembled ring to the plugin before setup mode or `start()`:
```javascript
const session = ijewelViewer.prepareConfiguratorTryon(
viewerApp,
tryon
);
if (!tryon.enterSetupMode()) {
session.restore();
throw new Error("Try-On setup mode could not be opened.");
}
tryon.setup.autoFit();
```
Calling `tryon.exitSetupMode()` restores the complete configurator. Pass a
`ringId` when a Wedding Band Builder has several rings. See
[Configurator Try-On Helpers](../viewer/viewer-class.md#configurator-try-on-helpers)
for ring choices and the custom runtime flow.
## Configuration
Placement and visual settings live on grouped config objects. Every field is serialized, so `toJSON()` / `fromJSON()` round-trip them - this is exactly how the settings authored in the editor reach the plugin at runtime.
```javascript
// Apply settings authored in the editor.
tryon.fromJSON({ ...tryonConfig, type: ij_vto.RingTryonPlugin.PluginType });
// Or set individual values.
tryon.setup.modelScaleFactor = 1.1;
tryon.contactShadow.intensity = 0.45;
```
For a configurator, call
[`prepareConfiguratorTryon()`](../viewer/viewer-class#configurator-try-on-helpers)
after `fromJSON()` and before `start()`.
### `setup` - model placement
| Property | Type | Default | Description |
|---|---|---|---|
| `modelScaleFactor` | `number` | `1` | Uniform scale applied to the model. |
| `modelPosition` | `Vector3` | `(0,0,0)` | Position offset. |
| `modelRotation` | `Vector3` | `(0,0,0)` | Rotation offset in **radians**. |
These three are also mirrored directly on the plugin as `modelScaleFactor`, `modelPosition` and `modelRotation`.
::: warning Radians here, degrees in `tracking`
`setup.modelRotation` is applied straight to the model's Euler rotation, so it is in radians - the editor converts for display. The separate [`tracking.offsetRotation`](#tracking-advanced-tuning) *is* in degrees. Use `MathUtils.degToRad()` when you have a degree value for `modelRotation`.
:::
### `contactShadow` - shadow where the ring meets the finger
| Property | Type | Default | Description |
|---|---|---|---|
| `enabled` | `boolean` | `true` | Draw the contact shadow. |
| `intensity` | `number` | `0.6` | Shadow strength. |
| `distance` | `number` | `0.15` | How far the shadow reaches from the ring. |
| `smoothness` | `number` | `0.55` | Softness of the shadow edge. |
| `angle` | `number` | `0` | Light direction in screen space, in degrees. `0` puts the light above. |
| `elevation` | `number` | `70` | Light elevation toward the camera, in degrees. `90` is head-on, casting no visible shadow. |
| `skinWarmth` | `number` | `0.1` | Warm halo bleeding into the shadow, approximating light scattering in skin. |
| `color` | `Color \| string` | black | Tint added inside the shadow. |
### `ssao` - ambient occlusion and skin shading
| Property | Type | Default | Description |
|---|---|---|---|
| `enabled` | `boolean` | `false` | Enable ambient occlusion. |
| `intensity` | `number` | `0.2` | Occlusion strength. |
| `radius` | `number` | `1.07` | Sampling radius. |
| `falloff` | `number` | `0.33` | How quickly occlusion fades with distance. |
| `smoothEnabled` | `boolean` | `true` | Blur the occlusion result. |
### `ssr` - screen-space reflections
| Property | Type | Default | Description |
|---|---|---|---|
| `enabled` | `boolean` | `true` | Reflect the hand and surroundings in the metal. |
| `intensity` | `number` | `1.5` | Reflection strength. |
| `radius` | `number` | `2` | Ray-march radius. |
| `tolerance` | `number` | `5` | Depth tolerance when matching a reflection hit. |
### `environmentReflection`
| Property | Type | Default | Description |
|---|---|---|---|
| `enabled` | `boolean` | `true` | Apply the scene environment map to the ring while in try-on. |
| `scale` | `number` | `1.67` | Environment scale. |
| `stretch` | `number` | `2.675` | Environment stretch. |
### `motionBlur`
| Property | Type | Default | Description |
|---|---|---|---|
| `enabled` | `boolean` | `false` | Blur the ring along its motion as the hand moves. |
| `intensity` | `number` | `1.5` | Blur strength. |
| `edgeSmear` | `number` | `0.2` | How far the blur smears past the ring's edges. |
### `interactionZoom`
After the hand has been tracked steadily for a moment, the view zooms in on the ring automatically.
| Property | Type | Default | Description |
|---|---|---|---|
| `enabled` | `boolean` | `true` | Enable the automatic zoom. |
| `targetScale` | `number` | `1.5` | Zoom level to settle at. |
| `delayMs` | `number` | `1000` | Delay before the zoom starts. |
| `durationMs` | `number` | `1250` | Length of the zoom animation. |
### `tracking` - advanced tuning
Defaults suit most catalogues; change these only when a model consistently sits wrong.
| Property | Type | Default | Description |
|---|---|---|---|
| `minHandDistance` | `number` | `10` | Hide the ring when the hand is farther than this. |
| `snappiness` | `number` | `0.9` | Tracking responsiveness. `0` is heavily smoothed, `1` is instant and jittery. |
| `locationOffset` | `number` | `0.65` | Where along the finger segment the ring sits. |
| `offsetScale` | `number` | `1` | Multiplier on the detected finger width - effectively ring size. |
| `offsetPosition` | `Vector3` | `(0,0,0)` | Extra position offset applied every frame. |
| `offsetRotation` | `Vector3` | `(0,0,0)` | Extra rotation offset in degrees, mirrored for the left hand. |
| `zOffset` | `number` | `-3.25` | Depth offset from the finger surface. |
| `worldZFactor` | `number` | `1` | Scaling applied along the depth axis. |
## Events
Standard WebGi events - subscribe with `addEventListener(type, handler)`.
| Event | Detail | Fired when |
|---|---|---|
| `start` | `{}` | `start()` was called and initialisation has begun. |
| `initializationProgress` | `{ progress }` | Loading progress, `0`–`1`. Drive your own progress bar with this. |
| `initialized` | `{}` | Tracking is live and the ring is ready to appear. |
| `interaction` | `{}` | The hand has been tracked steadily - this is what triggers the automatic zoom. |
| `stop` | `{}` | Try-on has stopped and the camera is released. |
| `error` | `{ reason, error, isCameraError? }` | Something failed. See below. |
### Handling errors
```javascript
tryon.addEventListener("error", ({ detail }) => {
if (detail.isCameraError) {
showMessage("We couldn't access your camera.");
} else {
showMessage("Try-on couldn't start. Please try again.");
}
console.error(detail.reason, detail.error);
});
```
`detail.reason` is one of:
| Reason | Meaning |
|---|---|
| `startupFailed` | Initialisation threw - not camera-related. |
| `noSupport` | The browser has no webcam API. |
| `permissionDenied` | The user declined camera access. |
| `notFoundError` | No camera matches the requested constraints. |
| `notReadableError` | The camera is in use by another application. |
| `overconstrainedError` | The camera can't satisfy the requested settings. |
| `abortError` | Camera access was aborted. |
| `invalidStateError` | The page was inactive when access was requested. |
| `securityError` | Camera access is blocked by browser or page security settings. |
| `typeError` | The camera request was rejected as invalid. |
| `mediaDevicesError` | Any other failure starting the camera. |
Camera reasons arrive with `isCameraError: true`. [`TryonUIPlugin`](./tryon-ui-plugin.md) already renders a message for each of these - add your own handler only if you want different behaviour.
## `canRunVTO()`
A standalone pre-flight check, exported alongside the plugin. Call it before showing a try-on button so users on unsupported hardware never hit a dead end. It creates and discards a throwaway WebGL context, so it's cheap enough to call on page load.
```javascript
const result = ij_vto.canRunVTO();
if (!result.ok) {
tryOnButton.remove();
console.warn("Try-on unavailable:", result.reason, result.details);
} else if (result.warning) {
console.warn(result.warning); // runs, but may be slow
}
```
### Result
| Field | Type | Description |
|---|---|---|
| `ok` | `boolean` | Whether try-on should be offered. |
| `reason` | `string?` | Present when `ok` is `false`. One of `no_webgl2`, `weak_or_software_renderer`, `insufficient_cores`, `insufficient_memory`. |
| `warning` | `string?` | Present when try-on will run but performance may suffer - for example an integrated GPU on Chrome for Windows. |
| `details` | `object` | What was measured: `webgl2`, `renderer`, `vendor`, `cores`, `memoryGB`. Worth logging for support. |
### Options
| Option | Type | Default | Description |
|---|---|---|---|
| `minCores` | `number` | `4` | Minimum CPU cores. A reported `0` (browser withheld it) never fails the check. |
| `minMemoryGB` | `number` | `4` | Minimum device memory in GB, treated the same way. |
| `weakRendererPatterns` | `RegExp[]` | built-in list | Renderer strings to reject - software rasterisers and known-weak GPUs. |
| `powerPreference` | `string` | `"high-performance"` | Power preference used for the probe context. |
```javascript
// Be stricter than the defaults.
const result = ij_vto.canRunVTO({ minCores: 6, minMemoryGB: 8 });
```
---
# TryonUIPlugin API Reference
`TryonUIPlugin` is the ready-made overlay for the try-on session. It listens to [`RingTryonPlugin`](./ring-tryon-plugin.md) and renders three things over the canvas:
- a **loading box** with a title, optional subheader, optional logo and a progress bar, shown while hand tracking initialises;
- a **hand prompt** - an outlined hand and a line of copy - once try-on is live but no hand has been detected yet;
- **error messages** for every camera and startup failure the plugin can report.
Using it is optional. Everything it does can be built from the plugin's [events](./ring-tryon-plugin.md#events), but it saves you writing loading and error states for a dozen camera failure modes.
```javascript
const tryon = await viewer.addPlugin(ij_vto.RingTryonPlugin);
await viewer.addPlugin(ij_vto.TryonUIPlugin);
```
::: warning Add it after the try-on plugin
`TryonUIPlugin` looks for a try-on plugin on the viewer when it is added, and throws if there isn't one. Always add `RingTryonPlugin` first.
:::
::: info Alias
The plugin is exported both as `ij_vto.TryonUIPlugin` and as `ij_vto.RingTryonUIPlugin`. They are the same class - the second name exists for older integrations.
:::
## Configuring
Pass a config to the constructor, or update it later with `configure()`. Both take a deep-partial object that is merged onto the defaults, so you only specify what you want to change.
```javascript
await viewer.addPlugin(new ij_vto.TryonUIPlugin({
loading: {
title: "Preparing your try-on",
subText: null, // hide the subheader
logo: "https://example.com/logo.svg",
align: "center",
background: "#111",
textColor: "#fff",
progressColor: "linear-gradient(90deg, #c9a227, #f0d878)",
},
handPrompt: {
text: "Show the back of your hand",
},
}));
```
#### `configure(partial)`
Merges a partial config onto the current one and re-applies it to the live DOM immediately - safe to call while try-on is running.
```javascript
const ui = viewer.getPlugin(ij_vto.TryonUIPlugin);
// Switch to a different message mid-session.
ui.configure({ handPrompt: { text: "Move your hand a little closer" } });
```
#### `config`
The full, resolved config object. Read it to inspect current values; mutate through `configure()` so changes reach the DOM.
#### `enabled: boolean`
Set to `false` to suppress the whole overlay without removing the plugin.
## `loading`
The box shown while hand tracking initialises.
| Property | Type | Default | Description |
|---|---|---|---|
| `enabled` | `boolean` | `true` | Render the loading box at all. Set to `false` if you show your own loading state. |
| `title` | `string` | `"Loading..."` | Main heading. |
| `subText` | `string \| null` | `"Loading models..."` | Subheader. `null` or `''` hides it. |
| `logo` | `string \| null` | `null` | Logo above the title. Either an image URL / data-URI, or a raw SVG or HTML string. |
| `size` | `'card' \| 'half' \| 'full'` | `'card'` | Preset box size - a centered card, roughly half the container, or a full-canvas overlay. |
| `width` | `string \| null` | `null` | Explicit CSS width, e.g. `'320px'` or `'60vw'`. Takes precedence over `size`. |
| `align` | `'start' \| 'center' \| 'end'` | `'start'` | Horizontal alignment of logo, title and subheader. |
| `background` | `string` | white, near-opaque | Any valid CSS `background` value. |
| `textColor` | `string` | `'#000000'` | Title colour. |
| `subTextColor` | `string` | `'#4a4a4a'` | Subheader colour. |
| `showProgressBar` | `boolean` | `true` | Show the progress bar. |
| `progressColor` | `string` | dark gradient | CSS colour or gradient for the progress fill. |
```javascript
// Full-bleed dark loading screen with a logo and no subheader.
ui.configure({
loading: {
size: "full",
align: "center",
background: "#0b0b0b",
textColor: "#ffffff",
subText: null,
logo: "https://example.com/logo-light.svg",
},
});
```
## `handPrompt`
The overlay shown once try-on is live but no hand has been detected yet.
| Property | Type | Default | Description |
|---|---|---|---|
| `enabled` | `boolean` | `true` | Show the prompt. |
| `text` | `string \| null` | `"Show your hand to start"` | Prompt copy. `null` or `''` leaves just the outline. |
| `showHandOutline` | `boolean` | `true` | Draw the outlined hand graphic. |
| `handSvg` | `string` | built-in outline | Replace the outline with your own SVG markup. |
| `color` | `string` | near-white | Colour of the prompt text. |
#### `showHandPrompt()` / `hideHandPrompt()`
Show or hide the prompt imperatively. `showHandPrompt()` respects `handPrompt.enabled` and does nothing when the prompt is disabled.
```javascript
// Text-only prompt, no outline.
ui.configure({
handPrompt: { showHandOutline: false, text: "Hold your hand up to the camera" },
});
```
## `messages`
Every user-facing string the plugin can display. Override any subset - for translation, or to match your store's tone.
| Property | Description |
|---|---|
| `initialization` | Loading title (mirrors `loading.title`). |
| `initializationSubText` | Loading subheader. |
| `error.noSupport` | The browser has no webcam API. |
| `error.permissionDenied` | The user declined camera access. |
| `error.startupFailed` | Initialisation failed for a non-camera reason. |
| `error.mediaDevicesError` | Generic camera start failure. |
| `error.runtimeError` | Try-on failed while already running. |
| `error.abortError` | Camera access was aborted. |
| `error.invalidStateError` | The page was inactive when access was requested. |
| `error.notFoundError` | No camera matched the requested constraints. |
| `error.notReadableError` | The camera is in use by another application. |
| `error.overconstrainedError` | The camera can't satisfy the requested settings. |
| `error.securityError` | Camera access is blocked by security settings. |
| `error.typeError` | The camera request was rejected as invalid. |
| `error.unknown` | Fallback for unrecognised failures. |
| `error.unknownCameraError` | Fallback for unrecognised camera failures. |
```javascript
// Localise the strings users are most likely to see.
ui.configure({
messages: {
initialization: "Chargement…",
initializationSubText: "Préparation de l'essayage virtuel.",
error: {
permissionDenied: "Vous avez refusé l'accès à la caméra. Autorisez-le puis réessayez.",
notReadableError: "Votre caméra est utilisée par une autre application.",
},
},
});
```
## Full example
```javascript
const tryon = await viewer.addPlugin(ij_vto.RingTryonPlugin);
const ui = await viewer.addPlugin(new ij_vto.TryonUIPlugin({
loading: {
title: "Preparing your try-on",
subText: "This takes a few seconds the first time.",
logo: "https://example.com/logo.svg",
size: "full",
align: "center",
background: "#0b0b0b",
textColor: "#ffffff",
subTextColor: "#a0a0a0",
progressColor: "linear-gradient(90deg, #c9a227, #f0d878)",
},
handPrompt: {
text: "Show the back of your hand",
color: "#ffffff",
},
}));
await tryon.start();
```
---
# Changelog for @ijewel3d/web-vto
## [0.3.3] - 2026-09-15
### Fixed
- Hand detection now works on phones with an Adreno 8xx GPU, such as the Galaxy S25 Ultra. MediaPipe's GPU delegate returns no hands on these GPUs, so hand detection uses the CPU delegate there. All other devices keep the GPU delegate (IJ-249).
## [0.3.2] - 2026-09-07
### Fixed
- AR Setup no longer darkens editor backgrounds. The AR color conversion now applies only while an AR background is active.
## [0.3.1] - 2026-09-01
### Fixed
- Camera stop now restores the canvas scale. The canvas stayed mirrored after the rear camera stopped.
## [0.3.0] - 2026-08-02
### Added
- On-device engine ported from Pyodide/Python to TypeScript: ~15 MB smaller download.
- Ribbon edge fit.
- Depth-normalization fallback when edges are missing, flagged as `depthNormFallback`.
- `pauseRendering` hook so inference no longer contends with the render loop.
## [0.2.9] - 2026-07-20
### Added
- Wristwear: Onbody front-end loading and support.
## [0.2.8] - 2026-07-13
### Added
- Onbody front-end loading and support.
### Changed
- Move onbody handling from back-end to on-device engine.
## [0.2.7] - 2026-06-18
### Added
- `TryonUIPlugin` (`RingTryonUIPlugin`) is now fully configurable via a `TryonUIConfig` object — pass it to the constructor (`new RingTryonUIPlugin({ ... })`) or update it at runtime with `uiPlugin.configure({ ... })`, which re-applies to the live DOM.
- Loading box: `enabled` (disable entirely), `title`, `subText` (`null`/`''` hides the subheader), `logo` (image URL/data-URI or raw SVG/HTML), `size` (`'card' | 'half' | 'full'`), `width` (custom CSS override), `align` (`'start' | 'center' | 'end'` for logo/title/subheader), `background`, `textColor`, `subTextColor`, `showProgressBar`, `progressColor`.
- Hand prompt: `enabled` (show/hide the "show your hand" overlay), `text` (`null`/`''` for outline only), `showHandOutline`, `handSvg` (override the outline markup), `color`.
- Customizable `messages` strings (initialization, save error, and all camera/error messages).
- `TryonUIPlugin.showHandPrompt()` / `hideHandPrompt()` to imperatively control the hand-prompt overlay.
### Changed
- `TryonUIPlugin` no longer hardcodes loading text, logo, box size/background, alignment, hand SVG, or prompt text — all driven by config (existing defaults preserved when no config is passed).
## [0.2.6] - 2026-06-18
### Added
- Try-on save-image UI with a smoother image-saving animation (ultra mode).
### Changed
- Ultra-mode save: crop size now sized relative to the ring's bounding-sphere radius.
- Fade shader: ring distance fade-out with more smoothness; reduced finger fade occlusion factor and increased circle fade factor.
### Fixed
- Ultra-resolution save mode artifacts.
- Fade shader circle fade-out being incorrect during zoom.
- Ring non-uniform rotation depending on aspect ratio.
- Reset on window resize.
## [0.2.5] - 2026-06-12
### Added
- High-resolution image export using camera.setViewOffset(): Super-sampled ring crop composited onto the original.
- Downloading/loading image bake files for importing accurate onbody image data (for using try-on backend data such as finger edges, finger width, depth rotation, occlusion mask)
- `maxSize` option to `saveImage` for ultra-mode output.
### Fixed
- SSAO options not properly resetting when entering and then exiting the try-on.
## [0.2.4] - 2026-06-10
### Added
- `shadowColor` for SSS contact shadows.
### Fixed
- apply/restore zoom in `_setCameraSettings()`
## [0.2.3] - 2026-06-04
### Added
- `enterSetupMode({ showGizmos: false })`: enter setup mode with the transform gizmo created but hidden/disabled. Calling `setTransformMode()` re-shows it.
### Fixed
- Auto-fit: original child transforms now restored when fit fails (no inner boundary or validation failure) instead of leaving them zeroed.
- Setup mode: camera position is now saved on enter and restored on exit.
- Image-mode transform gizmo could disappear after resize/render-scale changes; now detaches on resize so the next update rebinds it.
## [0.2.2] - 2026-05-29
### Fixed
- Set webcam state throwing error if camera background plugin is not set.
## [0.2.1] - 2026-05-29
### Fixed
- Setting video scale changed video aspect ratio unexpectedly.
## [0.2.0] - 2026-05-28 - Try-On Backend Integration
### Added
- Try-on backend: comprehensive server-side pipeline for ring placement: edge detection,
depth-based yaw/pitch, finger-width estimation, per-finger visibility scoring, and
health warmup, roll + many more misc additions. Opt in via `backendUrl` config or the `?backend` query parameter.
- Improvements for the wristwear try-on: wrist velocity calculations and motion-prediction features in `MPHand` and `MPBody` for more stable wristwear tracking.
### Fixed
- Ring landmarks no longer fade when try-on backend is in use.
- Ring position and finger width mismatch when using backend predictions.
- `offsetRotation` was incorrectly displacing ring position.
- Incorrect transform where only the ring model was scaled, not the full setup.
- Ring alignment now uses a single reference edge for consistent placement.
- Fist pitch correction when backend is active.
- Occluded ring finger now shows an explicit error instead of silently failing.
- Cylinder occluder size reduced in image mode to prevent over-occlusion.
- Auto-fit placement accuracy after the onbody-depth merge.
- Share button now downloads via `getImageBlob()` with a proper filename.
- Various setup mode issues and toolbar regressions.
## [0.1.11] - 2026-05-04
### Added
- Setup mode: shift key snapping override for transform controls.
- Setup mode: reset functionality for all transform modes.
- Setup mode: transform mode selector and auto-fit controls exposed in viewer setup (`index.ts`, `watch-index.ts`).
- Watch occluder estimator: new `WatchOccluderDepthPass` for top-down depth map approach; greatly improves occluder accuracy for rings auto-fit as well.
- Wrist velocity calculations and motion-prediction features in `MPHand` and `MPBody` for more stable wristwear tracking.
### Changed
- Wristwear placement now uses `TrackingConfig` offsets (consistent with ring try-on).
- Pose landmarker: reduced smoothing for faster response; disabled for back camera to save resources.
- Pose landmarker: slightly faster convergence for still poses.
- Default `videoScale` changed from 1.0 to 1.35.
- Wrist width calculation in `HandAnalyzer` refined for better size estimation.
- SSAO power no longer influences SSS gamma (separated concerns); SSS parameters tuned for wristwear.
- Watch occluder estimation rewrote using circle-fitting for improved auto-centering and scaling.
### Fixed
- Severe animation lag in `TryonUIPlugin` animations.
- Incorrect wristwear yaw when hand deviates radially/ulnarly while the arm remains still.
- `borderColor` / `borderImage` not applied in wristwear image mode.
- Inconsistent relative wristwear placement across frames.
- Transform gizmo rendering artifacts caused by `FadeShaderExtension`.
- Watch occluder losing its material after estimation.
- Camera depth alignment in setup mode auto-fit.
## [0.1.10] - 2026-05-01
### Fixed
- `TryonUIPlugin` failing to attach in obfuscated builds; reverted plugin lookup to use `PluginType` strings instead of mangled class names.
## [0.1.9] - 2026-05-01
### Added
- `canRunVTO()` pre-flight helper exported from the lib. Returns WebGL2/GPU/device capability check plus an optional `warning` for Chrome/Windows on integrated GPUs.
### Removed
- License/key system removed from `BaseTryonPlugin`; licensing is now handled solely by the underlying webgi runtime.
## [0.1.8] - 2026-04-21
### Fixed
- Fix race condition in `stop` method by setting `_running` to `false` right away.
## [0.1.7] - 2026-04-16
### Added
- `getImageBlob(type?, quality?)` method to retrieve the current try-on image as a `Blob` (auto-cropped in image mode).
- `saveImage` now accepts a file format/MIME type parameter.
- Vertical border support in image mode.
- Crop image in image mode when saving it.
### Changed
- `startWithImage` and `setImage` now accept any `CanvasImageSource` (not just `HTMLImageElement`).
- Hand analyzer resets on window resize to prevent stale tracking state.
## [0.1.6] - 2026-04-09
### Added
- Side fade-out at cylinder edges in live try-on mode to prevent floating shadow artifacts.
### Changed
- Unified SSAO and contact shadows into a single SSS computation pipeline — both now drive the same warm-skin shading path independently.
- Improved orbit-normal line smoothing (`irregularSmoothing`) with a refined distance mapping function.
- Refactored `SSSFingerCylinderShadow`: eliminated duplicated material/uniform/extension blocks; added `updateRingTransform()` for a single-call per-frame update.
- Removed SSS wrap strength and saturation boost config parameters; simplified shader accordingly.
### Fixed
- Contact shadow Z-fighting artifacts between shadow cylinder and sphere end-caps.
- SSAO warm-shading had no effect when contact shadows were disabled; AO now correctly activates the full SSS colour path.
## [0.1.5] - 2026-04-07
### Added
- Pose-based wristwear try-on integration for more independent wrist transform.
- Screen-space contact shadows (SSCS) for more realistic shadow rendering.
- Alternating tracking and model inference for better performance.
- Preliminary API documentation.
### Fixed
- Fix try-on running always in "IMAGE" mode.
- Fix shadow rendering in wrist wear try-on.
- Fix static image resize, fade shader, and default transform controls.
- Fix borderColor and borderImage styling.
- Fix camera moving in image mode.
### Changed
- Adjust wristwear size and snappiness.
- Use average landmarks for body tracking.
- UI clean-ups and code refactoring.
## [0.1.4] - 2026-03-11
### Fixed
- Jewelry object visible in the first frame after entering try-on mode.
## [0.1.3] - 2026-03-11
### Fixed
- Inconsistent AO setting.
## [0.1.2] - 2026-03-08
### Fixed
- Video scale not applied correctly.
- Quaternion filters improved.
## [0.1.1] - 2026-03-08
### Fixed
- Video texture lagging behind during zoom on invisible elements.
- Error messages being to short.
- Restore older hand tracking smoothing functions in MPHand to address degraded tracking.
## [0.1.0] - 2026-03-06
### Added
- WristwearTryonPlugin: Add a watch and bracelet try-on.
- Major refactoring of the codebase.
- Refactor to support future try-on plugins.
- Automatic zoom in on interaction (closer zoom of 1.5 for better experience).
### Fixed
- UX improvements: preloading, polling in-store try-on plugin.
- Fix occlusion for bigger jewelry like the billion dollar ring demo ring.
- Various improvements for artifacts in fade shader and motion blur.
## [0.0.41] - 2026-03-01
### Added
- `preferBackCamera` option on RingTryonPlugin to allow selecting the back (environment) camera on start.
## [0.0.40] - 2026-02-16
### Fixed
- Support for larger rings (e.g. billion dollar ring demo ring) with proper occlusion (faded and SSR occluders) and shadow SSAO.
- Less visual occlusion artifacts for poses like fist.
- Ring try-on UI: no specific error message for most common error (camera permission denied) shown.
- Enable quaternion filters for smoothing rotation flickering which was especially noticeable for larger rings like the billion dollar ring demo one.
- Fix strong display artifacts when entering AR mode due to interpolation with unclamped tonemapped output color.
## [0.0.39] - 2026-01-16
### Added
- A static preload function to the RingTryonPlugin.
## [0.0.38] - 2025-12-26
### Fixed
- Disable DollyFov in camera settings.
## [0.0.37] - 2025-10-02
### Fixed
- In-store: Shader crash when using segmentation.
- In-store: Address not selecting the correct camera.
### Changed
- In-store: More proper syncing of MP and Leap.
## [0.0.36] - 2025-08-29
### Changed
- Demo page: css changes, changed 3d model.
- minDistance change in `RingTryonConfig`
## [0.0.35] - 2025-08-27
### Changed
- Demo page: check for 'edit' query parameter to show UIConfig for TryOn.
- Removed setup mode UI
- static variables for mediapipe libraries
## [0.0.34] - 2025-08-15
### Fixed
- Minor fix: proper button display in demo when try-on start failed.
## [0.0.33] - 2025-08-15
### Changed
- Demo page: setup mode UI, try-on buttons only showing when try-on running.
### Fixed
- Setup mode UI: proper updating in scene when config changed.
## [0.0.32] - 2025-08-06
### Changed
- Update demo link and WebGi version to 0.15.2.
## [0.0.31] - 2025-08-03
### Changed
- Disable motion blur by default.
- Update WebGi version to 0.15.0.
### Fix
- Add backwards compatibility for motion blur and WebGi pre-0.11.0.
- Resolved issues with ring fading and hiding for certain hand poses.
## [0.0.30] - 2025-08-03
### Changed
- Refactored configuration system for improved structure and maintainability.
- Improved motion blur effect; cleaned up and refactored related code.
- Removed `lil-gui` dependency; moved GLSL code to separate files; improved code obfuscation workflow.
### Fixed
- Addressed an issue where the asset was not being hidden entirely, causing an outline to be visible.
- Camera near/far planes are now constant to address a performance issue and to prevent possible clipping artifacts.
## [0.0.29] - 2025-06-17
### Fixed
- Fix camera near/far based clipping at close range.
## [0.0.28] - 2025-06-17
### Fixed
- Revert web camera background plugin to recent version. Fix scene background reset issue introduced by reverting.
## [0.0.27] - 2025-06-06
### Fixed
- Check first for video full HD resolution.
## [0.0.26] - 2025-06-06
### Fixed
- Reverted to old web camera plugin for now.
## [0.0.25] - 2025-06-06
### Fixed
- Reverted to old web camera plugin for now.
## [0.0.24] - 2025-06-06
### Fixed
- Applied custom configs and checking for in-store plugin.
### Added
- Check for in-store availability in index.ts
## [0.0.23] - 2025-06-02
### Fixed
- Revert some scene config (SSR, SSAO).
## [0.0.22] - 2025-06-01
### Fixed
- Instore build deployment.
## [0.0.21] - 2025-05-31
### Fixed
- Integrate latest development changes.
- Deprecate segmenter hand analyzing. Finger width detection is now based on landmarks.
- Adjust config and smoothing.
## [0.0.20-dev.10] - 2025-05-30
### Fixed
- Setup mode cylinder.
## [0.0.20-dev.9] - 2025-05-15
### Added
- Deployment
---
# Ring Configurator in iJewel3D
iJewel3D Ring Configurator is a powerful tool that lets you create interactive, customizable ring configurators for your jewelry business. By combining modular ring components (heads and shanks), customers can explore hundreds of ring variations in real-time 3D choosing diamond shapes, carat sizes, shank styles, and materials.
Whether you want to embed a configurator on your website, share it directly with customers, or self-host it on your own server, Ring Configurator makes it simple.
### How It Works
Ring Configurator uses a modular approach: instead of modeling every ring variation, you create separate **Head** and **Shank** components that iJewel combines dynamically. This means fewer 3D files to manage and endless possibilities for your customers.
## Getting Started
Follow these three steps to set up your Ring Configurator:
### [1. Prepare 3D Models](./prepare-components)
Learn how to prepare your ring components, assign proper layers, and set up anchor points for automatic alignment.
[](./prepare-components)
**What you'll learn:**
- Separating rings into Head and Shank components
- Creating variations (prong counts, diamond shapes, shank styles)
- Setting up anchor-based auto placement
- Naming conventions and layer assignment in Rhino
### [2. Set Up in iJewel3D Platform](./ring-configurator-in-ijewel3d)
Upload your components to the iJewel3D platform and configure your Ring Configurator with variations, materials, and settings.
[](./ring-configurator-in-ijewel3d)
**What you'll learn:**
- Uploading and syncing 3D files
- Configuring head and shank variations
- Setting up materials and finishes
- Organizing your component library
### [3. Share, Embed, or Self-Host](./using-ring-configurator)
Deploy your Ring Configurator to reach customers embed it on your website, share direct links, or use templates for self-hosting.
[](./using-ring-configurator)
**What you'll learn:**
- Embedding the configurator on your website
- Sharing direct links with customers
- Using ready-made templates
- Self-hosting options for full control
---
# Prepare Ring Components
When building rings in iJewel, you don't need to model every variation from scratch. By separating a ring into **Head** and **Shank** components, you can dynamically combine them inside iJewel to generate dozens or even hundreds of unique ring designs from a small set of files.
### Why Separate Components?
| Benefit | Description |
|---------|-------------|
| **Mix and Match** | Combine any head with any shank |
| **Fewer Models** | Reduce total files needed |
| **Easy Updates** | Add new variations without remodeling the entire ring |
## Creating Variations
Each component should have multiple variations to maximize configurability.
### Head Variations
| Property | Examples |
|----------|----------|
| **Prong Count** | 4-prong, 5-prong, 6-prong |
| **Diamond Shape** | Round, Princess, Pear, Oval, Marquise |
| **Carat Size** | 0.5 ct, 1 ct, 2 ct, 3 ct |
### Shank Variations
| Style | Description |
|-------|-------------|
| **Plain** | Simple, smooth band |
| **Pave** | Small diamonds set into the band |
| **Channel** | Diamonds set in a channel groove |
| **Split Shank** | Band splits near the head |
| **Cathedral** | Arched supports rising to meet the head |
By combining these, iJewel can automatically generate dozens or hundreds of ring combinations from a small set of files.
## Two Methods for Creating Components
These guidelines work with any modelling software, but examples here use **Rhino** and **MatrixGold**, as they are most commonly used in the jewelry industry.
### Method 1: Pre-Positioned Components
In this method:
- Each Head and Shank is modeled separately
- They are positioned correctly relative to each other in 3D space
- When combined, they already form a complete ring
::: tip When to Use
- Fixed designs with limited variations
- Simple setups
- When exact manual positioning is preferred
:::
---
### Method 2: Anchor-Based Auto Placement (Recommended)
In this method, exact positioning is handled by iJewel automatically using an **anchor object**.
#### Steps (Rhino Example)
1. Create a cube or simple shape (anchor object)
2. Place it on top of the shank, exactly where the head should sit
3. Assign the anchor object to a layer named `placeholder:head` likewise it can be anything which you want to place it over `placeholder:Controls
## Three Pillars
### Photorealistic 3D in the Browser
Customers see a real time 3D model with physically accurate materials, lighting, and reflections. White gold looks like white gold. A hammered finish catches light differently than polished. Material properties are tuned to match real metal alloys.
### Parametric Design, No 3D Models to Manage
Every ring is built from parameters, not pre made files. The current Drive
starter provides 7 profile shapes, 3 metals, 7 finishes, 3 partition modes, 4
diamond settings, and continuous width/height dimensions. You can replace or
extend those catalogs in your project, and the engine generates the selected
geometry on demand.
### From Screen to CNC
Every design your customers create can be exported as a detailed specification sheet: profile cross section, exact dimensions in millimeters, ring size (US/EU/UK), metal composition, diamond count and carat weight, and pricing breakdown. Ready for your CAD team or CNC machine.
## Who Is This For?
| | |
|---|---|
| **Jewelry Brands** | Offer a premium, interactive wedding band experience on your website. Your customers design their own rings with real time photorealistic preview. |
| **Online Retailers** | Drop a configurator into your Shopify, WooCommerce, or Magento store. Customers configure, see the price, and add to cart, all without leaving your site. |
| **Luxury Jewellers** | Build a fully custom interface that matches your brand identity. Use the headless SDK to control every pixel while the engine handles the 3D. |
| **Manufacturers** | Customers design. You manufacture. The spec sheet bridges the gap: accurate dimensions and materials, ready for production. |
## What Makes It Different
| Traditional Configurators | Wedding Band Builder |
|---|---|
| Pre rendered image swaps | Real time 3D geometry generation |
| Fixed catalog of options | Parametric: every combination is unique |
| Separate pricing spreadsheets | Volume based pricing from actual 3D geometry |
| Desktop-only or app-required | Web based, mobile ready, AR capable |
| Generic white label UI | Fully customizable SDK with theming |
| Single pricing model | Western markup, Indian making charges, Gulf per-gram |
## Get Started
Want runnable code first? Open the
[Wedding Band starter templates](./templates), where every example includes
both a live page and its GitHub source.
Why Wedding Band Builder
Competitive advantages, use cases, and business outcomes Features
Complete feature tour: profiles, metals, diamonds, and more Live Demo
Try it yourself: configure a ring in your browser right now Start Here
Create the project on iJewel3D, then choose how to share or embed it Create a Project
Build your Wedding Band project on iJewel3D, no code required Starter Templates
Open each implementation live and inspect its published source
---
# Why Wedding Band Builder
## The Problem
Most online jewelry stores present wedding bands as static image catalogs with a fixed set of pre made options. This creates several issues for jewellers:
- **Lost sales**: customers can't visualize exactly what they want, so they hesitate or leave
- **Returns and remakes**: what looked good in a photo doesn't match expectations
- **Limited catalog**: every new option requires new photography, new 3D models, new SKUs
- **No at-home experience**: customers still need to visit a store to see the ring in context
## The Solution
The Wedding Band Builder replaces static catalogs with a **real time design engine**. Customers design their ring by adjusting dimensions, materials, and details that update live in 3D. The rendered preview reflects physically based materials and lighting.
## Competitive Advantages
### Runs in the Browser, No App Needed
The configurator runs entirely in the browser on desktop, tablet, and phone. No app install or plugin is required. Reducing friction between browsing and purchasing tends to improve conversion rates.
Competitive advantages, use cases, and business outcomes Features
Complete feature tour: profiles, metals, diamonds, and more Live Demo
Try it yourself: configure a ring in your browser right now Start Here
Create the project on iJewel3D, then choose how to share or embed it Create a Project
Build your Wedding Band project on iJewel3D, no code required Starter Templates
Open each implementation live and inspect its published source
### AR Try On
Customers can preview their designed ring on their hand using camera-based live
hand tracking. This gives a sense of scale and appearance before purchasing.
### Spec Sheets for Manufacturing
Every design produces a precise specification sheet: profile cross section diagram, dimensions in millimeters, ring size across three international systems, metal composition, diamond count and carat weight, and complete pricing breakdown. Your CAD team or CNC machine gets exactly what was designed on screen.
### His & Her Paired Band Configuration
Customers design both bands together. Linked mode keeps both rings in sync: change the metal on one, both update. Independent mode lets each band be unique. The pricing shows individual and combined totals.
### Global Pricing
Not every jeweller prices the same way. The engine supports:
- **Western model**: markup multiplier (1.5×–2.5×) covering all costs
- **Indian model**: explicit making charges (8–35% of metal cost)
- **Gulf model**: per-gram making charges ($5–$50/gram)
Per-metal pricing (white gold costs more than yellow due to palladium), finish surcharges, diamond setting labor costs, and configurable rounding are all built in.
### Physically Based Rendering
The 3D engine uses PBR materials with image-based lighting and real time gem refraction. White gold has the reflectance of a palladium alloy. A hammered finish displaces the surface geometry. Diamonds refract light through computed facets. This isn't a texture swap on a generic 3D model.
### No Vendor Lock In
Your configuration data is JSON. Export it, store it, migrate it. The headless API means your frontend is yours: your team or agency builds and maintains the UI without depending on a third party for every change. Switch hosting, switch CMS, switch developer. The data and the integration stay portable.
### Works With Any Manufacturer
The spec sheet is manufacturer-independent. It outputs profile cross sections, exact dimensions in millimeters, ring size across three international systems, metal composition, and diamond specs. Send it to any workshop, any CAD team, any CNC machine.
### Your Brand, Your Design
Use the built-in UI with one of 11 theme presets, or build your own interface from scratch using the headless SDK. The configurator is a white label engine. Your customers see your brand, not ours. No billable hours to a vendor for branding changes or layout updates.
### Mobile Optimized
The 3D engine is optimized for mobile GPUs. Touch gestures such as pinch to
zoom and swipe to rotate work natively. On compatible devices, camera Try-On
lets customers preview the ring on their hand in current Safari on iOS and
Chrome on Android.
### Predictable Costs
One-time onboarding plus an annual subscription. No opaque project pricing, no change orders for every UI tweak. You know what you'll pay.
### Dedicated Onboarding
Setup assistance is included. Documentation, email support, and a partner network for integrations. You're not left to figure it out from a wiki.
### Ecommerce Ready
Drop in integrations for the platforms your business already uses:
| Platform | Integration |
|---|---|
| **Shopify** | Liquid section, iframe embed, add-to-cart bridge |
| **WooCommerce** | Shortcode or custom product template |
| **Magento** | Custom block with Storefront API |
| **BigCommerce** | Stencil theme template |
| **Wix** | HTML embed with Velo integration |
Or integrate directly with any website using a `
```
Best for: custom websites, React/Vue/Angular apps, full API access.
→ [Full script tag guide](./integration-direct) · [Framework examples](./frameworks/vanilla)
## What's Next?
Choose your path based on what you need:
| I want to... | Go to |
|---|---|
| Customize the look and feel | [Theming & Branding](./theming) |
| Build my own UI from scratch | [Custom UI (Headless)](./integration-headless) |
| Set up pricing | [Pricing Engine](./pricing) |
| Add to Shopify / WooCommerce / etc. | [E-Commerce Platforms](./ecommerce/shopify) |
| See the full API | [API Reference](./api-reference) |
| Understand the measurement system | [Ring Measurements Guide](./measurement-guide) |
---
# Wedding Band Starter Templates
Use these maintained examples as implementation starting points. Every row
includes a live GitHub Pages build and the exact source currently published
from the `main` branch of
[`iJewelTemplates`](https://github.com/ijewel3d/iJewelTemplates).
| Template | Use it when | Live | Code |
| --- | --- | --- | --- |
| Built-in Wedding Band UI | You want to load a complete Wedding Band project and use the standard iJewel3D interface. | [Open live](https://ijewel3d.github.io/iJewelTemplates/wedding-band/wedding-band.html) | [View HTML](https://github.com/ijewel3d/iJewelTemplates/blob/main/wedding-band/wedding-band.html) |
| Published Drive project | You have a public Drive file ID and want the smallest `loadModelById` example. | [Open live](https://ijewel3d.github.io/iJewelTemplates/wedding-band/wedding-band-default.html) | [View HTML](https://github.com/ijewel3d/iJewelTemplates/blob/main/wedding-band/wedding-band-default.html) |
| Custom UI | You want same-page controller access and a fully custom storefront interface. | [Open live](https://ijewel3d.github.io/iJewelTemplates/wedding-band/custom-ui/index.html) | [Browse source](https://github.com/ijewel3d/iJewelTemplates/tree/main/wedding-band/custom-ui) |
| iframe host integration | You want custom host-page controls around a published Drive embed using `postMessage`. | [Open live](https://ijewel3d.github.io/iJewelTemplates/wedding-band/iframe-demo/index.html) | [Browse source](https://github.com/ijewel3d/iJewelTemplates/tree/main/wedding-band/iframe-demo) |
The folder-based examples depend on their adjacent JavaScript, CSS, JSON, and
image assets, so copy the whole folder rather than only `index.html`.
::: info Release baseline
The documentation examples use Mini Viewer `0.6.18`, which adds configurator
Try-On on top of the material variants, outside and inside material features,
and Modern Metals layout from `0.6.17`. The linked templates are maintained in
a separate repository and may still show an earlier pinned version. Check the
script URL in the source you copy and use `0.6.18` or later when the project
offers Try-On.
The hosted iframe uses the Viewer version deployed by `ijewel3d.com`.
:::
::: warning Hosted iframe version requirement
The iframe host controls require the `ijewel3d.com` embedded application to be
deployed with Mini Viewer `0.6.11` or newer. If the rings render inside the
iframe but the host remains on **Loading iframe…**, the hosted application is
still serving an older Viewer. Update that deployment or use the self-hosted
iframe viewer from the [iframe guide](./integration-iframe).
:::
## Choose the right starting point
- Start with **Published Drive project** when your Wedding Band configurator
already exists in iJewel Drive. Replace its `fileId` and `instance`. If it
does not exist yet, start with [Create a Project](./drive-setup).
- Start with **Built-in Wedding Band UI** when you are loading a complete
project JSON and want the standard controls.
- Start with **Custom UI** when your controls and viewer run on the same page.
The implementation reads catalogs from the controller instead of hard-coding
profile, material, variant, finish, and diamond choices.
- Start with **iframe host integration** when the viewer and host page have
different origins or when a CMS owns the outer page.
## Before production
1. Replace demo project URLs, Drive file IDs, instance names, prices, and cart
behavior with your own values.
2. Compare the template's pinned SDK URL with the version required by this
documentation. Configurator Try-On requires Mini Viewer `0.6.18` or later.
3. For iframe integrations, restrict `postMessage` to the exact viewer origin.
4. Serve the page over HTTPS and retain `allow="camera"` if Try-On runs inside
an iframe.
5. Test desktop and mobile layouts with the actual catalog and project size.
Continue with [Assets Setup](./assets-setup) to prepare your own profiles,
materials, icons, and models, or go directly to the
[integration guides](./deployment).
---
# Setting Up Assets on iJewel Platform
Before deploying your Wedding Band Builder, you need to configure all the building blocks on the iJewel platform. This page covers each asset type and how to prepare it.
When these assets are ready, [Create a Project](./drive-setup)
shows the complete creation flow, the generated folder structure, exact Sync
rules, version migration, and which configuration fields Sync preserves.
## 2D Profiles
Profiles are **2D cross section curves** that define the shape of the wedding band. The builder extrudes these curves along a circular torus path to generate the 3D ring geometry in real time.
The platform includes several built-in profiles:
| Profile | Description |
|---------|-------------|
| D-Shape | Classic rounded exterior, flat interior |
| Flat | Flat exterior and interior |
| Comfort | Rounded on both exterior and interior |
| Knife Edge | Pointed peak on the exterior |
| Beveled | Angled flat facets on the exterior |
| Concave | Inward-curving exterior surface |
| Round | Fully circular cross section |
**Custom profiles** can be uploaded as `.3dm` (Rhino) files containing a single closed 2D curve. The curve defines the cross section shape, which the builder then extrudes and scales based on the user's width and thickness settings.
Custom profile upload needs the **Silver** plan or above. The profiles in the
table above are the built-in library, available on every plan. See
[Create a Project](./drive-setup) for the upload steps.
::: warning
The 2D profile curve must be drawn in accurate millimeter dimensions. The engine uses the curve's actual size as the base measurement for width and thickness. If your profile is drawn at the wrong scale, all dimensions, weight calculations, and pricing will be incorrect.
:::
## Material Library
The material library models the real combinations your catalog offers instead
of assuming a complete metal-by-finish grid:
```text
base material → variant/quality → finish PMAT
```
Examples include Yellow Gold → 14k/18k/22k → Polished/Brush/Hammered,
Carbon → pattern 1/pattern 2 → a single default PMAT, and Wood → species → a
single default PMAT.
The standard Drive folder layout is:
```text
materials/
Available presets: `default`, `luxury-gold`, `modern-minimal`, `dark`, `rose-elegant`, `coral-modern`, `fresh-teal`, `minimal-blue`, `warm-beige`, `classic-gold`, `ijewel`. See [Theming & Branding](./theming) for full customization options.
## Framework Examples
| Framework | What You Get | Example |
|-----------|-------------|---------|
| **Vanilla JS** | Plain HTML/JS, no build step | [View example](./frameworks/vanilla) |
| **React** | Component + hooks, headless variant | [View example](./frameworks/react) |
| **Vue 3** | Composable + SFC, headless variant | [View example](./frameworks/vue) |
| **Next.js** | Client component, App Router + Pages Router | [View example](./frameworks/nextjs) |
| **Angular** | Service + Component, RxJS observables | [View example](./frameworks/angular) |
| **Svelte** | Component with slots, headless variant | [View example](./frameworks/svelte) |
## Error Handling
```javascript
api.events.on('error', (err) => {
console.error(`[${err.source}] ${err.message}`);
});
```
## Multiple Viewers
You can have multiple viewers on one page. Each gets its own API instance:
```javascript
const viewer1 = new ijewelViewer.Viewer(root1, project1, options);
const viewer2 = new ijewelViewer.Viewer(root2, project2, options);
```
Configuration Reference
### Project Options | Property | Type | Description | |----------|------|-------------| | `name` | `string` | Display name shown in the loading screen | | `version` | `string` | Project version (use `'v5'`) | | `basePath` | `string` | Base URL for resolving asset paths in the manifest | | `plugins.WeddingBandBuilder.manifestUrl` | `string` | URL to the manifest JSON file (relative to `basePath`) | ### Viewer Options | Property | Type | Default | Description | |----------|------|---------|-------------| | `showCard` | `boolean` | `false` | Show the product info card | | `showSwitchNode` | `boolean` | `false` | Show the model switcher | | `showUiButtons` | `boolean` | `true` | Show viewer control buttons (quality, reset view, etc.) | | `showConfigurator` | `boolean` | `false` | Show the generic configurator panel (not needed since WBB has its own) | | `showZoomButtons` | `boolean` | `true` | Show +/- zoom controls | | `enableZoom` | `boolean` | `true` | Allow scroll/pinch zoom | | `hideWbbUi` | `boolean` | `true` | Hide the built-in Wedding Band panel; set to `false` to show it |Container Sizing & Mobile Layout
### Container Sizing The viewer fills its container. Make sure the container has explicit dimensions: ```css /* Full viewport */ #viewer-root { width: 100vw; height: 100vh; } /* Fixed size */ #viewer-root { width: 800px; height: 600px; } /* Responsive (4:3 aspect ratio) */ #viewer-root { width: 100%; height: 0; padding-bottom: 75%; position: relative; } ``` ::: danger The viewer fills its container. If the container has zero height, nothing renders. Always set height explicitly: ```html ``` This is the most common cause of a blank viewer. ::: ### Mobile Responsiveness The built-in panel automatically switches to a stacked layout on screens narrower than 768px. The 3D viewer sits on top and the configuration panel goes below, each taking 50% of the viewport height. Tab labels collapse to icons only.
### Communicate via postMessage
```javascript
const iframe = document.getElementById('wbb-iframe');
const viewerOrigin = new URL(iframe.src).origin;
let requestId = 0;
// Send a command
function send(method, args = []) {
iframe.contentWindow.postMessage({
id: `req-${++requestId}`, method, args,
}, viewerOrigin);
}
// Listen for events
window.addEventListener('message', (e) => {
if (e.source !== iframe.contentWindow) return;
if (e.origin !== viewerOrigin) return;
if (e.data?.event === 'ready') {
send('setProfile', [0]);
send('setMaterialRef', [1, {
base: 'yellow', variant: '18k', finish: 'polished',
}]);
}
if (e.data?.event === 'price:updated') {
document.getElementById('price').textContent =
`$${e.data.data.pricing.totalUsd.toFixed(2)}`;
}
});
```
The bridge also exposes the outside-feature methods. For example, send
`setOutsideFeatures` with one feature object and the optional band name:
```javascript
send('setOutsideFeatures', [{
inlays: [{
centerZ: 0, widthMm: 1,
metal: 'yellow', variant: '18k', finish: 'polished',
}],
overlays: [],
}]);
```
It forwards `inlays:changed`, `overlays:changed`, and `sleeve:changed` events to
the parent with the same `{ event, data }` envelope.
### Ready lifecycle
The Wedding Band plugin installs its global and postMessage exposure before it
emits `{ event: 'ready', data: {} }`. It emits `ready` exactly once for each
successful project initialization. Wait for that event before sending commands
or queries.
Importing another project or reloading the iframe starts a new lifecycle and
produces a new `ready` event. Disposing or resetting the plugin removes its
message listener and event forwarding, so an old controller cannot reply after
teardown.
**[View complete host page example](./examples/iframe-host)** for a full page with profile/material buttons and live price display.
## Headless Mode
For a self-hosted viewer page, load the iframe with `?ui=false` to hide the
built-in panel and build all controls on the host page:
```html
```
For the hosted iJewel3D route, use `hideWbbUi=true`:
```html
```
Use `postMessage` to query the catalog and control everything from your page. See [Custom UI (Headless)](./integration-headless) for a full guide on building custom controls.
## postMessage Protocol
**Sending commands** (all [API methods](./api-reference) are available):
```javascript
// Command: { id: 'req-1', method: 'setWidth', args: [5.0] }
// Success: { id: 'req-1', result: null }
// Error: { id: 'req-1', error: { message: '...', source: 'api' } }
```
**Receiving events** (forwarded automatically from the viewer):
```javascript
// { event: 'price:updated', data: { bandName: 'her', pricing: { totalUsd: 1250.00, ... } } }
```
Promise-based query helper
```javascript function query(method, args = []) { return new Promise((resolve, reject) => { const id = `req-${++requestId}`; const timeout = setTimeout(() => { cleanup(); reject(new Error(`Timed out waiting for ${method}`)); }, 8000); const cleanup = () => { clearTimeout(timeout); window.removeEventListener('message', handler); }; const handler = (e) => { if (e.source !== iframe.contentWindow) return; if (e.origin !== viewerOrigin) return; if (e.data?.id !== id) return; cleanup(); if (e.data.error) reject(new Error(e.data.error.message)); else resolve(e.data.result); }; window.addEventListener('message', handler); iframe.contentWindow.postMessage({ id, method, args }, viewerOrigin); }); } // Usage const price = await query('getPrice', ['her']); const snapshot = await query('getSnapshot'); ```
Security: Restrict Origins
In production, always use the exact target origin and validate both the source window and origin of every incoming message: ```javascript const viewerOrigin = new URL(iframe.src).origin; iframe.contentWindow.postMessage({ id, method, args }, viewerOrigin); window.addEventListener('message', (event) => { if (event.source !== iframe.contentWindow) return; if (event.origin !== viewerOrigin) return; // Handle the validated message. }); ```Responsive Sizing
```css .viewer-container { position: relative; width: 100%; padding-bottom: 75%; /* 4:3 aspect ratio */ } .viewer-container iframe { position: absolute; top: 0; left: 0; width: 100%; height: 100%; border: none; } ```AR Support
Add `camera` to the iframe's `allow` attribute. Try-On uses the camera and live hand tracking; it does not require WebXR. Without camera permission, the button can appear but the camera cannot start.Same-Origin Shortcut
If the iframe and host page are on the same origin, you can skip postMessage entirely: ```javascript const iframe = document.getElementById('wbb-iframe'); const viewer = iframe.contentWindow.ijewelViewer; const api = viewer.getPluginByType('WeddingBandBuilder').controller; api.setWidthMultiplier(1.1); ```URL Parameters
The self-hosted viewer page accepts these query parameters: | Parameter | Default | Description | |-----------|---------|-------------| | `manifest` | `wedding-band-project.json` | URL to the manifest JSON file | | `basePath` | (viewer page directory) | Base URL for resolving asset paths | | `ui` | `true` | Set to `false` to hide the built-in panel (headless mode) | ```html ```Hosted Embed URL Parameters
The iJewel3D hosted route uses `isAutoplay`, `hideWbbUi`, and `showUiButtons`. Parameter names are case-sensitive; for example, `isAutoPlay` is not equivalent to `isAutoplay`. ```html ```
## Overview
Set `hideWbbUi: true` in Mini Viewer's options to run in **headless mode**. The 3D viewer renders with no built-in panel. This works with both integration approaches:
| Integration | How to Enable | How to Access API |
|-------------|--------------|-------------------|
| [Script Tag](./integration-direct) | `hideWbbUi: true` in viewer options | `viewer.getPluginByType('WeddingBandBuilder').controller` |
| [iframe](./integration-iframe) | `?ui=false` URL parameter | `postMessage` from the host page |
This page covers the Script Tag approach. For iframe-based custom UI, the same concepts apply but you wrap each API call in `postMessage`. See [iframe headless mode](./integration-iframe#headless-mode).
## Getting Started
```javascript
let api;
let wbbPlugin;
// Initialize in headless mode
new ijewelViewer.Viewer(document.getElementById('viewer'), {
name: 'Wedding Band Builder',
version: 'v5',
basePath: 'https://your-cdn.com/wbb-assets/',
plugins: {
WeddingBandBuilder: {
manifestUrl: 'wedding-band-project.json',
},
},
}, {
showCard: false, showSwitchNode: false, showUiButtons: false,
showConfigurator: false, showZoomButtons: false, enableZoom: true,
hideWbbUi: true,
});
// Wait for API, then build your UI
window.addEventListener('ijewel-viewer-ready', (e) => {
wbbPlugin = e.detail.viewer.getPluginByType('WeddingBandBuilder');
api = wbbPlugin.controller;
// Read the catalog to see what's available in your manifest
const profiles = api.getAvailableProfiles();
const materials = api.getAvailableMaterials('band');
// Wire your controls to the API
buildProfileSelector(profiles);
buildMaterialSwatches(api, materials);
buildWidthSlider();
buildPriceDisplay();
});
```
## Building Controls
Each control follows the same pattern: read options from the catalog, create your UI, and call an API setter on interaction.
Profile Selector
```javascript function buildProfileSelector(profiles) { const container = document.getElementById('profile-selector'); profiles.forEach((profile) => { const btn = document.createElement('button'); btn.textContent = profile.name; // Use thumbnail from manifest if available if (profile.thumbnail) { btn.style.backgroundImage = `url(${profile.thumbnail})`; } btn.addEventListener('click', async () => { await api.setProfile(profile.index); container.querySelectorAll('button').forEach(b => b.classList.remove('active')); btn.classList.add('active'); }); container.appendChild(btn); }); } ```
Material Swatches
```javascript function buildMaterialSwatches(api, materials) { const container = document.getElementById('metal-selector'); materials.forEach((material) => { const swatch = document.createElement('button'); swatch.className = 'swatch'; swatch.title = material.name; if (material.iconUrl) { swatch.style.backgroundImage = `url(${material.iconUrl})`; swatch.style.backgroundSize = 'cover'; } else if (material.swatch) { swatch.style.backgroundColor = material.swatch; } swatch.addEventListener('click', async () => { const variants = api.getAvailableVariants(material.id); const variant = variants.find(v => v.id === material.defaultVariant) || variants[0]; const finishes = api.getAvailableFinishesFor(material.id) .filter(f => !variant?.files || variant.files[f.id]); const finish = finishes.find(f => f.id === material.defaultFinish) || finishes[0]; await api.setMaterialRef(1, { base: material.id, variant: variant?.id, finish: finish?.id, }); }); container.appendChild(swatch); }); } ```
Outside Features and Inside Sleeve
Read each feature picker with its usage role. Push a complete group with one `setOutsideFeatures()` call when several controls change together. ```javascript const inlayMaterial = api.getAvailableMaterials('inlay')[0]; const sleeveMaterial = api.getAvailableMaterials('sleeve')[0]; if (api.areOutsideFeaturesAvailable() && inlayMaterial) { await api.setOutsideFeatures({ inlays: [{ centerZ: 0, widthMm: 1, metal: inlayMaterial.id, variant: inlayMaterial.defaultVariant, }], overlays: [], sleeve: sleeveMaterial ? { enabled: true, metal: sleeveMaterial.id, variant: sleeveMaterial.defaultVariant, full: true, } : null, }); const bounds = api.getInlayBounds(0); const inlayPosition = document.getElementById('inlay-position'); inlayPosition.min = bounds.centerMin; inlayPosition.max = bounds.centerMax; } ``` Re-read bounds after width or feature changes. Inlay indices can change because the controller sorts them by center position.Dimension Sliders
```javascript function buildDimensionSliders() { const widthSlider = document.getElementById('width-slider'); const widthLabel = document.getElementById('width-value'); const widthLimits = api.getLimits().width; widthSlider.min = widthLimits.min; widthSlider.max = widthLimits.max; widthSlider.step = widthLimits.step || 0.05; const dims = api.getDimensions(); widthSlider.value = dims.widthMm; widthLabel.textContent = `×${dims.widthMm.toFixed(2)}`; widthSlider.addEventListener('input', (e) => { const multiplier = parseFloat(e.target.value); api.setWidthMultiplier(multiplier); widthLabel.textContent = `×${multiplier.toFixed(2)}`; }); } ``` ```html ×1.00 ```Diamond Controls
```javascript function buildDiamondControls() { const container = document.getElementById('diamond-controls'); const types = api.getAvailableSettingTypes(); // "None" option const noneBtn = document.createElement('button'); noneBtn.textContent = 'No Diamonds'; noneBtn.addEventListener('click', () => api.setDiamonds(null)); container.appendChild(noneBtn); types.filter(type => type.id !== 'none').forEach((type) => { const btn = document.createElement('button'); btn.textContent = type.name; btn.addEventListener('click', () => api.setDiamonds({ settingType: type.id })); container.appendChild(btn); }); } ```Ring Size
```javascript function buildRingSizeControl() { const slider = document.getElementById('ring-size'); const label = document.getElementById('ring-size-value'); // Ring size: inner diameter in mm, snapping to standard half-sizes slider.min = 14.04; // US 3 slider.max = 22.32; // US 13 slider.step = 0.4; // ~half-size increments slider.addEventListener('input', (e) => { const diamMm = parseFloat(e.target.value); api.setRingSize(diamMm / 2); // API takes radius label.textContent = `${diamMm.toFixed(1)} mm`; }); } ```Live Price Display
```javascript function buildPriceDisplay() { const el = document.getElementById('price'); api.events.on('price:updated', (data) => { const p = data.pricing; let text = `$${p.totalUsd.toFixed(2)}`; if (p.diamonds) { text += ` (${p.diamonds.count} diamonds, ${p.diamonds.totalCarats.toFixed(2)}ct)`; } el.textContent = text; }); // Show initial price const price = api.getPrice(); if (price) el.textContent = `$${price.totalUsd.toFixed(2)}`; } ```
Design Tips
**Keep it simple.** You don't need to expose every API option. Start with profile, metal, and width. **Use thumbnails.** Catalog methods return `thumbnail` URLs when available. Use them for visual selectors. **Show loading state.** Profile changes require geometry loading. Listen for `build:started` / `build:complete`. **Debounce sliders.** For continuous sliders, debounce to avoid excessive rebuilds: ::: tip Debounce slider inputs. The `input` event fires on every pixel of drag, which can trigger 60+ geometry rebuilds per second. A 50ms debounce keeps the UI responsive: ```javascript let timer; slider.addEventListener('input', (e) => { clearTimeout(timer); timer = setTimeout(() => api.setWidthMultiplier(parseFloat(e.target.value)), 50); }); ``` ::: **Test on mobile.** Make sure your custom controls work on touch devices. The 3D viewer handles touch/pinch natively.
Loading...
is_in_stock()) : ?>
Loading...
{{product.title}}
Loading...
Profile
Metal
Width
x1.00
Diamonds
{profiles.map((p) => (
))}
{materials.map((m) => (
))}
{price && (
${price.toFixed(2)}
)}
${{ price.totalUsd.toFixed(2) }}
x{{ width.toFixed(2) }}
${{ price.totalUsd.toFixed(2) }}
{loading && (
);
}
```
## Page (App Router)
```jsx
// app/configurator/page.jsx
'use client';
import { useState } from 'react';
import WeddingBandBuilder from '@/components/WeddingBandBuilder';
export default function ConfiguratorPage() {
const [price, setPrice] = useState(null);
const [api, setApi] = useState(null);
return (
Loading 3D viewer...
)}
Loading...
}
);
export default function ConfiguratorPage() {
return (
{{ price ? '$' + price.toFixed(2) : 'Loading...' }}
`,
})
export class AppComponent {
price: number | null = null;
api: any = null;
onReady(api: any) {
this.api = api;
console.log('Profiles:', api.getAvailableProfiles());
}
onPrice(pricing: any) {
this.price = pricing.totalUsd;
}
}
```
## Module Declaration
```typescript
// app.module.ts
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { AppComponent } from './app.component';
import { WeddingBandBuilderComponent } from './wedding-band-builder.component';
@NgModule({
declarations: [AppComponent, WeddingBandBuilderComponent],
imports: [BrowserModule],
bootstrap: [AppComponent],
})
export class AppModule {}
```
---
# Svelte Integration: Complete Example
A Svelte component for the Wedding Band Builder.
[Back to Script Tag guide](../integration-direct)
## Component
```svelte
{#if price}
{/if}
```
## Usage
```svelte
${price.totalUsd.toFixed(2)}
{#each profiles as p}
{/each}
{#each materials as m}
{/each}
x{width.toFixed(2)}
{#if price}
${price.totalUsd.toFixed(2)}
{/if}
iJewel Drive asks for the layout when the project is created and stores it in
the manifest:
```json
{
"ui": {
"layout": "modern-metals",
"linkBands": false,
"theme": {
"preset": "dark",
"showRingToggle": false
}
}
}
```
For a self-hosted Modern Metals project, also define exactly one entry in
`defaults.bands`. Setting the layout name by itself changes presentation; it
does not delete extra bands from a hand-authored manifest.
Modern Metals organizes the single-ring workflow into **Style**, **Material**,
**Outside**, **Inside**, **Stones**, and **Engrave** tabs. Its Material tab shows
the base color, then Quality when the base has multiple variants, then only the
finishes supported by that material and variant.
The Outside tab has left, center, and right slots. The outer slots can be
floating inlays or rim-anchored overlays. The center slot is always an inlay.
The Inside tab controls the bore sleeve and inside polish. This focused layout
does not expose non-circular paths, design grooves, or edge controls, although
those controller APIs remain available to a custom interface.
At runtime, use `getAvailableLayouts()`, `getLayout()`, and `setLayout(id)`.
An unknown ID is rejected with a validation warning rather than rendering an
empty panel.
## Presets
11 built-in themes, applied with one line:
```javascript
api.setTheme('luxury-gold');
```
| Preset | Character |
|---|---|
| `default` | Clean, neutral. Works with any brand |
| `luxury-gold` | Warm gold accents, serif typography |
| `modern-minimal` | Monochrome, light, minimal chrome |
| `dark` | Dark background, light text, jeweler showcase feel |
| `rose-elegant` | Rose/blush tones, elegant serif fonts |
| `coral-modern` | Clean white with a coral-red accent, rounded sans-serif |
| `fresh-teal` | Light canvas with a calm teal accent, clean sans-serif |
| `minimal-blue` | Pure white, airy spacing, blue accent, system sans-serif |
| `warm-beige` | Warm beige tones with a muted blue selection accent |
| `classic-gold` | Dark-gold accent on white, gold-gradient ring toggle |
| `ijewel` | iJewel3D's own purple-accented brand styling |
To cycle through presets interactively:
```javascript
const nextTheme = api.cycleTheme();
console.log(`Now using: ${nextTheme}`);
```
## Custom Themes
Start from a preset and override specific properties:
```javascript
api.setTheme({
preset: 'modern-minimal',
colors: {
primary: '#2E5B3C',
background: '#F5F7F5',
},
fonts: {
body: "'Cormorant Garamond', serif",
googleFonts: ['Cormorant+Garamond:wght@400;500;600'],
},
panelWidth: 380,
});
```
Or build a theme from scratch without a preset base:
```javascript
api.setTheme({
colors: {
primary: '#8B6914',
primaryHover: '#A07D1C',
text: '#1a1a1a',
textMuted: '#666666',
background: '#FAFAF8',
surface: '#FFFFFF',
border: '#E0DDD8',
},
fonts: {
body: "'Inter', sans-serif",
headline: "'Playfair Display', serif",
googleFonts: ['Inter:wght@300;400;500', 'Playfair+Display:wght@400;700'],
},
shapes: {
borderRadius: 8,
},
});
```
## Colors
All color properties are optional. Unset values fall back to the preset (or `default` if no preset).
```typescript
interface ThemeColors {
primary?: string // Accent color (buttons, active states, sliders)
primaryHover?: string // Primary hover state
secondary?: string // Secondary accent
text?: string // Main text color
textMuted?: string // Secondary/hint text
textPlaceholder?: string // Placeholder text
background?: string // Page background
surface?: string // Card/panel background
surfaceHover?: string // Surface hover state
border?: string // Border color
borderLight?: string // Subtle borders
borderHover?: string // Border hover state
}
```
## Fonts
```typescript
interface ThemeFonts {
body?: string // Body text (e.g., "'Inter', sans-serif")
headline?: string // Section headings
light?: string // Light weight variant
googleFonts?: string[] // Google Fonts to load (e.g., ['Inter:wght@300;400;500'])
}
```
Google Fonts listed in the `googleFonts` array are automatically loaded via the Google Fonts API. No manual `` tags needed.
## UI Controls
| Property | Type | Default | Description |
|---|---|---|---|
| `panelWidth` | `number` | `340` | Width of the configuration panel in pixels |
| `showPoses` | `boolean` | `true` | Show camera angle buttons |
| `showARButton` | `boolean` | `true` | Show the AR try-on button |
| `showExportButton` | `boolean` | `true` | Show export/import buttons |
| `showRingToggle` | `boolean` | `true` | Show the His/Her band toggle |
| `initialTab` | `string` | - | Which tab to open by default |
```javascript
// Hide features you don't need
api.setTheme({
preset: 'dark',
showARButton: false,
showExportButton: false,
panelWidth: 360,
initialTab: 'material',
});
```
## Custom CSS
For fine-grained control, inject raw CSS:
```javascript
api.setTheme({
preset: 'modern-minimal',
customCSS: `
.wbb-root .field-label { text-transform: uppercase; letter-spacing: 0.05em; }
.wbb-root .pricing-total { font-size: 1.4em; }
`,
});
```
All custom CSS is scoped under `.wbb-root`, so it won't affect the rest of your page.
## CSS Custom Properties
The theme system injects CSS custom properties on the `.wbb-root` element. Use these in your own stylesheets to stay in sync with the active theme:
| Property | Maps to |
|---|---|
| `--rb-color-primary` | `colors.primary` |
| `--rb-color-primary-hover` | `colors.primaryHover` |
| `--rb-color-secondary` | `colors.secondary` |
| `--rb-color-text` | `colors.text` |
| `--rb-color-text-muted` | `colors.textMuted` |
| `--rb-color-background` | `colors.background` |
| `--rb-color-surface` | `colors.surface` |
| `--rb-color-border` | `colors.border` |
| `--rb-font-body` | `fonts.body` |
| `--rb-font-headline` | `fonts.headline` |
| `--rb-radius-md` | `shapes.borderRadius` |
```css
/* Example: style your own elements to match the configurator theme */
.my-price-display {
background: var(--rb-color-surface);
color: var(--rb-color-text);
border: 1px solid var(--rb-color-border);
font-family: var(--rb-font-body);
border-radius: var(--rb-radius-md);
}
```
## Full Type Reference
```typescript
interface UITheme {
preset?: ThemePresetName
colors?: ThemeColors
fonts?: ThemeFonts
shapes?: ThemeShapes
components?: ThemeComponentOverrides
customCSS?: string
panelWidth?: number
showPoses?: boolean
showARButton?: boolean
showExportButton?: boolean
showRingToggle?: boolean
initialTab?: string
}
type ThemePresetName =
| 'default'
| 'luxury-gold'
| 'modern-minimal'
| 'dark'
| 'rose-elegant'
| 'coral-modern'
| 'fresh-teal'
| 'minimal-blue'
| 'warm-beige'
| 'classic-gold'
| 'ijewel'
```
For the complete API, see [`setTheme()`](./api-reference#settheme-theme) in the API Reference.
---
# API Reference
Complete reference for the Wedding Band Builder API.
## Accessing the API
### Direct Integration (Same Page)
```javascript
window.addEventListener('ijewel-viewer-ready', (e) => {
const viewer = e.detail.viewer;
const api = viewer.getPluginByType('WeddingBandBuilder').controller;
api.setWidthMm(4.4);
});
```
### Same-Origin iframe
The iframe page fires `ijewel-viewer-ready` on its own `window`. That event does
not bubble to the parent page. Register a parent callback before the iframe
loads, then forward the viewer from a listener inside the iframe page.
Parent page:
```html
```
```javascript
window.handleWbbViewerReady = (viewer) => {
const api = viewer.getPluginByType('WeddingBandBuilder').controller;
api.setWidthMm(4.4);
};
const iframe = document.getElementById('wbb-iframe');
iframe.src = './wbb-viewer.html';
```
Inside `wbb-viewer.html`, register this listener before creating Mini Viewer:
```javascript
window.addEventListener('ijewel-viewer-ready', ({ detail }) => {
window.parent.handleWbbViewerReady?.(detail.viewer);
}, { once: true });
```
This direct callback requires both pages to use the same origin. You can also
use the postMessage protocol below for a same-origin iframe.
### Cross-Origin (PostMessage)
For iframes on a different domain:
```javascript
// Parent page sends to iframe
const viewerOrigin = 'https://ijewel3d.com';
iframe.contentWindow.postMessage({
id: 'req-1',
method: 'setWidthMm',
args: [4.4]
}, viewerOrigin);
// Listen for responses from iframe
window.addEventListener('message', (event) => {
if (event.source !== iframe.contentWindow) return;
if (event.origin !== viewerOrigin) return;
if (event.data.id === 'req-1') {
if (event.data.error) {
// Structured error: { message, source, details }
console.log(event.data.error.message);
} else {
console.log('Result:', event.data.result);
}
}
if (event.data.event) {
console.log('Event:', event.data.event, event.data.data);
}
});
```
Events (including `'log'` and `'error'`) are automatically forwarded from the iframe to the parent window.
## Read Methods
### `getSnapshot(bandName?)`
Returns a customer-facing summary snapshot for one band. It includes the
outside and inside features and each slot's base, variant and finish. Use
`toJSON()` when exact state restoration is required.
```javascript
const snapshot = api.getSnapshot('her');
```
**Parameters:**
| Name | Type | Default | Description |
|------|------|---------|-------------|
| `bandName` | `string` | active band | `'her'` or `'his'` |
**Returns:** [`RingSnapshot`](#ringsnapshot)
### `exportConfig()`
Exports one `RingSnapshot` summary for every band included in the project. This
is the readable record for a cart, an order line, or a manufacturer handoff.
```javascript
const config = api.exportConfig();
// { her: RingSnapshot, his: RingSnapshot }
```
**Returns:** `RecordWhat does the Wedding Band Builder cost?
The Wedding Band Builder is part of the iJewel3D platform. The pricing model is one-time onboarding plus an annual subscription. No per-change fees, no opaque project quotes. Contact [contact@ijewel3d.com](mailto:contact@ijewel3d.com) for a quote. See [License and Pricing](../introduction/license) for general iJewel3D pricing information.Which plan do I need?
Every plan includes the Wedding Band Builder, from Free upward. On any plan you can create a Wedding Band project and use the built-in profile library. **Custom profile upload** — your own `.3dm` cross sections — needs the **Silver** plan or above. On a lower plan, the upload option shows an upgrade prompt. A **whitelabel embed**, with the iJewel branding removed, needs the **Gold** plan or above. See [Whitelabeling and Branding](../integrations/whitelabeling).Do I need a developer to set it up?
**For the basic setup, no.** The project itself is created and configured on the iJewel3D platform, no code required ([Create a Project](./drive-setup)). You can then embed the Wedding Band Builder with a single ` ``` Without `camera` permission, the Try-On button can appear but the camera cannot start inside the iframe.What browsers are supported?
The Wedding Band Builder uses WebGL 2.0 through the iJewel3D engine and works in current desktop and mobile versions of Chrome, Edge, Firefox, and Safari. Camera Try-On does not use WebXR. It requires WebGL 2, camera access through `navigator.mediaDevices.getUserMedia`, and HTTPS. Device performance also matters. For custom controls, use `ij_vto.canRunVTO()` before showing the Try-On button: ```javascript const support = ij_vto.canRunVTO(); if (!support.ok) { console.warn("Try-On unavailable", support.reason, support.details); } ``` Test the exact devices and in-app browsers used by your customers instead of depending on a browser version number alone.How large is the viewer bundle?
The mini-viewer IIFE bundle (including the WebGI engine) is approximately 2-3 MB gzipped. Assets (profiles, PMAT materials, environment maps) are separate and load on demand after the viewer initializes. First-load time depends on your CDN and the number of assets in your manifest, but the viewer shell typically renders within 1-2 seconds.Is the ring geometry generated in real time or pre made?
Real time. The Wedding Band Builder uses a **parametric approach**: 2D profile curves are extruded along a circular path, materials are applied procedurally, and diamonds/edges/grooves are computed on the fly. Every combination produces a unique ring. There's no fixed catalog of 3D models.Does the configurator work offline?
No. The Wedding Band Builder requires an internet connection. The viewer bundle, 3D engine, profile curves, material files, and environment maps are all loaded from the CDN or your asset server. Without connectivity, the viewer cannot initialize. However, assets are cached by the browser after the first load. Subsequent visits on the same device load significantly faster because profiles, materials, and environment maps are served from the browser cache. The viewer bundle itself is also cached. If a customer loses connectivity mid-session, the ring they've already configured remains visible and interactive (rotation, zoom). Changes that require loading new assets (switching profiles or materials) will fail until connectivity is restored.The viewer is blank / not loading. What do I check?
1. **Script loaded?** Check the browser console for 404 errors on the mini-viewer bundle. 2. **Container has dimensions?** The viewer fills its container. If the container has `0` height, nothing renders. Give it explicit dimensions (e.g., `height: 600px`). 3. **Manifest accessible?** The `manifestUrl` must be reachable from the browser. Check the Network tab for failed fetches. 4. **CORS?** If your assets are on a different domain, make sure the server sends `Access-Control-Allow-Origin` headers. 5. **Console errors?** Check for JavaScript errors. The `error` event also fires if something goes wrong after initialization: ```javascript api.events.on('error', (err) => console.error(err)); ```How do I track what customers are configuring?
Listen to change events and send them to your analytics platform: ```javascript // Track profile changes api.events.on('profile:changed', (data) => { analytics.track('ring_profile_changed', { band: data.bandName, profile: data.profileName, }); }); // Track material changes api.events.on('material:changed', (data) => { analytics.track('ring_material_changed', { band: data.bandName, metal: data.metal, finish: data.finish, }); }); // Track price views api.events.on('price:updated', (data) => { analytics.track('ring_price_viewed', { band: data.bandName, total: data.pricing.totalUsd, }); }); ``` This works with any analytics provider (Google Analytics, Segment, Mixpanel, etc.).How do I handle version updates?
The viewer bundle is versioned. Pin to a specific version in your script tag or iframe URL to avoid unexpected changes: ```html ``` The Wedding Band SDK guides pin the release pair that was verified end to end. Check the [Changelog](../viewer/viewer-changelog) before upgrading. The Wedding Band iframe lifecycle fixes require Mini Viewer `0.6.11` or newer. Material variants, the outside and inside material features, and the Modern Metals layout require `0.6.17` or newer. Ring Configurator and Wedding Band Builder Try-On require `0.6.18` or newer.Validates an active internet connection. This is critical because iJewel Viewer pulls a rich library of assets from the cloud, including:
* Photorealistic material definitions (metals, diamonds, gemstones)
* HDR lighting environments
* 3D asset templates
* Texture maps and surface details
This ensures that every designer has access to the most updated visual assets.
2. ##### Local File Server Initialization and Model Observervation
The plugin starts a lightweight local file server to serves 3D model data to web clients.This enables Rhino’s 3D model data to be seamlessly streamed into the iJewel Viewer without manual exporting. ```csharp protected void StartFileServer() { if (IsPortInUse(Port)) return; _listener = new HttpListener(); _listener.Prefixes.Add($"http://localhost:{Port}/"); _listener.Start(); _serverThread = new Thread(() => ServerUtility.ServerThreadStart(_listener, _cancellationTokenSource.Token)); _serverThread.Start(); } ``` Alongside this, the `RhinoModelObserver` class continuously monitors model changes:
* Model creation, deletion, or modification
* Layer hiding or reassignment
* Material and object property changes
* Transformation changes
Every update is instantly reflected in the iJewel Viewer, ensuring what the designer sees is always accurate and up to date. The `RhinoModelObserver` class tracks the above model changes. This ensures that any changes to the 3D model are automatically detected and can trigger re-exports or notifications to connected iJewel Viewer. ```csharp public sealed class RhinoModelObserver { private RhinoModelObserver() { RhinoDoc.AddRhinoObject += (s, e) => MarkChanged(); RhinoDoc.DeleteRhinoObject += (s, e) => MarkChanged(); RhinoDoc.ReplaceRhinoObject += (s, e) => MarkChanged(); // Additional event handlers... } } ``` 3. ##### Launching iJewelViewer in Browser or Embedded Window Finally, the plugin launches the iJewel Viewer, either in:
* The user’s default web browser, or
* An embedded in-app web view
```csharp string uri = "https://ijewel.design/rhinoceros"; if (Rhino.Runtime.HostUtils.RunningOnOSX) { if (!BrowserLauncher.LaunchBrowserInMac(uri)) { //launch webview if none of the supported browsers are available on mac var webViewForm = new WebViewForm(uri); webViewForm.Show(); } } else { //use webview directly on windows var webViewForm = new WebViewForm(uri); webViewForm.Show(); } ``` * On macOS, it attempts to launch specific browsers (Chrome, Firefox, Opera) before falling back to an embedded WebView. * On Windows, the embedded WebView is the default. ::: tip * You can replace the uri "https://ijewel.design/rhinoceros", with "https://ijewel.design/rhinoceros?rhino" to ensure that the iJewel Viewer will listen to any model changes made in your CAD software. * To Launch [iJewel Playground](https://playground.ijewel3d.com/v2/index.html), change the uri to "https://playground.ijewel3d.com/v2/index.html" ::: ### Source Code Access You can fork the github repo to get access to the complete source code - [Here](https://github.com/ijewel3d/ijewel-rhino). --- # Changelog for iJewel Rhino Plugin ## [0.2.5] - 2025-12-11 ### Added - `iJewelPlatform` command to launch the viewer in ijewel3d.com. - `iJewelEnterprise` command to launch the viewer in any ijewel3d organization. ### Changed - Reverted `iJewelPlayground` command to launch Playground V2. --- # iJewel Partner Program  iJewel3D partners with developers, designers, and agencies to create custom AR applications, configurators, and viewers. We provide tools, support, and resources to help partners build and deploy high-quality experiences for their clients. We also partner with resellers and local distributors to provide iJewel3D products in different regions. This includes training, support, and marketing resources to help partners grow. ::: tip Interested in becoming a partner? Learn about our partner program and get in touch — [Become a Partner](./become-a-partner) ::: ## Technical Partners
Software development company focused on 3D jewelry experiences. The team develops 3D viewers and configurators based on the iJewel3D API. Hundreds of retailers and vendors trust Thinkspace to increase customer engagement and drive jewelry sales through branded and custom experiences.
Services
3D model creation & optimization
Viewers & configurators (iJewel SDK)
E-commerce platform integration
Portfolio
Coming soon
Jewelry technology platform enabling businesses to sell online and offline through specialized B2B and B2C applications. VDB provides wholesale tools, retail solutions, marketplace integrations, and 3D jewelry customization — connecting retailers, suppliers, and consumers across the diamond, lab-grown diamond, and gemstone markets. Trusted by over 30,000 jewelry trade professionals.
Services
B2B wholesale tools & marketplace
B2C retail apps & websites
Shopify & WooCommerce integrations
3D jewelry configurators (Ring Creator)
In-store Sales Genie app
API & webhook integrations
CRM/ERP integrations
Portfolio
Bespoke XR and real-time 3D company leveraging spatial computing to merge the physical and digital worlds. Founded in 2012 with roots in LEGO R&D and early AR innovation, VZ777 creates high-fidelity interactive solutions for enterprise clients across automotive, luxury, industrial, and real estate sectors.
Services
Real-time 3D visualizers
Configurators
Bespoke XR applications
R&D and innovation consulting
Portfolio
Coming soon
Trendsetting B2B provider of advanced 3D CAD and product configurator solutions for the jewelry industry. As a strategic iJewel3D partner, the team leverages iJewel APIs and SDKs to deliver precision engineered services for jewelry manufacturing and customization.
Services
3D jewelry configurators (iJewel SDK)
CAD visual engineering
Photorealistic 3D visuals
Product catalogue creation
Website development
Portfolio
Coming soon
Led by luxury jewelry expert Anja Hermanns with 25+ years in high-end jewelry, retail strategy, and brand development. As an official iJewel partner, Alloyum creates customized configurator solutions reflecting each brand's philosophy and emotional identity, with integration guidance, consulting, and team training.
Services
Custom configurator solutions
Integration consulting
Team training & adoption
Premium visual storytelling
Portfolio
Coming soon
Technology and digital execution partner specializing in eCommerce, 3D visualization (using iJewel API), automation, and AI led operational workflows. Ole helps brands build scalable digital platforms, product experiences, and backend systems that improve customer engagement, operational efficiency, and online sales. Strong experience in jewelry, product visualization, Shopify, and automation led business transformation.
Services
3D viewers & configurators
Shopify / Shopify Plus
E-commerce development
Supply chain activation
Catalog management
AI & workflow automation
Portfolio
Global technology company specializing in digital transformation solutions for the jewelry industry. Serving clients across the US, Europe, UK, Australia, Africa, and India, AMG Dynamics combines deep jewelry expertise with cutting edge technology to help businesses scale, automate, and innovate. Also the creator of The Goldsmith AI, the world's first AI platform built specifically for the jewelry industry.
Services
E-commerce website development
Jewelry configurators & 3D viewers
API integrations & enterprise systems
AI & machine learning solutions
Factory & workflow automation
Custom software development
Digital catalog & inventory management
Portfolio
Coming soon
Internationally trusted, award winning custom jewelry CAD studio. Since 2013, the team has completed over 20,000 bespoke jewelry projects for jewelers, designers, and manufacturers worldwide. Expertise includes intricate, technically refined, and organic CAD models that combine artistry with manufacturability. Models integrate seamlessly into the iJewel workflow.
Services
Custom CAD design
Rendering & animation
GLB file preparation for iJewel
Portfolio
Technology and digital execution partner specializing in eCommerce, 3D visualization (using iJewel API), automation, and AI led operational workflows. Ole helps brands build scalable digital platforms, product experiences, and backend systems that improve customer engagement, operational efficiency, and online sales. Strong experience in jewelry, product visualization, Shopify, and automation led business transformation.
Services
3D model creation & rendering
Product image enhancement
Photorealistic rendering
3D viewers & configurators
Portfolio
Brazilian studio specialized in technical jewelry development and CAD engineering. Focuses on manufacturing oriented CAD modeling combining structural precision, stone setting reliability, and production efficiency. The workflow combines engineering logic with aesthetic refinement, supporting jewelry brands and manufacturers in transforming concepts into production ready pieces.
Services
Jewelry CAD (Rhino & ZBrush)
Manufacturing ready files
Structural optimization
Stone setting analysis
GLB preparation for iJewel
Portfolio
Coming soon
Software development company focused on 3D jewelry experiences. The team develops 3D viewers and configurators based on the iJewel3D API. Hundreds of retailers and vendors trust Thinkspace to increase customer engagement and drive jewelry sales through branded and custom experiences.
Services
3D model creation & optimization
Viewers & configurators (iJewel SDK)
E-commerce platform integration
Portfolio
Coming soon
Global technology company specializing in digital transformation solutions for the jewelry industry. Serving clients across the US, Europe, UK, Australia, Africa, and India, AMG Dynamics combines deep jewelry expertise with cutting edge technology to help businesses scale, automate, and innovate. Also the creator of The Goldsmith AI, the world's first AI platform built specifically for the jewelry industry.
Services
Rendering & product visualization
Jewelry photography solutions
Jewelry configurators & 3D viewers
Digital catalog & inventory management
Portfolio
Coming soon
You can also join our [Discord community](https://discord.com/invite/apzU8rUWxY) to connect with the team and other partners. --- # Frequently Asked Questions (FAQs) This page contains answers to common questions about iJewel3D products and features. ::: details How do I preserve user data strings when importing 3DM files? By default, when importing 3DM files, iJewel3D ignores user data strings that may have been defined by some people or plugins, this helps reduce the file size and improve the loading performance. However, you can choose to keep them if needed. If you're using iJewel3D.com, follow these steps when uploading a file: 1. Upload your 3DM file to iJewel3D 2. In the upload options popup, navigate to **Advanced Settings** 3. Under **3DM Options**, you'll find a checkbox labeled **Load User Data Strings** 4. Switch it **ON** to preserve the user data strings from your 3DM file This option allows you to retain any custom metadata or information stored in the user data strings of your 3DM files. Alternatively, if you're using the Playground, on the right side menu, under **Plugins** >> **Rhino 3dm Loader**, you'll find an option called **LoadUserDataString**. Switch it on before dropping your 3DM file to load the file with user data strings preserved. ::: --- Privacy Policy ============== Last updated: June 27, 2024 This Privacy Policy describes Our policies and procedures on the collection, use and disclosure of Your information when You use the Service and tells You about Your privacy rights and how the law protects You. We use Your Personal data to provide and improve the Service. By using the Service, You agree to the collection and use of information in accordance with this Privacy Policy. Interpretation and Definitions ------------------------------ ### Interpretation The words of which the initial letter is capitalized have meanings defined under the following conditions. The following definitions shall have the same meaning regardless of whether they appear in singular or in plural. ### Definitions For the purposes of this Privacy Policy: * **Account** means a unique account created for You to access our Service or parts of our Service. * **Affiliate** means an entity that controls, is controlled by or is under common control with a party, where "control" means ownership of 50% or more of the shares, equity interest or other securities entitled to vote for election of directors or other managing authority. * **Company** (referred to as either "the Company", "We", "Us" or "Our" in this Agreement) refers to iJewel 3d, 160 Robinson Road, #14-04 Singapore Business Federation Center, Singapore (068914). * **Cookies** are small files that are placed on Your computer, mobile device or any other device by a website, containing the details of Your browsing history on that website among its many uses. * **Country** refers to: Singapore * **Device** means any device that can access the Service such as a computer, a cellphone or a digital tablet. * **Personal Data** is any information that relates to an identified or identifiable individual. * **Service** refers to the Website. * **Service Provider** means any natural or legal person who processes the data on behalf of the Company. It refers to third-party companies or individuals employed by the Company to facilitate the Service, to provide the Service on behalf of the Company, to perform services related to the Service or to assist the Company in analyzing how the Service is used. * **Usage Data** refers to data collected automatically, either generated by the use of the Service or from the Service infrastructure itself (for example, the duration of a page visit). * **Website** refers to iJewel3D including all subdomains, accessible from [https://ijewel3d.com/](https://ijewel3d.com/) * **You** means the individual accessing or using the Service, or the company, or other legal entity on behalf of which such individual is accessing or using the Service, as applicable. Collecting and Using Your Personal Data --------------------------------------- ### Types of Data Collected #### Personal Data While using Our Service, We may ask You to provide Us with certain personally identifiable information that can be used to contact or identify You. Personally identifiable information may include, but is not limited to: * Email address * First name and last name * Usage Data #### Usage Data Usage Data is collected automatically when using the Service. Usage Data may include information such as Your Device's Internet Protocol address (e.g. IP address), browser type, browser version, the pages of our Service that You visit, the time and date of Your visit, the time spent on those pages, unique device identifiers and other diagnostic data. When You access the Service by or through a mobile device, We may collect certain information automatically, including, but not limited to, the type of mobile device You use, Your mobile device unique ID, the IP address of Your mobile device, Your mobile operating system, the type of mobile Internet browser You use, unique device identifiers and other diagnostic data. We may also collect information that Your browser sends whenever You visit our Service or when You access the Service by or through a mobile device. #### Tracking Technologies and Cookies We use Cookies and similar tracking technologies to track the activity on Our Service and store certain information. Tracking technologies used are beacons, tags, and scripts to collect and track information and to improve and analyze Our Service. The technologies We use may include: * **Cookies or Browser Cookies.** A cookie is a small file placed on Your Device. You can instruct Your browser to refuse all Cookies or to indicate when a Cookie is being sent. However, if You do not accept Cookies, You may not be able to use some parts of our Service. Unless you have adjusted Your browser setting so that it will refuse Cookies, our Service may use Cookies. * **Web Beacons.** Certain sections of our Service and our emails may contain small electronic files known as web beacons (also referred to as clear gifs, pixel tags, and single-pixel gifs) that permit the Company, for example, to count users who have visited those pages or opened an email and for other related website statistics (for example, recording the popularity of a certain section and verifying system and server integrity). Cookies can be "Persistent" or "Session" Cookies. Persistent Cookies remain on Your personal computer or mobile device when You go offline, while Session Cookies are deleted as soon as You close Your web browser. You can learn more about cookies on [TermsFeed website](https://www.termsfeed.com/blog/cookies/#What_Are_Cookies) article. We use both Session and Persistent Cookies for the purposes set out below: * **Necessary / Essential Cookies** Type: Session Cookies Administered by: Us Purpose: These Cookies are essential to provide You with services available through the Website and to enable You to use some of its features. They help to authenticate users and prevent fraudulent use of user accounts. Without these Cookies, the services that You have asked for cannot be provided, and We only use these Cookies to provide You with those services. * **Cookies Policy / Notice Acceptance Cookies** Type: Persistent Cookies Administered by: Us Purpose: These Cookies identify if users have accepted the use of cookies on the Website. * **Functionality Cookies** Type: Persistent Cookies Administered by: Us Purpose: These Cookies allow us to remember choices You make when You use the Website, such as remembering your login details or language preference. The purpose of these Cookies is to provide You with a more personal experience and to avoid You having to re-enter your preferences every time You use the Website. For more information about the cookies we use and your choices regarding cookies, please visit our Cookies Policy or the Cookies section of our Privacy Policy. ### Use of Your Personal Data The Company may use Personal Data for the following purposes: * **To provide and maintain our Service**, including to monitor the usage of our Service. * **To manage Your Account:** to manage Your registration as a user of the Service. The Personal Data You provide can give You access to different functionalities of the Service that are available to You as a registered user. * **For the performance of a contract:** the development, compliance and undertaking of the purchase contract for the products, items or services You have purchased or of any other contract with Us through the Service. * **To contact You:** To contact You by email, telephone calls, SMS, or other equivalent forms of electronic communication, such as a mobile application's push notifications regarding updates or informative communications related to the functionalities, products or contracted services, including the security updates, when necessary or reasonable for their implementation. * **To provide You** with news, special offers and general information about other goods, services and events which we offer that are similar to those that you have already purchased or enquired about unless You have opted not to receive such information. * **To manage Your requests:** To attend and manage Your requests to Us. * **For business transfers:** We may use Your information to evaluate or conduct a merger, divestiture, restructuring, reorganization, dissolution, or other sale or transfer of some or all of Our assets, whether as a going concern or as part of bankruptcy, liquidation, or similar proceeding, in which Personal Data held by Us about our Service users is among the assets transferred. * **For other purposes**: We may use Your information for other purposes, such as data analysis, identifying usage trends, determining the effectiveness of our promotional campaigns and to evaluate and improve our Service, products, services, marketing and your experience. We may share Your personal information in the following situations: * **With Service Providers:** We may share Your personal information with Service Providers to monitor and analyze the use of our Service, to contact You. * **For business transfers:** We may share or transfer Your personal information in connection with, or during negotiations of, any merger, sale of Company assets, financing, or acquisition of all or a portion of Our business to another company. * **With Affiliates:** We may share Your information with Our affiliates, in which case we will require those affiliates to honor this Privacy Policy. Affiliates include Our parent company and any other subsidiaries, joint venture partners or other companies that We control or that are under common control with Us. * **With business partners:** We may share Your information with Our business partners to offer You certain products, services or promotions. * **With other users:** when You share personal information or otherwise interact in the public areas with other users, such information may be viewed by all users and may be publicly distributed outside. * **With Your consent**: We may disclose Your personal information for any other purpose with Your consent. ### Retention of Your Personal Data The Company will retain Your Personal Data only for as long as is necessary for the purposes set out in this Privacy Policy. We will retain and use Your Personal Data to the extent necessary to comply with our legal obligations (for example, if we are required to retain your data to comply with applicable laws), resolve disputes, and enforce our legal agreements and policies. The Company will also retain Usage Data for internal analysis purposes. Usage Data is generally retained for a shorter period of time, except when this data is used to strengthen the security or to improve the functionality of Our Service, or We are legally obligated to retain this data for longer time periods. ### Transfer of Your Personal Data Your information, including Personal Data, is processed at the Company's operating offices and in any other places where the parties involved in the processing are located. It means that this information may be transferred to — and maintained on — computers located outside of Your state, province, country or other governmental jurisdiction where the data protection laws may differ than those from Your jurisdiction. Your consent to this Privacy Policy followed by Your submission of such information represents Your agreement to that transfer. The Company will take all steps reasonably necessary to ensure that Your data is treated securely and in accordance with this Privacy Policy and no transfer of Your Personal Data will take place to an organization or a country unless there are adequate controls in place including the security of Your data and other personal information. ### Delete Your Personal Data You have the right to delete or request that We assist in deleting the Personal Data that We have collected about You. Our Service may give You the ability to delete certain information about You from within the Service. You may update, amend, or delete Your information at any time by signing in to Your Account, if you have one, and visiting the account settings section that allows you to manage Your personal information. You may also contact Us to request access to, correct, or delete any personal information that You have provided to Us. Please note, however, that We may need to retain certain information when we have a legal obligation or lawful basis to do so. ### Disclosure of Your Personal Data #### Business Transactions If the Company is involved in a merger, acquisition or asset sale, Your Personal Data may be transferred. We will provide notice before Your Personal Data is transferred and becomes subject to a different Privacy Policy. #### Law enforcement Under certain circumstances, the Company may be required to disclose Your Personal Data if required to do so by law or in response to valid requests by public authorities (e.g. a court or a government agency). #### Other legal requirements The Company may disclose Your Personal Data in the good faith belief that such action is necessary to: * Comply with a legal obligation * Protect and defend the rights or property of the Company * Prevent or investigate possible wrongdoing in connection with the Service * Protect the personal safety of Users of the Service or the public * Protect against legal liability ### Security of Your Personal Data The security of Your Personal Data is important to Us, but remember that no method of transmission over the Internet, or method of electronic storage is 100% secure. While We strive to use commercially acceptable means to protect Your Personal Data, We cannot guarantee its absolute security. If We need to rely on consent as a legal basis for processing Your information and Your country requires consent from a parent, We may require Your parent's consent before We collect and use that information. Links to Other Websites ----------------------- Our Service may contain links to other websites that are not operated by Us. If You click on a third party link, You will be directed to that third party's site. We strongly advise You to review the Privacy Policy of every site You visit. We have no control over and assume no responsibility for the content, privacy policies or practices of any third party sites or services. Changes to this Privacy Policy ------------------------------ We may update Our Privacy Policy from time to time. We will notify You of any changes by posting the new Privacy Policy on this page. We will let You know via email and/or a prominent notice on Our Service, prior to the change becoming effective and update the "Last updated" date at the top of this Privacy Policy. You are advised to review this Privacy Policy periodically for any changes. Changes to this Privacy Policy are effective when they are posted on this page. Contact Us ---------- If you have any questions about this Privacy Policy, You can contact us: * By email: [contact@ijewel3d.com](mailto:contact@ijewel3d.com) * By visiting this page on our website: [https://www.ijewel3d.com/contact](https://www.ijewel3d.com/contact) --- # iJewel3D Developer Terms of Use Last updated: June 21, 2024 Check out the details in the [License](./introduction/license) section. --- Join our [discord](https://discord.com/invite/apzU8rUWxY), and share your feedback, ask questions, showcase your work and more. You can also email us at [contact@ijewel3d.com](mailto:contact@ijewel3d.com) or [Book a demo/meeting](https://ijewel3d.zohobookings.in/#/209816000000031082) with our sales team. ---