01Spatial Documentation

Machine-readable: manifest · index · 简体中文 Markdown

使用 KIRI Engine 扫描

KIRI Engine 可以在支持 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 至少应包含：

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 说明为准。看不到 Raw Data 时，不要用普通模型文件代替。

3. 准备空间

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

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

4. 开始 Scene Scan

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

KIRI Engine 的 LiDAR Scan 菜单，其中 Scene Scan 是用于扫描空间的正确类型

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

5. 扫描完整路线

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

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

KIRI Engine 的 Scene Scan 扫描进行中界面，实时相机画面上叠加正在恢复的白色三维网格

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

6. 完成前检查

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

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

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

使用 Local Processing 完成项目

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

KIRI Engine 扫描完成后的处理方式界面，Local Processing 已选中，底部显示 Start Processing

这里的本地处理用于完成并保存 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 按钮用于进入文件导出菜单

如需在 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 链接输入框清晰可见

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

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

建图后验收

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

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