Metadata-Version: 2.4
Name: fluxeem_driver
Version: 1.0.0
Summary: Fluxeem Event Camera Python SDK
Home-page: https://github.com/fluxeem/fluxeem_driver_python
Author: Fluxeem
Author-email: Fluxeem <info@fluxeem.com>
Maintainer-email: Fluxeem <info@fluxeem.com>
License: MIT
Project-URL: Homepage, https://github.com/fluxeem/fluxeem_driver_python
Project-URL: Documentation, https://github.com/fluxeem/fluxeem_driver_python/docs
Project-URL: Repository, https://github.com/fluxeem/fluxeem_driver_python
Project-URL: Issues, https://github.com/fluxeem/fluxeem_driver_python/issues
Keywords: event camera,camera,event,vision,sensor,fluxeem,neuromorphic
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.20.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0; extra == "dev"
Requires-Dist: black>=22.0; extra == "dev"
Requires-Dist: flake8>=4.0; extra == "dev"
Requires-Dist: mypy>=0.950; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=4.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=1.12; extra == "docs"
Provides-Extra: viz
Requires-Dist: opencv-python>=4.5; extra == "viz"
Requires-Dist: matplotlib>=3.4; extra == "viz"
Dynamic: author
Dynamic: home-page
Dynamic: requires-python

<div align="center">
  <img src="docs/img/html_title.png" alt="Fluxeem Logo" width="260" />
</div>

<h1 align="center">Fluxeem Python SDK</h1>

<p align="center">
  面向 Fluxeem 事件相机的 Python SDK，提供设备连接、事件流采集、RAW 文件读取回放、工具参数控制与跨版本 wheel 打包能力。
</p>
<p align="center">
  <a href="https://fluxeem.github.io/fluxeem_driver/tutorial_python_index.html">在线文档</a> ·
  <a href="https://www.fluxeem.com">官网</a>
</p>
<p align="center">
  <a href="https://github.com/fluxeem/fluxeem_driver_python/releases"><img src="https://img.shields.io/github/v/release/fluxeem/fluxeem_driver_python" alt="Release"></a>
  <a href="https://github.com/fluxeem/fluxeem_driver_python/blob/main/pyproject.toml"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License"></a>
  <a href="https://img.shields.io/badge/python-3.8%20to%203.13-brightgreen"><img src="https://img.shields.io/badge/python-3.8%20to%203.13-brightgreen" alt="Python"></a>
</p>

## 主要功能

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

## 使用简介

### 1. 安装并使用 SDK

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

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

安装示例：

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

导入示例：

```python
import fluxeem_driver
```

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

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

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

```powershell
fluxeem-install-drivers
```

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

```bash
sudo fluxeem-install-drivers
```

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


### 3. 从源码构建使用

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

- [构建要求](#构建要求)
- [Windows 源码编译](#windows-源码编译)
- [Linux 源码编译](#linux-源码编译)

## 仓库结构

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

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

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

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

### 3. 编译并安装

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

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

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

## Linux 源码编译

以下命令以 Ubuntu 为例。

### 1. 安装系统依赖

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

### 2. 设置 SDK 路径

```bash
export FLUXEEM_DRIVER_DIR=/usr/local
```

### 3. 编译并安装

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

## 快速开始

### 1. 实时读取相机事件

```python
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 文件

```python
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. 事件可视化与统计

```python
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"])
```

## 示例程序

运行示例：

```bash
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 依赖安装：

```bash
python -m pip install opencv-python
```

## 测试

运行内置单元测试：

```bash
python -m unittest discover -s tests -v
```

或使用 pytest：

```bash
python -m pytest
```

## 常见问题

### 导入报错：`No module named fluxeem_driver.fluxeem_core`

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

```bash
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
- 联系邮箱：info@fluxeem.com
