Multiscale Surface Difference (Spatial Analyst)

Summary

Calculates the maximum difference from the mean elevation across a range of spatial scales.

Learn more about how Multiscale Surface Difference works.

Usage

• The maximum difference from the mean elevation is calculated across scales. This means that for each scale, the mean elevation is found, and the difference between the center cell's value and that scale's mean elevation is found. The difference is retained for comparison with values of different scales. These scales are the neighborhood distance value used for calculation (the distance from the target cell center, creating a square of cells around the target cell). For example, a scale of two cells is a 5 by 5 cell neighborhood.

• The Input Surface Raster (in_raster in Python) parameter value can be any type of surface raster.

• The Output Difference Raster (out_difference_raster in Python) parameter is the primary output. This is a raster containing the maximum difference from the mean elevation across a range of spatial scales.

• The Output Scale Raster (out_scale_raster in Python) parameter provides more information about the primary output. It contains the scale at which the maximum difference from the mean elevation was found for each cell. The scale is the neighborhood distance value, which is the distance from the target cell center, creating a square of cells around the target cell.

• The Minimum Neighborhood Distance (min_scale in Python) and Maximum Neighborhood Distance (max_scale in Python) parameters define the minimum and maximum neighborhood sizes, or scales, that the difference will be calculated for. These values represent the smallest and largest distance from the target cell. For example, a value of 1 creates a 3 by 3 cell neighborhood, and a value of 2 creates a 5 by 5 cell neighborhood.

  These values cannot be less than the input raster cell size or 1 cell.

  The Minimum Neighborhood Distance parameter value must be less than or equal to the Maximum Neighborhood Distance parameter value.

• The Distance Increment (increment in Python) parameter is the increase in neighborhood distance between scales.

  This parameter value cannot be less than the input raster cell size or 1 cell. The default value is the input raster cell size.

• NoData cells in the Input Surface Raster value will be ignored and those cells will be assigned NoData in the Output Difference Raster and Output Scale Raster parameter values.

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

• Running with GPU results in higher precision output compared to CPU.

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

  By default, this tool will use 50 percent of the available cores. 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

Dialog

Label	Explanation	Data Type
Input Surface Raster	The input surface raster.	Raster Layer
Output Scale Raster (Optional)	The output raster containing the scale at which the most extreme difference was found for each cell. Scales are represented as their neighborhood distance values. It will be floating-point type.	Raster Dataset
Distance Units (Optional)	Specifies the distance unit that will be used for the Minimum Neighborhood Distance, Maximum Neighborhood Distance, and Distance Increment parameters. Distance will be measured in the number of cells or specified unit. The default is the map unit of the spatial reference for the Input Surface Raster value. 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
Minimum Neighborhood Distance (Optional)	The distance that defines the minimum neighborhood scale that elevation difference will be calculated for. This is the distance from the target cell center, creating a square of cells around the target cell. This value must be less than or equal to the Maximum Neighborhood Distance parameter value and greater than or equal to the input raster cell size or one cell. The default value is 4 times the cell size of the Input Surface Raster parameter value, resulting in a 9 by 9 cell neighborhood.	Double
Maximum Neighborhood Distance (Optional)	The distance that defines the maximum neighborhood scale that elevation difference will be calculated for. This is the distance from the target cell center, creating a square of cells around the target cell. This value must be greater than or equal to the Minimum Neighborhood Distance parameter value and the input raster cell size or one cell. The default value is 13 times the cell size of the Input Surface Raster parameter value, resulting in a 27 by 27 cell neighborhood.	Double
Distance Increment (Optional)	The increase in neighborhood distance between scales. This parameter value cannot be less than the Input Surface Raster cell size or 1 cell. The default value is the cell size of the Input Surface Raster parameter value.	Double
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 Difference Raster	The output raster containing the maximum difference from the mean elevation for each cell. It will be floating-point type.	Raster

Python

MultiscaleSurfaceDifference(in_raster, {out_scale_raster}, {distance_units}, {min_scale}, {max_scale}, {increment}, {analysis_target_device})

Name	Explanation	Data Type
in_raster	The input surface raster.	Raster Layer
out_scale_raster (Optional)	The output raster containing the scale at which the most extreme difference was found for each cell. Scales are represented as their neighborhood distance values. It will be floating-point type.	Raster Dataset
distance_units (Optional)	Specifies the distance unit that will be used for the min_scale, max_scale, and increment parameters. Distance will be measured in the number of cells or specified unit. The default is the map unit of the spatial reference for the in_raster value. 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
min_scale (Optional)	The distance that defines the minimum neighborhood scale that elevation difference will be calculated for. This is the distance from the target cell center, creating a square of cells around the target cell. This value must be less than or equal to the max_scale parameter value and greater than or equal to the input raster cell size or one cell. The default value is 4 times the cell size of the in_raster parameter value, resulting in a 9 by 9 cell neighborhood.	Double
max_scale (Optional)	The distance that defines the maximum neighborhood scale that elevation difference will be calculated for. This is the distance from the target cell center, creating a square of cells around the target cell. This value must be greater than or equal to the min_scale parameter value and the input raster cell size or one cell. The default value is 13 times the cell size of the in_raster parameter value, resulting in a 27 by 27 cell neighborhood.	Double
increment (Optional)	The increase in neighborhood distance between scales. This parameter value cannot be less than the in_raster cell size or 1 cell. The default value is the cell size of the in_raster parameter value.	Double
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_difference_raster	The output raster containing the maximum difference from the mean elevation for each cell. It will be floating-point type.	Raster

Code sample

MultiscaleSurfaceDifference example 1 (Python window)

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

This example generates the difference output raster from an input surface raster using the default values for all optional parameters.

from arcpy.sa import *
outMaxDifferences = MultiscaleSurfaceDifference("elevation.tif", "", "", "", "", "", "")
outMaxDifferences.save("C:/sapyexamples/output/outmaxdifferencs01.tif")

MultiscaleSurfaceDifference example 2 (stand-alone script)

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

This example generates a difference raster for scales starting at 10 meters up to 100 meters with 1 meter increments between each scale.

# Name: MultiscaleSurfaceDifference_standalone.py
# Description: Calculates the maximum difference for each cell from the mean
# over a range of spatial scales.
# 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.tif"
inDistanceUnits = "METERS"
inMinScale = 10
inMaxScale = 100
inIncrement = 1

# Execute the tool
outMaxDifferences = MultiscaleSurfaceDifference(inRaster, "", inDistanceUnits, inMinScale,
                                                inMaxScale, inIncrement, "")

# Save the output 
outMaxDifference.save("C:/sapyexamples/output/outmaxdifferences02.tif")

Environments

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