Gradient

Summary

Calculates the gradient along x, y, x,y, or a given dimension.

Discussion

The Gradient function works on a single-band input. If the input is multiband, the first band will be used. Use the ExtractBand function to specify the required band.

For multidimensional input that contains multiple variables, all variables will be processed. If a variable does not contain the specified gradient_dimension parameter, it will be ignored. Use the Multidimensional Filter function to select the required variables.

The Multidimensional Filter function can also be used to define the dimension range for which the function is applied.

The following table lists the equations for the various gradient calculations:

Gradient type	Equation
Gradient X	\((right \space pixel \space - \space current \space pixel) \space / \space Denominator \space Unit\)
Gradient Y	\((lower \space pixel \space - \space current \space pixel) \space / \space Denominator \space Unit\)
Gradient for a dimension	\((next \space slice \space - \space current \space slice) \space / \space Denominator \space Unit\)

Syntax

Gradient(raster, {gradient_dimension}, {denominator_unit})

Parameter	Explanation	Data Type
raster	The input raster or list of rasters.	Raster
gradient_dimension	The available dimensions for which the gradient will be calculated. For nonmultidimensional input, available dimension options are X, Y, and XY. For multidimensional input, available dimension options are X, Y, XY, and all dimensions available in the data, including time (StdTime). If there are two or more dimensions, the gradient will be calculated on the gradient dimension for all slices in the available dimensions. The XY option outputs a 2-band raster in which band 1 represents the gradient along the x-dimension, and band 2 represents the gradient along the y-dimension. The default value is X.	String
denominator_unit	The unit of the gradient denominator. The unit depends on the gradient_dimension argument value. The following options are available for X, Y, and XY: DEFAULT—The output will be the difference between adjacent cells. This is the default. CELLSIZE—The output will be the difference between adjacent cells divided by the cell size of the input. The output unit will be the same as the unit of the x,y coordinates of the input. If the data is in a geographic coordinate system, it will be converted to meters. The following options are available for StdTime: DEFAULT—The output will be the difference between adjacent slices. This is the default. PER_HOUR—The output will be the difference between adjacent slices divided by the difference between the time values and converted to the per-hour rate. PER_DAY—The output will be the difference between adjacent slices divided by the difference between their time values and converted to the per-day rate. PER_MONTH—The output will be the difference between adjacent slices divided by the difference between their time values and converted to the per-month rate. PER_YEAR—The output will be the difference between adjacent slices divided by the difference between their time values and converted to the per-year rate. PER_DECADE—The output will be the difference between adjacent slices divided by the difference between their time values and converted to the per-decade rate. The following options are available for dimensions other than time dimensions: DEFAULT—The output will be the difference between adjacent slices. This is the default. DIMENSION_INTERVAL—The output will be the difference between adjacent slices divided by the difference between their dimension values. The default value is DEFAULT.	String

Return value

Data Type	Explanation
Raster	The output raster.

Code sample

Gradient example 1

Calculate the gradient along the x and y dimensions of a Landsat image.

# Import system modules
import arcpy
from arcpy.ia import *
arcpy.ia.Gradient(raster, gradient_dimension, denominator_unit)

# Set local variables
input_raster = in_multidimensional_raster = "C:/data/landsat.crf"
gradient_dimension = "XY"
denominator_unit = "Cellsize"
# Apply Gradient function
gradient_raster = arcpy.ia.Gradient (raster, gradient_dimension, denominator_unit)
# Save the output
gradient_raster.save("C:/output/landsat_xy_gradient.crf")

Gradient example 2

This example calculates the gradient along StdTime of an NDVI time series.

# Import system modules
import arcpy
from arcpy.ia import *
arcpy.ia.Gradient (raster, gradient_dimension, denominator_unit)

# Set local variables
input_raster = in_multidimensional_raster = "C:/data/ndvi_time_series.crf"
gradient_dimension = "StdTime"
denominator_unit = "Per Year"
# Apply Gradient function
gradient_raster = arcpy.ia.Gradient (raster, gradient_dimension, denominator_unit)
# Save the output
gradient_raster.save("C:/output/ndvi_stdtime_gradient.crf")