Skip to content
mapcvmapcv

Map labels in.
Training data out.

mapcv turns a region, imagery and labels into a ready-to-train dataset for six computer-vision tasks, exact to the pixel, with spatial splits that don't leak.

pip install mapcv

Get startedGitHub

Three commands

From config to dataset in minutes

Section titled “From config to dataset in minutes”
1init

Answer four questions, or start from a template.

$ mapcv init
1/4 Imagery
Imagery [esri/sentinel2/custom] (esri):
2/4 Area
Area: 4.9375,52.3725,4.9515,52.3780
Zoom (17): 18
3/4 Labels
Label file: buildings.geojson
Which field holds the class? (): class
4/4 Patches and output …
✓ Wrote mapcv.yaml
2plan

See tiles, patches, disk and memory before downloading anything.

$ mapcv plan mapcv.yaml
╭─ Plan for mapcv.yaml ─────────
Imagery  esri_satellite · zoom 18
         (≈ 0.36 m/px)
Raster   2,816 × 1,792 px · 77 tiles
Labels   967 polygons
         classes: building → 1
Patches  ≈ 77 × 256 px
Output   dataset · png (≈ 8.6 MB)
3generate

Fetch, rasterize, cut patches and split, with a summary at the end.

$ mapcv generate mapcv.yaml
Reading imagery and writing patches
━━━━━━━━━━━━━━━━━━━━ 2/2 chunks
╭─ Dataset ready ───────────────
Patches  77
Shape    256×256×3 uint8
Splits   train 52 · val 8 · test 17
Time     21s
  building   1   19.0%

Four aerial patches over Amsterdam and the same patches with building masks

Real (trimmed) output from the Quickstart: 967 OpenStreetMap building outlines in Amsterdam, imagery at about 0.36 m per pixel, 77 labeled patches in under half a minute. Figure: patches and masks over the same area (imagery: Beeldmateriaal Nederland, CC BY 4.0; labels: © OpenStreetMap contributors).

Why mapcv

Built for the dataset step, and only that

Section titled “Built for the dataset step, and only that”

Fast Rust core

Tile fetching, GeoTIFF reading, rasterizing and patch encoding run in Rust. One wheel per platform covers Python 3.10 and newer. pip install and go.

Leakage-safe splits

The default spatial split keeps whole blocks of the map in one split and drops train/val patches that overlap a test patch, so scores aren’t inflated by shared pixels.

Any imagery, six tasks

XYZ tiles, your own GeoTIFF/COG, Sentinel-2 (EOPF or STAC with cloud masking) or Earth Engine, into segmentation, detection, instance, classification, change or regression data.

Large regions, resumable

mapcv plan estimates tiles, disk and memory first. Generation runs in bounded windows and picks up where it stopped, byte for byte the same as an uninterrupted run.

ML-ready output

Patches as PNG, JPEG, NPY or georeferenced GeoTIFF, COCO/YOLO, a manifest and split lists. Load them with MapcvDataset, or export to Hugging Face, WebDataset, Zarr and TerraTorch.

Keys stay private

API keys in a tile URL never reach the manifest, logs or messages, and Earth Engine runs on your own login. Each source’s credit line is listed and written into the dataset card.

What you get

A folder you can train on

Section titled “A folder you can train on”
  • Directorydataset/
    • DirectoryImages/
      • patch_0000000.png RGB patch (or bands-first float32 .npy)
      • …
    • DirectoryMasks/
      • patch_0000000.png same name, uint8 class IDs
      • …
    • manifest.json source, CRS, transform, class map, per-patch stats
    • Directorysplits/
      • train.txt
      • val.txt
      • test.txt
      • split.json how the split was made
      • Directory10/ labeled.txt and unlabeled.txt for semi-supervised work
        • labeled.txt
        • unlabeled.txt

See Dataset format for every field.

How it compares

Where mapcv fits

Section titled “Where mapcv fits”

mapcv does one job: it writes a static, reproducible dataset from imagery and labels, checked against reference implementations. On the benchmarks, a careful rasterio script, GDAL’s tools and leafmap produce the same patches, 1.5–34× more slowly.

  • TorchGeo samples patches on the fly from rasters inside PyTorch and ships many benchmark datasets. Pick it to train directly on large rasters.
  • Raster Vision covers the full workflow from data to trained model and prediction. Pick it if you want one framework end to end.
  • Your own GDAL/rasterio script handles any one-off. mapcv handles the parts scripts get wrong at scale: exact grids, NoData, memory, resuming and leakage-safe splits.

More in Why mapcv.

The tools combine well: a mapcv dataset is plain files, so you can train it with any library.

Next

Pick your path

Section titled “Pick your path”
QuickstartBuild a labeled dataset of buildings in five minutes.
TutorialsBuildings from aerial imagery, land cover from Sentinel-2, then train a model.
Use your datasetLoad patches, masks and splits in NumPy or PyTorch.
Configuration referenceEvery YAML field, its default and how it is validated.