mapcv

Turn imagery and labels into ready-to-train remote-sensing datasets, fast.

_{Patches and building masks made by mapcv. Imagery: Beeldmateriaal Nederland (CC BY 4.0); labels: © OpenStreetMap contributors.}

Statement of Need

Building a machine-learning dataset from geospatial data usually means a one-off script: fetch or read imagery, burn label polygons, cut patches, split. Done carefully, it handles coordinate systems, pixel-centre rules, NoData, memory, crashes and spatial leakage between train and test; done quickly, it silently gets them wrong. Existing geospatial tools are analysis-first or sample data at training time. mapcv is data-creation-first: one YAML config, and the result is plain files on disk, checked against reference implementations.

• Imagery: XYZ tiles, your own GeoTIFF/COG (local, https://, s3://), Sentinel-2 (EOPF Zarr, or COGs found in a STAC catalog, with cloud masking), Google Earth Engine; several sources on one grid.
• Labels: GeoJSON, KML, GeoPackage, Shapefile, GeoParquet, OpenStreetMap, or a label raster.
• Tasks: semantic segmentation, object detection (COCO/YOLO), instance segmentation (COCO RLE), patch classification, change detection and regression.
• Output: PNG/JPEG/GeoTIFF/NPY patches, a manifest, leakage-safe splits, and exports to Hugging Face Parquet, WebDataset, Zarr and TerraTorch; mapcv.data.MapcvDataset loads any of them for PyTorch.
• Correct and fast: masks follow GDAL's exact rules; a careful rasterio script, GDAL's tools and leafmap produce the same patches, 1.5–34× more slowly (benchmarks). Interrupted runs resume byte for byte; memory stays bounded on any region size.

Why not a script, TorchGeo, Raster Vision or geoai? See Why mapcv.

Installation

pip install mapcv

Requires Python 3.10 or newer. One pre-built wheel per platform (Linux x86-64 and aarch64 with glibc or musl, macOS, Windows) covers every supported Python version; other platforms build from source and need a Rust toolchain.

Optional extras: mapcv[zarr] (Sentinel-2 EOPF Zarr, Python 3.10–3.13), mapcv[gee] (Google Earth Engine), mapcv[parquet] (GeoParquet labels), mapcv[export] (Hugging Face Parquet) and mapcv[mcp] (the MCP server for AI agents). XYZ tiles, GeoTIFF/COG and STAC need none of them.

Quick start

1. Scaffold a config file

mapcv init my_dataset.yaml

In a terminal this asks a few questions (imagery, area, labels, patches) and writes a working config; mapcv init my_dataset.yaml --template xyz writes a commented example to fill in instead. Everything else has sensible defaults.

Note: XYZ sources must return standard 256x256 pixel tiles. mapcv does not provide imagery; see PROVIDERS.md for how it treats imagery and how to credit each source.

2. Generate the dataset

mapcv generate my_dataset.yaml

This fetches tiles, rasterizes labels, extracts patches, and writes everything to the output directory specified in your config.

3. Re-split an existing dataset (optional)

mapcv split ./output --test-ratio 0.15 --val-ratio 0.10

Re-runs the train/val/test split from the existing manifest.json without re-downloading anything.

4. Prepare it for training and sharing (optional)

mapcv stats ./output     # per-band mean/std and class weights over train → stats.json
mapcv card ./output      # README.md dataset card with Hugging Face metadata
mapcv verify ./output --write-checksums

Bring your own imagery

Your own GeoTIFF or Cloud Optimized GeoTIFF (a local file, an https:// URL, a public s3:// object, or a glob pattern such as tiles/*.tif that reads a folder of local tiles as one mosaic) can be the imagery; no tile server is involved. mapcv reads it directly, keeps its CRS, pixel grid, bands and data type, and reprojects the labels onto it. Patches can be written as PNG/JPEG (8-bit RGB), NPY or georeferenced GeoTIFF.

imagery:
  type: geotiff
  path: ortho/scene.tif      # or https://.../scene.tif, s3://bucket/scene.tif, or tiles/*.tif (a mosaic)
  # bands: [1, 2, 3]         # 1-based, default: all
  # overview: 0              # reduced-resolution level
  # nodata: 0                # override the file's NoData

Sentinel-2 can come from an EOPF Zarr product (type: eopf_zarr) or be found for your region and dates in a STAC catalog (type: stac_cog, with SCL cloud masking); Earth Engine images use imagery.earth_engine. Every option: configuration reference.

AI agents

pip install "mapcv[mcp]" adds mapcv mcp, an MCP server that lets Claude Code, Claude Desktop, Cursor or VS Code inspect labels, validate, plan and generate datasets. It is read-only by default, confined to one folder (--root), and refuses large jobs until you confirm them. In Claude Code, /plugin marketplace add tahamukhtar20/mapcv then /plugin install mapcv@mapcv also installs the agent skill. See Use mapcv with AI agents.

Documentation

Full documentation including configuration reference, CLI reference, and API reference is available at tahamukhtar20.github.io/mapcv.

Contributing

Contributions are welcome. Please review the Contributing Guide and Code of Conduct before opening a pull request.

Citation

If mapcv helped your work, please cite it. The DOI 10.5281/zenodo.23149438 covers every release and always resolves to the latest one:

@software{mukhtar_mapcv,
  author  = {Mukhtar, Muhammad Taha},
  title   = {mapcv: computer-vision datasets from map imagery and geospatial labels},
  year    = {2026},
  doi     = {10.5281/zenodo.23149438},
  url     = {https://github.com/tahamukhtar20/mapcv},
  license = {MIT}
}

GitHub's "Cite this repository" button gives the same from CITATION.cff. See Citing mapcv for the DOI of a single version and for crediting the data sources.

Author

Muhammad Taha Mukhtar · tahamukhtar20+mapcv@gmail.com

License

This project is licensed under the MIT License — see the LICENSE file for details.