The Orders API exposes a suite of raster customization tools. You can preprocess data at Planet before downloading it or delivering it to a cloud data source. Tools have their own settings and may work on scenes and Basemaps differently depending on the nature of those files. You can request an individual tool or use a chain of tools in the same call. When chaining tools, the sequence matters. After reviewing Using tools and the Creating toolchains sections, use this reference for all available tools.

Using tools	Creating toolchains
Add a tools block to your JSON orders packet and review the results	Understand the precedence of tools in a chain and the expected behavior

Scenes tools	Basemap tools
Band Math Clip Composite Coregister File Harmonization Reproject Tile TOAR	Band Math Clip Merge Reproject

Using tools¶

In this example, we show how to use the Clip tool. Clip basically crops the imagery to the provided boundary. The API payload can be read as: Activate 20170614_113217_3163208_RapidEye-5 analytic bundle and then clip the imagery to the specified AOI, and return download URL for the result.

{
  "name": "just clip",
  "source_type": "scenes",
  "source_type": "scenes",
  "products": [
    {
      "item_ids": [
        "20170614_113217_3163208_RapidEye-5"
      ],
      "item_type": "REOrthoTile",
      "product_bundle": "analytic"
    }
  ],
  "tools": [
    {
      "clip": {
        "aoi": {
          "type": "Polygon",
          "coordinates": [
            [
              [
                -163.828125,
                -44.59046718130883
              ],
              [
                181.7578125,
                -44.59046718130883
              ],
              [
                181.7578125,
                78.42019327591201
              ],
              [
                -163.828125,
                78.42019327591201
              ],
              [
                -163.828125,
                -44.59046718130883
              ]
            ]
          ]
        }
      }
    }
  ]
}

Creating toolchains¶

To derive insights or perform any meaningful analysis, it is likely that you may need multiple tools 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 tools	Basemap tools
`harmonize` `toar` `clip` `reproject` `bandmath` `tile` `composite` `coregister` `fileformat`	`merge` `clip` `reproject` `bandmath`

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

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

TOAR, Reproject, and Tile

{
  "name": "toar and reproject",
  "source_type": "scenes",
  "source_type": "scenes",
    "products": [
    {
      "item_ids": [
        "20170614_113217_3163208_RapidEye-5"
      ],
      "item_type": "REOrthoTile",
      "product_bundle": "analytic"
    }
  ],
  "tools": [
    {
      "toar": {
        "scale_factor": 10000
      }
    },
    {
      "reproject": {
        "projection": "WGS84",
        "kernel": "cubic"
      }
    },
    {
      "tile": {
        "tile_size": 1232,
        "origin_x": -180,
        "origin_y": -90,
        "pixel_size": 0.000027056277056,
        "name_template": "C1232_30_30_{tilex:04d}_{tiley:04d}"
      }
    }
  ]
}

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. (For a list of supported mathematical functions, see Bandmath supported numpy math routines.)

Product inputs¶

The source_type for this tool is scenes. The bandmath tool supports PlanetScope, SkySat, and RapidEye bundles except for those with non-orthorectified images (designated as 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.

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

{
  "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"
      }
    }
  ]
}

The output of this tool is a bundle that includes all four bands of the original file, a fourth band that is the ar 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 bundle, 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 or a Basemap 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.

For Basemaps, use this operation only with orders that use a geometry in the product block. When you order a Basemap using an Area of Interest, whole quads are returned. This tool clips those quads to your Area of Interest and operates on that geometry specified in your product block. For example:

"tools": [{"clip": {}}]

This code does not work for Basemap orders placed using quad IDs.

Product inputs¶

The source_type for this tool is either scenes or basemaps. The clip tool supports all item types and all bundle types except for those with non-orthorectified images (basic_* bundles).

Parameters¶

For Basemaps, there are no parameters for this operation, as the geometry in the product block is used as the area of interest.

For scenes, there is one parameter:

aoi (dict): GeoJSON polygon or multipolygon defining the clip area, with up to 1500 vertices. The minimum geographic area of any polygon or internal ring is one square meter. The clip tool requires an AOI when used with scenes orders but doesn’t take an AOI when used for basemaps orders.

Example request

{
  "name": "clip_example",
  "source_type": "scenes",
  "products": [
    {
      "item_ids": [
        "20201129_150531_19_1065"
      ],
      "item_type": "PSScene",
      "product_bundle": "analytic_sr_udm2"
    }
  ],
  "tools": [
    {
      "clip": {
        "aoi": {
          "type": "Polygon",
          "coordinates": [
            [
              [
                -71.42186164855957,
                41.830816472727356
              ],
              [
                -71.41611099243164,
                41.812267143599804
              ],
              [
                -71.39302253723143,
                41.821862295060974
              ],
              [
                -71.39920234680176,
                41.83363038420449
              ],
              [
                -71.42186164855957,
                41.830816472727356
              ]
            ]
          ]
        }
      }
    }
  ]
}

AOI geometry limits on clipping scenes¶

While clipping an AOI with GeoJSON, users should be aware of multipolygon limitation for successful order creation. The python-geojson and python-shapely validation process involved in passing an AOI to the clip tool, as well as Orders v2 limitations, may flag validation errors that result in your order being rejected. The following geometries are invalid and will result in unsuccessful orders:

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 1500 vertices will be rejected.
Clipping outside of the contract AOI may result in a rejected order.

Tool outputs¶

For scenes, one clipped imagery output file is produced for each product bundle. nodata pixels will be preserved.

UDM files will also be clipped, and XML file attributes “filename”, “numRows”, “numColumns” and “footprint” are 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 do not have “_clip” appended to their file name.

For scenes orders, 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 bundle.

Info

There may sometimes be discrepancies between an asset’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 circumstance, no imagery file is delivered but auxiliary assets are delivered.

Composite¶

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

Product inputs¶

The source_type for this tool is scenes. The composite tool supports all item types except for SkySatCollect and all bundle types except for those with non-orthorectified images (basic_* bundles). All product inputs must share the same item type and product bundle.

All product inputs must be in the same coordinate 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 has the same resolution as 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 differences in resolution.

High resolution (SkySatScene): Limit of 375 sqkm per composite
Medium resolution (PSScene, REOrthoTile, Sentinel2L1C): Limit of 9,000 sqkm per composite
Low resolution (Landsat8L1G): Limit of 1,200,000 sqkm per composite

Parameters¶

group_by (enum) (optional): Defines how items are grouped to create one or more composites. Currently, the tool supports two group_by values:
- “order”: All input items in the order will be used to create a single output composite geotiff. This is the default behavior if no group_by parameter is provided.
- “strip_id”: Input items will be grouped by their strip_id. If there are items from multiple strips then there will be multiple output composite geotiffs.

Example request - composite by order

{
  "name": "composite by order example",
  "products": [
    {
      "item_ids": [
        "20200710_172116_0e19",
        "20200710_172117_0e19"
      ],
      "item_type": "PSScene",
      "product_bundle": "analytic_udm2"
    }
  ],
  "tools": [
    {
      "composite": {
        }
    }
  ]
}

Example request - composite by strip_id

The payload below contains 5 items from two unique strips so the order will contain two output composite files.

{
  "name": "composite by strip_id example",
  "products": [
    {
      "item_ids": [
        "20220808_181151_70_2426",
        "20220808_181149_44_2426",
        "20220808_181147_18_2426",
        "20220808_175911_89_249d",
        "20220808_175909_61_249d"
      ],
      "item_type": "PSScene",
      "product_bundle": "visual"
    }
  ],
  "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 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 (for example, 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 is:

<date>_strip_<stripid>_composite_metadata.json

where <date> is the date of the strip and <stripid> is the strip id of the scenes in the composite.

The 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 coregistration tool ensures that images in a specified 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 times series.

Product inputs¶

The source_type for this tool is scenes. The coregister tool supports all item types except for REScene and all bundle types except for basic_* and *_nitf bundles. It is not compatible with the composite tool.

Parameters¶

anchor_item (string) (required): The item_id of the item to which all other items should be coregistered. Currently, only one item_id may be supplied, and it must be included as one of the products in the order. Items in the order must geographically overlap with the anchor item to be successfully coregistered.

Example request

{
  "name": "coreg_example",
  "source_type": "scenes",
  "products": [
    {
      "item_ids": [
        "20200720_194019_0f4c",
        "20200714_165944_0f4e",
        "20200630_164149_0e3a"
      ],
      "item_type": "PSScene",
      "product_bundle": "analytic_udm2"
    }
  ],
  "tools": [
    {
      "coregister": {
        "anchor_item": "20200630_164149_0e3a"
      }
    }
  ]
}

Tool outputs¶

One imagery output file is produced for each 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.

The tool delivers an additional coregistration quality json file for each item in the order (except for the anchor item), which includes details on each output item's transformation. Rpc and xml files will be passed through.

Item coregistration quality JSON file parameters¶

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

projection_epsg_before: Lists the original projection of the item.
projection_epsg_after: Lists the projection of the item after transformation. If it 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 coregistration 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 above 0.8 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 projection and delivered).
- If the score is below 0.8, the tool will attempt to coregister 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 it 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 coregistration transformation will not be transformed. Instead, those will be delivered without any coregistration (or reprojection) 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 – coregistration failure

{
   "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 – coregistration skipped; 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 thorugh.

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 source_type for this tool is scenes. The file_format tool supports all item types and all bundle types except for those with NITF images (designated as *_nitf bundles). When used with SkySatCollect item types, no more than 100 items should be ordered.

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 on Cloud Optimized GeoTIFFs here.
- "PL_NITF": This option converts the output to the National Imagery Transmission Format 2.1 specification. You can find more information the NITF 2.1 specification here. The NITF format only supports WGS84 geographic and UTM projections. A Reproject tool may be used to change projections prior to File Format.

Example request

{
  "name": "file_format_example",
  "source_type": "scenes",
  "products": [
    {
      "item_ids": [
        "20200710_172116_0e19"
      ],
      "item_type": "PSScene",
      "product_bundle": "analytic_udm2"
    }
  ],
  "tools": [
    {
      "file_format": {
        "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 tool passes through udms, rpcs, and xml 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 product bundles 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 bundles from PlanetScope instrument types (PS2, PS2.SD, and PSB.SD) can be harmonized to Sentinel-2.
With the Sentinel-2 target sensor, the tool harmonizes PSScene surface reflectance bundle types (analytic_8b_sr_udm2, analytic_sr_udm2) to Sentinel-2 bands (blue, green, red, and narrow near-infrared (NIR)).

Note

analytic bundles are not supported.

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

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

Merge¶

The Basemap merge tool combines all quads that fall within the geometry you specify into a composite image. One raster GeoTIFF is returned instead of the individual quads. Any assets, such as UDM, are also merged. The output files have _merge appended to the file names.

The merge tool requires a geometry and does not work for orders by list of quad_ids.

Product inputs¶

The source_type for this tool is basemaps.

Parameters¶

There are no parameters for this operation.

Example request¶

{
  "name": "basemap order with geometry",
  "source_type": "basemaps",
  "products": [
    {
      "mosaic_name": "global_monthly_2022_01_mosaic",
      "geometry":{
        "type": "Polygon",
        "coordinates":[
          [
            [4.607406, 52.353994],
            [4.680005, 52.353994],
            [4.680005, 52.395523],
            [4.607406, 52.395523],
            [4.607406, 52.353994]
          ]
      ]
      }
   }
  ],
    "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 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 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 scenes and Basemaps to a new projected coordinate system and resolution.

Product inputs¶

The reproject tool supports all Basemaps, and all scene item types and bundle types except for those with non-orthorectified images (basic_* bundles). For scenes, the item type REScene is also disallowed.

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 request

{
  "name": "reproject_example",
  "source_type": "scenes",
  "products": [
    {
      "item_ids": [
        "20200710_172116_0e19"
      ],
      "item_type": "PSScene",
      "product_bundle": "analytic_udm2"
    }
  ],
  "tools": [
    {
      "reproject": {
        "projection": "EPSG:4326",
        "kernel": "cubic"
      }
    }
  ]
}

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 file outputs have “_reproject” appended to their file names.

The 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 {tilex} and {tiley} 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 {tilex} and {tiley} 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 projected coordinates with this formula:

origin_x + tilex * tile_size * pixel_size

And the bottom edge of the tile in projected coordinates can be calculated with this:

origin_y + tiley * tile_size * pixel_size

Product inputs¶

The source_type for this tool is scenes. The tile tool supports all item types and all bundle types except for those with non-orthorectified images (basic_* bundles) and NITF images (*_nitf bundles).

Parameters¶

origin_x (float): Tiling system x origin in projected coordinates (default is zero)
origin_y (float): Tiling system y origin in projected coordinates (default is zero)
pixel_size (float): Tiling system pixel size in projected coordinates (defaults to pixel_size of input raster).
tile_size (integer): Height and width of output tiles in pixels and lines (always square) (required)
name_template (string): A naming template for creating output tile filenames. The default is "{tilex}_{tiley}.tif" resulting in filenames like 128_200.tif. The {tilex} and {tiley} parameters can be of the form {tilex:06d} to produce a fixed width field with leading zeros.
conformal_x_scaling (boolean): If the coordinate system is conformal (such as WGS84) it may be desirable to scale output tiles in the X direction in order to minimize the distortion of shape as the poles are approached. Enabling this will reduce in the width of tiles being less than tile_size as one gets further away from the equator.

Example request

{
  "name": "web_mercator_zoom_15_tile_example",
  "source_type": "scenes",
  "products": [
    {
      "item_ids": [
        "20200710_172116_0e19"
      ],
      "item_type": "PSScene",
      "product_bundle": "analytic_udm2"
    }
  ],
  "tools": [
    {
      "tile": {
        "origin_x": -20037508.340,
        "origin_y": -20037508.340,
        "pixel_size": 3,
        "tile_size": 256,
        "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 composite). Udm files are also tiled. The tiled files will have a file name defined by the “name_template” tool parameter below.

The tool passes through xml files.

Top of Atmosphere Reflectance¶

The Top of Atmosphere Reflectance (TOAR) tool converts Analytic assets from top of atmosphere (TOA) radiance to a TOA scaled reflectance. The Orders 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 source_type for this tool is scenes. The toar tool supports the analytic bundle type for all item types.

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.

{
  "name": "toar_example",
  "source_type": "scenes",
  "products": [
    {
      "item_ids": [
        "20200710_172116_0e19"
      ],
      "item_type": "PSScene",
      "product_bundle": "analytic_udm2"
    }
  ],
  "tools": [
    {
      "toar": {
        "scale_factor": 10000
      }
    }
  ]
}

Tool outputs¶

One 16bit 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 tool passes through udms, rpcs, and xml files.

We are continually working to improve our technical documentation and support. Please help by sharing your experience with us.

Send Us Your Feedback

Orders API Tools

last updated: October 24, 2024

Using tools¶

Creating toolchains¶

Tools Reference¶

Band math¶

Product inputs¶

Parameters¶

Tool outputs¶

Clip¶

Product inputs¶

Parameters¶

AOI geometry limits on clipping scenes¶

Tool outputs¶

Composite¶

Product inputs¶

Parameters¶

Tool outputs¶

Coregister¶

Product inputs¶

Parameters¶

Tool outputs¶

Item coregistration quality JSON file parameters¶

File Format¶

Product inputs¶

Parameters¶

Tool outputs¶

Harmonization¶

Parameters¶

Target Sensor Options¶

Sentinel-2¶

Tool outputs¶

Merge¶

Product inputs¶

Parameters¶

Example request¶

Tool outputs¶

Reproject¶

Product inputs¶

Parameters¶

Tool outputs¶

Tile¶

Product inputs¶

Parameters¶

Tool outputs¶

Top of Atmosphere Reflectance¶

Product inputs¶

Parameters¶

Tool outputs¶