Stretch

Summary

Enhances an image by changing properties such as brightness, contrast, and gamma through multiple stretch types based on statistics.

Discussion

For more information about how this function works, see the Stretch raster function.

The referenced raster dataset for the raster object is temporary. To make it permanent, you can call the raster object's save method.

Syntax

Stretch (raster, stretch_type, min, max, num_stddev, statistics, dra, {min_percent}, max_percent, {gamma}, {compute_gamma}, sigmoid_strength_level)
ParameterExplanationData Type
raster

The input raster.

Raster
stretch_type
[stretch_type,...]

Specify the type of stretch to apply to the image.

  • NoneNo stretch method will be applied, even if statistics exist.
  • StdDevUses the Brovey algorithm based on spectral modeling for data fusion. Requires the number of standard deviations (num_stddev) to be specified, statistics to be computed, or DRA (dra) set to True.
  • HistogramApply a histogram equalization stretch. Requires the source dataset to have histograms computed, or DRA set to True.
  • MinMaxApplies a linear stretch based on the output minimum and output maximum pixel values, which are used as the endpoints for the histogram. Requires statistics to be computed, or DRA (dra) to be set to True.
  • PercentClipApplies a linear stretch between the defined percent clip minimum and percent clip maximum pixel values.
  • SigmoidPlaces all of the pixels in the image along a sigmoid function (an S-shaped curve).

(The default value is 0)

String
min

Set the lowest pixel value for the output histogram.

The output minimum (min) and output maximum (max) will set the range of values that will then be stretched.

(The default value is None)

Double
max

Set the highest pixel value for the output histogram.

The output maximum (max) and output minimum (min) will set the range of values that will then be stretched.

(The default value is None)

Double
num_stddev

Specify the n value for the number of standard deviations to use. This method is used to emphasize how much feature values vary from the mean value; it is best when used on normally distributed data.

(The default value is None)

Double
statistics
[statistics,...]

By default, the statistics used are retrieved from the data; however, any statistic values you enter in this parameter will be used instead.

Statistics are specified as: [[<min>, <max>, <mean>, <standardDeviation>] [<min>, <max>, <mean>, <standardDeviation>] [<min>, <max>, <mean>, <standardDeviation>]]

(The default value is None)

Double
dra

Calculate statistics from only the pixels displayed on your screen. The statistics parameter is ignored when DRA is True.

  • True—Dynamic Range Adjustment (dra) will be computed.
  • False—Dynamic Range Adjustment (dra) will not be computed.

(The default value is None)

Boolean
min_percent

Specify the percentage of the low values to exclude when the PercentClip stretch is specified.

Valid values range from 0 through 99.

(The default value is None)

Double
max_percent

Specify the percentage of the high values to exclude when the PercentClip stretch is specified.

Valid values range from 0 through 99.

(The default value is None)

Double
gamma

Specify gamma values for each band to apply to the image.

For example, a three-band image would have three values, such as [<gamma1>, <gamma2>, <gamma3>].

(The default value is None)

Double
compute_gamma

Calculates the best gamma value to render the exported image based on an empirical model.

  • True—Gamma values for the image are computed.
  • False—Gamma values for the image are not computed.

(The default value is None)

Boolean
sigmoid_strength_level

Determines how much of the sigmoidal function will be used in the stretch. A low value such as 1 will only use the middle portion of the curve, which tends to produce dull and faint colors. A high value such as 6 will use the entire curve, which tends to produce bold and sharp colors. The valid range is 1 through 6.

(The default value is None)

Integer
Return Value
Data TypeExplanation
Raster

The output stretched raster.

Code sample

Stretch example

Enhances an image by changing properties such as brightness, contrast, and gamma through multiple stretch types based on statistics.

import arcpy

Stretch_raster = arcpy.sa.Stretch(imagePath1, "PercentClip", None, None, None, None, True, 0.25, 0.75, None, None, None)

Related topics