# 使用 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 使用同一地图坐标系。

## 模板中的核心对象

保持下面的职责分离：

```text
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 集成](/tutorials/localization/localization-api)。

## 上线检查

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