Metadata-Version: 2.4
Name: touchglove
Version: 0.2.0
Requires-Dist: numpy >=1.20.0
License-File: LICENSE
Summary: Touch Glove SDK - Python bindings
Author: ImprintX
License: Proprietary
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# Touch Glove SDK

Touch Glove 数据采集与实时推理 SDK。本项目包含由 Rust 实现的高性能底层驱动库，对外提供 Python 绑定（`touchglove`）与标准 C API 接口。

SDK 的核心功能包括：
- **高吞吐数据传输**：支持 5 个通道（手套传感器）实时 192x192 灰度图像流的高频采集。
- **PTP / RTC 硬件时间同步**：支持手套硬件 RTC 与主机系统时间同步及精准时间戳查询。
- **设备 SN 读写工具**：提供读写和校验手套硬件 SN 的命令行工具 [write_sn.py](file:///home/iiserver0/Projects/touch-glove-sdk_0.2/write_sn.py)。
- **实时物理推理**：集成 **ONNX Runtime / OpenVINO 推理引擎**，支持直接推理 3D 位移场与 3D 力场，并提供去皮基线校准。
- **H.265 视频录制**：支持高效率 H.265 (HEVC) MP4 视频录制，并生成多通道精准逐帧微秒级时间戳 JSON。
- **ROS 2 实时发布**：支持将原始图像、位移场和力场实时广播至 ROS 2 话题。

---

## 1. 项目源码结构

```text
.
├── example.py                     # Python 综合示例（支持 stream, gui, ros2, inference, record 五大模式）
├── write_sn.py                    # 硬件 SN 序列号写入与校验工具
├── pyproject.toml                 # Maturin Python SDK 构建配置
├── TacSP_上行协议规范.md           # TacSP 串口通信协议设计规范
├── README.md                      # 本说明文档
├── LICENSE                        # 项目开源许可证
├── include/
│   └── touch_glove_api.h          # C/C++ 接口头文件
├── api/                           # Rust/C 底层驱动与推理引擎源码项目
│   ├── Cargo.toml                 # Cargo 项目配置
│   ├── build.rs                   # Rust build 脚本
│   ├── touch_glove_api.c          # C API 实现源码
│   ├── touch_glove_api.h          # C API 头文件
│   └── src/
│       ├── lib.rs                 # Rust 库入口
│       ├── serial_io.rs           # 串口通信与 PTP 时钟同步
│       ├── protocol.rs            # TacSP 协议解析器
│       ├── parser.rs              # 图像帧解码
│       ├── context.rs             # SDK 句柄上下文与状态流
│       ├── encoder.rs             # H.265 视频录制与多通道时间戳导出
│       ├── inference.rs           # ONNX / OpenVINO 多引擎推理
│       └── python/                # PyO3 Python 扩展绑定
└── scripts/                       # SDK 依赖获取与打包辅助脚本
    ├── fetch_onnxruntime.py
    └── package_sdk.py
```

---

## 2. 编译与构建

### 2.1 构建 Python SDK 包 (`touchglove`)

推荐使用 [maturin](https://github.com/PyO3/maturin) 编译 Rust 底层库并安装为 Python 包：

```bash
# 1. 安装 maturin
pip3 install maturin

# 2. 编译并以 release 模式安装到当前 Python 环境
maturin develop --release --features python
```

### 2.2 编译 C/C++ 原生动态库 (`libtouch_glove.so`)

如果需要在 C/C++ 项目中使用 SDK，进入 `api/` 目录进行构建：

```bash
cd api
cargo build --release
```
编译生成的共享库文件位于 `api/target/release/libtouch_glove.so`。

---

## 3. 示例程序使用说明

### 3.1 Python 综合示例 `example.py`

[example.py](file:///home/iiserver0/Projects/touch-glove-sdk_0.2/example.py) 是 SDK 的核心功能演示程序，支持 5 种运行模式：

```bash
# 模式 1: Simple Stream (基础控制台终端实时数据流输出)
python3 example.py /dev/ttyACM0 --mode stream

# 模式 2: GUI Display (OpenCV 网格图形界面展示 5 通道实时图像)
python3 example.py /dev/ttyACM0 --mode gui

# 模式 3: ROS 2 Publishing (作为 ROS 2 Publisher 实时发布 /touch_glove/ch{0..4} 图像话题)
python3 example.py /dev/ttyACM0 --mode ros2

# 模式 4: Inference (实时 ONNX 物理推理，计算 3D 位移场与 3D 力场，支持按 'b' 键实时基线去皮标定)
python3 example.py /dev/ttyACM0 --mode inference --model /path/to/dense_3ch.onnx --device cuda

# 模式 5: Record (录制 5 通道 H.265 MP4 视频，并导出微秒级多通道时间戳 JSON)
python3 example.py /dev/ttyACM0 --mode record --record-path output.mp4 --duration 10.0
```

> **参数说明**：
> - `port`：串口路径（如未指定，程序会自动扫描并弹出可交互列表供选择）。
> - `--mode`：选择运行模式（`stream` | `gui` | `ros2` | `inference` | `record`）。
> - `--model`：指定 ONNX 推理模型路径（`inference` 模式下必需）。
> - `--device`：指定推理硬件（`cuda` / `gpu` 或 `cpu`）。
> - `--record-path`：录制模式输出 MP4 视频路径。
> - `--duration`：录制时长（秒）。

### 3.2 硬件 SN 写入与校验工具 `write_sn.py`

[write_sn.py](file:///home/iiserver0/Projects/touch-glove-sdk_0.2/write_sn.py) 用于读写和校验手套硬件内部存储的序列号（SN）：

```bash
# 交互式运行（自动检测串口并提示输入 SN）
python3 write_sn.py

# 指定 SN 自动写入（自动匹配串口）
python3 write_sn.py 30L260803001P

# 指定 SN 与串口写入
python3 write_sn.py 30L260803001P /dev/ttyACM0
```

---

## 4. Python SDK API 极简示例

在您自己的 Python 代码中，可以直接导入 `touchglove`：

```python
from touchglove import TouchGlove, list_ports

# 1. 查询可用串口
ports = list_ports()
print("可用串口:", ports)

# 2. 打开设备并开启数据流
with TouchGlove(port=ports[0]) as glove:
    # 2.1 获取设备 SN 与 同步系统时间至硬件 RTC
    sn = glove.get_sn()
    print("设备 SN:", sn)
    glove.sync_rtc()
    
    # 2.2 启动数据流
    glove.start()
    
    # 2.3 轮询拉取数据帧
    while True:
        frames = glove.poll()
        for frame in frames:
            print(f"通道 {frame.channel} | 帧号: {frame.seq_id} | 时间戳 (PTP): {frame.timestamp_us} us | 图像形状: {frame.image.shape}")
```

---

## 5. C API 文档说明

底层 Rust 驱动库导出标准 C 接口（定义见 [include/touch_glove_api.h](file:///home/iiserver0/Projects/touch-glove-sdk_0.2/include/touch_glove_api.h)）。

### 5.1 核心数据类型

```c
typedef struct ts_frame_t {
    uint8_t addr;                  // 设备地址
    uint8_t type;                  // 帧类型
    uint8_t cmd;                   // 命令 / 通道号 (0x11-0x15 对应 Ch 0-4)
    uint16_t param_len;            // 参数长度 (图像为 36864 字节)
    uint32_t seq_id;               // 序列号 (丢包检测)
    uint64_t timestamp_us;         // 硬件接收 PTP 时间戳 (微秒)
    uint8_t sensor_id[8];          // 通道传感器 UID
    uint8_t param[36864];          // 192x192 灰度图像原始字节
} ts_frame_t;
```

### 5.2 核心 C 函数

- **`touch_glove_handle_t touch_glove_create(void)`**：创建 SDK 句柄实例。
- **`void touch_glove_destroy(touch_glove_handle_t h)`**：断开连接并销毁实例。
- **`int touch_glove_open(touch_glove_handle_t h, const char* port_name)`**：打开串口设备。
- **`void touch_glove_close(touch_glove_handle_t h)`**：关闭串口。
- **`int touch_glove_send_start(touch_glove_handle_t h)`**：启动硬件数据流。
- **`int touch_glove_send_stop(touch_glove_handle_t h)`**：停止硬件数据流。
- **`void touch_glove_poll_read(touch_glove_handle_t h)`**：非阻塞轮询读取并解析串口缓冲区。
- **`int touch_glove_init_model(touch_glove_handle_t h, const char* model_path)`**：初始化 ONNX 推理引擎。
- **`int touch_glove_calibrate(touch_glove_handle_t h)`**：执行零点基线去皮标定。
- **`int touch_glove_infer(touch_glove_handle_t h, const uint8_t* last_images, float* out_disp, float* out_force)`**：传入 5 通道图像数据，推理输出 3D 位移场与 3D 力场。

---

## 6. 通信协议规范

关于手套串口通信协议格式、寄存器指令集、硬件 RTC 时间戳同步规范及 SN 数据帧格式的完整说明，请参阅：
- [TacSP_上行协议规范.md](file:///home/iiserver0/Projects/touch-glove-sdk_0.2/TacSP_%E4%B8%8A%E8%A1%8C%E5%8D%8F%E8%AE%AE%E8%A7%84%E8%8C%83.md)

