From 221f7303ee759e63a1e2076f77b205fdf8ab0ebe Mon Sep 17 00:00:00 2001 From: lenn Date: Wed, 5 Nov 2025 09:12:24 +0800 Subject: [PATCH] update README.md --- README.md | 119 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 68 insertions(+), 51 deletions(-) diff --git a/README.md b/README.md index a85cd81..b477ebc 100644 --- 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 生态构建。