# 使用 Space Studio 执行定位测试

在应用接入定位 API 之前，可以先用 Space Studio 和现场测试照片验证已就绪地图。测试使用与 API 相同的定位服务，并将每次定位得到的相机位置和朝向直接显示在地图中。

> **测试要求：** 照片应覆盖多个位置、拍摄方向、光照条件和计划使用的设备。单张照片定位成功，只能证明该位置和方向有效，不能证明整个空间都能稳定定位。

## 开始前需要准备

你需要：

- 一个能够访问目标地图的 01Spatial Portal 账号。
- 一张状态为 **Ready（已就绪）** 的地图。
- 在地图覆盖区域内拍摄的清晰 JPG 或 PNG 图片。
- 与上传图片的实际像素尺寸匹配的相机内参（描述相机焦距和图像中心的参数）：`fx`、`fy`、`cx`、`cy`。

如果图片经过缩放或裁剪，必须按相同比例和裁剪偏移调整内参。估算值只能用于初步检查；正式验收应使用相机 API 提供的内参或相机标定结果。

## 1. 在 Space Studio 中打开地图

1. 在 Portal 中打开 **Spatial Maps**。
2. 找到需要验证的 Ready（已就绪）地图。
3. 点击地图卡片上的 **Open**。

Space Studio 会在新标签页中打开，并加载地图的三维点云，以及建图时各相机的位置和朝向。

## 2. 切换到定位模式

在左侧**位姿**面板中，从**建图**切换到**定位**。建图模式显示参与建图的相机；定位模式用于创建独立的查询图片测试集。

如果**定位**不可用，请确认地图已经处于**已就绪**状态，并且定位所需文件已经生成完成。

[![Space Studio 左侧位姿面板切换到定位模式，测试集区域等待添加查询图片](/media/docs/space-studio-localization-mode.real-ui.jpg)](/media/docs/space-studio-localization-mode.real-ui.jpg)

## 3. 添加覆盖实际场景的测试照片

把 JPG 或 PNG 文件拖入定位测试区域，或通过文件选择器添加。你可以一次加载多张图片，也可以在同一个 3D 视图中比较多组测试。

每组照片都应回答实际使用中的问题：

- 访客从实际行进方向接近入口时能否定位？
- 重复走廊或白墙区域是否包含足够的视觉信息？
- 白天构建的地图能否用于定位夜间或弱光环境下拍摄的图片？
- 计划投入生产的不同设备表现是否一致？

## 4. 输入相机内参

打开 **Parameters**，输入与上传图片分辨率对应的内参。

| 字段 | 含义 |
| --- | --- |
| `fx` | 水平焦距，单位为像素 |
| `fy` | 垂直焦距，单位为像素 |
| `cx` / `ox` | 水平主点，单位为像素 |
| `cy` / `oy` | 垂直主点，单位为像素 |

只有当上传文件中的画面方向与拍摄方向不一致时，才开启旋转处理。除非 01Spatial 支持人员明确要求，否则保持默认定位设置。

[![Localization Parameters 对话框，包含相机内参、查询图像缩放、Auto Match Map 和定位选项](/media/docs/space-studio-localization-parameters.real-ui.jpg)](/media/docs/space-studio-localization-parameters.real-ui.jpg)

## 5. 运行并检查结果

点击 **Run**。Space Studio 会按顺序处理图片，并显示：

- 每张图片的成功或失败状态。
- 定位相机在 3D 地图中的位置和朝向（以视锥体表示）。
- 当前图片中用于确认定位结果的匹配点。
- 当前账号允许查看的置信度（confidence）和诊断指标。

开始运行前，Portal 会显示本次测试需要的 Credits 或价格。每张完成处理的图片与 API 定位查询遵循相同的账号计费规则。

## 6. 判断地图是否可以使用

一组合格的测试照片应该覆盖计划使用的区域，而不是包含大量位置和方向几乎相同的图片。遇到失败时请依次检查：

1. 确认照片的拍摄位置位于地图覆盖范围内。
2. 核对相机内参与上传图片的分辨率、裁剪和画面方向是否一致。
3. 检查运动模糊、强反光、遮挡或大面积无纹理表面。
4. 在 3D 地图中比较失败视角与附近成功视角。
5. 先重新拍摄更清晰或视野更宽的图片，再判断是否需要补充地图覆盖。

这些测试照片全部通过后，请继续阅读[定位 API 与 AR 集成](/tutorials/localization/localization-api)，接入通用客户端。