Metadata-Version: 2.4
Name: speck_tools
Version: 0.1.1
Summary: Speck channel mapping, event CSV utilities and Speck2f configuration export
Project-URL: Repository, https://github.com/Synsense-Industrial-Applications/speck_tools
Project-URL: Issues, https://github.com/Synsense-Industrial-Applications/speck_tools/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.23

# speck_tools

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

```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 发布完成后，可直接安装公开发行包：

```bash
python -m pip install speck_tools
```

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

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

```bash
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`。

也可以下载源码后安装：

```bash
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 发布者绑定](docs/maintenance.md#首次绑定-pypi)。

## 目录

```text
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` 应保存在使用者的项目中。

## 通道和空间映射

```python
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 字节数组封装，但其内部固件协议不同：

| 接口 | 数据来源 | 是否需要开发板 | 配置协议 |
| --- | --- | --- | --- |
| `generate_speck_config_c` | 354 KiB Flash 镜像 | 否 | `legacy_flash` |
| `generate_speck_config_c_spi` | SDK 实际发送的 SPI 数据 | 是 | `spi_zero_rle` |

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

```python
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 捕获示例见
[配置导出说明](docs/config_export.md)。

## 事件存储

```python
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 说明](docs/api.md)。

## 迁移现有项目

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

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

## 测试与构建

```bash
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 加载需在配套固件上验证。
初始代码迁移和七序列配置的一致性结果见 [迁移验证记录](docs/migration.md)。

## 版本维护

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