ArcGIS REST API

Create Image Collection

Create Image Collection diagram

The CreateImageCollection operation is a task that takes multiple image items as input, creates a mosaic dataset in a registered data store, and publishes it as an image service. The input raster dataset can be clipped, resampled, and reprojected based on the setting. The image upload can also be run in parallel.

Licensing

License:

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

This operation is supported at 10.6.1 and later.

Request URL

http://<raster analysis service tool url>/CreateImageCollection/submitJob?
inputRasters={“itemIds”: ["1780d648db3545bba8661ad98df824a4", "1780d648db3545bba8661ad98df824a5", 
"1780d648db3545bba8661ad98df824a6"]}& rasterType={"rasterTypeName": "UAV/UAS", "rasterTypeParameters": 
{"GPS": [[“image1.jpg”, “10”, “2”, “300”], [“image2.jpg”, “10”, “3”, “300”], [“image3.jpg”, “10”, “4”, “300”]]}}&
imageCollection={"serviceProperties": {"name": "uavcollection"}}

Request parameters

The following table lists the parameters with syntax and details for each.

ParameterDescription

inputRasters

(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 (mosaic dataset).

Syntax: A JSON object describes the input raster.

Example:

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

At least one type of input must be provided in the JSON object. If multiple inputs are given, the item IDs take priority.

At 10.6.1, the service tools are enhanced to create image collection by reference and value.

Supported cases for "byref" where the data will not be uploaded, where the input JSON object should contain the “byref” key set to True.

1. Single item:

{"url": <single cloud raster url>, “byref”: true}
{"uri": <single mosaic dataset unc path>, “byref”: true}
{"uri": <single raster dataset unc path>, “byref”: true}

When setting the input raster dataset, a relative data store path is supported such as /fileshare/a/a.tif or /cloudStore/B/b.crf through the "uri" key. The "uri" key can also be used to set an input mosaic dataset, and the mosaic dataset will not be copied to the raster store.

When setting the input raster dataset stored in the cloud storage by reference, the cloud storage bucket must be open to the public. This syntax does not support a secured bucket.

2. Multiple items:

{"uris": [<single rd unc path>, <single rd unc path>, 
<single rd unc path>], “byref”: true}
{"urls": [<single cloud raster url>, <single cloud raster url>, 
<single cloud raster url>], “byref”: true}

Supported cases for “byvalue”: If the “byref” flag is not given or is set to False, the input raster data or mosaic dataset will be uploaded or copied to the raster store.

1. Single item:

{"folderId": <folder id>}
{"itemId": <uploaded item id>}
{"url": <single cloud raster url>}
{"uri": <single md path or rd unc path>}

When a mosaic dataset is given as input, the mosaic dataset is copied to the raster store but not the source image it references. The server should also be granted access to the location of the source image. If the raster store only has a file share, the mosaic dataset is copied to the file geodatabase created in the file share. If the raster store has a database, the mosaic dataset is copied to the database.

2. Multiple items:

{"itemIds": [<uploaded item id>, <uploaded item id>, 
<uploaded item id>]}
{"uris": [<single rd unc path>, <single rd unc path>, <single rd unc path>]}
{"urls": [<single cloud raster url>, <single cloud raster url>, 
<single cloud raster url>]}

imageCollection

The output image collection (mosaic dataset) name or URL. As with Raster Analysis services, the service can be an existing multitenant service URL, or this service tool can create it.

Syntax: A JSON object supports three keys, itemId, url and uri. These keys are case sensitive.

Example:

{"itemId": “<portal item id>”}
{“url”: “<image service url>”}
{“uri”: “<cloud raster uri or shared data path>”}

rasterType

(Required)

The raster type that will be used to add images to the image collection (mosaic dataset).

Syntax: A JSON object describes the raster type, which can be used to set properties of the raster types.

Example (UAV/UAS raster type):

{“rasterTypeName”: “UAV/UAS”, 
 “rasterTypeParameters”: {
 “gps”: [[“image1.jpg”, “10”, “2”, “300”], [“image2.jpg”, “10”, “3”, “300”], [“image3.jpg”, “10”, “4”, “300”]], 
 “cameraProperties”: {"Maker": "Canon", "Model": "5D Mark II", "FocalLength": 20, "PixelSize": 10, “x0”: 0, “y0”: 0, “columns”: 4000, “rows”: 3000},
 “constantZ”: 300, 
 “isAltitudeFlightHeight”: true”,
 “dem”: {“url”: “https://….”}
}

The supported raster types keywords in JSON are UAV/UAS, Aerial, ScannedAerial, Landsat 7 ETM+, Landsat 8, Sentinel-2, ZY3-SASMAC, and ZY3-CRESDA.

Example (Landsat 8 raster type):

{“rasterTypeName”: “Landsat 8”, 
 “rasterTypeParameters”: {
 “dem”: {“url”: “https://….”}
}

Example (Raster type setting with collection properties setting):

{“rasterTypeName”: “Landsat 7”, 
 “rasterTypeParameters”: {
“dem”: {“url”: “https://….”}},
“imageCollectionProps”: {
“imageCollectionType”: “Satellite”}
}
  • The “imageCollectionType” property is important for an image collection that will be adjusted later by the orthomapping system service. Based on the image collection type, the orthomapping system service will choose a different algorithm for adjustment. Therefore, if the image collection is created by reference, the requester should set this property based on the type of images in the image collection using the following keywords: UAV/UAS, Aerial, ScannedAerial, and Satellite.
  • If imageCollectionType is not set, it defaults to “UAV/UAS”.
  • The raster type parameters that can be set through the JSON in this system service tool are the same as the supported parameters that can be set through the Auxiliary Inputs parameter of the Add Rasters To Mosaic Dataset geoprocessing tool.
  • The “dem” parameter input value follows the same syntax as raster input for the GenerateRaster service. That is, “url”, “itemId”, “uri”.

context

Contains additional settings that affect task execution.

The Create Image Collection task has the following setting:

Output Spatial Reference (outSR)—The image collection (mosaic dataset) will be projected into the output spatial reference.

Syntax:{"outSR": {spatial reference}}

The "outSR" setting is required if you want the service to create the mosaic dataset and hosted image service.

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, use the jobId to retrieve the results. To track the status, you can make a request of the following form:

http://<raster analysis service tool url>/CreateImageCollection/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>/CreateImageCollection/jobs/<jobId>/results/result?token=<your token>&f=json

ParameterDescription

result

This is the output image collection URL.

Examples:

{"url": 
"http://<raster analysis url>/CreateImageCollection/jobs/<jobId>/results/result"}

The result has properties for parameter name, data type, and value. The content of value is always the image service URL. For example:

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