Using environment settings in Python

Each tool has a set of parameters it uses to execute an operation. Some of these parameters are common among all tools, such as a tolerance or output location. These parameters may obtain their default values from a geoprocessing environment that all tools utilize during their operation. When a tool is executed, the current environment settings can also be used as global input parameter values. Settings such as an area of interest, the spatial reference of the output dataset, and the cell size of a new raster dataset can all be specified with geoprocessing environments.

A script can be executed in several different ways. It can be run as a script tool in an ArcGIS application, such as ArcMap. It can also be run from another script or by itself from a Python window. When a script is run inside a tool from an ArcGIS application or from another geoprocessing script, the environment settings used by the calling application or script are passed to it. These settings become the default settings used by the tool's script when it is executed. The called script may alter the settings passed to it, but those changes are only used within that script or by any other tool it may call. Changes are not passed back to the calling script or application. The environment model can best be described as cascading, where values flow down to any process that uses the geoprocessing environment.

Getting and setting environment settings

Environment settings are exposed as properties on the env class. These properties can be used to retrieve the current values or to set them. Each environment setting has a name and a label. Labels are displayed on the Environment Settings dialog box in ArcGIS. Names are used in scripts or at the command line in ArcGIS applications. Below are examples of how to use environment values:

NoteNote:

Environments can be accessed as read/write properties from the environment class, as arcpy.env.<environmentName>. Alternatively, instead of prefixing each environment name with arcpy.env, you can simplify your code by taking advantage of Python's from-import statement. This alternative has the advantage of simplifying your code and making it easier to read.

import arcpy

from arcpy import env

import arcpy

arcpy.env.workspace = "c:/data"
import arcpy
from arcpy import env

env.workspace = "c:/data"

Example 1: Setting environment values

import arcpy
from arcpy import env

# Set the workspace environment setting
#
env.workspace = "c:/St_Johns/data.gdb"

# Set the XYTolerance environment setting
#
env.XYTolerance = 2.5

# Calculate the default spatial grid index, divide in half, then
#   set the spatial grid 1 environment setting
#
result = arcpy.CalculateDefaultGridIndex_management("roads")

env.spatialGrid1 = float(result.getOutput(0)) / 2

# Clip the roads by the urban area feature class
#
arcpy.Clip_analysis("roads","urban_area","urban_roads")

Example 2: Getting and setting an environment value

import arcpy
from arcpy import env

# Check the current raster cell size and make sure it is a certain size
#   for standard output
#
env.workspace = "c:/avalon/data"

if env.cellSize < 10:
    env.cellSize = 10
elif env.cellSize > 20:
    env.cellSize = 20
    
arcpy.HillShade_3d("island_dem", "island_shade", 300)
CautionCaution:

Spelling and case count when setting environment values. Assigning a value to arcpy.env.Workspace is not the same as setting arcpy.env.workspace (note: arcpy.env.workspace is the correct form). If you encounter a case where you've set an environment but are not seeing the effect on subsequent tools, check the spelling and case.

The ListEnvironments function can be used to check proper environment names.

import arcpy
print arcpy.ListEnvironments()

Saving and loading settings

Automatic transfer of settings is only done when a script is executed by a geoprocessing tool. When a geoprocessing script calls another geoprocessing script, the environments are not automatically passed to the called script, since there is no way for the first script to know that the second script is using ArcPy.

To facilitate the transfer of environment settings from one script to another and to save settings from one session to the next, settings can be saved to a file. ArcPy can then set its environments by loading a settings file. In the first example below, a script transfers its settings to a second script by saving them to a file and passing that file name as a parameter to a second script. The second example loads an environment settings file using a name passed as a script argument.

Example 1:

# Import ArcPy site-package
#
import arcpy
from arcpy import env
import os

# Set the raster environment settings and the workspace
#
env.cellSize = 25
env.mask = "D:/St_Johns/Landcover"
env.workspace = "D:/St_Johns"

# Save the environment settings
#
envfile = arcpy.SaveSettings("c:/St_Johns/settings")

# Call Python script and pass file name as argument
#
os.system('MyHillshade.py ' + envfile)

Example 2:

# Import ArcPy site-package
#
import arcpy

# Get the input parameter value
#
envfile = arcpy.GetParameterAsText(0)

# Load the environment settings
#
arcpy.LoadSettings(envfile)

# Calculate hillshade
#
arcpy.Hillshade_3d("city_dem","city_shade",250)

Environment values can be passed between modules as arguments. Saving and loading settings between executing modules is not an efficient way of sharing values. Using a settings file is valid when used by modules that are not run together, which is the intent of the above example.

Related Topics


12/15/2011