The bandmath tool applies band math expressions to the bands of input files to produce derived outputs and indices for analysis. Common indices include the Normalized Difference Vegetation Index (NDVI), the Enhanced Vegetation Index (EVI), and the Normalized Difference Water Index (NDWI).

How band expressions work

Input bands are referenced as b1, b2, b3, and so on, where b1 equals band 1. For each band expression, the bandmath tool supports standard arithmetic operations and simple math operators provided by the Python NumPy package. For the list of supported functions, see Band Math in the Orders API tools documentation.

• The tool can calculate up to 15 bands for an item.
• Band math expressions cannot reference neighboring pixels, because non-local operations are not supported.
• Input band parameters cannot be skipped. For example, if the b4 parameter is provided, then the b1, b2, and b3 parameters are also required.

Parameters

• b1 (string, required): an expression defining how output band 1 is computed
• b2 to b15 (string, optional): an expression defining how each of output bands 2 to 15 is computed
• pixel_type (string, optional): the output pixel type

Pixel type values

By default, pixel_type is Auto, the same as the input file. Depending on the equation or index being calculated, you can also use one of these values:

• 8U: 8-bit unsigned
• 16U: 16-bit unsigned
• 16S: 16-bit signed
• 32R: 32-bit floating point

Example request

The following order applies several band calculations in one bandmath tool. The output keeps the original first three bands, adds a fourth band that is the arc tangent of the original first band, and adds a fifth band with NDVI values.

POST https://api.planet.com/compute/ops/orders/v2

{
  "name": "ndvi_bandmath_example",
  "source_type": "scenes",
  "products": [
    {
      "item_ids": [
        "20220124_062250_31_220b"
      ],
      "item_type": "PSScene",
      "product_bundle": "analytic_udm2"
    }
  ],
  "tools": [
    {
      "bandmath": {
        "b1": "b1",
        "b2": "b2",
        "b3": "b3",
        "b4": "arctan(b1)",
        "b5": "(b4-b3)/(b4+b3)",
        "pixel_type": "32R"
      }
    }
  ]
}

Output files

• Output files have _bandmath appended to their file names.
• nodata pixels are processed with the band math equation.

Related articles

• Orders API tools