sentineltoolbox

sentineltoolbox (stb) is a Python library for manipulating Copernicus Sentinel satellite products. It provides I/O, conversion, documentation generation, validation and convenience utilities on top of xarray.DataTree.

Sentinel products are described in the Copernicus Programme documentation.

Stable API

API stability is a core principle of sentineltoolbox: users must be able to upgrade to a newer version without rewriting any code.

All symbols exported by {obj}sentineltoolbox.api and {obj}sentineltoolbox.typedefs are stable. Stability is All other modules are internal and must not be used directly. See {doc}overview for the full feature list.

Installation

pip install eopf-cpm>=2.6
pip install sentineltoolbox

For development (editable install):

git clone <repository_url>
pip install -e ".[dev]"

uv

This project can use uv for dependency locking. The lockfile (uv.lock) resolves optional extras separately when they have incompatible requirements (see tool.uv.conflicts in pyproject.toml).

Runtime-only install (zarr v3, no eopf — default):

uv sync

Runtime-only with zarr v2 (no eopf). Cannot be combined with dev or zarr-v3:

uv sync --extra zarr-v2

Runtime-only with an explicit zarr v3 pin (same outcome as plain uv sync, no eopf):

uv sync --extra zarr-v3

Full development environment (zarr v3, no eopf, plus linters, tests, docs, etc.):

uv sync --extra dev

With eopf 2.x (>=2.6.0, zarr v2). Use a dedicated environment; this extra cannot be combined with dev or zarr-v3:

uv sync --extra converter-v2 --no-dev

With eopf 3.x (pre-release, Python 3.13+, zarr v3 compatible). Cannot be combined with converter-v2:

uv sync --extra converter --prerelease=allow --python 3.13

Optional extras:

Note — eopf 2.x (converter-v2) on Python 3.13

eopf 2.x pins rasterio==1.3.10, which has no Python 3.13 wheel and cannot be built from source in practice. The converter-v2 extra is therefore a priori incompatible with Python 3.13 when using pip.

uv on Python 3.13: installation works using uv because tool.uv.override-dependencies in pyproject.toml relaxes the rasterio pin to >=1.3.11.

pip on Python 3.11 or 3.12: use the converter-v2 extra directly:

pip install ".[converter-v2]"

Quick start

from sentineltoolbox.api import open_datatree, display

xdt = open_datatree("path/to/product.zarr")
display(xdt)

Features

Open products, ADFs and other data files

Open DPR Zarr, JSON, or legacy SAFE/SEN3 data as DataTree or Dataset:

• open_datatree, load_datatree — open/load a product as xarray.DataTree
• open_json — open JSON
• load_metadata load only metadata (very quick) from zarr and replace arrays with 1 element fake arrays.

Generate HTML documentation for products

Create rich interactive HTML summaries of DPR products directly in Jupyter or Sphinx:

• display — render a DataTree as an HTML table with metadata, flags, and structure
• print_summary — compact text summary

Convert legacy products

Convert original S2/S3 products (.SAFE, .SEN3) and ADF to DPR Zarr format (.zarr):

• Supported products (via eopf-cpm mappings): S3 OLCI (EFR, ERR, LFR), S3 SLSTR (RBT, FRP, LST), S3 SYNERGY (AOD, SYN, VG1, VGP, VGK, V10), S2 MSI (L1A, L1B, L1C, L2A)
• Supported ADF (internal converters): S3 OLCI, SLSTR, SYNERGY
• CLI: stb_convert_products, stb_eop_convert_products

Flag operations

Bitwise operations on CF-convention flag arrays:

• create_flag_array — create a flag array with a given shape and bit depth
• update_flag — set or clear individual flags
• get_flag — extract a boolean mask for a given flag

Parse and generate product file names

• ProductFileNameGenerator, AdfFileNameGenerator — build DPR-compliant file names from legacy names
• detect_filename_pattern, filename_generator — detect product and ADF filename patterns (legacy, dpr) and instantiate generators

DataTree utilities

• AttributeHandler — set, extract, and fix product attributes
• DataTreeHandler — high-level wrapper for product metadata and attributes (derived from AttributeHandler)
• get_array, get_datatree — type-safe node access (no mypy errors)
• convert_to_datatree — convert dict, Dataset, or EOProduct to DataTree
• validate_datatree — validate structure, dtypes and attributes against a schema
• patch_datatree — apply patches to a DataTree

Check processor inputs

Verify consistency of input products and ADFs before processing:

• check_processor_inputs, check_adfs

Filesystem and credentials

Browse local or S3 filesystems transparently:

• get_universal_path, get_fsspec_filesystem, get_url_and_credentials
• S3BucketCredentials

Sentinel metadata databases

Cached, extensible JSON/TOML databases of product metadata, properties, naming conventions, and namespaces.

Environment and logging

• init, init_jupyter_env — set up logging, xarray display, IPython formatters
• LoggerSuppressor, WarningsSuppressor — context managers for quiet execution

Command Line Tools

• stb_convert_products — convert SAFE/SEN3 ADF and products (deprecated) to DPR Zarr
• stb_eop_convert_products — same using EOPF/CPM mappings
• stb_compare_products — compare two products and summarize differences
• stb_dump_product — dump product summary

API stability

Only symbols re-exported from sentineltoolbox.api are considered stable. All other modules are internal and may change without notice.

Documentation

Full documentation: https://DPR-ACR.pages.eopf.copernicus.eu/sentineltoolbox

License

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for details.

Copyright

Copyright 2024-2026 ACRI-ST.