speck_tools

用于 Speck 实验代码的 Python 工具库。所有工具通过一个入口导入：

from speck_tools import (
    ChannelHelper,
    generate_speck_config_c,
    generate_speck_config_c_spi,
    generate_flow_decode_comment,
    write_events_to_csv,
)

本版本整理已有代码并完善注释，保留原函数名、参数、默认值及配置字节编码。 暂不包含可视化工具，不需要 Matplotlib 或 samnagui。

安装

需要 Python 3.10 或更高版本，基础依赖为 NumPy。 PyPI 发布完成后，可直接安装公开发行包：

python -m pip install speck_tools

指定版本安装使用 python -m pip install speck_tools==0.1.1。 已安装的版本可通过 speck_tools.__version__ 查看。

也支持直接从源码仓库安装。仓库当前为私有仓库，需要先配置具有仓库读取权限的 GitHub SSH 身份：

python -m pip install "speck_tools @ git+ssh://git@github.com/Synsense-Industrial-Applications/speck_tools.git@main"

正式实验应将 @main 替换为经过验证的完整 commit SHA，记录在项目的 requirements.txt 中。维护者发布版本标签后，也可使用 @v0.1.0 这样的标签。 工具包版本保存在 src/speck_tools/_version.py。

也可以下载源码后安装：

git clone git@github.com:Synsense-Industrial-Applications/speck_tools.git
cd speck_tools
python -m pip install .

维护工具源码时使用 python -m pip install -e .。 源码提交、Git 版本标签和 PyPI 发行是三个步骤；以实际 PyPI 项目页面为准。 维护者首次发布前必须完成 PyPI 发布者绑定。

目录

src/speck_tools/
├── __init__.py          # 统一公开入口
├── _version.py          # 工具包版本
├── channel_mapping.py   # ChannelHelper、point_withchannel
├── config_export.py     # 两种配置编码和 C 文件导出
├── flow_decode.py       # 当前四方向光流的解码示例注释
└── event_io.py          # CSV 读写侧的存储、后台写入和事件计数

event_io 当前提供写入功能，没有新增 CSV 读取器。 算法网络配置和实验生成的 .c 应保存在使用者的项目中。

通道和空间映射

from speck_tools import ChannelHelper

helper = ChannelHelper(input_channel=2, input_size=128, output_size=64)
coarse = helper.get_tuple((1, 5, 6))  # (6, 2, 3)
assert helper.get_tuple(coarse, mode_flage=1) == (1, 5, 6)
padding, stride, kernel_size, weights = helper.generate_conv_mapping()

历史参数 mode_flage、方法 caculate_cxy 和类 point_withchannel 保持原拼写，避免已有代码失效。详细返回值和适用范围见函数 docstring。

配置导出

两种工具导出相同类型的 C 字节数组封装，但其内部固件协议不同：

工具包升级后仍可生成旧协议，协议不随包版本自动切换。 samna 由硬件环境单独安装和管理；导入基础工具不加载 samna。 旧格式导出在调用时才导入 samna，SPI 捕获需要设备支持 make_unifirm_hook()。

from speck_tools import generate_speck_config_c

# config 是调用者已构造完成的 Speck2f 网络配置。
path = generate_speck_config_c(
    config, "output/model_legacy.c", fast_output=True,
)

完整参数、fast 输出说明、光流注释开关及 SPI 捕获示例见 配置导出说明。

事件存储

from speck_tools import write_events_to_csv, print_layer_feature_counts

# events 是已经从设备缓冲区读取到的同一批事件。
write_events_to_csv(events, "recordings/run_001")
print_layer_feature_counts(events)

每个物理 layer 对应 layer_<编号>.csv，列顺序保留为 feature,y,x,timestamp。后台进程写入和清理目录接口见 API 说明。

迁移现有项目

1. 安装本库并固定版本或提交。
2. 将旧项目中的 speck_tools.py 移出模块搜索路径，避免遮蔽已安装的包。
3. 将独立文件导入改为 from speck_tools import ...。
4. 使用同一份配置检查生成数组一致，再切换正式实验。

本次迁移不改动使用者已有算法脚本，也不自动修改 samna 环境。

测试与构建

python -m pip install -e .
python -m unittest discover -s tests -v
python -m pip install build
python -m build

dist/ 生成 wheel 和源码压缩包；安装 wheel 时，NumPy 必须已存在或能从 配置的软件源下载。CI 在 Python 3.10 和 3.12 中执行无板测试并验证 wheel 安装。 SPI 测试使用模拟设备，不会访问或修改硬件；实际 MCU 加载需在配套固件上验证。 初始代码迁移和七序列配置的一致性结果见 迁移验证记录。

版本维护

修改后运行回归测试，在 _version.py 和 CHANGELOG.md 中更新版本， 提交后再创建对应标签。涉及配置协议的修改必须明确记录，不能将工具包版本 当成 MCU 协议版本。发布流程见 维护说明。