%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990-2006 European Southern Observatory
%.IDENT      load_tabl.hlq
%.AUTHOR     JDP, IPG/ESO
%.KEYWORDS   MIDAS, help files, LOAD/TABLE
%.PURPOSE    On-line help file for the command: LOAD/TABLE
%.VERSION    1.0  17-OCT-1983 : Creation, JDP
%.VERSION    040308	last modif
%----------------------------------------------------------------
\se
SECTION./TABL
\es\co
LOAD/TABLE					9-MAY-2006  JDP, KB
\oc\su
LOAD/TABLE table x y [ident] [symbol] [size] [color] [conn_flag]
	load table into overlay channel of Image Display
\us\pu
Purpose:    
           Load table values in the overlay plane of the Image Display
\up\sy
Syntax:     
           LOAD/TABLE table x y [ident] [symbol] [size] [color] [conn_flag]
\ys\pa
           table = table file name
\ap\pa
           x = column used as abscissa
\ap\pa
           y = column used as ordinate
\ap\pa
           ident = optional column used as reference (char. or numerical)
               if entered, coords with equal identifier value are connected
               by lines - the table must be sorted by this column;
               but the line connection may be overridden by param `conn_flag'
               the contents of the reference column are also drawn unless
               ",NODRAW" is appended to the column label
\ap\pa
           symbol = optional int. symbol code or column holding it:
               negative = draw no symbols
               0,2 = square, 1 = circle, 3 = triangle up, 4 = triangle down,
               5 = cross, 6 = open cross, 7 = diamond, 8 = x-shaped cross;
               100,102 = filled square, 101 = filled circle
               defaulted to 0
\ap\pa
           size = symbol size in pixels or column holding it (default is 3)
\ap\pa
           color = color for symbol or column holding it 
               for colour definition see Note;
               defaulted to 255
\ap\pa
           conn_flag = connection flag, overrides parameter `ident' effect
               = 0, ignore this flag, = 1, connect all table coords.,
               = -1, connect no table coords.; defaulted to 0
\ap\sa
See also:
           PLOT/TABLE, DRAW/RECTANGLE, CLEAR/OVERLAY, CONVERT/RADEC
\as\no
Note:       
           Coordinate conversion from world or pixel values to screen pixels 
	   in the display is done according to the column units.
           The necessary input for the conversion is taken from the currently
           displayed image, so there must be an image loaded!

	   Note, that RA and DEC columns in sexagesimal format (as stored in
	   tables via GET/CURSOR) have to be first converted to decimal world 
	   coords. - e.g. via CONVERT/RADEC (see the last example).

	   Rows with coords of pixels located outside the currently displayed
	   image are skipped. The no. of skipped rows is saved in INPUTI(11).:w


           The following colours are supported via name or number in X11:
           Black(1), White(2), Red(3), Green(4), Blue(5), Yellow (6),
           Magenta(7), Cyan(8) - "colour" 0 is used to erase. 
 
	   If you use option 0 to erase, please choose the same symbol and
	   the same size which you used for the creation.  
           All other values are interpreted as White.
\on\exs
Examples:
\ex
           LOAD/TABLE coords :X_COORD :Y_COORD
             Draw small squares around the positions where we used 
             GET/CURSOR before (with output to table `coords.tbl').
\xe\ex
           LOAD/TABLE coords :xval :yval :ident
             Draw small squares around the positions found in columns :xval 
             and :yval of table `coords.tbl'. Also draw the contents of
             column :ident beside the position. If :ident is the same for 
             several rows, connect all table coords from these rows.
\xe\ex
           LOAD/TABLE coords :xval :yval :ident ? ? ? -1
             As above but do NOT connect any coords even if they have equal
             :ident values.
\xe\ex
           LOAD/TABLE coords :xval :yval :ident,nodraw ? ? ? 1
             As above but connect all coords regardless of what's in column
             :ident and do NOT draw the contents of column :ident.
\xe\ex
           LOAD/TABLE coords :xval :yval ? :symbol 8 4
             Draw green symbols (actual symbol depends upon the elements in 
             integer column :symbol) around the positions specified in columns
             :XVAL and :YVAL of table `coords.tbl'.
\xe\ex
           LOAD/TABLE coords :xval :yval ? 4 8 4 1
             As above but connect all positions with a green line.
\xe\ex
           LOAD/TABLE coords :xval :yval ? 4 8 0 1
             will remove the symbols and line which were drawn by the previous
	     example.	     
\xe\ex
           LOAD/TABLE coords :xval :yval :ident
             Draw small squares around the positions found in columns :xval 
             and :yval of table `coords.tbl'. Also draw the contents of
             column :ident beside the position. If :ident is the same for 
             several rows, connect all table coords from these rows.
\xe\ex
 
	   CONVERT/RADEC wcstest.mt from table coords.tbl,:ra,:dec -
	                 :xcoord,:ycoord
           LOAD/TABLE coords :xcoord :ycoord 
	     First convert :RA, :DEC columns obtained from a GET/CURSOR 
	     command with `wcstest.mt' displayed and output in table 
	     `coords.tbl' to decimal world coords stored in (already existing!)
	     columns :xcoord, :ycoord of `coords.tbl'.
             Then, draw squares around the positions found in :xcoord and 
	     :ycoord of table `coords.tbl' - assuming that `wcstest.mt' is
             still displayed.
\xe\sxe
