Program:       GETVAL

Purpose:       Get image values at given positions in a set

Category:      UTILITY

File:          getval.c

Author:        M.G.R. Vogelaar

Keywords:

   INSET=      Give set (,subset):
 
               Maximum number of subsets is 1.
               The set/subset can have any dimension.


   OUTFILE=    Name of output file:                 [GETVAL_output.txt]
 
               ASCII file on disk which contains the positions in
               POSITION= and the corresponding image values. The 
               image values are formatted according the string 
               entered in FORMAT=
                 
  
   APPEND=     Ok to append?                                      [Y]/N
  
               ASCII file on disk exists. Is it ok to append?
               
  
   FORMAT=     Give format for output:                [fffffffff.fffff]
 
               Print numbers on screen or save numbers in file in user 
               given output format.
               See description for possible formats
  
 
   POSITION=   Enter position in (......):                       [STOP]
     
               Positions are entered as grids or physical coordinates
               (or mixed) according to the GIPSY rules for coordinate
               input. Each position consists of n numbers where n is the 
               dimension of INSET=
               You can abort the loop by pressing [enter].
               If you want to read coordinates from file then this file
               must have extension '.rcl' and you can use it in the 
               following way: POSITION=<myfile
               (where myfile.rcl is the file on disk).
               Examples:
               
               POSITION= 10 -24
               Pixel position RA=10, DEC=-24
               
               POSITION= * 10 12 8    -24
               RA = 10 hours, 12 minutes, 8 seconds,
               DEC = pixel -24
               
               POSITION= * 10 12 8 * -67 8 9.6 
               RA = 10 hours, 12 minutes, 8 seconds, 
               DEC = -67 degrees, 8 minutes, 9.6 seconds, in a 2-dimensional
               area and in the epoch as found in the descriptor of the set. 
                     
               POSITION= *2000.0 3 14 38.02 *2000.0 41 13 54.84 
               Input of RA 3 h 14 m 38.02 s, DEC 41 d 13 m 54.84 s in 
               epoch 2000.0 
               
               You can also use the prefixes 'G' and 'E': 
             
               G        Galactic longitude or latitude in degrees
               E        Ecliptic longitude or latitude in degrees
               
              

Description:   Program GETVAL gets image values from INSET= at user
               given positions in POSITION=
               The position keyword is asked in a loop. Coordinates
               within the frame of the set and with an image value
               that is not blank, are plotted on screen and saved to disk 
               in file OUTFILE= together with the image value. The 
               image value is formatted according to the string in FORMAT=
               Example output from RA, DEC positions in a set:
               
               RA         DEC           IMAGEVALUE
               ===================================
                0.000000  0.000000      9854.73340
                1.000000  1.000000     10071.29688
                3.000000  3.000000      7277.25098
                3.000000  3.000000      7277.25098
               -2.000000 -2.000000      7707.51221 
              
               Note: The header is not part of the output.
               Note: Positions that correspond to a blank image value
                     are not saved to file. However a message appears
                     in the GIPSY LOG file.
               
              
               The program is written for people who want to know image 
               values in a set on certain positions without using
               interpolation (as for instance in program TRACE).
               GETVAL is different from PRINT because is works on
               arbitrary positions and not on boxes and its output
               is directed to an ASCII file on disk. Also GETVAL
               differs from GDS2TEXT because the latter works on a
               box only.
            

               FORMATS
               =======


               The specification in FORMAT= is called a 'format image'.
               A 'format image' is used to print numbers in a user given
               format consisting of characters representing the
               wanted output format. The syntax is:

 flag(s)       Zero or more flags, in any order, which modify the
               meaning of the conversion specification.  The flag
               characters and their meanings are:

      -        The result of the conversion is left-
               justified within the field.

      +        The result of a signed conversion always
               begins with a sign, "+" or "-".

 string        Characters, some with special meaning.
               If the string (f.i. FFFFF.FF or gggg.gg or wwwww)
               contains no dot, the number of characters specify
               a minimum field width.  For an output field, if the
               converted value has fewer characters than the field
               width, it is padded on the left (or right, if the
               left-adjustment flag, - has been given) to the field
               width.
               If the string contains a dot, the total number of
               characters including the dot is the minimum field width
               and the number of characters after the dot is the
               precision.

               The characters are used to determine the conversion
               type. If the string contains an:

               'e' or 'E'
                      The floating-point-number argument is
                      printed in the style [-]drddde+dd,
                      where there is one digit before the
                      radix character, and the number of
                      digits after it is equal to the
                      precision. The E conversion character
                      produces a number with E introducing
                      the exponent instead of e. The
                      exponent always contains at least two
                      digits.  However, if the value to be
                      printed requires an exponent greater
                      than two digits, additional exponent
                      digits are printed as necessary.

               'g' or 'G'

                      The floating-point-number argument is
                      printed in style f or e (or int style E
                      n the case of a G conversion
                      character), with the precision
                      specifying the number of significant
                      digits.  The style used depends on the
                      value converted; style e is used only
                      if the exponent resulting from the
                      conversion is less than -4 or greater
                      than or equal to the precision.

               others
                      Strings without 'e', 'E', 'g' and 'G'
                      indicate a floating point conversion.
                      The floating point number argument is
                      printed in decimal notation in the
                      style [-]dddrddd, where the number of
                      digits after the radix character, r, is
                      equal to the precision specification.

               If the result of a conversion is longer than the
               field width, an asterisk is returned. If the
               input number is a blank, a 'b' is returned.



Examples:      Format string: +eeeeee.eeee
                      Number: 43345.5436
                      Result:  +4.3346e+04
                      Remark: exponential format
                              signed conversion
                              field width: 12
                              precision:    4

               Format string: gggg.ggggg
                      Number: 34.43
                      Result:     34.430
                      Remark: Field width is 10
                              Number of significant digits is 5

               Format string: +ffff.ff
                      Number: 23.456
                      Result:   +23.46
                      Remark: signed conversion

               Format string: -ffff
                      Number: 345.87
                      Result: 346
                      Remark: left justified

               Format string: -+ffff.fff
                              Number: 34.43
                              Result: +34.430
                              Remark: left justified
                                      signed conversion

               Format string: eee.eeee
                      Number: 234.43
                      Result:        *
                      Remark: Field width too small
                              for conversion

               Format string: ffff.ff
                      Number: blank
                      Result:       b
                      Remark: input was a blank




Notes:         

Example:       See above.

Updates:       Apr 23, 1998: VOG, Document created.