Metadata-Version: 2.4
Name: ecaio
Version: 0.2.2
Summary: Read-only access to EarthCARE data product files
Author-email: Edward Baudrez <edward.baudrez@meteo.be>
Project-URL: repository, https://gitlab.com/ebaudrez/ecaio
Project-URL: issues, https://gitlab.com/ebaudrez/ecaio/-/issues
Project-URL: releasenotes, https://gitlab.com/ebaudrez/ecaio/blob/main/ReleaseNotes.md
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENCE.txt
Requires-Dist: astropy
Requires-Dist: deprecated
Requires-Dist: gdal
Requires-Dist: geopandas
Requires-Dist: netCDF4
Requires-Dist: numpy
Requires-Dist: tomli>=1.1.0; python_version < "3.11"
Dynamic: license-file

# ecaio - Read-only access to EarthCARE data product files

## Synopsis

```
from ecaio import EcaioFilename, EcaioOpen, EcaioTime

# ecaio can work with .zip-compressed files directly:
my_msi_file = "ECA_EXAF_MSI_RGR_1C_20250219T114658Z_20250219T133232Z_04147D.ZIP"

# Or you can locate files by glob(). The following will try and locate the
# unique file that matches the following components, regardless of their
# extension, processing start time, or anything else that was not specified
# explicitly. If that doesn't work, an exception is raised.
my_msi_file = EcaioFilename.glob_unique(
    root_directory="/my/data/directory",
    baseline="AF",
    file_type="MSI_RGR_1C",
    frame="4147D",
)

# EcaioOpen automatically dispatches to the right subclass, if it recognizes
# the file type (currently, only M-NOM, M-RGR, and B-SNG); otherwise it opens
# the file as a generic EarthCARE file.
with EcaioOpen(my_msi_file) as msi:

    # access any header property (here, from the Main Product Header)
    description = msi.mph.description

    # access fields from /ScienceData with the following convenient syntax
    elevation = msi.surface_elevation

    # ecaio has built-in recipes for some quantities, like MSI TIR thermal
    # radiances (converted from brightness temperatures)
    thermal_radiance = msi.thermal_radiance

    # use EcaioTime to convert times in EarthCARE format to another format
    # (here, to Python standard library ‘datetime’)
    line_acquisition_times = EcaioTime.from_float(msi.time).to_datetime()
```

## Description

`ecaio` is a Python library for convenient access to the data stored in
EarthCARE data product files, together with derived quantities that can be
computed from those data products. The data within `.zip`-compressed data
product archives can be accessed transparently. Currently, access is read-only.
`ecaio` strives to be fast, by caching and performing vector operations where
possible, and convenient to use, by allowing you to retrieve data in few lines
of code, with a syntax that is (hopefully) easy to remember.

`ecaio` is not a library for plotting or analysis of EarthCARE data. There are
other libraries that are better suited for that (e.g., `pandas`, `matplotlib`,
and the tools listed under "See also" below), but `ecaio` strives to make it
easy to prepare your data for subsequent analysis and plotting with other
packages.

## Features

 - Work with `.zip`-compressed data product files directly
 - Convenient syntax for access to datasets under `/ScienceData`:
   `values = msi_rgr.pixel_values`
 - Data are cached to avoid the time penalty when re-using the same data
 - Recipes for a few derived quantities are already implemented, such as VNS
   reflectances from radiances, TIR radiances from brightness temperatures, RGB
   composites for MSI, narrowband-to-broadband conversion for MSI, computation
   of frame margins, etc.
 - Mask values from bad BBR detectors
 - Correct and convenient conversion of time stamps to and from EarthCARE
   format (i.e., float)
 - Generic file opening with `EcaioOpen()`
 - Convenient and fast spatial subsetting of data with `.subset_rectangle()`
 - Conversion to GDAL raster datasets with geolocation metadata, to process the
   data with [the GDAL library](https://gdal.org)

## Project development status and interface stability

`ecaio` is still under development, and its interface may change in the future.
Some features have not been implemented yet, and not all EarthCARE file types
are fully supported yet.

## Homepage

`ecaio` can be found at <https://gitlab.com/ebaudrez/ecaio>.

## Installation instructions

`ecaio` has not yet been uploaded to the Python Package Index, so for the time
being, the recommended way to install it is to grab a `.tar.gz` archive from
the Gitlab [release page](https://gitlab.com/ebaudrez/ecaio/-/releases), and to
install it using

```
pip install ecaio-x.y.z.tar.gz
```

where _x.y.z_ is the version you've downloaded.

## Bugs and known issues

No bugs have been reported so far. Please report bugs or feature requests at
<https://gitlab.com/ebaudrez/ecaio/-/issues>.

## See also

There are a number of other libraries that can ingest and process EarthCARE
data, with a different focus than `ecaio`:

- [ectools](https://bitbucket.org/smason/workspace/projects/EC) is a set of
  open tools for searching, loading, plotting, intercomparing and analysing
  EarthCARE data products, licensed under Apache 2.0
- [earthcarekit](https://github.com/TROPOS-RSD/earthcarekit) is a comprehensive
  toolkit for downloading, reading, analysing and visualizing data from
  EarthCARE, licensed under Apache 2.0

## Copyright and license

Copyright (C) 2025, 2026 Edward Baudrez <edward.baudrez@meteo.be>

This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0. If a copy of the MPL was not distributed with this
file, You can obtain one at https://mozilla.org/MPL/2.0/.
