[{"_1":2,"_169":-5,"_170":-5},"loaderData",{"_3":4,"_13":14,"_21":22,"_144":145},"root",{"_5":-5,"_6":-7,"_7":8,"_9":-7,"_10":11,"_12":-7},"currentUser","primaryEmail","siteVerification","6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI","toast","enableDev",false,"incidentStatus","routes/_layout",{"_15":-5,"_16":17,"_18":17,"_19":11,"_20":11},"username","isAskGordonEnabled",true,"isUsingNewTemplate","showMinimalLanding","showHoneypotTrap","routes/_layout.r.$namespace.$reponame",{"_23":24,"_25":-5,"_26":11,"_27":11,"_28":29,"_30":31,"_32":-5,"_33":11,"_34":35,"_84":-5,"_85":86,"_135":-5,"_136":11,"_137":17,"_138":11,"_139":-5,"_140":11,"_141":-5,"_142":143},"canonicalUrl","https://hub.docker.com/r/danieljh/robosat/tags","mcpServer","canSeeDockerfile","canSeeAutobuilds","namespace","danieljh","reponame","robosat","cloudBuildSource","isAutobuildsAvailable","repo",{"_36":37,"_38":39,"_41":42,"_43":44,"_45":11,"_46":47,"_48":49,"_50":51,"_53":31,"_28":29,"_54":55,"_56":40,"_57":58,"_59":60,"_61":62,"_63":-5,"_64":58,"_65":66,"_67":11,"_68":29,"_69":70,"_75":11,"_76":77,"_81":29,"_82":83},"categories",[],"content_types",[40],"image","date_registered","2019-05-29T17:10:35.426064Z","description","Generic ecosystem for feature extraction from aerial and satellite imagery ","is_private","last_updated","2020-05-29T08:37:20.656936Z","last_modified","2024-10-16T13:48:34.145251Z","media_types",[52],"application/vnd.docker.container.image.v1+json","name","pull_count",168,"repository_type","star_count",0,"status",1,"status_description","active","source","collaborator_count","full_description","**Note: Robosat is neither maintained not actively developed any longer by Mapbox. See [this issue](https://github.com/mapbox/robosat/issues/184). \nThe main developers ([@daniel-j-h](https://github.com/daniel-j-h), [@bkowshik](https://github.com/bkowshik)) are no longer with Mapbox.**\n\n

RoboSat

\n\n

\n Generic ecosystem for feature extraction from aerial and satellite imagery\n\n $\"RoboSat$ \n Berlin aerial imagery, segmentation mask, building outlines, simplified GeoJSON polygons\n

\n\n

\n\n\n## Table of Contents\n\n1. [Overview](#overview)\n2. [Installation](#installation)\n3. [Usage](#usage)\n - [extract](#rs-extract)\n - [cover](#rs-cover)\n - [download](#rs-download)\n - [rasterize](#rs-rasterize)\n - [train](#rs-train)\n - [export](#rs-export)\n - [predict](#rs-predict)\n - [mask](#rs-mask)\n - [features](#rs-features)\n - [merge](#rs-merge)\n - [dedupe](#rs-dedupe)\n - [serve](#rs-serve)\n - [weights](#rs-weights)\n - [compare](#rs-compare)\n - [subset](#rs-subset)\n4. [Extending](#extending)\n - [Bring your own imagery](#bring-your-own-imagery)\n - [Bring your own masks](#bring-your-own-masks)\n - [Add support for feature in pre-processing](#add-support-for-feature-in-pre-processing)\n - [Add support for feature in post-processing](#add-support-for-feature-in-post-processing)\n5. [Contributing](#contributing)\n6. [License](#license)\n\n\n## Overview\n\nRoboSat is an end-to-end pipeline written in Python 3 for feature extraction from aerial and satellite imagery.\nFeatures can be anything visually distinguishable in the imagery for example: buildings, parking lots, roads, or cars.\n\nHave a look at\n- [this OpenStreetMap diary post](https://www.openstreetmap.org/user/daniel-j-h/diary/44145) where we first introduced RoboSat and show some results\n- [this OpenStreetMap diary post](https://www.openstreetmap.org/user/daniel-j-h/diary/44321) where we extract building footprints based on drone imagery in Tanzania\n- [this OpenStreetMap diary post](https://www.openstreetmap.org/user/daniel-j-h/diary/45042) where we summarize the v1.1 release\n- [this OpenStreetMap diary post](https://www.openstreetmap.org/user/daniel-j-h/diary/368726) where we summarize the v1.2 release\n- [this OpenStreetMap diary post](https://www.openstreetmap.org/user/daniel-j-h/diary/368771) where we run robosat v1.2 on aerial imagery for Bavaria, Germany\n- [this OpenStreetMap diary post](https://www.openstreetmap.org/user/maning/diary/44462) where [Maning](https://github.com/maning) runs robosat on imagery from the Philippines\n\nThe tools RoboSat comes with can be categorized as follows:\n- data preparation: creating a dataset for training feature extraction models\n- training and modeling: segmentation models for feature extraction in images\n- post-processing: turning segmentation results into cleaned and simple geometries\n\nTools work with the [Slippy Map](https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames) tile format to abstract away geo-referenced imagery behind tiles of the same size.\n\n![](./assets/pipeline-01.png)\n\nThe data preparation tools help you with getting started creating a dataset for training feature extraction models.\nSuch a dataset consists of aerial or satellite imagery and corresponding masks for the features you want to extract.\nWe provide convenient tools to automatically create these datasets downloading aerial imagery from the [Mapbox](mapbox.com) Maps API and generating masks from [OpenStreetMap](openstreetmap.org) geometries but we are not bound to these sources.\n\n![](./assets/pipeline-02.png)\n\nThe modelling tools help you with training fully convolutional neural nets for segmentation.\nWe recommend using (potentially multiple) GPUs for these tools: we are running RoboSat on AWS p2/p3 instances and GTX 1080 TI GPUs.\nAfter you trained a model you can save its checkpoint and run prediction either on GPUs or CPUs.\n\n![](./assets/pipeline-03.png)\n\nThe post-processing tools help you with cleaning up the segmentation model's results.\nThey are responsible for denoising, simplifying geometries, transforming from pixels in Slippy Map tiles to world coordinates (GeoJSON features), and properly handling tile boundaries.\n\nIf this sounds almost like what you need, see the [extending section](#extending) for more details about extending RoboSat.\nIf you want to contribute, see the [contributing section](#contributing) for more details about getting involved with RoboSat.\n\n\n## Installation\n\nWe provide pre-built Docker images for both CPU as well as GPU environments on Docker Hub in [mapbox/robosat](https://hub.docker.com/r/mapbox/robosat/tags/).\n\nUsing a CPU container to show all available sub-commands\n\n docker run -it --rm -v $PWD:/data --ipc=host --network=host mapbox/robosat:latest-cpu --help\n\nUsing a GPU container (requires [nvidia-docker](https://github.com/NVIDIA/nvidia-docker) on the host) to train a model\n\n 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\n\nArguments\n- `--runtime=nvidia` enables the nvidia-docker runtime for access to host GPUs\n- `--ipc=host` is required for shared memory communication between workers\n- `--network=host` is required for network communication in the download tool\n- `-v $PWD:/data` makes the current directory on the host accessible at `/data` in the container\n\nFor installation from source (requires installing dependencies) see the Dockerfiles in the [`docker/`](docker) directory.\n\n\n## Usage\n\nThe following describes the tools making up the RoboSat pipeline.\nAll tools can be invoked via\n\n ./rs \n\nAlso see the sub-command help available via\n\n ./rs --help\n ./rs --help\n\nMost tools take a dataset or model configuration file. See examples in the [`configs`](./config) directory.\nYou will need to adapt these configuration files to your own dataset, for example setting your tile resolution (e.g. 256x256 pixel).\nYou will also need to adapt these configuration files to your specific deployment setup, for example using CUDA and setting batch sizes.\n\n\n### rs extract\n\nExtracts GeoJSON features from OpenStreetMap to build a training set from.\n\nThe result of `rs extract` is a GeoJSON file with the extracted feature geometries.\n\nThe `rs extract` tool walks OpenStreetMap `.osm.pbf` base map files (e.g. from [Geofabrik](http://download.geofabrik.de)) and gathers feature geometries.\nThese features are for example polygons for parking lots, buildings, or roads.\n\n\n### rs cover\n\nGenerates a list of tiles covering GeoJSON features to build a training set from.\n\nThe result of `rs cover` is a file with tiles in `(x, y, z)` [Slippy Map](https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames) tile format covering GeoJSON features.\n\nThe `rs cover` tool reads in the GeoJSON features generated by `rs extract` and generates a list of tiles covering the feature geometries.\n\n\n### rs download\n\nDownloads aerial or satellite imagery from a Slippy Map endpoint (e.g. the Mapbox Maps API) based on a list of tiles.\n\nThe result of `rs download` is a Slippy Map directory with aerial or satellite images - the training set's images you will need for the model to learn on.\n\nThe `rs download` tool downloads images for a list of tiles in `(x, y, z)` [Slippy Map](https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames) tile format generated by `rs cover`.\n\nThe `rs download` tool expects a Slippy Map endpoint where placeholders for `{x}`, `{y}`, and `{z}` are formatted with each tile's ids.\nFor example, for the Mapbox Maps API: `https://api.mapbox.com/v4/mapbox.satellite/{z}/{x}/{y}@2x.webp?access_token=TOKEN`.\n\n\n### rs rasterize\n\nRasterizes GeoJSON features into mask images based on a list of tiles.\n\nThe result of `rs rasterize` is a Slippy Map directory with masks - the training set's masks you will need for the model to learn on.\n\nThe `rs rasterize` tool reads in GeoJSON features and rasterizes them into single-channel masks with a color palette attached for quick visual inspection.\n\n\n### rs train\n\nTrains a model on a training set made up of `(image, mask)` pairs.\n\nThe result of `rs train` is a checkpoint containing weights for the trained model.\n\nThe `rs train` tool trains a fully convolutional neural net for semantic segmentation on a dataset with `(image, mask)` pairs generated by `rs download` and `rs rasterize`.\nWe recommend using a GPU for training: we are working with the AWS p2 instances and GTX 1080 TI GPUs.\n\nBefore you can start training you need the following.\n\n- You need a dataset which you should split into three parts: training and validation for `rs train` to train on and to calculate validation metrics on and a hold-out dataset for final model evaluation. The dataset's directory need to look like the following.\n\n dataset\n ├── training\n │ ├── images\n │ └── labels\n └── validation\n ├── images\n └── labels\n\n- You need to calculate label class weights with `rs weights` on the training set's labels\n\n- You need to add the path to the dataset's directory and the calculated class weights and statistics to the dataset config.\n\n\n### rs export\n\nExports a trained model in [ONNX](https://onnx.ai/) format for prediction across different backends (like Caffe2, TensorFlow).\n\nThe result of `rs export` is an ONNX GraphProto `.pb` file which can be used with the ONNX ecosystem.\n\nNote: the `rs predict` tool works with `.pth` checkpoints. In contrast to these `.pth` checkpoints the ONNX models neither depend on PyTorch or the Python code for the model class and can be used e.g. in resource constrained environments like AWS Lambda.\n\n\n### rs predict\n\nPredicts class probabilities for each image tile in a Slippy Map directory structure.\n\nThe result of `rs predict` is a Slippy Map directory with a class probability encoded in a `.png` file per tile.\n\nThe `rs predict` tool loads the checkpoint weights generated by `rs train` and predicts semantic segmentation class probabilities for a Slippy Map dataset consisting of image tiles.\n\n\n### rs masks\n\nGenerates segmentation masks for each class probability `.png` file in a Slippy Map directory structure.\n\nThe result of `rs masks` is a Slippy Map directory with one single-channel image per tile with a color palette attached for quick visual inspection.\n\nThe `rs masks` tool loads in the `.png` tile segmentation class probabilities generated by `rs predict` and turns them into segmentation masks.\nYou can merge multiple Slippy Map directories with class probabilities into a single mask using this tool in case you want to make use of an ensemble of models.\n\n\n### rs features\n\nExtracts simplified GeoJSON features for segmentation masks in a Slippy Map directory structure.\n\nThe result of `rs features` is a GeoJSON file with the extracted simplified features.\n\nThe `rs features` tool loads the segmentation masks generated by `rs masks` and turns them into simplified GeoJSON features.\n\n\n### rs merge\n\nMerges close adjacent GeoJSON features into single features.\n\nThe result of `rs merge` is a GeoJSON file with the merged features.\n\nThe `rs merge` tool loads GeoJSON features and depending on a threshold merges adjacent geometries together.\n\n\n### rs dedupe\n\nDeduplicates predicted features against existing OpenStreetMap features.\n\nThe result of `rs dedupe` is a GeoJSON file with predicted features which are not in OpenStreetMap.\n\nThe `rs dedupe` deduplicates predicted features against OpenStreetMap.\n\nNote: `rs extract` to generate a GeoJSON file with OpenStreetMap features.\n\n\n### rs serve\n\nServes tile masks by providing an on-demand segmentation tileserver.\n\nThe `rs serve` tool implements a Slippy Map raster tileserver requesting satellite tiles and applying the segmentation model on the fly.\n\nNotes: useful for visually inspecting the raw segmentation masks on the fly; for serious use-cases use `rs predict` and similar.\n\n\n### rs weights\n\nCalculates class weights for a Slippy Map directory with masks.\n\nThe result of `rs weights` is a list of class weights useful for `rs train` to adjust the loss based on the class distribution in the masks.\n\nThe `rs weights` tool computes the pixel-wise class distribution on the training dataset's masks and outputs weights for training.\n\n\n### rs compare\n\nPrepares images, labels and predicted masks, side-by-side for visual comparison.\n\nThe result of `rs compare` is a Slippy Map directory with images that have the raw image on the left, the label in the middle and the prediction on the right.\n\n\n### rs subset\n\nFilters a Slippy Map directory based on a list of tile ids.\n\nThe result of `rs subset` is a Slippy Map directory filtered by tile ids.\n\nThe main use-case for this tool is hard-negative mining where we want to filter false positives from a prediction run.\n\n\n## Extending\n\nThere are multiple ways to extend RoboSat for your specific use-cases.\nBy default we use [Mapbox](mapbox.com) aerial imagery from the Maps API and feature masks generated from [OpenStreetMap](openstreetmap.org) geometries.\nIf you want to bring your own imagery, masks, or features to extract, the following will get you started.\n\n### Bring your own imagery\n\nRoboSat's main abstraction is the [Slippy Map](https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames) tile format.\nAs long as your imagery is geo-referenced and you can convert it to a Slippy Map directory structure to point the command lines to, you are good to go.\nMake sure imagery and masks are properly aligned.\n\n### Bring your own masks\n\nRoboSat's main abstraction is the [Slippy Map](https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames) tile format.\nAs long as you can convert your masks to a Slippy Map directory structure to point the command lines to, you are good to go.\nMasks have to be single-channel `.png` files with class indices starting from zero.\nMake sure imagery and masks are properly aligned.\n\n### Add support for feature in pre-processing\n\nPre-processing (`rs extract`) is responsible for turning OpenStreetMap geometries and tags into polygon feature masks.\nIf you want to add a new feature based on geometries in OpenStreetMap you have to:\n- Implement an [osmium](https://docs.osmcode.org/pyosmium/latest/) handler which turns OpenStreetMap geometries into polygons; see [`robosat/osm/`](./robosat/osm/) for existing handlers.\n- Import and register your handler in [`robosat/tools/extract.py`](./robosat/tools/extract.py).\n\nAnd that's it! From there on the pipeline is fully generic.\n\n### Add support for feature in post-processing\n\nPost-processing (`rs features`) is responsible for turning segmentation masks into simplified GeoJSON features.\nIf you want to add custom post-processing for segmentation masks you have to:\n- Implement a featurize handler turning masks into GeoJSON features; see [`robosat/features/`](./robosat/features/) for existing handlers.\n- Import and register your handler in [`robosat/tools/features.py`](./robosat/tools/features.py).\n\nAnd that's it! From there on the pipeline is fully generic.\n\n\n## Contributing\n\nWe are thankful for contributions and are happy to help; that said there are some constraints to take into account:\n- For non-trivial changes you should open a ticket first to outline and discuss ideas and implementation sketches. If you just send us a pull request with thousands of lines of changes we most likely won't accept your changeset.\n- We follow the 80/20 rule where 80% of the effects come from 20% of the causes: we strive for simplicity and maintainability over pixel-perfect results. If you can improve the model's accuracy by two percent points but have to add thousands of lines of code we most likely won't accept your changeset.\n- We take responsibility for changesets going into master: as soon as your changeset gets approved it is on us to maintain and debug it. If your changeset can not be tested, or maintained in the future by the core developers we most likely won't accept your changeset.\n\n\n## License\n\nCopyright (c) 2018 Mapbox\n\nDistributed under the MIT License (MIT).\n","has_starred","hub_user","immutable_tags_settings",{"_71":11,"_72":73},"enabled","rules",[74],".*","is_automated","permissions",{"_78":17,"_79":11,"_80":11},"read","write","admin","user","storage_size",9788381438,"orgData","recentTags",[87,125],{"_88":40,"_89":90,"_91":92,"_93":94,"_95":96,"_46":114,"_115":90,"_116":29,"_117":52,"_53":118,"_119":120,"_121":105,"_122":114,"_123":62,"_124":17},"content_type","creator",21422,"full_size",504195605,"id",57431437,"images",[97],{"_98":99,"_100":101,"_102":103,"_104":105,"_106":107,"_108":109,"_110":103,"_111":-5,"_112":92,"_59":62,"_113":-5},"architecture","amd64","digest","sha256:c408ef3d730d422b7adf832225366ee652f2389b5ab7f4c888f6acdca03341a7","features","","last_pulled","2026-09-18T12:30:48.144617361Z","last_pushed","2020-05-29T08:37:20Z","os","linux","os_features","os_version","size","variant","2020-05-29T08:37:20.223575Z","last_updater","last_updater_username","media_type","latest-cpu","repository",7190477,"tag_last_pulled","tag_last_pushed","tag_status","v2",{"_88":40,"_89":90,"_91":126,"_93":127,"_95":128,"_46":133,"_115":90,"_116":29,"_117":52,"_53":134,"_119":120,"_121":131,"_122":133,"_123":62,"_124":17},2164506567,57428190,[129],{"_98":99,"_100":130,"_102":103,"_104":131,"_106":132,"_108":109,"_110":103,"_111":-5,"_112":126,"_59":62,"_113":-5},"sha256:232d9363152859bcc6506ad2f8dfe3f363900e21b1ab69ae0ce4346b6c545fa5","2026-09-22T06:32:42.566335491Z","2020-05-29T08:28:54Z","2020-05-29T08:28:53.066433Z","latest-gpu","sbxKitMetadata","isPotentialSpam","isHubSbxKitsEnabled","showSbxLogoOverride","sbxTrademarkText","displaySecurityMetadata","tagAttestations","tagsHaveAttestations",[],"routes/_layout.r.$namespace.$reponame.tags",{"_34":146,"_153":154,"_142":167,"_168":11},{"_36":147,"_38":148,"_41":42,"_43":44,"_45":11,"_46":47,"_48":49,"_50":149,"_53":31,"_28":29,"_54":55,"_56":40,"_57":58,"_59":60,"_61":62,"_63":-5,"_64":58,"_65":66,"_67":11,"_68":29,"_69":150,"_75":11,"_76":152,"_81":29,"_82":83},[],[40],[52],{"_71":11,"_72":151},[74],{"_78":17,"_79":11,"_80":11},"tags",{"_155":156,"_157":-5,"_158":-5,"_159":160},"count",2,"next","previous","results",[161,164],{"_88":40,"_89":90,"_91":92,"_93":94,"_95":162,"_46":114,"_115":90,"_116":29,"_117":52,"_53":118,"_119":120,"_121":105,"_122":114,"_123":62,"_124":17},[163],{"_98":99,"_100":101,"_102":103,"_104":105,"_106":107,"_108":109,"_110":103,"_111":-5,"_112":92,"_59":62,"_113":-5},{"_88":40,"_89":90,"_91":126,"_93":127,"_95":165,"_46":133,"_115":90,"_116":29,"_117":52,"_53":134,"_119":120,"_121":131,"_122":133,"_123":62,"_124":17},[166],{"_98":99,"_100":130,"_102":103,"_104":131,"_106":132,"_108":109,"_110":103,"_111":-5,"_112":126,"_59":62,"_113":-5},[],"canDeleteTags","actionData","errors"]

danieljh/robosat

Tags for danieljh/robosat