Fill (Spatial Analyst)

Available with Spatial Analyst license.

Summary

Fills sinks in a surface raster to remove small imperfections in the data.

Learn more about how Fill works

Illustration

Fill tool illustration

Usage

  • A sink is a cell with an undefined drainage direction; no cells surrounding it are lower. The pour point is the boundary cell with the lowest elevation for the contributing area of a sink. If the sink were filled with water, this is the point where water would pour out.

  • The z-limit specifies the maximum difference allowed between the depth of a sink and the pour point and determines which sinks will be filled and which will remain untouched. The z-limit is not the maximum depth to which a sink will be filled.

    For example, consider a sink area where the pour point is 210 feet in elevation, and the deepest point within the sink is 204 feet (a difference of 6 feet). If the z-limit is set to 8, this particular sink will be filled. However, if the z-limit is set to 4, this sink will not be filled since the depth of this sink exceeds this difference and would be considered a valid sink.

  • All sinks that are less than the z-limit, and lower than their lowest adjacent neighbor, will be filled to the height of their pour points.

  • Running the Fill tool can be memory, CPU, and disk intensive. It can require up to four times the disk space of the input raster.

  • The number of sinks found with the z-limit will determine the length of processing time. The more sinks there are, the longer the processing time will be.

  • The Sink tool can be used in advance of using the Fill tool to find the number of sinks and help identify their depth. Knowing the depth of the sinks can help in determining an appropriate z-limit.

  • Fill can also be used to remove peaks. A peak is a cell where no adjacent cells are higher. To remove peaks, the input surface raster must be inverted. This can be performed with the Minus tool. Specify the highest value of the surface raster as the first input to Minus and surface raster as the second input. Perform a Fill. Invert the results to obtain a surface that has original surface raster values with the peaks removed. The z-limit can be applied to this process as well. If nothing is specified for z-limit, then all peaks will be removed. If it is specified, where the difference in z-value between a peak and its highest adjacent neighbor is greater than the z-limit, that peak will not be removed.

  • This tool supports parallel processing. If your computer has multiple processors or processors with multiple cores, better performance may be achieved, particularly on larger datasets. The Parallel processing with Spatial Analyst help topic includes details about this capability and how to configure it.

    When using parallel processing, temporary data will be written to manage the data chunks being processed. The default temp folder location will be on your local C: drive. You can control the location of this folder by setting up a system environment variable named TempFolders and specifying the path to a folder to use (for example, E:\RasterCache). If you have administrator privileges on your machine, you can also use a registry key (for example, [HKEY_CURRENT_USER\SOFTWARE\ESRI\ArcGISPro\Raster]).

    By default, this tool will use 50 percent of the available cores. If the input data is smaller than 5,000 by 5,000 cells in size, fewer cores may be used. You can control the number of cores the tool uses with the Parallel processing factor environment.

  • 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.

Parameters

LabelExplanationData Type
Input surface raster

The input raster representing a continuous surface.

Raster Layer
Z limit
(Optional)

Maximum elevation difference between a sink and its pour point to be filled.

If the difference in z-values between a sink and its pour point is greater than the z_limit, that sink will not be filled.

The value for z-limit must be greater than zero.

Unless a value is specified for this parameter, all sinks will be filled, regardless of depth.

Double

Return Value

LabelExplanationData Type
Output surface raster

The output surface raster after the sinks have been filled.

If the surface raster is integer, the output filled raster will be integer type. If the input is floating point, the output raster will be floating point.

Raster

Fill(in_surface_raster, {z_limit})
NameExplanationData Type
in_surface_raster

The input raster representing a continuous surface.

Raster Layer
z_limit
(Optional)

Maximum elevation difference between a sink and its pour point to be filled.

If the difference in z-values between a sink and its pour point is greater than the z_limit, that sink will not be filled.

The value for z-limit must be greater than zero.

Unless a value is specified for this parameter, all sinks will be filled, regardless of depth.

Double

Return Value

NameExplanationData Type
out_surface_raster

The output surface raster after the sinks have been filled.

If the surface raster is integer, the output filled raster will be integer type. If the input is floating point, the output raster will be floating point.

Raster

Code sample

Fill example 1 (Python window)

This example fills the sinks of an input elevation surface Grid raster.

import arcpy
from arcpy import env
from arcpy.sa import *
env.workspace = "C:/sapyexamples/data"
outFill = Fill("elevation")
outFill.save("C:/sapyexamples/output/outfill01")
Fill example 2 (stand-alone script)

This example fills the sinks of an input elevation surface Grid raster with a z-limit applied.

# Name: Fill_Ex_02.py
# Description: Fills sinks in a surface raster.
# Requirements: Spatial Analyst Extension

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

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

# Set local variables
inSurfaceRaster = "elevation"
zLimit = 3.28

# Execute FlowDirection
outFill = Fill(inSurfaceRaster, zLimit)

# Save the output 
outFill.save("C:/sapyexamples/output/outfill02")

Related topics