Feature Preserving Smoothing (Spatial Analyst)

Summary

Smooths a surface raster by removing noise while preserving features.

Learn more about how Feature Preserving Smoothing works

Illustration

Usage

• This tool can be used to remove noise from a digital elevation model (DEM) raster. It can be used in any analysis workflow where a smoother final output is desired.

• This tool has several parameters that affect the smoothing process. They can be used separately or in combination to customize the results to your specific application. The analysis can be controlled in the following ways:

  • The size of the neighborhood around the cells being smoothed.
  • The relative steepness of the local variation that will be affected.
  • The number of times the smoothing process will be applied.
  • The relative height of the objects that will be affected.

• The Neighborhood Distance parameter defines the size of the neighborhood. Provide a small value that ensures only noise will be smoothed away while features on the input raster will be preserved. For example, a setting of 5 cells will result in an 11 by 11 cell processing window, which is typically a good starting point.

• The Normal Difference Threshold parameter defines the potential maximum change of the feature edge steepness (in degrees) in a single iteration. Specifying a small value (such as 15 degrees or less) ensures that only flat feature edges will be smoothed away.

• The Maximum Elevation Change parameter defines the potential maximum change of the feature height in a single iteration. Specifying a small value (such as 0.5 meters or less) ensures that only short features will be smoothed away.

• The Number of Iterations parameter specifies the number of times the smoothing process will be repeated. Specifying larger values can increase the smoothness of the output raster; however, more iterations will cause additional processing time. In many cases, a small value (such as 3) works well for this parameter.

• When the Input Surface Raster parameter value has a vertical coordinate system defined, the z-unit of the vertical coordinate system will be honored in the analysis. If the input surface raster does not have a vertical coordinate system defined, specify the Z Unit parameter value to ensure proper computation of normal vectors during the analysis.

• This tool can be GPU accelerated, which means that if a compatible graphics processing unit (GPU) is available on your system, it will be used to enhance the performance of the tool. Use the Target device for analysis (analysis_target_device in Python) parameter to control whether the GPU or CPU will be used to run the tool.

  See GPU processing with Spatial Analyst for details on compatible GPUs, configuring and working with GPU devices, as well as troubleshooting tips.

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

Dialog

Label	Explanation	Data Type
Input Surface Raster	The input surface raster.	Raster Layer
Distance Units (Optional)	Specifies the distance unit that will be used for the Neighborhood Distance parameter. The default is Cells. Cells—The distance unit will be cells. Meters—The distance unit will be meters. Centimeters—The distance unit will be centimeters. Kilometers—The distance unit will be kilometers. Inches—The distance unit will be inches. Feet—The distance unit will be feet. Yard—The distance unit will be yards. Miles—The distance unit will be miles.	String
Neighborhood Distance (Optional)	The distance away from the target cell that defines the size of the processing neighborhood. The value must be a positive number. The default value is 5 cells.	Double
Normal Difference Threshold (Optional)	The maximum normal difference for a neighboring cell to be included in computing a new cell value for the current processing cell. A normal difference is an angle formed by the normal vector of a neighboring cell and the normal vector of the current processing cell. The value can be any number from –180 degrees to 180 degrees. The default value is 15 degrees.	Double
Number of Iterations (Optional)	The number of times that the smoothing process will be repeated. The value must be a positive integer. The default value is 3.	Long
Maximum Elevation Change (Optional)	The allowed maximum height change of any cell in one iteration. When a new value is calculated for a cell location, it is compared to the original value at that cell location. If the difference is less than or equal to this parameter setting, the new cell value will be used. Otherwise, the original value will remain unchanged. The value must be a positive number. The default value is 0.5 meters.	Linear Unit
Z Unit (Optional)	Specifies the linear unit that will be used for vertical z-values. It is defined by a vertical coordinate system if it exists. If no vertical coordinate system exists, define the z-unit using the unit list to ensure correct geodesic computation. The default is meter. Inch—The linear unit will be inches. Foot—The linear unit will be feet. Yard—The linear unit will be yards. Mile US—The linear unit will be miles. Nautical mile—The linear unit will be nautical miles. Millimeter—The linear unit will be millimeters. Centimeter—The linear unit will be centimeters. Meter—The linear unit will be meters. Kilometer—The linear unit will be kilometers. Decimeter—The linear unit will be decimeters.	String
Target Device for Analysis (Optional)	Specifies the device that will be used to perform the calculation. GPU then CPU—If a compatible GPU is found, it will be used to perform the calculation. Otherwise, the CPU will be used. This is the default. CPU only—The calculation will only be performed on the CPU. GPU only—The calculation will only be performed on the GPU.	String

Return Value

Label	Explanation	Data Type
Output Raster	The output smoothed raster.	Raster

Python

FeaturePreservingSmoothing(in_raster, {distance_units}, {neighborhood_distance}, {normal_difference_threshold}, {number_iterations}, {maximum_elevation_change}, {z_unit}, {analysis_target_device})

Name	Explanation	Data Type
in_raster	The input surface raster.	Raster Layer
distance_units (Optional)	Specifies the distance unit that will be used for the Neighborhood Distance parameter. The default is CELLS. CELLS—The distance unit will be cells. METERS—The distance unit will be meters. CENTIMETERS—The distance unit will be centimeters. KILOMETERS—The distance unit will be kilometers. INCHES—The distance unit will be inches. FEET—The distance unit will be feet. YARDS—The distance unit will be yards. MILES—The distance unit will be miles.	String
neighborhood_distance (Optional)	The distance away from the target cell that defines the size of the processing neighborhood. The value must be a positive number. The default value is 5 cells.	Double
normal_difference_threshold (Optional)	The maximum normal difference for a neighboring cell to be included in computing a new cell value for the current processing cell. A normal difference is an angle formed by the normal vector of a neighboring cell and the normal vector of the current processing cell. The value can be any number from –180 degrees to 180 degrees. The default value is 15 degrees.	Double
number_iterations (Optional)	The number of times that the smoothing process will be repeated. The value must be a positive integer. The default value is 3.	Long
maximum_elevation_change (Optional)	The allowed maximum height change of any cell in one iteration. When a new value is calculated for a cell location, it is compared to the original value at that cell location. If the difference is less than or equal to this parameter setting, the new cell value will be used. Otherwise, the original value will remain unchanged. The value must be a positive number. The default value is 0.5 meters.	Linear Unit
z_unit (Optional)	Specifies the linear unit that will be used for vertical z-values. It is defined by a vertical coordinate system if it exists. If no vertical coordinate system exists, define the z-unit using the unit list to ensure correct geodesic computation. The default is meter. INCH—The linear unit will be inches. FOOT—The linear unit will be feet. YARD—The linear unit will be yards. MILE_US—The linear unit will be miles. NAUTICAL_MILE—The linear unit will be nautical miles. MILLIMETER—The linear unit will be millimeters. CENTIMETER—The linear unit will be centimeters. METER—The linear unit will be meters. KILOMETER—The linear unit will be kilometers. DECIMETER—The linear unit will be decimeters.	String
analysis_target_device (Optional)	Specifies the device that will be used to perform the calculation. GPU_THEN_CPU—If a compatible GPU is found, it will be used to perform the calculation. Otherwise, the CPU will be used. This is the default. CPU_ONLY—The calculation will only be performed on the CPU. GPU_ONLY—The calculation will only be performed on the GPU.	String

Return Value

Name	Explanation	Data Type
out_raster	The output smoothed raster.	Raster

Code sample

FeaturePreservingSmoothing example 1 (Python window)

The following sample demonstrates the use of this tool in the Python window.

This example smooths a 1-meter resolution DEM using a neighborhood distance of 5 cells and a normal difference threshold of 15 degrees.

from arcpy.sa import *
outFPS01 = FeaturePreservingSmoothing("elevation_1m.tif", "CELLS", 5, 15, 3, 
                                      "0.5 Meters", "METER", "GPU_THEN_CPU")
outFPS01.save("C:/sapyexamples/output/outsmoothraster01.tif")

FeaturePreservingSmoothing example 2 (stand-alone script)

The following sample demonstrates the use of this tool in a stand-alone Python script.

This example smooths a 1-meter resolution DEM using a neighborhood distance of 5 meters and a normal difference threshold of 10 degrees.

# Name: FeaturePreservingSmoothing_Ex_02.py
# Description: Smooths a 1m resolution elevation raster  
# Requirements: Spatial Analyst Extension

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

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

# Check out the ArcGIS Spatial Analyst extension license
arcpy.CheckOutExtension("Spatial")

# Set local variables
inRaster = "elevation_1m.tif"
distUnits = "METERS"
nbrDistance = 5
normDiffThreshold = 10
iterations = 1
maxElevChange = "1.5 Meters"
zUnit = ""
analysisDevice = ""

# Execute the tool
outFPS02 = FeaturePreservingSmoothing(inRaster, distUnits, nbrDistance,
                                    normDiffThreshold, iterations, maxElevChange,
                                    zUnit, analysisDevice)

# Save the output 
outFPS02.save("C:/sapyexamples/output/outsmoothraster02.tif")

Environments

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