Skip to main content

Tools

The Subscriptions API supports select raster processing tools which can be applied to imagery before delivery to reduce time spent in data post-processing.

info

Tools are only supported for catalog subscriptions, and all other subscriptions are automatically clipped to their AOI.

Tools Schema​

The schema for Subscriptions API tools is below.

"tools": [
    {
        "type": "tool-name",
        "parameters": {
            "parameter-1-name": "p1-value",
            "parameter-2-name": "p2-value"
        }
    }
]

Tools Reference​

Band Math​

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

The bands of the input file are referenced as b1, b2, b3, etc., where b1 equals "band 1". For each band expression, the bandmath tool supports normal arithmetic operations and simple math operators offered in the Python numpy package.

The full list of supported mathematical functions of the Python numpy package.

addlogcan_cast
subtractlog10promote_types
multiplysinhdtype
dividecoshlogical_and
maximumtanhlogical_or
minimumfftlogical_not
sinifftlogical_xor
cosfft2greater_equal
tanifft2less_equal
arcsinfftnequal
arccosifftnnot_equal
arctanbitwise_andarray_equal
prodbitwise_orhistogram
sumbitwise_xorhistogram2d
absinverthistogramdd
sqrtleft_shiftwhere
expright_shiftnan_to_num

Product inputs​

  • Supported item types: PlanetScope, SkySat, and RapidEye.
  • Supported assets: All asset types except non-orthorectified, basic_* asset types.

Parameters​

The parameters of the bandmath tool define how each output band in the derivative product should be produced, referencing the product inputs' original bands. Band math expressions may not reference neighboring pixels, as non-local operations are not supported. The tool can calculate up to 15 bands for an item. Input band parameters may not be skipped. For example, if the b4 parameter is provided, then b1, b2, and b3 parameters are also required.

PropertyTypeRequiredDescription
b1StringRequiredAn expression defining how output band 1 should be computed.
b2StringOptionalAn expression defining how output band 2 should be computed.
b3StringOptionalAn expression defining how output band 3 should be computed.
b4StringOptionalAn expression defining how output band 4 should be computed.
b5StringOptionalAn expression defining how output band 5 should be computed.
b6StringOptionalAn expression defining how output band 6 should be computed.
b7StringOptionalAn expression defining how output band 7 should be computed.
b8StringOptionalAn expression defining how output band 8 should be computed.
b9StringOptionalAn expression defining how output band 9 should be computed.
b10StringOptionalAn expression defining how output band 10 should be computed.
b11StringOptionalAn expression defining how output band 11 should be computed.
b12StringOptionalAn expression defining how output band 12 should be computed.
b13StringOptionalAn expression defining how output band 13 should be computed.
b14StringOptionalAn expression defining how output band 14 should be computed.
b15StringOptionalAn expression defining how output band 15 should be computed.
pixel_typeStringOptionalA value indicating what the output pixel type should be. By default this value will be "Auto", the same as the input file. "8U" (8bit unsigned), "16U" (16bit unsigned), "16S" (16bit signed), and "32R" (32bit floating point) may also be used depending on the type of equation or index being calculated.
"tools": [
    {
        "type": "bandmath",
        "parameters": {
            "b1": "b1",
            "b2": "b2",
            "b3": "b3",
            "b4": "arctan(b1)",
            "b5": "(b4-b3)/(b4+b3)",
            "pixel_type": "32R"
        }
    }
]

The output of this tool is an asset that includes all four bands of the original file, a fourth band that is the arc tangent of the original first band, and a fifth band with NDVI values.

Tool outputs​

One bandmath imagery output file is produced for each product asset, with output bands derived from the band math expressions. nodata pixels are processed with the band math equation. These files have _bandmath appended to their file names.

The bandmath tool passes through UDM, RPC, and XML files, and does not update values in these files.

Clip​

The clip tool allows you to clip a scene to a specified area of interest (Polygon or MultiPolygon) to limit your storage costs or quota usage.

Product inputs​

  • Supported item types: All item types except for SkySatVideo.
  • Supported asset types: All asset types except for non-orthorectified, basic_* asset types.

Parameters​

PropertyTypeRequiredDescription
aoiDictOptionalGeoJSON Polygon or MultiPolygon defining the clip area, with up to 1,500 vertices. The minimum geographic area of any polygon or internal ring is one square meter. When this parameter is omitted, the subscription geometry will be used (so long as the clip tool is still specified).
"tools": [
    {
        "type": "clip",
        "parameters": {
            "aoi": {
                "type": "Polygon",
                "coordinates": [
                    [
                        [-163.828125, -44.59046718130883],
                        [181.7578125, -44.59046718130883],
                        [181.7578125, 78.42019327591201],
                        [-163.828125, 78.42019327591201],
                        [-163.828125, -44.59046718130883]
                    ]
                ]
            }
        }
    }
]

AOI geometry limits​

While clipping an AOI with GeoJSON, users should be aware of MultiPolygon limitations for successful subscription creation. The python-geojson and python-shapely validation process involved in passing an AOI to the clip tool, as well as Subscriptions limitations, may flag validation errors that result in your subscription being rejected.

The following geometries are invalid and will result in an error:

  • GeoJSON Polygons with holes.
  • GeoJSON Polygons with multiple exterior rings.
  • GeoJSON MultiPolygons with overlapping/intersecting Polygons. The GeoJSON spec technically allows this, but is generally not supported in many programs (For example, PostGIS, Shapely, and QGIS.).
  • GeoJSON Polygons or MultiPolygons with more than 1,500 vertices.
  • Clipping outside of your contractual Area of Access (AOA).

Tool outputs​

Imagery and UDM files will be clipped to your area of interest. nodata pixels will be preserved.

XML file attributes filename, numRows, numColumns and footprint will be updated based on the clip results.

The clipped output files will have _clip appended to their file names. If the clip AOI is so large that full scenes may be delivered without any clipping, those files will not have _clip appended to their file name.

The delivered item metadata JSON file will also be updated for catalog subscriptions. The metadata geometry will reflect the footprint of the item clipped to the clip tool's area of interest. Similarly, the UDM2 metadata values such as clear_percent may be updated and relevant to the clipped area of interest. These UDM2 metadata values are only updated if a UDM2 asset is included in the subscription.

info

There might be discrepancies between an item's footprint and the area of its usable pixels. When clipping, this can result in a clipped AOI that does not intersect with any usable pixels of an image. In this case, an imagery file will not be delivered while auxiliary assets will continue to be delivered.

Cloud Filter​

The cloud filter tool allows you to filter out imagery that exceeds your provided per Area of Interest (AOI) cloud cover metadata thresholds after the scene has been clipped with the clip tool. This allows for more granular filtering based on the clipped AOI, instead of the metadata of the entire scene.

info

Always use this tool after the clip tool.

Product inputs​

The cloud filter tool only supports item types with UDM2 assets.

Parameters​

PropertyTypeRequiredDescription
clear_percentInteger (0 - 100)OptionalPercent of clear values in the dataset. Clear values represent scene content areas (non-blackfilled) deemed to be not impacted by cloud, haze, shadow, or snow.
cloud_percentInteger (0 - 100)OptionalPercent of cloud values in the dataset. Cloud values represent scene content areas (non-blackfilled) that contain opaque clouds which prevent reliable interpretation of the land cover content.
heavy_haze_percentInteger (0 - 100)OptionalPlanet's UDM2.1 product launched 11/29/2023 does not include a heavy haze classification. Any non-zero values for this field were generated by the previous UDM2.0 product before 11/29/2023. Under UDM2.0’s definition: Percent of heavy haze values in the dataset. Heavy haze values represent scene content areas (non-blackfilled) that contain thin low altitude clouds, higher altitude cirrus clouds, soot and dust which allow fair recognition of land cover features, but not having reliable interpretation of the radiometry or surface reflectance.
light_haze_percentInteger (0 - 100)OptionalPercent of haze values in the dataset. Haze values represent regions of a scene (non-blackfilled) with thin, filamentous clouds, soot, dust, and smoke. You can see ground objects through haze.
shadow_percentInteger (0 - 100)OptionalPercent of shadow values in the dataset. Shadow values represent scene content areas (non-blackfilled) not fully exposed to the solar illumination due to atmospheric transmission losses due to cloud, haze, soot, and dust, and therefore do not allow for reliable interpretation of the radiometry or surface reflectance.
snow_ice_percentInteger (0 - 100)OptionalPercent of snow and ice values in the dataset. Snow_ice values represent scene content areas (non-blackfilled) that are hidden below snow or ice.
info

Each parameter should have one or two comparators (lte or gte) and a value in the integer range as specified above. See example below.

"tools": [
    {
        "type": "cloud_filter",
        "parameters": {
            "cloud_percent": {"lte": 20}
        }
    }
]

Tool outputs​

If a scene is not filtered, it will be delivered as you would expect. If a scene is filtered, then delivery will not be made.

Filtered scenes will be returned in the api.planet.com/subscriptions/v1/{id}/results/ endpoint, as a result with no output, containing a "filtered" key in its properties block.

{
    "_links": {
        "_self": "https://api.planet.com/subscriptions/v1/d31a3663-6ead-4e3d-bf53-0ea2ab856c66/results"
    },
    "results": [
        {
            "id": "e310e1e3-7205-4b3f-a75c-a55faf517845",
            "status": "success", <--- still successful though
            "properties": {
                "filtered": "cloud_filter", <--- filtered for this reason
                "item_id": "20201129_151145_42_222b",
                "item_types": [
                    "PSScene"
                ]
            },
            "created": "2023-09-27T17:43:30.132674Z",
            "updated": "2023-09-27T17:52:12.636226Z",
            "completed": "2023-09-27T17:52:12.636226Z",
            "errors": {},
            "outputs": []
        }
    ]
}

File Format​

The file format tool allows you to convert imagery to Cloud Optimized GeoTIFFs (COGs). COGs are ideal for light-weight, web-based workflows or NITF 2.1 formats.

Product inputs​

  • Supported item types: All item types.
  • Supported asset types: All asset types except for those with NITF images (*_nitf assets).

Parameters​

PropertyTypeEnumDescription
formatEnum (String)COGThis option produces a tiled Cloud Optimized GeoTIFF, with LZW compression and powers of two overviews. You can find more information on Cloud Optimized GeoTIFFs here.
formatEnum (String)PL_NITFThis option converts the output to the National Imagery Transmission Format 2.1 specification. Learn more about the NITF 2.1 Interface Standard here. The NITF format only supports WGS84 geographic and UTM projections. The reproject tool may be used to change projections before File Format.
"tools": [
    {
        "type": "file_format",
        "parameters": {
            "format": "COG"
        }
    }
]

Tool outputs​

One formatted imagery output file is produced for each asset. These files have _file_format appended to their file names.

The file format tool passes through UDM, RPC and XML files.

Harmonize​

The harmonize tool allows you to radiometrically harmonize imagery captured by one satellite instrument type to imagery captured by another.

Product inputs​

Target sensors​

Sentinel-2​

PSScene surface reflectance assets from PlanetScope instrument types (PS2.SD and PSB.SD) can be harmonized to Sentinel-2. The tool harmonizes PSScene surface reflectance asset types (ortho_analytic_8b_sr, ortho_analytic_4b_sr) to Sentinel-2 bands (blue, green, red, red-edge, and narrow near-infrared (NIR)).

There will be small differences between harmonization results for 8-band data and 4-band data even for the same scene. This is due to the regularization metric that minimizes changes in band ratios during harmonization. Including more bands gives slightly different results.

This sensor type requires that the surface reflectance asset and the supplemental Ortho UDM2 and XML (i.e., ortho_analytic_4b_xml, ortho_analytic_8b_xml) assets are included when creating a subscription.

Read more about the harmonization to Sentinel-2 in Scene Level Normalization and Harmonization of Planet Dove Imagery.

  • Supported item types: PSScene
  • Required asset types:
    • ortho_analytic_4b_sr, ortho_analytic_4b_xml, ortho_udm2 and/or
    • ortho_analytic_8b_sr, ortho_analytic_8b_xml, ortho_udm2

Parameters​

PropertyTypeRequiredDescription
target_sensorStringRequiredThe sensor to calibrate the input data to. The only supported value is: Sentinel-2.
"tools": [
    {
        "type": "harmonize",
        "parameters": {
            "target_sensor": "Sentinel-2"
        }
    }
]

Tool outputs​

One imagery output file with harmonized band values is delivered for each surface reflectance asset type. The transformation of each item depends on the instrument used to capture that item and its relationship to the target sensor. Files which have been transformed have _harmonize appended to their file names.

The harmonize tool passes through UDM, RPC, and XML files, and does not update values in these files.

Reproject​

The reproject tool allows you to reproject and resample imagery products to a new projected coordinate system and resolution.

Product inputs​

  • Supported item types: All item types except for TanagerScene and TanagerMethane.
  • Supported asset types: All asset types except for those with non-orthorectified images (basic_* assets).

Parameters​

PropertyTypeRequiredDescription
projectionStringRequiredA coordinate system in the form EPSG:n (for example, EPSG:4326 for WGS84, EPSG:32611 for UTM 11 North (WGS84), or EPSG:3857 for Web Mercator). Well known text CRS values are also supported (for example, WGS84).
resolutionFloatOptionalThe pixel width and height in the output file. If not provided, the default is the resolution of the input item. This value is in meters unless the coordinate system is geographic (such as EPSG:4326), in which case, it is pixel size in decimal degrees.
kernelStringOptionalThe resampling kernel used. If not provided, the default is near. UDM files always use near. This parameter also supports bilinear, cubic, cubicspline, lanczos, average, mode, min, max, med, q1, and q3 (see the gdalwarp "resampling_method" docs for details).
"tools": [
    {
        "type": "reproject",
        "parameters": {
            "projection": "EPSG:4326",
            "kernel": "near"
        }
    }
]

Tool outputs​

One imagery output file reprojected to the target configuration is produced for each product asset. UDM files are also reprojected to the target configuration. These file outputs will have _reproject appended to their file names.

The reproject tool passes through XML files.

Top of Atmosphere Reflectance (TOAR)​

The Top of Atmosphere Reflectance (TOAR) tool converts Analytic assets from top of atmosphere (TOA) radiance to a TOA scaled reflectance, accounting for varying solar irradiance based on the distance to the sun and geometry of incoming solar radiation. The resulting product is a top of atmosphere reflectance value. No atmospheric correction is applied.

Product inputs​

  • Supported item types: PSScene, REOrthoTile.
  • Required asset types:
    • For PSScene:
      • ortho_analytic_4b, ortho_analytic_4b_xml and/or
      • ortho_analytic_8b, ortho_analytic_8b_xml
    • For REOrthoTile:
      • analytic, analytic_xml

Parameters​

PropertyTypeRequiredDescription
scale_factorIntegerOptionalScale factor applied to convert 0.0 to 1.0 reflectance floating point values to a value that fits in 16-bit integer pixels. The default is 10000. Values over 65535 could result in high reflectances not fitting in 16-bit integers.
"tools": [
    {
        "type": "toar",
        "parameters": {
            "scale_factor": 10000
        }
    }
]

Tool outputs​

One 16bit imagery output file, holding scaled reflectance values, produced for each analytic asset. These files have _toar appended to their file names.

The toar tool passes through the corresponding XML assets.

Creating Toolchains​

Multiple tools will likely be required to process the data to derive insights or perform any meaningful analysis. You can push Planet data through an individual tool or several tools chained together to achieve the results you need.

Planet processes tool requests synchronously in an order that has been validated against prior methodology. Given the changing output of each tool, certain processes necessarily go before others. Other tool chains are arbitrarily chosen based on the inputs or the effects on the output. For example, although not required, it’s recommended to run the clip tool before reproject and bandmath in order to reduce processing time. But, depending on the clip geometry, clipping before reprojecting may produce undesirable edge effects. In that case, you would clip before reproject.

When using multiple tools in a subscription, you must request tools in a specific order in the request body in order to ensure each tool succeeds. The required order of tools is as follows:

Tool precedence
Harmonize
TOAR
Clip, Reproject, Band Math (can go in any order)
Cloud Filter, Bandmath (must be after a clip)
File Format

If the array you provide does not follow the sequence above, a 400 error is returned, clarifying which tool must be declared before another.

Example​

In this example, the ortho-analytic product is manipulated by three tools in the series: TOAR --> Reproject --> File format.

"tools": [
    {
        "type": "toar",
        "parameters": {
            "scale_factor": 10000
        }
    },
    {
        "type": "reproject",
        "parameters": {
            "projection": "EPSG:3857",
            "kernel": "near"
        }
    },
    {
        "type": "file_format",
        "parameters": {
            "format": "COG"
        }
    }
]
Last updated on