05 第一个 Python 程序

本页通过仓库中的 Python 绑定模块 hv_toolkit（pybind11 生成）验证最小采集链路。同一套 API 通吃 USB（x86_64）与 MIPI HVS（S100/RK3588）。

v2.0 已移除旧版四个独立模块（hv_evt2_codec_python / hv_event_reader_python / hv_event_writer_python / hv_camera_python），统一为单一 hv_toolkit 模块。完整接口见 Python API。

1. 构建 Python 绑定

Python 绑定默认关闭，构建时加全局开关 --python：

cd shimetapi_Hybrid_vision_toolkit
./run.sh --python build x86_64   # USB；产物 build/hv_toolkit.<abi>.so
# MIPI HVS（S100）：./run.sh --python build s100 → out/s100/build/hv_toolkit.cpython-310-aarch64-linux-gnu.so

产物 .so 必须与运行 Python 的架构/ABI 匹配：x86_64 跑 x86_64 的，S100 板卡跑 aarch64 的（不能互换）。

2. 核心代码（USB）

import hv_toolkit as hv

# 1. 配置后端（USB）
cfg = hv.DeviceConfig()
cfg.backend    = hv.Backend.Usb
cfg.vendor_id  = 0x1d6b   # 替换为你的实际 VID/PID
cfg.product_id = 0x0105

# 2. 初始化 + 启动采集
cam = hv.Camera()
cam.init(cfg)
if not cam.start_stream():
    print("打开相机失败")
    raise SystemExit(1)
print("相机已就绪")

# 3. 同步拉取 10 帧 + 解码事件
dec = hv.Evt2Decoder()
f = hv.Frame()
for i in range(10):
    if cam.get_frame(f, 1000):
        events = dec.decode(bytes(f.evs))   # → numpy 结构数组 (x, y, t, polarity)
        print(f"frame {i}: {f.width}x{f.height}, {len(events)} events, aps={f.aps.nbytes} bytes")

# 4. 停止 + 释放
cam.stop_stream()
cam.destroy()

3. MIPI HVS（S100）

只换 backend 配置与解码器——Camera/Frame/get_frame 完全一致：

cfg = hv.DeviceConfig()
cfg.backend      = hv.Backend.MipiHvs
cfg.device_node  = "/dev/video0"
cfg.sensor_index = 0
cfg.i2c_bus      = 1

cam = hv.Camera(); cam.init(cfg); cam.start_stream()
dec = hv.MipiRaw8Decoder()        # MIPI HVS 的 Frame.evs 是 RAW8 子帧流，必须用它（不是 Evt2/Evt3）
f = hv.Frame()
while cam.get_frame(f, 1000):
    events = dec.decode(bytes(f.evs))
    print(f"{len(events)} events, aps={f.aps.nbytes} bytes, fmt={f.format}")
cam.stop_stream(); cam.destroy()

完整可运行样例见仓库 samples/python/get_started.py（USB）与 samples/python/get_started_mipi.py（MIPI HVS，支持 -s/-i/-n/-c 参数）。

S100 板卡部署

把 out/s100/build/ 下的 libshimetapi_*.so + hv_toolkit.*.so + 样例拷到板卡 /home/sunrise/build：

# 板卡上
export LD_LIBRARY_PATH=/home/sunrise/build:$LD_LIBRARY_PATH
export PYTHONPATH=/home/sunrise/build:$PYTHONPATH
python3 /home/sunrise/build/samples/python/get_started_mipi.py

详细部署步骤（打包/scp/冒烟测试）见 Python API → 构建与部署。

4. EVT3 编解码

# 编码：事件 → EVT3 bytes
enc = hv.Evt3Encoder()
e = hv.EventCD()
e.x, e.y, e.t, e.polarity = 100, 50, 12345, True
raw = enc.encode([e])

# 解码：EVT3 bytes → 事件数组
dec = hv.Evt3Decoder()
events = dec.decode(raw)
print(f"decoded {len(events)} events")

5. USB 权限

若 start_stream() 返回 False 且报 LIBUSB_ERROR_ACCESS，推荐 udev 规则（免 sudo）：

echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="1d6b", ATTR{idProduct}=="0105", MODE="0666"' \
  | sudo tee /etc/udev/rules.d/99-hv-camera.rules
sudo udevadm control --reload-rules && sudo udevadm trigger

6. 下一步

仍需 C++ 的能力：异步回调（SetFrameCallback / SetEventCallback / SetImageCallback）、EventReader / EventWriter、HybridReader / HybridWriter 暂未导出 Python，需要时使用 C++ API。