HEXFELLOW CAMERA DRIVER

📖 Overview

What is hex_driver_camera

hex_driver_camera is a Python library for managing RGB and RGB-D cameras with a unified interface. It supports dummy cameras (for testing), USB cameras, Intel RealSense, and Berxel depth cameras. The library runs each camera in a background thread, buffers frames in a deque, and provides simple get_color_img/get_depth_img APIs. A callback variant is also available for each camera type.

What problem it solves

• Unified camera interface: Use the same API for dummy, USB, RealSense, and Berxel cameras.
• Background acquisition: Each camera runs in its own daemon thread; the main thread only reads the latest frame when needed.
• Two usage patterns: Poll frames via get_color_img/get_depth_img (deque mode), or register callbacks that fire on every new frame (callback mode).
• Optional‑dependency handling: RealSense and Berxel support are extra dependencies; the core works without them.

Target users

• Developers who need a simple, consistent way to capture from multiple camera types.
• Robotics researchers prototyping vision pipelines with real or simulated cameras.
• Anyone who wants to switch between a dummy camera (for testing) and a real camera without changing client code.

📦 Installation

Requirements

• Python ≥ 3.10
• OS: Linux (macOS/Windows may work for USB cameras but are less tested)
• Core dependencies:
  • hex_util_runtime ≥ 0.0.0, < 0.1.0
  • opencv-python ≥ 4.10.0

Optional device support (install via extras):

Install from PyPI

For those who don't need examples, you can install the package from PyPI.

• Full install: includes all optional cameras (Berxel, RealSense)

  pip install hex_driver_camera[all]
  

• Core install: only the core package (dummy + USB cameras)

  pip install hex_driver_camera
  

• Install with a specific extra (e.g., only RealSense):

  pip install hex_driver_camera[realsense]
  

Install from Source

For those who need examples, you can install the package from source code with examples.

Note: We use uv to manage the Python environment. Please install it first.

1. Clone and install in editable mode. The venv.sh script expects uv.

   git clone https://github.com/hexfellow/hex_driver_camera.git
   cd hex_driver_camera
   ./venv.sh
   

   • ./venv.sh — creates .venv, installs hex_driver_camera with [all] and example dependencies.
   • ./venv.sh --min — installs the core package only (no optional camera extras). Some examples will not run.
   • ./venv.sh --pkg-only — installs the package only, skips example-related dependencies.

2. Activate before running examples:

   source .venv/bin/activate
   

📑 API

See API for details of all camera classes and parameters.

💡 Example

See Example for usage examples of each camera type.

📚 Citation

If you want to cite this project in your work, you can use the following BibTeX entry:

@software{hex_driver_camera,
  author    = {Dong, Zhaorui and Chen, Zejun},
  title     = {Hex Driver Camera: A Unified Python Camera Driver Library},
  year      = {2025},
  publisher = {Zenodo},
  version   = {v0.1.0},
  doi       = {10.5281/zenodo.18309954},
  url       = {https://doi.org/10.5281/zenodo.18309954}
}

📄 License

Apache License 2.0. See LICENSE.

🌟 Star History

👥 Contributors