📖 Full Documentation & Examples
Current Version:
1.9.1- Quest AR session recovery plus the v1.9 measurement calibration, VR endpoint deletion, and integration events.
Dive Shipwrecks in Virtual Reality
Setup virtual dives in minutes. Full control over your underwater photogrammetry models. Web and virtual reality as first class technologies.
BelowJS is a 3D model viewer built on Three.js that allows communities to share their underwater photogrammetry models on the web and in VR.
Virtual reality and desktop modes are tightly integrated with a measurement system, so archaeologists can research sites with confidence. An optional dive mode lets audiences feel the wrecks as they are - optimised for the Meta Quest 3 headset.
BelowJS can be deployed statically or as part of a system. A simple GitHub page can share optimised models for free, and will last forever with little maintenance. Conversely, it can power dynamic systems like BelowVR, which lets teams virtually dive together.
Sensible defaults make your work look beautiful. The drag-and-drop viewer helps you inspect, measure and correct model scale before building your own viewer.
The code is yours, as long as you share what you do with it.
npm install belowjs threeimport { ModelViewer } from 'belowjs';
import 'belowjs/dist/belowjs.css';
const config = {
models: {
'kxi': {
url: 'shipwreck.glb',
measurable: true // optional, defaults to true
}
}
};
const viewer = new ModelViewer('body', config);This gives you a complete VR-ready 3D viewer with dive lighting, measurement tools, and mode switching enabled by default.
<!DOCTYPE html>
<html>
<head>
<script type="importmap">
{
"imports": {
"three": "https://cdn.jsdelivr.net/npm/three@0.179.1/+esm",
"belowjs": "https://cdn.jsdelivr.net/npm/belowjs@1.9.1/dist/belowjs.js"
}
}
</script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/belowjs@1.9.1/dist/belowjs.css">
<style>
body, html { margin: 0; padding: 0; overflow: hidden; }
</style>
</head>
<body>
<script type="module">
import { ModelViewer } from 'belowjs';
const config = {
models: {
'kxi': {
url: 'shipwreck.glb',
measurable: true // optional, defaults to true
}
}
};
const viewer = new ModelViewer('body', config);
</script>
</body>
</html>- Loads and displays GLB 3D models in a web browser
- Works with VR headsets through WebXR, optimised for Quest 3
- Provides measurement tools for both desktop and VR environments
- Includes underwater lighting simulation and particle effects
- Supports multiple models with dropdown switching
- Can be embedded in iframes with URL parameter configuration
Examples are included:
git clone https://github.com/patrick-morrison/belowjs
cd belowjs
npm install && npm run buildnpm run dev— Full-featured viewer with model selection and all systems enablednpm run dev:dragdrop— Load a GLB, check measurements and correct its scalenpm run dev:embed— Lightweight viewer designed for iframe embeddingnpm run dev:tileset— 3D Tiles streaming example for large datasets
- Basic Viewer — Full-featured multi-model viewer
- Drag & Drop — Load a GLB, check measurements and correct its scale
- Embed Viewer — Lightweight iframe-ready viewer
- Tileset Viewer — 3D Tiles streaming example
npm install belowjs threeIf you prefer to install manually, clone the repository and build the distribution files:
git clone https://github.com/patrick-morrison/belowjs
cd belowjs
npm install
npm run buildThis builds the necessary files into the /dist directory:
belowjs.js(~419 KB) — ES modules versionbelowjs.css(~20 KB) — Complete stylesheet
Deploy statically on your server, integrate with JS/ES modules in an app, or simplest of all - GitHub Pages:
shipwrecks-vr/
├── index.html # Main HTML with BelowJS
├── belowjs.js # Download from releases
├── belowjs.css # Download from releases
└── models/
├── kxi.glb
└── kozvii.glb
Push to GitHub, enable Pages in Settings → live in minutes.
import { ModelViewer } from 'belowjs';
import 'belowjs/dist/belowjs.css';
new ModelViewer('#container', {
models: {
'ship': { url: 'model.glb', name: 'Historic Ship', measurable: true }
}
});new ModelViewer('#container', {
models: {
'draftSite': {
url: 'draft-site.glb',
name: 'Draft Site',
measurable: false // disable measurements for uncertain scale
}
}
});In the drag-and-drop viewer, make a measurement across a known distance, then right-click its measurement box on desktop or long press it on mobile. Enter the correct distance and BelowJS will rescale the model around its original origin. The applied scale is shown so you can use the same factor when preparing the final model.
Scale correction is enabled by default. Disable it for a viewer with:
new ModelViewer('#container', {
enableMeasurementScaleCalibration: false
});new ModelViewer(document.body, {
models: {
'wreck': {
url: 'shipwreck.glb',
name: 'Historic Shipwreck',
initialPositions: {
desktop: {
camera: { x: 10, y: 5, z: 15 },
target: { x: 0, y: 0, z: 0 }
},
vr: {
dolly: { x: 0, y: 2, z: 10 },
rotation: { x: 0, y: 0, z: 0 }
}
}
}
},
enableVR: true,
enableMeasurement: true,
enableDiveSystem: true,
enableScreenshot: true
});Enable enableScreenshot to add a button that captures the scene without UI overlays.
BelowJS can stream 3D Tiles datasets for large environments. Tilesets still require a tileset.json root plus streamed tile content hosted alongside it. Point a model at the tileset.json and set type: 'tileset':
new ModelViewer('#container', {
models: {
'site': {
url: 'https://example.com/tiles/site/tileset.json',
type: 'tileset',
name: 'Survey Site',
autoCenter: true,
maxTriangles: 1000000, // adaptive LOD target for VR
errorTarget: 16,
loadAncestors: true
}
}
});Ancestor fallback keeps a coarse tile visible until its detailed children are ready, avoiding distracting holes during movement. BelowJS automatically uses a smaller texture-transcoding worker pool on standalone headsets and a larger pool on PCVR; set ktxWorkerLimit only when profiling a specific deployment.
The embed example supports URL parameters for dynamic configuration:
<iframe
src="viewer.html?model=wreck.glb&name=Historic%20Wreck&cx=10&cy=5&cz=15"
width="800" height="600">
</iframe>npm run build # Build distribution files
npm run dev # Start development serverThe examples load from /dist/. Run npm run build once before first testing to generate /dist/. During npm run dev, source edits will auto-rebuild the library.
GPL-3.0-or-later — See LICENSE file.
Created by Patrick Morrison.
Built for underwater archaeology. Models courtesy of WreckSploration.