physicalai-runtime-adding-a-camera-backend

添加相机后端

相机通过实现 src/physicalai/capture/camera.py 中的 Camera 接口来构建。工厂入口：src/physicalai/capture/factory.py 中的 create_camera() 将小写类型名称（uvc、realsense、basler 等）映射到相应实现。参考目录：src/physicalai/capture/cameras/uvc/、src/physicalai/capture/cameras/realsense/、src/physicalai/capture/cameras/basler/。

工作流程

1. 选择参考后端，选择与新硬件最接近的后端（UVC 适用于 USB 视频、RealSense 适用于 RGB-D、Basler 适用于 GenICam 工业相机）。
   • 完成标准：你可以列出需要参照实现的模块（_camera.py、_discover.py、__init__.py 导出）。
2. 实现 Camera：实现 connect()、disconnect()、read() / read_latest()、上下文管理器支持，以及 Frame 上的单调时间戳（src/physicalai/capture/frame.py）。
   • 完成标准：使用虚假设备或模拟设备的测试可以在没有硬件的情况下测试连接和读取。
3. 如果设备可以枚举，则接入发现功能——在 src/physicalai/capture/discovery.py 或后端专用的 _discover.py 下添加辅助函数。
4. 在 src/physicalai/capture/factory.py 中注册类型；如果该类面向用户，则从 src/physicalai/capture/__init__.py 导出。
5. 对于厂商 SDK，可在 pyproject.toml 中添加可选附加依赖；在相机模块中延迟导入，使 pip install physicalai 保持轻量。
   • 完成标准：没有安装附加依赖时，import physicalai.capture 仍可正常运行；缺少附加依赖时，导入相机类会失败并显示清晰的错误消息。
6. 在 tests/unit/capture/ 中添加测试，使用现有的虚假对象（tests/unit/capture/fake.py、conftest.py 中的模式）。
   • 完成标准：uv run pytest tests/unit/capture -k <backend> 通过。

共享传输

对于多进程访问，create_camera(..., shared=True) 会使用 SharedCamera 包装相机（需要 physicalai[capture] / transport 附加依赖，即 iceoryx2）。仅在安装了传输附加依赖时，才记录共享模式。

必须检查的项目

• 如果 CameraType 或工厂字符串对用户可见，则需在 docs/reference/camera-api.md 中记录。
• 帧的形状和数据类型需与 README 示例一致（RGB 为 (H, W, 3)）。
• 导入时不得执行会阻塞的发现操作。

验证

uv run pytest tests/unit/capture -q
prek run --all-files