PYRAMID

Description

PYRAMID builds an image pyramid (or overview) for one or more raster channels in a PCIDSK (.pix) file or in another supported file format.

Parameters

pyramid(file, dboc, force, olevels, poption)

Name	Type	Caption	Length	Value range
FILE *	str	Input file	1 -
DBOC	List[int]	Channels to build pyramids	0 -
FORCE	str	Force replacement of existing pyramid levels	0 - 3	Yes \| No Default: No
OLEVELS	List[int]	List of overview levels to build	0 - 16
POPTION	str	Pyramid options	0 - 20	Default: AVER

* Required parameter

Parameter descriptions

FILE

The name of the raster file to be modified. The format of the file must be supported by PCI. With some common formats, such as PCIDSK (.pix), TIFF (.tif) and Imagine (.img), the input file will be updated directly to store the overviews, provided the file is writable. With all other files, a new .pox file will be created with the same base name as the input file and stored in the same folder.

DBOC

The list of channels for which to build pyramid overviews based on the input file specified for FILE (Input file). When no value is specified for this parameter, overviews are built for all channels in the input file. Duplicate output channels are not allowed.

FORCE

Specifies whether to replace existing overview levels.

Supported values are:

Yes: overview levels are always recomputed and replaced
No: overview levels are recomputed only if they do not exist, or if they exist but are marked as out of date. This is the default value.

This parameter is normally set to the default value of No. However, you can select Yes in rare circumstances in which the image is altered by a tool that does not mark the pyramid levels as being out of date.

When Force is set to No, and a level specified would result in an overview that is too small, then the overview will be ignored. When Force is set to Yes, and a level specified would result in an overview that is too small, then an exception is thrown.

OLEVELS

The decimation levels for which to build overviews. For example, specifying values of 2,4 indicates an overview level that is one-half the resolution in each dimension, and an overview that is one-fourth the resolution in each dimension.

When not specified explicitly, this parameter is determined automatically based on the raster dimensions. By default, the overview levels will be powers of two (that is, 2, 4, 8, 16...), provided the smaller dimension of the overview is still greater than 64 pixels. For example, if the input file was 8000 x 600 pixels, this would result in levels of 2, 4, and 8 corresponding to overviews that would be 4000 x 300, 2000 x 150, and 1000 x 75 pixels, respectively. CATALYST Professional visualization tools, such as Focus, are optimized to use base-2 overviews.

This parameter specifies new overviews that are created; it does not remove existing overviews. Therefore, when PYRAMID is run with this parameter set to 3,9, and then run again with a setting of 27, it associates three overviews with the channel. Specified overview levels that do not match existing ones are added to the existing pyramid.

This parameter also supports two special values: -2 and -3. When -2 is specified, all of the powers-of-two overview levels will be created.

Similarly, when -3 is specified, all of the power-of-three overview levels will be created.

Assuming that the raster data is uncompressed, the files size will increase by approximately 33 percent when using -2, and approximately 12.5 percent when using -3.

POPTION

The option specifies the resampling method to use to compute the pixel values in the overviews or to delete the overviews.

Supported values are:

NEAR (Nearest neighbor): uses nearest-neighbor resampling (default). With this method, each pixel in the resampled raster is assigned the value of its nearest neighbor in the original raster. While this method is the fastest, it does not smooth the data, and does not synthesize image values that do not occur in the original data. However, the results exhibit more aliasing than averaging, and cause a jagged appearance.
AVER (Block average): averages all pixels that contribute to the overview pixel. This method is suitable for continuous-tone images, and produces a better-looking overview that is easier to interpret than nearest neighbor. This method is not recommended for classified, pseudocolored, or thematic rasters, as it introduces intermediate values not found in the original.
MODE (Block mode): uses the mode of the pixels that contribute to the overview pixel. This method is suitable for classified, pseudocolored, or thematic raster, but not recommended for continuous-tone images.
BILIN (Bilinear): uses bilinear interpolation. The pixel value is determined from the weighted average of the nine closest pixels to the specified input coordinates, and then assigned to the output coordinates. This method generates an raster with a smoother appearance than nearest neighbor, but the pixel values are altered in the process. This results in blurring or degraded resolution of the raster. This method is most appropriate for continuous data.
CUBIC (Cubic): uses cubic-convolution resampling. The pixel value is determined from the weighted average of the 16 pixels closest to the specified input coordinates, and then assigned to the output coordinates. The resulting raster is slightly sharper than one produced by bilinear interpolation, and it does not have the disjointed appearance produced by nearest neighbor. Like bilinear interpoloation, this method is most appropriate for continuous data.
DEL (Delete):Delete all existing overviews from the file. The DBOC and OLEVELS parameters must be left blank when DEL (Delete) is specified, otherwise an exception is thrown. When deleting overviews the force (Force Overview Rebuild) parameter is ignored.

Note: With complex data, you can use only the NEAR (Nearest neighbor) and AVER (Average) options.

It is recommended that:

thematic raster overviews, such as classification results, be computed using MODE (Block mode)
continuous tone images, especially radar images, be computed using AVER (Block average)

Building overviews with MODE (Block mode) or AVER (Block average) can be significantly slower than computing them using NEAR (Nearest neighbor) or BILIN (Bilinear)

If the nature of the raster is unknown, or if the speed of preparing the overviews is important, use NEAR (Nearest neighbor). For a sharper raster, use CUBIC (Cubic). The default is AVER (Block average).

Details

PYRAMID is typically used to generate image pyramids (raster overviews) to accelerate loading the raster.

The simplest way to use PYRAMID is to use the default values for each parameter, except FILE (Input file). With these settings, a default set of pyramid levels is built for all channels that do not have up-to-date overviews.

The storage of image pyramids that are generated with this function depends on the type of image file. For example, pyramids generated for images in a raw file are stored as external files with a .pox extension, while those generated for images in a PCIDSK file are stored internally in SYS segments in the same PCIDSK file. Some formats, such as JP2, inherently have overviews; therefore, running PYRAMID on files of these types is unnecessary.

Example

Generate the default overview levels for irvine.pix, which, since the file is 512 x 512 pixels, will be levels 2, 4, and 8. Use average resampling to reduce speckle in the overview images.

The original image is stored in a PCIDSK file; therefore, the image pyramids will also be stored in that file.

from pci.pyramid import pyramid

file	=	"irvine.pix"
dboc	=	[]	# build an image pyramid for each image in the file
force	=	""	# default, no forced replacement of existing levels
olevels	=	[]	# default overview levels (2, 4, 8)
poption	=	"AVER"	# average resampling

pyramid( file, dboc, force, olevels, poption )

Environments	PYTHON :: EASI :: MODELER
Quick links	Description :: Parameters :: Parameter descriptions :: Details :: Example :: Related