@realsee/five 6.8.0-alpha.1 → 6.8.0-alpha.11

package/ai_guides/features/plugin.md

@@ -0,0 +1,210 @@
+# 插件系统 (Plugin System)
+
+- **Summary**: Five 插件系统基于 `BasePlugin` 命名空间构建，提供了一套标准化的状态管理、生命周期控制和事件通信机制。
+- **Schema**: 核心类型定义位于 `BasePlugin` 命名空间。
+- **Concepts**: BasePlugin, State, Lifecycle, Controller.
+- **Configuration**: 插件特定的参数配置。
+- **Examples**: 标准插件开发示例。
+
+## Schema
+
+> **Definition**: [BasePlugin](../../plugins/BasePlugin/index.d.ts)
+
+`BasePlugin` 是一个命名空间，包含 `Controller` (抽象基类), `State` (状态接口), `EventMap` (事件映射) 等核心定义。
+
+```typescript
+export namespace BasePlugin {
+  export interface State {
+    enabled: boolean
+    visible?: boolean
+    config?: unknown
+  }
+  export abstract class Controller<PluginState, PluginEventMap, PluginServerData, PluginData> {
+    public five: Five
+    public abstract state: PluginState
+    public hooks: Subscribe<PluginEventMap>
+    // ...
+  }
+}
+```
+
+## Concepts
+
+### Directory Structure (目录结构)
+
+一个标准的插件通常包含以下文件：
+
+```text
+PluginName/
+  ├── index.ts        # 插件入口，导出工厂函数和类型
+  ├── Controller.ts   # 插件控制器，核心逻辑实现
+  └── typing.ts       # 类型定义
+```
+
+### BasePlugin
+
+所有插件推荐继承 `BasePlugin.Controller`。它定义了规范的泛型接口：
+
+- `PluginState`: 插件状态类型，继承自 `BasePlugin.State`。
+- `PluginEventMap`: 插件事件类型，继承自 `BasePlugin.EventMap`。
+- `PluginServerData`: 服务端原始数据类型。
+- `PluginData`: 解析后的插件数据类型。
+
+### State (状态)
+
+插件的状态驱动其行为。`BasePlugin.State` 定义了最基本的状态：
+
+- `enabled`: 是否启用。
+- `visible`: UI 是否可见。
+- `config`: 配置项。
+
+### Lifecycle (生命周期)
+
+插件的主要生命周期方法：
+
+- **constructor**: 初始化配置和初始状态。
+- **load**: 加载和解析数据。
+- **enable**: 启用插件，注册事件监听，添加副作用。
+- **disable**: 禁用插件，移除事件监听，清理副作用。
+- **dispose**: 销毁插件，彻底清理资源。
+
+## Configuration
+
+### BasePlugin Configuration
+
+`BasePlugin` 控制器构造函数接受可选的配置对象：
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `staticPrefix` | `string` | `'//vr-image-4.realsee-cdn.cn'` | 静态资源前缀。 |
+| `i18n` | `(key: string) => string` | `undefined` | 国际化转换函数。 |
+
+## Examples
+
+### Plugin Development Walkthrough (插件开发指南)
+
+以创建一个 `MyPlugin` 为例。
+
+#### 1. 定义类型 (typing.ts)
+
+定义插件所需的参数、状态、数据和事件类型。
+
+```typescript
+import { BasePlugin } from '../BasePlugin'
+
+// 1. 定义参数
+export interface Params extends BasePlugin.Config {
+  initialState?: Partial<State>
+  config?: Config
+}
+
+// 2. 定义配置
+export interface Config {
+  color?: string
+}
+
+// 3. 定义状态 (继承 BasePlugin.State)
+export interface State extends BasePlugin.State {
+  activeId?: string
+}
+
+// 4. 定义数据类型
+export interface ServerData { /* 服务端数据结构 */ }
+export interface PluginData { /* 解析后的数据结构 */ }
+
+// 5. 定义事件 (继承 BasePlugin.EventMap)
+export interface EventMap extends BasePlugin.EventMap<State, PluginData> {
+  click: (id: string) => void
+}
+```
+
+#### 2. 实现控制器 (Controller.ts)
+
+继承 `BasePlugin.Controller` 并实现核心逻辑。
+
+```typescript
+import { Five } from '@realsee/five'
+import { BasePlugin } from '../BasePlugin'
+import * as MyPluginType from './typing'
+
+export class Controller extends BasePlugin.Controller<
+  MyPluginType.State,
+  MyPluginType.EventMap,
+  MyPluginType.ServerData,
+  MyPluginType.PluginData
+> {
+  public state: MyPluginType.State
+
+  constructor(five: Five, params?: MyPluginType.Params) {
+    super(five)
+    this.state = {
+      enabled: true,
+      visible: true,
+      ...params?.initialState
+    }
+    if (this.state.enabled) {
+      this._enable()
+    }
+  }
+
+  public async load(serverData: MyPluginType.ServerData) {
+    // 解析数据
+  }
+
+  public enable() {
+    if (this.state.enabled) return
+    this.state.enabled = true
+    this._enable()
+    this.hooks.emit('stateChange', { state: this.state, userAction: true })
+  }
+
+  public disable() {
+    if (!this.state.enabled) return
+    this.state.enabled = false
+    this._disable()
+    this.hooks.emit('stateChange', { state: this.state, userAction: true })
+  }
+
+  public dispose = () => {
+    this.disable()
+    this.hooks.emit('dispose')
+  }
+
+  private _enable() {
+    // five.scene.add(...)
+    // five.on('tap', this.onTap)
+  }
+
+  private _disable() {
+    // five.scene.remove(...)
+    // five.off('tap', this.onTap)
+  }
+}
+```
+
+#### 3. 导出插件 (index.ts)
+
+提供一个工厂函数。
+
+```typescript
+import { Five } from '@realsee/five'
+import { Controller } from './Controller'
+import * as MyPluginType from './typing'
+
+export const MyPlugin = (five: Five, params?: MyPluginType.Params) =>
+  new Controller(five, params)
+
+export type { MyPluginType, Controller as MyPluginController }
+```
+
+## Common Pitfalls (最佳实践)
+
+1. **状态驱动**: 始终通过修改 `state` 来驱动插件行为，而不是直接操作 DOM 或 3D 对象。
+2. **清理资源**: 在 `disable` 和 `dispose` 中务必清理所有事件监听和副作用，防止内存泄漏。
+3. **类型安全**: 充分利用 TypeScript 泛型，确保事件和状态的类型安全。
+
+---
+
+```yaml
+tags: [plugin, baseplugin, development, guide]
+```

package/ai_guides/features/postprocessing.md

@@ -0,0 +1,259 @@
+# 后处理 (Post Processing)
+
+- **Summary**: Five 提供了基于 EffectComposer 的后处理机制，默认挂载了自适应亮度 (Auto Exposure) 和眼球穹顶光照 (EDL) 两种效果，同时提供多种可选内置 Pass，并支持开发者编写自定义 Pass。
+- **Schema**: `FivePass` 类及 `Pass` 接口。
+- **Concepts**: EffectComposer, G-Buffer, Pass, AdaptiveLuminance, EyeDomeLighting。
+- **Configuration**: 开启内置 Pass 的开关及参数配置。
+- **Examples**: 开启内置 Pass 示例，自定义黑白滤镜 Pass 示例。
+
+## Schema
+
+> **Definition**: [FivePass](../../five/renderer/postprocessing/passes/pass.d.ts)
+
+```typescript
+/**
+ * Pass 接口 (兼容 three.js EffectComposer)
+ */
+export interface Pass {
+  enabled: boolean;
+  needsSwap: boolean;
+  clear: boolean;
+  renderToScreen: boolean;
+  setSize(width: number, height: number): void;
+  render(
+    renderer: THREE.WebGLRenderer,
+    writeBuffer: THREE.WebGLRenderTarget,
+    readBuffer: THREE.WebGLRenderTarget,
+    deltaTime?: number,
+    maskActive?: boolean
+  ): void;
+}
+
+/**
+ * FivePass 基类
+ * 支持 G-Buffer 注入 (depth, normal, color)
+ */
+export class FivePass implements Pass {
+  public enabled: boolean = true;
+  public needsSwap: boolean = true;
+  public clear: boolean = false;
+  public renderToScreen: boolean = true;
+  public dependencies: ('depth' | 'normal' | 'color')[];
+
+  // 由 EffectComposer 在 render 时注入
+  public gbuffer!: Map<'depth' | 'normal' | 'color', THREE.Texture>;
+
+  constructor(dependencies?: ('depth' | 'normal' | 'color')[]);
+  // ... render method implementation
+}
+```
+
+## Concepts
+
+- **EffectComposer**: 后处理管理器，负责按顺序执行 Pass，管理渲染目标 (RenderTarget) 和 G-Buffer。
+- **FivePass**: Five 引擎优化的 Pass 基类。相比普通 Pass，它声明了 `dependencies`，Five 会在渲染 Pass 之前准备好所需的 G-Buffer (如深度图、法线图)，避免在每个 Pass 中重复渲染场景。
+- **AdaptiveLuminancePass (自适应亮度)**: 模拟人眼对光线的适应过程。当场景亮度变化时，会自动平滑调整曝光度，使画面保持在舒适的亮度范围内。
+- **EyeDomeLightingPass (EDL)**: 一种非真实感渲染技术，主要用于增强点云模型的深度感知。通过屏幕空间的深度差计算遮蔽效果，让点云看起来更有轮廓感。
+
+## Built-in Passes (内置 Pass)
+
+Five 默认挂载了两个 Pass 实例，挂载在 `five` 实例上，默认是关闭状态。
+
+### 1. AdaptiveLuminancePass
+
+位于 `five.adaptiveLuminancePass`。
+
+*   **作用**: 自动调整画面曝光。
+*   **开启方式**: `five.adaptiveLuminancePass.enabled = true`。
+*   **配置项**:
+    *   `luminanceScale` (number): 亮度缩放系数，影响最终画面的整体亮度。
+    *   `luminanceStep` (number): 亮度适应步长，影响适应速度。
+
+### 2. EyeDomeLightingPass
+
+位于 `five.eyeDomeLightingPass`。
+
+*   **作用**: 增强点云的轮廓和深度感。
+*   **开启方式**: `five.eyeDomeLightingPass.enabled = true`。
+*   **配置项**:
+    *   `strength` (number): 增强强度，值越大轮廓越明显。
+    *   `radius` (number): 采样半径，影响阴影的范围。
+*   **注意**: 这是一个基于屏幕空间深度的算法，依赖 Depth Buffer。
+
+### 3. Optional Built-in Passes (可选内置 Pass)
+
+Five 新增了三个可选使用的内置 Pass，这些 Pass 没有预先挂载在 `five` 实例上，需手动导入并添加到渲染链中：
+
+*   **[GaussianBlurPass](gaussian-blur-pass.md)**: 高斯模糊效果。
+*   **[FlowingLight2DPass](flowing-light-2d-pass.md)**: 2D 流光效果（通常用于平面路线流光）。
+*   **[FlowingLight3DPass](flowing-light-3d-pass.md)**: 3D 流光效果（通常用于空间路径流光）。
+
+#### GaussianBlurPass 使用示例
+
+```typescript
+import { GaussianBlurPass } from '@realsee/five';
+
+// 1. 创建 GaussianBlurPass 实例 (需要传入 camera)
+const gaussianBlurPass = new GaussianBlurPass(five.camera);
+
+// 2. 配置参数
+// 设置模糊半径 (默认 4.0)
+gaussianBlurPass.setRadius(6);
+
+// 3. 将 Pass 添加到渲染链
+five.addPass(gaussianBlurPass);
+
+// 4. (可选) 动态开关
+// gaussianBlurPass.enabled = false;
+
+// 5. (可选) 移除 Pass
+// five.removePass(gaussianBlurPass);
+```
+
+## Custom Pass (自定义 Pass)
+
+如果需要实现自定义的后处理效果（如景深、色彩校正、描边等），建议继承 `FivePass`。
+
+### 步骤
+
+1.  **创建类**: 继承 `FivePass`。
+2.  **声明依赖**: 在 `super()` 中传入需要的 G-Buffer 依赖 (如 `['depth']`)。
+3.  **实现 render**: 使用 `readBuffer` 作为输入，将结果渲染到 `writeBuffer` (或直接渲染到屏幕)。
+4.  **挂载**: 使用 `five.addPass(pass)` 将其实例添加到渲染链中。
+
+## Examples
+
+### 开启内置 Pass
+
+```typescript
+import { Five } from '@realsee/five';
+
+const five = new Five();
+
+// 开启自适应亮度
+five.adaptiveLuminancePass.enabled = true;
+five.adaptiveLuminancePass.luminanceScale = 0.5; // 调整目标亮度
+
+// 开启 EDL (通常用于点云模式)
+five.eyeDomeLightingPass.enabled = true;
+five.eyeDomeLightingPass.strength = 1.5; // 增强轮廓感
+
+five.needsRender = true;
+```
+
+### 自定义 Pass (黑白滤镜)
+
+```typescript
+import * as THREE from 'three';
+import { Five, FivePass } from '@realsee/five';
+import { FullScreenQuad } from '@realsee/five/lib/five/tools/full-screen-quad'; // 需根据实际路径引用
+
+// 1. 定义 Shader
+const grayscaleVertexShader = `
+  varying vec2 vUv;
+  void main() {
+    vUv = uv;
+    gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+  }
+`;
+
+const grayscaleFragmentShader = `
+  uniform sampler2D tDiffuse;
+  varying vec2 vUv;
+  void main() {
+    vec4 color = texture2D(tDiffuse, vUv);
+    float gray = dot(color.rgb, vec3(0.299, 0.587, 0.114));
+    gl_FragColor = vec4(vec3(gray), color.a);
+  }
+`;
+
+// 2. 创建 Pass 类
+class GrayscalePass extends FivePass {
+  private material: THREE.ShaderMaterial;
+  private fsQuad: FullScreenQuad;
+
+  constructor() {
+    super(); // 不需要额外的 G-Buffer 依赖，只需要前一个 Pass 的颜色结果
+    this.material = new THREE.ShaderMaterial({
+      uniforms: {
+        tDiffuse: { value: null }
+      },
+      vertexShader: grayscaleVertexShader,
+      fragmentShader: grayscaleFragmentShader
+    });
+    this.fsQuad = new FullScreenQuad(this.material);
+  }
+
+  render(renderer, writeBuffer, readBuffer) {
+    // 将上一个 Pass 的结果 (readBuffer) 传给 Shader
+    this.material.uniforms.tDiffuse.value = readBuffer.texture;
+
+    if (this.renderToScreen) {
+      // 如果是最后一个 Pass，直接渲染到屏幕
+      renderer.setRenderTarget(null);
+      this.fsQuad.render(renderer);
+    } else {
+      // 否则渲染到 writeBuffer，供下一个 Pass 使用
+      renderer.setRenderTarget(writeBuffer);
+      if (this.clear) renderer.clear();
+      this.fsQuad.render(renderer);
+    }
+  }
+}
+
+// 3. 挂载到 Five
+const grayPass = new GrayscalePass();
+five.addPass(grayPass);
+
+// 触发重绘
+five.needsRender = true;
+```
+
+### 使用 G-Buffer (深度图示例)
+
+如果你的 Pass 需要使用场景的深度信息（例如雾效），可以在构造函数中声明依赖。
+
+```typescript
+class FogPass extends FivePass {
+  constructor() {
+    super(['depth']); // 声明需要深度图
+  }
+
+  render(renderer, writeBuffer, readBuffer) {
+    // 获取深度图
+    const depthTexture = this.gbuffer.get('depth');
+
+    // 在 Shader 中使用 depthTexture ...
+    // this.material.uniforms.tDepth.value = depthTexture;
+
+    // ... 渲染逻辑
+  }
+}
+```
+
+## Debugging
+
+*   **查看 Pass 列表**: 检查 `five.fiveRenderer.composer.passes` 数组，确认 Pass 是否已添加以及顺序是否正确。
+*   **检查 Enabled 状态**: 确保 Pass 实例的 `.enabled` 属性为 `true`。
+*   **G-Buffer 调试**: 如果自定义 Pass 依赖 G-Buffer 但效果不对，检查 `this.gbuffer` 是否包含预期的纹理。
+
+## Common Pitfalls
+
+1.  **Pass 顺序**: 后处理是按顺序执行的。如果添加了多个 Pass，要注意它们的添加顺序。`addPass` 会添加到末尾，`insertPass` 可以插入到指定位置。
+2.  **renderToScreen**: 只有链中的最后一个 Pass (且 `renderToScreen` 为 true) 才会渲染到屏幕。EffectComposer 会自动管理这个标志，但自定义 Pass 必须在 `render` 方法中正确处理 `this.renderToScreen` 逻辑。
+3.  **Performance**: 过多的后处理 Pass 会显著降低帧率，尤其是在高分辨率屏幕上。尽量合并 Shader 逻辑，避免频繁的 Buffer 拷贝。
+4.  **Dependencies**: 只有继承 `FivePass` 并声明了 `dependencies`，`this.gbuffer` 才会有值。普通 `Pass` 实现无法自动获取 G-Buffer。
+
+## Related
+
+*   [Gaussian Blur Pass](gaussian-blur-pass.md): 高斯模糊 Pass 文档。
+*   [Flowing Light 2D Pass](flowing-light-2d-pass.md): 2D 流光 Pass 文档。
+*   [Flowing Light 3D Pass](flowing-light-3d-pass.md): 3D 流光 Pass 文档。
+*   [five.ts](../../five/application/five.d.ts): 查看 `addPass` 方法的实现。
+*   [pass.ts](../../five/renderer/postprocessing/passes/pass.d.ts): 查看 `FivePass` 基类定义。
+
+---
+
+```yaml
+tags: [postprocessing, shader, effect, adaptive-luminance, edl]
+```

package/ai_guides/features/raycast.md

@@ -0,0 +1,175 @@
+# Raycast (射线检测)
+
+- **Summary**: Five 提供了增强版的射线检测机制，内置 BVH 加速，并扩展了 Three.js Raycaster 以支持更灵活的过滤和性能优化。
+- **Schema**: 参见下方 `Three.js Raycaster Extensions`。
+- **Concepts**: BVH, IntersectRaycaster, Raycaster Extensions。
+- **Examples**: 提供基础检测与性能优化示例。
+
+## Schema: Three.js Raycaster Extensions
+
+> **Definition**: [Raycaster](../../five/declare.d.ts)
+
+Five 对 Three.js 的 `Raycaster` 进行了扩展，在 `declare module 'three'` 中增加了以下属性：
+
+```typescript
+// defined in five/declare.d.ts
+declare module 'three' {
+  export interface Raycaster {
+    /**
+     * 只捕获第一个焦点 (性能优化)
+     * - true: 找到第一个交点后立即停止检测，返回结果。
+     * - false (默认): 检测所有可能的交点。
+     */
+    firstHitOnly?: boolean;
+
+    /**
+     * 自定义交点过滤器
+     * - 回调函数，返回 boolean。
+     * - true: 保留该交点。
+     * - false: 丢弃该交点。
+     */
+    hitFilter?: (intersect: THREE.Intersection) => boolean;
+
+    /**
+     * 是否由近及远排序
+     * - true (默认): 返回的结果数组按距离摄像机从近到远排序。
+     * - false: 结果顺序不确定（通常按遍历顺序）。
+     */
+    sortByDistance?: boolean;
+
+    /**
+     * 作用楼层 (Five 特有逻辑)
+     * - 用于多楼层场景过滤。
+     */
+    floorIndex?: number;
+  }
+
+  export interface Intersection {
+    /** 命中的具体 Tile 对象 (仅 3DTiles) */
+    tile?: Tile;
+    /** 命中的 ViewLayer 对象 */
+    viewLayer?: ViewLayer;
+    /** 命中的 Model 对象 */
+    model?: Model;
+  }
+}
+```
+
+## Concepts
+
+### 1. Five 内置 BVH (Bounding Volume Hierarchy)
+Five 内置了一套高效的 BVH 实现，用于优化 `Mesh` 和 `Points` 的射线检测。
+*   **作用**: 在进行射线检测时，不直接遍历所有三角形或点，而是先与构建好的 BVH 树（包围盒层次结构）进行相交测试。只有当射线穿过包围盒时，才进一步检测内部的几何体。
+*   **优势**: 极大提升了复杂模型（如数十万面的 Mesh 或百万级 Points）的碰撞检测性能。
+*   **透明性**: 开发者通常无需手动操作 BVH，Five 在加载模型时会自动构建，并在调用 `intersectRaycaster` 时自动应用。
+
+### 2. models.intersectRaycaster / model.intersectRaycaster vs 原生 intersectObject
+
+Five 提供了 `model.intersectRaycaster` 方法，与 Three.js 原生的 `raycaster.intersectObject` 有显著区别：
+
+| 特性 | `five.model.intersectRaycaster` | `raycaster.intersectObject` (Three.js 原生) |
+| :--- | :--- | :--- |
+| **检测范围** | 聚合检测 `five.model.shownModels` 中所有可见模型。 | 仅检测指定的单个 Object3D 及其子节点。 |
+| **结果排序** | 自动合并所有模型的检测结果，并根据 `raycaster.sortByDistance` 排序。 | 仅对当前 Object 及其子节点的结果排序。 |
+| **扩展支持** | **支持** `firstHitOnly`, `hitFilter`, `sortByDistance` 等扩展属性。 | 不支持 Five 的扩展属性（需手动实现）。 |
+| **内部优化** | 自动调用模型内部的优化逻辑（如 BVH, Tile3D 的空间索引）。 | 仅进行标准的场景图遍历检测。 |
+| **使用场景** | **推荐**。适用于全局点击、地板检测、物体拾取等业务场景。 | 仅在需要检测特定原生 Object3D 时使用。 |
+
+## Examples
+
+### 基础用法：检测点击位置
+
+最常见的场景是将鼠标点击的屏幕坐标转换为 3D 空间中的点。
+
+```typescript
+import * as THREE from 'three';
+import { Five } from '@realsee/five';
+
+const five = new Five();
+// ... 初始化 ...
+
+const raycaster = new THREE.Raycaster();
+const vector = new THREE.Vector2();
+
+// 假设 onTap 是点击事件处理函数
+function onTap(event: { x: number, y: number }) {
+  // 1. 将屏幕坐标转换为归一化设备坐标 (NDC)
+  // 注意：five.getElement() 获取 canvas 容器
+  const element = five.getElement();
+  if (!element) return;
+
+  const rect = element.getBoundingClientRect();
+  vector.x = ((event.x - rect.left) / rect.width) * 2 - 1;
+  vector.y = -((event.y - rect.top) / rect.height) * 2 + 1;
+
+  // 2. 设置射线
+  raycaster.setFromCamera(vector, five.camera);
+
+  // 3. 调用 Five 的检测方法
+  const intersects = five.model.intersectRaycaster(raycaster);
+
+  if (intersects.length > 0) {
+    const firstHit = intersects[0];
+    console.log('点击到了模型:', firstHit.object);
+    console.log('交点坐标 (世界坐标):', firstHit.point);
+  }
+}
+```
+
+### 性能优化：只获取第一个交点
+
+在进行如“地面检测”或“视线遮挡检测”时，通常只需要知道最近的交点。此时开启 `firstHitOnly` 可以显著提升性能。
+
+```typescript
+const raycaster = new THREE.Raycaster();
+raycaster.setFromCamera(mouseVector, five.camera);
+
+// 开启性能优化：找到最近的一个交点后立即停止
+raycaster.firstHitOnly = true;
+
+// 结果数组长度最多为 1
+const intersects = five.model.intersectRaycaster(raycaster);
+
+if (intersects.length > 0) {
+    // 处理最近的交点
+}
+```
+
+### 高级用法：使用过滤器
+
+如果你只想检测特定类型的物体（例如只检测地板，忽略天花板），可以使用 `hitFilter`。
+
+```typescript
+raycaster.hitFilter = (intersect) => {
+  // 示例：假设地板的法线是向上的 (0, 1, 0)
+  // 只保留法线朝上的交点（地板）
+  if (intersect.face && intersect.face.normal.y > 0.5) {
+    return true; // 保留
+  }
+  return false; // 丢弃
+};
+
+const intersects = five.model.intersectRaycaster(raycaster);
+```
+
+## Debugging
+
+*   **验证交点**: 在开发阶段，可以在交点处添加一个临时的红色小球 `THREE.Mesh`，直观地确认检测位置是否正确。
+*   **检查模型可见性**: `intersectRaycaster` 只会检测 `visible = true` 的模型。如果检测不到，请检查模型的可见性状态。
+*   **Performance**: 如果射线检测导致掉帧，检查是否频繁调用了全场景检测。尝试使用 `firstHitOnly` 或减小检测频率（如节流）。
+
+## Common Pitfalls
+
+1.  **混淆 API**: 错误地使用 `raycaster.intersectObject(five.scene)`。虽然这也能工作，但会失去 Five 的 BVH 优化和多模型聚合能力，导致性能下降或漏检。请始终优先使用 `five.model.intersectRaycaster(raycaster)`。
+2.  **忽略坐标系**: `raycaster.setFromCamera` 需要 NDC 坐标（-1 到 1），而不是像素坐标。务必进行正确的坐标转换。
+3.  **Tile3D 模型的特殊性**: 对于大型 Tile3D 场景，射线检测可能涉及动态加载的瓦片。Five 内部已处理这些逻辑，外部调用方式不变，但返回的 `object` 可能是某个具体的 Tile 节点。
+
+## Related
+
+*   [parameter.md](./parameter.md): 了解模型参数配置。
+
+---
+
+```yaml
+tags: [raycast, bvh, interaction, performance]
+```