Build Pyramids And Statistics (Data Management)

Summary

Traverses a folder structure, building pyramids and calculating statistics for all the raster datasets it contains. It can also build pyramids and calculate statistics for all the items in a mosaic dataset.

Usage

• Building pyramids improves the display performance of raster datasets

• Calculating statistics allows ArcGIS applications to properly stretch and symbolize raster data for display.

• All supported raster formats will be processed.

• If the workspace includes a mosaic dataset, only the statistics associated with the mosaic dataset will be included The statistics associated with the items within the mosaic dataset will not be included.

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

Parameters

Dialog

Label	Explanation	Data Type
Input Data or Workspace	The workspace that contains all the raster datasets or mosaic datasets to be processed. If the workspace includes a mosaic dataset, only the statistics associated with the mosaic dataset will be included. The statistics associated with the items within the mosaic dataset will not be included.	Text File; Workspace; Raster Layer; Mosaic Layer
Include Sub-directories (Optional)	Specify whether to include subdirectories. Unchecked—Does not include subdirectories. Checked—Includes all the raster datasets within the subdirectories when loading. This is the default. Mosaic datasets must be specified as an input workspace if you want to include the items within the mosaic dataset. Otherwise, only the statistics associated with the mosaic dataset will be used.	Boolean
Build Pyramids (Optional)	Specify whether to build pyramids. Unchecked—Does not build pyramids. Checked—Builds pyramids. This is the default.	Boolean
Calculate Statistics (Optional)	Specify whether to calculate statistics. Unchecked—Does not calculate statistics. Checked—Calculates statistics. This is the default.	Boolean
Include Source Datasets (Optional)	Specify whether to build pyramids and calculate statistics on the source raster datasets, or calculate statistics on the raster items in a mosaic dataset. This option only applies to mosaic datasets. Unchecked—Statistics will be calculated for each raster item in the mosaic dataset (on each row in the attribute table). Any functions added to the raster item will be applied before generating the statistics. This is the default. Checked—Builds pyramids and calculates statistics on the source data of the mosaic dataset.	Boolean
Block Field (Optional)	The name of the field within a mosaic dataset's attribute table used to identify items that should be considered one item when performing some calculations and operations.	String
Estimate Mosaic Dataset Statistics (Optional)	Specify whether to calculate statistics for the mosaic dataset (not the rasters within it). The statistics are derived from the existing statistics that have been calculated for each raster in the mosaic dataset. Unchecked—Statistics are not calculated for the mosaic dataset. This is the default. Checked—Statistics will be calculated for the mosaic dataset.	Boolean
X Skip Factor (Optional)	The number of horizontal pixels between samples. A skip factor controls the portion of the raster that is used when calculating the statistics. The input value indicates the horizontal or vertical skip factor, where a value of 1 will use each pixel and a value of 2 will use every second pixel. The skip factor can only range from 1 to the number of columns/rows in the raster. The value must be greater than zero and less than or equal to the number of columns in the raster. The default is 1 or the last skip factor used.	Long
Y Skip Factor (Optional)	The number of vertical pixels between samples. A skip factor controls the portion of the raster that is used when calculating the statistics. The input value indicates the horizontal or vertical skip factor, where a value of 1 will use each pixel and a value of 2 will use every second pixel. The skip factor can only range from 1 to the number of columns/rows in the raster. The value must be greater than zero and less than or equal to the number of rows in the raster. The default is 1 or the last y skip factor used.	Long
Ignore Values (Optional)	The pixel values that are not to be included in the statistics calculation. The default is no value.	Long
Pyramid levels (Optional)	Choose 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. The maximum number of pyramid levels you can specify is 29. Any value of 30 or higher will create a full set of pyramids.	Long
Skip first level (Optional)	Choose whether to skip the first pyramid level. Skipping the first level will take up slightly less disk space, but it will slow down performance at these scales. Unchecked—The first pyramid level will be built. This is the default. Checked—The first pyramid level will not be built.	Boolean
Pyramid resampling technique (Optional)	The resampling technique used to build your pyramids. Nearest neighbor —This method uses the value of the closest cell to assign a value to the output cell when resampling. This is the default. Bilinear —This method determines the new value of a cell based on a weighted distance average of the four nearest input cell centers. Cubic —This method determines the new value of a cell based on fitting a smooth curve through the 16 nearest input cell centers.	String
Pyramid compression type (Optional)	The compression type to use 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 Compression —The LZ77 compression algorithm will be used to build the pyramids. LZ77 can be used for any data type. JPEG Compression —The JPEG compression algorithm 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. No compression —No compression will be used when building pyramids.	String
Compression quality (1-100) (Optional)	The compression quality to use when pyramids are built with the JPEG compression method. 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)	Specify whether to calculate statistics only where they are missing, or regenerate them even if they exist. Checked—Statistics will only be calculated if they do not already exist. This is the default. Unchecked—Statistics will be calculated even if they already exist; existing statistics will be overwritten.	Boolean
Query Definition (Optional)	An SQL expression to select raster datasets that will be processed.	SQL Expression
SIPS Mode (Optional)	Specifies whether to enable building of pyramid files using key processes and algorithms defined in the Softcopy Image Processing Standard (SIPS), NGA.STND.0014. Unchecked—Pyramids will be built using standard subsampling methods. This is the default. Checked—Pyramids will be built using SIPS processing.	Boolean

Derived Output

Label	Explanation	Data Type
Updated Input Data	The updated output workspace.	Text File; Workspace; Raster Layer; Mosaic Layer

Python

arcpy.management.BuildPyramidsandStatistics(in_workspace, {include_subdirectories}, {build_pyramids}, {calculate_statistics}, {BUILD_ON_SOURCE}, {block_field}, {estimate_statistics}, {x_skip_factor}, {y_skip_factor}, {ignore_values}, {pyramid_level}, {SKIP_FIRST}, {resample_technique}, {compression_type}, {compression_quality}, {skip_existing}, {where_clause}, {sips_mode})

Name	Explanation	Data Type
in_workspace	The workspace that contains all the raster datasets or mosaic datasets to be processed. If the workspace includes a mosaic dataset, only the statistics associated with the mosaic dataset will be included. The statistics associated with the items within the mosaic dataset will not be included.	Text File; Workspace; Raster Layer; Mosaic Layer
include_subdirectories (Optional)	Specify whether to include subdirectories. NONE —Does not include subdirectories. INCLUDE_SUBDIRECTORIES —Includes all the raster datasets within the subdirectories when loading. This is the default. If the workspace includes a mosaic dataset, only the statistics associated with mosaic dataset will be included. The statistics associated with the items within the mosaic dataset will not be included.	Boolean
build_pyramids (Optional)	Specify whether to build pyramids. NONE —Does not build pyramids. BUILD_PYRAMIDS —Builds pyramids. This is the default.	Boolean
calculate_statistics (Optional)	Specify whether to calculate statistics. NONE —Does not calculate statistics. CALCULATE_STATISTICS —Calculates statistics. This is the default.	Boolean
BUILD_ON_SOURCE (Optional)	Specify whether to build pyramids and calculate statistics on the source raster datasets, or calculate statistics on the raster items in a mosaic dataset. This option only applies to mosaic datasets. NONE —Statistics will be calculated for each raster item in the mosaic dataset (on each row in the attribute table). Any functions added to the raster item will be applied before generating the statistics. This is the default. BUILD_ON_SOURCE —Builds pyramids and calculates statistics on the source data of the mosaic dataset.	Boolean
block_field (Optional)	The name of the field within a mosaic dataset's attribute table used to identify items that should be considered one item when performing some calculations and operations.	String
estimate_statistics (Optional)	Specify whether to calculate statistics for the mosaic dataset (not the rasters within it). The statistics are derived from the existing statistics that have been calculated for each raster in the mosaic dataset. NONE —Statistics are not calculated for the mosaic dataset. This is the default. ESTIMATE_STATISTICS —Statistics will be calculated for the mosaic dataset.	Boolean
x_skip_factor (Optional)	The number of horizontal pixels between samples. A skip factor controls the portion of the raster that is used when calculating the statistics. The input value indicates the horizontal or vertical skip factor, where a value of 1 will use each pixel and a value of 2 will use every second pixel. The skip factor can only range from 1 to the number of columns/rows in the raster. The value must be greater than zero and less than or equal to the number of columns in the raster. The default is 1 or the last skip factor used.	Long
y_skip_factor (Optional)	The number of vertical pixels between samples. A skip factor controls the portion of the raster that is used when calculating the statistics. The input value indicates the horizontal or vertical skip factor, where a value of 1 will use each pixel and a value of 2 will use every second pixel. The skip factor can only range from 1 to the number of columns/rows in the raster. The value must be greater than zero and less than or equal to the number of rows in the raster. The default is 1 or the last y skip factor used.	Long
ignore_values [ignore_value,...] (Optional)	The pixel values that are not to be included in the statistics calculation. The default is no value.	Long
pyramid_level (Optional)	Choose 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. The maximum number of pyramid levels you can specify is 29. Any value of 30 or higher will create a full set of pyramids.	Long
SKIP_FIRST (Optional)	Choose whether to skip the first pyramid level. Skipping the first level will take up slightly less disk space, but it will slow down performance at these scales. NONE —The first pyramid level will be built. This is the default. SKIP_FIRST —The first pyramid level will not be built.	Boolean
resample_technique (Optional)	The resampling technique used to build your pyramids. NEAREST —This method uses the value of the closest cell to assign a value to the output cell when resampling. This is the default. BILINEAR —This method determines the new value of a cell based on a weighted distance average of the four nearest input cell centers. CUBIC —This method determines the new value of a cell based on fitting a smooth curve through the 16 nearest input cell centers.	String
compression_type (Optional)	The compression type to use 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 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. NONE —No compression will be used when building pyramids.	String
compression_quality (Optional)	The compression quality to use when pyramids are built with the JPEG compression method. 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)	Specify whether to calculate statistics only where they are missing, or regenerate them even if they exist. SKIP_EXISTING —Statistics will only be calculated if they do not already exist. This is the default. OVERWRITE —Statistics will be calculated even if they already exist; existing statistics will be overwritten.	Boolean
where_clause (Optional)	An SQL expression to select raster datasets that will be processed.	SQL Expression
sips_mode (Optional)	Specifies whether to enable building of pyramid files using key processes and algorithms defined in the Softcopy Image Processing Standard (SIPS), NGA.STND.0014. NONE —Pyramids will be built using standard subsampling methods. This is the default. SIPS_MODE —Pyramids will be built using SIPS processing.	Boolean

Derived Output

Name	Explanation	Data Type
out_workspace	The updated output workspace.	Text File; Workspace; Raster Layer; Mosaic Layer

Code sample

BuildPyramidsAndStatistics example 1 (Python window)

This is a Python sample for the BuildPyramidsAndStatistics tool.

import arcpy
arcpy.BuildPyramidsAndStatistics_management(
     "C:/Workspace", "INCLUDE_SUBDIRECTORIES", "BUILD_PYRAMIDS",
     "CALCULATE_STATISTICS","BUILD_ON_SOURCE", "BlockField", 
     "ESTIMATE_STATISTICS", "10", "10", "0;255", "-1", "NONE",
     "BILINEAR", "JPEG", "50", "OVERWRITE")

BuildPyramidsAndStatistics example 2 (stand-alone script)

This is a Python script sample for the BuildPyramidsAndStatistics tool.

#Build pyramids and calculate statistics for all raster in a folder

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

inws = "folder"
includedir = "INCLUDE_SUBDIRECTORIES"
buildpy = "BUILD_PYRAMIDS"
calcstats = "CALCULATE_STATISTICS"
buildsource = "NONE"
blockfield = "#"
estimatemd = "#"
skipx = "4"
skipy = "6"
ignoreval = "0;255"
pylevel = "3"
skipfirst = "NONE"
resample = "BILINEAR"
compress = "JPEG"
quality = "80"
skipexist = "SKIP_EXISTING"

arcpy.BuildPyramidsAndStatistics_management(
     inws, includedir, buildpy, calcstats, buildsource, blockfield,
     estimatemd, skipx, skipy, ignoreval, pylevel, skipfirst,
     resample, compress, quality, skipexist)

Environments

Parallel Processing Factor, Pyramid, Raster Statistics

Licensing information

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