Skip To Content
ArcGIS Developers
Dashboard

Compute Change Raster

Description

Compute Change Raster diagram

The ComputeChangeRaster task is used to evaluate the difference between two input rasters, and generates a change raster output service. This tool supports continuous raster data and categorical raster data. When the raster inputs are two categorical rasters, the output change raster includes an attribute table containing all the permutations of class transitions, as well as the pixel counts for all changed and unchanged classes.

License:
You must license your ArcGIS Server as an ArcGIS Image Server to use this resource.

Request parameters

ParameterDetails
inputFromRaster

(Required)

The portal item ID, image service URL, cloud raster dataset, or shared raster dataset representing the initial or earlier raster to be analyzed.

Syntax: A JSON object describing the inputFromRaster. At least one type of input must be provided in the JSON object. If multiple inputs are given, the itemId takes priority.

Example

//Image Service URL example
{"url": [<image service URL>]}

//Shared Data Path example
{"uri": [<cloud raster URI or shared data path>]}

//Item ID example
{"itemID": [<portal item id>]}
inputToRaster

(Required)

The portal item ID, image service URL, cloud raster dataset, or shared raster dataset representing the second or later raster to be analyzed.

Syntax: A JSON object describing the inputFromRaster. At least one type of input must be provided in the JSON object. If multiple inputs are given, the itemID takes priority.

Example

//Image Service URL example
{"url": [<image service URL>]}

//Shared Data Path example
{"uri": [<cloud raster URI or shared data path>]}

//Item ID example
{"itemID": [<portal item id>]}
outputName

(Required)

The output image service name that will be created.

If the image service already exists, the portal item ID or service URL can be provided and the output path of the raster dataset generated in the raster store will be used to update the existing service definition. Otherwise, a new image service will be created.

The output hosted image service is stored in the raster store and shared on the image hosting ArcGIS Image Server or the raster analysis ArcGIS Image Server, depending on your configuration.

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

Example

//New Image Service example
{"serviceProperties": {“name”: ”change_analysis”}}

//Existing Image Service URL example
{"url": [<image service URL>]}

//Existing Shared Data Path example
{"uri": [<cloud raster URI or shared data path>]}

//Existing Item ID example
{"itemID": [<portal item id>]}
computeChangeMethod

Specifies the type of calculation to perform between the two input rasters.

  • DIFFERENCE—The mathematical difference, or subtraction, between the pixel values in the rasters will be calculated. This is the default.
  • RELATIVE_DIFFERENCE—The difference in pixel values, accounting for the magnitude of the values being compared, will be calculated.
  • CATEGORICAL_DIFFERENCE—The difference between two categorical or thematic rasters will be calculated in which the output contains class transitions that occurred between the two rasters.

Syntax: String.

Example:

computeChangeMethod="CATEGORICAL_DIFFERENCE"
fromClasses

The class names from the inputFromRaster to include in the analysis, if the computeChangeMethod is set to CATEGORICAL_DIFFERENCE. If no class name is provided, all the classes in the inputFromRaster will be included.

Syntax: List of class name strings or a single string.

Example:

//Single class example
fromClasses="Forest"

//Multiple classes example
fromClasses=["Forest","Urban","Grassland"]
toClasses

The class names from the inputToRaster to include in the analysis, if the computeChangeMethod is set to CATEGORICAL_DIFFERENCE. If no class name is provided, all the classes in the inputToRaster will be included.

Syntax: List of class name strings or a single string.

Example:

//Single class example
toClasses="Urban"

//Multiple classes example
toClasses=["Agriculture","Urban","Bare"]
filterMethod

Specifies the pixels to be categorized in the output raster, if the computeChangeMethod is set to CATEGORICAL_DIFFERENCE.

  • ALL—All pixels will be categorized in the output. This is the default.
  • CHANGED_PIXELS_ONLY—Only the pixels that changed classes will be categorized in the output. All pixels that did not change categories will be grouped in a class called Other.
  • UNCHANGED_PIXELS_ONLY—Only the pixels that did not change classes will be categorized in the output. All pixels that changed categories will be grouped in a class called Other.

Syntax: String.

Example:

filterMethod="CHANGED_PIXELS_ONLY"
transitionClassColors

Specifies the color to use to symbolize the output classes, if the computeChangeMethod is set to CATEGORICAL_DIFFERENCE. When a pixel changes from one class type to another, the output pixel color represents the initial class type, the final class type, or a blend of the two.

  • AVERAGE—The color of the output class will be the average of the colors from the fromClasses (initial) and toClasses (final). This is the default.
  • FROM_COLOR—The color of the output class will match the color of the fromClasses.
  • TO_COLOR—The color of the output class will match the color of the toClasses.

Syntax: String.

Example:

transitionClassColors="AVERAGE"
context

Contains additional settings that affect task execution.

This task has the following setting:

  • Cell Size (cellSize)—The output raster will have the resolution specified by cell size.
  • Extent (extent)—A bounding box that defines the analysis area.
  • Output Spatial Reference (outSR)—The output raster will be projected into the output spatial reference.
  • Parallel Processing Factor (parallelProcessingFactor)—The specified number or percentage of processes will be used for the analysis.
  • Snap Raster (snapRaster)—The output raster will have its cells aligned with the specified snap raster.
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 Checking job status. Once the job has successfully completed, you use the jobId to retrieve the results. To track the status, you can make a request of the following form:

https://<raster analysis url>/ComputeChangeRaster/jobs/<jobId>

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>/ComputeChangeRaster/jobs/<jobId>/results/outputRaster?token=<your token>&f=json

Example usage

Below is a sample request URL for ComputeChangeRaster.

https://services.myserver.com/arcgis/rest/services/System/RasterAnalysisTools/GPServer/ComputeChangeRaster/submitJob

JSON Response example

The response returns the outputRaster output parameter, which has properties for parameter name, data type, and value. The content of value is always the output raster dataset itemId and the image service URL.

{
  "paramName": "outputRaster",
  "dataType": "GPString",
  "value": {
    "itemId": "c267610d0feb4370bf38cc6e2c4ac261", 
    "url": "https://services.myserver.com/arcgis/rest/services/Hosted/<service name>/ImageServer"
  }
}