Library Reference  

Geoprocessing Library Overview


Supported with: ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server

Library dependencies: System, SystemUI, Geometry, Display, Server, Output, GeoDatabase, GISClient, DataSourcesFile, DataSourcesGDB, DataSourcesOleDB, DataSourcesRaster, GeoDatabaseDistributed, Carto, Location, NetworkAnalysis, Controls, GeoAnalyst, 3DAnalyst, GlobeCore, SpatialAnalyst, Framework, GeoDatabaseUI, DisplayUI, OutputUI, Catalog, CatalogUI, CartoUI, DataSourcesRasterUI, ArcCatalogUI, ArcCatalog, ArcMapUI, Editor, LocationUI, ArcMap, EditorExt, GeoDatabaseDistributedUI


The Geoprocessing library contains the objects that implement the unified geoprocessing framework. The geoprocessing framework is intended to meet the functional requirements to perform many GIS tasks and to provide a flexible framework for tool use, tool creation, and tool sharing.

What is Geoprocessing

Geoprocessing is a fundamental part of ArcGIS. Whether you're a new user or an old pro, geoprocessing will become an essential part of your day-to-day work with ArcGIS. Geoprocessing provides the data analysis, data management, and data conversion tools necessary for all GIS users.

Geoprocessing consists of operators, called tools, that operate on the data within ArcGIS (tables, feature classes, rasters, TINs, and so on), and perform tasks that are necessary for manipulating and analyzing geographic information across a wide range of disciplines. Each geoprocessing tool performs an essential operation on geographic data, such as projecting datasets from one map projection to another, adding fields to a table, or creating buffer zones around features. ArcGIS includes over 400 such geoprocessing tools. A geoprocessing tool takes ArcGIS datasets as inputs (such as feature classes, tables, rasters, and CAD files), applies an operation against this data, and creates a newly derived dataset as output.

Many uses of GIS involve the repetition of work, and this creates the need for a framework to provide automation of workflows. Geoprocessing answers this need by providing a rich set of tools and a mechanism to combine a series of tools in a sequence of operations using models and scripts.

Geoprocessing Framework

The core idea behind geoprocessing is to provide a flexible framework to allow you to quickly and easily turn your ideas into new geoprocessing tools. A model, for example, is a new tool built by you using ModelBuilder available with ArcGIS Desktop. This section is intended to explore this idea that geoprocessing is just a way for you to execute and create new tools. But first, it is important to explain how tools are managed and the different types of geoprocessing tools.

Toolboxes

A toolbox is a persistent entity that contains geoprocessing tools. It takes the form of a TBX file on disk or a table in a geodatabase. There are a collection of system toolboxes that are installed with ArcGIS. Toolboxes are composed of tools, grouped by functionality. For example, the Analysis Toolbox contains tools to do overlay analysis and proximity analysis. Some toolboxes are installed as part of an extension. For example, the Spatial Analyst Toolbox is only available when Spatial Analyst is installed. A toolbox is the mechanism for managing and sharing tools.

You can create new toolboxes in the ArcToolbox window or the ArcCatalog tree to hold the tools you want to use.

Tools

As mentioned, a Geoprocessing tool can be referred to as an operation that can take an input or set of inputs and generate one or more outputs. These inputs are referred to as parameters. Most Geoprocessing tools provided by ESRI are implemented as COM Function Tools contained in system toolboxes. However, there are four types of Geoprocessing Tools: a model tool, a script tool, a custom tool, and a function tool.

A Model is a tool that you author to automate your work flow, and keep track of your geoprocessing tasks. A model consists of one process or, more commonly, multiple processes strung together. A process consists of a tool, and its parameter values. The most important thing to note here is models are just tools. They behave exactly like all other tools. A model tool runs your GIS workflow to generate a new output.

A Script can be a tool that you author using a scripting language such as Python. Scripts are analogous to models, in that they can be used to automate a geoprocessing workflow. All geoprocessing tools can be accessed and executed inside a script.

A Function tool is built into the system and implemented via a programming language such as Microsoft Visual C++ or Microsoft .NET with COM interfaces. A Function tool requires implementing a minimum of two objects: a function object that implements IGPFunction and a function factory object that implements IGPFunctionFactory. The upcoming section called Tool Creation will focus on how to extend geoprocessing with function tools.

A Custom tool is similar in concept to a Function tool. However, unlike a Function tool with a static definition (i.e. behavior and parameters), a Custom tool can have a dynamic parameter definition (e.g. Models). A Custom tool is also referred to as a Tool Extension. Custom tools are built into the system and implemented via a programming language such as Microsoft Visual C++ or Microsoft .NET with COM interfaces. A Custom tool requires implementing four interfaces: IGPToolExtension, IGPToolExtensionFactory, IClone, and IPersistStream. More information about Custom tools will be explained in the Tool Creation section.

Tool Execution

A geoprocessing tool is executed by a geoprocessor. A geoprocessor is a helper 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, and examine the resulting messages. As explained above, toolboxes define the set of available tools for the geoprocessor. Toolboxes can be added and removed from the geoprocessor.

The following example uses the IGeoprocessor object to execute the CopyFeatures tool. This sample will export a shapefile to a new feature class in a file geodatabase. This sample also temporarily overrides the output coordinate system environment. The tool is simply executed by tool name, and the parameters and environments are provided as property sets.

[VC++]
int _tmain(int argc, _TCHAR* argv[])
{
	HRESULT hr;

	// Initialize the COM subsystem
	CoInitialize(NULL);

	// Initialize the Geoprocessor COM Object
	IGeoProcessorPtr ipGP(CLSID_GeoProcessor);

	// Build variant for the output feature class
	_variant_t vInputWells(L"C:\\gp\\IGeoprocessor\\wells.shp");

	// Build variant for the output feature class
	_variant_t vOutputWells(L"C:\\gp\\IGeoprocessor\\nfld.gdb\\wells");

	ipValues->Add(vInputWells);
	ipValues->Add(vOutputWells);

	// Override the output coordinate system environment
	IPropertySetPtr ipCoordSys(CLSID_PropertySet);
	ipCoordSys->SetProperty(L"outputCoordinateSystem", _variant_t(L"C:\\Program Files\\ArcGIS\\Coordinate Systems\\Projected Coordinate Systems\\Utm\\Nad 1983\\NAD 1983 UTM Zone 21N.prj"));

	// Execute CopyFeatures tool
	hr = ipGP->ExecuteToolByName(L"CopyFeatures_management", ipValues, 0, (IUnknownPtr)ipCoordSys, 0);

	// Print the bsMessages
	ipGP->GetMessage(-1, &bsMessages);
	wprintf(bsMessages);
	::SysFreeString(bsMessages);

	// If error occurred, exit
	if (FAILED(hr))
	  return 1;

	return 0;
}

Tool Creation

The geoprocessing framework is fully extensible by creating new geoprocessing tools and data types. Most geoprocessing tools provided by ESRI are implemented as COM function tools. A geoprocessing function tool is the low-level implementation of a geoprocessing tool. Geoprocessing functions tools are written in a system language (such as C++) and support a few standard COM interfaces that are used by the geoprocessing framework to load and execute the tool.

A geoprocessing function tool performs four basic tasks:

Each of these four basic tasks are described in detail in the technical document, Building Geoprocessing Function Tools. This document is available in the VB and VC++ SDKs and is intended for developers wanting to extend geoprocessing by building new tools using ArcObjects. This document will be further updated to describe how to build Custom tools.