Raster Calculator (Spatial Analyst)
Summary
Builds and executes a single Map Algebra expression using Python syntax in a calculator-like interface.
Illustration
 |
Raster Calculator tool dialog box example |
Usage
The Raster Calculator tool allows you to create and execute a Map Algebra expression that will output a raster.
Use the Layers and variables list to select the datasets and variables to use in the expression. Numerical values and mathematical operators can be added to the expression by clicking the respective buttons in the tool dialog box. A list of commonly used conditional and mathematical tools is provided, allowing you to easily add them to the expression.
Full paths to data or data existing in the specified current workspace environment setting can be entered in quotes (""). Numbers and scalars can be directly entered into an expression.
The operators in the Raster Calculator tool dialog box are:
Multiple geoprocessing tools and operations can be combined in a map algebra expression using standard Python syntax.
Caution:When typing tool names, be sure to check the tool name syntax. If the capitalization is incorrect, the expression will be invalid and fail to execute because Python is case sensitive.
An example of the general format of a Map Algebra expression using using geoprocessing tools is:
Con(IsNull("streams"), 0, "streams")
The tool supports the standard Map Algebra syntax that is used in Python scripting. The only differences are the following:
- You do not need to put the output raster name or the = sign in the expression because the output name is specified in the Output raster parameter.
- You do not need to cast input data as a Raster object when using operators.
You can easily clip a raster dataset by setting the extent environment and specifying the input raster name in the expression. When the tool is executed, the resulting raster output will be clipped based on the specified extent.
To create a raster with cells of a constant value, specify the appropriate extent and cell size environment settings and enter the numerical value into the expression.
When multiple operators are used in an expression, they are not necessarily executed in left-to-right order. The operator with the highest precedence value will be executed first. For more information on operator precedence, see operator precedence table. You can use parentheses to control the execution order.
Boolean (~, &, ^, |) operators have a higher precedence level than Relational (<, <=, >, >=, ==, !=) operators. Therefore, when Boolean operators are used in the same expression as Relational operators, the Boolean operators will be executed first. To change the order of execution, use parentheses.
When multiple Relational and/or Boolean operators are used consecutively in a single expression, in some cases it may fail to execute. To avoid this potential problem, use appropriate parentheses in the expression so that the execution order of the operators is explicitly defined. For more information, see Complex Statement Rules.
The performance of an operation may be enhanced by the deferred evaluation capabilities of Map Algebra. Deferred evaluation is an optimization technique where individual components of an expression are intelligently processed so as to minimize the creation of intermediate datasets on disk.
Only operators and tools that process on a per-cell basis can take advantage of this capability. Operators and tools that support deferred evaluation are included on the raster calculator tool itself either as a button or in the list of tools provided.
The Raster Calculator tool can be used in ModelBuilder, but keep the following points in mind:
- The syntax of the expression determines how variables are to be specified. If you select a variable from the variable list, it will be automatically added to the expression at the current cursor location. Upon model validation:
- Layer names will be enclosed in double-quote symbols ("").
Example: "inlayer"
- Long, double, or Boolean-type variables will be enclosed in percent symbols (%%). They do not need to be in quotes.
Example: %scale_factor%
- Variables representing dataset names or strings should be enclosed in both quotes and percent symbols ("%%").
For example, inraster when selected from the variable list will become "%inraster%" in the expression.
- Layer names will be enclosed in double-quote symbols ("").
- In ModelBuilder, the following variable types are valid inputs for an expression:
- String
- Boolean
- Numeric (Double and Long)
- Data (Raster dataset, raster layer, raster band, .lyr layer file)
- The Raster Calculator tool generally follows the standard connectivity behavior of models in ModelBuilder, with some exceptions resulting from the requirements of formulating a valid Map Algebra expression. These include the following:
- Variables are connected to the Raster Calculator tool when they are selected from the list of variables. All variables are automatically listed in the Variable list inside the tool.
- When a dataset or variable is used in the expression, a link between the variable and the tool will be created. If you remove the variable from the expression, the associated link between the variable and the tool will also be removed.
- If you delete the connection to a variable, the variable is not removed from the expression.
- You should not rename a variable that is connected to the tool, since the variable will not be renamed within the expression. If you do so, the expression will be invalid.
- The syntax of the expression determines how variables are to be specified. If you select a variable from the variable list, it will be automatically added to the expression at the current cursor location. Upon model validation:
Note:The Raster Calculator tool is intended for use in the ArcGIS Desktop application only as a GP tool dialog box or in ModelBuilder. It is not intended for use in scripting and is not available in the ArcPy Spatial Analyst module.
Syntax
| Parameter | Explanation | Data Type |
expression | Note: In Python, Map Algebra expressions should be created and executed with the Spatial Analyst module, which is an extension of the ArcPy Python site package. See Map Algebra in Spatial Analyst to learn about how to perform your analysis in Python. | String |
output_raster | Note: See Creating output from Map Algebra for information on producing output from Map Algebra expressions in Python. | Raster Dataset |