Scope
This specification, intended for raster and 3D developers, defines the data structure, the REST API, and the applications available to work with Esri tiled elevation services.
Data Structure
LODs
Tiled elevation services represent elevation data at multiple resolutions using a pyramid structure from level 0 to level l (figure 1). Each successive level improves resolution and map scale by twice the previous level. The term resolution in this document refers to the edge length of a raster pixel in a given unit of linear measurement. Level 0 refers to the coarsest resolution x, and level l refers to finer resolution x(2l). The information about available levels and each level's corresponding resolution and scale are referred to as levels of detail LODs.
Figure 1. An Illustration of Tiled Elevation Services Structure Showing Tile Levels, Rows, and Columns
Tile Size and Origin
Tiled elevation services use a tiled structure as the logical unit for storage and access. A tile's horizontal and vertical dimensions can be measured by a fixed number of pixels (columns, rows), collectively referred to as tile size. At every LOD level l, tiles start from the same fixed location at the top left corner of a given extent, referred to as the tile origin. There can be multiple rows and columns of tiles to cover a given extent. A tile position can be identified by its level, row, and column position. For example, the tile located at level l, row r, and column c is identified as tile (l, r, c), where l, r, and c are positive integers. Tile (l, 0,0) is the first tile next to the tile origin at each level, and tile row and column numbers increase down and to the right. A characteristic of Esri services is that tiles at a specific level, including tile (l, 0,0), may not exist.
Tiling Scheme and Tile ID
Technical details in the "LODs" and "Tile Size and Origin" sections can be combined to form a tiling scheme, which defines spatial reference, origin, LODs, and tile size. Elevation services typically use an ArcGISTM Online tiling scheme based on the web Mercator (auxiliary sphere) projection (wkid: 3857). In this data structure, each tile is uniquely identified by its level, row, and column, also known as the tile ID. The tile at the coarsest resolution and that is closest to the origin is referred to as level=0, row=0, column=0. Each tile has a unique tile extent, which can be calculated using the tile scheme and the tile ID.
Tile Interpretation
There are two types of tiles: map tiles and elevation tiles. Map tiles represent rendered maps, typically in JPEG or PNG format. Elevation tiles represent elevation data and are stored as Limited Error Raster Compression (LERC) tiles (see the "Compression and Accuracy" section below).
In terms of topology, elevation tiles differ from normal map tiles in two ways:
-
When the service specifies a tile size of 2n pixels (rows/columns), elevation tiles actually contain 2n+1 pixels in each dimension.
-
Pixel values for each elevation tile are sampled with an offset of -0.5 * resolution relative to the matching map tile.
For a tile size of 4x4 pixels, these properties result in the following arrangement for a colocated map tile and elevation tile (figure 2).
Figure 2. Sample Locations of Colocated Map and Elevation Tiles
This arrangement allows the elevation samples (the pixels of the elevation tile) to be used directly as height values for the vertices of a regular-grid 3D mesh, and for the colocated map tile to be used as a texture for that mesh.
Due to the extra row and column of pixels and the offset, an elevation tile shares one row/column of samples with each of its neighboring tiles. The shared elevation samples are shown in yellow in figure 3.
Figure 3. Shared Elevation Samples of Neighboring Tiles
The benefit of this overlap is that the geometry and texture for each tile can be constructed independently, without requiring data from neighboring tiles. Figure 3 also illustrates that the geometries for two neighboring meshes form a gapless surface patch. A contiguous terrain surface of arbitrary extent is achieved by independently constructing and drawing as many tiles as is necessary to cover the extent.
For a map tile whose tile size is 2n rows by *2n\ *columns, using a 3D mesh of (2n+1)2 vertices may be excessive. A convincing result can usually be achieved with fewer vertices than pixels. To achieve this goal, the elevation samples should be taken from a lower-LOD tile. If the client already has the elevation tile data from the same level as the map tile, the elevation tile data needs to be resampled properly, as simply omitting samples can lead to aliasing artifacts. For any target number of vertices (2m+1)2 with 0 < m < n, the elevation tile at LOD l – (n – m) contains the samples that coincide with the vertex positions and can thus be used as height values without resampling (figure 4, left).
Note that while two neighboring tiles of different LODs have colocated grid cell vertices in the horizontal plane (figure 4, right), the format does not require or guarantee that the sample values from these tiles at different LODs are identical. Clients need to factor this into their mesh generation process.
Figure 4. Alignment of Elevation Samples from Tiles at Different LODs
The elevation tiles are designed for 3D clients, but they can also be used by 2D applications. When overlaying them with map tiles in 2D applications, it's important to factor in the half-pixel offset in the elevation value during both interpretation and rendering.
Compression and Accuracy
Each elevation tile is compressed using LERC, a highly effective raster data compression technology invented by Esri. It encodes data at user-specified precision together with a data mask. The compression tolerance LercError is the maximum difference between the source and the LERC decoded pixel value at any location. For elevation, a LercError of 0.1 means the maximum change in height is under 0.1 meter (or other measuring unit defined by the elevation service).
The open-source LERC implementation and details about LERC compression can be found in the GitHub repository: https://github.com/Esri/lerc. The LERC GitHub repository also contains a LERC library, which provides a standard C API (encoding and decoding) and a JavaScript API (decoding).
Deriving Tile Extent from Tile ID
Given the following notations:
Service Extent (serviceExt): {xmin, ymin, xmax, ymax}
Tile Origin (origin): {x, y}
Tile Width and Height (tileSize): {cols, rows}
Each LOD (lod): {level, resolution, scale}
Tile ID (tileId): {level, row, column}
Tile Extent (tileExt): {xmin, ymin, xmax, ymax}
Level (lod): LODs[tileID.level]
Tile extent can be derived using the following formulas:
tileExt.xmin = tileId.column * tileSize.cols * lod.resolution + origin.x;
tileExt.xmax = tileExt.xmin + tileSize.cols * lod.resolution;
tileExt.ymin = tileId.row * tileSize.rows * lod.resolution + origin.y;
tileExt.ymax = tileExt.ymin + tileSize.rows * lod.resolution;
REST API
The elevation service REST API provides two resources. The root resource advertises service information, including tile details, extent, and LODs. The tile resource provides access to tiles for a given tile level, row, and column.
Below is an excerpt from the image service REST API document. To learn more about the image service REST API, including optional parameters for requesting tiles, see the full ArcGIS® REST API documentation on image services and image tiles.
Requesting Information from the Root Resource
To request service information, simply append f=json to the service endpoint (for example, see elevation3d.arcgis.com/arcgis/rest/services/WorldElevation3D/Terrain3D/ImageServer?f=json).
The response contains the following important properties:
"currentVersion": 10.3, // elevation tiles available at ArcGIS Server 10.3 or newer
"extent" : {<extent>},//extent of the service
"singleFusedMapCache" : true,
"capabilities" : "Image, Tilemap",
"tileInfo": {
"rows" : <rows>,
"cols" : <cols>,
"dpi" : <dpi>,
"format" : "LERC",
"lercError":<lercError>, //compression tolerance
"origin" : {<point>},
"spatialReference" : {<spatialReference>},
"lods": [
{"level" : <level1>, "resolution" : <resolution1>, "scale" : <scale1> },
{"level" : <level2>, "resolution" : <resolution2>, "scale" : <scale2> },
...
]
},
//The cache type. Can be map, or elevation.
"cacheType": "Elevation",
//The denominator of the minimum suitable scale.
"minScale": <minScale>,
//The denominator of the maximum suitable scale.
"maxScale": <maxScale>
It is important to note that cacheType for elevation tiles is Elevation. This is in contrast to other Esri tiled services, such as map cache, which use Map as the cache type.
Additionally, a client should leverage the service extent property to avoid requesting tiles that fall outside the elevation service.
Requesting a Tile from the Tile Resource
To access a tile given the level, row, and column, use the following syntax:
http://<imageservice-url>/tile/<level>/<row>/<column>
For example:
http://elevation3d.arcgis.com/arcgis/rest/services/WorldElevation3D/Terrain3D/ImageServer/tile/0/0/0
Detecting Missing Tiles on Esri Tiled Basemap and Elevation Servers
Esri provides basemap tile services through ArcGIS Online at server.arcgisonline.com or, alternatively, services.arcgisonline.com. ArcGIS Online elevation tile services are available at elevation3d.arcgis.com. HTTPS is also supported.
The client application should take steps to detect missing tiles. When tiles at a specific level and location do not exist, the usual solution is to use data for the same location from the lower LOD. The process for detecting missing tiles on Esri tiled basemap and elevation servers is slightly different from the process used to detect missing tiles on standard ArcGIS Server.
ArcGIS Online basemap and terrain servers use a content delivery network (CDN) to provide fast response times regardless of the location of the consuming application. To improve CDN caching, these servers are slightly different from ArcGIS Server, especially when it comes to detecting tile locations where no data is available. ArcGIS Server uses the tile request parameter blankTile=False, which was introduced in ArcGIS 10.2. While currently functional on some of the services, the use of this parameter is strongly discouraged, as it may be discontinued at any time.
There are two recommended methods for detecting missing tiles on the ArcGIS Online basemap servers: a tilemap request and the ETag method. Use of the tilemap request provides better performance than the ETag method, since it can eliminate unnecessary requests and their associated latency.
The recommended method for detecting missing tiles uses a tilemap request, which is currently specific to the basemap and elevation tile services. It is not yet available as part of ArcGIS Server. This request is available if the service root info capabilities includes the Tilemap keyword, as shown above. The tilemap request returns a JSON structure containing tile presence information for an area of a specific level.
The tilemap request uses the following syntax:
http://<imageservice-url>/tilemap/<level>/<row>/<column>/<width>/<height>
The level, row, and column arguments select the level and the top-left tile location, while the width and height specify the size of the requested area. The response includes the following: a validity flag; a location structure with left, top, width, and height values defining the area; and a data array of size width x height, which contains a 1 if the respective tile exists or a 0 if the respective tile is missing. The data array is in row-major order.
For example, the request at services.arcgisonline.com/arcgis/rest/services/World_Imagery/MapServer/tilemap/10/0/0/8/8 returns the following:
{
"valid": true,
"location":{
"left":0,
"top":0,
"width":8,
"height":8
},
"data":[
1,1,1,1,1,1,1,1,
1,1,1,1,1,1,1,1,
1,1,1,1,1,1,1,1,
1,1,1,1,1,1,1,1,
1,1,1,1,1,1,1,1,
1,1,1,1,1,1,1,1,
1,1,1,1,1,1,1,1,
1,1,1,1,1,1,1,1]
}
The response width and height may be different from the requested dimensions, which is why the response includes the actual dimensions. The top and left coordinates will always match the requested row and column.
For example, the request at services.arcgisonline.com/arcgis/rest/services/World_Imagery/MapServer/tilemap/10/126/0/8/8
returns an adjusted response:
{
"valid":true,
"adjusted":true,
"location": {
"left":0,
"top":126,
"width":8,
"height":2
},
"data":[
1,1,1,1,1,1,1,1,
1,1,1,1,1,1,1,1]
}
When requesting a tilemap, it is recommended that the client always make requests for an 8x8 area starting at a row and column that are a multiple of 8. These types of request areas are not modified by the server. The tilemap responses are themselves cacheable and not likely to change during a session.
The second method for detecting missing tiles involves obtaining the ETag of a missing tile and making every subsequent tile request conditional, using the If-None-Match request header. The row 0, column 0 tile at level -1 is guaranteed to not exist and will return the missing tile together with its ETag value. For example, the request at services.arcgisonline.com/arcgis/rest/services/World_Imagery/MapServer/tile/-1/0/0 returns the missing tile ETag header for World_Imagery map tiles, which is currently 10i954m13i2. Any subsequent tile request that includes the request header If-None-Match: "10i954m13i2" will return a 304 Not Modified response if the requested tile is missing. The missing-tile ETag is service specific and may change from time to time, so it should be obtained or verified at the beginning of each session.
Creating and Consuming Tiled Elevation Services in ArcGIS
Tiled elevation services can be created using ArcMap™ or ArcGIS Pro. For more information, please follow the documentation listed below:
ArcMap: server.arcgis.com/en/server/latest/get-started/windows/publish-elevation-service.htm ArcGIS Pro: pro.arcgis.com/en/pro-app/help/sharing/overview/web-elevation-layer.htm
Tiled elevation services can be accessed by ArcGIS Pro 1.4, ArcGIS Maps API 3.x–4.x for JavaScript, and ArcGIS Maps SDK for Native Apps 100.0.0 for 2D and 3D mapping applications. ArcMap 10.5 can consume tiled elevation services for 2D mapping uses.