% @(#)convercoor.hlq	19.2 (ESO-DMD) 03/17/03 14:49:03 
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990 European Southern Observatory
%.IDENT      convercoor.hlq
%.AUTHOR     JDP, IPG/ESO
%.KEYWORDS   MIDAS, help files, CONVERT/COORDS
%.PURPOSE    On-line help file for the command: CONVERT/COORDS
%.VERSION    1.0  990118: Creation KB
%----------------------------------------------------------------
\se
SECTION./COOR
\es\co
CONVERT/COORDS						17-MAR-2003  KB
\oc\su
CONVERT/COORDS image coord_string [dsplay_flag]
	frame pixel ro world coordinates conversion (and vice versa)
\us\pu
Purpose:    
          Convert frame pixels to world coordinates and back.
\up\sy
Syntax:     
          CONVERT/COORDS image coord_string [dsplay_flag]
\ys\pa
          image = name of image frame
\ap\pa
          coord_string = string of up to 3-dim coords separated by comma;
               the syntax of this string determines if we convert from
               frame pixels to world coords or from world coords to frame
               pixels;
               frame pixels are specified via: @xpix,@ypix,@zpix
               world coords are specified either as: xwc,ywc,zwc 
               or as: xh:xm:xs,yd:ym:ys,zwc 
\ap\pa
          display_flag = Yes or No, to display the results in the Midas
               command window or not; defaulted to Yes
\ap\sa
See also: 
          @a getcoord
\as\no
Note:  
          The pixels/coords are always stored in keyword OUTPUTD in the
          following way:
          the frame pixels are stored in OUTPUTD(10,11,12)
          the decimal world coords are stored in OUTPUTD(1,2,3)
          the RA, DEC world coords (if used) are stored in OUTPUTD(4,5,6)
          as hours,minutes,seconds and in OUTPUTD(7,8,9) as degrees.
	  If the conversion failed, OUTPUTD(10-12) are set to -1, but the
	  currently running procedure (if any) is NOT aborted.
	  Please, note, that CONVERT/COORDS does not support the
	  conversion of screen pixels. The application procedure getcoord.prg
	  has to be used in that case.
\on\exs
Examples:
\ex
          CONVERT/COORDS fors @1000,@1000
            Yields (for a given UT1/FORS file) the output:
            frame pixels entered = 1000,1000
            world coords =  57.210487, -0.97601925  or  3:48:50.52, -0:58:33.67
            and the keyword OUTPUTD holds
            57.210487488432435,-0.9760192515391457,0,
            3,48,50.52,
            0,58,33.67,
            1000,1000,1,...
\xe \ex
          CONVERT/COORDS fors 57.210487,-0.97601925
            Yields (for the same UT1/FORS file) the output:
            world coords entered = 57.210487,-0.97601925
              or 3:48:50.52, -0:58:33.67
            frame pixels = 1000,1000
            and the keyword OUTPUTD holds the same values as shown above
\xe \ex
          CONVERT/COORDS fors 3:48:50.52,-0:58:33.67
            Yields (for the same UT1/FORS file) the output:
            world coords entered = 3:48:50.52,-0:58:33.67
              or    57.2105, -0.97601944
            frame pixels = 1000,1000
            and the keyword OUTPUTD holds the same values as shown above
\xe \sxe
