Developer’s Guide to Geoprocessing

Corey Tucker & Jason Pardy

Monday, March 17th Schedule

8:30 a.m.–11:30 a.m.

Presummit Morning Seminars

10:00 a.m.–5:00 p.m.

ESRI Showcase (Oasis 1)

11:30 a.m.–1:00 p.m.

Lunch (Oasis 4)

1:00 p.m.–5:00 p.m.

Presummit Afternoon Seminars

5:30 p.m.–7:30 p.m.

Welcome Social (Wyndham Poolside)

ESRI Developer Summit 2008 2

Got technical questions . . .

Ask them at:

www.esri.com/devsummitquestions

We will reply to your question as soon as possible.

ESRI Developer Summit 2008 3

Workshop Outline
• Geoprocessing Overview
• Accessing and Executing Tools in Scripting and Programs
• Developing Tools with Models
• Developing Tools with Python
• Developing Tools with ArcObjects
• A Look Ahead at ArcGIS 9.3
Who we think you are:

• You add value to ArcGIS community

– Through your understanding of GIS and expertise in a particular
domain (wastewater, urban planning, etc.)
• You want to develop new functions for ArcGIS
– Models, Scripts, .NET, JAVA
– Extend behavior of the system (i.e., new feature class behavior)
– Extend functionality of the system (new toolbars and tools)
…and why you should know about geoprocessing

• Empowers GIS professionals to implement workflows

– Reduces barriers between GIS professionals and software
developers
• A complete platform for delivering solutions
– Universal capability that can be used and deployed by all GIS users
to automate their work, build repeatable and well-defined methods
and procedures, and to model important geographic processes.
• Significant reduction of your development cycle
Geoprocessing Overview
Geoprocessing is…
Geoprocessing Tools & Framework
Geoprocessing Tools

• A set of operators (tools) that perform essential and

elemental tasks on GIS data.
–“Classic GIS” Analysis (Overlay, Proximity)
– Geographic Geometry – Projection/Coordinate
transformation
– Data Management and Conversion
– Domain specific analysis – 3D, Surfaces, Network,
Raster, Geostatistics, Linear Referencing, Cartography,
etc.
Geoprocessing Framework

Command Line

Models

Tool dialog

Scripts

11
Geoprocessing Framework

• A fully developed framework for automating work

–Finding the right tool and connecting it to data in a simple
way
–Creating new, useful tools
• models (visual programming)
• scripts (text programming)
–Ubiquitous
• Available in all ArcGIS configurations
–Comprehensive management and sharing of tools you
develop
• Consistent user interface
• Documentation
• Available in any programming language
Executing Tools
Executing Tools
• System languages (C++, Java, .NET) and scripting
languages (Python, JScript) can execute tools.

• With ArcGIS 9.2, geoprocessing is now supported in ArcGIS

Engine which also supports UNIX & Linux.

• Tools have a fixed set of parameters required for execution.

• Parameter values are specified either as strings or objects

(i.e. IFeatureClass, ISpatialReference).
Geoprocessor
• A Geoprocessing tool is executed by the Geoprocessor.
• The Geoprocessor is the main object that simplifies the task
of executing geoprocessing tools.
• The Geoprocessor contains properties and methods which
make it possible to:
– execute tools
– set global environment settings
– examine the resulting messages

• It is the single access point for the execution of any

geoprocessing tool in ArcGIS, including extensions.
Scripting

• ArcGIS 9.2 contains a new native python module

called arcgisscripting.
– This module is used to create the Geoprocessor.
– This module will work on any platform.

• Win32com is still supported for windows, but new

scripts should be written to use the arcgisscripting
module.
– VBScript and JScript will only work on windows using
Dispatch.
Scripting

• Existing scripts can be easily updated to use

arcgisscripting by replacing two lines.

– 9.0, 9.1
from win32com.client import Dispatch
gp = win32com.client.Dispatch(“esriGeoprocessing.GpDispatch.1”)

– 9.2
import arcgisscripting
gp = arcgisscripting.create()
Scripting
• ArcGIS 9.2 Desktop, Engine & Server install python 2.4.1.
• Pythonwin is no longer automatically installed.
– The version for 2.4.1 has an install bug that prevents a silent install
– Users must manually install for existing scripts to continue to work
– Install EXE is distributed with ArcGIS
• Users may use any IDE when they use the arcgisscripting
module.
• Users can edit existing scripts to create the geoprocessor
the new way and avoid Pythonwin altogether.
– Unless scripts use other win32com functions, such as messagebox
Scripting – Running a Tool

# Create the Geoprocessor object

import arcgisscripting
gp = arcgisscripting.create()

# Set workspace environment

gp.Workspace = “C:/Newfoundland”

# Execute the Buffer tool

try:
gp.Buffer_analysis(“roads”, “roads_500”, “500 METERS”)
except:
print gp.GetMessages(2)

• http://webhelp.esri.com/arcgisdesktop/9.2
– Geoprocessing (Automating your work with Scripts)
Visual Basic 6 and C++

• The ESRI Geoprocessing Object Library contains a

new object class called the GeoProcessor.
• The GeoProcessor implements the IGeoprocessor
interface.
• Parameters are passed to execute as a Variant
Array.
• VB6 and C++ users use this interface.
– VB6 – windows only
– C++ - cross platform support
Create a shapefile: VB & ArcObjects

Public Sub CreateShapefile()

CreateShapefile()
Const strFolder As String = "D:\
"D:\DATA"
Const strName As String = "MyShapeFile
"MyShapeFile"
" ' Dont include .shp
.shp extension
Const strShapeFieldName As String = "Shape"

' Open the folder to contain the shapefile as a workspace

Dim pFWS As IFeatureWorkspace
Dim pWorkspaceFactory As IWorkspaceFactory
Set pWorkspaceFactory = New ShapefileWorkspaceFactory
Set pFWS = pWorkspaceFactory.OpenFromFile(strFolder,
pWorkspaceFactory.OpenFromFile(strFolder, 0)

' Set up a simple fields collection

Dim pFields As IFields
Dim pFieldsEdit As IFieldsEdit
Set pFields = New esriGeoDatabase.Fields
Set pFieldsEdit = pFields

Dim pField As IField

Dim pFieldEdit As IFieldEdit

' Make the shape field

' it will need a geometry definition, with a spatial reference
Set pField = New esriGeoDatabase.Field
Set pFieldEdit = pField
pFieldEdit.Name = strShapeFieldName
pFieldEdit.Type = esriFieldTypeGeometry
Wait! There’s more!

Dim pGeomDef As IGeometryDef

Dim pGeomDefEdit As IGeometryDefEdit
Set pGeomDef = New GeometryDef
Set pGeomDefEdit = pGeomDef
With pGeomDefEdit
.GeometryType = esriGeometryPolygon
Set .SpatialReference
.SpatialReference = New UnknownCoordinateSystem
End With
Set pFieldEdit.GeometryDef = pGeomDef
pFieldsEdit.AddField pField

' Add another miscellaneous text field

Set pField = New esriGeoDatabase.Field
Set pFieldEdit = pField
With pFieldEdit
.Length = 30
.Name = "MiscText
"MiscText"
"
.Type = esriFieldTypeString
End With
pFieldsEdit.AddField pField

' Create the shapefile

' (some parameters apply to geodatabase options and can be defaulted as Nothing)
Dim pFeatClass As IFeatureClass
Set pFeatClass = pFWS.CreateFeatureClass(strName,
pFWS.CreateFeatureClass(strName, pFields,
pFields, Nothing, _
Nothing, esriFTSimple,
esriFTSimple, strShapeFieldName,
strShapeFieldName, "")
End Sub
Better Alternative: Use the Geoprocessor

'Initialize the Geoprocessor (VB6)

Dim GP As IGeoProcessor
Set GP = New GeoProcessor

‘Set the workspace environment

GP.SetEnvironmentValue(“workspace”, “C:\Newfoundland”)

‘Set up the array of parameters

Dim parameters As IVariantArray
Set parameters = New VarArray
parameters.Add (“roads”)
parameters.Add (“roads_500”)
parameters.Add (“500 Meters")

'Execute the buffer tool

GP.Execute "Buffer_analysis", parameters, Nothing
C++ - Running a Tool
// Intialize the COM subsystem
CoInitialize(NULL);

// Intialize the Geoprocessor COM Object

IGeoProcessorPtr ipGP(CLSID_GeoProcessor);

// Set the workspace environment

pGP->SetEnvironmentValue(L"workspace", _variant_t(L"C:\\Newfoundland"));

// Build the array of variant paramters

_variant_t vInputFC(L"roads");
_variant_t vOutputFC(L"roads_500");
_variant_t vBufferDist(L"500 METERS");

IVariantArrayPtr ipValues(CLSID_VarArray);
ipValues->Add(vInputFC);
ipValues->Add(vOutputFC);
ipValues->Add(vBufferDist);

// Execute Buffer tool by name

IGeoProcessorResultPtr ipResult;
HRESULT hr = ipGP->Execute(L"Buffer_analysis", ipValues, 0, &ipResult);
.NET
• ArcGIS 9.2 includes a new .NET assembly called
ESRI.ArcGIS.Geoprocessor.
– Contains a managed class called the Geoprocessor.
– This assembly is built against the .NET Framework version 2.0.

• Each system geoprocessing toolbox is represented by a

managed assembly.
– Each toolbox assembly contains classes representing each
geoprocessing tool in the standard ArcGIS geoprocessing toolboxes.
– Use these classes to set up and run geoprocessing tools with the
Geoprocessor class.
.NET – Running a Tool
using ESRI.ArcGIS.Geoprocessor;
using ESRI.ArcGIS.AnalysisTools;
…
// Initialize the Geoprocessor
GeoProcessor GP = new Geoprocessor();

// Set workspace environment

GP.SetEnvironmentValue("workspace", @ "C:\Data\Nfld.gdb");

// Initialize the Buffer Tool

Buffer bufferTool = new Buffer();
bufferTool.in_features = "roads";
bufferTool.out_feature_class = "roads_500";
bufferTool.buffer_Distance_or_field = "500 METERS";

// Execute the buffer

GP.Execute(bufferTool, null)
.NET – Running a Tool By Name

• Can also execute a tool by name.

// Initialize the Geoprocessor

Geoprocessor GP = new Geoprocessor();

// Generate the array of parameters

IVariantArray parameters = new VarArrayClass();
parameters.Add(@"C:\newfoundland\roads.shp");
parameters.Add(@"C:\newfoundland\roads_500.shp");
parameters.Add(“500 METERS");

// Execute the Model tool by name

GP.Execute(“Buffer_analysis", parameters, null);
JAVA
• A new Geoprocessor namespace has been added to the
ArcObjects Jar.
– provides the same easy access to tools
import com.esri.aoj.gp.GeoProcessor;
Import com.esri.aoj.gp.AnalysisTools;
…
// Initialize the Geoprocessor
GeoProcessor gp = new GeoProcessor();

// Initialize the Buffer tool

Buffer buffer = new Buffer( );

buffer.setInFeatures("C:/usa/usa.gdb/ushigh");
buffer.setBufferDistanceOrField("500 METERS");
buffer.setOutFeatureClass( "C:/usa/usa.gdb/ushigh_buff");
buffer.setDissolveOption("ALL");

// Execute buffer
gp.Execute( buffer, null);
Working with Tool Names and Avoid Name
Conflicts
• When using multiple toolboxes, it is possible that two or
more toolboxes will contain a tool with the same name.
• All toolboxes have an Alias property. The alias is a short,
alternative name for the toolbox.
• Use the Execute method in which you specify the tool name
along with the toolbox alias.

gp.Execute("Buffer_analysis", parameters, null)

ArcObjects as Tool Input
• If you are accustomed to working with ArcObjects, you can
continue with that object model when working with the
Geoprocessor.
• An ArcObject may be used instead of an ArcCatalog path
when defining an input parameter.
– IFeatureClass, IRasterDataset
• New outputs must be defined by the ArcCatalog path.

…
IFeatureClass inputFC = pInputName.Open
…
bufferTool.in_features = inputFC;
bufferTool.out_feature_class = @"C:\Data\Nfld.gdb\roads_500";
bufferTool.buffer_Distance_or_field = “500 METERS”;
GP.Execute(bufferTool, null)
Geoprocesssing Results
• The Execute method returns an IGeoProcessorResult
object which manages the results.
– ESRI.ArcGIS.Geoprocessing namespace
• The result object will have the return value of a tool when
executed.
• Return values are necessary when a tool has no output
dataset, instead, it has an output scalar value, such as an
integer or Boolean. (i.e. GetCount)
Geoprocessing Results
Example 1: Return path to output data

using ESRI.ArcGIS.Geoprocessing;
…
// The return value is an Object of type string
IGeoProcessorResult pResult = GP.Execute(bufferTool, null);
object path = pResult.ReturnValue;
…
IFeatureClass pFc = GP.Open(path);

Example 2: Return the default grid size

// The return value is an Object of type double.
IGeoProcessorResult pResult = GP.Execute(calculateGridIndexTool, null);
object defgrid = pResult.ReturnValue;
Geoprocessing Messages
• Executing a tool will produce messages. These can be:
– Informative messages
– Or warning messages
– Or error messages
• Messages are retrieved from the Geoprocessing result
object.
• The GetMessages method will return all messages for the
specified severity (0=informative, 1=warning, 2=error)

C#
string messages = GPResult.GetMessages(ref sev);
System.Console.WriteLine(messages);

JAVA
String messages = GPResult.getMessages(2);
System.out.println(messages);
Geoprocessing Messages

• Individual messages can be retrieved using the

GetMessage method.

// Execute Union
IGeoProcessorResult GPResult = GP.Execute(uniontool, null);

If (GPResult.MessageCount > 0) {
for (int Count = 0; Count <= GPResult.MessageCount - 1; Count++)
{
Console.WriteLine(GPResult.GetMessage(Count));
}
}
Environment Settings
• Environments are global parameters for tools.
• Script and program writers set the environment and tools
use it.
– General settings: current workspace, output spatial reference, extent
– Raster analysis settings: cell size, mask
– Coverage settings: derived and new precision, project compare
– More…

// Get the Cell Size environment value

object env = GP.GetEnvironmentValue("cellsize");

// Set the Cell size environment

GP.SetEnvironmentValue(“CellSize", “50");
Licensing
• Whenever a tool is executed in a program or script, an
ArcGIS license is required.
– By default, the highest license level is initialized when the
Geoprocessor is created
• You can control and set the license level:
– Scripting – use SetProduct() method to set the license level
– System languages – use AoInitialize to set the license level
• Two ArcGIS Engine license levels:
– ArcGIS Engine Runtime (Equivalent to ArcView)
– ArcGIS Engine with Geodatabase Update extension (Equivalent to
ArcEditor)
– ArcInfo tools such as Near, Frequency, etc. require ArcInfo license
access
Licensing and Extensions
• Tools from ArcGIS extensions, such as ArcGIS Spatial
Analyst, require an additional license for that extension.
• A program must explicitly use AoIntialize to check out an
extension.
• A script does not use AoIntialize. ArcGISScripting module
contains methods for setting the product and checking out
an extension.

try:
if gp.CheckExtension("spatial") == "Available":
gp.CheckOutExtension("spatial")
else:
raise "LicenseError"
Checking out an Extension
//Initialize the application
IAoInitialize m_AoInitialize = new AoInitializeClass();
licenseStatus =
m_AoInitialize.Initialize(esriLicenseProductCode.esriLicenseProductCodeArcEngine);
licenseStatus =
m_AoInitialize.CheckOutExtension(esriLicenseExtensionCode.esriLicenseExtension
CodeSpatialAnalyst);

// Initialize the Geoprocessor

Geoprocessor gp = new Geoprocessor();
Slope tSlope = new Slope();
tSlope.in_raster = @"E:\Data\demlatgrd";
tSlope.out_raster = @”E:\Data\aspect03";
gp.Execute(tSlope, null);
licenseStatus =
m_AoInitialize.CheckInExtension(esriLicenseExtensionCode.esriLicenseExtensionCo
deSpatialAnalyst);
m_AoInitialize.Shutdown(); m_AoInitialize = null;
Creating Tools
Creating Tools
• Model Tool
– Samples Toolbox
• Script Tool
– Multiple Ring Buffer Tool
– Spatial Statistics Tools
• Function Tool (System Tool)
– Most Geoprocessing Tools are Function Tools

• Remember: “A Tool is a Tool is a Tool”

Model Tools
What is a Model?
• Automated work flow by adding processes together in
ModelBuilder that will execute in sequence when the model
is run.
What is ModelBuilder?
• The ModelBuilder window is the interface you use to create
models in ArcGIS.

MB Window
Why Build Models?

• Automate a geoprocessing workflow

– Analysis, data management, conversion, etc.
• Record and document a methodology
– How to create a specific geodatabase schema
• Share geoprocessing knowledge
– Easily communicates what is being done
• Create custom tools
– Aggregate common operations into one tool
Models are Tools
• Models are stored as tools in toolboxes
–Toolboxes may be stored in a folder as a .tbx file or in a
geodatabase
–Toolboxes may be easily shared by sharing the .tbx file or
a personal geodatabase
Model Tools
• Generic tools that will be reused and shared.

• Behave exactly like all other tools in the toolbox

and can be executed:
–using its dialog
–as a command in the command line window
–within another model
–as a function within a script or program.
Model Parameters

Exposed model
parameters appear as
input boxes on the
model dialog
Working with variables: Intermediate data

Derived data is
flagged as
intermediate
Intermediate Data
• By default all derived data is flagged as intermediate

• Exceptions:
–Variables set as model parameters
–Output of tools that modify the input (Ex: AddField)

• Models run from a dialog box or the command line delete

intermediate data automatically

• Models run within the MB window maintain intermediate

data on disk. Delete Intermediate Data option deletes
intermediate data and updates process state.
Model Properties: General

Modify the name, label,

description, and style
sheet of the model. Plus
specify relative vs.
absolute paths
Model Properties: Help

Link to compiled help

file
Compiled help file
location
Tool help context id
Export to HTML
Model Properties: Parameters

•Add
•Remove
•Change order
Model Properties: Environments
Model Environment Settings
• Values used by multiple tools, similar to a parameter (ex:
current workspace, cell size, cluster tolerance)
• Can be set application wide, model level, or process level
– Model specific settings override application settings
– Process specific settings override model settings
Create Environment Variables
• Variables created this way will be attached to just this tool
Create Parameter Variables
• All parameters for a tool, other than input and output, must
be set as variables to be shared between processes.
Use models to organize your work

• You can include one model in another just like any other
tool.
Sharing Models
• To make models easy to share
– Set relative paths for model and script tools
– Set relative paths for map documents
– Document
– Share entire directory/geodatabase
ArcGIS 9.2 - More Advanced Programming
Constructs
• Lists & Series
– Variable properties: List

• Do loop
– Model properties: Iteration
• Fixed loop
• Conditional loop
– Variable properties
• Series
• Feedback

• If/Then
– Process properties: Preconditions
– Merge Branch tool
Demo – Create a Model Tool
Script Tools
Learning Python Scripting with ArcGIS

• ArcGIS Desktop Help

– Specific help and samples for all of the geoprocessor’s methods and
properties
• Geoprocessing Programming Model
– Logical layout of scripting objects with their methods and properties
as a quick reference (.pdf availabe)
• ESRI Training has two classes focused on Python
• Python References
– You should have a good Python reference to augment ArcGIS
documentation
– Introductory Python References
– We like:
• “Learning Python” by Mark Lutz, published by O’Reilly & Associates
• “Core Python” by Wesley J. Chun, published by Prentice-Hall
Why Scripting?
• Scripting supports the use of easy to learn, yet powerful
languages that offer:
– Rapid development
– Interoperability (Glue language)
• C/C++, VB, COM classes
• Executables (anything that runs at the OS prompt)
• Other apps which support scripting (Excel, Word, SAS)
• Most do not support interface programming
– Some languages are cross platform (Python)
– Can be run independent of ArcGIS applications
– Can be scheduled to run daily/weekly, anytime
Creating Tools from Scripts

• Why?
–Provides an efficient method for defining and executing a
series of geoprocessing tools
• Automation
–The script is generic and can be used with other data
• Script can use arguments from the user
–You want to use a script in ModelBuilder
• Incorporate another system with a script wrapper or do branching
–You want to easily share your script
• Not everyone knows how to run a stand-alone script
• Puts a familiar face on your work
Scripting Tasks and Needs

• Batch processing
– Scripts require the ability to find and iterate data (i.e. tables, features
classes, workspaces, fields)
• Data properties
– Scripts need to be able to determine properties of data (i.e. Spatial
reference, geometry type)
• Data Access
– Miscellaneous functions to make scripts easier to write and more
productive
• Error Handling
– Scripts need to determine if something went wrong and report why
ESRI Recommends Python
• Fulfills the needs of our user community
–Free
–Simple
–Modular
–Object oriented
–Easy to maintain
–Scalable
–Cross platform (windows & UNIX/Linux)
–Integrated Development Environment (IDE)
–Established and active user community
–Most geoprocessing examples are available in Python
Creating Tools from Scripts

• Step 1: Create argument variables

–Use GetParameterAsText() to obtain script argument
values
• Step 2: Add messaging to your script
–Return informative messages during execution of the
script
–Return error messages when a problem arises
–Three methods on the geoprocessor to support tool
messaging
• AddMessage()
• AddWarning()
• AddError()
Creating Tools from Scripts

• Step 3: Add the script to a toolbox

– Give the tool a name, label and description
– Set the tool source and use relative paths option if you plan on
sharing the tool
– Define the parameters that will correspond to your script
Creating Tools from Scripts

• Step 3: Defining Parameters

–Parameters have several properties
• Name: What you see on the dialog and on the command line.
• Type: Is it required, optional or derived?
• Direction: Is the data being used (input) or created (output)?
• Multi-value: Do you want a list of values or just one?
• Default: Is there a default value?
• Environment: Does an environment provide a default value?
• Filter: Do you want to provide a choice or limit input values?
• Dependency: Does this parameter depend on another?
Script Tools - Output Parameters

• All tools should have an output

–If the script updates an input dataset, create a derived
parameter
• Set its dependency to the input parameter
• The properties of the input are automatically added to the output

• This makes for a better user experience when used in

ModelBuilder
Script Tools - Output Parameters

• If an output parameter is a scalar value, make it

derived.
–Use the Geoprocessor’s SetParameterAsText() method to
set it at the end of your script
–Allows chaining of the output value in a model
–The output value is automatically added as a message
Script Tools - Parameter Dependencies

• Some parameter types have built-in behavior

when there is a parameter dependency.
• Fields with an Input table or feature class
– Fields will be populated automatically in the dialog
• Derived parameter with an input parameter
– The derived parameter value will automatically be set to the
value of the input parameter it depends upon
Script Tools

• AML is a supported source for script tools

– Need to change the default behavior of an AML to support this
• By default it must execute with arguments when opened
• Use the RegisterAMLAsExecutable registry file to make
this change
– File is in the ArcGIS\ArcToolbox\Scripts folder
• Any ArcInfo workstation module is supported
– AML must start in the Arc module and then call other modules
– Display windows and form menus are supported

AML & Python Equivalency Documentation

Script Tools and Personal GDB

• Script tools run outside the calling application (ArcMap &

ArcCatalog).

• Locking affects them as they are a 2nd application.

• MSAccess applies a lock to the entire file (vs table by table).

• Can add records (Append tool) or remove records (Delete

Rows & Delete Features tools), but can not change schema:
Delete Field, Add Field, Define Projection.
ArcGIS 9.3 Bulletin

• The script tool framework has been extensively

enhanced to support:
–Custom behavior for your tool dialogs and a rich user
experience in ModelBuilder
• Achieved by editing a pre-defined Python class
–Indication of tool progress via the standard progress
dialog
–Faster execution of Python based tools
• No startup time required for the geoprocessor

• Python scripters will have the same capabilities as

ArcObjects developers for writing tools
Demo – Create a Script Tool
Running Model Tools and Script Tools
• It is also possible to execute your custom tools such as
model tools and script tools from custom toolboxes.

// Initialize the Geoprocessor

GeoProcessor GP = new Geoprocessor();

// Must Load the BestPath toolbox to the Geoprocessor

GP.AddToolbox(@"C:\SanDiego\BestPath.tbx");

// Generate the array of parameters

IVariantArray parameters = new VarArrayClass();
parameters.Add(@"C:\SanDiego\source.shp");
parameters.Add(@"C:\SanDiego\destination.shp");
parameters.Add(@"C:\SanDiego\bestpath.shp");

// Execute the Model tool by name

GP.Execute("CalculateBestPath", parameters, null);
Generate Assemblies for Custom Geoprocessing
Tools - .NET

• .NET users can use the IDE

integration framework built in to
Visual Studio .NET to generate a
Geoprocessing assembly to
represent any custom toolbox.

• http://edndoc.esri.com/arcobjects/9
.2/NET/462f5942-7928-44d6-b85b-
56dc1a0d2ac4.htm
Running Custom Geoprocessing Tools - JAVA

• JAVA users can use the IDE

integration framework built in to
Eclipse or the command line, to
generate Java code to
represent any custom toolbox.

• http://edndoc.esri.com/arcobjects/9
.2/Java/java/engine/ide_integration
/eclipse/EclipseGPTool.html
Demo – Show Code for Running a Model Tool - .NET
Summary: Use Geoprocessing Tools in
Your Applications

• Not necessary to understand multiple Object Models.

• Saves time and reduces the amount of code necessary to
perform an operation.
• Provides an efficient method to perform iterative processes.
• Provides easy access to data properties.
• If there is a need to do data Analysis, Conversion, or
Management, check first if a Geoprocessng tool exists.
Geoprocessing Offers More
Batch Processing
• Many Geoprocessing tasks are repeated multiple times.
– Example: executing a Geoprocessing tool on each feature classes in
a Geodatabase

• The GeoProcessor can be used to support automation and

batch processing.
Batch Processing
• Geoprocessor provides a number of “list” functions:
– ListFeatureClasses (string Wild Card, string Feature Type, string
Dataset)
– ListTables (string Wild Card, string Table Type)
– ListDatasets (string Wild Card, string Dataset Type)
– ListRasters (string Wild Card, string Raster Type)
– ListWorkspaces (string Wild Card, string WorkspaceType)

• The workspace environment must be set.

• The return of each of these methods is an IGpEnumList.
Batch Processing
// List all TIFF files in the workspace and build pyramids
GP.SetEnvironmentValue("workspace", @"C:\Ccm\results");

IGpEnumList rasters = GP.ListRasters("*", "TIFF");

string raster = rasters.Next();

// Intialize the BuildPyramids tool

BuildPyramids pyramids = new BuildPyramids();

while (raster != "") {

// Set input raster dataset pyramids.
pyramids.in_raster_dataset = raster;
GP.Execute(pyramids, null);
raster = rasters.Next();
}
Describing Data: Scripting
• Similar to &DESCRIBE in AML.
• Returns an object with relevant properties based on type of
data being described.
• Allow script to determine properties of data:
– Spatial reference
– Extent of features
– List of fields
– ShapeType (point, polygon, etc)
– Data type (coverage, shapefile, etc)
• Logic can be added to the script to branch (if statement)
based on those properties.
Describe: Scripting Example

# describe a feature class

dsc = gp.Describe(“c:/myGDB.mdb/rivers”)

# branch based on the feature class’ property

if dsc.ShapeType == “Polyline”:
print “This is a line feature class”
Describing Data: VB, .NET, JAVA…

• The Geoprocessor's GetDataElement method can be used

to describe data.
• Returns an IDataElement object.
• Data elements allows a program to determine properties of
data.
– Spatial reference
– Extent of features
– List of fields
– ShapeType (point, polygon, etc)
– Data type (coverage, shapefile, etc)
• Logic can be added to the program to branch (if statement)
based on those properties.
Describing Data: .NET Example

• A data element is a light-weight object providing access to

the properties of a dataset
– The DataElement type defines the available properties of the data
– Every data type in ArcGIS has a data element

// Describe the input featureclass

IDataElement de = GP.GetDataElement(@"C:\Portland.gdb\streets", ref dt);

// Open the featureclass dataelement and get the shapetype

IDEFeatureClass defc = de as IDEFeatureClass;
If (defc.ShapeType == esriGeometryType.esriGeometryPolyline)
Console.WriteLine("ShapeType is polyline.");
Cursors: Scripting

• Step through feature classes or tables

–Search cursor: step through each record and get the
field’s value*
–Update cursor: step through each the records with the
option to change some of those values (excludes the
geometry field)
–Insert cursor: add a record to a table and set some
values, not supported for feature classes

* including the Geometry

Function Tools – ArcObject Implmentation
Developing Function Tools

• Most ESRI Geoprocessing tools are implemented as COM

function tools.

• Functions in most cases are a single operation composed of

parameters (recommended).

• Requires ( a minimum) of implementing two interfaces:

– IGPFunction
– IGPFunctionFactory

• Many tools can be included in a single DLL.

Developing Function Tools - Usage

• Determine the tool usage:

–What is the tool name?
–What are the parameters and their properties?
• Name
• Type – Required, Optional, Derived
• DataType – FeatureClass, Raster
• Value – FeatureClass, Raster
• Direction – Input, Output
• Domain – set of values
• Dependencies – one parameter dependent on another
Usage Example
• Clip <in_features> <clip_features> <out_feature_class>
{cluster_tolerance}

• AddField <in_table> <field_name> <LONG | TEXT | FLOAT

| DOUBLE | SHORT | DATE | BLOB> {field_precision}
{field_scale} {field_length} {field_alias} {NULLABLE |
NON_NULLABLE} {NON_REQUIRED | REQUIRED}
{field_domain}

<> = required {} = optional UPPERCASE = Keyword

Parameters

• Defines the characteristics of the inputs and

outputs to the function tool.

• IGPFunction::ParameterInfo property
–Define the parameters
–Returns an array (IArray) of parameter objects
(IGPParameter).
Parameter Type
• Required
– <input_featureclass>

• Optional
– {cluster_tolerance}

• Derived
– Used to indicate when the tool updates the input parameter i.e.
AddField
– Does not show up on the dialog or command line
– Used in ModelBuilder to indicate changed state of the value and
to provide proper chaining.
Parameter Type - Derived

‘VB Code
‘ Define the datatype of the Derived Parameter
Dim pGPParameterEdit as IGPParameterEdit
Set pGPParameterEdit = New GPParameter
Set pGPParameterEdit.DataType = New DEFeatureClassType
'Value object is DEFeatureClass
Set pValue = New DEFeatureClass
Set pParamEdit.Value = pValue
'Set Output Parameter properties
pParamEdit.Direction = esriGPParameterDirectionOutput
pParamEdit.DisplayName = "Output FeatureClass"
pParamEdit.Enabled = True
pParamEdit.Name = "out_featureclass"
pParamEdit.ParameterType = esriGPParameterTypeDerived
pParamEdit.AddDependency "input_featureclass"
Parameter DataType

• Defines the datatype of each parameter

– DataTypes: FeatureClass, Table, Rasters, …
– Basic Types: String, Double, Boolean, …
– Geoprocessing Structures: spatial reference, extent, cell size,
remap table, …
– Complex Structures: list of values, composite datatype (either |
or)

‘VB Code
‘ Define the datatype of the Input Parameter
Dim pGPParameterEdit as IGPParameterEdit
Set pGPParameterEdit = New GPParameter
Set pGPParameterEdit.DataType = New DEFeatureClassType
Parameter DataType

• Supporting layers and tables in ArcMap and ArcGlobe:

– GPTableViewType, GPFeatureLayerType,
GPRasterLayerType...

‘ Define the datatype of the Input Parameter to accept layers

Dim pGPParameterEdit as IGPParameterEdit
Set pGPParameterEdit = New GPParameter
Set pGPParameterEdit.DataType = New GPFeatureLayerType
Parameter DataType - Lists
• GPValueTableType – a table of one or more datatypes.
– Define the datatype for each column in the value table (Union
Tool)

‘GPValueTableType
Dim pValueTableType As IGPValueTableType
Set pValueTableType = New GPValueTableType

'GPValueTable
Dim pGPValueTable As IGPValueTable
Set pGPValueTable = New GPValueTable

'First DataType
Dim pDataType1 As IGPFeatureLayerType
Set pDataType1 = New GPFeatureLayerType
pValueTableType.AddDataType pDataType1, “input_Features", 100, Nothing

‘Second DataType
Dim pDataType2 As IGPDoubleType
Set pDataType2 = New GPDoubleType
pValueTableType.AddDataType pDataType2, "double", 100, Nothing
'Add DataTypes to the GPValueTable
pGPValueTable.AddDataType pDataType1
pGPValueTable.AddDataType pDataType2
Parameter DataType - Composite

• GPCompositeDataType – this datatype is used when

the parameter can be more than one datatype.
–i.e. Append Tool

'Create the GPCompositeDataType

Dim pGPCompositeDataType As IGPCompositeDataType
Set pGPCompositeDataType = New GPCompositeDataType
'Create the DataTypes that are permitted as input
Dim pDataType3 As IGPDataType
Set pDataType3 = New GPTableViewType
Dim pDataType4 As IGPDataType
Set pDataType4 = New GPRasterLayerType
'Add datatypes
pGPCompositeDataType.AddDataType pDataType3
pGPCompositeDataType.AddDataType pDataType4
'Set the Input Parameter
Set pParamEdit = New GPParameter
Set pParamEdit.DataType = pGPCompositeDataType
Set pParamEdit.Value = New GPTableView
Parameter Value
• For each DataType there is a Value object (IGPValue).
– FeatureClass, FeatureLayer, Table …
• Used as actual inputs to each function.
– Contains the path to the FeatureClass, scalar value…

• Arrays of values are created based upon the same order as

the parameters.
• This array is input to the validate and execute methods of
the function.
Parameter Domain

• Used to filter values

–Feature type: Polygon, Polyline, Point, …
–Field type: string, double, …
–Coded Value domain (fixed list of values)
–Range domain (range of numeric values)

• For a complete list of Domain objects, refer to the

ArcGIS Developer Help and search for IGPDomain.
Parameter Dependency

• Field parameters are commonly dependent on

another table/featureclass parameter.
–E.g. The list of fields for a field parameter is dependent on
the input table.
IGPFunction::Validate
• Performs light-weight verification that a given set of values
are of the appropriate number, type, and value.

• Returns an array of messages, identifying warnings/errors,

with a one-to-one correspondence to the array of
parameters.

• Three important roles of Validate:

– Basic validation – number of required values, datatype, etc.
( use GPUtilities::InternalValidate )
– Complex interaction between parameters
– Populate properties of the output parameter
Validate - InternalValidate

• Method available on GPUtilities object.

• Tests the validity of a set of values against a set of
parameters.
–Have all the required parameter values been supplied?
–Are the values of the appropriate data types?
–Does the input exist?
• This does not happen in ModelBuilder when the output value is the
input to another tool (i.e. a derived value)
Validate – Parameter Interaction

• Set rules for parameters.

– Adding a field
• limit the length of the field name. Sets maximum number of allowable
characters.

• Enable/Disable parameters.
– AddField
• Selecting FieldType of Text enables the Field Length parameter.
Validate – Update Output Properties

• Update the value (e.g. schema) of the output

parameter.
–i.e. AddField, Overlay operations

• This is important when using the tool in

ModelBuilder.

• Use GPUtilities::UnPackGPValue() and

GPUtilitities::PackGPValue()
IGPFunction::Execute

• Method to execute the tool given the array of

parameter values.
• Execute should do the following:
–Call Validate
• basic validation
–Open the datasets
• do this after calling validate
• Create objects from inputs (IFeatureClass, IField, etc)
–Check if overwrite output is true or false
• Delete the output if overwrite output is true
–Perform the operation
GPEnvironmentManager
• Object for managing all environments and settings used by
the tools.

• GPEnvironmentManager is passed to Validate() and

Execute().

• The tool will then have access to all of the current

environments and settings.
GPMessages Object
• Manages an array of GPMessage objects.

• Contains methods to generate and replace message

objects.

• Validate() returns a new GPMessages object, with the same

number and order as the parameter definition.
– GPUtilities::InternalValidate() creates/returns a new GPMessages
object based upon a given parameter definition.

• Execute() is passed an existing GPMessages object and

simply adds new messages as needed.
GPMessage Object
• GPMessage objects are composed of a message type, error
code, and description properties.

• GPMessage contains the following methods:

– IsInformational
– IsError
– IsWarning
– IsAbort
GPUtilities Object
• COM object which contains useful helper methods for the
function writer
– UnPackGPValue() to get the GPValue from the parameter.
– PackGPValue() to put the GPValue into the parameter.
– Exists
– Delete
– OpenDataset to open the datasouce associated with a value
– Others…
IGPFunctionFactory

• “Serves” up the functions.

–Factory is responsible for handing out the function name
objects for each function.

• Registered in the CATID_GPFunctionFactories

• Logical grouping of functions.

Demo – Calculate Area Tool
Function Tool Deployment

• Use ArcGIS Component Category Registrar dialog box

– Adds COM Registration function in your code.
– http://edndoc.esri.com/arcobjects/9.2/NET/ba841691-f879-407c-
ab9e-34043e10968f.htm
Function Tool Deployment – Custom Toolbox
Tool Deployment - Help

• Deliver the .chm file which is used to describe the tool and
its operation.

• Deliver the .xml file containing the default metadata for this
tool.
– For information about creating the metadata file refer to Knowledge
base article:
• http://support.esri.com/index.cfm?fa=knowledgebase.techarticles.articleSh
ow&d=27000
Function Tool Deployment – Install Program

• Create a custom install program (.NET)

–Recommended approach as many target machines may
not have the .NET Framework SDK.
– http://edndoc.esri.com/arcobjects/9.2/NET/0df20605-b457-42d6-
b63c-341a3824474a.htm
Function Tools - Summary
• Function Tools are built using ArcObjects.
• Required to implement IGPFunction and
IGPFunctionFactory
• Functions in most cases are a single operation composed of
parameters (recommended).
• Define the Tool’s usage
– Set the type, datatype, direction, domains, dependencies, etc.
• Each parameter is a specific data type.
Function Tools - Summary
• Validate – 3 important roles of Validate()

• Execute – Call Validate(), Open Datasets, check for fields,

perform operation.

• IGPFunctionFactory/IGPDataTypeFactory serves up the

functions and datatypes.

• GPUtilities provide helper functions

– UnpackGPValue, PackGPValue, OpenDataset, etc.
Summary

• Geoprocessing is for GIS Professionals

–Tools perform essential and elemental tasks
• Some of these tools go back > 25 years
–Computing with data – express ideas quickly and easily
–Framework for creating, managing, executing,
documenting, and sharing tools
• Geoprocessing is for developers
–Easy access to a rich set of tools from any language
–Reduce barriers between GIS professionals and software
developers
–Ubiquitous platform for delivering software
Additional Support
• Help “One Stop Shopping”
– Using Geoprocessing Tools
– Geoprocessing Tool Help
– Geoprocessing Concepts
– Samples
– Building Geoprocessing Custom Tools

• http://edndoc.esri.com/arcobjects/9.2/NET/shared/geoprocessing/geopr
ocessing/what_is_geoprocessing_qst_.htm

• http://edndoc.esri.com/arcobjects/9.2/Java/java/gp.html
Session Evaluations Reminder

Session Attendees:
Please turn in your session evaluations.
. . . Thank you