@realsee/five/ai_guides/README.md

Realsee Renderer SDK

# Five SDK Documentation

[![npm version](https://img.shields.io/npm/v/@realsee/five.svg?style=flat-square&logo=npm&label=npm%20install%20@realsee/five)](https://www.npmjs.com/package/@realsee/five)

- **Summary**: Five SDK 的文档索引与阅读指南，旨在帮助开发者与 AI 助手快速定位所需信息。
- **Audience**: 开发者、AI 辅助编程工具。

## Context for AI Agents

**Five** 是贝壳如视 (Realsee) 提供的三维空间渲染 SDK。

### 1. Documentation Maintenance (文档维护)
> [!IMPORTANT]
> Before writing or updating any documentation, YOU MUST READ [AI Documentation Guidelines](./ai-doc-guidelines.md).
> 在书写文档时，务必遵循 [AI Documentation Guidelines](./ai-doc-guidelines.md) 中的规范。

### 2. Application Development Strategy (应用开发建议)
当协助用户编写代码或构建 Five 应用时，请遵循以下阅读与检索策略：

*   **Initialization (初始化)**:
    *   阅读 [Quick Start](./quick-start.md) 掌握最小化启动流程。
    *   查阅 [Parameter](./features/parameter.md) 获取 `new Five(config)` 的完整配置项（如 canvas 尺寸、资源路径、纹理压缩设置）。
*   **Data Handling (数据加载)**:
    *   核心 VR 数据：深入理解 [Work](./features/work.md) 结构，它是 Five 渲染的基础。
    *   外部模型：参考 [Load External Model](./features/load-external-model.md) 加载 GLTF/OBJ 等格式。
    *   多场景/沙盘：参考 [Multi-Work (Sandbox)](./features/multi-work.md) 处理复杂场景切换。
*   **Interaction & Logic (交互逻辑)**:
    *   事件监听：查阅 [Event](./features/event.md) 处理用户点击 (Tap)、手势 (Gesture) 及状态变更 (StateChange)。
    *   空间操作：使用 [Raycast](./features/raycast.md) 实现物体拾取，使用 [Screen & Space Projection](./features/screen-project.md) 实现 3D 标签挂载。
    *   动画控制：参考 [Camera Animation](./features/camera-animation.md) 和 [Move Pano Effect](./features/move-pano-effect.md) 实现平滑运镜。
*   **State Management (状态管理)**:
    *   保存/恢复场景：**必须** 深刻理解 [State](./features/state.md)。它是 Five 的核心快照机制，包含 Pose、Mode 和 PanoIndex。不要尝试手动管理零散的相机参数，应统一使用 State。
*   **Coding Standards (代码规范)**:
    *   优先使用 TypeScript 类型提示。
    *   确保从 `@realsee/five` 导入核心类与类型 (e.g., `import { Five, Mode, Work, State } from "@realsee/five"`).

### 3. General Retrieval (通用检索)
*   **API Signatures**: [API Reference](./api.md) 是最权威的接口定义来源，包含方法的参数与返回值。
*   **Terminology**: 遇到不确定的术语 (e.g., Pose vs State, Observer) 时，务必查阅 [Glossary](./glossary.md)。
*   **Core Relationships**: 理解 [Five](./features/five.md) (渲染器) 与 [Work](./features/work.md) (数据) 的分离设计。

## Documentation Map

### 1. Essential Reference (必读/速查)
最常用的入口文档。

*   [Intro](./intro.md): Five SDK 简介与能力概览。
*   [Quick Start](./quick-start.md): 快速集成指南。
*   [API Reference](./api.md): **核心 API 索引** (Five 类, State, Events, Methods)。
*   [Glossary](./glossary.md): **术语表** (Work, Observer, Pose, etc.)。

### 2. Core Concepts (核心概念)
基础架构与生命周期管理。

*   [Five](./features/five.md): 核心类 `Five`，管理渲染循环与全局状态。
*   [Work](./features/work.md): 数据载体，描述三维空间的数据结构 (VR 看房数据)。
*   [Panorama UV](./features/pano-uv.md): 全景图 UV 与空间方向转换工具。
*   [Mode](./features/mode.md): 五种核心浏览模式 (Panorama, Floorplan, Topview, Model, Map)。
*   [State](./features/state.md): 状态管理 (Pose, Mode, PanoIndex)，用于复原场景。
*   [Coordinate System](./features/coordinate-system.md): 坐标系定义 (右手坐标系, Y轴向上)。

### 3. Data & Resource (数据与资源)
数据加载与资源管理配置。

*   [Load External Model](./features/load-external-model.md): 加载外部 3D 模型 (GLTF, OBJ 等)。
*   [Load Progress](./features/load-progress.md): 监控模型与全景图的加载进度 (Loaded/Refined)。
*   [Multi-Work (Sandbox)](./features/multi-work.md): 多 Work 加载与沙盘场景管理。
*   [Request Proxy](./features/request-proxy.md): 请求拦截与代理 (CDN 替换、鉴权)。
*   [Image Options](./features/image-options.md): 图片资源配置 (CDN, 格式, 尺寸)。

### 4. Rendering & Visuals (渲染与视觉)
画面表现与渲染管线配置。

*   [Pano Tile](./features/pano-tile.md): 全景瓦片渲染机制（高分辨率分片加载）。
*   [Model](./features/model.md): 内置模型渲染 (Mesh/Geometry)。
*   [Postprocessing](./features/postprocessing.md): 后处理效果 (Pass, EffectComposer)。
*   [Flowing Light 2D Pass](./features/flowing-light-2d-pass.md): 屏幕空间流光特效(InstancedMesh 优化)。
*   [Flowing Light 3D Pass](./features/flowing-light-3d-pass.md): 3D 世界坐标流光特效(InstancedMesh 优化)。
*   [Flowing Fireworks 3D Pass](./features/flowing-fireworks-3d-pass.md): 流光尾部喷射的烟花粒子特效(GPU 粒子)。
*   [Gaussian Blur Pass](./features/gaussian-blur-pass.md): 高斯模糊特效。
*   [Material](./features/material.md): 材质参数配置 (透明度、点云大小、顶点标记)。
*   [Pano Filter](./features/pano-filter.md): 全景图滤镜 (亮度、对比度、色温调节)。
*   [Get Screen Pixels](./features/get-screen-pixels.md): 获取屏幕像素 (放大镜/截图)。
*   [Move Pano Effect](./features/move-pano-effect.md): 全景点位切换的过渡效果。
*   [Clipper](./features/clipper.md): 模型裁切功能 (房屋剖面)。
*   [3D Tile](./features/3dtile.md): 大场景 3D Tile 渲染策略。

### 5. Interaction & Control (交互与控制)
用户输入与相机控制。

*   [Event](./features/event.md): 事件系统 (Tap, Gesture, StateChange)。
*   [Gesture](./features/gesture.md): 手势交互详解。
*   [Screen & Space Projection](./features/screen-project.md): 屏幕坐标与空间坐标转换 (标签/射线)。
*   [Raycast](./features/raycast.md): 射线检测 (点击拾取物体)。
*   [Camera Animation](./features/camera-animation.md): 相机动画控制 API。

### 6. Advanced & Extensions (进阶与扩展)
复杂配置与功能扩展。

*   [Plugin](./features/plugin.md): 插件开发指南。
*   [ViewLayer](./features/view-layer.md): 视图层。
*   [Parameter](./features/parameter.md): Five 初始化详细参数配置。

### 7. Meta & Support (其他)
*   [Support](./support.md): 浏览器兼容性。
*   [AI Documentation Guidelines](./ai-doc-guidelines.md): AI 文档编写与维护规范 (必读)。
*   Release Notes: 版本更新记录。
    *   [6.8](./release_notes/6.8.md)
    *   [6.7](./release_notes/6.7.md)
    *   [6.6](./release_notes/6.6.md)

## Common Scenarios (场景 → 文档速查)

> **Keyword Search Tip:** Each doc in `features/` has a `tags` yaml block at the bottom with Chinese and English keywords. Use these for keyword matching when the scenario table below doesn't cover your need.

| Scenario | Docs | Tags |
| :--- | :--- | :--- |
| 点击拾取物体 / Object picking | [Raycast](./features/raycast.md) | click, hit-test, floor-detection, 碰撞检测, 物体选择 |
| 3D 标签 / HTML overlay on 3D point | [Screen Project](./features/screen-project.md) | label, HUD, tooltip, 坐标转换, 3D转2D |
| 全景滤镜 / 色温调节 / Color correction | [Pano Filter](./features/pano-filter.md) | warm, cool, brightness, contrast, saturation, 暖色, 冷色, 饱和度 |
| 加载外部 GLTF/OBJ/FBX 模型 | [Load External Model](./features/load-external-model.md) | gltf, glb, ply, splat, fbx, draco, point-cloud, dispose |
| 相机巡航 / 自动导览 / Camera fly-through | [Camera Animation](./features/camera-animation.md) | rotate, zoom, auto-tour, 运镜, 旋转, 缩放 |
| 截图 / 放大镜 / Screen capture | [Get Screen Pixels](./features/get-screen-pixels.md) | magnifier, screenshot, color-picker, 取色器 |
| 模型裁切 / 房屋剖面 | [Clipper](./features/clipper.md) | clipping-box, section-view, discard, 开盖, 剖面 |
| 流光特效 / Flowing light effect | [Flowing Light 2D](./features/flowing-light-2d-pass.md), [Flowing Light 3D](./features/flowing-light-3d-pass.md) | 光带, 导航路径, 动态路径, instanced |
| 烟花 / 火花 / 流光拖尾粒子 / Fireworks sparks | [Flowing Fireworks 3D](./features/flowing-fireworks-3d-pass.md) | 烟花, 火花, 粒子, 发散, 爆裂, fireworks, particle, sparks |
| 模糊特效 / Blur effect | [Gaussian Blur Pass](./features/gaussian-blur-pass.md) | 毛玻璃, 背景虚化, gaussian |
| 保存/恢复场景状态 | [State](./features/state.md) | snapshot, save, restore, 快照, 场景还原 |
| 多场景切换 / 沙盘 | [Multi-Work](./features/multi-work.md) | sandbox, 多户型, 拼接, workCode |
| 请求鉴权 / CDN 替换 | [Request Proxy](./features/request-proxy.md) | authentication, token, url-rewrite, cors, 私有化 |
| 插件开发 | [Plugin](./features/plugin.md) | lifecycle, extension, baseplugin, 状态管理 |
| 事件监听 / 拦截默认行为 | [Event](./features/event.md) | preventDefault, waitUntil, on, off, gesture, 回调 |
| 手势交互 / 自定义拖拽 | [Gesture](./features/gesture.md) | tap, pan, pinch, press, 触摸, 鼠标 |
| 后处理特效 / 自定义 Shader | [Postprocessing](./features/postprocessing.md) | effect-composer, addPass, edl, 描边, 景深 |
| 材质 / 透明度 / 点云样式 | [Material](./features/material.md) | opacity, pointcloud, roof, ceiling, 天花板, 顶点标记 |
| 模式切换 / 全景↔模型↔户型图 | [Mode](./features/mode.md) | panorama, floorplan, mapview, topview, VR |
| 全景高清瓦片 / 分片加载 | [Pano Tile](./features/pano-tile.md) | LOD, tile, 按需加载, 高清全景 |
| 图片 CDN / 私有化部署 | [Image Options](./features/image-options.md) | avif, webp, cdn, private-deployment |
| 加载进度 / 首屏优化 | [Load Progress](./features/load-progress.md) | refined, loaded, loading-bar, 首屏 |

## Terminology Summary

*   **Work**: 包含全景图、模型、户型数据的 JSON 对象。
*   **Observer**: 观察点，通常对应一个全景拍摄点位。
*   **PanoIndex**: 全景点位的索引下标。
*   **Pose**: 相机位姿 (Longitude, Latitude, Fov)。
*   **Mode**: 浏览模式 (Panorama, Model, etc.)。

---
```yaml
tags: [index, readme, guide, map]
```