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	Length	Value range
Input *	Integer	1 - 1024
Input vector channel: Sampling vector mask *	Vector port	1 - 1
Output: Output vector segment *	Vector port	1 - 1
Field Name	String	0 - 1	Default: ATTRIBUTE
Output format	String	0 - 1	COORD | DATA | GEOCORD Default: COORD
Text File Name	String	0 -
Working Memory Size	Integer	0 - 1	0, 4, 8, 16, 32, 64 Default: 8
Undefined Value	Float	0 - 1	Default: 0.0

* Required parameter

Parameter descriptions

Input

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

Input vector channel: Sampling vector mask

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

Output: Output vector segment

Specifies the output vector segment to receive the sampled vector point layer.

Field Name

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.

Output format

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

Text File Name

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.

Working Memory Size

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.

Undefined Value

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

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.