# 配置扫描数据

Map Configurator 用现场实测坐标标记视频中的固定角点，从而确定地图的真实大小、原点和坐标方向。Portal 会直接加载已经解析好的全景画面，不需要再次上传视频。

> **GCP** 是 **Ground Control Point（地面控制点）** 的缩写。这里的“地面”是测绘术语，GCP 不必位于地板上；门框角点、墙根交点或固定构件角点都可以。关键是该点不会移动、可在多个画面中准确确认，并且现场 X、Y、Z 坐标已知。

[![Map Configurator 英文界面总览：全景视图、底部帧带、Points 与 Scale-bars 配置面板、世界朝上轴和 Build 按钮](/media/docs/configurator-overview-real-ui.en.jpg)](/media/docs/configurator-overview-real-ui.en.jpg)

> 手工配置建图至少需要 **3 个可用且不共线的 GCP**，也就是这 3 个点不能位于同一直线上。正式项目建议使用 **4–5 个 GCP**，其中至少 4 个不能全部落在同一墙面、地面或其他平面上，并覆盖左右、高低和近远三个方向。每个 GCP 都要填写以米为单位的 X、Y、Z 坐标，并在至少 2 个不同的全景画面中标记。Tie Point（连接点）和 Scale Bar（距离标尺）只能补充连接或距离信息，不能代替 GCP。

## 先理解三类配置

| 类型 | 需要填写 | 解决的问题 |
| --- | --- | --- |
| **GCP（地面控制点）** | X、Y、Z，单位米 | 定义地图的真实大小、原点和坐标方向 |
| **Tie Point（连接点）** | 不需要坐标 | 把多个画面中的标记关联为同一个固定角点，加强房间、门口或走廊之间的连接 |
| **Scale Bar（距离标尺）** | 两端的真实距离，单位米 | 为地图增加一条独立的实测距离约束 |

GCP 定义一个点的完整坐标；Scale Bar 只提供长度；Tie Point 只说明不同画面中标记的是同一个点。三者不能相互替代。

## 1. 打开配置并确定坐标系

1. 等待 Spatial Maps 中的地图状态变为 **Parsed（已解析）**。
2. 在地图卡片中选择 **Configure**，打开 Map Configurator。
3. 从底部缩略图列表选择一帧。拖动中央画面观察四周；需要精确标点时选择右上角 **Full Resolution**。
4. 在右侧 **WORLD UP** 中选择地图里表示“竖直向上”的坐标轴：
   - **Y**：常用于 AR 和实时 3D。原点在地面时，地面点通常满足 `Y = 0`。
   - **Z**：常用于测绘和 CAD。原点在地面时，地面点通常满足 `Z = 0`。
5. 确认这个约定与后续 Space Studio 内容或已有测量坐标一致。配置开始后不要更换坐标约定。

## 2. 添加第一个 GCP

### 创建点

1. 在全景画面中找到已经测量过的固定角点。优先选择墙面、地面和固定建筑构件形成的交点；它们比物体表面上的任意位置更容易在多个画面中重复确认。
2. 右键该位置，选择 **Add Point**。
3. 新点会出现在右侧 **Points** 列表和当前帧中。

[![在门洞右侧墙根角点打开 Map Configurator 右键菜单，Add Point 处于高亮状态](/media/docs/configurator-step-gcp-add.en.jpg)](/media/docs/configurator-step-gcp-add.en.jpg)

*将标点位置精确对准门框与地面的固定角点，再选择 **Add Point**。不要把阴影边缘、反光、高光、植物或可移动物体作为控制点。*

### 填写名称和坐标

1. 为点填写可识别的名称，例如 `O · Corridor origin`。
2. 选择点右侧的 **XYZ**。
3. 按当前世界坐标系输入 X、Y、Z；单位始终是米。
4. 核对正负号和小数点后选择 **Save**。填写坐标后，该点类型会显示为 **GCP**。

[![Map Configurator 英文界面：为走廊原点 O 填写以米为单位的 0、0、0 坐标](/media/docs/configurator-step-gcp-coordinates.en.jpg)](/media/docs/configurator-step-gcp-coordinates.en.jpg)

*示例把墙根角点定义为世界原点 `O = (0, 0, 0)`。填写完整的 X、Y、Z 后，该点成为 GCP；若只需要 Tie Point，应保持三个坐标均为空。*

### 添加多帧观测

1. 在底部画面列表中切换到另一帧，确认它也能清楚看到同一个物理点。
2. 在完全相同的位置右键，展开 **Add Observation**，再选择刚创建的点。
3. 至少在 2 个不同帧中完成观测。若第 3 帧也能清楚看见同一角点，并且拍摄位置不与前两帧重合，建议继续添加第 3 帧。
4. 在右侧展开 **Obs**，逐帧检查图片名称。若某次点击不准确，先删除该观测再重新添加，不要移动到“看起来差不多”的位置。

[![Map Configurator 在第二帧的同一墙根角点展开 Add Observation，并显示可选择的 O Corridor origin](/media/docs/configurator-step-gcp-observations.en.jpg)](/media/docs/configurator-step-gcp-observations.en.jpg)

*在新帧的同一物理角点右键，展开 **Add Observation**，再选择已有的 GCP。*

## 3. 用 GCP 定义三维坐标系

重复创建点、填写坐标并添加多帧观测。系统要求至少 3 个可用且不共线的 GCP。正式项目建议配置 4–5 个 GCP，其中至少 4 个不能全部落在同一平面上。每个 GCP 必须同时满足：

- X、Y、Z 都是有效数值，且单位为米。
- 至少有 2 个不同全景帧中的观测。
- 所有观测都落在同一个静态物理点上。
- 至少 3 个 GCP 的世界坐标不接近同一条直线。
- 建议所有 GCP 共同覆盖左右、高低和近远，不全部落在同一面墙、同一地面或其他单一平面上。

下面的门洞示例用 4 个角点直接建立 `O-X-Y-Z` 坐标骨架。这里采用 Y 轴向上（Y-up）：

| 点 | 示例坐标（米） | 约束方向 |
| --- | --- | --- |
| **O · Corridor origin** | `(0, 0, 0)` | 墙根原点 |
| **X · Threshold right** | `(2.4, 0, 0)` | 沿门槛覆盖 X |
| **Y · Jamb upper-left** | `(0, 2.8, 0)` | 沿竖直门框覆盖 Y |
| **Z · Corridor far-left** | `(0, 0, 5.6)` | 沿走廊深度覆盖 Z |

这 4 个点不在同一平面上，因此能够同时确定 X、Y、Z 三个方向。大空间可在远端再增加第 5 个 GCP，用于交叉检查测量和标记是否正确。表中的数值只用于说明坐标关系；实际项目必须填写现场测量结果，不要为了得到整数或整齐的轴向数值而修改实测坐标。

[![Map Configurator 全景画面中四个橙色 GCP 分别定义墙根原点以及 X、Y、Z 三个方向，右侧 Points 计数为四](/media/docs/configurator-step-gcp-distribution.en.jpg)](/media/docs/configurator-step-gcp-distribution.en.jpg)

*四个橙色 GCP 分别位于近端左下、近端右下、近端左上和走廊远端角点；它们共同覆盖 X、Y、Z，而不是落在同一个平面。*

## 4. 添加 Tie Point

Tie Point 适合门口、长走廊转角、外观重复的区域或相互连通房间的过渡处。它不需要现场坐标，只用于告诉系统“这些画面中标记的是同一个不会移动的物理角点”。

1. 选择在相邻区域两侧都清晰可见、不会移动且容易重复点击的**几何角点**。例如固定基座的上角、地砖填缝线的十字交点，或门框与横梁的交角。不要点击平整墙面、地面花纹或一段边线上的任意位置。
2. 右键并选择 **Add Point**。
3. 填写名称，但保持 X、Y、Z 为空；右侧类型应显示 **Tie Point**。
4. 切换到连接另一侧的帧，在同一物理位置通过 **Add Observation** 选择这个 Tie Point。
5. 至少添加 2 帧观测，并展开 **Obs** 逐项核对。
6. 只保留自己能够确认属于同一物理角点的观测。错误的 Tie Point 比缺少 Tie Point 更容易破坏建图结果。

[![Map Configurator 全景画面中三个亮青绿色 Tie Point 分别精确落在固定基座上角、地砖接缝十字交点和门洞横梁角，右侧显示 Tie Point 类型与观测数量](/media/docs/configurator-step-tie-point.en.jpg)](/media/docs/configurator-step-tie-point.en.jpg)

*三个亮青绿色 Tie Point 都应落在不同画面中可以重复点击的真实角点上；它们还应分布在需要加强连接的位置，而不是重叠在同一小块区域。*

## 5. 添加 Scale Bar

当现场有一段可靠的实测距离时，可以用 Scale Bar 进行独立的距离校验。优先选择长度明确、两端容易重复识别、能从多个位置看到的固定线段。

1. 先在现场测量两端之间的直线距离，记录单位为米。
2. 在能够同时看清两端的全景帧中右键，选择 **Add Scale-bar**。
3. 右键位置成为端点 A；随后在同一帧准确点击端点 B。
4. 打开右侧 **Scale-bars**，为线段填写清晰名称和实测长度。
5. 切换到其他帧，为端点 A 和 B 添加成对观测。每个端点至少应在 2 个不同帧中可见。
6. 回到 **Scale-bars**，确认状态显示 **Ready（可用）**，长度和单位无误。

[![Map Configurator 全景画面中一条 2.4 米 Scale Bar 精确连接门洞两侧墙根角点，右侧状态为 Ready](/media/docs/configurator-step-scale-bar.en.jpg)](/media/docs/configurator-step-scale-bar.en.jpg)

*示例把门槛两侧固定角点之间的实测宽度设为 2.4 米。确认黄色线段连接了正确的两个物理端点，并在右侧显示 **Ready**。Scale Bar 不能替代 GCP。*

## 6. 提交建图前检查

右侧状态会显示当前缺少的内容。选择 **Build** 前逐项确认：

- [ ] 至少 3 个可用且不共线的 GCP 拥有有效的 XYZ 坐标，单位为米。
- [ ] 每个 GCP 在至少 2 个不同全景帧中有观测。
- [ ] 正式项目优先使用 4–5 个不全部位于同一平面的 GCP，并覆盖左右、高低和近远。
- [ ] GCP 没有全部落在同一面墙、同一地面或同一个角落。
- [ ] 每个 Tie Point 至少有 2 帧观测，且确实对应同一个固定物理角点。
- [ ] 每个准备使用的 Scale Bar 都显示 **Ready**，长度单位为米。
- [ ] WORLD UP 与项目坐标约定一致。
- [ ] 没有观测落在模糊、遮挡或错误的物理位置。

选择 **Build** 后，Map Configurator 会提交当前配置并触发建图；解析好的全景帧仍保留在服务器，不会重复上传。

## 常见问题

### GCP 数量够了，Build 仍然不可用

检查每个 GCP 是否至少有 2 帧观测，以及任意 3 个点是否几乎位于同一直线上。只有坐标、没有足够观测的点不算可用 GCP。4–5 个覆盖三维空间的点是质量建议，系统的最低数量仍为 3 个。

### 同一个点在其他帧中很难确认

切换到 **Full Resolution** 并放大检查。如果仍不确定，删除这一观测并改选不会移动、边界清楚的几何角点；不要猜测位置。

### 应该添加多少 Tie Point

只在相邻画面共同可见区域较少的位置添加。门口、转角或房间连接处的少量准确 Tie Point，通常比在整个地图中随意添加大量点更有效。

配置通过检查后继续[建图与验收](/tutorials/mapping/panorama-camera-video/build)。