; XTRAN
;---------------------------------------------------------------
;! Create an image with transformed coordinates
;# TASK ASTROMETRY COORDINATES IMAGE OPTICAL
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 1999-2000, 2003-2004
;;  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
;-----------------------------------------------------------------------
XTRAN     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
XTRAN:  Task to create an image with transformed coodinates
USERID     -32000.0     32000.0    User ID.  0=>current user
                                     32000=>all users
INNAME                             Input image name. blank=>any
INCLASS                            Input name(class). blank=>any
INSEQ           0.0      9999.0    Input name(seq. #). 0=>any
INDISK                             Input disk drive #. 0=>any
OUTNAME                            Output name(name).
                                     blank=>INNAME
OUTCLASS                           Output name(class).
                                     blank=>INCLASS
OUTSEQ          0.0      9999.0    Output name(seq. #).
                                     0=>lowest unique
OUTDISK                            Output image disk drive #
                                     0 => highest with space
BLC                                Bottom left corner of input
TRC                                Top right corner of input
ORDER           0.0         6.0    Number of parameters to fit.
                                     (Only 3 or 6 allowed)
DOOUTPUT       -2.0         2.0    Transform coordinates
                                     (1 => regrid image to new)
                                     (2 => copy image with fit
                                      parameters in header)
INFILE                             File with star positions.
----------------------------------------------------------------
XTRAN
Type: Task
Use:  XTRAN is a generalized coordinate transformer used to find the
      relationship between x,y coordinates in the image and RA and Dec
      from user supplied standard star postiions (1000 stars maximum).
      If DOOUTPUT is FALSE, the transformation will be calculated, but
      the image header will not be updated (DOOUTPUT = -2) and no
      output image file will be written (DOOUTPUT=-1).  If DOOUTPUT=1,
      a new image is created with re-gridding as needed using the
      transformation coefficients and filling in the appropriate
      parameters in the image header.   If DOOUTPUT is 2, a new image is
      created by copying the old image with new, fitted header
      parameters.  This is only correct for simple transformations
      (ORDER = 3).  Note that these two transformations are not
      exactly the same since they do not necessarily use the same
      refernce pixel.

      WARNING: XTRAN does not do a full non-linear geometry in doing
      its fits.  Therefore, it is limited in its accuracy and should be
      used only for small fields and applications not requiring high
      astrometric accuracy.
Adverbs:
  USERID......User ID of owner of image.  0=>current user
                 32000=>any user
  INNAME......Input name of image(name).  blank=>any
  INCLASS.....Input name of image(class).  blank=>any
  INSEQ.......Input name of image(seq. #).  0=>any
  INDISK......Disk drive # of image.  0=>any
  OUTNAME.....Output name of image(name). blank=>INNAME
  OUTCLASS....Output name of image(class). blank=>INCLASS
  OUTSEQ......Output name of image(seq. #).  0=>lowest unique
  OUTDISK.....Disk drive # of Output image.  0 => highest with space.
  BLC.........The bottom left-hand pixel of the input image which
              becomes the bottom left corner of the new image.  The
              value (0,0) means (1,1).
  TRC.........The top right-hand pixel of the input image which becomes
              the top right corner of the new image.  The value (0,0)
              means take the top right hand corner of the image.
  ORDER.......Type of transformation: 3 is rotation plus x and y pixel
              size.  ORDER=6 is rotation, x and y pixel size, plus
              quadradic stretch.
  DOOUTPUT....If = 1, a new image is created with regridding using the
              transformed coordinates from the xy-RA,Dec fit.
              If = 2, a new image is created by copying the old image
              and adjusting the output header parameters.  This is only
              appropriate for an ORDER=3 fit.
              If = -1, compute the fit as +1 but write no output.
              If = -2, compute the fit as +2 but write no output.
  INFILE......File name of standard star positions (8 characters).  This
              file must have the following format:
              (a) The first line contains an initial guess of the RA,
              DEC of the center of the image (RA-hr, min,sec,
              DEC-deg,min,sec) in the format:
                        18X,F3.0,F3.0,F7.3,F3.0,F3.0,F6.2
              (b) The following lines (up to 20) contain Star name, X
              position, Y position, RA-hr, RA-min, RA-sec, DEC-deg,
              DEC-min, DEC-sec in the format:
                 A4,F7.2,F7.2,F3.0,F3.0,F7.3,F3.0,F3.0,F6.2

              Note that these are fixed-length Fortran formats; the
              characters must appear in the columns as specified.  See
              the example in the EXPLAIN XTRAN section.
----------------------------------------------------------------
XTRAN: Task to create an image with transformed coodinates
RELATED PROGRAMS: REGRD, STRAN

                           PURPOSE

XTRAN
Type: Task
Use:  XTRAN is a generalized coordinate transformer.  XTRAN finds a
coordinate relationship between image pixels and coordinates of objects
located at these pixels (i.e., matching star coordinates to their pixel
locations).  If DOOUTPUT is FALSE, only the transformation will be
calculated, but NOT applied to the image.  If DOOUTPUT is 1 a new image
is created regridding the input image using the transformation
coefficients.  If DOOUTPUT=2, the input image is copied and a corrected
header is supplied.  This is only correct for simple transformations.

The fit to the coordinate transformation assumes the X and Y axes are
perpendicular, so that the X transformation can be calculated separately
from the Y transformation.  The angle of orientation returned from the
fit is the average of the two fits.  Note that if all coordinates are in
a line, a fit is not possible.  (ie better fits result from stars
distributed over a large area; stars in a long thin region will not
produce a good fit.)

In the 6-parameter case, the X and Y fits are still done individually.
X distortions must be independent of Y distortions, ie an image can be
compressed in one direction and stretched in another.

The Name of the input file must be in the "standard" DIRECTORY:FILE
format and the file name must be in UPPER CASE LETTERS.
    Examples:
         INFILE='myarea:MYSTARS.DAT'
                     where MYAREA is an environment variable set
                     before starting AIPS:
         %setenv MYAREA /mnt/username

The Input Star location file must be provided with fixed format.
    Example input file is listed below:
                   23 22 43.64 -12 23 58.0
STR1 155.98  78.75 23 22 42.23 -12 24 21.8
STR2 169.96  64.92 23 22 38.52 -12 23 23.2
STR3 159.19  67.12 23 22 41.36 -12 23 32.9
STR4 145.08  83.27 23 22 45.48 -12 24 37.8
STR5 133.07  82.89 23 22 49.19 -12 24 38.1
STR6 158.00  83.00 23 22 41.67 -12 24 37.7
AB   151.24  73.26 23 22 43.64 -12 23 58.0

Fortran formats, for those of you too young to know such things are:
   18X   18 ignored characters (best left blank)
   A4    4 characters
   F7.2  7 characters, including a decimal point, blank = 0
   F3.0  3 characters, if no decimal it is assumed to follow the 3
         (those " 23" = "23.")
The simplest thing to do is to copy the format above EXACTLY.

Full lines that function as comments may be added anywhere in the
file.  Comment lines must begin with a dollar sign ($).
----------------------------------------------------------------
