Creating Custom Tools with Python Scripts

In Review

Once you've created a Python script you can save it as a new toolbox function and even create a tool button for it.

Note: Python has some capabilities to create user interface elements like dialog boxes but ESRI no longer supports having developers add "extensions" to ArcGIS that have complex user interfaces that interace with their user interfaces.

1. Create a script to be used in the toolbox

Scripts for toolbox tools are very simiarl to regular Python scripts we've been created. The major difference is that you'll need to read in the parameters the user sets in the tool dialog. These are passed through "parameters". Your Python script will read the values of the parameters into variables you can use in your script. The code below will read in the first parameter show it as a message in a dialog box. Enter this code and then continue creating the tool.

import arcpy
import Tkinter
import tkMessageBox

root=Tkinter.Tk()
root.withdraw()

TheFirstParameter="Test"

if (True):
    TheFirstParameter=arcpy.GetParameterAsText(0)
 
tkMessageBox.showinfo("Parameter Info","TheFirstParameter="+TheFirstParameter)

Notice that I've put the code that calls ArcGIS inside an "if" statement. This is so I can turn it off easily when we run the script out side of ArcGIS (more on this later).

3. Create a toolbox tool from a script

Open ArcCatalog
Open "Toolboxes"
Right-click on "My Toolboxes" and select "New -> Toolbox"
This may seem strange but do not select "New -> Python Toolbox". This is a more sophisticated way to add Python scripts to ArcMap and we'll talk about them after we do the simple approach.

Note: If you want to disribute your tool, DO NOT create it under "My Toolboxes". This folder is in your "Documents and Settings" folder and may be hidden from you. You may not be able to distribute it because you won't be able to find it! Instead, create the tool under a "Folder Connection" to a folder you can easily find.

Give the new toolbox a good name
Right click on the new toolbox and select "Add->Script..."

Give the script and appropriate name and label and click "Next"
In the dialog that appears, browse to your file and click "Next"
The next dialog is for defining the parameters going into your script. Start by clicking just under "Display Name" and giving the first parameter a good name like "Input Layer". Remember that this can be either a file path or the name of a layer loaded into ArcGIS (ArcGIS will save the file to a temporary location and then load the output from a file into a new layer).
Click just below "Data Type" and select "Feature Layer".
In the next line, add a "Display Name" for an "Attribute" and give it the "Data Type" "Field". This is how you add a selection for an attribute column in a tool.
We need to let ArcMap know which layer to get the attributes from so down in "Parameter Properties" click on "Obtained from" and select "Input Layer". This links our "Input Layer" to the parameter "Attribute".
Add another parameter, "Output Layer" and select "Feature Layer" for the data type.
For the "Output Layer", we need to let ArcGIS know that this is a layer that will be saved rather than one that already exists. With the "Output Layer" selected, click on "Direction" in the "Parameter Properties" and select "Output".
For the last parameter name it something like "Distance" and then select "String" for the data type

Note: You might have considered "Double" or another numeric type for the distance. You can do this but if you take a look at the ESRI help documentation you'll see that they always have all the parameters as strings. This is not the best code practice but it does allow you to add a unit to the distance such as "100 meters".

Finish the tool and then run it and see if you receive the dialog box with the parameter you type in. Now try it for other parameters. Spend some time trying different parameters in the tool and displaying them in the message box.

4. Common Data Types

You probably noticed that there were a lot of data types available. Below is a list of the ones you may commonly use.

Feature Set - A shapefile or a feature set in a geodatabase
Raster Layer - A raster file (GRID) or a raster in a geodatabase
String - Any text string
Double - A 64 bit floating point value
Field - A column in an attribute table from a feature set
Long - A 64-bit integer (really big integer)
Date - A US formatted date string

Notice that the only integer type is "Long" and the only floating point type is "Double".

5. Sharing Tools

It's actually very easy to share simple tools in ArcGIS. Just place your Python script in a folder that is easily acessible and then create your tool in the same folder through "Folder Connections" (i.e. not "My Toolboxes). You'll want to let the user place the tool anywhere in their folder structure so check the option for using relative paths and make sure the script path only includes the name of the script file. You'll also want to make sure that your Python script only uses paths provided by the user (or by ArcGIS like the workspace).

It's very hard for others to know what you meant with your problems. Arc makes it easy to add help to your tools. Make sure you provide a nice description of what your tool does through the "Description" in properties or through an external help file. Also, give your parameters good, clear, names for what the user is to enter. You can even add parameter names that include restrictions to the parameter like:

Output path for the image (only 'png' and 'jpg' files are supported):

Make sure your Python script provides good error messages that help the user to determine what has gone wrong. You're probably already aware that there is nothing more frustrating than running a software program and recievinng a message that you can't understand or no message at all when a problem occurrs. Now it is your turn to either be the developer that everyone values or hates!

6. Testing Your Script

There are a lot of versions of ArcGIS out there and there will only be more in the future. There are also a lot of different operating systems, versions of Python, and different file formats. Make sure you test your tools on the variety of options that you think users will have and beyond! Also, document in your tool what it works with and what it does not. This will save you and your users many frustations.

ArcGIS has a habit of crashing and having to have it's processes termainated when creating tools. Most users will not even know how to kill a process let along feel ok about it. They will proably blame your tool instead of ArcGIS (even though your tool should not be able to crash ArcGIS) so you need to really test your tool even to the point of trying to break it and make sure it is as strong as possible.

Note: Developers are notoriously bad at testing programs, especially there own.

Additional Resources

ArcGIS Desktop Help: Creating Custom Tools