RasterCellIterator

Summary

Defines an iterator object to iterate through the cells of one or more rasters.

The input is a dictionary containing single or multiple Raster objects and optionally a padding factor. Additionally, a list of Raster objects whose NoData cells will be skipped during the iteration can also be specified.

Discussion

A RasterCellIterator object enumerates row and column pairs for given Raster objects in a loop. The row and column pairs can be used in a [row, column] index notation with the Raster objects to read or write cell values.

When multiple rasters are used in the iterator, the first raster in the list defines the iterator's raster analysis environment. All other rasters in the list are expected to match in spatial reference, cell size, and extent with that of the first raster. If the properties of the second and subsequent rasters in this list don't match with the first raster, the analysis environment of the first raster is applied to them. It is recommended that you create all output rasters using the RasterInfo object of the first raster so that they inherit its spatial reference, cell size, and extent.

See A quick tour of using Raster Cell Iterator for more information on how to use RasterCellIterator to perform custom raster analysis.

Syntax

RasterCellIterator (*args)

Parameter	Explanation	Data Type
*args	A dictionary that defines rasters and padding in the following format: {'rasters': [in_rasterobj1, in_rasterobj2, ...], 'padding': padding_factor, 'skipNoData': [in_rasterobj1, in_rasterobj2, ...]} The rasters key is expressed as a list of Raster objects. Each Raster object must be an instance of the arcpy.Raster class. The optional padding key is expressed as an integer. The padding factor expands the internal pixel block size of the raster objects by the value specified. The optional skipNoData key is expressed as a list of rasters specifying cells to be skipped by the iterator. For any given cell, if one or more rasters in this list has a NoData value, that cell would be skipped by the iterator. The rasters in the skipNoData list must be a subset of, or equal to, the rasters list.	Dictionary

Code sample

RasterCellIterator example 1

Using RasterCellIterator to shift a raster by one cell through reading each cell value from the input raster and writing it to the output raster.

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

# Create inRaster raster object
inRaster = arcpy.Raster("C:/arcpyExamples/inputs/elevation.tif")

# Get the raster info object from inRaster
rasInfo = inRaster.getRasterInfo()
# Create a new raster dataset 
outRaster = arcpy.Raster(rasInfo)

# The following code shifts inRaster by one cell and writes to outRaster
with arcpy.sa.RasterCellIterator({"rasters":[inRaster, outRaster], "padding":1}) as rci:
    for r, c in rci:
        # Read cell value from inRaster (at upper left corner of the current location)
        v = inRaster[r-1, c-1]
        # Check for NoData
        if math.isnan(v):
            # Write NoData to outRaster
            outRaster[r, c] = math.nan
        else:
            # Write v to outRaster
            outRaster[r, c] = v 

# Save the output
outRaster.save("C:/arcpyExamples/outputs/outras01.tif")

RasterCellIterator example 2

Using RasterCellIterator to assign the row (or column) numbers to each cell on a new raster.

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

# Create a raster info object
rasInfo = arcpy.RasterInfo()

# Create a spatial reference object
spRef = arcpy.SpatialReference(32145)
# Create an extent object
ext = arcpy.Extent(471090.082572495, 208342.353396819, 494670.082572495, 231352.353396819, 0, 0, 0, 0, spRef)

# Initialize raster info object properties
# Set the spatial reference property
rasInfo.setSpatialReference(spRef)
# Set the extent property
rasInfo.setExtent(ext)
# Set the cell size property
rasInfo.setCellSize((30, 30))
# Set the pixel type property
rasInfo.setPixelType("S32")

# Create a new raster dataset 
outRaster = arcpy.Raster(rasInfo)

# The following code will create a row (or column) raster
with RasterCellIterator({"rasters":[outRaster], "padding":1}) as rci:
    for r, c in rci:
        # Assign 'r' to outRaster will result in a row raster
        # Assign 'c' to outRaster will result in a column raster.
        outRaster[r, c] = r

# Save the output
outRaster.save("C:/arcpyExamples/outputs/outras02.tif")

RasterCellIterator example 3

Using RasterCellIterator to get flow directions along a stream.

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

# Create inRaster raster object
inStreamRas = arcpy.Raster("C:/arcpyExamples/inputs/streamras.tif")
inFlowDirRas = arcpy.Raster("C:/arcpyExamples/inputs/flowdir.tif")

# Get the raster info object from inRaster
rasInfo = inFlowDirRas.getRasterInfo()
# Create a new raster dataset 
outRaster = arcpy.Raster(rasInfo)

# Get flow directions along a stream network
with arcpy.sa.RasterCellIterator({"rasters":[inStreamRas, inFlowDirRas, outRaster], "padding":1, "skipNoData":[inStreamRas]}) as rci:
    for r, c in rci:        
        v = inFlowDirRas[r, c]
        outRaster[r, c] = v 

# Save the output
outRaster.save("C:/arcpyExamples/outputs/outras03.tif")