# 使用 KIRI Engine 扫描

[KIRI Engine](https://www.kiriengine.app/) 可以在支持 LiDAR 的 iPhone 或 iPad 上记录空间画面、设备的移动路径（相机轨迹）和深度信息。01Spatial 使用 **Scene Scan 的 Raw Data（原始数据）ZIP** 建立视觉地图，并在建图过程中进一步优化这条轨迹。

> 这条路径只接受 **LiDAR Scene Scan 的 Raw Data**。Room Scan、Object Capture、Photo Scan、3DGS，以及单独导出的 OBJ、USDZ、PLY 或 GLB 都不能替代 Raw Data ZIP。

## 1. 确认设备与输出

使用带 LiDAR 的 iPhone 或 iPad，并将 KIRI Engine 更新到能够导出 Scene Scan Raw Data 的版本。根据 KIRI Engine 当前的官方说明，导出 Scene Scan Raw Data 需要 KIRI Engine Pro。开始正式扫描前，请先用一次短测试确认导出菜单中能够看到 Raw Data。

一个可用于 01Spatial 的 ZIP 至少应包含：

```text
transforms.json   # 每张画面的相机参数与位置
image/            # 建图使用的原始画面
depth/            # 可选：深度图
confidence/       # 可选：标记深度值可靠程度的图
```

`transforms.json` 与 `image/` 是必需内容。不要只导出三维模型，也不要重命名文件或调整 ZIP 内部目录。

## 2. 扫描前开启 Developer Mode

Raw Data 属于 KIRI Engine 的开发者导出；应在正式扫描前确认该功能已经开启。

1. 打开 KIRI Engine，进入 **Me（我的）**。
2. 打开 **Developer Mode**。
3. 返回首页，先完成一次短 Scene Scan，并确认能够导出 Raw Data。
4. 确认设备有足够的电量与存储空间，再开始正式扫描。

如果菜单名称随 KIRI Engine 版本变化，请以 [KIRI Engine 官方 Raw Data 说明](https://www.kiriengine.app/blog/kiri-engine-3.14-release)为准。看不到 Raw Data 时，不要用普通模型文件代替。

## 3. 准备空间

- 打开现场照明，让门框、墙角、标识和固定设施保持清晰。
- 清洁镜头，并确认手机壳或保护膜没有遮挡镜头和 LiDAR 传感器。
- 暂停搬运、布置和清洁作业，避免桌椅、门扇、展架等物体在扫描过程中改变位置。
- 规划一条连续路线，覆盖所有需要定位或放置 AR 内容的区域，并回到已经扫描过的位置形成闭环。

玻璃、镜面、强反光金属和大面积纯色表面会降低画面与深度数据的稳定性。无法避开时，应从多个方向拍摄其周围的门框、墙角和固定构件，不要让困难表面长时间占满画面。

## 4. 开始 Scene Scan

1. 在 KIRI Engine 首页选择 **+**。
2. 选择 **LiDAR Scan**，再选择 **Scene Scan**。
3. 在起点缓慢观察周围的墙面、地面、门框和固定设施，确认实时覆盖正常。
4. 开始沿规划路线连续移动。

[![KIRI Engine 的 LiDAR Scan 菜单，其中 Scene Scan 是用于扫描空间的正确类型](/media/docs/kiri-mobile-scene-scan-mode.real-ui.jpg)](/media/docs/kiri-mobile-scene-scan-mode.real-ui.jpg)

不要选择 Room Scan 或 Object Capture。它们的输出结构与 Scene Scan Raw Data 不同，不能用于本流程。

## 5. 扫描完整路线

1. 以正常步速平稳移动，避免快速旋转或大幅晃动设备。
2. 让相邻位置持续看到共同区域，同时逐步拍到新的墙面和结构。
3. 经过门口、转角、楼梯和房间连接处时放慢，并从两侧重复观察连接区域。
4. 对覆盖不完整的位置，从不同角度平稳补扫；不要快速摆动手机来追赶覆盖提示。
5. 在路线末端回到起点附近，或重新经过一段已经扫描的路线，形成闭环后再结束。

扫描时，KIRI Engine 会把实时相机画面与正在恢复的三维表面叠加显示。白色网格表示已经扫描到的空间结构，未出现网格的区域仍需从稳定、清晰的角度补扫。底部红色按钮用于结束扫描；完成整条路线并形成闭环之前不要提前点击。

[![KIRI Engine 的 Scene Scan 扫描进行中界面，实时相机画面上叠加正在恢复的白色三维网格](/media/docs/kiri-mobile-scene-scan-progress.real-ui.jpg)](/media/docs/kiri-mobile-scene-scan-progress.real-ui.jpg)

大型空间可以分成多个相互重叠的区域，但同一次扫描必须保持空间连续。设备明显发热、操作持续卡顿或跟踪反复丢失时，应在已经充分覆盖的位置结束本次扫描，不要带着错误继续移动。

## 6. 完成前检查

- [ ] 所有目标房间、门口、转角和路线端点都已覆盖。
- [ ] 相邻区域之间有连续、清楚的共同画面。
- [ ] 没有长时间的模糊、过暗、过曝或镜头遮挡。
- [ ] 实时模型中的墙面、门框和地面没有明显重叠、倾斜或断裂。
- [ ] 路线回到了已扫描区域，并形成闭环。

如果实时模型已经与真实空间明显错位，继续扫描通常只会扩大错误。应结束并删除这次失败扫描，改善路线或移动速度后重新开始。

## 7. 在设备上处理并导出 Raw Data

### 使用 Local Processing 完成项目

结束扫描后，KIRI Engine 会要求选择处理方式。选择 **Local Processing**，再点击 **Start Processing**，即可在当前设备上处理项目。处理过程中保持 KIRI Engine 在前台运行，并确保设备有足够电量和可用存储空间。

[![KIRI Engine 扫描完成后的处理方式界面，Local Processing 已选中，底部显示 Start Processing](/media/docs/kiri-mobile-local-processing.real-ui.jpg)](/media/docs/kiri-mobile-local-processing.real-ui.jpg)

这里的本地处理用于完成并保存 KIRI Engine 项目。上传至 01Spatial 的建图主输入仍然是下一步导出的 **Raw Data ZIP**，不是界面中看到的三维预览模型。

### 导出 Raw Data ZIP

1. 在最初采集数据的设备上打开已完成的 Scene Scan。
2. 在项目页面点击 **Export**，进入导出菜单。
3. 选择 **Raw Data**；如果名称有所变化，请选择明确标注为“原始数据集”的选项。
4. 等待 ZIP 完整保存，不要在导出过程中切换项目或清理应用数据。
5. 解压一份副本，确认其中存在 `transforms.json` 和 `image/`，然后保留未经修改的原始 ZIP 用于上传。

[![KIRI Engine 已完成的 Scene Scan 项目页面，底部的 Export 按钮用于进入文件导出菜单](/media/docs/kiri-mobile-export.real-ui.jpg)](/media/docs/kiri-mobile-export.real-ui.jpg)

如需在 Space Studio 中查看三维表面，可另行导出 GLB 模型，并将其单独放入另一个 ZIP。Raw Data ZIP 是建图主输入；这个 Mesh（三维表面模型）ZIP 只用于可选预览，不能替代 Raw Data。

## 8. 上传到 01Spatial

1. 打开 Portal 的 **Spatial Maps**，进入目标项目并选择 **+ New Map**。
2. 为地图命名，然后选择 **KIRI** 输入类型。
3. 在 **Upload from** 中选择来源：
   - **Cloud（推荐）**：先把 Raw Data ZIP 上传到界面支持的网盘，生成这个文件的分享链接；选择对应网盘并把链接粘贴到 **Raw Data URL**。如有 Mesh ZIP，把它的链接粘贴到可选的 **Mesh URL**。选择 **Download from Cloud** 后，服务器会直接下载文件。
   - **Local**：从电脑选择 Raw Data ZIP；如有 Mesh，再选择独立的 Mesh ZIP。保持页面打开直到上传完成。
4. 等待 Portal 检查输入并进入建图流程。

[![Spatial Maps 的 New Map 界面，KIRI 输入已选中，Cloud 来源、Raw Data 和可选 Mesh 链接输入框清晰可见](/media/docs/spatial-maps-new-map-kiri-cloud.real-ui.jpg)](/media/docs/spatial-maps-new-map-kiri-cloud.real-ui.jpg)

> KIRI 这条路径上传的是 **Raw Data ZIP，不是普通视频或单独的三维模型**。大文件优先使用 Cloud；分享链接必须指向单个 ZIP，并允许服务器读取。不要使用文件夹链接、需要登录才能打开的链接，或浏览器地址栏中的普通预览地址。

Portal 会检查 ZIP 中是否存在 `transforms.json` 和 `image/`。缺少其中任意一项、ZIP 损坏，或只上传模型文件都会导致输入被拒绝。

## 建图后验收

地图变为 **Ready（已就绪）** 后，[使用 Space Studio 执行定位测试](/tutorials/localization/space-studio-test)，检查起点、路线中部、门口、转角和终点。重点验证相互连通区域是否连续，以及正常持机高度和实际照明条件下的定位表现。

在完成定位验收前，请保留 KIRI Engine 项目、原始 Raw Data ZIP 和可选 Mesh ZIP。