VSAMPLE

Description

VSAMPLE samples pixels from one or more image channels that lie underneath a specified vector segment and writes the result to a vector point layer and to an optional text file.

Parameters

Name	Type	Caption	Length	Value range
FILE *	String	Input file name	1 - 192
DBIC *	Integer	Input raster image channel	1 -
DBVS *	Integer	Sampling vector mask	1 - 1
QUERY	String	Vector query selection criteria	0 - 64
FLDNME	String	Field to display with output	0 - 64	Default: ATTRIBUTE
NUMFORM	String	Output format	0 - 12	COORD | DATA | GEOCORD Default: COORD
TFILE	String	Text file name	0 - 192
MEMSIZE	Integer	Working memory size	0 - 1	0, 4, 8, 16, 32, 64 Default: 8
UNDEFVAL	Float	Value for undefined operations	0 - 1	Default: 0.0
MONITOR	String	Monitor mode	0 - 3	ON, OFF Default: ON

* Required parameter

Parameter descriptions

FILE

Specifies the name of the PCIDSK file that contains the image channels to sample. This file must contain at least one image channel and one vector segment.

DBIC

Specifies the raster image channel(s) to be sampled.

DBVS

Specifies the vector segment that defines the area under which the image will be sampled. Only one segment may be specified.

QUERY

Specifies an optional vector query expression that may be used to selectively sample underneath vectors that satisfy the search criteria.

VSAMPLE will only sample under vectors that have attribute values of less than 10.

The following is the grammar:

EXPRESSION:     PRIMARY
                not (EXPRESSION)
                (EXPRESSION) BINARY_OP (EXPRESSION)

PRIMARY:        FIELDNAME OPERATOR VALUE

OPERATOR:       =
                <=
                >=
                <
                >

BINARY_OP:      and
                or
VALUE:          number
                "string"

FIELDNAME:      valid fieldname of the vector segment or "ShapeId"

                attribute = 1
                not (attribute = 1)
                (attribute < 12 and attribute > 4) or (group < 2)

FLDNME

Specifies a field associated with the vector segment to output as a data element.

If the field name is specified, it is considered the first data element and will be output before any image channel data values.

NUMFORM

Specifies the format in which data values will be output to the text file.

TFILE

Specifies the output text file to which the results will be returned. X,Y are in the georeferenced coordinate system of the input imagery. One column of output is produced for each input channel specified.

If this parameter is not specified, the results are written only to new vector segments, and not to a text file. If specified, the text file must already exist.

MEMSIZE

Specifies the size, in megabytes (MB) of the internal working memory for VSAMPLE.

Ideally, VSAMPLE requires that the entire input image be held in RAM memory. This requirement however, would be unacceptable for large images on small computer systems; for example, a 6000 x 6000 input image would require about 72 MB of RAM memory. In reality, only a fraction of the input image needs to be in RAM at any particular time. The size of the fraction that needs to be in memory is a complex interaction based on image size and the amount of rotation between the raw input image and the geocoded output image. The default working memory value is 8 MB.

UNDEFVAL

Specifies the value to assign to a shape that is outside the raster image. The default value is 0.0.

MONITOR

The program progress can be monitored by printing the percentage of processing completed. A system parameter, MONITOR, controls this activity.

Available options are:

• ON: Turns the monitor ON (default)
• OFF: Turns the monitor OFF (recommended if running in batch or background mode)

Details

VSAMPLE samples one or more image planes underneath a complete or partial vector segment. When VSAMPLE is run, all pixels in the specified image planes that are "underneath" the specified vectors are output to a vector point layer and, optionally, to a text file. Vectors are sampled at "pixel" intervals, and one column of data is produced for each image plane specified.

The vectors are sampled in the same order in which the vertices of a polyline are specified. The polylines are not necessarily output in increasing ShapeId order.

The pixel sampling is performed using the Bresenham's line algorithm for each line segment. The point output for each sampled pixel is the point at which the vector is closest to the center of the pixel or the vertex, if this is the start or the end of a line segment.

In the following example, the vector (*) is sampled at position S, which is the point of the vector closest to the center of the pixel (C) and the two end vertices marked as '+'.

        +----------------+----------------+
        |                |                |
        |                |                |
        |                |            +   |
        |                |           *    |
        |                |          *     |
        |                |         *      |
        |                |        *       |
        |                |       *        |
        +----------------+------*---------+
        |                |     *          |
        |                |    *           |
        |                |   S            |
        |                |  *  \          |
        |                | *     C        |
        |                |*               |
        |                *                |
        |               *|                |
        +--------------*-+----------------+
        |             *  |                |
        |            *   |                |
        |           *    |                |
        |          *     |                |
        |         *      |                |
        |        *       |                |
        |       *        |                |
        |      +         |                |
        +----------------+----------------+
        |<-Single Pixel->|

NUMFORM (Output Format) specifies the format in which the data will be output.

For the coordinate (COORD) format, the text file contains values for each pixel: database x-position (pixel) and database y-position (line), followed by any data as a result of specifying the FLDNME (Field Name) parameter, followed by gray-level value(s) pertaining to each input channel (in pixel-interleave mode).

You may specify the number of pixels that will be output on each line of text using the "COORDn" form.

For example:

If n=2 ("COORD2"), two pixels (6 values) will be output on each line for one input channel.

X, Y, G, X, Y, G             | G = gray level
X, Y, G, X, Y, G             | X, Y = Pixel, Line coordinates

If the number of input channels is four, and n=2 ("COORD2"), four values (x,y coordinate and two gray-level values) will be output on first line and two on the second line (2 gray-level values).

X, Y, G1, G2                 | G = gray level for different channels
X, Y, G3, G4

If no value is specified, by default 5 pixels will be output per line for 8-bit input image channels, 4 for 16-bit channels, and 3 for 32-bit real channels for one input channel ("Input").

X, Y, G, X, Y, G, X, Y, G, X, Y, G, X, Y, G    | 8-bit input channel
X, Y, G, X, Y, G, X, Y, G, X, Y, G             | 16-bit input channel
X, Y, G, X, Y, G, X, Y, G                      | 32-bit input channel

For the georeferenced coordinate (GEOCORD) format, the content of the text file is similar to that of the COORD format except that the (x,y) position is expressed in georeferenced units. You may specify the number of pixels that will be output on each line of text using the "GEOCORDn" form.

For example

If n=2 ("GEOCORD2"), two pixels (6 values) will be output on each line, if DBIC (Input raster channel) is equal to one.

If no n value is specified, by default 1 pixel will be output per line for 8-bit, 16-bit or 32-bit channels.

For the data ("DATA") format, the text file will contain a gray-level value for each pixel (one gray-level value for each input channel). You may specify the number of pixels that will be output on each line of text using the "DATAn" form.

For example:

If n=2 ("DATA2"), two pixels (2 values) will be output on each line.

If no n value is specified, by default 16 pixels will be output per line for 8-bit input image channels, 10 for 16-bit channels, and 5 for 32-bit real channels.

Example

Create a text file from "irvine.pix", querying all classification result pixels that underlie the vector and having attribute values less than 10. Save the file to "sample.txt". Any points outside the raster will be given a value of -1.

EASI>FILE="irvine.pix"               ! input file name
EASI>DBIC=7                          ! classification results
EASI>DBVS=26                         ! input vector segment
EASI>QUERY="attribute < 10"       ! attribute query expression   
EASI>FLDNME="attribute"              ! field name from attribute
EASI>NUMFORM="coord"                 ! format in coordinate
EASI>TFILE="sample.txt"              ! text file name
EASI>MEMSIZE=                        ! defaults to 4 MB
EASI>UNDEFVAL=-1                     ! set undefined value to -1

EASI>RUN VSAMPLE