# 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: 双指缩放。

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