physicalai-runtime-adding-a-camera-backend

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Adding a Camera Backend

添加相机后端

Cameras implement the

Camera

interface in

src/physicalai/capture/camera.py

. Factory entry:

create_camera()

src/physicalai/capture/factory.py

maps lowercase type names (

uvc

realsense

basler

, …) to implementations. Reference layouts:

src/physicalai/capture/cameras/uvc/

src/physicalai/capture/cameras/realsense/

src/physicalai/capture/cameras/basler/

相机需实现

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/

。

Workflow

工作流程

Pick a reference backend closest to the new hardware (UVC for USB video, RealSense for RGB-D, Basler for GenICam industrial).
- Done when: you can list which modules to mirror (
```
_camera.py
```
  ,
```
_discover.py
```
  ,
```
__init__.py
```
  exports).
Implement
Camera
:
```
connect()
```
,
```
disconnect()
```
,
```
read()
```
/
```
read_latest()
```
, context manager support, monotonic timestamps on
```
Frame
```
(
```
src/physicalai/capture/frame.py
```
).
- Done when: fake or mocked device tests can exercise connect/read without hardware.
Wire discovery if the device is enumerable — add helpers under
```
src/physicalai/capture/discovery.py
```
or backend-specific
```
_discover.py
```
.

Register the type in

src/physicalai/capture/factory.py

and export public class from

src/physicalai/capture/__init__.py

when user-facing.

Optional extra in
```
pyproject.toml
```
for vendor SDKs; lazy-import inside the camera module so
```
pip install physicalai
```
stays light.
- Done when:
```
import physicalai.capture
```
  works without the extra; importing the camera class fails with a clear message if the extra is missing.

Tests in

tests/unit/capture/

using existing fakes (

tests/unit/capture/fake.py

conftest.py

patterns).

Done when:

uv run pytest tests/unit/capture -k <backend>

passes.

选择最贴近新硬件的参考后端（UVC适用于USB视频设备，RealSense适用于RGB-D设备，Basler适用于GenICam工业相机）。
- 完成标志：可列出需要镜像的模块（
```
_camera.py
```
  、
```
_discover.py
```
  、
```
__init__.py
```
  导出内容）。
实现
Camera
接口：
```
connect()
```
、
```
disconnect()
```
、
```
read()
```
/
```
read_latest()
```
、上下文管理器支持，以及为
```
Frame
```
（
```
src/physicalai/capture/frame.py
```
）添加单调时间戳。
- 完成标志：无需硬件即可通过虚拟或模拟设备测试执行连接/读取操作。
配置设备发现功能（如果设备可枚举）——在
```
src/physicalai/capture/discovery.py
```
或后端专属的
```
_discover.py
```
中添加辅助工具。

在
src/physicalai/capture/factory.py
中注册类型，若面向用户，则从

src/physicalai/capture/__init__.py

导出公共类。

为厂商SDK配置可选额外依赖（在
```
pyproject.toml
```
中）；在相机模块内使用延迟导入，确保
```
pip install physicalai
```
保持轻量。
- 完成标志：无需安装额外依赖即可正常
```
import physicalai.capture
```
  ；若缺少额外依赖，导入相机类时会显示清晰的错误提示。
在
tests/unit/capture/
中编写测试，使用现有虚拟设备（
```
tests/unit/capture/fake.py
```
、
```
conftest.py
```
中的模式）。
- 完成标志：执行
```
uv run pytest tests/unit/capture -k <backend>
```
  测试通过。

Shared transport

共享传输

For multi-process access,

create_camera(..., shared=True)

wraps with

SharedCamera

(

physicalai[capture]

transport

extra, iceoryx2). Only document shared mode when the transport extra is installed.

对于多进程访问场景，

create_camera(..., shared=True)

会通过

SharedCamera

（需安装

physicalai[capture]

transport

额外依赖，基于iceoryx2）进行包装。仅当安装了传输额外依赖时，才需文档化共享模式。

Required checks

必要检查

```
CameraType
```
or factory string is documented in
```
docs/reference/camera-api.md
```
when user-visible.
Frame shapes and dtypes match README examples (RGB
```
(H, W, 3)
```
).
No blocking discovery at import time.

若面向用户，需在
```
docs/reference/camera-api.md
```
中记录
```
CameraType
```
或工厂字符串。
帧的形状和数据类型需与README示例一致（RGB格式为
```
(H, W, 3)
```
）。
导入时不得执行阻塞式设备发现操作。

Verify

验证

bash

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

bash

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