Content
# RViz Map Image MCP
FastMCP tools for converting a live ROS 2 occupancy map into a shareable image.
The server subscribes to the same `nav_msgs/msg/OccupancyGrid` data that RViz
uses for a 2D map display, usually `/map`, then returns PNG/JPEG images,
base64 payloads, metadata, corner goals, and optional Nav2 navigation commands.
This is useful when an AI agent needs to inspect the robot's current map,
send the map image to a user, convert between map coordinates and pixels, or
navigate to coarse locations such as the map corners.
## Features
- Render a live ROS 2 occupancy grid as an RViz-style map image.
- Return images as base64, data URIs, or saved PNG/JPEG files.
- Include map metadata: resolution, origin, image size, occupancy statistics,
and pixel-to-world conventions.
- Mark the robot pose and safe corner goals on the rendered image.
- Convert map-frame world coordinates to rendered-image pixels and back.
- Find safe free-space goals near `top_left`, `top_right`, `bottom_left`, and
`bottom_right`.
- Validate candidate navigation goals against the map and optional costmap.
- Send Nav2 `NavigateToPose` goals to coordinates or named corners.
## Files
```text
occupancy_map_to_image.py One-shot CLI map capture script
map_image_mcp_server.py FastMCP server with map image and navigation tools
mcp_config_example.json Example MCP client configuration
requirements.txt Python dependencies outside the ROS install
```
## Requirements
- ROS 2 with Python support, tested with Humble-era APIs.
- A live `nav_msgs/msg/OccupancyGrid` topic such as `/map`.
- For navigation tools: Nav2 `nav2_msgs/action/NavigateToPose`.
- Python packages:
```bash
python3 -m pip install --user -r requirements.txt
```
ROS message packages such as `rclpy`, `nav_msgs`, `geometry_msgs`,
`nav2_msgs`, and `tf2_ros` should come from your ROS 2 installation, not pip.
## One-Shot Map Capture
```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
```
Useful options:
```text
--return-base64 include base64 image data in the JSON output
--scale 2 render at 2 pixels per map cell before max-side limiting
--max-image-side 1600 cap the longest rendered side
--no-flip-y keep raw occupancy-grid row order
--use-sim-time use ROS simulated time
```
The command prints JSON with the saved image path, map metadata, and optionally
base64 image data.
## MCP Server
Run over stdio:
```bash
cd /home/bharat/Desktop/rviz_map_image_mcp
python3 map_image_mcp_server.py --transport stdio
```
Run over streamable 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
```
Default ROS topics and frames:
```text
/map
/global_costmap/costmap
/odom
/navigate_to_pose
map
base_footprint
```
Override them with CLI flags or the `configure_topics` MCP tool.
## MCP Client Config
Stdio example:
```json
{
"mcpServers": {
"rviz-map-image-stdio": {
"name": "RViz Map Image MCP",
"transport": "stdio",
"command": "python3",
"args": [
"/home/bharat/Desktop/rviz_map_image_mcp/map_image_mcp_server.py",
"--transport",
"stdio"
]
}
}
}
```
HTTP example:
```json
{
"mcpServers": {
"rviz-map-image-http": {
"name": "RViz Map Image MCP HTTP",
"transport": "http",
"url": "http://127.0.0.1:8767/mcp"
}
}
}
```
## MCP Tools
```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
```
### Image Tools
`get_map_image` returns an image and metadata. Important options:
```text
return_base64=true return image_base64 and mime_type
save=true save a copy to disk
save_path=... choose a specific output path
draw_robot=true overlay the current robot pose when TF/odom is available
draw_corners=true overlay safe corner goals
draw_legend=true overlay occupancy legend
scale=1.0
max_image_side=1600
```
`save_map_image` is a convenience wrapper that saves by default under:
```text
/home/bharat/Desktop/rviz_map_captures
```
### Coordinate Tools
With the default `flip_y=true`, image right is `+map_x` and image up is
`+map_y`, matching the normal top-down RViz view. The server returns the exact
image dimensions and transform metadata with each rendered image.
Use:
```text
world_to_pixel
pixel_to_world
```
to connect visual annotations back to map-frame coordinates.
### Navigation Tools
`get_map_corners` returns safe free-space goals near:
```text
top_left
top_right
bottom_left
bottom_right
```
`navigate_to_corner` accepts those IDs, plus:
```text
nearest
farthest
```
`navigate_to_coordinate` sends a Nav2 `NavigateToPose` action after optional
goal validation.
## Notes
This server reads the ROS occupancy grid, not RViz internals. RViz and this
tool should show the same map when they subscribe to the same `/map` topic.
The companion UGV workspace package `src/ugv_main/ugv_navigation_mcp` provides
more geometry-focused navigation tools, including Hough-style room-corner
detection. This project is focused on visual map access and lightweight
map-corner interaction for AI agents.
