add-tile-map-guides and update for ros 2 (#812)

Co-authored-by: Ben <[email protected]>
swri-robotics · Feb 23, 2024 · 2e0452e · 2e0452e
1 parent a9dbf61
commit 2e0452e
Show file tree

Hide file tree

Showing 20 changed files with 270 additions and 14 deletions.
diff --git a/docs/_config.yml b/docs/_config.yml
@@ -25,7 +25,7 @@ aux_links:
     - "//github.com/swri-robotics/mapviz"
 
 # Footer content appears at the bottom of every page's main content
-footer_content: "Copyright &copy; 2020 Southwest Research Institute. Distributed under the <a href=\"https://github.com/swri-robotics/mapviz/tree/master/LICENSE\">BSD 3-Clause license.</a>"
+footer_content: "Copyright &copy; 2024 Southwest Research Institute. Distributed under the <a href=\"https://github.com/swri-robotics/mapviz/tree/master/LICENSE\">BSD 3-Clause license.</a>"
 
 # Color scheme currently only supports "dark" or nil (default)
 color_scheme: nil

diff --git a/docs/assets/images/add-plugin.png b/docs/assets/images/add-plugin.png
diff --git a/docs/assets/images/aerial-imagery.png b/docs/assets/images/aerial-imagery.png
diff --git a/docs/assets/images/bulk-download.png b/docs/assets/images/bulk-download.png
diff --git a/docs/assets/images/choose-resolution.png b/docs/assets/images/choose-resolution.png
diff --git a/docs/assets/images/configure-wmts-source.png b/docs/assets/images/configure-wmts-source.png
diff --git a/docs/assets/images/draw-geometry.png b/docs/assets/images/draw-geometry.png
diff --git a/docs/assets/images/example-map.png b/docs/assets/images/example-map.png
diff --git a/docs/assets/images/extra-criteria.png b/docs/assets/images/extra-criteria.png
diff --git a/docs/assets/images/item-basket.png b/docs/assets/images/item-basket.png
diff --git a/docs/assets/images/pick-data.png b/docs/assets/images/pick-data.png
diff --git a/docs/assets/images/results.png b/docs/assets/images/results.png
diff --git a/docs/assets/images/satellite-imagery.png b/docs/assets/images/satellite-imagery.png
diff --git a/docs/assets/images/select-geometry.png b/docs/assets/images/select-geometry.png
diff --git a/docs/assets/images/set-frames.png b/docs/assets/images/set-frames.png
diff --git a/docs/guides.md b/docs/guides.md
@@ -0,0 +1,14 @@
+---
+layout: default
+title: Guides
+nav_order: 3
+has_children: true
+---
+
+# Guides
+{: .no_toc }
+
+| Title | Description |
+|:- |:- |
+| [Local tile_map imagery]({{site.basurl}}/mapviz/guides/local_tile_map_imagery) | How to wrangle data to the correct format and direct mapviz's `tile_map` plugin to use it from local storage. |
+| [Geospatial Imagery From USGS Earth Explorer]({{site.basurl}}/mapviz/guides/imagery_usgs_earth_explorer) | An example of how to get imagery that could be used as a source for local `tile_map` imagery. Provided for reference only. |
diff --git a/docs/guides/imagery_usgs_earth_explorer.md b/docs/guides/imagery_usgs_earth_explorer.md
@@ -0,0 +1,81 @@
+---
+title: Imagery USGS Earth Explorer
+parent: Guides
+has_children: false
+---
+
+# Geospatial Imagery from USGS Earth Explorer
+{: .no_toc }
+
+A guide to getting satellite imagery from USGS's [Earth Explorer](https://earthexplorer.usgs.gov/).
+
+### Create an account
+
+First step is to create an account for Earth Explorer. It is free.
+
+## Mark an area of interest
+
+### Choose method to describe geometry
+
+Polygon is recommended. Just click on the map until you have the shape you want.
+
+![Select geometry]({{ site.baseurl | append: '/assets/images/' }}select-geometry.png)
+
+## Draw geometry
+
+Zoom to area and draw geometry on the map as needed. See coordinates populate on left hand side.
+
+![Draw geometry]({{ site.baseurl | append: '/assets/images/' }}draw-geometry.png)
+
+## Extra search criteria (optional)
+
+If you need a certain date it can be supplied. Generally I leave this blank and choose the latest.
+Cloud cover can be good if using raw data products, like Landsat, that have not had clouds filtered out yet. 
+Once done click on the Data Sets button below:
+
+## Choose data sets
+
+### Aerial imagery
+
+Imagery collected from aerial sources (as opposed to space). Usually higher resolution. NAIP is the best option here (usually pretty recent and decent resolution). Limited to the (continental?) United States.
+
+![Aerial imagery]({{ site.baseurl | append: '/assets/images/' }}aerial-imagery.png)
+
+### Satellite imagery
+
+
+Collected from satellites in space. Harder to get high resolution data from satellites. Usually much more up to date (within ~1 week usually). May have cloud cover, so be sure to check the preview later.
+
+![Satellite imagery]({{ site.baseurl | append: '/assets/images/' }}satellite-imagery.png)
+
+## Move to results
+
+Just click the results button at the bottom.
+
+![Results]({{ site.baseurl | append: '/assets/images/' }}results.png)
+
+## Pick data from results
+
+Use the foot and the preview icon to preview the data on the map.
+If selecting multiple, prefer using data from one acquisition (check date).
+After choosing desired data, add each to Bulk Download as shown below.
+
+![Pick data]({{ site.baseurl | append: '/assets/images/' }}pick-data.png)
+
+## View item basket
+
+At the bottom of the screen.
+
+![Item basket]({{ site.baseurl | append: '/assets/images/' }}item-basket.png)
+
+## Continue to start order (Bulk Download)
+
+![Bulk Download]({{ site.baseurl | append: '/assets/images/' }}bulk-download.png)
+
+### Choose resolution for each
+
+![Choose resolution]({{ site.baseurl | append: '/assets/images/' }}choose-resolution.png)
+
+## Done
+
+You may need to unzip the data, but the images provided can be opened and used by a variety of programs.
diff --git a/docs/guides/local_tile_map_imagery.md b/docs/guides/local_tile_map_imagery.md
@@ -0,0 +1,155 @@
+---
+title: Local tile_map imagery
+parent: Guides
+has_children: false
+---
+
+# Local `tile_map` imagery
+{: .no_toc }
+
+
+## Pre-requisites
+
+First, ensure mapviz and its tile_map plugin are installed
+
+```bash
+$ sudo apt install ros-$ROS_DISTRO-mapviz ros-$ROS_DISTRO-tile-map
+```
+
+Then, install [GDAL](https://gdal.org/index.html). GDAL is a geospatial translator library that can handle import/exporting and transforming various geospatial data formats.
+
+```bash
+$ sudo apt install gdal-bin
+```
+
+## Get the data
+
+You need a source of geospatial raster data! Specifically a raster format that GDAL [can work with](https://gdal.org/drivers/raster/index.html).
+One example guide is provided [here]({{site.basurl}}/mapviz/guides/imagery_usgs_earth_explorer) for reference only.
+
+## Geo-wrangle the data
+
+Once you have the data it is time to format it to XYZ WMTS tiles (the format mapviz's `tile_map` plugin expects).
+Thankfully, GDAL makes this simpler than it _could_ be.
+
+### Single File
+
+Fairly easy and simple. Using `test.tif`  as an example file with geospatial reference:
+```bash
+# could be used to see all sorts of metadata for test.tif
+$ gdalinfo test.tif
+
+# the command we actually want to see what sort of bands we're dealing with
+$ gdalinfo test.tif | grep Band
+Band 1 Block=2672x392 Type=Byte, ColorInterp=Red
+Band 2 Block=2672x392 Type=Byte, ColorInterp=Green
+Band 3 Block=2672x392 Type=Byte, ColorInterp=Blue
+Band 4 Block=2672x392 Type=Byte, ColorInterp=Alpha # We don't want the alpha, so note this band to skip
+
+# Remove the alpha by selecting all other bands with `-b #`
+$ gdal_translate -b 1 -b 2 -b 3 test.tif test_no_alpha.tif
+
+# Convert to WMTS tiles in the proper directory structure of `<output_dir>/<level>/<x>/<y>.png`
+#     -z manually sets desired zoom levels. If left blank it will only output tiles in levels where the data would be visible.
+#     --xyz Use OGC WMTS standard format for output. This is the format that matches what mapviz expects.
+# More info: https://gdal.org/programs/gdal2tiles.html
+$ gdal2tiles.py --xyz test_no_alpha.tif
+
+# Check that the output makes sense with gdal's generated preview using a browser, like chrome.
+#     Check the "Layers" box in the top left
+$ google-chrome test_no_alpha/leaflet.html
+```
+
+### Multiple Files
+
+Similar steps to above, just need to build a virtual dataset first to work with. First, create a text file containing the list of input files that looks like the following:
+
+```bash
+$ cat input.txt
+test1.tif
+test2.tif
+test3.tif
+
+
+# Could be created with various bash tricks (here choosing all GeoTiffs in current dir):
+$ ls *.tif > input.txt
+```
+
+
+Now, use GDAL's virtual format to treat many files like one:
+
+```bash
+# Use input.txt from above
+$ gdalbuildvrt --input_file_list input.txt test.vrt
+
+# Same steps as for single file now:
+$ gdal_translate -b 1 -b 2 -b 3 test.vrt test_no_alpha.vrt
+
+$ gdal2tiles.py --xyz test_no_alpha.vrt
+```
+
+## Add custom `tile_map` source
+
+
+### Make sure you have an origin set
+
+Without a local xy origin set, mapviz will be unable to convert between ROS's TF frames and its geospatial reference system (wgs84).
+
+```bash
+# Making an origin at SwRI's campus
+$ ros2 topic pub /local_xy_origin geometry_msgs/msg/PoseStamped "header:
+  stamp:
+    sec: 0
+    nanosec: 0
+  frame_id: 'map'
+pose:
+  position:
+    x: -98.601085
+    y: 29.441902
+    z: 0.0
+  orientation:
+    x: 0.0
+    y: 0.0
+    z: 0.0
+    w: 1.0"
+```
+
+### Setup mapviz
+
+In a new terminal launch mapviz:
+
+```bash
+$ ros2 launch mapviz mapviz.launch.py
+```
+
+### Set Frames:
+
+Choose the same fixed frame as the `frame_id` of the published origin.
+Or at least a frame that has a valid transform to that frame through the TF tree.
+
+![Set frames]({{ site.baseurl | append: '/assets/images/' }}set-frames.png)
+
+### Add `tile_map` plugin
+
+![Add plugin]({{ site.baseurl | append: '/assets/images/' }}add-plugin.png)
+
+### Configure new Custom WMTS Source
+
+Replace the Base URL with your own path: `file:///some/path/to/created/tile/map/dir/{level}/{x}/{y}.png`
+
+Set the max zoom to the max zoom specified in previous steps.
+Save the WMTS source to your mapviz current config.
+**You may need to use the dropdown menu to switch to the saved config to trigger mapviz to reload.**
+
+![Add plugin]({{ site.baseurl | append: '/assets/images/' }}configure-wmts-source.png)
+
+### Caveats
+
+- Note that this will **_not_** persist between multiple mapviz configs.
+- If the tile map directory moves, you will need to update the URL to point to the new location.
+	- If you wish to have this point to a path relative to a ROS package or any changing path, you will need a script to edit your mapviz config before launching it.
+- Crashes have been noticed in cases where you have a large map with certain levels not fully populated.
+
+## Enjoy local maps
+
+![Example maps]({{ site.baseurl | append: '/assets/images/' }}example-map.png)
diff --git a/docs/guides/local_tile_map_imagery.mg b/docs/guides/local_tile_map_imagery.mg
diff --git a/docs/index.md b/docs/index.md
@@ -30,34 +30,40 @@ $ sudo apt-get install ros-$ROS_DISTRO-mapviz \
 
 ### Building From Source
 
-These directions assume you have already set up a `catkin` workspace. If not, see [this tutorial](http://wiki.ros.org/catkin/Tutorials/create_a_workspace) on the ROS Wiki to set one up.
+These directions assume you have already set up a `colcon` workspace. If not, see [this tutorial](https://docs.ros.org/en/rolling/Tutorials/Beginner-Client-Libraries/Creating-A-Workspace/Creating-A-Workspace.html) on the ROS 2 Wiki to set one up.
 
 1.  Check out the source
-    *   Using `wstool`
-        If you're using `wstool`, add this repository to your `wstool` workspace:
-
-        ```
-        $ wstool set mapviz --git https://github.com/swri-robotics/mapviz.git
-        $ wstool update mapviz
+    *   Using `vcstool`
+        If you're using `vcstool`, add this repository to your `vcstool` workspace:
+
+        ```bash
+        $ cat mapviz.repos
+        # example repos file to import
+        repositories:
+          vcstool:
+            type: git
+            url: https://github.com/swri-robotics/mapviz.git
+            version: ros2-devel
+        $ vcs import < mapviz.repos
         ```
 
     *   Using `git`
-        If you're not using wstool, you can check out the repository directly with `git`:
+        If you're not using vcstool, you can check out the repository directly with `git`:
 
-        ```
+        ```bash
         $ git clone https://github.com/swri-robotics/mapviz.git
         ```
 
 2.  Install dependencies
 
-    Install all of the dependencies using `rosdep` by running the following command from the root of your `catkin` workspace:
+    Install all of the dependencies using `rosdep` by running the following command from the root of your `colcon` workspace:
 
-    ```
+    ```bash
     $ rosdep install --from-paths src --ignore-src
     ```
 
 3.  Build the workspace:
 
-    ```
-    $ catkin_make
+    ```bash
+    $ colcon build
     ```