Topographic Position Index (Spatial Analyst Tools)

Summary

Calculates the topographic position index value for each cell within a specified neighborhood.

Learn more about how Topographic Position Index works

Usage

The output raster of this tool contains the Topographic Position Index (TPI) values for each cell. A TPI value is the difference between the current cell value and the mean value of all the cells in its neighborhood.
The available neighborhood shapes are annulus (a donut or ring), circle, rectangle, and wedge. A custom neighborhood shape can be defined using a kernel file.
When a circular, annulus-shaped, or wedge-shaped neighborhood is specified, some of the outer diagonal cells may not be considered in the calculations because the center of the cell must be encompassed within the neighborhood.
The irregular neighborhood type requires that a kernel file value be specified. A kernel file is an ASCII text file that specifies the values and shape of the neighborhood. The file can be created with any plain text editor. The file must have a .txt extension and no spaces in the file name.
When the output raster format is .crf, this tool supports the Pyramid raster storage environment. Pyramids will be created in the output by default. For any other output format, this environment is not supported, and pyramids will not be created.
See Analysis environments and Spatial Analyst for additional details on the geoprocessing environments that apply to this tool.

Label	Explanation	Data type
Input Surface Raster	The input surface raster.	Raster Layer
Neighborhood (Optional)	The cells surrounding a processing cell that will be used in the TPI calculation. There are several predefined neighborhood types to choose from, or a custom kernel can be defined. Once the neighborhood type is selected, other parameters can be set to fully define the shape, size, and units of measure. The default neighborhood is an annulus with an inner radius of one cell and an outer radius of three cells. The following are the forms of the available neighborhood types: Annulus, Inner radius, Outer radius, Units type A ring or donut-shaped neighborhood defined by an inner radius and an outer radius. The minimum value for radius is 1 cell, and the outer radius must be larger than the inner. The maximum inner radius is 2046 cells, and the maximum outer radius is 2047 cells. The default annulus is an inner radius of 1 cell and an outer radius of 3 cells. Circle, Radius, Units type A circular neighborhood with the given radius. The minimum value for radius is 1 cell, and the maximum value is 2047 cells. The default radius is 3 cells. Rectangle, Height, Width, Units type A rectangular neighborhood defined by width and height. The minimum value for width or height is 1 cell, and the maximum value is 4096 cells. The default is a square with a width and height of 3 cells. Wedge, Radius, Start angle, End angle, Units type A wedge-shaped neighborhood defined by a radius, a start angle, and an end angle. The minimum value for radius is 1 cell, and the maximum value is 2047 cells. The wedge extends counterclockwise from the starting angle to the ending angle. Angles are specified in degrees, with 0 or 360 representing east. Negative angles can be used. The default wedge is from 0 to 90 degrees, with a radius of 3 cells. Irregular, Kernel file A custom neighborhood with specifications set by the identified kernel text file. The minimum value for width or height of the kernel is 1 cell, and the maximum value is 4096 cells. For the annulus, circle, rectangle and wedge neighborhood types, the distance units for the parameters can be specified in Cell units or Map units. Cell units is the default. For the irregular neighborhood type, the first line in the kernel file defines the width and height of the neighborhood in numbers of cells. The subsequent lines indicate how the input value that corresponds to that location in the kernel will be processed. A value of 0 in the kernel file indicates that the corresponding location will not be included in the calculation. A value of 1 in the kernel file indicates that the corresponding input cell will be included in the operation.	Neighborhood

Label

Explanation

Data type

Input Surface Raster

The input surface raster.

Raster Layer

Neighborhood

(Optional)

The cells surrounding a processing cell that will be used in the TPI calculation. There are several predefined neighborhood types to choose from, or a custom kernel can be defined.

Once the neighborhood type is selected, other parameters can be set to fully define the shape, size, and units of measure. The default neighborhood is an annulus with an inner radius of one cell and an outer radius of three cells.

The following are the forms of the available neighborhood types:

Annulus, Inner radius, Outer radius, Units type

A ring or donut-shaped neighborhood defined by an inner radius and an outer radius. The minimum value for radius is 1 cell, and the outer radius must be larger than the inner. The maximum inner radius is 2046 cells, and the maximum outer radius is 2047 cells. The default annulus is an inner radius of 1 cell and an outer radius of 3 cells.
Circle, Radius, Units type

A circular neighborhood with the given radius. The minimum value for radius is 1 cell, and the maximum value is 2047 cells. The default radius is 3 cells.
Rectangle, Height, Width, Units type

A rectangular neighborhood defined by width and height. The minimum value for width or height is 1 cell, and the maximum value is 4096 cells. The default is a square with a width and height of 3 cells.
Wedge, Radius, Start angle, End angle, Units type

A wedge-shaped neighborhood defined by a radius, a start angle, and an end angle. The minimum value for radius is 1 cell, and the maximum value is 2047 cells. The wedge extends counterclockwise from the starting angle to the ending angle. Angles are specified in degrees, with 0 or 360 representing east. Negative angles can be used. The default wedge is from 0 to 90 degrees, with a radius of 3 cells.
Irregular, Kernel file

A custom neighborhood with specifications set by the identified kernel text file. The minimum value for width or height of the kernel is 1 cell, and the maximum value is 4096 cells.

For the annulus, circle, rectangle and wedge neighborhood types, the distance units for the parameters can be specified in Cell units or Map units. Cell units is the default.

For the irregular neighborhood type, the first line in the kernel file defines the width and height of the neighborhood in numbers of cells. The subsequent lines indicate how the input value that corresponds to that location in the kernel will be processed. A value of 0 in the kernel file indicates that the corresponding location will not be included in the calculation. A value of 1 in the kernel file indicates that the corresponding input cell will be included in the operation.

Neighborhood

Return value

Label	Explanation	Data type
Output Raster	The output topographic position index raster.	Raster

TopographicPositionIndex(in_raster, {neighborhood})

Name Explanation Data type

Name	Explanation	Data type
in_raster	The input surface raster.	Raster Layer
neighborhood (Optional)	The cells surrounding a processing cell that will be used in the TPI calculation. There are several predefined neighborhood types to choose from, or a custom kernel can be defined. Once the neighborhood type is selected, other parameters can be set to fully define the shape, size, and units of measure. The default neighborhood is an annulus with an inner radius of one cell and an outer radius of three cells. The shape of the neighborhoods are defined by the `Neighborhood` class. The available neighborhood types are `NbrAnnulus`, `NbrCircle`, `NbrRectangle`, `NbrWedge`, and `NbrIrregular`. The following are the forms of the available neighborhood types: `NbrAnnulus({innerRadius}, {outerRadius}, {units})` A ring or donut-shaped neighborhood defined by an inner radius and an outer radius. The minimum value for radius is 1 cell, and the outer radius must be larger than the inner. The maximum inner radius is 2046 cells, and the maximum outer radius is 2047 cells. The default annulus is an inner radius of 1 cell and an outer radius of 3 cells. `NbrCircle({radius}, {units}` A circular neighborhood with the given radius. The minimum value for radius is 1 cell, and the maximum value is 2047 cells. The default radius is 3 cells. `NbrRectangle({width}, {height}, {units})` A rectangular neighborhood defined by width and height. The minimum value for width or height is 1 cell, and the maximum value is 4096 cells. The default is a square with a width and height of 3 cells. `NbrWedge({radius}, {startAngle}, {endAngle}, {units})` A wedge-shaped neighborhood defined by a radius, a start angle, and an end angle. The minimum value for radius is 1 cell, and the maximum value is 2047 cells. The wedge extends counterclockwise from the starting angle to the ending angle. Angles are specified in degrees, with 0 or 360 representing east. Negative angles can be used. The default wedge is from 0 to 90 degrees, with a radius of 3 cells. `NbrIrregular(inKernelFile)` A custom neighborhood with specifications set by the identified kernel text file. The minimum value for width or height of the kernel is 1 cell, and the maximum value is 4096 cells. For the irregular neighborhood type, the first line in the kernel file defines the width and height of the neighborhood in numbers of cells. The subsequent lines indicate how the input value that corresponds to that location in the kernel will be processed. A value of 0 in the kernel file indicates that the corresponding location will not be included in the calculation. A value of 1 in the kernel file indicates that the corresponding input cell will be included in the operation.	Neighborhood

in_raster

The input surface raster.

Raster Layer

neighborhood

(Optional)

The cells surrounding a processing cell that will be used in the TPI calculation. There are several predefined neighborhood types to choose from, or a custom kernel can be defined.

The shape of the neighborhoods are defined by the Neighborhood class. The available neighborhood types are NbrAnnulus, NbrCircle, NbrRectangle, NbrWedge, and NbrIrregular.

The following are the forms of the available neighborhood types:

NbrAnnulus({innerRadius}, {outerRadius}, {units})

A ring or donut-shaped neighborhood defined by an inner radius and an outer radius. The minimum value for radius is 1 cell, and the outer radius must be larger than the inner. The maximum inner radius is 2046 cells, and the maximum outer radius is 2047 cells. The default annulus is an inner radius of 1 cell and an outer radius of 3 cells.
NbrCircle({radius}, {units}

A circular neighborhood with the given radius. The minimum value for radius is 1 cell, and the maximum value is 2047 cells. The default radius is 3 cells.
NbrRectangle({width}, {height}, {units})

A rectangular neighborhood defined by width and height. The minimum value for width or height is 1 cell, and the maximum value is 4096 cells. The default is a square with a width and height of 3 cells.
NbrWedge({radius}, {startAngle}, {endAngle}, {units})

A wedge-shaped neighborhood defined by a radius, a start angle, and an end angle. The minimum value for radius is 1 cell, and the maximum value is 2047 cells. The wedge extends counterclockwise from the starting angle to the ending angle. Angles are specified in degrees, with 0 or 360 representing east. Negative angles can be used. The default wedge is from 0 to 90 degrees, with a radius of 3 cells.
NbrIrregular(inKernelFile)

A custom neighborhood with specifications set by the identified kernel text file. The minimum value for width or height of the kernel is 1 cell, and the maximum value is 4096 cells.

Neighborhood

Return value

Name	Explanation	Data type
out_raster	The output topographic position index raster.	Raster

Code sample

TopographicPositionIndex example 1 (Python window)

This example calculates the TPI values using an annulus neighborhood around each cell in the input raster.

from arcpy.sa import *
outTPI = TopographicPositionIndex("elevation.tif", "Annulus 1 3 CELL")
outTPI.save("C:/sapyexamples/output/tpiout01.tif")

TopographicPositionIndex example 2 (stand-alone script)

This example determines the TPI values using a ring-shaped neighborhood around each cell in the input raster.

# Name: TopographicPositionIndex_standalone.py
# Description: Calculates the TPI.
# Requirements: Spatial Analyst extension

# Import system modules
import arcpy
from arcpy.sa import *

# Set environment settings
arcpy.env.workspace = "C:/sapyexamples/data"

# Set local variables
inRaster = "elevation.tif"
inNeighborhood = "Circle 90 Map"

# Run the tool
outTPI = TopographicPositionIndex(inRaster, inNeighborhood)

# Save the output
outTPI.save("C:/sapyexamples/output/tpiout02.tif")

Environments

Auto Commit, Cell Size, Cell Size Projection Method, Compression, Current Workspace, Extent, Geographic Transformations, Mask, Output CONFIG Keyword, Output Coordinate System, Pyramid, Scratch Workspace, Snap Raster, Tile Size

Licensing information

Basic: Requires Spatial Analyst
Standard: Requires Spatial Analyst
Advanced: Requires Spatial Analyst

Topographic Position Index (Spatial Analyst Tools)

Summary

Usage

Parameters

Return value

Environments

Licensing information

Related topics