Compute Change Raster—REST APIs | Documentation for ArcGIS Enterprise

Available with Image Analyst license.

URL:https://<rasteranalysistools-url>/ComputeChangeRaster
Version Introduced:10.9.1

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 the from and to classes 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


Parameter	Details
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 `{"itemId": <portal item id>} {“url”: <image service url>} {“uri”: <cloud raster uri or shared data path>}`
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 `{"itemId": <portal item id>} {“url”: <image service url>} {“uri”: <cloud raster uri or shared data path>}`
outputName (Required)	The name of the output image service 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 service tool can also generate new hosted image service with the given service properties. 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 `{"itemId": <portal item id>} {“url”: <image service url>} {“uri”: <cloud raster uri or shared data path>} or {"serviceProperties": {“name”: ”change_analysis”}}`
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. It can be one or multiple values. 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. It can be one or multiple values. 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"`
fromClassnameField	A field that stores class names in the inputFromRaster. The tool automatically searches for CLASSNAME field or CLASS_NAME field to use. Use this option if the input does not contain these standard field names. Syntax: A string representing the class name field in the inputFromRaster Example: `fromClassnameField="CLASSES"`
toClassnameField	A field that stores class names in the inputToRaster. The tool will automatically search for CLASSNAME field or CLASS_NAME field to use. Use this option if the input does not contain these standard field names. Syntax: A string representing the class name field in the inputToRaster Example: `toClassnameField="CLASSES"`
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 jobId to periodically review the status of the job and messages as described in Checking job status. Once the job has successfully completed, use 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"
  }
}

Accessing results

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

Access results

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

Parameter

Parameter
outputRaster	The output raster itemId and url. Example `{"url": "http://<raster analysis url>/ComputeChangeRaster/jobs/<jobId>/results/outputRaster"}` The result has properties for parameter name, data type, and value. The content of the value is always the output raster dataset’s itemId and image service url. Result `{ "paramName": "outputRaster", "dataType": "GPString", "value": { "itemId": "c267610d0feb4370bf38cc6e2c4ac261", "url": "https://<server name>/arcgis/rest/services/Hosted/<service name>/ImageServer" } }`

outputRaster

The output raster itemId and url.

Example

{"url": "http://<raster analysis url>/ComputeChangeRaster/jobs/<jobId>/results/outputRaster"}

The result has properties for parameter name, data type, and value. The content of the value is always the output raster dataset’s itemId and image service url.

Result

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

Feedback on this topic?