Creating Custom Tools with Python Scripts

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. For now, use the user interface elements provided by Esri and we'll talk about using other UI elements in the future.

1. Create a script to be used in the toolbox

Scripts for toolbox tools are very similar 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

TheFirstParameter=arcpy.GetParameterAsText(0)
 
arcpy.AddMessage("TheFirstParameter="+TheFirstParameter)

3. Create a toolbox tool from a script

1. Open ArcCatalog
2. Open "Toolboxes"
3. Right-click on "My Toolboxes" and select "New -> Toolbox"
4. 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 distribute 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.

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

1. Give the script and appropriate name and label.
2. Make sure that Store relative path names is checked or you will not be able to move your tools to a different folder and click Next
3. In the dialog that appears, browse to your script file.
4. You may want to check Show commend window when executing script at least for debugging.
5. Click Next
6. 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).
7. Click just below Data Type and select Feature Layer.
8. In the next line, add a Display Name for an Attribute and set the Data Type to Field. This is how you add a selection for an attribute column in a tool.
9. 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.
10. Add another parameter, Output Layer and select Feature Layer for the data type.
11. 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.
12. 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 (img, tif, etc.) 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
• 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 accessible 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).

ArcMap makes it easy to add help to your tools. Right click on the tool and select Properties and then the General tab. If you add text to the Description box, it will appear in the help panel next to your tool. 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):

See section 7.4 for more information on documenting tools.

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 receiving a message that you can't understand or no message at all when a problem occurs. 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 frustrations.

ArcGIS has a habit of crashing and having to have it's processes terminated when creating tools. Most users will not even know how to kill a process let along feel OK about it. They will probably 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 their own.

Version with Tkinter (optional)

The code below shows how to display debugging information using the Tkinter library. This allows more flexibility than the approach above but can crash (more on this later).

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).

Additional Resources

ArcGIS Desktop Help: Creating Custom Tools

A quick tour of creating custom tools