RoboSat: a Mapbox pipeline that turns tiles and OSM geometries into segmentation masks and GeoJSON polygons

The gap RoboSat fills between raw imagery and map-ready polygons

Most segmentation code stops at a probability mask. RoboSat's README frames the project as an end-to-end pipeline whose output is not a mask but simplified GeoJSON features. The repository describes three groups of tools: data preparation, training and modeling, and post-processing. The post-processing group is the part that distinguishes it from a plain training script, because it is responsible for denoising, simplifying geometries, converting pixels in Slippy Map tiles into world coordinates, and handling tile boundaries. That last item is the one that quietly breaks naive implementations: a building that straddles two tiles appears as two partial polygons unless something merges them. RoboSat ships a merge tool and a dedupe tool for exactly this class of problem. The intended user is someone with aerial or satellite imagery who wants vector features out, not someone who wants a segmentation benchmark score. The README lists buildings, parking lots, roads, cars, water and clouds as examples, and notes that features can be anything visually distinguishable. It also points to OpenStreetMap diary posts as the record of what the authors ran, including work on drone imagery in Tanzania and aerial imagery for Bavaria, Germany.

Everything is a tile: the Slippy Map abstraction and why it constrains you

RoboSat works with the Slippy Map tile format, and the README gives the reason directly: it abstracts away geo-referenced imagery behind tiles of the same size. That single decision propagates through the whole pipeline. Data preparation produces tiles plus masks. Training consumes fixed-size tiles. Prediction emits per-tile masks. Post-processing converts tile pixels back into world coordinates. The benefit is that imagery from different sources looks identical to the model as long as it is tiled the same way. The cost is that anything that does not tile cleanly has to be forced into the format first, and the README's extending section exists precisely because users arrive with imagery and masks that do not match the defaults. A dataset in RoboSat's sense is imagery plus corresponding masks for the features you want. The README states that the project provides tools to download aerial imagery from the Mapbox Maps API and to generate masks from OpenStreetMap geometries, but adds that it is not bound to these sources. That sentence is the honest description of the architecture: Mapbox and OSM are the paved road, and the extending section is the dirt road for everyone else.

The rs subcommands and the data flow they encode

All tools are invoked through a single entry point, documented as ./rs <tool> <args>, with per-tool help at ./rs <tool> --help. The ordering of the subcommands in the README is itself the data flow. rs extract walks OpenStreetMap .osm.pbf base map files, such as those from Geofabrik, and gathers feature geometries, producing a GeoJSON file. rs cover generates a list of tiles that cover those GeoJSON features, so you only download imagery where there is something to learn from. rs download fetches the imagery for those tiles, and rs rasterize turns the vector geometries into raster masks aligned with the tiles. That is the dataset. rs train fits a fully convolutional segmentation model against a model TOML and a dataset TOML, and rs export writes a checkpoint. rs predict runs the trained model over tiles, and rs mask converts the network output into something the geometry stage can consume. rs features converts masks into GeoJSON, then rs merge and rs dedupe clean up the result across tile seams. The README also lists rs serve, rs weights, rs compare and rs subset, which are auxiliary rather than part of the main chain. Because every stage reads and writes files, you can inspect and replace any single step without rewriting the others.

Getting it running: Docker first, configs second

The README leads with pre-built Docker images on Docker Hub under mapbox/robosat, tagged for CPU and GPU. The CPU example is docker run -it --rm -v $PWD:/data --ipc=host --network=host mapbox/robosat:latest-cpu --help. The GPU example adds --runtime=nvidia and runs train with three arguments: docker run --runtime=nvidia -it --rm -v $PWD:/data --ipc=host --network=host mapbox/robosat:latest-gpu train --model /data/model.toml --dataset /data/dataset.toml --workers 4. The README explains each flag: --runtime=nvidia enables the nvidia-docker runtime for host GPU access, --ipc=host is required for shared memory communication between workers, --network=host is required for network communication in the download tool, and -v $PWD:/data mounts the current directory at /data inside the container. Note that the train example passes --workers 4, and that the README recommends potentially multiple GPUs, citing AWS p2/p3 instances and GTX 1080 TI GPUs as what the authors ran. For installation from source, the README points to the Dockerfiles in the docker/ directory and states that dependencies must be installed. Configuration lives in the configs directory, and the README is explicit that you must adapt it: set your tile resolution, for example 256x256 pixels, and adapt for your deployment, for example using CUDA and setting batch sizes. There is no default that will work on your data unchanged.

The maintenance status is the headline, not a footnote

The README opens with a notice that RoboSat is neither maintained nor actively developed by Mapbox, and links to issue 184 for context. It names the two main developers and states they are no longer with Mapbox. The last release listed is v1.2.0 from June 2019, with v1.1.0 the release before it in September 2018. The repository is not archived. Those facts have to be read together. Not archived means the code is still there and issues can still be filed. Unmaintained means nobody is obligated to answer, and the dependency surface of a Python 3 deep learning project from 2019 will drift. The Docker images are the mitigating factor: if mapbox/robosat:latest-cpu and :latest-gpu remain pullable, you can run the pipeline without resolving a Python environment at all. If they are removed, the README's fallback is building from the Dockerfiles in docker/, which means pinning the dependencies yourself. Anyone evaluating this for production should treat the image availability as the real support boundary, because that is the only distribution channel the documentation promises.

Where RoboSat is the wrong tool

RoboSat assumes your problem is tiled and geographic. If your imagery is a handful of large orthomosaics that you do not want to cut into Slippy Map tiles, you will spend more time fighting the tile abstraction than training a model, and the post-processing stage that converts tile pixels to world coordinates has nothing to do. The README's extending section acknowledges this by describing how to bring your own imagery and masks, but that is a description of work you do, not a feature that removes the work. The second constraint is the post-processing premise. RoboSat's value comes from producing simplified GeoJSON polygons, which is what you want for map data and not what you want if your downstream consumer needs a per-pixel probability map or a dense class raster. The mask and predict tools give you the raster stage, but the merge and dedupe logic exists for vector output and adds nothing if you never cross that boundary. Third, the training path is GPU-oriented: the README recommends potentially multiple GPUs and cites specific hardware, and while it states you can run prediction on GPUs or CPUs after training, it says nothing about training being practical on CPU. If you have no GPU, the pipeline still runs, but the part you most need is the part the documentation steers away from.

Alternatives and the actual difference in approach

The most direct comparison is to a general segmentation framework such as a torchvision or segmentation-models style training loop paired with your own tiling and vectorization code. The difference is not model quality, which the README does not claim, but scope. A general framework gives you a model, a dataloader and a training loop, and stops. You then write the tiling scheme, the mask rasterization, the tile-boundary merge and the coordinate conversion yourself. RoboSat gives you all of those as named subcommands with a shared tile convention, at the cost of accepting its conventions and its 2019 dependency set. The second comparison is to treating OpenStreetMap itself as the answer. If your target features are already mapped in OSM, rs extract gives you the geometries directly and you never need a model. RoboSat is for the case where the imagery shows something OSM does not record, or records incompletely, and you want to propose features rather than read them. That framing is consistent with the README's own diary posts, which describe extracting building footprints from drone imagery in Tanzania, where the OSM baseline is thin. The third comparison is to a hosted imagery analysis API: it removes the GPU requirement and the dependency drift, but it also removes the ability to run rs merge and rs dedupe against your own tile boundaries, which is the part of this pipeline that is hardest to reproduce.

Licence, upgrade cost and what to check before you commit

RoboSat is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is a permissive licence and it does not obligate you to publish your modifications. It says nothing about the licence of the imagery you feed it, the OpenStreetMap data you extract from, or the Mapbox Maps API terms under which the download tool operates, and those are separate questions the README does not answer. The upgrade cost is the more practical concern. With v1.2.0 from June 2019 as the most recent release and no maintainer, there is no upgrade path to plan for; you are either on the released version or you are maintaining a fork. That has a concrete consequence for the extending section: if you add support for a feature in pre-processing and post-processing, as the README describes, you own that code indefinitely. The cheapest way to reduce that exposure is to keep the pipeline at the file boundaries, since each rs stage reads and writes files and can be replaced individually. If the model training stage is the part that ages badly, you can swap in a current training loop and keep rs cover, rs download, rs rasterize, rs features, rs merge and rs dedupe as they are, provided your new model emits masks in the same tile layout.

Editorial conclusion

Adopt RoboSat if you already have geo-referenced imagery in Slippy Map tiles and want a working reference for the full chain from OSM geometries to simplified GeoJSON polygons, and you accept that no one at Mapbox maintains it. Do not adopt it if you need a supported dependency, a maintained training loop, or a pipeline that does not assume tile-shaped inputs. Before committing, check the issue the README links for the maintenance status, confirm the pre-built mapbox/robosat image tags you intend to use still exist on Docker Hub, and read the configs directory to see whether the dataset and model TOML files match your tile resolution and batch size.

Official sources

1. Issues
2. License: MIT
3. mapbox/robosat on GitHub
4. README
5. Releases