Create Map Server Cache (Server)

Summary

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

Usage

Syntax

CreateMapServerCache_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}, {Antialiasing}, {cache_format}, {tile_compression_quality}, {storage_format}, use_local_cache_dir)
ParameterExplanationData Type
server_name

The ArcGIS Server machine hosting the service to be cached.

String
object_name

The map service to be cached.

String
data_frame

The map data frame to be cached.

String
out_folder

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.

  • NEWYou 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.
  • PREDEFINEDYou will specify a tiling scheme .xml file that already exists on disk. You can create a tiling scheme file using Generate Map Server Cache Tiling Scheme.
String
scales_type

Specify how you will define the scales for the tiles.

  • STANDARDAuto-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.
  • CUSTOMPermits 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
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 of the cache tiles in pixels. The default is 256. For the best balance between performance and manageability, avoid deviating from standard widths of 256 or 512.

Long
tile_height

The height of the cache tiles in pixels. The default is 256. For the best balance between performance and manageability, avoid deviating from standard widths of 256 or 512.

Long
map_or_layers
(Optional)

Choose to generate a FUSED or MULTI_LAYER cache:

  • FUSED Choose this option if you want to create each tile as a fused image of all the layers in the source map document. This is the most efficient method of caching your map and is the default option. Since all layers are fused into one image, client applications of this service cannot turn individual layers on or off. If you need to toggle a layer's visibility you must separate it into its own service and cache.
  • MULTI_LAYERChoose this option if you want to organize tiles into sub-caches, each depicting a layer in the source map document. This method of caching allows client applications of this service to turn individual layers on or off. However, a larger number of tiles will be created and client will need to do the work of retrieving and overlaying the separate images. This option should be avoided for caches that will be consumed in Web clients.
String
tiling_schema
(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
levels
[levels,...]
(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.

String
Layer
[Layer,...]
(Optional)

Layers to include in the cache if MULTI_LAYER cache type is chosen.

String
Antialiasing
(Optional)

Specifies 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. The performance cost is greater when using MXD-based map services (as opposed to MSD-based map services that have antialiasing defined in the MSD file). Antialiasing provides no benefit with raster imagery.

If the source for your map service is an MSD file and you defined antialiasing within the MSD, antialiasing will be applied in your cache whether or not you choose the option in this tool.

  • NONEAntialiasing will not be applied. This is the default.
  • ANTIALIASINGAntialiasing will be applied.
Boolean
cache_format
(Optional)

Choose either PNG8, PNG24, PNG32, JPEG, or MIXED file format for the tiles in the cache. PNG8 is the default.

  • PNG8A 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.
  • PNG24A 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.
  • PNG32A 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.
  • JPEGA 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.
  • MIXEDCreates 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)

Choose whether to group your tiles into large .bundle files using "Compact" storage format, instead of storing each tile as a separate file using "Exploded" format. Compact storage format is more efficient in terms of storage and mobility.

String
use_local_cache_dir

Choose whether bundle files should be written into a local directory on the server when creating a compact cache, instead of being written directly into the shared cache directory. If you choose this option, the bundle files will be copied into the shared cache directory as they are completed. This option improves performance when multiple machines are working on the caching job.

  • TRUETiles stored in bundles are written into a local directory, then copied into the shared cache directory as bundles are completed. This is the default when the storage format is Compact.
  • FALSETiles are written directly into the shared cache directory. This is the only valid option when the storage format is Exploded.
Boolean

Code Sample

This example creates a map cache using the "standard" scale type.

# CreateMapServerCache example (stand-alone script)

# Name: CreateMapServerCache.py
# Description: The following stand-alone script demonstrates how to create map
#               using Custom scales & jpg image format with Antialiasing feature turned on
# Requirements: os, sys, time & traceback modules
# Author: ESRI

# 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
server = "MyServer"
service = "Rainfall"
dataFrame = "" 
cacheDir = "C:\\arcgisserver\\arcgiscache\\"
tilingScheme = "NEW"
scalesType = "CUSTOM"
extents = ""
tileOrigin = ""
scales = "4"
dpi = "96"
scaleValues = "600265;350200;225400;44000"
tileWidth = "256"
tileHeight = "256"
cacheType = "FUSED"
inputLayers = ""
pathToXML = ""
antialiasing = "ANTIALIASING"
tileFormat = "JPEG"
tileCompressionQuality = "75"
storageFormat = "Compact"
useLocalCacheDir = "True"

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(server, service, dataFrame, cacheDir,
                                      tilingScheme, scalesType, scales, dpi,
                                      tileWidth, tileHeight, cacheType,
                                      pathToXml, tileOrigin, scaleValues,
                                      inputLayers, antialiasing, tileFormat,
                                      tileCompressionQuality,
                                      storageFormat, useLocalCacheDir)
    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 "
    + service + " 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()

This example creates a map cache using "custom" scales.

# CreateMapServerCache example (stand-alone script)

# Name: CreateMapServerCache.py
# Description: The following stand-alone script demonstrates how to create map
#               using Custom scales & jpg image format with Antialiasing feature turned on
# Requirements: os, sys, time & traceback modules
# Author: ESRI

# 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
server = "MyServer"
service = "Rainfall"
dataFrame = "" 
cacheDir = "C:\\arcgisserver\\arcgiscache\\"
tilingScheme = "NEW"
scalesType = "CUSTOM"
extents = ""
tileOrigin = ""
scales = "4"
dpi = "96"
scaleValues = "600265;350200;225400;44000"
tileWidth = "256"
tileHeight = "256"
cacheType = "FUSED"
inputLayers = ""
pathToXML = ""
antialiasing = "ANTIALIASING"
tileFormat = "JPEG"
tileCompressionQuality = "75"
storageFormat = "Compact"
useLocalCacheDir = "True"

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(server, service, dataFrame, cacheDir,
                                      tilingScheme, scalesType, scales, dpi,
                                      tileWidth, tileHeight, cacheType,
                                      pathToXml, tileOrigin, scaleValues,
                                      inputLayers, antialiasing, tileFormat,
                                      tileCompressionQuality,
                                      storageFormat, useLocalCacheDir)
    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 "
    + service + " 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()

This example creates a map cache using a predefined tiling scheme.

# CreateMapServerCache example (stand-alone script)

# Name: CreateMapServerCache.py
# Description: The following stand-alone script demonstrates how to create map
#               using Custom scales & jpg image format with Antialiasing feature turned on
# Requirements: os, sys, time & traceback modules
# Author: ESRI

# 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
server = "MyServer"
service = "Rainfall"
dataFrame = "" 
cacheDir = "C:\\arcgisserver\\arcgiscache\\"
tilingScheme = "NEW"
scalesType = "CUSTOM"
extents = ""
tileOrigin = ""
scales = "4"
dpi = "96"
scaleValues = "600265;350200;225400;44000"
tileWidth = "256"
tileHeight = "256"
cacheType = "FUSED"
inputLayers = ""
pathToXML = ""
antialiasing = "ANTIALIASING"
tileFormat = "JPEG"
tileCompressionQuality = "75"
storageFormat = "Compact"
useLocalCacheDir = "True"

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(server, service, dataFrame, cacheDir,
                                      tilingScheme, scalesType, scales, dpi,
                                      tileWidth, tileHeight, cacheType,
                                      pathToXml, tileOrigin, scaleValues,
                                      inputLayers, antialiasing, tileFormat,
                                      tileCompressionQuality,
                                      storageFormat, useLocalCacheDir)
    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 "
    + service + " 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()

Environments

This tool does not use any geoprocessing environments

Related Topics

Licensing Information

ArcView: Yes
ArcEditor: Yes
ArcInfo: Yes

5/9/2011