Five SDK API Reference

This document provides a summary of the core API for the Five SDK, designed to be easily understood by AI assistants.

Core Class: Five

The Five class is the main entry point for the SDK. It manages the rendering, state, and interaction of the 3D scene.

Constructor

const five = new Five(initArgs?: FiveInitArgs);
Copy

Properties

Property	Type	Description
five.state	State	The current state (mode, position, etc.) of the instance.
five.currentMode	Mode	Shortcut to get the current display mode.
five.panoIndex	number	Shortcut to get the current panorama index.
five.work	Work	The currently loaded work data.
five.model	Model	The 3D model object.
five.scene	THREE.Scene	The Three.js scene used for non-model elements.
five.modelScene	ModelScene	The Three.js scene used for the model.
five.camera	Camera	The internal camera.
five.renderer	THREE.WebGLRenderer	The WebGL renderer.
five.needsRender	boolean	Set to true to request a render frame in the next loop.
five.plugins	Object	Access to registered plugins.

Static Properties

Property	Type	Description
Five.Mode	Enum	Available modes: Panorama, Model, Floorplan, Topview, Mapview, VRPanorama, XRPanorama.

Initialization Configuration (FiveInitArgs)

Configuration object passed to the Five constructor.

interface FiveInitArgs {
  /** External WebGLRenderer. If provided, internal renderer creation is skipped. */
  renderer?: THREE.WebGLRenderer;

  /** Width/Height of the viewport relative to container (0-1). */
  viewport?: { left: number; bottom: number; width: number; height: number };

  /** Canvas background color. Default: 0x181A1C */
  backgroundColor?: number | THREE.Color;

  /** Canvas background alpha (0-1). Default: 1 */
  backgroundAlpha?: number;

  /** Enable antialiasing. Default: false */
  antialias?: boolean;

  /** Auto-play rendering loop. Default: true */
  play?: boolean;

  /** Enable on-demand rendering to save battery. Default: true */
  onlyRenderIfNeeds?: boolean;

  /** Max FPS limit. false = unlimited. Default: false */
  maxFps?: number | false;

  /** Mode transition duration in ms. Default: 1000 */
  modeChangeDuration?: number;

  /** Enable mouse wheel zoom. Default: true */
  enableWheel?: boolean;

  /** Initial plugins to load. */
  plugins?: FivePlugin[];

  /** Dynamic image configuration for optimization. */
  imageOptions?: ImageOptions;

  /** Dynamic texture configuration for optimization. */
  textureOptions?: TextureOptions;

  /** Request URL interceptor for auth/CDN. */
  requestProxy?: (url: string) => string | Promise<string>;

  /** Per-mode configuration (panorama, mapview, floorplan, topview, model). */
  panorama?: PanoramaConfig;
  mapview?: MapviewConfig;
  floorplan?: FloorplanConfig;
  topview?: TopviewConfig;
  model?: ModelConfig;
}
Copy

详细的模式配置参数见 Mode。 图片加载策略见 ImageOptions。 请求代理见 Request Proxy。 完整初始化参数见 Five 和 Parameter。

Core Methods

load(work, state?, options?)

Loads a "Work" (dataset) into the Five instance.

• work: The data object (LooseWork or Work) containing scene information.
• state: Initial state overrides. "inherit", "initial", or a State object.
• options: Loading options (e.g., transition duration, mode: "add" | "replace").

详见 Work 和 Multi-Work。

appendTo(element, size?)

Mounts the Five canvas to a DOM element.

• element: HTMLElement to append to.
• size: Optional { width, height }. Defaults to element size.

setState(state, immediately?, userAction?)

Updates the current state (position, mode, etc.).

• state: Partial State object to merge.
• immediately: If true, skips animation.
• userAction: Marks the change as triggered by user interaction.

详见 State。

changeMode(mode, state?, options?)

Switches the viewing mode (e.g., from Panorama to Model).

• mode: Target Five.Mode.
• state: Target state after mode change.
• options: Animation duration and effect.

详见 Mode。

moveToPano(panoIndex, options?)

Moves to a specific panorama spot.

• panoIndex: Index of the panorama.
• options: { effect?: MovePanoEffect, duration?: number, effectEasing?: Function }.

详见 Move Pano Effect 和 Camera Animation。

updateCamera(pose, duration, userAction?)

Animates the camera to a target pose without changing pano index.

• pose: Partial Pose object (longitude, latitude, fov, etc.).
• duration: Animation duration in ms.
• returns: Promise<void> (rejects if interrupted).

详见 Camera Animation。

ready(args?)

Returns a Promise that resolves when Five is stable (state synced, model loaded, optionally tiles loaded).

• args: { tile?: boolean } — if tile: true in Panorama mode, waits for tile loading.

refresh(size?)

Resizes the renderer to fit the container or specified size.

getElement()

Returns the <canvas> element used by Five.

project2d(vector, testModel?)

Projects a 3D point to 2D screen coordinates.

• vector: THREE.Vector3 (World Space).
• testModel: boolean (default false). If true, checks for occlusion.
• returns: THREE.Vector2 (Screen Space, px) or null.

详见 Screen & Space Projection。

getPixels(options)

Get pixel data from the renderer (e.g. for color picking or magnifier).

• options: { x, y, width, height, pixelRatio?, flipY?, buffer?, skipPanorama?, helperVisible? }
• returns: Uint8Array (RGBA data).

详见 Get Screen Pixels。

intersectRaycaster(raycaster)

(On five.model) Performs raycasting against the scene models.

• raycaster: THREE.Raycaster (supports extended props: firstHitOnly, hitFilter, sortByDistance, floorIndex).
• returns: THREE.Intersection[] (extended with tile, viewLayer, model fields).

详见 Raycast。

addPass(pass) / removePass(pass)

Add or remove a post-processing pass to/from the rendering chain.

• pass: FivePass instance (e.g. GaussianBlurPass, FlowingLight2DPass).

详见 Postprocessing。

updateConfiguration(config)

Dynamically update mode configurations after initialization (e.g., panorama, mapview settings).

详见 Mode。

dispose()

Destroys the Five instance and releases resources.

State Management

The State interface defines the complete status of the Five instance at any moment.

interface State {
  mode: Mode;          // Current view mode
  panoIndex: number;   // Current panorama index
  workCode: string;    // ID of the current work
  latitude: number;    // Camera latitude (radians)
  longitude: number;   // Camera longitude (radians)
  distance: number;    // Camera distance from target
  fov: number;         // Field of view
  offset: THREE.Vector3; // Camera target offset
}
Copy

Data Structures

以下为核心数据结构摘要。完整定义见 Work、State、Model。

Work

The main data object containing the scene description.

interface Work {
  workCode: string;          // Unique identifier
  name: string;             // Project name
  observers: WorkObserver[]; // List of panorama points
  model: WorkModel;          // 3D model data
  initial: WorkInitial;      // Initial view state
  transform: THREE.Matrix4;  // World transform matrix
}
Copy

WorkObserver (Panorama Point)

Represents a single panorama spot.

interface WorkObserver {
  index: number;             // Index in the list
  floorIndex: number;        // Floor number
  position: THREE.Vector3;   // Position in 3D space
  quaternion: THREE.Quaternion; // Rotation relative to model
  accessibleNodes: number[]; // Indices of reachable points
  images: WorkImage;         // Panorama image URLs
  active: boolean;           // Whether the point is enabled

  // Coordinate Methods
  getWorldPosition(): THREE.Vector3;
  getWorldStandingPosition(): THREE.Vector3;

  // UV Conversion Methods
  vectorToEquirectangularUv(vector: THREE.Vector3, uvOrigin?: 'top-left' | 'bottom-left'): THREE.Vector2;
  equirectangularUvToVector(uv: THREE.Vector2, uvOrigin?: 'top-left' | 'bottom-left'): THREE.Vector3;
  vectorToCubemapUv(vector: THREE.Vector3, uvOrigin?: 'top-left' | 'bottom-left'): [CubeFace, THREE.Vector2];
  cubemapUvToVector(cubeFace: CubeFace, uv: THREE.Vector2, uvOrigin?: 'top-left' | 'bottom-left'): THREE.Vector3;
}
Copy

Events

Five extends Subscribe, allowing event listening via .on(), .once(), and .off().

The SDK provides a modern event system (dot-notation, e.g., gesture.tap) which is recommended over the legacy system (camelCase, e.g., wantsTapGesture).

Recommended Events (Modern)

These events follow a standard naming convention and provide typed event objects.

Interaction & Gestures

Event Name	Description	Payload
gesture.tap	Triggered on tap/click. Replaces wantsTapGesture.	GestureEvent
gesture.dbltap	Triggered on double tap/click.	GestureEvent
gesture.pan	Triggered on pan/drag.	GestureEvent
gesture.pinch	Triggered on pinch/zoom.	GestureEvent
gesture.press	Triggered on long press.	GestureEvent
gesture.mousewheel	Triggered on mouse wheel scroll.	GestureEvent
gesture.mousemove	Triggered on mouse move.	GestureEvent
gesture.momentum	Triggered on inertia movement after pan.	GestureEvent
gesture.fire	Triggered when any gesture event fires.	GestureEvent

手势事件详解及不同 Mode 下的默认行为见 Gesture。

State & Mode

Event Name	Description	Payload
mode.change	Triggered when mode changes.	ModeChangeEvent
state.change	Triggered when state changes (frequent).	StateEvent
camera.update	Triggered when camera pose updates.	CameraEvent

状态管理详见 State，模式切换详见 Mode。

Lifecycle & Resources

Event Name	Description	Payload
works.load	Triggered when work data starts loading.	WorksEvent
works.ready	Triggered when work data is loaded and controller is ready.	WorksEvent
models.load	Triggered when models are loaded.	ModelSceneEvent
models.refined	Triggered when all models finish texture refinement.	ModelSceneEvent
model.load	Triggered when a single model geometry is loaded.	ModelEvent
model.tileLoad	Triggered when a 3D tile is loaded.	ModelTileEvent
model.tileUnload	Triggered when a 3D tile is unloaded.	ModelTileEvent
model.changeShownFloor	Triggered when floor visibility changes.	ModelEvent
model.error	Triggered when model loading fails.	ModelErrorEvent
pano.prepare	Triggered before switching to a new pano. ExtendableEvent, supports waitUntil.	PanoPrepareEvent
pano.arrived	Triggered when arrival at a panorama node.	PanoEvent
pano.moving	Triggered during pano transition animation.	PanoEvent
pano.error	Triggered when pano loading or movement fails.	PanoEvent
pano.texture.progress	Triggered when panorama texture loading progresses.	PanoTextureEvent
render	Triggered after each render frame.	RenderEvent
render.prepare	Triggered before each render frame.	RenderEvent
error	Triggered on internal errors.	Error

事件系统详解见 Event。手势事件详解见 Gesture。 pano.prepare 的 waitUntil / preventDefault 用法见 Event - Event 对象。 模型生命周期事件见 Model 和 Load Progress。

Legacy Events (Deprecated)

Older events are still supported for compatibility but should be avoided in new code.

Legacy Event	Recommended Replacement	Notes
wantsTapGesture	gesture.tap
wantsPanGesture	gesture.pan
modelLoaded	models.load
initAnimationEnded	mode.change	Check payload for details

Usage Example

// Recommended: Use the new event system
five.on('gesture.tap', (event) => {
  console.log('User tapped at:', event);
});

// Legacy (Avoid):
// five.on('wantsTapGesture', (raycaster) => { ... });
Copy