Function:     BEAM

Purpose:      Draw elliptical shaded beam (PGPLOT)

Category:     PLOTTING

File:         beam.c

Author:       M. Vogelaar

Use:          INTEGER BEAM( 
                         SET,        Input    character*(*)
                         SUBSET,     Input    integer
                         SPATIAL,    Input    integer
                         DELTA,      Input    double precision array
                         CENTREXY,   Input    double precision array
                         FWHMMAJ,    Input    double precision
                         FWHMMIN,    Input    double precision
                         PA,         Input    double precision
                         LINES,      Input    integer
                         SLOPE       Input    double precision
                         SHAPE )     Input    integer


              BEAM       Returns:
                          0  successful
                         -1  No valid shape selected
                         -2  No sky coordinates found in set
                         -3  Cannot find the grids for this beam!
              SET        GDS set (as returned by GDSINP).
              SUBSET     A single subset (as returned by GDSINP).
              SPATIAL    = 1 if both subset axes are spatial 
                         = 0 other combinations 
              DELTA      Grid spacing in X and Y. In the calling
                         environment this parameter is set to 
                         header values of cdelt or ddelt or
                         the parameter is calculated some other way.
              CENTREXY   X and Y position of centre of ellipse in
                         world coordinates/grids.
              FWHMMAJOR  FWHM major axis of ellipse in degrees!
              FWHMMINOR  FWHM minor axis of ellipse in degrees!
              PA         Position angle of ellipse wrt. north in the 
                         direction of the east, in degrees.
              LINES      Approximation of number of shading lines
                         for ellipse.
              SLOPE      Slope of shading lines in degrees.
                         This slope is defined in the system
                         of the grids i.e. slope = 0 is draws 
                         shading line parallel to the X axis.
              SHAPE      1: Plot shaded ellipse
                         2: Plot rectangle (e.g.IRAS beam)
                         3: Plot cross


Description:  Draw an beam with an elliptical or rectangular shape or a 
              cross with specifications (origin, axes and projection 
              angle). The beam axes are specified in degrees and all 
              calculated ellipse coordinates are transformed to grids 
              using the transformation formulas for sky system and
              projection.  The position angle of the major
              axis is wrt. +m axis. This angle is corrected for the 
              rotation of the image (CROTA). 
              If user wants shading (parallel line pattern only) you can 
              give the slope of the lines (wrt +X axis) in 'SLOPE' and the 
              approximate number of shade lines in 'DELTA'.
              
             
Updates:      Dec  9, 1991: MV,  Document created
              Sep 19, 1994: MV,  Rectangular beam implemented
              Jul  7, 1997: MV,  Cross implemented
              Sep 30, 1997: MV,  Completely rewritten 'pgbeam'.