Create Map Server Cache (Server)

Summary

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

Usage

• This tool only works with map and image layers in ArcGIS Enterprise and map and image services in ArcGIS Server.

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

• When the Ready To Serve Format parameter is checked, the cache content is generated using the open tile package specification. The cache format is Compact V2, but the cache schema is stored in JSON instead of XML. This cache content can be packaged to a zip archive as a tile package for publishing and offline workflows. This cache content is ready to serve using the workflows described in the Publish a tile layer from a cache dataset topic.

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

Parameters

Dialog

Label	Explanation	Data Type
Input Service	The map or image layer that will be cached. You can drag a map or image layer from the Catalog pane to populate this parameter.	Image Service; Map Server
Service Cache Directory	The parent directory for the cache. This must be a registered ArcGIS Server cache directory.	String
Tiling Scheme	Specifies how the tiling scheme will be defined. You can define a new tiling scheme 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—The tiling scheme will be defined using other parameters in this tool to define scale levels, image format, storage format, and so on. This is the default. Predefined—The tiling scheme will be defined using an .xml file. You can create a tiling scheme file using the Generate Map Server Cache Tiling Scheme tool.	String
Scales Type	Specifies how the tiles will be scaled. Standard—The scales will be automatically generated based on the number of scale levels value. It will use levels that increase or decrease by half from 1:1,000,000 and will start with the 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—The cache designer will determine the scales.	String
Number of Scales	The number of scale levels that will be created in the cache. This parameter is disabled if you create a custom list of scales.	Long
Dots(Pixels) Per Inch	The dots per inch (DPI) of the intended output device. If a DPI is specified 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 (in pixels)	Specifies the width and height of the cache tiles in pixels. For the best balance between performance and manageability, avoid deviating from standard widths of 256 by 256 or 512 by 512. 128 by 128—The width and height of the cache tiles will be 128 by 128 pixels. 256 by 256—The width and height of the cache tiles will be 256 by 256 pixels. This is the default. 512 by 512—The width and height of the cache tiles will be 512 by 512 pixels. 1024 by 1024—The width and height of the cache tiles will be 1024 by 1024 pixels.	String
Predefined Tiling Scheme (Optional)	The path to a predefined tiling scheme file (usually named conf.xml).	File
Tiling origin in map units (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)	The 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, for example.	Value Table
Cache Tile Format (Optional)	Specifies the cache tile format that will be used. PNG—A PNG format with varying bit depths will be used. The bit depths are optimized according to the color variation and transparency values in a tile. This is the default. PNG8—A lossless, 8-bit color, image format that uses an indexed color palette and an alpha table will be used. 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 PNG images are similar to GIF images, and most web browsers support transparent backgrounds in PNG images. PNG24—A lossless, three-channel image format that supports large color variations (16 million colors) and has limited support for transparency will be used. Each pixel contains three 8-bit color channels, and the file header contains the single color that represents the transparent background. Versions of Microsoft Internet Explorer earlier than version 7 do not support this type of transparency. Caches using PNG24 are significantly larger than those using PNG8 or JPEG and will use 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 will be used. 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 use 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 will be used. Each pixel contains three 8-bit color channels. Caches using JPEG provide control over output quality and size. Mixed—The PNG32 format will be created anywhere that transparency is detected (that is, anywhere that the data frame background is visible). The JPEG format will be created for the remaining tiles. This keeps the average file size down while providing a clean overlay on top of other caches.	String
Tile Compression Quality (Optional)	The JPEG compression quality (1–100) that will be used. The default value is 75 for the JPEG tile format and 0 for other formats. Compression is supported only for the 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)	Specifies the storage format that will be used for the tiles. Legacy: This parameter has been deprecated. The Compact V2 storage format will always be used regardless of the storage format specified. Compact—The Compact V2 storage format will be used to group tiles into large files called bundles. This storage format is efficient in terms of storage and mobility. This is the default. Exploded—This option has been deprecated. The Compact V2 storage format will always be used.	String
Ready To Serve Format (Optional)	Specifies whether the cache content will be generated using the open tile package specification, and specifies the file format of the cache schema. Checked—The cache content will be generated using the open tile package specification. A tile package can be packaged to a zip archive as a tile package for offline workflows. The cache format will be Compact V2, and the cache schema will be stored in JSON format. Unchecked—The cache content will be generated using a schema stored in XML format. Use this option to copy the cache to previous versions of ArcGIS Enterprise. This is the default.	Boolean

Derived Output

Label	Explanation	Data Type
Output Map Service URL	The output map service URL.	String

Python

arcpy.server.CreateMapServerCache(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}, {ready_to_serve_format})

Name	Explanation	Data Type
input_service	The map or image layer that will be cached.	Image Service; Map Server
service_cache_directory	The parent directory for the cache. This must be a registered ArcGIS Server cache directory.	String
tiling_scheme_type	Specifies how the tiling scheme will be defined. You can define a new tiling scheme 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—The tiling scheme will be defined using other parameters in this tool to define scale levels, image format, storage format, and so on. This is the default. PREDEFINED—The tiling scheme will be defined using an .xml file. You can create a tiling scheme file using the Generate Map Server Cache Tiling Scheme tool.	String
scales_type	Specifies how the tiles will be scaled. STANDARD—The scales will be automatically generated based on the number of scale levels value. It will use levels that increase or decrease by half from 1:1,000,000 and will start with the 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—The cache designer will determine the scales.	String
num_of_scales	The number of scale levels that will be created in the cache. This parameter is disabled if you create a custom list of scales.	Long
dots_per_inch	The dots per inch (DPI) of the intended output device. If a DPI is specified 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	Specifies the width and height of the cache tiles in pixels. For the best balance between performance and manageability, avoid deviating from standard widths of 256 by 256 or 512 by 512. 128 x 128—The width and height of the cache tiles will be 128 by 128 pixels. 256 x 256—The width and height of the cache tiles will be 256 by 256 pixels. This is the default. 512 x 512—The width and height of the cache tiles will be 512 by 512 pixels. 1024 x 1024—The width and height of the cache tiles will be 1024 by 1024 pixels.	String
predefined_tiling_scheme (Optional)	The 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 [scales,...] (Optional)	The 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, for example.	Value Table
cache_tile_format (Optional)	Specifies the cache tile format that will be used. PNG—A PNG format with varying bit depths will be used. The bit depths are optimized according to the color variation and transparency values in a tile. This is the default. PNG8—A lossless, 8-bit color, image format that uses an indexed color palette and an alpha table will be used. 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 PNG images are similar to GIF images, and most web browsers support transparent backgrounds in PNG images. PNG24—A lossless, three-channel image format that supports large color variations (16 million colors) and has limited support for transparency will be used. Each pixel contains three 8-bit color channels, and the file header contains the single color that represents the transparent background. Versions of Microsoft Internet Explorer earlier than version 7 do not support this type of transparency. Caches using PNG24 are significantly larger than those using PNG8 or JPEG and will use 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 will be used. 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 use 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 will be used. Each pixel contains three 8-bit color channels. Caches using JPEG provide control over output quality and size. MIXED—The PNG32 format will be created anywhere that transparency is detected (that is, anywhere that the data frame background is visible). The JPEG format will be created for the remaining tiles. This keeps the average file size down while providing a clean overlay on top of other caches.	String
tile_compression_quality (Optional)	The JPEG compression quality (1–100) that will be used. The default value is 75 for the JPEG tile format and 0 for other formats. Compression is supported only for the 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)	Specifies the storage format that will be used for the tiles. Legacy: This parameter has been deprecated. The Compact V2 storage format will always be used regardless of the storage format specified. COMPACT—The Compact V2 storage format will be used to group tiles into large files called bundles. This storage format is efficient in terms of storage and mobility. This is the default. EXPLODED—This option has been deprecated. The Compact V2 storage format will always be used.	String
ready_to_serve_format (Optional)	Specifies whether the cache content will be generated using the open tile package specification, and specifies the file format of the cache schema. READY_TO_SERVE_FORMAT—The cache content will be generated using the open tile package specification (https://github.com/Esri/tile-package-spec). A tile package can be packaged to a zip archive as a tile package for offline workflows. The cache format will be Compact V2, and the cache schema will be stored in JSON format. NON_READY_TO_SERVE_FORMAT—The cache content will be generated using a schema stored in XML format. Use this option to copy the cache to previous versions of ArcGIS Enterprise. This is the default.	Boolean

Derived Output

Name	Explanation	Data Type
out_service_url	The output map service URL.	String

Code sample

CreateMapServerCache example 1 (stand-alone script)

The following example creates the tiling scheme and preparatory folders for a map service cache using the STANDARD scale type. After running this script, run 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
#               using standard tiling schema for weblayers published to ArcGIS Enterprise and ArcGIS Online.
#               and for map and image services on a stand alone ArcGIS Server
# 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
import traceback, sys

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

# Sign in to portal
myPortal= "https://MyPortal.domain.com/portalwebadaptor"
arcpy.SignInToPortal(myPortal, "siteadminValue", "siteadminPassword")
myServer="https://Myserver.domain.com/serverwebadaptor"
serviceName= "SampleWorldCities"
serviceType= "MapServer"
myPortalServiceURL = (myServer + "/" + "rest/services" +"/" + serviceName + "/"
                      + serviceType)

print (myPortalServiceURL)

# Stand alone ArcGIS Server
##target_server_connection = r"C:\share\python3\arcgis on MyServer"
##serviceName= "States"
##serviceType= "MapServer"
##myServerServiceURL= target_server_connection + "/" + serviceName + "." + serviceType


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 = ""
ready_to_serve_format="READY_TO_SERVE_FORMAT"

#variables for reporting
currentTime = datetime.datetime.now()
arg1 = currentTime.strftime("%H-%M")
arg2 = currentTime.strftime("%Y-%m-%d %H:%M")
file = 'E:/data/report_%s.txt' % arg1

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

try:
##    starttime = time.clock()
    result = arcpy.server.CreateMapServerCache(myPortalServiceURL,
                                               serviceCacheDirectory,
                                               tilingSchemeType, scalesType,
                                               numOfScales, dotsPerInch,
                                               tileSize, predefinedTilingScheme,
                                               tileOrigin, scales,
                                               cacheTileFormat,
                                               tileCompressionQuality,
                                               storageFormat,
					       ready_to_serve_format)

##    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" + \
##        myServerServiceURL + " in " + str(elapsedtime) + " sec \n on " + arg2)
    print("Created cache schema with 4 scales & default properties for" + \
        myServerServiceURL + " in " + arg2)

except Exception as 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)
    report.write(str(e))

print("Executed creation of Map server Cache schema ")
report.close()

CreateMapServerCache example 2 (stand-alone script)

The following example creates the tiling scheme and preparatory folders for a map service cache using the CUSTOM scale type. After running this script, run 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
#              using Custom scales & jpg image format.
# 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
# Sign in to portal
myPortal= "https://MyPortal.domain.com/portalwebadaptor"
arcpy.SignInToPortal(myPortal, "siteadminValue", "siteadminPassword")
myServer= "https://Myserver.domain.com/serverwebadaptor"
serviceName= "SampleWorldCities"
serviceType= "MapServer"
myPortalServiceURL = (myServer + "/" + "rest/services" +"/" + serviceName + "/"
                      + serviceType)

print (myPortalServiceURL)

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:
    result = arcpy.server.CreateMapServerCache(myPortalServiceURL,
                                               serviceCacheDirectory,
                                               tilingSchemeType, scalesType,
                                               numOfScales, dotsPerInch,
                                               tileSize, predefinedTilingScheme,
                                               tileOrigin, scales,
                                               cacheTileFormat,
                                               tileCompressionQuality,
                                               storageFormat)


    #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 as 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(str(e))

print("Executed creation of map server Cache schema using custom scales")

report.close()

CreateMapServerCache example 3 (stand-alone script)

The following example creates the tiling scheme and preparatory folders for a map service cache using the PREDEFINED tiling scheme. After running this script, run 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
#               using existing predefined schema in a ready to serve format
# 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 = "E:/data"

# Sign in to portal
myPortal= "https://MyPortal.domain.com/portalwebadaptor"
arcpy.SignInToPortal(myPortal, "siteadminValue", "siteadminPassword")
myServer= "https://Myserver.domain.com/serverwebadaptor"
serviceName= "SampleWorldCities"
serviceType= "MapServer"
myPortalServiceURL = (myServer + "/" + "rest/services" +"/" + serviceName + "/"
                      + serviceType)

print (myPortalServiceURL)

# Stand alone ArcGIS Server
##target_server_connection = r"C:\share\python3\arcgis on MyServer"
##serviceName= "States"
##serviceType= "MapServer"
##myServerServiceURL= target_server_connection + "/" + serviceName + "." + serviceType


# List of input variables for map service properties
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"
ready_to_serve_format="READY_TO_SERVE_FORMAT"

#variables for reporting
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:
    result = arcpy.server.CreateMapServerCache(myPortalServiceURL,
                                               serviceCacheDirectory,
                                               tilingSchemeType, scalesType,
                                               numOfScales, dotsPerInch,
                                               tileSize, predefinedTilingScheme,
                                               tileOrigin, scales,
                                               cacheTileFormat,
                                               tileCompressionQuality,
                                               storageFormat,
                                               ready_to_serve_format)

    #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 "  + arg2)

except Exception as 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(str(e))

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

Environments

This tool does not use any geoprocessing environments.

Licensing information

• Basic: Yes
• Standard: Yes
• Advanced: Yes