Published October 5, 2026
| Version v0.2.0
Software
Open
tahamukhtar20/mapcv: v0.2.0
Authors/Creators
- 1. National Center of Artificial Intelligence, Deutsches Forschungszentrum für Künstliche Intelligenz
Description
mapcv 0.2 adds Sentinel-2 imagery, leakage-safe dataset splits and Python 3.14 support, and fixes several ways 0.1 could silently produce wrong datasets. See MIGRATION.md before upgrading: configs and datasets need small changes.
Highlights
- EOPF Sentinel-2 L2A Zarr input (
pip install "mapcv[zarr]"): lazy windowed reads, band selection, 10/20/60 m harmonization on the product's own pixel grid, labels aligned in the native UTM CRS, and bands-firstfloat32NPY patches. - Leakage-safe splits by default. The new
spatialstrategy keeps whole raster blocks in one split and leaves out train/val patches that overlap a held-out patch, so test scores are not inflated by shared pixels. - Python 3.14 and one wheel per platform. Stable-ABI (abi3) wheels cover Python 3.10 and newer on Linux (x86-64 and aarch64, glibc and musl), macOS and Windows, so Docker on Apple Silicon, AWS Graviton, Raspberry Pi and Alpine install without a Rust toolchain.
- Bounded memory for large regions. XYZ tiles are fetched per chunk instead of all at once; labels and resume compatibility are checked before the first download, and a resumed run fetches only the chunks it still needs. Labels are reprojected in one pass and each chunk rasterizes only the polygons near it.
- Stable class IDs. Integer labels are used as mask values, other labels are numbered in sorted order, and
labels.classespins IDs explicitly. - A CLI that walks you through it.
mapcv initasks about imagery, area, zoom and labels and writes a commented config;mapcv planestimates tiles, patches, download size and memory without downloading;generatepreviews the plan, asks before large jobs and ends with a summary of files, classes and splits;mapcv infodescribes an existing dataset. - Manifest version 2 records the source, product, bands, dtype, patch shape, CRS, affine transform and sampler settings.
Breaking changes
- New
imagery:block (type: xyzoreopf_zarr);imagery.typeis required. - Unknown config keys are errors instead of being ignored, and
sourceandurl_templatecannot both be set. - Relative paths in a config resolve against the config file's folder, not the working directory.
mapcv initwritesmapcv.yamlunless given a path;--stdoutprints the config instead.- The built-in
google_satelliteandosmtile presets are removed (provider terms forbid bulk downloading); configs using them fail validation with an explanation. - The default split strategy is
spatialinstead ofstratified. - Class IDs no longer follow feature order; set
labels.classesto reproduce 0.1 IDs. sampler.mode: randomdrawsrandom_countpatches in total rather than per strip, and grid patches may cross former strip seams.- 0.1 datasets (manifest v1) can still be split but not resumed; resuming any dataset requires the same imagery, label file, label settings, sampler and writer settings.
max_failed_ratioapplies to each chunk of tiles rather than the whole region.- Removed Python APIs:
download_region_strips,iter_tile_strips,TilesConfigandhello().sample_patchesremains, and its metadata now includesempty_ratio. - The
zarrextra supports Python 3.10–3.13 until its zarr 2 dependency ships Python 3.14 wheels.
Deprecations
region.zoomand thetilesblock are accepted with a deprecation notice and will be removed in 0.3.0.
Fixes
Datasets and resume
- Save the manifest after every chunk and overwrite orphaned files from interrupted runs, so a resume can no longer pair entries with the wrong files.
- Count black or failed XYZ tiles as empty for
max_empty_ratioagain. - Refuse to resume when the label file or the writer settings changed, and refuse manifests written by a newer mapcv.
- A resumed run records the same chunk index for each patch as an uninterrupted one; Ctrl-C during
generatesays how to resume. - Warn when failed tiles were filled with black inside kept patches (
sampler.max_empty_ratio: 1), where masks still carry labels. - Record how a split was made in
splits/split.json; split lists end with a newline. stratifiedsplits now stratify the train/val/test assignment (by labeled fraction and dominant class), not only the subsample; labeled-ratio folders are named exactly (0.29→29/) and stale split lists are overwritten.
Labels
- More than 255 classes is an error instead of wrapping KML IDs to background or reusing class 1;
3and3.0are one class. - Read QGIS/ogr2ogr
<SimpleData>labels, tolerate spaces after commas in coordinates, keep polygons inside GeometryCollections, and put the outer ring first. - Reject projected GeoJSON
crsmembers, truncated KML, non-finite coordinates and unsupported label files (.kmz,.shp) instead of producing empty masks. - Warn with counts when features are skipped and when no label intersects the imagery.
Tile downloads
- Say why tiles failed: errors and warnings group failures by cause (HTTP status, timeout, non-image response) with one example URL.
- Retry truncated responses and apply the failure policy instead of aborting the run; count HTML error pages and empty bodies as failed tiles.
- Honour
Retry-Afterwith jittered backoff, identify requests with a contact URL, and enforcemax_failed_ratiofor any capitalization oflenient. - Validate
url_templateplaceholders when the config loads (for example, a leftover{s}).
EOPF
- Retry Sentinel-2 window reads up to 4 times when the object store times out or a band comes back empty, instead of failing the run on the first error.
- A band that fails to read is an error instead of a silent all-NaN band, and a pixel is valid only when every band has data.
- Accept Windows drive and
file:///C:/paths; reject URLs with credentials, query strings or fragments at validation.
Security
- Update quick-xml to 0.42, fixing quadratic parse time on KML with many duplicate attributes (RUSTSEC-2026-0194); also update rustls (RUSTSEC-2026-0285) and crossbeam-epoch (RUSTSEC-2026-0204).
- Build the image crate with only the PNG, JPEG, WebP and GIF codecs, dropping 56 dependencies including the unmaintained
paste.
CLI and security
- On Windows, redirected or piped output (
mapcv plan x.yaml > plan.txt, CI logs) no longer crashes withUnicodeEncodeError. - Print each warning once, also under
--quiet; warn when most tiles fail underpolicy: ignore; say why a resume was refused. mapcv.__version__, and uppercase argument names in--helpwith Typer 0.27.- Keep secrets out of manifests and
mapcv validateoutput; show deprecation notices; report generation errors without a traceback;mapcv initlinks the provider guidance.
Documentation
- A rebuilt documentation site organised around getting from zero to a dataset: quickstart, tutorials, how-to guides, a full CLI and configuration reference, and a new logo.
examples/: an Esri + OpenStreetMap quickstart, Sentinel-2 land cover, notebooks for exploring a dataset and training a model, and scripts for the Python API and a PyTorch dataset.PROVIDERS.mdon imagery licensing, provider terms and credentials;MIGRATION.md.
Packaging and CI
- PyO3 0.29, committed
Cargo.lockand--lockedbuilds; project URLs, keywords and dependency floors on PyPI; a 0.2 MB sdist (was 4.5 MB). - CI tests Python 3.10–3.14 with branch coverage; releases are cut only from
main, test every wheel and the sdist, wait for approval before publishing, and use this changelog as release notes. - Release artifacts carry build provenance (
gh attestation verify <file> --repo tahamukhtar20/mapcv);SECURITY.mddescribes how to report vulnerabilities privately. - PR-title policy, grouped Dependabot updates, an EOPF smoke-test workflow and issue/PR templates.
Files
tahamukhtar20/mapcv-v0.2.0.zip
Additional details
Related works
- Is supplement to
- Software: https://github.com/tahamukhtar20/mapcv/tree/v0.2.0 (URL)
Software
- Repository URL
- https://github.com/tahamukhtar20/mapcv