enmap-downloader 0.6.0

Downloader for EnMAP data products with STAC

Downloader for EnMAP data products with STAC

• Free software: EUPL-1.2

• Documentation: https://global-land-monitoring.git-pages.gfz-potsdam.de/enmap_downloader/doc/

Status

See also the latest coverage report and the pytest HTML report.

Feature overview

The EnMAP Downloader is a Python-based tool designed to streamline access to hyperspectral imagery from the Earth Observation Center (EOC). It provides a flexible and efficient interface for searching, downloading, and preparing EnMAP data tailored to user-defined spatial and temporal criteria.

🌐 Download Hyperspectral EnMAP Data

• Fetches .tif hyperspectral datasets (EnMAP L2A) directly from the EOC archive.

🗺️ User-Defined Spatial Parameters

• Accepts a a single GeoJSON, or a folder of multiple GeoJSON files — each is handled automatically and clipped to the defined area.

🕒 User-Defined Temporal Filtering

• Specify a date range to download only the scenes captured within that timeframe.

⚡ Multithreaded Downloads

• Utilizes parallel downloading to significantly speed up large or batch operations on e.g. clusters.

📂 Batch Processing of Multiple AOIs

• Efficiently processes multiple areas of interest in one go, especially useful for regional or project-wide data collection.

💾 Flexible Output Formats

• Outputs data as GeoTIFFs (.tif) or NumPy arrays (.npy)—choose based on your workflow.

🔐 Authentication & Config File Support

• Includes authentication checks and a customizable config file for repeatable, automated use.

✅ Typical Use Cases

• 🛰️ Collecting hyperspectral scenes for machine learning and remote sensing projects

• 🗃️ Handling a large folder of AOIs automatically for environmental or urban monitoring

• 🔄 Automating scheduled or repeatable data collection workflows

History / Changelog

You can find the protocol of recent changes in the EnMAP Downloader package here.

Credentials

To access the EnMAP data, you need to have a valid EOC account. You can register for an account at the EOC website. When running the code for the first time, a .env file will be created in the root directory of the package. This file will contain the following variables:

ENMAP_USERNAME=USERNAME
ENMAP_PASSWORD=PASSWORD

You can edit this file to securely add your EOC credentials. The package will automatically read the credentials from this file when executing the code.

Important: This file contains sensitive information. To protect your credentials, keep it private and do not share it with others.

The package requires valid credentials to function properly. If the credentials are missing or incorrect, you will receive an error message.

Once saved, your credentials will be stored in the .netrc file in your home directory. This means you won’t need to enter them again for future runs.

Quick Installation

To install the package, clone it into a local directory and run the following command:

python -m pip install .

Alternatively you can create a conda environment and install the package with its dependencies:

conda env create -f environment_enmap_downloader.yml
conda activate enmap_downloader
pip install .

Make sure to create a config.json file in the config directory. You can use the provided example file as a template. The config.json file should contain the following information:

{
"search_settings": {
    "collections": [
    "ENMAP_HSI_L2A"
    ],
    "catalog_link" : "https://geoservice.dlr.de/eoc/ogc/stac/v1/",
    "aoi_settings": {
        "bounding_box": "./config/geojson",
        "start_date": "",
        "end_date": ""
    }
},
"result_settings": {
    "results_dir": "./downloads",
    "result_format": "npy",
    "download_data": true,
    "download_metadata": false,
    "logging_level": "INFO",
    "logging_dir": "./logs"
}

Configuration Options

Below is a description of the configurable parameters in the configuration file used by this project.

AOI Settings

These settings define the area of interest (AOI) and the time window for data selection.

"aoi_settings": {
    "bounding_box": "./config/geojson",
    "start_date": "",
    "end_date": ""
}

• bounding_box (str): Path to a GeoJSON file that defines the spatial bounding box for the area of interest.

• start_date (str, optional): Start date for the data query, in YYYY-MM-DD format. Leave empty to ignore.

• end_date (str, optional): End date for the data query, in YYYY-MM-DD format. Leave empty to ignore.

Result Settings

These settings control how the results are processed, saved, and logged.

"result_settings": {
    "crop_data": true,
    "results_dir": "./downloads",
    "result_format": "npy",
    "download_data": true,
    "download_metadata": false,
    "logging_level": "INFO",
    "logging_dir": "./logs"
}

• crop_value (str):

  • If default, the data will not be cropped.

  • If bbox, the data will be cropped to the max bounds of the supplied geojson.

  • If precise, the data will be cropped to the exact polygon of the supplied geojson.

• results_dir (str): Directory path where result files will be saved.

• result_format (str): Format in which results are stored. Supported options: “npy” (NumPy array), “tif” (GeoTIFF).

• download_data (bool): If true, the raw data will be downloaded, in the defined result_format.

• download_metadata (bool): If true, associated metadata files will also be downloaded.

• logging_level (str): Logging verbosity level. Typical values: “DEBUG”, “INFO”, “WARNING”, “ERROR”.

• logging_dir (str): Directory where log files are saved.

Then you can use the package by running the following code block:

import os

from enmap_downloader.config import loadConfiguration, Config
from enmap_downloader.enmap_downloader import enmapDownloader

if __name__ == "__main__":

    config_file = os.path.abspath("config/config.json")
    config = loadConfiguration(path=config_file)
    Config(**config)

    enmapDownloader(config, in_parallel=True)

The function enmapDownloader has the following parameters:

• config (Config): The configuration object containing all settings.

• in_parallel (bool, optional): If True, the downloader will run in parallel mode, downloading multiple files simultaneously. Default is True.

• num_workers (int, optional): Number of worker threads used by the ThreadPoolExecutor when in_parallel is True. Default is None, which uses the number of available CPU cores.

• limit (int, optional): Maximum number of items to download per query. If None, all items matching the query will be downloaded. Default is None.

The downloader will search for EnMAP data products based on the configuration provided, download the data, and save it in the specified format and directory. The downloaded files will be logged in the specified logging directory.

Jupyer Notebooks

To make it easier for new users, or anyone who wants to try out the package quickly, we provide a collection of Jupyter notebooks. These notebooks demonstrate a variety of common use cases and are designed to run out-of-the-box, with only the need for small adjustments. Each notebook contains step-by-step examples that can be executed interactively. This makes them well suited both for first explorations and for adapting the workflows to your own data or research questions. If you are new to the package, starting with the notebooks is the fastest way to get familiar with its core functionality.

FAQ

• Is there a possibility to just fetch the available data with given AOI and time range without downloading the data?

Yes, you can set the fetch_only parameter to True in the enmapDownloader function. This will only fetch the available data without downloading it.

Developed by

enmap_downloader has been developed by the Global Land Monitoring group and FERN.Lab at the GFZ Helmholtz Centre for Geosciences.

Copyright

Copyright (c) 2025 GFZ Helmholtz Centre for Geosciences.

Credits

This package was created with Cookiecutter and the fernlab/cookiecutter-py-package project template.