VSAMPLE -- Sample Image Along Vectors

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

See Also: NUMWRIT, NUMREAD, VECREP, VIMAGE

PARAMETERS

VSAMPLE is controlled by the following global parameters: 

Name     Prompt                                  Count     Type
FILE     Database File Name                      1-64      Char
DBIC     Database Input Channel List             1-1024    Int
DBVS     Database Vector Segment                 1         Int
QUERY    Vector Query Selection Criteria         1-64      Char
FLDNME   Field to display along with output      1-64      Char
NUMFORM  Output Form: COORD/DATA/GEOCORD         4-12      Char
TFILE    Text File Name                          0-64      Char
MEMSIZE  Working Memory Size (Mbytes)            0-1       Int

FILE

Specifies the name of the PCIDSK file to be used. This file must contain at least one image channel and one vector segment. 

 EASI>FILE="/pci/demo/irvine.pix"

DBIC

Specifies the channel(s) to be sampled. Up to 1024 channels may be specified. 

 EASI>DBIC=1,-5
 EASI>DBIC=1,2,3,4,5
Samples channels 1 through 5.

DBVS

Specifies the vector segment to sample under. Only one segment may be specified. 

 EASI>DBVS=2                    | Uses vector segment 2.

QUERY

An optional vector query expression which may be used to selectively sample underneath vectors which satisfy the search criteria. 

 EASI>QUERY="attribute < 10"
The program will only sample underneath vectors which 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"
Examples: 

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

FLDNME

  Valid Values:   none, ShapeId, Attribute
  Default:
This indicates a field associated with the vector segment you wish to output as a data element. Besides the name of a valid field you may also use one of the following values. 

 none           -> Specifies that no associated vector info is to be
                   generated.
 ShapeId        -> Specifies that the "shapeid" is to be used.
 Attribute      -> Specifies that "Attribute" of the vector
                   segment is used.
If this field is specified, then it is considered the first data element and will be output before any image channel data values.

NUMFORM

  Valid Values:   COORD, DATA, GEOCORD
  Default:        COORD
Indicates the format in which data values will be output to the text file. There is a choice of three formats: COORDinate, DATA, or GEOcoordinate. 

 Note:

 COORDn         = coordinate format, n sets/line
 COORD          = coordinate format, default sets/line
 GEOCORDn       = georeferenced coordinate format, n sets/line
 GEOCORD        = georeferenced coordinate format, 1 set/line
 DATAn          = data format, n values/line
 DATA           = data format, default values/line

TFILE

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

If the TFILE parameter is empty (defaulted) the results will be written as new vector segments, instead of to a text file.

MEMSIZE

  Valid Values:   0, 4, 8, 16, 32, 64
  Default:        4
Specifies the size (in Mbytes) of the internal working memory for VSAMPLE. In general, VSAMPLE will run faster with larger amounts of memory, however VSAMPLE will work with any size of memory.

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 (e.g., 6000 x 6000 input image would require about 72Mbytes of RAM memory). Conveniently, 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.

DETAILS

VSAMPLE is used to sample 1 or more image planes underneath a complete or partial vector segment. When VSAMPLE is run all pixels in the specified image planes which are "underneath" the specified vectors are output 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 point output in the position is the point at which the vector is closest to the center of a pixel. In the example the vector (*) is sampled at position S which is the point of the vector closest to the center of the pixel (C). 

                         *
        +--------------*-----------------+
        |            *                   |
        |          *                     |
        |        *                       |
        |      S                         |
        |    *   o                       |
        |  *       o                     |
        |*           o                   |
       *|              o                 |
     *  |                C               |
        |                                |
        |                                |
        |                                |
        |                                |
        |                                |
        |                                |
        |                                |
        +--------------------------------+
        |<--------- Single Pixel ------->|
NUMFORM specifies the format in which the data will be output.

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

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

For example, if n=2 (i.e., "COORD2"), then 2 pixels (6 values) will be output on each line for one input channel. 

 X, Y, G, X, Y, G             |G = grey level
 X, Y, G, X, Y, G             |X, Y = Pixel, Line coordinates
If number of input channels is four, and n=2 (i.e., "COORD2"), then four values (x,y coordinate and two grey level values) will be output on first line and two on the second line (2 grey level values). 

 X, Y, G1, G2                 |G = grey level for different channels
 X, Y, G3, G4
If no value is specified, then 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 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. The user can specify the number of pixels that will be output on each line of text using the "GEOCORDn" form. For example, if n=2 (i.e., "GEOCORD2"), then 2 pixels (6 values) will be output on each line, if DBIC is equal to one.

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

For data ("DATA") format, the text file will contain a grey level value for each pixel (one grey level value for each input channel, DBIC). The user can specify the number of pixels that will be output on each line of text using the "DATAn" form.

For example, if n=2 (i.e., "DATA2"), then 2 pixels (2 values) will be output on each line. If no n value is specified, then 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.

Note: values for n must result in a text line less than 150 characters.

EXAMPLE

Create a text file from Irvine.pix querying all classification result pixels that underlie with vector having attributes less than 10. Save the file to sample.txt 

 EASI>FILE="Irvine.pix"                 | File name
 EASI>DBIC=7                            | Classification Results
 EASI>DBVS=26                           | Vector Segment
 EASI>QUERY="attribute < 10"            | Attribute Query Expression   
 EASI>FLDNME="attribute"                | Fieldname from attribute
 EASI>NUMFORM="coord"                   | Format in coordinate
 EASI>TFILE="sample.txt"                | Text file name
 EASI>MEMSIZE=                          | Default value
About PCI Help Gateway