Repository files navigation

Inspect, compare and align multiple grid maps in an intuitive & fast GUI

maps is 100% Rust and compiles & runs natively (cross-platform) or as web assembly.

maps can be useful for you if ...

• ...you work on mobile robot SLAM or navigation.
• ...your SLAM or navigation system supports exporting maps as 2D grid map images.
• ...you want to quickly work with the map files, but other tools are either...
  • ...better suited for live data streams (e.g. RViz, Rerun, Foxglove etc)
  • ...not supporting grid coordinates (most image viewers)
  • ...bloated, vendor-locked or unsuited for dev workflows (commercial fleet/layout tools)
• ...you want to display in a shared coordinate system, take measurements etc.
• ...you want to align multiple, potentially very large maps.

The features are best summarized in a video:

At its core,maps is an image viewer that is aware of the metric properties of the grid maps.

• Maps of different resolutions can be displayed in a shared coordinate system with correct scale and position.
• Details of large maps can be quickly inspected using a lens tool without zooming & dragging.
• Several keybindings make it fast to use, e.g.W A S D for moving andQ E for rotating, zoom via scroll or touch gesture, etc.
• Files can be loaded both via GUI and CLI.
• Sessions can be saved and loaded at a later point to continue working, settings are autosaved by default.
• No context menus or other hidden UI.

• Interaction should be fast and responsive, also with very large high resolution maps.
• maps is optimized to allow dragging / rotating images also at high zoom levels in real-time, with efficient resource usage.
• Built withRust usingegui +wgpu.

The supported grid map file format is ROS map_server files, i.e. a pair of image and metadata per map:

• YAML metadata file containing information about the origin, resolution and other properties.
• Image file containing the grid cells.

See theROS documentation for all details.

💡maps does not require a ROS installation, it just uses this data format as convention.

• Click☰ to open the sidebar to manage maps and their visibility.
• Click⚙ to open the sidebar for settings.
• Click the ℹ️ button in the lower right corner to display version & keybindings.

maps provides three different main view modes.

• Aligned:
  • Maps are shown in a metric grid, with their origin at zero.
  • The grid can be dragged and zoomed, grid lines can be shown etc.
• Tiles:
  • Map images are shown in separate tab tiles.
  • The tab tiles can be freely rearranged, for example to view images side by side.
• Stacked: Map images are shown stacked in a scrollable view.

Does exactly what you think: activate the tool and click two points in the aligned grid view to measure their distance.

The lens tool magnifies a region below the mouse cursor with a magnification factor (in Aligned view) or to the original image size (in Tiles / Stacked view). This makes it fast to inspect details of large maps in selected regions without tedious zooming and/or dragging.

• Right-click the mouse on a map to enable/disable the lens (or press L).
• Adjust it...
  • in Aligned view: use the options side bar to set the magnification factor.
  • in Tiles/Stacked view: scroll to adjust the size of the lens.

In the Aligned view, you can add multiple lenses that are looking at a fixed coordinate each. They stay centered at the coordinate that was clicked, even if the main grid is moved.

This can be useful when aligning large maps, where you need to watch different areas in detail to check how well they fit while moving the map.

You can change the pose of a map relative to the global origin in the aligned grid view.

This can be used when you have multiple maps with different origins (e.g. different floors, different origin due to remapping),or to align with a fixed layout, etc.

• Select the map that you want to move in the menu sidebar.
• Enter values or move the map with the keyboard (after enabling "Move Map")
• Poses can be exported to YAML files.
• Optionally, use the tools to make alignment easier, for example:
  • make the texture of the maps transparent/colored using the blend settings
  • add fixed lenses in different areas of a large map
  • adjust the movement step size for the WASD/QE keybindings to the sensitivity you need

👉 maps doesn't touch theorigin of yourmap.yaml file, but writes a separate file.Many ROS tools don't support rotations in the map yaml file, and it's anyway cleaner to separate the alignment pose from the map origin.

Also with transparency enabled, you might want to reorder the map layers.

Changing the draw order is just a matter of using drag & drop in the map list of the menu panel:

You can display maps the same way as you would see them in RViz when using an occupancy grid publisher like map_server together with RViz.

maps simulates this by first applying avalue interpretation followed by a colormap.Just enable value interpretation and choose the options you want.This allows for example to tune the free/occupied thresholds for your application, sincemaps directly shows the effect when the corresponding slider is moved.

💡 If the map metadata YAML already contains the optionalmode parameter, value interpretation is enabled automatically for that map.

💩 The implementation in map_server is not fully consistent with the documentation.This is a "standard" that most likely will stay, but worth to consider that there are slight differences in case you rely on the documentation.Hencemaps defaults to a reimplementation of that map_server quirk, but an implementation that follows the Wiki docs / occupancy grid message definition can be chosen as alternative.

maps has a built-in screenshot feature.

• Pressp to save a picture of the full application.
• Pressshift + p to save a picture containing only the central panel that shows the maps.

You can save your session and reload it later using the menu. maps also asks you if you want to save before quitting or when there are unsaved changes.

Note thatmaps never overwrites your input map files.

⚠️ The files that are written are not self-contained. They just contain the relevant config and point to the map file paths.

The general options are autosaved by default.So for example, if you change the grid color and spacing, you will automatically have the same setting the next time you open maps.

If you don't want this, you can disable this for the active session in the options side bar of the app.All options can be reset with the respective reset buttons in the UI.

If you want to use a custom configuration file path instead of the autosaved default for a session:

maps --config my_custom_config.toml

If the file doesn't exist yet, it opensmaps with default options, creates the file and saves your changes there on exit.You can then reload these settings again anytime you want using the same command.

First, you need toinstall the Rust toolchain if you don't have it already.

Then you can install the latest release fromcrates.io:

cargo install maps

You can also build completely from source if you want.

cargo install --path crates/maps/

You can usetrunk to directly build & serve the wasm version ofmaps from source. Just run:

trunk serve --release --open

and go to:http://localhost:8080/index.html/#dev

Adist/ target folder for a specific URL can be generated with:

trunk build --release --public-url <url>

Start the app with:

maps

Use theLoad Maps button to add your map files.

You can also already pass map file paths from the command line:

maps some/map.yaml some/other/map.yaml

Seemaps --help for all command line options.

Note for Linux users:maps generates a.desktop file when first launched from the terminal. After that, you should be able to launch it also from the launcher of your desktop environment, pin it as favorite etc (you might need to restart the app once). This doesn't apply if you build from source, but you can override this with--write-desktop-file.

CI pipelines run for Linux, macOS, Windows and wasm targets:

There are integration tests in thetests/ directory that are run in pull requests.These include kit tests that check if the UI stays consistent, using the snapshot diff feature ofegui_kittest.

RUST_LOG=maps=info cargo test --profile kittest --verbose -- --show-output

RUST_LOG=maps=info cargo test --profile kittest --verbose --no-default-features -- --show-output

The repository is organized in separate crates for modularity and faster rebuilds during development.The core I/O library can be reused for other applications, see themaps_io_ros crate (docs).maps itself has only a small public library. But in case you are interested:https://docs.rs/maps/latest/maps/

With-log-level debug ortrace, a debug window can be opened through a ⚒️ button in the footer panel.

Apache 2.0

@misc{grupp2025maps,  title={maps: Inspect, compare and align multiple grid maps in an intuitive & fast GUI.},  author={Grupp, Michael},  howpublished={\url{https://github.com/MichaelGrupp/maps}},  year={2025}}