@realsee/five-webgpu 1.0.0-alpha.1

package/ai_guides/features/clipper.md

@@ -0,0 +1,135 @@
+# 模型裁切 (Model Clipper)
+
+- **Summary**: 使用 `parameter.clippers` 定义裁切盒，用于隐藏 (discard) 模型中特定区域的点云或网格。
+- **Schema**: `PBMClipperParameter` 数组，包含变换矩阵和楼层索引。
+- **Concepts**: Clipping Box (裁切盒), Matrix Transformation (矩阵变换), Negative Space (负空间).
+- **Configuration**: `five.model.clippers`.
+- **Examples**: 创建裁切盒并应用。
+
+## Schema
+
+> **Definition**: [PBMClipperParameter](../../five/model/materials/pbmMaterial.d.ts)
+
+```typescript
+/** 模型裁切参数 */
+interface PBMClipperParameter {
+  /**
+   * 裁切盒的变换矩阵。
+   * @description
+   * 定义了一个变换后的立方体空间。
+   * 基础形状为边长为 1 的立方体，中心在 (0,0,0)，范围 [-0.5, 0.5]。
+   * 凡是落在这个变换后立方体内部的模型点，都会被丢弃 (discard)。
+   */
+  clippingBoxMatrix: THREE.Matrix4;
+
+  /**
+   * (可选) 楼层索引。
+   * @description
+   * 如果指定，则裁切仅对该楼层的点云生效。
+   * 如果未指定 (undefined)，则对所有楼层生效。
+   */
+  floorIndex?: number;
+}
+```
+
+## Concepts
+
+### Clipping Box (裁切盒)
+Five 的裁切机制是基于**负空间**的：
+- 默认情况下，所有模型点都是可见的。
+- 当你添加一个 Clipper 时，你实际上是在定义一个“不可见区域”。
+- 任何位于 Clipper 定义的 3D 盒体内部的点，都不会被渲染。
+
+### Matrix Transformation (矩阵变换)
+Clipper 的几何定义依赖于 `clippingBoxMatrix`。
+- shader 内部逻辑是将世界坐标系下的点，乘以 `clippingBoxMatrix` 的**逆矩阵**。
+- 然后判断该点是否在 `[-0.5, 0.5]` 的单位立方体范围内。
+- 这意味着你可以直接使用 `THREE.Mesh` (BoxGeometry 1x1x1) 的 `matrix` 属性作为 `clippingBoxMatrix`，所见即所得。
+
+## Configuration
+
+你可以通过 `five.model.clippers` 属性来读写裁切配置。
+
+| 属性 | 类型 | 说明 |
+| --- | --- | --- |
+| `five.model.clippers` | `PBMClipperParameter[]` | 设置裁切参数数组。设置新数组会覆盖旧配置。 |
+
+## Examples
+
+### 基础用法 (Basic Usage)
+
+创建一个不可见的 Box，将其位置和大小作为裁切区域。
+
+```typescript
+import * as THREE from 'three';
+import { Five } from '@realsee/five';
+
+// 1. 创建一个辅助 Mesh 来定义裁切区域
+// 注意：必须使用 1x1x1 的 BoxGeometry，因为 Shader 是基于单位立方体判断的
+const clipperMesh = new THREE.Mesh(
+  new THREE.BoxGeometry(1, 1, 1),
+  new THREE.MeshBasicMaterial({ color: 0xff0000, wireframe: true })
+);
+
+// 2. 设置裁切盒的位置、旋转和缩放
+clipperMesh.position.set(0, 1.5, 0); // 抬高位置
+clipperMesh.scale.set(2, 3, 2);      // 设定大小为 2x3x2
+clipperMesh.rotation.y = Math.PI / 4; // 旋转 45 度
+
+// 更新矩阵，确保 .matrix 属性是最新的
+clipperMesh.updateMatrix();
+
+// (可选) 将辅助 Mesh 加入场景以便调试看到范围
+five.scene.add(clipperMesh);
+
+// 3. 应用裁切参数
+five.model.clippers = [
+  {
+    clippingBoxMatrix: clipperMesh.matrix,
+    // floorIndex: 0 // 可选：仅裁切第 0 层
+  }
+];
+
+// 4. 触发重绘
+five.needsRender = true;
+```
+
+### 动态更新 (Dynamic Update)
+
+如果需要动态移动裁切盒，需要重新赋值 `five.model.clippers` 或手动触发更新机制（虽然 setter 会自动触发更新，但如果只修改数组内部对象可能需要重新赋值）。
+
+```typescript
+function updateClipper(mesh: THREE.Mesh) {
+  mesh.updateMatrix();
+
+  // 重新赋值以触发 Five 内部的 setter 和 uniform 更新
+  five.model.clippers = [{
+    clippingBoxMatrix: mesh.matrix
+  }];
+}
+
+// 在动画循环或交互事件中调用
+// ...
+```
+
+## Debugging
+
+- **辅助显示**: 始终建议在开发阶段将用于生成矩阵的 `THREE.Mesh` (Wireframe 模式) 添加到 `five.scene` 中，这样可以直观地看到裁切范围是否正确。
+- **单位问题**: 确保 `BoxGeometry` 构造时没有传入参数 (默认 1,1,1) 或者显式传入 `(1, 1, 1)`。如果使用了 `(10, 10, 10)` 的几何体，那么 `scale` 设置为 1 时实际裁切范围是 10，可能会导致误解。建议统一使用单位几何体 + `scale` 的方式。
+
+## Common Pitfalls
+
+1.  **矩阵未更新**: 修改了 Mesh 的 position/scale 后忘记调用 `updateMatrix()`，导致裁切位置没变。
+2.  **几何体尺寸**: 使用了非 `1x1x1` 的 BoxGeometry，导致裁切范围与 Mesh视觉大小不一致（Shader 始终假定是单位立方体）。
+3.  **楼层索引**: 设置了错误的 `floorIndex` 导致裁切看起来没生效（因为该区域的点可能属于另一个 floorIndex）。
+4.  **坐标系**: `clippingBoxMatrix` 是世界坐标系下的变换。如果模型本身有额外的父级变换（通常 Five 的模型直接在 Scene 下，或者是 Identity 变换），通常不需要额外处理。
+
+## Related
+
+*   [model.md](./model.md): 模型模块概览。
+
+---
+
+```yaml
+tags: [clipper, model, cut, discard, geometry]
+```

package/ai_guides/features/coordinate-system.md

@@ -0,0 +1,128 @@
+# 坐标系 (Coordinate System)
+
+- **Summary**: 详解 Five 中的坐标系定义（Local, ENU, ECEF）及其相互转换关系。
+- **Concepts**: Local (Y-up), ENU (Z-up), ECEF, ENU84, RootMeta, Observers.
+- **Configuration**: `rootMeta` `coordinate` 配置。
+- **Examples**: 坐标转换方法示例。
+
+## Schema
+
+> **Definition**: [TilesetHeader](../../five/model/tile3d/header.d.ts)
+
+### RootMeta
+
+3D Tiles `rootMeta` 字段中定义的坐标系元数据。
+
+```typescript
+interface RootMeta {
+  /** 模型垂直轴向 (如 "Z", "-Y") */
+  upAxis?: string;
+  /** 坐标系转换矩阵信息 */
+  coordinate?: Coordinate;
+}
+```
+
+### Coordinate
+
+描述 ECEF 与 ENU 之间的转换关系。
+
+```typescript
+interface Coordinate {
+  /** 地面高度 */
+  ground_height?: number;
+  /** ECEF 到 ENU 的转换矩阵 (4x4 数组) */
+  pose_ecef_to_enu?: number[];
+  /** ENU 到 ECEF 的转换矩阵 (4x4 数组) */
+  pose_enu_to_ecef?: number[];
+}
+```
+
+## Concepts
+
+### Local Coordinate System (Y-up)
+Five 的渲染场景 (`five.scene`) 和 Observers (观察点) 使用 **Y-up** (Y 轴向上) 的右手坐标系。
+这与 Three.js 的默认坐标系一致，便于前端开发和场景渲染。
+- **Y 轴**: 垂直向上。
+- **X/Z 轴**: 水平平面。
+
+### ENU Coordinate System (Z-up)
+在本项目及相关算法交互中，**ENU** 指代 **Z-up** (Z 轴向上) 的坐标系。这是为了和测绘行业习惯保持一致。
+- **Z 轴**: 垂直向上。
+- **X/Y 轴**: 水平平面。
+- **ENU84**: 特指 Y 轴正向指向正北 (North) 的 ENU 坐标系。（注：普通的 ENU 坐标系中，北向不一定对应 Y 轴，这与部分行业标准有所区别）。
+- **用途**: 推荐在给算法或后端接口传递模型数据时，使用 ENU 坐标系。
+
+### ECEF Coordinate System
+地心地固坐标系 (Earth-Centered, Earth-Fixed)。
+- 当模型包含 RTK (Real-time kinematic) 信息时，通常基于 ECEF 坐标系进行描述。
+- 可以通过 `ecefToEnu` 方法将 ECEF 坐标转换为 ENU 坐标。
+
+### Model Orientation (at3d / 3dtiles)
+模型 (如 `.at3d`, 3D Tiles) 的加载逻辑遵循以下原则：
+1.  **无 RTK 信息**: 默认为 **Z-up** (ENU)。
+2.  **有 RTK 信息**: 遵循 **ECEF** 坐标系。
+3.  **自动对齐**: Five 加载模型时（load 方法），会自动处理旋转和坐标系转换，将其对齐到 Five 的 Local (Y-up) 坐标系中。
+    - 开发者在 `five.scene` 中看到的所有模型都已处于统一的 Y-up 坐标系下。
+
+### Coordinate in Files
+在 3D Tiles 的 `tileset.json` 中，`rootMeta` 字段用于描述坐标系转换信息（没有该字段则默认 Z-up）：
+- 包含 `pose_ecef_to_enu` 和 `pose_enu_to_ecef` 变换矩阵。
+- Five 读取这些信息来计算并构建完整的坐标转换链, 进行模型-观察点的坐标对齐。
+
+在 model 的 `coordinate` 字段用于描述坐标系转换信息（没有该字段则默认 Z-up）：
+- 包含 `pose_ecef_to_enu` 和 `pose_enu_to_ecef` 变换矩阵。
+- Five 读取这些信息来计算并构建完整的坐标转换链，确保模型-观察点的坐标对齐。
+
+## Instance Methods
+
+`ViewLayer` (继承自 `Tile3D`) 提供了成套的坐标转换方法，用于在 Local, ENU, ECEF 和 World 之间进行转换。
+
+| 方法名 | 说明 |
+| --- | --- |
+| `localToEnu(vector)` | Local (Y-up) -> ENU (Z-up) |
+| `enuToLocal(vector)` | ENU (Z-up) -> Local (Y-up) |
+| `enuToEcef(vector)` | ENU (Z-up) -> ECEF |
+| `ecefToEnu(vector)` | ECEF -> ENU (Z-up) |
+| `localToEcef(vector)` | Local (Y-up) -> ECEF |
+| `ecefToLocal(vector)` | ECEF -> Local (Y-up) |
+| `worldToEnu(vector)` | World -> ENU (Z-up) |
+| `enuToWorld(vector)` | ENU (Z-up) -> World |
+
+> 注: `World` 坐标系通常指 Three.js 的世界坐标 (即 `five.scene` 的坐标)。在未通过 `Object3D` 层级嵌套偏移的情况下，`World` 等同于 `Local`。
+
+## Examples
+
+### 坐标转换 (Coordinate Transformation)
+
+推荐在与后端或算法交互时，将 Local 坐标转换为 ENU 坐标。
+
+```typescript
+import * as THREE from 'three';
+import { ViewLayer } from '@realsee/five';
+
+// 假设已加载 ViewLayer
+const viewLayer: ViewLayer = ...;
+
+// 1. 获取场景中某点的坐标 (Local Y-up)
+const localPosition = new THREE.Vector3(10, 20, 30);
+
+// 2. 转换为 ENU 坐标 (Z-up) 用于传输给后端/算法
+const enuPosition = viewLayer.localToEnu(localPosition.clone());
+
+console.log(`Local: ${localPosition.toArray()}`); // [x, y, z] (y-up)
+console.log(`ENU: ${enuPosition.toArray()}`);     // [x, y, z] (z-up)
+
+// 3. 将 ECEF 坐标转换为 Local 坐标用于显示
+const ecefPosition = new THREE.Vector3( ... );
+const displayPosition = viewLayer.ecefToLocal(ecefPosition.clone());
+```
+
+## Related
+
+*   [load-external-model.md](./load-external-model.md): 加载外部模型时的坐标轴配置 (`upAxis`, `modelUpAxis`)。
+
+---
+
+```yaml
+tags: [coordinate-system, enu, ecef, z-up, y-up, transform]
+```

package/ai_guides/features/event.md

@@ -0,0 +1,154 @@
+# Events (事件系统)
+
+- **Summary**: Five 提供了一套基于发布/订阅模式的事件系统，用于监听用户交互、状态变更、数据加载及渲染生命周期。
+- **Schema**: `on` / `once` / `off` 接口定义。
+- **Concepts**: Gesture Events, State Events, Pano Events, Model Events, Lifecycle Events.
+- **Examples**: 监听全景移动、手势交互及状态变更。
+
+## Schema
+
+> **Definition**: [Five](../../five/application/five.d.ts), [EventTypes](../../five/application/events.d.ts)
+
+Five 实例提供了以下方法来管理事件监听：
+
+### on
+注册持久化事件监听器。
+
+```typescript
+five.on(
+  name: string,
+  callback: (...args: any[]) => void,
+  once?: boolean
+): () => void
+```
+
+- **name**: 事件名称（支持的事件见 Concepts）。
+- **callback**: 事件触发时的回调函数。
+- **once**: (可选) 是否仅执行一次，默认为 `false`。
+- **返回**: 一个函数，调用该函数可取消当前监听。
+
+### once
+注册一次性事件监听器（触发一次后自动销毁）。
+
+```typescript
+five.once(
+  name: string,
+  callback: (...args: any[]) => void
+): () => void
+```
+
+### off
+取消事件监听。
+
+```typescript
+five.off(
+  name?: string,
+  callback?: (...args: any[]) => void
+): void
+```
+
+- **name**: (可选) 若不传，则清空所有事件；若传，则取消指定类型的事件。
+- **callback**: (可选) 若传，则仅取消该特定的回调函数；若不传，则取消该类型下的所有回调。
+
+## Concepts
+
+Five 的事件系统将事件主要分为以下几类：
+
+### Gesture Events (交互手势)
+监听用户的鼠标或触摸操作。
+
+- `gesture.tap`: 点击/轻触。
+- `gesture.dbltap`: 双击/双击轻触。
+- `gesture.press`: 长按。
+- `gesture.pan`: 平移/拖拽。
+- `gesture.pinch`: 缩放（双指或滚轮）。
+- `gesture.mousewheel`: 鼠标滚轮滚动。
+- `gesture.mousemove`: 鼠标移动。
+
+### Pano Events (全景导航)
+监听全景图的点位切换过程。
+
+- `pano.arrived`: 成功到达新点位（移动动画结束）。
+- `pano.moving`: 正在移动到新点位（动画进行中）。
+- `pano.willChange`: 即将发生点位变更（旧版兼容）。
+- `pano.error`: 点位加载或移动出错。
+
+### State Events (状态变更)
+监听 Five 内部状态（State）的变化，常用于 UI 同步或数据记录。
+
+- `state.change`: 状态发生变更（可能是用户操作或代码触发）。
+- `currentState.change`: 当前状态发生变更（通常指即时状态）。
+- `state.synced`: 状态已同步。
+
+### Model & Work Events (数据加载)
+监听场景数据（Work）或模型（Model）的加载生命周期。
+
+- `works.load`: Work 数据开始加载。
+- `works.ready`: Work 数据加载完成且 Controller 就绪。
+- `model.load`: 模型开始加载。
+- `models.load`: 所有模型加载完成。
+
+### Render Events (渲染循环)
+监听每一帧的渲染过程。
+
+- `render`: 每一帧渲染后触发。
+- `render.prepare`: 每一帧渲染前触发。
+
+## Examples
+
+### 快速上手 (Quick Example)
+监听点击事件并打印日志。
+
+```typescript
+import { Five } from "@realsee/five";
+
+const five = new Five();
+
+// 监听点击事件
+five.on("gesture.tap", (pose) => {
+  console.log("User tapped at:", pose);
+});
+
+// 监听点位变更完成
+five.on("pano.arrived", (index) => {
+  console.log("Arrived at pano index:", index);
+});
+```
+
+### 进阶用法 (Advanced Usage)
+使用 `once` 监听一次性初始化事件，使用返回值取消监听。
+
+```typescript
+// 1. 等待首次数据加载完成
+five.once("works.ready", () => {
+  console.log("Five is ready!");
+  // 执行初始化逻辑，如自动巡游
+});
+
+// 2. 动态绑定与解绑
+const onRender = () => {
+  // 每一帧执行的逻辑
+  updateUI();
+};
+
+// 开始监听
+five.on("render", onRender);
+
+// 在某个时刻取消监听（例如组件销毁时）
+// five.off("render", onRender);
+```
+
+## Debugging
+
+- 使用 `five.on("error", (err) => console.error(err))` 捕获全局错误。
+
+## Related
+
+- [state.md](./state.md): 了解 State 的结构与变更机制。
+- [five.md](./five.md): Five 核心类说明。
+
+---
+
+```yaml
+tags: [events, interaction, lifecycle, gesture, state]
+```

package/ai_guides/features/five.md

@@ -0,0 +1,184 @@
+# Five (Five 核心类)
+
+- **Summary**: Five 是 @realsee/five 的核心类，负责 3D 场景的渲染、资源加载、用户交互和状态管理。
+- **Schema**: FiveInitArgs 初始化参数接口。
+- **Concepts**: Instance Management, Rendering Loop, Resource Loading, State Sync.
+- **Configuration**: Five 初始化参数详解。
+- **Examples**: 基础初始化、加载数据、销毁实例。
+
+## Schema
+
+### FiveInitArgs
+
+> **Definition**: [FiveInitArgs](../../five/application/fiveInitArgs.d.ts)
+
+`new Five(args)` 的初始化参数对象。
+
+```typescript
+interface FiveInitArgs {
+  /** 外部传入的渲染器 (如果传入，部分渲染配置将失效) */
+  renderer?: THREE.WebGLRenderer;
+  /**
+   * 屏幕渲染区域 { left, bottom, width, height }
+   * 必须配合外部 renderer 使用
+   */
+  viewport?: Viewport;
+  /** 背景颜色 (默认 0x181A1C) */
+  backgroundColor?: number | THREE.Color;
+  /** 背景透明度 (0-1, 默认 1) */
+  backgroundAlpha?: number;
+  /** 是否开启抗锯齿 (默认 false) */
+  antialias?: boolean;
+  /** 全景图配置 (见 image-options.md) */
+  imageOptions?: ImageOptions;
+  /** 贴图配置 (见 image-options.md) */
+  textureOptions?: TextureOptions;
+  /** 是否按需渲染 (默认 true, 推荐开启以节省性能) */
+  onlyRenderIfNeeds?: boolean;
+  /** 模式切换动画时长 (ms, 默认 1000) */
+  modeChangeDuration?: number;
+  /** 是否支持滚轮缩放 (默认 true) */
+  enableWheel?: boolean;
+  /** 插件列表 */
+  plugins?: FivePlugin[];
+  /** 是否显示 Powered by Realsee */
+  poweredByRealsee?: boolean;
+}
+```
+
+## Concepts
+
+### Instance Management (实例管理)
+Five 实例是整个 3D 场景的入口。
+- **Singleton-like**: 虽然支持多实例，但在同一个 DOM 容器中通常只维护一个 Five 实例。
+- **Lifecycle**: 包含 `appendTo` (挂载)、`load` (加载数据)、`dispose` (销毁) 等生命周期方法。
+
+### Rendering Loop (渲染循环)
+Five 内部维护了一个 `requestAnimationFrame` 循环。
+- **按需渲染**: 默认开启 `onlyRenderIfNeeds`，仅在画面发生变化（如视角移动、数据加载）时才触发 WebGL 绘制，大幅降低能耗。
+- **手动触发**: 可以通过 `five.needsRender = true` 强制下一帧进行渲染。
+
+### Resource Loading (资源加载)
+通过 `load()` 方法加载 Work 数据。
+- **数据解析**: 自动解析 Work 数据结构，生成场景图。
+- **预加载**: 支持配置预加载策略，平衡首屏速度与流量。
+
+## Configuration
+
+| 参数 | 类型 | 默认值 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `imageOptions` | `ImageOptions` | `{}` | 图片加载策略，详见 [image-options.md](./image-options.md) |
+| `textureOptions` | `TextureOptions` | `{}` | 贴图加载策略，同上 |
+| `onlyRenderIfNeeds` | `boolean` | `true` | 是否仅在需要时渲染，建议保持 `true` |
+| `antialias` | `boolean` | `false` | 抗锯齿，开启会增加性能消耗 |
+| `modeChangeDuration` | `number` | `1000` | 模式切换动画时长 (ms) |
+| `enableWheel` | `boolean` | `true` | 是否支持滚轮缩放 |
+
+## Examples
+
+### 快速上手 (Quick Example)
+创建一个全屏的 Five 实例并加载数据。
+
+```typescript
+import { Five, parseWork } from "@realsee/five";
+
+// 1. 初始化实例
+const five = new Five({
+  imageOptions: { size: 512 }, // 初始加载小图
+  onlyRenderIfNeeds: true
+});
+
+// 2. 挂载到 DOM
+five.appendTo(document.getElementById("app"));
+
+// 3. 加载数据
+// workData 通常来自服务端 API
+five.load(workData);
+```
+
+### 进阶用法：自定义渲染器与视口
+使用外部渲染器并指定视口区域（例如用于分屏渲染）。
+
+```typescript
+import * as THREE from "three/webgpu";
+import { Five } from "@realsee/five";
+
+const renderer = new THREE.WebGLRenderer();
+renderer.setSize(window.innerWidth, window.innerHeight);
+document.body.appendChild(renderer.domElement);
+
+const five = new Five({
+  renderer: renderer,
+  viewport: { left: 0, bottom: 0, width: 0.5, height: 1 } // 仅占用左半屏
+});
+
+five.load(workData);
+```
+
+### 进阶用法：自定义相机动画
+
+使用 `updateCamera` 或 `updateCameraWithKeyframes` 实现平滑的视角漫游。
+
+```typescript
+// 简单移动到指定视角
+five.updateCamera(
+  { longitude: Math.PI / 2, latitude: 0 }, // 目标姿态
+  1000 // 动画时长 1秒
+).then(() => {
+  console.log("移动完成");
+}).catch(() => {
+  console.log("移动被打断");
+});
+
+// 复杂关键帧动画
+const keyframes = [
+  { progress: 0, value: { longitude: 0, latitude: 0 } },
+  { progress: 0.5, value: { longitude: Math.PI / 4, latitude: 0.2 } },
+  { progress: 1, value: { longitude: Math.PI / 2, latitude: 0 } }
+];
+
+five.updateCameraWithKeyframes(keyframes, 2000).then(() => {
+  console.log("关键帧动画完成");
+});
+```
+
+### 实例属性 (Instance Properties)
+
+- **`work`**: 当前加载的 Work 数据（主 Work）。详见 [work.md](./work.md)。
+- **`works`**: 当前加载的所有 Work 数据列表。详见 [work.md](./work.md)。
+- **`model`**: 当前加载的 Model 数据（主 Model）。详见 [model.md](./model.md)。
+- **`models`**: 当前加载的所有 Model 数据列表。详见 [model.md](./model.md)。
+
+### 实例方法 (Instance Methods)
+
+- **`appendTo(element: HTMLElement)`**: 将 canvas 挂载到指定 DOM 元素。
+- **`load(work: Work, state?: State, duration?: number)`**: 加载场景数据。详见 [work.md](./work.md)。
+- **`dispose()`**: 销毁实例，释放 WebGL 上下文与内存。
+- **`updateCamera(pose: Partial<Pose>, duration: number, userAction?: boolean)`**: 移动相机（不触发点位移动）。移动相机的视角或位置，不会改变当前所在的 PanoIndex。如果动画中途被打断，Promise 会被 reject。
+- **`updateCameraWithKeyframes(keyframes: { progress: number; value: Pose; key?: string }[], duration: number, userAction?: boolean)`**: 通过关键帧动画移动相机。
+- **`refresh()`**: 强制刷新画布尺寸。通常在窗口 resize 时调用，Five 会自动监听 resize，但在某些布局变化场景下可能需要手动调用。
+- **`getPixels(x, y, width, height, ...)` / `getPixels(options)`**: 获取画布指定区域的像素数据。常用于截图、生成缩略图或颜色拾取。支持配置区域、像素比 (pixelRatio)、Y轴翻转 (flipY) 及是否忽略全景图 (skipPanorama) 等。
+- **`project2d(vector: THREE.Vector3, testModel?: boolean): THREE.Vector2 | null`**: 计算三维坐标对应到屏幕的二维坐标。如果坐标在视野外或被遮挡（开启 testModel 时），返回 null。详见 [screen-project.md](./screen-project.md)。
+- **`ready(args?: { tile?: boolean })`**: Promise，当 Five 状态稳定时 resolve。
+  - **Resolve 时机**：
+    1. **状态同步**：相机姿态已通过动画过渡到目标状态（`stateSynced` 为 true）。
+    2. **模型加载**：如果是 Floorplan/Topview/Mapview/Model 模态，需等待模型加载完成 (`modelScene.loaded`)。
+    3. **瓦片加载**：如果是 Panorama 模态且传入了 `{ tile: true }`，需等待当前视角的瓦片加载完成。
+- **`setState(state: Partial<State>, options?: ChangeStateOptions)`**: 变更当前状态（如点位、视角）。详见 [state.md](./state.md)。
+- **`on(event, callback)` / `off(event, callback)`**: 事件监听。详见 [event.md](./event.md)。
+
+## Related
+
+*   [work.md](./work.md): Work 数据结构说明。
+*   [model.md](./model.md): Model 数据结构说明。
+*   [state.md](./state.md): 状态管理详解。
+*   [event.md](./event.md): 事件系统说明。
+*   [image-options.md](./image-options.md): 图片加载配置。
+*   [mode.md](./mode.md): 模态切换说明。
+*   [parameter.md](./parameter.md): 其他核心参数。
+
+---
+
+```yaml
+tags: [five, initialization, core, instance, lifecycle]
+```