Robosat workshop guide

rs.md

RS workshop attendee handout

Setup

Installing Docker

Docker is a container platform. It basically lets you use a virtual machine inside your regular machine. A working Robosat installation is provided in a Docker image, so let’s get Docker and that image installed. Starting points:

• For Mac: https://docs.docker.com/docker-for-mac/install/
• For Windows: https://docs.docker.com/docker-for-windows/install/
• For Ubuntu: https://docs.docker.com/install/linux/docker-ce/ubuntu/ (but note: if you are on Ubuntu 19.10 (Eoan), see docker/docs#8891 to get it working)
• Other Linux distros are supported – just search and you should find what you need.

Once you have Docker installed, run:

docker run -it --rm -v $PWD:/data --ipc=host --network=host mapbox/robosat:v1.2.0-cpu --help

After a (lengthy) wait while the image and other necessities download, you should see a usage message. (Specifically, the last line should start subset filter images in a slippy map directory using a csv.) If you see an error instead, raise your hand!

Working with rs inside the containers

rs is the command-line tool that wraps Robosat’s various functions. The easy way to use it is from “inside” the Docker container where it lives. (The subtleties of container management will not be covered in this workshop 😉.) To get a shell within the Docker container, run this:

docker run -it --rm -v $PWD:/data --ipc=host --network=host --entrypoint /bin/bash mapbox/robosat:v1.2.0-cpu

Telling Docker that the entrypoint is the bash shell will connect you to a shell inside the container. (The other flags cover how the container should communicate and share with the “host” or real computer.)

Your prompt will change to something like root@66144f0d0c8a:/usr/src/app#. That terminal is now “inside” the Docker image, where Robosat is preinstalled and should be working perfectly. To test again, type ./rs --help (for example) and see the list of Robosat tools.

Congratulations, you have a working Robosat installation!

Keep in mind that until you disconnect, this terminal will be inside the Docker image. Many commands that work in a shell on your “real” computer will not work in the container, and vice versa! Keep track of which terminal(s) are which (for example, by keeping in-container terminals on one side of your screen) or you could easily run into what seem like highly mysterious bugs.

Using Robosat

Resources

First, here’s some documentation and tutorials that you can refer to or read later. You’re also free to follow one of the tutorials below instead of tonight’s track, if you’re already confident!

• Meet RoboSat 🤖 🛰: https://blog.mapbox.com/meet-robosat-af42530f163f
• The main repo has an excellent readme with helpful illustrations: https://github.com/mapbox/robosat
• RoboSat — robots at the edge of space! https://www.openstreetmap.org/user/daniel-j-h/diary/44145
• RoboSat ❤️ Tanzania: https://www.openstreetmap.org/user/daniel-j-h/diary/44321 – this is roughly what we’ll be following this evening.
• Servus, Bayern: The robots are coming! https://www.openstreetmap.org/user/daniel-j-h/diary/368771
• Data preparation for feature detection with Robosat: https://www.openstreetmap.org/user/maning/diary/44462

This is just a sampling – there are quite a few good Robosat docs out there.

Data prep with RoboSat

We will walk through how you can make slippy map directories for images and labels, which serve as inputs for training a model. In this example, we’ll run a modified version of a tutorial (linked above) to predict buildings in Zanzibar, Tanzania from drone imagery and OpenStreetMap buildings.

(Don’t actually do this part, it’s just for context:) Ordinarily, you would download the latest Tanzania OpenStreetMap data from GeoFabrik as the first step: wget http://download.geofabrik.de/africa/tanzania-latest.osm.pbf. Then you would use a tool like osmium to cut out your specific area of interest from the OSM data: osmium extract --bbox '39.188696444034576,-6.162502256504413,39.19135719537735,-6.160310216613677' tanzania-latest.osm.pbf --output map.osm.pbf`` (for more on setting up osmium`: https://www.openstreetmap.org/user/daniel-j-h/diary/44321#comment42689).

(Do actually do this:) Here, we provide the cropped OSM data to begin with, for the area shown below: https://drive.google.com/file/d/1cMEDCDf5r5BAl-0JaRyUYpwVgS4gBnux/view?usp=sharing.

1. Download the building config file dataset-building.toml into your working directory: https://gist.github.com/yoninachmany/04eef1b30bb42924911cbea3a4601b34
2. Run the RoboSat container: docker run -it --rm -v $PWD:/data --ipc=host --network=host --entrypoint /bin/bash mapbox/robosat:v1.2.0-cpu
3. Check that map.osm.pbf data exists in your Docker setup: ls /data
4. Extract the geometries from OSM: ./rs extract --type building /data/map.osm.pbf /data/buildings.geojson
5. Check the new contents of the data directory again: ls /data. Note that buildings.geojson now has a different name (buildings-<uuid>.geojson), which is used to ensure one GeoJSON file has no more than 100,000 features.
6. Rename the GeoJSON file: mv /data/buildings-*.geojson /data/buildings.geojson
7. Get the (x, y, z) tiles with OSM buildings in them: ./rs cover --zoom 20 /data/buildings.geojson /data/buildings.tiles
8. Check the (x, y, z) pairs that have buildings: cat /data/buildings.tiles
9. Download imagery tiles: ./rs download https://tiles.openaerialmap.org/5d61181eb97490000728b768/0/5d61181eb97490000728b769/{z}/{x}/{y} /data/buildings.tiles /data/images/
10. Create the corresponding building masks, indicating which pixels have buildings: ./rs rasterize --dataset /data/dataset-building.toml --zoom 20 --size 256 /data/buildings.geojson /data/buildings.tiles /data/masks.

The images and masks can train a deep learning model that learns to predict buildings like this: https://maning.github.io/robosat-viz/villaimelda-macarthur.html.

Now to predict (using a model trained on Bavaria):

1. Download https://github.com/mapbox/robosat/releases/download/v1.2.0/bavaria-dop80-release-1.tar.gz (linked from https://github.com/mapbox/robosat/releases/).
2. Unpack it and put bavaria-dop80-checkpoint.pth (not the one with scse in its name) in your Docker data directory.
3. Download the non-GPU model config file from https://gist.github.com/yoninachmany/dc0f8306a65f228a9ccd81936450ca49 and put it in your data directory.
4. Run ./rs predict /data/images /data/probabilities --batch_size 16 --checkpoint /data/bavaria-dop80-checkpoint.pth --overlap 32 --tile_size 512 --workers 2 --model /data/model-unet.toml --dataset /data/dataset-building.toml
5. If it ever completes on your CPU 😉 use ./rs serve to visualize the results. But more likely, just refer to, for example, Maning’s demo: https://maning.github.io/robosat-viz/villaimelda-macarthur.html