User's Guide

GRNDSPOT

Outputs the pixel values of specified image pixels

Function:

GRNDSPOT prints the value of specified image pixels. There are four methods of specifying the pixels to process: (1) terminal, (2) text file input of individual pixel coordinates, (3) all pixels within an image window, or (4) all pixels within polygonal areas.

Parameters:

Subcommand -TERM:
Input coordinates are specified at the terminal. The following parameter is specified through dynamic tutor: 


COORD(0,0,..,0,0)  
      Set of coordinate pairs for which pixel values 
      will be printed.  Up to 25 pairs may be given 
      at a time.  Values are interpreted as (line, sample),
      or (Y coordinate, X coordinate). See User's 
      Note 1.

IN
Input image. The image may be any type. Window size and/or bands may be specified.

INGRID(-- )
Input grid file. This file contains the transformation matrix to transform the user specified coordinates to line and sample coordinates. If not specified, input coordinates will be treated as line and sample values. INGRID may be created using the function POLYFIT or ROTRNSCL.

PRINT(TERM)
Output destination. The destination of the output image pixels. 


  = TERM:      Terminal.  Output is sent to the user's 
           terminal.
  = LP:        Line printer.  Output is sent to the 
           printer defined by $PRINTER.
  = Filename:  User-supplied filename.  Output is sent 
           to the user-supplied file with the 
           extension ";prt".

TEXT(--)
Text string. String to be printed at the top of the PRINT specified output.
Subcommand -FILE:
Input coordinates are stored in a text file. This file is created using the text editor. Each record in the file should contain the point name, the Y coordinate, and the X coordinate. The first record in the file may contain header information and it is ignored.

IN
Input image. The image may be any type. Window size and/or bands may be specified.

INFILE
Input file. Input file containing point name and pixel coordinates. Refer to User's Note 1 for further information.

INGRID(-- )
Input grid file. This file contains the transformation matrix to transform the user specified coordinates to line and sample coordinates. If not specified, input coordinates will be treated as line and sample values. INGRID may be created using the function POLYFIT or ROTRNSCL.

PRINT(TERM)
Output destination. The destination of the output image pixels. 


  = TERM:      Terminal.  Output is sent to the user's 
           terminal.
  = LP:        Line printer.  Output is sent to the 
           printer defined by $PRINTER.
  = Filename:  User-supplied filename.  Output is sent 
           to the user-supplied file with the 
           extension ";prt".

TEXT(--)
Text string. String to be printed at the top of the PRINT specified output.
Subcommand -WIND:
Input coordinates are derived from an image window. The value for all pixels within this window will be processed. The window is given by specifying (SL, SS, NL, NS) with the IN parameter.

IN
Input image. The image may be any type. Window size and/or bands may be specified.

PRINT(TERM)
Output destination. The destination of the output image pixels. 


  = TERM:      Terminal.  Output is sent to the user's 
           terminal.
  = LP:        Line printer.  Output is sent to the 
           printer defined by $PRINTER.
  = Filename:  User-supplied filename.  Output is sent 
           to the user-supplied file with the 
           extension ";prt".

TEXT(--)
Text string. String to be printed at the top of the PRINT specified output.
Subcommand -STAT:
Subcommand STAT is used if the input coordinates are to be derived from polygonal image areas. The vertices of the polygons are stored in a statistics file. The polygons are represented as training sites within classes in the statistics file.

IN
Input image. The image may be any type. Window size and/or bands may be specified.

INSTAT
Input statistics file.Statistics file containing the polygons for which pixel values will be extracted. The polygons are stored as training sites within classes. The total number of sites cannot exceed 1023. A polygon may have no more than 200 vertices.

NCLASS(--)
Number of classes to be processed. If defaulted, classes and sites in the statistics file will be processed. If a value of "n" is given, the user will be prompted for the number of sites and site names for "n" classes (prompts also issued for class names).

PRINT(TERM)
Output destination. The destination of the output image pixels. 


  = TERM:      Terminal.  Output is sent to the user's 
           terminal.
  = LP:        Line printer.  Output is sent to the 
           printer defined by $PRINTER.
  = Filename:  User-supplied filename.  Output is sent 
           to the user-supplied file with the 
           extension ";prt".

TEXT(--)
Text string. String to be printed at the top of the PRINT specified output.

Examples:

  1. LAS> grndspot-term in=brazil ingrid=geo2img print=lp

    Input coordinates are given via TAE dynamic tutor for the input image BRAZIL. The coordinates are converted to image coordinates by the transformation in the grid file GEO2IMG;GRID.

  2. LAS> grndspot-file in=brazil infile=geocoords.dat ingrid=geo2img print=imgcoords;dat

    Input coordinates are given via the text file GEOCOORDS;DAT. The coordinates are converted to image coordinates using the grid file GEO2IMG;GRID and the output information is sent to the text file IMGCOORDS;DAT.

  3. LAS> grndspot-wind in=brazil(20,20,30,30) print=imgcoords;dat text="grndspot output data"

    GRNDSPOT prints the value for all pixels in the window (20,20,30,30) for the image BRAZIL. Output is sent to a text file and includes the user-supplied comment.

  4. LAS> grndspot-stat in=brazil instat=braz print=lp

    GRNDSPOT prints the value for all pixels in the polygons whose vertices are stored in the statistics file BRAZ;STAT. By default, all classes are used. Output is directed to the line printer.

Description/Algorithm:

Output may be directed to the terminal, the line printer, or a text file. For each qualifying pixel, GRNDSPOT prints the pixel coordinates and its value in all selected bands. For all non qualifying pixels, GRNDSPOT prints the pixel coordinates and an out of range message. A grid file may be used to transform user-supplied input coordinates into image coordinates (subcommands -TERM, -FILE). In this case, both the input and output image coordinates are printed. If text file output is chosen, descriptive information such as user-supplied comments, point names (subcommand -FILE), or site names (subcommand -STAT) are also printed.

SUBCOMMANDS -TERM and -FILE: For each pixel whose coordinates match the user-specified coordinates, GRNDSPOT prints the pixel values in all specified bands along with the line and sample coordinates. If INGRID is specified, the transformation is applied to the input coordinates to convert them to line and sample values. The corresponding pixel values are then retrieved and output along with the input point name from the text file INFILE (subcommandFILE), the user-input coordinates, and the line and sample coordinates. Refer to User's Notes for a detailed description of the text file formats.

SUBCOMMAND -WIND: GRNDSPOT processes all pixels that lie within the rectangular region specified by (SL, SS, NL, NS) on the parameter IN. For each qualifying pixel, the image coordinates and the its value in each band are printed. Refer to User's Note 2 for a detailed description of the text file format.

SUBCOMMAND -STAT: All pixels that lie within specified polygonal regions are processed. The polygon vertices are stored in a statistics file (INSTAT). The polygons are referenced as sites within classes. The parameter NCLASS is defaulted to select all polygons. If a value of "n" is specified for NCLASS, GRNDSPOT prompts for "n" classes; prompts are also issued to select a subset, or all, of the sites in each class. For each qualifying pixel, the image coordinates and the pixel value in each band are printed. For text file output, the first 10 characters of the class and site names are inserted before the image coordinates.

Nonfatal Error Messages:

  1. [grndspot-nclass] Number of classes specified exceed number in file

    NCLASS is larger than the number of classes in statistics file. The user is given an option to continue with all classes or abort.

  2. [grndspot-nrange] Number of invalid coordinates: xxx

    User is informed of the number of coordinates that fell outside the image window.

Fatal Error Messages:

  1. [grndspot-alloc] Error allocating dynamic memory

    An error occurred while allocating dynamic memory for processing. Rerun the function. If the error reoccurs, notify the system manager.

  2. [grndspot-allout] No sites within image bounds

    All polygons are outside the image area. Redefine the polygons or increase the image area.

  3. [grndspot-batch] GRNDSPOT-TERM cannot be run in batch

    Subcommand TERM uses dynamic tutor for getting coordinates and so cannot be used in batch. Use FILE subcommand.

  4. [grndspot-cfile] Error opening coordinates file

    An error was encountered while trying to open coordinates file. Verify that the file exists.

  5. [grndspot-fatal] Fatal error encountered

    A fatal error was encountered. The message displayed preceding this message is the error that was encountered. Processing terminates.

  6. [grndspot-grid] Error getting grid from grid file

    An error was encountered retrieving grid. Use DSPGRID to check the correctness of the grid file contents.

  7. [grndspot-maxsit] Total number of selected sites for all selected classes exceeds 1023

    Specify a smaller number of sites using parameter NCLASS.

  8. [grndspot-nvert] Maximum # site vertices = 200. Simplify site shapes

    Error in the number of site vertices. Simplify the polygons.

  9. [grndspot-sfin] Error getting statistics file name

    The statistics file could not be opened. Check that the file is a statistics file.

User's Notes:

  1. For subcommand -FILE, INFILE may be created using the text editor. The first record in the file may contain header information (it is ignored). Each record must contain the point name and its Y and X coordinates in FREE format. EXAMPLE: 

    
    positions interpreted in image tm8oct88b5lavg, part 1
    3  78  156
    3  78  157
    5  115  171
    5  115  170
    5  116  170
    5  116  169
    5  117  169
    6  121  159
    6  121  160
    6  122  160
    6  122  161
    7  123  167

  2. The output text file has the following format (all file items are separated by one or more blanks):

    SUBCOMMANDS -TERM, -FILE: The first field for each point contains the first 10 characters of the point name (subcommand -FILE only), the input Y, X coordinates (if INGRID is specified), and the image line and pixel coordinates. Subsequent fields contain the pixel values in each band. The maximum number of pixel values per record is based on the image data type as follows: Byte and Integer*2 data (11), Integer*4 and Real*4 data (6).

    SUBCOMMAND -WIND: The first field of each point contains the image line and sample coordinates. Subsequent fields for each point contain the pixel values as described for subcommands -TERM and -FILE.

    SUBCOMMAND -STAT: The first field of each pixel in a polygon contains the first 10 characters of the class and site names. Subsequent fields for each point contain the pixel values as described above.