IIIAVG

Description

Transfers image data from image channels between two image files or within one image file. This function is similar to III, except that input pixels are averaged instead of decimated if the input window size is larger than the output window size. The processing time for IIIAVG is longer than III; therefore, it is recommended that IIIAVG be used only when DBIW is larger than DBOW and you want to perform averaging.

Parameters

iiiavg(fili, filo, dbic, dboc, dbiw, dbow, nullvalu)

Name	Type	Caption	Length	Value range
FILI *	str	Input file name	1 -
FILO	str	Output file name	0 -
DBIC *	List[int]	Input raster channel(s)	1 -
DBOC	List[int]	Output raster channel(s)	0 -
DBIW	List[int]	Raster input window	0 - 4	Xoffset, Yoffset, Xsize, Ysize
DBOW	List[int]	Raster output window	0 - 4	Xoffset, Yoffset, Xsize, Ysize
NULLVALU	List[float]	Null value	0 - 1

* Required parameter

Parameter descriptions

FILI

Specifies the name of the PCIDSK image file from which image data is read.

FILO

Specifies the name of the PCIDSK file to receive image data. The output file can be the same as the input file. If FILO is not specified, FILI is used by default. If FILO does not already exist, it is created and the appropriate projection information and meta data is copied from the source file.

DBIC

Specifies the input channel(s) to read from the input file (FILI).

DBOC

Specifies the output channel(s) generated to the output file (FILO).

The total number of channels specified by DBOC must be equal to the total number of channels specified by DBIC.

If the corresponding input and output channels are the same, the input and output windows (DBIW and DBOW) must not overlap.

DBIW

Specifies the raster window (Xoffset, Yoffset, Xsize, Ysize) that is read from the input layers. If DBIW is not specified, the entire channel is used by default. Xoffset, Yoffset define the upper-left starting pixel coordinates of the window. Xsize is the number of pixels that define the window width. Ysize is the number of lines that define the window height.

DBOW

Specifies the raster window (Xoffset, Yoffset, Xsize, Ysize) to be output. If DBOW is not specified, the entire layer is output by default. Xoffset, Yoffset define the upper-left starting pixel coordinates of the window. Xsize is the number of pixels that define the window width. Ysize is the number of lines that define the window height.

The Xsize and Ysize need not be the same for DBIW and DBOW. Image scaling and mapping is automatic.

If FILI equals FILO and DBIC, DBOC, DBIW, and DBOW are defined in such a way that the windows overlap, unexpected results may occur.

NULLVALU

Optionally specifies the value that is skipped when the average is calculated.

If more than half of the input values in an output pixel are null values, the output value is assigned the null value. If a null value is not given and the channel NO_DATA_VALUE meta data value specified then it will be used.

Details

IIIAVG transfers data from image channels (DBIC) in the input file (FILI) to image channels (DBOC) in the output file (FILO). Channel remapping is automatic.

IIIAVG is essentially the same as III, except that input pixel values are averaged instead of decimated if the input window size (DBIW) is larger than the output window size (DBOW). Averaged output images created by IIIAVG look much better than decimated output images created by III, but the process time for IIIAVG is much longer.

If the output image file (FILO) does not already exist, the function creates an output file and georeferences it. If DBOC is empty, it is automatically populated.

Any arbitrary rectangular window on the input file (DBIW) can be transferred to an arbitrary rectangular window on the output file (DBOW). Shrinking or zooming of image data, or both, is automatic when the input window size does not match the output window size. Input pixel values are averaged to calculate output pixel values, where appropriate.

If the image contains a null (background) value, use the NULLVALU parameter to skip the value when the average is calculated. The channel meta data tag NO_DATA_VALUE, if it is available, will be used automatically if NULLVALU is not specified. If more than half of the input values in a window are null values, the output value is assigned the null value.

If the output channel is not 32-bit real, the values are rounded to the nearest integer value after the averaging operation.

Example

Copy a 512x512 input window from channel 1 to a 256x256 output window in a new file (this is essentially block averaging with a 2x2 filter size).

from pci.iiiavg import iiiavg

fili	=	'irvine.pix'
filo	=	'oirvine.pix'
dbic	=	[1]
dboc	=	[]
dbiw	=	[0,0,512,512]
dbow	=	[0,0,256,256]
nullvalu	=	[]

iiiavg( fili, filo, dbic, dboc, dbiw, dbow, nullvalu )

Each pixel value in the resulting 256x256 output window is based on the average of four pixel values (a 2x2 square) from the 512x512 input window.