@3d-viewer/core

The framework-agnostic 3D rendering and customization engine for luxury jewelry and precision products, powered by Three.js and custom GLSL diamond raytracing shaders.

Features

• 💎 Photorealistic Diamond Raytracing — Spectral dispersion (RGB chromatic splitting), 5-bounce internal reflections, and facet normal baking with zero runtime CPU cost.
• 🥇 PBR Precious Metals — Realistic 14K/18K Yellow, White, Rose Gold, Platinum 950, Silver 925, and Black Ruthenium with accurate Fresnel reflectance and roughness.
• 📐 Automated Jewelry Part Detection — Heuristically categorizes meshes into metal, diamond, and gemstone parts upon loading.
• 🌐 HDR Studio Environment Lighting — Integrated PMREM generation for high-dynamic-range reflections and diamond sparkle.
• 📦 Universal Model Support — Loads .glb, .gltf with Draco compression and meshopt support out of the box.
• ⚡ Framework Agnostic — Zero dependency on React, Angular, or Vue; works in vanilla JS, Node/SSR, and any web application.

Installation

npm install @3d-viewer/core three
# or with pnpm
pnpm add @3d-viewer/core three

Peer Dependency: Requires three >= 0.150.0.

Quickstart

import { createViewer, ALL_METAL_PRESETS, DIAMOND_PRESETS } from '@3d-viewer/core'

// 1. Initialize viewer container
const container = document.getElementById('viewer-container')!
const viewer = createViewer(container, {
  autoRotate: true,
  environment: 'studio-neutral',
})

// 2. Load 3D jewelry model
await viewer.loadModel('https://cdn.example.com/models/solitaire-ring.glb')

// 3. Customize materials
viewer.setMetal('yellow-gold-18k')
viewer.setStone('diamond-colorless')

// 4. Listen to events
viewer.on('loaded', (info) => {
  console.log('Model loaded! Detected parts:', info.parts)
})

viewer.on('metalChanged', (metalId) => {
  console.log('Active metal:', metalId)
})

Preset Catalogs

Metals (ALL_METAL_PRESETS)

• yellow-gold-18k, yellow-gold-14k
• white-gold-18k, white-gold-14k
• rose-gold-18k, rose-gold-14k
• platinum-950
• silver-925
• black-ruthenium

Gemstones & Diamonds (ALL_STONE_PRESETS)

• diamond-colorless (D/E/F Grade)
• diamond-warm (G/H Grade)
• diamond-canary (Fancy Yellow)
• diamond-pink (Fancy Pink)
• diamond-blue (Fancy Blue)
• emerald, ruby, sapphire

API Reference

createViewer(container: HTMLElement, options?: ViewerOptions): Viewer

Creates and mounts a WebGL viewer instance.

Viewer Methods:

• loadModel(urlOrBuffer: string | ArrayBuffer): Promise<void>
• setMetal(metalId: string): void
• setStone(stoneId: string): void
• setAutoRotate(enabled: boolean): void
• resetCamera(): void
• screenshot(options?: { mimeType?: string, quality?: number }): Promise<string>
• dispose(): void

License

MIT