A lightweight, high-precision Three.js GLB/glTF 3D artifact and model viewer for React. Built for cultural heritage, numismatics, archaeology, and scientific inspection, featuring 3-tier physical scale calibration, a collapsible zebra photoscale bar with universal reference object silhouettes, portable 3D spatial annotations with guided tours, point-to-point surface measurements, glTF animation playback, cross-section slicing, raking studio lighting, and multi-format mesh exports.
The models in the demo include the Head and Shoulders of a Sphinx of Hatshepsut, a 3D scan made on holiday in New York (Met Museum collection record), an animated model of A'a scanned by Thomas Flynn at the British Museum, and a scan of the Caryatids from the Acropolis of Athens.
- 3-Tier Scale Calibration:
- Catalog Auto-Scale: Pass
knownMaxDimensionMmfrom your database record to normalize the bounding box's longest axis automatically. - Metric Sanity Check: Converts standard glTF meter units to millimeters (
defaultUnitScale={1000}) while automatically flagging implausible dimensions as unscaled. - Interactive 2-Point Calibration: Click any two reference points on a scale bar or known feature and enter the real-world millimeter distance to calibrate unscaled photogrammetry meshes on the fly.
- Catalog Auto-Scale: Pass
- Portable 3D Spatial Annotations & Guided Tour:
- Backend-Agnostic Schema & W3C / IIIF 3D Support: Accepts either native portable annotation JSON or standard W3C Web Annotation / IIIF 3D
PointSelectorpayloads, with built-in bidirectional adapters (toW3CWebAnnotations,encodeAnnotationsHash,decodeAnnotationsHash). - Controlled or Uncontrolled Modes: Works zero-backend with
defaultAnnotationsor integrates with REST/GraphQL/Laravel APIs viaannotationsandonCreateAnnotation/onUpdateAnnotation/onDeleteAnnotationcallbacks. - Surface Normal Occlusion & Camera Fly-To: Automatically fades pins facing away from the camera, smoothly tweens to saved curatorial camera viewpoints, and provides a
< 1 / N >guided tour stepper bar.
- Backend-Agnostic Schema & W3C / IIIF 3D Support: Accepts either native portable annotation JSON or standard W3C Web Annotation / IIIF 3D
- Zebra Photoscale & Reference Object Silhouettes: A high-contrast 4-segment archaeological scale bar that automatically adapts to zoom level and metric/imperial units (
mm,cm,in), paired with a collapsible comparison drawer featuring true-to-scale silhouettes (AA Cell, Tennis Ball, 330ml Can, and A4 Sheet). - Point-to-Point Surface Measurements: BVH-accelerated (
three-mesh-bvh) 3D surface raycasting for instant point placement even on dense, multi-million-triangle scans, complete with projected 2D distance badges (mm,cm, andin). - glTF Keyframe Animation Timeline: Automatically mounts a responsive playback bar whenever a
.glb/.gltfcontains embedded animations, supporting play/pause, clip selection, timeline scrubbing, and playback speed cycling (0.5×,1×,2×). - Diagnostic Shading & Studio IBL Lighting: Switch between PBR (lit by Three.js
RoomEnvironmentImage-Based Lighting with adjustable Env intensity, Exposure, and raking Light angle), Relief (screen-space normal curvature shader for faint inscriptions and tool marks), Clay (Matcap raking relief), Normals, and Vertex Colors, plus Wireframe overlay. - Draco & KTX2 Compression Support: Built-in
DRACOLoaderandKTX2Loaderconfiguration with sensible CDN defaults and customizable decoder paths. - Cross-Section Slicer: Interactive X, Y, and Z clipping planes (
0%–100%) with a translucent slice plane indicator. - Scoped Light & Dark UI Themes: Toggle between frosted Light and Dark HUD themes independently of the host page (
initialTheme="dark"or"light"), with all CSS scoped under.gmv-root. - Modular & Composable: Toggle individual toolbars, panels, and features on or off via boolean props, or import standalone HUD sub-components (
ScaleBarOverlay,AnnotationOverlay,AnimationTimeline,TelemetryDrawer, etc.) directly. - Multi-Format Exports: Download the original
.glb, convert in-browser to.objor binary 3D-print-ready.stl, capture.pngviewport renders, or record a 5-second 360° turntable.webmclip. - Accessible & Memory-Safe: Full keyboard navigation (orbit, pan, zoom, and tool shortcuts), ARIA roles/live regions, and strict WebGL geometry, texture, BVH, and context disposal on unmount.
Install the package alongside its peer dependencies (react, react-dom, and three >=0.163.0):
npm install @micropasts/glb-model-viewer threeImport both ModelViewer and its bundled stylesheet (@micropasts/glb-model-viewer/style.css). Wrap the component in a container with an explicit width and height:
import React from 'react';
import { ModelViewer } from '@micropasts/glb-model-viewer';
import '@micropasts/glb-model-viewer/style.css';
export default function ArtifactPage() {
return (
<div style={{ width: '100%', height: '650px' }}>
<ModelViewer
modelUrl="/models/hatshepsut.glb"
title="Head and Shoulders of a Sphinx of Hatshepsut"
subtitle="Indurated Limestone • New Kingdom, Dynasty 18 (ca. 1479–1458 B.C.)"
badge="GLB"
fileName="hatshepsut_sphinx.glb"
fileSize="8.4 MB"
knownMaxDimensionMm={520}
initialTheme="dark"
onLoad={(stats) => {
console.log('Loaded mesh stats:', stats);
}}
onCalibrate={({ scaleFactor, targetMm }) => {
console.log(`Calibrated to ${targetMm} mm (factor: ${scaleFactor})`);
}}
/>
</div>
);
}Important:
ModelViewerfills100%of its parent container (width: 100%; height: 100%). Always give the wrapping<div>an explicit height (such asheight: 100vh,height: 600px, or Tailwind'sh-[80vh]), otherwise the WebGL canvas will collapse to0px.
Every UI panel and interactive tool can be toggled independently via boolean props (all default to true, except annotation mutation flags). For example, to render a clean, minimal embed card for a catalog grid:
<div className="w-full h-[420px]">
<ModelViewer
modelUrl="/models/hatshepsut.glb"
title="Sphinx of Hatshepsut"
knownMaxDimensionMm={520}
initialTheme="light"
showBottomToolbar={false}
showReferenceObjects={false}
showTelemetry={false}
enableCalibrate={false}
enableMeasure={false}
enableExport={false}
enableDeepLink={false}
/>
</div>You can also pass custom JSX overlays as children inside <ModelViewer>—they will render inside the .gmv-root container above the WebGL canvas.
Because Three.js accesses window and WebGL APIs, load the component inside a Client Component ('use client') or via next/dynamic with ssr: false:
'use client';
import dynamic from 'next/dynamic';
import '@micropasts/glb-model-viewer/style.css';
const ModelViewer = dynamic(
() => import('@micropasts/glb-model-viewer').then((mod) => mod.ModelViewer),
{ ssr: false }
);
export default function NextArtifactViewer({ modelUrl, title }) {
return (
<div className="w-full h-[80vh]">
<ModelViewer modelUrl={modelUrl} title={title} />
</div>
);
}Mount the viewer onto a DOM element carrying data-* attributes from your Eloquent model:
resources/js/threeD-viewer.jsx
import React from 'react';
import { createRoot } from 'react-dom/client';
import { ModelViewer } from '@micropasts/glb-model-viewer';
import '@micropasts/glb-model-viewer/style.css';
const rootEl = document.getElementById('model-viewer-root');
if (rootEl) {
const maxMm = rootEl.dataset.maxMm ? parseFloat(rootEl.dataset.maxMm) : null;
createRoot(rootEl).render(
<ModelViewer
modelUrl={rootEl.dataset.modelUrl}
title={rootEl.dataset.title}
subtitle={rootEl.dataset.subtitle}
fileName={rootEl.dataset.fileName}
knownMaxDimensionMm={maxMm}
/>
);
}resources/views/finds/viewer.blade.php
<div class="w-full h-[calc(100vh-4rem)]">
<div
id="model-viewer-root"
data-model-url="{{ $modelUrl }}"
data-title="{{ $find->find_identifier }}"
data-subtitle="{{ $find->objectTerm?->term }} • {{ $find->broadPeriod?->term }}"
data-file-name="{{ $find->find_identifier }}.glb"
data-max-mm="{{ $find->length ?? '' }}"
class="w-full h-full"
></div>
</div>
@viteReactRefresh
@vite(['resources/js/threeD-viewer.jsx'])ModelViewer includes a backend-agnostic spatial annotations layer designed to store and exchange 3D surface pins across static JSON sidecars, relational databases (Laravel/PostgreSQL/MariaDB), W3C Web Annotation / IIIF 3D manifests, or URL hashes.
Each annotation stores its 3D anchor in model-local coordinates (target.position), the surface normal (target.normal) for automatic back-face occlusion fading, an optional camera viewpoint (camera) for guided tour fly-to transitions, and curatorial metadata (body):
{
"id": "ann-01hxyz89",
"target": {
"position": [0.0142, 0.1185, 0.0431],
"normal": [0.12, 0.34, 0.93],
"meshName": "hatshepsut_head_mesh"
},
"camera": {
"position": [0.045, 0.16, 0.22],
"target": [0.0142, 0.1185, 0.0431],
"projection": "perspective"
},
"body": {
"title": "Uraeus Cobra Fragment",
"summary": "Broken hood of the royal uraeus on the brow of the nemes headdress.",
"category": "damage",
"tags": ["iconography", "conservation"],
"author": "D. Pett",
"createdAt": "2026-11-17T15:30:00Z"
}
}Supported built-in body.category values are 'note', 'damage' (Condition), 'iconography', 'inscription', and 'manufacture' (Technique).
Pass defaultAnnotations (fetched from a static .json file or bundled directly) and enable creation/editing in memory:
<ModelViewer
modelUrl="/models/hatshepsut.glb"
defaultAnnotations={sidecarAnnotations}
enableAnnotationCreate={true}
enableAnnotationEdit={true}
enableAnnotationDelete={true}
/>Pass annotations from your API state and wire onCreateAnnotation, onUpdateAnnotation, and onDeleteAnnotation to persist changes to your backend:
function CuratorialViewer({ findId, modelUrl }) {
const [annotations, setAnnotations] = useState([]);
const [selectedId, setSelectedId] = useState(null);
useEffect(() => {
fetch(`/api/finds/${findId}/annotations`)
.then((res) => res.json())
.then(setAnnotations);
}, [findId]);
return (
<ModelViewer
modelUrl={modelUrl}
annotations={annotations}
selectedAnnotationId={selectedId}
enableAnnotationCreate={true}
enableAnnotationEdit={true}
enableAnnotationDelete={true}
onSelectAnnotation={(ann) => setSelectedId(ann?.id ?? null)}
onCreateAnnotation={async (draft) => {
const res = await fetch(`/api/finds/${findId}/annotations`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(draft),
});
const saved = await res.json();
setAnnotations((prev) => [...prev, saved]);
return saved;
}}
onUpdateAnnotation={async (updated) => {
const res = await fetch(`/api/annotations/${updated.id}`, {
method: 'PATCH',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(updated),
});
const saved = await res.json();
setAnnotations((prev) => prev.map((a) => (a.id === saved.id ? saved : a)));
return saved;
}}
onDeleteAnnotation={async (id) => {
await fetch(`/api/annotations/${id}`, { method: 'DELETE' });
setAnnotations((prev) => prev.filter((a) => a.id !== id));
}}
/>
);
}You can pass standard W3C Web Annotation / IIIF 3D PointSelector objects directly into annotations or defaultAnnotations—the viewer normalizes them automatically. You can also export or serialize annotations using the built-in helpers:
import {
toW3CWebAnnotations,
encodeAnnotationsHash,
decodeAnnotationsHash,
} from '@micropasts/glb-model-viewer';
// Export current annotations as W3C Web Annotation / IIIF 3D JSON-LD
const jsonLd = toW3CWebAnnotations(annotations, 'https://example.org/models/hatshepsut.glb');
// Serialize annotations into a shareable URL hash (#annotations=...)
const hash = encodeAnnotationsHash(annotations);
window.history.replaceState(null, '', `#annotations=${hash}`);3D scans exported from photogrammetry tools (such as Agisoft Metashape or RealityCapture) without a scale bar often use arbitrary mesh units rather than meters. ModelViewer handles this automatically:
- Database-Driven Calibration (
knownMaxDimensionMm): If your catalog record already stores the object's longest physical measurement in millimeters, pass it viaknownMaxDimensionMm. The viewer normalizes the bounding box so every point-to-point measurement and the zebra photoscale bar are accurate immediately. - Metric Unit Scaling (
defaultUnitScale): IfknownMaxDimensionMmis omitted, the viewer multiplies raw mesh units bydefaultUnitScale(1000by default, converting standard glTF meters to millimeters) and checks whether the result falls withinsanityRangeMm([0.5, 5000]mm). - Interactive 2-Point Calibration: If a model falls outside
sanityRangeMm(ordefaultUnitScale={null}is passed), the header displays an Unscaled • Calibrate badge. Clicking it (or pressingC) lets the user click two points of known distance on the mesh and enter the real millimeter length to calibrate the session.
| Prop | Type | Default | Description |
|---|---|---|---|
modelUrl |
string |
Required | URL or path to the .glb or .gltf asset (must support CORS if hosted cross-origin). |
title |
string |
'3D Model' |
Primary heading displayed in the top-left header. |
subtitle |
string |
'' |
Secondary metadata line (period, material, classification). |
badge |
string |
'GLB' |
Uppercase format badge next to the title. |
fileName |
string |
'model' |
Base filename used when exporting .glb, .obj, .stl, .png, or .webm. |
fileSize |
string | null |
null |
Optional human-readable file size displayed in the Telemetry drawer. |
backUrl |
string | null |
null |
Optional URL rendering a back navigation button in the top-left header. |
knownMaxDimensionMm |
number | null |
null |
Known longest physical dimension (in mm) to auto-calibrate the mesh. |
defaultUnitScale |
number | null |
1000 |
Multiplier converting raw mesh units to mm (1000 for meters, 10 for cm, null for unscaled). |
sanityRangeMm |
[number, number] |
[0.5, 5000] |
Plausible millimeter range before flagging defaultUnitScale output as unscaled. |
initialBackground |
string |
'#090d16' |
Initial hex background color of the WebGL viewport. |
initialTheme |
'light' | 'dark' |
'dark' |
Initial UI theme for the frosted-glass HUD panels. |
dracoDecoderPath |
string |
gstatic CDN 1.5.7 |
Base path/URL to Draco WASM/JS decoder files for compressed meshes. |
ktx2TranscoderPath |
string |
gstatic CDN 2021-04-15 |
Base path/URL to Basis Universal KTX2 transcoder files. |
| Prop | Type | Default | Description |
|---|---|---|---|
showHeader |
boolean |
true |
Shows or hides the top-left title, badge, and scale status card. |
showBottomToolbar |
boolean |
true |
Shows or hides the bottom shading, overlay, camera, and lighting toolbar. |
showScaleBar |
boolean |
true |
Shows or hides the dynamic zebra photoscale bar (when model is scaled). |
showReferenceObjects |
boolean |
true |
Enables the expandable reference object silhouettes (AA Cell, Tennis Ball, 330ml Can, A4 Sheet) on the scale bar. |
showAnimationTimeline |
boolean |
true |
Shows the timeline scrubber bar when the loaded glTF/GLB contains animations. |
showThemeToggle |
boolean |
true |
Shows the Light/Dark UI theme toggle button in the top-right toolbar. |
showTelemetry |
boolean |
true |
Shows the Telemetry button and mesh statistics/measurements drawer. |
enableMeasure |
boolean |
true |
Enables the point-to-point measurement tool (M shortcut). |
enableCalibrate |
boolean |
true |
Enables the 2-point manual scale calibration tool (C shortcut). |
enableExport |
boolean |
true |
Shows the Export dropdown menu (.glb, .obj, .stl, .png, .webm). |
enableFullscreen |
boolean |
true |
Shows the fullscreen toggle button. |
enableDeepLink |
boolean |
true |
Enables #view=... and #annotations=... URL hash serialization and restoration. |
| Prop | Type | Default | Description |
|---|---|---|---|
annotations |
Annotation[] |
undefined |
Controlled list of annotations (supports native schema or W3C Web Annotation / IIIF 3D objects). |
defaultAnnotations |
Annotation[] |
[] |
Initial list of annotations when running in uncontrolled mode. |
selectedAnnotationId |
string | null |
undefined |
Controlled ID of the currently active annotation pin. |
showAnnotations |
boolean |
true |
Shows or hides spatial annotation pins and detail popovers. |
showAnnotationTour |
boolean |
true |
Shows or hides the bottom < 1 / N > guided tour navigation bar when annotations exist. |
enableAnnotationCreate |
boolean |
false |
Enables the Annotate toolbar button so users can click the mesh surface to drop new pins. |
enableAnnotationEdit |
boolean |
false |
Shows an Edit button inside annotation popovers. |
enableAnnotationDelete |
boolean |
false |
Shows a Delete button inside annotation popovers. |
onSelectAnnotation |
(ann: Annotation | null) => void |
null |
Callback fired when a pin is clicked, stepped through in the tour, or closed. |
onCreateAnnotation |
(draft: Annotation) => Promise<Annotation> | Annotation |
null |
Async or sync callback fired when a new surface pin is saved. |
onUpdateAnnotation |
(updated: Annotation) => Promise<Annotation> | Annotation |
null |
Async or sync callback fired when an existing annotation is edited. |
onDeleteAnnotation |
(id: string) => Promise<void> | void |
null |
Async or sync callback fired when an annotation is deleted. |
renderAnnotationBody |
(ann: Annotation) => React.ReactNode |
null |
Optional custom renderer for rich HTML, Markdown, or linked citations inside the annotation card. |
| Prop | Type | Default | Description |
|---|---|---|---|
onLoad |
(stats: MeshStats) => void |
null |
Callback fired once the model parses and renders ({ triangles, vertices, meshes, rawSize }). |
onError |
(error: unknown) => void |
null |
Callback fired if fetching or parsing the 3D asset fails. |
onCalibrate |
(result: CalibrationResult) => void |
null |
Callback fired when a user applies a manual 2-point calibration ({ scaleFactor, targetMm }). |
children |
React.ReactNode |
null |
Optional custom HUD elements rendered inside the .gmv-root viewport container. |
In addition to ModelViewer, the package exports its individual HUD building blocks, distance formatter, and annotation serialization adapters:
import {
ModelViewer,
TopBar,
BottomToolbar,
TelemetryDrawer,
ScaleBarOverlay,
AnimationTimeline,
AnnotationOverlay,
ThemeToggle,
formatDistance,
normalizeAnnotation,
normalizeAnnotationList,
toW3CWebAnnotations,
encodeAnnotationsHash,
decodeAnnotationsHash,
} from '@micropasts/glb-model-viewer';| Input | Action |
|---|---|
Double-click (surface) |
Smoothly focus and orbit around the clicked surface point |
Double-click (background) |
Reset camera to isometric fit view |
↑ ↓ ← → |
Orbit camera around target |
Shift + ↑ ↓ ← → |
Pan camera |
+ / - |
Zoom in / out |
M |
Toggle point-to-point measurement mode |
C |
Toggle 2-point scale calibration mode |
P |
Switch between Perspective and Orthographic projection |
G |
Toggle scale reference grid |
R |
Toggle turntable auto-rotation |
F |
Reset camera to isometric fit view |
Esc |
Cancel active measurement/calibration point or close menus |
MIT © 2026 Daniel Pett