Map Service GetMapTile method
Returns 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. 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, GetMapTile() 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.
Note, GetMapTile() does not provide the optimum solution from retrieving
cached map images. When calling GetMapTile() 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 GetMapTile() 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 GetMapTile() 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
So, 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 GetMapTile()
or the virtual cache directory.
Examples