04 示例程序总览

所有示例程序基于 v2.0 Hybrid Vision Toolkit（采集）与 Hybrid Vision Algo（算法）SDK。Toolkit 示例统一在 samples/cpp/ 下，三后端（USB / MIPI / Ethernet）共用同一套 API。

第一次开发事件相机？

从第一个 C++ 程序起步跑通最小闭环，再按编程指引（打开相机 → 读事件 → 录制 → 去噪 → 显示 → 调参）逐项深入。

Toolkit 示例（C++）

示例	用途	涉及 API	需硬件	构建路径
`get_started`	最小 Camera 流程（Init→StartStream→GetFrame→StopStream→Destroy）	`Camera` / `DeviceConfig`	是	`samples/cpp/get_started`
`callback`	双回调演示（事件 + APS）	`SetEventCallback` / `SetImageCallback`	是	`samples/cpp/callback`
`record`	事件录制为 RAW 文件	`EventWriter` / `HybridWriter`	是	`samples/cpp/record`
`viewer`	实时采集、解码并统计事件数	`Camera` / `Evt2Decoder`	是	`samples/cpp/viewer`
`bench_hw`	实机 USB 计时基准	`Camera` (USB)	是	`samples/cpp/bench_hw`
`live_record_display`	MIPI-HVS 实时预览 + 按键录制	`Camera` (MipiHvs) / `HybridWriter`	是（MIPI）	`samples/cpp/live_record_display`
`player`	离线回放录制文件（EVS .raw + APS .avi）	`HybridReader` / `MipiRaw8Decoder`	否（离线）	`samples/cpp/player`

先在 Toolkit 仓库根目录执行 ./run.sh build、./run.sh build s100 或 ./run.sh build x5。S100/X5 将对应的 out/<arch>/build 整体部署到板卡 /app/build 后，再执行以下命令。

get_started

# x86_64（USB）
./out/x86_64/build/samples/cpp/get_started/hv_sample_get_started

# S100（MIPI）
/app/build/samples/cpp/get_started/hv_sample_get_started --mipi

# X5（MIPI）
/app/build/samples/cpp/get_started/hv_sample_get_started --mipi

最小同步采集示例：初始化相机后读取 10 帧并打印事件字节数。x86_64 默认连接 USB 相机；S100/X5 的 --mipi 使用构建时写入的默认传感器索引（S100 为 9，X5 为 49）。

x86_64：

get_started 示例运行输出

callback

# x86_64（USB）
./out/x86_64/build/samples/cpp/callback/hv_sample_callback

# S100（MIPI-HVS 双 VC）
/app/build/samples/cpp/callback/hv_sample_callback --mipi-hvs

# X5（MIPI-HVS 双 VC）
/app/build/samples/cpp/callback/hv_sample_callback --mipi-hvs

注册事件与 APS 图像的异步回调，采集 2 秒后输出两类回调的计数。ARM 板卡使用 --mipi-hvs 同时获取 EVS 与 APS；如只接 EVS 单 VC 相机，可改用 --mipi。

x86_64：

callback 示例运行输出

record

# x86_64（USB）
./out/x86_64/build/samples/cpp/record/hv_sample_record

# S100（MIPI-HVS 双 VC）
/app/build/samples/cpp/record/hv_sample_record --mipi-hvs

# X5（MIPI-HVS 双 VC）
/app/build/samples/cpp/record/hv_sample_record --mipi-hvs

将采集到的 EVS 与 APS 写入 /tmp/hv_record.raw 和 /tmp/hv_record.avi，默认录制 3 秒。可追加 --duration <秒数> 调整录制时长；单 VC 的 ARM 相机使用 --mipi 时只写 EVS 数据。

x86_64：

record 示例运行输出

viewer

# x86_64（USB）
./out/x86_64/build/samples/cpp/viewer/hv_sample_viewer

# S100（MIPI）
/app/build/samples/cpp/viewer/hv_sample_viewer --mipi

# X5（MIPI）
/app/build/samples/cpp/viewer/hv_sample_viewer --mipi

实时读取并解码 10 帧事件数据，最后输出累计事件数。USB 数据按 EVT2 解码；S100/X5 的 MIPI RAW8 数据通过 --mipi 选择对应解码器。

x86_64：

viewer 示例运行输出

bench_hw

# x86_64（USB，默认测试 5 秒）
./out/x86_64/build/samples/cpp/bench_hw/hv_sample_bench_hw

# S100
# 不支持：bench_hw 固定使用 USB 后端。

# X5
# 不支持：bench_hw 固定使用 USB 后端。

USB 实机吞吐基准，统计事件吞吐率与 APS 帧率。可传入 VID PID 时长，例如 hv_sample_bench_hw 0x1d6b 0x0105 10；S100/X5 没有 USB 后端，不能运行此示例。

x86_64：

bench_hw 示例运行输出

live_record_display

# x86_64
# 不支持：live_record_display 固定使用 MIPI-HVS 后端。

# S100（MIPI-HVS 双 VC）
/app/build/samples/cpp/live_record_display/hv_sample_live_record_display

# X5（MIPI-HVS 双 VC）
/app/build/samples/cpp/live_record_display/hv_sample_live_record_display

实时显示 EVS 与 APS 画面，按 r 开始或停止录制，按 q 或 ESC 退出。无显示器时追加 --no-display；可用 --evs-prefix 和 --aps-prefix 设置录制文件前缀。

player

# x86_64
./out/x86_64/build/samples/cpp/player/hv_sample_player events.raw video.avi

# S100
/app/build/samples/cpp/player/hv_sample_player events.raw video.avi

# X5
/app/build/samples/cpp/player/hv_sample_player events.raw video.avi

离线同步回放 record 或 live_record_display 生成的 EVS .raw 和 APS .avi 文件。可在文件名后追加 fps 与 speed，例如 events.raw video.avi 60 2.0；ARM 平台需先满足下方的 OpenCV 运行库要求。

x86_64：

player 示例运行输出

HV Player 回放窗口

player 与 live_record_display 在 S100/X5 上还需要部署 third_party/aarch64_opencv/lib/aarch64-linux-gnu 中的 OpenCV 运行库，并将其加入 LD_LIBRARY_PATH。

Toolkit 示例（Python）

Python 样例统一在 samples/python/ 下，与 C++ 同一套 hv_toolkit API。构建 Python 绑定（./run.sh --python build ...）时随构建拷贝到 build/samples/python/（S100 为 out/s100/build/samples/python/），可直接 scp 到板卡运行。

示例	用途	涉及 API	需硬件	适用平台
`get_started.py`	USB 最小采集（init→get_frame→解码）	`Camera` / `DeviceConfig` / `Evt2Decoder`	是	x86_64（USB）
`get_started_mipi.py`	MIPI HVS 最小采集（支持 `-s/-i/-n/-c` 参数）	`Camera`（`MipiHvs`）/ `MipiRaw8Decoder`	是（MIPI）	S100 / RK3588
`record.py`	`Evt3Encoder` 编码合成事件并写 RAW 文件（不碰相机）	`Evt3Encoder` / `EventCD`	否	全平台
`viewer.py`	`Evt3` 编解码往返（encode→decode→计数）	`Evt3Encoder` / `Evt3Decoder`	否	全平台
`callback.py`	事件 / 图像计数演示（同步轮询）	`Camera` / `get_frame`	是	x86_64（USB 默认）

Python 绑定暂未导出异步回调（set_event_callback 等），故 callback.py 用 get_frame 同步轮询演示等价的计数模式；需要真正异步回调时用 C++ callback 示例。
没有相机时，record.py / viewer.py 可直接跑（验证 aarch64 编解码往返）；接好 MIPI 相机后跑 get_started_mipi.py 验证实采。完整 Python 接口见 Python API，板卡部署见第一个 Python 程序 → S100 板卡部署。

Algo 示例（去噪 / 检测）

示例	用途	算法	需硬件	详情
`dwf_denoising`	双窗口滤波去噪	`DoubleWindowFilter`	否（可读 raw）	algo
`event_flow_denoising`	事件流滤波去噪	`EventFlowFilter`	否	algo
`khodamoradi_denoising`	时空邻域去噪	`KhodamoradiDenoiser`	否	algo
`mlpf_denoising`	MLP 深度学习去噪（需 PyTorch）	`MultiLayerPerceptronFilter`	否	algo
`re_denoising`	递归事件去噪	`ReclusiveEventDenoisor`	否	algo
`ts_denoising`	时间表面去噪	`TimeSurfaceDenoisor`	否	algo
`y_denoising`	Yang 时空密度去噪	`YangNoiseFilter`	否	algo
OpticalFlow	EVS 光流可视化	`Of`	否（可读 raw）	windows-algo-sdk
HandDetector	手形检测 + 关键点	`HandDetector`	否	windows-algo-sdk
HumanDetector	人形检测	`HumanDetector`	否	windows-algo-sdk

如何选择示例

入门：get_started（最小闭环）→ callback（双回调）→ record（录制）→ viewer（回放）
实时预览 + 录制：MIPI 用 live_record_display；离线回放用 player
性能基准：实机 USB 用 bench_hw
去噪：从 dwf_denoising（经典、低算力）入手；运动场景试 event_flow_denoising；高精度场景试 mlpf_denoising（需 PyTorch）。算法对比见 Hybrid Vision Algo
没有相机：所有标"否"的示例均可使用示例录像

各算法解决什么问题

事件相机的原始输出是稀疏的异步事件点，通常需要经过"去噪 → 特征/运动分析 → 识别"等步骤才能用于应用。以下是 SDK 中主要算法的定位。

去噪（Denoise）

事件相机即使在静止场景下也会持续产生少量"背景活动噪声"，真实运动事件与之混在一起。去噪算法判断每个事件是真实信号还是噪声。

输入：一个事件 (x, y, t, polarity) 及其时空邻域内的事件历史。
算法做什么：基于"真实运动会在时空上产生成簇事件"这一先验，统计邻域内的事件数量/密度/流速，将孤立事件判为噪声并丢弃。
输出：布尔判定（保留/丢弃），或过滤后的事件序列。

7 种去噪算法的差异主要在邻域度量与判定准则：双窗口滤波用两个时间窗分类；事件流滤波用流速特征；Khodamoradi/递归/时间表面用时空邻域；MLP 用神经网络；Yang 用时空密度。选用建议见 Hybrid Vision Algo。

光流（Optical Flow）

输入：EVS 叠帧图像（事件累加成的帧）。
算法做什么：在相邻事件帧之间估计每个像素的运动方向与速度（光流向量）。
输出：每像素的 (vx, vy) 光流场，可用箭头可视化。

光流适合高速运动分析、运动方向检测。

手形 / 人形检测（Hand / Human Detector）

输入：EVS 事件图像。
算法做什么：基于事件流训练的深度学习检测器，定位目标并输出边界框（人形）或边界框 + 关键点（手形）。
输出：检测框列表 vector<Rect>，手形额外输出关键点 vector<vector<Point2f>>。

适合手势识别、人员监测等。当前 Windows Algo SDK 提供预训练模型；模型替换与训练能力见 Windows Algo SDK。