imprintsdk 使用说明（macOS / Ubuntu Linux）

imprintsdk 0.2.6 是适用于 macOS 和 Linux 的 EVT20 事件相机 Python SDK，公开接口为 gui()。imprintx 默认打开原始事件窗口；imprintx --tracking 打开一个更大的窗口，左侧显示原始信号，右侧显示 PCNF tracking 图像。

0.2.6 更新说明

• 增加 Ubuntu Linux x86_64 编译、原生动态库加载和 USB 串口自动检测支持。
• Linux 发布包经 auditwheel 检查并转换为 manylinux_2_27_x86_64，保持 py3-none 的 Python ABI 无关接口。
• 发布脚本支持 Linux 包选择、预检及读取已有 .pypirc 凭据。
• 0.2.6 首先提供 Linux wheel；macOS 现有 PyPI 安装包为 0.2.5，macOS 用户仍可从源码构建当前版本。

0.2.5 更新说明（源码及本地 wheel）

• 增加 imprintx 命令，保留 imprintsdk 和 python -m imprintsdk 入口；三个入口使用同一套参数。
• 增加 --tracking，集成 tracking_2413 的 11×11 PCNF 算法及 2413 初始中心、坏点文件，直接使用 SDK 采集的事件流。
• 默认原始信号模式保持单窗口显示；tracking 模式在同一个窗口并排显示原始信号和跟踪结果，重连时重置跟踪状态。
• 无需 Linux daemon、共享内存读取器或原始 tracking_2413 文件夹，仍只依赖 NumPy 和 OpenCV。
• 修复自动归零：积压丢帧保留已观测的按压历史，缺失区间不参与安静确认；确认全局释放后，跟踪状态立即重锚，显示在 4 帧内回到零，新按压会中止正在进行的回零显示。

本页描述 0.2.6 的源码和 wheel 用法。PyPI 各平台的可用文件以项目下载列表为准；新功能的设备效果需要在实际传感器及标定条件下验证。

0.2.4 更新说明

• 事件画面改为灰色背景（灰度 128）、正极性白色、负极性黑色；重连状态背景同步为灰色。
• Events/s 的统计和刷新间隔由约 1 秒缩短为约 100 ms，按实际统计时长换算为每秒事件数，使数值更及时地响应输入变化。
• 公开 gui() 接口、采集逻辑和图像刷新参数不变。

0.2.3 更新说明

• 修复启动应答与大批事件同时到达时，应答被丢弃并误报启动超时的问题。
• 修复合法 TIME_HIGH=0 被视为未同步，导致事件丢失和错误时间戳的问题。
• 增加 Connected - no events yet 提示，区分串口已连接与已收到事件。
• 开发仓库增加真实设备稳定性检查脚本和相应回归测试；公开 gui() 接口不变。

1. 安装

需要 macOS Apple Silicon（M 系列芯片）或 Ubuntu Linux x86_64，以及 Python 3.8+，并需要可用的桌面显示环境，以及通过 USB 串口连接的 EVT20 事件相机。Ubuntu 本地构建方式见第 6 节。

从 PyPI 安装 Linux 当前版本：

python -m pip install --upgrade "imprintsdk==0.2.6"

macOS Apple Silicon 现有 PyPI 版本为 0.2.5：

python -m pip install --upgrade "imprintsdk==0.2.5"

pip 会自动下载并安装以下依赖，无需单独安装 OpenCV：

• opencv-python：图像处理和窗口显示。
• numpy：事件数组处理。

本包支持 macOS 和 Linux，不支持 Windows。macOS 安装包适配 Apple Silicon（arm64）；Linux x86_64 发布包标记为 manylinux_2_27_x86_64，SDK 原生库要求 glibc 2.27+，NumPy 和 OpenCV 还需各自兼容当前系统和 Python 版本。Ubuntu 原始本地构建包标记为 linux_x86_64，发布前需使用 auditwheel 检查和转换。同一平台的 wheel 支持多个 Python 版本，无需按 Python 小版本选择安装包；macOS 原有验证范围为 Python 3.8–3.14，Ubuntu 的实际验证结果以当前构建环境为准。Intel Mac 暂未提供对应的发布包。

建议使用独立虚拟环境，避免和其他项目安装的 OpenCV 发行包冲突。同一环境应使用带 GUI 功能的 opencv-python；opencv-python-headless 不具备窗口功能。

从本地 wheel 安装

在尚未上传 PyPI 或离线分发 SDK wheel 时，进入 wheel 所在目录：

python -m pip install --find-links . "imprintsdk==0.2.6"

本地 wheel 安装也会自动下载依赖；完全离线安装需要提前准备 OpenCV 和 NumPy 的匹配 wheel。SDK 的 C++ 核心以普通动态库（macOS 为 .dylib，Linux 为 .so）包含在 wheel 中，由 Python 标准库 ctypes 调用，不依赖某个 Python 小版本的扩展 ABI，不需要额外复制 libevtcap，也不依赖开发仓库的 build/ 目录。

2. 命令行启动

自动选择端口

系统只检测到一个 USB 串口设备时，直接运行：

imprintx

需要 tracking 时运行：

imprintx --tracking

默认中心标定为包内的 xypt_frequency_center_candidates.csv，支持 320×320 传感器、11×11 网格。文件来自 tracking_2413/data/11_11/initial_center/2413/，加载其中 121 个中心的传感器坐标及 circle_radius，半径为空时使用默认值 5 px。其他设备需要对应标定，不能仅凭串口成功连接就认为 tracking 适配。

macOS 自动检测范围为 /dev/cu.usbmodem* 和 /dev/cu.usbserial*；Linux 为 /dev/ttyACM* 和 /dev/ttyUSB*。这只是串口枚举，不会验证设备型号；如果还连接了其他串口设备，请明确指定相机端口。

也可以使用保留的命令或模块入口：

imprintsdk --tracking
python -m imprintsdk
python -m imprintsdk --tracking

明确指定端口

下面的端口名称是示例，请替换成实际设备端口。

ls /dev/cu.usbmodem* /dev/cu.usbserial* 2>/dev/null
python -m imprintsdk --device /dev/cu.usbmodemYOUR_DEVICE

macOS 优先使用 /dev/cu.*。传入 /dev/tty.* 时，SDK 会在对应 /dev/cu.* 存在的情况下自动切换。

查看参数

python -m imprintsdk --help

命令行参数	默认值	含义
--device	自动选择	相机串口；多个设备时必须指定
--baudrate	115200	串口配置波特率，按设备要求设置
--width	320	传感器宽度，范围 1–2048
--height	320	传感器高度，范围 1–2048
--display-fps	60	界面刷新上限；必须大于 0，不改变相机采集速率
--tracking	关闭	启用左侧原始信号、右侧 PCNF tracking 的单窗口显示；要求 320×320
--centers-csv	包内 xypt_frequency_center_candidates.csv	自定义 11×11 中心标定 CSV；只能与 --tracking 一起使用
--hot-pixels-csv	包内 2413 坏点	自定义坏点 CSV；只能与 --tracking 一起使用

例如：

python -m imprintsdk --device /dev/cu.usbmodemYOUR_DEVICE --width 320 --height 320 --display-fps 60
imprintx --tracking --device /dev/cu.usbmodemYOUR_DEVICE

为同一 320×320、11×11 配置使用其他标定时：

imprintx --tracking --centers-csv /path/to/centers.csv --hot-pixels-csv /path/to/hot_pixels.csv

中心 CSV 必须包含 121 个点，坐标列可以是 center_x_sensor,center_y_sensor、raw_x,raw_y 或 center_x,center_y。坏点 CSV 使用 x,y 传感器原始坐标列。两项独立使用包内默认值；切换设备时应同时提供该设备的中心和坏点文件。替换 CSV 不会自动适配其他分辨率、网格或镜头模型。

3. 在 Python 中调用

创建 view_camera.py：

from imprintsdk import gui

if __name__ == "__main__":
    gui(device="/dev/cu.usbmodemYOUR_DEVICE")

运行：

python view_camera.py

系统只有一个相机串口时，也可以省略端口：

from imprintsdk import gui

gui()

开启 tracking：

from imprintsdk import gui

gui(tracking=True)

唯一公开函数的完整签名：

gui(device=None, *, baudrate=115200, width=320, height=320, display_fps=60,
    tracking=False, centers_csv=None, hot_pixels_csv=None)

gui() 会阻塞到窗口退出，必须在 Python 主线程调用。正常关闭后返回 None；参数错误会抛出 ValueError，打开设备、启动采集或资源清理失败会抛出 RuntimeError。命令行入口会打印错误并以非零状态退出。

采集期间如果设备固件复位或 USB 重新枚举，窗口会显示 Connection lost - reconnecting...，SDK 会释放失效的旧串口句柄，并每 0.5 秒尝试使用同一路径重新打开、开灯和恢复采集。tracking 状态会重置，避免旧轨迹延续到新的采集会话。重连期间仍可按 q、Esc 或关闭窗口退出。

4. 窗口显示与退出

启动后自动开启补光灯并开始采集。默认模式只显示一个名为 Imprint SDK - Events 的 OpenCV 窗口；加 --tracking 后显示一个横向大窗口，左边为原始事件，右边为 PCNF 跟踪图像。

原始事件显示沿用 0.2.4 的配色与速率统计：

• 灰色背景： 无事件像素，灰度值为 128。
• 白色像素： 正极性事件。
• 黑色像素： 负极性事件。
• Events: 12,000/s： 事件速率，单位为每秒事件数；一个事件是一个像素的一次变化记录。该数值不代表整帧图像数量。约每 100 ms 统计并刷新一次，以该窗口的事件数除以实际经过秒数，换算为 /s；例如 100 ms 收到 1,200 个事件，显示约 12,000/s。短窗口比 1 秒平均值响应更快，数值也会更容易波动。

显示窗口会把一批事件合并绘制。C++ 后台线程独立采集，界面刷新上限和事件速率互相独立；窗口只展示最新可用数据，不执行数据录制或完整历史回放。

tracking 保留原算法的 1 ms 时间窗、每窗 512 个事件预算、按标记点和极性平衡的事件选择，以及因果显示和 responsive 释放归零策略。右侧使用完成时间窗内经过坏点过滤、去畸变的事件，保证事件与标记坐标一致；左侧仍显示原始事件。程序限制过大积压时的追赶工作量，以保持窗口可响应；发生缓冲覆盖或算法跳过积压事件时，右下角显示 Input dropped 累计数。缺失区间会打断连续安静确认，但保留已观测的按压历史，不会把少收的事件当作释放证据。过载时不能保证与原 Linux 程序逐点、逐时刻轨迹一致。此模式只显示实时结果，不保存视频、事件流或轨迹 CSV。

自动归零仍需满足原有按压历史、位移和释放条件，并确认连续 2 个完整安静显示帧。通过确认后，符合重锚条件的跟踪点立即回到初始中心，画面单独用 4 个显示帧平滑回零，即使此后没有新事件也能完成。新的测量位移会中止该点的回零显示；同一次释放确认不会反复重置下一次按压。

以下任一操作都可以退出：

1. 点击图像窗口的关闭按钮。
2. 图像窗口获得焦点后按 q 或 Esc。
3. 在启动程序的终端按 Ctrl+C。

退出时会依次尝试关灯、停止采集、关闭串口和销毁窗口。即使前一步出现异常，也会继续尝试后续清理。

5. 常见问题

Specify device explicitly

未检测到串口，或同时检测到多个串口。检查 USB 连接，并使用 --device 指定相机的实际端口。重新插拔或更换相机后，端口名可能变化。

Cannot open ...

检查端口是否存在、是否被其他采集程序占用，以及当前用户是否有串口访问权限。macOS 优先使用 /dev/cu.*；Ubuntu 通常使用 /dev/ttyACM0 或 /dev/ttyUSB0，并需要当前用户拥有设备的读写权限（通常由 dialout 组控制）。

无法创建 OpenCV 窗口 / The function is not implemented

确认在有桌面的会话中运行，并且当前虚拟环境安装的是 opencv-python。无桌面的 SSH 会话或 headless OpenCV 不满足这个 GUI 的运行条件。

No matching distribution found

确认 wheel 的系统和 CPU 架构与当前 Python 匹配，并升级 pip。macOS 使用 Apple Silicon 上的原生 Python，而不是 Rosetta 下的 x86_64 Python；Ubuntu x86_64 使用 PyPI 的 manylinux_2_27_x86_64 wheel 或本地构建的 linux_x86_64 wheel。同一平台安装包适用于 Python 3.8+。当前没有 Windows 或 Intel Mac 发布包。

窗口黑屏或事件数很低

事件相机输出的是亮度变化。先让相机观察有运动或亮度变化的场景，再查看事件数；同时确认终端没有开灯或启动采集失败的提示。

如果串口连接和启动命令均成功，但 3 秒后仍未解码到任何事件，窗口会显示 Connected - no events yet，终端会提示一次。收到命令应答不等于已收到事件流；此状态不会触发反复重连。若施加正常输入变化仍始终为零，可退出程序，拔下设备 USB，等待 5 秒再连接后重试。冷启动恢复只能说明设备状态影响了输出，不能单凭此现象确定固件复位或供电故障。

运行一段时间后显示正在重连

这表示原串口会话已经失效，常见原因是设备固件复位、USB 供电或线材不稳定。SDK 会自动恢复同名端口，并在终端打印具体系统错误，例如 Input/output error。如果频繁重复出现，应继续检查固件 watchdog、USB CDC 发送队列、供电、线材和 Hub；自动重连避免 GUI 卡死，但不能消除设备自身的复位原因。

原始信号正常，但 tracking 点位不匹配

确认使用 320×320、11×11 配置及当前设备对应的初始中心和坏点 CSV。默认文件来自 2413，不能作为其他传感器的通用标定；当前镜头去畸变参数也沿用 2413 原算法。先检查静止时初始点位与实际标记是否重合，再验证按压、释放和重连后的跟踪。

6. 从源码构建与开发

源码构建支持 macOS 和 Linux。在项目根目录使用 Python 3.8+；macOS 需安装 Xcode Command Line Tools，Ubuntu 需安装 C++17 编译器和 CMake。构建不需要 Python 开发头文件或 pybind11：

uv build --wheel

在项目根目录直接试用源码入口：

uv run imprintx
uv run imprintx --tracking

Ubuntu 本地构建与安装（示例使用系统 Python 3.10，避免复用从 macOS 复制的 .venv）：

sudo apt-get install build-essential cmake python3-venv libgl1 libglib2.0-0
uv build --wheel --python /usr/bin/python3 --out-dir dist/ubuntu
uv venv --python /usr/bin/python3 /tmp/imprintsdk-ubuntu
uv pip install --python /tmp/imprintsdk-ubuntu/bin/python dist/ubuntu/imprintsdk-0.2.6-py3-none-linux_x86_64.whl
/tmp/imprintsdk-ubuntu/bin/imprintx --device /dev/ttyACM0
/tmp/imprintsdk-ubuntu/bin/imprintx --tracking --device /dev/ttyACM0

Ubuntu 的 wheel 包含 libimprintsdk.so，无需 macOS AppKit 或 Objective-C++。linux_x86_64 表示本机构建包，未经过 manylinux 兼容性修复；跨发行版或旧版本系统分发前需另行验证 glibc / libstdc++ 兼容性。GUI 需在有显示服务的桌面会话中运行；无设备时可以运行 imprintx --help 检查入口，但不能据此确认真实采集及显示效果。Linux OpenCV 窗口使用自身的关闭按钮；macOS 保留 Cocoa 关闭按钮修正。

macOS Apple Silicon 发布构建只需执行一次：

python tools/build_macos_wheels.py

安装生成的 wheel：

python -m pip install --find-links dist/release "imprintsdk==0.2.6"

开发目录中仍可使用原来的脚本入口，它会调用同一个 GUI，支持 --tracking：

uv run tools/consumer/visualize_events.py --device /dev/cu.usbmodemYOUR_DEVICE

安装 wheel 后运行 GUI 生命周期回归检查：

python -m unittest discover -s test -p test_gui.py -v

开发目录中可执行有时限的真实设备稳定性检查（运行时不要同时打开 GUI）：

uv run tools/consumer/check_stability.py --duration 600
uv run tools/consumer/check_stability.py --duration 20 --cycles 3

工具逐秒报告事件数、事件速率并检查部分事件的坐标、极性和结构标记；每轮均关闭串口、关灯并停止采集。断线、整个测试没有事件或清理失败会以非零状态退出，不会将“串口保持连接但没有数据”判定为通过。可加 --no-light 做关灯对照。通过结果只覆盖实际测试时长和输入条件，不证明长期运行或完整数据无丢失。

项目原有的 C++ API 与底层构建说明保留在 README.md 中。本文件描述的是 imprintsdk 0.2.6 的 Python 使用接口；内部原生模块和跟踪实现不属于稳定公开 API。

维护者发布前，生成单个 py3-none-macosx_*_arm64.whl，并检查包说明。py3-none 表示不绑定 CPython 小版本，macOS 和 CPU 架构仍有平台要求：

python tools/build_macos_wheels.py
uvx twine check dist/release/imprintsdk-0.2.6-*.whl
python tools/publish_pypi.py

发布脚本默认只选择当前版本的 macOS wheel。Linux x86_64 发布流程为：

uv build --wheel --python /usr/bin/python3 --out-dir dist/ubuntu
uvx --with patchelf auditwheel show dist/ubuntu/imprintsdk-0.2.6-py3-none-linux_x86_64.whl
uvx --with patchelf auditwheel repair --plat manylinux_2_27_x86_64 --wheel-dir dist/release dist/ubuntu/imprintsdk-0.2.6-py3-none-linux_x86_64.whl
uvx twine check dist/release/imprintsdk-0.2.6-py3-none-manylinux_2_27_x86_64.whl
python tools/publish_pypi.py --platform linux --dry-run
python tools/publish_pypi.py --platform linux

manylinux_2_27_x86_64 为本次 Ubuntu 构建经 auditwheel 检测支持的标签；其他编译环境必须按 auditwheel show 的实际结果选择标签，不能直接降低 glibc 要求。Linux 发布仅选择 dist/release 内当前版本的 manylinux_* wheel，跳过原始 linux_* wheel、macOS wheel 和源码包。--dry-run 仅检查，不上传。

上传需要有 imprintsdk 发布权限的 PyPI API Token。脚本优先使用 UV_PUBLISH_TOKEN，其次读取已有 ~/.pypirc 的 [pypi] password，否则在本机终端隐藏输入 Token。凭据仅传给上传进程，不写入源码或新配置文件。请勿把 Token 填进 README 或提交到 Git。