Library functions for running WIP within python
Started 12 April 2007 - NLC
First used for a real plot on 19 April 2007
last updated: 13 March 2008 - NLC
    Color Table                        Palettes
======================     ===============================
| key | Description  |     |   key   |    Description    |
----------------------     -------------------------------
|  w  |     white    |     |   bw    |  black and white  |
|  k  |     black    |     |  gray   |     grayscale     |
|  r  |      red     |     | rainbow |   Rainbow scale   |
|  g  |    green     |     |  heat   |     Heat scale    |
|  b  |     blue     |     |  iraf   |     IRAF scale    |
|  c  |     cyan     |     |  aips   |     AIPS scale    |
|  m  |    magenta   |     | pgplot  |    PGPLOT scale   |
|  y  |    yellow    |     |    a    | SAOimage A scale  |
|  o  |    orange    |     |   bb    | SAOimage BB scale |
| gy  | green-yellow |     |   he    | SAOimage HE scale |
| gc  |  green-cyan  |     |   i8    | SAOimage I8 scale |
| bc  |  blue-cyan   |     |   ds    |      DS scale     |
| bm  | blue-magenta |     | cyclic  |    Cyclic scale   |
| rm  | red-magenta  |     -------------------------------
| dg  |  dark gray   |     * can prepend palette keywords with
| lg  |  light gray  |       a minus sign to reverse the scale
    Fill Styles                     Fonts
=======================   =========================
| key |  Description  |   | key |   Description   |
-----------------------   -------------------------
|  s  |    solid      |   |  sf |   sans-serif    |
|  h  |    hollow     |   |  rm | roman (default) |
|  /  |    hatched    |   |  it |     italics     |
|  #  | cross-hatched |   |  cu |     cursive     |
-----------------------   -------------------------
             Symbols                               Line Styles
==================================        ===========================
|  key  |       Description      |        | key  |    Description   |
----------------------------------        ---------------------------
|   s   |         square         |        |   -  |       solid      |
|   .   |           dot          |        |  --  |      dashed      |
|   +   |       plus sign        |        |  .-  |    dot-dashed    |
|   *   |       asterisks        |        |   :  |      dotted      |
|   o   |         circle         |        | -... | dash-dot-dot-dot |
|   x   |          an x          |        ---------------------------
|   ^   |        triangle        |
| oplus |  circle with plus sign |
| odot  |    circle with a dot   |
|  ps   |     pointed square     |
|   d   |        diamond         |
|  st   |    five-point star     |
|  o+   |    open plus symbol    |
| david |     star of david      |
LaTeX is supported in text strings by default.  Note that unlike math mode in
LaTeX, the text is NOT italicized by  default.  LaTeX symbols supported: all
greek symbols, \times, \AA (for angstroms), \odot (for sun symbol),
\oplus (for earth symbol), \pm (for proper +-), \geq (for greater than or
equal to), \leq (for less than or equal to), ^{} (for superscripts),
_{} (for subscripts), \sf{} (for sans-serif font), \rm{} (for roman font),
\it{} (for italics), \cu{} (for cursive)


arc(x, y, majorx, majory, deg=360, start=0, angle=0, fill='s', color=None, style=None, width=None, limits=None, logx=None, logy=None)
Draw a curved line to make circles, ellipses, arcs, etc.
x,y           - central coordinates for arc.  If a string, convert WCS
                into units usable by WIP.  The WCS can be given as
                hh:mm:ss, dd:mm:ss or as degrees.  Note that you don't
                have to give all three parts, you can omit the ss.  x is
                always assumed to be RA and y is always assumed to be DEC.
majorx,majory - major axes for x and y.  Like x,y this can be given as
                a string to specify the WCS.
deg           - draw arc over this many degrees
start         - start drawing at this degree angle measured counter-
                clockwise from +x axis.
angle         - Tilt angle for curve in degrees measured counter-clockwise
                from +x axis.
fill          - a string specifying the fill style
color         - a string with the color of the line
style         - a string specifying the line style
width         - thickness of lines
limits        - If a list/tuple, use as limits.  Otherwise try to use
                any prexisting limits or set new ones
logx          - If True, make logarithmic in x direction.  Otherwise
                default to what has already been set for plot/panel.
logy          - If True, make logarithmic in y direction.  Otherwise
                default to what has already been set for plot/panel
axis(xaxis=None, yaxis=None, color=None, font=None, size=None, style=None, width=None, xtick=None, ytick=None)
Draw the axes.
xaxis,yaxis - wip string for drawing x and y axis.  If left as None,
              then axis function will try to guess something appropriate
              based on panel arrangement and whether log of x or y has
              been taken.  If an image has been plotted, then axis will
              assume you want WCS labeling.
color       - the color of the axis as a string
font        - the font to use for the axis
size        - the size for numbers on axis
style       - the line style
width       - the thickness of the lines
xtick       - tuple of two numbers.  First value is interval between major
              tick marks in x.  Second value is number of minor tick marks
              between each major tick mark.
ytick       - Same as xtick except for y axis
beam(x, y, amajor, aminor, angle=0, scale='ra', color=None, fillcolor=None, style=None, width=None, bg=None)
Draw an ellipse showing a beam.  Useful for radio data.
x,y           - Central coordinates for beam.  If a string, convert WCS
                into units usable by WIP.  The WCS can be given as
                hh:mm:ss, dd:mm:ss or as degrees.
amajor,aminor - major and minor axes for ellipse as arcseconds. Like x,y
                this can be given as a string to specify the WCS.
angle         - tilt angle for ellipse given as degrees from the +x axis
scale         - set to None for no scaling of x axis
color         - color of edge of ellipse
fillcolor     - color of inside of ellipse.  Defaults to color
style         - line style for edge of ellipse
width         - line thickness
bg            - color for background box surrounding beam.  Defaults to
bin(xcol, ycol, datafile=None, color=None, width=None, style=None, limits=None, coord='center', logx=False, logy=False, text=None)
Draw a histogram from previously histogrammed data.
xcol,ycol - either an integer specifying column in datafile or a
            list/tuple of x/y data points
datafile  - string containing filename with data.  Leave as None if
            xcol and ycol are tuples/lists
color     - the color for the histogram
width     - the thickness of the histogram
style     - line style for histogram.  Defaults to solid
limits    - If a list/tuple, use as limits.  Otherwise try to use
            any prexisting limits or set new ones
coord     - are x coordinates the center or left side of the bin?
logx      - If True, make logarithmic in x direction.  Otherwise
            default to what has already been set for plot/panel.
logy      - If True, make logarithmic in y direction.  Otherwise
            default to what has already been set for plot/panel
text      - Text to be used for curve.  Defaults to "Generic Curve"
blowup(xmin, xmax, ymin, ymax, corners=['ll', 'ul'], color=None, style=None, width=None)
Draw a blow-up box around a given region.
Draws a blow-up box around a region and also stores the region limits in
wip registers \9 - \12.  These are used by the connect command to draw
connecting lines from the blowup box to the actual zoomed region.
xmin,xmax,ymin,ymax - four values for limits of blowup box given as
                      pixel values
corners - a two element list of ll,ul,lr, or ur to specify which corners
          of the box to store in memory.  These correspond to lower left,
          upper left,lower right, upper right
color   - a string giving the color for the box
style   - a string giving the linestyle for the box
width   - a number giving the thickness of the line
connect(corners=['ll', 'ul'], color=None, style=None, width=None)
Draw lines connecting a blow-up region to the current viewport coordinates.
corners - a two element list of ll,ul,lr, or ur to specify which corners
          of the box to store in memory.  These correspond to lower left,
          upper left,lower right, upper right
color   - a string giving the color for the box
style   - a string giving the linestyle for the box
width   - a number giving the thickness of the line
contour(image, header, levels, routine='smooth', limits=None, color=None, font=None, style=None, width=None, border=False)
Draw contours with the specified levels.
image   - string with name of image
header  - string with header for image such as rd, px, etc.
levels  - a list/tuple or string of contour levels.  If a string,
          give as min:max:step to specify levels, or as 'border', if
          you just want to draw a box around the border of the image.
routine - how to draw contours: smooth, fast, neg.  neg will draw negative
          contours with the same line style as positive ones.  By default,
          negative contours are drawn dashed.
limits  - If not specified show whole image.  If a list/tuple of
          four numbers, plot given sub-image.  If anything else,
          use limits stored in \1 \2 \3 \4 (set by halftone)
color   - color for contour lines
font    - font for contour labelling (TODO: not supported)
style   - line style for contours
width   - thickness of contour lines
curve(color=None, size=None, style=None, width=None, text=None, fillcolor=None)
Return a generic curve that can be used by a legend.
A curve is a dictionary that is returned by the plot command and can
be used with the legend command to make it easier to make legends.  The
keyword arguments give the default values for the dictionary.
default(color=None, font=None, size=None, style=None, width=None, bg=None, xmargin=None, ymargin=None)
Set default parameters that will be used for everything in the plot.
color  - a string giving the default color
font   - a string giving the default font
size   - a number giving the default size for everything
style  - a string giving the default line style
width  - a number giving the default width of lines
bg     - a string giving the background color for text.  Can set to -1
         for transparent (the default)
xmargin - set space between panels to this number of character units
          in the x direction.  Default is 2.
ymargin - set space between panels to this number of character units
          in the y direction.  Default is 2.
errorbar(xcol, ycol, datafile=None, xerr=None, yerr=None, color=None, size=None, style=None, width=None, limits=None, logx=False, logy=False)
Draw x,y errorbars on some data.
xcol,ycol - Integer or list/tuple of x/y data
datafile  - If a string, read columns xcol and ycol from datafile
xerr      - Integer or list/tuple of x errorbars.  If int, read specified
            column from datafile
yerr      - Integer or list/tuple of y errorbars.  If int, read specified
            column from datafile
color     - A string specifying the color of the errorbars
size      - A number specifying the size of the caps on the errorbars
style     - A string specifying the line style
width     - A number specifying the line thickness
limits    - If a list/tuple, use as limits.  Otherwise try to use
            any prexisting limits or set new ones
logx,logy - If True, plot logarithmic errorbars
halftone(image, header='px', palette='gray', minmax=None, blank=None, limits=None)
Plot a halftone image with specified palette.
Before using this, one should call winadj to make sure your pixels come
out square.
image   - string with name of image
header  - string of header for image such as rd, px, etc.
palette - color palette for halftone
minmax  - list or tuple of (min,max) halftone limits to display
blank   - If set, ignore specified value when making halftone
limits  - If not specified show whole image.  If a list/tuple of
          four numbers, plot given sub-image.  If anything else,
          use limits stored in \1 \2 \3 \4 (set by halftone)
legend(x, y, curves, dx, dy, length, height, align='left', color=None, font=None, size=None, style=None, width=None, bg=None)
Make an entire legend box.
x,y       - starting x and y location for legend
curves    - a list/tuple of dictionarys that were returned by the plot
            or curve functions
dx        - space between line and text for each entry
dy        - offset of line from text for each entry
length    - length of line for each entry
height    - vertical offset between each entry
align     - alignment for text.  left, right, or center
color     - a string giving the color for the text
font      - a string giving the font to use for the text
size      - a number giving the size for text
style     - a string giving the line style for the text
width     - a number giving the thickness of the line
bg        - color for background of text.  Default is transparent
panel(nx, ny, idx)
Switch to panel idx.
There are nx,ny panels in a grid.  If nx or ny is negative, then there
will be no space between panels in that direction.  If idx is negative,
the panels are counted from the upper left downward.  If positive, the
panels are counted from the lower left corner upward.
nx  - Number of panels in x direction.
ny  - Number of panels in y direction.
idx - Current panel number.
plot(xcol, ycol, datafile=None, color=None, size=None, style='o', width=None, fillcolor=None, limits=None, logx=False, logy=False, text='Generic Curve')
Plot data from a file or input lists/tuples.
This function is extremely versatile and can be used to plot data
points and lines.  Note that when specifying column numbers from a file,
columns are counted starting from 1.
xcol,ycol - either an integer, list, or tuple for x/y data points.  If
            integers, these are column numbers to read from the specified
datafile  - string name of input data file.  Leave as None if
            xcol and ycol are a sequence of numbers
color     - If a string, use as the color for every point.  If an integer,
            read that column from the datafile for color index for each
size      - The size for each data point.
style     - If a string, use as the symbol or line style.  If an integer,
            then read from datafile for symbol for each point.
width     - Line width
fillcolor - Color to fill symbols with.  Only available for five-point
            stars, squares, circles, and triangles.  If used inappropriately,
            an error will occur.  Use in the same way as for color keyword.
            Default is 'None' which means no filling will occur (transparent).
limits    - If None, set min/max to values in xcol and ycol.  If a list
            or tuple of xmin,xmax,ymin,ymax, set to specified values.
            If anything else, do not attempt to set any limits (i.e.
            assume they have already been set to something sensible)
logx,logy - If True, take log of x/y values before plotting.  Useful for
            logarithmic plots.  Note that limits must be specified in
            relation to the logarithms to work properly.
text      - A string that can be used for the legend command.  Defaults
            to "Generic Curve"
poly(xcol, ycol, datafile=None, color=None, style=None, width=None, fill='s', limits=None, logx=False, logy=False)
Draw a closed polygon.
xcol,ycol - either an integer, list, or tuple for x/y data points
datafile  - string name of input data file.  Leave as None if
            xcol and ycol are a sequence of numbers
color     - string with color to use for line style and fill
style     - string with line style to draw polygon with
width     - Line width of polygon
fill      - Fill style for polygon
limits    - If None, set min/max to values in xcol and ycol.  If a list
            or tuple of xmin,xmax,ymin,ymax, set to specified values.
            If anything else, do not attempt to set any limits (i.e.
            assume they have already been set to something sensible)
logx      - If True, make logarithmic in x direction.  Otherwise
            default to what has already been set for plot/panel.
logy      - If True, make logarithmic in y direction.  Otherwise
            default to what has already been set for plot/panel
rect(xmin, xmax, ymin, ymax, color=None, style=None, width=None, fill='s', limits=None, logx=False, logy=False)
Draw a rectangle on the figure.
This function uses the poly command behind the scenes.
xmin,xmax,ymin,ymax - the limits of the rectangle
color  - string with color to use for line style and fill
style  - string with line style to draw rectangle with
width  - thickness of line used to draw rectangle
fill   - fill style for rectangle
limits - If a list/tuple, use as limits.  Otherwise try to use
         any prexisting limits or set new ones
logx   - If True, make logarithmic in x direction.  Otherwise
         default to what has already been set for plot/panel.
logy   - If True, make logarithmic in y direction.  Otherwise
         default to what has already been set for plot/panel
savefig(filename, orient='portrait', color='y', debug=0)
Make the output plot by actually running wip.
filename - a string or list/tuple giving the output filename(s) with
           either a .gif or .ps extension
orient   - make plot portrait or landscape orientation?
color    - make plot in color or black and white?
debug    - If 1, do not delete all temp files needed by wip
text(x, y, text, align='left', angle=None, color=None, font=None, size=None, style=None, width=None, logx=False, logy=False, bg=None)
Put a given text label at specified coordinates.
x,y       - coordinates for location of text
text      - a string of text to print out
align     - alignment for label.  Either left, center, or right
angle     - angle is degrees for text
color     - a string giving the color for the label
font      - a string giving the font to use for the label
size      - a number giving the size for label
style     - a string giving the line style for the label
width     - a number giving the width of the lines
logx,logy - If True, take log of x/y coordinates before plotting
bg        - background color for text.  Default is -1 (transparent)
title(text, offset=0, align='center', color=None, font=None, size=None, style=None, width=None, bg=None)
Set the title of the plot to the given text.
text   - a string of text to print out as title of plot
offset - offset for text in addition to standard offset for a title
align  - alignment for label.  Either left, center, or right
color  - a string giving the color for the title
font   - a string giving the font to use for the title
size   - a number giving the size for the title
style  - a string giving the line style for the title
width  - a number giving the width of the lines
bg     - background color for text
vector(xcol, ycol, anglecol, lengthcol, datafile=None, color=None, size=None, width=None, limits=None, logx=None, logy=None)
Draw a vector field.
pcol is a column with the length of each arrow and ecol is the angle for
each arrow, in degrees.
xcol,ycol - either an integer, list, or tuple for x/y data points
anglecol  - either an integer, list, or tuple for direction of arrows
lengthcol - either an integer, list, or tuple for length of arrows
datafile  - string name of input data file.  Leave as None if
            xcol,ycol,pcol,ecol are a sequence of numbers
color     - string with color for each arrow
size      - Size of arrows
width     - Line width of arrows
limits    - If None, set min/max to values in xcol and ycol.  If a list
            or tuple of xmin,xmax,ymin,ymax, set to specified values.
            If anything else, do not attempt to set any limits (i.e.
            assume they have already been set to something sensible)
logx      - If True, make logarithmic in x direction.  Otherwise
            default to what has already been set for plot/panel.
logy      - If True, make logarithmic in y direction.  Otherwise
            default to what has already been set for plot/panel
viewport(xmin, xmax=None, ymin=None, ymax=None)
Use this to set the plot area.
Sometimes WIP gets this wrong and part of your plot is off the page.
winadj can alter these values, but only within the bounds of the viewport.
xmin - either a number or a list/tuple of four numbers
xmax - leave as None if xmin is a list/tuple
ymin - leave as None if xmin is a list/tuple
ymax - leave as None if xmin is a list/tuple
wedge(side, offset, thickness, minmax=None, boxarg=None, color=None, font=None, size=None, style=None, width=None)
Draw a halftone wedge on the image.
This is only useful for halftone images.
side      - string containing side to draw wedge on.  One of left, right,
            top, or bottom
offset    - offset of wedge from side
thickness - thickness of wedge
minmax    - a list/tuple of the min/max values for the wedge.  Defaults
            to whatever min/max was for halftone
boxarg    - argument for box style.  Same as used by axis function
color     - color for the box around the wedge
font      - font for labelling the wedge
size      - size of box labels around wedge
style     - line style for box
width     - thickness of box aroun wedge
winadj(xmin=None, xmax=None, ymin=None, ymax=None, image=None)
Adjust the window so the plot will have the correct aspect ratio.
xmin   - If set, either a number of a list/tuple of four numbers
xmax   - leave as None if xmin is a list/tuple
ymin   - leave as None if xmin is a list/tuple
ymax   - leave as None if xmin is a list/tuple
image  - If a string of an image name (and optionally a subimage defined
         ala IRAF's method : image[xmin:xmax,ymin:ymax], then adjust
         window according to image size.  If limits are defined via
         xmin,xmax,ymin,ymax, then multiply nx and ny pixels in the 
         image by the limits to get the true adjustment
xlabel(text, offset=0, align='center', color=None, font=None, size=None, style=None, width=None, bg=None)
Set the x label to the given text.
text   - a string of text to print out as x axis label
offset - offset for text in addition to standard offset for an x label
align  - alignment for label.  Either left, center, or right
color  - a string giving the color for the label
font   - a string giving the font to use for the label
size   - a number giving the size for label.
style  - a string giving the line style for the label
width  - a number giving the width of the lines
bg     - background color for text
ylabel(text, offset=0, align='center', color=None, font=None, size=None, style=None, width=None, bg=None)
Set the y label to the given text.
text   - a string of text to print out as y axis label
offset - offset for text in addition to standard offset for a y label
align  - alignment for label.  Either left, center, or right
color  - a string giving the color for the label
font   - a string giving the font to use for the label
size   - a number giving the size for label.
style  - a string giving the line style for the label
width  - a number giving the width of the lines
bg     - background color for text