rviz-map-image-mcp

# RViz 地图图像 MCP 用于将实时的 ROS 2 占用率地图转换为可共享图像的 FastMCP 工具。 服务器订阅与 RViz 用于 2D 地图显示的相同的 `nav_msgs/msg/OccupancyGrid` 数据，通常为 `/map`，然后返回 PNG/JPEG 图像、 base64 有效载荷、元数据、角目标和可选的 Nav2 导航命令。 这在 AI 代理需要检查机器人的当前地图、 将地图图像发送给用户、在地图坐标和像素之间转换或 导航到粗略位置（例如地图角）时非常有用。 ## 功能特点 - 将实时的 ROS 2 占用率网格渲染为 RViz 风格的地图图像。 - 以 base64、数据 URI 或保存的 PNG/JPEG 文件形式返回图像。 - 包括地图元数据：分辨率、原点、图像大小、占用率统计数据、 和像素到世界的转换规则。 - 在渲染的图像上标记机器人姿势和安全角目标。 - 在地图帧世界坐标和渲染图像像素之间转换。 - 在 `top_left`、`top_right`、`bottom_left` 和 `bottom_right` 附近查找安全自由空间目标。 - 根据地图和可选的代价地图验证候选导航目标。 - 向坐标或命名角发送 Nav2 `NavigateToPose` 目标。 ## 文件 ```text occupancy_map_to_image.py 单次命令行地图捕获脚本 map_image_mcp_server.py 具有地图图像和导航工具的 FastMCP 服务器 mcp_config_example.json 示例 MCP 客户端配置 requirements.txt ROS 安装之外的 Python 依赖项 ``` ## 要求 - 带有 Python 支持的 ROS 2，已使用 Humble 时代的 API 进行测试。 - 一个实时的 `nav_msgs/msg/OccupancyGrid` 主题，例如 `/map`。 - 用于导航工具：Nav2 `nav2_msgs/action/NavigateToPose`。 - Python 包： ```bash python3 -m pip install --user -r requirements.txt ``` ROS 消息包，例如 `rclpy`、`nav_msgs`、`geometry_msgs`、 `nav2_msgs` 和 `tf2_ros`，应来自您的 ROS 2 安装，而不是 pip。 ## 单次地图捕获 ```bash cd /home/bharat/Desktop/rviz_map_image_mcp python3 occupancy_map_to_image.py \ --map-topic /map \ --output /home/bharat/Desktop/rviz_map_captures/latest_map.png \ --draw-corners \ --draw-legend ``` 有用选项： ```text --return-base64 在 JSON 输出中包含 base64 图像数据 --scale 2 在最大边限制之前以 2 像素每地图单元格渲染 --max-image-side 1600 将最长渲染边限制为 1600 --no-flip-y 保持原始占用网格行顺序 --use-sim-time 使用 ROS 模拟时间 ``` 命令打印 JSON，包含保存的图像路径、地图元数据和可选的 base64 图像数据。 ## MCP 服务器 通过 stdio 运行： ```bash cd /home/bharat/Desktop/rviz_map_image_mcp python3 map_image_mcp_server.py --transport stdio ``` 通过可流式 HTTP 运行： ```bash cd /home/bharat/Desktop/rviz_map_image_mcp python3 map_image_mcp_server.py \ --transport streamable-http \ --host 127.0.0.1 \ --port 8767 ``` 默认 ROS 主题和帧： ```text /map /global_costmap/costmap /odom /navigate_to_pose map base_footprint ``` 使用命令行标志或 `configure_topics` MCP 工具覆盖它们。 ## MCP 客户端配置 stdio 示例： ```json { "mcpServers": { "rviz-map-image-stdio": { "name": "RViz 地图图像 MCP", "transport": "stdio", "command": "python3", "args": [ "/home/bharat/Desktop/rviz_map_image_mcp/map_image_mcp_server.py", "--transport", "stdio" ] } } } ``` HTTP 示例： ```json { "mcpServers": { "rviz-map-image-http": { "name": "RViz 地图图像 MCP HTTP", "transport": "http", "url": "http://127.0.0.1:8767/mcp" } } } ``` ## MCP 工具 ```text server_status list_map_topics configure_topics summarize_map get_map_image save_map_image get_map_corners world_to_pixel pixel_to_world get_robot_pose validate_goal navigate_to_coordinate navigate_to_corner ``` ### 图像工具 `get_map_image` 返回图像和元数据。重要选项： ```text return_base64=true 返回 image_base64 和 mime_type save=true 保存一份副本到磁盘 save_path=... 选择特定的输出路径 draw_robot=true 当 TF/odom 可用时，叠加当前机器人姿势 draw_corners=true 叠加安全角目标 draw_legend=true 叠加占用率图例 scale=1.0 max_image_side=1600 ``` `save_map_image` 是一个便捷的包装器，默认情况下保存在： ```text /home/bharat/Desktop/rviz_map_captures ``` ### 坐标工具 使用默认 `flip_y=true`，图像右侧为 `+map_x`，图像上侧为 `+map_y`，匹配正常的自上而下 RViz 视图。服务器返回精确的 图像尺寸和变换元数据与每个渲染图像。 使用： ```text world_to_pixel pixel_to_world ``` 将视觉注释连接到地图帧坐标。 ### 导航工具 `get_map_corners` 返回附近的安全自由空间目标： ```text top_left top_right bottom_left bottom_right ``` `navigate_to_corner` 接受这些 ID，加上： ```text nearest farthest ``` `navigate_to_coordinate` 在可选目标验证后发送 Nav2 `NavigateToPose` 操作。 ## 备注 此服务器读取 ROS 占用网格，而不是 RViz 内部数据。RViz 和此 工具在订阅相同的 `/map` 主题时应显示相同的地图。 配套 UGV 工作区包 `src/ugv_main/ugv_navigation_mcp` 提供了 更多以几何为中心的导航工具，包括 Hough 风格的房间角检测。 该项目专注于 AI 代理的视觉地图访问和轻量级 地图角交互。