Summarize Raster Within

Summarize Raster Within diagram

This task summarizes the cells of a raster within the boundaries of areas defined by another dataset.

Some example applications include:

You can think of Summarize Raster Within as taking two layers, one that defines specific areas and another that defines the value at each location across the whole area, and calculate some summary statistic for all of the values that fall within each particular area. The layer that defines the areas, inputZoneLayer, is a feature or raster dataset that defines the boundaries of each of the areas (zones) for which a summary values will be calculated. The area defining the values, the inputRasterLayertoSummarize, is a raster dataset recording the value of some particular properly at each location.

The statistic can report such properties as the sum of all the values in each area, the maximum value, or the average value. The statisticType can be the calculated based on some mathematical function, the result of a sorting operation on the values, or an indication of the frequency of values.

Request URL

http://<raster analysis url>/SummarizeRasterWithin/submitJob

Request Parameters

Following is the list of parameters with syntax and details for each.

Parameter

Description

inputZoneLayer

(Required)

The layer that defines the boundaries of the areas.

Raster input

Syntax: This parameter can be specified as a Portal Item ID, a URL to a raster image service layer, or a cloud raster dataset.

Domain: Integer raster

Examples:

  • "inputZoneLayer":{"itemID": <portal item id>}
  • "inputZoneLayer":{"url": <image service layer url>}

Feature input

Syntax: This parameter can be specified as:

  • a URL to a feature service layer
  • a feature collection.

Examples:

  • "inputZoneLayer":{"url": <feature service layer url>}
  • "inputZoneLayer":{"layerDefinition": {}, "featureSet": {}}

zoneField

(Required)

A field on theinputZoneLayer that holds the values that define each zone.

It can be an integer or a string field of the zone dataset.

Domain: Integer or string field

Default: Value

Example: "zoneField": "Boundary1"

inputRasterLayertoSummarize

(Required)

Choose the raster layer you wish to summarize by the areas defined by the inputZoneLayer.

Syntax: This parameter can be specified as a Portal Item ID, a URL to a raster image service layer, or a cloud raster dataset.

Examples:

  • "inputRasterLayertoSummarize":{"itemID": <portal item id>}
  • "inputRasterLayertoSummarize":{"url": <image service layer url>}

outputName

(Required)

This is the output image service name that will be created.

Syntax: A JSON object describes the name of the output or the output raster.

You can specify the name or you create an empty service using Portal Admin Sharing API and use the return JSON object as input to this parameter.

Output name example:

"outputName":{"serviceProperties":{"name":"testrasteranalysis"}}

Output raster example:

"outputName":{"itemId": <portal item id>}
"outputName":{"url": <image service url}
"outputName":{"serviceProperties":{"name":"testrasteranalysis","serviceUrl":"http://<server name>/server/rest/services/Hosted/testrasteranalysis/ImageServer"}, "itemProperties":{"itemId":"8cfbd3ec25584d0d8f4ed23b8ff7c43b","folderId":"sdfwerfbd3ec25584d0d8f4"}}

statisticType

The statistical summary type that you wish to calculate for all of the cells within each zone of the features in the inputRasterLayertoSummarize.

Syntax: statisticType

It can be one of the following:

  • Mean — Calculates the average of all cells in the value raster that belong to the same zone as the output cell.
  • Majority — Determines the majority value of all cells in the value raster that belong to the same zone as the output cell.
  • Maximum — Determines the largest value of all cells in the value raster that belong to the same zone as the output cell.
  • Median — Finds the median value of all cells in the value raster that belong to the same zone as the output cell.
  • Mininimum — Finds the smallest value of all cells in the value raster that belong to the same zone as the output cell.
  • Minority — Determines the minority value of all cells in the value raster that belong to the same zone as the output cell.
  • Range — Finds the range of all cells in the value raster that belong to the same zone as the output cell.
  • Sum — Adds the total value of all cells in the value raster that belong to the same zone as the output cell.
  • STD — Finds the standard deviation of all cells in the value raster that belong to the same zone as the output cell.
  • Variety — Finds the variety of all cells in the value raster that belong to the same zone as the output cell.

The default choice is Mean.

If the inputRasterLayertoSummarize is floating-point type, the zonal calculations for majority, median, minority, and variety cannot be computed.

Example:

  • "statisticType": "Sum"

ignoreMissingValues

Specify whether missing values in the raster layer to summarize will influence the results of the areas they fall within.

  • Values: true | false
  • True: Within any particular area, only cells that have a value in the raster layer being summarized will be used in determining the output value for that area. Any missing or NoData cells will be ignored in the statistic calculation.
  • False: Within any particular area, if any cells in the raster layer do not have a value, it is deemed that there is insufficient information to perform statistical calculations for all the cells in that zone; therefore, the entire zone will receive the NoData value on the output raster.

Default: True

Example:

  • "ignoreMissingValues": true

context

Context contains additional settings that affect task execution.

For this tool, there are five settings.

  • Extent (extent) — a bounding box that defines the analysis area. Only those areas in the inputZoneLayer that intersect the bounding box will have the statistics calculated.
  • Output Spatial Reference (outSR) — the output raster will be projected into the output spatial reference.
  • Snap Raster (snapRaster) — the output raster will have its cells aligned with the specified snap raster.
  • Cell Size (cellSize) — the output raster will have the resolution specified by cell size
  • Mask (mask) — only cells that fall within the analysis mask will be considered in the operation.

f

The response format. The default response format is html.

Values: html | json

Response

When you submit a request, the task assigns a unique job ID for the transaction.

Syntax:

{
"jobId": "<unique job identifier>",
"jobStatus": "<job status>"
}

After the initial request is submitted you can use the jobId to periodically check the status of the job and messages as described in the topic Checking job status. Once the job has successfully completed, you use the jobId to retrive the results. To track the status, you can make a request of the following form:

http://<raster analysis url>/SummarizeRasterWithin/jobs/<jobId>

Accessing results

When the status of the job request is esriJobSucceeded, you can access the results of the analysis by making a request of the following form:

http://<raster analysis url>/jobs/<jobId>/results/rasterLayer?token=<your token>&f=json

Parameter

Description

outputRaster

The output raster itemId and url.

Example:

{"url": 
"http://<analysis url>/SummarizeRasterWithin/jobs/<jobId>/results/resultLayer"}

The result has properties for parameter name, data type, and value. The contents of value is always the output raster dataset's itemid and the image service URL. For example:

{
    "paramName": "outRaster",
    "dataType": "GPString",
    "value": {
        "itemId": "f121390b85ef419790479fc75b493efd", 
        "url": "https://<server name>/arcgis/rest/services/Hosted/<service name>/ImageServer"
    } 
}

Related topics

7/5/2017