belowjs

v1.3.0

Published

a month ago

A modular Three.js library for creating immersive underwater/dive model viewers with VR support

0High
0Medium
0Low

patrick-morrison

threejs webxr vr 3d underwater model-viewer webgl

BelowJS

📖 Full Documentation & Examples

Current Version: 1.3.0 - Quest Link stability patch for WebXR optional features.

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.

About

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. We have tools to help you optimise, scale and annotate them.

The code is yours, as long as you share what you do with it.

Quick Start

With npm

npm install belowjs three

import { ModelViewer } from 'belowjs';
import 'belowjs/dist/belowjs.css';

const config = {
    models: {
        'kxi': {
            url: 'shipwreck.glb'
        }
    }
};

const viewer = new ModelViewer('body', config);

With CDN

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/[email protected]/+esm",
            "belowjs": "https://cdn.jsdelivr.net/npm/[email protected]/dist/belowjs.js"
        }
    }
    </script>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/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'
                }
            }
        };
        
        const viewer = new ModelViewer('body', config);
    </script>
</body>
</html>

What it does

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

Three different examples are included:

git clone https://github.com/patrick-morrison/belowjs
cd belowjs
npm install && npm run build

npm run dev — Full-featured viewer with model selection and all systems enabled
npm run dev:dragdrop — File loader with drag-and-drop GLB support and custom UI elements
npm run dev:embed — Lightweight viewer designed for iframe embedding

Live Examples

Basic Viewer — Full-featured multi-model viewer
Drag & Drop — File loader with custom UI; recommended path for Meta Quest Link desktop streaming
Embed Viewer — Lightweight iframe-ready viewer

Installation

npm

npm install belowjs three

Manual Installation

If 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 build

This builds the necessary files into the /dist directory:

belowjs.js (~419 KB) — ES modules version
belowjs.css (~20 KB) — Complete stylesheet

Deployment

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.

Usage

Basic Setup

import { ModelViewer } from 'belowjs';
import 'belowjs/dist/belowjs.css';

new ModelViewer('#container', {
  models: { 'ship': { url: 'model.glb', name: 'Historic Ship' } }
});

With Camera Positioning and All Features

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.

URL Parameter Integration

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>

Development

npm run build    # Build distribution files
npm run dev      # Start development server

The 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.

License

GPL-3.0-or-later — See LICENSE file.

Created by Patrick Morrison.

Built for underwater archaeology. Models courtesy of WreckSploration.