VIMAGE -- Collect Image Point/Polygon Statistics

VIMAGE samples a raster image layer for each vector in a vector layer, and adds a column to the vector layer containing the requested sample statistics. Either point sampling, or polygon statistics can be computed.

See Also: GRDVEC, CONTOUR, RTV, VSAMPLE, GRDPOL, HISDUMP

PARAMETERS

VIMAGE is controlled by the following global parameters:

Name     Prompt                                  Count     Type
FILE     Database File Name                      1-64      Char
DBIC     Database Input Channel List             1         Int
FILV     Database Vector File Name               1-64      Char
DBVS     Database Vector Segment                 1         Int
OCOLUMN  Output Column Name                      0-64      Char
SAMPTYP  Sampling Method: POINT/MEAN/...         1-8       Char
UNDEFVAL Value for Undefined Operations          0-1       Real

FILE

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

 EASI>FILE="filespec"

DBIC

Specifies the image channel on FILE to be sampled.

 EASI> DBIC = 1

FILV

Specifies the name of the file containing the vector layer for which image statistics should be computed. If this is not specified, it will be assumed to be the same as the contents of FILE.

 EASI>FILV="filespec"

DBVS

Specifies the vector segment to which a column with image statistic values should be added, and containing the points, or polygons to be used for sampling purposes. Note that this segment serves as input, and output.

The vectors in this segment must be in a georeferencing system that is compatible with the image.

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

 EASI> DBVS = 25

OCOLUMN

  Valid Values:   See Below
  Default:

Specifies the name of the new column to be added to the table.

If the indicated column already exists then that column's contents will be replaced, instead of adding a new field to the table.
If not provided, a default column name will be constructed based on the "Sampling Method" operation and the channel being operated on.

SAMPTYP

  Valid Values:   POINT, MEAN, MODE, MEDIAN, MIN, MAX, HISTnnn, COUNT
  Default:        POINT

Specifies the sampling scheme to be used to compute the value of the new column based on the input image. The legal values are POINT, MEAN, MODE, MEDIAN, MIN, MAX, HISTnnn and COUNT.

POINT: Only computes a value for point vectors (one vertex), and the 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 the be 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 -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
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.

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", were nnn is the number appearing immediately after the keyword HIST. 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.

UNDEFVAL

  Valid Values:   X <= 0.0, X >= 0.0
  Default:        0.0

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

DETAILS

The VIMAGE PACE task reads a single image channel (DBIC) from an input raster file (FILE). It then samples all the pixels associated with the polygon and/or point structures in an input vector layer (DBVS) on the indicated 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 parameter is used to establish what type of statistic is generated, and it can have one of the following values:

POINT: Only computes a value for point vectors (one vertex), and the 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 -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
32768 to 65536, potentially invalidating the results.

MIN: Only computes a value for polygon structures. The computed value will be minimum image value of all pixels inside the polygon.

MAX: Only computes a value for polygon structures. The computed value will be the maximum image value of all pixels inside 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. 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.

Vector structures which don't match criteria for SAMPTYP (must be a single vertex for POINT, or a closed polygon for all the others) have a default 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. More information on different polygon organization can be found in the GeoGateway Data Model documentation.

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 it reads the image rectangle containing the vector, for sampling purposes. This means that if a lot of large vector polygons are being processed the overall processing time can be very slow.

EXAMPLE

A typical use of VIMAGE might be 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.

 EASI> FILE = "agri.pix"
 EASI> DBIC = 1                 | Classification result
 EASI> DBVS = 2                 | Field boundaries.
 EASI> OCOLUMN = "ClassMode"
 EASI> SAMPTYP = "MODE"
 EASI> UNDEFVAL = 0             | unclassified
 EASI> RUN VIMAGE

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.

 EASI> FILE = "irvine.pix"
 EASI> DBIC = 7
 EASI> FILV = "irvine.pix"
 EASI> DBVS = 31
 EASI> OCOLUMN = "Urban_Count"
 EASI> SAMPTYP = "HIST30"
 EASI> UNDEFVAL = -1
 EASI> RUN VIMAGE

About PCI Help Gateway