{"id":30140530,"url":"https://github.com/patrick-morrison/belowjs","last_synced_at":"2026-04-17T01:02:10.845Z","repository":{"id":309200675,"uuid":"1014266973","full_name":"patrick-morrison/belowjs","owner":"patrick-morrison","description":"Dive shipwrecks in VR. A lightweight 3D model viewer library with VR support, dive lighting effects, and measurement tools built on Three.js","archived":false,"fork":false,"pushed_at":"2026-03-16T09:08:58.000Z","size":107631,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-16T20:45:14.258Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/patrick-morrison.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-07-05T11:26:52.000Z","updated_at":"2026-03-15T14:23:28.000Z","dependencies_parsed_at":"2025-08-27T12:36:25.363Z","dependency_job_id":"7c21d387-0344-4015-bd2c-6be2d076bd78","html_url":"https://github.com/patrick-morrison/belowjs","commit_stats":null,"previous_names":["patrick-morrison/belowjs"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/patrick-morrison/belowjs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrick-morrison%2Fbelowjs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrick-morrison%2Fbelowjs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrick-morrison%2Fbelowjs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrick-morrison%2Fbelowjs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/patrick-morrison","download_url":"https://codeload.github.com/patrick-morrison/belowjs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrick-morrison%2Fbelowjs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31910585,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T18:22:33.417Z","status":"ssl_error","status_checked_at":"2026-04-16T18:21:47.142Z","response_time":69,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-11T04:01:10.957Z","updated_at":"2026-04-17T01:02:10.803Z","avatar_url":"https://github.com/patrick-morrison.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BelowJS\n\n[![npm version](https://badge.fury.io/js/belowjs.svg)](https://www.npmjs.com/package/belowjs)\n[![npm downloads](https://img.shields.io/npm/dm/belowjs.svg)](https://www.npmjs.com/package/belowjs)\n[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n\n📖 **[Full Documentation \u0026 Examples](https://patrick-morrison.github.io/belowjs/)**\n\n\u003e **Current Version:** `1.7.3` - Comfort-mode teleport refined with cleaner landing visuals and controller handling.\n\n**Dive Shipwrecks in Virtual Reality**\n\nSetup virtual dives in minutes. Full control over your underwater photogrammetry models. Web and virtual reality as first class technologies.\n\n## About\n\nBelowJS is a 3D model viewer built on Three.js that allows communities to share their underwater photogrammetry models on the web and in VR. \n\nVirtual 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.\n\nBelowJS 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.\n\nSensible defaults make your work look beautiful. We have tools to help you optimise, scale and annotate them.\n\nThe code is yours, as long as you share what you do with it.\n\n## Quick Start\n\n### With npm\n\n```bash\nnpm install belowjs three\n```\n\n```javascript\nimport { ModelViewer } from 'belowjs';\nimport 'belowjs/dist/belowjs.css';\n\nconst config = {\n    models: {\n        'kxi': {\n            url: 'shipwreck.glb',\n            measurable: true // optional, defaults to true\n        }\n    }\n};\n\nconst viewer = new ModelViewer('body', config);\n```\n\n### With CDN\n\nThis gives you a complete VR-ready 3D viewer with dive lighting, measurement tools, and mode switching enabled by default.\n\n```html\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n\u003chead\u003e\n    \u003cscript type=\"importmap\"\u003e\n    {\n        \"imports\": {\n            \"three\": \"https://cdn.jsdelivr.net/npm/three@0.179.1/+esm\",\n            \"belowjs\": \"https://cdn.jsdelivr.net/npm/belowjs@1.7.3/dist/belowjs.js\"\n        }\n    }\n    \u003c/script\u003e\n  \u003clink rel=\"stylesheet\" href=\"https://cdn.jsdelivr.net/npm/belowjs@1.7.3/dist/belowjs.css\"\u003e\n    \u003cstyle\u003e\n        body, html { margin: 0; padding: 0; overflow: hidden; }\n    \u003c/style\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n    \u003cscript type=\"module\"\u003e\n        import { ModelViewer } from 'belowjs';\n        \n        const config = {\n            models: {\n                'kxi': {\n                    url: 'shipwreck.glb',\n                    measurable: true // optional, defaults to true\n                }\n            }\n        };\n        \n        const viewer = new ModelViewer('body', config);\n    \u003c/script\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\n## What it does\n\n- Loads and displays GLB 3D models in a web browser\n- Works with VR headsets through WebXR, optimised for Quest 3\n- Provides measurement tools for both desktop and VR environments\n- Includes underwater lighting simulation and particle effects\n- Supports multiple models with dropdown switching\n- Can be embedded in iframes with URL parameter configuration \n\n## Examples\n\nExamples are included:\n\n```bash\ngit clone https://github.com/patrick-morrison/belowjs\ncd belowjs\nnpm install \u0026\u0026 npm run build\n```\n\n- `npm run dev` — Full-featured viewer with model selection and all systems enabled\n- `npm run dev:dragdrop` — File loader with drag-and-drop GLB support and custom UI elements\n- `npm run dev:embed` — Lightweight viewer designed for iframe embedding\n- `npm run dev:tileset` — 3D Tiles streaming example for large datasets\n\n### Live Examples\n\n- [Basic Viewer](https://patrick-morrison.github.io/belowjs/examples/basic/) — Full-featured multi-model viewer\n- [Drag \u0026 Drop](https://patrick-morrison.github.io/belowjs/examples/dragdrop/) — File loader with custom UI; recommended path for Meta Quest Link desktop streaming\n- [Embed Viewer](https://patrick-morrison.github.io/belowjs/examples/embed/) — Lightweight iframe-ready viewer\n- [Tileset Viewer](https://patrick-morrison.github.io/belowjs/examples/tileset/) — 3D Tiles streaming example\n\n## Installation\n\n### npm\n```bash\nnpm install belowjs three\n```\n\n### Manual Installation\nIf you prefer to install manually, clone the repository and build the distribution files:\n```bash\ngit clone https://github.com/patrick-morrison/belowjs\ncd belowjs\nnpm install\nnpm run build\n```\n\nThis builds the necessary files into the `/dist` directory:\n- `belowjs.js` (~419 KB) — ES modules version  \n- `belowjs.css` (~20 KB) — Complete stylesheet\n\n## Deployment\n\nDeploy statically on your server, integrate with JS/ES modules in an app, or simplest of all - GitHub Pages:\n\n```\nshipwrecks-vr/\n├── index.html          # Main HTML with BelowJS\n├── belowjs.js          # Download from releases\n├── belowjs.css         # Download from releases\n└── models/\n    ├── kxi.glb\n    └── kozvii.glb\n```\n\nPush to GitHub, enable Pages in Settings → live in minutes.\n\n\n## Usage\n\n### Basic Setup\n```javascript\nimport { ModelViewer } from 'belowjs';\nimport 'belowjs/dist/belowjs.css';\n\nnew ModelViewer('#container', {\n  models: {\n    'ship': { url: 'model.glb', name: 'Historic Ship', measurable: true }\n  }\n});\n```\n\n### Per-Model Measurement Availability\n```javascript\nnew ModelViewer('#container', {\n  models: {\n    'draftSite': {\n      url: 'draft-site.glb',\n      name: 'Draft Site',\n      measurable: false // disable measurements for uncertain scale\n    }\n  }\n});\n```\n\n### With Camera Positioning and All Features\n```javascript\nnew ModelViewer(document.body, {\n  models: {\n    'wreck': {\n      url: 'shipwreck.glb',\n      name: 'Historic Shipwreck',\n      initialPositions: {\n        desktop: {\n          camera: { x: 10, y: 5, z: 15 },\n          target: { x: 0, y: 0, z: 0 }\n        },\n        vr: {\n          dolly: { x: 0, y: 2, z: 10 },\n          rotation: { x: 0, y: 0, z: 0 }\n        }\n      }\n    }\n  },\n  enableVR: true,\n  enableMeasurement: true,\n  enableDiveSystem: true,\n  enableScreenshot: true\n});\n```\n\nEnable `enableScreenshot` to add a button that captures the scene without UI overlays.\n\n### 3D Tiles (Experimental)\nBelowJS 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'`:\n\n```javascript\nnew ModelViewer('#container', {\n  models: {\n    'site': {\n      url: 'https://example.com/tiles/site/tileset.json',\n      type: 'tileset',\n      name: 'Survey Site',\n      autoCenter: true,\n      maxTriangles: 1000000, // adaptive LOD target for VR\n      errorTarget: 16,\n      optimizedLoadStrategy: true\n    }\n  }\n});\n```\n\n### URL Parameter Integration\nThe embed example supports URL parameters for dynamic configuration:\n\n```html\n\u003ciframe \n  src=\"viewer.html?model=wreck.glb\u0026name=Historic%20Wreck\u0026cx=10\u0026cy=5\u0026cz=15\"\n  width=\"800\" height=\"600\"\u003e\n\u003c/iframe\u003e\n```\n\n## Development\n\n```bash\nnpm run build    # Build distribution files\nnpm run dev      # Start development server\n```\n\nThe 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.\n\n## License\n\nGPL-3.0-or-later — See [LICENSE](LICENSE) file.\n\n---\n\nCreated by [Patrick Morrison](https://padmorrison.com).\n\nBuilt for underwater archaeology. Models courtesy of [WreckSploration](https://wrecksploration.au).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatrick-morrison%2Fbelowjs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpatrick-morrison%2Fbelowjs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatrick-morrison%2Fbelowjs/lists"}