As of Tue Jan 16 4:33:43 2018

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
STVERS          0.0     46655.0    STar file version number.
INTEXT                             File with star positions
DECIMAL        -1.0         2.0    1->RA Dec in decimal degrees,
                                   2->RA DEC in arc seconds from
                                   <= 0 RA DEC sexagesimal
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


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.
  INNAME......Image name (name).       Standard defaults.
  INCLASS.....Image name (class).      Standard defaults.
  INSEQ.......Image name (seq. #).     0 => highest.
  INDISK......Disk unit #.             0 => any.
  STVERS......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
  DECIMAL.....= 1 => Right ascensions and declinations are in
                     decimal degrees
              = 2 => Right ascensions and Declinations are given as
                     RASHIFT and DECSHIFT values in arc seconds
              <= 0 => Right ascensions and declinations are in
  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


     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.


     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 (unless you leave off the close quote mark).
                     where MYAREA is an environment variable set
                     before starting AIPS:
          percentsetenv 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 HH MM SS.SS if DECIMAL <= 0)
   2. Y position (Declination +/-DD MM SS.S if DECIMAL <= 0)
      RA/DEC in degrees if 0 < DECIMAL < 1.5
      RA/DEC as offsets in arc sec if DECIMAL > 1.5 so that
         RA = RA_0 + Value1 / cos (DEC_0)
         DEC = DEC_0 + Value2
   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.

Blank lines and lines beginning with # in column 1 are ignored.

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.

   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.
   Smith, C.A., et al, 1989.  Astron. J., 97, 265.
   Yallop, B.D., et al, 1989.  Astron. J., 97, 274.
  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
  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.