SPHR

SPHR is an open source 3D space viewer you can host yourself. It is built for lidar scans, 3D Gaussian Splatting (3DGS) captures, and 360 image or video tours, and it runs entirely in the browser. Clone it, point it at your own scans, and serve tours from your own domain.

Self-host SPHR with this repository, or use paid hosting at spacery.dev.

• LIVE DEMO (E57): a campus observatory converted from a Matterport E57 export.
• LIVE DEMO (3DGS): a garden captured as 3D Gaussian splats.
• Get started with your agent (optional): add the Spacery MCP server to Claude, Codex, Grok, Antigravity or Meta Muse and your agent uploads a capture from your computer and publishes it as a space. Setup for agents is at spacery.dev/agents.md.

This branch is the Next.js + Three.js migration. It removes the old separate backend requirement and ships as a client-rendered viewer that can load a default demo, a remote JSON config, or embedded bootstrap data from a host page.

https://github.com/user-attachments/assets/169c7729-e4d7-4889-99d2-42d81e33a6d8

Matterport E57 migration

https://github.com/user-attachments/assets/2a181774-616f-445d-8eed-7d4ed589bd88

Import a Matterport export ZIP or E57 into a complete local tour:

python3 -m venv .venv-matterport
.venv-matterport/bin/pip install -r scripts/matterport/requirements.txt
npm run import:matterport -- --e57 /path/to/export.zip
npm run dev

Open / to browse thumbnails, search, sort and copy permanent scene links. /library redirects to this collection. See collection and hosting. The importer derives image orientation from camera poses, preserves meters, fuses measured depth into a mesh of at most 50,000 triangles, and validates every scan before publishing. See the migration guide for configuration, geometry conventions, quality checks, and output files.

3D Gaussian Splatting

The reworked SPHR is centered on 3D Gaussian Splatting. The runtime can load splat assets or 360 images, etc directly in the browser, place them in a Three.js scene, animate camera movement through the capture, and layer guided tour text, UI controls, skyboxes, annotations, models, and effects over the scene.

SPHR uses @sparkjsdev/spark for splat rendering. The current splat layer supports:

• .splat, .ply, .spz, .ksplat, .sog, and .rad sources
• local or remote URLs loaded through fetch
• per-splat position, rotation, scale, opacity, and LOD settings
• reveal animation for initial scene entry
• guided-tour study modes such as point shrinking, projected splat emphasis, and night mode
• a separate scene graph for GLB/mesh overlays, raycast targets, and transition meshes

Example splat config:

{
  "space": {
    "title": "Research Garden Capture",
    "type": "splat",
    "space_data": {
      "noPanos": true,
      "initialPosition": { "x": 4, "y": 1.5, "z": 4 },
      "initialRotation": { "azimuth": 0, "polar": 90 },
      "splats": [
        {
          "id": "garden",
          "url": "https://your-asset-host.example/captures/garden.splat",
          "fileType": "splat",
          "position": [0, 2.6, 0],
          "rotation": [-2.56518, -2.66973, 0.2615546],
          "scale": 1,
          "lod": false,
          "reveal": true
        }
      ]
    }
  }
}

Large splat files are intentionally not meant to live in git. Host captures in object storage, a CDN, a research artifact mirror, or a local static directory that is excluded from version control.

What It Renders

SPHR currently supports these runtime layers:

• 3D Gaussian splats through SparkSplatLayer
• 360 panorama nodes through PanoramaLayer
• IIIF image planes through IiifImageLayer
• custom GLB/model/light hierarchies through SceneGraphLayer
• 3D annotations through AnnotationLayer
• navigation markers and floor click navigation
• equirectangular, cube, and color skyboxes
• first-person and orbit camera modes
• guided tours with text, audio, annotations, model visibility, and camera moves

The runtime is not a visual authoring tool. It is the viewer/runtime that renders a structured SPHR scene.

Quickstart

Install dependencies:

npm install

Run the Next.js dev server:

npm run dev

Open http://localhost:3000.

Build and serve a production build:

npm run build
npm run start

Run TypeScript validation:

npm run typecheck

npm run start is for production builds. Use npm run dev while developing.

Opening 3DGS Captures

To open your own capture:

1. Export or convert the capture to .splat, .ply, .spz, .ksplat, .sog, or .rad.
2. Put the file behind a URL the browser can fetch. For remote URLs, make sure CORS allows the app origin.
3. Create a bootstrap JSON with a space.type of splat and a space.space_data.splats entry.
4. Load it with /?config=/path/to/bootstrap.json.

This is the beginning of the README. Read the rest at the original. Read the full README ↗