ArcMap

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 use 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 ways. It can be run as a script tool in an ArcGIS application. 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 arcpy.env class. These properties can be used to retrieve the current values or to set them. Environments can be accessed as read/write properties from the environment class.

import arcpy

arcpy.env.workspace = "c:/data"
Example 1: Setting environment values
import arcpy

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

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

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

arcpy.env.spatialGrid1 = float(grid_index) / 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

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

if arcpy.env.cellSize < 10:
    arcpy.env.cellSize = 10
elif arcpy.env.cellSize > 20:
    arcpy.env.cellSize = 20

arcpy.HillShade_3d("island_dem", "island_shade", 300)

Using environment settings to handle scratch data

The scratchGDB and scratchFolder environments are read-only environments that provide a geodatabase and folder location that are guaranteed to exist. This means that you can reliably use a geodatabase or folder at any time without creating or managing 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)

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

The scratchFolder environment is set as follows:

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

The scratchGDB environment is set as follows:

  • If scratchWorkspace is not set, scratchGDB defaults to a geodatabase named scratch.gdb in the current user's temporary files directory.
  • If scratchWorkspace references a geodatabase, scratchGDB will be the same as 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 keep track of environment settings and to reset environments to their default states when necessary.

Used within a with statement, the EnvManager class can be used to temporarily set one or more environments. When you exit the with block, the environments will be reset to their previous values.

In the following code, the cellSize and extent environments are set only for the duration of the with statement.

import arcpy

with arcpy.EnvManager(cellSize=10, extent='-16, 25, 44, 64'):
    # Code to be executed with the environments set

Additionally, the ResetEnvironments function can be used to restore all environments to their default values, or the ClearEnvironment function can be used to reset a specific environment.

import arcpy

# Reset geoprocessing environment settings
arcpy.ResetEnvironments()

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

Related topics