Spectral Indices

Warning

This is a new experimental API, subject to change.

openeo.extra.spectral_indices is an auxiliary subpackage to simplify the calculation of common spectral indices used in various Earth observation applications (vegetation, water, urban etc.). It leverages the spectral indices defined in the Awesome Spectral Indices project by David Montero Loaiza.

New in version 0.9.1.

Band mapping

The formulas provided by “Awesome Spectral Indices” are defined in terms of standardized variable names like “B” for blue, “R” for red, “N” for near-infrared, “WV” for water vapour, etc.

"NDVI": {
     "formula": "(N - R)/(N + R)",
     "long_name": "Normalized Difference Vegetation Index",

Obviously, these formula variables have to be mapped properly to the band names of your cube.

Automatic band mapping

In most simple cases, when there is enough collection metadata to automatically detect the satellite platform (Sentinel2, Landsat8, ..) and the original band names haven’t been renamed, this mapping will be handled automatically, e.g.:

cube = connection.load_collection("SENTINEL2_L2A", ...)
indices = compute_indices(cube, indices=["NDVI", "NDMI"])

Manual band mapping

In more complex cases, it might be necessary to specify some additional information to guide the band mapping. If the band names follow the standard, but it’s just the satellite platform can not be guessed from the collection metadata, it is typically enough to specify the platform explicitly:

indices = compute_indices(
    cube,
    indices=["NDVI", "NDMI"],
    platform="SENTINEL2",
)

Additionally, if the band names in your cube have been renamed, deviating from conventions, it is also possible to explicitly specify the band name to spectral index variable name mapping:

indices = compute_indices(
    cube,
    indices=["NDVI", "NDMI"],
    variable_map={
        "R": "S2-red",
        "N": "S2-nir",
        "S1": "S2-swir",
    },
)

New in version 0.26.0: Function arguments platform and variable_map to fine-tune the band mapping.

API

openeo.extra.spectral_indices.append_and_rescale_indices(datacube, index_dict, *, variable_map=None, platform=None)[source]

Computes a list of indices from a datacube and appends them to the existing datacube

Parameters:

  • datacube (DataCube) – input data cube

  • index_dict (dict) –

    a dictionary that contains the input- and output range of the collection on which you calculate the indices as well as the indices that you want to calculate with their responding input- and output ranges It follows the following format:

    {
    "collection": {
        "input_range": [0,8000],
        "output_range": [0,250]
    },
    "indices": {
        "NDVI": {
            "input_range": [-1,1],
            "output_range": [0,250]
        },
    }
}

    See list_indices() for supported indices.

  • variable_map (Optional[Dict[str, str]]) – (optional) mapping from Awesome Spectral Indices formula variable to actual cube band names. To be specified if the given data cube has non-standard band names, or the satellite platform can not be recognized from the data cube metadata. See Manual band mapping for more information.

  • platform (Optional[str]) – optionally specify the satellite platform (to determine band name mapping) if the given data cube has no or an unhandled collection id in its metadata. See Manual band mapping for more information.

Return type:

DataCube

Returns:

data cube with appended indices

Warning

this “rescaled” index helper uses an experimental API (e.g. index_dict argument) that is subject to change.

New in version 0.26.0: Added variable_map and platform arguments.

openeo.extra.spectral_indices.append_index(datacube, index, *, variable_map=None, platform=None)[source]

Compute a single spectral index and append it to the given data cube.

Parameters:

  • cube – input data cube

  • index (str) – name of the index to compute and append. See list_indices() for supported indices.

  • variable_map (Optional[Dict[str, str]]) – (optional) mapping from Awesome Spectral Indices formula variable to actual cube band names. To be specified if the given data cube has non-standard band names, or the satellite platform can not be recognized from the data cube metadata. See Manual band mapping for more information.

  • platform (Optional[str]) – optionally specify the satellite platform (to determine band name mapping) if the given data cube has no or an unhandled collection id in its metadata. See Manual band mapping for more information.

Return type:

DataCube

Returns:

data cube with appended index

New in version 0.26.0: Added variable_map and platform arguments.

openeo.extra.spectral_indices.append_indices(datacube, indices, *, variable_map=None, platform=None)[source]

Compute multiple spectral indices and append them to the given data cube.

Parameters:

  • datacube (DataCube) – input data cube

  • indices (List[str]) – list of names of the indices to compute and append. See list_indices() for supported indices.

  • variable_map (Optional[Dict[str, str]]) – (optional) mapping from Awesome Spectral Indices formula variable to actual cube band names. To be specified if the given data cube has non-standard band names, or the satellite platform can not be recognized from the data cube metadata. See Manual band mapping for more information.

  • platform (Optional[str]) – optionally specify the satellite platform (to determine band name mapping) if the given data cube has no or an unhandled collection id in its metadata. See Manual band mapping for more information.

Return type:

DataCube

Returns:

data cube with appended indices

New in version 0.26.0: Added variable_map and platform arguments.

openeo.extra.spectral_indices.compute_and_rescale_indices(datacube, index_dict, *, append=False, variable_map=None, platform=None)[source]

Computes a list of indices from a data cube

Parameters:

  • datacube (DataCube) – input data cube

  • index_dict (dict) –

    a dictionary that contains the input- and output range of the collection on which you calculate the indices as well as the indices that you want to calculate with their responding input- and output ranges It follows the following format:

    {
    "collection": {
        "input_range": [0,8000],
        "output_range": [0,250]
    },
    "indices": {
        "NDVI": {
            "input_range": [-1,1],
            "output_range": [0,250]
        },
    }
}

    If you don’t want to rescale your data, you can fill the input-, index- and output-range with None.

    See list_indices() for supported indices.

  • append (bool) – append the indices as bands to the given data cube instead of creating a new cube with only the calculated indices

  • variable_map (Optional[Dict[str, str]]) – (optional) mapping from Awesome Spectral Indices formula variable to actual cube band names. To be specified if the given data cube has non-standard band names, or the satellite platform can not be recognized from the data cube metadata. See Manual band mapping for more information.

  • platform (Optional[str]) – optionally specify the satellite platform (to determine band name mapping) if the given data cube has no or an unhandled collection id in its metadata. See Manual band mapping for more information.

Return type:

DataCube

Returns:

the datacube with the indices attached as bands

Warning

this “rescaled” index helper uses an experimental API (e.g. index_dict argument) that is subject to change.

New in version 0.26.0: Added variable_map and platform arguments.

openeo.extra.spectral_indices.compute_index(datacube, index, *, variable_map=None, platform=None)[source]

Compute a single spectral index from a data cube.

Parameters:

  • datacube (DataCube) – input data cube

  • index (str) – name of the index to compute. See list_indices() for supported indices.

  • variable_map (Optional[Dict[str, str]]) – (optional) mapping from Awesome Spectral Indices formula variable to actual cube band names. To be specified if the given data cube has non-standard band names, or the satellite platform can not be recognized from the data cube metadata. See Manual band mapping for more information.

  • platform (Optional[str]) – optionally specify the satellite platform (to determine band name mapping) if the given data cube has no or an unhandled collection id in its metadata. See Manual band mapping for more information.

Return type:

DataCube

Returns:

data cube containing the index as band

New in version 0.26.0: Added variable_map and platform arguments.

openeo.extra.spectral_indices.compute_indices(datacube, indices, *, append=False, variable_map=None, platform=None)[source]

Compute multiple spectral indices from the given data cube.

Parameters:

  • datacube (DataCube) – input data cube

  • indices (List[str]) – list of names of the indices to compute and append. See list_indices() for supported indices.

  • append (bool) – append the indices as bands to the given data cube instead of creating a new cube with only the calculated indices

  • variable_map (Optional[Dict[str, str]]) – (optional) mapping from Awesome Spectral Indices formula variable to actual cube band names. To be specified if the given data cube has non-standard band names, or the satellite platform can not be recognized from the data cube metadata. See Manual band mapping for more information.

  • platform (Optional[str]) – optionally specify the satellite platform (to determine band name mapping) if the given data cube has no or an unhandled collection id in its metadata. See Manual band mapping for more information.

Return type:

DataCube

Returns:

data cube containing the indices as bands

New in version 0.26.0: Added variable_map and platform arguments.

openeo.extra.spectral_indices.list_indices()[source]

List names of supported spectral indices

Return type:

List[str]