EOMasters Toolbox Pro

  SpeX Processor - Command Line Interface

Overview

Since the SpeX Processor makes use of the SNAP graph processing framework, it can be used by the command line tool gpt. General information about GPF and GPT can be found on their help pages. Specific help for the SpeX Processor can be obtained with: ${SNAP-INSTALL-DIR}/bin/gpt -h spex
This will show the following help:

Usage:
gpt Spex [options]

Description:
  Creates SpeX (SPEctral indeX) images for a source product. See help pages for detailed instructions.


Source Options:
  -SsourceProduct=<file>    The source product
                            This is a mandatory source.

Parameter Options:
  -Pshapefile=<path>                       An ESRI shapefile, providing the considered geographical region(s).
  -PspexList=<string,string,string,...>    List of short names of SpeX to be calculated.
  -PvalidExpression=<string>               The valid expression to be used for the spectral index.
  -PwktRegion=<geometry>                   The considered geographical region as a geometry in well-known text format (WKT).

Graph XML Format:
  <graph id="someGraphId">
    <version>1.0</version>
    <node id="someNodeId">
      <operator>Spex</operator>
      <sources>
        <sourceProduct>${sourceProduct}</sourceProduct>
      </sources>
      <parameters>
        <spexList>string,string,string,...</spexList>
        <validExpression>string</validExpression>
        <shapefile>path</shapefile>
        <wktRegion>geometry</wktRegion>
        <customIndices>
          <index>
            <name>string</name>
            <domain>domain</domain>
            <formula>string</formula>
            <description>string</description>
            <reference>string</reference>
            <sourceName>string</sourceName>
            <sourceUrl>string</sourceUrl>
            <validExpression>string</validExpression>
            <shapefile>path</shapefile>
            <wktRegion>geometry</wktRegion>
          </index>
          <_.002e../>
        </customIndices>
      </parameters>
    </node>
  </graph>

Note
Please ignore <_.002e../>. This is a wrong addition by SNAP. It should actually be <.../> and indicates that multiple of the preceding tag <index/> can follow.

Parameters

If you want to define custom spectral indices, you can only do it using a graph xml file. Specifying custom indices is to complex to be done directly on the command line. A possible graph xml file could look like the following:

<graph id="someGraphId">
  <version>1.0</version>
  <node id="spexNode">
    <operator>Spex</operator>
    <sources>
      <sourceProduct>${sourceProduct}</sourceProduct>
    </sources>
    <parameters>
      <spexList>NDVI</spexList>
      <validExpression>!flags.INVALID</validExpression>
      <customIndices>
        <index>
          <name>myNDVI</name>
          <formula>(N - RE1) / (N + RE1)</formula>
          <validExpression>flags.LAND</validExpression>
          <wktRegion>POLYGON ((-1.08 46.98, 0.54 46.63, 0.32 46.15, -1.28 46.51, -1.08 46.98))</wktRegion>
        </index>
        <index>
          <name>NDWI</name>
          <validExpression>flags.WATER</validExpression>
        </index>
        <index>
          <name>special</name>
          <formula>(B3 - B8) / (B3 + B8)</formula>
          <description>Using directly the bands of the source product</description>
        </index>
      </customIndices>
    </parameters>
  </node>
</graph>

A custom spectral index can simply be defined by a known name from the database. It is optional to overwrite other attributes and add additional masks. Even the formula does not need to use symbols but can use directly band names from the source product.

Mask Combination

The general masks apply to all indices, either specified in the spexList or one of the custom indices. When multiple masks are specified, they are combined using the logical AND operator. This means that a pixel is only valid if it is valid for all masks. For example, if the general validExpression mask is set to flags.LAND and the shapefile mask of an index ist set to cover a city, only the land pixels covered by this city shape are processed. The invalid pixels of bands used in the formulas, defined by the bands no-data value and valid-pixel expression, are considered by default.

Resampling of source data

If a source product has bands of different sizes, e.g. Sentinel-2 products, they are resampled to the highest resolution of the product. This is done by using the SNAP Resample operation with the default parameters. If a different resampling is required the source product should be resampled first.

CLI Processing Examples

Here are some examples how to use the SpeX Processor from the command line.

Example 1

Compute the NDVI and NBR indices for the given source product only over land and save the result as a BEAM-DIMAP product.

gpt Spex -PspexList=NDVI,NBR -PvalidExpression=flags.LAND -t spex.dim -SsourceProduct=source.dim

Example 2

Compute the NDVI, NBAI and NWI for the given source product and save the result as a GeoTIFF product.

gpt Spex -PspexList=NDVI,NBAI,NWI -Pshapefile=computeRegion.shp -t spex.tif -f GeoTIFF source.dim