Program:       CURSOR

Purpose:       Write positions (GRIDS and PHYSICAL coordinates), pointed 
               with an interactive graphics cursor in a GIDS overlay, to 
               screen or ASCII file. Write also (interpolated) image 
               values.

Category:      UTILITY

File:          cursor.c

Author:        M.G.R. Vogelaar

Keywords:


   INSET=      Give input set (, subsets):

               If there is not a set displayed on GIDS then you are 
               prompted with this keyword. The task VIEW will be 
               spawned to display the map.
               Maximum number of subsets is 2048.

   
   BOX=        Give box in .....                        [entire subset]
                               

 **COLOUR=     Marker colour (number or abbrv. name):             [red]   
   
               The positions pointed by the graphics cursor will
               be marked in this colour. The colour is entered as
               a number between 1 and 15 (see notes) or as a string
               which represent a colour. The colours are listed in 
               the description. Colour strings can be abbreviated.
               Example: Set marker colour to yellow:
               COLOUR=7
               COLOUR=Yellow
               COLOUR=yel
   
  
   FILENAME=   Give name of ASCII file:                       [No file]
   
               Write positions to a file on disk or screen. If a 
               transformation to physical coordinates is possible, 
               write these coordinates also.
               
              
   OVERWRITE=  File exists, ok to overwrite?                      [Y]/N
               
               Only prompted if FILENAME= is an existing file. 
              
             

Description:   Program CURSOR writes an ASCII table with positions 
               pointed with a graphics cursor in GIDS where a (sub)set 
               is loaded. If nothing is loaded or GIDS is not available
               you are prompted with the INSET= and the BOX= keywords.
               Then application VIEW is spawned and (after VIEWs'
               CLIP= keyword) a (sub)set is loaded. A simple frame
               is plotted and the graphics cursor appears. 

               With the cursor it is possible to select positions with
               the left button or any keyboard key except 'Q'/'q'. The 
               cursor loop is aborted if the right mouse button or the 
               keyboard key 'Q' (or 'q') is pressed.
               
               Default, the entered positions are written to screen, 
               but if you give a name at the FILENAME= prompt,
               the data is written to an ASCII file on disk. 
               
               The first column in the file (or on screen) is a grid 
               position in X direction, the second is a grid position 
               in Y direction. If a transformation to header units is 
               possible, then also these transformed physical coordinates 
               are written where both columns are prefixed with a 'U' to 
               indicate that the units are header units (in most cases: 
               DEGREE). Between grid- and physical coordinates is a column
               with the interpolated image value at the listed position.
               Image data is taken from the input set at the four integer 
               neighbouring positions of an input position. If all
               positions are within the input box (BOX=) and all image 
               data is not blank then a bilinear interpolation is applied. 
               For three valid neighbours, a plane is constructed to do 
               the interpolation and for two positions, the interpolation
               is linear. 
               Example of the output:
   
               User              : M.G.R. Vogelaar 
               Date of creation  : Thu Jan  4 16:51:31 1996
               X-grid     Y-grid      Image        X-physical     Y-physical
               =================================================================
               -18.44     -19.94      +0.76    U  +158.346481 U   -39.386364
               -12.19     -19.56      -0.00    U  +158.312785 U   -39.384825
                -5.31     -24.81      +0.36    U  +158.275732 U   -39.406715
                etc.
                
               The prefix 'U' indicates that the coordinates are expressed
               in units as found in the header of INSET=.
                      
                             
               The colours that can be used are:

               index  name
               =============================================
               0      Background
               1      Default (Black if background is white)
               2      Red
               3      Green
               4      Blue
               5      Cyan
               6      Magenta
               7      Yellow
               8      Orange
               9      Green + Yellow
               10     Green + Cyan
               11     Blue + Cyan
               12     Blue + Magenta
               13     Red + Magenta
               14     Dark Gray
               15     Light Gray
               
               
Notes:         If you started GIDS on another machine than the one on 
               which you run CURSOR, then cursor actions can be very slow!

Example:       .......

Updates:       Feb  8,  1995: VOG, Document created.
               Jul 27,  2000: VOG, Changed local 'getipval' to 
                                   library 'interpol'.