% @(#)align_imag.hlq	19.1 (ESO-DMD) 02/25/03 14:02:55
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990 European Southern Observatory
%.IDENT      align_imag.hlq
%.AUTHOR     KB, IPG/ESO
%.KEYWORDS   MIDAS, help files, ALIGN/IMAGE
%.PURPOSE    On-line help file for the command: ALIGN/IMAGE
%.VERSION    1.0  03-JUNE-1986 : Creation, KB
%----------------------------------------------------------------
\se
SECTION./IMAG
\es\co
ALIGN/IMAGE						17-OCT-2001  KB
\oc\su
ALIGN/IMAGE intab reftab [option] [overlay_flag] [residual_flag]
	compute transformation coefficients for two rotated images
\us\pu
Purpose: 
           Compute transformation coefficients for rotation translation and
           scaling of an image.
\\
           The coefficients are computed using two tables with columns of
           world coordinates of common objects in the image to be aligned 
           and the reference image, respectively.
\up\sub
Subject:
           Alignment, Transformation, Superposition
\bus\sy
Syntax:
           ALIGN/IMAGE intab reftab [option] [overlay_flag] [residual_flag]
\ys\pa
           intab = name of table and columns with world coordinates of object
               in the image to be aligned in the form: table[,:xlabel,:ylabel]
\\
               If the labels are omitted, they are defaulted to label :XCEN 
               and :YCEN which are created by the Midas commands CENTER/GAUSS 
               or CENTER/MOMENT 
\ap\pa
           reftab = name of table and columns with world coordinates of the
               same objects in the reference image in the form:
               table[,:xlabel,:ylabel].
\\
               If the labels are omitted, they are defaulted to :XCEN,:YCEN
\ap\pa
           option = type of transformation to calculate as given below:
               FREE, all parameters in the transformation are free;
               EQUAL, the scaling factors in x and y are equal;
               UNIT, the scaling factors in x and y are equal to 1;
               SHIFT, the scaling factors in x and y are equal to 1 and
                      rotation angle = 0.0;
	       thus, these options decrease in the degree of freedom for
	       the paramaters of the solution;
               defaulted to UNIT
\ap\pa
           overlay_flag = OVER,[intensity] - plot positions of the object in
               table `intab' transformed to the reference frame.
\\
               Points are plotted in the overlay plane with given intensity,
               default intensity = 255 (white); defaulted to no overlay
\\
               The reference frame must be displayed for this option to work!
\ap\pa
           residual_flag = YES or NO - if you want to save the residuals
               calculated in ALIGN/IMAGE also to be stored in the input
               table `intab' in columns labeled :XRESIDUAL, :YRESIDUAL and
               :RESIDUALS;
\\
               defaulted to NO
\ap\sa
See also:
           Chapter 3 of Vol B of the MIDAS User's Guide,
\\
           CENTER/MOMENT, CENTER/GAUSS, REBIN/ROTATE, ALIGN/CENTER
\\
           ALIGN/INTER, TUTORIAL/ALIGN
\as\no
Note:  
              The character column IDENT is used to find matching pairs in 
	   the input tables. Thus, this column must exist in both tables!
              For the SHIFT option one common object is sufficient while the
           other options require at least 3 common objects in the two
           tables. The higher the degree of freedom for the paramaters of
	   the solution, the more objects should be used. Also, these objects
           should not be clustered in one part of the image but, preferably,
	   spread apart covering the whole image area.
              The resulting rotation angle (in degrees), scaling factor 
	   in x and y are stored in the double precision keyword 
	   TRANSFRM(1,2,3), the transformation matrix in TRANSFRM(4-7),
           and the x,y translation in TRANSFRM(8-9).
           The values in TRANSFRM may be used later on as input for the
           REBIN/ROTATE command.
              Preparing the tables, applying ALIGN/IMAGE and finally rebinning
           the images accordingly is quite a complex process, therefore a 
           command ALIGN/INTER exists to interactively align two
           images.
              At most 2000 coord. pairs (objects) are used for the alignment.
\on\exs
Examples:
\ex
           ALIGN/IMAGE c1 c2
             Use columns labeled :XCEN and :YCEN in tables `c1.tbl' and 
             `c2.tbl' to obtain the world coordinates of common objects in the
             two images, say `im1.bdf' and `im2.bdf', from which tables 
             `c1.tbl' and `c2.tbl' were built.
\\
             The method is defaulted to UNIT, so the scaling factors in x and y
             are forced to 1.0.
\\
             Then use:  REBIN/ROTATE im1 im1r KEYWORD im2 
\\
             to obtain image `im1r.bdf' which is aligned with image `im2.bdf'.
\xe\ex
           ALIGN/IMAGE c1,:X_COORD,:Y_COORD c2,:X_COORD,:Y_COORD F
             Use columns labeled :X_COORD and :Y_COORD in tables `c1.tbl' and
             `c2.tbl' to obtain the world coordinates of common objects in the
             two images from which table `c1.tbl' and `c2.tbl' were built.
\\
             All transformation coefficients are free.
\xe\ex
           ALIGN/IMAGE c1,:X_COORD,:Y_COORD c2,:X_COORD,:Y_COORD E OV
             As above but force equal scaling factors in x and y and display
             calculated positions (using the coefficients just obtained) for
             the reference points.
\xe \sxe
