01Spatial Documentation

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

使用 Unity 模板开发 AR 应用

Unity 模板用于把 01Spatial 绝对定位接入 AR Foundation：ARKit 或 ARCore 负责帧间平滑跟踪，01Spatial 把这段本地 AR Session 对齐到持久地图坐标。

接入前准备

  • Unity 项目已安装与目标平台匹配的 AR Foundation、ARKit XR Plugin 或 ARCore XR Plugin。
  • 一张 Ready 地图的 Map Key，或一个 Project 的 Project Key。
  • Portal 个人资料中的 API Key。
  • 地图 Origin 已确认，Content 使用同一地图坐标系。

模板中的核心对象

保持下面的职责分离：

AR Session Origin
├── AR Camera             # 只由 AR Foundation 更新
└── Map Root              # 应用 01Spatial 的地图到 Session 变换
    └── Map Content       # 保存为地图坐标

不要把定位结果直接写到 AR Camera。每次采样必须从同一个相机更新中取得 CPU Image、相机内参和 AR Camera 变换，并在异步编码或网络请求前复制这些值。

接入顺序

  1. 用 ARCameraManager.TryAcquireLatestCpuImage() 获取相机图像。
  2. 同一更新中用 TryGetIntrinsics() 获取内参，并保存 AR Camera 的 camera-to-session 变换。
  3. 编码图像并调用定位 API；复制完成后及时释放 XRCpuImage。
  4. 只接受 HTTP 200、存在有效位姿且满足客户端置信度策略的响应。
  5. 使用返回位姿对应的同一采样帧计算地图到 AR Session 的变换，并应用到 Map Root。
  6. 后续可靠定位只校正 Map Root，本地 AR 相机继续由 AR Foundation 平滑跟踪。

完整请求字段、坐标转换和公式见定位 API 与 AR 集成。

上线检查

  • 图片、内参和 AR Camera 变换来自同一帧。
  • 图片旋转、裁剪或缩放后，内参与相机轴得到相同处理。
  • AR Session 重置后丢弃旧请求的响应。
  • API Key 不写入公开仓库或客户端日志；正式应用应通过受控配置交付。
  • iOS 与 Android 真机分别验证初始化、恢复跟踪和长时间漂移校正。