How I Build Geoprocessing Tools: #6 Script Definition

Creating A Script Tool Definition

I recently met with a friend of mine who among many other fascinating accomplishments helped design the first successful human powered aircraft. And, every time I talk with him I am inspired to know that revisiting the same problem with a fresh look, new tools and new methods can an will eventually bring success. People were visualizing man powered flight for thousands of years, all that tried failed to the point that not even motorized flight was thought possible.

(He and I have been collaborating on improving a swimming device to make most anyone, even me, swim faster and farther than an Olympic gold medalist! If you're into scuba... Lets talk!)

Let's visualize and build a script tool. Like I mentioned in the last post a script tool has two distinct parts. The script tool and the script file. The script tool has properties and inputs and outputs that conform to the rules and standards of the ArcGIS geoprocessing framework. The second part is a text file of script instructions, the guts of the tool.

It doesn't really matter which one you create first; the tool definition or the script file. I always like to create the script tool part first since it helps me visualize the inputs and output. Once you create the script tool you can actually use it in a model before you write the script. The tool won't do anything of course, but it will look and act just the same as it will when it is finished, which gives you a great sense of accomplishment even though your work is really just starting.

Let's do it. We need to create a script tool. Tools live in toolboxes. In a previous post we created a toolbox for a Model tool we thought about creating. We can create a new toolbox or just use the one we already created or any other geoprocessing toolbox. Highlighting the toolbox of choice, right-click on the toolbox and select ADD>Script.

A Wizard walks you through the creation of the script tool properties (The wizard is actually the script tool's property sheet presented one tab at a time. After you go through it you can change any or all the values by accessing the tools property sheet). Name your script, and add a description. I always create the tool with a relative path, which makes the tool easier to distribute.

I think the idea is that you normally write your script first and then ADD it, but I don't do it that way. I like to build the script tool interface first and then I come back and add the script. The wizard will create the file if it doesn't exist. (I don't like to see the command window, so I leave the show command window option unchecked).

In this next dialog I am asked to provide my tool parameters in a grid. This is the important part. Geoprocessing tools have typed parameters. This typing allows the geoprocessing framework to provide validation and to understand how tools can and should fit together. Without this information, the geoprocessing framework will not understand how this tool relates to other tools in geoprocessing.

The order of the parameters in the grid determines the organization of the parameters in the dialog, on the command line, or in another script. The data type is very important because this determines how the tool will function in relation to other GP tools. Also critical are the individual parameter properties set in the lower grid for the highlighted parameter. In this lower grid the parameter's properties are set that determine if the value is required, is input or output, or if it has dependencies or constraints.

My first parameter will be the Input Features. Right away I have an important decision to make. What type of data will I accept as input? There is a subtle difference between a Feature Class and a Feature Layer. For most tools you should use a Feature Layer since it would include layers built from Feature Classes that have selection sets and joined tables, whereas the Feature Class choice is limited to the data in that feature class as it sits on the disk. The same is true for the distinction between a Table and a Table View.

I then can go ahead and enter my other parameters:
X', Y' and Z' offset parameters, which will be Optional inputs of the type Double without any other restrictions. The Output features will be a Required Output feature class,
(which means my script will not run unless an output path to a feature class is provided. It is up to my script to actually create the output. )

Presto, I have created a finished script tool (definition). I can double-click the tool in my toolbox and the tool's dialog box interface is generated on-the-fly based on the tools parameter properties, according to the types and order of the parameters I specified. The geoprocessing framework is now able to use my tool. It is my responsibility to make-good on my promise in the script file to create the correct output, but as far as the geoprocessing framework is concerned I have provided enough information to use the tool.

Let prove the point by adding a new model tool to our toolbox and use my MOVE tool (definition). We can drag my new custom GP Move script tool on to the ModelBuilder canvas. When I double-click the tool you see a dialog interface is generated on-the-fly for my MOVE tool based on the parameters I defined in the script tools property sheet. You will also notice the parameter types and an output bubble are automatically generated according to these properties in ModelBuilder. When I browse for input data from my tool the tool automatically filters the data for valid inputs. I can actually populate the parameters for the tool and see the colored validation symbology of ModelBuilder functioning on my unfinished custom Move tool. Granted it won't do anything if I run it, but we're making progress!

I want to reflect a little on what just happened. The entire user interface (UI) for my tool was created on-the-fly based on properties I entered into the script tool property sheet. This tool was integrated into the geoprocessing framework automatically. All validation for the inputs and outputs were done for me automatically. ModelBuilder is awesome and we'll see lots more of it before this is all done, but let's give the designers of GP scripting some credit, what I just did was pretty cool!

Continue to Part 7