







		       ASTROPHYSICS DATA SYSTEM
		      GRAPHICAL VISUALIZATION TOOL




   AGRA is an ADS graphics tool for the display and simple analysis
   of tabular, sky-location data. It's sources of data are ASCII EOS
   tables where two of the columns represent sky coordinates
   (in any coordinate system).  AGRA then interactively generates sky
   maps in a variety of sky coordinate systems and map projections
   and with a wide range of colors, sizes, symbol shapes, character
   fonts, and coordinate grid options.

   Formatted table files (FITS) can be accessed by column name and the
   arrays ingested referred to by symbolic variables, simplifying the task
   of organization.

   Because it is meant primarily to be used in conjunction with the ADS
   system, which has very advanced user interface and process executive
   capabilities,  these aspects of this service have been kept to a
   minimum.  The direct interface has a standard verb/argument syntax 
   with simple script running mechanisms.  Such facilities are more 
   amply provided by the core ADS software.



			      FACILITIES

   The following facilities are available in AGRA: 

   Table reading       -- Extract data from table files
   Control functions   -- Control the state of output devices
   Labelling           -- TeX-like strings (XY axis or general labels)
   Interaction         -- Determine cursor position
   Map setup           -- Projections and coordinate systems
   Map drawing         -- Projected grids, markers and polygons
   Map plot attributes -- Colors, linestyles, markers, etc.
   Grid plotting       -- Contouring and projected plotting of 2D grids 




   In these categories we have the following functions:
   

   Table Reading   

      file           -- Data table file (ADS formatted table)
      read           -- Extract data from table file
      header         -- Get a listing of the columns in the table


   Control Functions

      print          -- Print the output to a laser printer
      script         -- Run a script file. In practice, just type the script
			file name, instead of the string "script"
      close          -- Close current device 
      help           -- Interactive command syntax help
      system         -- Suspend program and escape to UNIX
      quit           -- End program




   Interaction

      cursor         -- Return position of cursor



   Map Setup

      projection     -- Map projection associated with the display surface

      dcs            -- Coordinate system of the data table
      pcs            -- Coordinate system of the map
      gcs            -- Coordinate system of the coordinate overlay grid

      pcenter        -- Projection center for the map
      mcenter        -- The location of the map center
      mctype         -- The units used in defining the map center
      rotation       -- Map twist angle 

      apply          -- Apply the scale calculated automatically from the
			data table to be the current plotting range
      scale          -- Set the best fitting range for the known data, and
		        display the current scale 
      size           -- Size of the map in pseudo-angles


   Map Drawing

      map            -- Draw marker symbols on the map surface
      grid           -- Draw coordinate overlay grid on the map surface
      dot            -- Draw a marker at the current map location


   Map Plot Attributes

      expand         -- Set expansion factor for text, markers
      rotate         -- Set relative rotation angle for text, markers
      color          -- Set colour for markers, labels and grid 
      ptype          -- Select from a set of preset markers 
                        or define new polygon symbol for marker(s)


   Map Labelling

      label          -- Write general label




				  COMMANDS

		   Short Descriptions of AGRA Commands
 			 (in alphabetical order)

______________________________________________________________________________


 cd DIR                               Change directory

    CD changes the current working directory to a new directory specified
       by DIR.


______________________________________________________________________________


 close                                 Close current window

   Close the current X window and delete it from the screen.

                                                                 
______________________________________________________________________________


 color CNAME | CINDEX                  Set colour to C 

   COLOR CNAME sets the color to be CNAME.  CNAME must be one of
   "white", "black", "green", "blue", "red", "magenta", "yellow", or
   "cyan".  The default in X-windows is black on white.

   COLOR CINDEX is another way of selecting the same color as are
   available with COLOR CNAME, where the CINDEX is an index into the
   array [white, black, green, blue, red, magenta, yellow, cyan], so
   "COLOR 1" is the same as "COLOR white".

   [Note: "white" has a bug right now.]
                                                                 
______________________________________________________________________________

______________________________________________________________________________


 cursor                                Return position of cursor 

   Interactively pick points and get their locations.  The mouse is
   used as a locator and as many points as are desired may be picked by
   hitting the mouse button.  This mode ends when the user types a
   character at the keyboard.


______________________________________________________________________________


 dcs EQUATORIAL | GALACTIC |           Set coordinate system 
      ECLIPTIC  | SUPERGALACTIC        associated with data from table

   Set the coordinate system of the data read from the table file.

______________________________________________________________________________



 dot                                   Draw a marker at the current location

   Draw a marker at the current location (set by MOVE) in
   the style determined by PTYPE. The point's size and rotation are
   governed by EXPAND and ROTATE.

______________________________________________________________________________



 erase                                 Erase screen

   ERASE erases the current window (but does not delete it).

______________________________________________________________________________


 expand FACTOR                         Set map marker expansion factor 

   MEXPAND expands the markers used by MDOT and MAP by a factor.


______________________________________________________________________________



 file TBLFILE                          Specify table file for input

   FILE specifies the ADS table file to be used by the READ command.



______________________________________________________________________________


 gcs EQUATORIAL | GALACTIC |           Set coordinate system 
      ECLIPTIC  | SUPERGALACTIC        for map coordinate overlay 

   Set the coordinate system associated with the coordinate grid to be
   plotted on the display surface.

______________________________________________________________________________


 grid                                  Generate map overlay coordinate grid

   Draw a coordinate grid on the display surface in the grid coordinate
   system (GCS), projected to the projection coordinate system (PCS).
   Line spacing is determined automatically from the map size (SIZE).

______________________________________________________________________________


 header                                List names of a table column

   HEAD will cause the column names for a specified table to be
   printed out.


_____________________________________________________________________________


 help COMMAND                          Optain help on a command


   HELP (with no arguments) prints out the list of available commands
   and one-line descriptions.  HELP COMMAND prints out a short 
   description (such as this) for the command.

______________________________________________________________________________


 la EQUATORIAL | GALACTIC      |       Set Label Alignment 
     ECLIPTIC  | SUPERGALACTIC |
     UV
    
   "Label Alignment" allows the user to choose the orientation of the
   label. By default, it is "UV", which means the label will appear
   horizontally, aligned with the paper. If a coordinate system is
   chosen instead, the label will be aligned along the latitute lines
   in that system.

______________________________________________________________________________

 label STR                             Write a label 

   MLABEL writes the string STR at the current location (set by MOVE,
   etc). The string's size and angle are determined by EXPAND and
   ANGLE. The character "\" is an escape character and causes the
   following actions:

		   \\x - set mode x
		    \x - set mode x for next char only

		    \r - roman font
		    \g - greek font
		    \s - script font
		    \t - tiny font
		    \i - toggle italics
		    \u - superscript
		    \d - subscript
		    \e - end string

   The string orientation is determined by the local North (i.e., is
   perpendicular to that line) in the coordinate system specified by
   LCS.

______________________________________________________________________________

 lcs EQUATORIAL | GALACTIC      |      Set the coordinate system for 
      ECLIPTIC  | SUPERGALACTIC |      the locator

    
    LCS sets the coordinate system associated with the locator,
    used in picking up points on the screen and defining the
    location of labels.  By default, the locator coordinate
    system is equatorial.

______________________________________________________________________________


 map LON LAT                           Map centered markers

   MAP draws centered markers of the current style (PTYPE), size
   (EXPAND), and rotation (ROTATE) at the map locations in vectors LON
   and LAT.  The markers are oriented with respect to the data
   ccordinate system North (and ROTATE is relative to this direction).

______________________________________________________________________________


 mcenter LON LAT                       Set the map center

   Set the longitude (LON) and latitude (LAT) of the center of the map.
   The coordinate system used is either that of the projection (PCS),
   the data (DCS), the overlay grid (GCS), or is in cartesian pseudo-
   angles.  The choice is made by setting one of these through the
   command MCTYPE.

   The last coordinate system option (UV) is included to simplify 
   interaction with image files (which have their own projection and
   map centers).  A zoomed-in portion of such an image is centered on 
   a point that is a simple linear offset from the image map center.
   Using this system makes it easy to specify the region of interest
   for overlaying such a portion of an image.

______________________________________________________________________________


 mctype PROJ | DATA | GRID | UV        Units used in defining map center

   Set the longitude (LON) and latitude (LAT) in the projection coordinate
   system (see PCS) of the map projection center.  This is not the same as
   the map center (set by MCENTER).

______________________________________________________________________________


 move LON LAT                          Relocate on the map to (LON,LAT)

   Set the current position to (LON,LAT) in map data coordinates without
   drawing a line.

______________________________________________________________________________


 pcenter LON LAT                       Set map projection center

    Set the longitude (LON) and latitude (LAT) in the projection coordinate
    system (see PCS) of the map projection center.  This is not the same as
    the map center (set by MCENTER).


______________________________________________________________________________


 pcs EQUATORIAL | GALACTIC |           Set map projection coordinate system
      ECLIPTIC  | SUPERGALACTIC 

   Set the coordinate system associated with the map projection to be used.

______________________________________________________________________________


 ptype NSIDE STYLE                     Define marker symbol        

   PTYPE NSIDE STYLE causes points to be drawn as NSIDE-sided polygons
   of style STYLE, where:

   STYLE = 0 : open 
           1 : skeletal (center connected to vertices)
           2 : starred
           3 : solid

______________________________________________________________________________


 projection   GNOMONIC  |    AITOFF    |        Set map projection type
	    CYLINDRICAL |

   Mapped data will must be processed through on of the available  
   projections.  This applies to mapped marker symbols (MAP) and coordinate
   grids (GRID).                          

______________________________________________________________________________


 quit                                  End program

   All the windows and files are closed and the program is exited. 

______________________________________________________________________________


 read ARRAY COLNAME                    Read data from table file

   Read a column by name COLNAME into an internal array pointed to 
   by symbolic variable ARRAY.

______________________________________________________________________________


redraw                                        REDRAW/REDO the plotting

   If the current scale does not change, REDRAW will redraw everything
   on the screen. If some map setting does change, this will perform as
   "redo" -- repeat the same sequence of getting current plotting.


______________________________________________________________________________



 size DELTAX DELTAY                    Size of the map in pseudo-angles

   Because of the non-linearities inherent in map projections, it is
   difficult to characterize the size of the map in units that make
   sense to the user (angles) in a way that "feels right".  The method
   we are using derives from imaging, where the size of a pixel at the
   center of the image is given (in effect the gradient at that point)
   as well as the number of pixels.  

   The product of these two is not any real angle, but makes sense to 
   the user and in the small angle limit is a good approximation for 
   the angular extent of the image.  

   Likewise here DELTAX and DELTAY are angles (in degrees) but they 
   should be viewed as the product of the gradient of the map on the
   display surface at the map center with the extent of the display 
   surface.

______________________________________________________________________________


 system COMMAND                        UNIX system escape        
      ! COMMAND     

   Have the system execute the command COMMAND and then return.  If
   SYSTEM is given with no arguments, a shell will be spawned and the
   user can give several commands, ending with 'exit' to return to the
   program.  An exclamation mark ("!") can be used in place of the
   command "system" for the former option (single command escape).

______________________________________________________________________________



window WIN                                 Select output window WIN

   AGRA can handle up to 10 simultaneous windows (numbered 1 through
   10 by default. These windows are dynamic; a number of them can be
   active and bits and pieces of plotting data can be sent to each.


______________________________________________________________________________



				 EXAMPLE



   This example utilizes most of the basic functions of the system.
   It combines mapped point sources, coordinate grids, mapped contours,
   and XY plots into one resultant display.  The steps involved in doing
   this are the following:
   
      o  Read data from a table file containing positions and fluxes 
 	 at two wavelengths for a set of points; 
	
      o  Set up a map area based on the range of positions of the points 
	 and a projection defined by the user; 
	
      o  Map the points onto the screen;
	
      o  Overlay the map with a coordinate grid;



   Read Data from a FITS Table File
   --------------------------------
   In the first part of this example we are going to read data from a
   table file containing positions and fluxes at two wavelengths for a
   set of points.


      file mydata          # My FITS data file
      read ra RAD          # Read the column named RAD into 'ra'
      read dec DECD        # Read the column named DECD into 'dec'
      dcs equatorial       # The data coordinate system cannot 
			   # reliably be inferred from the column names
      read x F12           # Read the column named F12 into 'x'
      read y F25           # Read the column named F25 into 'y'




   Plot Points on a Sky Map
   ------------------------
   In the first part of this example we are going to read data from a
   table file containing positions and fluxes at two wavelengths for a
   set of points, set up a map area based on the range of positions of
   the points and a projection defined by the user, map the points onto
   the screen, and then overlay the map with a coordinate grid.


      projection gnomonic  # We want a Gnomonic projection map
      mcenter ra dec       # Let the map projection center
      size ra dec          #    and size be deduced from the data
      ptype 4 0            # We'll use square points
      map ra dec           # Put the points on the sky




   Overlay with Coordinate Grid
   ----------------------------
   We will use a different coordinate system for the coordinate grid
   (a Galactic grid on this Equatorial map).


      gcs galactic         # The coordinate overlay grid will be galactic
      grid                 # Generate the coordinate overlay grid


