This tool performs a percentage contrast stretch on a raster image. This operation maps each grid cell value in the input raster image (z) onto a new scale that ranges from a lower-tail clip value (L) to the upper-tail clip value (U), with the user-specified number of tonal values (n), such that:
zn = (z - L) / (U - L) × n
where zn is the output value. The values of L and U are determined from the frequency distribution and the user-specified Tail clip value. For example, if a value of 1% is specified, the tool will determine the values in the input image for which 1% of the grid cells have a lower value L and 1% of the grid cells have a higher value U. The user must also specify which tails to clip (upper, lower, or both).
Notice that any values in the input image that are less than L are assigned a value of L in the output image. Similarly, any input values greater than U are assigned a value of U in the output image. This is a type of linear contrast stretch with saturation at the tails of the frequency distribution. This same stretch can be applied on the fly for displayed raster data by using the Clip buttons associated with the minimum and maximum display values in the Layer Properties.
The following is an example of a Python script that uses this tool:
wd = pluginHost.getWorkingDirectory()
# You may have multiple input files but they must
# be separated by semicolons in the string.
inputFiles = wd + "input1.dep" + ";" + wd + "input2.dep" + ";" + wd + "input3.dep"
outputSuffix = "PercentStretch"
tailClipValue = "1.0"
tailsToClip = "both"
numTones = "256"
args = [inputFile, outputSuffix, tailClipValue, tailsToClip, numTones]
pluginHost.runPlugin("PercentageContrastStretch", args, False)
This is a Groovy script also using this tool:
def wd = pluginHost.getWorkingDirectory()
# You may have multiple input files but they must
# be separated by semicolons in the string.
def inputFiles = wd + "input1.dep" + ";" + wd + "input2.dep" + ";" + wd + "input3.dep"
def outputSuffix = "PercentStretch"
def tailClipValue = "1.0"
def tailsToClip = "both"
def numTones = "256"
String[] args = [inputFile, outputSuffix, tailClipValue, tailsToClip, numTones]
pluginHost.runPlugin("PercentageContrastStretch", args, false)