Create Map Server Cache

Summary

Creates the tiling scheme and preparatory folders for a map or image service cache. After running this tool, run Manage Map Server Cache Tiles to add tiles to the cache.

Usage

Legacy:

Parameters have changed for this tool at version 10.1. Models and scripts written prior to 10.1 that use this tool will need to be modified to work in 10.1.
• This tool only works with ArcGIS Server map or image services.

• Only one data frame can be cached at a time. If you need maps from multiple data frames, you must create separate map services and caches for each data frame.

• Once you create the tiling scheme you cannot modify it. However, you can add or delete scales using the Manage Map Server Cache Scales tool.

• Raster data is best served with JPEG or MIXED image format. When using JPEG or MIXED with vector maps, use a high-compression quality value (such as 90) to reduce blurring of lines and text. Vector data can also be served in PNG format.

• The cache image format cannot be changed once the cache is generated. The cache must first be deleted before switching to a different format.

Syntax

CreateMapServerCache_server (input_service, service_cache_directory, tiling_scheme_type, scales_type, num_of_scales, dots_per_inch, tile_size, {predefined_tiling_scheme}, {tile_origin}, {scales}, {cache_tile_format}, {tile_compression_quality}, {storage_format})

Parameter	Explanation	Data Type
input_service	The map or image service to be cached. This is a string containing both the server and service information. To see how to construct this string, open ArcCatalog, select your service in the Catalog tree, and note the text in the Location toolbar. Then change the backslashes to forward slashes, for example, GIS Servers/arcgis on MYSERVER (admin)/USA.MapServer.	String
service_cache_directory	The parent directory for the cache. This must be a registered ArcGIS Server cache directory.	String
tiling_scheme_type	Choose to use a NEW or PREDEFINED tiling scheme. You can define a new tiling scheme with this tool or browse to a predefined tiling scheme file (.xml). A predefined scheme can be created by running the Generate Map Server Cache Tiling Scheme tool. NEW —You will define a new tiling scheme using the various other parameters in this tool to define scale levels, image format, storage format, and so on. This is the default. PREDEFINED —You will specify a tiling scheme .xml file that already exists on disk. You can create a tiling scheme file using the Generate Map Server Cache Tiling Scheme tool.	String
scales_type	Specify how you will define the scales for the tiles. STANDARD —Autogenerates the scales based on the number defined in the Number of Scales (num_of_scales in Python) parameter. It will use levels that increase or decrease by half from 1:1,000,000 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 three 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 enter any scales desired.	String
num_of_scales	The number of scale levels to create in the cache. This option is disabled if you create a custom list of scales.	Long
dots_per_inch	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_size	The width and height of the cache tiles in pixels. The default is 256 by 256. For the best balance between performance and manageability, avoid deviating from standard widths of 256 by 256 or 512 by 512. 128 x 128 —128 by 128 pixels 256 x 256 —256 by 256 pixels 512 x 512 —512 by 512 pixels 1024 x 1024 —1024 by 1024 pixels	String
predefined_tiling_scheme (Optional)	Path to a predefined tiling scheme file (usually named conf.xml).	File
tile_origin (Optional)	The origin (upper left corner) of the tiling scheme in the 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.	Point
scales (Optional)	Scale levels available for the cache. These are not represented as fractions. Instead, use 500 to represent a scale of 1:500, and so on.	Value Table
cache_tile_format (Optional)	Choose either PNG, PNG8, PNG24, PNG32, JPEG, or MIXED file format for the tiles in the cache. PNG8 is the default. PNG —Creates PNG format with varying bit depths. The bit depths are optimized according to the color variation and transparency values in a tile. 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. MIXED —Creates PNG 32 anywhere that transparency is detected (in other words, anywhere that the data frame background is visible). Creates JPEG for the remaining tiles. This keeps the average file size down while providing you with a clean overlay on top of other caches.	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. Choosing a higher value will result in a larger file size with a higher-quality image. Choosing a lower value will result in a smaller file size with a lower-quality image.	Long
storage_format (Optional)	Determines the storage format of tiles. COMPACT —Group tiles into large files called bundles. This storage format is more efficient in terms of storage and mobility. EXPLODED —Store each tile as a separate file.	String

Code sample

The following example creates the tiling scheme and preparatory folders for a map service cache using the STANDARD scale type. After executing this script, execute the Manage Map Server Cache Tiles tool to add tiles to the cache.

# Name: CreateMapServerCache.py
# Description: The following stand-alone script demonstrates how to create map
# cache tiling scheme using standard scales.
# Note: Use ManageMapServerCacheTile tool to generate cache tiles
# Requirements: os, sys, time & traceback modules


# Any line that begins with a pound sign is a comment and will not be executed
# Empty quotes take the default value.
# To accept arguments from the command line replace values of variables to
# "sys.argv[]"

# Import system modules
import arcpy
from arcpy import env
import os, sys, time, datetime, traceback, string

# Set environment settings
env.workspace = "C:/data"

# List of input variables for map service properties
connectionFile = r"C:\Users\<username>\AppData\Roaming\ESRI\Desktop10.1\ArcCatalog"
server = "arcgis on MyServer_6080 (publisher)"
serviceName = "Rainfall.MapServer"
inputService = connectionFile + "\\" + server + "\\" + serviceName
serviceCacheDirectory = "C:\\arcgisserver\\arcgiscache\\"
tilingSchemeType = "NEW"
scalesType = "STANDARD"
numOfScales = "4"
scales = ""
dotsPerInch = "96"
tileOrigin = ""
scales = ""
tileSize = "256 x 256"
cacheTileFormat = "PNG32"
tileCompressionQuality = ""
storageFormat = "COMPACT"
predefinedTilingScheme = ""


currentTime = datetime.datetime.now()
arg1 = currentTime.strftime("%H-%M")
arg2 = currentTime.strftime("%Y-%m-%d %H:%M")
file = "C:/data/report_%s.txt" % arg1

# print results of the script to a report
report = open(file,'w')

try:
    starttime = time.clock()
    result = arcpy.CreateMapServerCache_server(inputService,
                                               serviceCacheDirectory,
                                               tilingSchemeType, scalesType,
                                               numOfScales, dotsPerInch,
                                               tileSize, predefinedTilingScheme,
                                               tileOrigin, scales,
                                               cacheTileFormat,
                                               tileCompressionQuality,
                                               storageFormat)
                                              
    finishtime = time.clock()
    elapsedtime = finishtime - starttime
    
    # print messages to a file
    while result.status < 4:
        time.sleep(0.2)
    resultValue = result.getMessages()
    report.write ("completed " + str(resultValue))
    
    print "Created cache schema with 4 scales & default properties for" + \
    serviceName + " in " + str(elapsedtime) + " sec \n on " + arg2
    
except Exception, e:
    # If an error occurred, print line number and error message
    tb = sys.exc_info()[2]
    report.write("Failed at step 1 \n" "Line %i" % tb.tb_lineno)
    report.write(e.message)
    
print "Executed creation of Map server Cache schema "
report.close()

The following example creates the tiling scheme and preparatory folders for a map service cache using CUSTOM scales. After executing this script, execute the Manage Map Server Cache Tiles tool to add tiles to the cache.

# Name: CreateMapServerCache.py
# Description: The following stand-alone script demonstrates how to create map
# cache tiling scheme using Custom scales & jpg image format.

# Note: Use ManageMapServerCacheTile tool to generate cache tiles
# Requirements: os, sys, time & traceback modules


# Any line that begins with a pound sign is a comment and will not be executed
# Empty quotes take the default value.
# To accept arguments from the command line replace values of variables to
# "sys.argv[]"

# Import system modules
import arcpy
from arcpy import env
import os, sys, time, string, datetime, traceback

# Set environment settings
env.workspace = "C:/data"

# List of input variables for map service properties
connectionFile = r"C:\Users\<username>\AppData\Roaming\ESRI\Desktop10.1\ArcCatalog"
server = "arcgis on MyServer_6080 (publisher)"
serviceName = "Rainfall.MapServer"
inputService = connectionFile + "\\" + server + "\\" + serviceName
serviceCacheDirectory = "C:\\arcgisserver\\arcgiscache"
tilingSchemeType = "NEW"
scalesType = "CUSTOM"
numOfScales = "4"
dotsPerInch = "96"
tileSize = "256 x 256"
predefinedTilingScheme = ""
tileOrigin = ""
scales = "600265;350200;225400;44000"
cacheTileFormat = "JPEG"
tileCompressionQuality = "75"
storageFormat = "COMPACT"


currentTime = datetime.datetime.now()
arg1 = currentTime.strftime("%H-%M")
arg2 = currentTime.strftime("%Y-%m-%d %H:%M")
file = "C:/data/report_%s.txt" % arg1

# print results of the script to a report
report = open(file,'w')

try:
    starttime = time.clock()
    result = arcpy.CreateMapServerCache_server(inputService,
                                               serviceCacheDirectory,
                                               tilingSchemeType, scalesType,
                                               numOfScales, dotsPerInch,
                                               tileSize, predefinedTilingScheme,
                                               tileOrigin, scales, 
                                               cacheTileFormat,
                                               tileCompressionQuality,
                                               storageFormat)
    finishtime = time.clock()
    elapsedtime = finishtime - starttime

    #print messages to a file
    while result.status < 4:
        time.sleep(0.2)
    resultValue = result.getMessages()
    report.write ("completed " + str(resultValue))

    print "Created cache schema with custom scales successfully for " + \
    serviceName + " in " + str(elapsedtime) + " sec \n on " + arg2 

except Exception, e:
    # If an error occurred, print line number and error message
    tb = sys.exc_info()[2]
    report.write("Failed at step 1 \n" "Line %i" % tb.tb_lineno)
    report.write(e.message)
print "Executed creation of map server Cache schema using custom scales"

report.close()

The following example creates the tiling scheme and preparatory folders for a map service cache using a PREDEFINED tiling scheme. After executing this script, execute the Manage Map Server Cache Tiles tool to add tiles to the cache.

# Name: CreateMapServerCache.py
# Description: The following stand-alone script demonstrates how to create map
# cache tiling scheme using existing predefined schema.

# Note: Use ManageMapServerCacheTile tool to generate cache tiles
# Requirements: os, sys, time & traceback modules

# Any line that begins with a pound sign is a comment and will not be executed
# Empty quotes take the default value.
# To accept arguments from the command line replace values of variables to
# "sys.argv[]"

# Import system modules
import arcpy
from arcpy import env
import os, sys, time, datetime, traceback, string

# Set environment settings
env.workspace = "C:/data"

# List of input variables for map service properties
connectionFile = r"C:\Users\<username>\AppData\Roaming\ESRI\Desktop10.1\ArcCatalog"
server = "arcgis on MyServer_6080 (publisher)"
serviceName = "Rainfall.MapServer"
inputService = connectionFile + "\\" + server + "\\" + serviceName
serviceCacheDirectory = "C:\\arcgisserver\\directories\\arcgiscache"
tilingSchemeType = "PREDEFINED"
scalesType = ""
tileOrigin = ""
scalesType = ""
numOfScales = ""
scales = ""
dotsPerInch = "96"
tileSize = "256 x 256"
cacheTileFormat = "MIXED"
tileCompressionQuality = "75"
storageFormat = "COMPACT"
predefinedTilingScheme = "C:/data/TilingSchemes/ArcGIS_Online_Bing_Maps_Google_Maps.xml"


currentTime = datetime.datetime.now()
arg1 = currentTime.strftime("%H-%M")
arg2 = currentTime.strftime("%Y-%m-%d %H:%M")
file = "C:/data/report_%s.txt" % arg1

# print results of the script to a report
report = open(file,'w')

try:
    starttime = time.clock()
    result = arcpy.CreateMapServerCache_server (inputService,
                                                serviceCacheDirectory,
                                                tilingSchemeType, scalesType,
                                                numOfScales, dotsPerInch,
                                                tileSize, predefinedTilingScheme,
                                                tileOrigin, scales,
                                                cacheTileFormat,
                                                tileCompressionQuality,
                                                storageFormat)

    finishtime = time.clock()
    elapsedtime = finishtime - starttime

    #print messages to a file
    while result.status < 4:
        time.sleep(0.2)
    resultValue = result.getMessages()
    report.write ("completed " + str(resultValue))
    
    print "Created cache schema using predefined tiling schema for " +\
    serviceName + " in " + str(elapsedtime) + " sec \n on " + arg2 

except Exception, e:
    # If an error occurred, print line number and error message
    tb = sys.exc_info()[2]
    report.write("Failed at step 1 \n" "Line %i" % tb.tb_lineno)
    report.write(e.message)

print "Executed creation of map server Cache schema using tiling scheme"
report.close()

Environments

This tool does not use any geoprocessing environments.

Licensing information

• ArcGIS Desktop Basic: Yes
• ArcGIS Desktop Standard: Yes
• ArcGIS Desktop Advanced: Yes