Creating a non-trival custom GP tool - inputs, outputs, and responding to environment settings


This document was published with and applies to ArcGIS 9.3.
PurposeThe purpose of the Point File Information geoprocessing tool is to demonstrate how a non-trivial custom geoprocessing tool can be written using ArcObjects and the .NET Platform utilizing a variety of required, optional, and derived input and output parameters, and responding to environment settings as necessary. This tool can be run standalone against a folder of XYZ, LAS, or GENERATE point files to output basic statistical information about the point files in the form of a Feature Class where the Shape field is set to the 2D or 3D bounding box of the points contained within each file. Alternatively, it can be chained to other tools used in the Terrain build process that require its Average Point Spacing output value to specify an optimal Terrain tile size for the data provided.

Development licensing Deployment licensing
ArcView ArcView
ArcEditor ArcEditor
ArcInfo ArcInfo
Engine Developer Kit Engine Runtime

Additional Requirements
  • A 3D Analyst license (ArcView, ArcEditor, or ArcInfo) or a 3D license (Engine Runtime) is required at runtime of the tool to view geometries persisted in the output Feature Class in three dimensions.

How to use

See Using the samples for help on compiling, setting up the debugger, and running the sample (either an exe or dll).

How to run this sample from ArcCatalog
  1. After compiling the sample, run ArcCatalog.
  2. Right click on the ArcToolbox heading at the top of the ArcToolbox pane and click New Toolbox to add a new toolbox.
  3. Right click on the new toolbox added and click Add, Tool.
  4. Expand Developer Samples, Terrain, and then check the box next to Point File Information and click OK.
  5. Double click on the Point File Information tool now added to the new toolbox to run the tool, which will open the user interface shown in the first image below.
  6. Enter the parameters to be passed as input to the tool. For additional help on defining these parameters see the Additional Information section below.
  7. Click OK to run the geoprocessing tool, and the execution window (in the second image below) will appear.
  8. Once the tool has finished executing, you will see the output of it in the ArcCatalog window. An example of what you might see is shown in the third image.

  9. the tool's user interface

    the tool's execution window

    the tool's output

Additional information

Overview

 
This tool is intended to be run as the first step in the Terrain build process.
 
In order to optimally build a Terrain, we need to know some basic statistical information about the raw point data that the Terrain will be constructed from. One of these statistics is termed: Average Point Spacing, which takes the number of points in a given source file containing XYZ data (whether in ASCII or Binary form), divides it by the XY extent that that file encompasses (points/area), and then returns the square root of that quantity as the: Average Point Spacing - a linear approximation of the average spacing in the X or Y direction between points in a given file.
 
If one attempts to build a Terrain from more than one source file, then the minimum of the Average Point Spacings of all files will be taken as the Average Point Spacing for the entire Terrain. This parameter dictates how many tiles will then be generated to represent the Terrain, and how many points from the original source data will be clustered onto each tile, as Terrains use a tile-based caching mechanism to reduce the amount of time required to render at a given zoom level/resolution.
 
Tests revealed that having a greater number of tiles with fewer points per tile performed better than having a fewer number of tiles with greater points per tile, this being the reason for taking the minimum of the Average Point Spacings.
 
One would ideally run this tool as the first step in a Terrain build model (ModelBuilder), and feed its Min Average Point Spacing output into intermediate steps that require this parameter in the successful construction of a Terrain dataset ("Create Terrain (3d)" and "ASCII 3D To Feature Class (3d)").
 

GP Parameters Exposed

 
[Parameter {Direction, Type}]
 
InputFolder {Input, Required}
 
The location from which source data are read. This folder can be located locally or remotely on a network share. Data can all be placed directly in the top level folder or in subfolders, to be examined recursively - if one checks the following RecurseInputSubfolders parameter.
 
RecurseInputSubfolders {Input, Required}
 
If checked, all subfolders will be examined recursively for data matching the InputFileSuffix (if specified) or all data if unspecified. If unchecked, only data stored in the top level folder will be examined.
 
InputFileFormat {Input, Required}
 
One specifies here whether one's source data has been recorded in the LAS Binary format or ASCII XYZ or GENERATE format. The Terrain Data Importer will then use this information to attempt to extract relevant data such as the PointCount and Extent of the data, used to calculate the Average Point Spacing. There is no specific requirement that XYZ files end with .xyz, GENERATE files end with .gen, and LAS files end with .las, for example. Consequently, one can choose a single InputFileFormat and place files recorded in this format having different extensions in the same folder and all be read successfully by the Terrain Data Importer.
 
InputFileSuffix {Input, Optional}
 
One can optionally specify the extension of files to consider when examining the Input Folder (either top level only or additionally subfolders recursively). For example, if one specifies ".las" or "las" here, without the quotes, all files that do not match this extension will be filtered out, and only files ending with "las" will be processed. One should not include a leading "*" here, as this parameter is merely a suffix and not intended to be used to wildcard match entire file names. If unspecified, all files (".*") will be processed.
 
InputCoordinateSystem {Input, Optional}
 
If knows the coordinate system the data has been recorded in, one can specify it here. If one does not know this information or leaves it blank, the parameter will default to an Unknown Coordinate System. This parameter is one component of an Input Spatial Reference object to be generated.
 
OutputGeometryDimensions {Input, Required}
 
The user specifies here whether the geometries written to the output Feature Class should be 2D (Polygon) or 3D (Multipatch). This parameter is cross validated against the OutputZFlag parameter exposed via Environment Settings. If there is a conflict, a message will be displayed.
 
OutputFeatureClass {Output, Required}
 
An Output Feature Class is generated from all of the source data loaded into the tool, containing the following information:
 
Shape: The 2D/XY extent (in the form of a Polygon) or 3D/XYZ extent (in the form of a Multipatch) of a given file - that can then be loaded into ArcMap or ArcScene for visual validation of data (in case some files may have had one or more erroneous values recorded - causing one or more of the X, Y, or Z values to be out of range of other data loaded in the same set). One can symbolize one's 2D polygons in ArcMap or use the Identify tool in ArcScene to quickly identify the files that may need to be excluded from or cleaned prior to being loaded into subsequent steps of the Terrain build process.
 
FileName: The name of file including the extension (not prefixed by path).
 
PointCount: The number of data points contained by the file.
 
AvgPtSpc: The average point spacing of all points in the given file.
 
XMin, XMax, YMin, YMax, ZMin, ZMax: Data extent information extracted as attributes here for convenience.
 
This Feature Class can be written as a shapefile or Feature Class within a Geodatabase, whether Personal, File, or SDE, either locally or on a network share. If written as a Feature Class within a Geodatabase, it can either be written into a Feature Dataset within the Geodatabase or directly into the Geodatabase. If the Feature Class is not fully specified (only a name is provided, no path information is supplied by the user), the Feature Class will be written: to the Scratch Workspace location, if specified via Environment Settings, otherwise to the Input Folder location, the location from which source data are loaded.
 
OutputMinAvgPtSpc {Output, Derived}
 
At the end of the tool's execution, the Min of the AvgPtSpc column of the Output Feature Class is extracted and written into this derived GP Parameter. As it is a derived parameter, it does not appear on GP Function UI. It does not require any user intervention - making it an appropriate candidate for a derived parameter.
 
If at the end of the tool's execution, no features were written to the Output Feature Class, then this parameter will assume a default value of: -1. Models can test this value to see if they can proceed (if the value is > 0) or whether they must halt and the user must investigate the reason why no features were written before proceeding (if the value is -1).
 

Environment Settings Responded To

 
ConfigKeyword
 
Mainly for illustration purposes, one can observe how this Environment Setting is to be used in the construction of the Output Feature Class.
 
Extent
 
If an extent is specified here, then any files read from within the specified Input Folder whose extents do not even partially intersect the specified extent will not be considered and will not have a corresponding feature written to the Output Feature Class. This is used for spatial filtering of data.
 
OutputCoordinateSystem
 
Similar to the above case for the Input Spatial Reference, this parameter is used (if specified), to construct an Output Spatial Reference object. And as in the above case, if the parameter is not specified, a default Unknown Spatial Reference object is generated. If the parameter is specified, then the tool uses it in the construction of a Spatial Reference object.
 
OutputZFlag
 
Mainly for illustrative purposes, one can set this parameter - to see if the tool runs if the value set conflicts with the OutputGeometryDimensions parameter specified via the GP Function UI.
 
OverwriteOutput (via IGeoprocessorSettings)
 
If this parameter is set and one specifies an Output Feature Class that already exists, then one can proceed (although warned with an exclamation mark next to the parameter) to overwrite this Feature Class. If this parameter is not set and one specifies an Output Feature Class that already exists, then one cannot proceed and a red [x] will appear beside the parameter.
 
ScratchWorkspace
 
As indicated earlier, if one has not fully specified one's Output Feature Class, and has only typed in a name, then if this parameter is specified, it is prepended to the specified name to result in a fully specified path to which the Output Feature Class is to be written.
 
SpatialGrid1, SpatialGrid2, SpatialGrid3
 
For illustration purposes, the proper utilization of these parameters has been demonstrated in the construction of the Output Feature Class.
 

General Flow Of Execution

 
  1. When the user loads the GPPointFileInfo tool, the GP Function checks to see if it is licensed to run. This check involves verifying that at least one satisfying Product license is available on the machine. If this condition is not satisfied, a message is displayed and the tool will not proceed further. If, however, this condition is satisfied, the tool will proceed.
  2. A GP Parameter Array is initialized with all input and output parameters.
  3. InternalValidate() is called to verify that all parameters have been successfully constructed and can be recognized/utilized as valid GP Parameters.
  4. The user specifies as much information as he knows about the underlying data via the GP Function UI, making sure to specify all required inputs/outputs and optionally specifying optional fields and relevant Environment Settings and clicks [Execute].
  5. The License Manager initializes, checking out all necessary licenses for the duration of the execution of the tool.
  6. If any errors were encountered during Internal Validation of the GP Parameter Array, the tool will not execute. If no errors were encountered, the tool will proceed.
  7. Wrapper objects for Parameter Values, Environment Settings, Cancel Tracker, and Messages Window are initialized, to simplify verification of state throughout the tool.
  8. All inputs and outputs are attempted to be initialized, using Environment Settings as necessary. If at this point, any error is encountered, an exception will be thrown, a message displayed in the Messages Window, and the application will terminate. Otherwise the tool will proceed. In the case of the Input and Output Spatial Reference objects, the former is initialized using only the input GP Parameter values and the latter is initialized using only the Environment Settings. If after constructing both the Input and Output Spatial References, it is found that one is Unknown and the other is Known, the Known will be used whenever a Spatial Reference is called for throughout the tool. If both have been specified, then the shapes written to the Output Feature Class will be represented according to the projection of the data from the Input Spatial Reference to the Output Spatial Reference.
  9. Then a collection of files is obtained from the Input Folder, according to the specified Input File Extension and Recurse Input Subfolders flag. For each file in the collection, the tool attempts to construct an Output Feature Buffer, and then insert the Feature Buffer into the Output Feature Class. If any error is encountered in the process, it will be written as a Warning to the Messages Window along with a description of the error when available. No Feature will be written for such erroneous files, but a textual log will be available in the Messages Window at the end of execution for the user to examine files that were unable to be processed. If the file was able to be processed successfully, it will be written as a Feature to the Output Feature Class, and then the next file in the collection will be examined until all files have been processed.
  10. If during the execution of the tool, say a collection of several thousand files are to be processed, and the user decides to cancel the operation, and only wants to examine the data that has been written up until to the point of cancellation, the tool can respond to the user's [Cancel] request by checking whether the [Cancel] button has been pressed before examining each file in the collection via the Cancel Tracker.
  11. Once all files have been processed, the Output Feature Cursor is flushed, and the Minimum Average Point Spacing derived output GP Parameter is populated by extracting the Min from the column of AvgPtSpc written to the Output Feature Class, using IDataStatistics and IStatisticsResults.
 

Additional Notes

 
 
 
 
 
 
 


GPPointFileInfo/ESConfigKeyword.cs Environment Settings Config Keyword Implementation
GPPointFileInfo/ESExtent.cs Environment Settings Extent Implementation
GPPointFileInfo/ESOutputCoordinateSystem.cs Environment Settings Output Coordinate System Implementation
GPPointFileInfo/ESOutputZFlag.cs Environment Settings Output Z Flag Implementation
GPPointFileInfo/ESOverwriteOutput.cs Environment Settings Overwrite Output Implementation
GPPointFileInfo/ESScratchWorkspace.cs Environment Settings Scratch Workspace Implementation
GPPointFileInfo/ESSpatialGrid1.cs Environment Settings Spatial Grid 1 Implementation
GPPointFileInfo/ESSpatialGrid2.cs Environment Settings Spatial Grid 2 Implementation
GPPointFileInfo/ESSpatialGrid3.cs Environment Settings Spatial Grid 3 Implementation
GPPointFileInfo/GPEnvironmentManager.cs Geoprocessing Environment Manager Implementation
GPPointFileInfo/GPException.cs Geoprocessing Exception Implementation
GPPointFileInfo/GPExceptionSeverity.cs Geoprocessing Exception Severity Enumeration Definition
GPPointFileInfo/GPInputCoordinateSystem.cs Input Coordinate System Geoprocessing Parameter Implementation
GPPointFileInfo/GPInputFileFormat.cs Input File Format Geoprocessing Parameter Implementation
GPPointFileInfo/GPInputFileSuffix.cs Input File Suffix Geoprocessing Parameter Implementation
GPPointFileInfo/GPInputFolder.cs Input Folder Geoprocessing Parameter Implementation
GPPointFileInfo/GPMessages.cs Geoprocessing Messages Implementation
GPPointFileInfo/GPOutputFeatureClass.cs Output Feature Class Geoprocessing Parameter Implementation
GPPointFileInfo/GPOutputGeometryDimensions.cs Output Geometry Dimensions Geoprocessing Parameter Implementation
GPPointFileInfo/GPOutputMinAvgPtSpc.cs Output Minimum Average Point Spacing Geoprocessing Parameter Implementation
GPPointFileInfo/GPPointFileInfoFunction.cs Point File Information Geoprocessing Function Implementation
GPPointFileInfo/GPFunctionFactory.cs Geoprocessing Function Factory Implementation
GPPointFileInfo/GPRecurseInputSubfolders.cs Recurse Input Subfolders Geoprocessing Parameter Implementation
GPPointFileInfo/InputFile.cs Input File Implementation
GPPointFileInfo/InputFileArray.cs Input File Array Implementation
GPPointFileInfo/Interfaces.cs Interface Definitions
GPPointFileInfo/LicensedProducts.cs Licensed Products Implementation
GPPointFileInfo/LicenseManager.cs License Manager Implementation
GPPointFileInfo/ObjectToString.cs Object To String Implementation
GPPointFileInfo/OutputFeatureBuffer.cs Output Feature Buffer Implementation
GPPointFileInfo/OutputFeatureCursor.cs Output Feature Cursor Implementation
GPPointFileInfo/OutputHasZs.cs Output Has Zs Implementation
GPPointFileInfo/ParameterValueArray.cs Parameter Value Array Implementation
GPPointFileInfo/SpatialReferenceClass.cs Spatial Reference Class Implementation
GPPointFileInfo/TrackCancel.cs Track Cancel Implementation
Download the C# files
GPPointFileInfo/ESConfigKeyword.vb Environment Settings Config Keyword Implementation
GPPointFileInfo/ESExtent.vb Environment Settings Extent Implementation
GPPointFileInfo/ESOutputCoordinateSystem.vb Environment Settings Output Coordinate System Implementation
GPPointFileInfo/ESOutputZFlag.vb Environment Settings Output Z Flag Implementation
GPPointFileInfo/ESOverwriteOutput.vb Environment Settings Overwrite Output Implementation
GPPointFileInfo/ESScratchWorkspace.vb Environment Settings Scratch Workspace Implementation
GPPointFileInfo/ESSpatialGrid1.vb Environment Settings Spatial Grid 1 Implementation
GPPointFileInfo/ESSpatialGrid2.vb Environment Settings Spatial Grid 2 Implementation
GPPointFileInfo/ESSpatialGrid3.vb Environment Settings Spatial Grid 3 Implementation
GPPointFileInfo/GPEnvironmentManager.vb Geoprocessing Environment Manager Implementation
GPPointFileInfo/GPException.vb Geoprocessing Exception Implementation
GPPointFileInfo/GPExceptionSeverity.vb Geoprocessing Exception Severity Enumeration Definition
GPPointFileInfo/GPInputCoordinateSystem.vb Input Coordinate System Geoprocessing Parameter Implementation
GPPointFileInfo/GPInputFileFormat.vb Input File Format Geoprocessing Parameter Implementation
GPPointFileInfo/GPInputFileSuffix.vb Input File Suffix Geoprocessing Parameter Implementation
GPPointFileInfo/GPInputFolder.vb Input Folder Geoprocessing Parameter Implementation
GPPointFileInfo/GPMessages.vb Geoprocessing Messages Implementation
GPPointFileInfo/GPOutputFeatureClass.vb Output Feature Class Geoprocessing Parameter Implementation
GPPointFileInfo/GPOutputGeometryDimensions.vb Output Geometry Dimensions Geoprocessing Parameter Implementation
GPPointFileInfo/GPOutputMinAvgPtSpc.vb Output Minimum Average Point Spacing Geoprocessing Parameter Implementation
GPPointFileInfo/GPPointFileInfoFunction.vb Point File Information Geoprocessing Function Implementation
GPPointFileInfo/GPFunctionFactory.vb Geoprocessing Function Factory Implementation
GPPointFileInfo/GPRecurseInputSubfolders.vb Recurse Input Subfolders Geoprocessing Parameter Implementation
GPPointFileInfo/InputFile.vb Input File Implementation
GPPointFileInfo/InputFileArray.vb Input File Array Implementation
GPPointFileInfo/Interfaces.vb Interface Definitions
GPPointFileInfo/LicensedProducts.vb Licensed Products Implementation
GPPointFileInfo/LicenseManager.vb License Manager Implementation
GPPointFileInfo/ObjectToString.vb Object To String Implementation
GPPointFileInfo/OutputFeatureBuffer.vb Output Feature Buffer Implementation
GPPointFileInfo/OutputFeatureCursor.vb Output Feature Cursor Implementation
GPPointFileInfo/OutputHasZs.vb Output Has Zs Implementation
GPPointFileInfo/ParameterValueArray.vb Parameter Value Array Implementation
GPPointFileInfo/SpatialReferenceClass.vb Spatial Reference Class Implementation
GPPointFileInfo/TrackCancel.vb Track Cancel Implementation
Download the VB.NET files

Download the files for all languages

See Also:

Getting started with geoprocessing
How to access geoprocessing tools and toolboxes
How to run a geoprocessing tool