fluxeem-driver 1.0.2

Fluxeem Event Camera Python SDK

Fluxeem Python SDK

面向 Fluxeem 事件相机的 Python SDK，提供设备连接、事件流采集、RAW 文件读取回放、工具参数控制与跨版本 wheel 打包能力。

在线文档 · 官网

主要功能

• 事件相机发现、打开、关闭与生命周期管理。
• 实时事件流读取、回调注册、录制与配置导入导出。
• RAW 文件读取、时间/事件数定位、区间抽取。
• 基于 NumPy 的事件可视化与统计工具函数。
• CMake + pybind11 构建体系，支持 Python 3.8 至 3.13。
• 支持 cibuildwheel 批量构建 Windows wheel。

使用简介

1. 安装并使用 SDK

如果你只需要在 Python 中快速接入 Fluxeem 事件相机，请优先使用现成 wheel 或直接安装源码包。

本仓库当前发布名与导入包名均为 fluxeem_driver。

安装示例：

python -m pip install .\wheelhouse\fluxeem_driver-1.0.0-cp310-cp310-win_amd64.whl

导入示例：

import fluxeem_driver

2. 安装 USB 驱动（首次使用时执行一次）

pip 安装完成后，需要以特权身份运行以下命令，将设备访问权限写入系统。

Windows（以 管理员身份 运行 PowerShell / 命令提示符）：

fluxeem-install-drivers

Linux（Ubuntu / Debian 等）（使用 sudo）：

sudo fluxeem-install-drivers

注意： 该步骤需要管理员 / root 权限，若权限不足会立即提示并退出，不会静默失败。
此步骤仅需执行一次，重新安装 Python 包时无需重复操作。

3. 从源码构建使用

如果你需要修改 Python 包装层、调试 pybind11 绑定、维护跨版本 wheel 或参与发布流程，请继续阅读下面的构建说明。

• 构建要求
• Windows 源码编译
• Linux 源码编译

仓库结构

目录	说明
fluxeem_driver/	Python 包、包装器、类型标注与运行时库
src/	pybind11 绑定源码
examples/	Python 示例程序（实时预览、回放、同步、工具控制）
tests/	单元测试
tools/	构建辅助脚本（如 cibuildwheel bootstrap）
wheelhouse/	本地构建 wheel 产物目录
CMakeLists.txt	C++ 扩展构建配置
setup.py	setuptools 与 CMake 桥接入口
pyproject.toml	项目元数据与构建配置

支持平台与产物

平台	典型产物	说明
Windows x64	.whl	支持 cp38 到 cp313，可通过 cibuildwheel 批量构建
Linux x86_64	源码安装 / wheel	使用 CMake 与系统工具链构建扩展

构建要求

基础要求：

• Python 3.8 或更高版本。
• CMake 3.15 或更高版本。
• 支持 C++20 的编译器。
• 已安装 Fluxeem Driver SDK（fluxeem_driver）。
• pybind11 2.11 或更高版本。

可选依赖：

• OpenCV：运行实时可视化、回放相关示例。
• pytest：运行测试。
• cibuildwheel：批量构建多 Python 版本 wheel。

SDK 路径查找规则：

• 优先使用环境变量 FLUXEEM_DRIVER_DIR。
• Windows 默认回退路径：C:\Program Files\fluxeem_driver、C:\Program Files (x86)\fluxeem_driver。
• Linux 默认回退路径：/usr/local。

构建参数

参数	默认值	说明
FLUXEEM_DRIVER_DIR	自动探测	指向已安装 fluxeem_driver SDK 根目录
FLUXEEM_BUNDLE_DRIVER_RUNTIME	ON	是否把 SDK 运行时库打包到 Python 包旁
CMAKE_GENERATOR	自动探测	Windows 下可指定生成器（如 VS/Ninja）

Windows 源码编译

推荐在 PowerShell 中执行，先激活目标 Python 环境。

1. 安装构建依赖

python -m pip install --upgrade pip setuptools wheel build cmake pybind11 ninja

2. 设置 SDK 路径（非默认安装目录时）

$env:FLUXEEM_DRIVER_DIR = "C:\Program Files\fluxeem_driver"

3. 编译并安装

python setup.py build_ext --inplace
python -m pip install .

4. 开发模式安装（可选）

python setup.py build_ext --inplace
python -m pip install -e ".[dev,viz]"

Linux 源码编译

以下命令以 Ubuntu 为例。

1. 安装系统依赖

sudo apt-get update
sudo apt-get install -y \
  build-essential \
  cmake \
  pkg-config \
  libusb-1.0-0-dev \
  python3-dev

2. 设置 SDK 路径

export FLUXEEM_DRIVER_DIR=/usr/local

3. 编译并安装

python -m pip install --upgrade pip setuptools wheel build cmake pybind11 ninja
python setup.py build_ext --inplace
python -m pip install .

快速开始

1. 实时读取相机事件

import fluxeem_driver

camera_manager = fluxeem_driver.EvCameraService()
camera_descs = camera_manager.list_cameras()

for camera_desc in camera_descs:
    print(camera_desc)

serial = sys.argv[1] if len(sys.argv) > 1 else camera_descs[0].serial
camera = camera_manager.open(serial)

if not devices:
    raise RuntimeError("No camera found")


camera.start(batch_events_num=5000)
events = camera.get_events()
if events is not None:
    print(len(events), events.dtype.names)
camera.stop()

2. 读取 RAW 文件

import fluxeem_driver

with fluxeem_driver.FileReader("recording.raw") as reader:
    if not reader.is_loaded():
        raise RuntimeError("Failed to load raw file")

    while not reader.reached_end():
        events = reader.get_events(10000)
        if events is not None and len(events):
            print(events[0])

3. 事件可视化与统计

from fluxeem_driver import utils

frame = utils.events_to_frame(events, width=1280, height=720)
rgb = utils.events_to_rgb_frame(events, width=1280, height=720)
stats = utils.get_event_statistics(events)
print(stats["count"], stats["polarity_ratio"])

示例程序

运行示例：

python examples/live_viewer.py
python examples/tool_control.py
python examples/hardware_sync.py
python examples/file_playback.py recording.raw
python examples/slow_motion.py recording.raw

OpenCV 依赖安装：

python -m pip install opencv-python

测试

运行内置单元测试：

python -m unittest discover -s tests -v

或使用 pytest：

python -m pytest

常见问题

导入报错：No module named fluxeem_driver.fluxeem_core

通常是 C++ 扩展未正确编译或未安装，请重新执行：

python setup.py build_ext --inplace
python -m pip install .

构建报错：fluxeem_driver SDK was not found

请确认：

• 已安装 Fluxeem Driver SDK。
• FLUXEEM_DRIVER_DIR 指向 SDK 安装根目录。
• SDK 目录下存在 share/cmake/fluxeem_driver。

找不到相机设备

请确认设备连接、驱动安装和权限设置；若设备已被其他进程占用，请先关闭占用进程再重试。

OpenCV 导入异常

请确认运行示例的 Python 环境与安装 opencv-python 的环境一致。

许可证

本项目使用 MIT 协议发布。

联系方式

• 项目主页：https://github.com/fluxeem/fluxeem_driver_python
• 问题反馈：https://github.com/fluxeem/fluxeem_driver_python/issues
• 联系邮箱：[e-mail]