- If you use stac2cube in your research, you are kindly asked to cite it. Thank you!
See: Citation - Free software: Apache 2.0
- This software is designed to function on any local-machine and also HPC system using SLURM jobs.
- Feature Overview
- Installation
- How to run
- How to run on HPC
- Access and Licensing Details for STAC Catalogs
- Method References
- Citation
stac2cube converts SpatioTemporal Asset Catalogs (STAC) into Analysis-Ready Data (ARD) cubes for efficient Earth Observation (EO) processing.
For Sentinel-2, the ARD cubes are built with three main components:
-
Cloud masking based on user-defined thresholds. This lets users control how strict cloud detection should be and export multiple cloud-masked cubes. Traditional options like filtering by max_cc (STAC metadata) and masking with the Scene Classification Layer (SCL) are also supported for faster processing.
- Cloud shadow masking following the Google Earth Engine s2cloudless tutorial: clouds are projected along the anti-solar direction using the per-scene mean solar azimuth from the STAC metadata, and dark non-water NIR pixels inside that projection are flagged as shadow. Returns cloud, shadow and combined masks on the exact cube grid, with optional masking of the cube.
-
Co-registration to reduce scene-to-scene X/Y misalignment (often around 1-2 pixels). Small sub-pixel shifts (below 10 m) can still remain.
-
Super-resolution of both 10-meters and 20-meters bands to 2.5 meters. Another option is 20-meters bands super-resolution to 10-meter.
The result is a data cube that is cloud-masked with customizable thresholds, spatially aligned across time, and available at higher spatial resolution. Details about the underlying algorithms and how to cite the used third-party tools can be found in the Examples section.
Installation is possible with package managers like Micromamba & Anaconda.
git clone https://github.com/BaturalpArisoy/stac2cube.git
If git is not available for you, download and unzip the file: https://github.com/BaturalpArisoy/stac2cube/archive/refs/heads/main.zip
cd "path/to/stac2cube/"
environment.yml file should be present in this path, please double check.
micromamba env create -n stac2cube -f environment.yml
micromamba env create -n stac2cube -f environment.yml; micromamba install -n stac2cube -c conda-forge vs2015_runtime
conda env create -n stac2cube -f environment.yml && conda activate stac2cube && conda install -c conda-forge vs2015_runtime
Linux users (including HPC systems such as terrabyte) can skip this section - the installation above already comes with a CUDA-enabled PyTorch, and super-resolution automatically uses an NVIDIA GPU if one is present.
This step is only needed on Windows, where the default PyTorch is CPU-only: super-resolution runs on the CPU (it works, just slowly) until you swap in the CUDA build below. Once installed, the code detects and uses the GPU automatically.
First, check that you have a CUDA-capable NVIDIA GPU:
nvidia-smi
If it prints a table showing your NVIDIA GPU and a CUDA version of 12.x, you are ready to continue. If the command is not found, you do not have an NVIDIA GPU or driver, so stay on the CPU build.
Then replace the CPU PyTorch in the stac2cube environment with the matching CUDA build:
micromamba run -n stac2cube pip install torch==2.2.2+cu121 torchvision==0.17.2+cu121 --index-url https://download.pytorch.org/whl/cu121
conda run -n stac2cube pip install torch==2.2.2+cu121 torchvision==0.17.2+cu121 --index-url https://download.pytorch.org/whl/cu121
Verify that the GPU is detected:
micromamba run -n stac2cube python -c "import torch; print(torch.__version__, '| CUDA available:', torch.cuda.is_available())"
It should print a build ending in +cu121 and CUDA available: True.
Notes
- The CUDA build downloads ~2.4 GB of GPU libraries, which is why it is not installed by default.
- The same build also runs on machines without a GPU (it falls back to the CPU), so it is safe to use in a shared environment.
The recommended way to run stac2cube is through the interactive GUI tools in the User Interface Tools notebook. It bundles the full workflow in one place and requires no manual coding.
Just set the parameters and enjoy your coffee while your data cube is being built :)
- Data Cube Builder - area, date range, bands and indices, the STAC catalogue to pull from, cloud masking, scene filters and temporal composites. Exports to NetCDF, Zarr or GeoTIFFs, and the settings of any cube can be copied out as a JSON config to re-run later or as an HPC job.
- Available missions: Sentinel-2 L2A, Sentinel-2 L1C, Sentinel-1 RTC
- Data Cube Editor - clip, reproject, slice, filter and mosaic an existing cube, inspect it with the time viewer and animations, and extend it with new dates or bands without rebuilding it from scratch.
- Analysis Ready Data Cube Tools - probabilistic cloud masking, cloud shadow masking, co-registration and super-resolution.
If you want to script stac2cube or see what the interface does in the background, the tutorials folder documents the Python API function by function: building and updating cubes, cloud and shadow masking, co-registration, super-resolution, and comparing scene availability across catalogues. The interface covers the same ground with less setup, so start there unless you specifically need the code.
A documentation file on how to use stac2cube features on terrabyte's HPC for compute-intensive processes and for faster processing time can be found in the slurm folder. It is super simple once the instruction is followed.
Tip
You can copy settings from User Interface and directly paste to .json file to run fast and easy!
- Important: terrabyte STAC catalogs can be only computed when working on a terrabyte environment.
- However, stac2cube package is designed to work on both local-machine without terrabyte connection and within terrabyte HPC environment.
- The user can select the desired STAC source (also in user interface).
- Note that stac2cube package can not guarantee unlimited access to these open-access data catalogs in the future!
| Provider | Service | STAC API | License | Open-Access | Requires Credentials |
|---|---|---|---|---|---|
| DLR | terrabyte | https://stac.terrabyte.lrz.de/public/api/ | MIT License Copyright (c) 2024 Deutsches Zentrum für Luft- und Raumfahrt e.V. | No | Yes |
| Element 84 | Earth Search | https://earth-search.aws.element84.com/v1/ | Apache License 2.0 | Yes | No |
| Microsoft | Planetary Computer | https://planetarycomputer.microsoft.com/api/stac/v1 | MIT License Copyright (c) Microsoft Corporation. | Yes | No |
| ESA | Copernicus Data Space Ecosystem | https://stac.dataspace.copernicus.eu/v1 | Copernicus data - free, full and open access (Legal notice on the use of Copernicus data) | Yes | Yes |
-
Cloud Mask Data Cube applies s2cloudless by Sentinel Hub - CC-BY-SA-4.0 license.
-
Co-register Data Cube applies AROSICS by Daniel Scheffler - Apache-2.0 license.
Daniel Scheffler. (2017, July 3). AROSICS: An Automated and Robust Open-Source Image Co-Registration Software for Multi-Sensor Satellite Data (Version 0.12.1). Zenodo. https://doi.org/10.5281/zenodo.3742909
-
Super-resolve Data Cube applies SEN2SR by Aybar et al. - CC0-1.0 license.
Aybar, C., Contreras, J., Donike, S., Portalés-Julià, E., Mateo-García, G., & Gómez-Chova, L. (2026). A radiometrically and spatially consistent super-resolution framework for Sentinel-2. Remote Sensing of Environment, 334, 115222. https://doi.org/10.1016/j.rse.2025.115222
Arisoy, B., Betz, F., Stauch, G., Klein, D., Dech, S., and Ullmann, T.: Scalable Earth Observation Data Cubes for Advanced Analytics of Dynamic Earth Surface Processes: An Open-Source Package for Customized Processing of Sentinel-2 Data on HPCs and Beyond, EGUsphere [preprint], https://doi.org/10.5194/egusphere-2026-619, 2026.
Please include the exact version
Arisoy, B., Betz, F., Stauch, G., Klein, D., Dech, S., & Ullmann, T. (2026). stac2cube (Version 1.5.0). Zenodo. https://doi.org/10.5281/zenodo.20666787
https://www.geographie.uni-wuerzburg.de/en/earthobservation/staff/baturalp-arisoy/