Adding a Camera Backend

Camera

src/physicalai/capture/camera.py

create_camera()

src/physicalai/capture/factory.py

uvc

realsense

basler

src/physicalai/capture/cameras/uvc/

src/physicalai/capture/cameras/realsense/

src/physicalai/capture/cameras/basler/

Workflow

1. 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).
2. 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.
3. Wire discovery if the device is enumerable — add helpers under

   src/physicalai/capture/discovery.py

   or backend-specific

   _discover.py

   .
4. Register the type in

   src/physicalai/capture/factory.py

   and export public class from

   src/physicalai/capture/__init__.py

   when user-facing.
5. 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.
6. 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.

Shared transport

create_camera(..., shared=True)

SharedCamera

physicalai[capture]

transport

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.

Verify

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