# 点云地图编辑工具 **Repository Path**: changan-project/point-cloud-map-editing-tool ## Basic Information - **Project Name**: 点云地图编辑工具 - **Description**: 点云地图编辑工具 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-04-25 - **Last Updated**: 2025-06-23 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # CMALmap 应用程序技术与功能文档 --- ## 摘要 CMALmap是一款专为机器人地图操作与可视化设计的桌面应用程序。它提供了强大的地图查看、编辑和管理功能，能够通过WebSocket实时接收和显示来自机器人系统(如ROS)的地图、激光扫描和位姿数据。本文档详细阐述了该应用的功能需求和技术实现方案。 --- ## 1. 模块需求 ### 1.1 基础功能需求 - **① 地图显示与管理**：支持加载、显示、保存各种格式的地图数据。 - **② 多地图单元管理**：支持创建、切换、重命名和删除多个地图单元。 - **③ 实时数据接收**：通过WebSocket接收地图、激光扫描和机器人位姿数据。 - **④ 特征管理**：支持添加和管理地图上的特征点。 - **⑤ 区域划分**：支持定义和管理地图上的特定区域。 - **⑥ 自动保存**：支持地图数据的自动保存和恢复。 - **⑦ 通用操作**：提供通用的编辑操作，包括对标注和特征的移动、删除、复制、粘贴以及撤销/重做功能。 - **⑧ 地图擦除工具**：提供橡皮擦工具，可以擦除地图图像的部分区域。 ### 1.2 高级功能需求 - **① 地图拼接**：支持多个地图的拼接和整合。 - **② 地图校正**：自动校正地图的偏移和旋转。 - **③ 在线建图**：实时接收并可视化由外部SLAM系统生成的地图数据流，支持建图过程的动态观察。 - **④ 离线建图**：加载并可视化预先记录的数据集，支持离线分析地图构建过程。 - **⑤ 机器人控制**：从应用程序直接向机器人发送控制指令，实现远程遥控和导航。 - **⑥ 视图控制**：提供放大缩小、平移、适配等视图操作。 --- ## 2. 实现方案 ### 2.1 技术栈 - **开发框架**: Qt 5.15 (C++) - **UI组件**: Qt Widgets, Qt Graphics View Framework - **通信协议**: WebSocket (QtWebSockets) - **数据格式**: - **地图数据**: PNG, PGM, JPG, 自定义.mapdata格式 - **通信数据**: JSON - **图形渲染**: QGraphicsView/QGraphicsScene ### 2.2 基础功能实现方案 #### ① 地图显示与管理 **功能描述**: 支持加载、显示、保存各种格式的地图数据，提供地图的基本可视化功能。 **实现方案**: 1. **MapWidget类**: - 基于`QGraphicsView`框架创建一个专用的地图显示控件。 - 使用`QGraphicsScene`作为容器，管理地图、激光点、机器人和各类标注项。 - 实现地图图像的缩放、平移和旋转操作。 2. **MapManager类**: - 负责地图文件的加载和保存。 - 支持标准图像格式(PNG, PGM, JPG)直接加载。 - 实现自定义的`.mapdata`格式，该格式为ZIP压缩包，包含: ``` map.png - 地图图像文件 annotations.json - 标注数据(特征点、区域等) metadata.json - 地图元数据(分辨率、原点等) ``` 3. **图层管理**: - 将不同类型的数据组织为独立的逻辑图层: - 地图图层: 显示底层栅格地图。 - 激光扫描图层: 显示实时激光点云数据。 - 机器人图层: 显示机器人位置和姿态。 - 标注图层: 显示所有用户创建的标注。 - 每个图层可独立控制显示/隐藏状态。 4. **坐标转换**: - 实现像素坐标(图像)和物理坐标(世界)之间的转换。 - 提供坐标显示功能，使用户能够获取鼠标位置对应的物理坐标。 #### ② 多地图单元管理 **功能描述**: 支持在单个应用程序实例中管理多个独立的地图单元，每个单元具有独立的数据和配置。 **实现方案**: 1. **MapUnitManager类**: - 维护一个地图单元列表，每个单元具有唯一的名称和独立的文件系统路径。 - 为每个地图单元提供元数据管理，如创建时间、最后修改时间等。 - 实现地图单元的创建、切换、重命名和删除操作。 2. **文件系统结构**: - 在应用程序目录下创建`maplist/`文件夹，用于存储所有地图单元。 - 每个地图单元在`maplist/`下有独立子文件夹，命名为单元名称。 - 单元目录结构: ``` maplist/ ├── 单元1/ │ ├── map.png │ ├── annotations.json │ ├── metadata.json │ └── connection.json └── 单元2/ ├── ... ``` 3. **UI交互**: - 在主界面侧边栏提供地图单元列表。 - 实现右键菜单，提供创建、重命名、删除等操作。 - 双击列表项切换到相应的地图单元。 4. **数据隔离**: - 每个地图单元的数据(地图、标注、连接配置等)完全隔离，避免相互干扰。 - 切换单元时，清理当前场景并加载新单元的数据。 #### ③ 实时数据接收 **功能描述**: 通过WebSocket实时接收并可视化地图、激光扫描和机器人位姿数据。 **实现方案**: 1. **WebSocketClient类**: - 封装`QWebSocket`，实现与服务器的连接管理。 - 支持自动重连、连接状态监控和错误处理。 - 提供端口扫描功能，自动探测可用的WebSocket服务。 2. **数据解析**: - 接收JSON格式的消息，根据消息类型进行分类处理。 - 支持的消息类型: - `map`: 地图数据，包含占据栅格和元数据。 - `scan`: 激光扫描数据，包含距离值和角度信息。 - `pose`: 机器人位姿数据，包含位置和方向。 - `tf`: 坐标变换数据，处理多个参考系统间的转换。 3. **数据可视化**: - 地图数据: 解析为`QImage`并显示在地图图层。 - 激光数据: 将距离值转换为2D点集，绘制为散点图。 - 位姿数据: 使用自定义图标表示机器人位置和朝向。 4. **配置管理**: - 为每个地图单元保存独立的WebSocket连接配置。 - 提供连接设置界面，可指定服务器地址和端口。 - 支持连接历史记录，便于快速重连。 #### ④ 特征管理 **功能描述**: 支持在地图上添加、编辑和管理特征点，用于标记关键位置或导航点。 **实现方案**: 1. **FeatureItem类**: - 继承`QGraphicsItem`，实现特征点的可视化表示。 - 支持自定义图标、颜色和标签。 - 提供拖拽、选择和属性编辑功能。 2. **FeatureManager类**: - 管理所有特征点的集合。 - 实现特征点的添加、删除和查找。 - 提供数据序列化和反序列化功能，用于保存和加载。 3. **FeaturePanel类**: - 创建一个特征管理面板，显示所有特征点的列表。 - 支持选择、过滤和排序功能。 - 提供添加、删除和编辑特征的界面。 4. **交互逻辑**: - 当选择特征工具时，鼠标点击地图创建新特征点。 - 支持拖拽移动特征点位置。 - 双击特征点打开属性编辑对话框。 - 特征面板和地图之间的选择状态保持同步。 #### ⑤ 区域划分 **功能描述**: 支持在地图上定义和管理矩形区域，用于标记特定区域或设定工作范围。 **实现方案**: 1. **RegionAreaItem类**: - 继承`QGraphicsRectItem`，实现矩形区域的可视化。 - 支持半透明填充和边框样式定制。 - 提供缩放把手，允许调整区域大小。 2. **区域属性**: - 为每个区域提供名称、类型、描述等属性。 - 支持设定区域的用途标签(如"工作区"、"禁区"等)。 - 允许设置区域的颜色和透明度。 3. **编辑操作**: - 实现矩形绘制工具，通过拖拽定义区域。 - 支持移动、调整大小和旋转操作。 - 提供区域合并和拆分功能。 4. **数据管理**: - 将区域数据作为annotations.json的一部分保存。 - 在加载地图时恢复所有区域。 - 提供区域的导入/导出功能。 #### ⑥ 自动保存 **功能描述**: 支持地图数据的自动保存和恢复，防止意外情况下的数据丢失。 **实现方案**: 1. **自动保存机制**: - 使用`QTimer`定时触发自动保存操作(默认5分钟)。 - 检测数据修改状态，仅在有变动时执行保存。 - 保存到临时文件，避免覆盖主文件。 2. **恢复功能**: - 程序启动时检查是否存在自动保存文件。 - 若发现，提示用户是否恢复上次编辑状态。 - 提供自动保存历史，允许恢复到特定时间点。 3. **配置选项**: - 允许用户自定义自动保存间隔。 - 提供开启/关闭自动保存的选项。 - 配置自动保存文件的保留数量和清理策略。 4. **实现细节**: - 使用独立线程执行保存操作，避免阻塞UI。 - 采用两阶段保存策略(先写临时文件，成功后替换)，确保数据完整性。 - 维护简单的操作日志，记录关键编辑动作。 #### ⑦ 通用操作 **功能描述**: 提供通用的编辑操作，包括对标注和特征的移动、删除、复制、粘贴以及撤销/重做功能。 **实现方案**: 1. **选择机制**: - 实现矩形选择和点选功能。 - 支持多选操作(按住Ctrl点选或拖拽框选)。 - 提供"全选"和"反选"功能。 2. **编辑操作**: - 移动: 拖拽选中项到新位置。 - 删除: 删除选中的项目。 - 复制/粘贴: 复制选中项并在指定位置粘贴。 - 剪切: 结合复制和删除功能。 3. **撤销/重做系统**: - 实现命令模式(`Command Pattern`)，将每个操作封装为命令对象。 - 维护命令历史栈，支持撤销和重做。 - 为复杂操作提供原子性，将多步操作合并为单一可撤销单元。 4. **快捷键支持**: - 实现标准编辑快捷键(Ctrl+C, Ctrl+V, Ctrl+X, Ctrl+Z等)。 - 提供快捷键自定义功能。 - 在状态栏显示当前可用的快捷键提示。 #### ⑧ 地图擦除工具 **功能描述**: 提供橡皮擦工具，可以擦除地图图像的部分区域。 **实现方案**: 1. **擦除功能实现**: - 将地图图像转换为可编辑的`QImage`。 - 实现可调节大小的圆形或方形擦除工具。 - 支持完全擦除(设为透明)或部分擦除(设为特定颜色)。 2. **擦除参数**: - 提供擦除工具大小调节。 - 支持设置擦除强度(透明度)。 - 允许选择擦除模式(完全擦除或替换为背景色)。 3. **交互体验**: - 实时预览擦除效果。 - 支持连续擦除(按住鼠标拖动)。 - 提供擦除历史，可单独撤销擦除操作。 4. **优化**: - 对大地图采用分块处理，减少内存占用。 - 实现擦除操作的缓存，避免频繁重绘整个地图。 - 提供对擦除区域的平滑处理，减少锯齿感。 ### 2.3 高级功能实现方案 #### ① 地图拼接 **功能描述**: 支持将多个地图拼接整合，创建更大范围或更完整的地图。 **实现方案**: 1. **MapStitcher类**: - 设计专门的地图拼接器类，处理拼接逻辑。 - 支持两种拼接模式: - 手动拼接: 用户指定拼接点和重叠区域。 - 辅助拼接: 基于边缘匹配提供拼接建议。 2. **拼接流程**: - 选择待拼接的地图文件。 - 在预览界面中调整地图的相对位置、旋转角度。 - 指定重叠区域的处理方式(平均、最大值、最小值、自定义权重)。 - 执行拼接并生成新地图。 3. **MapStitcherDialog**: - 创建专用对话框，提供交互式拼接界面。 - 显示两张地图的缩略图，支持拖拽调整位置。 - 提供透明度滑块，便于观察重叠区域。 - 显示拼接预览，并允许微调参数。 4. **数据处理**: - 处理不同分辨率地图的拼接，通过重采样使分辨率一致。 - 保留原始地图的元数据，并为拼接地图生成新的元数据。 - 合并两个地图的标注数据，调整坐标以适应新地图。 #### ② 地图校正 **功能描述**: 提供地图校正功能，调整地图的偏移、旋转和缩放，使其与实际环境更加匹配。 **实现方案**: 1. **手动校正**: - 提供交互式工具，允许用户手动调整地图的: - 平移(X和Y方向) - 旋转(围绕中心点或指定点) - 缩放(等比例或非等比例) - 实时预览调整效果。 2. **参考点校正**: - 允许用户在地图上标记参考点。 - 输入参考点的实际物理坐标。 - 系统根据参考点计算最佳变换矩阵。 - 应用变换，校正整个地图。 3. **对齐工具**: - 提供网格对齐功能，辅助校正地图方向。 - 支持对齐到激光扫描数据，提高校正精度。 - 实现吸附功能，帮助对齐墙壁等直线特征。 4. **自动校正(规划)**: - 计划引入基于图像处理的自动校正功能: - 分析地图边缘和特征。 - 检测并校正明显的偏斜。 - 提供自动水平/垂直对齐。 #### ③ 在线建图 **功能描述**: 通过WebSocket实时接收并可视化SLAM系统生成的地图数据，支持建图过程的动态观察。 **实现方案**: 1. **数据接收与处理**: - 扩展WebSocketClient，支持订阅地图构建相关的数据流: - 增量地图更新(OccupancyGrid) - 机器人轨迹(Path) - 当前激光扫描(LaserScan) - 实时解析接收到的数据，更新到相应图层。 2. **可视化功能**: - 动态更新地图图层，显示最新的地图状态。 - 绘制机器人历史轨迹，形成路径线。 - 实时渲染激光扫描点云，与地图叠加显示。 - 提供建图状态指示器，显示当前建图质量和覆盖范围。 3. **控制面板**: - 创建专用的在线建图控制面板: - 连接状态显示。 - 数据流控制(暂停/继续)。 - 显示建图统计信息(覆盖面积、扫描次数等)。 - 提供手动触发地图保存的按钮。 4. **实时保存**: - 定期自动保存当前建图状态。 - 支持手动触发保存操作。 - 维护建图历史版本，允许回退到之前的状态。 #### ④ 离线建图 **功能描述**: 加载并可视化预先记录的数据集，支持离线分析地图构建过程。 **实现方案**: 1. **数据加载**: - 支持加载常见的数据记录格式: - JSON序列(时间戳+数据) - 简化的ROS bag格式 - 自定义的录制格式 - 解析数据集中的时间戳和消息类型。 2. **回放控制**: - 实现数据回放控制面板: - 播放/暂停按钮 - 进度条，显示当前回放位置 - 速度控制(0.5x-10x) - 跳转到特定时间点 - 支持单步模式，逐帧分析数据。 3. **可视化效果**: - 与在线建图类似，提供地图、轨迹和激光数据的可视化。 - 添加时间轴，显示回放进度和关键事件。 - 支持对比模式，同时查看不同时间点的地图状态。 4. **分析工具**: - 提供简单的数据分析功能: - 统计覆盖区域变化。 - 计算机器人移动距离。 - 标记关键点(如闭环检测点)。 - 支持添加标注和注释，记录分析结果。 #### ⑤ 机器人控制 **功能描述**: 从应用程序直接向机器人发送控制指令，实现远程遥控和导航。 **实现方案**: 1. **通信扩展**: - 扩展WebSocketClient，增加消息发送功能: - 速度指令(cmd_vel) - 导航目标(goal) - 控制命令(start/stop/pause) - 实现命令队列和超时重试机制。 2. **遥控操作**: - 创建虚拟摇杆控件，支持: - 前进/后退控制(线速度) - 左转/右转控制(角速度) - 紧急停止按钮 - 支持键盘控制(WASD键)。 - 提供预设速度配置(慢速/中速/快速)。 3. **导航控制**: - 实现导航目标设定工具: - 点击地图设置目标点。 - 拖拽调整目标点方向。 - 支持设置中间路径点。 - 显示规划路径和导航状态。 - 提供导航控制按钮(启动/暂停/取消)。 4. **安全机制**: - 实现命令超时机制，防止失控。 - 提供速度限制设置。 - 添加操作确认对话框，防止误操作。 - 支持自定义安全区域，限制机器人活动范围。 #### ⑥ 视图控制 **功能描述**: 提供灵活的视图操作功能，如缩放、平移、旋转和适配等，提升用户体验。 **实现方案**: 1. **基本视图操作**: - 缩放: 鼠标滚轮或缩放按钮，支持设定缩放级别。 - 平移: 拖拽视图或使用滚动条。 - 旋转: Ctrl+拖拽或旋转按钮，支持90度快速旋转。 - 重置: 一键恢复默认视图。 2. **视图适配**: - 适配全图: 自动调整视图以显示整个地图。 - 适配选区: 聚焦到选中的区域或对象。 - 适配屏幕: 根据当前窗口大小优化显示。 - 保持比例: 在调整大小时维持地图纵横比。 3. **高级视图功能**: - 鸟瞰图: 在角落显示小型地图全局视图，标记当前可视区域。 - 分屏显示: 支持水平或垂直分屏，同时查看不同区域。 - 标记视图: 保存和恢复特定的视图状态(位置、缩放级别)。 - 动画过渡: 在视图切换时使用平滑动画。 4. **界面集成**: - 提供视图控制工具栏，包含常用操作按钮。 - 支持状态栏显示当前缩放比例和坐标。 - 实现右键菜单，提供上下文相关的视图操作。 - 添加键盘快捷键，加速常用视图操作。 ## 3. 工作计划 ### 第一阶段：基础功能完善 - 完成所有基础功能的稳定实现。 - 优化用户界面和交互体验。 - 进行全面的功能测试和性能调优。 ### 第二阶段：高级功能开发 - 实现地图拼接和校正功能。 - 完成在线和离线建图的可视化支持。 - 开发机器人控制界面和通信模块。 ### 第三阶段：系统集成与优化 - 整合所有功能模块，确保协同工作。 - 进行全面的系统测试和Bug修复。 - 编写详细的用户文档和开发指南。 - 准备发布并收集用户反馈。