Build Pyramids (Data Management)

Summary

Builds raster pyramids for your raster dataset.

This tool can also be used to delete pyramids. To delete pyramids, set the Pyramids Levels parameter to 0.

Illustration

Usage

• Building pyramids improves the display performance of raster datasets.

• You only need to build pyramids once per dataset. The pyramids will be accessed every time you display the raster dataset.

• Pyramids will not be built for raster datasets that have less than 1,024 pixels in the row or column. Pyramids are not needed since the raster dataset is small enough, and building pyramids will not help improve performance.

• Wavelet compressed raster datasets, such as ECW, JPEG2000, and MrSID, do not need to have pyramids built. These formats have internal pyramids that are created upon encoding.

• You can choose the compression type for your overview pyramid file using the raster storage environments. Compression will create a smaller .ovr file. The IMAGINE format and older versions of ArcGIS will create reduced-resolution dataset files (.rrd) when compression is not available.

• The default pyramid compression will use the optimal compression type, depending on the data type. You can manually choose LZ77, JPEG, or no compression.

• JPEG compression can only be used with file formats that can store data according to the JPEG specifications. The list of supported raster dataset file formats lists which specification the JPEG format can support.

Parameters

Dialog

Label	Explanation	Data Type
Input Raster Dataset	The raster dataset for which you want to build pyramids. The input should have more than 1,024 rows and 1,024 columns.	Raster Dataset; Raster Layer
Pyramid levels (Optional)	The number of reduced-resolution dataset layers that will be built. The default value is -1, which will build full pyramids. A value of 0 will result in no pyramid levels. To delete pyramids, set the number of levels to 0. The maximum number of pyramid levels you can specify is 29. Any value that is 30 or higher will revert to a value of -1, which will create a full set of pyramids.	Long
Skip first level (Optional)	Specifies whether the first pyramid level will be skipped. Skipping the first level will take up slightly less disk space but will slow down performance at these scales. Unchecked—The first pyramid level will not be skipped; it will be built. This is the default. Checked—The first pyramid level will be skipped; it will not be built.	Boolean
Pyramid resampling technique (Optional)	Specifies the resampling technique that will be used to build the pyramids. Nearest—The value of the closest pixel will be used to assign a value to the output pixel when resampling. This is the default. Bilinear—The new value of a pixel will be based on a weighted distance average of the four nearest input pixel centers. Cubic—The new value of a pixel will be based on fitting a smooth curve through the 16 nearest input pixel centers.	String
Pyramid compression type (Optional)	Specifies the compression type that will be used when building the raster pyramids. Default—If the source data is compressed using a wavelet compression, it will build pyramids with the JPEG compression type; otherwise, LZ77 will be used. This is the default compression method. LZ77—The LZ77 compression algorithm will be used to build the pyramids. LZ77 can be used for any data type. Jpeg—The JPEG compression algorithm will be used to build pyramids. Only data that adheres to the JPEG compression specification can use this compression type. If JPEG is chosen, you can then set the compression quality. Jpeg Luma and Chroma—A lossy compression using the luma (Y) and chroma (Cb and Cr) color space components will be used to build pyramids. No compression—No compression will be used when building pyramids.	String
Compression quality (1-100) (Optional)	The compression quality that will be used when pyramids are built with the JPEG compression type. The value must be between 0 and 100. The values closer to 100 will produce a higher-quality image, but the compression ratio will be lower.	Long
Skip Existing (Optional)	Specifies whether pyramids will be built only when they are missing or will be regenerated even if they exist. Unchecked—Pyramids will be built even if they already exist, and existing pyramids will be overwritten. This is the default. Checked—Pyramids will only be built if they do not already exist.	Boolean

Derived Output

Label	Explanation	Data Type
Updated Input Raster	The output raster dataset.	Raster Dataset

Python

arcpy.management.BuildPyramids(in_raster_dataset, {pyramid_level}, {SKIP_FIRST}, {resample_technique}, {compression_type}, {compression_quality}, {skip_existing})

Name	Explanation	Data Type
in_raster_dataset	The raster dataset for which you want to build pyramids. The input should have more than 1,024 rows and 1,024 columns.	Raster Dataset; Raster Layer
pyramid_level (Optional)	The number of reduced-resolution dataset layers that will be built. The default value is -1, which will build full pyramids. A value of 0 will result in no pyramid levels. To delete pyramids, set the number of levels to 0. The maximum number of pyramid levels you can specify is 29. Any value that is 30 or higher will revert to a value of -1, which will create a full set of pyramids.	Long
SKIP_FIRST (Optional)	Specifies whether the first pyramid level will be skipped. Skipping the first level will take up slightly less disk space but will slow down performance at these scales. NONE—The first pyramid level will not be skipped; it will be built. This is the default. SKIP_FIRST—The first pyramid level will be skipped; it will not be built.	Boolean
resample_technique (Optional)	Specifies the resampling technique that will be used to build the pyramids. NEAREST—The value of the closest pixel will be used to assign a value to the output pixel when resampling. This is the default. BILINEAR—The new value of a pixel will be based on a weighted distance average of the four nearest input pixel centers. CUBIC—The new value of a pixel will be based on fitting a smooth curve through the 16 nearest input pixel centers.	String
compression_type (Optional)	Specifies the compression type that will be used when building the raster pyramids. DEFAULT—If the source data is compressed using a wavelet compression, it will build pyramids with the JPEG compression type; otherwise, LZ77 will be used. This is the default compression method. LZ77—The LZ77 compression algorithm will be used to build the pyramids. LZ77 can be used for any data type. JPEG—The JPEG compression algorithm will be used to build pyramids. Only data that adheres to the JPEG compression specification can use this compression type. If JPEG is chosen, you can then set the compression quality. JPEG_YCbCr—A lossy compression using the luma (Y) and chroma (Cb and Cr) color space components will be used to build pyramids. NONE—No compression will be used when building pyramids.	String
compression_quality (Optional)	The compression quality that will be used when pyramids are built with the JPEG compression type. The value must be between 0 and 100. The values closer to 100 will produce a higher-quality image, but the compression ratio will be lower.	Long
skip_existing (Optional)	Specifies whether pyramids will be built only when they are missing or will be regenerated even if they exist. OVERWRITE—Pyramids will be built even if they already exist, and existing pyramids will be overwritten. This is the default. SKIP_EXISTING—Pyramids will only be built if they do not already exist.	Boolean

Derived Output

Name	Explanation	Data Type
out_raster	The output raster dataset.	Raster Dataset

Code sample

BuildPyramids example 1 (Python window)

This is a Python sample for the BuildPyramids tool.

import arcpy
arcpy.BatchBuildPyramids_management(
     "C:/data/img1.tif;C:/data/img2.img", "6", "SKIP_FIRST",
      "BILINEAR", "JPEG", "50", "SKIP_EXISTING")

BuildPyramids example 2 (stand-alone script)

This is a Python script sample for the BuildPyramids tool.

#Build Pyramids for multiple raster datasets in the workspace
#Skip the dataset that already has pyramid
#Build pyramids with compression and level setting

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

    
inras = "image1.tif;image2.img;fgdb.gdb/image3"
pylevels = "6"
skipfirst = "SKIP_FIRST"
resample = "BILINEAR"
compress = "JPEG"
quality = "80"
skipexist = "SKIP_EXISTING"

arcpy.BatchBuildPyramids_management(
     inras, pylevels, skipfirst, resample, compress,
     quality, skipexist)

Environments

Current Workspace, Pyramid, Parallel Processing Factor, Scratch Workspace

Special cases

Pyramid

The pyramid level, pyramid compression, and resampling method does not apply to the IMG format.

Parallel Processing Factor

Only supported for CRF format.