The Subscriptions API supports select raster processing tools which can be applied to imagery before delivery to reduce time spent in data post-processing.
Tools schema¶
The schema for Subscriptions API tools is below. Note that this schema varies slightly different from the tools schema of the Orders API.
"tools": [
{
"type": "tool-name",
"parameters": {
"parameter-1-name": "p1-value",
"parameter-2-name": "p2-value"
}
}
]
Creating toolchains¶
To derive insights or perform any meaningful analysis, it is highly likely that multiple tools will be required to process the data. You can push Planet data through individual or several of these 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:
harmonizetoarclip,reproject,bandmath(can go in any order)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.
Toolchain example¶
In this example, the ortho-analytic product is manipulated by three tools in the series: TOAR --> Reproject --> File format.
TOAR, reproject, and file format¶
"tools": [
{
"type": "toar",
"parameters": {
"scale_factor": 10000
}
},
{
"type": "reproject",
"parameters": {
"projection": "EPSG:3857",
"kernel": "near"
}
},
{
"type": "file_format",
"parameters": {
"format": "COG"
}
}
]
Supported tools¶
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. (For a list of supported mathematical functions, see Bandmath supported numpy math routines.)
Product inputs¶
The bandmath tool supports PlanetScope, SkySat, and RapidEye except for those with non-orthorectified images (designated as basic_* assets).
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.
- b1 (string): An expression defining how output band 1 should be computed. (required)
- b2 (string): An expression defining how output band 2 should be computed. (optional)
- ...
- b15 (string): An expression defining how output band 15 should be computed. (optional)
- pixel_type (string): A 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. (optional)
Example request
"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 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 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. clip may also be used as a billing management tool, depending on the Raster Tools Plan you’ve purchased.
Product inputs¶
The clip tool supports all item types except SkySatVideo and all asset types except for non-orthorectified, basic_* asset types.
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.
Note: There may sometimes be discrepancies between an item’s footprint and the area of its usable pixels. When clipping, this can result in a clipped aoi which does not intersect with any usable pixels of an image. In this circumstance, no imagery file will be delivered while auxiliary assets will continue to be delivered.
Parameters¶
- aoi (dict): GeoJSON polygon or multipolygon defining the clip area, with up to 500 vertices. The minimum geographic area of any polygon or internal ring is one square meter.
Example request
"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. Notable validation changes are due to the python-geojson + python-shapely validation process and may result in your subscription being rejected. The following geometries are invalid and will result in the failure of a subscription request:
- GeoJSON Polygons with holes first will be rejected.
- GeoJSON Polygons with multiple exterior rings will be rejected.
- GeoJSON MultiPolygons with overlapping/intersecting Polygons will be rejected. The GeoJSON spec technically allows this, but is generally invalid geometry in many programs (PostGIS, Shapely, QGIS to name a few).
- GeoJSON containing more than 500 vertices will be rejected.
- Clipping outside contract AOI may result in a rejected order.
File Format¶
The file_format tool allows you to convert imagery to Cloud Optimized GeoTIFF (ideal for light-weight, web-based workflows) or NITF 2.1 formats.
Product inputs¶
The file_format tool supports all item types and all asset types except for those with NITF images (designated as *_nitf assets).
Parameters¶
- format (enum): The format of the tool output. Currently, the tool supports two formats:
- "COG": This option produces a tiled Cloud Optimized GeoTIFF, with LZW compression and powers of two overviews. You can find more information at Cloud Optimized GeoTIFF.
- "PL_NITF": This option converts the output to the National Imagery Transmission Format 2.1 specification. Find out more about the NITF 2.1 Interface Standard. The NITF format only supports WGS84 geographic and UTM projections. If your imagery is in a different projection, use the Reproject tool first.
Example
"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 tool passes through UDM and XML files, and does not update values in these files.
Harmonization¶
The harmonize tool allows you to radiometrically harmonize imagery captured by one satellite instrument type to imagery captured by another.
Parameters¶
- target_sensor (string): A value indicating to what sensor the input asset types should be calibrated. Each sensor value transforms items captured by a defined set of instrument IDs. Items which have not been captured by that defined set of instrument IDs are unaffected by (passed through) the harmonization operation.
Target sensor options¶
Sentinel-2¶
- PSScene surface reflectance assets from PlanetScope instrument types (
PS2.SDandPSB.SD) can be harmonized to Sentinel-2. - With the Sentinel-2 target sensor, the tool harmonizes PSScene surface reflectance asset types (
ortho_analytic_8b_sr,ortho_analytic_4b_sr) to Sentinel-2 bands (blue, green, red, and narrow near-infrared (NIR)). - 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.
Example request
"tools": [
{
"type": "harmonize",
"parameters": {
"target_sensor": "Sentinel-2"
}
}
]
Tool outputs¶
One imagery output file with harmonized band values is delivered for each 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 Harmonization 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¶
The reproject tool supports all item types and all asset types except for those with non-orthorectified images (basic_* assets).
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.
Parameters¶
- projection (string): A 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).
- resolution (float): The 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.
- kernel (string): The 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).
Example
"tools": [
{
"type": "reproject",
"parameters": {
"projection": "EPSG:4326",
"kernel": "near"
}
}
]
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. The Subscriptions API TOAR tool is only applicable to Analytic assets, which represent TOA radiance. The tool converts the pixel values to a 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¶
The toar tool supports the analytic asset type for PSScene and REOrthoTile item types. In addition to the asset type, the corresponding XML metadata asset type is required. Pairs of analytic and XML asset types are listed below:
ortho_analytic_4b, ortho_analytic_4b_xml
ortho_analytic_8b, ortho_analytic_8b_xml
analytic, analytic_xml
Parameters¶
- scale_factor (integer): Scale factor applied to convert 0.0 to 1.0 reflectance floating point values to a value that fits in 16bit integer pixels. The default is 10000. Values over 65535 could result in high reflectances not fitting in 16bit integers.
Example
"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 tool also passes through the corresponding XML assets.
Rate this guide: