mapcv

A high-performance satellite imagery dataset creation tool for computer vision.

Statement of Need

Creating machine learning datasets from satellite imagery is traditionally a frustrating experience. Wrestling with heavy, notoriously complex GIS libraries like GDAL is a massive pain point for researchers who just want to train models.

Existing geospatial ecosystems are heavily analysis-first. mapcv is different. It is explicitly designed as a data creation-first tool. It provides a fast, end-to-end pipeline written in Python and Rust specifically optimized for fetching map tiles, rasterizing complex labels (KML/GeoJSON), and splitting areas into uniform, ML-ready patches. The target audience includes computer vision researchers, data scientists, and ML engineers who need an efficient and reliable way to prepare high-quality satellite datasets for training segmentation models without the traditional GIS headaches.

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.

EOPF Sentinel-2 L2A Zarr support is optional:

pip install "mapcv[zarr]"

The zarr extra currently supports Python 3.10–3.13: its zarr 2 dependency has no Python 3.14 wheels yet.

Quick start

1. Scaffold a config file

mapcv init my_dataset.yaml

Open the file and fill in your region, imagery source, and (optionally) label path. Everything else has sensible defaults.

Note: XYZ sources must return standard 256x256 pixel tiles. You are responsible for complying with the imagery provider's license, attribution, rate limits, and terms. mapcv does not grant imagery rights.

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.

EOPF Sentinel-2 Zarr

Version 0.2.0 can read one local or anonymous public EOPF Sentinel-2 L2A product per run. It preserves the product's projected CRS, harmonizes selected bands with the EOPF backend, and writes bands-first float32 NPY patches.

region:
  west: 10.0
  south: 45.0
  east: 10.2
  north: 45.2

imagery:
  type: eopf_zarr
  path: /data/S2_L2A_PRODUCT.zarr
  resolution: 10
  bands: [b01, b02, b03, b04, b05, b06, b07, b08, b8a, b09, b11, b12]
  chunk_rows: 1024

sampler:
  patch_size: 256

writer:
  staging_dir: ./dataset
  image_format: npy

Private-store credentials, STAC discovery, mosaicking, cloud masking, GeoTIFF output, and Google Earth Engine integration are outside the 0.2.0 scope. See the migration guide and provider guidance.

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

(Citation information will be added after publication.)

Author

Muhammad Taha Mukhtar · tahamukhtar20+mapcv@gmail.com

License

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