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 the 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:

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	import arcpy arcpy.env.workspace = "c:/data"
from arcpy import env	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)

Caution:

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 situation 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()

Using environment settings to handle scratch data

scratchGDB and scratchFolder are read-only environments that provide a geodatabase and folder location that are guaranteed to exist. Meaning that you can reliably use a geodatabase or folder at any time, without having to create, or manage one.

import arcpy

inputFC = arcpy.GetParameterAsText(0)
clipFC = arcpy.GetParameterAsText(1)
outputFC = arcpy.GetParameterAsText(2)

# Use scratchGDB environment to write intermediate data
#
tempData = arcpy.CreateScratchName(workspace=arcpy.env.scratchGDB)

bufferResult = arcpy.Buffer_analysis(inputFC, tempData, "50 METERS")
arcpy.Clip_analysis(clipFC, bufferResult, outputFC)

How the scratchFolder environment is set:

• If scratchWorkspace is not set, scratchFolder defaults to the current users temporary files directory.
• If scratchWorkspace references a geodatabase, scratchFolder will be the folder containing the geodatabase.
• If the scratchWorkspace is set to a folder, scratchFolder will be the same as the scratchWorkspace

How the scratchFolder environment is set:

• If scratchWorkspace is not set, scratchGDB defaults to a gdb named scratch.gdb in the current users temporary files directory.
• If the scratchWorkspace references a geodatabase, scratchGDB will be the same as the scratchWorkspace.
• If scratchWorkspace is set to a folder, scratchGDB will be set to a geodatabase named scratch.gdb in the scratchWorkspace folder.

Resetting environments

Since geoprocessing environments can significantly affect tool operation and output, it is important to be able to keep track of environment settings and to reset environments to their default states when necessary.

The ResetEnvironments function can be used to restore the default environment values, or the ClearEnvironment function can be used to reset a specific environment.

# Reset geoprocessing environment settings
arcpy.ResetEnvironments()

# Reset a specific environment setting
arcpy.ClearEnvironment("workspace")