API Reference

This page documents the core public surface of @realsee/five — the classes, enums, interfaces, and events you'll touch in every integration. It's organized as a class reference, not an alphabetic dump: methods you call together are listed together.

class Five

Five is the only class you instantiate. One instance owns one <canvas> and renders one work at a time.

import { Five, parseWork } from '@realsee/five'

const five = new Five(args: FiveInitArgs)

new Five(args)

Constructs a renderer. Side effects: none until you call load or appendTo. Safe to construct off the main render path.

.load(work)

five.load(work: Work): Promise<void>

Loads a parsed Realsee Work and prepares it for rendering. Parse JSON with parseWork(workJSON) before calling load. You can call load again later to swap the loaded work.

.appendTo(container)

five.appendTo(container: HTMLElement): void

Mounts the renderer's <canvas> as a child of container. The container must have a non-zero size at call time — Five SDK reads clientWidth / clientHeight to size the canvas.

.refresh()

five.refresh(): void

Re-measures the container and updates the canvas, projection matrix, and renderer viewport. Call this whenever the container's size changes (window resize, sidebar open, orientation change).

.changeMode(mode, config?)

five.changeMode(mode: Five.Mode, config?: { transition?: boolean }): void

Transitions the camera to the requested mode. By default the SDK animates between modes; pass { transition: false } to jump instantly.

.getCurrentState()

five.getCurrentState(): {
  mode: Five.Mode
  panoIndex: number
  // …additional camera and pose fields
}

Returns a snapshot of the renderer's current state. The shape is stable across mode transitions — fields not relevant to the active mode are still defined, just with sentinel values.

.on(event, handler) / .off(event, handler)

five.on<E extends FiveEvent>(event: E, handler: FiveEventHandler<E>): void
five.off<E extends FiveEvent>(event: E, handler: FiveEventHandler<E>): void

Subscribe / unsubscribe to renderer events. See Events for the full list and payload shapes. Handlers are called synchronously on the event's source frame.

.dispose()

five.dispose(): void

Releases GPU resources, removes the <canvas> from the DOM, detaches global event listeners, and stops the render loop. Call this from your framework's teardown hook (React's useEffect cleanup, Vue's onBeforeUnmount) when navigating away in an SPA — otherwise you will leak WebGL contexts. After dispose, the instance is unusable; construct a new one to render again.

enum Five.Mode

The three viewing modes. Pass these to changeMode and read them out of getCurrentState().mode.

interface FiveInitArgs

Initialization options passed to new Five(args). Every field is optional; the defaults below are tuned for the typical web embed.

interface FiveInitArgs {
  imageOptions?: ImageOptions
  textureOptions?: TextureOptions
  backgroundAlpha?: number
  initWithTransition?: boolean
  onlyRenderIfNeeds?: boolean
  initialBasisLoader?: boolean
  floorplan?: ModeViewOptions
  panorama?: ModeViewOptions
  plugins?: FivePlugin[]
}

ImageOptions

interface ImageOptions {
  size?: 512 | 1024 | 2048 | 4096 | 8192
  quality?: number       // 0–100
  format?: 'jpg' | 'png' | 'webp' | 'avif' | 'heif'
  transform?: (source: string, opts: TransformOptions) => string
}

The transform hook lets you proxy panorama URLs through an image-CDN (Alibaba Cloud OSS, Tencent COS, your own service). Five SDK calls it for every tile fetch.

TextureOptions

interface TextureOptions {
  size?: number | null
  autoResize?: boolean
}

size: null plus autoResize: false loads the full-resolution mesh texture — the crispest result, but expensive on memory.

Events

Subscribe with five.on(event, handler). The table covers the events you'll use most often; package typings remain the source of truth for less-common renderer events.

Unsubscribe with five.off(event, handler) using the same handler reference you registered. Anonymous handlers cannot be removed individually; pass a named function if you need to detach.

See also

• Quickstart — a working integration in five minutes.
• Playground — render the bundled Demo scene or a VR from an accessible Viewing Team.