xarray-enmap 0.0.3

xarray backend for EnMAP data archives

xarray-enmap

An xarray backend to read the data archives provided by the EOWEB data portal of the EnMAP mission.

Installation

With mamba or conda

mamba install xarray-enmap

or

conda install xarray-enmap

⚠️ Starting with release 0.0.3, xarray-enmap includes the command-line tool convert-enmap. If you wish to use convert-enmap, you should also install the optional packages zarr and numcodecs.

With pip

⚠️ xarray-enmap requires the gdal library, which cannot be installed with pip. If you're working in a conda environment, you can use conda or mamba to install the libgdal-core package before starting the pip install. See the GDAL documentation for other installation methods.

To install the basic package:

pip install xarray-enmap

If you want to export Zarr archives using the included command-line tool convert-enmap (available from release 0.0.3):

pip install xarray-enmap[zarr]

Development install from the git repository

Clone the repository and set the current working directory:

git clone https://github.com/bcdev/xarray-enmap.git
cd xarray-enmap

Install the dependencies with mamba or conda:

mamba env create
mamba activate xarray-enmap

Install xarray-enmap itself:

pip install --no-deps --editable .

Usage as an xarray extension

import xarray as xr

enmap_dataset = xr.open_dataset(
    "/path/to/enmap/data/filename.tar.gz",
    engine="enmap",
    backend_kwargs={"scale_reflectance": False}
)

The optional scale_reflectance keyword argument controls whether the reflectance values are left as raw values or scaled to the range 0–1. When they are scaled, the special background value of −32768 in the raw data is also replaced with NaN. scale_reflectance is True by default, so you can simply omit it if you want the reflectances scaled.

⚠️ Theoretically, the raw reflectance values in an EnMAP file should be between 0 and 10000. In practice, some real-world EnMAP products contain a few values outside this range, which will also result in values outside the 0–1 range after scaling.

The supplied path can reference:

• a .tar.gz archive as provided by the EnMAP portal, containing one or more EnMAP products in .ZIP sub-archives, or
• a .ZIP archive containing a single product, as found within an EnMAP .tar.gz archive, or
• a directory contained the unpacked contents of either of the aforementioned archive types.

At present, if the archive or directory contains multiple EnMAP products, xarray-enmap will open only the first.

In addition to the standard band index co-ordinate containing the band number, xarray-enmap creates an additional wavelength co-ordinate which can be used to index by the corresponding band's centre wavelength. So you can do things like

enmap_dataset.reflectance.sel(wavelength=slice(950, 1000))

to select data for a particular wavelength range.

Usage of the command-line tool convert-enmap

Note that, to use the --zarr-output option, you must install the appropriate optional packages (see installation instructions).

usage: convert-enmap [-h] [--zarr-output ZARR_OUTPUT]
                     [--tiff-output TIFF_OUTPUT] [--raw-reflectance]
                     [--tempdir TEMPDIR] [--compress] [--datatree] [--verbose]
                     input_filename

Extract data from EnMAP archives. The expected input is an Zip archive, or a
.tar.gz archive of multiple Zip archives, downloaded from the EnMAP portal.
Output can be written as TIFF, Zarr, or both.

positional arguments:
  input_filename        Either a Zip for a single product, or a .tar.gz
                        containing multiple Zips

options:
  -h, --help            show this help message and exit
  --zarr-output ZARR_OUTPUT
                        Write Zarr output to this directory.
  --tiff-output TIFF_OUTPUT
                        Write TIFF output to this directory.
  --raw-reflectance, -r
                        Use raw reflectance values rather than rescaling to
                        0-1 range.
  --tempdir, -t TEMPDIR
                        Use specified path as temporary directory, and don't
                        delete it afterwards (useful for debugging)
  --compress, -c        Higher Zarr output compression. ~25% smaller than
                        default compression. Compression process (but not
                        decompression) is much slower.
  --datatree, -d        Whether to write the data as datatree. This parameter
                        is only considered when the parameter zarr-output is
                        given.
  --verbose, -v

⚠️ The --zarr-output and --tiff-output arguments specify the parent directory for any output files. So e.g. specifying --zarr-output myzarrs will not produce a Zarr called "myzarrs", but a directory called "myzarrs" which contains one or more Zarr archives as subdirectories.