camera-stream-orbbec

Standalone Orbbec DCW2 ingest extension. It isolates the legacy Orbbec SDK and its NumPy ABI from the main camera-stream server:

⚡ Run with uvx

The PyPI wheel bundles the matching Linux Orbbec v1 native runtime. No compiler, SDK installation, or persistent virtual environment is required:

uvx camera-stream server --config /absolute/path/to/server.yaml

uvx --python 3.11 camera-stream-orbbec --download-template
# Edit ./config.yaml: server address, serial, profiles, and alignment.
uvx --python 3.11 camera-stream-orbbec --config ./config.yaml

Supported release wheels are Linux x86_64 with glibc 2.28 or newer and CPython 3.10/3.11. Passing --python 3.11 keeps the legacy SDK ABI explicit even when the host's default Python is newer. Verify the bundled SDK without opening a camera:

uvx --python 3.11 camera-stream-orbbec --doctor

The plugin publishes <camera>/color and, when enabled, <camera>/depth. Both frames from one SDK frameset carry the same frameset_sequence, captured_monotonic_ns, and captured_utc_ns. Set camera.enabled: false to retain the configuration while exiting without opening the device or connecting to the server.

Configuration

server:
  ingest_endpoint: "tcp://192.168.5.24:5557"
  token: null
camera:
  name: dcw2
  enabled: true
  serial: "REPLACE_WITH_DCW2_SERIAL"
streams:
  color:
    profile: {width: 640, height: 480, fps: 15}
    codec: jpeg
    jpeg_quality: 85
  depth:
    enabled: true
    profile: {width: 640, height: 400, fps: 15}
    alignment: color       # native | color
    # scale_m: 0.001       # Optional override if the SDK cannot report it.

alignment: color requests SDK software alignment and emits depth at the color profile resolution. The DCW2 native depth profile is commonly 640x400 at 15 FPS, while aligned output follows the 640x480 color geometry. Use native to avoid resampling; the depth and color coordinates then have different geometries. Depth payloads are unsigned 16-bit little-endian values. Multiply a value by the header's depth_scale_m to obtain metres. The extension converts the SDK's millimetres-per-unit scale to metres per unit. Set scale_m only when a vendor SDK build cannot report the value or reports an incorrect one.

Behavior

• One latest-frame slot is kept per topic; a slow network never builds a queue.
• The server claims <camera>/color and <camera>/depth independently. A local topic always wins a collision.
• The optional server ingest token is sent with every claim.
• A duplicate local or remote topic is rejected and the plugin exits with a non-zero status instead of silently publishing under another name.
• The plugin reconnects after a server restart and the server releases idle remote topics according to ingest_policy.topic_lease_s.
• The server does not decode, transform, or re-encode plugin payloads.

The plugin intentionally does not import the main camera_stream package. If the SDK reports No device connected for an attached camera, install the Orbbec v1 udev rules and verify that the configured serial matches the device.

🛠️ Source development and release

The upstream pyorbbecsdk==1.3.2 Linux wheel is mislabeled and contains macOS ARM binaries. A source checkout can instead build the checksummed official SDK source into its isolated environment:

cd extensions/orbbec-dcw2
uv sync --extra build --extra dev
uv run camera-stream-orbbec --install-sdk
uv run pytest
uv run camera-stream-orbbec --config ./config.yaml

Do not use uv run --active; the SDK must remain isolated from the main server. The release build uses the manylinux_2_28 baseline required by the vendor's prebuilt native library and bundles the runtime plus its Apache 2.0 license:

bash scripts/build_wheels.sh  # Docker is required

Pushing a tag such as camera-stream-orbbec-v0.1.2 runs the two-wheel build in GitHub Actions. Before creating the tag, configure a PyPI Trusted Publisher for workflow orbbec-dcw2-pypi.yml and environment pypi.