# mapbox/robosat: a semantic segmentation pipeline for aerial imagery, and what its archived status means

> RoboSat is an MIT-licensed Python 3 pipeline that turns Slippy Map tiles and OpenStreetMap geometry into trained segmentation models and cleaned GeoJSON features. It is a full pipeline rather than a library, and Mapbox states it is no longer maintained.

**mapbox/robosat** —  Semantic segmentation on aerial and satellite imagery. Extracts features such as: buildings, parking lots, roads, water, clouds

- Repository: https://github.com/mapbox/robosat
- Stars: 2,065 · Forks: 384
- Language: Python
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/mapbox-robosat

## What RoboSat extracts, and who the pipeline is built for

RoboSat describes itself as a "generic ecosystem for feature extraction from aerial and satellite imagery". The features are not fixed by the code: the README says they can be anything visually distinguishable, and names buildings, parking lots, roads and cars as examples. The repository topics add water and clouds to that list. The intended user is someone who has imagery and wants vector geometry out of it, not someone who wants a pretrained detector for a standard class list.

The design assumes a specific kind of user. Data preparation downloads imagery from the Mapbox Maps API and builds masks from OpenStreetMap geometries, but the README is explicit that the tools are "not bound to these sources". Training is expected to be GPU work: the README recommends potentially multiple GPUs and says the authors ran it on AWS p2/p3 instances and GTX 1080 TI cards. Prediction can run on GPUs or CPUs. That split matters, because the expensive part is training, and the part you deploy is cheaper.

RoboSat is not a hosted service and has no homepage. It is a command line pipeline you run yourself, distributed as source and as Docker images. If you want an API endpoint that returns building polygons for a coordinate, this is the wrong layer: you would have to build that on top of the `rs serve` tool.

## How the tile abstraction and the rs sub-commands fit together

The central design decision is the tile format. RoboSat works with the Slippy Map tile scheme, which the README says abstracts away geo-referenced imagery behind tiles of the same size. That single choice makes the rest of the pipeline uniform: imagery from different providers becomes interchangeable as long as it can be addressed as (x, y, z) tiles, and the model always sees fixed-size inputs.

The tools fall into three groups. Data preparation covers `rs extract`, which walks OpenStreetMap `.osm.pbf` base map files such as those from Geofabrik and gathers feature geometries, and `rs cover`, which generates the list of tiles covering those GeoJSON features. Training and modeling covers `rs train`, which fits fully convolutional nets for segmentation and writes checkpoints. Post-processing covers the tools that clean the model output: denoising, simplifying geometries, converting pixels in tiles to world coordinates as GeoJSON features, and handling tile boundaries.

The tile boundary handling is the part worth noticing. A segmentation model predicts per-pixel classes inside one tile, but a building that straddles two tiles is one object in the world. The post-processing stage exists to reconcile that, and the README lists `rs merge` and `rs dedupe` among the sub-commands, which is consistent with the problem. The pipeline is therefore not a model plus a script; it is a sequence of stages where the output of one is the input of the next, and the intermediate artifacts are files on disk.

## Installing RoboSat from the Docker Hub images

The README gives pre-built Docker images as the primary route, published on Docker Hub under `mapbox/robosat` with CPU and GPU tags. The CPU image is the quickest way to see the command surface. Running it with `--help` prints the available sub-commands, and the README notes that `--network=host` is required for network communication in the download tool.

```bash
docker run -it --rm -v $PWD:/data --ipc=host --network=host mapbox/robosat:latest-cpu --help
```

The `-v $PWD:/data` flag makes the current directory on the host available at `/data` inside the container, which is where the pipeline expects to find and write files.

Training uses the GPU image and requires nvidia-docker on the host. The README gives this example, and the flags are not optional: `--runtime=nvidia` exposes the host GPUs, and `--ipc=host` is required for shared memory communication between workers.

```bash
docker run --runtime=nvidia -it --rm -v $PWD:/data --ipc=host mapbox/robosat:latest-gpu train --model /data/model.toml --dataset /data/dataset.toml --workers 4
```

Both `--model` and `--dataset` point at TOML configuration files. The README says examples live in the `config` directory and that you must adapt them to your dataset, for example setting your tile resolution such as 256x256 pixels, and to your deployment, for example using CUDA and setting batch sizes. Expect to edit those files before any training run produces something meaningful.

If you install from source instead, the README points at the Dockerfiles in the `docker/` directory rather than giving a pip command. Note that `setup.py` registers a console script named `rs`, and the README's usage section invokes tools as `./rs <tool> <args>`. Individual tools also take `--help`.

## The maintenance situation is the first thing to check

The README opens with a note that RoboSat is "neither maintained not actively developed any longer by Mapbox", linking to issue 184, and states that the main developers are no longer with Mapbox. The repository is not archived and its last push was on 2026-06-29, but the project's own documentation is the authority on intent, and it says development stopped. The most recent release listed is v1.2.0 from 2019-06-01, with v1.1.0 before it in 2018. A pipeline whose last tagged release predates its last commit by several years is a pipeline you vendor, not one you track.

The practical consequence is dependency drift. `setup.py` pins `osmium==2.15.2` exactly and uses compatible-release specifiers such as `torch~=1.1`, `numpy~=1.16`, `rasterio~=1.0` and `pillow~=6.0`. Those constraints describe an environment from around 2019. `requirements.txt` is a pip-compile output with hashes, which helps reproducibility but also freezes the same era. Installing from source today means resolving that against a current Python and CUDA stack, and the README does not document a supported Python version beyond Python 3.

There is no rollback or migration documentation to fall back on, and no upgrade guide between v1.1.0 and v1.2.0 in the README. If you adopt RoboSat, the container images are the safer artifact because they carry the resolved environment with them.

## Where the pipeline breaks down, and when not to use it

The failure modes follow from the tile abstraction. Anything that cannot be expressed as Slippy Map tiles is awkward, because the whole pipeline assumes that addressing scheme. The README frames this as a benefit for swapping imagery providers, and it is, but it also means the download tool needs host networking to fetch tiles, and the model never sees context beyond its tile.

The second limitation is the training data assumption. `rs extract` reads OpenStreetMap `.osm.pbf` files and produces GeoJSON geometries, which `rs cover` turns into a tile list. That path is well suited to features OpenStreetMap actually maps well, such as buildings and roads. For something like clouds, which the repository topics mention, there is no OpenStreetMap geometry to extract, so the automatic mask generation path does not apply and you are back to producing masks yourself. The README acknowledges this by offering extending sections for bringing your own imagery and your own masks.

The third is hardware. Training is described as GPU work with a recommendation for potentially multiple GPUs. If you have only CPUs, the README says prediction can run on CPU, but it does not present CPU training as a practical route. Treat RoboSat as a tool that needs a GPU host for the training stage.

Finally, the post-processing stages are not optional polish. If you skip denoising, simplification and boundary handling, you get raster predictions, not usable vector features. Teams expecting a one-command model will find that most of the engineering sits after the model.

## RoboSat compared with a general segmentation framework

The obvious alternative shape is a general deep learning framework where you assemble your own segmentation model, for example PyTorch directly, which RoboSat itself depends on through `torch~=1.1` and `torchvision~=0.3`. The difference is scope, not quality. A framework gives you layers, optimizers and data loaders; you write the tiling, the mask generation, the boundary merging and the GeoJSON export. RoboSat ships those as named sub-commands with configuration files, which is the entire reason to pick it.

That trade goes the other way too. Because RoboSat owns the pipeline, changing the tiling scheme or the mask format means working inside its abstractions rather than replacing a data loader. The README's extending section exists precisely because those points are where users need to intervene, listing bringing your own imagery, bringing your own masks, and adding feature support in pre-processing and post-processing.

A second alternative is to use RoboSat only for the parts that are hard to reimplement. The post-processing stage, which converts pixel predictions into simplified, deduplicated GeoJSON with tile boundaries handled, is the least glamorous and most reusable piece. Nothing in the repository layout prevents you from running your own model and using the geometry tooling around it, provided you produce masks in the format the tools expect.

## Licence and the cost of keeping a vendored pipeline alive

The licence is MIT, and `setup.py` declares the classifier `License :: OSI Approved :: MIT License`. MIT is permissive, so the usual obligations apply: keep the copyright and permission notice with copies or substantial portions, and note that the software comes without warranty. That is a summary of the licence family, not legal advice; read the LICENSE file in the repository root before you ship anything derived from it.

The licence is not where the cost sits. The cost is that you are adopting a codebase whose own README says Mapbox stopped maintaining it. The repository is not archived, so issues and pull requests are not closed by policy, but the README names the maintainers as having left. Budget for reading the source when something breaks, because there is no upstream support channel described.

Upgrade cost is mostly dependency cost. The `requirements.txt` file is generated by pip-compile with hashes and carries the instruction to regenerate it with `pip-compile --generate-hashes`. Moving the project to a newer PyTorch or a newer `osmium` is a change you make and own. The Makefile offers a hint about how the authors worked: `make install` builds the image from `docker/Dockerfile.cpu` by default, `make update` rebuilds with `--pull --no-cache`, and `make run` starts a container with the source mounted at `/usr/src/app/robosat` and data at `/data`. Those targets are the practical starting point for a fork.

## Conclusion

RoboSat suits engineers who need a complete, inspectable pipeline for turning aerial or satellite tiles into GeoJSON features and who are willing to vendor a repository that Mapbox states is no longer maintained. It is the wrong choice if you need a supported dependency with a release cadence, or if your imagery is not expressible as Slippy Map tiles. Before adopting it, verify that the pinned `osmium==2.15.2` and `torch~=1.1` in setup.py build in your environment, and confirm which of the `rs` sub-commands your workflow actually needs, because the README documents only some of them in detail.

## FAQ

### What is mapbox/robosat?

It is an end-to-end pipeline written in Python 3 for feature extraction from aerial and satellite imagery, distributed under the MIT licence. It covers data preparation, segmentation model training, and post-processing of predictions into cleaned GeoJSON geometries.

### How do I install mapbox/robosat?

The README gives pre-built Docker images on Docker Hub under mapbox/robosat, with CPU and GPU tags. For installation from source it points at the Dockerfiles in the docker/ directory rather than a pip command.

### Is mapbox/robosat still maintained?

The README states that RoboSat is neither maintained nor actively developed any longer by Mapbox, and that the main developers are no longer with Mapbox. The repository is not archived and its last push was on 2026-06-29, but the most recent release listed is v1.2.0 from 2019-06-01.

## Sources

- [Issues](https://github.com/mapbox/robosat/issues)
- [License: MIT](https://github.com/mapbox/robosat/blob/master/LICENSE)
- [mapbox/robosat on GitHub](https://github.com/mapbox/robosat)
- [README](https://github.com/mapbox/robosat/blob/master/README.md)
- [Releases](https://github.com/mapbox/robosat/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mapbox-robosat