From dba114ec96fbc7b7652f50510b73cae68eb7fd0c Mon Sep 17 00:00:00 2001
From: Michael Grupp <michael.grupp@tum.de>
Date: Fri, 27 Dec 2024 15:10:17 +0100
Subject: [PATCH] Add README.md

---
 Cargo.toml |   3 +-
 README.md  | 105 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 107 insertions(+), 1 deletion(-)
 create mode 100644 README.md

diff --git a/Cargo.toml b/Cargo.toml
index 588617b..9e4a51f 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,10 +1,11 @@
 [package]
 name = "maps"
-description = "Inspect, compare and align multiple grid maps in an intuitive GUI"
+description = "Inspect, compare and align multiple grid maps in an intuitive & fast GUI"
 authors = ["Michael Grupp"]
 license = "Apache-2.0"
 version = "0.1.0"
 edition = "2021"
+readme = "README.md"
 
 [dependencies]
 clap = { version = "4.5.23", features = ["derive"] }
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..33c1285
--- /dev/null
+++ b/README.md
@@ -0,0 +1,105 @@
+# maps
+
+**Inspect, compare and align multiple grid maps in an intuitive & fast GUI**
+
+## Audience
+
+`maps` can be useful for you if ...
+
+* ...you work with robots using SLAM.
+* ...your SLAM system supports exporting maps as grid maps.
+* ...you want to view the maps, but other viewers are...
+  * ...tedious to spin up (e.g. ROS nodes/topics + RViz).
+  * ...not supporting grid coordinates (any pure image viewer).
+
+
+## Goals
+
+At its core, `maps` is an image viewer that is aware of the metric properties of the grid maps.
+
+### Intuitive
+  * 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.
+  * Files can be loaded both via GUI and CLI.
+### Fast
+  * Interaction should be fast and responsive, also with very large high resolution maps.
+  * Built with [Rust](https://www.rust-lang.org/) using [egui](https://github.com/emilk/egui) + [wgpu](https://github.com/gfx-rs/wgpu).
+
+> ⚠️ `maps` is ready to use, but also under active development. Some features may be added or changed in upcoming versions.
+
+## Input
+
+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 the [ROS documentation](http://wiki.ros.org/map_server#Map_format) for all details.
+
+## User Interface
+
+### Views
+
+`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.
+
+### Lens
+
+The lens tool magnifies a region below the mouse cursor to the original image size. 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).
+* Scroll to adjust the size of the lens.
+
+### Menu & Settings
+
+* Click `☰` to open the sidebar to manage maps and their visibility.
+* Click `⚙` to open the sidebar for settings.
+
+## Install
+
+First, you need to [install the Rust toolchain](https://www.rust-lang.org/tools/install).
+
+Then you can install the latest release from [crates.io](https://crates.io/):
+> ⚠️ TODO
+
+---
+
+You can also build completely from source if you want.
+<details>
+<summary>Details</summary>
+
+Clone this repository, then:
+```bash
+cargo install --path maps/
+```
+
+(or `cargo build --release` if you just want to build)
+
+</details>
+
+## Run
+
+Start the app with:
+
+```bash
+maps
+```
+Use the `Load Maps` button to add your map files.
+
+
+You can also already pass map file paths from the command line:
+
+```bash
+maps some/map.yaml some/other/map.yaml
+```
+
+## License
+
+Apache 2.0