; STARS
;---------------------------------------------------------------
;! Task to generate an ST ext. file with star positions
;# TASK PLOT
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 2004-2006, 2008-2009
;;  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
;-----------------------------------------------------------------------
STARS     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
STARS:  Task to generate an ST ext. file with star positions *
INNAME                             Image name(name).
INCLASS                            Image name(class).
INSEQ           0.0      9999.0    Image name(seq. #). 0=>high
INDISK                             Disk drive #. 0=>any
OUTVERS         0.0     46655.0    STar file version number.
INTEXT                             File with star positions
X                                  Input  Star Coordinate epoch
                                   1: 1900; 2: B1950; 3: J2000
                                   4: Galactic; 5: OHLSSON Gal.
                                   6: VAN TULDER Galactic
                                   7: Super Galactic; 0=> 3
Y                                  Output Star Coordinate epoch
----------------------------------------------------------------
STARS
Type: Task
Use:  STARS reads a text file containing "star" positions and
      makes an ST extension file.  Plot programs can then use
      this file to plot symbols at the indicated positions.
      See EXPLAIN STARS for the required format of the text
      file.
Adverbs:
  INNAME......Image name (name).       Standard defaults.
  INCLASS.....Image name (class).      Standard defaults.
  INSEQ.......Image name (seq. #).     0 => highest.
  INDISK......Disk unit #.             0 => any.
  OUTVERS.....Version number of ST (star position) file to be
              created.   0 => highest+1.
  INTEXT......Name of file containing star positions; name
              should be of the form:
              myarea:filename.ext
  X...........Input  Star Coordinate epoch
              1: 1900; 2: B1950; 3: J2000; 4: Galactic
              5: OHLSSON Gal.; 6: VAN TULDER Galactic
              7: Super Galactic; if > 1000 then year assumed
              0:=> 3 (J2000)
  Y...........Output Star Coordinate epoch.
              If X = Y then no transformation is performed
----------------------------------------------------------------
STARS: Task to create an ST (star position) extension file
RELATED PROGRAMS: CNTR, PCNTR, GREYS, PROFL, REGRD

                           PURPOSE

     STARS creates an ST extension file for the specified image.
This file contains a list of positions and "sizes" for stars or
whatever else one wishes marked on images.  The output file is a
standard table extension file and hence can be reviewed with
PRTAB and handled by a number of tasks including FITTP and
IMLOD.  The star "sizes" can be used to indicate, for example,
Gaussian component widths and position angle or position
uncertainty or magnitudes and are used as scale factors in
plotting plus signs or other symbols on contour or grey-scale
images.

                          COMMENTS

INTEXT:
     The user must create a table from which STARS reads star
positions and uncertainties.  The Name of the input file must
be in the "standard" DIRECTORY:FILE format and the file name
must be in UPPER CASE LETTERS.
    Example:
         INTEXT='myarea:MYSTARS.DAT'
                     where MYAREA is an environment variable set
                     before starting AIPS:
         %setenv MYAREA /mnt/username
The AIPS area $RUNFIL is often used for STARS inputs.

    The text file contains one line per star and each line has
up to 7 logical columns containing, in order:
   1. X position (Right Ascension 00 00 00.00)
   2. Y position (Declination +/-00 00 00.0)
   3. Major axis (Full width in arc seconds on sky)
   4. Minor axis (Full width in arc seconds on sky)
   5. Position Angle (E of N, degrees)
   6. Star Type  (-1 to 20, integer )
   7. Star label (up to 24 character string)
If X and Y are not RA-DEC or DEC-RA, then the logical columns
are also 7 actual columns and the units are in AIPS standard
units (e.g. degrees, m/s etc. ).  In this case the position
angle should be given as 0.0, the major axis is the width in the
Y coordinate and the minor axis is the width in the X
coordinate.  For RA and DEC positions, the sexagesimal notation
is used (e.g. HH MM SS.SSS -DD MM SS.S) for the positions and
arc seconds on the sky are used for the Deltas.

The last 5 columns are not required.  If the last 5 columns are
not given, a value of 1 cell is assumed for the deltas.
If the position angle is not included, the default is 0 degrees.
If the star type is not included, the default type is a cross.
The default is no label string.

There are currently 24 different types of star marks.
  <0: No Mark, only the star label is printed
  =0: value changed to -1 if a label is present, else changed to +1

   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.  The CROSS WITH GAP
(type=24) has the inner third of the cross removed so the
marked object is not over written.

You can view the contents of the ST file with PRTAB.

                Coordinate transformation

The input and output epochs of the coordinates is specified by
X and Y. Currently indexes are:
   1: 1900;
   2: B1950;
   3: J2000;
   4: Galactic
   5: OHLSSON Gal.;
   6: VAN TULDER Galactic
   7: Super Galactic
   if > 1000 then year assumed  (ie if X = 1975, input epoch
      is 1975)
   0:=> 3 (J2000)

The coordinate transformation performed by STARS is an
approximation to the exact transformation from B1950 to J2000.
As it currently stands, the year of observation of the B1950
coordinate can not be incorperated into the J2000 trans.
Accuraccy of the B1950 to J2000 transformation is on the
order of 1" over most of the sky if the date of observation
is not included.  Also see the EXPLAIN file for REGRD.

Algorithm:
   The Euler angles for the transformation from a variety of
   coordinate systems to Equatorial B1950.0 are stored or
   computed.  To obtain the Euler angles to go from system X to
   system Y, those from X to B1950.0 are combined with the
   inverse of those from Y to B1950.0.
References:
   Smith, C.A., et al, 1989.  Astron. J., 97, 265.
   Yallop, B.D., et al, 1989.  Astron. J., 97, 274.
Notes:
  1) A failing of the IAU1976 system was not to give simple and
   unambiguous names to the systems of constants and
   coordinates.  For example, the equatorial coordinate system
   loosely described as "J2000.0" usually means "the position at
   epoch J2000.0 on the mean equator and equinox of J2000.0 in
   the IAU1976 system of coordinates".  However, the J prefix
   only indicates the new convention for computing epochs, there
   is no formal reason to disassociate it from the old Bessel-
   Newcomb system.
     Nevertheless, one is left to assume that any coordinate
   system associated with a Julian epoch refers to the IAU1976
   system, and that Besselian epochs indicate Bessel-Newcomb
   precession.  An epoch prefix of 'b' is interpreted as
   Bessel-Newcomb without E-terms.
  2) References here to "equatorial B1950.0" or "ecliptic J2000.0"
   etc. refer strictly to space-fixed coordinate systems.  These
   are defined by the mean equator (or ecliptic) and equinox
   specified by the Bessel-Newcomb precession formulae for
   Besselian epochs, or the IAU1976 system for Julian epochs.
     In transforming star catalogue positions it should be noted
   that coordinates in the "FK4" system include the E-terms of
   aberration (less than 1 arcsec), whereas the "FK5" system
   excludes them.  The exact transformation between these two
   systems is therefore not a simple rotation.
  3) The angles for transforming from J2000.0 to B1950.0 were
   computed from the matrix coefficients Mij in the SLALIB
   routine FK524 according to the following
      PHI0  = ATAN2(-M31,M32)
      THETA = ATAN2(STH,M33)
      PHI   = ATAN2(M13,-M23)
   where STH is an average
      STH = (M31/SIN(PHI0) - M13/SIN(PHI))/2D0
  4) Formulae for the precession angles are conventionally given
   for precession from epoch E1 to epoch E2, referenced to the
   basic epoch E0 (J2000.0 or B1900.0).  This is avoided here,
   since it results in precession coefficients which are not
   independent of one another.  Instead, only precession from
   the basic epoch E0 to arbitrary epoch E is used. Precession
   between any two arbitrary epochs is then given by the inverse
   of precession from E0 to E1 followed by precession from E0 to
   E2.
  5) If the Euler angles for a rotation are (PHI0, THETA, PHI)
   then for the inverse rotation they are (PHI, -THETA, PHI0).
Author of coordinate transformations:
   Mark Calabretta, Australia Telescope.
----------------------------------------------------------------

