; GSTAR
;---------------------------------------------------------------
;! Task to read a Guide Star (UK) table and create an ST table.
;# TASK PLOT OPTICAL
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 2006, 2009, 2020
;;  Associated Universities, Inc. Washington DC, USA.
;;
;;  This program is free software; you can redistribute it and/or
;;  modify it under the terms of the GNU General Public License as
;;  published by the Free Software Foundation; either version 2 of
;;  the License, or (at your option) any later version.
;;
;;  This program is distributed in the hope that it will be useful,
;;  but WITHOUT ANY WARRANTY; without even the implied warranty of
;;  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;;  GNU General Public License for more details.
;;
;;  You should have received a copy of the GNU General Public
;;  License along with this program; if not, write to the Free
;;  Software Foundation, Inc., 675 Massachusetts Ave, Cambridge,
;;  MA 02139, USA.
;;
;;  Correspondence concerning AIPS should be addressed as follows:
;;         Internet email: aipsmail@nrao.edu.
;;         Postal address: AIPS Project Office
;;                         National Radio Astronomy Observatory
;;                         520 Edgemont Road
;;                         Charlottesville, VA 22903-2475 USA
;-----------------------------------------------------------------------
GSTAR     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
GSTAR:  Task reads a Guide Star (UK) table and create an ST tab.
INNAME                             Image name(name).
INCLASS                            Image name(class).
INSEQ           0.0      9999.0    Image name(seq. #). 0=>high
INDISK                             Disk drive #. 0=>any
INVERS                             Guide star (UK) table number
OUTVERS         0.0     46655.0    STar file version number.
FACTOR          0.0        24      Star Type: 1=Plus, etc
DETIME                             Output Star Coordinate epoch
                                   1: 1900; 2: 1950; 3: 2000
                                   4: Galactic; 5: OHLSSON Gal.
                                   6: VAN TULDER Galactic
                                   7: Super Galactic
----------------------------------------------------------------
GSTAR
Type: Task
Use:  GSTAR reads a Guide Star Table (currently type UK) and
      creates an ST table.  The ST table contains the J2000
      positions of the Stars from the Guide Star Cataloge.
      Plot programs can then use this file to plot marks showing
      the locations of stars in images.
Adverbs:
  INNAME......Image name (name).       Standard defaults.
  INCLASS.....Image name (class).      Standard defaults.
  INSEQ.......Image name (seq. #).     0 => highest.
  INDISK......Disk unit #.             0 => any.
  INVERS......Guide star ("UK") table number
  OUTVERS.....Version number of ST (star position) file to be
              created.   0 => highest+1.
  INFILE......Name of file containing star positions; name
              should be of the form:
              myarea:filename.ext
  FACTOR......Index to the type of mark plotted to indicate the Stars
              location.  Allowed Values are 1-24.  0 -> 1 a "plus"
              symbol.  See explain for full list.
  DETIME......Epoch of RA+DEC coordinates or index to Galactic
              or super galactic coordinates.   <1 => J2000
              1: 1900; 2: 1950; 3: 2000; 4: Galactic
              5: Old Galactic (Ohlsson)
              6: Old Galactic (Van Tulder)
              7: Super Galactic (Revised)
----------------------------------------------------------------
GSTAR: Task to read a Guide Star (UK) table and create an ST
       (star position) extension table.
Related Tasks: IMLOD, TACOP, TABED, CNTR, PCNTR, GREYS, STARS,
       STRAN
Documentor: Glen Langston (NRAO)

                           PURPOSE

     GSTAR creates an ST table from an Guide Star Table.  The
Guide Star tables are provided by NASA on CDROM and contain the
coordinates of nearly all stars brighter than 15 magnitude.  At
this faint level, there are several stars in every few square
arc minute field.  The Purpose of GSTAR is to translate the
FITS Guide Star table into a table usable by AIPS for plotting
and for coordiante transformations (AIPS task STRAN).
See help information on STARS for an explanation of the AIPS
ST table format.

                          COMMENTS

The Guide Star Fits tables should be read into AIPS using the
task IMLOD.  The UK table should then be copied to the image
requiring star marks.  Next, because of the great number of
stars in the tables (Millions and Millions) the task TABED
should be used to select only the stars in the region desired.
(The magnitude of the stars required can also be selected with
TABED.)

The Input Guide Star Table (UK) contains 9 columns
   1. The Guide Star ID number. (A star can be listed twice
      in the Guide Star Table)
   2. Right Ascension (J2000 in degrees, range 0-360)
   3. Declination (J2000 +/-degrees)
   4. Position Error (arc seconds)
   5. Magnitude
   6. Magnitude Error
   7. Band code for the Magnitude estimate
   8. Class of the Guide Star identification.
   9. ID of the Plate from which the star was identified.

The Output ST table has 7 Columns
   1.    Right Ascension or Longitude of the star
         Coordinate system depends on ADVERB DETIME (below)
   2.    Declination or Latitude of the star
          (degrees, range -90 to 90)
   3,4   Star Size X,Y (degrees)
         (roughly size of star on Palomar Sky Survey degrees)
   5.    Star Position Angle = Star Magnitude/1000
         (range (6 to 15)/1000)
   6.    Star type index = Value of ADVERB FACTOR (below)
   7.    Star Label = 'S' and Star number in UK table

FACTOR: Selects the type of Star mark for plots.
There are currently 24 different types of star marks.
   1: Plus sign (default)   12: Five pointed star
   2: Cross (X)             13: Star of David
   3: Circle                14: Seven-pointed star
   4: Box                   15: Eight-pointed star
   5: Triangle              16: Nine-pointed star
   6: Diamond               17: Ten-pointed star
   7: Pentagon              18: 11-pointed star
   8: Hexagon               19: 12-pointed star
   9: Septagon              20: 13-pointed star
   10: Octagon              21: 14-pointed star
   11: Nine-gon             22: Plus with gap
                            23: Vertical line
                            24: Cross (X) with gap

The Box (type=4) is different from the diamond in that the
star size is the half height and width of the box dimensions.
The Box and the Null (<0) are labeled at RA and Dec plus Delta
RA and Delta Dec.  The other marks are labeled at the right
edge of the of the Rotated RA axis.

DETIME: The Guide Star Cataloge star positions are in J 2000
Coordinates.  The output Star file can have star positions in
one of seven coordinate systems.  The coordiantes are

    Epoch         Coordinate system      Euler angles in 1950
    -----  --------------------------  -----------------------
      1            Equatorial 1900     89.679  +0.278   90.320
      2            Equatorial 1950      0.0     0.0      0.0
      3            Equatorial 2000     90.320  -0.278   89.679
      4            Galactic            33.0   -62.6    -77.75
      5        Old Galactic (Ohlsson)  -0.056 -62.273  -79.386
      6     Old Galactic (Van Tulder)  -0.061 -62.772  -78.388
      7      Super Galactic (Revised) 116.868 +74.355 +193.189

You can view the contents of the UK and ST tables with PRTAB.
----------------------------------------------------------------

