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

- ATOMIC_WEIGHT
- BESELI_FRACT
- BESELK_FRACT
- CHEM2LBL
- CHISQR
- CLEAR
- * CONT_IMAGE
- CONT_IMAGE2
- CURVE_LABEL
- CW_CURVE_LABEL
- CW_DRAWSIZE
- CW_FIELD
- CW_PLOTAXES
- CW_PLOTAXIS
- CW_PLOTLABEL
- CW_PLOTSTYLE
- CW_PLOTSTYLES
- CW_PLOTTITLE_CHAR
- CW_VECTOR
- DGTZ_IMAGE
- * DGTZ_PLOT
- DIALOG
- DISPLAY_FONT
- DLIB
- ELECTRON_MFP
- EPLOT
- EROM
- ERRORF_FIT
- EXPO_FIT
- FILE_DATE
- FINDEX
- FRACTAL_FIT
- FWHM
- GAUSSEXPO_FIT
- GAUSS_FIT
- * GAUS_CONVOL
- GET_PEAK
- GET_PT
- GET_ROI
- GHOSTVIEW
- * GREEK
- KAISER_BESSEL
- LEGEND
- LPRINT
- LS
- MAKE_LATEX_TBL
- MK_HTML_HELP
- MORE
- OEPLOT
- PLOT_MOVIE
- PLOT_PRINT
- PLOT_TEXT
- PROFILE_NI
- PWD
- RECROI
- RECTANGLE
- REC_IMAGE
- ROI_WIDTH
- ROTATION
- SHIFT_PLOT
- SHOW_CT
- SINC
- SINCSQUARE_FIT
- SMALL_WINDOW
- SP
- SQUARE_PLOT
- SYM
- SYMBOLS
- TEXT_WIDTH
- TRACK_PLOT
- VALUE_TO_INDEX
- * VECTOR
- XWD2GIF

# 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)