ArcGIS Server SOAP API - Image service GetImageTile method

Returns the image tile from the cache directory of the image service.

GetImageTile(int Level, int Row, int Column, string Format)

Parameter	Description
Level	The level of detail (scale) of the cached image service from which a tile will be retrieved.
Row	The row in which a tile is located. Row values start at 0 from top of each cache level.
Column	The column in which a tile is located. Column values start at 0 from the left of each cache level.
Format	The image format to retrieve from a cache. This defines the file extension to be used when retrieving the cached tile. A cache can be generated in multiple image formats.

Return Value

A byte array containing the raw image content. The image format for the cached image sevice can be discovered using the TileImageInfo object returned from a call to GetTileImageInfo() on the image service proxy. If the image tile is not available, a SOAP exception will be thrown. A tile may not be generated in situations where no image data was present in the tile extent.

Remarks

In general, GetImageTile() is used to retrieve image tiles that have been pre-generated (cached) for a image service. The cache properties such as the number and scale of levels and the physical size of image tiles in pixels can be defined by the service administrator, thus the values can be arbitrary.

GetImageTile() does not provide the optimum solution from retrieving cached images. When calling GetImageTile() the image service is responsible for retrieving the cached image, writing the byte stream and returning it to the client. If you are able to access the cached tiles directly, you can skip the call to GetImageTile() and remove unneeded requests to the image service.

In general, there are two options provide the fastest way to retrieve cached image tiles:

Using a simple HTTP Get request to the virtual cache directory of the web server
Requesting a tile from the ArcGIS Server image service tile handler

The URL for each option is deconstructed and discussed below:

Virtual cache directory

If the cache's virtual directory is exposed, you can request a tile from the web server via the public cache directory. Use the GetVirtualCacheDirectory() method to determine the virtual directory. Here's an example of a URL for a tile retrieved from the virtual cache directory:

http://serverx.esri.com/arcgiscache/dgaerials/Layers/_alllayers/L00/R0000029f/C00000280.jpg

The URL contains the following parameters:

Parameter	Description
http://serverx.esri.com/arcgiscache	The root URL of a virtual cache directory.
dgaerials	The name of the image service.
_alllayers	The folder where the tiles are stored. This is the default and cannot be modified.
L00	The ID of the detail level.
R0000029f	The cache tile row in padded hexadecimal format.
C00000280.jpg	The cache tile column in padded hexadecimal format.

Image service tile handler

If the virtual directory is not exposed, you can still request a tile from the web server, but in this case you need to use the image service tile handler. Here's an example of a URL for a tile retrieved by the image service tile handler:

http://serverx.esri.com/arcgis/services/dgaerials/ImageServer?&format=JPEG&level=0&row=671&column=640

The URL contains the following parameters:

Parameter	Description
http://serverx.esri.com/arcgis/services/dgaerials/ImageServer	The URL to the image service of the cache.
format=JPEG	The image type of the cache.
_alllayers	The folder where the tiles are stored. This is the default and cannot be modified.
level=0	The ID of the detail level.
row=671	The cache tile row in decimal format.
column=640	The cache tile column in decimal format.

Replacing the call to GetImageTile()

In order to call GetImageTile() you need to provide a value for all of the input parameters. These parameters are determined by working with the TileCacheInfo, LODInfo, and TileImageInfo objects which can be returned from a single call to the GetCacheDescriptionInfo() method.

TileCacheInfo: Contains spatial reference information, as well as the width and height of the tile in pixels.
LODInfo: Contains information about the resolution and scale for a level of detail in the cache. You can access an array of LODInfos from TileCacheInfo.
TileImageInfo: Contains information about the cache image format.

To find the specific tile that covers a point of interest requires a few calculations. Here are a few important items to consider:

Tile origin: The tiling origin is the upper-left point of the tiling scheme grid. You can get it using TileCacheInfo.TileOrigin.
Width and height of a tile in map units: Calculate this value by multiplying the tile width (TileCacheInfo.TileCols) or height (TileCacheInfo.TileRows) by the resolution (LODInfo.Resolution).
Row and column of the point of interest on the tiling grid: Columns are zero-based and increase as you move to the right from the tiling origin. Rows are also zero-based and increase as you move down from the tiling origin. For example, in the map below, if you were traveling from the tiling origin to Salt Lake City, you would have to move five tiles to the right and four tiles down. This puts Salt Lake City in Column 4, Row 3.

With these values, use the following calculations to find the tile in which a point of interest lies:

Column = Floor((Point of interest X - Tile origin X) / width of a tile in map units)
Row = Floor((Tile origin Y - Point of interest Y) / height of a tile in map units)

The example code referenced via the links below illustrate how to query cache properties and retrieve a tile via GetImageTile().

Samples

C#

/// <param name="url">service endpoint</param>
private static void RetrieveKeyProperties(string url)
{

      //connect to image server
      sampleImage_ImageServer imageSrv = new sampleImage_ImageServer();
      imageSrv.Url = url;

      //get service's key properties
      PropertySet propSet = imageSrv.GetKeyProperties();
      for (int i = 0; i < propSet.PropertyArray.Length; i++)
      {
            PropertySetProperty prop = propSet.PropertyArray[i];
            if (prop.Value is double)
                  Console.WriteLine("{0}: {1}", prop.Key, (double)prop.Value);
            if (prop.Value is string)
                  Console.WriteLine("{0}: {1}", prop.Key, (string)prop.Value);
      }

      //get first item's key properties
      PropertySet propSet1 = imageSrv.GetRasterKeyProperties(1);
      for (int i = 0; i < propSet1.PropertyArray.Length; i++)
      {
            PropertySetProperty prop = propSet.PropertyArray[i];
            if (prop.Value is double)
                  Console.WriteLine("{0}: {1}", prop.Key, (double)prop.Value);
            if (prop.Value is string)
                  Console.WriteLine("{0}: {1}", prop.Key, (string)prop.Value);
      }
}

private static void GetFirstImageTile(string url)
{

      //define image service and get cache description info
      sampleImage_ImageServer imageSrv = new sampleImage_ImageServer() { Url = url };
      CacheDescriptionInfo cacheDescInfo = imageSrv.GetCacheDescriptionInfo();
      TileCacheInfo tcInfo = cacheDescInfo.TileCacheInfo;
      LODInfo[] lodInfo = tcInfo.LODInfos;

      //request level 12
      double resolution = lodInfo[12].Resolution;
      PointN origin = tcInfo.TileOrigin as PointN;
      EnvelopeN extent = imageSrv.GetServiceInfo().Extent as EnvelopeN;
      int mintileCol = (int)((extent.XMin - origin.X) / (tcInfo.TileCols * resolution));
      int maxtileCol = (int)((extent.XMax - origin.X) / (tcInfo.TileCols * resolution));
      int mintileRow = (int)((origin.Y - extent.YMax) / (tcInfo.TileRows * resolution));
      int maxtileRow = (int)((origin.Y - extent.YMin) / (tcInfo.TileRows * resolution));

      //get first tile
      byte[] firstTile = imageSrv.GetImageTile(12, mintileRow, mintileCol);

      //show first tile or save it...
}

10/23/2013