Show Navigation | Hide Navigation

You are here:
Geoprocessing tool reference > Server toolbox > Caching toolset > Tools

Generate Map Server Cache (Server)
Release 9.2 Last modified November 22, 2006	Print all topics in : "Tools"

Related Topics

Generates a cache of static image tiles for an ArcGIS Server Map Service.

Usage tips

This tool only works with ArcGIS Server MapServices.
Before running this tool, configure the MapService to use as many instances as possible. This will dramatically decrease cache generation time.
Only one data frame can be cached at a time. If other data frames are needed, separate caches must be generated that associated with separate MapServices.
The tiling scheme determines how the client should reference the tiles in the cache. A new tiling scheme can be created, or an existing tiling scheme created with the Generate Map Server Cache Tiling Scheme tool can be used.
Use Fused caches for most cases. All the layers in the map are composited into single images for each specified scale level, then split into many tiles.
Use Multi-layer caches for cases where you want to toggle layers on and off.
The Number of Scales parameter is the number of different map scales the tool will create layers for in the cache.
Choosing large scale levels (> 1/100,000) will result in large creation times.
The primary benefit of employing image-compression in your cache is to reduce the size of the image tiles to improve performance over the network. Because less data is transmitted between the client and the server, it is possible to cache large, seamless raster datasets (as large as several terabytes) and serve them quickly to a client for display. An added benefit is the significantly reduced size of the cache on disk.
When using this tool to add additional levels (scales) to an existing cache, make sure to specify the same compression factor that was used in the original levels.
JPEG is best used with raster data. When used with vector data, lines and text may be blurred.
JPEG file format is not supported for multi-layer caches.
The cache tile format cannot be changed once the cache is generated. The cache must first be deleted before switching to a different file format.
For best performance of streaming cache tiles to clients choose the JPEG image format. For the best combination of performance and transparency support, choose the PNG8 image format.
The Antialiasing option smooths out the edges of lines and text, but offers little enhancement for raster images.
This tool does not accept any Environment Settings that have been specified.

Command line syntax
An overview of the Command Line window
GenerateMapServerCache_Server <server_name> <object_name> <data_frame> <out_folder> <NEW | PREDEFINED> <STANDARD| CUSTOM> <num_of_scales> <dpi> <tile_width> <tile_height> {FUSED| MULTI_LAYER} {tiling_schema} {tile_origin} {Scale; Scale...} {Layer; Layer...} {thread_count} {ANTIALIASING | NONE} {PNG8 | PNG24 | PNG32 | JPEG} {tile_compression_quality}

Parameter	Explanation	Data Type
<server_name>	The host name of the ArcGIS Server to use to generate the cache.	String
<object_name>	The name of the Map Service to use to generate the cache.	String
<data_frame>	The map from from the source map document to cache.	String
<out_folder>	The parent directory for this Map Service cache.	String
<NEW \| PREDEFINED>	Choose to use a NEW or PREDEFINED tiling scheme. A new tiling scheme can be defined in this tool, or a predefined scheme file (.xml) can be loaded. A predefined scheme can be created by running the Generate Map Server Cache Tiling Scheme GP Tool. NEW is the default.	Boolean
<STANDARD\| CUSTOM>	Set the scale level STANDARD — Auto-generates the scales based on the number defined in the "Number of Scales" field. It will use levels that increase or decrease by half from 1:1000000 and will start with a level closest to the extent of the source map document. For example, if the source map document has an extent of 1:121,000,000 and 3 scale levels are defined, the map service will create a cache with scale-levels at: 1:128,000,000; 1:64,000,000; and 1:32,000,000. This is the default. CUSTOM — Permits the cache designer to create a number of scales defined by the "Number of Scales" field at any scale level desired.	Boolean
<num_of_scales>	The number of scale levels to create in the cache.	Long
<dpi>	The dots per inch of the intended output device. If a DPI is chosen that does not match the resolution of the output device, the scale of the map tile will appear incorrect. The default value is 96.	Long
<tile_width>	The width, in pixels, of output map tiles. Small widths map improve performance of the application requesting tiles from the cache as less data will travel over the wire. However, smaller tile size results in a larger cache size and longer creation time. The default tile width is 512.	Long
<tile_height>	The height, in pixels, of output map tiles. Small heights map improve performance of the application requesting tiles from the cache as less data will travel over the wire. However, smaller tile size results in a larger cache size and longer creation time. The default tile height is 512.	Long
{FUSED\| MULTI_LAYER}	Choose to generate a FUSED or MULTI_LAYER cache: FUSED — Each tile is created as a fused image of all the layers in the source map document. MULTI_LAYER — There is one cache, but it is organized into sub-caches containing tiles from each layer in the source map document.	Boolean
{tiling_schema}	Path to a pre-defined tiling scheme.	String
{tile_origin}	Specify the origin (upper left corner) of the tiling scheme in coordinates of the spatial reference of the source map document. The extent of the source map document must be within (but does not need to coincide) with this region.	String
{Scale; Scale...}	Scales at which to cache the Map Service.	String
{Layer; Layer...}	Layers to include in the cache if MULTI_LAYER cache type is chosen.	String
{thread_count}	The number of MapServer Instances to use while generating the cache.	Long
{ANTIALIASING \| NONE}	Choose whether to use antialiasing when rendering the tiles. If ANTIALIASING is chosen, edges of lines, borders, and text will be smoothed. There is a performance cost for this option. No benefit will be gained on raster data.	Boolean
{PNG8 \| PNG24 \| PNG32 \| JPEG}	Choose either PNG8, PNG24, PNG32 or JPEG file format for the tiles in the cache. PNG24 is the default. PNG8 — a lossless, 8-bit color, image format that uses an indexed color palette and an alpha table. Each pixel stores a value (0-255) that is used to look up the color in the color-palette and the transparency in the alpha table. 8-bit PNGs are similar to GIF images and enjoy the best support for transparent background by most web browsers. PNG24 — a lossless, three-channel image format that supports large color variations (16 million colors) and has limited support for transparency. Each pixel contains three 8-bit color channels and the file header contains the single color that represents the transparent background. The color representing the transparent background color can be set in ArcMap. Versions of Internet Explorer less than version 7 do not support this type of transparency. Caches using PNG24 are significantly larger than those using PNG8 or JPEG and will take more disk space and require greater bandwidth to serve clients. PNG32 — a lossless, four-channel image format that supports large color variations (16 million colors) and transparency. Each pixel contains three 8-bit color channels and one 8-bit alpha channel that represents the level of transparency for each pixel. While the PNG32 format allows for partially transparent pixels in the range from 0 to 255, the ArcGIS Server cache generation tool only writes fully transparent (0) or fully opaque (255) values in the transparency channel. Caches using PNG32 are significantly larger than the other supported formats and will take more disk space and require greater bandwidth to serve clients. JPEG — a lossy, three-channel image format that supports large color variations (16 million colors) but does not support transparency. Each pixel contains three 8-bit color channels. Caches using JPEG provide control over output quality and size and can be more compact than the PNG format.	String
{tile_compression_quality}	Enter a value between 1 and 100 for the JPEG compression quality. The default value is 75 for JPEG tile format and zero for other formats. Compression is supported only for JPEG format. The level of compression will depend on the data, but can also be controlled by changing the compression quality. Choosing a higher value will result in less compression and a higher-quality image. Choosing a lower value will result in more compression but a lower-quality image.	Long

Data types for geoprocessing tool parameters

Command line example

GenerateMapServerCache "myServer" "myMapService" "Layers" "C:\arcgisserver\arcgisscache\" NEW STANDARD "3" "96" "512" "512" FUSED # "0 0" "8000000;4000000;2000000" "Layer1;Layer2" 2 ANTIALIASING "JPEG" "75"

Scripting syntax
About getting started with writing geoprocessing scripts
GenerateMapServerCache_Server (server_name, object_name, data_frame, out_folder, tiling_scheme_type, scales_type, num_of_scales, dpi, tile_width, tile_height, map_or_layers, tiling_schema, tile_origin, levels, layer, thread_count, Antialiasing, cache_format, tile_compression_quality)

Parameter	Explanation	Data Type
server_name (Required)	The host name of the ArcGIS Server to use to generate the cache.	String
object_name (Required)	The name of the Map Service to use to generate the cache.	String
data_frame (Required)	The map from from the source map document to cache.	String
out_folder (Required)	The parent directory for this Map Service cache.	String
tiling_scheme_type (Required)	Choose to use a NEW or PREDEFINED tiling scheme. A new tiling scheme can be defined in this tool, or a predefined scheme file (.xml) can be loaded. A predefined scheme can be created by running the Generate Map Server Cache Tiling Scheme GP Tool. NEW is the default.	Boolean
scales_type (Required)	Set the scale level STANDARD — Auto-generates the scales based on the number defined in the "Number of Scales" field. It will use levels that increase or decrease by half from 1:1000000 and will start with a level closest to the extent of the source map document. For example, if the source map document has an extent of 1:121,000,000 and 3 scale levels are defined, the map service will create a cache with scale-levels at: 1:128,000,000; 1:64,000,000; and 1:32,000,000. This is the default. CUSTOM — Permits the cache designer to create a number of scales defined by the "Number of Scales" field at any scale level desired.	Boolean
num_of_scales (Required)	The number of scale levels to create in the cache.	Long
dpi (Required)	The dots per inch of the intended output device. If a DPI is chosen that does not match the resolution of the output device, the scale of the map tile will appear incorrect. The default value is 96.	Long
tile_width (Required)	The width, in pixels, of output map tiles. Small widths map improve performance of the application requesting tiles from the cache as less data will travel over the wire. However, smaller tile size results in a larger cache size and longer creation time. The default tile width is 512.	Long
tile_height (Required)	The height, in pixels, of output map tiles. Small heights map improve performance of the application requesting tiles from the cache as less data will travel over the wire. However, smaller tile size results in a larger cache size and longer creation time. The default tile height is 512.	Long
map_or_layers (Optional)	Choose to generate a FUSED or MULTI_LAYER cache: FUSED — Each tile is created as a fused image of all the layers in the source map document. MULTI_LAYER — There is one cache, but it is organized into sub-caches containing tiles from each layer in the source map document.	Boolean
tiling_schema (Optional)	Path to a pre-defined tiling scheme.	String
tile_origin (Optional)	Specify the origin (upper left corner) of the tiling scheme in coordinates of the spatial reference of the source map document. The extent of the source map document must be within (but does not need to coincide) with this region.	String
levels (Optional)	Scales at which to cache the Map Service.	String
layer (Optional)	Layers to include in the cache if MULTI_LAYER cache type is chosen.	String
thread_count (Optional)	The number of MapServer Instances to use while generating the cache.	Long
Antialiasing (Optional)	Choose whether to use antialiasing when rendering the tiles. If ANTIALIASING is chosen, edges of lines, borders, and text will be smoothed. There is a performance cost for this option. No benefit will be gained on raster data.	Boolean
cache_format (Optional)	Choose either PNG8, PNG24, PNG32 or JPEG file format for the tiles in the cache. PNG24 is the default. PNG8 — a lossless, 8-bit color, image format that uses an indexed color palette and an alpha table. Each pixel stores a value (0-255) that is used to look up the color in the color-palette and the transparency in the alpha table. 8-bit PNGs are similar to GIF images and enjoy the best support for transparent background by most web browsers. PNG24 — a lossless, three-channel image format that supports large color variations (16 million colors) and has limited support for transparency. Each pixel contains three 8-bit color channels and the file header contains the single color that represents the transparent background. The color representing the transparent background color can be set in ArcMap. Versions of Internet Explorer less than version 7 do not support this type of transparency. Caches using PNG24 are significantly larger than those using PNG8 or JPEG and will take more disk space and require greater bandwidth to serve clients. PNG32 — a lossless, four-channel image format that supports large color variations (16 million colors) and transparency. Each pixel contains three 8-bit color channels and one 8-bit alpha channel that represents the level of transparency for each pixel. While the PNG32 format allows for partially transparent pixels in the range from 0 to 255, the ArcGIS Server cache generation tool only writes fully transparent (0) or fully opaque (255) values in the transparency channel. Caches using PNG32 are significantly larger than the other supported formats and will take more disk space and require greater bandwidth to serve clients. JPEG — a lossy, three-channel image format that supports large color variations (16 million colors) but does not support transparency. Each pixel contains three 8-bit color channels. Caches using JPEG provide control over output quality and size and can be more compact than the PNG format.	String
tile_compression_quality (Optional)	Enter a value between 1 and 100 for the JPEG compression quality. The default value is 75 for JPEG tile format and zero for other formats. Compression is supported only for JPEG format. The level of compression will depend on the data, but can also be controlled by changing the compression quality. Choosing a higher value will result in less compression and a higher-quality image. Choosing a lower value will result in more compression but a lower-quality image.	Long

Data types for geoprocessing tool parameters

Script example

# Script Name: Generate Fused Map Server Cache
# Description: Generates a fused map server cache using PNG8 image format
# Uncomment sys.argv[] lines to accept arguments from the command line.

# Import standard library modules
import sys, string, os, arcgisscripting

# Create the Geoprocessor object
gp = arcgisscripting.create()

# Set the path to the cache.
# Example: \\\\myServer\\arcgiscache\\MyServiceFolder_MyService\out_folder = "\\\\myServer\\arcgiscache\\MyServiceFolder_MyService\\"
#out_folder = sys.argv[1]

# Set the SOM server name
# Example: "mySOM"
server_name = "mySOM"
#server_name = sys.argv[2]

# Set the object_name
# Example: "MyServiceFolder/MyService"
object_name = "MyServiceFolder/MyService"
#object_name = sys.argv[3]

# Set the data frame
# Example: "Layers"
data_frame = "Layers"
#data_frame = sys.argv[4]

# Set the map cache tiling origin
# Example: "-180 90"
tile_origin = "-180 90"
#tile_origin = sys.argv[5]

# Set the scale levels for the cache.
# Example: "2000000;500000;250000"
scales = "2000000;500000;250000"
#scales = sys.argv[6]

# Set the layers to cache.
# Example: "My First Layer;My Second Layer;My Third Layer"
layers = "My First Layer;My Second Layer;My Third Layer"
#layers = sys.argv[7]

# Set number of instances to use while updating the cache
# Example: "3"
thread_count = "3"
#thread_count = sys.argv[8]

# Set cache tile image format.
# Example: "PNG8"
cache_format = "PNG8"
#layers = sys.argv[9]

# Non-argument variable declarations
tiling_scheme_type = "NEW"
tiling_schema = ""
scales_type = "STANDARD"
num_of_scales = "3"
dpi = "96"
tile_width = "512"
tile_height = "512"
map_or_layers = "FUSED"
antialiasing = "ANTIALIASING"
tile_compression_quality = "0"

try:
    print 'Starting Cache Generation'
    gp.GenerateMapServerCache(server_name, object_name, data_frame, out_folder, tiling_scheme_type,  scales_type, num_of_scales, dpi, tile_width, tile_height, map_or_layers, tiling_schema, tile_origin, scales, layers, thread_count, antialiasing, cache_format, tile_compression_quality)
    print 'Finished Cache Generation'
except:
    gp.AddMessage(gp.GetMessages(2))
    print gp.GetMessages(2)

Generate Map Server Cache (Server)

Command line example

Script example