# TouchSensor 2.0

> 基于 Qt 6 与自研 Modern Qt 组件库打造的实时触觉传感器探索界面。

![状态](.assist/status-alpha.svg)
![Qt 版本](.assist/qt-6-5-plus.svg)
![C++ 标准](.assist/cpp-23.svg)
![CMake 版本](.assist/cmake-3-20.svg)
![UI 工具集](.assist/modern-qt.svg)

![TouchSensor Logo](images/logo.png)

## 项目亮点
- 基于仓库内置的 `modern-qt` 库构建现代化、贴近 Material 风格的桌面壳层。
- 左侧导航栏搭配卡片式主界面，集中承载串口控制面板与双热力图视图。
- 实时触觉数据流水线：`ffmsep::CPStreamCore` 负责串口 I/O、编解码调度与帧缓存。
- 内置触觉编解码模块（`ffmsep::tactile`）自动解析载荷、推断矩阵尺寸并输出压力量表。
- 两套 `HeatMapPlot` 组件通过响应式数据源实时刷新，并与主题色梯度联动。

## 当前进展
- UI 内可完成串口的搜索、连接与断开，同时支持周期性从站轮询指令。
- 编解码注册流程已接入触觉解码器，控制台输出原始帧内容与矩阵提示，便于调试。
- 双热力图面板会根据解码结果动态调整矩阵尺寸，停止串流时自动回落至默认状态。
- 同时提供 `cpstream_demo` CLI，用于在无界面环境校验串流核心逻辑。

## 架构速览
- **入口**：`main.cc` 负责加载主题、导航栏、遮罩动画以及传感器面板。
- **组件层**：`components/` 收纳导航/视图界面、图表组件以及触觉串流管线。
- **Modern Qt 工具集**：`modern-qt/` 提供声明式封装、主题系统与 Material 图标工具。
- **串流与编解码**：`components/ffmsep` 打包编解码注册、`CPStreamCore` 与触觉帧解析工具。
- **可视化**：`components/charts/heatmap.*` 提供可主题化的热力图控件，支持梯度和矩阵重设。
- **示例**：`examples/` 下的 `cpstream_demo.cc` 可单独运行验证串流核心。

## 快速开始

### 环境要求
- CMake 3.20+
- 支持 C++23 的编译器（MSVC 19.3x、Clang 16+ 或 GCC 13+）
- Qt 6（至少包含 Widgets、Network、PrintSupport 模块）
- Eigen3
- `spdlog`（可通过包管理器安装或手动提供给 CMake）
- [`serial`](https://github.com/wjwwood/serial)（跨平台串口库，可包管理器安装或自行构建）

确保 `Qt6_DIR` 或 `CMAKE_PREFIX_PATH` 指向 Qt 安装路径，以便 CMake 正确找到依赖模块。

### 配置与构建

![](https://picgo-upload.cn-nb1.rains3.com/2025/10/407c29f139a834ed0f79a81347f810f1.png)
```powershell
pacman -Sy
pacman -S mingw-w64-x86_64-toolchain
pacman -S mingw64/mingw-w64-x86_64-qt6-base
pacman -S mingw-w64-x86_64-eigen3 mingw-w64-x86_64-yaml-cpp

mkdir build
cmake -G "MinGW Makefiles" -B build -DCMAKE_INSTALL_PREFIX="YOUR INSTALL PATH"

cd build && mingw32-make install

cat install_manifest.txt
```

从构建目录直接运行：

```powershell
.\touchsensor.exe
```

在 Linux/macOS 上使用对应的 Qt 安装路径与可执行文件名。

### 运行传感器界面
- 通过 USB 接入触觉设备，确认系统识别到的串口号。
- 启动 `touchsensor.exe`（或平台对应的可执行文件）。
- 在串口下拉列表中选择端口，可按需刷新；若需更换波特率请同步调整。
- 点击链接图标开始串流，双热力图将实时更新，控制台亦会打印原始载荷。
- 再次点击链接图标即可断开连接，界面会回落到默认示例数据。

当 `BUILD_EXAMPLE` 选项开启时会同步构建 `cpstream_demo`，可在终端中运行验证串流与编解码流程。

## 项目结构

```text
.
|-- components/
|   |-- charts/           # 基于 QCustomPlot 的热力图等可视化组件
|   |-- ffmsep/           # 触觉串流核心与编解码实现
|   |-- nav.cc            # 导航栏与主题切换逻辑
|   |-- view.cc           # 传感器控制面板与双热力图
|   `-- ...               # 其他 UI 组件
|-- examples/             # cpstream_demo 命令行示例
|-- modern-qt/            # 自研 Qt 声明式 UI 框架
|-- serial/               # 串口通信辅助库
|-- images/logo.png       # 项目标识
|-- main.cc               # 程序入口
`-- CMakeLists.txt        # 构建脚本，聚合 Qt、Eigen、Modern Qt、Serial、SPDLOG
```

## 路线图（进行中）
- **已完成** 串口串流管线（轮询、编解码回调、热力图数据绑定）已连通。
- **已完成** HeatMapPlot 支持矩阵提示与梯度调节，能随解码结果刷新。
- **规划中** 引入内置诊断/历史面板，替换当前的标准输出日志。
- **规划中** 保存串口偏好、提供手动矩阵覆写，并补充文档素材。
- **规划中** 扩展导航目标，完善非传感器场景。

## 致谢
- [Qt](https://www.qt.io/) 提供核心 UI 框架。
- [QCustomPlot](https://www.qcustomplot.com/) 支撑热力图组件。
- [spdlog](https://github.com/gabime/spdlog) 用于日志记录（已在 CMake 中接入）。
- [serial](https://github.com/wjwwood/serial) 提供跨平台串口能力。
- 内部 **Modern Qt** 工具集基于 creeper-qt 生态构建。