VIMAGE

Name	Type	Caption	Length	Value range
FILE*	str	Input file name	1 -
DBIC*	List[int]	Input raster channel	1 - 1
DBIB	List[int]	Area mask	0 - 1
FILV	str	Input vector file name	0 -
DBVS*	List[int]		1 - 1
OCOLUMN	str	Output column names	0 -
SAMPTYP	str	Sampling method	0 -	POINT \| MEAN \| MODE \| MEDIAN \| MIN \| MAX \| SUM \| HIST \| COUNT \| STDEV \| VAR Default: POINT
UNDEFVAL	List[float]	Value for undefined operations	0 -	Default: 0.0

Parameter descriptions

FILE

Specifies the name of the PCIDSK file that contains the image channel to be sampled.

DBIC

Specifies the raster image channel to be sampled.

DBIB

Optionally specifies the window or bitmap that defines the area to be processed within the input raster.

Only the area under the mask is written to the output. If this parameter is not specified, the entire channel is processed.

If a single value is specified, that value represents the channel number of the bitmap segment in the input file. Only the pixels under the bitmap are processed; the rest of the image remains unchanged.

If four values are specified, they define the x,y offsets and x,y dimensions of a rectangular window identifying the area to process. 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.

FILV

Specifies the name of the file that contains the vector segment for which image statistics will be computed. If this parameter is not specified, it is be assumed to be the same as the input file.

DBVS

Specifies the vector segment that contains the points or polygons to use for sampling purposes.

This vector segment is also used as output; it will receive the new column of image statistics when the function completes.

Polygons may be expressed as simple closed polygons, polygons with multiple rings, or polygons stored as a topology.

OCOLUMN

Specifies the names of the new columns to be added to the table in the output vector segment.

If the specified column already exists, that column's contents will be replaced, instead of adding a new field to the table.

If this parameter is not specified, a default column names will be added, based on the "Sampling Method" operation and the channel being operated on.

If this value is set and there are more than one "Sampling Method" set, one column name per "Sampling Method" must be set. Each name is delimited by a comma.

SAMPTYP

Specifies the sampling methods used to compute the value of the new column, based on the input image.

Multiple sampling methods can be specified using commas.

Supported methods are:

POINT (default)
MEAN
MODE
MEDIAN
MIN
MAX
SUM
HIST
COUNT
STDEV
VAR

The sampling methods are described in the Details section.

UNDEFVAL

Specifies the values assigned to the output field for which an output value cannot be computed. This value will be used for vectors that fall outside the available image region, as well as to non-point structures when the sampling method is POINT, and to non-polygon structures when a polygon-based sample type is selected.

If this value is set, one value per "Sampling Method" must be specified.

Details

VIMAGE reads a single image channel (DBIC) from an input raster file. It then samples all the pixels associated with the polygon and/or point structures in an input vector segment (DBVS) in the input vector file (FILV). These pixels are then used to compute an image statistic related to that point or polygon, and the statistic is written to a new attribute field (OCOLUMN) for that vector structure.

The SAMPTYP (Sampling Method) parameter is used to define the type of statistic generated. Supported sampling methods are:

POINT: Only computes a value for point vectors (one vertex); the computed value will be the value of the image pixel in which this point falls.
MEAN: Only computes a value for polygon structures (more than two vertices, and the last vertex is the same as the first vertex). The computed value will be the arithmetic mean of the image values of all pixels inside the polygon.
MODE: Only computes a value for polygon structures. The computed value will be the mode (value with the highest occurrence count) of image values in the polygon. Floating point images are binned as if they were integers in the range of -32768 to 65536, potentially invalidating the results.
MEDIAN: Only computes a value for polygon structures. The computed value will be the median (value with half the pixels greater, and half lower) of image values in the polygon. Floating point images are binned as if they were integers in the range of -32768 to 65536, potentially invalidating the results.
MIN: Only computes a value for polygon structures (more than two vertices, and the last vertex is the same as the first vertex). The computed value will be minimum image value of all pixels inside the polygon.
MAX: Only computes a value for polygon structures (more than two vertices, and the last vertex is the same as the first vertex). The computed value will be the maximum image value of all pixels inside the polygon.
SUM: Only computes a value for polygon structures (more than two vertices, and the last vertex is the same as the first vertex). The computed value will be sum of image values in the polygon.
HISTnnn: Only computes a value for polygon structures. The computed value will be the count of pixels within the polygon that had the value "nnn", where nnn is the number appearing immediately after the keyword HIST. This is useful for getting counts of classification results within a polygon.
COUNT: Only computes a value for polygon structures (more than two vertices, and the last vertex is the same as the first vertex). The computed value will be the number of pixels falling inside the polygon.
STDEV: Only computes a value for polygon structures (more than two vertices, and the last vertex is the same as the first vertex). The computed value will be the standard deviation value of all pixels inside the polygon.
VAR: Only computes a value for polygon structures (more than two vertices, and the last vertex is the same as the first vertex). The computed value will be the variance value of all pixels inside the polygon.

Vector structures that do not match the criteria for the sampling method (must be a single vertex for POINT, or a closed polygon for the others) have a default undefined operation value (UNDEFVAL) assigned to the output attribute (OCOLUMN). This also occurs if the vector does not overlay the image, or in the case of polygons with no pixels (based on the center of the pixels) within the polygon.

Vector polygons may be expressed as simple whole polygons (closed polylines), as multi-ring polygons (via RingStart field), or as topological polygons.

The statistics for polygons are based on all pixels for which the center of the pixel falls within, or on the boundary of, the pixel. Pixel contributions are not weighted according to the amount of the pixel within the polygon.

The HIST, MODE, and MEDIAN statistics are computed based on building an in-memory histogram for floating point channels, but the histogram bins the values to integers in the range -32768 to 65536. In many cases, this means the HIST, MODE and MEDIAN results for floating point channels will be inaccurate, or even meaningless.

The VIMAGE program computes statistics by looping over all vectors and, for each appropriate vector, reads the image rectangle containing the vector for sampling purposes. This means that if several large vector polygons are being processed, the overall processing time can be very slow.

Examples

A typical use of VIMAGE is to take a set of field boundaries and compute MODE class from a classification result for each field. We assume that in reality all pixels in a field should really be classified to the same class, and that this class is likely the most commonly occurring (MODE) for the pixels of the field.

from pci.vimage import *

file	=	"agri.pix"
dbic	=	[1]	# classification result
dbib	=	[9]	# bitmap mask
filv	=	""	# use FILE
dbvs	=	[2]	# field boundaries
ocolumn	=	"ClassMode"
samptyp	=	"MODE"
undefval	=	[0]	# unclassified

vimage( file, dbic, dbib, filv, dbvs, ocolumn, samptyp, undefval )

In another example, we can use VIMAGE to get a count of a certain class from a classified channel within the bounds of landuse vectors. Here, we use the USGS Land Use/Land Cover boundary vectors and the classified channel from irvine.pix to find the count of pixels classified as urban (30) within each area.

from pci.vimage import *

file	=	"irvine.pix"
dbic	=	[7]
dbib	=	[9]
filv	=	"irvine.pix"
dbvs	=	[31]
ocolumn	=	"Urban_Count"
samptyp	=	"HIST30"
undefval	=	[-1]

vimage( file, dbic, dbib, filv, dbvs, ocolumn, samptyp, undefval )

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

VIMAGE

Collect image point/polygon statistics

Description

Parameters

Parameter descriptions

Details

Examples