windt library - General purpose routines

Last Updated: 13-Oct-1998

New routines and those that have changed since the last release (May-1998) are marked with an asterix.


List of Routines


Routine Descriptions

ATOMIC_WEIGHT

[Next Routine] [List of Routines]

 NAME:

      ATOMIC_WEIGHT

 PURPOSE:

      Function to return the atomic weight of specified chemical
      elements.

 CALLING SEQUENCE:

      Result=ATOMIC_WEIGHT(SYMBOL)
 
 INPUTS:

      SYMBOL - A string or string array specifying the name or names
               of the chemical elements. Each element of SYMBOL must
               be a one or two character string, corresponding to the
               chemical symbol of the atom.  Case is ignored.

 KEYWORD PARAMETERS:

      ALL - Set this to return all 92 atomic weights and symbols.

 OUTPUTS:

      Result - The atomic weight of the specified atom or atoms.

 RESTRICTIONS:

      Only the first 92 elements are available.

 PROCEDURE:

      The mass of the proton is first calculated using quantum field
      theory, and then...actually, it's just a lookup table.

 EXAMPLE:

      Print the atomic weight of carbon:

      print,ATOMIC_WEIGHT('C')

 MODIFICATION HISTORY:

      David L Windt, Bell Labs, May 1997
      windt@bell-labs.com

(See atomic_weight.pro)


BESELI_FRACT

[Previous Routine] [Next Routine] [List of Routines]

 NAME:

       BESELI_FRACT

 PURPOSE:

       This function returns the Modified Bessel Function of the
       First Kind of Order N, for any N, i.e., including fractional
       and negative orders.

 CALLING SEQUENCE:

        Result = BESELI_FRACT(X, N)


 INPUTS:
 
       X - The value for which the I Bessel function is required. X
           must be greater than 0. The result will have the same
           dimensions as X.
        
       N - The Bessel function order.

 PROCEDURE:

       The series expansion

       I_n(x) = SUM_(k=0->inf) [ (x/2)^(n+2k) / k! Gamma(n+k+1) ]

       is used, and is terminated when the k'th term is less than .001.

 MODIFICATION HISTORY:

       David L. Windt, Bell Laboratories, June 1993
       windt@bell-labs.com

(See beseli_fract.pro)


BESELK_FRACT

[Previous Routine] [Next Routine] [List of Routines]

 NAME:

       BESELK_FRACT

 PURPOSE:

       This function returns the Modified Besel Function of the Second
       Kind of order N, for any N, i.e., including fractional and
       negative orders.

 CALLING SEQUENCE:

        Result = BESELK_FRACT(X, N)


 INPUTS:

       X - The value for which the K Bessel function is required. X
           must be greater than 0. The result will have the same
           dimensions as X.
        
       N - The Bessel function order.

 PROCEDURE:

       This function uses the BESELI_FRACT function:

       Results=(BESELI_FRACT(X,-N)-BESELI_FRACT(X,B))*!PI/2./SIN(N*!PI)

 MODIFICATION HISTORY:

       David L. Windt, Bell Laboratories, June 1993
       windt@bell-labs.com

(See beselk_fract.pro)


CHEM2LBL

[Previous Routine] [Next Routine] [List of Routines]

 NAME:

      CHEM2LBL

 PURPOSE:

      Convert a 'chemical name', i.e. a string containing characters
      and numbers - H2O, for example - into a string containing
      formatting commands so that the numbers become subscripts when
      using the result in IDL graphics.

      For example: "H2O" would come back as "H!d2!nO".

 CALLING SEQUENCE:

      Result = CHEM2LBL(CHEMICAL)
 
 INPUTS:

     CHEMICAL - a string specifying the chemical name

 KEYWORD PARAMETERS:
 
     NOREFERENCE - if this keyword is set, text following an
                   underscore character in CHEMICAL will be
                   ignored.  The default behavior is that
                   any text following an underscore character
                   will be surrounded by brackets (i.e. < >)
                   and subscripted.  For example, "SiO2_tetragonal"
                   will be returned as "!nSiO!d2 !n"

 MODIFICATION HISTORY:

     David L. Windt, March 1997
     windt@bell-labs.com

(See chem2lbl.pro)


CHISQR

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
            CHISQR

 PURPOSE:

            Compute the Chi Square statistic of a function and a fit
            to the function.  

 CALLING SEQUENCE:
 
            Result=CHISQR(Y,SIGMA_Y,YFIT)
            
 INPUTS:
            Y - Input array.
            
            SIGMA_Y - Uncertainty in Y.
            
            YFIT - Fit to Y.

 PROCEDURE:
 
           CHISQR=TOTAL((Y-YFIT)^2/SIGMAY^2)

 MODIFICATION HISTORY:
 
    David L. Windt, Bell Labs, November 1989
    windt@bell-labs.com

(See chisqr.pro)


CLEAR

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
 
        CLEAR
        
 CATEGORY:
 
       Stupid little convenience routines.
   
 PURPOSE:
 
        Clear the screen, just like the Unix command.
        
 CALLING SEQUENCE:
 
       CLEAR

 RESTRICTIONS:

       Only works on Unix platforms.
        
 MODIFICATION HISTORY:

       David L. Windt, Bell Labs, November 1989
       windt@bell-labs.com

(See clear.pro)


CONT_IMAGE

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
 
       CONT_IMAGE
        
 PURPOSE:
 
       Overlay an image and a contour plot.
        
 CALLING SEQUENCE:
 
        CONT_IMAGE, IMAGE[,X,Y]
        
 INPUTS:
 
       IMAGE - 2 dimensional array to display.
        
 OPTIONAL INPUTS:
 
        X - 1 dimensional array of x-axis values.
        
        Y - 1 dimensional array of y-axis values.
        
 KEYWORD PARAMETERS:
 
       WINDOW_SCALE - Set to scale the window size to the image size,
                      otherwise the image size is scaled to the
                      window size.  Ignored when outputting to
                      devices with scalable pixels.
                
       ASPECT - Set to retain image's aspect ratio.  Assumes square
                pixels.  If WINDOW_SCALE is set, the aspect ratio is
                retained.
                
       INTERP - set to bi-linear interpolate if image is resampled.
        
       NOCONTOUR - set to just display framed image.
        
       INVERT - set to invert the image scale, ie image=255-image
        
       TOP - The maximum value of the scaled image. If not set, then
             it's set to (!d.n_colors < 255)-1.

       MIN_VALUE - The minimum value of IMAGE to be displayed.

       MAX_VALUE - The maximum value of IMAGE to be displayed.

       COLORBAR - Set to display a color bar alongside the image.

       BAR_TITLE - A text string to be used as the colorbar title if
                   COLORBAR is set.

       BAR_WIDTH - Width of the colorbar, in pixels. Default is 10
                   pixels for non-scalable pixel devices, or 2% of
                   the plot width for scalable pixel devices.
 
        
 MODIFICATION HISTORY:

       Adapted (i.e. stolen) from IMAGE_CONT.
        
       D. L. Windt, Bell Laboratories, Nov 1989.
        
       April 1994:
       Changed image scaling to go from 32 to !d.n_colors, so that
       TEK_COLOR can be called to use first 32 colors for other plotting.
        
       Added _EXTRA keyword.

       March 1998 - Added TOP, MIN_VALUE, MAX_VALUE, COLORBAR, and
                    BAR_TITLE keywords.  Also fixed quite a few bugs.
                    Note that setting the XSTYLE, XTYPE, YSTYLE, and
                    YTYPE keywords has no effect: these parameters
                    are always set to 0,1,0, and 1, respectively.

       August 1998 - Plots are now drawn properly when !p.multi is
                     different from 0. Added BAR_OFFSET keyword.

        windt@bell-labs.com
        

(See cont_image.pro)


CONT_IMAGE2

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
 
        CONT_IMAGE2
        
 PURPOSE:
 
        Display an image and overlayer the contours from a second image.
        
 CALLING SEQUENCE:
 
        CONT_IMAGE2, IMAGE1, IMAGE2, X, Y
        
 INPUTS:
 
        IMAGE1 = Image to display.
        
        IMAGE2 = Image from which contours are drawn.
        
 KEYWORD PARAMETERS:
 
        WINDOW_SCALE = set to scale the window size to the image size,
                otherwise the image size is scaled to the window size.
                Ignored when outputting to devices with scalable pixels.
                
        ASPECT = set to retain image's aspect ratio.  Assumes square
                pixels.  If /WINDOW_SCALE is set, the aspect ratio is
                retained.
                
        INTERP = set to bi-linear interpolate if image is resampled.
        
        Plus IDL graphics keywords: XTITLE, YTITLE, SUBTITLE, TITLE
        
 PROCEDURE:
 
        If the device has scalable pixels then the image is written over the
       plot window.
        
 MODIFICATION HISTORY:
 
        Adapted (i.e. stolen) from IMAGE_CONT
        
        D. L. Windt, Bell Laboratories, June 1991.
        
        April 1994:
        Changed image scaling to go from 32 to !d.n_colors, so that
        TEK_COLOR can be called to use first 32 colors for other plotting.
        Added _EXTRA keyword.

        windt@bell-labs.com
        

(See cont_image2.pro)


CURVE_LABEL

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
       CURVE_LABEL

 PURPOSE:

       Draw labels close to one or more (up to 30) curves that have
       been previously plotted.

 CALLING SEQUENCE:

       CURVE_LABEL,X,Y1,[Y2,Y3,Y4,Y5],LABELS=LABELS, $
                  [COLOR=COLOR,XPOSITION=XPOSITION,YOFFSET=YOFFSET]
 
 INPUTS:
       X - xaxis vector (1D array)
       Y1 - 1st y axis vector to be labelled.

 OPTIONAL INPUTS:
       Y2 - 2nd y axis vector to be labelled.
       Y3 - 3rd y axis vector to be labelled.
       ....etc....
        
 KEYWORD PARAMETERS:

       LABELS - String array of labels.  The size of the LABELS array
                must match the number of y variables passed.  This
                keyword is required.

       XPOSITION - A scalar variable specifying where along the x
                   axis the labels are to be drawn, in normal
                   coordinates.  Default = 0.25.  Unless the
                   NO_REPOSITION keyword is set, this might get
                   changed if the procedure determines that the
                   labels are too close together when drawing
                   multiple labels.  Setting XPOSITION to -1
                   will inhibit drawing the curve label altogether.

       YOFFSET - A scalar specifying the distance in Y between the
                 labels and the curves, in normal
                 coordinates. Default = 0.01

       NO_REPOSITION - Set this to inhibit moving the label positions
                       if the labels are too close together when
                       drawing multiple labels.

       COLOR - Integer array of color indices for the labels.

       _EXTRA - The idl _EXTRA keyword, for additional graphics
                keywords to the XYOUTS procedure.
       

 PROCEDURE:

       All labels are lined up at one point along the xaxis.  The
       procedure will try to find a position along the xaxis for
       which the labels are not too close to each other.  If it fails
       at this, it will just stick the labels at x=0.25 (normal).

 EXAMPLE:

       To label a plot containing three curves, try something like
       this:

       plot,x,y1,/nodata
       oplot,x,y1,color=2
       oplot,x,y2,color=3
       oplot,x,y3,color=4
       curve_label,x,y1,y2,y3,labels=['Y1','Y2','Y3'],color=[2,3,4]

 MODIFICATION HISTORY:

       David L. Windt, Bell Labs, March, 1997.
       windt@bell-labs.com

       February, 1998 - Added the ability to inhibit labelling
       the curve by specifying a value of -1 for XPOSITION.

(See curve_label.pro)


CW_CURVE_LABEL

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
       CW_CURVE_LABEL

 PURPOSE:

       A compound widget used to select the position for a curve
       label; this widget is intended to be used in conjunction with
       the CURVE_LABEL procedure in this directory, in that this
       widget lets the user select a value from a slider from 0 to
       one, corresponding to the XPOSITION keyword in CURVE_LABEL.
      
 CATEGORY:
 
        Compound widgets.

 CALLING SEQUENCE:
 
        Result = CW_CURVE_LABEL(PARENT)

 INPUTS:
 
       PARENT - The ID of the parent widget.  

 KEYWORD PARAMETERS:
 
        UVALUE - Supplies the user value for the widget.

       VALUE - Initial value for the widget: a floating point between
               0 and 1, corresponding to the XPOSITION keyword in
               CURVE_LABEL.
 
       TITLE - A title for the widget. 

       FRAME - Set to draw a frame around the widget; ignored if
               PARENT is present.

       FORMAT - Format string for CW_FSLIDER (default is F5.3)

       FONT - Fonts to use for labels and buttons.

       DONE - Set this to add a Done button, in addition to the
              standard Apply button.
 
 OUTPUTS:
 
       The ID of the created widget is returned.

 PROCEDURE/EXAMPLE:

         A slider widget is created in which the user can select a
         position value.  By pressing the "Apply" button, an event is
         returned, allowing the calling procedure to redraw the
         curve label if desired.

         This widget generates an event when the user presses the
         Apply button or the Done button, if present. The EVENT.TAG
         keyword will return either "APPLY" or "DONE" accordingly.

 MODIFICATION HISTORY:
 
       David L. Windt, Bell Labs, April 1997
       windt@bell-labs.com

(See cw_curve_label.pro)


CW_DRAWSIZE

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
       CW_DRAWSIZE

 PURPOSE:
 
       A compound widget used to change the size of an existing
       draw widget.  The widget contains fields for the X and Y
       draw size (in pixels), an Apply button, and optionally a
       Done button.
      
 CATEGORY:
 
        Compound widgets.

 CALLING SEQUENCE:
 
        Result = CW_DRAWSIZE(PARENT,DRAW_WIDGET)

 INPUTS:
 
       PARENT - The ID of the parent widget.  

       DRAW_WIDGET - The id of the draw widget being resized.
 
 KEYWORD PARAMETERS:
 
        UVALUE - Supplies the user value for the widget.
 
       FRAME - set to draw a frame around the widget; ignored if
               PARENT is present.

       ROW - set to place the two window size fields (x,y) in a row.
 
       COLUMN - set to place the two window size fields (x,y) in a column.

       FONT - fonts to use for labels and buttons.

       DONE - set this to add a Done button, in addition to the standard
              Apply button.

       NO_RETURN - The default behavior is that the user must press
                    after entering new values.  Set this
                   keyword so that an event is returned even if the
                   user just changes a value and then moves the
                   cursor outside of the text entry area.

 OUTPUTS:
 
       The ID of the created widget is returned.

 PROCEDURE/EXAMPLE:

         A widget is created in which the user can specify the X and Y
         draw widget size in pixels.   By pressing the "Apply" button,
         the draw widget is resized, and an event is returned, allowing
         the calling procedure to repaint the window if desired.

         This widget generates an event when the user presses the
         Apply button or the Done button, if present. The EVENT.TAG
         keyword will return either "APPLY" or "DONE" accordingly.

 MODIFICATION HISTORY:
 
       David L. Windt, Bell Labs, March 1997
       windt@bell-labs.com

       DLW, June 1997, Added NO_RETURN keyword.

       DLW, Sep 1997, Fixed bug that caused initial values of X and Y
       pixel sizes to be displayed as floating point values rather
       than integers.
       

(See cw_drawsize.pro)


CW_FIELD

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
        CW_FIELD

 PURPOSE:
        This widget cluster function manages a data entry field widget.
        The field consists of a label and a text widget.  CW_FIELD's can
        be string fields, integer fields or floating-point fields.  The
        default is an editable string field.

 CATEGORY:
        Widget Clusters.

 CALLING SEQUENCE:
        Result = CW_FIELD(Parent)

 INPUTS:
        Parent: The widget ID of the widget to be the field's parent.

 KEYWORD PARAMETERS:
        TITLE:  A string containing the text to be used as the label for the
                field.  The default is "Input Field:".

        VALUE:  The initial value in the text widget.  This value is
                automatically converted to the type set by the STRING,
                INTEGER, and FLOATING keywords described below.

        UVALUE: A user value to assign to the field cluster.  This value
                can be of any type.

        FRAME:  The width, in pixels, of a frame to be drawn around the
                entire field cluster.  The default is no frame.

RETURN_EVENTS:  Set this keyword to make cluster return an event when a
                 is pressed in a text field.  The default is
                not to return events.  Note that the value of the text field
                is always returned when the WIDGET_CONTROL, field, GET_VALUE=X
                command is used.

   ALL_EVENTS: Like RETURN_EVENTS but return an event whenever the
                contents of a text field have changed.

        COLUMN: Set this keyword to center the label above the text field.
                The default is to position the label to the left of the text
                field.

        ROW:    Set this keyword to position the label to the left of the text
                field.  This is the default.

        XSIZE:  An explicit horizontal size (in characters) for the text input
                area.  The default is to let the window manager size the
                widget.  Using the XSIZE keyword is not recommended.

        YSIZE:  An explicit vertical size (in lines) for the text input
                area.  The default is 1.

        STRING: Set this keyword to have the field accept only string values.
                Numbers entered in the field are converted to their string
                equivalents.  This is the default.

     FLOATING:  Set this keyword to have the field accept only floating-point
                values.  Any number or string entered is converted to its
                floating-point equivalent.

      INTEGER:  Set this keyword to have the field accept only integer values.
                Any number or string entered is converted to its integer
                equivalent (using FIX).  For example, if 12.5 is entered in
                this type of field, it is converted to 12.

        LONG:   Set this keyword to have the field accept only long integer
                values.  Any number or string entered is converted to its
                long integer equivalent (using LONG).

        FONT:   A string containing the name of the X Windows font to use
                for the TITLE of the field.

    FIELDFONT:  A string containing the name of the X Windows font to use
                for the TEXT part of the field.

        NOEDIT: Normally, the value in the text field can be edited.  Set this
                keyword to make the field non-editable.
                
   NO_RETURN:  The default behavior is that the user must press
                after entering new values.  Set this
               keyword so that an event is returned even if the
               user just changes a value and then moves the
               cursor outside of the text entry area.

     TEXT_ID:  The widget id of the text widget.

 OUTPUTS:
        This function returns the widget ID of the newly-created cluster.

 COMMON BLOCKS:
        None.

 PROCEDURE:
        Create the widgets, set up the appropriate event handlers, and return
        the widget ID of the newly-created cluster.

 EXAMPLE:
        The code below creates a main base with a field cluster attached
        to it.  The cluster accepts string input, has the title "Name:", and
        has a frame around it:

                base = WIDGET_BASE()
                field = CW_FIELD(base, TITLE="Name:", /FRAME)
                WIDGET_CONTROL, base, /REALIZE

 MODIFICATION HISTORY:
        Written by:     Keith R. Crosley   June 1992
                        KRC, January 1993 -- Added support for LONG
                                             integers.
                        AB, 7 April 1993, Removed state caching.
                        JWG, August 1993, Completely rewritten to make
                                use of improved TEXT widget functionality
                        ACY, 25 March, 1994, fix usage of FRAME keyword
                       KDB, May 1994, Initial value =0 would result
                                      in a null text field. Fixed
                                      keyword check.
                       David L. Windt, Bell Labs, June 1997,
                       Added NO_RETURN keyword.
                       David L. Windt, Bell Labs, March 1998,
                       Added TEXT_ID keyword.
                       windt@bell-labs.com

(See cw_field.pro)


CW_PLOTAXES

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
       CW_PLOTAXES

 PURPOSE:
 
       A compound widget used to change the type, range and style
       (bit 0) values of one or more plot axis structure variable.  A
       CW_PLOTAXIS (single axis) widget is created for each element
       of the LABELS input parameter. The widget also includes an
       Apply button, and (optionally) a Done button.
      
 CATEGORY:
 
        Compound widgets.

 CALLING SEQUENCE:
 
        Result = CW_PLOTAXES(PARENT,LABELS)

 INPUTS:
 
       PARENT - The ID of the parent widget.  

       LABELS - A string array of labels to be drawn to the left (or
                top) of each of the CW_PLOTAXIS widgets.

 OPTIONAL KEYWORD PARAMETERS:
 
        UVALUE - Supplies the user value for the widget.
 
       FRAME - Set to draw a frame around the widget.

       VALUE - An (n,4) array of initial values, where
               n = n_elements(LABELS), and each row has
               the form VALUE(i,*)=[type,min,max,style]

       FONT - Font keyword for labels etc.

       ROW - Set to create a row of column-oriented CW_PLOTAXIS widgets.

       COLUMN - Set to create a column of row-oriented CW_PLOTAXIS
                widgets. (default)
 
       DONE - Set this to add a Done button, in addition to the standard
              Apply button.

       AXIS_IDS - An array of widget id's for the individual
                  CW_PLOTAXIS widgets.

       X_SCROLL_SIZE, Y_SCROLL_SIZE - if these values are non-zero,
                                      then the base widget which
                                      holds the CW_PLOTAXIS widgets
                                      will include scroll bars.

       NO_RETURN - The default behavior is that the user must press
                    after entering new values.  Set this
                   keyword so that new values are accepted even if
                   the user just changes a value and then moves the
                   cursor outside of the text entry area.

 OUTPUTS:
 
       The ID of the created widget is returned.

 PROCEDURE/EXAMPLE:

         The idea is that this cw would be used in a widget intended
         to allow the user to interactively adjust the settings for a
         plot.  For instance, you might have a menu item such as Plot
         Options->Scaling, which would create a popup widget
         containing a CW_PLOTAXES subwidget for the X and Y plot
         variables.  When the user makes changes to the Type, Range,
         and Style values, and then presses the Apply button, the
         popup widget event handler would re-draw the plot
         accordingly.

         This widget generates an event when the user presses the
         Apply button or the Done button, if present. The EVENT.TAG
         keyword will return either "APPLY" or "DONE" accordingly.

         Example:
 
         axes=CW_PLOTAXES(BASE,['X','Y'],/DONE, $
                      VALUE=TRANSPOSE([[FLTARR(4)],[FLTARR(4)]]))

 MODIFICATION HISTORY:
 
       David L. Windt, Bell Labs, March 1997
       windt@bell-labs.com

       DLW, June 1997, Added NO_RETURN keyword.

(See cw_plotaxes.pro)


CW_PLOTAXIS

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
 
       CW_PLOTAXIS

 PURPOSE:
 
       A compound widget used to change the type, range and style
       (bit 0 only) values of plot axis structure variable.
      
 CATEGORY:
 
        Compound widgets.

 CALLING SEQUENCE:
 
        Result = CW_PLOTAXIS(PARENT,LABEL)

 INPUTS:
 
       PARENT - The ID of the parent widget.  

       LABEL - a label to be drawn to the left of the widget.

 OPTIONAL KEYWORD PARAMETERS:
 
        UVALUE - Supplies the user value for the widget.
 
       FRAME - set to draw a frame around the widget.

       VALUE - a 4-element array of the form [type,min,max,style].
               type and min,max correspond to the !axis.type and
               !axis.range variables, and style is bit 0 of
               !axis.style.

       FONT - font keyword for labels etc.
       
       ROW - set to orient the subwidgets in a row (default.)

       COLUMN - set to orient the subwidgets in a column.

       NO_RETURN - The default behavior is that the user must press
                    after entering new values.  Set this
                   keyword so that new values are accepted even if
                   the user just changes a value and then moves the
                   cursor outside of the text entry area.

 OUTPUTS:
 
       The ID of the created widget is returned.

 PROCEDURE/EXAMPLE:

       The idea is that one or more instances of this cw would be
       used in a widget intended to allow the user to interactively
       adjust the settings for a plot.  For instance, you might have
       a menu item such as Plot Options->Scaling, which would create
       a popup widget containing CW_PLOTAXIS subwidgets for the X and
       Y plot variables.  When the user makes changes to the Type,
       Range, and Style values, the popup widget event handler would
       re-draw the plot accordingly.

       The widget returns events when any of it's children generate
       events.  The returned event has the form
       {CW_PLOTAXIS_EVENT,ID:id,TOP:top,HANDLER:handler,TAG:tag}
       where TAG indicates which child widget generated the event:
       possible values for EVENT.TAG are TYPE, MIN, MAX, and STYLE.

       NOTE: you probably really want to use the CW_PLOTAXES (plural)
       widget, not this one.

 MODIFICATION HISTORY:
 
       David L. Windt, Bell Labs, March 1997
       windt@bell-labs.com

       DLW, June 1997, Added NO_RETURN keyword.

       DLW, November 1997, Text fields for Range values are now
       updated when the user makes a change; the specified values are
       converted to floating point.
       

(See cw_plotaxis.pro)


CW_PLOTLABEL

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
 
       CW_PLOTLABEL

 PURPOSE:

       A compound widget used to select the position for a plot label
       or legend.  This widget is intended to be used in conjunction
       with the PLOT_TEXT or LEGEND procedures in this directory, in
       that this widget lets the user select one of 13 pre-defined
       positions corresponding to the POSITION keyword in PLOT_TEXT
       and LEGEND.
      
 CATEGORY:
 
        Compound widgets.

 CALLING SEQUENCE:
 
        Result = CW_PLOTLABEL(PARENT)

 INPUTS:
 
       PARENT - The ID of the parent widget.  

 KEYWORD PARAMETERS:
 
        UVALUE - Supplies the user value for the widget.

       VALUE - initial value for the widget: an integer between 0 and
               12, corresponding to the POSITION keyword in plot_text
               or legend.
 
       TITLE - a title for the widget. 

       FRAME - set to draw a frame around the widget; ignored if
               PARENT is present.

       FONT - fonts to use for labels and buttons.

       DONE - set this to add a Done button, in addition to the standard
              Apply button.
 
       NO_BELOW - set this to inhibit drawing the three buttons that
                  correspond to label positions below the plot, i.e.,
                  position values of 1, 2 and 3.

 OUTPUTS:
 
       The ID of the created widget is returned.

 PROCEDURE/EXAMPLE:

         A widget is created in which the user can select one of 13
         position values.  By pressing the "Apply" button, an event
         is returned, allowing the calling procedure to redraw the
         plot label or legend if desired.

         This widget generates an event when the user presses the
         Apply button or the Done button, if present. The EVENT.TAG
         keyword will return either "APPLY" or "DONE" accordingly.

 MODIFICATION HISTORY:
 
       David L. Windt, Bell Labs, April 1997
       windt@bell-labs.com

(See cw_plotlabel.pro)


CW_PLOTSTYLE

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
 
       CW_PLOTSTYLE

 PURPOSE:
 
       A compound widget used to set values for the graphics keywords
       COLOR, LINESTYLE, THICK, PSYM, and SYMSIZE.
      
 CATEGORY:
 
        Compound widgets.

 CALLING SEQUENCE:
 
        Result = CW_PLOTSTYLE(PARENT,LABEL)

 INPUTS:
 
       PARENT - The ID of the parent widget.  

       LABEL - a label to be drawn to the left (or top, for /column)
               of the widget.

 OPTIONAL KEYWORD PARAMETERS:
 
        UVALUE - Supplies the user value for the widget.

       VALUE - an array of initial values:
               [COLOR,LINESTYLE,THICK,PSYM,SYMSIZE]

       FRAME - set to draw a frame around the widget.
       
       FONT - font keyword for labels etc.

       ROW - set to orient the subwidgets in a row (default.)

       COLUMN - set to orient the subwidgets in a column.

       NO_PSYM - set to delete the PSYM and SYMSIZE widgets. If set,
                 PSYM=0 and SYMSIZE=0 will be returned when using
                 WIDGET_CONTROL,GET_VALUE; PSYM and SYMSIZE are
                 ignored when using WIDGET_CONTROL,SET_VALUE

 OUTPUTS:
 
       The ID of the created widget is returned.

 PROCEDURE/EXAMPLE:

       The idea is that one or more instances of this cw would be
       used in a widget intended to allow the user to interactively
       adjust the settings for a plot.  For instance, you might have
       a menu item such as Plot Options->Styles, which would create a
       popup widget containing CW_PLOTSTYLE subwidgets for each of
       the variables being plotted.  When the user makes changes to
       the Color, Linestyle, Thick, Psym, and Symsize values, the
       popup widget event handler would re-draw the plot accordingly.
 
       The user is presented with:

       - a droplist of color choices, by name, referring to the first
         19 colors (i.e., the ones I was able to describe by name)
         defined by the TEK_COLOR procedure.  It's therefore
         necessary for the plotting program to call TEK_COLOR before
         drawing the plot using these color settings.

       - a droplist of linestyle choices.

       - a droplist of thickness choices, from 1 to 9

       - a droplist of psym choices, by name.

       - a droplist of symsize choices, from 0.25 to 2.00, in
         0.25 increments.

       The widget returns events when any of it's children generate
       events.  The returned event has the form
       {CW_PLOTSTYLE_EVENT,ID:id,TOP:top,HANDLER:handler,TAG:tag}
       where TAG indicates which child widget generated the event:
       Possible values for EVENT.TAG are COLOR, LINESTYLE, THICK
       PSYM, and SYSMSIZE.

       NOTE: you probably really want to use the CW_PLOTSTYLES (plural)
       widget, not this one.

 MODIFICATION HISTORY:
 
       David L. Windt, Bell Labs, March 1997
       windt@bell-labs.com

(See cw_plotstyle.pro)


CW_PLOTSTYLES

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
 
       CW_PLOTSTYLES

 PURPOSE:
 
       A compound widget used to set values for the graphics keywords
       COLOR, LINESTYLE, THICK, PSYM, and SYMSIZE, for several plot
       variables.  A CW_PLOTSTYLE (single variable) widget is created
       for each element of the LABELS input parameter. The widget
       also includes an Apply button, and (optionally) a Done button.
      
 CATEGORY:
 
        Compound widgets.

 CALLING SEQUENCE:
 
        Result = CW_PLOTSTYLES(PARENT,LABEL)

 INPUTS:
 
       PARENT - The ID of the parent widget.  

       LABELS - a string array of labels to be drawn to the left
               (or top) of each of the CW_PLOTSTYLE widgets.

 OPTIONAL KEYWORD PARAMETERS:
 
        UVALUE - Supplies the user value for the widget.

       VALUE - an (n,5) array of initial values, where 
               n = n_elements(LABELS), and each row has
               the form VALUE(i,*)=[color,linestyle,thick,psym,symsize]

       FRAME - set to draw a frame around the widget.
       
       FONT - font keyword for labels etc.

       ROW - set to create a row of column-oriented CW_PLOTSTYLE widgets.

       COLUMN - set to create a column of row-oriented CW_PLOTSTYLE
                widgets. (default)
 
       DONE - set this to add a Done button, in addition to the standard
              Apply button.

       STYLE_IDS - an array of widget id's for the individual
                   CW_PLOTSTYLE widgets.

       X_SCROLL_SIZE, Y_SCROLL_SIZE - if these values are non-zero,
                                      then the base widget which
                                      holds the CW_PLOTSTYLE widgets
                                      will include scroll bars.


 OUTPUTS:
 
       The ID of the created widget is returned.

 PROCEDURE/EXAMPLE:

         The idea is that this compound widget would be used in a
         widget intended to allow the user to interactively adjust
         the style settings for several variables contained in a
         plot.  For instance, you might have a menu item such as Plot
         Options->Styles, which would create a popup widget
         containing a CW_PLOTSTYLES subwidget, allowing the user to
         affect each of the variables in the plot.  When the user
         makes changes to the Color, Linestyle, Thick, Psym, and
         Symsize values, the popup widget event handler would re-draw
         the plot accordingly.
 
         This widget generates an event when the user presses the
         Apply button or the Done button, if present. The EVENT.TAG
         keyword will return either "APPLY" or "DONE" accordingly.

         Example:

         style=CW_PLOTSTYLE(BASE,['A','B'],/DONE, $
                            VALUE=TRANSPOSE([[FLTARR(5)],[FLTARR(5)]]))

 MODIFICATION HISTORY:
 
       David L. Windt, Bell Labs, March 1997
       windt@bell-labs.com

(See cw_plotstyles.pro)


CW_PLOTTITLE_CHAR

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
 
       CW_PLOTTITLE_CHAR

 PURPOSE:
 
       A compound widget used to set values for the graphics keywords
       CHARSIZE, SUBTITLE, and TITLE.  The widget contains fields for
       these parameters, an Apply button, and (optionally) a Done
       button.
      
 CATEGORY:
 
        Compound widgets.

 CALLING SEQUENCE:
 
        Result = CW_PLOTTITLE_CHAR(PARENT)

 INPUTS:
 
       PARENT - The ID of the parent widget.  

 OPTIONAL KEYWORD PARAMETERS:
 
        UVALUE - Supplies the user value for the widget.
 
       FRAME - set to draw a frame around the widget.

       VALUE - a structure, containing initial values for
               the charsize, subtitle and title fields, of
               the form {charsize:_float_, subtitle: _string_,
               title:_string_}

       FONT - font keyword for labels etc.

       DONE - set this to add a Done button, in addition to the standard
              Apply button.
 
       IDS - widget ids of the title, subtitle, and charsize cw_field
             widgets, and the apply button widget.

       NO_RETURN - The default behavior is that the user must press
                    after entering new values.  Set this
                   keyword so that new values are accepted even if
                   the user just changes a value and then moves the
                   cursor outside of the text entry area.

 OUTPUTS:
 
       The ID of the created widget is returned.

 PROCEDURE/EXAMPLE:

         The idea is that this cw would be used in a widget intended
         to allow the user to interactively adjust the settings for a
         plot.  For instance, you might have a menu item such as Plot
         Options->Titles/Charsize, which would create a popup widget
         containing a CW_PLOTTITLE_CHAR subwidget.  When the user
         makes changes to the CW_PLOTTITLE_CHAR fields, and then
         presses the Apply button, the popup widget event handler
         would re-draw the plot accordingly.

         This widget generates an event when the user presses the
         Apply button or the Done button, if present. The EVENT.TAG
         keyword will return either "APPLY" or "DONE" accordingly.

         Example:
 
         title_char=CW_PLOTTITLE_CHAR(BASE,/DONE, $
                          VALUE={CHARSIZE:!P.CHARSIZE,SUBTITLE:!P.SUBTITLE,
                                 TITLE:!P.TITLE}

 MODIFICATION HISTORY:
 
       David L. Windt, Bell Labs, March 1997
       windt@bell-labs.com

       DLW, June 1997, Added NO_RETURN keyword.

(See cw_plottitle_char.pro)


CW_VECTOR

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
 
       CW_VECTOR

 PURPOSE:
 
       A compound widget used to get input necessary to create a
       "vector", in the spirit of the VECTOR function in this
       directory, i.e, get input for the MIN, MAX, and PTS values.
       The widget also lets the user specify the increment between
       points, and whether the point spacing is linear or
       logarithmic.
      
 CATEGORY:
 
        compound widgets.

 CALLING SEQUENCE:
 
        Result = CW_VECTOR(PARENT)

 INPUTS:
 
       PARENT - the id of the parent widget.  

 OPTIONAL KEYWORD PARAMETERS:
 
        UVALUE - Supplies the user value for the widget.
 
       FRAME - Set to draw a frame around the widget.

       FONT - Font keyword for labels etc.

       TITLE - A string used to label the widget

       XSIZE - An explicit horizontal size (in characters) for the
               min, max and increment input areas.  The default is to
               let the window manager size the widget.  

       NXSIZE - An explicit horizontal size (in characters) for the
                pts field area.  The default is to let the window
                manager size the widget.  

       YSIZE - An explicit vertical size (in lines) for the text input
               areas.  The default is 1.

       VALUE - A structure used to set the initial value of the
               widget, containing the following tags:

               min, max, n and log - the parameters used to specify a
                                     vector (see vector.pro)

               format - a valid format command string used to format
                        the min, max, and increment values. a null
                        string will result in default floating-point
                        formatting.

               nformat - a valid format command string to format the
                         pts field.  a null string will result in
                         default integer formatting.
 
               units - a string used to label the vector units. for
                       example, if the CW_VECTOR widget is being used
                       to get input to create a vector of lengths in
                       feet, then set value.units='feet'

               uunits - a flag to indicate whether or not to actually
                        update the units label.
             
               The same value structure is used with WIDGET_CONTROL
               to set the value of a CW_VECTOR, as in
               WIDGET_CONTROL,WIDGET,SET_VALUE=VALUE

               When using the GET_VALUE keyword with WIDGET_CONTROL,
               however, the returned value is a structure with only
               four tags: {min,max,pts,log}

      MINRANGE, MAXRANGE - These keywords define the range of
                           acceptable values for the min and max
                           fields.  If not set, any values for min
                           and max are allowed; otherwise, (min >
                           MINRANGE) < MAXRANGE, and (max > MINRANGE)
                           < MAXRANGE.  None, one or both of these
                           keywords can be specified.

      MINN - The minimum allowable value for n. default is 1.

      NO_RETURN - The default behavior is that the user must press
                   after entering new values.  Set this
                  keyword so that an event is returned even if the
                  user just changes a value and then moves the
                  cursor outside of the text entry area.

 OUTPUTS:
 
       The id of the created widget is returned.

 PROCEDURE:
 
      Entering a value in the pts, min or max fields will set the
      increment field.  Entering a value in the increment field will
      set the points field, and possibly the max field if the
      increment doesn't divide evenly into the range specified by min
      and max.

 EXAMPLE:
 
     Create a CW_VECTOR to get input to create a vector of lengths in
     [feet]:
     
      
        base=WIDGET_BASE()
        length_widget=CW_VECTOR(BASE,VALUE={MIN:0.,MAX:10.,N:11,LOG:0, $
                                            UNITS:'feet', $
                                            FORMAT:'(F10.2)',
                                            NFORMAT:'(I4)',
                                            UUNITS:1}
                                TITLE='LENGTHS')

     Later, get the widget values and create the length vector:
 
        WIDGET_CONTROL,length_widget,GET_VALUE=value
        lengths=VECTOR(value.min,value.max,value.n,log=value.log)

 MODIFICATION HISTORY:
 
       David L. Windt, Bell Labs, March 1997
       windt@bell-labs.com

       DLW, June 1997, Added NO_RETURN keyword.

       DLW, November 1997, Removed TRACKING keyword; corrected bug
       that caused improper updates when NO_RETURN was set and the
       user toggled between linear and logarithmic step sizes.

(See cw_vector.pro)


DGTZ_IMAGE

[Previous Routine] [Next Routine] [List of Routines]

 NAME:

       DGTZ_IMAGE
       
 PURPOSE:

       A widget application to interactively measure distances in an
       image, either between two points, two horizontal lines, or two
       vertical lines.
       
 CATEGORY:

       Image analysis
       
 CALLING SEQUENCE:
 
       DGTZ_IMAGE,IMAGE
                
 INPUTS:
 
      IMAGE = 2-D array containing image.

 OUTPUTS:

      The measured distances are listed on the widget, and
      can also be saved to a text file (using MORE.)
                
 KEYWORD PARAMETERS:
 
        UNITS - String specifying units.  Default is 'units'.
        
 COMMON BLOCKS:
 
        dgtz_image, internal to this program.

 MODIFICATION HISTORY:
 
      David L. Windt, Bell Laboratories, May 1997
      windt@bell-labs.com

      Jul 1997: Corrected problem with widget labels

(See dgtz_image.pro)


DGTZ_PLOT

[Previous Routine] [Next Routine] [List of Routines]

 NAME:

          DGTZ_PLOT

 PURPOSE:

          A widget application used to extract (X,Y) values from an
          image of plot.  For example, you can use this program to
          extract data from a published plot that you've scanned and
          converted to an image array.

 CALLING SEQUENCE:
 
         DGTZ_PLOT,IMAGE,XRANGE,YRANGE

 INPUTS:
 
         IMAGE - 2D array containing the plot image.
         
         XRANGE - 2-element array specifying data range of X axis on
                  plot image.
                  
         YRANGE - 2-element array specifying data range of Y axis on
                  plot image.
                               
 KEYWORD PARAMETERS:
 
         XTYPE - set if plot image has log x axis.

         YTYPE - set if plot image has log x axis.

         SXMAX - Visible size of draw widget along x direction, in pixels.
                 Default=512.
                 
         SYMAX - Visible size of draw widget along y direction, in pixels.
                 Default=512.

 OUTPUTS:

         The digitized X,Y pairs are listed on a widget. You can
         also save these data to a file (using MORE.)
         
 COMMON BLOCKS:
 
         DGTZ_PLOT internal to this procedure.
         
 PROCEDURE:
 
         The image of the plot is displayed on a widget, and the user
         can digitize points which are converted to X,Y values.  The
         first step,however, is generally to calibrate the X and Y
         axes; the endpoints of the specified axis are digitized,
         after pressing the Calibrate X Axis or Calibrate Y Axis
         button.

         
 MODIFICATION HISTORY:
 
         David L. Windt, Bell Laboratories, May, 1997

         September, 1998 - Addex SXMAX and SYMAX keywords.

         windt@bell-labs.com

(See dgtz_plot.pro)


DIALOG

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
 
        DIALOG

 PURPOSE:
 
       A popup widget dialog box to get user input. Like
       WIDGET_MESSAGE, which is better in some cases, but this widget
       also includes fields and lists.

 CATEGORY:
 
        Widgets.

 CALLING SEQUENCE:

        Result = DIALOG([TEXT])

 OPTIONAL INPUTS:
 
        TEXT - The label seen by the user.
        
 KEYWORD PARAMETERS:
 
   There are 6 types of dialogs, each with unique behavior.  With
   each default dialog type are associated buttons; these buttons can
   be overridden with the BUTTONS keyword, except in the case of the
   LIST and FIELD dialogs.

       One of the following six keywords MUST be set:

       ERROR - Display an error message; default BUTTONS =
               ['Abort','Continue']

       WARNING - Display a warning message.  default BUTTONS = ['OK']

       INFO - Display an informational message; 
              default BUTTONS = ['Cancel','OK']
 
       QUESTION - Ask a question.  default BUTTONS =
                  ['Cancel','No','Yes']

       LIST - Get a selection from a list of choices.  default
              BUTTONS = ['Cancel','OK'] Must specify CHOICES = string
              array of list choices.

              Set the RETURN_INDEX keyword to cause the returned
               value to be the zero-based index of the selected
               list item.  

       FIELD - Get user input, using CW_FIELD.  default BUTTONS =
               ['Cancel','OK']. FLOAT, INTEGER, LONG, and STRING
               keywords apply here, as does the VALUE keyword to set
               an initial value.

   GROUP - Group leader keyword.

   TITLE - title of popup widget.
        
 COMMON BLOCKS:

       DIALOG

 OUTPUTS:
 
       In the case of LIST or FIELD dialogs, this function returns
       the selected list element or the user input, respectively.
       Otherwise, this function returns the name of the pressed
       button.

 EXAMPLE:
 
        1. Create a QUESTION DIALOG widget.

       D = DIALOG(/QUESTION,'Do you want to continue?')

       2. Get the user to enter a number.

       D = DIALOG(/FLOAT,VALUE=3.14159,'Enter a new value for pi.')
 
       3. Get the user to choose from a list of options.

       D = DIALOG(/LIST,CHOICES=['Snoop','Doggy','Dog'])

 MODIFICATION HISTORY:
 
       David L. Windt, Bell Labs, March 1997

       May 1997 - Added GROUP keyword, and modified use of MODAL
                  keyword to work with changes in IDL V5.0
                  
       windt@bell-labs.com

(See dialog.pro)


DISPLAY_FONT

[Previous Routine] [Next Routine] [List of Routines]

 NAME:

       DISPLAY_FONT
       
 PURPOSE:

       Display the font sets listed in the IDL User's Guide.
       
 CALLING SEQUENCE:
 
       DISPLAY_FONT[,FONT_NUMBER,HARDWARE=HARDWARE]
       
 OPTIONAL INPUT PARAMETERS:
 
      FONT_NUMBER - The font index. If not supplied, the user is
                    prompted for input.
                        
 KEYWORD PARAMETERS:
 
      HARDWARE - set to use the hardware fonts (i.e. PostScript for
                 !d.name='PS') set; otherwise Hershey sets are used.
                        
 MODIFICATION HISTORY:
 
        D. L. Windt, Bell Laboratories, Sept. 1991
        windt@bell-labs.com

(See display_font.pro)


DLIB

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
 
        DLIB
        
 PURPOSE:
 
        A cheesy alias to DOC_LIBRARY, with a name that's easier to
        type.

 CATEGORY:
 
        Cheesy aliases.

 MODIFICATION HISTORY:
 
        D. L. Windt, Bell Labs, April 1990.
        windt@bell-labs.com

(See dlib.pro)


ELECTRON_MFP

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
        ELECTRON_MFP

 PURPOSE:
 
        This function returns the elastic mean-free-path for electrons
        of energy E, in a material having density N, and atomic number Z.

 CALLING SEQUENCE:
 
        Result = ELECTRON_MFP(Z,A,RHO,E)

 INPUTS:
        
        Z = Atomic number
        
        A = Atomic weight (g/mole)
        
        RHO = Density (g/cm3)
        
        E = electron energy in keV

 OUTPUTS:
 
        This function returns the elastic mean-free-path, in angstroms.

 EXAMPLE:

       The elastic mean-free-path of tungsten (Z=74, Rho=19.35) at an
       electron energy of 100 keV = ELECTRON_MFP(74,183.85,19.35,100.)

 MODIFICATION HISTORY:
 
        Written by D. L. Windt, Bell Labs, June 1994
        windt@bell-labs.com

(See electron_mfp.pro)


EPLOT

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
 
       EPLOT
                
 PURPOSE:

       Plot x vs y, with vertical error bars on y.

 CALLING SEQUENCE:

       EPLOT,Y,SIGY
       EPLOT,X,Y,SIGY
       EPLOT,Y,SIGY_UP,SIGY_DOWN
       EPLOT,X,Y,SIGY_UP,SIGY_DOWN

 INPUTS:

       X, Y -  1-D arrays

       SIGY - Uncertainty in Y, i.e. Y+/-SIGY

       SIGY_UP, SIGY_DOWN - +/- uncertainties in Y, i.e.,
                           Y +SIGY_UP -SIGY_DOWN

 KEYWORD PARAMETERS:

       BARLINESTYLE = Linestyle for error bars.

               plus all valid IDL plot keywords.  Only the COLOR,
               THICK, NOCLIP, and T3D keywords apply to the error
               bars.

 MODIFICATION HISTORY:

      D. L. Windt, Bell Laboratories, November 1989
      Replaced specific plot/oplot keywords with _EXTRA,
      April, 1997

      windt@bell-labs.com

(See eplot.pro)


EROM

[Previous Routine] [Next Routine] [List of Routines]

 NAME:

      EROM
      
 PURPOSE:

       Read up to ten columns of data from a text file.

       This program can be used to read data written by the MORE
       program.

       The file to be read must be such that if the data are
       space-separated, then all variables are numeric; String
       variables are allowed only if the data are separated by tabs,
       colons, etc.

       The file may contain any number of comment lines - which MUST
       begin with a semicolon, and MUST be positioned before all data
       lines.

 CALLING SEQUENCE:
 
        EROM,V0[,V1,V2,...V9]
             
 KEYWORD PARAMETERS:
 
   FILE - String specifying the name of a file; if not supplied, the
          user is queried.
   
   SKIP - The number of lines at the beginning of the file that
          should be skipped.
          
   TAB - Specify /TAB for tab-separated data.  (The default is space-
         separated data.)  It is only necessary to specify this
         keyword if the file contains any string data columns.
         
   SEPARATOR - A string specifiying the character separating the data
               columns.
               
 OUTPUTS:
 
        V0, V1, V2, ... variables to hold the data.  There must be as many
       v's specified in the call to EROM as there are columns of
       data.  The V's are floating point arrays, unless the TAB
       keyword is specified in which case they are all string arrays.
        
 MODIFICATION HISTORY:
 
        David L. Windt, Bell Labs, March 1990

        January, 1997 - DLW
         Modified to ignore lines beginning with semicolons, and to
         accept data separated by tabs, etc.; Removed the notitle and
         comment keyword; included pickfile to prompt for filenames
         when not specified.

       June, 1997 - DLW
         Returned numeric variables are now double-precision instead
         of floating-point.
        
        windt@bell-labs.com

(See erom.pro)


ERRORF_FIT

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
 
        ERRORF_FIT
        
 PURPOSE:
 
        fit y=f(x) where:
        f(x) = a0*errorf((x-a1)/a2))+a3+x*a4
        
 CALLING SEQUENCE:
 
        YFIT = ERRORF_FIT(X,Y,A)
        
 INPUTS:
 
       X - independent variable, must be a vector.
       
       Y - dependent variable, must have the same number of points ;
           as x.
                
        A - initial values of adjustable parameters.
        
 OUTPUTS:
 
        YFIT = fitted function.
        
 MODIFICATION HISTORY:
 
        Adapted from GAUSSFIT
        
        D. L. Windt, Bell Laboratories, June 1990
        windt@bell-labs.com

(See errorf_fit.pro)


EXPO_FIT

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
 
        EXPO_FIT
        
 PURPOSE:
 
        Fit y=f(x) where:
        F(x) = a0*exp(-abs(x-a1)/a2)+a3
        a0 = height of exp, a1 = center of peak, a2 = 1/e width,
        Estimate the parameters a0,a1,a2,a3 and then call curvefit.
        
 CALLING SEQUENCE:
 
        YFIT = EXPO_FIT(X,Y,A)
        
 INPUTS:
 
        X - independent variable, must be a vector.
        
       Y - dependent variable, must have the same number of points ;
           as x.
                
 OUTPUTS:
 
        YFIT - fitted function.
        
 OPTIONAL OUTPUT PARAMETERS:
 
       A - Fit coefficients. a four element vector as described
           above.

 MODIFICATION HISTORY:
 
        Adapted from GAUSSFIT
        
        D. L. Windt, Bell Laboratories, March, 1990
        windt@bell-labs.com

(See expo_fit.pro)


FILE_DATE

[Previous Routine] [Next Routine] [List of Routines]

 NAME:

     FILE_DATE


 PURPOSE:

    Determine Unix file creation date.


 CALLING SEQUENCE:

   Result=FILE_DATE(FILE_NAME)

 
 INPUTS:

   FILE_NAME - A string specifying the name of the file


 OUTPUTS:

   Result - a string specifying the file creation date.

 RESTRICTIONS:

   Probably won't work the way you want.  So sue me.

 MODIFICATION HISTORY:

   David L. Windt, Bell Labs, May 1997
   windt@bell-labs.com 

(See file_date.pro)


FINDEX

[Previous Routine] [Next Routine] [List of Routines]

 NAME:

           FINDEX

 PURPOSE:  Compute "floating point index" into a table using binary
           search.  The resulting output may be used with INTERPOLATE.

 USEAGE:   result = findex(u,v)

 INPUT:    
   u       a monitically increasing or decreasing 1-D grid
   v       a scalor, or array of values

 OUTPUT:
   result  Floating point index. Integer part of RESULT(i) gives
           the index into to U such that V(i) is between
           U(RESULT(i)) and U(RESULT(i)+1).  The fractional part
           is the weighting factor

                          V(i)-U(RESULT(i))
                          ---------------------
                     U(RESULT(i)+1)-U(RESULT(i))


 DISCUSSION: 
           This routine is used to expedite one dimensional
           interpolation on irregular 1-d grids.  Using this routine
           with INTERPOLATE is much faster then IDL's INTERPOL
           procedure because it uses a binary instead of linear
           search algorithm.  The speedup is even more dramatic when
           the same independent variable (V) and grid (U) are used
           for several dependent variable interpolations.

  
 EXAMPLE:  

; In this example I found the FINDEX + INTERPOLATE combination
; to be about 60 times faster then INTERPOL.

  u=randomu(iseed,200000) & u=u(sort(u))
  v=randomu(iseed,10)     & v=v(sort(v))
  y=randomu(iseed,200000) & y=y(sort(y))

  t=systime(1) & y1=interpolate(y,findex(u,v)) & print,systime(1)-t
  t=systime(1) & y2=interpol(y,u,v)            & print,systime(1)-t
  print,f='(3(a,10f7.4/))','findex:   ',y1,'interpol: ',y2,'diff:     ',y1-y2

 AUTHOR:   Paul Ricchiazzi                        21 Feb 97
           Institute for Computational Earth System Science
           University of California, Santa Barbara
           paul@icess.ucsb.edu

 REVISIONS:

(See findex.pro)


FRACTAL_FIT

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
 
        FRACTAL_FIT
        
 PURPOSE:
 
        Fit y=f(x) where:
        F(x) = a0/(x^a1) [+a2]
        Estimate the parameters a0,a1[,a2] and then call curvefit.
        
 CALLING SEQUENCE:
 
        YFIT = FRACTAL_FIT(X,Y,A,BACKGROUND=BACKGROUND)
        
 INPUTS:
 
        X = independent variable, must be a vector and MUST BE POSITIVE!
        
        Y = dependent variable, must have the same number of points as x.
        
        BACKGROUND = set to add a background term (a2).
        
 OUTPUTS:
 
        YFIT = fitted function.
        
 OPTIONAL OUTPUT PARAMETERS:
 
        A = coefficients. a two [three] element vector as described above.
        
 RESTRICTIONS:
 
        X must be positive.
        
 MODIFICATION HISTORY:
 
        D. L. Windt, Bell Laboratories, March, 1990
        windt@bell-labs.com

(See fractal_fit.pro)


FWHM

[Previous Routine] [Next Routine] [List of Routines]

 NAME:

      FWHM
      
 PURPOSE:
 
       Interactively measure the full-width-half-max of a region of a
       curve that has been previously plotted.
        
 CALLING SEQUENCE:
 
        RESULT=FWHM(XAXIS,YAXIS)
        
 INPUTS:
 
        XAXIS - The x axis variable which has been plotted.
        
        YAXIS - The y axis variable which has been plotted.
        
 OPTIONAL INPUT PARAMETERS:
 
       RANGE - Vector of subscripts, which refers to the range of X,Y
               values over which the FWHM is to be determined.  If
               not supplied, then GET_ROI is used to interactively
               define the range.  To use FWHM with a non-interactive
               graphics device, range MUST be supplied.
            
 KEYWORD PARAMETERS:
 
       YZERO - The zero point level. If not specified, the zero point
               level is determined from the endpoints of the region
               of interest of the curve.
                
       YHM - The value at which the full-width is computed.
             Allowable range is 0. to 1. If not specified, .5 is
             used.
                
       INVERT - Set to get width of 'absorption line' rather than
                'emission line'.
                
       NOHIGHLIGHT - Set to inhibit highlighting the region of
                     interest.
                
       H_COLOR - The color index for highlighting the region of
                 interest. Default is 7 (Yellow.)
                
       H_THICK - The thickness for highlighting the region of
                 interest.
                
        NOLABEL - Set to inhibit labelling the fwhm.
        
       L_HEADER - String specifying the label header. Default=''.
        
       L_COLOR - Color index for the label.
        
       L_FORMAT - Format string for label (eg. '(F4.2)').
        
       UNITS - String specifying units along x axis, used in label.
        
       CHARSIZE - Size of label text.
        
       PSYM - PSYM
   
 OUTPUTS:

        Result - The full-with-half-max of the region of interest 
                 of the curve, in x-axis data units.
                
 OPTIONAL OUTPUT PARAMETERS:
 
       ROI - The subscripts of the digitized region of interest.
        
       FWHM_ROI - The subscripts of the region between the fwhm
                  points and the max (min) of the function.
            
       LINE_PTS - A 4-element array containing the coordinates of
                  the line drawn on the plot: [x0,x1,y0,y1]
            
       LABEL - The label for the plot.
        
       L_POS - A two element array containing the x,y coordinates
               of the label, in data coords.

 SIDE EFFECTS:
 
       TEK_COLOR is used to load in the tektronix colors.  The region of
       interest of the curve is highlighted. The fwhm is labelled.
        
 RESTRICTIONS:
 
        The data must be plotted prior to calling FWHM.
        
 PROCEDURE:
 
       The user is asked to digitize the endpoints of the region of
       interest with the mouse.  The region is highlighted, and the
       fwhm is labelled.
        
 MODIFICATION HISTORY:
 
        D. L. Windt, Bell Laboratories, November 1989

        March 1998 - Removed MANUAL keyword. 

        windt@bell-labs.com

(See fwhm.pro)


GAUSSEXPO_FIT

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
 
        GAUSSEXPO_FIT
        
 PURPOSE:
 
        Fit y=f(x) where:
        
        f(x) = a0*exp(-z^2/2)+a3*exp(-abs(x-a4)/a5)+a6 and z=(x-a1)/a2
                
       a0 = height of gaussian, a1 = center of gaussian, a2 = 1/e
       width of ; gaussian, a3 = height of exponential, a4 = center
       of exponential, ; a5 = 1/e width of exponential,
       a6=background.
        
        Estimate the parameters a0,a1,a2,a3,a4,a5,a6 and then call curvefit.
        
 CALLING SEQUENCE:
 
        YFIT = GAUSSEXPO_FIT(X,Y,A)
        
 INPUTS:
 
        X = independent variable, must be a vector.
        
        Y = dependent variable, must have the same number of points as x.
                
 OUTPUTS:
 
        YFIT = fitted function.
        
 OPTIONAL OUTPUT PARAMETERS:
 
       A = Fit coefficients. A six element vector as described above.

 MODIFICATION HISTORY:
 
        Adapted from GAUSSFIT
        
        D. L. Windt, Bell Laboratories, March, 1990
        windt@bell-labs.com

(See gaussexpo_fit.pro)


GAUSS_FIT

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
 
       GAUSS_FIT
        
 PURPOSE:
 
        Fit y=f(x) where:
        f(x) = a0*exp(-z^2/2) + a3
                and z=(x-a1)/a2
        a0 = height of gaussian, a1 = center of gaussian, a2 = 1/e width,
        a3 = background.
        Estimate the parameters a0,a1,a2,a3 and then call CURFIT.
        
 CALLING SEQUENCE:
 
        YFIT = GAUSS_FIT(X,Y,A)
        
 INPUTS:
 
       X - independent variable, must be a vector.
        
       Y - dependent variable, must have the same number of points ;
           as x.
                
 OUTPUTS
 
        YFIT - fitted function.
        
 OPTIONAL OUTPUT PARAMETERS:
 
       A - Fit coefficients. a three element vector as described
           above.

 MODIFICATION HISTORY:
 
        Adapted from GAUSSFIT
        
        D. L. Windt, Bell Laboratories, March, 1990
        windt@bell-labs.com

(See gauss_fit.pro)


GAUS_CONVOL

[Previous Routine] [Next Routine] [List of Routines]

 NAME:      

       GAUS_CONVOL
 
 PURPOSE:
 
        Convolve a function with a gaussian.
 
 CALLING SEQUENCE:
 
        Result=GAUS_CONVOL(X,Y,SIG)

 INPUTS:

        X = vector of independent variables.
 
        Y = vector of dependent variables.

        SIG = width of gaussian, in same units as X.

 KEYWORDS:

       NSIGMA - A factor that determines how many points to use for
                the gaussian kernel. The exact number of points used
                depends on the value of SIG and the range of X values
                as well, but it will be roughly equal to 2*NSIGMA*SIG.
                Default=2.5.

 PROCEDURE:
 
       CONVOL is used to convolve y with a gaussian whose width is
       sig, in x axis units.  The gaussian is defined as Gaussian =
       1./sqrt(2.*!pi*sigma)*exp(-.5*(x/sigma)^2)
 
 MODIFICATION HISTORY:
 
   David L. Windt, Bell Labs, July 1990.

   November 1990: added factor of 2 in gaussian argument.

   February 1997: made sure gaussian kernel has at least 2 points.

   windt@bell-labs.com

   16-SEP-1998  - Introduced the keyword NSIGMA and changed the
                  calculation of the number of points
                  n_pts. NSIGMA=5.  Made conversion parameter DOUBLE
                  precision and corrected the calculation of this
                  parameter.  Note, width in xvar is only approximate
                  (and always a little larger than +- NSIGMA).  -
                  
   Roger Dejus (dejus@aps.anl.gov)


(See gaus_convol.pro)


GET_PEAK

[Previous Routine] [Next Routine] [List of Routines]

 NAME:

        GET_PEAK
        
 PURPOSE:
 
        Interactively find the local maximum of a previously plotted
        curve, and indicate it on the plot.
        
 CALLING SEQUENCE:
 
        Result=GET_PEAK(XAXIS,YAXIS)
                
 INPUTS:
 
         XAXIS = the x axis variable which has been plotted.
         
         YAXIS = the y axis variable which has been plotted.
         
 KEYWORD PARAMETERS:
 
         COLOR - the color index for marking the local maximum.
         
         NOMARK - set to disable marking the location of the peak.
                    
         NOHIGHLIGHT - set to disable highlighting the region of
                       interest.
                        
         H_COLOR - the color index for highlighting the region of
                   interest. Default is 7 (Yellow).
                        
         H_THICK- the thickness for highlighting the region ; of
                  interest.
                        
         PRINT - set to print the x,y values of the peak.
                
 OUTPUTS:

         Result = the array subscript of the local max.
         
 SIDE EFFECTS:
 
         TEK_COLOR is used to load in the tektronix colors.
         The region of interest of the curve is highlighted.
         A vertical line is drawn through the local maximum.
                
 PROCEDURE:     

        The user is asked to digitize the endpoints of the region of
        interest with the mouse using GET_ROI.
                
 MODIFICATION HISTORY:
 
        D. L. Windt, Bell Laboratories, February 1990.

        windt@bell-labs.com

(See get_peak.pro)


GET_PT

[Previous Routine] [Next Routine] [List of Routines]

 NAME:

       GET_PT
       
 PURPOSE:
 
        Digitize a point on a previously plotted curve, and return
        the corresponding array element.

 CALLING SEQUENCE:
 
        Result = GET_PT(XAXIS,YAXIS,XPOINT,YPOINT)
        
 INPUTS:
 
        XAXIS - the x axis vector which was used to make the plot.
        
        YAXIS - the y axis vector which was used to make the plot.
                
 KEYWORD PARAMETERS:
 
        NOHIGHLIGHT - set to inhibit putting a red mark on the curve
                      at the digitized point.
                        
        MESSAGE - a string to print as the message to the user.
                  Default = 'Digitize a point: '
                        
        NOINIT - set to inhibit placing the cursor in the center of
                 the plot window.
                    
 OUTPUTS:
 
        Result - The array subscript of the digitized point.

 OPTIONAL OUTPUT PARAMETERS:
 
        XPOINT, YPOINT - the digitized points.

 SIDE EFFECTS:
 
        A mark is drawn on the plot at the digitized point.

 PROCEDURE:

        The user is asked to digitize a point on the curve using the
        mouse.  The VALUE_TO_INDEX function is used to find the
        closest array element.
                
 MODIFICATION HISTORY:
 
        D. L. Windt, Bell Laboratories, November 1989
        Feb. 1991, Removed call to TEK_COLOR
        Mar. 1997, replaced index search code with call to
        VALUE_TO_INDEX function.

        windt@bell-labs.com

(See get_pt.pro)


GET_ROI

[Previous Routine] [Next Routine] [List of Routines]

 NAME:

        GET_ROI
        
 PURPOSE:

       Get a region-of-interest of a previously plotted curve.
       
 CALLING SEQUENCE:
 
        Result=GET_ROI(XAXIS,YAXIS)
        
 INPUTS:
 
         XAXIS = the x axis variable which has been plotted.
         
         YAXIS = the y axis variable which has been plotted.
         
 KEYWORD PARAMETERS:

         NOHIGHLIGHT - set to disable highlighting the region of
                       interest.
                        
         H_COLOR - the color index for highlighting the region of
                   interest. Default is 7 (Yellow).
                        
         H_THICK - the thickness for highlighting the region ; of
                  interest.
                        
         PSYM - PSYM.
         
 OUTPUTS:

         Result = the array of subscripts of the roi.
         
 SIDE EFFECTS:
 
       TEK_COLOR is used to load in the tektronix colors.
       The region of interest of the curve is highlighted.
       
 PROCEDURE:
 
       The user is asked to digitize the endpoints of the region of
       interest with the mouse using GET_PT.  The region is
       highlighted (unless nohighlight is set.)
                
 MODIFICATION HISTORY:
 
       D. L. Windt, Bell Laboratories, November 1989

       windt@bell-labs.com

(See get_roi.pro)


GHOSTVIEW

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
 
       GHOSTVIEW

 PURPOSE:
 
       Use the Unix ghostview program to view an IDL postscript file

 CALLING SEQUENCE:
 
       GHOSTVIEW [,FILE=FILE]
 
 KEYWORD PARAMETERS:
 
       FILE - the name of the file to view.  Default is idl.ps

 RESTRICTIONS:

       Since the procedure spawns a "ghostview" process, 
       such an executable must exist or it ain't goin' nowhere.

 PROCEDURE:
     
       If the current device is PS, the program will issue
       a DEVICE,/CLOSE command.

       It will then SPAWN,'ghostview file_name&'

 MODIFICATION HISTORY:
 
            David L. Windt, Bell Labs, March 1997
            windt@bell-labs.com

(See ghostview.pro)


GREEK

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
 
	GREEK

 PURPOSE:
 
       This function returns the string needed to draw the specified
       greek character using either the vector graphics font no. 4,
       or PostScript font 9.

       If (!d.name eq 'PS') and (!p.font eq 0), then the PostScript
       font will be used.  Otherwise, the vector font will be used.

 CALLING SEQUENCE:
 
	Result = GREEK(Name)

 INPUTS:
 
       Name - String specifying the greek character name. Valid
              inputs are:

              alpha, beta, gamma, delta, epsilon, zeta, eta, theta
              iota, kappa, lambda, mu, nu, xi, omicron, pi, rho,
              sigma, tau, upsilon, phi, chi, psi, omega

              Alpha, Beta, Gamma, Delta, Epsilon, Zeta, Eta, Theta
              Iota, Kappa, Lambda, Mu, Nu, Xi, Omicron, Pi, Rho,
              Sigma, Tau, Upsilon, Phi, Chi, Psi, Omega

              Although not greek, the following characters are also
              valid (but will only work with the 'default' font !3):

              angstrom, Angstrom, degrees, plus_minus

 KEYWORDS:

       FORCE_PS - Set to use PostScript font, regardless of the value
                  of !d.name and !p.font.

       PLAIN - Set to just return Name in plain text.

       APPEND_FONT - Set to append the characters specifying a
                     'default' font: !3. That is, if this keyword is
                     set, then the command

                     Result=GREEK(theta,/APPEND_FONT)

                     will return the string

                     '!9q!3' for PostScript and '!4h!3' for vector
                     fonts.
 
 OUTPUTS:
 
       Result - The string containing the specified greek character.

 EXAMPLE:

	Result=GREEK(theta)
	
        In this case, Result='!9q' if !d.name is 'PS' and !p.font is
        0; otherwise, Result='!4h'

 MODIFICATION HISTORY:
 
 	David L. Windt, Bell Labs, September 1998.
        windt@bell-labs.com
                    

(See GREEK.pro)


KAISER_BESSEL

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
 
        KAISER_BESSEL

 PURPOSE:
 
        Window function for Fourier Transform filtering.  

 CATEGORY:
 
        Signal, image processing.

 CALLING SEQUENCE:
 
        Result = KAISER_BESSEL(N1) (for 1D)

        Result = KAISER_BESSEL(N1,N2) (for 2D)

 INPUTS:
 
        N1 - The number of columns of the result.

        N2 - The number of rows of the result.
        
 KEYWORD PARAMETERS:
 
       ALPHA - The value of Pi*Alpha is half of the time-bandwidth
               product.  Default = 3.0

 OUTPUTS:
 
   Result(i) = BESELI(!pi*alpha*sqrt(1-( (findgen(N)-N/2) / (N/2) )^2),0) / $
                    BESELI(!pi*alpha,0)

 MODIFICATION HISTORY:
 
        David L Windt, Bell Labs, August 1996
        May, 1997 - Added 2D option.
        windt@bell-labs.com

(See kaiser_bessel.pro)


LEGEND

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
         LEGEND

 PURPOSE:
 
         Add to a plot a legend containing lines and plotting symbols,
         enclosed in a box.

 CALLING SEQUENCE:

        LEGEND,LABELS
 
 INPUTS:
        LABELS - n-element string array of labels.
 
 KEYWORD PARAMETERS:

       POSITION - an integer, specifying the location of the legend box:
 
                  0: no legend is drawn.
                  1: below plot, left
                  2: below plot, center
                  3: below plot, right
                  4: lower left
                  5: lower center
                  6: lower right
                  7: middle left
                  8: middle center
                  9: middle right
                  10: upper left
                  11: upper center
                  12: upper right
         
                  if not specified, default position=10

        COLOR - n-element array of colors. default is !p.color
        
        LINESTYLE - n-element array of linestyles. if ommited, only
                    symbols are plotted.
                    
        THICK - n-element array of thicknesses. default is !p.thick
        
        PSYM - n-element array of psym values. if positive, only
               symbols are plotted.
               
        SYMSIZE - n-element array of symsize values. default is !p.symsize
        
        SYMBOLS - array of 'symbol' specifiers: each element of
                  psym which is equal to 8 (user-defined symbol)
                  must have a corresponding value for 'symbol' to be 
                  used by the procedure SYMBOLS.  
                  Examples:     psym=[8,8,8,8],symbols=[1,2,20,30]
                                psym=[1,2,8,8],symbols=[1,2]
                                
        CHARSIZE - scalar specifiying the size of the text.
        
        TITLE - scalar string specifying legend title
        
        T_COLOR - scalar specifying the color index of the title.
        
        NOLINES - set to inhibit drawing lines and symbols; just draw
                  labels in color.
                  
        SYMONLY - set to inhibit drawing lines; just draw symbols.
        
        NOBOX - set to inhibit drawing a box around the legend
        
        LINEWIDTH - width in character units. default = 4.

        BOXPADX - padding in character units, between text and box in
                  x. default=2.0
        BOXPADY - padding in character units, between text and box in
                  y. default=0.5
                  
        FONT - Set to an integer from 3 to 20, corresponding to the
               Hershey vector font sets, referring to the font used
               to display the text.  If a font other than !3 is used
               in the text string, then FONT should be set
               accordingly. (Any font commands embedded in the text
               string are ignored.)

        BOXFUDGEX - A scaling factor, used to fudge the width of the
                    box surrounding the text.  Default=1.0.

 RESTRICTIONS:
 
       When specifying a position of 1,2 or 3, you'll need
       to (a) use the same charsize value for the plot and
       for the legend, and (b) draw the plot with an extra
       ymargin(0).  i.e., set ymargin(0)=7+n_elements(text_array)


 MODIFICATION HISTORY:
 
        David L. Windt, Bell Labs, March 1997
        windt@bell-labs.com
        
       October, 1997, dlw:

       Now using the TEXT_WIDTH function, in order to do a somewhat
       better job of drawing the box around the text.

       NONPRINTER_SCALE keyword parameter is now obsolete.

       BOXFUDGEX keyword parameter added.

(See legend.pro)


LPRINT

[Previous Routine] [Next Routine] [List of Routines]

 NAME:

       LPRINT
       
 PURPOSE:

       Close an IDL graphics file and print it.
       
 CALLING SEQUENCE:
 
       LPRINT
       
 KEYWORD PARAMETERS:

       NORETURN - set this keyword to inhibit executing
                  set_plot,getenv('IDL_DEVICE') followed by
                  !p.font=-1
                          
       FILE - the name of the file to print. Default is device
              dependent: idl.ps for PS, idl.hp for HP, and idl.pcl
              for PCL devices.
                       
       PRINTER - set to the name of the printer to use. Default = lp
                
       COMMAND - set to the name of the printer command to 
                 use. Default = lpr.
                          
                          
       Note: the COMMAND, PRINTER, and FILE keywords are combined as
               follows:

       if COMMAND='lpr', then the program spawns the unix command
                        "lpr -Pprinter file"
                        
       if COMMAND='lp', then the program spawns the unix command
                        "lp dprinter file"

       if COMMAND is anything else, the program simply ignores the
                        printer and file keywords, and spawns the
                        command as is.
 
 MODIFICATION HISTORY:
 
        D. L. Windt, Bell Laboratories, November 1989
        Added PRINTER keyword, June 1993.
                
       Added COMMAND keywrd, replaced RETURN with NORETURN keyword,
                     and added code to execute !p.font=-1 unless
                     NORETURN keyword is set. March, 1997.
                      
      windt@bell-labs.com

(See lprint.pro)


LS

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
 
        LS
        
 CATEGORY:
 
       Stupid little convenience routines.
   
 PURPOSE:
 
        List the contents of the current directory, like the Unix 'ls'
       command.
        
 CALLING SEQUENCE:
 
       LS[,NAME]

       NAME - An optional string specifying the names of the files to
              be listed.  Wild cards are allowed. For example,
              ls,'*.pro' will list all files ending in .pro.

 MODIFICATION HISTORY:

       David L. Windt, Bell Labs, November 1989
       windt@bell-labs.com

       February, 1998 - Now works under Windows and MacOS, making use
                        of FINDFILE.  But the old DIR keyword is gone.
       

(See ls.pro)


MAKE_LATEX_TBL

[Previous Routine] [Next Routine] [List of Routines]

 NAME:

      MAKE_LATEX_TBL

 PURPOSE:
 
        Create a LaTeX format table.
        
 CALLING SEQUENCE:
 
        MAKE_LATEX_TBL,ARRAY,TFILE
        
 INPUTS:
 
        ARRAY - (n,m) array of data.
        
        TFILE - string specifying the name of the '.tex' file to create.
        
 KEYWORD PARAMETERS:
 
        COLUMNS - An n-element string specifying the LaTeX column
                 format. For example, if array = (3,m), then an
                 acceptable value for columns would be
                 ['|l|','|c|','|c|'], which would left-justify the
                 first column of data, and center the remaining two.
            
       FORMAT - an n-element string specifying the FORMAT used to
                PRINTF the data.  This must conform to IDL FORMAT
                standards.  If not set, the default the data are
                printed using the IDL free format.
            
        TITLE - a string specifying the title of the table.
        
       HEADINGS - an n-element string array containing the table
                  headings.
            
        NOHLINES - set to inhibit printing \hline between rows of data.
        
 SIDE EFFECTS:
 
                The '.tex' file is created.
                
 RESTRICTIONS:
 
        The TITLE is printed with vertical lines on either ; side,
       regardless of how the COLUMNS parameter may be ; set.  It is
       thus necessary to edit the file to remove the vertical line
       commands if desired.
        
 PROCEDURE:
 
        The data contained in ARRAY are printed to a file ; with the
       appropriate '&' and '\\' symbols necessary ; for use as in the
       LaTeX tabular environment.  If ; COLUMNS is not set, the
       default is '|c|' which centers the data in columns, with
       vertical line separators.
        
 MODIFICATION HISTORY:
 
        David L. Windt, Bell Laboratories, December 1989.
        windt@bell-labs.com

(See make_latex_tbl.pro)


MK_HTML_HELP

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
        MK_HTML_HELP

 PURPOSE:
        Given a list of IDL procedure files (.PRO), VMS text library 
       files (.TLB), or directories that contain such files, this procedure 
       generates a file in the HTML format that contains the documentation 
       for those routines that contain a DOC_LIBRARY style documentation 
       template.  The output file is compatible with World Wide Web browsers.

 CATEGORY:
        Help, documentation.

 CALLING SEQUENCE:
        MK_HTML_HELP, Sources, Outfile

 INPUTS:
     Sources:  A string or string array containing the name(s) of the
                .pro or .tlb files (or the names of directories containing 
               such files) for which help is desired.  If a source file is 
               a VMS text library, it must include the .TLB file extension.  
               If a source file is an IDL procedure, it must include the .PRO
               file extension.  All other source files are assumed to be
               directories.
     Outfile:   The name of the output file which will be generated.

 KEYWORDS:
     TITLE:     If present, a string which supplies the name that
                should appear as the Document Title for the help.
     VERBOSE:   Normally, MK_HTML_HELP does its work silently.
                Setting this keyword to a non-zero value causes the procedure
                to issue informational messages that indicate what it
                is currently doing. !QUIET must be 0 for these messages
               to appear.
     STRICT:   If this keyword is set to a non-zero value, MK_HTML_HELP will 
               adhere strictly to the HTML format by scanning the 
               the document headers for characters that are reserved in 
               HTML (<,>,&,").  These are then converted to the appropriate 
               HTML syntax in the output file. By default, this keyword
               is set to zero (to allow for faster processing).

 COMMON BLOCKS:
        None.

 SIDE EFFECTS:
        A help file with the name given by the Outfile argument is
        created.

 RESTRICTIONS:
        The following rules must be followed in formatting the .pro
        files that are to be searched.
                (a) The first line of the documentation block contains
                    only the characters ";+", starting in column 1.
               (b) There must be a line which contains the string "NAME:",
                   which is immediately followed by a line containing the
                   name of the procedure or function being described in
                   that documentation block.  If this NAME field is not
                   present, the name of the source file will be used.
                (c) The last line of the documentation block contains
                    only the characters ";-", starting in column 1.
                (d) Every other line in the documentation block contains
                    a ";" in column 1.

       Note that a single .pro file can contain multiple procedures and/or
       functions, each with their own documentation blocks. If it is desired
       to have "invisible" routines in a file, i.e. routines which are only
       for internal use and should not appear in the help file, simply leave
       out the ";+" and ";-" lines in the documentation block for those
       routines.

        No reformatting of the documentation is done.

 MODIFICATION HISTORY:
       July 5, 1995, DD, RSI. Original version.
       July 13, 1995, Mark Rivers, University of Chicago. Added support for
               multiple source directories and multiple documentation
               headers per .pro file.
       July 17, 1995, DD, RSI. Added code to alphabetize the subjects;
               At the end of each description block in the HTML file,
               added a reference to the source .pro file.
       July 18, 1995, DD, RSI. Added STRICT keyword to handle angle brackets.
       July 19, 1995, DD, RSI. Updated STRICT to handle & and ".
               Changed calling sequence to accept .pro filenames, .tlb
               text librarie names, and/or directory names.
               Added code to set default subject to name of file if NAME
               field is not present in the doc header.
       May 22, 1997, D. L. Windt, Bell Labs (windt@bell-labs.com)
               Modified to allow for a blank line between
               the NAME: string and the procedure name in the header.

(See mk_html_help.pro)


MORE

[Previous Routine] [Next Routine] [List of Routines]

 NAME:

      MORE
      
 PURPOSE:

       Print one or more variables on the screen or to a file, using
       the MORE keyword to printf.

 CALLING SEQUENCE:

       MORE,v0[,v1,v2,...v19]

 INPUTS:

       V0,V1,...V19 - Any type of array variables; they must all be
                      the same length.

 KEYWORD PARAMETERS:

   FILE - string specifying the name of an output file.

   INDEX - set this to one to print the array indices in the first
           column.

   TITLE - string array of variable names.

   COMMENT - string array of comments

   TAB - set this keyword to create tab-separated data; this is
         useful when writing to a file if any of the variables are
         strings, in which case the data can be read using EROM,/TAB

 MODIFICATION HISTORY:
 
        David L. Windt, Bell Labs, March 1990

        Added comment keyword, August 1992
        
       March 1997 - Title and comment lines are now written with
                    preceding semicolons.  Fixed bug to correctly
                    deal with string arrays.  Added TAB keyword.
                    Removed NOINDEX keyword.  Added INDEX keyword.

       November 1997 - Removed Unix-specific stuff, so that it now
                       works (somewhat) under Windows and MacOS.
                    
       windt@bell-labs.com

(See more.pro)


OEPLOT

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
 
       OEPLOT
                
 PURPOSE:

       Overplot x vs y, with vertical error bars on y.

 CALLING SEQUENCE:

       OEPLOT,Y,SIGY
       OEPLOT,X,Y,SIGY
       OEPLOT,Y,SIGY_UP,SIGY_DOWN
       OEPLOT,X,Y,SIGY_UP,SIGY_DOWN

 INPUTS:

       X, Y -  1-D arrays

       SIGY - Uncertainty in y, i.e. Y+/-SIGY

       SIGY_UP, SIGY_DOWN - +/- uncertainties in Y,
                                i.e., Y +SIGY_UP -SIGY_DOWN

 KEYWORD PARAMETERS:

       BARLINESTYLE = Linestyle for error bars.
 
               plus the IDL keywords color, linestyle,thick, psym,
               symsize, noclip, and t3d.

 MODIFICATION HISTORY:

       D. L. Windt, Bell Laboratories, November 1989
       windt@bell-labs.com

(See oeplot.pro)


PLOT_MOVIE

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
 
        PLOT_MOVIE

 PURPOSE:

        Display an animated sequence of X-Y plots in a window.

 CALLING SEQUENCE:

        PLOT_MOVIE,X,Y[,Y1,Y2,Y3,Y4]
 
 INPUT PARAMETERS:
 
        X = N_x-element array, common to all Y vectors
        
        Y = 2D array, N_x x N_plots
 
 OPTIONAL INPUT PARAMETERS:

       Y1, Y2, Y3, Y4 - additional Y arrays to be overplotted; these
                        must all have the same dimensions as Y.

 KEYWORD PARAMETERS:

       XRANGE- A two-element vector specifying the xrange of the
               plot.  Default = [0, max(x)]

       YRANGE- A two-element vector specifying the yrange of the
               plot. Default = [0 < min(y)*1.05,max(y)*1.05]

       COLOR- array of colors for each Y plot

       LINESTYLE - array of linestyles for each Y plot

       THICK - array of thicknesses for each Y plot

       _EXTRA - This keyword is use to pass additional parameters to
                the plot command.

 EXAMPLE:

      Make a movie of two 'travelling' sin waves:

      X=VECTOR(0.,100.,100)
      Y=FLTARR(100,30)
      for i=0,29 do Y(*,i)=sin((x+i*!pi)/!pi)
      Y1=-Y
      PLOT_MOVIE,X,Y,Y1

 MODIFICATION HISTORY:

        Written by:     David L. Windt, Bell Labs, April 1994

        windt@bell-labs.com

(See plot_movie.pro)


PLOT_PRINT

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
          PLOT_PRINT


 PURPOSE:
 
          A widget-based interface for creating and printing IDL
          graphics output files.  The widget allows the user to
          select an output device type (PS, PCL, or HP), and specify
          whether or not to use color, the color depth (for PS), the
          plot orientation (landscape or portrait), the size of the
          plot, whether or not to use Vector or PS fonts, the name of
          the file to create, whether to send the file to a printer,
          and the print command.

 CALLING SEQUENCE:
 
          PLOT_PRINT,PLOT_PROCEDURE
 
 INPUTS:
          PLOT_PROCEDURE - A string containing the name of the
                           procedure - or the executable IDL code - that
                           creates the desire graphics. See EXAMPLE
                           below for more details.


 KEYWORD PARAMETERS:
 
          PRINTPARS - a structure of the following form (default
                      values indicated), whose values are used to
                      set the initial value of this quasi-compound widget:

          PRINTPARS={ $
                      device:0, $  ; 0=PS, 1=HP, 2=PCL, 3=CGM
                      psfont:0, $  ; 0=use vector fonts, 1=use PS fonts.
                      color:1, $   ; 0=B&W, 1=color
                      depth:2, $   ; PS resolution: 0=>1, 1=>2, 2=>4, 4=>8.
                      orient:0, $  ; 0=portrait, 1=landscape
                      size:1, $    ; 0=small, 1=large, 2=custom (i.e., use
                                     plotsize)
                      plotsize:[xsize,ysize,xoffset,yoffset], $
                                   ; keyword to the DEVICE command,
                                   ; in inches. only used if size=2.
                      file_name:'idl.ps', $ ; default file name
                      print:1, $   ; 0=print only to file, 1=send to printer.
                      command:'lpr -Plp'} ; print command

          GROUP - the standard GROUP_LEADER keyword, which is passed directly
                  to XMANAGER when the PLOT_PRINT widget is created.

 COMMON BLOCKS:
 
          PLOT_PRINT, plot_printpars
 
                     where plot_printpars = the current state of
                     the printpars structure.

 SIDE EFFECTS:
 
          The returned value of the printpars structure, if passed,
          is changed to reflect the settings changes made by the
          user.  Thus, settings shown in the widget upon subsequent
          calls to plot_print with the same printpars structure will
          show the same settings as the last call to PLOT_PRINT.

 RESTRICTIONS:
 
          Requires widgets.  Requires several programs in the windt
          library, including a modified version of CW_FIELD!
 
          The PLOT_PRINT widget is modal.

 EXAMPLE:
 
         This program is intended to be used from within another
         widget application, where a procedure is already defined
         that creates the graphics.  You can then add a WIDGET_BUTTON
         to this application, labelled "Print", for example, that
         when pressed calls PLOT_PRINT, with the name of the plot
         creation procedure as the input. i.e., pressing the "Print"
         button would execute the IDL code < PLOT_PRINT,"myplot" >.

         For example:

         PRO MYPLOT_EV,event

         widget_control,event.id,get_uvalue=eventval
         if eventval eq 'print' then plot_print,'myplot_plot'
         if eventval eq 'done' then widget_control,event.top,/destroy
         return
         end

         PRO MYPLOT_PLOT

         plot,[1,2],title='My Plot'
         return
         end

         PRO MYPLOT

         base=widget_base(mbar=menubar)
         file=widget_button(menubar,/menu,value='File')
         print=widget_button(file,value='Print...',uvalue='print')
         done=widget_button(file,value='Quit',uvalue='done')
         window=widget_draw(base,xsize=400,ysize=300)
         widget_control,base,/realize
         myplot_plot
         xmanager,'myplot',base,event='myplot_ev'
         return
         end
 
         Of course, you can call the program right from the command
         line too, as in

         IDL> plot_print,'x=vector(0.,!pi,100) & y=sin(5*x) & plot,x,y,/xstyle'

 MODIFICATION HISTORY:
 
         David L. Windt, Bell Labs, March 1997

         May 1997 - Modified use of MODAL keyword to work with
                    changes in IDL V5.0.

         June 1997 - Changed text and field widgets so that it's no
                     longer necessary to hit  after entering
                     text.  But this requires use of the modified
                     CW_FIELD widget.

         January 1998 - Added support for CGM graphics; switched
                        plot_print.device values for HP and PCL
                        output, to be consistent with the SP.PRO
                        routine.

         March 1998 - Made some attempt to include a better default
                      print command for HP-UX and Win95 platforms.

         May 1998 - The user is now prompted before attempting to
                    write over an existing file.

         windt@bell-labs.com

(See plot_print.pro)


PLOT_TEXT

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
 
        PLOT_TEXT

 PURPOSE:
 
        Add text in a box to a plot.  The text is located in one
        of 12 possible positions (i.e., upper left corner, lower
        right corner, etc.)

 CALLING SEQUENCE:
 
       PLOT_TEXT,TEXT_ARRAY[,POSITION=POSITION]
 
 INPUTS:
 
       TEXT_ARRAY - a string array of text

 KEYWORD PARAMETERS:

       POSITION - an integer, specifying the location of the text box:
 
                  0: no text is drawn
                  1: below plot, left
                  2: below plot, center
                  3: below plot, right
                  4: lower left
                  5: lower center
                  6: lower right
                  7: middle left
                  8: middle center
                  9: middle right
                  10: upper left
                  11: upper center
                  12: upper right
         
                  if not specified, default position=10

        CHARSIZE - the charsize value for the text

        COLOR - an array of colors to be used for each line of text

        NOBOX - set to inhibit drawing a box around the text

        BOXPADX - padding in character units, between text and box,
                  in x. default=2.0

        BOXPADY - padding in character units, between text and box,
                  in y. default=0.5

        FONT - Set to an integer from 3 to 20, corresponding to the
               Hershey vector font sets, referring to the font used
               to display the text.  If a font other than !3 is used
               in the text string, then FONT should be set
               accordingly. (Any font commands embedded in the text
               string are ignored.)

        BOXFUDGEX - A scaling factor, used to fudge the width of the
                    box surrounding the text.  Default=1.0.

        Plus all valid graphics keywords for xyouts and plots
       
 RESTRICTIONS:
 
       When specifying a position of 1,2 or 3, you'll need to (a) use
       the same charsize value for the plot and for the plot_text,
       and (b) draw the plot with an extra ymargin(0).  i.e., set
       ymargin(0)=7+n_elements(text_array)


 MODIFICATION HISTORY:
 
       David L. Windt, Bell Labs, March 1997
       windt@bell-labs.com

       October, 1997, dlw:

       Now using the TEXT_WIDTH function, in order to do a somewhat
       better job of drawing the box around the text.

       NONPRINTER_SCALE keyword parameter is now obsolete.

       BOXFUDGEX keyword parameter added.

(See plot_text.pro)


PROFILE_NI

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
 
        PROFILE_NI

 PURPOSE:

        Extract a profile from an image noninteractively.
        
 CALLING SEQUENCE:
 
        Result = PROFILE_NI(IMAGE,COORDS)
        
 INPUTS:
 
        IMAGE - data array.  May be any type except complex.
                
        COORDS - 2 x 2 array of x and y coordinate of profile endpoints,
                [[X0,Y0],[X1,Y1]]
        
 KEYWORD PARAMETERS:
 
       XSTART, YSTART - starting (x,y) location of lower left corner
                        of image.
        
 OUTPUTS:
 
        Result = 1-D array of image values along the line from

 MODIFICATION HISTORY:
 
        Adapted from PROFILE
        
        D. L. Windt, Bell Laboratories, November 1991.
        windt@bell-labs.com
        

(See profile_ni.pro)


PWD

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
 
        PWD
        
 CATEGORY:
 
       Stupid little convenience routines.
   
 PURPOSE:
 
       Print the current directory, like the Unix 'pwd' command.
        
 CALLING SEQUENCE:
 
       PWD
 MODIFICATION HISTORY:

       David L. Windt, Bell Labs, February 1998
       windt@bell-labs.com

(See pwd.pro)


RECROI

[Previous Routine] [Next Routine] [List of Routines]

 NAME:

        RECROI
        
 PURPOSE:

        Define a rectangular region of interest of an image using the
        image display system and the cursor/mouse.
                
 CATEGORY:

        Image processing.
        
 CALLING SEQUENCE:
 
        Result=RECROI(SX,SY[,XVERTS,YVERTS])
        
 INPUTS:
 
        SX, SY = size of image, in pixels.
        
 KEYWORD PARAMETERS:
 
       X0, Y0 - coordinate of lower left corner of image on display.
                if omitted, (0,0) is assumed.  Screen device
                coordinates.
            
       ZOOM - zoom factor, if omitted, 1 is assumed.
        
       XAXIS, YAXIS - optional 1-d arrays corresponding to the x and
                      y scales of image. Needed only if XROI and/or
                      YROI are specified.
            
       XROI, YROI - optional output vectors associated with the
                    digitized rectangular region of interest.  XAXIS
                    and YAXIS keyword parameters must be supplied.
            
 OUTPUTS:
 
        Result = vector of subscripts of pixels inside the region.
        
 OPTIONAL OUTPUTS:
 
       XVERTS, YVERTS - optional output parameters which will contain
                        the vertices enclosing the region.  Setting
                        NOREGION inhibits the return of the pixel
                        subscripts.
            
 COMMON BLOCKS:
 
        Colors is used to obtain the current color table which is modified
       and then restored.
        
 SIDE EFFECTS:
 
        For this implementation, bit 0 of each pixel is used to draw ; the
       outline of the region.  You WILL have to change this to fit
       the capabilities and procedures of your display.  ; The lowest
       bit in which the write mask is enabled is changed.
         
 PROCEDURE:
 
        The write mask for the display is set so that only bit 0 may be
       written.  Bit 0 is erased for all pixels.  The color tables
       are loaded with odd values complemented, even values
       unchanged.  A message is printed, assuming a mouse, indicating
       the effect of the three buttons.  The operator marks opposite
       corners of the rectangle.
        
 MODIFICATION HISTORY:
 
        Adapted from DEFROI
        
        D. L. Windt, Bell Laboratories, November 1989
        windt@bell-labs.com

(See recroi.pro)


RECTANGLE

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
 
       RECTANGLE
                
 PURPOSE:
 
        Draw a rectangle on a plot.
                
 CALLING SEQUENCE:
 
        RECTANGLE,X0,Y0,XLENGTH,YLENGTH
                
 INPUTS:

       X0, Y0 - Points specifying a corner of the rectangle.

       XLENGTH, YLENGTH - the lengths of the sides of the rectangle,
                          in data coords.
       
 KEYWORD PARAMETERS:
 
       FILL = set to fill rectangle.
                
       FCOLOR = fill color.
                
       Graphics keywords: CHARSIZE,COLOR,LINESTYLE,NOCLIP,
       T3D,THICK,Z,LINE_FILL,ORIENTATION,DEVICE
                
 MODIFICATION HISTORY:
 
        D. L. Windt, Bell Laboratories, September 1990.
        
       Added device keyword, January 1992.

       windt@bell-labs.com
                

(See rectangle.pro)


REC_IMAGE

[Previous Routine] [Next Routine] [List of Routines]

 NAME:

       REC_IMAGE
       
 PURPOSE:
 
       Extract a rectangular portion of a previously displayed image.
       
 CALLING SEQUENCE:
 
        SMALL_IMAGE=REC_IMAGE(BIG_IMAGE)
        
 INPUTS:
 
       BIG_IMAGE = array containing original image
                
 OUTPUTS:
 
        SMALL_IMAGE = portion of big_image
                
 PROCEDURE:
 
        RECROI is used to digitize a portion of the image.
                
 MODIFICATION HISTORY:
 
        David L. Windt, Bell Labs, Feb. 1992.
        windt@bell-labs.com
        

(See rec_image.pro)


ROI_WIDTH

[Previous Routine] [Next Routine] [List of Routines]

 NAME:

      ROI_WIDTH
      
 PURPOSE:
 
        Measure the width of a region of curve that has been previously
       plotted. The region is defined to be within ymin and ymax of a
       digitized region of the curve.
        
 CALLING SEQUENCE:
 
        Result=ROI_WIDTH(XAXIS,YAXIS)
        
 INPUTS:
 
       XAXIS - the x axis variable which has been plotted.
        
       YAXIS - the y axis variable which has been plotted.
        
 KEYWORD PARAMETERS:
 
       YMIN - minimum value of digitized region of interest.
        
       YMAX - maximum value of digitized region of interest.
        
       NOHIGHLIGHT - set to inhibit highlighting the region of 
                     interest.
                
       H_COLOR - the color index for highlighting the region of 
                 interest. Default is 7 (Yellow).
                
       H_THICK - the thickness for highlighting the region of
                 interest.
                
       NOLABEL - set to inhibit labelling fwhm.
        
       MANUAL - set to disable automatic location selection for
                labels.
            
       L_HEADER - string specifying the label header. Default-''.
        
       L_COLOR - color index for the label.
        
       L_FORMAT - format string for label (eg. '(f4.2)').
        
       UNITS - string specifying units along x axis.
        
       CHARSIZE - size of label text.
        
       PSYM - psym
   
 OUTPUTS:

       Result - the full-with-half-max of the region of interest of
                the curve, in x-axis data units.
                
 OPTIONAL OUTPUT PARAMETERS:
 
       ROI - the subscripts of the digitized region of interest.
        
       WIDTH_ROI - the subscripts of the region between the ymin and
                   ymax points.
            
       LINE_PTS - a 4-element array containing the coordinates of the
                  line drawn on the plot: [x0,x1,y0,y1]
            
       LABEL - the label for the plot.
        
       L_POS - a two element array containing the x,y coordinates of
               the label, in data coords.
            
                
 SIDE EFFECTS:
 
       TEK_COLOR is used to load in the tektronix colors.
       The region of interest of the curve is highlighted.
       The width is labelled.
        
 RESTRICTIONS:
 
        The data must be plotted prior to calling ROI_WIDTH
        
 PROCEDURE:
 
        The user is asked to digitize the endpoints of the
        region of interest with the mouse.  The region is
        highlighted, and the width is labelled.
        
 MODIFICATION HISTORY:
 
        D. L. Windt, Bell Laboratories, October 1990.
        windt@bell-labs.com
        

(See roi_width.pro)


ROTATION

[Previous Routine] [Next Routine] [List of Routines]

 NAME:

           ROTATION
 
 PURPOSE:
 
            Rotate two vectors by a specified amount.
            
 CALLING SEQUENCE:
 
            ROTATION,X,Y,DEG,NX,NY
            
 INPUTS:

           X,Y   :orignal data point pairs
           
            DEG   :degrees to rotate.
            
 OUTPUTS:
 
            Nx, Ny = rotated point pairs.
            
 MODIFICATION HISTORY:
 
            Jeff Bennett, U of Colorado

(See rotation.pro)


SHIFT_PLOT

[Previous Routine] [Next Routine] [List of Routines]

 NAME:

       SHIFT_PLOT
       
 PURPOSE:
 
       Interactively slide a previously plotted array using the mouse.
   
 CALLING SEQUENCE:
 
       SHIFT_PLOT,X[,Y,SHIFT=SHIFT]
   
 INPUTS:
 
        X,Y - array variables
   
 KEYWORD PARAMETERS:
 
        Same as for oplot
   
 OPTIONAL OUTPUT PARAMETERS:
 
        SHIFT - the shift along the x-axis
   
 PROCEDURE:
 
   MENUS is used to get input. The previously plotted array is first
   erased, then oplot'ed, with the incremental shift.
   
 MODIFICATION HISTORY:
 
   David L. Windt, Bell Labs, February, 1990
   windt@bell-labs.com

(See shift_plot.pro)


SHOW_CT

[Previous Routine] [Next Routine] [List of Routines]

 NAME:

       SHOW_CT
       
 PURPOSE:

       Make a window and show the first 32 colors in the current
       color table.
            
 CALLING SEQUENCE:
 
        SHOW_CT
        
 MODIFICATION HISTORY:
 
        David L. Windt, Bell Labs, November 1989
        windt@bell-labs.com

        DLW, November, 1997 - Removed default window position values, so
                             that the window is now visible on any
                             size display.
        

(See show_ct.pro)


SINC

[Previous Routine] [Next Routine] [List of Routines]

 NAME:

         SINC

 PURPOSE:

         Function to return the value of the SINC function,
         i.e., sin(x)/x.

 CALLING SEQUENCE:

         Result = SINC(X)
 
 INPUTS:

         X - Input value.  Scalar or array.

 OUTPUTS:

         Result - Value of SIN(X)/X. 

 PROCEDURE:

         Straightforward; except Result is explicitly set to
         one when X=0.

 MODIFICATION HISTORY:

         David L. Windt, Bell Laboratories, May 1997
         windt@bell-labs.com

(See sinc.pro)


SINCSQUARE_FIT

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
 
        SINCSQUARE_FIT
        
 PURPOSE:
 
        Fit y=f(x) where:
        F(x) = a0*( sin(a1*(x-a2))/(a1*(x-a2)) )^2 + a3
        Estimate the parameters a0,a1,a2,a3 and then call curvefit.
        
 CALLING SEQUENCE:
 
        YFIT = SINC_FIT(X,Y,A)
        
 INPUTS:
 
        X - independent variable, must be a vector.
        
       Y - dependent variable, must have the same number of points as
           x.
                
 OUTPUTS:
 
        YFIT = fitted function.
        
 OPTIONAL OUTPUT PARAMETERS:
 
        A = Fit coefficients. A four element vector as described above.

 MODIFICATION HISTORY:
 
        Adapted from GAUSSFIT
        
        D. L. Windt, Bell Laboratories, March, 1990
        windt@bell-labs.com

(See sincsquare_fit.pro)


SMALL_WINDOW

[Previous Routine] [Next Routine] [List of Routines]

 NAME:

       SMALL_WINDOW
       
 PURPOSE:

       Make a 500x400 graphics window.
       
 CATEGORY:
 
       Stupid little convenience routines.
       
 CALLING SEQUENCE:
 
        SMALL_WINDOW [,WINDOW_NUM]
        
 OPTIONAL INPUT PARAMETERS:
 
        WINDOW_NUM - the window number.
        
 KEYWORD PARAMETERS:
 
       LAPTOP - set this to make a nice window (400x300) for a
                small-screened laptop
        
 MODIFICATION HISTORY:
 
        David L. Windt, Bell Laboratories, March 1990.
        windt@bell-labs.com
        
        

(See small_window.pro)


SP

[Previous Routine] [Next Routine] [List of Routines]

 NAME:

       SP

 PURPOSE:  

       Execute SET_PLOT, and optionally some handy settings.

 CALLING SEQUENCE:

       SP[,DEVICE,N_PLOTS]

 OPTIONAL INPUTS:
 
            DEVICE = 0 for set_plot,'PS' 
                    1 for set_plot,'HP'
                    2 for set_plot,'PCL'
                    3 for set_plot,'X'
                    4 for set_plot,'MAC'
                    5 for set_plot,'WIN'
                    6 for set_plot,'SUN'
                    7 for set_plot,'TEK'
                    8 for set_plot,'CGM'
 
           if DEVICE is not set, the graphics device will be set
           to the platform-dependent default.

           N_PLOTS = 1 for !p.multi=0
                     2 for !p.multi=[0,1,2]
                     3 for !p.multi=[0,1,3]
                     4 for !p.multi=[0,2,2]
                     
 KEYWORD PARAMETERS:
 
           SMALL - Set to make a small plot.
           
           LANDSCAPE - Set for landscape mode when device=0,1, or 2.
           
           FULL_PAGE - Set for full page plotting when device=0, 1,
                       or 2. Only has an effect when in portrait mode
                       (landscape=0) for PS and PCL devices.
                       FULL_PAGE is set automatically if N_PLOTS is
                       greater than 1.
                       
           HARDWARE - Set for hardware fonts.
           
           FILE - Name of output file.
           
           ISOTROPIC - Set for isotropic (equal x and y) scaling.
           
           COLOR - Set to enable color for PS and PCL devices.

           PLOTSIZE - A four-element array specifying the
                      [XSIZE,YSIZE,XOFFSET,YOFFSET] keywords (in
                      INCHES) to the DEVICE procedure.  If PLOTSIZE
                      is set, then the SMALL and FULL_PAGE keywords
                      are ignored.  If PLOTSIZE is not set, then
                      default values are used for these parameters
                      that make decent-looking plots on 8-1/2 x 11"
                      paper.

 MODIFICATION HISTORY:
 
       David L. Windt, Bell Labs November 1989
       Added DEVICE=4, November 1990.
       Added ISOTROPIC keyword, August 1991.
       Added COLOR keyword, Sept 1991.
       Added pcl support, completely changed device<->number mapping,
             and changed functionality of small/full_page/landscape/size
             keywords, May 1997.

       DLW, September 1997: On Unix platforms, if DEVICE is not
       set, the graphics device is set to 'X' if the IDL_DEVICE
       environment variable is not defined.

       DLW, January 1998: Added support for CGM graphics; this
       routine will do nothing more than issue the SET_PLOT,'CGM'
       command, but is included for compatability with the PLOT_PRINT
       routine.  When using the CGM device, you will likely want to
       set the color table entry for !p.color to black; otherwise
       you'll get a white plot on a white background.

       Also, fixed bug that caused graphics output to anything but PS
       to fail!  (Doh!)

       windt@bell-labs.com
       

(See sp.pro)


SQUARE_PLOT

[Previous Routine] [Next Routine] [List of Routines]

 NAME:

      SQUARE_PLOT
      
 PURPOSE:
 
       Define !p.region so plots come out with aspect ratio of 1.
        
 CALLING SEQUENCE:
 
       SQUARE_PLOT
                
 KEYWORD PARAMETERS:
 
       CENTER - set to center plot in window.
                
 MODIFICATION HISTORY:
 
        David L. Windt, Bell Laboratories, December 1991.
        windt@bell-labs.com

(See square_plot.pro)


SYM

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
        SYM

 PURPOSE:
 
        This function provides a convenient way to utilize the
        USERSYM procedure to create an extended choice of plotting
        symbols, and is intended to be used directly with the PSYM
        keyword to PLOT, OPLOT, etc.

 CALLING SEQUENCE:
 
        Result=SYM(NUMBER)

 INPUTS:
 
        NUMBER - symbol number
 
               0 : dot
               1 : filled circle
               2 : filled upward triangle
               3 : filled downward triangle
               4 : filled diamond
               5 : filled square
               6 : open circle
               7 : open upward triangle
               8 : open downward triangle
               9 : open diamond
              10 : open square
              11 : plus
              12 : X
              13 : star
              14 : filled rightfacing triangle
              15 : filled leftfacing triangle
              16 : open rightfacing triangle
              17 : open leftfacing triangle

 OUTPUTS:
 
        The function returns the symbol number to be used with the
        PSYM keyword in the PLOT, OPLOT, etc. commands

 SIDE EFFECTS:
 
        The USERSYM procedure is used to create a symbol definition.

 EXAMPLE:

        To produce a plot using open circles as plotting symbols:
 
        PLOT,X,Y,PSYM=SYM(6)

 MODIFICATION HISTORY:
 
        Martin Schultz, Harvard University, 22 Aug 1997: VERSION 1.00
        
        (with some minor changes to the information in this header by
        D. Windt, windt@bell-labs.com)

(See sym.pro)


SYMBOLS

[Previous Routine] [Next Routine] [List of Routines]

 NAME:

         SYMBOLS
         
 PURPOSE:

         Create custom plotting symbols
         
 CALLING SEQUENCE:
 
          SYMBOLS,SYMBOL_NUMBER,SCALE
            
 INPUTS:
         SYMBOL_NUMBER:
         
                1 = open circle
                2 = filled circle
                3 = arrow pointing right
                4 = arrow pointing left
                5 = arrow pointing up
                6 = arrow pointing down
                7 = arrow pointing up and left (45 degrees)
                 8 = arrow pointing down and left
                 9 = arrow pointing down and right.
                 10 = arrow pointing up and right.
                 11 through 18 are bold versions of 3 through 10
                 19 = horizontal line
                 20 = box
                 21 = diamond
                 22 = triangle
                 30 = filled box
                 31 = filled diamond
                 32 = filled triangle
                 
         SCALE - size of symbols.
         
 KEYWORD PARAMETERS:
 
                COLOR - color of symbols
                
 SIDE EFFECTS:
 
           The desired symbol is stored in the user buffer and 
            will be plotted if !P.PSYM = 8.

 MODIFICATION HISTORY:
 
                Jeff Bennett, U of Colorado, 198?

(See symbols.pro)


TEXT_WIDTH

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
 
        TEXT_WIDTH

 PURPOSE:
 
        Function to determine the actual displayed width
        (approximately!) of a string of text, in normalized character
        units, accounting for the fact that non-equal spacing is used
        when such a string is displayed on a plot using XYOUTS.

        This function is used, for example, by the PLOT_TEXT and
        LEGEND procedures to ~correctly draw a box around displayed
        text.

 CALLING SEQUENCE:
 
       Result=TEXT_WIDTH(TEXT_STRING)
 
 INPUTS:
 
       TEXT_STRING - a string of text

 KEYWORD PARAMETERS:

       FONT - Set to an integer from 3 to 20 (corresponding to the
              Hershey vector font sets,) referring to the font that
              will be used to display the text. (Any font commands
              embedded in the text string are ignored.)

 RESTRICTIONS:

       This function hardly works perfectly, especially when the text
       string contains a mix of fonts; superscripts and subscripts
       will really mess things up as well.  But it comes close in
       many instances.

 PROCEDURE:

       A table of normalized character widths (determined using the
       !3 font) is used to determine the width of the text string.
       In order to account for the use of IDL font manipulation
       commands, the '!' symbol and the character immediately
       following it are not counted, except for the case of two
       consecutive '!' symbols.

 EXAMPLE:

       Determine the width of a text string:

       width=TEXT_WIDTH('!3This is some displayed text',font=3)

 MODIFICATION HISTORY:
 
       David L. Windt, Bell Labs, October 1997
       windt@bell-labs.com

(See text_width.pro)


TRACK_PLOT

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
 
       TRACK_PLOT
                
 PURPOSE:

       A procedure to plot X vs Y in a widget, track the cursor
       position, and interactively display the Y(X) value.

 CALLING SEQUENCE:

       TRACK_PLOT,X,Y

 INPUTS:

       X, Y -  1-D arrays

 KEYWORD PARAMETERS:

       WXSIZE - Draw widget X size, in pixels. (Default=640)

       WYSIZE - Draw widget Y size, in pixels. (Default=480)

       CROSSHAIR - Set this to display a crosshair at the current Y(X) value.

       plus all valid IDL PLOT keywords.  

 RESTRICTIONS:
 
       Requires widgets.  Requires use of the VALUE_TO_INDEX function
       in the windt library.

 EXAMPLE:

      Create some X,Y data and plot it using TRACK_PLOT:
 
      X=VECTOR(0.,100.,256)
      Y=SIN(X/5.)*EXP(-X/20.)
      TRACK_PLOT,X,Y

 MODIFICATION HISTORY:

      D. L. Windt, Bell Laboratories, August 1997
      windt@bell-labs.com

      March, 1998 - Added crosshair option and CROSSHAIR keyword.

(See track_plot.pro)


VALUE_TO_INDEX

[Previous Routine] [Next Routine] [List of Routines]

 NAME:

    VALUE_TO_INDEX

 PURPOSE:

    Given a (1D) ARRAY and a scalar VALUE, determine the array INDEX
    corresponding to the element of the array that is closest in
    magnitude to the specified value.

 CALLING SEQUENCE:

   Index=VALUE_TO_INDEX(ARRAY, VALUE)
 
 INPUTS:

   ARRAY = 1D array of values
   
   VALUE = scalar value

 EXAMPLE:

  ARRAY=findgen(100)/99.*5          ; create an array of 100 pts from 0 to 5.

  Index=VALUE_TO_INDEX(ARRAY,3.125) ; find the element of ARRAY whose value
                                    ; is closest to 3.125.
                                   
  In this case, Index=62 (i.e., ARRAY(62)=3.13131)
 
 MODIFICATION HISTORY:

   David L. Windt, Bell Labs, March 1997.

   May 1998 - Realized that this function is hardly necessary, as one
              can just make wise use of the min function and
              the !c system variable.  Duh!
   
   windt@bell-labs.com

(See value_to_index.pro)


VECTOR

[Previous Routine] [Next Routine] [List of Routines]

 NAME:
 
        VECTOR

 PURPOSE:
 
       Make a vector of PTS points, with values ranging from MIN to
       MAX.

 CALLING SEQUENCE:
 
        Result = VECTOR(MIN,MAX,PTS)

 INPUTS:
 
       MIN - Starting value for vector.
        
       MAX - Ending value for vector.
        
       PTS - Number of points.

 KEYWORDS:
 
       LOGARITHMIC - set for logarithmic spacing between points.
                     [MIN and MAX must be positive, i.e., gt 0]

 OUTPUTS:
 
       This function returns a vector of PTS points, ranging from MIN
       to MAX.  The returned vector is of the same type as MIN/MAX.

 EXAMPLE:

        X=VECTOR(5.,100.,1000)
        
        This example returns a 1-D Floating point array X, made up of 
        1000 points, ranging from 5. to 100.

        X=VECTOR(5.d,100.d,1000)
        
        This example returns a 1-D Double point array X, made up of 
        1000 points, ranging from 5. to 100.

 MODIFICATION HISTORY:
 
       David L. Windt, Bell Labs, June 1993.
        
       March, 1997: modified code so returned vector is same type as
                    MAX.  added LOGARITHMIC keyword.
                    
       May, 1998 - corrected a bug which occurred when LOGARITHMIC
                   was set and PTS=1.

       October, 1998 - corrected a bug which, when LOGARITHMIC was
                       set, had caused the log of MIN and MAX to be
                       returned if these parameters are passed as
                       named variables (rather than constants.)
                    
       windt@bell-labs.com
                    

(See vector.pro)


XWD2GIF

[Previous Routine] [List of Routines]

 NAME:
 
	XWD2GIF

 PURPOSE:
 
       Convert an XWD image file to a GIF image file.

 CALLING SEQUENCE:
 
       XWD2GIF[,FILE=FILE]

 KEYWORDS:
 
       FILE - The name of the XWD file.  If the XWD file is called
              file.xwd, then the newly created gif file will be called
              file.gif.  

 PROCEDURE:

       The procedure is just a simple interface to the READ_XWD and
       WRITE_GIF routines.

 MODIFICATION HISTORY:
 
       David L. Windt, Bell Labs, May 1998.
 	
       windt@bell-labs.com
                    

(See xwd2gif.pro)