Back to blog

Atlas + three.js: Build a First-Person Walkthrough

Nov 13, 2026Atlas World Model Editors

Load an Atlas SPZ or PLY splat with Spark, or a GLB mesh, into three.js and add first-person WASD controls. Minimal starter code and tips included.

Once Atlas by World Labs has turned your photos into a Gaussian splat, the obvious next step is to walk around in it in a browser. This post builds a minimal first-person viewer in three.js: it loads an Atlas splat with Spark, adds mouse-look and WASD movement, starts you at your photo's camera, and optionally loads a GLB mesh for collision. The code is a starting point, not a finished product. Test it against your own files, as of November 2026.

In this post

  • What you need from Atlas
  • Why Spark for splats
  • Project setup
  • Step 1: Render the splat
  • Step 2: Add first-person controls
  • Step 3: Start at your photo's camera
  • Step 4: Optional GLB mesh for collision
  • Performance and quality tips
  • Troubleshooting

What you need from Atlas

You need at least one of these files:

FileWhere it comes fromUsed for
.spz splatposedImages2Splats, or creating splats from ViewfinderWhat you see
.ply splat Listed as a Viewfinder splat output in the web appWhat you see (larger file)
.glb meshSplats to Mesh (splats2Mesh)Collision, or a fallback without splat support
Camera JSONThe posed image's camera from images2PosedRGBDStarting viewpoint

A refined splat costs 5,000 credits ($5) through the API, and the worked example in World Labs' docs returned 2,000,000 splats. Expect large files. If you don't have a splat yet, see the step-by-step Atlas guide, or use our photos to 3D app, which produces a splat and a GLB from photos.

Why Spark for splats

three.js doesn't render Gaussian splats on its own. World Labs' docs point to Spark (@sparkjsdev/spark), a splat renderer for three.js, and include a React example that loads an Atlas .spz file with SplatMesh. Spark's own docs list .ply, .spz, .splat, .ksplat and .sog among supported formats. PLY and SPZ are detected from file contents.

Atlas outputs use the OpenGL/three.js right-up-back camera convention, according to World Labs' best-practices page. In principle an Atlas splat lines up with three.js without axis flips. Spark's examples rotate some splats 180° around X, which is needed for files in other conventions. Check your scene and add the flip only if it comes in upside down.

Project setup

The simplest setup is one HTML file with an import map, following the pattern in Spark's docs. Put your exported file next to it as scene.spz, and serve the folder with any static server. Opening the file directly from disk usually blocks loading.

<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Atlas walkthrough</title>
    <style>
      body {
        margin: 0;
        overflow: hidden;
      }
      #hint {
        position: fixed;
        top: 12px;
        left: 12px;
        color: #fff;
        font: 14px sans-serif;
      }
    </style>
    <script type="importmap">
      {
        "imports": {
          "three": "https://cdn.jsdelivr.net/npm/three@0.180.0/build/three.module.js",
          "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.180.0/examples/jsm/",
          "@sparkjsdev/spark": "https://sparkjs.dev/releases/spark/2.4.0/spark.module.js"
        }
      }
    </script>
  </head>
  <body>
    <div id="hint">Click to look around. WASD to move, Esc to release.</div>
    <script type="module" src="./main.js"></script>
  </body>
</html>

The versions match Spark's current docs. Pin them, and update them together when you upgrade. With a bundler such as Vite, install three and @sparkjsdev/spark from npm and use the same imports.

Step 1: Render the splat

Create main.js. Spark needs a SparkRenderer added to the scene, plus one SplatMesh per file:

// main.js — starting point, not production code
import { SparkRenderer, SplatMesh } from '@sparkjsdev/spark';
import * as THREE from 'three';

const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(
  60,
  innerWidth / innerHeight,
  0.01,
  1000
);
const renderer = new THREE.WebGLRenderer({ antialias: false });
renderer.setSize(innerWidth, innerHeight);
renderer.setPixelRatio(Math.min(devicePixelRatio, 2));
document.body.appendChild(renderer.domElement);

scene.add(new SparkRenderer({ renderer }));

const splat = new SplatMesh({ url: './scene.spz' });
// Uncomment only if the scene loads upside down:
// splat.quaternion.set(1, 0, 0, 0);
scene.add(splat);

addEventListener('resize', () => {
  camera.aspect = innerWidth / innerHeight;
  camera.updateProjectionMatrix();
  renderer.setSize(innerWidth, innerHeight);
});

renderer.setAnimationLoop(() => renderer.render(scene, camera));

Load the page. You should see the scene from the origin. If you see nothing, the camera may be inside a wall or facing away. Step 3 fixes the starting position.

Step 2: Add first-person controls

three.js ships PointerLockControls in its addons. It handles mouse-look. Movement is a few lines of code on top:

import { PointerLockControls } from 'three/addons/controls/PointerLockControls.js';

const controls = new PointerLockControls(camera, document.body);
document.body.addEventListener('click', () => controls.lock());

const keys = new Set();
addEventListener('keydown', (e) => keys.add(e.code));
addEventListener('keyup', (e) => keys.delete(e.code));

const clock = new THREE.Clock();
const SPEED = 1.5; // scene units per second; Atlas scenes are roughly metric

function move() {
  const dt = Math.min(clock.getDelta(), 0.05);
  if (!controls.isLocked) return;
  const forward = (keys.has('KeyW') ? 1 : 0) - (keys.has('KeyS') ? 1 : 0);
  const right = (keys.has('KeyD') ? 1 : 0) - (keys.has('KeyA') ? 1 : 0);
  controls.moveForward(forward * SPEED * dt);
  controls.moveRight(right * SPEED * dt);
}

renderer.setAnimationLoop(() => {
  move();
  renderer.render(scene, camera);
});

Replace the earlier setAnimationLoop with this one. moveForward keeps you level, which feels like walking rather than flying. Add Q and E for up and down if you want a free camera.

Step 3: Start at your photo's camera

The nicest first frame is the photo the scene came from. World Labs' video guide recommends the same thing for camera paths: start on a camera the viewer knows. images2PosedRGBD returns a camera for each image, with intrinsics (fx, fy, width, height) and extrinsics (position and an XYZW quaternion, with a coordinateSystem such as rub). Camera poses are camera-to-world, and RUB cameras look along local negative Z, which is also three.js's camera convention.

Copy the camera object into camera.json and apply it:

const cam = await (await fetch('./camera.json')).json();
const { position, quaternion } = cam.extrinsics;
camera.position.fromArray(position);
camera.quaternion.fromArray(quaternion); // XYZW, same order as three.js

// Match the photo's vertical field of view
const { fy, height } = cam.intrinsics;
camera.fov = THREE.MathUtils.radToDeg(2 * Math.atan(height / (2 * fy)));
camera.updateProjectionMatrix();

This only works directly if coordinateSystem is rub. For RDF cameras, which look along positive Z, convert first. World Labs' cameras page covers the math. Also note that PointerLockControls assumes a Y-up world. If your scene's up axis differs, walking will feel tilted.

Step 4: Optional GLB mesh for collision

Splats don't collide. If you want to stop the player walking through walls, load the GLB from Splats to Mesh as an invisible collision proxy and cast a short ray in the movement direction:

import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';

let collider = null;
new GLTFLoader().load('./scene.glb', (gltf) => {
  collider = gltf.scene;
  collider.traverse((o) => {
    if (o.isMesh) o.visible = false;
  });
  scene.add(collider);
});

const ray = new THREE.Raycaster();
function blocked(direction, distance) {
  if (!collider) return false;
  ray.set(camera.position, direction);
  ray.far = distance + 0.3; // keep about 30 cm from walls
  return ray.intersectObject(collider, true).length > 0;
}

Check blocked() before calling moveForward or moveRight, using the camera's flattened forward or right vector. For a simple game, the collider boxes GLB that splats2Mesh can return is cheaper to test against than the full mesh. The boxes stay upright and turn only around the vertical axis, which suits walls and furniture.

For a mesh-only viewer, on devices where splats are too heavy, show the GLB instead of hiding it. A textured mesh from splats2Mesh uses a texture atlas of 4096 pixels by default, up to 8192.

Performance and quality tips

  • File size. Prefer SPZ over PLY for the web. SPZ is compressed and PLY is not, as World Labs' Marble export notes say for the same formats.
  • Pixel ratio. Capping setPixelRatio at 2 or lower helps a lot on phones and high-DPI laptops.
  • Antialiasing. Splats don't benefit from MSAA, so keep antialias: false.
  • Stay where the views were. Atlas reconstructs best near the views it was given. Wander far outside them and you'll see blur and invented geometry. Consider limiting movement to a bounding box around your capture.
  • Know the weak spots. Sky, foliage, glass and thin structures are listed by World Labs as hard cases. Frame the walkthrough so they aren't the focus.

Troubleshooting

SymptomCheck
Blank screenServe over HTTP, not from disk; check the console for a 404 on the file
Scene upside downTry splat.quaternion.set(1, 0, 0, 0); check the camera's coordinateSystem
Starting view wrongMake sure the camera JSON belongs to the same operation as the splat
Walking feels tiltedThe scene's up axis isn't +Y; rotate the splat and collider once at load
Blurry areasCoverage gaps in the input views; add views and reconstruct

Where to go next

The same viewer works for any Atlas scene. Build better inputs with the Viewfinder guide, get a GLB with Splats to Mesh, or head back to the Atlas World Model home page for more guides.