@realsee/five 6.8.0-alpha.0 → 6.8.0-alpha.10

package/ai_guides/features/gesture.md

@@ -0,0 +1,180 @@
+# Gesture (手势与事件)
+
+- **Summary**: Five 提供了一套跨平台的手势事件系统，抹平了 PC 与移动端的差异，并针对不同 Mode 提供了默认的交互逻辑。
+- **Schema**: `GestureEvent` 继承自 `StateEvent`，包含了手势中心点、射线等信息。
+- **Concepts**: Gesture Type, Default Behavior, PreventDefault。
+- **Examples**: 阻止默认行为、点击添加标记。
+
+## Schema
+
+> **Definition**: [GestureEvent](../../five/utils/event.d.ts)
+
+所有手势事件的回调参数均为 `GestureEvent` 类型：
+
+```typescript
+import { State } from "@realsee/five";
+import * as THREE from "three";
+
+interface GestureEvent {
+  type: string;             // 事件类型，如 "gesture.tap"
+  timeStamp: number;        // 时间戳
+  target: EventTarget | null;
+  pointerType: 'touch' | 'pen' | 'mouse' | 'kinect';
+
+  // 手势中心点信息
+  center: {
+    x: number;              // 屏幕 X 坐标
+    y: number;              // 屏幕 Y 坐标
+    raycaster: THREE.Raycaster; // 从相机发出的射线（已包含坐标变换）
+  };
+
+  // 当前相机状态
+  state: State;
+
+  // 是否是用户触发（区别于代码调用）
+  userAction: boolean;
+
+  // 阻止默认行为
+  preventDefault(): void;
+  defaultPrevented: boolean;
+}
+```
+
+## Concepts
+
+Five 的手势系统基于 Hammer.js 封装，主要包含以下几种手势：
+
+*   **gesture.pan**: 拖拽/平移。
+*   **gesture.pinch**: 双指缩放。
+*   **gesture.tap**: 点击。
+*   **gesture.dbltap**: 双击。
+*   **gesture.press**: 长按。
+*   **gesture.mousewheel**: 鼠标滚轮。
+
+### 模式差异 (Mode Specifics)
+
+不同的 Mode 对手势有不同的**默认响应**：
+
+| 手势 | Panorama (全景) | Mapview (模型) | 说明 |
+| :--- | :--- | :--- | :--- |
+| **Pan** | 旋转相机视角 (Look around) | 围绕模型旋转/平移相机 (Orbit/Pan) | |
+| **Pinch** | 调整 FOV (Zoom in/out) | 调整相机距离 (Distance) | |
+| **Tap** | **移动点位** (Move to pano) | **切换到全景** (Enter pano) | 若点击到地面/模型，Mapview 下默认无响应，除非点击到点位标记 |
+| **DblTap** | 动画调整 FOV | 聚焦并拉近视角 (Fly to) | |
+| **MouseWheel** | 调整 FOV | 调整相机距离 | |
+
+### 事件捕获与阻止 (Event Handling)
+
+Five 的事件触发顺序如下：
+1.  **Emit Event**: Five 触发 `gesture.xxx` 事件。
+2.  **User Callback**: 开发者注册的监听函数被执行。
+3.  **Default Behavior**: **如果**开发者没有调用 `event.preventDefault()`，Five 执行默认逻辑（如旋转相机、移动点位）。
+
+因此，如果你想自定义交互（例如：点击不走点，而是弹出一个框），**必须**调用 `event.preventDefault()`。
+
+## Examples
+
+### 快速上手 (Quick Example)
+
+监听点击事件并打印日志：
+
+```typescript
+five.on("gesture.tap", (event) => {
+  console.log("点击位置:", event.center.x, event.center.y);
+  // event.center.raycaster 可以用来做射线检测
+});
+```
+
+### 场景交互：点击添加标签球 (Add Label on Click)
+
+这个示例展示了如何通过点击事件在场景中添加一个红色的球体，并阻止 Five 默认的点位移动行为。
+
+```typescript
+import * as THREE from "three";
+import { Five } from "@realsee/five";
+
+const five = new Five();
+
+five.on("gesture.tap", (event) => {
+  // 1. 阻止默认行为（防止点击地面时 Five 自动走点或切换模式）
+  event.preventDefault();
+
+  // 2. 获取射线
+  const raycaster = event.center.raycaster;
+
+  // 3. 检测与模型的碰撞
+  // five.model.intersectRaycaster 是 Five 提供的便捷方法，会自动检测所有可见模型
+  const intersects = five.model.intersectRaycaster(raycaster);
+
+  if (intersects.length > 0) {
+    const intersect = intersects[0];
+    const point = intersect.point; // 碰撞点世界坐标
+
+    console.log("点击到了模型，坐标:", point);
+
+    // 4. 创建一个小球
+    const geometry = new THREE.SphereGeometry(0.1, 32, 32);
+    const material = new THREE.MeshBasicMaterial({ color: 0xff0000 });
+    const sphere = new THREE.Mesh(geometry, material);
+
+    // 5. 设置位置并添加到场景
+    sphere.position.copy(point);
+    five.scene.add(sphere);
+
+    // 强制刷新渲染，确保小球立即出现
+    five.needsRender = true;
+  } else {
+    console.log("未点击到任何模型");
+  }
+});
+```
+
+### 进阶用法：自定义双指缩放范围
+
+```typescript
+five.on("gesture.pinch", (event) => {
+  // 获取当前 FOV
+  const currentFov = five.state.fov;
+
+  // 假设我们限制 FOV 在 80 到 100 之间
+  // 注意：这只是逻辑演示，Five 内部有自己的 minFov/maxFov 配置，
+  // 这里演示如何完全接管控制权。
+  if (currentFov < 80 || currentFov > 100) {
+    // 阻止 Five 的默认缩放
+    event.preventDefault();
+    console.log("已达到缩放极限");
+  }
+});
+```
+
+## Debugging
+
+*   **查看事件触发**: 在控制台监听所有手势。
+    ```typescript
+    ["pan", "tap", "pinch", "press"].forEach(type => {
+      five.on(`gesture.${type}` as any, (e) => console.log(type, e));
+    });
+    ```
+*   **Helper Line**: 如果射线检测不准，可以画出射线辅助线。
+    ```typescript
+    five.scene.add(new THREE.ArrowHelper(raycaster.ray.direction, raycaster.ray.origin, 10, 0xff0000));
+    five.needsRender = true;
+    ```
+
+## Common Pitfalls
+
+1.  **忘记 preventDefault**: 如果你发现点击后既生成了小球，相机又自动飞走了，通常是因为没有调用 `event.preventDefault()`。
+2.  **坐标系混淆**: `event.center.x/y` 是屏幕像素坐标，`event.center.raycaster` 已经处理了屏幕到世界的转换。直接使用 `raycaster` 最安全。
+3.  **点击穿透**: 如果场景中有 HTML 覆盖层（如按钮），HTML 元素的点击事件可能会冒泡或被 Five 捕获。建议在 HTML 元素上使用 `stopPropagation` 或判断 `event.target`。
+
+## Related
+
+*   [Mode (模式)](./mode.md): 了解不同模式下的默认行为。
+*   [State (状态)](./state.md): 手势最终改变的是 State。
+*   [Raycast (射线检测)](./raycast.md): 深入了解 `intersectRaycaster` 的工作原理。
+
+---
+
+```yaml
+tags: [gesture, event, interaction, tap, pan, pinch]
+```

package/ai_guides/features/get-screen-pixels.md

@@ -0,0 +1,182 @@
+# 获取屏幕像素 (Get Screen Pixels)
+
+- **Summary**: `five.getPixels` 方法用于获取 Five 画布指定区域的像素数据（RGBA），常用于实现放大镜、取色器或截图功能。
+- **Schema**: `GetPixelsOptions`。
+- **Concepts**: `WebGLRenderTarget`, `gl.readPixels`, `Magnifier`。
+- **Examples**: 放大镜实现、获取中心点颜色。
+
+## Schema
+
+> **Definition**: [GetPixelsOptions](../../five/application/five.d.ts)
+
+`five.getPixels` 支持两种调用方式：参数列表（旧版）和对象参数（推荐）。
+
+### 推荐调用方式
+
+```typescript
+five.getPixels(options: GetPixelsOptions): Uint8Array | Uint8ClampedArray;
+
+interface GetPixelsOptions {
+  /** 获取像素区域的起始坐标 x (基于 Canvas 左下角，除非 flipY 为 true) */
+  x: number;
+  /** 获取像素区域的起始坐标 y */
+  y: number;
+  /** 获取像素区域的宽度 */
+  width: number;
+  /** 获取像素区域的高度 */
+  height: number;
+  /** 获取区域的像素比 (默认 1) */
+  pixelRatio?: number;
+  /** 是否显示辅助元素 (默认 false) */
+  helperVisible?: boolean;
+  /** 是否跳过全景图渲染 (仅渲染模型) */
+  skipPanorama?: boolean;
+  /** 是否 Y 轴翻转 (通常设为 true 以匹配 Canvas 2D 坐标系) */
+  flipY?: boolean;
+  /** 存储数组 (可选，复用数组以提升性能) */
+  buffer?: Uint8Array | Uint8ClampedArray;
+}
+```
+
+### 简写调用方式 (不推荐)
+
+```typescript
+five.getPixels(
+  x: number,
+  y: number,
+  width: number,
+  height: number,
+  pixelRatio?: number,
+  flipY?: boolean,
+  buffer?: Uint8Array | Uint8ClampedArray
+): Uint8Array | Uint8ClampedArray;
+```
+
+## Concepts
+
+### 坐标系统 (Coordinate System)
+
+- **WebGL 坐标系**: 原点在左下角。
+- **Canvas 2D 坐标系**: 原点在左上角。
+- **flipY 参数**: 当你需要将数据绘制到 Canvas 2D Context (`putImageData`) 时，通常需要将 `flipY` 设置为 `true`，否则图像是倒置的。
+
+### 性能注意事项 (Performance)
+
+- `five.getPixels` 会触发 WebGL 的 `readPixels` 操作，这是一个同步且耗时的操作（会阻塞 GPU 流水线）。
+- **优化建议**:
+    - 避免在每一帧都调用。
+    - 尽量复用 `buffer` 数组，避免频繁创建新的 `Uint8Array`。
+    - 仅获取需要的区域（`width` 和 `height` 越小越好）。
+
+## Examples
+
+### 放大镜 (Magnifier)
+
+这是一个经典的放大镜实现示例。通过获取鼠标周围的像素，并以更高的 `pixelRatio` 重新渲染，从而获得清晰的放大效果。
+
+```typescript
+import * as THREE from 'three';
+import { Five } from '@realsee/five';
+
+// 假设有一个用于显示的 canvas
+const magnifierCanvas = document.getElementById('magnifier-canvas') as HTMLCanvasElement;
+const ctx = magnifierCanvas.getContext('2d')!;
+const magnifierSize = 200; // 放大镜尺寸 200px
+const scale = 2; // 放大倍数
+
+// 预先创建 Buffer 以提升性能
+const pixelWidth = magnifierSize * scale;
+const pixelHeight = magnifierSize * scale;
+let magnifierImageData = ctx.createImageData(pixelWidth, pixelHeight);
+
+five.on('gesture.mousemove', (event) => {
+  // 1. 获取鼠标在 Canvas 上的坐标
+  const mouse = event.pointers[0]?.coords;
+  if (!mouse) return;
+
+  // 转换归一化坐标 (-1 到 1) 到 像素坐标
+  const renderSize = five.getSize(new THREE.Vector2());
+  const x = (mouse.x + 1) / 2 * renderSize.x;
+  const y = (mouse.y + 1) / 2 * renderSize.y;
+
+  // 2. 获取像素数据
+  // 注意：我们以更高的分辨率 (pixelRatio * scale) 渲染小区域，从而获得“无损”放大效果
+  const pixelRatio = five.renderer?.getPixelRatio() ?? 1;
+  const targetPixelRatio = Math.ceil(pixelRatio * scale);
+
+  five.getPixels({
+    x: x - magnifierSize / 2, // 居中
+    y: y - magnifierSize / 2,
+    width: magnifierSize,
+    height: magnifierSize,
+    pixelRatio: targetPixelRatio,
+    flipY: true, // 翻转以适配 Canvas 2D
+    buffer: magnifierImageData.data, // 复用 buffer
+    helperVisible: false, // 隐藏辅助线等干扰元素
+  });
+
+  // 3. 将数据绘制到放大镜 Canvas 上
+  // 需要调整 Canvas 尺寸以匹配数据
+  magnifierCanvas.width = pixelWidth;
+  magnifierCanvas.height = pixelHeight;
+  ctx.putImageData(magnifierImageData, 0, 0);
+
+  // 4. 更新放大镜位置 (CSS)
+  magnifierCanvas.style.left = `${x - magnifierSize / 2}px`;
+  magnifierCanvas.style.top = `${renderSize.y - y - magnifierSize / 2}px`; // 注意 Y 轴方向
+});
+```
+
+### 获取中心点颜色 (Color Picker)
+
+获取屏幕中心点的颜色。
+
+```typescript
+function getCenterColor(five: Five) {
+  const size = five.getSize(new THREE.Vector2());
+  const x = size.x / 2;
+  const y = size.y / 2;
+
+  const pixels = five.getPixels({
+    x: x,
+    y: y,
+    width: 1,
+    height: 1,
+    flipY: true
+  });
+
+  const r = pixels[0];
+  const g = pixels[1];
+  const b = pixels[2];
+  const a = pixels[3];
+
+  return `rgba(${r}, ${g}, ${b}, ${a / 255})`;
+}
+```
+
+## Common Pitfalls
+
+1.  **坑点1: 图像倒置**:
+    - **现象**: 获取到的图像是上下颠倒的。
+    - **解决**: 检查 `flipY` 参数。如果直接用于 Canvas 2D `putImageData`，通常需要 `flipY: true`。
+
+2.  **坑点2: 性能卡顿**:
+    - **现象**: 开启放大镜后，页面帧率显著下降。
+    - **解决**:
+        - 确保使用了 `buffer` 参数复用内存。
+        - 检查 `width` 和 `height` 是否过大。
+        - 确保 `pixelRatio` 不要设置得过高（例如不要超过 4）。
+
+3.  **坑点3: 渲染内容不全**:
+    - **现象**: 放大镜里只有背景，没有模型。
+    - **解决**: 检查 `skipPanorama` 参数。如果需要看全景图，确保设为 `false`（默认）。如果只想看模型细节（如在 Floorplan 模式），可以设为 `true`。
+
+## Related
+
+*   [api.md](../api.md): Five 核心 API 说明。
+
+---
+
+```yaml
+tags: [getPixels, magnifier, screenshot, pixel, canvas]
+```

package/ai_guides/features/image-options.md

@@ -0,0 +1,164 @@
+# ImageOptions (图片配置)
+
+- **Summary**: `Five` 初始化参数 `imageOptions` 用于全局配置全景图与资源的加载策略，支持多云/私有化部署映射、图片格式自适应、质量控制及内部瓦片裁剪。
+- **Schema**: `ImageOptions` 接口定义及相关配置。
+- **Concepts**: CDN Mapping, Format Adaptation, Tile Cutting.
+- **Configuration**: `imageOptions` 参数详解。
+- **Examples**: 基础优化、多云部署映射、瓦片裁剪调用。
+
+## Schema
+
+### ImageOptions
+
+> **Definition**: [ImageOptions](../../five/types/imageOptions.d.ts)
+
+全局图片加载配置接口。
+
+```typescript
+interface ImageOptions {
+  /** 图片类型标识 (内部使用，如 "pano.front") */
+  key?: string;
+  /** 图片尺寸参数 (例如 512, 1024...) */
+  size?: number;
+  /** 图片质量参数 (0-100) */
+  quality?: number;
+  /**
+   * 图片格式参数
+   * 自动降级逻辑：如果指定格式（如 avif/webp）当前浏览器不支持，会自动降级为 jpg
+   */
+  format?: "jpg" | "jpeg" | "png" | "heif" | "heic" | "webp" | "avif";
+  /**
+   * 图片裁切 [x, y, width, height]
+   * 通常用于内部工具获取局部图片，初始化 Five 时一般不设置此项
+   */
+  cut?: [x: number, y: number, width: number, height: number];
+  /** 锐化参数 (仅部分 CDN 支持) */
+  sharpen?: number;
+  /** 域名匹配规则，用于多云或私有化部署 */
+  mappings?: ImageURLMappings;
+  /** 自定义 URL 转换函数 */
+  transform?: (url: string, options: ImageURLOptions) => string;
+}
+```
+
+### ImageURLMappings
+域名映射规则配置，用于支持多云存储或私有化部署。
+
+```typescript
+interface ImageURLMappings {
+  [publicDomain: string]: {
+    /** CDN 类型，目前支持 'tencentCloud' | 'aliyun' 用于区分特定云厂商的图片处理参数 */
+    "type"?: string;
+    /** 全景图域名映射列表 */
+    "pano": [string, string];
+    /** 全景图瓦片域名映射列表 */
+    "tile": [string, string];
+    /** 3D Tile 模型域名映射列表 */
+    "model": [string, string];
+    /** AT3D 材质域名映射列表 */
+    "texture": [string];
+    /** 默认域名映射列表 */
+    "default": [string];
+  }
+}
+```
+
+## Concepts
+
+### CDN Mapping (多云部署与私有化)
+通过 `mappings` 字段，可以将原始数据中的 **初始域名**（`publicDomain`，即数据中尚未进行资源分流的统一地址）映射到不同用途的具体域名下。
+- **资源分流**: 针对不同资源类型配置不同域名：
+  - `pano`: 全景图
+  - `tile`: 全景图瓦片
+  - `model`: 3D Tile 模型
+  - `texture`: AT3D 材质
+- **负载均衡**: 每个资源类型支持配置多个域名（如 `[domain1, domain2]`），SDK 会自动进行轮询负载均衡。
+- **私有化支持**: 将初始数据中的通用域名映射到内网或私有 OSS 域名。
+- **CDN 适配**: 指定 `type` ('tencentCloud' | 'aliyun') 可启用特定云厂商的图片处理参数（如缩放、裁剪、格式转换）。
+
+### Format Adaptation (浏览器兼容性)
+SDK 内置了图片格式兼容性检测（`imageSupport`）。
+- **自动降级**: 当配置 `format: 'webp'` 或 `format: 'avif'` 时，SDK 会检测当前浏览器是否支持该格式。如果不支持，自动降级请求 `jpg` 格式，确保图片能正常显示。
+- **性能优化**: 推荐默认开启 `avif`，在支持的浏览器上大幅减小流量消耗。
+
+### Tile Cutting (内部瓦片裁剪)
+利用云厂商的图片处理能力（如腾讯云 ImageMogr2 或阿里云 OSS Process），可以通过 `cut` 参数获取大图的局部区域。
+- **应用场景**: 内部工具调用、生成特定视角的缩略图、动态获取全景图的某一部分。
+- **调用方式**: 通常配合 `imageURL` 工具函数使用。
+
+## Configuration
+
+在 `new Five()` 时传入 `imageOptions`。
+
+| 参数 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `format` | string | 推荐设置为 `"avif"`，SDK 会自动处理兼容性。 |
+| `quality` | number | 图片质量 (0-100)，非必要不设置。 |
+| `mappings` | object | 域名映射表，用于替换数据中的原始域名，非必要不设置。 |
+| `size` | number | 全景图初始尺寸，推荐设置为 `512`，可根据场景调整。 |
+
+## Examples
+
+### 基础优化配置 (推荐)
+启用 AVIF 格式并设置初始尺寸为 `512`，适用于大多数场景。
+
+```typescript
+import { Five } from "@realsee/five";
+
+const five = new Five({
+  imageOptions: {
+    format: "avif",
+    size: 512,
+  }
+});
+```
+
+### 多云/私有化部署配置
+将数据中的 `custom-oss-public.ljcdn.com` 域名映射到对应的资源专用 OSS 域名。
+
+```typescript
+import { Five } from "@realsee/five";
+
+const five = new Five({
+  imageOptions: {
+    mappings: {
+      "custom-oss-public.ljcdn.com": {
+        type: "tencentCloud", // 指定使用腾讯云图片处理协议
+        pano: ["custom-oss-image-1.com", "custom-oss-image-2.com"], // 双域名负载均衡
+        tile: ["custom-oss-tile-1.com", "custom-oss-tile-2.com"],
+        model: ["custom-oss-model-1.com", "custom-oss-model-2.com"],
+        texture: ["custom-oss-image-3.com"],
+        default: ["custom-oss-image-4.com"]
+      }
+    }
+  }
+});
+```
+
+### 内部调用：获取全景图局部裁剪
+使用 SDK 提供的 `defaultImageURLTransform` 工具函数（通常导出为 `defaultImageURLTransform`，可重命名为 `imageURL`），结合 `cut` 参数获取全景图特定区域（例如获取前方图片的中心 512x512 区域）。
+
+```typescript
+import { defaultImageURLTransform as imageURL } from "@realsee/five";
+
+const originalUrl = "https://vr-public.realsee-cdn.com/.../pano_f.jpg";
+
+const cutUrl = imageURL(originalUrl, {
+  cut: [256, 256, 512, 512], // x, y, width, height
+  format: "webp",
+  quality: 80,
+});
+
+console.log(cutUrl);
+// 输出示例: https://vr-image-4.realsee-cdn.com/.../pano_f.jpg?imageMogr2/format/webp/cut/512x512x256x256/quality/80
+```
+
+## Related
+
+*   [pano-tile.md](./pano-tile.md): 全景图瓦片加载策略与 WorkTile 数据结构说明。
+
+---
+
+```yaml
+tags: [imageOptions, configuration, optimization, cdn, private-deployment]
+```