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.
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.
numpy
package.add | log | can_cast |
subtract | log10 | promote_types |
multiply | sinh | dtype |
divide | cosh | logical_and |
maximum | tanh | logical_or |
minimum | fft | logical_not |
sin | ifft | logical_xor |
cos | fft2 | greater_equal |
tan | ifft2 | less_equal |
arcsin | fftn | equal |
arccos | ifftn | not_equal |
arctan | bitwise_and | array_equal |
prod | bitwise_or | histogram |
sum | bitwise_xor | histogram2d |
abs | invert | histogramdd |
sqrt | left_shift | where |
exp | right_shift | nan_to_num |
Product inputs
- Supported item types:
PlanetScope
,SkySat
, andRapidEye
. - 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.
Property | Type | Required | Description |
---|---|---|---|
b1 | String | Required | An expression defining how output band 1 should be computed. |
b2 | String | Optional | An expression defining how output band 2 should be computed. |
b3 | String | Optional | An expression defining how output band 3 should be computed. |
b4 | String | Optional | An expression defining how output band 4 should be computed. |
b5 | String | Optional | An expression defining how output band 5 should be computed. |
b6 | String | Optional | An expression defining how output band 6 should be computed. |
b7 | String | Optional | An expression defining how output band 7 should be computed. |
b8 | String | Optional | An expression defining how output band 8 should be computed. |
b9 | String | Optional | An expression defining how output band 9 should be computed. |
b10 | String | Optional | An expression defining how output band 10 should be computed. |
b11 | String | Optional | An expression defining how output band 11 should be computed. |
b12 | String | Optional | An expression defining how output band 12 should be computed. |
b13 | String | Optional | An expression defining how output band 13 should be computed. |
b14 | String | Optional | An expression defining how output band 14 should be computed. |
b15 | String | Optional | An expression defining how output band 15 should be computed. |
pixel_type | String | Optional | 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. |
- JSON
- Python SDK
"tools": [
{
"type": "bandmath",
"parameters": {
"b1": "b1",
"b2": "b2",
"b3": "b3",
"b4": "arctan(b1)",
"b5": "(b4-b3)/(b4+b3)",
"pixel_type": "32R"
}
}
]
from planet.subscription_request import band_math_tool
band_math = band_math_tool(
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
Property | Type | Required | Description |
---|---|---|---|
aoi | Dict | Optional | GeoJSON 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). |
- JSON
- Python SDK
"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]
]
]
}
}
}
]
from planet.subscription_request import clip_tool
clip_tool = clip_tool(
{
"type": "Polygon",
"coordinates": [
[
[139.56481933, 35.42374884],
[140.10314941, 35.42374884],
[140.10314941, 35.77102915],
[139.56481933, 35.77102915],
[139.56481933, 35.42374884],
]
],
}
)
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.
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.
Always use this tool after the clip tool.
Product inputs
The cloud filter tool only supports item types with UDM2 assets.
Parameters
Property | Type | Required | Description |
---|---|---|---|
clear_percent | Integer (0 - 100) | Optional | Percent 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_percent | Integer (0 - 100) | Optional | Percent 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_percent | Integer (0 - 100) | Optional | Planet'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_percent | Integer (0 - 100) | Optional | Percent 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_percent | Integer (0 - 100) | Optional | Percent 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_percent | Integer (0 - 100) | Optional | Percent of snow and ice values in the dataset. Snow_ice values represent scene content areas (non-blackfilled) that are hidden below snow or ice. |
Each parameter should have one or two comparators (lte
or gte
) and a value in the integer range as specified above. See example below.
- JSON
- Python SDK
"tools": [
{
"type": "cloud_filter",
"parameters": {
"cloud_percent": {"lte": 20}
}
}
]
from planet.subscription_request import cloud_filter_tool, FilterValue
cloud_filter = cloud_filter_tool(cloud_percent=FilterValue(lte=20.0))
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.
- JSON
{
"_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
Property | Type | Enum | Description |
---|---|---|---|
format | Enum (String) | COG | This 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. |
format | Enum (String) | PL_NITF | This 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. |
- JSON
- Python SDK
"tools": [
{
"type": "file_format",
"parameters": {
"format": "COG"
}
}
]
from planet.subscription_request import file_format_tool
file_format = file_format_tool(file_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/orortho_analytic_8b_sr
,ortho_analytic_8b_xml
,ortho_udm2
Parameters
Property | Type | Required | Description |
---|---|---|---|
target_sensor | String | Required | The sensor to calibrate the input data to. The only supported value is: Sentinel-2 . |
- JSON
- Python SDK
"tools": [
{
"type": "harmonize",
"parameters": {
"target_sensor": "Sentinel-2"
}
}
]
from planet.subscription_request import harmonize_tool
harmonization = harmonize_tool(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
andTanagerMethane
. - Supported asset types: All asset types except for those with non-orthorectified images (
basic_*
assets).
Parameters
Property | Type | Required | Description |
---|---|---|---|
projection | String | Required | 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 | Optional | 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 | Optional | 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). |
- JSON
- Python SDK
"tools": [
{
"type": "reproject",
"parameters": {
"projection": "EPSG:4326",
"kernel": "near"
}
}
]
from planet.subscription_request import reproject_tool
reproject = reproject_tool(
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/orortho_analytic_8b
,ortho_analytic_8b_xml
- For
REOrthoTile
:analytic
,analytic_xml
- For
Parameters
Property | Type | Required | Description |
---|---|---|---|
scale_factor | Integer | Optional | Scale 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. |
- JSON
- Python SDK
"tools": [
{
"type": "toar",
"parameters": {
"scale_factor": 10000
}
}
]
from planet.subscription_request import toar_tool
toar = toar_tool(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
.
- JSON
- Python SDK
"tools": [
{
"type": "toar",
"parameters": {
"scale_factor": 10000
}
},
{
"type": "reproject",
"parameters": {
"projection": "EPSG:3857",
"kernel": "near"
}
},
{
"type": "file_format",
"parameters": {
"format": "COG"
}
}
]
from datetime import datetime
from planet.subscription_request import (
toar_tool,
reproject_tool,
file_format_tool,
build_request,
catalog_source,
)
t = toar_tool(scale_factor=10000)
r = reproject_tool(
projection="EPSG:4326",
kernel="near",
)
f = file_format_tool(file_format="COG")
tool_chain = [t, r, f]
build_request(
name="example",
source=catalog_source(
item_types=["PSScene"],
asset_types=["ortho_analytic_4b"],
start_time=datetime.fromisoformat("2024-11-05T00:00:00Z"),
end_time=datetime.fromisoformat("2024-11-10T00:00:00Z"),
time_range_type="acquired",
geometry={
"coordinates": [
[
[139.56481933, 35.42374884],
[140.10314941, 35.42374884],
[140.10314941, 35.77102915],
[139.56481933, 35.77102915],
[139.56481933, 35.42374884],
]
],
"type": "Polygon",
},
),
tools=tool_chain,
)