# 如视 Five SDK

# Five SDK Documentation

- 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 Documentation Guidelines 中的规范。

### 2. Application Development Strategy (应用开发建议)

当协助用户编写代码或构建 Five 应用时，请遵循以下阅读与检索策略：

- Initialization (初始化):
  - 阅读 Quick Start 掌握最小化启动流程。
  - 查阅 Parameter 获取 `new Five(config)` 的完整配置项（如 canvas 尺寸、资源路径、纹理压缩设置）。
- Data Handling (数据加载):
  - 核心 VR 数据：深入理解 Work 结构，它是 Five 渲染的基础。
  - 外部模型：参考 Load External Model 加载 GLTF/OBJ 等格式。
  - 多场景/沙盘：参考 Multi-Work (Sandbox) 处理复杂场景切换。
- Interaction & Logic (交互逻辑):
  - 事件监听：查阅 Event 处理用户点击 (Tap)、手势 (Gesture) 及状态变更 (StateChange)。
  - 空间操作：使用 Raycast 实现物体拾取，使用 Screen & Space Projection 实现 3D 标签挂载。
  - 动画控制：参考 Camera Animation 和 Move Pano Effect 实现平滑运镜。
- State Management (状态管理):
  - 保存/恢复场景：必须 深刻理解 State。它是 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 是最权威的接口定义来源，包含方法的参数与返回值。
- Terminology: 遇到不确定的术语 (e.g., Pose vs State, Observer) 时，务必查阅 Glossary。
- Core Relationships: 理解 Five (渲染器) 与 Work (数据) 的分离设计。

## Documentation Map

### 1. Essential Reference (必读/速查)

最常用的入口文档。

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

### 2. Core Concepts (核心概念)

基础架构与生命周期管理。

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

### 3. Data & Resource (数据与资源)

数据加载与资源管理配置。

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

### 4. Rendering & Visuals (渲染与视觉)

画面表现与渲染管线配置。

- Pano Tile: 全景瓦片渲染机制（高分辨率分片加载）。
- Model: 内置模型渲染 (Mesh/Geometry)。
- Postprocessing: 后处理效果 (Pass, EffectComposer)。
- Flowing Light 2D Pass: 屏幕空间流光特效(InstancedMesh 优化)。
- Flowing Light 3D Pass: 3D 世界坐标流光特效(InstancedMesh 优化)。
- Gaussian Blur Pass: 高斯模糊特效。
- Material: 材质参数配置 (透明度、点云大小、顶点标记)。
- Pano Filter: 全景图滤镜 (亮度、对比度、色温调节)。
- Get Screen Pixels: 获取屏幕像素 (放大镜/截图)。
- Move Pano Effect: 全景点位切换的过渡效果。
- Clipper: 模型裁切功能 (房屋剖面)。
- 3D Tile: 大场景 3D Tile 渲染策略。

### 5. Interaction & Control (交互与控制)

用户输入与相机控制。

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

### 6. Advanced & Extensions (进阶与扩展)

复杂配置与功能扩展。

- Plugin: 插件开发指南。
- ViewLayer: 视图层。
- Parameter: Five 初始化详细参数配置。

### 7. Meta & Support (其他)

- Support: 浏览器兼容性。
- AI Documentation Guidelines: AI 文档编写与维护规范 (必读)。
- Release Notes: 版本更新记录。
  - 6.8
  - 6.7
  - 6.6

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

## Terminology Summary

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

    tags: [index, readme, guide, map]