FAQ
Do I need GDAL?
Section titled “Do I need GDAL?”No. mapcv’s tile math, fetching, rasterization and patch writing are in Rust, and it reads GeoJSON, KML, GeoPackage, Shapefile and GeoParquet itself (GeoPackage with Python’s sqlite3 and Shapely, Shapefile with the pure-Python pyshp, GeoParquet with pyarrow). You may still find GDAL’s ogr2ogr handy to convert other formats once (Prepare labels).
Which Python versions are supported?
Section titled “Which Python versions are supported?”Python 3.10–3.14 for the base package. Sentinel-2 support (mapcv[zarr]) works on 3.10–3.13, because its zarr 2 dependency has no Python 3.14 wheels.
Can I use Google, Bing or OpenStreetMap tiles?
Section titled “Can I use Google, Bing or OpenStreetMap tiles?”mapcv has no presets for them, because Google and the OpenStreetMap Foundation ask clients not to bulk-download their tiles. imagery.url_template takes any XYZ tile service. OpenStreetMap data is a good source of labels. See Providers & licensing.
Can I use my own GeoTIFF or drone orthomosaic?
Section titled “Can I use my own GeoTIFF or drone orthomosaic?”Yes. Set imagery.type: geotiff with a local path, an https:// URL or an anonymous s3:// URL. Patches keep the file’s CRS, pixel grid, bands and data type. A glob pattern such as tiles/*.tif reads a folder of tiles as one mosaic. See Use your own GeoTIFF.
Can I make an image-only dataset?
Section titled “Can I make an image-only dataset?”Yes. Leave out the labels block. You get Images/, a manifest and splits, but no Masks/.
Can I make an object-detection, instance-segmentation, classification, change or regression dataset?
Section titled “Can I make an object-detection, instance-segmentation, classification, change or regression dataset?”Yes. Set task: detection for a box per object (COCO JSON and YOLO labels), or task: instance for a mask per object (COCO JSON with RLE masks and, optionally, an instance-ID PNG per patch). Each label feature is one object. See Object detection datasets and Instance segmentation datasets. For one label per patch, or a set of labels, set task: classification: patches are labeled by how much of each class they cover, and a labels.csv and labels.json replace the masks (see Patch classification datasets). For change detection, set task: change with two imagery sources (before and after): each patch is an image pair with a change mask (change). For regression, set task: regression with a raster of values such as canopy height (continuous values).
How do I get several classes?
Section titled “How do I get several classes?”Put the class in a property of each feature and set labels.label_field to its name. Pin IDs with labels.classes. See How class IDs are chosen.
What value marks “ignore” in the masks?
Section titled “What value marks “ignore” in the masks?”255 by default. Pixels without imagery (padding, failed tiles, NoData) get labels.ignore_index, so pass the same value to your loss (CrossEntropyLoss(ignore_index=255)). labels.ignore_index: null writes background (0) there instead. See NoData and ignore pixels.
Why are my split percentages not exactly 72/8/20?
Section titled “Why are my split percentages not exactly 72/8/20?”The default spatial split moves whole blocks of the map, and drops train/val patches that overlap test patches. On small datasets that shifts the shares. Smaller block_size or another seed gets closer (guide).
Can I change the split after generating?
Section titled “Can I change the split after generating?”Yes, in seconds: mapcv split dataset --strategy … --test-ratio …. It reads only the manifest.
My run stopped. Do I start over?
Section titled “My run stopped. Do I start over?”No. Run the same mapcv generate command; it resumes after the last completed chunk (details).
Can I add more area to an existing dataset?
Section titled “Can I add more area to an existing dataset?”Only if the new config produces the same raster grid, sampler and class map; otherwise resuming is refused. In practice, generate the new area into its own folder and combine the split lists in your loader.
Can I use several Sentinel-2 products, or a time series?
Section titled “Can I use several Sentinel-2 products, or a time series?”An eopf_zarr or stac_cog source reads one product, which mapcv can find for you with a STAC search (imagery.search) and whose clouds it can mask (scl_mask). For a time series, list several sources on the same grid, for example the same tile on different dates; writer.stack_sources writes them into one array per patch. mapcv does not mosaic several Sentinel-2 scenes into one; for a composite over a period, use Google Earth Engine.
Can I read private S3 buckets or signed URLs?
Section titled “Can I read private S3 buckets or signed URLs?”No. Remote GeoTIFF, label raster, STAC and EOPF URLs must be anonymous public https:// or s3:// URLs; credentials and query strings are rejected. Download the file first if it is private.
Where are the docs for mapcv 0.1?
Section titled “Where are the docs for mapcv 0.1?”The 0.1 tiles: block and region.zoom were removed in 0.3.0; mapcv validate names the replacement. The migration guide lists every change.