Metadata-Version: 2.4
Name: sentineltoolbox
Version: 0.6.9
Author: ACRI-ST
License-Expression: Apache-2.0
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development
Classifier: Typing :: Typed
Requires-Python: <3.13,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: setuptools>=68.2.2
Requires-Dist: dask>=2023.11.0
Requires-Dist: distributed>=2023.11.0
Requires-Dist: xarray>=2024.11.0
Requires-Dist: numpy
Requires-Dist: zarr<3.0.0
Requires-Dist: fsspec[s3]>=2023.10.0
Requires-Dist: toml>=0.10.2
Requires-Dist: scipy
Requires-Dist: scikit-learn
Requires-Dist: tomli
Requires-Dist: colorlog
Requires-Dist: pandas
Requires-Dist: h5netcdf
Requires-Dist: h5py
Requires-Dist: eccodes>=1.7.1
Requires-Dist: ecmwflibs>=0.6.3
Requires-Dist: cfgrib>=0.9.10.4
Requires-Dist: geopandas
Requires-Dist: dacite
Requires-Dist: netcdf4>=1.6.5
Requires-Dist: rioxarray>=0.15.5
Requires-Dist: rasterio>=1.3.10
Requires-Dist: overrides
Requires-Dist: deepdiff
Requires-Dist: bs4
Requires-Dist: packaging
Requires-Dist: defusedxml
Requires-Dist: cql2
Provides-Extra: converter
Requires-Dist: eopf>=2.4.0; extra == "converter"
Provides-Extra: cluster-plugin
Requires-Dist: dask-jobqueue>=0.8.2; extra == "cluster-plugin"
Requires-Dist: dask-gateway>=2023.1.1; extra == "cluster-plugin"
Provides-Extra: tests
Requires-Dist: pytest<8; extra == "tests"
Requires-Dist: pytest-cov; extra == "tests"
Requires-Dist: hypothesis; extra == "tests"
Requires-Dist: pytest-error-for-skips; extra == "tests"
Requires-Dist: geopandas; extra == "tests"
Requires-Dist: dacite; extra == "tests"
Requires-Dist: lxml; extra == "tests"
Requires-Dist: jupytext; extra == "tests"
Requires-Dist: nbmake; extra == "tests"
Provides-Extra: linter
Requires-Dist: flake8; extra == "linter"
Provides-Extra: typing
Requires-Dist: mypy; extra == "typing"
Requires-Dist: types-python-dateutil; extra == "typing"
Requires-Dist: types-pytz; extra == "typing"
Requires-Dist: types-setuptools; extra == "typing"
Requires-Dist: types-toml; extra == "typing"
Requires-Dist: types-PyYAML; extra == "typing"
Requires-Dist: types-click; extra == "typing"
Requires-Dist: types-jinja2; extra == "typing"
Requires-Dist: types-colorama; extra == "typing"
Provides-Extra: formatter
Requires-Dist: black; extra == "formatter"
Requires-Dist: isort; extra == "formatter"
Provides-Extra: security
Requires-Dist: bandit; extra == "security"
Requires-Dist: safety; extra == "security"
Provides-Extra: notebook
Requires-Dist: jupyter>=1.0.0; extra == "notebook"
Requires-Dist: Jinja2>=3.1.2; extra == "notebook"
Requires-Dist: fonttools>=4.43.0; extra == "notebook"
Requires-Dist: matplotlib>=3.7.1; extra == "notebook"
Requires-Dist: itables; extra == "notebook"
Provides-Extra: doc
Requires-Dist: sphinx>=5.3.0; extra == "doc"
Requires-Dist: sphinx-autodoc-typehints>=1.22; extra == "doc"
Requires-Dist: sphinx_needs==5.1.0; extra == "doc"
Requires-Dist: jupyter-sphinx>=0.4.0; extra == "doc"
Requires-Dist: sphinx-book-theme>=1.0.1; extra == "doc"
Requires-Dist: sphinx-togglebutton>=0.3.2; extra == "doc"
Requires-Dist: sphinx-inline-tabs>=2023.4.21; extra == "doc"
Requires-Dist: sphinx-panels>=0.4.1; extra == "doc"
Requires-Dist: sphinx-test-reports==1.3.0; extra == "doc"
Requires-Dist: sqlalchemy>=2.0.0b1; extra == "doc"
Requires-Dist: myst-nb>=0.17.2; extra == "doc"
Requires-Dist: linkify-it-py>=2.0.0; extra == "doc"
Requires-Dist: numpydoc>=1.5.0; extra == "doc"
Requires-Dist: jupytext>=1.14.5; extra == "doc"
Requires-Dist: urllib3>=1.26.17; extra == "doc"
Requires-Dist: breathe>=4.35.0; extra == "doc"
Requires-Dist: sphinxcontrib-apidoc>=0.3.0; extra == "doc"
Requires-Dist: sphinxcontrib-spelling>=8.0.0; extra == "doc"
Requires-Dist: sphinxcontrib.plantuml; extra == "doc"
Requires-Dist: sphinxcontrib.mermaid; extra == "doc"
Requires-Dist: sphinx_copybutton>=0.5.2; extra == "doc"
Requires-Dist: GitPython>=3.1.41; extra == "doc"
Requires-Dist: nbsphinx>=0.9.1; extra == "doc"
Requires-Dist: mdutils>=1.6.0; extra == "doc"
Requires-Dist: tomark>=0.1.4; extra == "doc"
Requires-Dist: sphinxcontrib.mermaid; extra == "doc"
Provides-Extra: complexity
Requires-Dist: xenon>=0.9.1; extra == "complexity"
Provides-Extra: doc-cov
Requires-Dist: docstr-coverage>=2.2.0; extra == "doc-cov"
Provides-Extra: dev
Requires-Dist: pre-commit>=3.5.0; extra == "dev"
Requires-Dist: sentineltoolbox[complexity,doc-cov,tests]; extra == "dev"
Requires-Dist: sentineltoolbox[formatter,linter,typing]; extra == "dev"
Requires-Dist: sentineltoolbox[doc,notebook,security]; extra == "dev"
Requires-Dist: sentineltoolbox[cluster-plugin]; extra == "dev"
Requires-Dist: matplotlib; extra == "dev"
Dynamic: license-file

<!--
  Copyright 2024-2026 ACRI-ST

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->

# sentineltoolbox

[![Code Style][black-badge]][black-link]
[![Documentation][doc-badge]][doc-link]

**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](https://sentiwiki.copernicus.eu/web/).

## 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

```bash
pip install eopf-cpm>=2.4
pip install sentineltoolbox
```

For development (editable install):

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

## Quick start

```python
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](LICENSE) file for details.

## Copyright

Copyright 2024-2026 ACRI-ST.

[black-badge]: https://img.shields.io/badge/code%20style-black-000000.svg
[black-link]: https://black.readthedocs.io/en/stable/
[doc-badge]: https://img.shields.io/badge/documentation-passed-blue.svg
[doc-link]: https://DPR-ACR.pages.eopf.copernicus.eu/sentineltoolbox
