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’s expression, the bandmath tool supports normal arithmetic operations and simple math operators offered in Python's numpy package (available as "np" for methods needed from the package).

Product Inputs

The bandmath tool supports all item types and all bundle types 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. There is currently no mechanism to do non-local operations (i.e. band math expressions may not reference neighboring pixels). The tool can calculate up to nine bands for an item.

  • b1 (string): An expression defining how output band 1 should be computed.
  • b2 (string): An expression defining how output band 2 should be computed. (optional)
  • b3 (string): An expression defining how output band 3 should be computed. (optional)
  • ...
  • b9 (string): An expression defining how output band 9 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",
  "products": [
    {
      "item_ids": [
        "20200710_172116_0e19"
      ],
      "item_type": "PSScene4Band",
      "product_bundle": "analytic"
    }
  ],
  "tools": [
    {
      "bandmath": {
        "b1": "b1",
        "b2": "b2",
        "b3": "b3",
        "b4": "b4",
        "b5": "(b4-b3)/(b4+b3)",
        "pixel_type": "16U"
      }
    }
  ]
}

The output of this tool will be an asset which includes all four bands of the original file, 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 will have “_bandmath” appended to their file names.

The tool passes through udm, rpc, and xml 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 and all bundle types except for those with non-orthorectified images (basic_* bundles).

Parameters

  • aoi (dict): GeoJSON polygon or multipolygon defining the clip area, with up to 500 vertices

Example Request

{
  "name": "clip_example",
  "products": [
    {
      "item_ids": [
        "20200710_172116_0e19"
      ],
      "item_type": "PSScene4Band",
      "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
            ]
          ]
        }
      }
    }
  ]
}

Tool Outputs

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” will be updated based on the clip results.

The clipped file outputs 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.

Composite

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

Product Inputs

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 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 will have the same resolution as the first product file.

Parameters

There are no parameters for this operation.

Example Request

{
  "name": "composite_example",
  "products": [
    {
      "item_ids": [
        "20200710_172116_0e19",
        "20200710_172117_0e19"
      ],
      "item_type": "PSScene4Band",
      "product_bundle": "analytic"
    }
  ],
  "tools": [
    {
      "composite": {
        }
    }
  ]
}

Tool Outputs

A single imagery composite is delivered for a set of product bundles. Udms will also each be composited into a single file. These files will have "_composite" appended to their file names.

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 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",
  "products": [
    {
      "item_ids": [
        "20200720_194019_0f4c",
        "20200714_165944_0f4e",
        "20200630_164149_0e3a"
      ],
      "item_type": "PSScene4Band",
      "product_bundle": "analytic"
    }
  ],
  "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.

Coregister Tool Feedback

We'd love any feedback you have on the Coregister Tool here

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 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",
  "products": [
    {
      "item_ids": [
        "20200710_172116_0e19"
      ],
      "item_type": "PSScene4Band",
      "product_bundle": "analytic"
    }
  ],
  "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.

Reproject

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

Product Inputs

The reproject tool supports all item types and all bundle types except for those with non-orthorectified images (basic_* bundles).

Parameters

  • projection (string): A coordinate system in the form EPSG:n (ex. EPSG:4326 for WGS84, EPSG:32611 for UTM 11 North (WGS84), or EPSG:3857 for Web Mercator)
  • resolution (float): The pixel width and height in the output file. If not provided, it will default to the resolution of the input item. This value will be in meters unless the coordinate system is geographic (like EPSG:4326), then it will be a pixel size in decimal degrees.
  • kernel (string): The resampling kernel used. If not provided, it will default to "near". Udm files will always use "near". This parameter also supports "bilinear", "cubic", "cubicspline", "lanczos", "average" and "mode" (see the gdalwarp "resampling_method" docs for details).

Example Request

{
  "name": "reproject_example",
  "products": [
    {
      "item_ids": [
        "20200710_172116_0e19"
      ],
      "item_type": "PSScene4Band",
      "product_bundle": "analytic"
    }
  ],
  "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 will 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").

A common tile specification uses the Web Mercator tiling system where the origin is in the lower left corner of the world and tiles are numbers from that origin.

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.

Product Inputs

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 x 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",
  "products": [
    {
      "item_ids": [
        "20200710_172116_0e19"
      ],
      "item_type": "PSScene4Band",
      "product_bundle": "analytic"
    }
  ],
  "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 (TOAR)

The toar tool allows you to convert analytic imagery products to top of atmosphere reflectance products. Top of atmosphere reflectance products may be useful when looking at open water and coastal areas.

Product Inputs

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",
  "products": [
    {
      "item_ids": [
        "20200710_172116_0e19"
      ],
      "item_type": "PSScene4Band",
      "product_bundle": "analytic"
    }
  ],
  "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.

Harmonization

The harmonize tool allows you to radiometrically harmonize imagery captured by one satellite instrument type to imagery captured by another. At this time, only harmonization of Dove-R (instrument_id PS2.SD) to Dove Classic (insturment_id PS2) radiometry is supported.

Product Inputs

The harmonize tool supports the analytic bundle type for PSScene3Band, PSScene4Band, and PSOrthoTile item types. Note: analytic_sr bundles are not supported.

Parameters

  • target_sensor (string): A value indicating to what sensor the input product bundles should be calibrated. Each sensor value will transform items captured by a defined set of instrument ids. Items which have not been captured by that defined set of instrument ids will be unaffected by (pass through) the harmonization operation.
    • Currently, only "PS2" (Dove Classic) is supported as a target sensor, and it will transform only items captured by “PS2.SD” (Dove-R).

Example Request

{
  "name": "harmonize_example",
  "products": [
    {
      "item_ids": [
        "20200710_172116_0e19"
      ],
      "item_type": "PSScene4Band",
      "product_bundle": "analytic"
    }
  ],
  "tools": [
    {
      "harmonize": {
        "target_sensor": "PS2"
      }
    }
  ]
}

Tool Outputs

One imagery output file with harmonized band values will be delivered for each product bundle. The transformation of each item will depend 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 tool passes through udms, rpcs, and xml files.