Build Mosaic Dataset Item Cache (Data Management)

Summary

Inserts the Cached Raster function as the final step in all function chains within a mosaic dataset.

Usage

  • The Cached Raster function is inserted on the top of every function chain; therefore, it's the last function implemented in the chain.

  • If you do not check the Generate Cache parameter (set generate_cache to GENERATE_CACHE in Python) to generate the cache, you can use the Synchronize Mosaic Dataset tool to generate the cache.

  • The cache is not moved with the mosaic dataset when it is shared (published) to the server. If you will be building the cache for a mosaic dataset that will be published as an image service, you may want to run this tool on the mosaic dataset after it has been shared. Also, make sure the path to the cache is accessible by the server. If you build the cache prior to publishing the mosaic dataset, you can move the cache to the server and update the cache path stored in the mosaic dataset.

Parameters

LabelExplanationData Type
Mosaic Dataset

The mosaic dataset where you want to apply the cache function.

Mosaic Layer
Query Definition
(Optional)

An SQL expression to select specific raster datasets within the mosaic dataset on which you want the item cache built.

SQL Expression
Define Cache
(Optional)

Enable editing on the Cache properties.

  • Checked—Add the Cached Raster function to the selected items. If an item already has this function, it will not add another one. This is the default.
  • Unchecked—No raster cache will be defined.
Boolean
Generate Cache
(Optional)

Choose to generate the cache files based on the properties defined in the Cached Raster function, such as the location and the compression of the cache.

  • Checked—Cache will be generated. This is the default.
  • Unchecked—Cache will not be generated.
Boolean
Cache Path
(Optional)

Choose to overwrite the default location to save your cache. If the mosaic dataset is inside of a file geodatabase, by default, the cache is saved in a folder with the same name as the geodatabase and a .cache extension. If the mosaic dataset is inside of an enterprise geodatabase, by default, the cache will be saved inside of that geodatabase. Once created, the cache will always save to the same location. To save the cache to a different location, you need to first use the Repair Mosaic Dataset tool to specify a new location and run this tool again.

Once an item cache is created, regenerating an item cache to a different location is not possible by specifying a different cache path and rerunning this tool. It will still generate the item cache in the location where it was generated the first time. However, you can remove this function and insert a new one with the new path or use the Repair Mosaic Dataset tool to modify the cache path and run this tool to generate the item cache in a different location.

Workspace
Compression Method
(Optional)

Choose how you want to compress your data for faster transmission.

  • LOSSLESS Retain the values of each pixel when generating cache. Lossless has a compression ratio of approximately 2:1.
  • LOSSY Appropriate when your imagery is only used as a backdrop. Lossy has the highest compression ratio (20:1) but groups similar pixel values to achieve higher compression.
  • NONE Do not compress imagery. This will make your imagery slower to transmit but faster to draw because it will not need to be decompressed when viewed.
String
Compression Quality
(Optional)

Set a compression quality when using the lossy method. The compression quality value is between 1 and 100 percent, with 100 compressing the least.

Long
Maximum Allowed Rows
(Optional)

Limit the size of the cache dataset by number of rows. If value is more than the number of rows in the dataset, the cache will not generate.

Long
Maximum Allowed Columns
(Optional)

Limit the size of the cache dataset by number of columns. If value is more than the number of columns in the dataset, the cache will not generate.

Long
Request Size Type
(Optional)

Resample the cache using one of these two methods:

  • PIXEL_SIZE_FACTOR Set a scaling factor relative to the pixel size. To not resample the cache, choose Pixel size factor and set the Request Size parameter to 1.
  • PIXEL_SIZE Specify a pixel size for the cached raster.
String
Request Size
(Optional)

Set a value to apply to the Request Size Type.

Double

Derived Output

LabelExplanationData Type
Updated Mosaic Dataset

The updated mosaic dataset.

Mosaic Layer

arcpy.management.BuildMosaicDatasetItemCache(in_mosaic_dataset, {where_clause}, {define_cache}, {generate_cache}, {item_cache_folder}, {compression_method}, {compression_quality}, {max_allowed_rows}, {max_allowed_columns}, {request_size_type}, {request_size})
NameExplanationData Type
in_mosaic_dataset

The mosaic dataset where you want to apply the cache function.

Mosaic Layer
where_clause
(Optional)

An SQL expression to select specific raster datasets within the mosaic dataset on which you want the item cache built.

SQL Expression
define_cache
(Optional)

Choose to define the mosaic dataset cache. A Cached Raster function will be inserted to the selected items. If an item already has a Cached Raster function, it will not add another one.

  • DEFINE_CACHEThe Cached Raster function will be added to the selected items. If an item already has this function, it will not add another one. This is the default.
  • NO_DEFINE_CACHENo raster cache will be defined.
Boolean
generate_cache
(Optional)

Choose to generate the cache files based on the properties defined in the Cached Raster function, such as the location and the compression of the cache.

  • GENERATE_CACHECache will be generated. This is the default.
  • NO_GENERATE_CACHECache will not be generated.
Boolean
item_cache_folder
(Optional)

Choose to overwrite the default location to save your cache. If the mosaic dataset is inside of a file geodatabase, by default, the cache is saved in a folder with the same name as the geodatabase and a .cache extension. If the mosaic dataset is inside of an enterprise geodatabase, by default, the cache will be saved inside of that geodatabase. Once created, the cache will always save to the same location. To save the cache to a different location, you need to first use the Repair Mosaic Dataset tool to specify a new location and run this tool again.

Once an item cache is created, regenerating an item cache to a different location is not possible by specifying a different cache path and rerunning this tool. It will still generate the item cache in the location where it was generated the first time. However, you can remove this function and insert a new one with the new path or use the Repair Mosaic Dataset tool to modify the cache path and run this tool to generate the item cache in a different location.

Workspace
compression_method
(Optional)

Choose how you want to compress your data for faster transmission.

  • LOSSLESS Retain the values of each pixel when generating cache. Lossless has a compression ratio of approximately 2:1.
  • LOSSY Appropriate when your imagery is only used as a backdrop. Lossy has the highest compression ratio (20:1) but groups similar pixel values to achieve higher compression.
  • NONE Do not compress imagery. This will make your imagery slower to transmit but faster to draw because it will not need to be decompressed when viewed.
String
compression_quality
(Optional)

Set a compression quality when using the lossy method. The compression quality value is between 1 and 100 percent, with 100 compressing the least.

Long
max_allowed_rows
(Optional)

Limit the size of the cache dataset by number of rows. If value is more than the number of rows in the dataset, the cache will not generate.

Long
max_allowed_columns
(Optional)

Limit the size of the cache dataset by number of columns. If value is more than the number of columns in the dataset, the cache will not generate.

Long
request_size_type
(Optional)

Resample the cache using one of these two methods:

  • PIXEL_SIZE_FACTOR Set a scaling factor relative to the pixel size. To not resample the cache, choose PIXEL_SIZE_FACTOR and set the request_size parameter to 1.
  • PIXEL_SIZE Specify a pixel size for the cached raster.
String
request_size
(Optional)

Set a value to apply to the request_size_type.

Double

Derived Output

NameExplanationData Type
out_mosaic_dataset

The updated mosaic dataset.

Mosaic Layer

Code sample

BuildMosaicDatasetItemCache example 1 (Python window)

This is a Python sample for BuildMosaicDatasetItemCache.

import arcpy
arcpy.BuildMosaicDatasetItemCache_management(
     "C:/Workspace/itemcache.gdb/md",  "#", "DEFINE_CACHE", 
     "NO_GENERATE_CACHE", "C:/workspace/itemcache", "LOSSY", 
     "80", "#", "#")
BuildMosaicDatasetItemCache example 2 (stand-alone window)

This is a Python script sample for BuildMosaicDatasetItemCache.

#Define mosaic dataset item cache without generating the cache file

import arcpy
arcpy.env.workspace = "C:/Workspace"

mdname = "itemcache.gdb/md"
query = "#"
definecache = "DEFINE_CACHE"
generatecache = "NO_GENERATE_CACHE"
cachepath = "C:/workspace/itemcache"
compression = "LOSSY"
compquality = "80"
maxrow = "#"
maxcolumn = "#"

arcpy.BuildMosaicDatasetItemCache_management(
     mdname, query, definecache, generatecache, cachepath, compression, 
     compquality, maxrow, maxcolumn)