ArcGIS REST API

Generate DEM

Generate DEM diagram

The GenerateDEM operation is a service tool that allows you to generate DEM products from a previously adjusted image collection. It creates point clouds using adjusted image collections and interpolates the point clouds to create DEM surface products using the designated method.

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://<orthomapping service tool url>/GenerateDEM/submitJob?
imageCollection={"itemId": "1780d648db3545bba8661ad98df824a4"}&outputDEM={"serviceProperties": {"name": 
"dronedtm"}}&cellSize=5&surfaceType=DTM&matchingMethod=SGM&context={"maxObjectSize": 50,"groundSpacing": 
None,"minAngle": 10,"maxAngle": 70,"minOverlap": 0.6,"maxOmegaPhiDif": 8,"maxGSDDif": 2,
"numImagePairs": 2,"adjQualityThreshold": 0.2,"method": "TRIANGULATION","smoothingMethod": "GAUSS5x5",
"applyToOrtho": True}

Request parameters

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

ParameterDescription

imageCollection

The image collection (mosaic dataset) name or url.

The image service must exist before calling the service to generate a DEM.

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>”}

outputDEM

(Required)

This is the output digital elevation model image URL or name. 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 describes the output image collection name or URL.

Example:

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

cellSize

(Required)

The cell size of the output digital elevation model image. This is a single numeric input. Only square cell sizes are supported. The cell size unit will be the unit used by the image collection’s spatial reference.

surfaceType

(Required)

The output surface type of the digital elevation model. The following are the available choices:

  • DTM—Digital Terrain Model. The elevation is bare earth only and does not include structures above the surface.
  • DSM—Digital Surface Model. The elevation includes bare earth and features above the surface—for example, buildings, vegetation, bridges, and utility towers.

matchingMethod

(Optional)

The method used to generate 3D points. The following are the available options:

  • ETM—A feature-based stereo matching method that uses the Harris operator to detect feature points. It's recommended for DTM generation.
  • SGM— Produces more points and detail than the ETM method. It's suitable for generating a DSM for urban areas. This is more computationally intensive than the ETM method.
  • ESGM—This is an extension of the SGM method, with edge enhancement capability.

References

Heiko Hirschmuller et al., "Memory Efficient Semi-Global Matching," ISPRS Annals of the Photogrammetry, Remote Sensing and Spatial Information Sciences, Volume 1–3, (2012): 371–376.

context

(Optional)

Additional settings such as the allowed point cloud generation parameter and DEM interpolation parameter can be assigned here.

Example (Point cloud generation parameters):

{"maxObjectSize": 50,
"groundSpacing": None,
"minAngle": 10,
"maxAngle": 70,
"minOverlap": 0.6,
"maxOmegaPhiDif": 8,
"maxGSDDif": 2,
"numImagePairs": 2,
"adjQualityThreshold": 0.2,
"regenPointCloud": False
}

Where:

  • maxObjectSize—A search radius within which surface objects, such as buildings and trees, will be identified. It's the linear size in map units.
  • groundSpacing—The ground spacing, in meters, at which the 3D points are generated.
  • minAngle—The value, in degrees, that defines the minimum intersection angle the stereo pair must meet.
  • maxAngle—The value, in degrees, that defines the maximum intersection angle the stereo pair must meet
  • minOverlap—Specifies a minimum overlap threshold that is acceptable, which is a percentage of overlap between a pair of images. Image pairs with overlap areas smaller than this threshold will receive a score of 0 for this criteria and will descend in the ordered list. The range of values is from 0 to 1.
  • maxOmegaPhiDif—Specifies the maximum threshold for the Omega/Phi difference between the image pair. The Omega and Phi values for the image pair are compared, and a difference greater than this threshold will receive a score of 0 and will descend in the ordered list.
  • maxGSDDif—Specifies the maximum allowable threshold for the ground sample distance (GSD) between two images in a pair. The resolution ratio between the two images will be compared with the threshold value. Image pairs with a GSD greater than this threshold will receive a score of 0 and descend in the ordered list.
  • numImagePairs—The number of pairs used to generate 3D points.
  • adjQualityThreshold—Specifies the minimum acceptable adjustment quality. The threshold value will be compared to the quality value stored within the stereo model. Image pairs with an adjustment quality less than the specified threshold will receive a score of 0 and descend in the ordered list. The range of values for the threshold is between 0 and 1.
  • regenPointCloud—Regenerates the 3D point cloud.

Example (DEM interpolation parameters):

{"method": "TRIANGULATION",
"smoothingMethod": "GAUSS5x5",
"applyToOrtho": True,
“fillDEM”: “https://....”
}
Note:
  • The “applyToOrtho” flag can apply the generated DEM back into the mosaic dataset’s geometric function to achieve more accurate orthorectification results.
  • The “fillDEM” flag allows you to specify an elevation service URL as background elevation to fill the area when elevation model pixels cannot be interpolated from the point cloud.

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

The result will be the image service URL and item ID of the DEM.