developer’s guide to geoprocessing - esri · • empowers gis professionals to implement...
TRANSCRIPT
DeveloperDeveloper’’s Guide to Geoprocessing s Guide to Geoprocessing
Corey Tucker & Jason PardyCorey Tucker & Jason Pardy
ESRI Developer Summit 2008ESRI Developer Summit 2008 22
Monday, March 17th ScheduleMonday, March 17th Schedule
8:30 a.m.8:30 a.m.––11:30 a.m.11:30 a.m.PresummitPresummit Morning SeminarsMorning Seminars
10:00 a.m.10:00 a.m.––5:00 p.m.5:00 p.m.ESRI Showcase (Oasis 1) ESRI Showcase (Oasis 1)
11:30 a.m.11:30 a.m.––1:00 p.m.1:00 p.m.Lunch (Oasis 4)Lunch (Oasis 4)
1:00 p.m.1:00 p.m.––5:00 p.m.5:00 p.m.PresummitPresummit Afternoon SeminarsAfternoon Seminars
5:30 p.m.5:30 p.m.––7:30 p.m.7:30 p.m.Welcome Social (Wyndham Poolside) Welcome Social (Wyndham Poolside)
ESRI Developer Summit 2008ESRI Developer Summit 2008 33
Got technical questions . . .Got technical questions . . .
Ask them at:Ask them at:
www.esri.com/devsummitquestionswww.esri.com/devsummitquestions
We will reply to your question as soon as possible.We will reply to your question as soon as possible.
Workshop OutlineWorkshop 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: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 geoprocessingand 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 OverviewGeoprocessing Overview
Geoprocessing isGeoprocessing is……
Geoprocessing Tools & FrameworkGeoprocessing Tools & Framework
Geoprocessing ToolsGeoprocessing 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 FrameworkGeoprocessing Framework
1111
ModelsModels
Command LineCommand Line
Tool dialogTool dialog
ScriptsScripts
Geoprocessing FrameworkGeoprocessing 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 ToolsExecuting Tools
Executing ToolsExecuting Tools
•• System languages (C++, Java, .NET) and scripting System languages (C++, Java, .NET) and scripting languages (Python, languages (Python, JScriptJScript) can execute tools.) can execute tools.
• With ArcGIS 9.2, geoprocessing is now supported in ArcGISEngine 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).
GeoprocessorGeoprocessor
• 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.
ScriptingScripting
•• ArcGISArcGIS 9.2 contains a new native python module 9.2 contains a new native python module called called arcgisscripting.arcgisscripting.––This module is used to create the This module is used to create the GeoprocessorGeoprocessor..––This module will work on any platform.This module will work on any platform.
•• Win32com is still supported for windows, but new Win32com is still supported for windows, but new scripts should be written to use the arcgisscripting scripts should be written to use the arcgisscripting module.module.––VBScript and VBScript and JScriptJScript will only work on windows using will only work on windows using
Dispatch.Dispatch.
ScriptingScripting
• Existing scripts can be easily updated to use arcgisscripting by replacing two lines.
– 9.0, 9.1 from win32com.client import Dispatchgp = win32com.client.Dispatch(“esriGeoprocessing.GpDispatch.1”)
– 9.2import arcgisscriptinggp = arcgisscripting.create()
ScriptingScripting
• 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 geoprocessorthe new way and avoid Pythonwin altogether.– Unless scripts use other win32com functions, such as messagebox
Scripting Scripting –– Running a ToolRunning a Tool
• http://webhelp.esri.com/arcgisdesktop/9.2– Geoprocessing (Automating your work with Scripts)
# Create the Geoprocessor objectimport arcgisscriptinggp = arcgisscripting.create()
# Set workspace environmentgp.Workspace = “C:/Newfoundland”
# Execute the Buffer tooltry:gp.Buffer_analysis(“roads”, “roads_500”, “500 METERS”)
except:print gp.GetMessages(2)
Visual Basic 6 and C++Visual Basic 6 and C++
• The ESRI Geoprocessing Object Library contains a new object class called the GeoProcessor.
• The GeoProcessor implements the IGeoprocessorinterface.
• Parameters are passed to execute as a Variant Array.
• VB6 and C++ users use this interface.– VB6 – windows only– C++ - cross platform support
Public Sub Public Sub CreateShapefileCreateShapefile() () Const Const strFolderstrFolder As String = "D:As String = "D:\\DATA"DATA"Const Const strNamestrName As String = "As String = "MyShapeFileMyShapeFile" ' " ' DontDont include .include .shpshp extensionextensionConst Const strShapeFieldNamestrShapeFieldName As String = "Shape"As String = "Shape"
' Open the folder to contain the ' Open the folder to contain the shapefileshapefile as a workspaceas a workspaceDim Dim pFWSpFWS As As IFeatureWorkspaceIFeatureWorkspaceDim Dim pWorkspaceFactorypWorkspaceFactory As As IWorkspaceFactoryIWorkspaceFactorySet Set pWorkspaceFactorypWorkspaceFactory = New = New ShapefileWorkspaceFactoryShapefileWorkspaceFactorySet Set pFWSpFWS = = pWorkspaceFactory.OpenFromFile(strFolderpWorkspaceFactory.OpenFromFile(strFolder, 0), 0)
' Set up a simple fields collection' Set up a simple fields collectionDim Dim pFieldspFields As As IFieldsIFieldsDim Dim pFieldsEditpFieldsEdit As As IFieldsEditIFieldsEditSet Set pFieldspFields = New = New esriGeoDatabase.FieldsesriGeoDatabase.FieldsSet Set pFieldsEditpFieldsEdit = = pFieldspFields
Dim Dim pFieldpField As As IFieldIFieldDim Dim pFieldEditpFieldEdit As As IFieldEditIFieldEdit
' Make the shape field' Make the shape field' it will need a geometry definition, with a spatial reference' it will need a geometry definition, with a spatial referenceSet Set pFieldpField = New = New esriGeoDatabase.FieldesriGeoDatabase.FieldSet Set pFieldEditpFieldEdit = = pFieldpFieldpFieldEdit.NamepFieldEdit.Name = = strShapeFieldNamestrShapeFieldNamepFieldEdit.TypepFieldEdit.Type = = esriFieldTypeGeometryesriFieldTypeGeometry
Create a Create a shapefileshapefile: VB & : VB & ArcObjectsArcObjects
Dim Dim pGeomDefpGeomDef As As IGeometryDefIGeometryDefDim Dim pGeomDefEditpGeomDefEdit As As IGeometryDefEditIGeometryDefEditSet Set pGeomDefpGeomDef = New = New GeometryDefGeometryDefSet Set pGeomDefEditpGeomDefEdit = = pGeomDefpGeomDefWith With pGeomDefEditpGeomDefEdit
..GeometryTypeGeometryType = = esriGeometryPolygonesriGeometryPolygonSet .Set .SpatialReferenceSpatialReference = New = New UnknownCoordinateSystemUnknownCoordinateSystem
End WithEnd WithSet Set pFieldEdit.GeometryDefpFieldEdit.GeometryDef = = pGeomDefpGeomDefpFieldsEdit.AddFieldpFieldsEdit.AddField pFieldpField
' Add another miscellaneous text field' Add another miscellaneous text fieldSet Set pFieldpField = New = New esriGeoDatabase.FieldesriGeoDatabase.FieldSet Set pFieldEditpFieldEdit = = pFieldpFieldWith With pFieldEditpFieldEdit
.Length = 30.Length = 30
.Name = ".Name = "MiscTextMiscText""
.Type = .Type = esriFieldTypeStringesriFieldTypeStringEnd WithEnd WithpFieldsEdit.AddFieldpFieldsEdit.AddField pFieldpField
' Create the ' Create the shapefileshapefile' (some parameters apply to ' (some parameters apply to geodatabasegeodatabase options and can be defaulted as Nothing)options and can be defaulted as Nothing)Dim Dim pFeatClasspFeatClass As As IFeatureClassIFeatureClassSet Set pFeatClasspFeatClass = = pFWS.CreateFeatureClass(strNamepFWS.CreateFeatureClass(strName, , pFieldspFields, Nothing, _, Nothing, _
Nothing, Nothing, esriFTSimpleesriFTSimple, , strShapeFieldNamestrShapeFieldName, ""), "")End SubEnd Sub
Wait! ThereWait! There’’s more!s more!
Better Alternative: Use the Better Alternative: Use the GeoprocessorGeoprocessor
'Initialize the Geoprocessor (VB6)Dim GP As IGeoProcessorSet GP = New GeoProcessor
‘Set the workspace environmentGP.SetEnvironmentValue(“workspace”, “C:\Newfoundland”)
‘Set up the array of parametersDim parameters As IVariantArraySet parameters = New VarArrayparameters.Add (“roads”)parameters.Add (“roads_500”)parameters.Add (“500 Meters")
'Execute the buffer toolGP.Execute "Buffer_analysis", parameters, Nothing
C++ C++ -- Running a ToolRunning a Tool// Intialize the COM subsystemCoInitialize(NULL);
// Intialize the Geoprocessor COM ObjectIGeoProcessorPtr ipGP(CLSID_GeoProcessor);
// Set the workspace environmentpGP->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 nameIGeoProcessorResultPtr ipResult;HRESULT hr = ipGP->Execute(L"Buffer_analysis", ipValues, 0, &ipResult);
.NET.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 Each toolbox assembly contains classes representing each
geoprocessing tool in the standard geoprocessing tool in the standard ArcGISArcGIS geoprocessing toolboxes. geoprocessing toolboxes. –– Use these classes to set up and run geoprocessing tools with theUse these classes to set up and run geoprocessing tools with the
GeoprocessorGeoprocessor class.class.
.NET .NET –– Running a ToolRunning a Toolusing ESRI.ArcGIS.Geoprocessor;using ESRI.ArcGIS.AnalysisTools;…// Initialize the GeoprocessorGeoProcessor GP = new Geoprocessor();
// Set workspace environmentGP.SetEnvironmentValue("workspace", @ "C:\Data\Nfld.gdb");
// Initialize the Buffer ToolBuffer bufferTool = new Buffer();bufferTool.in_features = "roads";bufferTool.out_feature_class = "roads_500";bufferTool.buffer_Distance_or_field = "500 METERS";
// Execute the bufferGP.Execute(bufferTool, null)
.NET .NET –– Running a Tool By NameRunning a Tool By Name
• Can also execute a tool by name.
// Initialize the GeoprocessorGeoprocessor GP = new Geoprocessor();
// Generate the array of parametersIVariantArray 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 nameGP.Execute(“Buffer_analysis", parameters, null);
JAVAJAVA• 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 GeoprocessorGeoProcessor gp = new GeoProcessor();
// Initialize the Buffer toolBuffer 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 buffergp.Execute( buffer, null);
Working with Tool Names and Avoid Name Working with Tool Names and Avoid Name ConflictsConflicts
• 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)
ArcObjectsArcObjects as Tool Inputas 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)
GeoprocesssingGeoprocesssing ResultsResults
• The Execute method returns an IGeoProcessorResultobject 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 ResultsGeoprocessing ResultsExample 1: Return path to output data
Example 2: Return the default grid size
using ESRI.ArcGIS.Geoprocessing;…// The return value is an Object of type stringIGeoProcessorResult pResult = GP.Execute(bufferTool, null); object path = pResult.ReturnValue;…IFeatureClass pFc = GP.Open(path);
// The return value is an Object of type double. IGeoProcessorResult pResult = GP.Execute(calculateGridIndexTool, null); object defgrid = pResult.ReturnValue;
Geoprocessing MessagesGeoprocessing 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 Messages are retrieved from the Geoprocessing result object. 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);
JAVAString messages = GPResult.getMessages(2); System.out.println(messages);
Geoprocessing MessagesGeoprocessing Messages
• Individual messages can be retrieved using the GetMessage method.
// Execute UnionIGeoProcessorResult GPResult = GP.Execute(uniontool, null);
If (GPResult.MessageCount > 0) { for (int Count = 0; Count <= GPResult.MessageCount - 1; Count++) {
Console.WriteLine(GPResult.GetMessage(Count)); }
}
Environment SettingsEnvironment 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");
LicensingLicensing
•• Whenever a tool is executed in a program or script, an Whenever a tool is executed in a program or script, an ArcGISArcGIS license is required. license is required. –– By default, the highest license level is initialized when the By default, the highest license level is initialized when the
GeoprocessorGeoprocessor is createdis created
•• You can control and set the license level:You can control and set the license level:–– Scripting Scripting –– use use SetProductSetProduct() method to set the license level() method to set the license level–– System languages System languages –– use use AoInitializeAoInitialize to set the license levelto 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 ExtensionsLicensing 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 ExtensionChecking out an Extension
//Initialize the application IAoInitialize m_AoInitialize = new AoInitializeClass(); licenseStatus = m_AoInitialize.Initialize(esriLicenseProductCode.esriLicenseProductCodeArcEngine); licenseStatus = m_AoInitialize.CheckOutExtension(esriLicenseExtensionCode.esriLicenseExtensionCodeSpatialAnalyst);
// Initialize the GeoprocessorGeoprocessor 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.esriLicenseExtensionCodeSpatialAnalyst); m_AoInitialize.Shutdown(); m_AoInitialize = null;
Creating ToolsCreating Tools
Creating ToolsCreating 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: Remember: ““A Tool is a Tool is a ToolA Tool is a Tool is a Tool””
Model ToolsModel Tools
What is a Model?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 What is ModelBuilderModelBuilder??
• The ModelBuilder window is the interface you use to create models in ArcGIS.
MB Window
Why Build Models?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 ToolsModels 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 ToolsModel Tools
• Generic tools that will be reused and shared.
•• Behave exactly like all other tools in the toolbox Behave exactly like all other tools in the toolbox and can be executed: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 ParametersModel Parameters
Exposed model parameters appear as input boxes on the model dialog
Working with variables: Intermediate data
Derived data is flagged as intermediate
Intermediate DataIntermediate 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: GeneralModel Properties: General
Modify the name, label, description, and style sheet of the model. Plus specify relative vs. absolute paths
Model Properties: HelpModel Properties: Help
Link to compiled help fileCompiled help file locationTool help context idExport to HTML
Model Properties: ParametersModel Properties: Parameters
•Add•Remove•Change order
Model Properties: EnvironmentsModel Properties: Environments
Model Environment SettingsModel 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 VariablesCreate Environment Variables
• Variables created this way will be attached to just this tool
Create Parameter VariablesCreate 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 ModelsSharing 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
ArcGISArcGIS 9.2 9.2 -- More Advanced Programming More Advanced Programming ConstructsConstructs• 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 Demo –– Create a Model ToolCreate a Model Tool
Script ToolsScript Tools
Learning Python Scripting with Learning Python Scripting with ArcGISArcGIS
• 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 ArcGISdocumentation
– 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?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 ScriptsCreating 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 NeedsScripting 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 PythonESRI 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 ScriptsCreating 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 ScriptsCreating 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 ScriptsCreating 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 Script Tools -- Output ParametersOutput 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 Script Tools -- Output ParametersOutput 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 Script Tools -- Parameter DependenciesParameter 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 ToolsScript 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 GDBScript 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.
ArcGISArcGIS 9.3 Bulletin9.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 Demo –– Create a Script ToolCreate a Script Tool
Running Model Tools and Script ToolsRunning 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 GeoprocessorGeoProcessor GP = new Geoprocessor();
// Must Load the BestPath toolbox to the GeoprocessorGP.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 Generate Assemblies for Custom Geoprocessing Tools Tools -- .NET.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 Running Custom Geoprocessing Tools -- JAVAJAVA
• 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 Demo –– Show Code for Running a Model Tool Show Code for Running a Model Tool -- .NET.NET
Summary: Use Geoprocessing Tools in Summary: Use Geoprocessing Tools in Your ApplicationsYour 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 MoreGeoprocessing Offers More
Batch ProcessingBatch 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 ProcessingBatch 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 ProcessingBatch Processing
// List all TIFF files in the workspace and build pyramidsGP.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: ScriptingDescribing 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 ExampleDescribe: Scripting Example
# describe a feature classdsc = gp.Describe(“c:/myGDB.mdb/rivers”)
# branch based on the feature class’ propertyif dsc.ShapeType == “Polyline”:
print “This is a line feature class”
Describing Data: VB, .NET, JAVADescribing 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 ExampleDescribing 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 featureclassIDataElement de = GP.GetDataElement(@"C:\Portland.gdb\streets", ref dt);
// Open the featureclass dataelement and get the shapetypeIDEFeatureClass defc = de as IDEFeatureClass; If (defc.ShapeType == esriGeometryType.esriGeometryPolyline)
Console.WriteLine("ShapeType is polyline.");
Cursors: ScriptingCursors: 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 Function Tools –– ArcObjectArcObject ImplmentationImplmentation
Developing Function ToolsDeveloping 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 Developing Function Tools -- UsageUsage
• 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 ExampleUsage 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
ParametersParameters
• 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 TypeParameter 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 Parameter Type -- DerivedDerived
‘VB Code‘ Define the datatype of the Derived ParameterDim Dim pGPParameterEditpGPParameterEdit as as IGPParameterEditIGPParameterEditSet Set pGPParameterEditpGPParameterEdit = New = New GPParameterGPParameterSet Set pGPParameterEdit.DataTypepGPParameterEdit.DataType = New = New DEFeatureClassTypeDEFeatureClassType'Value object is DEFeatureClassSet Set pValuepValue = New = New DEFeatureClassDEFeatureClassSet Set pParamEdit.ValuepParamEdit.Value = = pValuepValue'Set Output Parameter propertiespParamEdit.DirectionpParamEdit.Direction = = esriGPParameterDirectionOutputesriGPParameterDirectionOutputpParamEdit.DisplayNamepParamEdit.DisplayName = "Output = "Output FeatureClassFeatureClass""pParamEdit.EnabledpParamEdit.Enabled = True= TruepParamEdit.NamepParamEdit.Name = "= "out_featureclassout_featureclass""pParamEdit.ParameterTypepParamEdit.ParameterType = = esriGPParameterTypeDerivedesriGPParameterTypeDerivedpParamEdit.AddDependencypParamEdit.AddDependency ""input_featureclassinput_featureclass""
Parameter Parameter DataTypeDataType
• 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 ParameterDim Dim pGPParameterEditpGPParameterEdit as as IGPParameterEditIGPParameterEditSet Set pGPParameterEditpGPParameterEdit = New = New GPParameterGPParameterSet Set pGPParameterEdit.DataTypepGPParameterEdit.DataType = New = New DEFeatureClassTypeDEFeatureClassType
Parameter Parameter DataTypeDataType
• Supporting layers and tables in ArcMap and ArcGlobe:– GPTableViewType, GPFeatureLayerType,
GPRasterLayerType...
‘ Define the datatype of the Input Parameter to accept layersDim Dim pGPParameterEditpGPParameterEdit as as IGPParameterEditIGPParameterEditSet Set pGPParameterEditpGPParameterEdit = New = New GPParameterGPParameterSet Set pGPParameterEdit.DataTypepGPParameterEdit.DataType = New = New GPFeatureLayerTypeGPFeatureLayerType
Parameter Parameter DataTypeDataType -- ListsLists• GPValueTableType – a table of one or more datatypes.
– Define the datatype for each column in the value table (Union Tool)
‘GPValueTableTypeDim pValueTableType As IGPValueTableTypeSet pValueTableType = New GPValueTableType
'GPValueTableDim pGPValueTable As IGPValueTableSet pGPValueTable = New GPValueTable
'First DataTypeDim pDataType1 As IGPFeatureLayerTypeSet pDataType1 = New GPFeatureLayerTypepValueTableType.AddDataType pDataType1, “input_Features", 100, Nothing
‘Second DataTypeDim pDataType2 As IGPDoubleTypeSet pDataType2 = New GPDoubleTypepValueTableType.AddDataType pDataType2, "double", 100, Nothing 'Add DataTypes to the GPValueTablepGPValueTable.AddDataType pDataType1pGPValueTable.AddDataType pDataType2
Parameter Parameter DataTypeDataType -- CompositeComposite
• GPCompositeDataType – this datatype is used when the parameter can be more than one datatype.–i.e. Append Tool
'Create the GPCompositeDataTypeDim Dim pGPCompositeDataTypepGPCompositeDataType As As IGPCompositeDataTypeIGPCompositeDataTypeSet Set pGPCompositeDataTypepGPCompositeDataType = New = New GPCompositeDataTypeGPCompositeDataType'Create the DataTypes that are permitted as inputDim pDataType3 As Dim pDataType3 As IGPDataTypeIGPDataTypeSet pDataType3 = New Set pDataType3 = New GPTableViewTypeGPTableViewTypeDim pDataType4 As Dim pDataType4 As IGPDataTypeIGPDataTypeSet pDataType4 = New Set pDataType4 = New GPRasterLayerTypeGPRasterLayerType'Add datatypespGPCompositeDataType.AddDataTypepGPCompositeDataType.AddDataType pDataType3pDataType3pGPCompositeDataType.AddDataTypepGPCompositeDataType.AddDataType pDataType4pDataType4'Set the Input ParameterSet Set pParamEditpParamEdit = New = New GPParameterGPParameterSet Set pParamEdit.DataTypepParamEdit.DataType = = pGPCompositeDataTypepGPCompositeDataTypeSet Set pParamEdit.ValuepParamEdit.Value = New = New GPTableViewGPTableView
Parameter ValueParameter 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 DomainParameter 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 DependencyParameter 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::ValidateIGPFunction::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 Validate -- InternalValidateInternalValidate
• 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 Validate –– Parameter InteractionParameter 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 Validate –– Update Output PropertiesUpdate 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::ExecuteIGPFunction::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
GPEnvironmentManagerGPEnvironmentManager
• 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.
GPMessagesGPMessages ObjectObject
• 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.
GPMessageGPMessage ObjectObject
• GPMessage objects are composed of a message type, error code, and description properties.
• GPMessage contains the following methods:– IsInformational– IsError– IsWarning– IsAbort
GPUtilitiesGPUtilities ObjectObject
• 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…
IGPFunctionFactoryIGPFunctionFactory
• “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 Demo –– Calculate Area ToolCalculate Area Tool
Function Tool Deployment Function Tool Deployment
•• Use Use ArcGISArcGIS Component Category Registrar dialog boxComponent Category Registrar dialog box–– Adds COM Registration function in your code.Adds COM Registration function in your code.–– http://edndoc.esri.com/arcobjects/9.2/NET/ba841691http://edndoc.esri.com/arcobjects/9.2/NET/ba841691--f879f879--407c407c--
ab9eab9e--34043e10968f.htm34043e10968f.htm
Function Tool Deployment Function Tool Deployment –– Custom ToolboxCustom Toolbox
Tool Deployment Tool Deployment -- HelpHelp
• 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 Function Tool Deployment –– Install ProgramInstall 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 Function Tools -- SummarySummary
• 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 Function Tools -- SummarySummary
• 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.
SummarySummary
• 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 SupportAdditional 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/geoprocessing/what_is_geoprocessing_qst_.htm
• http://edndoc.esri.com/arcobjects/9.2/Java/java/gp.html
Session Evaluations ReminderSession Evaluations Reminder
Session Attendees:Session Attendees:Please turn in your session evaluations.Please turn in your session evaluations.
. . . Thank you. . . Thank you