; STRAN
;-----------------------------------------------------------------------
;! Task compares ST tables, find image coordinates (e.g. guide star )
;# TASK IMAGE UTILITY OPTICAL
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 1996
;;  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
;-----------------------------------------------------------------------
STRAN     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
STRAN:  Task compares ST tables and finds image Coordiantes.
USERID     -32000.0     32000.0    User ID. 0 => current user
                                     32000 => any user.
INNAME                             Image name(name).
INCLASS                            Image name(class).
INSEQ           0.0      9999.0    Image name(seq. #). 0=>high
INDISK                             Disk drive #. 0=>any
INVER                              ST Table of Star Pixels
IN2VERS         0.0     46655.0    ST Table of Star Coordinates
BPARM                              1: >0 update image header
                                   2: Max number of triangles
                                   3: Print Level (0 to 2)
                                   4: >0 not use header as fit
CPARM                              1: Min triangle size (pixels)
                                   2: Max triangle size (pixels)
                                   3: Min triangle size (arcsec)
                                   4: Max triangle size (arcsec)
                                   5: Star match distance (pix)
                                   6: Min Number Stars in fit
                                   7: Max Triangle match delta
                                   8: Min Triangle side ratio
DPARM                              1: Estimated X Pixel scale
                                   2: Scale error (arcs/pix)
                                   3: Estimated X Pixel scale
                                   4: Scale error (arcs/pix)
                                   5: Orientation Angle
                                   6: Angle error (degrees)
                                   7: Image Center Ra
                                   8: Ra error (degrees)
                                   9: Image Center Dec
                                  10: Dec error (degrees)
----------------------------------------------------------------
STRAN
Type: Task
Use:  STRAN reads in two ST tables and determines the image
      scale and orientation.   The first ST table must contain
      the pixel locations of stars in the image (See STFND).
      The second ST table must contain coordinates (RA+DEC) of
      stars in the image (Use, for instance, GSCAT and GSTAR to
      read the NASA Guide Star cataloge to get a list of star
      coordinates).  Since the two ST tables will have the
      Stars in different orders, STRAN will search for matching
      triangles of sources.  Once matches are found, a best
      match to the star coordinates will be attempted.  NOTE!!!
      STRAN WILL ONLY WORK IF THE STAR TABLES HAVE ROUGHLY 30%
      OVERLAP!  (IF ONLY 10 STARS IN 1 TABLE ARE ACTUALLY AMOUNG
      1000 STARS IN THE SECOND TABLE, STRAN WILL PROBABLY _NOT_
      FIND A SOLUTION.)
      IT IS CERTAINLY BEST TO FIRST ESTIMATE THE IMAGE COORDS
      AND PLOT THE STAR LOCATIONS FIRST TO COMPARE LISTS.
      STRAN BECOMES EXTREAMLY SLOW WITH MORE THAN 300 STARS
      PER ST TABLE.
      THIS IS AN EXTREAMLY EXPERIMENTAL PROGRAM!!!!!!!!!!!!!!!!
Adverbs:
  USERID......The ID of the owner of the image.  0 => current
              user.  32000 => any user.
  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.
  INFILE......Name of file containing star positions; name
              should be of the form:
              myarea:filename.ext
----------------------------------------------------------------
STRAN: Task to read two ST (star position) tables and find
   the image orientation
RELATED PROGRAMS: CNTR, PCNTR, GREYS, PROFL, STARS, STFND, GSTAR
       GSCAT, TABED, PRTAB
DOCUMENTOR: Glen Langston

                           PURPOSE

STRAN - Attempts an "automatic" determinate of the location,
pixel scale, and orientation of an image.  Typical use will be
to determine the orientation of an optical image so that it
can be overlayed with a radio image.  Finding the image para-
meters is done by providing STRAN with two ST tables, one
containing the list of PIXEL locations of stars in the image
and the second containing the list of COORDINATE locations of
stars in the image.  There must be at least 30 % overlap in the
star lists.  (ie 30 % of the stars in one list must be present
in the other list, and visa-versa.)  STRAN WILL NOT WORK IF
THERE IS NOT SUFFICIENT OVERLAP IN THE ST TABLES.  STRAN WILL
WORK MUCH BETTER IF THE TWO LISTS CORRESPOND TO THE SAME STARS!

Use of STRAN requires serveral steps, listed below:
1.  Determine the image properties as well as posible.  Fill
the image header with the best estimates of the location
of a reference pixel,  pixel size and image orientation using
the AIPS verb PUTHEAD.  The critical KEYWORDS are listed
below:
   CRVAL1      X-Location (ie RA in degrees) of the reference
               pixel
   CRVAL2      Y-Location (ie DEC in degrees)
   CRPIX1      X-Location of reference Pixel (origin of pixel
               coordinate system
   CRPIX2      Y-Location of reference Pixel
   CDELT1      X-Size of a Pixel (in degrees)
   CDELT2      Y-Size of a Pixel (in degrees)
   CROTA1      Orientation angle of image (in degrees)
   CROTA2      Orientation angle of image (usually = CROTA1)

2. Find the Guide Star Table containing the region of interest.
   There are Millions of stars in the NASA guide star catalog
   so every few 10s of square arc minute region will contain
   some Guide Stars.  Use the Task GSCAT to read the NASA
   provided REGIONS.TBL containing the Guide Star table number
   corresponding to each region of the sky.

3. Transfer the Guide Star table of interest to the AIPS area
   called FITS (renaming the file to upper case letters).
   Use IMLOD to read in the Guide Star Table which will be
   called an UK (unknown) AIPS table.

4. Use the Task GSTAR to convert the UK table of coordiantes
   into an AIPS ST table.

5. Use the Task TABED to remove all stars outside the region
   of interest.  If many stars remain (more than 100) use
   TABED to remove all but the brightest stars.
   Below is a PRTAB listing of the table created by GSTAR

RING-PSS-O  .MWFLT .   1  Disk= 3    ST Table version   4
Title: AIPS ST star positions table
Created by      GSTAR on 30-JUN-1992 11:04:29
Last written by GSTAR on 02-JUL-1992 00:17:35
Ncol   7  Nrow    2080    Sort cols:
    Table has     1 keyword-value pairs:    TABEPOCH =  b1950.0

COL.NO    1           2           3         4        5       6     7
 ROW   RA---ARC    DEC--ARC   DELTRA--  DELTDEC-  POSANG   STAR  LABEL
 NUMB  DEGREES     DEGREES    DEGREES   DEGREES   DEGREES  INDEX  STR
  1   2.52512D+2  1.49264D+1  1.674E-3  1.674E-3  1.281E-2   0.0   S1
  2   2.52512D+2  1.49264D+1  1.563E-3  1.563E-3  1.314E-2   0.0   S1
  3   2.53565D+2  1.48021D+1  2.681E-3  2.681E-3  1.056E-2   0.0   S2
  4   2.53565D+2  1.48020D+1  2.958E-3  2.958E-3  1.009E-2   0.0   S2
  5   2.52367D+2  1.50045D+1  1.009E-3  1.009E-3  1.523E-2   0.0   S3
  6   2.53312D+2  1.49709D+1  9.801E-4  9.801E-4  1.537E-2   0.0   S4
  7   2.53399D+2  1.48005D+1  1.121E-3  1.121E-3  1.473E-2   0.0   S5
 ...
Note that the Epoch of the coordinates of the stars is
recorded with the keyword TABEPOCH, in this case 1950 coords.
Note that the ST table contains several entries for the same star,
which come from different measurements of the star brightness.
The RA and DEC are in degrees, and the size of the star (columns
3 and 4) are the size of the star on the Palomar sky survey.
The original magnitude of the star is recorded in the Position
angle column, but scaled down by 1000. (ie star S5 in row 7
is a 14.7 magnitude star.)

Make a plot the stars on the image, look for matches.

6. Take the input image and convert it with MWFLT (if necessary)
Usually scanners produce values from 0 to 255, but if it is
desired that the empty sky have values near 0, use MWFLT
to median window subtract the sky.

7. Use the task STFND to find bright stars in the image.  First
make ST tables with the star coordiantes, so that CNTR can
be used to mark identified Stars.  When the identifications
seem good, make an ST table with Pixel Coordinates.

8. Finally, run STRAN to identify stars in the two lists
and determine the image transformation.

                          COMMENTS

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

The Palomar Sky Survey (PSS) scanned with a page scanner is
expected to be a common input in to STRAN.  A few notes about
the PSS:   The PSS has a angular scale of 67.3 arc seconds per
millimeter.  Since Common scanners use dots per inch scales,
this is converted to arc-seconds per pixel below:

   DOTS PER INCH               ARC-SECONDS PER PIXEL
   -------------               ---------------------
       800                           2.14
       600                           2.85
       400                           4.27
       300                           5.7
       200                           8.5
       100                          17.1
        75                          22.8
        50                          34.2

The Palomar Sky Survey was done in two colors E (Red) and
O (Blue).
----------------------------------------------------------------

