hz-unity-passthrough-camera-access

Meta Quest 直通摄像头访问（PCA）

直通摄像头访问基于 Android Camera2 API 构建，可访问 Quest 3 和 Quest 3S 上朝前的 RGB 摄像头，以支持计算机视觉和机器学习。此 API 与 Media Projection API 不同。后者支持投射用户的视角（包括 UI），如果你的目的是呈现用户所看到的内容，就应该使用它。使用直通摄像头 API 可添加特定于应用的计算机视觉功能，进一步理解用户的环境和行为，超出 Scene API 所提供的能力。

使用场景

此 API 使用朝前的 RGB 摄像头提供无遮挡的视野，并可集成到 ML/CV 工作流中。常见使用场景：

1. 经过专门训练的 ML/CV 模型，可识别应用能够交互的特定物体（例如哑铃等健身器材、调音台等工业设备）。
2. 用于体验的 ML/CV 助手或向导。例如，在博物馆导览中，用户注视一幅画作时，应用会调用设备外的大模型，显示有关其历史、艺术家和风格的信息。
3. 为训练或特殊兴趣应用提供反馈：应用要求用户执行一项任务后，可通过解读环境变化来检测任务是否正确完成（例如在白板上书写）。
4. 改进设计。通过解读光照情况或使用摄像头图像修改纹理，可以实现更逼真的设计效果。

一般前提条件

1. Horizon OS v74 或更高版本。
2. Quest 3 或 Quest 3S（不支持 Quest Pro 及更早型号）。
3. 需要 android.permission.CAMERA 或 horizonos.permission.HEADSET_CAMERA 权限。CAMERA 可访问直通摄像头和 Avatar 摄像头；HEADSET_CAMERA 仅可访问直通摄像头。
4. 必须启用 Passthrough 功能，才能访问直通摄像头 API。

使用 Android Camera2 的直通摄像头

Meta VR 设备上的摄像头访问基于 Horizon OS 中的 Android Camera2 API 实现。从 Horizon OS v74 开始，Meta VR 头戴设备支持 Camera2 及其 Unity 扩展（Horizon OS v83 新增了 Unreal 扩展）。在 Quest 3 和 Quest 3S 上，开发者可以访问头戴设备正面的左、右摄像头。

Android Camera2 API 提供：

• **图像采集：**采集摄像头数据以进行高级处理。
• **摄像头元数据：**查询 API，获取硬件功能和配置信息。
• **多摄像头支持：**访问和控制多个摄像头。

已知问题

1. 在刷入新 OS 后，首次安装使用 v74 中 Camera API 的应用时，RGB 通道可能会翻转，导致颜色失真（例如，肤色会呈现蓝色）。重启设备即可修复。
2. XR Simulator 不支持直通摄像头 API。
3. 直通摄像头纹理捕获的是一个矩形区域（1280×960），小于用户看到的范围。v83 新增的 1280×1280 分辨率扩大了垂直视野，但仍未覆盖整个直通视野。
4. 如果应用是通过 Meta Quest Developer Hub 安装的，家长为限制青少年和儿童账户而设置的限制（例如限制访问直通摄像头 API）不会生效。

最佳实践

1. 确保用户隐私。 相机图像数据被视为设备用户数据，受《开发者数据使用政策》约束。请严格遵守该政策。
2. 避免在设备上进行高成本处理。 在设备上处理相机图像可以实现引人注目的用例，但应通过保持较高的帧率，确保体验流畅舒适。
3. 在设备上验证图像流。 部署后，在流水线运行时执行 metavr adb logcat --follow --tag Unity，确认帧能够正常流动；集成前，使用 metavr docs search "passthrough camera access Unity" 检查 PCA API 是否有变更——这一接口变化很快。

参考资料

关于如何在世界空间中投影和放置 PCA 图像的详细任务专属指南，请参阅 references/：

• references/principal-point-offset.md — 使用光轴作为平面法线，将相机图像正确投影到平坦的世界空间表面上（视锥切片四边形、视场角可视化工具、图像平面叠加层）。如果 ViewportPointToRay 发出的角点射线生成了非矩形四边形、与相机对齐的四边形偏离中心，或者在相机主点偏移的设备上 2 * d * tan(fov / 2) 得出的尺寸不正确（尽管在 Quest 3 上有效），请阅读本文。
• references/detection-bounding-boxes.md — 为机器学习模型检测到的真实世界物体绘制精确的 3D 边界框。如果要将 2D 机器学习检测结果（YOLO、SSD、DETR、自定义 CNN）放置到世界空间中、根据 2D 检测结果构建朝向相机的公告板四边形，或连接 PassthroughCameraAccess 与 EnvironmentRaycastManager 以实现物体定位，请阅读本文。