Metadata-Version: 2.4
Name: s2cube
Version: 0.2.0
Summary: Build co-registered, leakage-safe Sentinel-2 time-series datasets for machine learning
Author-email: Cao Vu Bui <vubc@fe.edu.vn>
License: MIT License
        
        Copyright (c) 2026 Cao Vu Bui and the s2cube contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/vubcfe/s2cube
Project-URL: Documentation, https://s2cube.readthedocs.io
Project-URL: Issues, https://github.com/vubcfe/s2cube/issues
Keywords: Sentinel-2,remote sensing,time series,co-registration,machine learning,spatial cross-validation,STAC,dataset
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy>=1.22
Requires-Dist: scipy>=1.8
Requires-Dist: h5py>=3.6
Requires-Dist: rasterio>=1.3
Requires-Dist: shapely>=2.0
Requires-Dist: requests>=2.25
Requires-Dist: pyyaml>=5.4
Requires-Dist: pillow>=9.0
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Provides-Extra: docs
Requires-Dist: mkdocs<2,>=1.5; extra == "docs"
Requires-Dist: mkdocs-material<10,>=9; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
Provides-Extra: dev
Requires-Dist: s2cube[docs,test]; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# s2cube

**Build co-registered, leakage-safe Sentinel-2 time-series datasets for machine learning.**

[![tests](https://github.com/vubcfe/s2cube/actions/workflows/tests.yml/badge.svg)](https://github.com/vubcfe/s2cube/actions/workflows/tests.yml)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23240761.svg)](https://doi.org/10.5281/zenodo.23240761)
[![docs](https://readthedocs.org/projects/s2cube/badge/?version=stable)](https://s2cube.readthedocs.io/en/stable/)
[![PyPI](https://img.shields.io/pypi/v/s2cube.svg)](https://pypi.org/project/s2cube/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE.txt)

`s2cube` turns a list of field sites and label polygons into an analysis-ready Sentinel-2 L2A
time series, stored in one HDF5 file, together with pixel labels and spatially separated
cross-validation splits. It is written for researchers who train (self-)supervised models on
satellite image time series and need the dataset to be **correct**, **reproducible** and
**free of spatial leakage**:

| Problem in practice | What s2cube does |
|---|---|
| Dates of the same place are misaligned by 3-15 m (one or more 10 m pixels) | measures the offset of every date by gradient cross-correlation on many locations, corrects reliable offsets by re-reading the original scenes on a shifted grid, and verifies the result |
| 20 m bands are interpolated to 10 m, values change across ESA processing baselines | 20 m bands are replicated 2 x 2 (never interpolated); DN offsets are removed per scene |
| Re-running a download months later silently gives different scenes | dates and exact scene URLs are frozen into the file at creation; downloads resume from that record ; `scenes_from` re-creates a dataset on the same scenes |
| Some products were not geometrically refined by ESA | `s2cube info --refinement` records ESA's GRI refinement flag per date |
| Labels drawn on one year's imagery are reused for other years | per-polygon, per-year index check flags land-use change; those pixels are ignored only in the affected year |
| Random splits put neighbouring pixels in train and test | sites closer than a linkage distance stay in one fold; every fold is checked for a minimum test/train gap; nested label budgets (5 % in 10 % in 50 % ...) |
| Unlabelled data for pretraining overlaps labelled sites | random windows are drawn at a guaranteed distance from every labelled site |

## Installation

```bash
pip install s2cube                       # from PyPI
# or, from source
git clone https://github.com/vubcfe/s2cube && cd s2cube
pip install -e ".[test]"
```

Requirements: Python >= 3.9, and the wheels of `numpy`, `scipy`, `h5py`, `rasterio` (bundles
GDAL/PROJ), `shapely`, `requests`, `pyyaml`, `pillow`. Linux, macOS and Windows are supported.
No account or API key is needed: data are read from the public STAC catalogues of Microsoft
Planetary Computer (default) or Element 84 Earth Search on AWS.

## Quick start

```bash
cd examples/minimal               # 4 crop sites in Flevoland (NL), May-June 2025
python ../netherlands/get_labels.py --bbox 5.60 52.50 5.68 52.55 --out brp.geojson
s2cube plan   project.yaml        # grids + available dates (nothing downloaded)
s2cube build  project.yaml        # ~3 min, resumable
s2cube coreg  project.yaml        # measure -> correct -> verify geolocation
s2cube labels project.yaml        # labels.h5
s2cube splits project.yaml        # splits.json
s2cube info   project.yaml        # summary + dates.csv
s2cube manifest project.yaml      # MANIFEST.sha256
```

In Python:

```python
from s2cube import Cube, reflectance
from s2cube.datasets import LabeledBlocks, UnlabeledWindows

with Cube("cube.h5") as c:
    print(c.dates[:3], c.bands, c.sites)
    X, scl = c.site(c.sites[0])            # (T, B, H, W) uint16, (T, H, W) uint8
    r = reflectance(X)                     # float32 reflectance, NaN = no data

train = LabeledBlocks("cube.h5", "labels.h5", "splits.json", fold=0, role="train", ratio=0.1, seed=0)
X, valid, y = train[0]                     # works with torch.utils.data.DataLoader
pretrain = UnlabeledWindows("cube.h5")
```

## Outputs

| File | Content |
|---|---|
| `cube.h5` | `/sites/<id>/X (T,B,H,W)`, `/sites/<id>/SCL`, `/unlabeled/X (N,T,B,w,w)`, dates, per-date scene provenance, QA fractions, `/coreg/*` |
| `labels.h5` | per site: class cover fractions, hard labels (255 = ignore), per-year labels and drift flags, block ids |
| `splits.json` | folds (test/val/train sites, measured gaps), nested label budgets per seed, leakage checks |
| `dates.csv` | per date: platform, cloud cover, observed valid/clear fraction, co-registration status and offsets |
| `MANIFEST.sha256` | checksums of all products (`sha256sum -c` compatible) |

The full layout is documented in [docs/data_format.md](docs/data_format.md).

## Documentation

Online: **https://s2cube.readthedocs.io**

* [Installation](docs/installation.md)
* [Tutorial](docs/tutorial.md)
* [Configuration reference](docs/configuration.md)
* [Data format](docs/data_format.md)
* [Methods](docs/methods.md) (co-registration, label drift, spatial splits)
* [Recommended settings](docs/settings.md)
* [API reference](docs/api.md)
* [Limitations and FAQ](docs/faq.md)

## Tests

```bash
pytest                      # offline: synthetic scenes written as local GeoTIFFs (~5 s)
pytest -m network           # also query the real STAC catalogues (needs internet)
```

The offline suite builds a complete dataset from synthetic scenes with a known displacement
and checks, among others, exact pixel values, the recovery and correction of the displacement,
labels, fold separation and nested subsets.

## Citing

If you use s2cube, please cite the software paper (see [CITATION.cff](CITATION.cff)).

## License

MIT, see [LICENSE.txt](LICENSE.txt). Sentinel-2 data are provided by the European Union's Copernicus
programme under its free and open data policy. When using a web-map tile service as
co-registration reference (`coreg.reference: xyz`), respect that provider's terms of use.
