% @(#)holes_opto.hlq	17.1.1.1 (ESO-IPG) 01/25/02 17:54:56
%+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT     (c) 1991 European Southern Observatory
%.IDENT         optop.hlq
%.AUTHOR        A. Gemmo     Padova Department of Astronomy
%.KEYWORDS      MIDAS, help files, HOLES/OPTOPUS
%.PURPOSE       On-line help file for the command: HOLES/OPTOPUS
%.VERSION       1.0 13-SEP-1991 : Creation, AG
%-----------------------------------------------------------------------
\se
SECTION./OPTO
\es\co
HOLES/OPTOPUS                                    13-SEP-1991 AG
\oc\su
HOLES/OPTOPUS [inp_tab] [out_tab] [HH,MM,SS.sss] [+/-DD,AM,AS.ss]
              [ac_flag] [p_flag] [old_eq,new_eq]  
	detetermine  holes positions on Optopus plate.
\us\pu
Purpose:    
            Calculate X and Y positions of guidestars and scientific
	    targets on Optopus plate from RA and DEC equatorial
	    coordinates using the center provided by the user or
	    calculating it automatically upon request. Checks are made
            to point out objects falling out of the plate limits or in
	    the so called "forbidden area".
	    Overlaps between big guidestars, big and small guidestars,
	    big guidestars and objects, small guidestars and objects
	    and objects and objects are also notified to the user.
\up\sy
Syntax:     
            HOLES/OPTOPUS [inp_tab] [out_tab] [HH,MM,SS.sss]
                   [+/-DD,AM,AS.ss] [ac_flag] [p_flag] [old_eq,new_eq]
\ys\pa
	    [inp_tab]        = table created by the command
	                       CREATE/OPTOPUS and containing columns :IDENT,
	                       :TYPE, :CHECK, :OLDRA, :OLDDEC, (if the
		               command PRECESS/OPTOPUS has been used),
		               :RA and :DEC. Default name is "opto1.tbl".
\ap\pa        
	    [out_tab]        = output table, with :X, :Y, and :Z columns,
		               instead of :RA and :DEC.
		               Default name is "opto2.tbl".
\ap\pa
            [HH,MM,SS.sss]   = \\Right Ascension of center of the plate.
		               If defaulted, it is automatically
			       calculated by taking the mean (see
			       STATISTIC/TABLE command) of column :RA in
			       input table or by reading the value set
			       with the command SET/OPTOPUS CRA=....
			       (see documentation to SET/OPTOPUS).
\ap\pa
	    [+/-DD,AM,AS.ss] = \\Declination of center of the plate.
		       	       If defaulted, it is automatically 
			       calculated by taking the mean (see
		       	       STATISTIC/TABLE command) of column :DEC
			       in input table or by reading the value
			       set with the command SET/OPTO CDEC=...
			       (see documentation to SET/OPTOPUS).
\ap\pa 
	    [ac_flag]        = Character flag which enables or
		     	       desables the automatic calculation of
			       the center. Default value is "Y" for
			       yes. If [ac_flag] is set to "Y" and RA
			       and DEC of the center are defaulted,
			       then the center is determined by
			       averaging :RA and :DEC columns of
			       input table. If, on the contrary,
			       [ac_flag] is set to "N" and RA and DEC
			       of the center are defaulted, the
			       corresponding values are read from the
			       keywords set with SET/OPTO CRA= CDEC=
			       command (see documentation).
\ap\pa
            [p_flag]         = Character flag which enables or
	        	       desables the automatic precession of
			       the center. Default value is "Y" for
			       yes. [p_flag] should be set to "N" if
			       the user has already precessed the 
			       center coordinates to [new_equinox].
			       In case of an automatic determination
			       of the center from an input table
			       already precessed by the command
			       PRECESS/OPTOPUS, [p_flag] is
			       automatically set to "N". 
\ap\pa
	    [old_eq,new_eq]  = \\Old and new epoch (before and after
		       	       precession) of center coordinates.
			       Default values are 1950.0 for [old_eq]
			       and 2000.0 (or the epoch calculated 
			       from year,month,day of the observation
			       if these values have already been set
			       by the command SET/OPTOPUS DATE=...
			       (see documentation)) for [new_eq].
\ap\no
Note:       
            Any parameter of HOLES/OPTOPUS command can be defaulted.
	    It is actually possible to default all of them having
	    previously used the SET/OPTOPUS command (see documentation)
	    to select convenient values which will be stored in keywords
	    initialized in Optopus context.
	    It is convenient to flip from the command HOLES/OPTOPUS to
	    the command MODIFY/OPTOPUS and viceversa to check that all
	    the objects in "wrong" position have been actually deleted
	    from HOLES/OPTOPUS input table. One can be sure this has
	    happened when no warning messages are displayed after
	    having issued the command HOLES/OPTOPUS. (See also
	    documentation to MODIFY/OPTOPUS command).
\on\exs
Examples:
\ex
            HOLES/OPTOPUS op1 op2 00,35,43.345 -00,11,53.56 n y 1950,1991.76
\xe\ex
	    HOLES/OPTOPUS op1 op2 ? ? y
\xe\ex
	    HOLES/OPTOPUS ? ? 00,35,43.345 -00,11,53.56 n y 1950,1991.76776
\xe\ex
	    HOLES/OPTOPUS op1 op2 00,35,43.345 -00,11,53.56 Y n
\xe\ex
	    HOLES/OPTOPUS op1 op2
\xe\sxe