@realsee/five/ai_guides/api.md

Realsee Renderer SDK

# 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

```typescript
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.

```typescript
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](./features/mode.md#configuration)。
> 图片加载策略见 [ImageOptions](./features/image-options.md)。
> 请求代理见 [Request Proxy](./features/request-proxy.md)。
> 完整初始化参数见 [Five](./features/five.md) 和 [Parameter](./features/parameter.md)。

## 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](./features/work.md) 和 [Multi-Work](./features/multi-work.md)。

### `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](./features/state.md)。

### `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](./features/mode.md)。

### `moveToPano(panoIndex, options?)`
Moves to a specific panorama spot.

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

> 详见 [Move Pano Effect](./features/move-pano-effect.md) 和 [Camera Animation](./features/camera-animation.md)。

### `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](./features/camera-animation.md)。

### `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](./features/screen-project.md)。

### `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](./features/get-screen-pixels.md)。

### `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](./features/raycast.md)。

### `addPass(pass)` / `removePass(pass)`
Add or remove a post-processing pass to/from the rendering chain.

- **pass**: `FivePass` instance (e.g. `GaussianBlurPass`, `FlowingLight2DPass`).

> 详见 [Postprocessing](./features/postprocessing.md)。

### `updateConfiguration(config)`
Dynamically update mode configurations after initialization (e.g., panorama, mapview settings).

> 详见 [Mode](./features/mode.md#动态修改配置-update-configuration)。

### `dispose()`
Destroys the Five instance and releases resources.

## State Management

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

```typescript
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](./features/work.md)、[State](./features/state.md)、[Model](./features/model.md)。

### `Work`
The main data object containing the scene description.

```typescript
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.

```typescript
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](./features/gesture.md)。

#### 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](./features/state.md)，模式切换详见 [Mode](./features/mode.md)。

#### 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](./features/event.md)。手势事件详解见 [Gesture](./features/gesture.md)。
> `pano.prepare` 的 `waitUntil` / `preventDefault` 用法见 [Event - Event 对象](./features/event.md#event-对象)。
> 模型生命周期事件见 [Model](./features/model.md#events) 和 [Load Progress](./features/load-progress.md)。

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

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

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