Map Service GetMapTile method
Gets the image tile from a fused map cache
for a specific location.
GetMapTile(string
MapName, int Level, int Row, int Column, string Format)
|
Parameter |
Description |
|
MapName |
The name of the map (data frame) that contains
a fused map cache. |
|
Level |
The level of detail (scale) of the fused map
cache 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
(byte[]). The image format for the fused map cache can be discovered using
the TileImageInfo
object returned from a call to GetTileImageInfo on the map 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 map data was present
in the tile extent.
Remarks
In general, this method is used to retrieve
image tiles that have been pre-generated (cached) for a map service. All
layers in the map service have been combined (or fused) into a cache of
map images generated at different scales. 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 map service administrator, thus the values
can be arbitrary.
This method does not provide the optimum solution from retrieving cached
map images. When calling this method, the map 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 this method and remove unneeded requests to the
map service.
In general, there two options provide
the fastest way to retrieve map tiles:
Using
a simple HTTP Get request to the virtual cache directory of the Web server
Requesting
a tile from the ArcGIS Server map service tile handler
The URL for each option is deconstructed and
discussed below
Virtual
cache directory
If the a 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 |
Root URL of a virtual cache directory.
|
|
dgaerials |
Map service name. |
|
Layers |
The name of the data frame of interest in the
map service.
|
|
_alllayers |
All layers in the map. This is always the case
for single fused caches, if you have a multi-layer cache it will correspond
to the specific group layer that was cached in the multi-layer cache.
|
|
L00 |
Level of detail ID.
|
|
R0000029f |
Cache tile row in padded hexadecimal format.
|
|
C00000280.jpg |
Cache tile column in padded hexadecimal format.
|
Map
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 map service tile handler. Here’s an example of a URL
for a tile retrieved by the map service tile handler:
http://serverx.esri.com/arcgis/services/dgaerials/MapServer?mapName=Layers&format=JPEG&level=0&row=671&column=640
The URL contains the following parameters:
|
Parameter |
Description |
|
http://serverx.esri.com/arcgis/services/dgaerials/MapServer |
URL to the map service of the cache
|
|
mapName=Layers |
The name of the data frame of interest in the
map service
|
|
format=JPEG |
Image type of the cache
|
|
level=0 |
Level of detail ID
|
|
row=671 |
Cache tile row in decimal format
|
|
column=640 |
Cache tile column in decimal format
|
Replacing
the call to GetMapTile
In order to call this method 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 these objects 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 &endash; Tile origin X) / width of a tile in map units)
Row = Floor((Tile origin
Y &endash; 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 GetMapTile
or the virtual cache directory.
Examples