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. 参考にするバックエンドを選ぶ：新しいハードウェアに最も近いものを選びます（USB ビデオなら UVC、RGB-D なら RealSense、GenICam 産業用なら Basler）。
   • 完了条件：参考にするモジュール（_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）でラップします。共有モードについて記載するのは、transport 追加依存関係がインストールされている場合に限ります。

必須のチェック

• ユーザー向けの場合、CameraType またはファクトリー文字列が docs/reference/camera-api.md に記載されていること。
• フレームの形状と dtype が README の例（RGB (H, W, 3)）と一致していること。
• インポート時にブロッキングを伴う検出処理が行われないこと。

検証

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