Skip To Content ArcGIS for Developers Sign In Dashboard

Subset Multidimensional Raster

Description

Subset Multidimensional Raster diagram

The SubsetMultidimensionalRaster task creates a subset of a multidimensional raster by slicing data along defined variables and dimensions.

License:
As of 10.5, you must license your ArcGIS Server as an ArcGIS Image Server to use this resource.

Request parameters

ParameterDetails
inputMultidimensionalRaster

(Required)

The portal folder ID, portal item ID, image service URL, cloud raster dataset, or shared raster dataset that will be added to the image collection. At least one type of input needs to be provided in the JSON object. If multiple inputs are given, the itemId takes priority.

Syntax: A JSON object describes the input multidimensional raster.

Example

inputMultidimensionalRaster={"folderId": <portal folder id>}
inputMultidimensionalRaster={"itemIds": [<portal item id>, <portal item id>, <portal item id>]}
inputMultidimensionalRaster={"urls": [<image service url>, <image service url>, <image service url>]}
inputMultidimensionalRaster={"uris": [<cloud raster uri or shared data path>, <cloud raster uri or shared data path>]}

At least one type of input needs to be provided in the JSON object. If multiple inputs are given. The itemId takes the priority.

outputName

(Required)

The output image collection name or URL. The image service must exist before you add the images. If the hosted image service is already created, the portal item ID or service URL can be given to the service tool. The output path of the raster dataset generated in the raster store will be used to update the existing service definition. The service tool can also generate a new hosted image service with the given service properties. The output hosted image service is stored in a raster store and shared on either the Raster Analysis Image Server or Image Hosting Image Server depending on the Enterprise configuration.

Syntax: A JSON object describes the output multidimensional or multiband raster.

Note:
Set “image, metadata” as image service capabilities to make sure the output image service can be recognized as multidimensional by other raster analysis tools.

Example

outputName={"folderId": <portal folder id>}
outputName={“url”: <image service url>}
outputName={“uri”: <cloud raster uri or shared data path>}
or
outputName={"serviceProperties": {“name”:”watertemp_anomaly”, ”capabilities”: ”image, metadata”}}

At least one type of input needs to be provided in the JSON object. If multiple inputs are given. The itemId takes the priority.

variables

The variable or variables to be analyzed. If the input raster is not multidimensional, the pixel values of the multiband raster are considered the variable. If the input raster is multidimensional and no variable is specified, all variables with the selected dimension will be analyzed.

For example, to find the years in which temperature values were highest, specify temperature as the variable to be analyzed. If you do not specify any variables and you have both temperature and precipitation variables, both variables will be analyzed, and the output multidimensional raster will include both variables.

Syntax: A list containing the variables.

Example

variables=["temp","salinity"]
dimensionDefinition

Specifies the dimension interval for which the data will be analyzed.

  • ALL—The data values will be analyzed across all slices. This is the default.
  • BY_RANGES—The dimension will be sliced using a range or a list of ranges.
  • BY_ITERATION—The dimension will be sliced over a specified interval size.
  • BY_VALUE—The dimension will be sliced using a list of dimension values.

Syntax: A string representing the method.

Example

dimensionDefinition="BY_VALUE"
dimensionRanges

This slices the data based on the dimension name and the minimum and maximum values for the range. This parameter is required when the dimensionDefinition parameter is set to BY_RANGES. If dimension is StdTime, the value must be specified in a readable time format (YYYY-MM-DDTHH:MM:SS).

Syntax: a list of dictionary objects.

Example

dimensionRanges=[{“dimension”:”<dimension name>”,"minValue":"<min value>","maxValue":"<max value>"},{“dimension”:”<dimension name>”,"minValue":"<min value>","maxValue":"<max value>"}]

Example

dimensionRanges=[{"dimension":"StdTime",“minValue":"2013-05-17T00:00:00","maxValue":"2013-05-17T03:00:00"},{"dimension":"StdZ", "minValue":"-5000","maxValue":"-4000"}]
dimensionValues

This slices the data based on the dimension name and value.

This parameter is required when the dimensionDefinition parameter is set to BY_VALUE.

If dimension is StdTime, the value must be specified in a readable time format (YYYY-MM-DDTHH:MM:SS).

Syntax: a list of dictionary objects.

Example

dimensionValues=[{"dimension":"<dimension name>", "value":"<value>”},{"dimension":"<dimension name>", "value":"<value>"}]

Example

dimensionValues=[{"dimension":"StdTime", "value":"2012-01-15T03:00:00"},{"dimension":" StdZ ", "value":"-4000"}]
dimension

The dimension along which the variables will be sliced.

Syntax: A string representing the dimension name.

Example

dimension="StdTime"
startOfFirstIteration

The beginning of the first interval. This interval is used to iterate through the dataset. This parameter is required when the dimensionDefinition parameter is set to BY_ITERATION.

Syntax: a string representing the start of the first iteration.

Example

startOfFirstIteration="1990-01-01T00:00:00"
endOfFirstIteration

The end of the first interval. This interval is used to iterate through the dataset. This parameter is required when the dimensionDefinition parameter is set to BY_ITERATION.

Syntax: a string representing the end of the first iteration.

Example

endOfFirstIteration="1990-01-02T00:00:00"
iterationStep

The frequency with which the data will be sliced. This parameter is required when the dimensionDefinition parameter is set to BY_ITERATION.

Syntax: A double value.

Example

iterationStep=2
iterationUnit

Specifies the iteration unit. This parameter is required when the dimensionDefinition parameter is set to BY_ITERATION.

  • HOURS—Hours is the specified unit of time.
  • DAYS—Days is the specified unit of time.
  • WEEKS—Weeks is the specified unit of time.
  • MONTHS—Months is the specified unit of time.
  • YEARS—Years is the specified unit of time.

Syntax: A string representing the iteration unit.

Example

iterationUnit="MONTHS"
context

Contains additional settings that affect task execution. This task has the following settings:

  • 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.
  • 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.
  • Parallel Processing Factor (parallelProcessingFactor)—The specified number or percentage of processes will be used for the analysis.

f

The response format. The default response format is html.

Values: html | json

Example usage

The following is a sample request URL for SubsetMultidimensionalRaster:

https://machine.domain.com/webadaptor/rest/services/System/RasterAnalysisTools/GPServer/SubsetMultidimensionalRaster?inputMultidimensionalRasters={"itemIds": ["1780d648db3545bba8661ad98df824a4"}&outputName={"serviceProperties":{"name":"subset_op"}}&variables=["temp"]&dimensionDefinition=BY_ITERATION&dimension=StdTime&startOfFirstIteration=2013-05-17T00:00:00&endOfFirstIteration=2013-05-17T03:00:00&iterationStep=3&iterationUnit=HOURS&f=json

The following is a sample POST request for SubsetMultidimensionalRaster:

POST /webadaptor/rest/services/System/RasterAnalysisTools/GPServer/SubsetMultidimensionalRaster HTTP/1.1
Host: machine.domain.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []

inputMultidimensionalRasters={"itemIds": ["1780d648db3545bba8661ad98df824a4"}&outputName={"serviceProperties":{"name":"subset_op"}}&variables=["temp"]&dimensionDefinition=BY_ITERATION&dimension=StdTime&startOfFirstIteration=2013-05-17T00:00:00&endOfFirstIteration=2013-05-17T03:00:00&iterationStep=3&iterationUnit=HOURSf=json

Both of the above requests use the following parameters and values in their requests:

inputMultidimensionalRasters={"itemIds": ["1780d648db3545bba8661ad98df824a4"}&
outputName={"serviceProperties":{"name":"subset_op"}}&
variables=["temp"]&
dimensionDefinition=BY_ITERATION&
dimension=StdTime&
startOfFirstIteration=2013-05-17T00:00:00&
endOfFirstIteration=2013-05-17T03:00:00&
iterationStep=3&
iterationUnit=HOURS
f=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, use the jobId to retrieve the results. To track the status, you can make a request of the following form:

https://<rasterAnalysisTools-url>/SubsetMultidimensionalRaster/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:

https://<rasterAnalysisTools-url>/SubsetMultidimensionalRaster/jobs/<jobId>/results/result

JSON Response example

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

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