# 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);

### 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;
    }

> 详细的模式配置参数见 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
    }

## 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
    }

### `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;
    }

## 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`. Event includes `options` (modifiable to affect transition), `prevMode`, `prevPano`, and `pano`. | `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) => { ... });