@realsee/five/ai_guides/glossary.md

Realsee Renderer SDK

# Glossary (术语表)

- **Summary**: Five SDK 中的核心术语定义与解释。
- **Audience**: 开发者、AI 助手。

## Core Entities (核心实体)

### Five
SDK 的核心入口类。一个 `Five` 实例对应一个 `<canvas>` 渲染上下文，负责管理场景生命周期、渲染循环、用户交互和状态更新。

### Work
VR 看房的**运行时实体**。通常指经过 `parseWork` 解析后生成的标准化数据对象。
- **LooseWork**: 服务端下发的原始 JSON 数据，结构较宽松。
- **WorkJson**: `workToJson` 生成的标准序列化数据，用于存储。
- **包含内容**: Observers, Panorama, Model, Plan 等。

### Vertex Marks (顶点标记)
在模型顶点上通过 `_feature_id_rsmask` 属性进行的标记。
- 用于在特定视角（如俯视）下控制 Mesh 的显隐（例如隐藏天花板）。
- 属于材质配置的一部分。

### Observer
**观察点**。对应现实空间中拍摄全景图的一个物理位置。
- 属性包含：位置 (position)、旋转 (quaternion)、关联的全景图信息。
- 用户在“全景模式”下，实际上是在不同的 Observer 之间跳转。

## State & Coordinates (状态与坐标)

### Mode (模式)
Five 定义的五种浏览状态：
1.  **Panorama (全景)**: 第一人称视角，固定在某个点位观察 360° 景象。
2.  **Floorplan (户型图)**: 2D 顶视视角，查看房屋平面结构。
3.  **Topview (顶视)**: 3D 俯视视角，可自由旋转查看房屋立体结构。
4.  **Model (模型)**: 自由漫游视角，可像游戏一样在模型中自由行走（脱离全景点位）。
5.  **Map (地图)**: 类似 Google Earth 的操作方式，用于大场景鸟瞰。

### Pose (位姿)
描述相机状态的数据结构。
- **Panorama 模式下**: 使用球面坐标 `(Longitude, Latitude)` + `Fov`。
- **其他模式下**: 使用 `(x, y, z)` 坐标或变换矩阵。

### PanoIndex
**全景索引**。当前所在的 Observer 在 `work.observers` 数组中的下标 (从 0 开始)。

### Fov (Field of View)
**视场角**。决定了视野的宽窄。
- 数值越大，视野越广（广角）。
- 数值越小，视野越窄（长焦/放大）。

## Rendering (渲染)

### Pano Tile (全景瓦片)
为了在移动端快速加载高分辨率全景图（如 8K/16K），将全景图切分为多个小块（瓦片）。Five 会根据当前视角按需加载可见区域的瓦片。

### Mesh (三维网格)
**三维模型**。通过激光扫描或视觉算法重建的空间几何结构。在 Five 中，全景图贴在几何模型上，从而实现“从全景中看出立体感”的效果。

### G-Buffer / Geometry Buffer
用于后处理的几何缓冲区，包含深度 (Depth)、法线 (Normal)、ID 等信息，用于实现高级特效（如轮廓线、SSAO）。

### ViewLayer
管理 `Model` 内部特定 3D 资源（如 Mesh、PointCloud、Gaussian Splatting）的图层。
- 继承自 `Tile3D`。
- 拥有独立的 `Parameter` 配置（覆盖上层配置）。
- 支持可见性控制 (`visible`) 和优先级加载。

### Gaussian Splatting
一种基于点的 3D 渲染技术，通过各向异性高斯球（Splat）来表示场景。
- 相比传统 Mesh，能更真实地还原复杂光照和细节。
- Five 支持 `.spz` 和 `.splat` 格式的 Gaussian Splatting 渲染。

### 3D Tiles Refinement (细化)
3D Tiles 加载过程中的状态概念：
- **Loaded (已加载)**: 瓦片的基本数据已下载并解析，满足最低显示要求 (`minLevelOfDetail`)。
- **Refined (已细化)**: 瓦片已加载最高质量数据，满足当前视角的屏幕空间误差要求 (`maxScreenSpaceError`)。
- `five.model.refineProgress` 可用于监控当前视角的细化进度。

## Interaction (交互)

### Raycast (射线检测)
将屏幕上的 2D 点击坐标转换为 3D 空间中的射线，用于检测用户点击了哪个物体（如点击地面移动、点击标签）。

### Tap / Press / Pan / Pinch
Five 封装的手势事件：
- **Tap**: 轻触。
- **Press**: 长按。
- **Pan**: 拖拽/平移。
- **Pinch**: 双指缩放。

---
```yaml
tags: [术语, 概念, glossary, terminology, definitions, observer, pose, mode, work, panoindex, fov, viewlayer, gaussian-splatting, 3dtile]
```