Exporting and importing map caches
In this topic
- How is export/import useful?
- The basics of export/import
- The importance of image format
- Choosing whether to merge or overwrite tiles
- Dealing with labels when exporting based on a feature class boundary
- Allow clients to export cache tiles
ArcGIS includes two tools that help you transfer sets of tiles from one cache to another: Export Map Server Cache and Import Map Server Cache, both in the Server Tools toolbox. They are useful for collaborative caching jobs where different organizations contribute tiles to one master cache. These tools can also be used to move subsets of tiles to machines for offline use.
How is export/import useful?
The following scenarios can help you get an idea of how the export and import tools may be useful to you.
Best-available cache
Suppose you're in charge of maintaining an imagery cache for your state. One of the counties in your state has new high-resolution imagery that it wants to contribute to your cache. You ask the county to export its cache to an external hard drive or an accessible network location where you can retrieve the exported tiles. You then import the tiles into your cache.
Collaborative cache
The best-available cache idea can be extended to multiple contributors. Imagine you're coordinating a web mapping project for an association of several local governments in your region. Each local government has its own GIS database and mapping applications; however, all have agreed on a matching cartographic style and cache tiling scheme.
In this scenario, you decide to build a collaborative cache made of tiles from each local government. Each local government exports the cache tiles that fall within its boundaries. You then import these tiles into one master cache for your web map. Members of the public who view the map on the Internet may not even recognize that the data came from different sources.
Disconnected cache
ArcMap can read tile caches from disk as if they were any other raster dataset. There is no need for a supporting map service. This allows a third scenario for the export and import tools, in which you move subsets of tiles to other machines for offline use.
Suppose you work for a large city and you've set up a cached map service with imagery. Your employees like to use this service in ArcMap to give context to their work. However, some of the employees must occasionally take laptops onto job sites where Internet access is not available.
You decide to export a copy of the cache to a shared location on the network. Your employees can now import tiles from this location onto their laptops. To avoid getting more tiles than they need, the employees create a feature class of their area of interest and use it to define the import area. When the employees run ArcMap on the laptops, they browse to the imported cache and add it to the map as they would with other raster datasets.
The basics of export/import
The workflow for export/import includes these steps:
1. Export a set of tiles
The first step is to export tiles from the source cache using Export Map Server Cache. You can optionally define an area of interest to constrain the boundaries of the export. In this way the export/import tools give you an advantage over copying and pasting tiles. With simple copy and paste, it would be difficult to spatially isolate a subset of tiles to an area of interest.
When you export based on a feature class boundary, the exported area is essentially clipped to the boundary of the feature class. Areas outside the feature class boundary on peripheral tiles are made transparent (if the source cache is PNG or MIXED) or have the background color burned in (if the source cache is JPEG).
The source destination can be a shared location on the network, a web-enabled folder, an occasionally disconnected laptop, or a piece of hard media. If the ArcGIS Server account doesn't have write access to the target destination, which might happen in cloud computing scenarios, you can check the box Copy data from server. This puts the tiles in the server output directory, from which the client then downloads them. This option is slower, but it opens up your export to a wider variety of clients.
The tiling scheme and basic cache dimension information are exported with the tiles in the conf.xml and conf.cdi files, respectively. These files are essential for clients such as ArcMap to retrieve basic information about the cache.
Finally, Export Map Server Cache allows you to convert between cache storage formats (Compact and Exploded). This is necessary because you cannot mix storage formats in a cache. Export to Compact format is recommended for large tile sets that will be copied to disconnected environments. The Compact format takes less disk space and allows for much faster copying than the Exploded format.
2. Optionally, use the tiles as a disconnected raster dataset
Once you've exported tiles, you can choose to use them directly from disk as a raster dataset in ArcMap. Just click Add Data and browse to the location where you exported the tiles. Many export/import workflows will not need this step, but it is an option. You can also stop here if you want and choose not to import the tiles anywhere else.
3. Optionally, import the tiles into another cache
The Import Map Server Cache tool brings an exported set of tiles into an existing cache. The tiling scheme of the caches must match. The image format of the caches must also match or the receiving cache must use the MIXED image format.
You can optionally define an area of interest for the import. This is useful if someone has exported an entire cache and you only want to retrieve a specific part of it.
If the ArcGIS Server account doesn't have read access to the source cache, you can check Upload data to server. This puts the tiles into the server system directory. The server then automatically moves the tiles into the server cache directory.
The importance of image format
When importing tiles from one cache to another, the cache image formats must match.
When possible, use PNG or MIXED caches in your export/import scenarios. JPEG caches do not have the ability to recognize the background color of a tile as transparent. If you must use JPEG tiles that contain a background color, be aware that the background color of those tiles will be introduced into your receiving cache. If your target cache has a different background color to begin with, the import will cause your target cache to have two background colors.
Tip:
To avoid sections of background being introduced into the cache, use PNG or MIXED format for caches that will participate in export/import scenarios.
Choosing whether to merge or overwrite tiles
When tiles are exported or imported into a cache, transparent pixels in the originating cache are ignored by default. This results in a merged or blended image in the receiving cache. For example, you can import tiles with point and line features into a basemap cache without overwriting the basemap image.
In some scenarios where a blended image would not be appropriate, you might want to force the import or export to replace all pixels in the area of interest. To do this, check the box Overwrite Tiles when you run the export or import tools. Be aware that if your originating cache contains transparent pixels, your receiving cache will also become transparent in those areas.
This choice is irrelevant with JPEG caches, which do not support transparent pixels.
Dealing with labels when exporting based on a feature class boundary
When you export tiles based on the boundary of a feature class, be aware that any labels or pieces of labels falling outside the feature class boundary will not be visible in the exported cache. This becomes a challenge in areas of high label density where labels tend to straddle or fall outside the feature class boundary.
If you know that map labels will tend to be exported based on certain geographies, you can set Maplex weighting rules that prohibit labels from overlapping the boundaries of those geographies. Click Label Weight Ranking on the Labeling toolbar to set these weights.
The image below shows how weighting rules prohibit labels from overlapping the state polygon boundary. This type of rule would ensure that no labels were clipped in half by an export performed along a state boundary.
A weight of 1000 means that a feature cannot be overlapped by a label. Notice that the weight is put on the polygon boundary and not the polygon itself. If the weight were placed on the polygon, you would see no labels within the state. If you were concerned about labels being placed outside the state boundary (as might happen along a coastline), you could create a polygon representing the inverse of the state boundary and prohibit labeling on that polygon.
You may not always be able to control the feature classes that clients use for importing tiles. However, using Maplex label weights, you can make a lot of progress toward handling labels correctly in your tile exports.
Allow clients to export cache tiles
The ArcGIS client APIs allow apps to download map tiles from the server for offline use. When you check the checkbox Allow clients to export cache tiles in the advanced caching page of the Service Editor in ArcGIS for Desktop, you enable a series of operations in the REST API that authorize these downloads to occur. To learn more about these operations, see Export Tiles.
Large downloads of tiles can negatively affect your server performance and overwhelm the storage on the client device. Use the Limit export cache setting to define the maximum number of tiles a client can request at once.
Tip:
If you're trying to decide the maximum number of tiles to allow for download, you may find it useful to determine the average area your clients would like to download, and then review the total number of tiles in that area. See Viewing cache completion status.
Exported tiles are placed in the server output directory. When you've allowed clients to export tiles, you may want to increase the maximum allowed age for files in the server output directory. The default of 10 minutes may not be long enough for the client to retrieve the tiles before they are cleaned up. See Editing a server directory in Manager for steps on how to make this edit.
Export performance
Exporting tiles using REST is performed by the caching controller service. The number of instances allocated to CachingTools, map, or image services does not affect performance. To increase the number of parallel exportTiles operations supported at any given time, you should increase the number of instances of the caching controller service. Use the formula 3*N, where N is the number of cores on a single GIS server machine in your site.