ndvi.json

{
    "id": "ndvi",
    "summary": "Normalized Difference Vegetation Index",
    "description": "Computes the Normalized Difference Vegetation Index (NDVI). The NDVI is computed as *`(nir - red) / (nir + red)`*.\n\nThe `data` parameter expects a raster data cube with a dimension of type `bands` or a `DimensionAmbiguous` exception is thrown otherwise. By default, the dimension must have at least two bands with the common names `red` and `nir` assigned. Otherwise, the user has to specify the parameters `nir` and `red`. If neither is the case, either the exception `NirBandAmbiguous` or `RedBandAmbiguous` is thrown. The common names for each band are specified in the collection's band metadata and are *not* equal to the band names.\n\nBy default, the dimension of type `bands` is dropped by this process. To keep the dimension specify a new band name in the parameter `target_band`. This adds a new dimension label with the specified name to the dimension, which can be used to access the computed values. If a band with the specified name exists, a `BandExists` is thrown.\n\nThis process is very similar to the process ``normalized_difference()``, but determines the bands automatically based on the common names (`red`/`nir`) specified in the metadata.",
    "categories": [
        "cubes",
        "math > indices",
        "vegetation indices"
    ],
    "parameters": [
        {
            "name": "data",
            "description": "A raster data cube with two bands that have the common names `red` and `nir` assigned.",
            "schema": {
                "type": "object",
                "subtype": "datacube",
                "dimensions": [
                    {
                        "type": "spatial",
                        "axis": [
                            "x",
                            "y"
                        ]
                    },
                    {
                        "type": "bands"
                    }
                ]
            }
        },
        {
            "name": "nir",
            "description": "The name of the NIR band. Defaults to the band that has the common name `nir` assigned.\n\nEither the unique band name (metadata field `name` in bands) or one of the common band names (metadata field `common_name` in bands) can be specified. If the unique band name and the common name conflict, the unique band name has a higher priority.",
            "schema": {
                "type": "string",
                "subtype": "band-name"
            },
            "default": "nir",
            "optional": true
        },
        {
            "name": "red",
            "description": "The name of the red band. Defaults to the band that has the common name `red` assigned.\n\nEither the unique band name (metadata field `name` in bands) or one of the common band names (metadata field `common_name` in bands) can be specified. If the unique band name and the common name conflict, the unique band name has a higher priority.",
            "schema": {
                "type": "string",
                "subtype": "band-name"
            },
            "default": "red",
            "optional": true
        },
        {
            "name": "target_band",
            "description": "By default, the dimension of type `bands` is dropped. To keep the dimension specify a new band name in this parameter so that a new dimension label with the specified name will be added for the computed values.",
            "schema": [
                {
                    "type": "string",
                    "pattern": "^\\w+$"
                },
                {
                    "type": "null"
                }
            ],
            "default": null,
            "optional": true
        }
    ],
    "returns": {
        "description": "A raster data cube containing the computed NDVI values. The structure of the data cube differs depending on the value passed to `target_band`:\n\n* `target_band` is `null`: The data cube does not contain the dimension of type `bands`, the number of dimensions decreases by one. The dimension properties (name, type, labels, reference system and resolution) for all other dimensions remain unchanged.\n* `target_band` is a string: The data cube keeps the same dimensions. The dimension properties remain unchanged, but the number of dimension labels for the dimension of type `bands` increases by one. The additional label is named as specified in `target_band`.",
        "schema": {
            "type": "object",
            "subtype": "datacube",
            "dimensions": [
                {
                    "type": "spatial",
                    "axis": [
                        "x",
                        "y"
                    ]
                }
            ]
        }
    },
    "exceptions": {
        "NirBandAmbiguous": {
            "message": "The NIR band can't be resolved, please specify the specific NIR band name."
        },
        "RedBandAmbiguous": {
            "message": "The red band can't be resolved, please specify the specific red band name."
        },
        "DimensionAmbiguous": {
            "message": "dimension of type `bands` is not available or is ambiguous.."
        },
        "BandExists": {
            "message": "A band with the specified target name exists."
        }
    },
    "links": [
        {
            "rel": "about",
            "href": "https://en.wikipedia.org/wiki/Normalized_difference_vegetation_index",
            "title": "NDVI explained by Wikipedia"
        },
        {
            "rel": "about",
            "href": "https://earthobservatory.nasa.gov/features/MeasuringVegetation/measuring_vegetation_2.php",
            "title": "NDVI explained by NASA"
        },
        {
            "rel": "about",
            "href": "https://github.com/radiantearth/stac-spec/tree/master/extensions/eo#common-band-names",
            "title": "List of common band names as specified by the STAC specification"
        }
    ]
}