@realsee/five-webgpu 1.0.0-alpha.1

package/ai_guides/features/parameter.md

@@ -0,0 +1,153 @@
+# Parameter (配置系统)
+
+- **Summary**: Five 用于控制三维模型渲染表现的核心配置系统，采用树形继承设计。
+- **Schema**: 是所有配置项的容器，通过继承机制管理 Material 和 3DTile 等子配置。
+- **Concepts**: Hierarchy (树形继承), Override (覆盖), Resolution (解析)。
+- **Examples**: 全局配置、局部覆盖、参数重置。
+
+## Schema
+
+> **Definition**: [Parameter](../../five/model/parameter.d.ts)
+
+`Parameter` 类是配置的入口。它并不直接包含所有配置字段的定义，而是将它们组织在不同的接口中。
+
+### Parameter Categories (参数分类)
+
+为了便于理解，我们将参数分为两大类：
+
+| Category | Description | Link |
+| :--- | :--- | :--- |
+| **Material & Appearance** | 控制“长什么样”。包括材质、颜色、楼层显示、阴影、点云样式等。 | [Material Params](./material.md) |
+| **3DTile & Performance** | 控制“怎么加载”。包括 LOD (细节层级)、显存配额、网络并发、SSE 阈值等。 | [3DTile Params](./3dtile.md) |
+
+### Parameter Class API
+
+#### 1. Getting Values (获取值)
+
+获取参数值**不使用** `get()` 方法，而是直接访问属性。
+
+*   **Direct Access (直接访问)**: 获取当前 `Parameter` 实例上设置的值。如果未设置，返回 `undefined`。
+*   **Resolve Value (计算最终值)**: 获取经过树形继承计算后的最终生效值。
+    *   如果不传参，则基于默认值计算 (Default -> Current)。
+    *   如果传入上游 Parameter，则基于默认值 + 上游 Parameter 计算 (Default -> Upstream -> Current)。
+
+```typescript
+// 方式 A: 直接访问 (获取当前层级配置)
+const currentVal = parameter.maxMemoryUsage;
+
+// 方式 B: 计算最终值 (包含继承逻辑)
+
+// 1. 基础用法：仅继承默认值
+const finalVal = parameter.resolveValue().maxMemoryUsage;
+
+// 2. 进阶用法：指定继承源 (例如 ViewLayer 继承自 Model)
+const inheritedVal = viewLayerParam.resolveValue(parentParameter).maxMemoryUsage;
+```
+
+#### 2. Methods (方法)
+
+`Parameter` 实例提供了以下核心方法来管理配置：
+
+```typescript
+class Parameter {
+  /**
+   * 设置配置项
+   * @param key 参数名 (如 'opacity', 'maxMemoryUsage')
+   * @param value 参数值
+   */
+  set(key: string, value: any): void;
+
+  /**
+   * 重置配置项（移除当前层级的设置，恢复继承上游的值）
+   * @param keys 要重置的参数名列表
+   */
+  reset(...keys: string[]): void;
+
+  /**
+   * 获取经过继承计算后的最终值
+   * @param upstream 上游 Parameter 对象列表（通常由引擎自动传入）
+   */
+  resolveValue(...upstream: Parameter[]): ResolvedParameterValue;
+}
+```
+
+## Concepts
+
+### 树形继承关系 (Hierarchy)
+
+Parameter 遵循 **“就近原则” (Override)** 的继承逻辑。
+
+1.  **ViewLayer Parameter**: 最具体，优先级最高。通常对应一个具体的 `.gltf` 文件或数据块。
+2.  **Model Parameter**: 覆盖该 Model 下的所有 ViewLayer。一个 Model 可能包含多个 ViewLayer (如 Mesh 层和 PointCloud 层)。
+3.  **ModelScene Parameter**: 全局默认值，优先级最低。影响整个场景。
+
+```mermaid
+graph TD
+  Scene[ModelScene.parameter] -->|Inherit| Model[Model.parameter]
+  Model -->|Inherit| Layer1[ViewLayer.parameter]
+  Model -->|Inherit| Layer2[ViewLayer.parameter]
+```
+
+> **Global Configuration (全局设置)**:
+> 若需修改所有模型的默认表现（如统一调暗亮度、统一设置显存上限），**请直接配置 `five.modelScene.parameter`**。它是继承链的根节点，其设置会向下传递给所有 Model 和 ViewLayer。
+>
+> **Why modelScene? (生命周期优势)**:
+> `Model` 实例是跟随 Work 加载生命周期的（需 `five.load(work)` 后才能访问，且切换 Work 会销毁重建）。
+> 相比之下，`ModelScene` 是常驻对象。因此，**使用 `modelScene` 进行配置更安全且持久**，既无需等待 Work 加载完成，也无需担心切换 Work 导致配置丢失。
+
+## Examples
+
+### 1. 基础配置 (Basic Usage)
+
+```typescript
+// 1. 设置全局最大显存 (影响所有模型)
+five.modelScene.parameter.set('maxMemoryUsage', 512);
+
+// 2. 设置全局半透明
+five.modelScene.parameter.set('opacity', 0.5);
+```
+
+### 2. 局部覆盖 (Override)
+
+```typescript
+// 场景中大部分模型不产生阴影
+five.modelScene.parameter.set('castShadow', false);
+
+// 但让特定的“主角”模型产生阴影
+const heroModel = five.models[0];
+heroModel.parameter.set('castShadow', true);
+```
+
+### 3. 重置配置 (Reset)
+
+```typescript
+// 假设之前设置了 opacity
+five.modelScene.parameter.set('opacity', 0.5);
+
+// ... 一段时间后 ...
+
+// 移除该设置，恢复默认值 (或继承值)
+five.modelScene.parameter.reset('opacity');
+```
+
+### 4. 获取配置 (Get Value)
+
+```typescript
+// 获取当前对象上的配置（如果未设置，则为 undefined）
+const ownOpacity = five.modelScene.parameter.opacity;
+
+// 获取最终生效的配置（计算继承链后的值）
+const finalOpacity = five.modelScene.parameter.resolveValue().opacity;
+```
+
+## Related
+
+*   [Material Parameters](./material.md): 材质与外观参数详情。
+*   [3DTile Parameters](./3dtile.md): 性能与加载参数详情。
+*   [Model](./model.md): Parameter 的宿主。
+
+---
+
+```yaml
+tags: [parameter, config, hierarchy, api]
+```

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]
+```

package/ai_guides/features/request-proxy.md

@@ -0,0 +1,112 @@
+# Request Proxy (请求代理)
+
+- **Summary**: `requestProxy` 是 Five 初始化时的关键参数，用于在发起网络请求前对 URL 进行拦截和修改，常用于鉴权、资源重定向或 CDN 域名替换。
+- **Schema**: `(url: string) => string | Promise<string>`
+- **Concepts**: 请求拦截、资源重定向、鉴权签名。
+- **Configuration**: `FiveInitArgs.requestProxy`。
+- **Examples**: CDN 替换、私有化部署鉴权、调试模式。
+
+## Schema
+
+> **Definition**: [FiveInitArgs](../../five/application/fiveInitArgs.d.ts)
+
+```typescript
+interface FiveInitArgs {
+  /**
+   * 请求代理函数
+   * @description 在 Five 内部发起任何网络请求（如加载图片、模型、配置）之前调用。
+   * @param url - 原始请求 URL
+   * @returns 修改后的 URL (string) 或异步返回修改后的 URL (Promise<string>)
+   */
+  requestProxy?: (url: string) => string | Promise<string>;
+}
+```
+
+## Concepts
+
+### 拦截时机
+Five 内部加载资源（全景图瓦片、3D 模型、纹理贴图等）时，会通过统一的 Fetcher 层发起请求。`requestProxy` 钩子函数会在每次请求发起**前**被触发。
+
+### 核心用途
+1.  **域名替换 (CDN Domain Sharding)**: 将资源请求分散到多个 CDN 域名以突破浏览器并发限制。
+2.  **鉴权签名 (Authentication)**: 针对私有化部署或受保护资源，在 URL 后追加鉴权 Token (如 SAS Token)。
+3.  **资源重定向 (Redirection)**: 在开发环境下将线上资源重定向到本地或测试环境。
+4.  **协议适配**: 强制将 `http` 协议升级为 `https`。
+
+## Configuration
+
+`requestProxy` 是 `Five` 构造函数的配置项之一。
+
+| 参数 | 类型 | 默认值 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `requestProxy` | `(url: string) => string \| Promise<string>` | `undefined` | 代理函数，返回修改后的 URL。支持同步或异步返回。 |
+
+## Examples
+
+### 1. 基础用法：CDN 域名替换
+
+将图片资源请求分散到不同的 CDN 节点，加速加载。
+
+```typescript
+const five = new Five({
+  requestProxy: (url) => {
+    // 简单的字符串替换示例
+    return url.replace('//vrlab-public.ljcdn.com/', '//vr-public.realsee-cdn.cn/');
+  }
+});
+```
+
+### 2. 进阶用法：异步鉴权 (Async Auth)
+
+对于需要动态获取 Token 的场景，可以使用 `Promise` 异步返回 URL。
+
+```typescript
+const five = new Five({
+  requestProxy: async (url) => {
+    // 仅对私有桶资源进行签名
+    if (url.includes('private-bucket')) {
+      const token = await fetchToken(); // 假设 fetchToken 是一个获取鉴权的异步函数
+      const separator = url.includes('?') ? '&' : '?';
+      return `${url}${separator}token=${token}`;
+    }
+    return url;
+  }
+});
+```
+
+### 3. 开发调试：本地资源代理
+
+在开发阶段，将特定资源重定向到本地文件。
+
+```typescript
+const proxyMap: Record<string, string> = {};
+
+const five = new Five({
+  requestProxy: (url) => {
+    // 如果该 URL 在映射表中存在（例如通过 <input type="file"> 加载的本地 Blob URL），则使用映射值
+    if (proxyMap[url]) {
+      console.log(`[Proxy] Redirecting ${url} -> ${proxyMap[url]}`);
+      return proxyMap[url];
+    }
+    return url;
+  }
+});
+```
+
+## Common Pitfalls
+
+1.  **死循环风险**: 不要在 `requestProxy` 内部再次发起会导致 `requestProxy` 触发的 Five 资源请求，否则可能导致递归调用。
+2.  **性能损耗**: `requestProxy` 会在**所有**资源请求前触发（包括成百上千个瓦片请求）。请确保该函数执行效率极高，避免进行耗时的同步操作。如果是异步操作，应做好缓存。
+3.  **URL 格式**: 确保返回的 URL 格式正确。如果原 URL 包含 Query 参数，拼接 Token 时要注意判断是使用 `?` 还是 `&`。
+4.  **缓存一致性**: 如果修改了 URL（例如加了 Token），可能会影响浏览器的缓存命中策略。
+
+## Related
+
+*   [Parameter](./parameter.md): Five 初始化参数总览。
+*   [Load External Model](./load-external-model.md): 加载外部模型时也会触发 requestProxy。
+
+---
+
+```yaml
+tags: [configuration, network, proxy, authentication]
+```

package/ai_guides/features/screen-project.md

@@ -0,0 +1,165 @@
+# Screen & Space Projection (屏幕与空间坐标转换)
+
+- **Summary**: 详解屏幕二维坐标与三维空间坐标/射线之间的相互转换关系，以及如何在 DOM 层与 3D 场景进行联动（如显示标签）。
+- **Schema**: `five.project2d` 接口定义。
+- **Concepts**: World Space, Screen Space, NDC, Raycasting.
+- **Examples**: 空间点位转屏幕坐标 (标签功能)、屏幕坐标转空间射线。
+
+## Schema
+
+> **Definition**: [Five](../../five/application/five.d.ts)
+
+```typescript
+// defined in Five class
+interface Five {
+  /**
+   * 计算三维坐标对应到屏幕的二维坐标
+   * @param vector - 三维空间坐标 (World Space)
+   * @param testModel - 是否进行模型遮挡检测 (默认 false)。如果为 true，且该点被模型遮挡，则返回 null。
+   * @returns 二维屏幕坐标 (相对于 Canvas 左上角) 或 null (如果点在视野外或被遮挡)
+   */
+  project2d(vector: THREE.Vector3, testModel?: boolean): THREE.Vector2 | null;
+}
+```
+
+## Concepts
+
+### 1. 坐标系转换流程
+
+在 Five (Three.js) 中，坐标转换通常遵循以下流程：
+
+*   **World Space (世界坐标)**: 三维场景中的绝对坐标 (x, y, z)，单位通常为米。
+*   **Camera Space (相机坐标)**: 相对于相机的坐标。
+*   **NDC (Normalized Device Coordinates)**: 归一化设备坐标，x, y, z 范围均为 [-1, 1]。
+*   **Screen Space (屏幕坐标)**: 对应 Canvas 画布的像素坐标。原点 (0, 0) 在左上角，x 向右增加，y 向下增加。
+
+### 2. 转换关系
+
+| 方向 | 方法 | 核心逻辑 | 用途 |
+| :--- | :--- | :--- | :--- |
+| **3D ➔ 2D** | `five.project2d(vector)` | World ➔ NDC ➔ Screen | 标签 (Tag)、HUD、跟随 3D 物体的 UI |
+| **2D ➔ 3D** | `Raycaster` | Screen ➔ NDC ➔ Ray | 点击拾取 (Picking)、地面检测、放置物体 |
+
+### 3. five.project2d
+
+`five.project2d` 是 Five 提供的便捷方法，它封装了以下逻辑：
+1.  将世界坐标投影 (Project) 到相机的 NDC 空间。
+2.  判断点是否在视锥体 (Frustum) 内（即是否在视野范围内）。
+3.  (可选) 发射射线检测该点与相机之间是否有模型遮挡。
+4.  将 NDC 坐标转换为相对于 Canvas 左上角的像素坐标 (px)。
+
+## Examples
+
+### 1. 空间标签 (3D Point to DOM Label)
+
+最典型的应用场景是在 3D 场景中的某个物体上方显示一个 HTML 标签。
+
+```typescript
+import { Five, Mode } from "@realsee/five";
+import * as THREE from "three/webgpu";
+
+const five = new Five();
+// ... 初始化 five ...
+
+// 1. 创建标签 DOM 元素
+const label = document.createElement("div");
+label.textContent = "Living Room";
+label.style.position = "absolute";
+label.style.padding = "4px 8px";
+label.style.background = "rgba(0, 0, 0, 0.6)";
+label.style.color = "white";
+label.style.borderRadius = "4px";
+label.style.pointerEvents = "none"; // 避免阻挡鼠标事件
+label.style.transform = "translate(-50%, -100%)"; // 居中并显示在点上方
+label.style.display = "none"; // 默认隐藏
+document.body.appendChild(label); // 添加到 container (注意 container 的定位 context)
+
+// 2. 定义目标空间坐标 (例如客厅中心)
+const targetPosition = new THREE.Vector3(1.5, 2.0, -3.0);
+
+// 3. 在每一帧渲染时更新标签位置
+five.on("render.prepare", () => {
+  // 计算屏幕坐标
+  // 参数2: false 表示不检测遮挡 (性能更好)；true 表示如果被墙挡住则隐藏
+  const screenPos = five.project2d(targetPosition, true);
+
+  if (screenPos === null) {
+    // 如果返回 null，说明点在相机背面，或者被遮挡（如果开启了 testModel）
+    label.style.display = "none";
+  } else {
+    label.style.display = "block";
+    // 更新 DOM 位置
+    // 注意：screenPos 是相对于 Canvas 的坐标。
+    // 如果 Canvas 占满全屏，直接使用即可。
+    // 如果 Canvas 有偏移，需加上 Canvas 的 offset。
+    label.style.left = `${screenPos.x}px`;
+    label.style.top = `${screenPos.y}px`;
+  }
+});
+```
+
+### 2. 屏幕点击转射线 (Screen to Ray)
+
+将鼠标点击的屏幕坐标转换为 3D 射线，用于检测物体。
+
+> **注意**: 更多射线检测细节请参考 [Raycast](./raycast.md)。
+
+```typescript
+import * as THREE from "three/webgpu";
+
+// 假设 container 是 five 的容器元素
+const container = five.getElement()!.parentElement!;
+
+container.addEventListener("click", (event) => {
+  const raycaster = new THREE.Raycaster();
+  const mouse = new THREE.Vector2();
+
+  // 1. 计算 NDC 坐标 (x, y 范围 [-1, 1])
+  // event.clientX/Y 是相对于视口的坐标
+  // getBoundingClientRect 用于获取容器的位置
+  const rect = container.getBoundingClientRect();
+
+  mouse.x = ((event.clientX - rect.left) / rect.width) * 2 - 1;
+  mouse.y = -((event.clientY - rect.top) / rect.height) * 2 + 1; // 注意 Y 轴翻转
+
+  // 2. 从相机发射射线
+  raycaster.setFromCamera(mouse, five.camera);
+
+  // 3. 进行相交检测
+  const intersects = five.model.intersectRaycaster(raycaster);
+
+  if (intersects.length > 0) {
+    console.log("Hit point:", intersects[0].point);
+  }
+});
+```
+
+## Common Pitfalls
+
+1.  **坐标系原点**:
+    *   DOM/CSS 坐标系原点在左上角，Y 轴向下。
+    *   NDC/WebGL 坐标系原点在中心，Y 轴向上。
+    *   `project2d` 返回的是 **DOM 风格** 的坐标 (左上角原点)，可以直接赋给 CSS `left`/`top`。
+    *   但在进行 Raycaster 转换时，需要手动将 DOM 坐标转换为 NDC (Y 轴翻转)。
+
+2.  **性能开销**:
+    *   `project2d(pos, true)` 开启 `testModel` 会进行射线检测，性能开销较大。如果在 `render.prepare` 中对大量点进行检测，可能会导致掉帧。
+    *   建议：对于大量标签，默认使用 `false`；或者仅对可视范围内的关键标签进行遮挡检测；或者限制检测频率（如每 10 帧检测一次）。
+
+3.  **Canvas 尺寸**:
+    *   `project2d` 内部使用 `five.renderer.getSize()` 和 `five.viewport` 计算。确保 Canvas 尺寸与 DOM 显示尺寸一致 (通常 Five 会自动处理，但如果使用了 CSS 缩放需注意)。
+
+4.  **Null 返回值**:
+    *   务必检查 `project2d` 的返回值是否为 `null`。点在相机背面、超出视锥体裁剪范围、或被遮挡（开启 testModel 时）都会返回 `null`。
+
+## Related
+
+*   [Raycast](./raycast.md): 详细的射线检测文档。
+*   [Five](./five.md): Five 核心类说明。
+*   [State](./state.md): 了解相机位姿 (Pose)。
+
+---
+
+```yaml
+tags: [coordinate, screen, project, label, ui]
+```