lumiere-gem

Real-time refractive + dispersive gem shader for three.js. Renders diamonds, moissanite, emerald, ruby and sapphire with true internal ray bouncing — not a transmission approximation.

Runs in the browser and on-device in React Native via expo-gl.

npm install lumiere-gem three

License: PolyForm Noncommercial 1.0.0. Free for personal, hobby, educational and research use. Commercial use requires a separate license — reach out at jeanrojas.com.

Why not MeshPhysicalMaterial?

transmission + ior gives you a glass ball. A cut gem's entire look comes from light entering a facet, bouncing several times off the internal facet walls under total internal reflection, and leaving through a different facet — with each wavelength taking a slightly different path.

This package models that directly:

• Cubemap-baked surface representation. Each geometry is baked once into a 256²×6 half-float cubemap storing per-direction surface normal (RGB) and radial distance (alpha). The ray march then resolves real facet hits without a BVH.
• Two-pass facet refinement. An ellipsoid intersection seeds the search, then two rounds of cubemap-lookup + plane-refine land the ray on the actual facet. The ellipsoid is fitted to the bounding box, so ovals and marquise cuts converge instead of clustering as round brilliants.
• Per-channel dispersion. Three IORs (R/G/B, separated by rIndexDelta) traced independently — this is what produces "fire".
• Beer-Lambert absorption for colored stones, plus a GGX environment specular and Fresnel term on the outer surface.

Geometry is CPU-flat-shaded before baking using the geometric face normal, oriented against the bounding-box center — so welded CAD exports with inconsistent winding render as crisp facets rather than smooth blobs.

Usage

import * as THREE from "three";
import { createGemMaterial, updateGemMatrix, clearGemCache } from "lumiere-gem";

// envMap is an equirectangular THREE.Texture (an HDR/EXR works well).
const material = createGemMaterial(
  mesh.geometry,
  envMap,
  renderer,
  {
    color: "#ffffff",
    refractiveIndex: 2.42,   // diamond
    rIndexDelta: 0.013,      // dispersion spread
    absorptionFactor: 0.6,
    environmentIntensity: 0.95,
    reflectivity: 0.55,
    bounces: 5,
  },
  mesh,
  "Gem 01", // bake key — see below
);

if (material) mesh.material = material;

The material refreshes its own model matrix in onBeforeRender, so animated or re-parented meshes need no extra work. Call updateGemMatrix(material, mesh) yourself only if you bypass that path.

The bake key matters

Baking is keyed, and choosing the key well is the difference between a correct render and a slow, inconsistent one:

createGemMaterial(geometry, envMap, renderer, opts, mesh, "Gem 01");

Every mesh passing the same key shares one cubemap bake. Use the material slot name from your GLB. If artists baked per-instance rotation into vertex positions — common in jewelry CAD exports — per-instance baking makes the left and right stones of a paired setting look visibly different. One bake per cut fixes that and costs one bake instead of N.

Omit the key and the bake falls back to a content-derived signature, which still dedupes geometries that happen to be identical.

Cleaning up

clearGemCache() disposes every baked cube texture. Call it when your scene tears down — otherwise bakes leak GPU textures across scene switches.

useEffect(() => () => clearGemCache(), []);

Options

| Option | Default | What it does | |---|---|---| | color | #ffffff | Base stone tint | | refractiveIndex | 2.4 | IOR. Diamond 2.42, moissanite 2.65, CZ 2.16, sapphire 1.77, ruby 1.76, emerald 1.58 | | rIndexDelta | 0.012 | R↔B IOR spread. Higher = more fire | | absorptionFactor | 1.0 | Beer-Lambert strength. ~0.6 for white stones, ~3.0 for colored | | environmentIntensity | 1.0 | Environment map contribution | | reflectivity | 0.5 | Outer-surface specular strength | | bounces | 5 | Internal ray bounces, clamped 1–7. Cost scales with this | | boostFactors | [1,1,1] | Per-channel output gain | | colorCorrection | [1,1,1] | Per-channel post-tint | | gammaFactor | 1.0 | Output gamma | | squashFactor | 1.0 | Per-cut vertical squash | | geometryFactor | 0.5 | Per-cut geometry blend | | centerOffset | [0,0,0] | Optical-center offset for non-centered cuts (pear, heart) |

Requirements

• three ≥ 0.160 (peer dependency)
• A WebGLRenderer — the bake needs render-to-cubemap
• Half-float render target support (universal on modern targets; on WebGL1 it needs OES_texture_half_float)

Performance

The bake is the expensive part and it happens once per key, synchronously, on first material creation. Budget for a frame hitch when a new cut first appears, or warm the cache during a loading state.

Per-frame cost scales with bounces — 5 is the visual sweet spot; 3 is noticeably cheaper on older mobile GPUs.

License

PolyForm Noncommercial 1.0.0 — free for noncommercial use.

Commercial licenses available: jeanrojas.com

Required Notice: Copyright 2026 Jean Rojas (https://jeanrojas.com)