update README.md

2025-11-05 09:12:24 +08:00
parent 6ed795a2b6
commit 221f7303ee
1 changed files with 68 additions and 51 deletions
--- a/README.md
+++ b/README.md
@@ -1,41 +1,49 @@
 # TouchSensor 2.0

-> Real-time tactile sensor exploration UI powered by Qt 6 and a custom Modern Qt component toolkit.
+> 基于 Qt 6 与自研 Modern Qt 组件库打造的实时触觉传感器探索界面。

-![Status](https://img.shields.io/badge/status-prototype-orange?style=for-the-badge)
-![Qt 6](https://img.shields.io/badge/Qt-6.5%2B-41CD52?style=for-the-badge&logo=qt)
-![C++23](https://img.shields.io/badge/C%2B%2B-23-00599C?style=for-the-badge&logo=cplusplus)
-![CMake](https://img.shields.io/badge/CMake-3.20%2B-064F8C?style=for-the-badge&logo=cmake)
-![UI Toolkit](https://img.shields.io/badge/Modern%20Qt-internal-8A2BE2?style=for-the-badge)
+![状态](.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)

-## Highlights
- Modern, material-inspired desktop shell built on the in-repo `modern-qt` library.
- Modular component system (`NavComponent`, `ViewComponent`) for quick UI experiments.
- Real-time tactile matrix visualisation via the `HeatMapPlot` wrapper around QCustomPlot.
- Codec infrastructure (`components/ffmsep`) ready for custom tactile packet decoding.
- Serial transport module scaffolded for COM port discovery and streaming.
+## 项目亮点
+- 基于仓库内置的 `modern-qt` 库构建现代化、贴近 Material 风格的桌面壳层。
+- 左侧导航栏搭配卡片式主界面，集中承载串口控制面板与双热力图视图。
+- 实时触觉数据流水线：`ffmsep::CPStreamCore` 负责串口 I/O、编解码调度与帧缓存。
+- 内置触觉编解码模块（`ffmsep::tactile`）自动解析载荷、推断矩阵尺寸并输出压力量表。
+- 两套 `HeatMapPlot` 组件通过响应式数据源实时刷新，并与主题色梯度联动。

-## Architecture At A Glance
- **Entry point**: `main.cc` composes the themed window, navigation rail, and card-based layout.
- **Components**: `components/` hosts UI widgets, charts, and the tactile decoder pipeline.
- **Modern Qt toolkit**: `modern-qt/` provides declarative wrappers, theming, and Material icon helpers.
- **Data layer**: `components/ffmsep` implements codec registration, packet decoding, and tactile frame processing.
- **Visualisation**: `components/charts/heatmap.*` exposes a themable heatmap control for sensor grids.
+## 当前进展
+- UI 内可完成串口的搜索、连接与断开，同时支持周期性从站轮询指令。
+- 编解码注册流程已接入触觉解码器，控制台输出原始帧内容与矩阵提示，便于调试。
+- 双热力图面板会根据解码结果动态调整矩阵尺寸，停止串流时自动回落至默认状态。
+- 同时提供 `cpstream_demo` CLI，用于在无界面环境校验串流核心逻辑。

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

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

-Ensure `Qt6_DIR` (or `CMAKE_PREFIX_PATH`) points to the Qt install so CMake can locate the required modules.
+确保 `Qt6_DIR` 或 `CMAKE_PREFIX_PATH` 指向 Qt 安装路径，以便 CMake 正确找到依赖模块。

-### Configure & Build
+### 配置与构建

 ![](https://picgo-upload.cn-nb1.rains3.com/2025/10/407c29f139a834ed0f79a81347f810f1.png)
 ```powershell
@@ -52,42 +60,51 @@ cd build && mingw32-make install
 cat install_manifest.txt
 ```

-To run from the build directory:
+从构建目录直接运行：

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

-On Linux/macOS adjust the Qt path and executable name accordingly.
+在 Linux/macOS 上使用对应的 Qt 安装路径与可执行文件名。

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

 ```text
 .
 |-- components/
-|   |-- charts/           # QCustomPlot-based visualisations (heatmaps, etc.)
-|   |-- ffmsep/           # Codec system and tactile decoder experiments
-|   |-- view.cc           # Main dashboard composition
-|   `-- ...               # Additional UI widgets
-|-- modern-qt/            # In-house declarative Qt UI framework
-|-- serial/               # Serial communication helper library
-|-- images/logo.png       # Current app branding
-|-- main.cc               # Application bootstrap
-`-- CMakeLists.txt        # Build script (adds Qt, Eigen, Modern Qt, Serial, SPDLOG)
+|   |-- 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
 ```

-## Roadmap (WIP)
- Flesh out tactile codec implementations and connect them to live serial streams.
- Replace placeholder random data with decoded sensor frames.
- Expand navigation targets beyond the current demo cards.
- Capture screenshots or recordings for documentation.
- Polish theming, animation masks, and landing experience.
+## 路线图（进行中）
+- **已完成** 串口串流管线（轮询、编解码回调、热力图数据绑定）已连通。
+- **已完成** HeatMapPlot 支持矩阵提示与梯度调节，能随解码结果刷新。
+- **规划中** 引入内置诊断/历史面板，替换当前的标准输出日志。
+- **规划中** 保存串口偏好、提供手动矩阵覆写，并补充文档素材。
+- **规划中** 扩展导航目标，完善非传感器场景。

-## Contributing
-This repository is in active development; feel free to open issues or PRs once guidelines land. Until then, keep discussions in the project chat or issues board.
-
-## Acknowledgements
- [Qt](https://www.qt.io/) for the core UI framework.
- [QCustomPlot](https://www.qcustomplot.com/) powering the heatmap widget.
- [spdlog](https://github.com/gabime/spdlog) for logging (wired via CMake).
- Internal **Modern Qt** toolkit built on top of creeper-qt utilities.
+## 致谢
+- [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 生态构建。