WWU Notes - Using ArcScripts

Scripting & ArcScripts for ArcGIS

One of the strengths of ESRI software (and of most GIS software in general), is the ability to create customized code or scripts to enable the repetition of common tasks as well as to extend the functionality of the software. Beyond simply creating scripts for their own use, a network for sharing scripts has also grown amongst GIS users and over the years the GIS community has contributed a wealth of coding to supplement the basic software. These scripts typically accomplish a specific task, using existing functionality (automating complex and/or repetitious tasks, etc.). In some cases, these scripts eventually become incorporated into the software itself (thus ESRI takes advantage of the user base to help determine what functionality needs to be addressed and possibly even the writing of the code as well…).

More recently, with the introduction of the ArcGIS ModelBuilder (a graphical scripting tool), there is also the possibility of sharing models, designed to accomplish a specific series of geoprocessing steps.

ArcScripts

ArcScripts is an online venue for sharing scripts designed to work with ESRI software. Note that many other online sources also exist for sharing GIS scripts (ESRI and otherwise). ArcScripts is, however, one of the largest and is well organized and regularly maintained.

Scripts and models can be searched by Language, Software, Keyword (subject) or combinations thereof. Given the longer history of command line ArcInfo and ArcView 3.x, the number of .aml and .ave scripts exceeds those written for ArcGIS (VB files, Pythonscripts and ModelBuilder models). This balance is already changing, however, as the ESRI community shifts to ArcGIS for their day to day as well as ‘behind the scenes’ geoprocessing needs.

Scripts located via the search tools are linked to a Script Details page (often containing information on the use and limitations of the script), with a link to a download the script. Downloads are typically zipped, and usually have some type of instructions or readme file included (in addition to the information contained on the online Script Detailspage).

Scripting Languages

Different software platforms use different programming languages. For ESRI users the more common scripting languages/tools (listed from current to older) are:

ModelBuilder Models: Models can be built in ArcMap or ArcCatalog, using ArcToolbox and the ModelBuilder. These models can combine any of the tools available from ArcToolbox as well as data sets and parameters for a series of geoprocessing steps. These models can be saved in a toolbox (a .tbx file) and shared with other users (who can insert their own data sets and/or parameters). In addition, models can be exported to a Python script for further customization. While appearing as a graphic display of tools and data, a model is actually a type of a script with a GUI (graphical user interface) for display and manipulation of the content, greatly simplifying the process of writing. See ModelBuilder usage notes below.

Python: With the release of ArcGIS 9.0, ESRI added the ability to create scripts in a variety of programming languages (Python, VBScript, Jscript, Perl). Python has been chosen (by ESRI and WWU) as the preferred language due to its ease of use. Python is an interpreted, object-oriented language. It is also platform independent (it works on UNIX and Linux as well as Windows) and is open source. See Python usage notes below.

Visual Basic (VB, VBA, VBScript): With the introduction of ArcGIS, ESRI shifted their primary software platform to Microsoft’s Component Object Model (COM). As such, the native scripting language is Visual Basic (VB). VB code can be added as a ‘macro’ or compiled as a .dll which needs to be installed via the Windows operating system. See VB usage notes below.

AVENUE: An object-oriented, application specific programming language, developed for customizing ArcView (3.x). As with .aml files, there is not a method to directly translate an .ave file to Python, VB or .aml.

AML (Arc Macro Language): this is an application specific (written specifically for command-line ArcInfo) language developed for geoprocessing and creating end-user applications, including cartographic output. AML is a 'high-level' algorithmic language. As command-line ArcInfo was one of the industry leaders for many years, a huge number of .aml files have been written. While these are not directly translatable to Python or VB, they still provide a library if ideas… Additionally, with the ArcInfo license of ArcGIS, many .aml files can be used directly within ArcGIS.For using AML files within ArcGIS see also: ArcGIS OnLine Help (webhelp.esri.com/arcgisdesktop/9.1).

Using the Different Types of Scripts for ArcGIS

The two primary scripting languages used with ArcGIS are Python and VB. In addition, users can also share models created in ModelBuilder and custom Toolboxes (.tbx files, which can optionally be stored in a geodatabase). Details on these different methods of scripting and their usage are provided below.

  1. Visual Basic files: VB files come in three types for use within ArcGIS (in ascending order of complexity):
    a. VBScript & VBA Macros
    b. VB .dll (Dynamic Link Library) files
    c. VB executables
    d. ArcGIS Extensions
  2. Python Scripts
  3. ModelBulder models


1. Visual Basic

1a. VBScript & VBA Macros: these are VBA (Visual Basic for Applications) or VBScriptfiles that can be added to an .mxd via the Tools / Macros / Visual Basic Editor menu and/or the Tools / Customize menu. Once these macros (scripts) have been added to a project they can be executed (run) from the Tools / Macros menu or from an associated icon on a toolbar, performing a series of steps. VB macros do not require administrator permissions to install, as they are contained in the .mxd, not the operating system files. Macros also have the advantage of being editable (i.e., the user can alter the code to customize the functionality). Installation of these files does require the user to understand and be able to navigate the basic VBA environment for customizing ArcGIS.

The basic steps for adding a VB script to ArcMap:

  1. From the Tools menu, choose Macros / Macros
  2. Enter a name for your new macro
  3. Choose whether to store the macro in the current .mxd (Project) or in theNormal.mxt or in All Standard Projects - if stored in the Normal.mxt it will be available anytime ArcMap is opened (note that at WWU students do not have access to creating/saving a Normal.mxt file so would want to choose the Projectoption)
  4. Click Create
  5. This should open the VB editor, with a Project - Module window open
  6. Using Copy and Paste, copy the code from the macro you wish to use into theProject - Module window - you will probably need to delete the default text (Sub... End Sub) first
  7. In the upper right hand dialog box of the Project - Module window, choose the name of the pasted module from the drop down list
  8. Save the Project (File / Save Project menu or the Save icon)
  9. Close the Visual Basic editor
  10. To run (execute) the macro
  11. Once again choose Macros / Macros from the Tools menu
  12. Choose the name of the macro you wish to run
  13. Click Run
  14. Macros can also be edited by choosing Edit
  15. To associate and run the macro with an icon:
  16. From the Tools menu, choose Customize
  17. Click the Commands tab
  18. In the Categories (left side) dialog box, scroll down and select Macros
  19. If your macro is saved in the .mxd, choose the .mxd name in the Save inbox
  20. Drag and drop the desired macro from the Commands (right side) dialog box to any toolbar
  21. The icon can now be used similar to any other icon on the toolbar
  22. The macro can be edited by right-clicking on the icon and choosing View Source


The basic steps for adding a VBScript as as UITool in ArcMap are:

  1. From the Tools menu, choose Customize
  2. Click the Commands tab
  3. In the Categories (left side) dialog box, scroll down and select UIControls
  4. In the Save in dialog box (at bottom of Customize window) choose the current .mxd or the Normal.mxt (note that at WWU students do not have access to creating/saving a Normal.mxt file so would want to choose the current .mxdoption)
  5. Click New UIControl
  6. In the New UIControl dialog box, choose UIToolControl for a Tool (orUIButtonControl for a button, etc)
  7. Click Create
  8. Close the Customize window
  9. To add the code for the Tool, right click on the tool icon and choose View Source
  10. Copy and Paste the code for the UITool into the Visual Basic Editor window(This Document) - you will probably need to delete the default text (Sub... End Sub) first
  11. Save the Project (File / Save Project menu or the Save icon)
  12. Close the Visual Basic editor
  13. Click on the tool icon to use it as usual (tools typically enable the mouse to perform new functionality...)
  14. Note that a UITool can be removed from (or relocated on) a toolbar by choosing Customize from the Tools menu and then dragging the undesired icon off of the toolbar (to anywhere else) or to a new location on a toolbar. This can only be done while the Customize window is open.
  15. See also: ArcGIS OnLine Help (webhelp.esri.com/arcgisdesktop/9.1)


1b. VB dll files: Dynamic Link Library (dll) files are typically more complex then a simple macro. These .dll's are VB (Visual Basic) files that need to be ‘loaded’ (installed) via theTools / Customize dialog box using the Add from file… button. Once the .dll has been installed, it will be available from the Command window of the Customize dialog box, and can be added to any toolbar in ArcMap or ArcCatalog. Having added the tool to a toolbar, the user can use the tool by clicking the icon as with any other tool on a toolbar.Because the .dll file needs to be installed in the Program Files of the operating system, these files typically require administrator privileges to install. Once installed, any login can add the tool to a toolbar and/or use the tool. These files are compiled and cannot be edited/customized (though the authors may choose to include the uncompiled code used to create the .dll as well). They are, however, relatively easy to install (simpler than an VBA macro).

The basic steps for installing a .dll file in ArcMap are:

  1. From the Tools menu, choose Customize
  2. Click the Add from file button at the bottom of the Customize window
  3. Browse to and select the .dll to be installed
  4. Click OK in the Added Objects dialog box
  5. Click the Commands tab in the Customize window
  6. In the Categories (left side) dialog box, scroll down and select the Category header for the installed .dll (you will need to read the help or readme file that came with the .dll to determine what/where this is)
  7. In the Save in box, choose where you wish to store this tool icon (the choices being the current .mxd or in the Normal.mxt (note that at WWU students do not have access to creating/saving a Normal.mxt file so would want to choose the current .mxd option)
  8. Drag and drop the desired command (tool) from the Commands (right side) dialog box to any toolbar
  9. Close the Customize window
  10. The icon can now be used similar to any other icon on the toolbar


1c. VB executables: These are files (sometimes including a .dll file) that need to be installed via an executable (.exe) file. As with loading .dll file from the customize dialog box, this process requires an administrator login. Installation happens outside of ArcGIS (typically, the .exe file is run from Windows Explorer). Once installed, the tool (or tools or menu) is available to all users of ArcGIS. As with .dll files, these files cannot be edited.

The basic steps for adding a .exe file are:

  1. Recommended: Close ArcMap and/or ArcCatalog if they are open
  2. Double click on the .exe file
  3. Follow installation instructions provided with the file or via the file installer dialogs


1d. ArcGIS Extensions: Technically a subcategory of VB executables, ArcGIS Extensions are typically a more complex, packaged collection of tools and/or menus. Unlike the majority of the scripts listed above (that are usually refinements and rearrangements of existing tools), Extensions typically add functionality to the basic ArcGIS toolset (e.g. the 3D Analyst extension). Extensions are installed via an .exe and as such require an administrator login. Installation happens outside of ArcGIS (typically, the .exe file is run from Windows Explorer). Once installed, the extension is available to all users of ArcGIS. These files cannot be edited.


2. Python Scripts

Python files are text files (typically with a .py extension). These can be edited using any text editor. The preferred application for editing is PythonWin (a stand alone editor for Python scripts that comes with ArcGIS), which provides syntax and coding help. The ModelBuilder can also be used to create a Python script by simply exporting a model to a script. Once exported, the script can be further refined (adding functionality not available in the ModelBuilder).

Python scripts for ArcGIS make use of the tools in ArcToolbox via a connection to ArcToolbox (the “Geoprocessor Object”). Once this relationship has been established, any tool in the Toolbox can be used in a script. These scripts can be executed from with ArcMap or ArcCatalog (Adding a script to an existing Toolbox) or from outside of ArcGIS (simply by running the script from Windows Explorer). If added to a Toolbox, the script typically will require the assigning of parameters (variable to receive input from the user at runtime). These parameters need to be properly assigned in terms of their order and data type, so that the script will run properly. Once added to a toolbox, the toolbox (a .tbx file) can be shared with other users, providing another means of sharing Python scripts (and saving the end user from the need to set parameters, etc.).

The adding and running of Python scripts does not require administrator privileges. These scripts can be edited as need be by the user.

The basic steps for adding a Python script to ArcToolbox are:

  • Optionally create a new toolbox for the script: right click on ArcToolbox and choose New Toolbox
  • Right-click on the desired toolbox in which to store the Python script and choose Add / Script
  • Enter a Name and Label for the script (these can be the same and do not need to correspond to the name of the script itself - the Label will be what is listed in the toolbox)
  • Optionally check the box to Store relative path names
  • Click Next
  • Browse to the location of the Python script to use
  • Click Next
  • Enter the Display Name(s) and Data Type(s) for any parameters required by the script (you may need to read the help or readme file that came with the script or the script itself to determine what parameters are required and what data types they use as well as any of the Parameter Properties that need to be set).
  • Click Finish
  • Double click on the Script in the toolbox to run it (which should open a dialog box prompting the user for the parameters)
  • Right-click the script in the toolbox and choose Properties to modify any of the above settings

Users wishing to learn more about writing Python scripts for ArcGIS are encouraged to refer to the following sources:


3. ModelBuilder Models

ArcGIS ModelBuilder provides a graphical interface for creating geoprocessing models. These models can use any of the tools available in ArcToolbox, and can be created in either ArcMap or ArcCatalog. Once created, these models can be shared (via a toolbox) with other users. As with a Python script, models can have parameters (variables) that users enter when running the model, allowing users to use a generic model with their own data. Models (in a toolbox) can be run by simply clicking on them (as with any other tool in ArcToolbox) or by opening the model in edit mode (right-click and choose Edit which opens the model in the ModelBuilder window). From the ModelBuilder window, models can be run via the Run icon or by choosing Run from the Modelmenu.

Models can incorporate other models or Python scripts (just as they can use any other tool in ArcToolbox). They can also be exported to either a graphic or a Python script. Exporting to a graphic provides a quick method of documenting and sharing the model. Exporting to a Python script enables further customization of the geoprocessing (e.g. the addition of conditional loops, etc. that cannot be included in a model).

Users wishing to learn more about models and using the ArcGIS ModelBuilder are encouraged to refer to the following sources: