The APPLY_FORMULA command allows you to apply a mathematical formula to the bands in one or more loaded raster layers to create a new raster or grid layer. This is useful for doing things like NDVI or NDWI calculations from multi-spectral imagery, among a large array of other multi-spectral analysis.
The following parameters are supported by the command:
- FILENAME - filename of the layer(s) to use as input to the operation. You can use * to use all loaded raster imagery layers. This is the default. This parameter can be listed more than once to specify multiple input files, like FILENAME="FILENAME_1" FILENAME="FILENAME_2". When multiple bands are named in the FORMULA they will be assigned in the order the files are listed. In this case, B1 would represent FILENAME_1 and B2 would represent FILENAME_2. You can also pass in the description of the layer if it isn't based on a file, such as a layer created by the script. When running the script in the context of the main map view (including loading a workspace) you can also pass in the value 'USER CREATED FEATURES' to have the 'User Created Features' layer updated or 'SELECTED LAYERS' to have any layers selected in the Control Center
- LAYER_DESC - description to assign to the newly created layer
- FORMULA - this free-form string describes the formula for a single band of the output. You would have a separate FORMULA parameter for each output band. So if you were creating a 3-band output you would have 3 separate FORMULA parameters. Each FORMULA parameter is a string that can either be the name of a pre-defined operation, like NDVI or NDWI, or a free-form equation definition. See formula reference documentation for details. The bands default to the original source bands from the provided input layers, but you can use the NUM_BANDS, BAND_BIT_DEPTH, and BAND_EXPORT_SETUP parameters (described below) to customize which bands from which input layers are assigned to each band number variable in the formula.
- OUTPUT_BIT_DEPTH - specifies the bit depth for the output band(s) (one for each FORMULA parameter). Valid values are 8, 16, or 32. If you don't specify this then you will get 32-bit floating point values if the output is a single band grid and 8-bit per band for imagery output.
- OUTPUT_GRID - specifies whether the output should be treated as a grid that is shaded using an "elevation" shader or as an imagery layer. Use OUTPUT_GRID=YES to make it a shaded grid.
- NUM_BANDS - specifies how many bands of data to make available for input. If you don't specify a value for this the band count will be the maximum available for any of the loaded layers.
- BAND_BIT_DEPTH - specifies how many bits to use for each band of data. If you don't specify a value for this the highest bit depth of any of the input data layers will be used. The valid values are BAND_BIT_DEPTH=8, BAND_BIT_DEPTH=16, or BAND_BIT_DEPTH=32.
- BAND_EXPORT_SETUP - allows you to override the default band assignment for the FORMULA parameters. Use the following format to specify what band from what layer to use for a given export band: <output_band>?<input_band>?<layer_filename> . So for example to assign the 4th (infrared) band in an export from the 1st (red) band in a previously loaded file name C:\data\input_file.tif, use the following parameter: BAND_EXPORT_SETUP="4?1?c:\data\input_file.tif". Note that you would include a separate BAND_EXPORT_SETUP parameter for each output band that you want to setup. If you leave off the filename then you all loaded data will be considered as input, with just the input-to-output band assignment being updated.
SAMPLE
Here is an example script command showing how to apply a formula to all currently loaded raster layers.
GLOBAL_MAPPER_SCRIPT VERSION=1.00 APPLY_FORMULA FILENAME="*" OUTPUT_BIT_DEPTH="8" FORMULA="IF(B1<90, B1*0.765+20, B1)"
GLOBAL_MAPPER_SCRIPT VERSION=1.00 APPLY_FORMULA FILENAME="Layer1_Grid" Filename="Layer2_Grid" FORMULA="IF(B1=0,B2,B1)"