Tools

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

Supported Tools

Scenes Orders	Basemaps Orders
Band Math Clip Composite Coregister File Format Harmonize Reproject Tile TOAR	Band Math Clip Merge Reproject

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.

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 source types: scenes.
• Supported item types: PlanetScope, SkySat, and RapidEye.
• Supported product bundles: All product bundles except for those with non-orthorectified images (basic_* bundles).

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

"tools": [
    {
        "bandmath": {
            "b1": "b1",
            "b2": "b2",
            "b3": "b3",
            "b4": "arctan(b1)",
            "b5": "(b4-b3)/(b4+b3)",
            "pixel_type": "32R"
        }
    }
]

Python SDK

from planet.order_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 the original first band, and a fifth band with NDVI values.

Tool outputs

One bandmath imagery output file is produced for each ordered item, 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 source types: scenes and basemaps.
• For scenes source types:
  • Supported item types: All item types except for SkySatVideo, TanagerScene, and TanagerMethane.
  • Supported product bundles: All product bundles except for those with non-orthorectified images (basic_* bundles).
• For basemaps source types:
  • The clip tool is only supported for geometry based requests. When you order a Basemap using an Area of Interest (geometry), whole quads are returned. This tool clips those quads to your provided geometry. The clip tool does not work for Basemap orders using quad_ids.

Parameters

For scenes source types:

Property	Type	Required	Description
aoi	Dict	Required	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.

JSON

"tools": [
    {
        "clip": {
            "aoi": {
                "type": "Polygon",
                "coordinates": [
                    [
                        [-71.42186132, 41.83081646],
                        [-71.4161135, 41.81226765],
                        [-71.39302278, 41.82186268],
                        [-71.39920293, 41.8336341],
                        [-71.42186132, 41.83081646]
                    ]
                ]
            }
        }
    }
]

Python SDK

from planet.order_request import clip_tool

clip = clip_tool(
    {
        "type": "Polygon",
        "coordinates": [
            [
                [-71.42186132, 41.83081646],
                [-71.4161135, 41.81226765],
                [-71.39302278, 41.82186268],
                [-71.39920293, 41.8336341],
                [-71.42186132, 41.83081646],
            ]
        ],
    }
)

For basemaps source types:

There are no parameters for the clip tool, as the geometry in the product block is used as the area of interest. The clip body should be an empty dictionary.

JSON

{
    "name": "basemap order by geometry with clip",
    "source_type": "basemaps",
    "products": [
        {
            "geometry":{
                "type": "Polygon",
                "coordinates":[
                    [
                        [4.607406, 52.353994],
                        [4.680005, 52.353994],
                        [4.680005, 52.395523],
                        [4.607406, 52.395523],
                        [4.607406, 52.353994]
                    ]
                ]
            },
            "mosaic_name": "global_monthly_2022_01_mosaic",
        }
    ],
    "tools" : [
        "clip": {}
    ]
}

AOI geometry limits

When clipping to an AOI with a GeoJSON, users should be aware of the multipolygon limitation for successful orders creation. The python-geojson and python-shapely validation process involved in passing an AOI to the clip tool, as well as Orders limitations, may flag validation errors that result in your order 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 (PostGIS, Shapely, QGIS to name a few).
• GeoJSON Polygons or MultiPolygons with more than 1,500 vertices.
• Clipping outside of your contractual Area of Access (AOA).

Tool outputs

For scenes source types, one clipped imagery output file is produced for each product bundle at a minimum. If the bundle includes a UDM file, it will also be clipped. nodata pixels will be preserved.

For basemaps source types, all quads and the provenance raster and vector files will be clipped.

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

The clipped file outputs have _clip appended to their file names. If the clip AOI is so large that full scenes or quads 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. 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 order's product bundle.

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 which 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.

Composite

The composite tool allows you to composite a set of images into a single output.

Product inputs

• Supported source types: scenes.
• Supported item types: All item types except for SkySatCollect, TanagerScene, and TanagerMethane.
• Supported product bundles: All product bundles except for those with non-orthorectified images (basic_* bundles).

All product inputs must share the same item type and product bundle (e.g., cannot composite PSScene and SkySatScene). They must also be in the same coordinate reference system (i.e. epsg_code) and have the same band configuration and pixel type. While product inputs do not need to have the same resolution, the output of the composite tool will produce outputs of the resolution of the first product file. The composite tool applies images to the composite "in order" with the later images applied over the earlier images. The ordering of the products influences the output where the last item included in the array is applied last on top.

Output GeoTIFFs created by the composite tool have a maximum area. The limit depends on the item type of the input scenes due to difference in resolution.

• High resolution (SkySatScene): Limit of 375 sqkm per composite
• Medium resolution (PSScene, REOrthoTile): Limit of 1,500 sqkm per composite

Parameters

Property	Type	Required	Enum	Description
group_by	Enum (String)	Optional	order	This option produces a single output composite GeoTIFF from all items in the order. This is the default behavior if no group_by parameter is provided.
group_by	Enum (String)	Optional	strip_id	This option groups items by their strip_id and produces a composite output for each unique strip_id.

Example group by order

JSON

"tools": [
    {
        "composite": {}
    }
]

Python SDK

from planet.order_request import composite_tool

composite = composite_tool()

Example group by strip_id

JSON

"tools": [
    {
        "composite": {
            "group_by": "strip_id"
        }
    }
]

Tool outputs

One or more imagery composites are delivered for a set of product bundles. Corresponding UDMs will also be composited. These files will have _composite appended to their file names.

If grouping by area (default: order), output composite files will use the format: composite.tif.

If grouping by strip_id, output composite files will use the format: <date>_strip_<strip_id>_composite.tif.

In addition, a metadata file is delivered that includes cloud statistics of the composite raster (e.g., cloud_cover) and an updated geometry to reflect the extent of the composite raster.

The metadata file name of the composite by area is: composite_metadata.json.

The metadata file name of the composite by strip_id is: {date}_strip_{strip_id}_composite_metadata.json where {date} is the date of the strip and {strip_id} is the strip_id of the scenes in the composite.

The composite tool passes through RPC and XML files.

Coregister

The coregister tool allows you to coregister a set of target items to a single anchor item within your order, making it easier to perform time series analysis of deep temporal imagery stacks. The coregister tool ensures that images in a specific time series are spatially aligned, so that any feature in one image overlaps as precisely as possible with its position in any other image in the series.

This tool is designed to support coregistration of small areas of interest - contained within a single scene - and works best with high geographic overlap between scenes in the time series.

Product inputs

• Supported source types: scenes.
• Supported item types: All item types except for REScene, TanagerScene, and TanagerMethane.
• Supported product bundles: All product bundles except for basic_* and *_nitf bundles.

Items in the order must geographically overlap with the anchor item to be successfully coregistered.

Parameters

Property	Type	Required	Description
anchor_item	String	Required	The item_id of the item to which all other items should be coregistered. Only one item_id may be supplied, and it must be included as one of the products in the order.

JSON

"tools": [
    {
        "coregister": {
            "anchor_item": "20200630_164149_0e3a"
        }
    }
]

Python SDK

from planet.order_request import coregister_tool

coregister = coregister_tool(anchor_item="20200630_164149_0e3a")

Tool outputs

One imagery output file is produced for each product bundle. The anchor imagery file and corresponding UDM will have _anchor appended to their file names. Imagery files and their corresponding UDMs which are successfully coregistered, or already spatially aligned with the anchor item (i.e. did not need to be coregistered), will have _coreg appended to their file names.

An additional coregistration quality json file is delivered for each item in the order (except the anchor item), which includes details on each output item's transformation.

The coregister tool passes through RPC and XML files.

Item coregistration quality JSON file

The item coregistration quality json sidecar file includes the following information on coregistration transformations:

Parameter	Description
projection_epsg_before	The original projection of the item.
projection_epsg_after	The projection of the item after transformation. If the item was transformed to the anchor item's reprojection, it will be updated. If the item was not reprojected, this field will be empty.
pixel_shift	Describes the transformation in pixels.
matching_score_before	A derived metric which describes image alignment before coregistration. The matching score looks at a combination of Normalized Root Mean Square Error and Structural Similarity Index. A matching score goes from 0 to 1. A score of 0.8 or above indicates that the item already has very good alignment and is already correlated. These files will be marked with the _coreg suffix and will be passed through (or reprojected to the anchor item's projection and delivered). If the score is below 0.8, the tool will attempt to coregister to the item. Note that a score of 0.8 does not necessarily indicate poor alignment.
matching_score_after	A derived metric which describes image alignment after coregistration. If the item was not coregistered because it was already correlated or it failed to successfully coregister, this field will be empty.
matching_score_improvement	The difference in image alignment after coregistration.

Items which fail to coregister or which result in a matching score improvement of less than 0.001 after the transformation will not be transformed. Instead, those items will be delivered without any transformation and _coreg will not be appended to their file names.

Output example - successful coregistration

{
  "projection_epsg_after":"",
  "matching_score_after":0.533,
  "pixel_shift":[
    -1.2461,
    0.909
  ],
  "coreg_method":"imreg_dft",
  "coreg_method_version":"imreg_dft-2.0.0",
  "target_item":"20200531_133140_0f21_3B_Analytic.tif",
  "output_item":[
    "coregistration_example/20200531_133140_0f21_3B_Analytic_coreg.tif",
    "coregistration_example/20200531_133140_0f21_3B_Analytic_DN_coreg_udm.tif"
  ],
  "matching_score_improvement":0.005,
  "anchor_item": "20200526_182301_0f4c_3B_Analytic.tif",
  "matching_score_before":0.528,
  "projection_epsg_before":"32618",
  "details": {}
}

Output example - failed coregistration

{
   "projection_epsg_after":"",
   "matching_score_after":"",
   "pixel_shift":"",
   "coreg_method":"imreg_dft",
   "coreg_method_version":"imreg_dft-2.0.0",
   "target_item":"20200720_194019_0f4c_3B_AnalyticMS.tif",
   "output_item":"coregistration_example/20200720_194019_0f4c_3B_AnalyticMS.tif",
   "matching_score_improvement":"",
   "anchor_item":"20200630_164149_0e3a_3B_AnalyticMS.tif",
   "matching_score_before":"",
   "projection_epsg_before":"",
   "details":{
      "reason":"Coregistration not improved",
      "message":"Calculated improvement for Target 20200720_194019_0f4c_3B_AnalyticMS.tif against reference 20200630_164149_0e3a_3B_AnalyticMS.tif is too low. Matching alignment score difference before and after warping is 0.000138218077682 and  below minimum of 0.001"
   }
}

Output example - skipped coregistration; item already correlated

{
   "projection_epsg_after":null,
   "matching_score_after":"",
   "pixel_shift":"",
   "coreg_method":"imreg_dft",
   "coreg_method_version":"imreg_dft-2.0.0",
   "target_item":"20200714_165944_0f4e_3B_AnalyticMS.tif",
   "output_item":[
      "coregistration_example/20200714_165944_0f4e_3B_AnalyticMS_DN_coreg_udm.tif",
      "coregistration_example/20200714_165944_0f4e_3B_AnalyticMS_coreg.tif"
   ],
   "matching_score_improvement":"",
   "anchor_item":"20200630_164149_0e3a_3B_AnalyticMS.tif",
   "matching_score_before":0.852,
   "projection_epsg_before":"32614",
   "details":{
      "reason":"Images already correlated",
      "message":"Image 20200714_165944_0f4e_3B_AnalyticMS.tif and reference [u'20200630_164149_0e3a_3B_AnalyticMS.tif'] are highly corelated already. MatchingScore: 0.851835213831 (MAX: 0.8)"
   }
}

Because the matching_score_before for 20200714_165944_0f4e_3B_AnalyticMS.tif is greater than 0.8, the item is passed through.

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 source types: scenes.
• Supported item types: All item types except for TanagerScene and TanagerMethane.
• Supported product bundles: All product bundles except for those with NITF images (*_nitf bundles).

When used with the SkySatCollect item type, no more than 100 items should be ordered.

Parameters

Property	Type	Required	Enum	Description
format	Enum (String)	Optional	COG	This option produces a tiled Cloud Optimized GeoTIFF, with LZW compression and powers of two overviews. Learn more about Cloud Optimized GeoTIFFs here.
format	Enum (String)	Optional	PL_NITF	This option converts the output to the National Imagery Transmission Format 2.1 specification. Learn more about the NITF 2.1 specification here. The NITF format only supports WGS84 geographic and UTM projections. The reproject tool may be used to change projections prior to File Format.

JSON

"tools": [
    {
        "file_format": {
            "format": "COG"
        }
    }
]

Python SDK

from planet.order_request import file_format_tool

file_format = file_format_tool(file_format="COG")

Tool outputs

One formatted imagery output file is produced for each product bundle. These files will 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 assets to Sentinel-2 bands (blue, green, red, and narrow near-infrared (NIR)).

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

• Supported source types: scenes.
• Supported item types: PSScene.
• Supported product bundles: analytic_sr_udm2, analytic_8b_sr_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

"tools": [
    {
        "target_sensor": "Sentinel-2",
    }
]

Python SDK

from planet.order_request import harmonize_tool

harmonize = harmonize_tool(target_sensor="Sentinel-2")

Tool outputs

One imagery output file with harmonized band values is delivered for each product bundle. 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 will have _harmonize appended to their file names.

The harmonize tool passes through UDM, RPC, and XML files.

Merge

The merge tool combines all quads that fall within the geometry you specify into a composite image.

Product inputs

• Supported source types: basemaps.
  • Only supported for geometry based requests, not quad_ids.

Parameters

There are no parameters for this operation, the merge body should be an empty dictionary.

JSON

"tools": [
    {
        "merge": {}
    }
]

Tool outputs

One raster GeoTIFF is returned instead of the individual quads. Any assets, such as UDM, are also merged. The output files will have _merge appended to their file names.

The merged output must be less than 425 megapixels (approximately equal to the area of 25 quads with pixel dimensions of 4096x4096 pixels). If the requested merge exceeds 425 megapixels, the create order request returns an error_hint containing the estimated pixel size of the attempted order.

Reproject

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

Product inputs

• Supported source types: scenes and basemaps.
• For scenes source types:
  • Supported item types: All item types except for REScene, TanagerScene, and TanagerMethane.
  • Supported product bundles: All product bundles except for those with non-orthorectified images (basic_* bundles).

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

"tools": [
    {
        "reproject": {
            "projection": "EPSG:4326",
            "kernel": "cubic"
        }
    }
]

Python SDK

from planet.order_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 bundle. UDM files are also reprojected to the target configuration. These files will have _reproject appended to their file names.

The reproject tool passes through XML files.

Tile

The tile tool allows you to split an item or multi-item composite into a regular set of tiles based on a specified tiling system.

The tiling system is a mapping from the projected coordinate system coordinates to tiles referenced by an x and y integer offset from the origin (see {tile_x} and {tile_y} in the name_template).

If your workflow is unconcerned with the tiling coordinate system and simply needs imagery broken into regular chunks, set tile_size to indicate tile size in pixels and accept the default for all other tile parameters`.

If you want to control the alignment of the tile grid, you can set the origin_x and origin_y values. These two parameters default to zero. When the defaults are used, the lower left of tile 0, 0 is at the origin of the projected coordinate system. The {tile_x} and {tile_y} values increase in the same direction as the x and y axes in the projected coordinate system (typically x increases going eastward and y increases going northward).

Given that, you can calculate the left edge of a tile in project coordinates with the following formula:

origin_x + tile_x * tile_size * pixel_size

The bottom edge of the tile in projected coordinates can be calulated with the following formula:

origin_y + tile_y * tile_size * pixel_size

Product inputs

• Supported source types: scenes.
• Supported item types: All item types except for TanagerScene and TanagerMethane.
• Supported product bundles: All product bundles except for those with non-orthorectified images (basic_* bundles) and NITF images (*_nitf bundles).

Parameters

Property	Type	Required	Default	Description
origin_x	Float	Optional	0	Tiling system x origin in projected coordinates.
origin_y	Float	Optional	0	Tiling system y origin in projected coordinates.
pixel_size	Float	Optional	pixel size of input raster	Tiling system pixel size in projected coordinates.
tile_size	Integer	Required		Height and width of the output tiles in pixels and lines, always square.
name_template	String	Optional	{tile_x}_{tile_y}.tif(which would produce something like 128_200.tif)	A naming template for creating output file names. The {tile_x} and {tile_y} parameters can be of the form {tile_x:06d} to produce a fixed width field with leading zeros.
conformal_x_scaling	Boolean	Optional	false	Whether or not to scale the output tiles in the X direction in order to miminize the distortion of shape as the poles are approached, which can be desirable if the coordate system in conformal (such as WGS84). Enabling this parameter will result in the width of tiles being less than the tile_size as one gets further away from the equator.

JSON

"tools": [
    {
        "tile": {
            "origin_x": -20037508.340,
            "origin_y": -20037508.340,
            "pixel_size": 3,
            "tile_size": 256,
            "name_template": "{tilex:07d}_{tiley:07d}.tif"
        }
    }
]

Python SDK

from planet.order_request import tile_tool

tile = tile_tool(
    tile_size=256,
    origin_x=-20037508.340,
    origin_y=-20037508.340,
    pixel_size=3,
    name_template="{tilex:07d}_{tiley:07d}.tif",
)

The output will produce Web Mercator tiles at Zoom Level 15.

Tool outputs

A set of tiled output files are produced for each bundle (or a composite, if paired with the composite tool). UDM files are also tiled. The tiled files will have a file name defined by the name_template tool parameter.

The tile 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 source types: scenes.
• Supported item types: All item types except for PelicanScene, TanagerScene and TanagerMethane.
• Supported product bundles: analytic.

Parameters

Property	Type	Required	Default	Description
scale_factor	Integer	Optional	10000	Scale factor applied to convert 0.0 to 1.0 reflectance floating point values to a value that fits in 16-bit integer pixels. Values over 65535 could result in high reflectances not fitting 16-bit integers.

JSON

"tools": [
    {
        "toar": {
            "scale_factor": 10000
        }
    }
]

Python SDK

from planet.order_request import toar_tool

toar = toar_tool(scale_factor=10000)

Tool outputs

One 16-bit imagery output file, holding scaled reflectance values, will be produced for each product bundle. These files will have _toar appended to their file names.

The toar tool passes through UDM, RPC, and XML files.

Creating Toolchains

To derive insights or perform any meaningful analysis, it is likely that multiple tools will be required to process the data. 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. When using multiple tools in an order, the sequence of tools processed is as follows:

Scenes Orders	Basemaps Orders
Harmonize TOAR Clip Reproject Band Math Tile Composite Coregister File Format	Merge Clip Reproject Band Math

Even if the array you provide does not follow the sequence above, the tools are executed in the sequence above.

Example

In this example, the analytic_udm2 product bundle (and namely, the ortho_analytic_4b asset) is manipulated by three tools in the series: TOAR --> Reproject --> File format.

JSON

{
    "name": "toar, reproject, file_format",
    "source_type": "scenes",
    "products": [
        {
            "item_ids": [
                "20220304_093300_37_2430"
            ],
            "item_type": "PSScene",
            "product_bundle": "analytic_udm2"
        }
    ],
    "tools": [
        {
            "toar": {
                "scale_factor": 10000
            }
        },
        {
            "reproject": {
                "projection": "EPSG:3857",
                "kernel": "near"
            }
        },
        {
            "file_format": {
                "format": "COG"
            }
        }
    ]
}

Python SDK

from planet.order_request import (
    toar_tool,
    reproject_tool,
    file_format_tool,
    build_request,
    product,
)

toar = toar_tool(scale_factor=10000)
reproject = reproject_tool(
    projection="EPSG:3857",
    kernel="near",
)
file_format = file_format_tool(file_format="COG")

tool_chain = [toar, reproject, file_format]

order_request = build_request(
    name="toar, reproject, file_format",
    products=[(product(["20220304_093300_37_2430"], "analytic_udm2", "PSScene"))],
    tools=tool_chain,
)