Five SDK

import { Five, parseWork } from '@realsee/five'
import workJSON from '@realsee/open-works/virtual/816lPVZQkQDF5XOpPo/work.json'

const container = document.querySelector<HTMLElement>('#tour')
const five = new Five({ imageOptions: { size: 1024 } })

if (container) {
  five.appendTo(container)
  await five.load(parseWork(workJSON), 'initial')
  five.refresh()
  await five.changeMode(Five.Mode.Panorama)
}

• WebGL under the hood. Three.js ^0.117.1 powers the renderer behind Five SDK
• Mode transitions. Panorama ↔ Floorplan ↔ Modeling, with smooth animated handoff.
• Lazy tile streaming. Dynamic resolution loading. Smooth on phones, sharp on desktops.
• Extension-ready interactions. Gesture and raycast events provide stable hooks for overlays and plugins.

Open Playground to render the bundled Demo scene now, or continue with the Five SDK Quickstart.

Install

Install Five SDK with its required Three.js peer. Add @realsee/open-works only when you want to use the public sample work in these guides.

npm install @realsee/five@6.8.9 three@^0.117.1 @realsee/open-works@0.1.1

three@^0.117.1 is the renderer peer declared by @realsee/five@6.8.9. @realsee/open-works is a separate sample-data package, not a Five SDK peer dependency.

What Five SDK does

These pages are verified against @realsee/five@6.8.9, @realsee/open-works@0.1.1, and three@0.117.1.

Five SDK gives you four things out of the box:

• Loads a work.json scene. A work is Realsee's portable description of a captured space — panoramas, depth maps, geometry, and metadata bundled into one JSON payload.
• Renders three viewing modes. Walk the space from the panorama view, look down on the model from the floorplan view, or orbit the textured mesh in the modeling view.
• Hit-tests 3D points. Convert a screen tap into a 3D world coordinate so you can attach overlays, measurements, or custom routing.
• Exposes interaction hooks. Gesture, camera, and intersection events let overlays and dedicated plugin packages respond as the user moves through the scene.

The Work data format

A Work is the unit Five SDK consumes. It is a JSON document — usually called work.json — that contains panoramic imagery, depth, geometry, and the camera path that walks the space. One Five SDK instance loads one work at a time, but you can swap works on a running instance to navigate between captured spaces.

Most works are produced by Realsee capture hardware: the Galois LiDAR scanner, the Realsee Lite panoramic camera, or the Realsee VR App. If you do not have capture hardware, use the public sample works below to learn Five SDK. Argus is a separate, reviewed reconstruction flow; its public contract exposes an optional result_url but does not guarantee Five SDK Work data or direct Five SDK compatibility. See the Argus introduction for that workflow.

For experimentation, Realsee publishes a set of public works under `@realsee/open-works` — the Quickstart imports one of them directly so you can render a real space without setting up storage.

Browser compatibility

Five SDK inherits Three.js's requirements: a modern browser with WebGL and a touch/pointer-capable surface. The supported floor across the major engines:

| Engine | Safari | Safari (iOS) | Chrome | Chrome (Android) | Edge | Firefox | | ------------- | :----: | :----------: | :----: | :--------------: | :--: | :-----: | | Minimum | ≥ 9 | ≥ 9 | ≥ 69 | ≥ 93 | ≥ 13 | ≥ 45 |

These minimum versions follow the browser-support table shipped with @realsee/five@6.8.9. Five SDK also requires WebGL; provide a non-WebGL fallback for unsupported browsers.

Architecture sketch

The core Five SDK lifecycle is short:

• A single <canvas> element is mounted into whatever DOM node you point Five SDK at. The renderer owns that canvas exclusively.
• A simple state machine sits behind the canvas, tracking the active mode: Panorama ↔ Floorplan ↔ Modeling. You drive transitions with five.changeMode(...), and the SDK animates the camera between modes.
• Event hooks notify you when the user interacts with the scene. The installed API includes legacy names such as modeChange, cameraUpdate, and tapGesture, plus namespaced events such as mode.change, camera.update, and gesture.tap. Subscribe with five.on(event, handler); unsubscribe with five.off(...).
• A clear lifecycle: new Five({...}) → five.appendTo(container) → five.load(work) → … → five.dispose(). Mount the renderer before loading Work data, and wire disposal into your framework's teardown hook to release GPU resources in SPAs.

Five SDK supports multiple instances. Give each instance its own stable container and dispose each instance when its surface unmounts.

Framework support

Five SDK is framework-agnostic. The constructor returns an object you can drive imperatively, which means you can use it from anywhere a <canvas> can render.

• Vanilla JavaScript or TypeScript. The smallest, fastest path. Recommended when you want full control over the lifecycle or are embedding Five SDK into a non-React stack. The Quickstart takes this route.
• React. Two patterns work well. The HOC pattern (a context provider plus a hook that exposes the Five SDK instance) is the easiest for shared instances; the `realsee-developer/five-sdk-typescript-react-hoc-tutorial` repo demonstrates it. The Hooks pattern (a custom useFive(container, work) hook owning instantiation and disposal) is cleaner for single-component embeds.
• Vue 3. Use the Composition API: instantiate Five SDK in onMounted, dispose it in onBeforeUnmount, and expose its state through a reactive wrapper if you need template binding. The same lifecycle hooks apply to Vue 2 with mounted / beforeDestroy.

Other frameworks (Svelte, SolidJS, Angular) work the same way — the SDK has no framework-specific dependency. The only requirement is a stable DOM node Five SDK can mount its canvas into.

Next steps

• Five SDK Quickstart — render a real 3D tour in five minutes.
• Five SDK API Reference — every class, method, and event on the public surface.
• Playground — render the bundled Demo scene or a VR from an accessible Viewing Team.
• Argus introduction — understand the separate reviewed image-reconstruction workflow and its output contract.