Executing Spatial Analyst Tools Using ArcGIS Pro SDK

[XuguangWang]

ArcGIS Pro SDK for .Net allows you to extend the ArcGIS Pro user interface by creating custom add-ins leveraging different GIS functionalities. In this blog, we will take a look at how to execute Spatial Analyst tools in your add-in using the ArcGIS Pro SDK.

How to execute a geoprocessing tool

The ArcGIS.Desktop.Core.Geoprocessing namespace in the SDK provides a Geoprocessing class to help execute a geoprocessing tool. The Geoprocessing class within the namespace offers necessary methods to specify the input parameters, set up environment settings, and execute the geoprocessing tool. The static method, ExecuteToolAsync is used to execute the tool.
The first argument for ExecuteToolAsync is the geoprocessing tool name as a string. To specify a tool uniquely, the tool name must be appended with its toolbox alias. For example, the Copy Features tool is in the data management toolbox, and the alias of the data management toolbox is management. Therefore, to execute the Copy Features tool, the tool name should be specified as CopyFeatures_management. Without the toolbox alias, or with a misspelled toolbox alias, an error will be returned and the tool will not be executed because the geoprocessing framework is not able to find the tool.
The second argument for ExecuteToolAsync is the tool parameter values array, which holds all the input and output parameter values for the geoprocessing tool. Do not create the array yourself. Simply call the method MakeValueArray, to create it, passing in all input and output parameter values as arguments.
Additionally, you may want to specify an environment setting for the tool execution. The third argument for ExecuteToolAsync allows you to do that. Like the input/output parameters, the environment settings also need to be specified in an array. Again, no need to create the array by yourself, simply call the method MakeEnvironmentArray to make one.
The rest of the arguments for ExecuteToolAsync are optional. As an asynchronous method, ExecuteToolAsync will start the geoprocessing tool execution in a different thread other than the user interface (UI) thread, which allows the ArcGIS Pro UI to remain active while the tool executes.

How to execute a Spatial Analyst tool

Executing a Spatial Analyst tool is no different than any other geoprocessing tool. All we need to do is supply a tool name with an appropriate toolbox alias, which is sa. The following example will walk you through a C# example on how to execute the Zonal Statistics tool to calculate average elevation for each zone, using SDK.

Let’s start by specifying the tool input and output parameters:

// declaring tool parameter variables
string inZoneRas = @"c:\data\county.tif" ; // input zone raster
string zoneField = "Value"; // zone field
string inValueRas = @"c:\data\elevation.tif" ; // input valueraster
string outRaster = @"c:\output\outzs01.tif" ; // output raster
string statType = "MEAN" ; // statistics type
bool ignoreNoData = true ; // ignore NoData option

Now let’s create the first array with the above parameter values using the Geoprocessing.MakeValueArray method:

// create an array for the input parameter values
var valueArray = Geoprocessing.MakeValueArray(inZoneRas, zoneField, inValueRas, outRaster, statType, ignoreNoData);

Next, create another array for environment settings using Geoprocessing.MakeEnvironmentArray to set the cell size for analysis and to overwrite output if it exists:

// create an array for the environment settings
var envArray = Geoprocessing.MakeEnvironmentArray(overwriteoutput: true, cellSize: 30);

Finally, let’s execute the tool by calling the ExecuteToolAsync method, passing in the tool name, the tool parameter values array, and the environment settings array that we created above. Notice that the tool name ‘ZonalStatistics’ is appended with its toolbox alias ‘sa’, which refers to the Spatial Analyst toolbox:

// run ZonalStatistics
var gpresult1 = await Geoprocessing.ExecuteToolAsync("ZonalStatistics_sa", valueArray, envArray);

Because the Spatial Analyst is an extension product, a license is required in order to use its capabilities. However, we did not enable the license in the preceding code snippet as in our case, it is enabled through the ArcGIS Pro application. If the Spatial Analyst license is not already enabled, the tool execution will fail with a licensing error. To enable the Spatial Analyst license, configure your licensing options from the ArcGIS Pro application.

How to execute a map algebra expression

Now that we have learned how to execute a Spatial Analyst tool using the ArcGIS Pro SDK, let’s look at another example. In raster modeling, we often need to execute map algebra expression to solve a complex problem. In the Spatial Analyst toolbox, the tool that allows us to execute map algebra expression is called Raster Calculator.
In your add-in, you may take advantage of the Raster Calculator tool to execute single-line map algebra expressions. The Raster Calculator tool has two parameters only. The first parameter is the map algebra expression itself. The second parameter is the output raster, which saves the result of the calculation.
In the example below, let’s build a map algebra expression to find the land uses for areas with slope greater than 30 degrees and aspect less than 120 degrees, and use the Raster Calculator tool to execute it.

First, let’s specify the input raster datasets that will be used in our map algebra expression:

// input raster datasets for the map algebra expression
string inRas1 = @"c:\data\in_slope.tif" ;
string inRas2 = @"c:\data\in_aspect.tif" ;
string inRas3 = @"c:\data\in_landuse.tif" ;

Now, let’s build the map algebra expression. Notice that the input raster datasets are embedded in the expression itself, enclosed by single quotation marks:

// define the map algebra expression
string maExpression = String.Format("Con((‘{0}’ > 30) & (‘{1}’ < 120), ‘{2}’)",inRas1, inRas2, inRas3);

We need another variable to specify the output raster:

// define the output raster
string outRaster = @"c:\output\outrascal01.tif" ;

Now we can create an array using maExpression and outRaster:

// make the input parameter values array
var valueArray = Geoprocessing.MakeValueArray(maExpression, outRaster);

Finally, we kick off the Raster Calculator tool, which will execute the map algebra expression and save the result in outRaster:

// execute the Raster calculator tool to process the map algebra expression
var gpresult1 = await Geoprocessing.ExecuteToolAsync("RasterCalculator_sa", valueArray);

Summary

Now that you are comfortable executing Spatial Analyst tools and map algebra expressions, you can perform raster modeling in your add-ins. If you need more information, check out our help pages on ArcGIS Pro SDK and ArcGIS Pro Spatial Analyst.