Tutorial: Perform an analysis with raster functions

Learn how to perform a raster analysis with raster functions.

raster function analysis

In this tutorial, you use tools to build a raster function template to generate a Terrain Ruggedness Index for an area around Santa Monica, CA. A Terrain Ruggedness Index or TRI calculates the difference in elevation between the cells of a DEM. You can perform the analyses either in Map Viewer or programmatically using the ArcGIS Python, ArcGIS REST JS, and ArcGIS REST APIs.

The analysis includes:

  • Creating a new raster function template item.
  • Adding and connecting built-in raster functions.
  • Perform the analysis by running the created template in the Map Viewer.
  • Visualize the analysis results in a map.

The functions used in the raster template are:

  • Extract Bands
  • Calculator
  • Remap Properties
  • Attribute Table

Prerequisites

You need an ArcGIS Online or ArcGIS Enterprise with the proper privileges to perform raster analysis.

Steps

Create a raster function template

  1. In a web browser, Sign in to your portal with your ArcGIS account.

  2. On the main menu, click Content. Then click the New Item button.

  3. In the New item dialog select Raster function template. new item dialog

  4. Fill out the following fields:

    • Title: Santa Monica - Terrain ruggedness index
    • Tags: raster, analysis, function, template, santa monica, tutorial
    • Summary: The Terrain Ruggedness Index (TRI) is used to express the amount of elevation difference between adjacent cells of a DEM.
  5. Click Save, then click Yes in the popup to open the template item in the Raster Function Editor.

  6. You will be presented with a blank function template diagram in the Raster Function Editor tool window.

    raster function editor

An new item is created in your portal.

Add raster functions

  1. In the Raster Function Editor, from the tools in the top right corner, click Add Raster Variable.

  2. Search for the built in Extract Bands function in the left side bar, and click the Add Function Button. The Extract Bands function will be added to your diagram.

  3. To connect the variable as input to the Extract Bands function. Drag a line from the Raster Variable to the new Extract Bands function.

  4. Double click the Extract Bands function to open the function properties dialog. Click through each of the tabs and fill out the properties to match below:

    extract bands props
  5. Add the Calculator function to your diagram and connect the output of the Extract Bands function as an input to the Calculator function.

  6. Open the properties of the Calculator function, Click the parameters tab and enter the following values:

    • Raster Variables : DEM
    • Expression: SquareRoot(Abs((Square(Focal_Max(DEM,3,3)) - Square(Focal_Min(DEM,3,3)))))
    • CellSize Type: Min Of
    • Extent Type: First Of
    calculator props
  7. Add the Remap function to your diagram and connect the output of the Calculator function as an input to the Remap function.

  8. Open the properties of the Remap function, Click the parameters tab and enter the following values:

    IDMinimumMaximumOutput
    10801
    2811162
    31171613
    41622394
    52404975
    64989586
    795950007
    calculator props
  9. Add the Attribute Table function to the diagram and connect the output of the Remap Function as the input to the Attribute Table function.

  10. Open the properties of the Attribute Table function, click the parameters tab and enter the following values:

    • Table Type: Manual
      IDValueClassNameColor
      11Level#3AA900
      22Nearly Level#6EC500
      33Slightly Rugged#B2E300
      44Intermediately Rugged#FFFC00
      55Moderately Rugged#FFAA00
      66Highly Rugged#FF5200
      77Extremely Rugged#ff0100
    attribute table props
  11. You completed raster function template should should look like this:

    complete template
  12. Click the Save button to persist your edits and close the Raster Function Editor tool.

Perform the analysis

Steps to use the Map ViewerSteps to use scripting APIs
  1. On the main menu click Map to open the Map Viewer.

  2. In the right side bar, click the Analysis button to open the Analysis panel. Then click Raster Functions to display the list of built in functions.

    raster-functions
  3. At the bottom of the function list select Open Raster Function Template from the dropdown. The Browse raster function templates dialog opens.

  4. Select My Content from the dropdown and select the Santa Monica - Terrain ruggedness index template you just created.

  5. Click the Confirm confirm button at the bottom of the dialog. The template opens as a tool in the Analysis panel.

    template-tool
  6. For the input elevation Raster, select Browse layers to open the Select layer dialog.

  7. In the dropdown to the left of the search bar, select ArcGIS Online.

  8. In the search bar paste in the following Item ID:

    • c7b1872373474e9086259f5796228921.

    This is a predefined elevation layer in our area of interest. If you have your own DEM or elevation layer you can use that.

  9. Click the Select Layer button to select the layer then click Confirm and add to map*.

  10. Enter the following values for each parameter under the Result Layer heading:

    • Output Name: Santa Monica TRI Result
    • Result Type: Tiled imagery layer
  11. At the bottom of the tool, click Estimate credits to determine the how many credits the analysis will consume.

    Using the provided input imagery layer the analysis will consume 1 credit.

  12. Click the Run button to start the analysis. After a short period of time an alert should display indicating the analysis has been submitted.

  13. Click the History button in the top right of the Analysis pane to view the progress of the analysis.

  14. Once the analysis has completed, the result layer will be added to the map.

A new tiled imagery layer will be created in your portal with the analysis result.

APIs

The general steps for performing the analysis programmatically are:

  1. Implement user authentication to access the raster analysis service.
  2. Access the raster function template you created in the steps above.
  3. Access an imagery layer to use as input to the analysis.
  4. Add input parameters and make the request.
  5. Handle the results.
ArcGIS API for PythonArcGIS API for PythonArcGIS REST JS
Expand
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
# send the request
output_result = generate_raster(
    raster_function=rft_json,
    function_arguments={"Raster": {"url": dem.url}},
    output_name="Santa Monica TRI (python)",
    context={
        "extent": {
            "xmin": -13203076.3188,
            "ymin": 4035131.0044,
            "xmax": -13193005.7403,
            "ymax": 4043863.9349,
            "spatialReference": {"wkid": 102100, "latestWkid": 3857},
        }
    },
)

# handle the output
print(f"output item id: {output_result.itemid}")

Service requests

Request
HTTPHTTPcURL
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

POST https://www.arcgis.com/sharing/rest/portals/self HTTP/1.1
Content-Type: application/x-www-form-urlencoded

f=json
&token={ACCESS_TOKEN}
Response (JSON)
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

{
  "helperServices": {
    // Other parameters
    "rasterAnalytics": {
      "url": "https://<YOUR_ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer"
    },
    "geoenrichment": {
      "url": "https://geoenrich.arcgis.com/arcgis/rest/services/World/GeoenrichmentServer"
    }
    // Other parameters
  }
}

What's next?

Learn how to perform raster analysis with raster operations:

Perform an analysis using raster operations

Learn how to perform raster analysis using a raster operation


Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.