%VERSION:2
%TITLE:ROUTINES
214
1499
0:<Overview>
5720:ABS
6513:ACOS
7322:ALOG
8042:ALOG10
8435:ASIN
8920:ASSOC
10816:ATAN
12012:AXIS
15952:BESELI
16570:BESELJ
17270:BESELY
17982:BINDGEN
18742:BREAKPOINT
20582:BYTARR
21267:BYTE
22704:BYTEORDER
27635:BYTSCL
29118:CALL_EXTERNAL
35927:CALL_FUNCTION
37114:CALL_PROCEDURE
38321:CATCH
41161:CD
42575:CEIL
43198:CHECK_MATH
46226:CINDGEN
46879:CLOSE
47661:COLOR_CONVERT
49561:COLOR_QUAN
56080:COMPLEX
58531:COMPLEXARR
59223:CONJ
59871:CONTOUR
79847:CONVERT_COORD
82311:CONVOL
85412:COS
86326:COSH
87175:CREATE_STRUCT
88516:CURSOR
92548:DBLARR
93236:DEFINE_KEY
101856:DEFSYSV
103398:DELETE_SYMBOL
103982:DELLOG
104424:DELVAR
105098:DEVICE
105755:DILATE
109477:DINDGEN
110085:DOUBLE
111623:EMPTY
112169:EOF
113566:ERASE
114693:ERODE
117816:ERRORF
118484:EXECUTE
119990:EXIT
120224:EXP
121192:EXPAND_PATH
127758:FFT
131082:FINDFILE
132289:FINDGEN
132957:FINITE
133962:FIX
135404:FLOAT
136928:FLOOR
137549:FLTARR
138243:FLUSH
138708:FREE_LUN
139227:FSTAT
141874:GAMMA
142641:GAUSSINT
143380:GET_KBRD
144264:GET_LUN
145532:GET_SYMBOL
146172:GETENV
147322:GRID3
151470:HANDLE_CREATE
155557:HANDLE_FREE
156114:HANDLE_INFO
158066:HANDLE_MOVE
159574:HANDLE_VALUE
161384:HELP
166637:HISTOGRAM
171557:IMAGINARY
172128:INDGEN
172689:INTARR
173327:INTERPOLATE
178763:INVERT
180627:IOCTL
185393:ISHFT
186135:JOURNAL
187460:KEYWORD_SET
188419:LABEL_REGION
190371:LINDGEN
190972:LINKIMAGE
196845:LNGAMMA
197419:LONARR
198052:LONG
199538:MAKE_ARRAY
202075:MAP_CONTINENTS
202936:MAP_GRID
205031:MAP_IMAGE
210157:MAP_SET
221528:MAX
222795:MEDIAN
224513:MESSAGE
226880:MIN
227926:N_ELEMENTS
228744:N_PARAMS
229304:N_TAGS
230520:ON_ERROR
231174:ON_IOERROR
232234:OPEN
247647:OPLOT
250322:PLOT
254794:PLOT_IO
255342:PLOT_OI
255890:PLOT_OO
256449:PLOTS
259576:POINT_LUN
261346:POLY_2D
265927:POLYFILL
272837:POLYFILLV
275616:POLYSHADE
281607:PRINT
283349:RANDOMN
285023:RANDOMU
286981:READ
290842:READ_JPEG
295830:READS
297179:READU
300366:REBIN
302674:REFORM
304648:REPLICATE
305640:RESTORE
306866:REWIND
307311:RIEMANN
311689:ROBERTS
312362:ROTATE
314490:ROUND
315126:SAVE
317882:SET_PLOT
320973:SET_SHADING
323761:SET_SYMBOL
324448:SETENV
324864:SETLOG
326527:SHADE_SURF
332765:SHADE_VOLUME
337083:SHIFT
338735:SIN
339857:SINDGEN
340483:SINH
341569:SIZE
342893:SKIPF
344379:SMOOTH
345266:SOBEL
346013:SORT
346905:SPAWN
353375:SQRT
354199:STOP
354920:STRARR
355333:STRCOMPRESS
356306:STRING
359467:STRLEN
360298:STRLOWCASE
361091:STRMESSAGE
361873:STRMID
363115:STRPOS
364707:STRPUT
366335:STRTRIM
367652:STRUPCASE
368407:SURFACE
377168:SYSTIME
378286:TAG_NAMES
379321:TAN
380049:TANH
381020:TAPRD
382566:TAPWRT
383821:TEMPORARY
384786:THIN
386151:TOTAL
387863:TRANSPOSE
388426:TRIANGULATE
392138:TRIGRID
396586:TRNLOG
400000:TV
405817:TVCRS
407517:TVLCT
411365:TVRD
414102:TVSCL
416072:USERSYM
417905:VOIGT
418440:VOXEL_PROJ
427392:WAIT
427970:WDELETE
428827:WEOF
429426:WHERE
431700:WIDGET_BASE
449316:WIDGET_BUTTON
459440:WIDGET_CONTROL
483136:WIDGET_DRAW
495887:WIDGET_EVENT
501919:WIDGET_INFO
509331:WIDGET_LABEL
516297:WIDGET_LIST
524770:WIDGET_SLIDER
535031:WIDGET_TEXT
546822:WINDOW
551428:WMENU
553330:WRITE_JPEG
557554:WRITEU
559798:WSET
560700:WSHOW
561849:XYOUTS
;+
    How to Use Online Help
    
    All of IDL's built-in routines are documented in 
    this section of the online help. Click on any routine 
    name in the scrolling list to see documentation for 
    that routine.
    
    Beneath the general description of the routine 
    are a number of sections that describe the calling 
    sequence for the routine, its arguments (if any), its 
    keywords (if any), and an example of using the rou-
    tine. These sections are described below.
    
    Calling Sequence
    
    The "Calling Sequence" section shows the proper 
    syntax for calling the function or procedure.
    
    Procedures
    
    IDL procedures have the calling sequence:
    
        PROCEDURE_NAME, Argument [, Optional_Arguments]
        
    where PROCEDURE_NAME is the name of the proce-
    dure, Argument is a required parameter, and 
    Optional_Argument is an optional parameter to the 
    procedure. Note that the square brackets around op-
    tional arguments are not used in the actual call to 
    the procedure, they are simply used to denote the op-
    tional nature of the arguments within this document.
    
    Functions
    
    IDL functions have the calling sequence:
    
        Result = FUNCTION_NAME(Argument [, 
        Optional_Arguments])
        
    where Result is the returned value of the func-
    tion, FUNCTION_NAME is the name of the function, Ar-
    gument is a required parameter, and Optional_Argument 
    is an optional parameter. Note that the square brack-
    ets around optional arguments are not used in the ac-
    tual call to the function, they are simply used to 
    denote the optional nature of the arguments within 
    this document. Note also that all arguments and key-
    word arguments to functions should be supplied within 
    the parentheses that follow the function's name.
    
    Functions do not always have to be used in as-
    signment statements (i.e., A=SIN(10.2)), they can be 
    used just like any other IDL expression. For example, 
    you could print the result of SIN(10.2) by entering 
    the command:
    
    PRINT, SIN(10.2)
    
    Arguments
    
    The "Arguments" section describes each valid ar-
    gument to the routine. Note that these arguments are 
    positional parameters that must be supplied in the 
    order indicated by the routine's calling sequence.
    
    Named Variables
    
    Often, arguments that contain values upon return 
    from the function or procedure ("output arguments") 
    are described as accepting "named variables". A named 
    variable is simply a valid IDL variable name. This 
    variable does not need to be defined before being used 
    as an output argument. Note, however that when an ar-
    gument calls for a named variable, only a named vari-
    able can be used-sending an expression causes an er-
    ror.
    
    Keywords
    
    The "Keywords" section describes each valid key-
    word argument to the routine. Note that keyword ar-
    guments are formal parameters that can be supplied in 
    any order.
    
    Keyword arguments are supplied to IDL routines by 
    including the keyword name followed by an equal sign 
    ("=") and the value to which the keyword should be 
    set. For example, to produce a plot with diamond-
    shaped plotting symbols, the PSYM keyword should be 
    set to 4 as follows:
    
    PLOT, FINDGEN(10), PSYM=4
    
    Note also that keywords can be abbreviated to 
    their shortest unique length. For example, the XSTYLE 
    keyword can be abbreviated to XST.
    
    Setting Keywords
    
    When the documentation for a keyword says some-
    thing similar to, "Set this keyword to enable loga-
    rithmic plotting," the keyword is simply a switch 
    that turns an option on and off. Usually, setting such 
    keywords equal to 1 causes the option to be turned 
    on. Explicitly setting the keyword to zero (or not 
    including the keyword) turns the option off.
    
    There is a "shortcut" that can be used to set a 
    keyword equal to 1 without the usual syntax (i.e., 
    KEYWORD=1). To "set" a keyword, simply it with a slash 
    character ("/"). For example, to plot a wire mesh sur-
    face with a skirt around it, set the SKIRT keyword to 
    the SURFACE routine as follows:
    
    SURFACE, DIST(10), /SKIRT
    
    Named Variables
    
    Often, keywords that contain values upon return 
    from the function or procedure ("output arguments") 
    are described as accepting "named variables". A named 
    variable is simply a valid IDL variable name. This 
    variable does not need to be defined before being used 
    with the keyword. Note, however that when a keyword 
    calls for a named variable, only a named variable can 
    be used-sending an expression causes an error.
    
    For example, the WIDGET_CONTROL procedure can re-
    turn the user values of widgets in a named variable 
    using the GET_UVALUE keyword. To return the user val-
    ue for a widget ID (contained in the variable mywid-
    get) in the variable userval, you would use the com-
    mand:
    
    WIDGET_CONTROL, mywidget, GET_UVALUE = userval
    
    Upon return from the procedure, userval contains 
    the user value. Note that userval did not have to be 
    defined before the call to WIDGET_CONTROL.
    
    Examples
    
    Most routines include a short example that dem-
    onstrates how the function or procedure is used. Most 
    of the examples are just one or two lines of IDL code 
    that can be entered at the IDL prompt. Others are code 
    fragments or routines designed to serve as examples 
    for you own programs.
    
;-
;+
ABS

The ABS function returns the absolute value of its 
argument.

Calling Sequence

        Result = ABS(X)
        
Arguments

    X
    
        The value for which the absolute value is 
        desired. If X is of complex type, ABS returns the 
        magnitude of the complex number:
        
        SQRT(Real^2 + Imaginary^2)
        
        If X is of complex or string type, the result is 
        returned as single-precision, floating-point type. 
        For all other types, the result has the same type as 
        X. If X is an array, the result has the same struc-
        ture, with each element containing the absolute 
        value of the corresponding element of X.
        
Example

To print the absolute value of -25, enter:

PRINT, ABS(-25)

IDL prints:

25

;-
;+
ACOS

The ACOS function returns the angle, expressed in 
radians, whose cosine is X (i.e., the arc-cosine). The 
range of ACOS is between 0 and pi.

Calling Sequence

        Result = ACOS(X)
        
Arguments

    X
    
        The cosine of the desired angle in the range (-1 
        LE X LE 1). If X is double-precision floating, the 
        result of ACOS is also double-precision. X cannot be 
        complex. All other types are converted to single-
        precision floating-point and yield floating-point 
        results. If X is an array, the result has the same 
        structure, with each element containing the arc-
        cosine of the corresponding element of X.
        
Example

To find the arc-cosine of 0.707 and store the result 
in the variable B, enter:

B = ACOS(0.707)

;-
;+
ALOG

The ALOG function returns the natural logarithm of X. 
The result has the same structure as X.

Calling Sequence

        Result = ALOG(X)
        
Arguments

    X
    
        The value for which the natural log is desired. 
        The result of ALOG is double-precision floating if X 
        is double-precision, and complex if X is complex. 
        All other types are converted to single-precision 
        floating-point and yield floating-point results. 
        When applied to complex numbers, the definition of 
        the ALOG function is:
        
        ALOG(x) = COMPLEX(log |x|, atan x)
        
Example

To print the natural logarithm of 5, enter:

PRINT, ALOG(5)

IDL prints:

1.60944

;-
;+
ALOG10

The ALOG10 function returns the logarithm to the base 
10 of X. This function operates in the same manner as the 
ALOG function.

Calling Sequence

        Result = ALOG10(X)
        
Arguments

    X
    
        The value for which the base 10 log is desired.
        
Example

To find the base 10 logarithm of 5 and store the 
result in the variable L, enter:

L = ALOG10(5)

;-
;+
ASIN

The ASIN function returns the angle, expressed in 
radians, whose sine is X (i.e., the arc-sine). The range 
of ASIN is between -pi/2 and pi/2. Rules for the type and 
structure of the result are the same as those given for 
the ACOS function.

Calling Sequence

        Result = ASIN(X)
        
Arguments

    X
    
        The sine of the desired angle, -1 LE X LE 1.
        
Example

To print the arc-sine of 0.707, enter:

PRINT, ASIN(0.707)

IDL prints:

0.785247

;-
;+
ASSOC

The ASSOC function associates an array structure with 
a file. It provides a basic method of random access input/
output in IDL. An associated variable, which stores this 
association, is created by assigning the result of ASSOC 
to a variable. This variable provides a means of mapping a 
file into vectors or arrays of a specified type and size.

Calling Sequence

        Result = ASSOC(Unit, Array_Structure [, Offset])
        
Arguments

    Unit
    
        The IDL file unit to associate with 
        Array_Structure.
        
    Array_Structure
    
        An expression of the data type and structure to 
        be associated with Unit are taken from 
        Array_Structure. The actual value of Array_Structure 
        is not used.
        
    Offset
    
        The offset in the file to the start of the data 
        in the file. For stream files, and RMS (VMS) block 
        mode files, this offset is given in bytes. For RMS 
        record-oriented files, the offset is specified in 
        records. Offset is useful for dealing with data 
        files that contain a descriptive header block fol-
        lowed by the actual data.
        
Example

Suppose that the file `images.dat' holds 5 images as 
256-element by 256-element arrays of bytes. Open the file 
for reading and create an associated variable by entering:

OPENR, 1, 'images.dat'	Open the file as file unit 1.

A = ASSOC(1, BYTARR(256, 256))	Make an associated variable.

Now A(0) corresponds to the first image in the file, 
A(1) is the second element, etc. To display the first 
image in the file, you could enter:

TV, A(0)

The data for the first image is read and then dis-
played. Note that the data associated with A(0) is not 
held in memory. It is read in every time there is a refer-
ence to A(0). To store the image in the memory-resident 
array B, you could enter:

B = A(0)

;-
;+
ATAN

The ATAN function returns the angle, expressed in 
radians, whose tangent is X (i.e., the arc-tangent). If 
two parameters are supplied, the angle whose tangent is 
equal to Y/X is returned. The range of ATAN is between -
pi/2 and pi/2 for the single argument case, and between -
pi and pi if two arguments are given.

Calling Sequence

        Result = ATAN(X)
        
        or
        
        Result = ATAN(Y, X)
        
Arguments

    X
    
        The tangent of the desired angle.
        
    Y
    
        An optional argument. If this argument is sup-
        plied, ATAN returns the angle whose tangent is equal 
        to Y/X. If both arguments are zero, the result is 
        undefined.
        
Examples

To find the arc-tangent of 0.707 and store the result 
in the variable B, enter:

B = ATAN(0.707)

The following code defines a function that converts 
Cartesian coordinates to polar coordinates. It returns 
"r" and "theta" given an "x" and "y" position:

FUNCTION TO_POLAR, X, Y	Define function TO_POLAR that accepts X 
and Y as arguments.

RETURN, [SQRT(X^2 + Y^2), ATAN(Y, X)
Return the distance and angle as a two-ele-
ment array.

END	End of function.

;-
;+
AXIS

The AXIS procedure draws an axis of the specified type 
and scale at a given position. The new scale is saved for 
use by subsequent overplots if the SAVE keyword parameter 
is set. The keyword parameters XAXIS, YAXIS, and ZAXIS 
specify the type of axis to be drawn, and its position.

Calling Sequence

        AXIS [[[, X], Y], Z]
        
Arguments

    X, Y, and Z
    
        Scalars giving the starting coordinates of the 
        new axis. If no coordinates are specified, the axis 
        is drawn in its default position as given by the 
        [XYZ]AXIS keyword. When drawing an X axis, the X 
        coordinate is ignored, similarly the Y and Z parame-
        ters are ignored when drawing their respective axes 
        (i.e., new axes will always point in the correct 
        direction).
        
Keywords

    SAVE
    
        Set this keyword to indicate that the scaling to 
        and from data coordinates established by the call to 
        AXIS is to be saved in the appropriate axis system 
        variable, !X, !Y, or !Z. If this keyword is not 
        present, the scaling is not changed.
        
    XAXIS
    
        Set this keyword to indicate that an X axis is 
        to be drawn. A call with XAXIS set to 0 draws an axis 
        under the plot window with the tick marks going 
        down, while a value of 1 draws an axis over the win-
        dow with tick marks going up. The axis position may 
        be overridden by the X, Y, and Z parameters.
        
    YAXIS
    
        Set this keyword to indicate that a Y axis is to 
        be drawn. In the same manner as XAXIS a parameter 
        value of 0 draws a Y axis to the left of the window, 
        and 1 draws on the right.
        
    ZAXIS
    
        Set this keyword to indicate that a Z axis is to 
        be drawn. As above, the positions are:
        
        1 = lower right, 2 = lower left, 3 = upper left, 
        and 4 = upper right.
        
    XTYPE
    
        Set this keyword to specify a logarithmic X 
        axis.
        
    YNOZERO
    
        Set this keyword to inhibit setting the minimum 
        Y axis value to zero when the Y data are all posi-
        tive and non-zero, and no explicit minimum Y value 
        is specified (using YRANGE, or !Y.RANGE). By 
        default, the Y axis spans the range of 0 to the max-
        imum value of Y, in the case of positive Y data. Set 
        bit 4 in !Y.STYLE to make this option the default.
        
    YTYPE
    
        Set this keyword to specify a logarithmic Y 
        axis.
        
Graphics Keywords Accepted

        See Chapter 2, Graphics Keywords and System 
        Variables, for the description of graphics and plot-
        ting keywords not listed above. CHANNEL CHARSIZE 
        CHARTHICK COLOR DATA DEVICE FONT NODATA NOERASE NOR-
        MAL SUBTITLE T3D TICKLEN XCHARSIZE XGRIDSTYLE XMAR-
        GIN XMINOR XRANGE XSTYLE XTHICK XTICKFORMAT XTICKLEN 
        XTICKNAME XTICKS XTICKV XTICK_GET XTITLE YCHARSIZE 
        YGRIDSTYLE YMARGIN YMINOR YRANGE YSTYLE YTHICK 
        YTICKFORMAT YTICKLEN YTICKNAME YTICKS YTICKV 
        YTICK_GET YTITLE ZCHARSIZE ZGRIDSTYLE ZMARGIN ZMINOR 
        ZRANGE ZSTYLE ZTHICK ZTICKFORMAT ZTICKLEN ZTICKNAME 
        ZTICKS ZTICKV ZTICK_GET ZTITLE ZVALUE.
        
Example

The following example shows how the AXIS procedure can 
be used with normal or polar plots to draw axes through 
the origin, dividing the plot window into four quadrants:

PLOT, /POLAR, XSTYLE=4, YSTYLE=4, TITLE='Polar Plot', r, 
theta
Make the plot, polar in this example, and 
suppress the X and Y axes using the XSTYLE 
and YSTYLE keywords.

AXIS,0,0,XAX=0,/DATA 	Draw an X axis, through data Y coordinate 
of 0. Because the XAXIS keyword parameter 
has a value of 0, the tick marks point down.

AXIS,0,0,0,YAX=0,/DATA	Similarly, draw the Y axis through data X = 
0. The tick marks point left.

;-
;+
BESELI

The BESELI function returns the I Bessel function of 
order N for the argument X. If X is double-precision, the 
result is double precision, otherwise the argument is con-
verted to floating-point and the result is floating-
point. 

Calling Sequence

        Result = BESELI(X, N)
        
Arguments

    X
    
        The expression 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 order of the I Bessel function to calculate. 
        N must be an integer greater than 0.
        
;-
;+
BESELJ

The BESELJ function returns the J Bessel function of 
order N for the argument X. If X is double-precision, the 
result is double precision, otherwise the argument is con-
verted to floating-point and the result is floating-
point. BESELJ uses the j0(3M), j1(3M), and jn(3M) func-
tions from the standard C math library.

Calling Sequence

        Result = BESELJ(X, N)
        
Arguments

    X
    
        The expression for which the J Bessel function 
        is required. X must be greater than 0. The result 
        has the same dimensions as X.
        
    N
    
        The order of the J Bessel function to calculate. 
        N must be an integer greater than 0.
        
;-
;+
BESELY

The BESELY function returns the Y Bessel function of 
order N for the argument X. If X is double-precision, the 
result is double precision, otherwise the argument is con-
verted to floating-point and the result is floating-
point. BESELY uses the y0(3M), y1(3M), and yn(3M) func-
tions from the standard C math library.

Calling Sequence

        Result = BESELY(X, N)
        
Arguments

    X
    
        The expression for which the Y Bessel function 
        is required. X must be greater than 0. The result 
        has the same dimensions as X.
        
    N
    
        The order of the Y Bessel function to calculate. 
        N must be an integer greater than or equal to 0.
        
;-
;+
BINDGEN

The BINDGEN function returns a byte array with the 
specified dimensions. Each element of the array is set to 
the value of its one-dimensional subscript.

Calling Sequence

        Result = BINDGEN(D1, ...,Dn)
        
Arguments

    Di
    
        The dimensions of the result. The dimension 
        parameters can be any scalar expression. Up to eight 
        dimensions can be specified.
        
Example

To create a four-element by four-element byte array, 
and store the result in the variable A, enter:

A = BINDGEN(4,4)

Each element in A holds the value of its one-dimen-
sional subscript. That is, if you enter the command:

PRINT, A

IDL prints the result:

   0   1   2   3

   4   5   6   7

   8   9  10  11

  12  13  14  15

;-
;+
BREAKPOINT

The BREAKPOINT procedure allows you to insert and 
remove breakpoints in programs for debugging. A break-
point causes program execution to stop after the desig-
nated statement is executed. Breakpoints are specified 
using the source file name and line number. You can insert 
breakpoints in programs without editing the source file. 
Use the command:

HELP, /BREAKPOINT

to display the breakpoint table which gives the index, 
module and source file locations of each breakpoint.

Calling Sequence

        BREAKPOINT [, File], Index
        
Arguments

    File
    
        An optional string argument that contains the 
        name of the source file.
        
    Index
    
        The line number at which to clear of set a 
        breakpoint.
        
Keywords

    CLEAR
    
        Set this keyword to remove a breakpoint. The 
        breakpoint to be removed is specified either by 
        index, or by the source file and line number. Use 
        command HELP, /BREAKPOINT to display the indices of 
        existing breakpoints. For example:
        
        BREAKPOINT, /CLEAR, 3	Clear breakpoint with an index of 3.
        
        BREAKPOINT, /CLEAR, 'test.pro',8		Clear the break-
        point corresponding to the statement 
        in the file test.pro, line number 8.
        
    SET
    
        Set this keyword to set a breakpoint at the des-
        ignated source file line. If this keyword is set, 
        the first input parameter, File must be a string 
        expression that contains the name of the source 
        file. The second input parameter must be an integer 
        that represents the source line number.
        
        For example, to set a breakpoint at line 23 in 
        the source file xyz.pro, enter:
        
        BREAKPOINT, /SET, 'xyz.pro', 23
        
;-
;+
BYTARR

The BYTARR function returns a byte vector or array.

Calling Sequence

        Result = BYTARR(D1, ..., Dn)
        
Arguments

    Di
    
        The dimensions of the result. The dimension 
        parameters can be any scalar expression. Up to eight 
        dimensions can be specified.
        
Keywords

    NOZERO
    
        Normally, BYTARR sets every element of the 
        result to zero. If the NOZERO keyword is set, this 
        zeroing is not performed (array elements contain 
        random values) and BYTARR executes faster.
        
Example

To create B as a 3 by 3 by 5 byte array where each 
element is set to zero, enter:

B = BYTARR(3, 3, 5)

;-
;+
BYTE

The BYTE function returns a result equal to Expression 
converted to byte type. If Expression is a string, each 
string is converted to a byte vector of the same length as 
the string. Each element of the vector is the character 
code of the corresponding character in the string. The 
BYTE function can also be used to extract data from 
Expression and place it in a byte scalar or array without 
modification, if more than one parameter is present. See 
the description in Chapter 4 of the IDL User's Guide for 
details.

Calling Sequence

        Result = BYTE(Expression[, Offset [, Dim1, ..., 
        Dimn]])
        
Arguments

    Expression
    
        The expression to be converted to type byte.
        
    Offset
    
        The byte offset from the beginning of Expres-
        sion. Specifying this argument allows fields of data 
        extracted from Expression to be treated as byte data 
        without conversion.
        
    Di
    
        When extracting fields of data, the Di arguments 
        specify the dimensions of the result. The dimension 
        parameters can be any scalar expression. Up to eight 
        dimensions can be specified. If no dimension argu-
        ments are given, the result is taken to be scalar.
        
Example

If the variable A contains the floating-point value 
10.0, it can be converted to byte type and saved in the 
variable B by entering:

B = BYTE(A)

;-
;+
BYTEORDER

The BYTEORDER procedure converts integers between 
host and network byte ordering or floating-point values 
between the native format and XDR (IEEE) format. This rou-
tine can also be used to swap the order of bytes within 
both short and long integers. If the type of byte swapping 
is not specified via one of the keywords below, bytes 
within short integers are swapped (even and odd bytes are 
interchanged).

The size of the parameter, in bytes, must be evenly 
divisible by two for short integer swaps, and by four for 
long integer swaps. BYTEORDER operates on both scalars and 
arrays. The parameter must be a variable, not an expres-
sion or constant, and may not contain strings. The con-
tents of Variable are overwritten by the result.

Network byte ordering is "big endian". That is, multi-
ple byte integers are stored in memory beginning with the 
most significant byte.

Calling Sequence

        BYTEORDER, Variable1, ..., Variablen
        
Arguments

    Variablen
    
        A named variable (not an expression or constant) 
        that contains the data to be converted. The contents 
        of Variable are overwritten by the new values.
        
Keywords

    DTOXDR
    
        Set this keyword to convert native double-preci-
        sion to XDR (IEEE) format. VAX users should see the 
        cautionary note below.
        
    FTOXDR
    
        Set this keyword to convert native single-preci-
        sion to XDR (IEEE) format. VAX users should see the 
        cautionary note below.
        
    HTONL
    
        Set this keyword to perform host to network con-
        version, longwords.
        
    HTONS
    
        Set this keyword to perform host to network con-
        version, short integers.
        
    LSWAP
    
        Set this keyword to perform a longword swap. 
        Swap the order of the bytes within each longword. 
        For example, the four bytes within a longword are 
        changed from (B0, B1, B2, B3), to (B3, B2, B1, B0).
        
    NTOHL
    
        Set this keyword to perform network to host con-
        version, longwords.
        
    NTOHS
    
        Set this keyword to perform network to host con-
        version, short integers.
        
    SSWAP
    
        Set this keyword to perform a short word swap. 
        Swap the bytes within short integers. The even and 
        odd numbered bytes are interchanged. This is the 
        default action, if no other keyword is set.
        
    XDRTOD
    
        Set this keyword to convert XDR (IEEE) format to 
        native double-precision floating-point. VAX users 
        should see the cautionary note below.
        
    XDRTOF
    
        Set this keyword to convert XDR (IEEE) format to 
        native single-precision floating-point. VAX users 
        should see the cautionary note below.
        
VAX Warning

        Do not attempt to interpret an XDR format float-
        ing-point number as a native floating number on a 
        VAX. They are two entirely different things. VAX's 
        generate an illegal instruction trap when the CPU 
        encounters illegal floating-point values. Under VAX/
        VMS, the illegal value is automatically replaced 
        with zero and execution continues. Some of the bit 
        patterns resulting from conversion to XDR format are 
        illegal VAX floating values. The resulting interac-
        tions can be confusing.
        
        For example, the following series of statements 
        work as expected:
        
        a = 1.0
        
        BYTEORDER, a, /FTOXDR
        
        BYTEORDER, a, /XDRTOF
        
        PRINT, a
        
        IDL prints:
        
        1.0
        
        However, the following on a VMS system produces 
        an error because of an attempt to interpret an XDR 
        floating point number as a native floating point 
        number:
        
        a = 1.0
        
        BYTEORDER, a, /FTOXDR
        
        PRINT, a
        
        IDL prints:
        
        0
        
        BYTEORDER, a, /XDRTOF
        
        PRINT, a
        
        IDL prints:
        
        0
        
        The illegal floating value is replaced by zero, 
        resulting in the wrong answer. On an Ultrix system, 
        IDL would have crashed. This problem can be avoided 
        in two ways:
        
        Avoid any operation that would result in the 
        data in the XDR format variable having its data 
        explicitly interpreted as floating point data. This 
        is why the first example above worked.
        
        Keep the binary data in an integer array. For 
        instance:
        
        a = LONG(1.0, 0, 1)
        
        BYTEORDER, a, /FTOXDR
        
        PRINT, a
        
        32831
        
        BYTEORDER, a, /XDRTOF
        
        PRINT, FLOAT(a, 0, 1)
        
        1.0
        
;-
;+
BYTSCL

The BYTSCL function scales all values of Array that 
lie in the range (Min LE x LE Max) into the range (0 LE x 
LE Top). The returned result has the same structure as the 
original parameter and is of byte type.

Calling Sequence

        Result = BYTSCL(Array)
        
Arguments

    Array
    
        The array to be scaled and converted to bytes.
        
Keywords

    MAX
    
        The maximum value of Array to be considered. If 
        MAX is not provided, Array is searched for its maxi-
        mum value. All values greater or equal to MAX are 
        set equal to TOP in the result.
        
    MIN
    
        The minimum value of Array to be considered. If 
        MIN is not provided, Array is searched for its mini-
        mum value. All values less than or equal to MIN are 
        set equal to 0 in the result.
        
    TOP
    
        The maximum value of the scaled result. If TOP 
        is not specified, 255 is used. Note that the minimum 
        value of the scaled result is always 0.
        
Example

BYTSCL is often used to scale images into the appro-
priate range for 8-bit displays. As an example, enter the 
following commands:

IM = DIST(200)	Create a simple image array.

TV, IM	Display the array as an image.

Now scale the image into the full range of bytes (0 to 
255) and re-display it by entering:

IM = BYTSCL(IM)	Byte scale the image and store the result in 
the same variable.

TV, IM	Display the new image.

;-
;+
CALL_EXTERNAL

The CALL_EXTERNAL function calls a function in an 
external sharable object and returns a scalar value. 
Parameters can be passed by reference (the default) or by 
value. See Chapter 18 of the IDL User's Guide for exam-
ples.

CALL_EXTERNAL is supported on VMS systems, some Unix 
systems (including some versions of SunOS, HPUX and AIX), 
and under Microsoft Windows. 

This function requires no interface routines and is 
much simpler and easier to use than the LINKIMAGE proce-
dure. However, CALL_EXTERNAL performs no checking of the 
type and number of parameters. Programming errors are 
likely to cause IDL to crash or to corrupt your data.

        UNIX: Only available on systems that support dynamic 
        linking. Routines written in other languages that ad-
        here to the C (argc, argv) calling convention, and 
        linked as a sharable object library can be dynamical-
        ly added and called from IDL.
        
        VMS: Routines written in any language that adheres 
        to the VMS calling convention may be easily called 
        using the CALL_EXTERNAL function.
        
        Windows: Windows-compatible DLLs that adhere to the 
        C (argc, argv) calling convention can be called from 
        IDL. Note that only 16-bit DLLs are supported under 
        Windows 3.1 unless your 32-bit DLL appears as a 16-
        bit DLL. IDL under Windows NT supports 32-bit DLLs.
        
        Macintosh: Stand Alone Code resources of resource 
        type CUST can be called from IDL.
        
The result of the CALL_EXTERNAL function is the scalar 
returned by the external function. By default, this is a 
longword scalar integer, unless the D_VALUE, F_VALUE, or 
S_VALUE keywords are specified, indicating that the func-
tion returns a double, single floating point, or string 
value respectively.

Calling Sequence

        Result = CALL_EXTERNAL(Image, Entry [, P0, ..., 
        PN-1])
        
Arguments

    Image
    
        The name of the file, which must be a sharable 
        image (VMS), sharable object library (Unix), DLL 
        (Windows), or CUST resource (Macintosh) and which 
        contains the routine to be called.
        
        UNIX: This argument is a pathname which specifies the 
        sharable object file to be loaded.
        
        VMS: This argument may contain only the file name. 
        File type, and device/directory specification strings 
        are not allowed. If the sharable image file is not in 
        SYS$SHARE, a logical name or the DEFAULT file name 
        keyword parameter must be used to direct 
        LIB$FIND_IMAGE_SYMBOL to locate the correct file.
        
        Windows: This argument is a pathname which specifies 
        the DLL to be loaded.
        
        Macintosh: This argument is a pathname to the file 
        which includes the CUST resource to be loaded.
        
    Entry
    
        The entry point of the procedure or function.
        
        UNIX, VMS: A string containing the name of the uni-
        versal symbol which is the entry point of the proce-
        dure or function.
        
        Windows: A string containing the name of the export-
        ed DLL procedure.
        
        Macintosh: A string containing the name of the CUST 
        resource.
        
    P0, ..., PN-1
    
        The parameters to be passed to the external rou-
        tine. The passing mechanism is by either reference 
        or value, according to the setting of the keyword 
        parameter VALUE.
        
        Strings passed by reference pass the address of 
        their descriptor. Strings passed by value pass the 
        address of the null-terminated string. String arrays 
        are passed via a pointer to an array of string 
        descriptors. Other arrays and all structures are 
        passed by reference.
        
        The definition of a string descriptor, as writ-
        ten in C, is:
        
        typedef struct {
        
            unsigned short length;
        
            short reserved;
        
            char *s;
        
        } STRING;
        
        Warning: Do not change the contents of the 
        string or its descriptor.
        
        Other scalars are passed by reference, unless 
        the VALUE keyword parameter is used to indicate a 
        scalar is to be passed by value. Care must be taken 
        to ensure that the type, structure, and passing 
        mechanism of the parameters passed to the external 
        routine match what it expects.
        
        UNIX, Windows, Macintosh: Routines are called with an 
        argc argument count, and an argv[] array of arguments 
        or pointers to arguments. Parameters passed by value 
        and addresses of parameters passed by reference are 
        placed in the argv[] array. A typical C function pro-
        totype is:
        
        int xxx(int argc, void *argv[])
        
        VMS: Routines are called with N arguments. In For-
        tran, a typical routine is declared:
        
        INTEGER *4 FUNCTION XXX(P1, P2, ..., PN)
        
Keywords

    ALL_VALUE (Windows Only)
    
        Set this keyword to indicate that all parameters 
        are passed by value.
        
    DEFAULT (VMS Only)
    
        A string containing the default device, direc-
        tory, file name, and file type information for the 
        file that contains the sharable image. This optional 
        keyword parameter must be used if the sharable image 
        is not in SYS$SHARE or no logical name exists that 
        corresponds to the Image argument.
        
    D_VALUE (UNIX, VMS, Macintosh)
    
        If set, this keyword indicates that the called 
        function returns a double-precision floating value.
        
    F_VALUE (UNIX, VMS, Macintosh)
    
        If set, this keyword indicates that the called 
        function returns a single-precision floating value.
        
    S_VALUE (All Platforms)
    
        If set, this keyword indicates that the called 
        function returns a pointer to a null-terminated 
        string.
        
    VALUE (UNIX, VMS, Windows)
    
        A byte array, with as many elements as there are 
        optional parameters, indicating the method of param-
        eter passing. Arrays are always passed by reference. 
        If parameter P is a scalar, P is passed by reference 
        if VALUE(i) is 0; and by value if it is non-zero. 
        Passing a scalar string parameter by value passes 
        the address of the first byte of the null-terminated 
        string. Your routine must not alter the contents of 
        such a string.
        
Example

See Chapter 18 of the IDL User's Guide for examples 
using CALL_EXTERNAL.

;-
;+
CALL_FUNCTION

CALL_FUNCTION calls the IDL function specified by the 
string Name, passing any additional parameters as its 
arguments. The result of the called function is passed 
back as the result of this routine.

Although not as flexible as the EXECUTE function, 
CALL_FUNCTION is much faster. Therefore, CALL_FUNCTION 
should be used in preference to EXECUTE whenever possible.

Calling Sequence

        Result = CALL_FUNCTION(Name [, P1, ..., Pn])
        
Arguments

    Name
    
        A string containing the name of the function to 
        be called. This argument can be a variable, which 
        allows the called function to be determined at runt-
        ime.
        
    Pi
    
        The arguments to be passed to the function given 
        by Name. These arguments are the positional and key-
        word arguments documented for the called function, 
        and are passed to the called function exactly as if 
        it had been called directly.
        
Example

The following command indirectly calls the IDL func-
tion SQRT (the square root function) with an argument of 4 
and stores the result in the variable R:

R = CALL FUNCTION('SQRT', 4)

;-
;+
CALL_PROCEDURE

CALL_PROCEDURE calls the procedure specified by Name, 
passing any additional parameters as its arguments.

Although not as flexible as the EXECUTE function, 
CALL_PROCEDURE is much faster. Therefore, CALL_PROCEDURE 
should be used in preference to EXECUTE whenever possible.

Calling Sequence

        CALL_PROCEDURE, Name [, P1, ..., Pn]
        
Arguments

    Name
    
        A string containing the name of the procedure do 
        be called. This argument can be a variable, which 
        allows the called procedure to be determined at 
        runtime.
        
    Pi
    
        The arguments to be passed to the procedure 
        given by Name. These arguments are the positional 
        and keyword arguments documented for the called pro-
        cedure, and are passed to the called procedure 
        exactly as if it had been called directly.
        
Example

The following example shows how to call the PLOT pro-
cedure indirectly with a number of arguments. First, cre-
ate a dataset for plotting by entering:

B = FINDGEN(100)

Call PLOT indirectly to create a polar plot by enter-
ing:

CALL_PROCEDURE, 'PLOT', B, B, /POLAR

A "spiral" plot should appear.

;-
;+
CATCH

The CATCH procedure provides a generalized mechanism 
for the handling of exceptions and errors within IDL. 
Calling CATCH establishes an error handler for the current 
procedure that intercepts all errors that can be handled 
by IDL, excluding non-fatal warnings such as math errors.

When an error occurs, each active procedure, begin-
ning with the offending procedure and proceeding up the 
call stack to the main program level, is examined for an 
error handler. If an error handler is found, control 
resumes at the statement after the call to CATCH. The 
index of the error is returned in the argument to CATCH. 
The !ERROR (or !SYSERROR) and !ERR_STRING (or 
!SYSERR_STRING) system variables are also set. If no error 
handlers are found, program execution stops, an error mes-
sage is issued, and control reverts to the interactive 
mode. A call to ON_IOERROR in the procedure that causes an 
I/O error supersedes CATCH, and takes the branch to the 
label defined by ON_IOERROR. 

This mechanism is similar, but not identical to, the 
setjmp/longjmp facilities in C and the catch/throw facil-
ities in C++.

Error handling is discussed in more detail in Chapter 
11 of the IDL User's Guide.

Calling Sequence

        CATCH, Variable
        
Arguments

    Variable
    
        A named variable in which the error index is 
        returned. When an error handler is established by a 
        call to CATCH, Variable is set to zero. If an error 
        occurs, Variable is set to the error index, and con-
        trol is transferred to the statement after the call 
        to CATCH.
        
Keywords

    CANCEL
    
        Set this keyword to cancel the error handler for 
        the current procedure. This cancellation does not 
        affect other error handlers that may be established 
        in other active procedures.
        
Example

The following procedure illustrates the use of CATCH:

PRO ABC

A = FLTARR(10)	Define variable A.

CATCH, Error_status	Establish error handler. When errors occur, 
the index of the error is returned in the vari-
able Error_status.

IF Error_status NE 0 THEN BEGIN	This statement begins the error handler.

        PRINT, 'Error index: ', Error_status

        PRINT, 'Error message:', !ERR_STRING

        A=FLTARR(12)	Handle the error by extending A.

        ENDIF

A(11)=12	Cause an error.

HELP, A	Even though an error occurs in the line 
above, program execution continues to this 
point because the event handler extended the 
definition of A so that the statement can be 
re-executed.

END

Running the ABC procedure causes IDL to produce the 
following output and control returns to the interactive 
prompt:

Error index:         -101

Error message:

Attempt to subscript A with <INT (      11)> is out of 
range.

A               FLOAT     = Array(12)

;-
;+
CD

The CD procedure is used to set and/or change the cur-
rent working directory. This routine changes the working 
directory for the IDL session and any child processes 
started from IDL during that session after the directory 
change is made. Under Unix, CD does not affect the working 
directory of the process that started IDL. The PUSHD, 
POPD, and PRINTD Users' Library procedures provide a con-
venient interface to CD.

Calling Sequence

        CD [, Directory]
        
Arguments

    Directory
    
        A scalar string specifying the path of the new 
        working directory. If Directory is specified as a 
        null string, the working directory is changed to the 
        user's home directory. If this argument is not spec-
        ified, the working directory is not changed.
        
Keywords

    CURRENT
    
        If CURRENT is present, it specifies a named 
        variable into which the current working directory is 
        stored as a scalar string. The returned directory is 
        the working directory before the directory is 
        changed. Thus, you can obtain the current working 
        directory and change it in a single statement:
        
        CD, new_dir, CURRENT=old_dir
        
Example

Under Unix, to change the working directory to the 
"data" subdirectory of the current directory, enter:

CD, 'data'

Under VMS, you could use:

CD, '[.data]'

;-
;+
CEIL

The CEIL function returns the closest integer greater 
than or equal to its argument. This value is returned as a 
longword integer with the same structure as the input 
argument..

Calling Sequence

        Result = CEIL(X)
        
Arguments

    X
    
        The value for which the ceiling function is to 
        be evaluated. This value can be of floating-point, 
        double-precision floating-point, or complex type. 
        CEIL returns a longword integer with the same struc-
        ture as X.
        
Example

To print the ceiling function of 5.1, enter:

PRINT, CEIL(5.1)

IDL prints:

6



;-
;+
CHECK_MATH

The CHECK_MATH function returns and clears the accu-
mulated math error status. If the optional parameter 
Print_Flag is non-zero then an error message indicating 
the accumulated math errors is printed, otherwise the rou-
tine produces no messages. The result of this function is 
0 if no math errors have occurred since the last call or 
issuance of the interactive prompt. Each type of error is 
encoded as a bit, as described in the table below.

Value    Condition

-----------------------------------

0        No errors detected since the last prompt or call to

         CHECK_MATH

1        Integer divided by zero

2        Integer overflow

16       Floating-point divided by zero

32       Floating-point underflow

64       Floating-point overflow

128      Floating-point operand error

Calling Sequence

        Result = CHECK_MATH([Print_Flag, 
        Message_Inhibit])
        
Arguments

    Print_Flag
    
        If this argument is present and non-zero, an 
        error message is printed if any accumulated math 
        errors exist. If this argument is omitted or zero, 
        CHECK_MATH executes silently.
        
    Message_Inhibit
    
        This optional parameter disables or enables the 
        printing of math error exception error messages when 
        they are detected. By default, these messages are 
        enabled. Set Message_Inhibit to 1 to inhibit, and 0 
        to re-enable. When the interpreter exits to the 
        interactive mode, error messages are printed for 
        accumulated math errors that were suppressed but not 
        cleared.
        
Keywords

    TRAP
    
        Set this parameter to a non-zero value to enable 
        floating-point traps (the default). Set this keyword 
        to a non-zero value to disable traps.
        
        The first 8 floating-point error exceptions 
        issue error messages. Subsequent errors are silent.
        
        The accumulated floating-point error status is 
        printed when IDL returns to the interactive mode if 
        a floating-point error occurred that was not logged.
        
        If TRAP is set to 0, no error messages are 
        printed excepting the final, accumulated error sta-
        tus.
        
        Trap handling is machine dependent. Some 
        machines will not operate properly with traps 
        enabled, others do not allow disabling traps. For 
        example, on the Sun 386i traps may not be enabled.
        
Examples

To simply check and clear the accumulated math error 
status using all the defaults, enter:

PRINT, CHECK_MATH()

The following code fragment would print the names of 
errors that have occurred:

ERRS = ['Divide by 0', 'Underflow', 'Overflow', $

        'Illegal Operand']	Create a string array of error names.

J = CHECK_MATH()	Get math error status.

FOR I = 4, 7 DO IF ISHFT(J, -I) AND 1 THEN $

    PRINT, ERRS(I-4), ' Occurred'	Check to see if an error occurred and 
print the corresponding error message.

;-
;+
CINDGEN

The CINDGEN function returns a complex, single-preci-
sion, floating-point array with the specified dimensions. 
Each element of the array has its real part set to the 
value of its one-dimensional subscript. The imaginary 
part is set to zero.

Calling Sequence

        Result = CINDGEN(D1, ..., Dn)
        
Arguments

    Di
    
        The dimensions of the result. The dimension 
        parameters can be any scalar expression. Up to eight 
        dimensions can be specified.
        
Example

To create C, a 4-element vector of complex values with 
the real parts set to the value of their subscripts, 
enter:

C = CINDGEN(4)

;-
;+
CLOSE

The CLOSE procedure closes the file units specified as 
arguments. All open files are also closed when IDL exits.

Calling Sequence

        CLOSE[,Unit1, ..., Unitn]
        
Arguments

    Uniti
    
        The IDL file units to close.
        
Keywords

    ALL
    
        Set this keyword to close all open file units. 
        In addition, any file units that were allocated via 
        GET_LUN are freed.
        
    FILE
    
        Set this keyword to close all file units from 1 
        to 99. File units greater than 99, which are associ-
        ated with the GET_LUN and FREE_LUN procedures, are 
        not affected.
        
Example

If file units 1 and 3 are open, they can both be 
closed at the same time by entering the command:

CLOSE, 1, 3

;-
;+
COLOR_CONVERT

The COLOR_CONVERT procedure converts colors to and 
from the RGB (Red Green Blue), HLS (Hue Lightness Satura-
tion), and HSV (Hue Saturation Value) color systems. A 
keyword parameter indicates the type of conversion to be 
performed (one of the keywords must be specified). The 
first three parameters contain the input color triple(s) 
which may be scalars or arrays of the same size. The 
result is returned in the last three parameters, O0, O1, 
and O2. RGB values are bytes in the range 0 to 255.

Hue is measured in degrees, from 0 to 360. Saturation, 
Lightness, and Value are floating-point numbers in the 
range 0 to 1. A Hue of 0 degrees is the color red. Green 
is 120 degrees. Blue is 240 degrees. A reference contain-
ing a discussion of the various color systems is: Foley 
and Van Dam, Fundamentals of Interactive Computer Graph-
ics, Addison-Wesley Publishing Co., 1982.

Calling Sequence

        COLOR_CONVERT, I0, I1, I2, O0, O1, O2
        
Arguments

    I0, I1, I2
    
        The input color triple(s). These arguments may 
        be either scalars or arrays of the same length.
        
    O0, O1, O2 
    
        The variables to receive the result. Their 
        structure is copied from the input parameters.
        
Keywords

    HLS_RGB
    
        Set this keyword to convert from HLS to RGB.
        
    HSV_RGB
    
        Set this keyword to convert from HSV to RGB.
        
    RGB_HLS
    
        Set this keyword to convert from RGB to HLS.
        
    RGB_HSV
    
        Set this keyword to convert from RGB to HSV.
        
Example

The command:

COLOR_CONVERT, 255, 255, 0, h, s, v, /RGB_HSV

converts the RGB color triple (255, 255, 0), which is 
the color yellow at full intensity and saturation, to the 
HSV system. The resulting hue in the variable h is 60.0 
degrees. The saturation and value, s and v, are set to 
1.0.

;-
;+
COLOR_QUAN

The COLOR_QUAN function quantizes a true-color image 
and returns a pseudo-color image and palette to display 
the image on standard pseudo-color displays. The output 
image and palette can have from 2 to 256 colors.

COLOR_QUAN solves the general problem of accurately 
displaying decomposed, true-color images, that contain a 
palette of up to 2^24 colors, on pseudo-color displays 
that can only display 256 (or fewer) simultaneous colors.

One of two color quantization methods can be used:

    Method 1 is a statistical method that attempts 
    to find the N colors that most accurately represent 
    the original color distribution. This algorithm uses 
    a variation of the Median Cut Algorithm, described 
    in "Color Image Quantization for Frame Buffer Dis-
    play", from Computer Graphics, Volume 16, Number 3 
    (July, 1982), Page 297. It repeatedly subdivides the 
    color space into smaller and smaller rectangular 
    boxes, until the requested number of colors are 
    obtained.
    
    The original colors are then mapped to the near-
    est output color, and the original image is resampled 
    to the new palette with optional Floyd-Steinberg col-
    or dithering. The resulting pseudo-color image and 
    palette are usually a good approximation of the orig-
    inal image.
    
    The number of colors in the output palette de-
    faults to the number of colors supported by the cur-
    rently-selected graphics output device. The number of 
    colors can also be specified by the COLOR keyword pa-
    rameter.
    
    Method 2, selected by setting the keyword param-
    eter CUBE, divides the three-dimensional color space 
    into equal-volume cubes. Each color axis is divided 
    into CUBE segments, resulting in CUBE^3 volumes. The 
    original input image is sampled to this color space 
    using Floyd-Steinberg dithering, which distributes 
    the quantization error to adjacent pixels.
    
    The CUBE method has the advantage that the color 
    tables it produces are independent of the input im-
    age, so that multiple quantized images can be viewed 
    simultaneously. The statistical method usually pro-
    vides a better-looking result and a smaller global 
    error.
    
COLOR_QUAN can use the same color mapping for a series 
of images. See the descriptions of the GET_TRANSLATION, 
MAP_ALL, and TRANSLATION keywords, below.

Calling Sequence

        Result = COLOR_QUAN(Image_R, Image_G, Image_B, 
        R, G, B)
        
        or
        
        Result = COLOR_QUAN(Image, Dim, R, G, B)
        
        Note that the input image parameter can be 
        passed as either three, separate color-component 
        arrays (Image_R, Image_G, Image_B) or as a three-
        dimensional array containing all three components, 
        Image, and a scalar, Dim, indicating the dimension 
        over which the colors are interleaved.
        
Arguments

    Image_R, Image_G, Image_B
    
        Arrays containing the red, green, and blue com-
        ponents of the decomposed true-color image. For best 
        results, the input image(s) should be scaled to the 
        range of 0 to 255.
        
    Image
    
        A three-dimensional array containing all three 
        components of the true-color image.
        
    Dim
    
        A scalar that indicates the method of color 
        interleaving in the Image parameter. A value of 1 
        indicates interleaving by pixel (3, n, m), 2 indi-
        cates interleaving by row (n, 3, m), and 3 indicates 
        interleaving by image (n, m, 3).
        
    R, G, B
    
        Three output byte arrays containing the red, 
        green, and blue components of the output palette.
        
Keywords

    COLORS
    
        The number of colors in the output palette. This 
        value must at least 2 and not greater than 256. The 
        default is the number of colors supported by the 
        current graphics output device.
        
    CUBE
    
        If this keyword is set, the color space is 
        divided into CUBE^3 volumes, to which the input 
        image is quantized. This result is always Floyd-
        Steinberg dithered. The value of CUBE can range from 
        2 to 6; providing from 2^3 = 8, to 6^3 = 216 output 
        colors. If this keyword is set, the COLORS, DITHER, 
        and ERROR keywords are ignored.
        
    DITHER
    
        Set this keyword to dither the output image. 
        Dithering can improve the appearance of the output 
        image, especially when using relatively few colors.
        
    ERROR
    
        Set this optional keyword to a named variable. A 
        measure of the quantization error is returned. This 
        error is proportional to the square of the Euclidean 
        distance, in RGB space, between corresponding colors 
        in the original and output images.
        
    GET_TRANSLATION
    
        Set this keyword to a named variable in which 
        the mapping between the original RGB triples (in the 
        true-color image) and the resulting pseudo-color 
        indices is returned as a vector. Do not use this 
        keyword if CUBE is set.
        
    MAP_ALL
    
        Set this keyword to establish a mapping for all 
        possible RGB triples into pseudo-color indices. Set 
        this keyword only if GET_TRANSLATION is also 
        present. Note that mapping all possible colors 
        requires more compute time and slightly degrades the 
        quality of the resultant color matching.
        
    TRANSLATION
    
        Set this keyword to a vector of translation 
        indices obtained by a previous call to COLOR_QUAN 
        using the GET_TRANSLATION keyword. The resulting 
        image is quantized using this vector.
        
Example

The following code segment reads a true-color, row 
interleaved, image from a disk file, and displays it on 
the current graphics display, using a palette of 128 col-
ors:

OPENR, unit, 'XXX.DAT', /GET_LUN	Open an input file.

a = BYTARR(512, 3, 480)	Dimensions of the input image.

READU, unit, a	Read the image.

FREE LUN, unit	Close the file.

TV, COLOR_QUAN(a, 2, r, g, b, COLORS=128)		Show the quantized 
image. The 2 indicates that the colors are 
interleaved by row.

TVLCT, r, g, b	Load the new palette.

To quantize the image into 216 equal-volume color 
cubes, replace the call to COLOR_QUAN with the following:

TV, COLOR_QUAN(a, 2, r, g, b, CUBE=6)

;-
;+
COMPLEX

The COMPLEX function returns complex scalars or 
arrays given one or two scalars or arrays. If only one 
parameter is supplied, the imaginary part of the result is 
zero, otherwise it is set to the value of the Imaginary 
parameter. Parameters are first converted to single-pre-
cision floating-point. If either or both of the parameters 
are arrays, the result is an array, following the same 
rules as standard IDL operators. If three parameters are 
supplied, COMPLEX extracts fields of data from Expres-
sion.

Calling Sequence

        Result = COMPLEX(Real [, Imaginary])
        
        or
        
        Result = COMPLEX(Expression, Offset, Dim1 [, 
        ..., Dimn])
        
Arguments

    Real
    
        Scalar or array to be used as the real part of 
        the complex result.
        
    Imaginary
    
        Scalar or array to be used as the imaginary part 
        of the complex result.
        
    Expression
    
        The expression from which data is to be 
        extracted.
        
    Offset
    
        Offset from beginning of the Expression data 
        area. Specifying this argument allows fields of data 
        extracted from Expression to be treated as complex 
        data. See the description in Chapter 4 of the IDL 
        User's Guide for details.
        
    Di
    
        When extracting fields of data, the Di arguments 
        specify the dimensions of the result. The dimension 
        parameters can be any scalar expression. Up to eight 
        dimensions can be specified. If no dimension argu-
        ments are given, the result is taken to be scalar.
        
        When converting from a string argument, it is 
        possible that the string does not contain a valid 
        floating-point value and no conversion is possible. 
        The default action in such cases is to print a warn-
        ing message and return 0. The ON_IOERROR procedure 
        can be used to establish a statement to be jumped to 
        in case of such errors.
        
Example

Create a complex array from two integer arrays by 
entering the following commands:

A = [1,2,3]	Create the first integer array.

B = [4,5,6]	Create the second integer array.

C = COMPLEX(A, B)	Make A the real parts and B the imaginary 
parts of the new complex array.

PRINT, C	See how the two arrays were combined.

IDL prints:

( 1.00000, 4.00000)( 2.00000, 5.00000)

( 3.00000, 6.00000)

;-
;+
COMPLEXARR

The COMPLEXARR function returns a complex, single-
precision, floating-point vector or array.

Calling Sequence

        Result = COMPLEXARR(D1, ..., Dn)
        
Arguments

    Di
    
        The dimensions of the result. The dimension 
        parameters may be any scalar expression. Up to eight 
        dimensions can be specified.
        
Keywords

    NOZERO
    
        Normally, COMPLEXARR sets every element of the 
        result to zero. If the NOZERO keyword is set, this 
        zeroing is not performed, and COMPLEXARR executes 
        faster.
        
Example

To create an empty, 5-element by 5-element, complex 
array C, enter:

C = COMPLEXARR(5, 5)

;-
;+
CONJ

The CONJ function returns the complex conjugate of X. 
The complex conjugate of the real-imaginary pair (x, y) is 
(x, -y). If X is not complex, a complex-valued copy of X 
is used.

Calling Sequence

        Result = CONJ(X)
        
Arguments

    X
    
        The value for which the complex conjugate is 
        desired. If X is an array, the result has the same 
        structure, with each element containing the complex 
        conjugate of the corresponding element of X.
        
Example

Print the conjugate of the complex pair (4.0, 5.0) by 
entering:

PRINT, CONJ(COMPLEX(4.0, 5.0))

IDL prints:

( 4.00000, -5.00000)

;-
;+
CONTOUR

The CONTOUR procedure draws a contour plot from data 
stored in a rectangular array. Both line contours and 
filled contour plots can be created. Note that outline and 
fill contours cannot be drawn at the same time. To create 
a contour plot with both filled contours and outlines, 
first create the filled contour plot, then add the outline 
contours by calling CONTOUR a second time with the OVER-
PLOT keyword.

Contours can be smoothed by using the MIN_CURVE_SURF 
User Library function on the contour data before contour-
ing.

Using various keywords, described below, it is possi-
ble to specify contour levels, labeling, colors, line 
styles, and other options. CONTOUR can draw contours using 
one of two different methods:

    The first algorithm, used by default, examines 
    each array cell and draws all contours emanating 
    from that cell before proceeding to the next cell. 
    This method is efficient in terms of computer 
    resources but does not allow contour labeling.
    
    The second method searches for each contour line 
    and then follows the line until it reaches a bound-
    ary or closes. This method gives better looking 
    results with dashed line styles, and allows contour 
    labeling, but requires more computer time. It is 
    used if any of the following keywords are specified: 
    C_ANNOTATION, C_CHARSIZE, C_LABELS, FOLLOW, PATH, 
    FILENAME, or DOWNHILL.
    
Although these two methods both draw correct contour 
maps, differences in their algorithms can cause small dif-
ferences in the resulting graphs. Note that the resulting 
contour plots are both correct-there can be more than one 
correct way to interpret contours.

Smoothing Contours

The Users' Library function MIN_CURVE_SURF can be 
used to smoothly interpolate both regularly and irregu-
larly sampled surfaces before contouring. This function 
replaces the older SPLINE keyword to CONTOUR, which was 
inaccurate and is no longer supported. MIN_CURVE_SURF 
interpolates the entire surface to a relatively fine grid 
before drawing the contours.

Calling Sequence

        CONTOUR, Z [, X, Y]
        
Arguments

    Z
    
        A two-dimensional array containing the values 
        that make up the contour surface. If arguments X and 
        Y are provided, the contour is plotted as a function 
        of the (X, Y) locations specified by their contents. 
        Otherwise, the contour is generated as a function of 
        the two-dimensional array index of each element of 
        Z.
        
        This argument is converted to single-precision 
        floating-point before plotting. Plots created with 
        CONTOUR are limited to the range and precision of 
        single-precision floating-point values.
        
    X
    
        A vector or two-dimensional array specifying the 
        X coordinates for the contour surface. If X is a 
        vector, each element of X specifies the X coordinate 
        for a column of Z (e.g., X(0) specifies the X coor-
        dinate for Z(0,*)). If X is a two-dimensional array, 
        each element of X specifies the X coordinate of the 
        corresponding point in Z (i.e., Xij specifies the X 
        coordinate for Zij).
        
    Y
    
        A vector or two-dimensional array specifying the 
        Y coordinates for the contour surface. If Y a vec-
        tor, each element of Y specifies the Y coordinate 
        for a row of Z (e.g., Y(0) specifies the Y coordi-
        nate for Z(*,0)). If Y is a two-dimensional array, 
        each element of Y specifies the Y coordinate of the 
        corresponding point in Z (Yij specifies the Y coordi-
        nate for Zij).
        
Keywords

    C_ANNOTATION
    
        The label to be drawn on each contour. Usually, 
        contours are labeled with their value. This parame-
        ter, a vector of strings, allows any text to be 
        specified. The first label is used for the first 
        contour drawn, and so forth. If the LEVELS keyword 
        is specified, the elements of C_ANNOTATION corre-
        spond directly to the levels specified, otherwise, 
        they correspond to the default levels chosen by the 
        CONTOUR procedure. If there are more contour levels 
        than elements in C_ANNOTATION, the remaining levels 
        are labeled with their values.
        
        Use of this keyword implies use of the FOLLOW 
        keyword.
        
        Example
        
        To produce a contour plot with three levels 
        labeled "low", "medium", and "high":
        
        CONTOUR, Z, LEVELS = [0.0, 0.5, 1.0], C_ANNOTATION = 
        ['low', 'medium', 'high']
        
    C_CHARSIZE
    
        The size of the characters used to annotate con-
        tour labels. Normally, contour labels are drawn at 
        3/4 of the size used for the axis labels (specified 
        by the CHARSIZE keyword or !P.CHARSIZE system vari-
        able. This keyword allows the contour label size to 
        be specified directly. Use of this keyword implies 
        use of the FOLLOW keyword.
        
    C_COLORS
    
        The color index used to draw each contour. This 
        parameter is a vector, converted to integer type if 
        necessary. If there are more contour levels than 
        elements in C_COLORS, the elements of the color vec-
        tor are cyclically repeated.
        
        Example
        
        If C_COLORS contains three elements, and there 
        are seven contour levels to be drawn, the colors c0, 
        c1, c2, c0, c1, c2, c0 will be used for the seven lev-
        els. To call CONTOUR and set the colors to 
        [100,150,200], use the command:
        
        CONTOUR, Z, C_COLORS = [100,150,200]
        
    C_LABELS
    
        Specifies which contour levels should be 
        labeled. By default, every other contour level is 
        labeled. C_LABELS allows you to override this 
        default and explicitly specify the levels to label. 
        This parameter is a vector, converted to integer 
        type if necessary. If the LEVELS keyword is speci-
        fied, the elements of C_LABELS correspond directly 
        to the levels specified, otherwise, they correspond 
        to the default levels chosen by the CONTOUR proce-
        dure. Setting an element of the vector to zero 
        causes that contour label to not be labeled. A non-
        zero value forces labeling.
        
        Use of this keyword implies use of the FOLLOW 
        keyword.
        
        Example
        
        To produce a contour plot with four levels where 
        all but the third level is labeled:
        
        CONTOUR, Z, LEVELS = [0.0, 0.25, 0.75, 1.0], $
        
          C_LABELS = [1, 1, 0, 1]
        
    C_LINESTYLE
    
        The line style used to draw each contour. As 
        with C_COLORS, C_LINESTYLE is a vector of line style 
        indices. If there are more contour levels than line 
        styles, the line styles are cyclically repeated. See 
        Table 2.1 on page 2-4 of the IDL Reference Guide for 
        a list of available styles.
        
        Note: The cell drawing contouring algorithm 
        draws all the contours in each cell, rather than 
        following contours. Since an entire contour is not 
        drawn as a single operation, the appearance of the 
        more complicated linestyles will suffer. Use of the 
        contour following method (selected with the FOLLOW 
        keyword) will give better looking results in such 
        cases.
        
        Example
        
        To produce a contour plot, with the contour lev-
        els directly specified in a vector V, with all nega-
        tive contours drawn with dotted lines, and with 
        positive levels in solid lines:
        
        CONTOUR, Z, LEVELS = V, C_LINESTYLE = (V LT 0.0)
        
    C_ORIENTATION
    
        If the FILL keyword is set, this keyword can be 
        set to the angle, in degrees counterclockwise from 
        the horizontal, of the lines used to fill contours. 
        If neither C_ORIENTATION or C_SPACING are specified, 
        the contours are solid filled.
        
    C_SPACING
    
        If the FILL keyword is set, this keyword can be 
        used to control the distance, in centimeters, 
        between the lines used to fill the contours.
        
    C_THICK
    
        The line used to draw each contour level. As 
        with C_COLORS, C_THICK is a vector of line thickness 
        values, although the values are floating point. If 
        there are more contours than thickness elements, 
        elements are repeated. If omitted, the overall line 
        thickness specified by the THICK keyword parameter 
        or !P.THICK is used for all contours.
        
    CLOSED
    
        Set this keyword to close contours that inter-
        sect the plot boundaries. After a contour hits a 
        boundary, it is follows the plot boundary until it 
        connects with its other boundary intersection.
        
    DOWNHILL
    
        Set this keyword to label each contour with 
        short, perpendicular tick marks that point in the 
        "downhill" direction, making the direction of the 
        grade readily apparent. If this keyword is set, the 
        contour following method is used in drawing the con-
        tours.
        
    FILL
    
        Set this keyword to produce a filled contour 
        plot. The contours are filled with solid or line-
        filled polygons. For solid polygons, use the C_COLOR 
        keyword to specify the color index of the polygons 
        for each contour level. For line fills, use 
        C_ORIENTATION, C_SPACING, C_COLOR, C_LINESTYLE, and/
        or C_THICK to specify attributes for the lines.
        
        If the current device is not a pen plotter, each 
        polygon is erased to the background color before the 
        fill lines are drawn, to avoid superimposing one 
        pattern over another.
        
        Contours that are not closed can not be filled 
        because their interior and exterior are undefined. 
        Contours created from data sets with missing data 
        may not be closed; many map projections can also 
        produce contours that are not closed. Filled con-
        tours should not be used in these cases.
        
    FOLLOW
    
        Set this keyword to force the CONTOUR procedure 
        to use the line-following method instead of the 
        cell-drawing method. CONTOUR can draw contours using 
        one of two different methods:
        
        The first algorithm, used by default, examines 
        each array cell and draws all contours emanating 
        from that cell before proceeding to the next cell. 
        This method is efficient in terms of computer 
        resources but does not allow contour labeling.
        
        The second method searches for each contour line 
        and then follows the line until it reaches a bound-
        ary or closes. This method gives better looking 
        results with dashed line styles, and allows contour 
        labeling, but re- quires more computer time. It is 
        used if any of the following keywords is specified: 
        C_ANNOTATION, C_CHARSIZE, C_LABELS, DOWNHILL, FOL-
        LOW, or PATH_FILENAME.
        
        Although these two methods both draw correct 
        contour maps, differences in their algorithms can 
        cause small differences in the resulting graph.
        
    LEVELS
    
        Specifies a vector containing the contour levels 
        drawn by the CONTOUR procedure. A contour is drawn 
        at each level in LEVELS.
        
        Example
        
        To draw a contour plot with levels at 1, 100, 
        1000, and 10000:
        
        CONTOUR, Z, LEVELS = [1, 100, 1000, 10000]
        
        To draw a contour plot with levels at 50, 60, 
        ..., 90, 100:
        
        CONTOUR, Z, LEVELS = FINDGEN(6) * 10 + 50
        
    MAX_VALUE
    
        Data points with values equal to or above this 
        value are ignored (i.e., treated as missing data) 
        when contouring. Cells containing one or more cor-
        ners with values above MAX_VALUE will have no con-
        tours drawn through them.
        
    NLEVELS
    
        The number of equally spaced contour levels that 
        are produced by CONTOUR. If the LEVELS parameter, 
        which explicitly specifies the value of the contour 
        levels, is present this keyword has no effect. If 
        neither parameter is present, approximately six lev-
        els are drawn.
        
    OVERPLOT
    
        Set this keyword to make CONTOUR "overplot". 
        That is, the current graphics screen is not erased, 
        no axes are drawn and the previously established 
        scaling remains in effect. You must explicitly spec-
        ify the values of the contour levels when using this 
        option, unless geographic mapping coordinates are in 
        effect.
        
    PATH_FILENAME
    
        Specifies the name of a file to contain the con-
        tour positions. If PATH_FILENAME is present, CONTOUR 
        does not draw the contours, but rather, opens the 
        specified file and writes the positions, in normal-
        ized coordinates, into it. The file consists of a 
        series of logical records containing binary data. 
        Each record is preceded with a header structure 
        defining the contour as follows:
        
        {CONTOUR_HEADER, TYPE:0B, HIGH:0B, LEVEL:0, $
        
         NUM:0L, VALUE:0.0}
        
        The fields are:
        
        TYPE: A byte that is zero if the contour is 
        open, and one if it is closed.
        
        HIGH: A byte that is 1 if the contour is closed 
        and above its surroundings, and is 0 if the contour 
        is below. This field is meaningless if the contour 
        is not closed.
        
        LEVEL: A short integer with value greater or 
        equal to zero (It is an index into the LEVELS 
        array).
        
        NUM: The longword number of data points in the 
        contour.
        
        VALUE: The contour value. This is a single preci-
        sion floating point value.
        
        Following the header in each record are NUM X-
        coordinate values followed by NUM Y-coordinate val-
        ues, expressed in normalized coordinates.
        
        Use of this keyword implies use of the FOLLOW 
        keyword.
        
    PATH_INFO
    
        Set this keyword to a named variable that will 
        return path information for the contours. This 
        information can be used, along with data stored in a 
        variable named by the PATH_XY keyword, to trace 
        closed contours. If PATH_INFO is present, CONTOUR 
        does not draw the contours, but rather records the 
        path information in an array of structures of the 
        following type:
        
        {CONTOUR_PATH_STRUCTURE, TYPE:0B, HIGH_LOW:0B, $
        
         LEVEL:0, N:0L, OFFSET:0L, VALUE:0.0}
        
        The fields are:
        
        TYPE: A byte that is zero if the contour is 
        open, and one if it is closed. In the present imple-
        mentation, all contours are closed.
        
        HIGH_LOW: A byte that is 1 if the contour is 
        above its surroundings, and is 0 if the contour is 
        below.
        
        LEVEL: A short integer indicating the index of 
        the contour level, from zero to the number of levels 
        minus one.
        
        N: A long integer indicating the number of XY 
        pairs in the contour's path.
        
        OFFSET: A long integer that is the offset into 
        the array defined by PATH_XY, representing the first 
        XY coordinate for this contour. 
        
        VALUE: The contour value. This is a single preci-
        sion floating point value.
        
        See the examples section below for an example 
        using the PATH_INFO and PATH_XY keywords to return 
        contour path information.
        
    PATH_XY
    
        Set this keyword to a named variable that 
        returns the normalized coordinates of the closed 
        paths of the contours. This information can be used, 
        along with data stored in a variable named by the 
        PATH_INFO keyword, to trace closed contours. If 
        PATH_XY is present, CONTOUR does not draw the con-
        tours, but rather records the normalized path coor-
        dinates in the named array.
        
        See the examples section below for an example 
        using the PATH_INFO and PATH_XY keywords to return 
        contour path information.
        
    TRIANGULATION
    
        Set this keyword to a variable that contains an 
        array of triangles returned from the TRIANGULATE 
        procedure. Providing triangulation data allows you 
        to contour irregularly gridded data directly, with-
        out gridding.
        
    XTYPE
    
        Set this keyword to specify a logarithmic X 
        axis.
        
    YTYPE
    
        Set this keyword to specify a logarithmic Y 
        axis.
        
    ZAXIS
    
        Set this keyword to draw a Z axis for the CON-
        TOUR plot. CONTOUR draws no Z axis by default. This 
        keyword is of use only if a three-dimensional trans-
        formation is established.
        
Graphics Keywords Accepted

        See Chapter 2, Graphics Keywords and System 
        Variables, for the description of graphics and plot-
        ting keywords not listed above. BACKGROUND CHANNEL 
        CHARSIZE CHARTHICK CLIP COLOR DATA DEVICE FOLLOW 
        FONT NOCLIP NODATA NOEDGE NOERASE NORMAL POSITION 
        SUBTITLE T3D THICK TICKLEN TITLE XCHARSIZE XGRID-
        STYLE XMARGIN XMINOR XRANGE XSTYLE XTHICK XTICKLEN 
        XTICKNAME XTICKFORMAT XTICKS XTICKV XTICK_GET XTITLE 
        YCHARSIZE YGRIDSTYLE YMARGIN YMINOR YRANGE YSTYLE 
        YTHICK YTICKLEN YTICKNAME YTICKFORMAT YTICKS YTICKV 
        YTICK_GET YTITLE ZCHARSIZE ZGRIDSTYLE ZMARGIN ZMINOR 
        ZRANGE ZSTYLE ZTHICK ZTICKLEN ZTICKFORMAT ZTICKNAME 
        ZTICKS ZTICKV ZTICK_GET ZTITLE ZVALUE.
        
Examples

To create a contour plot with 10 contour levels where 
every other contour is labeled:

Z = DIST(100)	Create a simple dataset to plot.

CONTOUR, Z, NLEVELS=10, /FOLLOW, TITLE='Simple Contour 
Plot'
Draw the plot.

The following commands describe a more complicated 
example that shows the use of polygon filling and smooth-
ing.

First, create a surface to contour:

A = RANDOMU(seed, 5, 6)	Create a 2D array of random numbers.

B = MIN_CURVE_SURF(A)	Smooth the dataset before contouring.

Draw solid-filled contours:

TEK_COLOR	Load discrete colors for contours.

CONTOUR, B, /FILL, NLEVELS=5, C_COLOR=INDGEN(5)+2
Draw filled contours.

CONTOUR, B, NLEVELS=5, /DOWNHILL, /OVERPLOT
Overplot the contour lines with tickmarks.

Draw line-filled contours:

CONTOUR, B, C_ORIENTATION=[0, 22, 45]

CONTOUR, B, /OVERPLOT	Overplot the contours.

The following program saves the closed path informa-
tion of a set of contours and plots the result:

PRO path

A = RANDOMU(seed, 8, 10)	Create a 2D array of random numbers.

B = MIN_CURVE_SURF(A)	Smooth the dataset before contouring.

CONTOUR, B, PATH_XY=xy, PATH_INFO=info
Compute contour paths.

FOR I = 0, (N_ELEMENTS(info) - 1 ) DO BEGIN

S = [INDGEN(info(I).N), 0]

PLOTS, xy(*,INFO(I).OFFSET + S ), /NORM
Plot the closed paths.

ENDFOR

END

To contour irregularly-gridded data without having to 
call TRIGRID, first use the TRIANGULATE procedure to get 
the Delaunay triangulation of your data, then pass the 
triangulation array to CONTOUR:

TRIANGULATE, X, Y, tri	Get triangulation.

CONTOUR, Z, X, Y, TRIANGULATION = tri
Draw the contours.

;-
;+
CONVERT_COORD

The CONVERT_COORD function transforms one or more 
sets of coordinates to and from the coordinate systems 
supported by IDL. The result of the function is a (3, n) 
vector containing the (x, y, z) components of the n output 
coordinates.

The input coordinates X and, optionally, Y and/or Z 
can be given in data, device, or normalized form by using 
the DATA, DEVICE, or NORMAL keywords. The default input 
coordinate system is DATA. The keywords TO_DATA, 
TO_DEVICE, and TO_NORMAL specify the output coordinate 
system.

If the input points are in 3D data coordinates, be 
sure to set the T3D keyword.

Calling Sequence

        Result = CONVERT_COORD(, X [, Y [, Z]])
        
Arguments

    X
    
        A vector or scalar argument providing the X com-
        ponents of the input coordinates. If only one argu-
        ment is specified, X must be an array of either two 
        or three vectors (i.e., (2,*) or (3,*)). In this 
        special case, X(0,*) is taken as the X values, 
        X(1,*) is taken as the Y values, and, if present, 
        X(2,*) is taken as the Z values.
        
    Y
    
        An optional argument providing the Y input coor-
        dinate(s).
        
    Z
    
        An optional argument providing the Z input coor-
        dinate(s).
        
Keywords

    DATA
    
        Set this keyword if the input coordinates are in 
        data space (the default).
        
    DEVICE
    
        Set this keyword if the input coordinates are in 
        device space.
        
    NORMAL
    
        Set this keyword if the input coordinates are in 
        normalized space.
        
    T3D
    
        Set this keyword if the 3D transformation !P.T 
        is to be applied.
        
    TO_DATA
    
        Set this keyword if the output coordinates are 
        to be in data space.
        
    TO_DEVICE
    
        Set this keyword if the output coordinates are 
        to be in device space.
        
    TO_NORMAL
    
        Set this keyword if the output coordinates are 
        to be in normalized space.
        
Example

Convert, using the currently established viewing 
transformation, 11 points along the parametric line x=t, 
y=2t, z=t, along the interval [0, 1] from data coordinates 
to device coordinates:

X = FINDGEN(11)/10.	Make a vector of X values.

D = CONVERT_COORD(X, 2*X, X^2, /T3D, /TO_DEVICE)
Convert the coordinates. D will be an (3,11) 
element array.

;-
;+
CONVOL

The CONVOL function convolves an array with a kernel, 
and returns the result. Convolution is a general process 
that can be used for various types of smoothing, signal 
processing, shifting, differentiation, edge detection, 
etc. The keyword CENTER controls the alignment of the ker-
nel with the array and the ordering of the kernel ele-
ments. If the keyword CENTER is explicitly set to 0, 
convolution is performed in the strict mathematical 
sense, otherwise the kernel is centered over each data 
point.



See the IDL Reference Guide for information on the 
algorithms used by CONVOL.

Calling Sequence

        Result = CONVOL(Array, Kernel [, Scale_Factor])
        
Arguments

    Array
    
        An array of any basic type except string. The 
        result of CONVOL has the same type and dimensions as 
        Array.
        
        If the Array parameter is of byte type, the 
        result is clipped to the range of 0 to 255. Negative 
        results are set to 0, and values greater than 255 
        are set to 255.
        
    Kernel
    
        An array of any type except string. If the type 
        of Kernel is not the same as Array, a copy of Kernel 
        is made and converted to the appropriate type before 
        use. The size of the kernel dimensions must be 
        smaller than those of Array.
        
    Scale_Factor
    
        A scale factor, for use with integer and byte 
        type data only, that is divided into each resulting 
        value. This argument allows the use of fractional 
        kernel values and avoids overflow with byte argu-
        ments. If omitted, 1.0 is used.
        
Keywords

    CENTER
    
        Set or omit this keyword to center the kernel 
        over each array point. If CENTER is explicitly set 
        to zero, the CONVOL function works in the conven-
        tional mathematical sense. In many signal and image 
        processing applications, it is useful to center a 
        symmetric kernel over the data, thereby aligning the 
        result with the original array.
        
    EDGE_WRAP
    
        Set this keyword to make CONVOL compute the val-
        ues of elements at the edge of Array by "wrapping" 
        the subscripts of Array at the edge. If neither 
        EDGE_WRAP nor EDGE_TRUNCATE is set, CONVOL sets the 
        values of elements at the edges of Array to zero.
        
    EDGE_TRUNCATE
    
        Set this keyword to make CONVOL compute the val-
        ues of elements at the edge of Array by repeating 
        the subscripts of Array at the edge. If neither 
        EDGE_WRAP nor EDGE_TRUNCATE is set, CONVOL sets the 
        values of elements at the edges of Array to zero.
        
Example

Convolve a vector of random noise and a one-dimen-
sional triangular kernel and plot the result. Create a 
simple vector as the original dataset and plot it by 
entering:

A = RANDOMN(SEED, 100) & PLOT, A

Create a simple kernel by entering:

K = [1, 2, 3, 2, 1]

Convolve the two and overplot the result by entering:

OPLOT, CONVOL(A, K, TOTAL(K))

;-
;+
COS

The periodic function COS returns the trigonometric 
cosine of X.

Calling Sequence

        Result = COS(X)
        
Arguments

    X
    
        The angle for which the cosine is desired, spec-
        ified in radians. If X is double-precision floating 
        or complex, the result is of the same type. All 
        other types are converted to single-precision float-
        ing-point and yield floating-point results. When 
        applied to complex numbers:
        
        COS(x) = COMPLEX(cos I cosh R, -sin R sinh (-I))
        
        where R and I are the real and imaginary parts 
        of x.
        
        If X is an array, the result has the same struc-
        ture, with each element containing the cosine of the 
        corresponding element of X.
        
Example

Find the cosine of 0.5 radians and print the result by 
entering:

PRINT, COS(.5)

IDL prints:

0.877583

;-
;+
COSH

The COSH function returns the hyperbolic cosine of X.

Calling Sequence

        Result = COSH(X)
        
Arguments

    X
    
        The value for which the hyperbolic cosine is 
        desired, specified in radians. If X is double-preci-
        sion floating, the result is also double- precision. 
        Complex values are not allowed. All other types are 
        converted to single-precision floating-point and 
        yield floating-point results. COSH is defined as:
        
        COSH(u) = (e^u + e^(-u))/2
        
        If X is an array, the result has the same struc-
        ture, with each element containing the hyperbolic 
        cosine of the corresponding element of X.
        
Example

Find the hyperbolic cosine of 0.5 radians and print 
the result by entering:

PRINT, COSH(.5)

IDL prints:

1.12763

;-
;+
CREATE_STRUCT

The CREATE_STRUCT function creates a structure given 
pairs of tag names and values. CREATE_STRUCT can also be 
used to concatenate structures.

Calling Sequence

        Result = CREATE_STRUCT(Tags, Values)
        
Arguments

    Tags
    
        The structure tag names. Tag names may be speci-
        fied either as scalar strings or string arrays. If 
        scalar strings are specified, values alternate with 
        tag names. If a string array is provided, values 
        must still be specified individually.
        
        Note that tag names must be enclosed in quotes.
        
    Values
    
        The value of each field of the structure must be 
        provided.
        
Keywords

    Name
    
        Use this keyword to create a named structure 
        using the specified string as the structure name.
        
Examples

To create the anonymous structure { A: 1, B: `xxx'} in 
the variable P, use the following command:

p = CREATE_STRUCT('A', 1, 'B', 'xxx')

To add the fields "FIRST" and "LAST" to the structure, 
do the following:

p = CREATE_STRUCT('FIRST', 0, p, 'LAST', 3)

The resulting structure contains { FIRST: 0, A: 1, B: 
'xxx', LAST: 3}.

Finally, the statement:

p = CREATE_STRUCT(name='list', ['A','B','C'], 1, 2, 
3)

creates the structure { LIST, A: 1, B: 2, C: 3}.



;-
;+
CURSOR

The CURSOR procedure is used to read the position of 
the interactive graphics cursor from the current graphics 
device. Note that not all graphics devices have interac-
tive cursors. CURSOR enables the graphic cursor on the 
device and optionally waits for the operator to position 
it. On devices that have a mouse, CURSOR normally waits 
until a mouse button is pressed (or already down). If no 
mouse buttons are present, CURSOR waits for a key on the 
keyboard to be pressed.

The system variable !ERR is set to the button status, 
or ASCII code of the key, if no mouse is present. Each 
mouse button is assigned a bit in !ERR, bit 0 is the left 
most button, bit 1 the next, etc.

Using CURSOR with Draw Widgets

Note that the CURSOR procedure is only for use with 
IDL graphics windows. It should not be used with draw wid-
gets. To obtain the cursor position and button state 
information from a draw widget, examine the X, Y, PRESS, 
and RELEASE fields in the structures returned by the draw 
widget in response to cursor events.

Using CURSOR with the TEK Device

Note that for the CURSOR procedure to work properly 
with Tektronix terminals, you may need to execute the com-
mand, DEVICE, GIN_CHARS=6.

Calling Sequence

        CURSOR, X, Y [, Wait]
        
Arguments

    X
    
        A named variable to receive the cursor's current 
        column position.
        
    Y
    
        A named variable to receive the cursor's current 
        row position.
        
    Wait
    
        An integer that specifies the conditions under 
        which CURSOR returns. This parameter can be used 
        interchangeably with the keyword parameters listed 
        below that specify the type of wait. The default 
        value is 1. The table below describes each type of 
        wait
        
        Note that not all modes of waiting work with all display devices.Wait 
        Value  Corresponding Keyword  Action
        ------------------------------------------------
        0           NOWAIT                Return immediately
        1           WAIT                  Return if button is down
        2           CHANGE                Return if a button is
                                          pressed, released, or the
                                          pointer is moved.
        3           DOWN                  Return on button down
        4           UP                    Return on button up
        
Keywords

    CHANGE
    
        Set this keyword to wait for pointer movement or 
        button transition within the currently selected win-
        dow.
        
    DATA
    
        Set this keyword to return X and Y in data coor-
        dinates.
        
    DOWN
    
        Set this keyword to wait for a button down tran-
        sition within the currently selected window.
        
    DEVICE
    
        Set this keyword to return X and Y in device 
        coordinates.
        
    NORMAL
    
        Set this keyword to return X and Y in normalized 
        coordinates.
        
    NOWAIT
    
        Set this keyword to read the pointer position 
        and button status and return immediately. If the 
        pointer is not within the currently selected window, 
        the device coordinates -1, -1 are returned.
        
    UP
    
        Set this keyword to wait for a button up transi-
        tion within the current window.
        
    WAIT
    
        Set this keyword to wait for a button to be 
        depressed within the currently selected window. If a 
        button is already pressed, return immediately.
        
Example

Activate the graphics cursor, select a point in the 
graphics window, and return the position of the cursor in 
device coordinates. Enter:

CURSOR, X, Y, /DEVICE

Move the cursor over the graphics window and press the 
mouse button. The position of the cursor in device coordi-
nates is stored in the variables X and Y. To label the 
location, enter:

XYOUTS, X, Y, 'X marks the spot.', /DEVICE

;-
;+
DBLARR

The DBLARR function returns a double-precision, 
floating-point vector or array.

Calling Sequence

        Result = DBLARR(D1, ..., Dn)
        
Arguments

    Di
    
        The dimensions of the result. The dimension 
        parameters can be any scalar expression. Up to eight 
        dimensions can be specified.
        
Keywords

    NOZERO
    
        Normally, DBLARR sets every element of the 
        result to zero. If NOZERO is set, this zeroing is 
        not performed and DBLARR executes faster.
        
Example

To create D, an 3-element by 3-element, double-preci-
sion, floating-point array with every element set to 0.0, 
enter:

D = DBLARR(3, 3)

;-
;+
DEFINE_KEY

The DEFINE_KEY procedure programs the keyboard func-
tion Key with the string Value, or with one of the actions 
specified by the available keywords.

Calling Sequence

        DEFINE_KEY, Key [, Value]
        
Arguments

    Key
    
        A scalar string containing the name of a func-
        tion key to be programmed. IDL maintains an internal 
        list of function key names and the escape sequences 
        they send.
        
        UNIX: Under Unix, if Key is not already on IDL's in-
        ternal list, you must use the ESCAPE keyword to spec-
        ify the escape sequence, otherwise, Key alone will 
        suffice. The available function keys and the escape 
        sequences they send vary from keyboard to keyboard. 
        The SETUP_KEYS Users' Library procedure should be 
        used once at the beginning of the session to enter 
        the keys for the current keyboard. See the IDL Ref-
        erence Guide for a list of standard key definitions. 
        
        VMS: Under VMS, the key names are those defined by 
        the Screen Management utility (SMG). See the IDL Ref-
        erence Guide for a list of standard key definitions. 
        
        Windows: Under Windows, function keys F1 through F12 
        can be customized.
        
        Macintosh: DEFINE_KEY does not currently work with 
        IDL for Macintosh.
        
    Value
    
        The scalar string that will be printed (as if it 
        had been typed manually at the keyboard) when Key is 
        pressed. If Value is not present, and no function is 
        specified for the key with one of the keywords, the 
        key is cleared so that nothing happens when it is 
        pressed.
        
Keywords

    MATCH_PREVIOUS
    
        Set this keyword to program Key to prompt the 
        user for a string, and then search the saved command 
        buffer for the most recently issued command that 
        contains that string. If a match is found, the 
        matching command becomes the current command, other-
        wise the last command entered is used. Under Unix, 
        the default match key is the up caret "^" key when 
        pressed in column 1. Under VMS, the default match 
        key is PF1.
        
    NOECHO
    
        Set this keyword to enter the Value assigned to 
        Key when pressed, without echoing the string to the 
        screen. This feature is useful for defining keys 
        that perform such actions as erasing the screen. If 
        NOECHO is set, TERMINATE is also assumed to be set.
        
    TERMINATE 
    
        If this keyword is set, and Value is present, 
        pressing Key terminates the current input operation 
        after its assigned value is entered. Essentially, an 
        implicit carriage return is added to the end of 
        Value.
        
Unix Keywords

    BACK_CHARACTER
    
        Set this keyword to program Key to move the cur-
        rent cursor position left one character.
        
    BACK_WORD
    
        Set this keyword to program Key to move the cur-
        rent cursor position left one word.
        
    DELETE_CHARACTER
    
        Set this keyword to program Key to delete the 
        character to the left of the cursor.
        
    DELETE_CURRENT
    
        Set this keyword to program Key to delete the 
        character directly underneath the cursor.
        
    DELETE_EOL
    
        Set this keyword to program Key to delete from 
        the cursor position to the end of the line.
        
    DELETE_LINE
    
        Set this keyword to program Key to delete all 
        characters to the left of the cursor.
        
    DELETE_WORD
    
        Set this keyword to programs Key to delete the 
        word to the left of the cursor.
        
    END_OF_LINE
    
        Set this keyword to program Key to move the cur-
        sor to the end of the line.
        
    ENTER_LINE
    
        Set this keyword to program Key to enter the 
        current line (i.e., the action normally performed by 
        the "Return" key).
        
    ESCAPE
    
        A scalar string that specifies the escape 
        sequence that corresponds to Key. See the discussion 
        below for further details.
        
    FORWARD_CHARACTER
    
        Set this keyword to program Key to move the cur-
        rent cursor position right one character.
        
    FORWARD_WORD
    
        Set this keyword to program Key to move the cur-
        rent cursor position right one word.
        
    INSERT_OVERSTRIKE_TOGGLE
    
        Set this keyword to program Key to toggle 
        between "insert" and "overstrike" mode. When charac-
        ters are typed into the middle of a line, insert 
        mode causes the trailing characters to be moved to 
        the right to make room for the new ones. Overstrike 
        mode causes the new characters to overwrite the 
        existing ones.
        
    NEXT_LINE
    
        Set this keyword to program Key to move forward 
        one command in the saved command buffer and make 
        that command the current one.
        
    PREVIOUS_LINE
    
        Set this keyword to program Key to move back one 
        command in the saved command buffer and make that 
        command the current one.
        
    RECALL
    
        Set this keyword to program Key to prompt the 
        user for a command number. The saved command corre-
        sponding to the entered number becomes the current 
        command. In order to view the currently saved com-
        mands and the number currently associated with each, 
        enter the IDL command:
        
        HELP, /RECALL COMMANDS
        
        The RECALL operation remembers the last command 
        number entered, and if the user simply presses 
        return, it recalls the command currently associated 
        with that saved number. Since the number associated 
        with a given command increases by one each time a 
        new command is saved, this feature can be used to 
        quickly replay a sequence of commands. For example
        
        IDL> PRINT, 1
        
        1
        
        IDL> PRINT, 2
        
        2
        
        IDL> HELP, /RECALL_COMMANDS
        
        Recall buffer length: 20
        
        1               PRINT, 2
        
        2               PRINT, 1
        
        IDL>	User presses key tied to RECALL.
        
        Recall Line #: 2	Line 2 is requested.
        
        IDL> PRINT, 1	Saved command 2 is recalled. 
        
        1
        
        Recall Line #: 	User presses return.
        
        IDL> PRINT, 2	Saved command 2 is recalled again.
        
        2
        
    REDRAW
    
        Set this keyword to program Key to retype the 
        current line.
        
    START_OF_LINE 
    
        Set this keyword to program Key to move the cur-
        sor to the start of the line.
        
Defining New Function Keys

Under VMS, IDL uses the SMG screen management package, 
which ensures that IDL command editing behaves in the 
standard VMS way. Hence, it is not possible to use a key 
SMG does not understand.

Under Unix, IDL can handle arbitrary function keys. 
When adding a definition for a function key that is not 
built into IDL's default list of recognized keys, you must 
use the ESCAPE keyword to specify the escape sequence it 
sends. For example, to add a function key named "HELP" 
which sends the escape sequence <Escape>[28~, use the com-
mand:

DEFINE_KEY, 'HELP', ESCAPE = '\033[28~'

This command adds the HELP key to the list of keys 
understood by IDL. Since only the key name and escape 
sequence were specified, pressing the HELP key will do 
nothing. The Value argument, or one of the keywords pro-
vided to specify command line editing functions, could 
have been included in the above statement to program it 
with an action.

Once a key is defined using the ESCAPE keyword, it is 
contained in the internal list of function keys. It can 
then be subsequently redefined without specifying the 
escape sequence.

It is convenient to include commonly used key defini-
tions in a startup file, so that they will always be 
available. See Chapter 2 of the IDL User's Guide for a 
discussion of startup files.

Usually, the User Library procedure SETUP_KEYS is 
used to define the function keys found on the keyboard, so 
it is not necessary to specify the ESCAPE keyword. For 
example, to program key "F2" on a Sun keyboard to redraw 
the current line:

SETUP_KEYS

DEFINE_KEY, 'F2', /REDRAW

;-
;+
DEFSYSV

The DEFSYSV procedure creates a new system variable 
called Name initialized to Value.

Calling Sequence

        DEFSYSV, Name, Value [, Read_Only]
        
Arguments

    Name
    
        A scalar string containing the name of the sys-
        tem variable to be created. All system variable 
        names must begin with the character `!'.
        
    Value
    
        An expression from which the type, structure, 
        and initial value of the new system variable is 
        taken. Value can be a scalar, array, or structure.
        
    Read_Only
    
        If the Read_Only argument is present and non-
        zero, the value of the newly-created system variable 
        cannot be changed (i.e., the system variable is 
        read-only, like the !PI system variable). Otherwise, 
        the value of the new system variable can be modi-
        fied.
        
Keywords

    EXISTS
    
        Set this keyword to a named variable that 
        returns 1 if the system variable specified by Name 
        exists. If this keyword is specified, Value can be 
        omitted. For example, the following commands could 
        be used to check that the system variable XYZ 
        exists:
        
        DEFSYSV, '!XYZ', EXISTS = i
        
        IF i EQ 1 THEN PRINT, '!XYZ exists' ELSE $
        
                  PRINT, '!XYZ does not exist'
        
Example

To create a new, floating-point, scalar system vari-
able called !NEWVAR with an initial value of 2.0, enter:

DEFSYSV, '!NEWVAR', 2.0

;-
;+
DELETE_SYMBOL (VMS Only)

The DELETE_SYMBOL procedure deletes a DCL (Digital 
Command Language) interpreter symbol for the current pro-
cess.

Calling Sequence

        DELETE_SYMBOL, Name
        
Arguments

    Name 
    
        A scalar string containing the name of the sym-
        bol to be deleted.
        
Keywords

    TYPE
    
        Indicates the table from which Name will be 
        deleted. Set TYPE to 1 to specify the local symbol 
        table. Set TYPE to 2 to specify the global symbol 
        table. The default is to search the local table.
        
;-
;+
DELLOG (VMS Only)

The DELLOG procedure deletes a VMS logical name.

Calling Sequence

        DELLOG, Lognam 
        
Arguments

    Lognam
    
        A scalar string containing the name of the logi-
        cal to be deleted.
        
Keywords

    TABLE
    
        A scalar string giving the name of the logical 
        table from which to delete Lognam. If TABLE is not 
        specified, LNM$PROCESS_TABLE is used.
        
;-
;+
DELVAR

The DELVAR procedure deletes variables from the main 
IDL program level. DELVAR frees any memory used by the 
variable and removes it from the main program's symbol 
table. The following restrictions on apply:

    DELVAR can only be called from the main program 
    level.
    
    Each time DELVAR is called, the main program is 
    erased. Variables that are not deleted remain 
    unchanged.
    
Calling Sequence

        DELVAR, V1, ..., Vn
        
Arguments

    Vi
    
        One or more named variables to be deleted.
        
Example

Suppose that the variable Q is defined at the main 
program level. Q can be deleted by entering:

DELVAR, Q

;-
;+
DEVICE

The DEVICE procedure provides device-dependent con-
trol over the current graphics device (as set by the 
SET_PLOT routine). The IDL graphics procedures and func-
tions are device-independent. That is, IDL presents the 
user with a consistent interface to all devices. However, 
most devices have extra abilities that are not directly 
available through this interface. DEVICE is used to access 
and control such abilities. It is used by specifying var-
ious keywords that differ from device to device.

See Chapter 3, "IDL Graphics Devices" of the IDL Ref-
erence Guide for a description of the keywords available 
for each graphics device.

;-
;+
DILATE

The DILATE function implements the morphologic dila-
tion operator on both binary and grayscale images.

Mathematical morphology is a method of processing 
digital images on the basis of shape. A discussion of this 
topic is beyond the scope of this manual. A suggested ref-
erence is: Haralick, Sternberg, and Zhuang, "Image Analy-
sis Using Mathematical Morphology," IEEE Transactions on 
Pattern Analysis and Machine Intelligence, Vol. PAMI-9, 
No. 4, July, 1987, pp. 532-550. Much of this discussion is 
taken from that article.

Briefly, the DILATE function returns the dilation of 
Image by the structuring element Structure. This operator 
is commonly known as "fill", "expand", or "grow." It can 
be used to fill "holes" of a size equal to or smaller than 
the structuring element.

Used with binary images, where each pixel is either 1 
or 0, dilation is similar to convolution. Over each pixel 
of the image, the origin of the structuring element is 
overlaid. If the image pixel is nonzero, each pixel of the 
structuring element is added to the result using the "or" 
operator.



See the IDL Reference Guide for more discussion about 
the algorithms used to the DILATE and ERODE functions.

Used with grayscale images, which are always con-
verted to byte type, the DILATE function is accomplished 
by taking the maximum of a set of sums. It can be used to 
conveniently implement the neighborhood maximum operator 
with the shape of the neighborhood given by the structur-
ing element.

Calling Sequence

        Result = DILATE(Image, Structure [, X0, Y0])
        
Arguments

    Image
    
        The array upon which the dilation is to be per-
        formed. If the parameter is not of byte type, a tem-
        porary byte copy is obtained. If neither of the 
        keywords GRAY or VALUES is present, the image is 
        treated as a binary image with all nonzero pixels 
        considered as 1.
        
    Structure
    
        The structuring element which may be a one or 
        two dimensional array. Elements are interpreted as 
        binary: values are either zero or nonzero.
        
    X0, Y0
    
        Optional parameters specifying the row and col-
        umn coordinate of the structuring element's origin. 
        If omitted, the origin is set to the center, ([Nx/
        2], [Ny/2]), where Nx and Ny are the dimensions of 
        the structuring element array. The origin need not 
        be within the structuring element.
        
Keywords

    GRAY
    
        Set this keyword to perform grayscale, rather 
        than binary, dilation. The nonzero elements of the 
        Structure parameter determine the shape of the 
        structuring element (neighborhood). If VALUES is not 
        present, all elements of the structuring element are 
        0, yielding the neighborhood maximum operator.
        
    VALUES
    
        An array with the same dimensions as Structure 
        providing the values of the structuring element. The 
        presence of this parameter implies grayscale dila-
        tion. Each pixel of the result is the maximum of the 
        sum of the corresponding elements of VALUE overlaid 
        with Image.
        
Example

The following example thresholds a gray scale image at 
the value of 100, producing a binary image. The result is 
then "opened" with a 3 pixel by 3 pixel square shape oper-
ator, using the DILATE and ERODE operators. The effect is 
to remove holes, islands, and peninsula smaller than the 
shape operator:

B = A GE 100	Threshold and make binary image.

S = REPLICATE(1, 3, 3)	Create the shape operator.

C = DILATE(ERODE(B, S), S)	"Opening" operator.

TVSCL, C	Show the result.

;-
;+
DINDGEN

The DINDGEN function returns a double-precision, 
floating-point array with the specified dimensions. Each 
element of the array is set to the value of its one-dimen-
sional subscript.

Calling Sequence

        Result = DINDGEN(D1, ..., Dn)
        
Arguments

    Di
    
        The dimensions of the result. The dimension 
        parameters may be any scalar expression. Up to eight 
        dimensions may be specified.
        
Example

To create D, a 100-element, double-precision, float-
ing-point array with each element set to the value of its 
subscript, enter:

D = DINDGEN(100)

;-
;+
DOUBLE

The DOUBLE function returns a result equal to Expres-
sion converted to double-precision floating-point.

Calling Sequence

        Result = DOUBLE(Expression[, Offset [, Dim1, 
        ..., Dimn]])
        
Arguments

    Expression
    
        The expression to be converted to double-preci-
        sion floating-point.
        
    Offset
    
        Offset from beginning of the Expression data 
        area. Specifying this argument allows fields of data 
        extracted from Expression to be treated as double-
        precision floating-point data. See the description 
        in Chapter 4 of the IDL User's Guide for details.
        
    Di
    
        When extracting fields of data, the Di arguments 
        specify the dimensions of the result. The dimension 
        parameters can be any scalar expression. Up to eight 
        dimensions can be specified. If no dimension argu-
        ments are given, the result is taken to be scalar.
        
        When converting from a string argument, it is 
        possible that the string does not contain a valid 
        floating-point value and no conversion is possible. 
        The default action in such cases is to print a warn-
        ing message and return 0. The ON_IOERROR procedure 
        can be used to establish a statement to be jumped to 
        in case of such errors.
        
Example

Suppose that A contains the integer value 45. A dou-
ble-precision, floating-point version of A can be stored 
in B by entering:

B = DOUBLE(A)

;-
;+
EMPTY

The EMPTY procedure causes all buffered output for the 
current graphics device to be written. IDL uses buffered 
output on many display devices for reasons of efficiency. 
This buffering leads to rare occasions where a program 
needs to be certain that data are not waiting in a buffer, 
but have actually been output. EMPTY is a low-level graph-
ics routine. IDL graphics routines generally handle 
flushing of buffered data transparently to the user, so 
the need for EMPTY is very rare.

Calling Sequence

        EMPTY
        
;-
;+
EOF

The EOF function tests the specified file unit for the 
end-of-file condition. If the file pointer is positioned 
at the end of the file, EOF returns true (1), otherwise 
false (0) is returned.

Note that the EOF function cannot be used with files 
opened with the NOSTDIO keyword to the OPEN routines. Many 
of the devices commonly used with NOSTDIO signal their 
end-of-file by returning a zero transfer count to the I/O 
operation that encounters the end-of-file.

Calling Sequence

        Result = EOF(Unit)
        
Arguments

    Unit
    
        The file unit to test for end-of-file.
        
Using EOF with VMS Files

Under VMS, the EOF function does not work with files 
accessed via DECNET or that do not have sequential organi-
zation (i.e., relative or indexed). The EOF procedure can-
not be used with such files as it will always return 
"false". Instead, use the ON_IOERROR procedure to detect 
when the end-of-file occurs.

Examples

If file unit number 1 is open, the end-of-file condi-
tion can be checked by examining the value of the expres-
sion EOF(1). For example, the following IDL code reads and 
prints a text file:

OPENR, 1, 'test.lis'	Open the file test.lis.

A = ''	Define a string variable.

WHILE NOT EOF(1) DO BEGIN	Loop until EOF is found.

    READF, 1, A	Read a line of text.

    PRINT, 	Print the line.

    ENDWHILE	

CLOSE, 1	Close the file.

;-
;+
ERASE

The ERASE procedure erases the screen of the currently 
selected graphics device (or starts a new page if the 
device is a printer). The device is reset to alphanumeric 
mode if it has such a mode (e.g., Tektronix terminals).

Calling Sequence

        ERASE [, Background_Color]
        
Arguments

    Background_Color
    
        The color index for the screen to be erased to. 
        If this argument is omitted ERASE resets the screen 
        to the default background color (normally 0), stored 
        in the system variable !P.BACKGROUND. Providing a 
        value for Background_Color overrides the default.
        
        Warning: Not all devices support this feature.
        
Keywords

    CHANNEL
    
        The channel or channel mask for the erase opera-
        tion. This parameter has meaning only when used with 
        devices that support true-color or multiple-display 
        channels. The default value is !P.CHL.
        
    COLOR
    
        Specifies the background color. Using this key-
        word is analogous to using the Background_Color 
        argument.
        
;-
;+
ERODE

The ERODE function implements the morphologic erosion 
operator on binary and grayscale images and vectors.

See the description of the DILATE function for back-
ground on morphological operators. Erosion is the dual of 
dilation. It does to the background what dilation does to 
the foreground.

Briefly, the ERODE function returns the erosion of 
Image by the structuring element Structure. This operator 
is commonly known as "shrink" or "reduce". It can be used 
to remove islands smaller than the structuring element. 



See the IDL Reference Guide for more information on 
the algorithms used by the ERSODE and DILATE functions.

Used with grayscale images, which are always con-
verted to byte type, the ERODE function is accomplished by 
taking the minimum of a set of differences. It can be used 
to conveniently implement the neighborhood minimum opera-
tor with the shape of the neighborhood given by the struc-
turing element.

Calling Sequence

        Result = ERODE(Image, Structure [, X0, Y0])
        
Arguments

    Image
    
        The array upon which the erosion is to be per-
        formed. If this parameter is not of byte type, a 
        temporary byte copy is obtained. If neither of the 
        keywords GRAY or VALUES is present, the image is 
        treated as a binary image with all nonzero pixels 
        considered as 1.
        
    Structure
    
        A one- or two-dimensional array to be used as 
        the structuring element. The elements are inter-
        preted as binary values-either zero or nonzero.
        
    X0, Y0
    
        Optional parameters specifying the row and col-
        umn coordinate of the structuring element's origin. 
        If omitted, the origin is set to the center, ([Nx/
        2], [Ny/2]), where Nx and Ny are the dimensions of 
        the structuring element array. The origin need not 
        be within the structuring element.
        
Keywords

    GRAY
    
        Set this keyword to perform grayscale, rather 
        than binary, erosion. nonzero elements of the Struc-
        ture parameter determine the shape of the structur-
        ing element (neighborhood). If VALUES is not 
        present, all elements of the structuring element are 
        0, yielding the neighborhood minimum operator.
        
    VALUES
    
        An array of the same dimensions as Structure 
        providing the values of the structuring element. The 
        presence of this keyword implies grayscale erosion. 
        Each pixel of the result is the minimum of Image 
        less the corresponding elements of VALUE.
        
Example

The following example thresholds a gray scale image at 
the value of 100, producing a binary image. The result is 
then "opened" with a 3 pixel by 3 pixel square shape oper-
ator, using the ERODE and DILATE operators. The effect is 
to remove holes, islands, and peninsula smaller than the 
shape operator:

B = A GE 100	Threshold and make binary image.

S = REPLICATE(1, 3, 3)	Create the shape operator.

C = DILATE(ERODE(B, S), S)	"Opening" operator.

TVSCL, C	Show the result.

;-
;+
ERRORF

The ERRORF function returns the value of the error 
function:

erf(x) = 2/(SQRT(!PI) * integral from 0 to x of (e^(-
t^2)dt)

The result is a double-precision if the argument is 
double-precision. If the argument is floating-point, the 
result is floating-point. The result always has the same 
structure as X. The ERRORF function does not work with 
complex arguments.

Calling Sequence

        Result = ERRORF(X)
        
Arguments

    X
    
        The expression for which the error function is 
        to be evaluated.
        
Example

To find the error function of 0.4 and print the 
result, enter:

PRINT, ERRORF(0.4)

IDL prints:

0.428392

;-
;+
EXECUTE

The EXECUTE function compiles and executes one or more 
IDL statements contained in a string at run-time. It also 
returns true (1) if the string was successfully compiled 
and executed. If an error occurs during either phase, the 
result is false (0).

Like the CALL_PROCEDURE and CALL_FUNCTION routines, 
calls to EXECUTE can be nested. However, compiling the 
string at run-time is inefficient. CALL_FUNCTION and 
CALL_PROCEDURE provide much of the functionality of EXE-
CUTE without imposing this limitation, and should be used 
instead of EXECUTE whenever possible.

Calling Sequence

        Result = EXECUTE(String)
        
Arguments

    String
    
        A string containing the command(s) to be com-
        piled and executed.
        
Warning

        Do not use EXECUTE to create new variables 
        inside procedures or functions. All variables used 
        by the string that is executed should be referenced 
        or defined when the program unit is originally com-
        piled. New variables cannot be created after a pro-
        cedure or function is compiled. Attempts to create 
        new variables result in the error "Program data area 
        full".
        
Example

Create a string that holds a valid IDL command by 
entering:

com = 'PLOT, [0,1]'

Execute the contents of the string by entering:

R = EXECUTE(com)

A plot should appear. You can confirm that the string 
was successfully compiled and executed by checking that 
the value of R is 1.

;-
;+
EXIT

The EXIT procedure quits IDL and exits back to the 
operating system. All buffers are flushed and open files 
are closed. The values of all variables that were not 
saved are lost.

Calling Sequence

        EXIT
        
;-
;+
EXP

The EXP function returns the natural exponential 
function of Expression.

Calling Sequence

        Result = EXP(Expression)
        
Arguments

    Expression
    
        The expression to be evaluated. If Expression is 
        double-precision floating or complex, the result is 
        of the same type. All other types are converted to 
        single-precision floating-point and yield floating-
        point results. The definition of the exponential 
        function for complex arguments is:
        
        exp(x) = COMPLEX(e^R cos I, e^R sin I)
        
        where:
        
        R = real part of x, and I = imaginary part of x. 
        If Expression is an array, the result has the same 
        structure, with each element containing the result 
        for the corresponding element of Expression.
        
Example

Plot a Gaussian with a 1/e width of 10 and a center of 
50 by entering:

PLOT, EXP(-(FINDGEN(100)/10. - 5.0)^2)

;-
;+
EXPAND_PATH

The EXPAND_PATH function is used to expand a simple 
path-definition string into a full path name for use with 
the !PATH and !HELP_PATH system variables.

As explained in Chapter 2 of the IDL User's Guide, 
there are two search paths maintained in IDL system vari-
ables:

    !PATH is a list of locations where IDL searches 
    for currently undefined procedures and functions.
    
    !HELP_PATH is a list of locations where IDL 
    searches for online help files when the online help 
    facility is used.
    
The Path Definition String

EXPAND_PATH accepts a single argument, a scalar 
string that contains a simple path-definition string, 
that the function expands into a list of directories that 
can be assigned to !PATH or !HELP_PATH. This string uses 
the same format as the IDL_PATH environment variable 
(Unix, Windows) or logical name (VMS). This format is also 
used in the path preferences dialog (Windows, Macintosh).

The path-definition string is a scalar string con-
taining a list of directories (and in the case of VMS, 
text library files that are prefixed with the "@" charac-
ter), separated by a special character (":" for Unix and 
Macintosh, "," for VMS, and ";" for Windows). Prepending a 
"+" character to a directory name causes all of its subdi-
rectories to be searched.

        If a directory specified in the string does not 
        have a "+" character prepended to it, it is copied 
        to the output string verbatim. However, if it does 
        have a leading "+" then EXPAND_PATH performs the 
        following steps, searching each subdirectory of the 
        specified directory recursively for other subdirec-
        tories. All directories found that contain at least 
        one file of the desired type are added to the search 
        path.
        
        UNIX: The directory name is expanded to remove wild-
        cards (~ and *). This avoids overhead IDL would oth-
        erwise incur as it searches for library routines. It 
        is discarded from the search path if any of the fol-
        lowing is true:
        
        It is not a directory.
        
        The directory it names does not exist or cannot 
        be accessed.
        
        The directory does not contain any .pro or .sav 
        files if the result is intended for !PATH (the 
        default) or the directory does not contain any .help 
        files if the result is intended for !HELP_PATH 
        (i.e., if the HELP keyword is set).
        
        VMS: The directory name is discarded from the search 
        path if any of the following is true:
        
        It is not a directory.
        
        The directory it names does not exist or cannot 
        be accessed.
        
        The directory does not contain any .PRO or .SAV 
        files if the result is intended for !PATH (the 
        default) or the directory does not contain any .HELP 
        files if the result is intended for !HELP_PATH 
        (i.e., if the HELP keyword is set).
        
        In addition, any text library (.TLB) files are 
        added to the result.
        
        Windows: The directory name is expanded to remove 
        wildcards (*). This avoids overhead IDL would other-
        wise incur as it searches for library routines. It is 
        discarded from the search path if any of the following 
        is true:
        
        It is not a directory.
        
        The directory it names does not exist or cannot 
        be accessed.
        
        The directory does not contain any .PRO or .SAV 
        files if the result is intended for !PATH (the 
        default) or the directory does not contain any .HEL 
        files if the result is intended for !HELP_PATH 
        (i.e., if the HELP keyword is set).
        
        Macintosh: The folder name is expanded to remove 
        wildcards (*). This avoids overhead IDL would other-
        wise incur as it searches for library routines. It is 
        discarded from the search path if any of the following 
        is true:
        
        It is not a folder.
        
        The folder it names does not exist or cannot be 
        accessed.
        
        The folder does not contain any .pro or .sav 
        files if the result is intended for !PATH (the 
        default) or the folder does not contain any .help 
        files if the result is intended for !HELP_PATH 
        (i.e., if the HELP keyword is set).
        
Calling Sequence

        Result = EXPAND_PATH(String)
        
Arguments

    String
    
        A scalar string containing the path-definition 
        string to be expanded. See "The Path Definition 
        String," above, for details.
        
Keywords

    ARRAY
    
        Set this keyword to return the result as a 
        string array with each element containing one path 
        segment. In this case, there is no need for a sepa-
        rator character and none is supplied. Normally, the 
        result is a string array with the various path seg-
        ments separated with the correct special delimiter 
        character for the current operating system.
        
    COUNT
    
        Set this keyword to a named variable which 
        returns the number of path segments contained in the 
        result.
        
    HELP
    
        When expanding a path segment that starts with a 
        `+' character, the default behavior is to assume 
        that the result will be assigned to the !PATH system 
        variable. In this case, EXPAND_PATH looks for .PRO, 
        and .SAV (and .TLB for VMS) files. Set the HELP key-
        word to interpret the result for use with 
        !HELP_PATH. EXPAND_PATH then looks for files with a 
        .HELP (or .HEL for DOS/Windows) extension.
        
Example

Under the Unix operating system, the default value of 
!PATH is specified as "+/usr/local/lib/idl/lib", unless 
this default is changed by setting the IDL_PATH environ-
ment variable. When IDL starts, one of the first things it 
does is to run this default value through the EXPAND_PATH 
function to obtain the actual value for the !PATH system 
variable. The following statement shows how this expan-
sion might look (assuming that your IDL is installed in /
usr/local/lib/idl):

PRINT, EXPAND_PATH('+/usr/local/lib/idl/lib')

IDL prints:

/usr/local/lib/idl/lib/userlib:/usr/local/lib/idl/lib/statlib:
/usr/local/lib/idl/lib/widgets:/usr/local/lib/idl/lib/demo:
/usr/local/lib/idl/lib/xdemo/examples:/usr/local/lib/idl/lib/xdemo

;-
;+
FFT

The FFT function returns a result equal to the com-
plex, discrete Fourier transform of Array. The result of 
this function is a complex array. See the IDL Reference 
Guide for the definition of the FFT.



If the keyword OVERWRITE is set, the transform is per-
formed in-place, and the result overwrites the original 
contents of the array.

The result returned by FFT is a complex array that has 
the same dimensions as the input array. The output array 
is ordered in the same manner as almost all discrete Fou-
rier transforms. Element 0 contains the zero frequency 
component, F0. F1 contains the smallest non-zero positive 
frequency, which is equal to 1/(NT) where N is the number 
of elements in the respective dimension and T is the sam-
pling interval. F2 corresponds to a frequency of 2/(NT). 
FN/2 contains the component corresponding to the Nyquist 
frequency, 1/(2T), which is the highest frequency that can 
be sampled.

Negative frequencies are stored in reverse order from 
FN-1, FN-2, ..., FN/2+1, corresponding to frequencies of -1/
NT, -2/NT, and -(N/2 - 1)/NT, respectively.

Calling Sequence

        Result = FFT(Array, Direction)
        
Arguments

    Array
    
        The array to which the Fast Fourier Transform 
        should be applied. If Array is not of complex type, 
        it is converted to complex type. The dimensions of 
        the result are identical to those of Array. The size 
        of each dimension may be any integer value and does 
        not necessarily have to be an integer power of 2, 
        although powers of 2 are certainly the most effi-
        cient.
        
    Direction
    
        Direction is a scalar indicating the direction 
        of the transform, which is negative by convention 
        for the forward transform, and positive for the 
        inverse transform.
        
        A normalization factor of 1/N, where N is the 
        number of points, is applied during the forward 
        transform.
        
        Note: When transforming from a real vector to 
        complex and back, it is slightly faster to set 
        Direction to 1 in the real to complex FFT.
        
Keywords

    OVERWRITE
    
        If this keyword is set, and the Array parameter 
        is a variable of complex type, the transform is done 
        "in-place". The result overwrites the previous con-
        tents of the variable. For example, to perform a 
        forward, in-place FFT on the variable a:
        
        a = FFT(a, -1, /OVERWRITE)
        
Example

Display the log of the power spectrum of a 100-element 
index array by entering:

PLOT_IO, ABS(FFT(FINDGEN(100), -1))

As a more complex example, display the power spectrum 
of a 100-element vector sampled at a rate of 0.1 seconds 
per point. Show the 0 frequency component at the center of 
the plot and label the abscissa with frequency:

N =100	Define the number of points.

T = 0.1	Define the interval.

N21 = N/2 + 1	Midpoint+1 is the most negative frequency 
subscript.

F = INDGEN(N)	The array of subscripts.

F(N21) = N21 -N + FINDGEN(N21-2)	Insert negative frequencies in elements 
F(N/2 +1), ..., F(N-1).

F = F/(N*T)	Compute T0 frequency.

PLOT_IO, SHIFT(F, -N21), SHIFT(ABS(FFT(Y, -1)), -N21)
Shift so that the most negative frequency is 
plotted first.



;-
;+
FINDFILE

The FINDFILE function returns a string array contain-
ing the names of all files matching File_Specification.

All matched filenames are returned in a string array, 
one file name per array element. If no files exist with 
names matching the File_Specification a null scalar 
string is returned instead of a string array.

Note: Under VMS, FINDFILE returns the full path spec-
ification for any file it finds. On all other platforms, 
FINDFILE returns only the local filename in the directory 
specified by File_Specification.

Calling Sequence

        Result = FINDFILE(File_Specification)
        
Arguments

    File_Specification
    
        A scalar string used to find files. The string 
        can contain any valid command-interpreter wildcard 
        characters. If File_Specification is omitted, the 
        names of all files in the current directory are 
        returned.
        
Keywords

    COUNT
    
        A named variable into which the number of files 
        found is placed. If no files are found, a value of 0 
        is returned.
        
Example

To print the names of all the Unix files with "dat" 
extensions, use the command:

PRINT, FINDFILE('*.dat')

;-
;+
FINDGEN

The FINDGEN function returns a single-precision, 
floating-point array with the specified dimensions. Each 
element of the array is set to the value of its one-dimen-
sional subscript.

Calling Sequence

        Result = FINDGEN(D1, ..., Dn)
        
Arguments

    Di
    
        The dimensions of the result. The dimension 
        parameters can be any scalar expression. Up to eight 
        dimensions can be specified.
        
Example

To create F, a 6-element vector of single-precision, 
floating-point values where each element is set to the 
value of its subscript, enter:

F = FINDGEN(6)

The value of F(0) is 0.0, F(1) is 1.0, et cetera.

;-
;+
FINITE

The FINITE function returns 1 (True) if its argument 
is finite. If the argument is infinite or not a defined 
number, "NaN", 0 (False) is returned. "NaN" is the result 
of an undefined operation, such as dividing zero by zero, 
taking the logarithm of zero or a negative number, or any 
operation involving a "NaN" (e.g., 1+NaN = NaN). The 
result is a byte expression of the same structure as the 
argument X.

Note: This function always returns 1 on machines that 
do not implement the IEEE floating-point standard, such as 
the VAX.

Calling Sequence

        Result = FINITE(X)
        
Arguments

    X
    
        A floating-point, double-precision, or complex 
        scalar or array expression. Strings are first con-
        verted to floating-point. This function is meaning-
        less for byte, integer, or longword arguments.
        
Example

To find out if the logarithm of 5.0 is finite, enter:

PRINT, FINITE(ALOG(5.0))

IDL prints "1" because the argument is finite.

;-
;+
FIX

The FIX function returns a result equal to Expression 
converted to integer type.

Calling Sequence

        Result = FIX(Expression [, Offset [, Dim1, ..., 
        Dimn]])
        
Arguments

    Expression
    
        The expression to be converted to integer.
        
    Offset
    
        Offset from beginning of the Expression data 
        area. Specifying this argument allows fields of data 
        extracted from Expression to be treated as integer 
        data. See the description in Chapter 4 of the IDL 
        User's Guide for details.
        
    Di
    
        When extracting fields of data, the Di arguments 
        specify the dimensions of the result. The dimension 
        parameters can be any scalar expression. Up to eight 
        dimensions can be specified. If no dimension argu-
        ments are given, the result is taken to be scalar.
        
        When converting from a string argument, it is 
        possible that the string does not contain a valid 
        integer and no conversion is possible. The default 
        action in such cases is to print a warning message 
        and return 0. The ON_IOERROR procedure can be used 
        to establish a statement to be jumped to in case of 
        such errors.
        
Example

Convert the floating-point array [2.2, 3.0, 4.5] to 
integer type and store the new array in the variable I by 
entering:

I = FIX([2.2, 3.0, 4.5])

;-
;+
FLOAT

The FLOAT function returns a result equal to Expres-
sion converted to single-precision floating-point.

Calling Sequence

        Result = FLOAT(Expression [, Offset [, Dim1, 
        ..., Dimn]])
        
Arguments

    Expression
    
        The expression to be converted to single-preci-
        sion floating-point.
        
    Offset
    
        Offset from beginning of the Expression data 
        area. Specifying this argument allows fields of data 
        extracted from Expression to be treated as single 
        precision floating point data. See the description 
        in Chapter 4 of the IDL User's Guide for details.
        
    Di
    
        When extracting fields of data, the Di arguments 
        specify the dimensions of the result. The dimension 
        parameters can be any scalar expression. Up to eight 
        dimensions can be specified. If no dimension argu-
        ments are given, the result is taken to be scalar.
        
        When converting from a string argument, it is 
        possible that the string does not contain a valid 
        floating-point value and no conversion is possible. 
        The default action in such cases is to print a warn-
        ing message and return 0. The ON_IOERROR procedure 
        can be used to establish a statement to be jumped to 
        in case of such errors.
        
Example

If A contains the integer value 6, it can be converted 
to floating-point and stored in the variable B by enter-
ing:

B = FLOAT(A)

;-
;+
FLOOR

The FLOOR function returns the closest integer less 
than or equal to its argument. This value is returned as a 
longword integer with the same structure as the input 
argument..

Calling Sequence

        Result = FLOOR(X)
        
Arguments

    X
    
        The value for which the FLOOR function is to be 
        evaluated. This value can be of floating-point, dou-
        ble-precision floating-point, or complex type. FLOOR 
        returns a longword integer with the same structure 
        as X.
        
Example

To print the floor function of 5.9, enter:

PRINT, FLOOR(5.9)

IDL prints:

5



;-
;+
FLTARR

The FLTARR function returns a single-precision, 
floating-point vector or array.

Calling Sequence

        Result = FLTARR(D1, ..., Dn)
        
Arguments

    Di
    
        The dimensions of the result. The dimension 
        parameters can be any scalar expression. Up to eight 
        dimensions can be specified.
        
Keywords

    NOZERO
    
        Normally, FLTARR sets every element of the 
        result to zero. Set this keyword to inhibit zeroing 
        of the array elements and cause FLTARR to execute 
        faster.
        
Example

Create F, a 3-element by 3-element floating-point 
array with each element set to 0.0 by entering:

F = FLTARR(3, 3)

;-
;+
FLUSH

The FLUSH procedure causes all buffered output on the 
specified file units to be written. IDL uses buffered out-
put for reasons of efficiency. This buffering leads to 
rare occasions where a program needs to be certain that 
output data are not waiting in a buffer, but have actually 
been output.

Calling Sequence

        FLUSH, Unit1, ..., Unitn
        
Arguments

    Uniti
    
        The file units (logical unit numbers) to flush.
        
;-
;+
FREE_LUN

The FREE_LUN procedure deallocates previously-allo-
cated file units. This routine is usually used with file 
units allocated with GET_LUN, but it will also close any 
other specified file unit. If the specified file units are 
open, they are closed prior to the deallocation.

Calling Sequence

        FREE_LUN, Unit1, ..., Unitn
        
Arguments

    Uniti
    
        The IDL file units (logical unit numbers) to 
        deallocate.
        
Example

See the example for the GET_LUN procedure.

;-
;+
FSTAT

The FSTAT function returns a structure expression of 
type FSTAT containing status information about a speci-
fied file unit. The contents of this structure are docu-
mented in Chapter 17 of the IDL User's Guide on page 17-
40.

Calling Sequence

        Result = FSTAT(Unit)
        
Arguments

    Unit
    
        The file unit about which information is 
        required. This parameter can be an integer or an 
        associated variable, in which case information about 
        the variable's associated file is returned.
        
Fields of the FSTAT Structure

The following descriptions are of fields in the struc-
ture returned by the FSTAT function. They are not keywords 
to FSTAT.

    UNIT
    
        The IDL logical unit number (LUN).
        
    NAME
    
        The name of the file.
        
    OPEN
    
        Nonzero if the file unit is open. If OPEN is 
        zero, the remaining fields in FSTAT will not contain 
        useful information.
        
    ISATTY
    
        Nonzero if the file is actually a terminal 
        instead of a normal file.
        
    READ
    
        Nonzero if the file is open for read access.
        
    WRITE
    
        Nonzero if the file is open for write access.
        
    TRANSFER_COUNT
    
        The number of scalar IDL data items transferred 
        in the last input/output operation on the unit. This 
        is set by the following IDL routines: READU, WRITEU, 
        PRINT, PRINTF, READ, and READF. TRANSFER_COUNT is 
        useful when attempting to recover from input/output 
        errors.
        
    CUR_PTR
    
        The current position of the file pointer, given 
        in bytes from the start of the file. If the device 
        is a terminal (ISATTY is nonzero), the value of 
        CUR_PTR will not contain useful information.
        
    SIZE
    
        The current length of the file in bytes. If the 
        device is a terminal (ISATTY is nonzero), the value 
        of SIZE will not contain useful information.
        
    REC_LEN
    
        If the file is record-oriented (VMS), this field 
        contains the record length; otherwise, it is zero.
        
Examples

If file unit number 1 is open, the FSTAT information 
on that unit can be seen by entering:

PRINT, FSTAT(1)

Specific information can be obtained by referring to 
single fields within the structure returned by FSTAT. The 
following code prints the name and length of the file open 
on unit 1:

A = FSTAT(1)	Put FSTAT information in variable A.

PRINT, 'File: ', A.NAME, ' is ', A.SIZE, ' bytes long.'
Print the name and size fields.

;-
;+
GAMMA

The GAMMA function returns the gamma function of X. 
The domain of the function is 0 < X < 34.5. See the IDL 
Reference Guide for the definition of the gamma function.

If X is double-precision, the result is double-preci-
sion, otherwise the argument is converted to floating-
point and the result is floating-point.

Use the LNGAMMA function to obtain the natural loga-
rithm of the gamma function when there is a possibility of 
overflow.

Calling Sequence

        Result = GAMMA(X)
        
Arguments

    X
    
        The expression for which the gamma function will 
        be evaluated.
        
Example

Plot the gamma function over the range 0.01 to 1.0 
with a step size of 100 by entering:

X = FINDGEN(99)/100. + 0.01

PLOT, X, GAMMA(X)

;-
;+
GAUSSINT

The GAUSSINT function evaluates the integral of the 
Gaussian probability function and returns the result. See 
the IDL Reference Guide for the definition of the Gaussian 
integral.

If X is double-precision, the result is double-preci-
sion, otherwise the argument is converted to floating-
point and the result is floating-point. The result has the 
same structure as the input argument, X.

Calling Sequence

        Result = GAUSSINT(X)
        
Arguments

    X
    
        The expression for which the Gaussian integral 
        is to be evaluated.
        
Example

Plot the Gaussian probability function over the range 
-5 to 5 with a step size of 0.1by entering:

X = FINDGEN(101)/10. - 5.

PLOT, X, GAUSSINT(X)

;-
;+
GET_KBRD

The GET_KBRD function returns the next character 
available from the standard input (IDL file unit 0) as a 
one-character string.

Calling Sequence

        Result = GET_KBRD(Wait)
        
Arguments

    Wait
    
        If Wait is zero, GET_KBRD returns the null 
        string if there are no characters in the terminal 
        type-ahead buffer. If it is nonzero, the function 
        waits for a character to be typed before returning.
        
Examples

To wait for keyboard input and store one character in 
the variable R, enter:

R = GET_KBRD(1)

Press any key to return to the IDL prompt. To see the 
character that was typed, enter:

PRINT, R

The following code fragment reads one character at a 
time and echoes that character's numeric code. It quits 
when a "q" is entered:

REPEAT BEGIN

  A = GET_KBRD(1)

  PRINT, BYTE(A)

ENDREP UNTIL A EQ 'q'

;-
;+
GET_LUN

The GET_LUN procedure allocates a file unit from a 
pool of free units. Instead of writing routines to assume 
the use of certain file units, IDL functions and proce-
dures should use GET_LUN to reserve unit numbers in order 
to avoid conflicts with other routines. Use FREE_LUN to 
free the file units when finished.

Calling Sequence

        GET_LUN, Unit
        
Arguments

    Unit
    
        The named variable into which GET_LUN should 
        place the file unit number. Unit is converted into a 
        longword integer in the process. The file unit num-
        ber obtained is in the range 100 to 128.
        
Example

Instead of explicitly specifying a file unit number 
that may already be used, use GET_LUN to obtain a free one 
and store the result in the variable U by entering:

GET_LUN, U

Now U can be used in opening a file, for Example

OPENR, U, 'file.dat'

Once the data from "file.dat" has been read, the file 
can be closed and the file unit can be freed with the com-
mand:

FREE_LUN, U

Note also that OPENR has a GET_LUN keyword that allows 
you to simultaneously obtain a free file unit and open a 
file. The following command performs the same tasks as the 
first two commands above:

OPENR, U, 'file.dat', /GET_LUN

;-
;+
GET_SYMBOL (VMS Only)

The GET_SYMBOL function returns the value of a VMS DCL 
(Digital Command Language) interpreter symbol as a scalar 
string. If the symbol is undefined, the null string is 
returned.

Calling Sequence

        Result = GET_SYMBOL(Name)
        
Arguments

    Name
    
        A scalar string containing the name of the sym-
        bol to be translated.
        
Keywords

    TYPE
    
        The table from which Name is translated. Set 
        TYPE to 1 to specify the local symbol table. A value 
        of 2 specifies the global symbol table. The default 
        is to search the local table.
        
;-
;+
GETENV

The GETENV function returns the equivalence string 
for Name from the environment of the IDL process. If Name 
does not exist in the environment, a null string is 
returned.

Calling Sequence

        Result = GETENV(Name)
        
Arguments

    Name
    
        The scalar string for which an equivalence 
        string from the environment is desired.
        
Environment Variables Under VMS

VMS does not directly support the concept of environ-
ment variables. Instead, it is emulated (by using the 
standard C getenv() function) as described below, 
enabling you to use GETENV portably between Unix and VMS:

    If Name is one of HOME, TERM, PATH, or USER, an 
    appropriate response is generated. This mimics the 
    most common Unix environment variables.
    
    An attempt is made to translate Name as a logi-
    cal name. All four logical name tables are searched 
    in the standard order.
    
    An attempt is made to translate Name as a com-
    mand-language interpreter symbol.
    
Example

To print the name of the current Unix shell, enter the 
command:

PRINT, 'The current shell is: ', GETENV('SHELL')

;-
;+
GRID3

The GRID3 function fits a smooth function to a set of 
3D scattered nodes (xi, yi, zi) with associated data val-
ues (fi). The function can be sampled over a set of user-
specified points, or over an arbitrary 3D grid which can 
then be viewed using the SLICER procedure.

GRID3 uses the method described in Renka, R. J., "Mul-
tivariate Interpolation of Large Sets of Scattered Data," 
ACM Transactions on Mathematical Software, Vol. 14, No. 2, 
June 1988, Pages 139-148, which has been referred to as 
the Modified Shepard's Method. The function described by 
this method has the advantages of being equal to the val-
ues of fi, at each (xi, yi, zi), and being smooth (having 
continuous first partial derivatives).

A regularly-sampled volume enclosing the original 
data points with dimensions of (25, 25, 25) is produced if 
no optional or keyword parameters are supplied.

Calling Sequence

        Result = GRID3(X, Y, Z, F, Gx, Gy, Gz)
        
Arguments

    X, Y, Z and F
    
        Arrays containing the locations of the data 
        points, and the value of the variable to be interpo-
        lated at that point. X, Y, Z, and F must have the 
        same number of elements (with a minimum of 10 ele-
        ments per array) and are converted to floating-point 
        if necessary.
        
    Gx, Gy, and Gz
    
        Optional arrays containing the locations within 
        the volume to be sampled (if the GRID keyword is not 
        set), or the locations along each axis of the sam-
        pling grid (if the GRID keyword is set). If these 
        parameters are supplied, the keywords DELTA, NGRID, 
        and START are ignored.
        
        If the keyword GRID is not set, the result has 
        the same number of elements as Gx, Gy, and Gz. The 
        ith element of the result contains the value of the 
        interpolate at (Gxi, Gyi, Gzi). The result has the 
        same dimensions as Gx.
        
        If the GRID keyword is set, the result of GRID3 
        is a three-dimensional, single-precision, floating-
        point array with dimensions of (Nx, Ny, Nz), where 
        Nx, Ny, and Nz are the number of elements in Gx, Gy, 
        and Gz, respectively.
        
Keywords

    DELTA
    
        Set this keyword to a three-element vector or a 
        scalar that specifies the grid spacing in the X, Y, 
        and Z dimensions. The default spacing produces NGRID 
        samples within the range of each axis.
        
    GRID
    
        This keyword specifies the interpretation of Gx, 
        Gy, and Gz. The default value for GRID is zero if Gx, 
        Gy, and Gz are supplied, otherwise a regularly-grid-
        ded volume is produced.
        
    NGRID
    
        The number of samples along each axis. NGRID can 
        be set to a scalar, in which case each axis has the 
        same number of samples, or to a three-element array 
        containing the number of samples for each axis. The 
        default value for NGRID is 25.
        
    START
    
        A three-element array that specifies the start-
        ing value for each grid. The default value for START 
        is the minimum value in the respective X, Y, and Z 
        array.
        
Examples

Produce a set random points within the (0,1) unit cube 
and simulate a function: 

N = 300	Number of irregular samples.

X = RANDOMU(SEED, N)	Generate random values.

Y = RANDOMU(SEED, N)

Z = RANDOMU(SEED, N)

F = (X-.5)^2 + (Y-.5)^2 + Z	The function to simulate.

Return a cube with 25 equal-interval samples along 
each axis:

Result = GRID3(X, Y, Z, F)

Return a cube with 11 elements along each dimension, 
which samples each axis at (0, 0.1, ..., 1.0):

Result = GRID3(X, Y, Z, F, START=[0., 0., 0], $

               DELTA=0.1, NGRID=10)

The same result is produced by the statements:

S = FINDGEN(11) / 10.	Create sample values

Result = GRID3(X, Y, Z, F, S, S, S, /GRID)

Return the value of the interpolating function at the 
eleven points (0,0,0), (.1, .1, .1), ..., (1., 1., 1.):

S = FINDGEN(11) / 10.	Create sample values

Result = GRID3(X, Y, Z, F, S, S, S) 	

;-
;+
HANDLE_CREATE

The HANDLE_CREATE function creates a new handle. A 
"handle" is a dynamically-allocated variable that is 
identified by a unique integer value known as a "handle 
ID". Handles can have a value, of any IDL data type and 
organization, associated with them.This function returns 
the handle ID of the newly-created handle.

Handle Terminology

The following terms are used to describe handles in 
the documentation for this function and other handle-
related routines:

    Handle ID: The unique integer identifier associ-
    ated with a handle.
    
    Handle value: Data of any IDL type and organiza-
    tion associated with a handle.
    
    Top-level handle: A handle at the top of a han-
    dle hierarchy. A top-level handle can have children, 
    but does not have a parent.
    
    Parents, children, and siblings: These terms 
    describe the relationship between handles in a han-
    dle hierarchy. When a new handle is created, it can 
    be the start of a new handle hierarchy (a top-level 
    handle) or it can belong to the level of a widget 
    hierarchy below an existing handle. A handle created 
    in this way is said to be a child of the specified 
    parent. Parents can have any number of children. All 
    handles that share the same parent are said to be 
    siblings.
    
Calling Sequence

        Result = HANDLE_CREATE([ID])
        
Arguments

    ID
    
        If this argument is present, it specifies the 
        handle ID relative to which the new handle is cre-
        ated. Normally, the new handle becomes the last 
        child of the parent handle specified by ID. However, 
        this behavior can be changed by setting the 
        FIRST_CHILD or SIBLING keywords.
        
        Omit this argument to create a new top-level 
        handle without a parent.
        
Keywords

    FIRST_CHILD
    
        Set this keyword to create the new handle as the 
        first child of the handle specified by ID. Any 
        existing children of ID become later siblings of the 
        new first child (i.e., the existing first child 
        becomes the second child, the second child becomes 
        the third child, etc.).
        
    NO_COPY
    
        Usually, when the VALUE keyword is used, the 
        source variable memory is copied to the handle 
        value. If the NO_COPY keyword is set, the value data 
        is taken away from the source variable and attached 
        directly to the destination. This feature can be 
        used to move data very efficiently. However, it has 
        the side effect of causing the source variable to 
        become undefined.
        
    SIBLING
    
        Set this keyword to create the new handle as the 
        sibling handle immediately following ID. Any other 
        siblings currently following ID become later sib-
        lings of the new handle.
        
    VALUE
    
        The value to be assigned to the handle.
        
        Every handle can contain a user-specified value 
        of any data type and organization. This value is not 
        used by the handle in any way, but exists entirely 
        for the convenience of the IDL programmer. Use this 
        keyword to set the handle value when the handle is 
        first created.
        
        If the VALUE keyword is not specified, the han-
        dle's initial value is undefined.
        
        Handle values can be retrieved using the 
        HANDLE_VALUE procedure.
        
Examples

The following commands create a top-level handle with 
3 child handles. Each handle is assigned a different 
string value:

top = HANDLE_CREATE()	Create top-level handle without an initial 
handle value.

first = HANDLE_CREATE(top, VALUE='First child')
Create first child of the top-level handle.

second = HANDLE_CREATE(top, VALUE='Second child')
Create second child of the top-level handle.

third = HANDLE_CREATE(first, VALUE='Another child', /SIB-
LING)
Create a new sibling between first and 
second. This handle is also a child of the 
top-level handle.

;-
;+
HANDLE_FREE

The HANDLE_FREE procedure frees an existing handle, 
along with any dynamic memory currently being used by its 
value. Any child handles associated with ID are also 
freed.

Calling Sequence

        HANDLE_FREE, ID
        
Arguments

    ID
    
        The ID of the handle to be freed. Once the han-
        dle is freed, further use of it is invalid and 
        causes an error to be issued.
        
Examples

To free all memory associated with the top-level han-
dle top, and all its children, use the command:

HANDLE_FREE, top

;-
;+
HANDLE_INFO

The HANDLE_INFO function returns information about 
handle validity and connectivity. By default, it returns 
True if the specified handle ID is valid. Keywords can be 
set to return other types of information.

Calling Sequence

        Result = HANDLE_INFO(ID)
        
Arguments

    ID
    
        The ID of the handle for which information is 
        desired. This argument can be scalar or array an 
        array of IDs. The result of HANDLE_INFO has the same 
        structure as ID, and each element gives the desired 
        information for the corresponding element of ID.
        
Keywords

    FIRST_CHILD
    
        Set this keyword to return the handle ID of the 
        first child of the specified handle. If the handle 
        has no children, 0 is returned.
        
    NUM_CHILDREN
    
        Set this keyword to return the number of chil-
        dren related to ID.
        
    PARENT
    
        Set this keyword to return the handle ID of the 
        parent of the specified handle. If the specified 
        handle is a top-level handle (i.e., it has no par-
        ent), 0 is returned.
        
    SIBLING
    
        Set this keyword to return the handle ID of the 
        sibling handle following ID. If ID has no later sib-
        lings, 0 is returned.
        
    VALID_ID
    
        Set this keyword to return 1 if ID represents a 
        currently valid handle. Otherwise, zero is returned. 
        This is the default action for HANDLE_INFO if no 
        other keywords are specified.
        
Examples

The following commands demonstrate a number of dif-
ferent uses of HANDLE_INFO:

IF HANDLE_INFO(handle1) THEN PRINT, 'Valid handle.'
Print a message if handle1 is a valid han-
dle ID.

handle = HANDLE_INFO(top, /FIRST_CHILD)
Retrieve the handle ID of the first child of 
top.

next= HANDLE_INFO(handle1, /SIBLING)
Retrieve the handle ID of the next sibling of 
handle1.

;-
;+
HANDLE_MOVE

The HANDLE_MOVE procedure moves a handle (specified 
by Move_ID) to a new location. This new position is spec-
ified relative to Static_ID. 

Calling Sequence

        HANDLE_MOVE, Static_ID, Move_ID
        
Arguments

    Static_ID
    
        The handle ID relative to which the handle spec-
        ified by Move_ID is moved. By default, Move_ID 
        becomes the last child of Static_ID. This behavior 
        can be changed by specifying one of the keywords 
        described below.
        
        If Static_ID is set to 0, Move_ID becomes a top 
        level handle without any parent.
        
    Move_ID
    
        The ID of the handle to be moved.
        
Keywords

    FIRST_CHILD
    
        Set this keyword to make Move_ID the first child 
        of Static_ID. Any existing children of Static_ID 
        become later siblings of the new first child (i.e., 
        the existing first child becomes the second child, 
        the second child becomes the third child, etc.).
        
    SIBLING
    
        Set this keyword to make Move_ID the sibling 
        handle immediately following Static_ID. Any siblings 
        currently following Static_ID become later siblings 
        of the new handle.
        
Example

top = HANDLE_CREATE()	Create top-level handle.

child1 = HANDLE_CREATE(top)	Create first child of top.

child2 = HANDLE_CREATE(top)	Create second child of top.

HANDLE_MOVE, top, child1	Move the first child to be the last child of top.

;-
;+
HANDLE_VALUE

The HANDLE_VALUE procedure returns or sets the value 
of an existing handle.

Calling Sequence

        HANDLE_VALUE, ID, Value
        
Arguments

    ID
    
        A valid handle ID.
        
    Value
    
        When using HANDLE_VALUE to return an existing 
        handle value (the default), Value is a named vari-
        able in which the value is returned.
        
        When using HANDLE_VALUE to set a handle value, 
        Value is the new value. Note that handle values can 
        have any IDL data type and organization.
        
Keywords

    NO_COPY
    
        By default, HANDLE_VALUE works by making a sec-
        ond copy of the source data. Although this technique 
        is fine for small data, it can have a significant 
        memory cost when the data being copied is large.
        
        If the NO_COPY keyword is set, HANDLE_VALUE 
        works differently. Rather than copy the source data, 
        it takes the data away from the source and attaches 
        it directly to the destination. This feature can be 
        used to move data very efficiently. However, it has 
        the side effect of causing the source variable to 
        become undefined. On a retrieve operation, the han-
        dle value becomes undefined. On a set operation, the 
        variable passed as Value becomes undefined.
        
    SET
    
        Set this keyword to assign Value as the new han-
        dle value. The default is to retrieve the current 
        handle value.
        
Examples

The following commands demonstrate the two different 
uses of HANDLE_VALUE:

HANDLE_VALUE, handle1, current	Retrieve the value of handle1 into the 
variable current.

HANDLE_VALUE, handle1, [2,3,5]	Set the value of handle1 to a 3-element 
integer vector.

;-
;+
HELP

The HELP procedure gives the user information on many 
aspects of the current IDL session. The specific area for 
which help is desired is selected by specifying the appro-
priate keyword. If no arguments or keywords are specified, 
the default is to show the current nesting of procedures 
and functions, all current variables at the current pro-
gram level, and open files. Only one keyword can be spec-
ified at a time.

Calling Sequence

        HELP, Expression1, ..., Expressionn
        
Arguments

    Expressioni
    
        The arguments are interpreted differently 
        depending on the keyword selected. If no keyword is 
        selected, HELP displays basic information for its 
        parameters. For example, to see the type and struc-
        ture of the variable A, enter:
        
        HELP, A
        
Keywords

        Note that the use of some of the following key-
        words causes any arguments to HELP to be ignored and 
        HELP provides other types of information instead. If 
        the description of the keyword does not explicitly 
        mention the arguments, the arguments are ignored.
        
    ALL_KEYS
    
        Set this keyword to show current function-key 
        definitions as set by DEFINE_KEY. If no arguments 
        are supplied, information on all function keys is 
        displayed. If arguments are provided, they must be 
        scalar strings containing the names of function 
        keys, and information on the specified keys is 
        given.
        
    BREAKPOINTS
    
        Set this keyword to display the breakpoint table 
        which shows the program module and location for each 
        breakpoint.
        
    CALLS
    
        Set this keyword to a named variable in which to 
        store the procedure call stack. Each string element 
        contains the name of the program module, source file 
        name, and line number. Array element zero contains 
        the information about the caller of HELP, element 
        one contains information about its caller, etc. This 
        keyword is useful for programs that require trace-
        back information.
        
    DEVICE
    
        Set this keyword to show information about the 
        currently selected graphics device.
        
    FILES
    
        Set this keyword to display information about 
        file units. If no arguments are supplied in the call 
        to HELP, information on all open file units (except 
        the special units 0, -1, and -2) is displayed. If 
        arguments are provided, they are taken to be integer 
        file unit numbers, and information on the specified 
        file units is given.
        
    KEYS
    
        Set this keyword to show current function key 
        definitions as set by DEFINE_ KEY, for those func-
        tion keys that are currently programmed to perform a 
        function. Under Unix, this keyword is different from 
        ALL_KEYS because that keyword displays every key, no 
        matter what its current programming. Under VMS, the 
        two keywords mean the same thing. If no arguments 
        are supplied, information on all function keys is 
        displayed. If arguments are provided, they must be 
        scalar strings containing the names of function 
        keys, and information on the specified keys is 
        given.
        
    MEMORY
    
        Set this keyword to see a report on the amount 
        of dynamic memory currently in use by the IDL ses-
        sion, and the number of times dynamic memory has 
        been allocated and deallocated.
        
    NAMES
    
        A string of the names of variables whose values 
        are to be printed. This string, which must be 
        enclosed in quotes, can contain the standard wild-
        card matching characters, "*" and "?". For example, 
        to print only the values of variables beginning with 
        "A", use the command HELP, NAME='a*'. Similarly, 
        HELP, NAME='?', prints the values of all variables 
        with a single-character name.
        
    RECALL_COMMANDS
    
        Set this keyword to display the saved commands 
        in the command input buffer.
        
    ROUTINES
    
        Set this keyword to show a list of all compiled 
        procedures and functions with their parameter names. 
        Keyword parameters accepted by each module are shown 
        enclosed in quotation marks.
        
    STRUCTURES
    
        Set this keyword to display information on 
        structure-type variables. If no arguments are pro-
        vided, all currently-defined structures are shown. 
        If arguments are provided, the structure definition 
        for those expressions is displayed.
        
    SYSTEM_VARIABLES
    
        Set this keyword to display information on all 
        system variables. Arguments are ignored.
        
    TRACEBACK
    
        Set this keyword to display the current nesting 
        of procedures and functions.
        
Example

To see general information on the current IDL session, 
enter:

HELP

To see information on the structure definition of the 
system variable !D, enter:

HELP, !D, /STRUCTURES

;-
;+
HISTOGRAM

The HISTOGRAM function returns a longword vector 
equal to the density function of Array. In the simplest 
case, the density function, at subscript i, is the number 
of Array elements in the argument with a value of i. See 
the IDL Reference Guide for the definition of the histo-
gram function.

Warning: There may not always be enough virtual memory 
available to find the density functions of arrays that 
contain a large number of bins.

For bivariate probability distributions, use the 
HIST_2D function in the IDL Users' Library (enter ? at the 
IDL prompt for online help).

HISTOGRAM can optionally return an array containing a 
list of the original array subscripts that contributed to 
each histogram bin. This list, commonly called the reverse 
(or backwards) index list, efficiently determines which 
array elements are accumulated in a set of histogram bins. 
A typical application of the reverse index list is reverse 
histogram or scatter plot interrogation-a histogram bin 
or 2D scatter plot location is marked with the cursor and 
the original data items within that bin are highlighted.

Calling Sequence

        Result = HISTOGRAM(Array)
        
Arguments

    Array
    
        The vector or array for which the density func-
        tion is to be computed.
        
Keywords

    BINSIZE
    
        The size of the bin to use. If this keyword is 
        not specified, a bin size of 1 is used.
        
    INPUT
    
        Set this keyword to a named variable that con-
        tains an array to be added to the output of HISTO-
        GRAM. The density function of Array is added to the 
        existing contents of INPUT and returned as the 
        result. The array is converted to longword type if 
        necessary and must have at least as many elements as 
        are required to form the histogram.
        
        Multiple histograms can be efficiently accumu-
        lated by specifying partial sums via this keyword.
        
    MAX
    
        MAX is the maximum value to consider. If this 
        keyword is not specified, Array is searched for its 
        largest value.
        
    MIN
    
        MIN is the minimum value to consider. If this 
        keyword is not specified, and Array is of type byte, 
        0 is used. If this keyword is not specified and 
        Array is not of byte type, Array is searched for its 
        smallest value.
        
    OMAX
    
        A named variable that, upon exit, contains the 
        maximum data value used in constructing the histo-
        gram.
        
    OMIN
    
        A named variable that, upon exit, contains the 
        minimum data value used in constructing the histo-
        gram.
        
    REVERSE_INDICES
    
        Set this keyword to a named variable in which 
        the list of reverse indices is returned. This list 
        is returned as a longword vector whose number of 
        elements is the sum of the number of elements in the 
        histogram, N, and the number of array elements 
        included in the histogram.
        
        The subscripts of the original array elements 
        falling in the ith bin, 0 LE i LT N, are given by the 
        expression: R(R(i) : R(i+1)-1), where R is the 
        reverse index list. If R(i) is equal to R(i+1), no 
        elements are present in the ith bin.
        
        For example, make a take the histogram of array 
        A:
        
        H = HISTOGRAM(A, REVERSE_INDICES = R)
        
        Set all elements of A that are in the ith bin of 
        H to 0 with the command:
        
        IF R(i) NE R(i+1) THEN A(R(R(I) : R(i+1)-1)) = 0
        
        which is usually more efficient than the com-
        mands:
        
        bini = WHERE(A EQ i, count)
        
        IF count NE 0 THEN A(bini) = 0
        
Examples

Create a simple, two-dimensional dataset with the 
User Library DIST function by entering:

D = DIST(200)

Plot the histogram of D with a bin size of 1 and the 
default minimum and maximum by entering:

PLOT, HISTOGRAM(D)

To plot a histogram considering only those values from 
10 to 50 using a bin size of 4, enter:

PLOT, HISTOGRAM(D, MIN = 10, MAX = 50, BINSIZE = 4)

The HISTOGRAM function can also be used to increment 
the elements of one vector whose subscripts are contained 
in another vector. To increment those elements of vector A 
indicated by vector B, use the command:

A = HISTOGRAM(B, INPUT=A, MIN=0, MAX=N_ELEMENST(A)-1)

This method works for duplicate subscripts, whereas 
the statement:

A(B) = A(B)+1

adds never adds more than 1 to any element, even if 
that element is duplicated in vector B. For example, the 
following commands:

A = LONARR(5)

B = [2,2,3]

PRINT, HISTOGRAM(B, INPUT=A, MIN=0, MAX=4)

prints:

   0  0  2  1  0

while the commands:

A = LONARR(5)

A(B) = A(B)+1

PRINT, A

gives the result:

   0  0  1  1  0

;-
;+
IMAGINARY

The IMAGINARY function returns the imaginary part of 
its complex-valued argument as a single-precision, float-
ing-point value.

Calling Sequence

        Result = IMAGINARY(Complex_Expression)
        
Arguments

    Complex_Expression
    
        The complex-valued expression for which the 
        imaginary part is desired.
        
Example

Create an array of complex values by entering:

C = COMPLEX([1,2,3],[4,5,6])

Print just the imaginary parts of each element in C by 
entering:

PRINT, IMAGINARY(C)

IDL prints:

 4.00000 5.00000 6.00000

;-
;+
INDGEN

The INDGEN function returns an integer array with the 
specified dimensions. Each element of the array is set to 
the value of its one-dimensional subscript.

Calling Sequence

        Result = INDGEN(D1, ..., Dn)
        
Arguments

    Di
    
        The dimensions of the result. The dimension 
        parameters can be any scalar expression. Up to eight 
        dimensions can be specified.
        
Example

Create I, a 5-element vector of integer values with 
each element set to the value of its subscript by enter-
ing:

I = INDGEN(5)

;-
;+
INTARR

The INTARR function returns an integer vector or 
array.

Calling Sequence

        Result = INTARR(D1, ..., Dn)
        
Arguments

    Di
    
        The dimensions of the result. The dimension 
        parameters can be any scalar expression. Up to eight 
        dimensions can be specified.
        
Keywords

    NOZERO
    
        Normally, INTARR sets every element of the 
        result to zero. If NOZERO is nonzero, this zeroing 
        is not performed and INTARR executes faster.
        
Example

Create I, a 3-element by 3-element integer array with 
each element set to 0 by entering:

I = INTARR(3, 3)

;-
;+
INTERPOLATE

The INTERPOLATE function returns an array of linear, 
bilinear or trilinear interpolates, depending on the 
dimensions of the input array P. Linear interpolates are 
returned in the one-dimensional case, bilinear in the two-
dimensional case and trilinear interpolates in the three-
dimensional case. The returned array has the same type as 
P and its dimensions depend on those of the location 
parameters X, Y, and Z, as explained below.

Interpolates outside the bounds of P can be set to a 
user-specified value by using the MISSING keyword.

Calling Sequence

        Result = INTERPOLATE(P, X [, Y [, Z]])
        
Arguments

    P
    
        The array of data values. P must be a one-, two-
        , or three-dimensional array of numeric type.
        
    X, Y, Z
    
        Arrays of numeric type containing the locations 
        for which interpolates are desired. For linear 
        interpolation (P is a vector), the result has the 
        same dimensions as X. The i-th element of the result 
        is P interpolated at location Xi. The Y and Z param-
        eters should be omitted.
        
        For bilinear interpolation Z should not be 
        present.
        
        If the keyword GRID is not set, all location 
        arrays must have the same number of elements. See 
        the description of the GRID keyword below for more 
        details on how interpolates are computed from P and 
        these arrays.
        
Keywords

    CUBIC
    
        Set this keyword to use the cubic convolution 
        interpolation method.
        
        Cubic convolution is an interpolation method 
        that closely approximates the theoretically optimum 
        sinc interpolation function using cubic polynomials. 
        According to sampling theory, details of which are 
        beyond the scope of this document, if the original 
        signal, f, is a band-limited signal, with no fre-
        quency component larger than Omega_0, and f is sam-
        pled with spacing less than or equal to 1/
        (2*Omega_0), then f can be reconstructed by convolv-
        ing with a sinc function: sinc(x) = sin(pi * x) / 
        (pi * x).
        
        In the one-dimensional case, four neighboring 
        points are used, while in the two-dimensional case 
        16 points are used. Note that cubic convolution 
        interpolation is significantly slower than bilinear 
        interpolation.
        
        For further details see Rifman, S.S. and McKin-
        non, D.M., "Evaluation of Digital Correction Tech-
        niques for ERTS Images-Final Report", Report 20634-
        6003-TU-00, TRW Systems, Redondo Beach, CA, July 
        1974.
        
    GRID
    
        The GRID keyword controls how the location 
        arrays specify where interpolates are desired. This 
        keyword has no effect in the case of linear interpo-
        lation.
        
        If GRID is not set: The location arrays, X, Y, 
        and, if present, Z must have the same number of ele-
        ments. The result has the same structure and number 
        of elements as X.
        
        In the case of bilinear interpolation, the 
        result is obtained as follows: Let i = |Xi| and k = 
        |Yi|. Element i of the result is computed by inter-
        polating between P(l, k), P(l+1, k), P(l, k+1), and 
        P(l+1, k+1). to obtain the estimated value at (Xi, 
        Yi). Trilinear interpolation is a direct extension 
        of the above.
        
        If GRID is set: Let Nx be the number of elements 
        in X, let Ny be the number of elements in Y, and Nz 
        be the number of elements in Z. The result has 
        dimensions (Nx, Ny) for bilinear interpolation, and 
        (Nx, Ny, Nz) for trilinear interpolation. For bilin-
        ear interpolation, element (i,j) of the result con-
        tains the value of P interpolated at position (Xi, 
        Yi). For trilinear interpolation, element (i, j, k) 
        of the result is P interpolated at (Xi, Yi, Zi).
        
    MISSING
    
        The value to return for elements outside the 
        bounds of P. If this keyword is not specified, loca-
        tions less than zero or greater than the largest 
        corresponding subscript of P are set to the nearest 
        element of P.
        
Examples

The example below computes bilinear interpolates with 
the keyword GRID set:

p = FINDGEN(4,4)

PRINT, INTERPOLATE(p, [.5, 1.5, 2.5], [.5, 1.5, 2.5], /
GRID)

and prints the 3 by 3 array:

   2.50000   3.50000   4.50000

   6.50000   7.50000   8.50000

   10.5000   11.5000   12.5000

corresponding to the locations:

(.5,.5), (1.5, .5), (2.5, .5), 
(.5,1.5), (1.5, 1.5), (2.5, 1.5),
(.5,2.5), (1.5, 2.5), (2.5, 2.5)

Another example computes interpolates, with GRID not 
set and a parameter outside the bounds of P:

PRINT, INTERPOLATE(p, [.5, 1.5, 2.5, 3.1], [.5, 1.5, 2.5, 
2])

prints the result:

   2.50000   7.50000   12.5000   11.0000

corresponding to the locations (.5,.5), (1.5, 1.5), 
(2.5, 2.5) and (3.1, 2.0). Note that the last location is 
outside the bounds of P and is set from the value of the 
last column. The following command uses the MISSING key-
word to set such values to -1:

PRINT, INTERPOLATE(p, [.5, 1.5, 2.5, 3.1], [.5, 1.5, 2.5, 
2], $

       MISSING = -1)

and gives the result:

   2.50000   7.50000   12.5000   -1.00000

;-
;+
INVERT

The INVERT function returns an inverted copy of a 
square array. The Gaussian elimination method is used. 
Errors from singular or near-singular matrices are accu-
mulated in the optional Status.

Note that unlike most IDL functions, INVERT requires 
input in column-major (matrix) format rather than row-
major (array) format.

Calling Sequence

        Result = INVERT(Matrix [, Status])
        
Arguments

    Matrix
    
        The matrix to be inverted. Matrix must have two 
        dimensions of equal size (i.e., a square matrix) and 
        can be of any type except string. If Matrix is dou-
        ble-precision floating-point, the result is also 
        double-precision. All other types yield a single-
        precision, floating-point result.
        
    Status
    
        A named variable to receive the status of the 
        operation. Possible status values are: 0 for suc-
        cessful completion, 1 for a singular matrix (which 
        indicates that the inversion is invalid), and 2 
        which is a warning that a small pivot element was 
        used and that significant accuracy was probably 
        lost.
        
Example

Begin with a matrix A. Note that A is entered in col-
umn-major format rather than the usual row-major format.

a = [[5.0, -1.0, 3.0], $

     [2.0, 0.0, 1.0], $

     [3.0, 2.0, 1.0]]

inv = INVERT(a)	Store the inverse of A in the named variable 
INV.

print, inv	Print the inverted matrix.

IDL prints:

 -2.00000  7.00000 -1.00000

  1.00000 -4.00000  1.00000

  4.00000 -13.0000  2.00000



You can check the accuracy of the inverse using the 
following relationship:

A A^-1 = I or A^-1 A = I

where I is a matrix with 1s on the main diagonal and 
zeros elsewhere.

print, inv # a

IDL prints:

 1.00000  0.00000  0.00000

 0.00000  1.00000  0.00000

 0.00000  0.00000  1.00000

;-
;+
IOCTL

The IOCTL function provides a thin wrapper over the 
Unix ioctl(2) system call. IOTCL performs special func-
tions on the specified file. The set of functions actually 
available depends on your version of Unix and the type of 
file (tty, tape, disk file, etc.) referred to.

To use IOCTL, read the C programmer's documentation 
describing the ioctl(2) function for the desired device 
and convert all constants and data to their IDL equiva-
lents.

The value returned by the system ioctl function is 
returned as the value of the IDL IOCTL function.

Calling Sequence

        Result = IOCTL(File_Unit [, Request, Arg])
        
Arguments

    File_Unit
    
        The IDL logical file unit (LUN) for the open 
        file on which the ioctl request is made.
        
    Request
    
        A longword integer that specifies the ioctl 
        request code. These codes are usually contained in C 
        language header files provided by the operating sys-
        tem, and are not generally portable between Unix 
        versions. If one of the "MT" keywords is used, this 
        argument can be omitted.
        
    Arg
    
        A named variable through which data if passed to 
        and from ioctl. IOCTL requests usually request data 
        from the system or supply the system with informa-
        tion. The user must make Arg the correct type and 
        size. Errors in typing or sizing Arg can corrupt the 
        IDL address space and/or make IDL crash. If one of 
        the MT keywords is used, this argument can be omit-
        ted.
        
Keywords

Note that the keyword below that start with "MT" can 
be used to issue commonly used magnetic tape ioctl() 
calls. When these keywords are used, the Request and Arg 
arguments are ignored and an be omitted. Magnetic tape 
operations not available via these keywords can still be 
executed by supplying the appropriate Request and Arg val-
ues. When issuing magnetic tape IOCTL calls, be aware that 
different devices have different rules for which ioctl 
calls are allowed, and when. The documentation for your 
computer system explains those rules.

    BY_VALUE
    
        If this keyword is set, Arg is converted to a 
        scalar longword and this longword is passed by 
        value. Normally, Arg is passed to ioctl by reference 
        (i.e., by address).
        
    MT_OFFLINE
    
        Set this keyword to rewind and unload a tape.
        
    MT_REWIND
    
        Set this keyword to rewind a tape.
        
    MT_SKIP_FILE
    
        Use this keyword to skip files on a tape. A pos-
        itive value skips forward that number of files. A 
        negative value skips backward.
        
    MT_SKIP_RECORD
    
        Use this keyword to skip records on tape. A pos-
        itive value skips forward that number of files. A 
        negative value skips backward.
        
    MT_WEOF
    
        Set this keyword to write an end of file ("tape 
        mark") on the tape at the current location.
        
    SUPPRESS_ERROR
    
        Set this keyword to log errors quietly and cause 
        a value of -1 to be returned. The default is for IDL 
        to notice any failures associated with the use of 
        ioctl and issue the appropriate IDL error and halt 
        execution.
        
Example

The following example prints the size of the terminal 
being used by the current IDL session. It is known to work 
under SunOS 4.1.2. Changes may be necessary for other 
operating systems or even other versions of SunOS.

winsize = { row:0, col:0, xpixel:0, ypixel:0 }
Variable to receive result. This structure is 
described in Section 4 of the SunOS manual 
pages under termios(4).

TIOCGWINSZ = 1074295912L	The request code for obtaining the tty size, as 
determined by reading the termios(4) docu-
mentation, and reading the system include 
files in the /usr/include/sys directory.

ret = ioctl(-1, TIOCGWINSZ, winsize)
Make the information request. -1 is the IDL 
logical file unit for the standard output.

print,winsize.row, winsize.col, $

      format='("TTY has ", I0," rows and ", I0," col-
umns.")'
Output the results.

The following points should be noted in this example:

    Even though we only want the number of rows and 
    columns, we must include all the fields required by 
    the TIOCGWINSIZ ioctl in the winsize variable (as 
    documented in the termio(4) manual page). Not pro-
    viding a large enough result buffer would cause 
    IDL's memory to be corrupted.
    
    The value of TIOCGWINSZ was determined by exam-
    ining the system header files provided in the /usr/
    include/sys directory. Such values are not always 
    portable between major operating system releases.
    
;-
;+
ISHFT

The ISHFT function performs the bit shift operation on 
bytes, integers and longwords. If P2 is positive, P1 is 
left shifted P2 bit positions with 0 bits filling vacated 
positions. If P2 is negative, P1 is right shifted with 0 
bits filling vacated positions.

Calling Sequence

        Result = ISHFT(P1, P2)
        
Arguments

    P1
    
        The scalar or array to be shifted.
        
    P2
    
        The scalar or array containing the number of bit 
        positions and direction of the shift.
        
Example

Bit shift each element of the integer array [1, 2, 3, 
4, 5] three bits to the left and store the result in B by 
entering:

B = ISHFT([1,2,3,4,5], 3)

The resulting array B is [8, 16, 24, 32, 40].

;-
;+
JOURNAL

The JOURNAL procedure provides a record of an interac-
tive session by saving, in a file, all text entered from 
the terminal in response to the IDL prompt. The first call 
to JOURNAL starts the logging process. The read-only sys-
tem variable !JOURNAL is set to the file unit used. To 
stop saving commands and close the file, call JOURNAL with 
no parameters. If logging is in effect and JOURNAL is 
called with a parameter, the parameter is simply written 
to the journal file.

Calling Sequence

        JOURNAL [, Arg]
        
Arguments

    Arg
    
        A string containing the name of the journal file 
        to be opened or text to be written to an open jour-
        nal file. If Arg is not supplied, and a journal file 
        is not already open, the file idlsave.pro is used. 
        Once journaling is enabled, a call to JOURNAL with 
        Arg supplied causes Arg to be written into the jour-
        nal file. Calling JOURNAL without Arg while journal-
        ing is in progress closes the journal file and ends 
        the logging process.
        
Example

To begin journaling to the file myjournal.pro, enter:

JOURNAL, 'myjournal.pro'

Any commands entered at the IDL prompt are recorded in 
the file until IDL is exited or the JOURNAL command is 
entered without an argument.

;-
;+
KEYWORD_SET

The KEYWORD_SET function returns a nonzero value if 
Expression is defined and nonzero or an array, otherwise 
zero is returned. This function is especially useful in 
user-written procedures and functions that process key-
words that are interpreted as being either true (keyword 
is present and nonzero) or false (keyword was not used, or 
was set to zero).

Calling Sequence

        Result = KEYWORD_SET(Expression)
        
Arguments

    Expression
    
        The expression to be tested. Expression is usu-
        ally a named variable.
        
Example

Suppose that you are writing an IDL procedure that has 
the following procedure definition line:

PRO myproc, KEYW1 = keyw1, KEYW2 = keyw2

The following command could be used to execute a set 
of commands only if the keyword KEYW1 is set (i.e., it is 
present and nonzero):

IF KEYWORD_SET(keyw1) THEN BEGIN

The commands to be executed only if KEYW1 is set would 
follow.

;-
;+
LABEL_REGION

The LABEL_REGION function consecutively labels all of 
the regions, or blobs, of a bi-level image with a unique 
region index. This process is sometimes called "blob col-
oring". A region is a set of non-zero pixels, each of 
which are a horizontal or vertical neighbor of one or more 
pixels within the same region.

The argument for LABEL_REGION is a two-dimensional 
bi-level integer type array-only zero and non-zero values 
are considered. The result of the function is a two-dimen-
sional integer array of the same dimensions with each 
pixel containing its region index. A region index of zero 
indicates that the original pixel was zero and belongs to 
no region. Output values range from 0 to the number of 
regions.

Statistics on each of the regions may be easily calcu-
lated using the HISTOGRAM function as shown in the exam-
ples below. 

Calling Sequence

        Result = LABEL_REGION(Image)
        
Arguments

    Image
    
        The two-dimensional image to be labeled. Image 
        is converted to integer type if necessary. Pixels at 
        the edges of Image are considered to be zero.
        
Example

Count the number of distinct regions within an image, 
and their population:

b = LABEL_REGION(image)	Get blob indices.

h = HISTOGRAM(b)	Get population of each blob.

FOR i=0, N_ELEMENTS(h)-1 DO PRINT 'Region ',i, $

    ', Population = ', h(i)

Note that region 0 is the set of zero pixels that are 
not within a region.

As above, but also print the average value and stan-
dard deviation of each region:

b = LABEL_REGION(image)	Get blob indices.

h = HISTOGRAM(b, REVERSE_INDEX=r)	Get population and members of each 
blob.

FOR i=0, N_ELEMENTS(h)-1 DO BEGIN	Each region 

p = r(r(i):r(i+1)-1)	Find subscripts of members of region i.

q = image(p)	Pixels of region i 

PRINT 'Region ', i, $ 

', Population = ', h(i), $

', Standard Deviation = ', STDEV(q, mean), $

', Mean = ', mean 

ENDFOR

;-
;+
LINDGEN

The LINDGEN function returns a longword integer array 
with the specified dimensions. Each element of the array 
is set to the value of its one-dimensional subscript.

Calling Sequence

        Result = LINDGEN(D1, ..., Dn)
        
Arguments

    Di
    
        The dimensions of the result. The dimension 
        parameters can be any scalar expression. Up to eight 
        dimensions can be specified.
        
Example

To create L, a 10-element by 10-element longword array 
where each element is set to the value of its one-dimen-
sional subscript, enter:

L = LINDGEN(10, 10)

;-
;+
LINKIMAGE

LINKIMAGE merges routines written in other languages 
with IDL at run-time. Each call to LINKIMAGE defines a new 
system procedure or function by specifying the routine's 
name, the name of the file containing the code, and the 
entry point name. The name of your routine is added to 
IDL's internal system routine table, making it available 
in the same manner as any other IDL built-in routine. 
LINKIMAGE can also be used to add graphics device drivers.

Warning: This procedure is only available under VMS, 
Windows NT, and on Unix systems that support the dynamic 
loading of object modules. Its use requires intimate 
knowledge of the internals of IDL, and is not for use by 
the novice user. It should only be used if there is abso-
lutely no alternative. If dynamic linking is necessary, we 
recommend you examine the CALL_EXTERNAL function before 
committing to LINKIMAGE, as it has a much simpler inter-
face.

Under VMS, the LIB$FIND_IMAGE_SYMBOL run-time library 
routine is used to activate your sharable image and merge 
it into the IDL address space. To understand this process 
better, or in the event of problems, it is a good idea to 
read the description of LIB$FIND_IMAGE_SYMBOL in the VMS 
Run Time Library Reference Manual.

Under Unix, LINKIMAGE uses the interface to the 
dynamic linker: dlopen() for Sun, shl_load() for HP-UX, 
and load() for AIX.

Under Windows NT, LINKIMAGE uses LoadLibrary() to 
load a 32-bit DLL. Windows 3.1 does not support LINKIMAGE.

Note: Modules must be merged via LINKIMAGE before 
other procedures and functions that call them are com-
piled, or the compilation of those routines will fail.

Calling Sequence

        LINKIMAGE, Name, Image [, Type [, Entry]]
        
Arguments

    Name
    
        A string containing the IDL name of the func-
        tion, procedure or device routine which is to be 
        merged. When loading a device driver, Name contains 
        the name of the global ("universal" for VMS) 
        DEVICE_DEF structure in the driver. Upon successful 
        loading of the routine, a new procedure or function 
        with the given name will exist, or the new device 
        driver will be loaded.
        
    Image
    
        A string that holds the name of the file con-
        taining the code to be dynamically linked.
        
        Under VMS, the specified file must be a sharable 
        image, and this argument can contain only the file 
        name. The device/directory, and file type parts of 
        the specification are not included. If the sharable 
        image file is not in SYS$SHARE, a logical name that 
        translates to the full specification can be used, or 
        the DEFAULT keyword can be used to specify the addi-
        tional information.
        
        Under Unix this argument contains the full path 
        specification of the dynamically loaded object file. 
        See the Unix documentation on sharable libraries and 
        dynamic linking for details.
        
    Type
    
        An optional scalar integer parameter that con-
        tains 0 for a procedure, 1 for a function, and 2 for 
        a device driver. The keyword parameters DEVICE and 
        FUNCTION can also be used to indicate the type of 
        routine being merged. The default value is 0, for 
        procedure.
        
    Entry
    
        An optional string that contains the name of the 
        symbol which is the entry point of the procedure or 
        function. If this parameter is not present, the 
        entry name is the value of the parameter Name. Under 
        VMS, the symbol must be declared to be a universal 
        symbol when the sharable image is linked. See the 
        documentation of the VMS LINK command for additional 
        details. With some compilers or operating systems 
        this name may require the addition of leading or 
        trailing characters. For example, many Unix C com-
        pilers add a leading underscore to the beginning of 
        a function name, and many Unix FORTRAN compilers add 
        a trailing underscore.
        
Keywords

    DEVICE
    
        Set this keyword to indicate that the module 
        being loaded contains a device driver.
        
    FUNCT
    
        Set this keyword to indicate that the module 
        being loaded contains a function.
        
    KEYWORDS
    
        Set this keyword to indicate that the procedure 
        or function being loaded accepts keyword parameters.
        
    MAX_ARGS
    
        An optional parameter containing the maximum 
        number of non-keyword arguments the procedure or 
        function accepts. If this parameter is not present, 
        the maximum number of parameters is not checked when 
        the routine is called.
        
    MIN_ARGS
    
        An optional parameter containing the minimum 
        number of non-keyword arguments accepted by the pro-
        cedure or function.
        
VMS Keywords

    DEFAULT 
    
        A string containing the default device, direc-
        tory, filename, and file type information for the 
        file that contains the sharable image. This optional 
        keyword parameter must be used if the sharable image 
        is not in SYS$SHARE and a logical name is not used 
        as the value of the Image argument.
        
Examples

To add a procedure called MY_PROC, whose entry symbol 
is also named MY_PROC, and whose file is pointed to by the 
logical name MY_PROC_EXE:

LINKIMAGE, 'MY_PROC', 'MY_PROC_EXE'

Under VMS, to add a device driver contained in the 
file DRA0:[SMITH]XXDRIV.EXE:

LINKIMAGE, 'XX_DEV', 'XXDRIV', $

           /DEVICE, DEFAULT='DRA0:[SMITH].EXE'

The global symbol XX_DEV, which contains the device 
definition structure, must be defined as universal within 
the sharable image.

;-
;+
LNGAMMA

The LNGAMMA function returns the logarithm of the 
gamma function of X. This function is undefined for nega-
tive integers. If the argument is double-precision, the 
result is double-precision. Otherwise, this function 
yields floating-point results. 

Calling Sequence

        Result = LNGAMMA(X)
        
Arguments

    X
    
        The expression for which the logarithm of the 
        gamma function will be evaluated.
        
Example

To find the logarithm of the gamma function of 0.5 and 
store the result in variable A, enter:

A = LNGAMMA(0.5)

;-
;+
LONARR

The LONARR function returns a longword integer vector 
or array.

Calling Sequence

        Result = LONARR(D1, ..., Dn)
        
Arguments

    Di
    
        The dimensions of the result. The dimension 
        parameters can be any scalar expression. Up to eight 
        dimensions can be specified.
        
Keywords

    NOZERO
    
        Normally, LONARR sets every element of the 
        result to zero. If NOZERO is set, this zeroing is 
        not performed and LONARR executes faster.
        
Example

To create L, a 100-element, longword vector with each 
element set to 0.0, enter:

L = LONARR(100)

;-
;+
LONG

The LONG function returns a result equal to Expression 
converted to longword integer type.

Calling Sequence

        Result = LONG(Expression[, Offset [, Dim1, ..., 
        Dimn]])
        
Arguments

    Expression
    
        The expression to be converted to longword inte-
        ger.
        
    Offset
    
        Offset from beginning of the Expression data 
        area. Specifying this argument allows fields of data 
        extracted from Expression to be treated as longword 
        integer data. See the description in Chapter 4 of 
        the IDL User's Guide for details.
        
    Di
    
        When extracting fields of data, the Di arguments 
        specify the dimensions of the result. The dimension 
        parameters can be any scalar expression. Up to eight 
        dimensions can be specified. If no dimension argu-
        ments are given, the result is taken to be scalar.
        
        When converting from a string argument, it is 
        possible that the string does not contain a valid 
        longword integer and no conversion is possible. The 
        default action in such cases is to print a warning 
        message and return 0. The ON_IOERROR procedure can 
        be used to establish a statement to be jumped to in 
        case of such errors.
        
Example

If A contains the floating-point value 32000.0, it can 
converted to a longword integer and stored in the variable 
B by entering:

B = LONG(A)

;-
;+
MAKE_ARRAY

The MAKE_ARRAY function returns an array of the spec-
ified type, dimensions, and initialization. This function 
enables you to dynamically create an array whose charac-
teristics are not known until run time.

Calling Sequence

        Result = MAKE_ARRAY([D1, ..., Dn])
        
Arguments

    Di
    
        The dimensions of the result. The dimension 
        parameters can be any scalar expression. Up to eight 
        dimensions can be specified.
        
Keywords

    BYTE
    
        Set this keyword to create a byte array.
        
    COMPLEX
    
        Set this keyword to create a complex, single-
        precision, floating-point array.
        
    DIMENSION
    
        A vector of 1 to 8 elements specifying the 
        dimensions of the result.
        
    DOUBLE
    
        Set this keyword to create a double-precision, 
        floating-point array.
        
    FLOAT
    
        Set this keyword to create a single-precision, 
        floating-point array.
        
    INDEX
    
        Set this keyword to initialize the array with 
        each element set to the value of its one-dimensional 
        subscript.
        
    INT
    
        Set this keyword to create an integer array.
        
    LONG
    
        Set this keyword to create a longword integer 
        array.
        
    NOZERO
    
        Set this keyword to prevent the initialization 
        of the array. Normally, each element of the result-
        ing array is set to zero.
        
    SIZE
    
        A size vector specifying the type and dimensions 
        of the result. The format of a size vector is given 
        in the description of the SIZE function.
        
    STRING
    
        Set this keyword to create a string array.
        
    TYPE
    
        The type code to set the type of the result. See 
        the description of the SIZE function for a list of 
        IDL type codes.
        
    VALUE
    
        The value to initialize each element of the 
        resulting array. VALUE can be a scalar of any type 
        including structure types. The result type is taken 
        from VALUE unless one of the other keywords that 
        specify a type is also set. In that case, VALUE is 
        converted to the type specified by the other keyword 
        prior to initializing the resulting array.
        
Example

To create M, a 3-element by 4-element, integer array 
with each element set to the value 5, enter:

M = MAKE_ARRAY(3, 4, /INTEGER, VALUE = 5)

;-
;+
MAP_CONTINENTS

The MAP_CONTINENTS procedure draws the projection of 
the continental boundaries according to the specifica-
tions established by MAP_SET. MAP_SET must be called 
before MAP_CONTINENTS to establish the projection type, 
the center of the projection, polar rotation and geograph-
ical limits.

Calling Sequence

        MAP_CONTINENTS
        
Keywords

    COLOR
    
        The color index of the continental boundaries.
        
    MLINESTYLE
    
        The line style of the boundaries. See the IDL 
        User's Guide for options. The default is solid.
        
    MLINETHICK
    
        The thickness of the boundary lines. The default 
        thickness is 1.
        
    USA
    
        Set this keyword to draw borders for each state 
        in the United States in addition to continental 
        boundaries.
        
;-
;+
MAP_GRID

The MAP_GRID procedure draws the graticule of paral-
lels and meridians, according to the specifications 
established by MAP_SET. MAP_SET must be called before 
MAP_GRID to establish the projection type, the center of 
the projection, polar rotation and geographical limits.

Calling Sequence

        MAP_GRID
        
Keywords

    CHARSIZE
    
        The size of the characters used for the labels. 
        The default is 1.
        
    COLOR
    
        The color index for the grid lines.
        
    LABEL 
    
        Set this keyword to label the parallels and 
        meridians with their corresponding latitudes and 
        longitudes.
        
    LATALIGN
    
        This keyword controls the alignment of the text 
        baseline for latitude labels. A value of 0.0 left 
        justifies the label, 1.0 right justifies it, and 0.5 
        centers it.
        
    LATDEL
    
        The spacing in degrees between parallels of lat-
        itude in the grid. The default is the 10 or (Maximum 
        Latitude - Minimum Latitude)/10.0, whichever is 
        smallest.
        
    LATLAB
    
        The longitude at which to place latitude labels. 
        The default is the center longitude on the map.
        
    LONALIGN
    
        This keyword controls the alignment of the text 
        baseline for longitude labels. A value of 0.0 left 
        justifies the label, 1.0 right justifies it, and 0.5 
        centers it.
        
    LONDEL
    
        The spacing in degrees between meridians of lon-
        gitude. The default is 10 or (Maximum Latitude - 
        Minimum Latitude)/10.0, whichever is smallest.
        
    LONLAB
    
        The latitude at which to place longitude labels. 
        The default is the center latitude on the map.
        
    GLINESTYLE
    
        If set, the line style used to draw the grid of 
        parallels and meridians. See the IDL User's Guide 
        for options. The default is dotted.
        
    GLINETHICK
    
        The thickness of the grid lines. Default is 1.
        
;-
;+
MAP_IMAGE

The MAP_IMAGE function returns an image warped to fit 
the map projection specified by the system variable !MAP. 
The MAP_SET procedure should be called prior to calling 
MAP_IMAGE.

This function provides an easy method for displaying 
geographical data as an image on any map that encloses a 
mathematically convex region (i.e., any two points on the 
map can be joined by a straight line that lies completely 
within the map boundary).

Calling Sequence

        Result = MAP_IMAGE(Image [, Startx, Starty [, 
        Xsize, Ysize]])
        
Arguments

    Image
    
        A two-dimensional array containing the image to 
        be overlaid on the map.
        
    Startx
    
        A named variable that, upon return, contains the 
        X coordinate position where the left edge of the 
        image should be placed on the screen.
        
    Starty
    
        A named variable that, upon return, contains the 
        Y coordinate position where the left edge of the 
        image should be placed on the screen.
        
    Xsize
    
        A named variable that, upon return, contains the 
        width of the image expressed in graphic coordinate 
        units. If the current graphics device uses scalable 
        pixels, the values of Xsize and Ysize should be 
        passed to the TV procedure.
        
    Ysize
    
        A named variable that, upon return, contains the 
        height of the image expressed in graphic coordinate 
        units. If the current graphics device uses scalable 
        pixels, the values of Xsize and Ysize should be 
        passed to the TV procedure.
        
Keywords

    LATMIN
    
        The latitude corresponding to the first row of 
        Image. The default is -90 degrees. Note also that -
        90 LE LATMIN < LATMAX LE 90.
        
    LATMAX
    
        The latitude corresponding to the last row of 
        Image. The default value is 90 degrees. Note also 
        that -90 LE LATMIN < LATMAX LE 90.
        
    LONMIN
    
        The longitude corresponding to the first column 
        of Image. The default is -180 degrees. Note also 
        that -180 LE LONMN < LONMAX LE 180.
        
    LONMAX
    
        The longitude corresponding to the last column 
        of Image. The default is 180 degrees. Note also that 
        -180 LE LONMIN < LONMAX LE 180.
        
    BILINEAR
    
        Set this flag to use bilinear interpolation to 
        soften edges in the returned image.
        
    COMPRESS
    
        This keyword, the interpolation compression 
        flag, controls the accuracy of the results from 
        MAP_IMAGE. The default is 4 for output devices with 
        fixed pixel sizes. Setting this keyword to a higher 
        number saves time while lower numbers produce more 
        accurate results. Setting this keyword to 1 solves 
        the inverse map transformation for every pixel of 
        the output image. 
        
    WHOLE_MAP
    
        Set this keyword to defeat the code that deter-
        mines the extent of the image on the map. Some pro-
        jections are so complex (especially the SATELLITE) 
        that it is difficult to find where the image goes on 
        the map. Setting this keyword computes the entire 
        map, at the cost of more time. For images that cover 
        the entire map, setting this keyword produces no 
        penalty.
        
    SCALE
    
        Set this keyword to the pixel/graphics scale 
        factor for devices with scalable pixels (e.g., Post-
        Script). The default is 0.02 pixels/graphic coordi-
        nate. This setting yields an approximate output 
        image size of 350 x 250. Make this number larger for 
        more resolution (and larger PostScript files and 
        images), or smaller for faster, smaller, and less 
        accurate images.
        
    MAX_VALUE
    
        Data points with values equal to or greater than 
        this value will be treated as missing data, and will 
        be set to the value specified by the MISSING key-
        word.
        
    MISSING
    
        The pixel value to set areas outside the valid 
        map coordinates. If this keyword is omitted, areas 
        outside the map are set to 255 (white) if the cur-
        rent graphics device is PostScript, otherwise they 
        are set to 0.
        
Example

The following lines of code set up an orthographic map 
projection and warp a simple image to it.

IMAGE = BYTSCL(SIN(DIST(400)/10))	Create a simple image to be warped.

TV, IMAGE	Display the image so we can see what it 
looks like before warping.

MAP_SET, 45, /ORTHO, TITLE="Orthographic Projection with 
Image"
Set up an orthographic projection.

newimage = MAP_IMAGE(image, startx, starty, /BILIN)
Return an image, warped to the entire map 
projection, in the variable newimage. Bilin-
ear interpolation is also turned on.

TV, newimage, startx, starty	Display the warped image on the map at the 
proper position.

MAP_GRID	Draw gridlines over the map and image.

MAP_CONTINENTS	Draw continent outlines.

;-
;+
MAP_SET

The MAP_SET procedure establishes the axis type and 
coordinate conversion mechanism for mapping points on the 
earth's surface, expressed in latitude and longitude, to 
points on a plane, according to one of several possible 
map projections.

The type of map projection, the map center, polar 
rotation and geographical limits can all be customized. 
The system variable !MAP retains the information needed to 
effect coordinate conversions to the plane and, 
inversely, from the projection plane to points on the 
earth in latitude and longitude. Users should not change 
the values of the fields in !MAP directly.

MAP_SET can also be made to plot the grid of latitude 
and longitude lines and continental boundaries by setting 
the keywords GRID and CONTINENT.

Calling Sequence

        MAP_SET [, P0lat, P0lon, Rot]
        
Arguments

    P0lat
    
        For all but Lambert's conformal conic projection 
        with two standard parallels, P0lat is the latitude of 
        the point on the earth's surface to be mapped to the 
        center of the projection plane. If the projection 
        type is sinusoidal, P0lat must be 0.
        
        Latitude is measured in degrees North of the 
        equator and P0lat must be in the range:  -90 to 90.
        
        If P0lat is not set, the default value is 0.
        
        For Lambert's conformal conic projection with 
        two standard parallels (i.e., the CONIC keyword is 
        set), P0lat should be set to the latitude in degrees 
        of one of the parallels. If either P0lat or P0lon is 
        omitted, P0lat is 20 degrees by default.
        
    P0lon
    
        For all but Lambert's conformal conic projection 
        with two standard parallels, P0lon is the longitude 
        of the point on the earth's surface to be mapped to 
        the center of the map projection.
        
        Longitude is measured in degrees east of the 
        Greenwich meridian and P0lon must be in the range:  
        -180 to 180.
        
        If P0lon is not set, the default value is zero.
        
        For Lambert's conformal conic projection with 
        two standard parallels (i.e, the CONIC keyword is 
        set), P0lon should be set to the latitude in degrees 
        of the other standard parallel. If either P0lon or 
        P0lat is omitted, P0lon is set to 60 degrees.
        
    Rot
    
        Rot is the angle through which the North direc-
        tion should be rotated around the line L between the 
        earth's center and the point (P0lat, P0lon). Rot is 
        measured in degrees with the positive direction 
        being clockwise rotation around line L. Rot can have 
        values from -180 to 180 degrees.
        
        For cylindrical maps and the Mollweide projec-
        tion, Rot should not be set to precisely 180 or -
        180.
        
        If the center of the map is at the North pole, 
        North is in the direction P0lon + 180 degrees. If 
        the origin is at the South pole, North is in the 
        direction P0lon.
        
        The default value of Rot is 0 degrees.
        
Keywords

    ADVANCE
    
        Set this keyword to advance to the next frame 
        when the screen is set to display multiple plots. 
        Otherwise the entire screen is erased.
        
    AITOFF
    
        Set this keyword to select the Hammer-Aitoff 
        equal area projection.
        
    AZIMUTHAL
    
        Set this keyword to select the azimuthal equi-
        distant projection.
        
    CONIC
    
        Set this keyword to select Lambert's conformal 
        conic projection with two standard parallels.
        
    CYLINDRICAL
    
        Set this keyword to select the cylindrical equi-
        distant projection. Cylindrical is the default map 
        projection.
        
    GNOMIC
    
        Set this keyword to select the gnomonic projec-
        tion.
        
    LAMBERT
    
        Set this keyword to select Lambert's equal area 
        projection.
        
    MERCATOR
    
        Set this keyword to select the Mercator projec-
        tion.
        
    MOLLWEIDE
    
        Set this keyword to select the Mollweide projec-
        tion.
        
    ORTHOGRAPHIC
    
        Set this keyword to select the orthographic pro-
        jection.
        
    SATELLITE
    
        Set this keyword to select the satellite projec-
        tion.
        
        For the satellite projection, P0LAT and P0LON 
        represent the latitude and longitude of the sub-sat-
        ellite point. Three additional parameters, P, Omega, 
        and Gamma (supplied as a three-element vector argu-
        ment to the SAT_P keyword), are also required.
        
        Note that since all meridians and parallels are 
        oblique lines or arcs, the LIMIT keyword must be 
        supplied as an eight-element vector representing 
        four points that delineate the limits of the map. 
        The extent of the map limits, when expressed in lat-
        itude/longitude is a complicated polygon, rather 
        than a simple quadrilateral.
        
    SAT_P
    
        A three-element vector containing three parame-
        ters, P, Omega, and Gamma, that must be supplied 
        when using the SATELLITE projection where:
        
        P is the distance of the point of perspective 
        (camera) from the center of the globe, expressed in 
        units of the radius of the globe.
        
        Omega is the downward tilt of the camera, in 
        degrees from the new horizontal. If both Gamma and 
        Omega are 0, a Vertical Perspective projection 
        results.
        
        Gamma is the angle, expressed in degrees clock-
        wise from north, of the rotation of the projection 
        plane.
        
    SINUSOIDAL
    
        Set this keyword to select the sinusoidal pro-
        jection.
        
    STEREOGRAPHIC
    
        Set this keyword to select the stereographic 
        projection
        
    CHARSIZE
    
        The size of the characters used for the labels. 
        The default is 1.
        
    COLOR
    
        The color index of the map border in the plot-
        ting window.
        
    CONTINENTS
    
        Set this keyword to plot the continental bound-
        aries.
        
    CON_COLOR
    
        The color index for continent outlines if CONTI-
        NENTS is set.
        
    GLINESTYLE
    
        The line style index used to draw the grid of 
        parallels and meridians. See the IDL User's Guide 
        for options. The default is dotted.
        
    GLINETHICK
    
        The thickness of the gridlines drawn if the GRID 
        keyword is set. The default is 1.
        
    GRID
    
        Set this keyword to draw the grid of parallels 
        and meridians.
        
    LABEL
    
        Set this keyword to label the parallels and 
        meridians with their corresponding latitudes and 
        longitudes.
        
    LATALIGN
    
        The alignment of the text baseline for latitude 
        labels. A value of 0.0 left justifies the label, 1.0 
        right justifies it, and 0.5 centers it.
        
    LATLAB
    
        The longitude at which to place latitude labels. 
        The default is the center longitude of the map.
        
    LATDEL
    
        The spacing in degrees between parallels of lat-
        itude drawn by the procedure MAP_GRID. The default 
        is 10 or (Latmax - Latmin)/10.0, whichever is small-
        est.
        
    LIMIT
    
        A four- or eight-element vector that specifies 
        the limits of the map.
        
        As a four-element vector, LIMIT has the form 
        [Latmin, Lonmin, Latmax, Lonmax] that specifies the 
        boundaries of the region to be mapped. (Latmin, Lon-
        min) and (Latmax, Lonmax) are the latitudes and lon-
        gitudes of two points diagonal from each other on 
        the region's boundary.
        
        Latmin must be less than Latmax and Lonmin must 
        be less than Lonmax.
        
        To plot the desired region of the globe, it may 
        be necessary for Lonmin to be less than -180 or Lon-
        max to exceed 180. For example, if the center of the 
        map is at (0, -45) and the user wants to map a region 
        150 degrees in longitude on either side of the cen-
        ter, then Lonmin should be set to 195 and Lonmax to 
        105.
        
        As an eight-element vector, LIMIT has the form: 
        [Lat0, Lon0, Lat1, Lon1, Lat2, Lon2, Lat3, Lon3]. 
        These four latitude/longitude pairs describe, 
        respectively, four points on the left, top, right, 
        and bottom edges of the map extent.
        
    LONALIGN
    
        The alignment of the text baseline for longitude 
        labels. A value of 0.0 left justifies the label, 1.0 
        right justifies it, and 0.5 centers it.
        
    LONDEL
    
        The spacing in degrees between meridians of lon-
        gitude drawn by the procedure MAP_GRID. The default 
        is 10 or (Lonmax - Lonmin)/10.0, whichever is 
        smaller.
        
    LONLAB
    
        The latitude at which to place longitude labels. 
        The default is the center latitude of the map.
        
    MLINESTYLE
    
    
The line style index used for continental boundaries. Linestyles are described in the table 
    below. The default is 0 for solid.
    
    Index    Linestyle
    ---------------------------
    0        Solid
    1        Dotted
    2        Dashed
    3        Dash Dot
    4        Dash Dot Dot Dot
    5        Long Dashes
    
    MLINETHICK
    
        The line thickness used for continental bound-
        aries. The default is 2.
        
    NOBORDER
    
        Set this keyword to not draw a border around the 
        map.
        
    NOERASE
    
        Set this keyword to have MAP_SET not erase the 
        current plot window. The default is to erase before 
        drawing the map.
        
    TITLE
    
        A string containing the main title for the map. 
        The title appears centered above the map window.
        
    USA
    
        Set this keyword to draw borders for each state 
        in the United States.
        
    WHOLE_MAP
    
        Set this keyword to defeat the code that deter-
        mines the extent of the image on the map. Some pro-
        jections are so complex (especially the SATELLITE) 
        that it is difficult to find where the image goes on 
        the map. Setting this keyword computes the entire 
        map, at the cost of more time. For images that cover 
        the entire map, setting this keyword produces no 
        penalty.
        
    XMARGIN
    
        A two-element vector that specifies the vertical 
        margin between the map and screen border in charac-
        ter units.
        
    YMARGIN
    
        A two-element vector that specifies in the hori-
        zontal margin between the map and screen border in 
        character units.
        
Graphics Keywords Accepted

        See Chapter 2, Graphics Keywords and System 
        Variables, for the description of graphics and plot-
        ting keywords not listed above. POSITION T3D ZVALUE.
        
;-
;+
MAX

The MAX function returns the value of the largest ele-
ment of Array. The type of the result is the same as the 
type of Array.

Calling Sequence

        Result = MAX(Array [, Max_Subscript])
        
Arguments

    Array
    
        The array to be searched.
        
    Max_Subscript
    
        A named variable that, if supplied, is converted 
        to a long integer containing the one-dimensional 
        subscript of the maximum element. Otherwise, the 
        system variable !C is set to the one-dimensional 
        subscript of the maximum element.
        
Keywords

    MIN
    
        A named variable to receive the value of the 
        minimum array element. If you need to find both the 
        minimum and maximum array values, use this keyword 
        to avoid scanning the array twice with separate 
        calls to MAX and MIN.
        
Example

Create a simple two-dimensional array by entering:

D = DIST(100)

Print the maximum value in array D and its linear sub-
script by entering:

PRINT, MAX(D, I), I

IDL prints:

   70.7107   5050

To convert I to a two-dimensional subscript, use the 
commands:

IX = I MOD 100

IY = I/100

PRINT, IX, IY

The maximum value of D is at location (50, 50) in the 
original array.

;-
;+
MEDIAN

The MEDIAN function returns the median value of Array 
or applies a one- or two-dimensional median filter of the 
specified width to Array and returns the result. Median 
smoothing replaces each point with the median of the one- 
or two-dimensional neighborhood of a given width. It is 
similar to smoothing with a boxcar or average filter but 
does not blur edges larger than the neighborhood.

In addition, median filtering is effective in remov-
ing "salt and pepper" noise, (isolated high or low val-
ues). The scalar median is simply the middle value, which 
should not be confused with the average value (e.g., the 
median of the array [1,10,4] is 4, while the average is 
5.)

Calling Sequence

        Result = MEDIAN(Array [, Width])
        
Arguments

    Array
    
        The array to be processed. If Width is also sup-
        plied, and Array is of byte type, the result is of 
        byte type. All other types are converted to single-
        precision floating-point, and the result is float-
        ing-point. Array can have only one or two dimen-
        sions.
        
        If Width is not given, Array can have any valid 
        number of dimensions. The array is converted to sin-
        gle-precision floating-point, and the median value 
        is returned as a floating-point value.
        
    Width
    
        The size of the one or two-dimensional neighbor-
        hood to be used for the median filter. The neighbor-
        hood has the same number of dimensions as Array.
        
Example

Create a simple image and display it by entering:

D = SIN(DIST(200)^0.8) & TVSCL, D

Display D median filtered with a width of 9 by enter-
ing:

TVSCL, MEDIAN(D, 9)

;-
;+
MESSAGE

The MESSAGE procedure issues error and informational 
messages using the same mechanism employed by built-in IDL 
routines. By default, the message is issued as an error, 
the message is output, and IDL takes the action specified 
by the ON_ERROR procedure. As a side-effect of issuing the 
error, the system variables !ERR and !ERROR are set and 
the text of the error message is placed in the system 
variable !ERR_STRING.

Calling Sequence

        MESSAGE, Text
        
Arguments

    Text
    
        The text of the message to be issued.
        
Keywords

    CONTINUE
    
        Set this keyword to return after issuing the 
        error instead of taking the action specified by 
        ON_ERROR. Use this option when it is desirable to 
        report an error and then continue processing.
        
    INFORMATIONAL
    
        Set this keyword to issue informational text 
        instead of an error. In this case, !ERR, !ERROR, and 
        !ERR_STRING are not set. The !QUIET system variable 
        controls the printing of informational messages.
        
    IOERROR
    
        Set this keyword to indicates that the error 
        occurred while performing I/O. The action specified 
        by the ON_IOERROR procedure is executed instead of 
        ON_ERROR.
        
    NONAME
    
        Set this keyword to suppress printing of the 
        issuing routine's name at the beginning of the error 
        message.
        
    NOPREFIX
    
        Usually, the message includes the message prefix 
        string (as specified by the !MSG_PREFIX system vari-
        able) at the beginning. Set this keyword to omit the 
        prefix.
        
    NOPRINT
    
        Set this keyword to prevent the message from 
        printing to the screen and cause the other actions 
        to proceed quietly. The error system variables are 
        updated as usual.
        
    TRACEBACK 
    
        Set this keyword to produce the error message 
        followed by a traceback message that gives the loca-
        tion at which MESSAGE was called.
        
Example

As an example, assume the statement:

message, 'Unexpected value encountered.'

is executed in a procedure named CALC. If an error 
occurs, the following message would be printed:

% CALC: Unexpected value encountered.

and execution would halt.

;-
;+
MIN

The MIN function returns the value of the smallest 
element of Array. The type of the result is the same as 
that of Array.

Calling Sequence

        Result = MIN(Array [, Min_Subscript])
        
Arguments

    Array
    
        The array to be searched.
        
    Min_Subscript
    
        A named variable that, if supplied, is converted 
        to a long integer containing the one-dimensional 
        subscript of the minimum element. Otherwise, the 
        system variable !C is set to the one-dimensional 
        subscript of the minimum element.
        
Keywords

    MAX
    
        The name of a variable to receive the value of 
        the maximum array element. If you need to find both 
        the minimum and maximum array values, use this key-
        word to avoid scanning the array twice with separate 
        calls to MAX and MIN.
        
Example

Create a simple two-dimensional array by entering:

D = DIST(100)

Find the minimum value in array D and print the result 
by entering:

PRINT, MIN(D)

;-
;+
N_ELEMENTS

The N_ELEMENTS function returns the number of ele-
ments contained in an expression or variable.

Calling Sequence

        Result = N_ELEMENTS(Expression)
        
Arguments

    Expression
    
        The expression for which the number of elements 
        is to be returned. Scalar expressions always have 
        one element. The number of elements in an array is 
        equal to the product of its dimensions. If Expres-
        sion is an undefined variable, N_ELEMENTS returns 
        zero.
        
Examples

Create an integer array, I by entering:

I = INTARR(4, 5, 3, 6)

Find the number of elements in I and print the result 
by entering:

PRINT, N_ELEMENTS(I)

To test if the variable Q is defined and, if not, set 
its value to 1, use the command:

IF N_ELEMENTS(Q) EQ 0 THEN Q=1

;-
;+
N_PARAMS

The N_PARAMS function returns the number of non-key-
word parameters used in calling an IDL procedure or func-
tion. This function is only useful within IDL procedures 
or functions. User-written procedures and functions can 
use N_PARAMS to determine if they were called with 
optional parameters.

Calling Sequence

        Result = N_PARAMS()
        
Arguments

        None. This function always returns the number of 
        parameters that were used in calling the procedure 
        or function from which N_PARAMS is called.
        
;-
;+
N_TAGS

The N_TAGS function returns the number of structure 
tags contained in an expression. It optionally returns the 
size, in bytes, of the structure.

Calling Sequence

        Result = N_TAGS(Expression)
        
Arguments

    Expression
    
        The expression for which the number of structure 
        tags is to be returned. Expressions that are not of 
        structure type are considered to have no tags. 
        N_TAGS does not search for tags recursively, so if 
        Expression is a structure containing nested struc-
        tures, only the number of tags in the outermost 
        structure are counted.
        
Keywords

    LENGTH
    
        Set this keyword to return the length of the 
        structure, in bytes.
        
        Note: the length of a structure is machine 
        dependent. The length of a given structure will vary 
        depending upon the host machine. IDL to pads and 
        aligns structures in a manner consistent with the 
        host machine's C compiler.
        
Example

Find the number of tags in the system variable !P and 
print the result by entering:

PRINT, N_TAGS(!P)

Find the length of !P, in bytes:

PRINT, N_TAGS(!P, /LENGTH)

;-
;+
ON_ERROR

The ON_ERROR procedure determines the action taken 
when an error is detected inside an IDL user procedure or 
function.

Calling Sequence

        ON_ERROR, N
        
Arguments

    N
    
        An integer that specifies the action to take. 
        Valid values for N are:
        
    0: Stop at the statement in the procedure that 
    caused the error, the default action.
    
    1: Return all the way back to the main program 
    level.
    
    2: Return to the caller of the program unit that 
    established the ON_ERROR condition.
    
    3: Return to the program unit that established 
    the ON_ERROR condition.
    
;-
;+
ON_IOERROR

The ON_IOERROR procedure specifies a statement to be 
jumped to if an I/O error occurs in the current procedure. 
Normally, when an I/O error occurs, an error message is 
printed and program execution is stopped. If ON_IOERROR is 
called and an I/O related error later occurs in the same 
procedure activation, control is transferred to the des-
ignated statement with the error code stored in the system 
variables !ERR and !ERROR. The text of the error message 
is contained in the system variable !ERR_STRING.

The effect of ON_IOERROR can be canceled by using the 
label "NULL" in the call.

Calling Sequence

        ON_IOERROR, Label
        
Example

The following code segment reads an integer from the 
keyboard. If an invalid number is entered, the program re-
prompts.

i = 0	Number to read

valid = 0	Valid flag

WHILE valid EQ 0 DO BEGIN

   ON_IOERROR, bad_num

   READ, 'Enter Number: ', i

   VALID = 1	If we get here, i is good.

bad_num: IF NOT valid THEN $

         PRINT, 'You entered an invalid number.'

ENDWHILE

END

;-
;+
OPEN

The three OPEN procedures open a specified file for 
input and/or output.

    OPENR (OPEN Read) opens an existing file for 
    input only.
    
    OPENW (OPEN Write) opens a new file for input 
    and output. When creating a new file under VMS, a 
    new file with the same name and a higher version 
    number is created. Under other operating systems, if 
    the file exists, it is truncated and its old con-
    tents are destroyed. 
    
    OPENU (OPEN Update) opens an existing file for 
    input and output.
    
Calling Sequence

        There are three forms of the OPEN procedure:
        
        OPENR, Unit, File [, Record_Length]
        
        OPENW, Unit, File [, Record_Length]
        
        OPENU, Unit, File [, Record_Length]
        
Arguments

    Unit
    
        The unit number to be associated with the opened 
        file.
        
    File
    
        A string containing the name of the file to be 
        opened. The following differences exist between the 
        Unix and VMS versions of OPEN:
        
    Under Unix, the filename can contain any wild-
    card characters recognized by the shell specified by 
    the SHELL environment variable. However, it is 
    faster not to use wildcards because IDL doesn't use 
    the shell to expand file names unless it has to. No 
    wildcard characters are allowed under VMS.
    
    Under VMS, filenames that do not have a file 
    extension are assumed to have the .DAT extension. No 
    such processing of file names occurs under Unix.
    
    Record_Length
    
        The Record_Length argument has meaning only 
        under VMS. It specifies the file record size in 
        bytes. This argument is required when creating new, 
        fixed-length files, and is optional when opening 
        existing files. If this argument is present when 
        creating variable-length record files, it specifies 
        the maximum allowed record size. If this argument is 
        present and no file organization keyword is speci-
        fied, fixed-length records are implied.
        
        Due to limitations in RMS (the VMS Record Man-
        agement System), the length of records must always 
        be an even number of bytes. Odd record lengths are 
        therefore automatically rounded up to the nearest 
        even boundary.
        
Keywords

    APPEND
    
        Set this keyword to open the file with the file 
        pointer at the end of the file, ready for data to be 
        appended. Normally, the file is opened with the file 
        pointer at the beginning of the file. Under Unix, 
        use of APPEND prevents OPENW from truncating exist-
        ing file contents.
        
    DELETE
    
        Set this keyword to delete the file when it is 
        closed.
        
        Caution: Setting the DELETE keyword causes the 
        file to be deleted even if it was opened for read-
        only access. In addition, once a file is opened with 
        this keyword, there is no way to cancel its opera-
        tion.
        
    ERROR
    
        A named variable to place the error status in. 
        If an error occurs in the attempt to open File, IDL 
        normally takes the error handling action defined by 
        the ON_ERROR and/or ON_IOERROR procedures. OPEN 
        always returns to the caller without generating an 
        error message when ERROR is present. A nonzero error 
        status indicates that an error occurred. The error 
        message can then be found in the system variable 
        !ERR_STRING.
        
        For example, statements similar to the following 
        can be used to detect errors:
        
        OPENR, 1, 'demo.dat', ERROR = err
        Try to open the file demo.dat.
        
        IF (err NE 0) then PRINTF, -2, !ERR_STRING
        If err is nonzero, something hap-
        pened. Print the error message to 
        the standard error file (logical unit -
        2).
        
    GET_LUN
    
        Set this keyword to use the GET_LUN procedure to 
        set the value of Unit before the file is opened. 
        Instead of using the two statements:
        
        GET_LUN, Unit
        
        OPENR, Unit, 'data.dat'
        
        you can use the single statement:
        
        OPENR, Unit, 'data.dat', /GET LUN
        
    MACTYPE (Macintosh Only)
    
        Use this keyword to specify a scalar string 
        identifying the Macintosh file type of the file 
        being created. For example, set MACTYPE = 'PICT' to 
        create a file of type PICT. The defualt Macintosh 
        file type is TEXT.
        
    MORE
    
        If MORE is set, and the specified File is a ter-
        minal, then all output to this unit is formatted in 
        a manner similar to the Unix more(1) command and 
        sent to the standard output stream. Output pauses at 
        the bottom of each screen, at which point the user 
        can press one of the following keys:
        
    Space: Display the next page of text.
    
    Return: Display the next line of text.
    
    `q' or `Q': Suppress all remaining output.
    
    `h' or `H': Display this list of options.
    
        For example, the following statements show how 
        to output a file named text.dat to the terminal:
        
        OPENR, inunit, 'text.dat', /GET_LUN
        Open the text file.
        
        OPENW, outunit, '/dev/tty', /GET_LUN, /MORE
        Open the terminal as a file.
        
        line = '' & READF, inunit, line
        Read the first line.
        
        WHILE NOT EOF(inunit) DO BEGIN
        While there is text left, output it.
        
           PRINTF, outunit, line
        
           READF, inunit, line
        
        ENDWHILE
        
        FREE_LUN, inunit & FREE_LUN, outunit
        Close the files and deallocate the 
        units.
        
    WIDTH
    
        The desired output width. When using the 
        defaults for formatted output, IDL uses the follow-
        ing rules to determine where to break lines:
        
    If the output file is a terminal, the terminal 
    width is used. item Under VMS, if the file has 
    fixed-length records or a maximum record length, the 
    record length is used.
    
    Otherwise, a default of 80 columns is used.
    
        The WIDTH keyword allows the user to override 
        this default.
        
    XDR
    
        Set this keyword to open the file for unformat-
        ted XDR (eXternal Data Representation) I/O via the 
        READU and WRITEU procedures. Use XDR to make binary 
        data portable between different machine architec-
        tures by reading and writing all data in a standard 
        format. When a file is open for XDR access, the only 
        I/O data transfer procedures that can be used with 
        it are READU and WRITEU.
        
        Under VMS, the XDR keyword can only be used with 
        stream files.
        
Unix Keywords

    F77_UNFORMATTED
    
        Unformatted variable-length record files pro-
        duced by Unix FORTRAN programs contain extra infor-
        mation along with the data in order to allow the 
        data to be properly recovered. This method is neces-
        sary because FORTRAN input/output is based on 
        record-oriented files, while Unix files are simple 
        byte streams that do not impose any record struc-
        ture. Set the F77_UNFORMATTED keyword to read and 
        write this extra information in the same manner as 
        f77(1), so that data to be processed by both IDL and 
        FORTRAN.
        
    NOSTDIO
    
        Set this keyword to disable all use of the stan-
        dard Unix I/O for the file, in favor of direct calls 
        to the operating system. This allows direct access 
        to devices, such as tape drives, that are difficult 
        or impossible to use effectively through the stan-
        dard I/O. Using this keyword has the following 
        implications:
        
        No formatted or associated (ASSOC) I/O is 
        allowed on the file. Only READU and WRITEU are 
        allowed.
        
        Normally, attempting to read more data than is 
        available from a file causes the unfilled space to 
        be set to zero and an error to be issued. This does 
        not happen with files opened with NOSTDIO. When 
        using NOSTDIO, the programmer must check the trans-
        fer count, either via the TRANSFER_COUNT keywords to 
        READU and WRITEU, or the FSTAT function.
        
        The EOF and POINT_LUN functions cannot be used 
        with a file opened with NOSTDIO.
        
        Each call to READU or WRITEU maps directly to 
        Unix read(2) and write(2) system calls. The program-
        mer must read the Unix system documentation for 
        these calls and documentation on the target device 
        to determine if there are any special rules for I/O 
        to that device. For example, the size of data that 
        can be transferred to many cartridge tape drives is 
        often forced to be a multiple of 512 bytes.
        
VMS Keywords

    BLOCK
    
        Set this keyword to process the file using RMS 
        block mode. In this mode, most RMS processing is 
        bypassed and IDL reads and writes to the file in 
        disk block units. Such files can only be accessed 
        via unformatted I/O commands. Block mode files are 
        treated as an uninterpreted stream of bytes in a 
        manner similar to Unix stream files.
        
        This keyword is ignored when used with stream 
        files.
        
        Note: With some controller/disk combinations, 
        RMS does not allow transfer of an odd number of 
        bytes.
        
    DEFAULT
    
        A scalar string that provides a default file 
        specification from which missing parts of the File 
        argument are taken. For example, to make .LOG be the 
        default file extension when opening a new file, use 
        the command:
        
        OPENW, 'DATA', DEFAULT='.LOG'
        
        This statement will open the file DATA.LOG.
        
    EXTENDSIZE
    
        File extension is a relatively slow operation, 
        and it is desirable to minimize the number of times 
        it is done. In order to avoid the unacceptable per-
        formance that would result from extending a file a 
        single block at a time, VMS extends its size by a 
        default number of blocks in an attempt to trade a 
        small amount of wasted disk space for better perfor-
        mance. The EXTENDSIZE keyword overrides the default, 
        and specifies the number of disk blocks by which the 
        file should be extended. This keyword is often used 
        in conjunction with the INITIALSIZE and 
        TRUNCATE_ON_CLOSE keywords.
        
    FIXED
    
        Set this keyword to indicate that the file has 
        fixed-length records. The Record_Length argument is 
        required when opening new, fixed-length files.
        
    FORTRAN
    
        Set this keyword to use FORTRAN-style carriage 
        control when creating a new file.
        
    INITIALSIZE
    
        The initial size of the file allocation in 
        blocks. This keyword is often used in conjunction 
        with the EXTENDSIZE and TRUNCATE_ON_CLOSE keywords.
        
    KEYED
    
        Set this keyword to indicate that the file has 
        indexed organization.
        
    LIST
    
        Set this keyword to specify carriage-return car-
        riage control when creating a new file. If no car-
        riage-control keyword is specified, LIST is the 
        default.
        
    NONE
    
        Set this keyword to specify explicit carriage 
        control when creating a new file. When using 
        explicit carriage control, VMS does not add any car-
        riage control information to the file, and the user 
        must explicitly add any desired carriage control to 
        the data being written to the file.
        
    PRINT
    
        Set this keyword to send the file to SYS$PRINT, 
        the default system printer, when it is closed.
        
    SEGMENTED
    
        Set this keyword to indicate that the file has 
        VMS FORTRAN-style segmented records. Segmented 
        records are a method by which FORTRAN allows logical 
        records to exist with record sizes that exceed the 
        maximum possible physical record sizes supported by 
        VMS. Segmented record files are useful primarily for 
        passing data between FORTRAN and IDL programs.
        
    SHARED
    
        Set this keyword to allow other processes read 
        and write access to the file in parallel with IDL. 
        If SHARED is not set, read-only files are opened for 
        read sharing and read/write files are not shared.
        
        Caution: It is not a good idea to allow shared 
        write access to files open in RMS block mode. In 
        block mode, VMS cannot perform the usual record 
        locking that prevents file corruption. It is there-
        fore possible for multiple writers to corrupt a 
        block mode file. This warning also applies to fixed-
        length record disk files, which are also processed 
        in block mode.
        
    STREAM
    
        Set this keyword to open the file in stream 
        mode.
        
    SUBMIT
    
        Set this keyword to submit the file to 
        SYS$BATCH, the default system batch queue, when it 
        is closed.
        
    SUPERSEDE
    
        Set this keyword to allow an existing file to be 
        superseded by a new file of the same name, type, and 
        version.
        
    TRUNCATE_ON_CLOSE
    
        Set this keyword to free any unused disk space 
        allocated to the file when the file is closed. This 
        keyword can be used to get rid of excess allocations 
        caused by the EXTENDSIZE and INITIALSIZE keywords. 
        If the SHARED keyword is set, or the file is open 
        for read-only access, TRUNCATE_ON_CLOSE has no 
        effect.
        
    UDF_BLOCK
    
        Set this keyword to create a file similar to 
        those created with the BLOCK keyword except that new 
        files are created with the RMS undefined record 
        type. Files created in this way can only be accessed 
        by IDL in block mode, and cannot be processed by 
        many VMS utilities.
        
    VARIABLE
    
        Set this keyword to indicate that the file has 
        variable-length records. If the Record_Length argu-
        ment is present, it specifies the maximum record 
        size. Otherwise, the only limit is that imposed by 
        RMS (32767 bytes). If no file organization is speci-
        fied, variable-length records are the default.
        
Example

The following example opens the IDL distribution file 
people.dat and reads an image from that file:

OPENR, 1, FILEPATH('people.dat', SUBDIR = 'images')
Open "people.dat" on file unit number 1. 
The FILEPATH function is used to return the 
full path name to this distribution file.

image=BYTARR(192, 192, /NOZERO)	Define a variable into which the image 
will be read.

READU, 1, image	Read the data.

TV, image	Display the image.

;-
;+
OPLOT

The OPLOT procedure plots vector data over a previ-
ously-drawn plot. It differs from PLOT only in that it 
does not generate a new axis. Instead, it uses the scaling 
established by the most recent call to PLOT and simply 
overlays a plot of the data on the existing axis.

Calling Sequence

        OPLOT, [X,] Y
        
Arguments

    X
    
        A vector argument. If X is not specified, Y is 
        plotted as a function of point number (starting at 
        zero). If both arguments are provided, Y is plotted 
        as a function of X.
        
        This argument is converted to single-precision 
        floating-point before plotting. Plots created with 
        OPLOT are limited to the range and precision of sin-
        gle-precision floating-point values.
        
    Y
    
        The ordinate data to be plotted. This argument 
        is converted to single-precision floating-point 
        before plotting. 
        
Keywords

    NSUM
    
        The presence of this keyword indicates the num-
        ber of data points to average when plotting. If NSUM 
        is larger than 1, every group of NSUM points is 
        averaged to produce one plotted point. If there are 
        m data points, then m/NSUM points are displayed. On 
        logarithmic axes a geometric average is performed. 
        
        It is convenient to use NSUM when there is an 
        extremely large number of data points to plot 
        because it plots fewer points, the graph is less 
        cluttered, and it is quicker.
        
    POLAR
    
        Set this keyword to produce polar plots. The X 
        and Y vector parameters, both of which must be 
        present, are first converted from polar to cartesian 
        coordinates. The first parameter is the radius, and 
        the second is, expressed in radians. For example, to 
        make a polar plot, use the command:
        
        OPLOT, /POLAR, R, THETA
        
    THICK
    
        Controls the thickness of the lines connecting 
        the points. A thickness of 1.0 is normal, 2.0 is 
        double wide, etc.
        
Graphics Keywords Accepted

        See Chapter 2, Graphics Keywords and System 
        Variables, for the description of graphics and plot-
        ting keywords not listed above. CHANNEL CLIP COLOR 
        LINESTYLE MAX_VALUE NOCLIP PSYM SUBTITLE SYMSIZE T3D 
        ZVALUE.
        
Example

Create a simple dataset by entering:

D = SIN(FINDGEN(100)/EXP(FINDGEN(100)/50))

Create an X-Y plot of vector D by entering:

PLOT, D

Overplot the sine of D as a thick, dashed line by 
entering:

OPLOT, SIN(D), LINESTYLE = 5, THICK = 2

;-
;+
PLOT

The PLOT procedure draws graphs of vector arguments. 
If one parameter is used, the vector parameter is plotted 
on the ordinate versus the point number on the abscissa. 
To plot one vector as a function of another, use two 
parameters. PLOT can also be used to create polar plots by 
setting the POLAR keyword.

Calling Sequence

        PLOT, [X,] Y
        
Arguments

    X
    
        A vector argument. If X is not specified, Y is 
        plotted as a function of point number (starting at 
        zero). If both arguments are provided, Y is plotted 
        as a function of X.
        
        This argument is converted to single-precision 
        floating-point before plotting. Plots created with 
        PLOT are limited to the range and precision of sin-
        gle-precision floating-point values.
        
    Y
    
        The ordinate data to be plotted. This argument 
        is converted to single-precision floating-point 
        before plotting.
        
Keywords

    MAX_VALUE
    
        The maximum value to be plotted. If this keyword 
        is present, data values greater than the value of 
        MAX_VALUE are treated as missing and are not plot-
        ted.
        
    NSUM
    
        The presence of this keyword indicates the num-
        ber of data points to average when plotting. If NSUM 
        is larger than 1, every group of NSUM points is 
        averaged to produce one plotted point. If there are 
        m data points, then m/NSUM points are displayed. On 
        logarithmic axes a geometric average is performed. 
        
        It is convenient to use NSUM when there is an 
        extremely large number of data points to plot 
        because it plots fewer points, the graph is less 
        cluttered, and it is quicker.
        
    POLAR
    
        Set this keyword to produce polar plots. The X 
        and Y vector parameters, both of which must be 
        present, are first converted from polar to cartesian 
        coordinates. The first parameter is the radius, and 
        the second is, expressed in radians. For example, to 
        make a polar plot, you would use a command such as:
        
        PLOT, /POLAR, R, THETA
        
    THICK
    
        Controls the thickness of the lines connecting 
        the points. A thickness of 1.0 is normal, 2 is dou-
        ble wide, etc.
        
    XTYPE
    
        Set this keyword to specify a logarithmic X 
        axis.
        
    YNOZERO
    
        Set this keyword to inhibit setting the minimum 
        Y axis value to zero when the Y data are all posi-
        tive and nonzero, and no explicit minimum Y value is 
        specified (using YRANGE, or !Y.RANGE). By default, 
        the Y axis spans the range of 0 to the maximum value 
        of Y, in the case of positive Y data. Set bit 4 in 
        !Y.STYLE to make this option the default.
        
    YTYPE
    
        Set this keyword to specify a logarithmic Y 
        axis.
        
Graphics Keywords Accepted

        See Chapter 2, Graphics Keywords and System 
        Variables, for the description of graphics and plot-
        ting keywords not listed above. BACKGROUND CHANNEL 
        CHARSIZE CHARTHICK CLIP COLOR DATA DEVICE FONT LINE-
        STYLE NOCLIP NODATA NOERASE NORMAL POSITION PSYM 
        SUBTITLE SYMSIZE T3D TICKLEN TITLE XCHARSIZE XGRID-
        STYLE XMARGIN XMINOR XRANGE XSTYLE XTHICK XTICKFOR-
        MAT XTICKLEN XTICKNAME XTICKS XTICKV XTICK_GET 
        XTITLE YCHARSIZE YGRIDSTYLE YMARGIN YMINOR YRANGE 
        YSTYLE YTHICK YTICKFORMAT YTICKLEN YTICKNAME YTICKS 
        YTICKV YTICK_GET YTITLE ZCHARSIZE ZGRIDSTYLE ZMARGIN 
        ZMINOR ZRANGE ZSTYLE ZTHICK ZTICKFORMAT ZTICKLEN 
        ZTICKNAME ZTICKS ZTICKV ZTICK_GET ZTITLE ZVALUE.
        
Example

The PLOT procedure has many keywords that allow you to 
create a vast variety of plots. Here are a few simple 
examples using the PLOT command. Create a simple dataset 
by entering:

D = FINDGEN(100)

To create a simple plot with the title "Simple Plot", 
enter:

PLOT, D, TITLE = 'Simple Plot'

Plot one argument versus another by entering:

PLOT, SIN(D/3), COS(D/6)

Create a polar plot with the command:

PLOT, D, D, /POLAR, TITLE = 'Polar Plot'

Use plotting symbols instead of connecting lines by 
including the PSYM keyword. Also, label the X and Y axes 
with the command:

PLOT, SIN(D/10), PSYM=4, XTITLE='X Axis', YTITLE='Y Axis'

;-
;+
PLOT_IO

The PLOT_IO procedure is identical to the PLOT proce-
dure, except that it produces logarithmic scaling on the Y 
axis. See the description of PLOT for the list of accepted 
keywords.

Calling Sequence

        PLOT_IO, [X,] Y
        
Arguments

    X
    
        A vector argument. If X is not specified, Y is 
        plotted as a function of point number (starting at 
        zero). If both arguments are provided, Y is plotted 
        as a function of X.
        
    Y
    
        The ordinate data to be plotted.
        
;-
;+
PLOT_OI

The PLOT_OI procedure is identical to the PLOT proce-
dure, except that it produces logarithmic scaling on the X 
axis. See the description of PLOT for the list of accepted 
keywords.

Calling Sequence

        PLOT_OI, [X,] Y
        
Arguments

    X
    
        A vector argument. If X is not specified, Y is 
        plotted as a function of point number (starting at 
        zero). If both arguments are provided, Y is plotted 
        as a function of X.
        
    Y
    
        The ordinate data to be plotted.
        
;-
;+
PLOT_OO

The PLOT_OO procedure is identical to the PLOT proce-
dure, except that it produces logarithmic scaling on both 
the X and Y axes. See the description of PLOT for the list 
of accepted keywords.

Calling Sequence

        PLOT_OO, [X,] Y
        
Arguments

    X
    
        A vector argument. If X is not specified, Y is 
        plotted as a function of point number (starting at 
        zero). If both arguments are provided, Y is plotted 
        as a function of X.
        
    Y
    
        The ordinate data to be plotted.
        
;-
;+
PLOTS

The PLOTS procedure plots vectors or points on the 
current graphics device in either two or three dimensions. 
The coordinates can be given in data, device, or normal-
ized form using the DATA (the default), DEVICE, or NORMAL 
keywords.

The COLOR keyword can be set to a scalar or vector 
value. If it is set to a vector value, the line segment 
connecting (Xi, Yi) to (Xi+1, Yi+1) is drawn with a color 
index of COLORi+1. In this case, COLOR must have the same 
number of elements as X and Y.

Calling Sequence

        PLOTS, X [, Y [, Z]]
        
Arguments

    X
    
        A vector or scalar argument providing the X com-
        ponents of the points to be connected. If only one 
        argument is specified, X must be an array of either 
        two or three vectors (i.e., (2,*) or (3,*)). In this 
        special case, X(0,*) is taken as the X values, 
        X(1,*) is taken as the Y values, and X(2,*) is taken 
        as the Z values.
        
    Y
    
        An optional argument providing the Y coordi-
        nate(s) of the points to be connected.
        
    Z
    
        An optional argument providing the Z coordinates 
        of the points to be connected. If Z is not provided, 
        X and Y are used to draw lines in two dimensions. 
        
        Z has no effect if the keyword T3D is not speci-
        fied and the system variable !P.T3D= 0.
        
Keywords

    CONTINUE
    
        Set this keyword to continue drawing a line from 
        the last point of the most recent call to PLOTS. For 
        example:
        
        PLOTS, 0, 0	Position at (0,0).
        
        PLOTS, 1, 1, /CONTINUE	Draws vector from (0,0) to (1,1).
        
        PLOTS, [2,3], [2,3], /CONTINUE
        	Draws two vectors from (1,1) to 
        (2,2) to (3,3).
        
Graphics Keywords Accepted

        See Chapter 2, Graphics Keywords and System 
        Variables, for the description of graphics and plot-
        ting keywords not listed above. CHANNEL CLIP COLOR 
        DATA DEVICE LINESTYLE NOCLIP NORMAL PSYM SYMSIZE T3D 
        THICK Z.
        
Examples

Draw a line from (100, 200) to (600, 700), in device 
coordinates, using color index 12:

PLOTS, [100,600], [200,700], COLOR=12, /DEVICE

Draw a polyline where the line color is proportional 
to the ordinate that ends each line segment. First create 
datasets X and Y by entering:

X = SIN(FINDGEN(100)) & Y = COS(FINDGEN(100))

Now plot X and Y in normalized coordinates with colors 
as described above:

PLOTS, X, Y, COLOR = BYTSCL(Y, TOP=!D.N COLORS-1), /NORMAL

Load a good colortable to better show the result. 
Enter:

LOADCT, 13



Draw 3D vectors over an established SURFACE plot:

SURFACE, DIST(5), /SAVE	The SAVE keyword tells IDL to save the 3D 
transformation established by SURFACE.

PLOTS, [0,3], [0,3], [0,3], /T3D	Draw a line between (0,0,0) and (3,3,3). 
The T3D keyword makes PLOTS use the pre-
viously established 3D transformation.

PLOTS, [3,3], [0,3], [0,3], /T3D	Draw a line between (3,0,0) and (3,3,3).

PLOTS, [0,3], [3,3], [0,3], /T3D	Draw a line between (0,3,0) and (3,3,3).

;-
;+
POINT_LUN

The POINT_LUN procedure sets or obtains the current 
position of the file pointer for the specified file.

Note that POINT_LUN cannot be used with files opened 
with the NOSTDIO keyword to the OPEN routines. Depending 
upon the device in question, the IOCTL function might be 
used instead for files of this type.

Calling Sequence

        POINT_LUN, Unit, Position
        
Arguments

    Unit 
    
        The file unit for the file in question. If Unit 
        is positive, POINT_LUN sets the file position to the 
        position given by Position. If negative, POINT_LUN 
        gets the current file position and assigns it to the 
        variable given by Position. Note that POINT_LUN can-
        not be used with the 3 standard file units (0, -1, 
        and -2).
        
    Position
    
        If Unit is positive, Position gives the byte 
        offset into the file at which the file pointer 
        should be set (hence, to rewind the file to the 
        beginning, specify 0). If Unit is negative, Position 
        must be a named variable into which the current file 
        position will be stored.
        
        Under VMS, be careful to move the file pointer 
        only to record boundaries. It is always safe to move 
        to a file position that was previously obtained via 
        POINT_LUN or the FSTAT function. Files with indexed 
        organization can only be positioned to the beginning 
        of the file.
        
Example

To move the file pointer 2048 bytes into the file 
associated with file unit number 1, enter:

POINT_LUN, 1, 2048

To find the position of the file pointer in the file 
associated with file unit 2 and store that position in the 
variable pos, enter:

POINT_LUN, -2, pos

;-
;+
POLY_2D

The POLY_2D function performs polynomial warping of 
images. This function performs a geometrical transforma-
tion in which the resulting array is defined by:

g(x,y) = f(x', y') = f[a(x,y), b(x,y)]

where g(x, y) represents the pixel in the output image 
at coordinate (x, y), and f(x', y') is the pixel at (x', 
y') in the input image that is used to derive g(x, y). 
Either the nearest neighbor or bilinear interpolation 
methods can be selected.

Calling Sequence

        Result = POLY_2D(Array, P, Q [, Interp [, Dimx, 
        Dimy]])
        
Arguments

    Array
    
        A two-dimensional array of any basic type except 
        string. The result has the same type as Array.
        
    P and Q
    
        P and Q are arrays containing the polynomial 
        coefficients. Each array must contain (N+1)^2 ele-
        ments (where N is the degree of the polynomial). For 
        example, for a linear transformation, P and Q con-
        tain four elements and can be a 2 by 2 array or a 4-
        element vector. Pi,j contains the coefficient used to 
        determine x', and is the weight of the term xjyi. The 
        IDL Users' Library procedure POLYWARP can be used to 
        fit (x', y') as a function of (x, y) and determines 
        the coefficient arrays P and Q.
        
    Interp
    
        Set this argument to a 1to perform bilinear 
        interpolation. Set this argument to 2 to perform 
        cubic convolution interpolation (as described under 
        the CUBIC keyword, below). Otherwise, the nearest 
        neighbor method is used. For the linear case, (N=1), 
        bilinear interpolation requires approximately twice 
        as much time as does the nearest neighbor method. 
        
    Dimx
    
        If present, Dimx specifies the number of columns 
        in the output. If omitted, the output has the same 
        number of columns as Array.
        
    Dimy
    
        If present, Dimy specifies the number of rows in 
        the output. If omitted, the output has the same num-
        ber of rows as Array.
        
Keywords

    CUBIC
    
        Set this keyword to use the cubic convolution 
        interpolation method. Note that cubic convolution 
        interpolation works only with one- and two-dimen-
        sional arrays.
        
        Cubic convolution is an interpolation method 
        that closely approximates the theoretically optimum 
        sinc interpolation function using cubic polynomials. 
        According to sampling theory, details of which are 
        beyond the scope of this document, if the original 
        signal, f, is a band-limited signal, with no fre-
        quency component larger than Omega_0, and f is sam-
        pled with spacing less than or equal to 1/
        (2*Omega_0), then f can be reconstructed by convolv-
        ing with a sinc function: sinc(x) = sin(pi * x) / 
        (pi * x).
        
        In the one-dimensional case, four neighboring 
        points are used, while in the two-dimensional case 
        16 points are used. Note that cubic convolution 
        interpolation is significantly slower than bilinear 
        interpolation.
        
        For further details see Rifman, S.S. and McKin-
        non, D.M., "Evaluation of Digital Correction Tech-
        niques for ERTS Images-Final Report", Report 20634-
        6003-TU-00, TRW Systems, Redondo Beach, CA, July 
        1974.
        
    MISSING
    
        Specifies the output value for points whose x', 
        y' is outside the bounds of Array. If MISSING is not 
        specified, the resulting output value is extrapo-
        lated from the nearest pixel of Array.
        
Example

POLY_2D is often used in conjunction with the User 
Library procedure POLYWARP to warp images. Create and dis-
play a simple image by entering:

A = BYTSCL(SIN(DIST(250)), TOP=!D.TABLE_SIZE) & TV, A

Set up the arrays of original points to be warped by 
entering:

XO = [61, 62, 143, 133]

YO = [89, 34, 38, 105]

Set up the arrays of points to be fit by entering:

XI = [24, 35, 102, 92]

YI = [81, 24, 25, 92]

Use POLYWARP to generate the P and Q inputs to POLY_2D 
by entering:

POLYWARP, XI, YI, XO, YO, 1, P, Q

To perform an image warping based on P and Q, enter:

B = POLY_2D(A, P, Q)

Display the new image by entering:

TV, B, 250, 250

For more information, see the on-line documentation 
for POLYWARP (use the "?" command).

Images can also be warped over irregularly gridded 
control points using the WARP_TRI User Library procedure.

;-
;+
POLYFILL

The POLYFILL procedure fills the interior of a region 
of the display enclosed by an arbitrary two or three-
dimensional polygon. The available filling methods are: 
solid fill, hardware-dependent fill pattern, parallel 
lines, or a pattern contained in an array. Not all methods 
are available on every hardware output device.

The polygon is defined by a list of connected vertices 
stored in X, Y, and Z. The coordinates can be given in 
data, device, or normalized form using the DATA, DEVICE, 
or NORMAL keywords.

Line-fill method: Filling using parallel lines is 
device-independent and works on all devices that can draw 
lines. Crosshatching can be simulated by performing mul-
tiple fills with different orientations. The spacing, 
linestyle, orientation, and thickness of the filling 
lines can be specified using the corresponding keyword 
parameters. The LINE_FILL keyword selects this filling 
style, but is not required if either the ORIENTATION or 
SPACING parameters are present.

Solid fill method: Most, but not all, devices can fill 
with a solid color. Solid fill is performed using the 
line-fill method for devices that don't have this hardware 
capability. Method specifying keyword parameters are not 
required for solid filling.

Patterned fill: The method of patterned filling and 
the usage of various fill patterns is hardware dependent. 
The fill pattern array can be explicitly specified with 
the PATTERN keyword parameter for some output devices. If 
this parameter is omitted, the polygon is filled with the 
hardware-dependent pattern index specified by the 
FILL_PATTERN keyword.

Calling Sequence

        POLYFILL, X [, Y [, Z]]
        
Arguments

    X
    
        A vector argument providing the X coordinates of 
        the points to be connected. The vector must contain 
        at least three elements. If only one argument is 
        specified, X must be an array of either two or three 
        vectors (i.e., (2,*) or (3,*)). In this special 
        case, the vector X(0,*) specifies the X values, 
        X(1,*) specifies Y, and X(2,*) contain the Z values.
        
    Y
    
        A vector argument providing the Y coordinates of 
        the points to be connected. Y must contain at least 
        three elements.
        
    Z
    
        An optional vector argument providing the Z 
        coordinates of the points to be connected. If Z is 
        not provided, X and Y are used to draw lines in two 
        dimensions. Z must contain at least three elements. 
        Z has no effect if the keyword T3D is not specified 
        and the system variable !P.T3D= 0.
        
Keywords

    FILL_PATTERN
    
        The hardware dependent fill pattern index for 
        the POLYFILL procedure. If omitted or set to 0, a 
        solid fill results.
        
    IMAGE_COORD
    
        (Z-Buffer output only) A 2 by N array containing 
        the fill pattern array subscripts of each of the N 
        polygon vertices.Use this keyword in conjunction 
        with the PATTERN keyword to warp images over 2D and 
        3D polygons.
        
    IMAGE_INTERP
    
        (Z-Buffer output only) Specifies the method of 
        sampling the PATTERN array when the 
        IMAGE_COORDINATES keyword is present. The default 
        method is to use nearest-neighbor sampling. Bilinear 
        interpolation sampling is performed if 
        IMAGE_INTERPOLATE is set.
        
    LINE_FILL
    
        Set this keyword to indicate that polygons are 
        to be filled with parallel lines, rather than using 
        solid or patterned filling methods.When using the 
        line-drawing method of filling, the thickness, line-
        style, orientation, and spacing of the lines may be 
        specified with keywords.
        
    PATTERN
    
        A rectangular array of pixels giving the fill 
        pattern. If this keyword parameter is omitted, POLY-
        FILL fills the area with a solid color. The pattern 
        array may be of any size; if it is smaller than the 
        filled area the pattern array is cyclically 
        repeated.
        
        Caution: Some devices, notably SunView, are not 
        able to fill with a pattern containing an odd number 
        of columns.
        
        For example, to fill the current plot window 
        with a grid of dots, enter the following commands:
        
        PAT = BYTARR(10,10)	Define pattern array as 10 by 10.
        
        PAT(5,5) = 255	Set center pixel to bright.
        
        POLYFILL, !X.WINDOW([0,1,1,0]), $
        
                  !Y.WINDOW([0,0,1,1]), /NORM, PAT = PAT
        
        	Fill the rectangle defined by the four 
        corners of the window with the pat-
        tern.
        
    SPACING
    
        The spacing, in centimeters, between the paral-
        lel lines used to fill polygons.
        
    TRANSPARENT
    
        (Z-Buffer output only) specifies the minimum 
        pixel value to draw in conjunction with the PATTERN 
        and IMAGE_COORDINATES keywords. Pixels less than 
        this value are not drawn and the Z-buffer is not 
        updated.
        
Graphics Keywords Accepted

        See Chapter 2, Graphics Keywords and System 
        Variables, for the description of graphics and plot-
        ting keywords not listed above. CHANNEL CLIP COLOR 
        DATA DEVICE LINE NOCLIP NORMAL ORIENTATION SPACING 
        T3D THICK Z.
        
Z-Buffer-Specific Keywords

Certain keyword parameters are only active when the Z-
buffer is the currently selected graphics device: 
IMAGE_COORD, IMAGE_INTERP, TRANSPARENT and COLOR. These 
parameters allow images to be warped over 2D or 3D poly-
gons, and the output of shaded polygons. For examples, see 
the description of the Z-buffer driver in Chapter 3.

For shaded polygons, the COLOR keyword can specify an 
array that contains the color index at each vertex. Color 
indices are linearly interpolated between vertices. If 
COLOR contains a scalar, the entire polygon is drawn with 
the given color index, just as with the other graphics 
output devices.

Images can be warped over polygons by passing in the 
image with the PATTERN parameter, and a (2, N) array con-
taining the image space coordinates that correspond to 
each of the N vertices with the IMAGE_COORDINATES keyword.

The IMAGE_INTERPOLATE keyword indicates that bilinear 
interpolation is to be used, rather than the default near-
est-neighbor sampling. Pixels less than the value of 
TRANSPARENT are not drawn, simulating transparency.

Example

Fill a rectangular polygon that has the vertices 
(30,30), (100, 30), (100, 100), and (30, 100) in device 
coordinates. Create the vectors of X and Y values by 
entering:

X = [30, 100, 100, 30] & Y = [30, 30, 100, 100]

Fill the polygon with color index 175 by entering:

POLYFILL, X, Y, COLOR = 175

;-
;+
POLYFILLV

The POLYFILLV function returns a vector containing 
the one-dimensional subscripts of the array elements con-
tained inside a polygon defined by vectors X and Y.

If no points are contained within the polygon, a -1 is 
returned and an informational message is printed. The X 
and Y parameters are vectors that contain the subscripts 
of the vertices that define the polygon in the coordinate 
system of the two-dimensional Sx by Sy array. The Sx and Sy 
parameters define the number of columns and rows in the 
array enclosing the polygon. At least three points must be 
specified, and all points should lie within the limits: 0 
LE Xi < Sx and 0 LE Yi < Sy members of i.

 As with the POLYFILL procedure, the polygon is 
defined by connecting each point with its successor and 
the last point with the first. This function is useful for 
defining, analyzing, and displaying regions of interest 
within a two-dimensional array.

The scan line coordinate system defined by Rogers in 
Procedural Elements for Computer Graphics, McGraw-Hill, 
1985, page 71, is used. In this system, the scan lines are 
considered to pass through the center of each row of pix-
els. Pixels are activated if the center of the pixel is to 
the right of the intersection of the scan line and the 
polygon edge within the interval.

Calling Sequence

        Result = POLYFILLV(X, Y, Sx, Sy [, Run_Length])
        
Arguments

    X
    
        A vector containing the X subscripts of the ver-
        tices that define the polygon.
        
    Y
    
        A vector containing the Y subscripts of the ver-
        tices that define the polygon.
        
    Sx
    
        The number of columns in the array surrounding 
        the polygon.
        
    Sy
    
        The number of rows in the array surrounding the 
        polygon.
        
    Run_Length
    
        Set this optional parameter to a nonzero value 
        to make POLYFILLV return a vector of run lengths, 
        rather than subscripts. For large polygons, a con-
        siderable savings in space results. When run-length 
        encoded, each element with an even subscript result 
        contains the length of the run, and the following 
        element contains the starting index of the run.
        
Example

To determine the mean and standard deviation of the 
elements within a triangular region defined by the verti-
ces at pixel coordinates (100, 100), (200, 300), and (300, 
100), inside a 512 by 512 array called DATA, enter the 
commands:

P = DATA(POLYFILLV([100,200,300], [100,300,100], 512, 512))
Get the subscripts of the elements inside the 
triangle.

STD = STDEV(P,MEAN)	Use the STDEV User's Library function to 
obtain the mean and standard deviation of 
the selected elements.

;-
;+
POLYSHADE

The POLYSHADE function returns a shaded-surface rep-
resentation of one or more solids described by a set of 
polygons. This function accepts, as arguments, an array of 
three-dimensional vertices and a list of the indices of 
the vertices that describe each polygon. Output is a two-
dimensional byte array containing the shaded image unless 
the current graphics output device is the Z-buffer. If the 
current output device is the Z-buffer, the results are 
merged with the Z-buffer's contents and the function 
result contains a dummy value.

Shading values are determined from one of three 
sources: a light source model, a user-specified array con-
taining vertex shade values, or a user-specified array 
containing polygon shade values.

The shaded surface is constructed using the scan line 
algorithm. The default shading model is a combination of 
diffuse reflection and depth cueing. With this shading 
model, polygons are shaded using either constant shading, 
in which each polygon is given a constant intensity, or 
with Gouraud shading where the intensity is computed at 
each vertex and then interpolated over the polygon. Use 
the SET_SHADING procedure to control the direction of the 
light source and other shading parameters.

User-specified shading arrays allow "4-dimensional" 
displays that consist of a surface defined by a set of 
polygons, shaded with values from another variable.

Calling Sequence

        Result = POLYSHADE(Vertices, Polygons)
        
        or
        
        Result = POLYSHADE(X, Y, Z, Polygons)
        
Arguments

    Vertices
    
        A (3, n) array containing the X, Y, and Z coor-
        dinates of each vertex. Coordinates can be in either 
        data or normalized coordinates, depending on which 
        keywords are present.
        
    X, Y, Z
    
        The X, Y, and Z coordinates of each vertex can, 
        alternatively, be specified as three array expres-
        sions of the same dimensions.
        
    Polygons
    
        An integer or longword array containing the 
        indices of the vertices for each polygon. The verti-
        ces of each polygon should be listed in counter-
        clockwise order when observed from outside the 
        surface. The vertex description of each polygon is a 
        vector of the form: [n, i0, i1, ..., i(n-1)].
        
         and the array Polygons is the concatenation of 
        the lists of each polygon. For example, to render a 
        pyramid consisting of four triangles, Polygons would 
        contain 16 elements, made by concatenating four, 
        four-element vectors of the form [3, V0, V1, V2]. V0, 
        V1, and V2 are the indices of the vertices describing 
        each triangle.
        
Keywords

    DATA
    
        Set this keyword to indicate that the vertex 
        coordinates are in data units, the default coordi-
        nate system.
        
    NORMAL
    
        Set this keyword to indicate that coordinates 
        are in normalized units, within the three dimen-
        sional (0,1) cube.
        
    POLY_SHADES
    
        An array expression, with the same number of 
        elements as Polygons, containing the color index 
        used to render each polygon. No interpolation is 
        performed all pixels within a given polygon have the 
        same shade value. For most displays, this parameter 
        should be scaled into the range of bytes.
        
    SHADES
    
        An array expression, with the same number of 
        elements as Vertices, containing the color index at 
        each vertex. The shading of each pixel is interpo-
        lated from the surrounding SHADE values. For most 
        displays, this parameter should be scaled into the 
        range of bytes.
        
    T3D
    
        Set this keyword to use the three-dimensional to 
        two-dimensional transformation contained in the 
        homogeneous 4 by 4 matrix !P.T. Note that if T3D is 
        set, !P.T must contain a valid transformation 
        matrix. The SURFACE, SCALE3, and T3D procedures (and 
        others) can all be used to set up transformations.
        
    TOP
    
        The maximum shading value when light source 
        shading is in effect. The default value is one less 
        than the number of colors available in the currently 
        selected graphics device.
        
    XSIZE
    
        The number of columns in the output image array. 
        If this parameter is omitted, the number of columns 
        is equal to the X resolution of the currently 
        selected display device.
        
        Warning: The size parameters should be explic-
        itly specified when the current graphics device is 
        PostScript or any other high-resolution device. Mak-
        ing the output image the default full device size is 
        likely to cause an insufficient memory error.
        
    YSIZE
    
        The number of rows in the output image array. If 
        this parameter is omitted, the number of rows is 
        equal to the Y resolution of the currently selected 
        display device.
        
Example

POLYSHADE is often used in conjunction with 
SHADE_VOLUME for volume visualization. The following 
example creates a spherical volume dataset and renders an 
isosurface from that dataset:

SPHERE = FLTARR(20, 20, 20)	Create an empty, 3D array.

FOR X=0,19 DO FOR Y=0,19 DO FOR Z=0,19 DO $

       SPHERE(X, Y, Z) = SQRT((X-10)^2 + (Y-10)^2 + (Z-10)^2)

	Create the spherical dataset.

SHADE_VOLUME, SPHERE, 8, V, P	Find the vertices and polygons for a density 
level of 8.

SCALE3, XRANGE=[0,20], YRANGE=[0,20], ZRANGE=[0,20]
Set up an appropriate 3D transformation so 
we can see the sphere. This step is very 
important.

image = POLYSHADE(V, P, /T3D)	Render the image. Note that the T3D key-
word has been set so that the previously-
established 3D transformation is used.

TV, image	Display the image.

;-
;+
PRINT

The two PRINT procedures perform formatted output. 
PRINT performs output to the standard output stream (IDL 
file unit -1), while PRINTF requires a file unit to be 
explicitly specified.

Calling Sequence

        PRINT, Expr1, ..., Exprn
        
        or
        
        PRINTF, Unit, Expr1, ..., Exprn
        
Arguments

    Unit
    
        For PRINTF, Unit specifies the file unit to 
        which the output is sent.
        
    Expri
    
        The expressions to be output.
        
Keywords

    FORMAT
    
        If FORMAT is not specified, IDL uses its default 
        rules for formatting the output. FORMAT allows the 
        format of the output to be specified in precise 
        detail, using a FORTRAN-style specification. See 
        "Explicitly Formatted Input/Output" on page 17-15 of 
        the IDL User's Guide.
        
VMS Keywords

    REWRITE
    
        When writing data to a file with indexed organi-
        zation, set the REWRITE keyword to specify that the 
        data should update the contents of the most recently 
        input record instead of creating a new record.
        
Format Compatibility

If the FORMAT keyword is not present and PRINT is 
called with more than one argument, and the first argument 
is a scalar string starting with the characters "$(", this 
initial argument is taken to be the format specification, 
just as if it had been specified via the FORMAT keyword. 
This feature is maintained for compatibility with version 
1 of VMS IDL.

Example

To print the string "IDL is fun." enter the command:

PRINT, 'IDL is fun.'

To print the same message to the open file associated 
with file unit number 2, use the command:

PRINTF, 2, 'IDL is fun.'

;-
;+
RANDOMN

The RANDOMN function returns one or more normally-
distributed, floating-point, pseudo-random numbers with a 
mean of zero and a standard deviation of one.

Each normal value is obtained by summing 12 uniformly-
distributed, pseudorandom numbers and subtracting 6. RAN-
DOMN uses the uniform random number generator described 
under the description of RANDOMU.

Calling Sequence

        Result = RANDOMN(Seed [, D1, ..., Dn])
        
Arguments

    Seed
    
        A named variable containing the seed value for 
        random number generation. Seed is updated by RANDOMN 
        once for each random number generated. The initial 
        value of Seed should be set to different values in 
        order to obtain different random sequences. If the 
        named variable Seed is undefined, it is derived from 
        the system clock.
        
    Di
    
        The dimensions of the result. The dimension 
        parameters can be any scalar expression. Up to eight 
        dimensions can be specified. If no dimensions are 
        specified, RANDOMN returns a scalar result
        
Examples

Create a 10-element by 10-element array of normally-
distributed, random numbers by entering:

R = RANDOMN(seed, 10, 10)

Since seed is undefined, the system time is used to 
initialize the random number generator. Print the result-
ing values by entering:

PRINT, R

Note that some of the values are negative. Use the 
RANDOMU function to generate uniformly-distributed, posi-
tive values.

A more interesting example plots the probability 
function of 2000 numbers returned by RANDOMN. Enter:

PLOT, HISTOGRAM(RANDOMN(SEED, 2000), BINSIZE=0.1)

;-
;+
RANDOMU

The RANDOMU function returns one or more uniformly-
distributed, floating-point, pseudo-random numbers in the 
range 0 LE Y < 1.0.

The random number generator is taken from: "Random 
Number Generators: Good Ones are Hard to Find", Park and 
Miller, Communications of the ACM, Oct 1988, Vol 31, No. 
10, p. 1192.

Calling Sequence

        Result = RANDOMU(Seed [, D1, ..., Dn])
        
Arguments

    Seed
    
        A named variable containing the seed value for 
        random number generation. Seed is updated by RANDOMU 
        once for each random number generated. The initial 
        value of Seed should be set to different values in 
        order to obtain different random sequences. If Seed 
        is undefined, it is derived from the system clock.
        
    Di
    
        The dimensions of the result. The dimension 
        parameters can be any scalar expression. Up to eight 
        dimensions can be specified. If no dimensions are 
        specified, RANDOMU returns a scalar result
        
Example

This example simulates rolling two dice 10,000 times 
and plots the distribution of the total using RANDOMU. 
Enter:

PLOT, HISTOGRAM(FIX(6 * RANDOMU(S, 10000)) + $

  FIX(6 * RANDOMU(S, 10000)) + 2)

In the above statement, the expression RANDOMU(S, 
10000) is a 10,000-element, floating-point array of ran-
dom numbers greater than or equal to 0 and less than 1. 
Multiplying this array by 6 converts the range to 0 LE Y < 
6.

Applying the FIX function yields a 10,000-point inte-
ger vector with values from 0 to 5, one less than the num-
bers on one die. This computation is done twice, once for 
each die, then 2 is added to obtain a vector from 2 to 12, 
the total of two dice.

The HISTOGRAM function makes a vector in which each 
element contains the number of occurrences of dice rolls 
whose total is equal to the subscript of the element. 
Finally, this vector is plotted by the PLOT procedure.

;-
;+
READ

The READ procedures perform formatted input into 
variables.

READ performs input from the standard input stream 
(IDL file unit 0), while READF requires a file unit to be 
explicitly specified.

Calling Sequence

        READ, [Prompt,] Var1, ..., Varn
        
        or
        
        READF, [Prompt,] Unit, Var1, ..., Varn
        
Arguments

    Prompt
    
        Note that the PROMPT keyword should be used 
        instead of the Prompt argument for compatibility 
        with window-based versions of IDL.
        
        A string or explicit expression (i.e, not a 
        named variable) to be used as a prompt. This argu-
        ment should not be included if the FORMAT keyword is 
        specified. Also, if this argument begins with the 
        characters "$(", it is taken to be a format specifi-
        cation as described below under "Format Compatibil-
        ity".
        
        Using the Prompt argument does not work well 
        with IDL for Windows and IDL for Macintosh. The 
        desired prompt string is written to the log window 
        instead of the command input window. To create cus-
        tom prompts compatible with these versions of IDL, 
        use the PROMPT keyword, described below.
        
    Unit
    
        For READF, Unit specifies the file unit from 
        which the input is taken.
        
    Vari
    
        The named variables to receive the input.
        
Keywords

    FORMAT
    
        If FORMAT is not specified, IDL uses its default 
        rules for formatting the input. FORMAT allows the 
        format of the input to be specified in precise 
        detail, using a FORTRAN-style specification. See 
        "Explicitly Formatted Input/Output" on page 17-15 of 
        the IDL User's Guide.
        
    PROMPT
    
        Set this keyword to a scalar string to be used 
        as a customized prompt for the READ command. If the 
        PROMPT keyword or Prompt argument is not supplied, 
        IDL uses a colon followed by a space (": ") as the 
        input prompt.
        
VMS Keywords

        Note also that the obsolete VMS-only routine 
        READ_KEY has been replaced by the keywords below.
        
    KEY_ID
    
        The index key to be used (primary = 0, first 
        alternate key = 1, etc...) when accessing data from 
        a file with indexed organization. If this keyword is 
        omitted, the primary key is used.
        
    KEY_MATCH
    
        The relation to be used when matching the sup-
        plied key with key field values (EQ = 0, GE = 1, GT 
        = 2) when accessing data from a file with indexed 
        organization. If this keyword is omitted, the equal-
        ity relation (0) is used.
        
    KEY_VALUE
    
        The value of a key to be found when accessing 
        data from a file with indexed organization. This 
        value must match the key definition that is deter-
        mined when the file was created in terms of type and 
        size-no conversions are performed. If this keyword 
        is omitted, the next sequential record is used.
        
Format Compatibility

If the FORMAT keyword is not present and READ is 
called with more than one argument, and the first argument 
is a scalar string starting with the characters "$(", this 
initial argument is taken to be the format specification, 
just as if it had been specified via the FORMAT keyword. 
This feature is maintained for compatibility with version 
1 of VMS IDL.

Example

To read a string value into the variable B from the 
keyboard, enter:

B = ''	Define B as a string before reading.

READ, B, PROMPT='Enter Name: '	Read input from the terminal.

To read formatted data from the previously-opened 
file associated with logical unit number 7 into variable 
C, use the command:

READF, 7, C

;-
;+
READ_JPEG

The READ_JPEG procedure reads JPEG (Joint Photo-
graphic Experts Group) format compressed images from 
files or memory. JPEG is a standardized compression method 
for full-color and gray-scale images. This procedure 
reads JFIF format files (often called "JPEG" files), 
including those produced by WRITE_JPEG.

READ_JPEG can optionally quantize true-color images 
contained in files to a pseudo-color palette with a spec-
ified number of colors, and with optional color dithering.

This procedure is based in part on the work of the 
"Independent JPEG Group". For a brief explanation of JPEG, 
consult the description of the WRITE_JPEG procedure (page 
-367). 

Calling Sequence

        READ_JPEG, [Filename,] Image [,Colortable]
        
Arguments

    Filename
    
        A string containing the name of the JFIF format 
        (JPEG) file to be read. If this parameter is not 
        present, the UNIT and/or the BUFFER keywords must be 
        specified.
        
    Image
    
        A named variable to receive the image.
        
    Colortable
    
        A named variable to receive the colormap, when 
        reading a true-color image that is to be quantized. 
        On completion, this variable contains a byte array 
        with dimensions (COLORS, 3).
        
Keywords

    BUFFER
    
        Set this keyword to a named variable that is 
        used for a buffer. A buffer variable need only be 
        supplied when reading multiple images per file. Ini-
        tialize the buffer variable to empty by setting it 
        to 0. Example:
        
        buff = 0	Initialize buffer.
        
        OPENR, 1, 'images.jpg', /STREAM
        
        FOR i=1, nimages DO BEGIN	Process each image.
        
        READ_JPEG, UNIT=1, BUFFER=buff, a		Read next image.
        
        TV, a	Display the image.
        
        ENDFOR
        
        CLOSE, 1	Done.
        
    COLORS
    
        If the image file contains a true-color image 
        which must be displayed on an 8-bit display, set 
        COLORS to the desired number of colors to be quan-
        tized. COLORS can be set to a value from 8 to 256. 
        The DITHER and TWO_PASS_QUANTIZE keywords affect the 
        method, speed, and quality of the color quantiza-
        tion. These keywords have no effect if the file con-
        tains a grayscale image.
        
    DITHER
    
        Set this keyword to use dithering with color 
        quantization (i.e., if the COLORS keyword is in 
        use). Dithering is a method that distributes the 
        color quantization error to surrounding pixels, to 
        achieve higher-quality results.
        
    ORDER
    
        JPEG/JFIF images are normally written in top-to-
        bottom order. If the image is to be stored into the 
        Image array in the standard IDL order (from bottom-
        to-top) set ORDER to 0. This is the default. If the 
        image array is to be top-to-bottom order, ORDER must 
        be set to 1.
        
    TRUE
    
        Use this keyword to specify the index of the 
        dimension for color interleaving when reading a 
        true-color image. The default is 1, for pixel inter-
        leaving, (3,m,n). A value of 2 indicates line inter-
        leaving (m,3,n), and 3 indicates band interleaving, 
        (m,n,3).
        
    TWO_PASS_QUANTIZE
    
        Set this keyword to use a two-pass color quanti-
        zation method when quantization is in effect (i.e., 
        the COLORS keyword is in use). This method requires 
        more memory and time, but produces superior results 
        to the default one-pass quantization method. 
        
    UNIT
    
        This keyword can be used to designate the logi-
        cal unit number of an already open JFIF file, allow-
        ing the reading of multiple images per file or the 
        embedding of JFIF images in other data files.
        
        When using this keyword, Filename should not be 
        specified.
        
        READ_JPEG buffers its input data. To read multi-
        ple images per file, see the BUFFER keyword. When 
        using VMS, open the file with the /STREAM keyword.
        
Examples

Read and display a JPEG grayscale image:

READ_JPEG, 'test.jpg', a	Read the image.

TV, a	Display the image.

Read and display a JPEG true-color image on a true-
color display:

READ_JPEG, 'test.jpg', a, TRUE=1	Read the image.

TV, a, TRUE=1	Display the image returned with pixel inter-
leaving (i.e., with dimensions 3, m, n).

Read and display a JPEG true-color image on a 8-bit 
pseudo-color display: 

READ_JPEG, 'test.jpg', a, ctable, COLORS=!D.N_COLORS-1
Read the image, setting the number of colors 
to be quantized to the maximum number of 
available colors. Note that we could have 
also included the TWO_PASS_QUANTIZE 
and DITHER keywords to improve the 
image's appearance.

TV, a	Display the image.

TVLCT, ctable	Load the quantized colortable.

;-
;+
READS

The READS procedure performs formatted input from a 
string variable and writes the results into one or more 
output variables. This procedure differs from the READ 
procedure only in that the input comes from memory instead 
of a file.

This routine is useful when you need to examine the 
format of a data file before reading the information it 
contains. Each line of the file can be read into a string 
using READF. Then the components of that line can be read 
into variables using READS.

Calling Sequence

        READS, Input, Var1, ..., Varn
        
Arguments

    Input
    
        The string variable from which the input is 
        taken. If the supplied argument is not a string, it 
        is automatically converted. The argument can be sca-
        lar or array. If Input is an array, the individual 
        string elements are treated as successive lines of 
        input.
        
    Vari
    
        The named variables to receive the input.
        
Keywords

    FORMAT
    
        If FORMAT is not specified, IDL uses its default 
        rules for formatting the input. FORMAT allows the 
        format of the input to be specified in precise 
        detail, using a FORTRAN-style specification. See 
        "Explicitly Formatted Input/Output" on page 17-15 of 
        the IDL User's Guide.
        
;-
;+
READU

The READU procedure reads unformatted binary data 
from a file into IDL variables. READU transfers data 
directly with no processing of any kind performed on the 
data.

Calling Sequence

        READU, Unit, Var1, ..., Varn
        
Arguments

    Unit
    
        The IDL file unit from which input is taken.
        
    Vari
    
        Named variables to receive the data. For non-
        string variables, the number of bytes required for 
        Var are read. When READU is used with a variable of 
        type string, IDL reads exactly the number of bytes 
        contained in the existing string. For example, to 
        read a 5-character string, enter:
        
        temp = '12345'
        
        READU, unit, temp
        
Unix Keywords

    TRANSFER_COUNT
    
        Set this keyword to a named variable in which to 
        return the number of elements transferred by the 
        input operation. Note that the number of elements is 
        not the same as the number of bytes (except in the 
        case where the data type being transferred is 
        bytes). For example, transferring 256 floating-point 
        numbers yields a transfer count of 256, not 1024 
        (the number of bytes transferred).
        
        This keyword is useful with files opened with 
        the NOSTDIO keyword to the OPEN routines. Normally, 
        attempting to read more data than is available from 
        a file causes the unfilled space to be zeroed and an 
        error to be issued. This does not happen with files 
        opened with the NOSTDIO keyword. Instead, the pro-
        grammer must keep track of the transfer count.
        
VMS Keywords

        Note that the obsolete VMS routines FORRD, and 
        FORRD_KEY have been replaced by the READU command 
        used with the following keywords.
        
    KEY_ID
    
        The index key to be used (primary = 0, first 
        alternate key = 1, etc...) when accessing data from 
        a file with indexed organization. If this keyword is 
        omitted, the primary key is used.
        
    KEY_MATCH
    
        The relation to be used when matching the sup-
        plied key with key field values (EQ = 0, GE = 1, GT 
        = 2) when accessing data from a file with indexed 
        organization. If this keyword is omitted, the equal-
        ity relation (0) is used.
        
    KEY_VALUE
    
        The value of a key to be found when accessing 
        data from a file with indexed organization. This 
        value must match the key definition that is deter-
        mined when the file was created in terms of type and 
        size-no conversions are performed. If this keyword 
        is omitted, the previous key value is used.
        
Example

The following commands can be used to open the IDL 
distribution file people.dat and read an image from that 
file:

OPENR, 1, FILEPATH('people.dat', SUBDIR='images')
Open the file for reading as file unit 1.

B = BYTARR(192, 192)	The image we want to read is a 192 by 192 
byte array, so make B that size.

READU, 1, B	Read the data into B.

CLOSE, 1	Close the file.

TV, B	Display the image.

;-
;+
REBIN

The REBIN function resizes a vector or array to dimen-
sions given by the parameters Di. The supplied dimensions 
must be integral multiples or factors of the original 
dimension. The expansion or compression of each dimension 
is independent of the others, so that each dimension can 
be expanded or compressed by a different value.

If the dimensions of the desired result are not inte-
ger multiples of the original dimensions, use the CONGRID 
Users' Library function.

Calling Sequence

        Result = REBIN(Array, D1, ..., Dn)
        
Arguments

    Array
    
        The array to be resampled. Array can be of any 
        basic type except complex or string.
        
    Di
    
        The dimensions of the resulting resampled array. 
        These dimensions must be integer multiples or fac-
        tors of the corresponding original dimensions.
        
Keywords

    SAMPLE
    
        Normally, REBIN uses bilinear interpolation when 
        magnifying and neighborhood averaging when minify-
        ing. Set the SAMPLE keyword to use nearest neighbor 
        sampling for both magnification and minification. 
        Bilinear interpolation gives higher quality results 
        but requires more time.
        
Endpoint Effects When Expanding

When expanding an array, REBIN interpolates, it never 
extrapolates. Each of the n-1 intervals in the n-element 
input array produces m/n interpolates in the m-element 
output array. The last m/n points of the result are 
obtained by duplicating element n-1 of the input array 
because their interpolates would lie outside the input 
array.

For example

A = [0, 10, 20, 30]	A four point vector.

B = REBIN(A, 12)	Expand by a factor of 3.

PRINT, B

0 3 6 10 13 16 20 23 26 30 30 30

Note that the last element is repeated three times. If 
this effect is undesirable, use the INTERPOLATE function. 
For example, to produce 12 equally spaced interpolates 
from the interval 0 to 3:

B = INTERPOLATE(A, 3./11. * FINDGEN(12))

PRINT, B

0 2 5 8 10 13 16 19 21 24 27 30

Here, the sampling ratio is (n - 1)/(m - 1).

Example

Create and display a simple image by entering:

D = SIN(DIST(50)/4) & TVSCL, D

Resize the image to be 5 times its original size and 
display the result by entering:

D = REBIN(D, 250, 250) & TVSCL, D

;-
;+
REFORM

The REFORM function changes the dimensions of an array 
without changing the total number of elements. If no 
dimensions are specified, REFORM returns a copy of Array 
with all leading dimensions of size 1 removed. If dimen-
sions are specified, the result is given those dimensions. 
Only the dimensions of Array are changed-the actual data 
remains unmodified.

Calling Sequence

        Result = REFORM(Array, D1, ..., Dn)
        
Arguments

    Array
    
        The array to have its dimensions modified.
        
    Di
    
        The dimensions of the result. The Di arguments 
        can be either a single array containing the new 
        dimensions or a sequence of scalar dimensions. Array 
        must have the same number of elements as specified 
        by the product of the new dimensions.
        
Keywords

    OVERWRITE
    
        Set this keyword to cause the specified dimen-
        sions to overwrite the present dimensions of the 
        Array parameter. No data are copied, only the inter-
        nal array descriptor is changed. The result of the 
        function, in this case, is the Array parameter with 
        its newly-modified dimensions. For example, to 
        change the dimensions of the variable a, without 
        moving data, enter:
        
        a = REFORM(a, n1, n2, /OVERWRITE)
        
Example

REFORM can be used to remove "degenerate" leading 
dimensions of size one. Such dimensions can appear when a 
subarray is extracted from an array with more dimensions. 
For example

a = INTARR(10,10,10)	a is a 3-dimensional array.

b = a(5,*,*)	Extract a "slice" from a.

HELP, b, REFORM(b)	Use HELP to show what REFORM does.

Executing the above statements produces the output:

B            INT = Array(1, 10, 10)

<Expression> INT = Array(10, 10)

The statements:

b = REFORM(a,200,5)

b = REFORM(a,[200,5])

have identical effect. They create a new array, b, 
with dimensions of (200, 5), from a.

;-
;+
REPLICATE

The REPLICATE function returns an array with the given 
dimensions, filled with the scalar value specified as the 
first parameter.

Calling Sequence

        Result = REPLICATE(Value, D1 [, ..., Dn])
        
Arguments

    Value
    
        The scalar value with which to fill the result-
        ing array. The type of the result is the same as 
        that of Value. Value can be of any scalar type, 
        including scalar structures.
        
    Di
    
        The dimensions of the result.
        
Example

Create D, a 5-element by 5-element array with every 
element set to the string "IDL" by entering:

D = REPLICATE('IDL', 5, 5)

REPLICATE can also be used to create arrays of struc-
tures. For example, the following command creates a struc-
ture named "emp" that contains a string name field and a 
long integer employee ID field:

employee = {emp, NAME:' ', ID:0L}

To create a 10-element array of this structure, enter:

emps = REPLICATE(employee, 10)

;-
;+
RESTORE

The RESTORE procedure restores the IDL objects saved 
in a file by the SAVE procedure. If RESTORE is used in an 
IDL procedure (i.e., at any level other than the main pro-
gram level), any variables that are to be restored must be 
defined prior to the call to RESTORE.

Calling Sequence

        RESTORE [, Filename]
        
Arguments

    Filename
    
        A scalar string that contains the name of the 
        file from which the IDL objects should be restored. 
        If not present, the file idlsave.dat is used.
        
Keywords

    FILENAME
    
        The name of the file from which the IDL objects 
        should be restored. If not present, the file idl-
        save.dat is used. This keyword serves exactly the 
        same purpose as the Filename argument-only one of 
        them needs to be provided.
        
    VERBOSE
    
        Set this keyword to have IDL print an informa-
        tive message for each restored object.
        
Example

Suppose that you have saved all the variables from a 
previous IDL session with the command:

SAVE, /VARIABLES, FILENAME = 'session1.sav'

The variables in the file session1.sav can be restored 
by entering:

RESTORE, 'session1.sav'

;-
;+
REWIND (VMS Only)

The REWIND procedure rewinds the tape on the desig-
nated IDL tape unit. See the description of the magnetic 
tape routines in Chapter 17 of the IDL User's Guide.

Calling Sequence

        REWIND, Unit
        
Arguments

    Unit
    
        The magnetic tape unit to rewind. Unit must be a 
        number between 0 and 9, and should not be confused 
        with standard file Logical Unit Numbers (LUNs).
        
;-
;+
RIEMANN

The RIEMANN procedure computes the "Riemann sum" (or 
its inverse) which helps implement the backprojection 
operator used to reconstruct the cross-section of an 
object, given projections through the object from multi-
ple directions. This technique is widely used in medical 
imaging in the fields of Computed x-ray tomography, MRI 
imaging, Positron Emission Tomography (PET), and also has 
applications in other areas such as seismology and astron-
omy. The inverse Riemann sum, which evaluates the projec-
tions given a slice through an object, is also a discrete 
approximation to the Radon transform. 

Given a matrix A(m,n), which will contain the recon-
structed slice; a vector P, containing the ray sums for a 
given view; and an angle Theta measured in radians from 
the vertical: the Riemann sum "backprojects" the vector P 
into A. For each element of A, the value of the closest 
element of P is summed, leaving the result in A. Bilinear 
interpolation is an option. All operations are performed 
in single precision floating point.

In the reverse operation, the ray sums contained in 
the view vector, P, are computed given the original slice, 
A, and Theta. This is sometimes called "front projection". 

The Riemann sum can be written: 

Sum from i=0 to M-1 of A(r*cos(delta - theta), i * 
delta)

which is the sum of the data along lines through an 
image with an angle of theta from the vertical.

Calling Sequence

        RIEMANN, P, A, Theta
        
Arguments

    P
    
        A k-element floating-point projection vector (or 
        matrix if the ROW keyword is specified). For back-
        projection (when the BACKPROJECT keyword is set), P 
        contains the ray sums for a single view. For the 
        inverse operation, P should contain zeros on input 
        and will contain the ray sums for the view on out-
        put.
        
    A
    
        An m by n floating-point image matrix. For back-
        projection, A contains the accumulated results. For 
        the inverse operation, A contains the original 
        image. Typically, k should be larger than sqrt(m^2 + 
        n^2), which is the diagonal size of A. 
        
    Theta
    
        The angle of the ray sums from the vertical.
        
Keywords

    BACKPROJECT
    
        Set this keyword to perform backprojection in 
        which P is summed into A. If this keyword is not 
        set, the inverse operation occurs and the ray sums 
        are accumulated into P.
        
    BILINEAR
    
        Set this keyword to use bilinear interpolation 
        rather than the default nearest neighbor sampling. 
        Results are more accurate but slower when bilinear 
        interpolation is used. 
        
    D
    
        Use this keyword to specify the spacing between 
        elements of P, expressed in the same units as the 
        spacing between elements of A. The default is 1.0.
        
    ROW
    
        Set this keyword to specify the P vector as a 
        given row within a matrix, so that the sinogram 
        array can be used directly without having to extract 
        or insert each row. In this case, P must be a (k, 
        Views) array, and the value of ROW must be in the 
        range of 0 to Nviews-1. 
        
Example

This example forms a synthetic image in A, computes 
Nviews equally spaced views, and stores the stacked pro-
jections (commonly called the "sinogram") in a matrix PP. 
It then backprojects the projections into the matrix B, 
forming the reconstructed slice. In practical use, the 
projections are convolved with a filter before being back-
projected. 

N = 100L	Define number of columns in A.

M = 100L	Define number of rows in A.

nviews = 100	Number of views.

K = CEIL(SQRT(N^2 + M^2))	The length of the longest projection. If fil-
tered backprojection is used, 1/2 the length 
of the convolution kernel must also be added.

A = FLTARR(N, M)	Form original slice.

A(N/2:N/2+5, M/2:M/2+5) = 1.0	Simulate a square object.

pp = FLTARR(K, nviews)	Make array for sinogram.

FOR I=0, NVIEWS-1 DO RIEMANN, pp, A, I * !PI/nviews, ROW=i
Compute each view.

TVSCL, pp	Show sinogram.

B = FLTARR(N,M)	Initial reconstructed image.

FOR I=0, nviews-1 DO $	Do the backprojection for each view.

  RIEMANN, pp, B, I * !PI/nviews, /BACKPROJECT, ROW=i

TVSCL, B	Show reconstructed array.

;-
;+
ROBERTS

The ROBERTS function returns an approximation to the 
Roberts edge enhancement operator for images.which is a 
simple, two-dimensional differencing method for edge-
sharpening and isolation. The result of this function is a 
two-dimensional array of integer type, with the same 
dimensions as Image.

Calling Sequence

        Result = ROBERTS(Image)
        
Arguments

    Image 
    
        The two-dimensional array containing the image 
        to which edge enhancement is applied.
        
Example

If the variable IM contains a two-dimensional image 
array, a Roberts sharpened version of IM can be displayed 
with the command:

TVSCL, ROBERTS(IM)

;-
;+
ROTATE

The ROTATE function returns a rotated and/or trans-
posed copy of Matrix. ROTATE can only rotate arrays in 
multiples of 90 degrees. To rotate by amounts other than 
multiples of 90 degrees, use the IDL Users' Library func-
tion ROT. Note, however, that ROTATE is more efficient.

ROTATE can also be used to reverse the order of ele-
ments in vectors. For example, to reverse the order of 
elements in the vector X, use the expression ROTATE(X,2). 
If X = [0,1,2,3] then ROTATE(X,2)yields the resulting 
array, [3,2,1,0].

Transposition is performed before rotation. Rotations 
are viewed with the first row at the top.

Calling Sequence

        Result = ROTATE(Matrix, Direction)
        
Arguments

    Matrix
    
        The array to be rotated. Matrix can have only 
        one or two dimensions. The result has the same type 
        as Matrix. The dimensions of the result are the same 
        as those of Matrix if Direction is equal to 0 or 2. 
        The dimensions are transposed if the direction is 4 
        or greater.
        
    Direction
    
    Direction specifies the operation to be performed as 
    follows:Direction  Transpose?  Rot. CCW  X1  Y1
    ----------------------------------------
    0          No          None     X0  Y0
    1          No          90      -Y0  X0
    2          No          180     -X0 -Y0
    3          No          270      Y0 -X0
    4          Yes         None     Y0  X0
    5          Yes         90      -X0  Y0
    6          Yes         180     -Y0 -X0
    7          Yes         270      X0 -Y0
    
    
    
        In the table above, (X0, Y0) are the original 
        subscripts, and (X1, Y1) are the subscripts of the 
        resulting array. The notation -Y0 indicates a rever-
        sal of the Y axis, Y1 = Ny - Y0 - 1. Direction is 
        taken modulo 8, so a rotation of -1 is the same as 7, 
        9 is the same as 1, etc.
        
Example

Create and display a wedge image by entering:

F = REPLICATE(1, 256) # FINDGEN(256) & TVSCL, F

To display the image rotated 90 degrees counterclock-
wise, enter:

TVSCL, ROTATE(F, 1)

;-
;+
ROUND

The ROUND function returns the integer closest to its 
argument. This value is returned as a longword integer 
with the same structure as the input argument..

Calling Sequence

        Result = ROUND(X)
        
Arguments

    X
    
        The value for which the ROUND function is to be 
        evaluated. This value can be of floating-point, dou-
        ble-precision floating-point, or complex type. ROUND 
        returns a longword integer with the same structure 
        as X.
        
Example

To print the rounded values of a 2-element vector, 
enter:

PRINT, ROUND([5.1, 5.9])

IDL prints:

     5      6



;-
;+
SAVE

The SAVE procedure saves variables and system vari-
ables in a file for later recovery by RESTORE.

Calling Sequence

        SAVE [, Var1, ..., Varn]
        
Arguments

    Varn
    
        Optional named variables that are to be saved.
        
Keywords

    ALL
    
        Set this keyword to save all aspects of the cur-
        rent IDL session (common blocks, system variables, 
        and local variables).
        
    COMM
    
        Set this keyword to save all main level common 
        block definitions. Note that setting this keyword 
        does not cause the contents of the common block to 
        be saved unless the VARIABLES keyword is also set.
        
    FILENAME
    
        A string containing the name of the file into 
        which the IDL objects should be saved. If this key-
        word is not specified, the file idlsave.dat is used.
        
    ROUTINES
    
        Set this keyword to save user defined procedures 
        and functions in a machine independent, binary form. 
        If parameters are present, they must be strings con-
        taining the names of the procedures and/or functions 
        to be saved. If no parameters are present, all com-
        piled routines are saved. If you are using VMS, see 
        the XDR keyword below. Warning: save files contain-
        ing routines are not guaranteed to be compatible 
        between successive versions of IDL.
        
    SYSTEM_VARIABLES
    
        Set this keyword to save the current state of 
        all system variables.
        
        Caution: Saving system variables is not recom-
        mended, as the structure may change between 
        releases, making the SAVE/RESTORE files incompati-
        ble.
        
    VARIABLES
    
        Set this keyword to save all variables in the 
        current program unit. This option is the default.
        
    VERBOSE
    
        Set this keyword to print an informative message 
        for each saved object.
        
    XDR
    
        Set this keyword to save the file in a portable 
        format using XDR (eXternal Data Representation). 
        Under operating systems other than VMS, XDR is the 
        only supported format, and this keyword is unneces-
        sary. Under VMS, the default is a VAX-specific for-
        mat which is more efficient to process. Use XDR 
        under VMS to interchange data with other versions of 
        IDL.
        
Example

Save the status of all currently-defined variables in 
the file variables1.dat by entering:

SAVE, /VARIABLES, FILENAME = 'variables1.dat'

The variables can be restored with the RESTORE proce-
dure. Save the user procedures MYPROC and MYFUN:

SAVE, /ROUTINES, 'MYPROC', 'MYFUN'

;-
;+
SET_PLOT

The SET_PLOT procedure sets the output device used by 
the IDL graphics procedures. Keyword parameters control 
how the color tables are transferred to the newly selected 
graphics device. SET_PLOT performs the following actions:

    It sets the read-only system variable !D to 
    reflect the configuration of the new device.
    
    It sets the default color !P.COLOR to the maxi-
    mum color index minus one or, in the case of devices 
    with white backgrounds, such as PostScript, to 0 
    (black).
    
    If the COPY keyword is set, the device color 
    tables are copied directly from IDL's internal color 
    tables. If the new device's color tables contain 
    more indices than those of the old device, the new 
    device's tables are not completely filled.
    
    If the INTERPOLATE keyword is set, the internal 
    color tables are interpolated to fill the range of 
    the new device.
    
    It sets the clipping rectangle to the entire 
    device surface.
    
Warnings: After calling SET_PLOT to change graphics 
devices, the scaling contained in the axis structures !X, 
!Y, and !Z is invalid. Any routines that rely on data 
coordinates should not be called until a new data coordi-
nate system has been established. Be careful when switch-
ing devices as the number of color indices frequently 
differs between devices. When in doubt, reload the color 
table of the new device explicitly. See "Color Tables" on 
page 16-6 of the IDL User's Guide.

Calling Sequence

        SET_PLOT, Device
        
Arguments

    Device
    
        A scalar string containing the name of the 
        device to use. The names of supported devices are 
        shown in the table below. The case of Device is 
        ignored by IDL.Valid devices are: CGM, HP, LJ, NULL, 
        PCL, PS, REGIS, SUN, TEK, X, and Z.
        
Keywords

    COPY
    
        Set this keyword to copy the device's color 
        table from the internal color table, preserving the 
        current color mapping. The default is not to load 
        the color table upon selection.
        
        Warning: Unless this keyword is set, IDL's 
        internal color tables will incorrectly reflect the 
        state of the device's color tables until they are 
        reloaded by TVLCT or the LOADCT User's Library pro-
        cedure. Assuming that the previously-selected 
        device's color table contains M elements, and the 
        new device's color table contains N elements, then 
        the minimum of M and N elements are loaded.
        
    INTERPOLATE
    
        Set this keyword to indicate that the current 
        contents of the internal color table should be 
        interpolated to cover the range of the newly-
        selected device. Otherwise, the internal color 
        tables are not changed.
        
Example

Change the IDL graphics device to PostScript by enter-
ing:

SET_PLOT, 'PS'

After changing the plotting device, all graphics com-
mands are sent to that device until changed again by 
another use of the SET_PLOT routine.

;-
;+
SET_SHADING

The SET_SHADING procedure modifies the light source 
shading parameters that affect the output of SHADE_SURF 
and POLYSHADE. Parameters can be changed to control the 
light-source direction, shading method, and the rejection 
of hidden surfaces. SET_SHADING first resets the shading 
parameters to their default values. The parameter values 
specified in the call then overwrite the default values. 
To reset all parameters to their default values, simply 
call this procedure with no parameters.

Calling Sequence

        SET_SHADING
        
Arguments

        None.
        
Keywords

    GOURAUD
    
        This keyword controls the method of shading the 
        surface polygons by the POLYSHADE procedure. The 
        SHADE_SURF procedure always uses the Gouraud method. 
        Set this keyword to a nonzero value (the default), 
        to use Gouraud shading. Set this keyword to zero to 
        shade each polygon with a constant intensity.
        
        Gouraud shading interpolates intensities from 
        each vertex along each edge. Then, when scan con-
        verting the polygons, the shading is interpolated 
        along each scan line from the edge intensities. 
        Gouraud shading is slower than constant shading but 
        usually results in a more realistic appearance.
        
    LIGHT
    
        A three-element vector that specifies the direc-
        tion of the light source. The default light source 
        vector is [0,0,1], with the light rays parallel to 
        the Z axis.
        
    REJECT
    
        Set this keyword (the default) to reject poly-
        gons as being hidden if their vertices are ordered 
        in a clockwise direction as seen by the viewer. This 
        keyword should always be set when rendering enclosed 
        solids whose original vertex lists are in counter-
        clockwise order. When rendering surfaces that are 
        not closed or are not in counterclockwise order this 
        keyword can be set to zero although shading anoma-
        lies at boundaries between visible and hidden sur-
        faces may occur.
        
    VALUES
    
        A two-element array that specifies the range of 
        pixel values (color indices) to use. The first ele-
        ment is the color index for the darkest pixel. The 
        second element is the color index for the brightest 
        pixel. For example, to render a shaded surface with 
        the darkest shade set to pixel value 100 and the 
        brightest value set to 150, use the commands:
        
        SET_SHADING, VALUES=[100, 150]
        
        SHADE_SURF, dataset
        
Example

Change the light source so that the light rays are 
parallel to the X axis:

SET_SHADING, LIGHT = [1, 0, 0]

;-
;+
SET_SYMBOL (VMS Only)

The SET_SYMBOL procedure defines a DCL (Digital Com-
mand Language) interpreter symbol for the current pro-
cess.

Calling Sequence

        SET_SYMBOL, Name, Value
        
Arguments

    Name 
    
        A scalar string containing the name of the sym-
        bol to be defined.
        
    Value
    
        A scalar string containing the value with which 
        Name is defined.
        
Keywords

    TYPE
    
        Indicates the table into which Name will be 
        defined. Setting TYPE to 1 specifies the local sym-
        bol table, while a value of 2 specifies the global 
        symbol table. The default is the local table.
        
;-
;+
SETENV (Unix Only)

The SETENV procedure adds or changes an environment 
string in the process environment.

Calling Sequence

        SETENV, Environment_Expression
        
Arguments

    Environment_Expression
    
        A scalar string containing an environment 
        expression to be added to the environment.
        
Example

Change the current shell variable by entering:

SETENV,'SHELL=/bin/sh'

;-
;+
SETLOG (VMS Only)

The SETLOG procedure defines a logical name.

Calling Sequence

        SETLOG, Lognam, Value
        
Arguments

    Lognam
    
        A scalar string containing the name of the logi-
        cal to be defined.
        
    Value
    
        A string containing the value to which the logi-
        cal will be set. If Value is a string array, Lognam 
        is defined as a multi-valued logical where each ele-
        ment of Value defines one of the equivalence 
        strings.
        
Keywords

    CONCEALED
    
        If this keyword is set, RMS (VMS Record Manage-
        ment Services) interprets the equivalence name as a 
        device name.
        
    CONFINE
    
        If this keyword is set, the logical name is not 
        copied from the IDL process to its spawned subpro-
        cesses.
        
    NO_ALIAS
    
        If this keyword is set, the logical name cannot 
        be duplicated in the same logical table at an outer 
        access mode. If another logical name with the same 
        name already exists at an outer access mode, it is 
        deleted. See the VMS System Services Manual for 
        additional information on logical names and access 
        modes.
        
    TABLE
    
        A scalar string containing the name of the logi-
        cal table from which to delete Lognam. If TABLE is 
        not specified, LNM$PROCESS_TABLE is used.
        
    TERMINAL
    
        If this keyword is set, when attempting to 
        translate the logical, further iterative logical 
        name translation on the equivalence name is not to 
        be performed.
        
;-
;+
SHADE_SURF

The SHADE_SURF procedure creates a shaded-surface 
representation of a regular or nearly-regular gridded 
surface with shading from either a light source model or 
from a user-specified array of intensities.

This procedure and its parameters are similar to SUR-
FACE. Given a regular or near-regular grid of elevations 
it produces a shaded-surface representation of the data 
with hidden surfaces removed. If the graphics output 
device has scalable pixels, the output image is scaled so 
that its largest dimension is less than or equal to 512. 
When outputting to a device that prints black on a white 
background, (e.g., PostScript), pixels that contain the 
background color index of 0 are set to white. Use the 
SET_SHADING procedure to control the direction of the 
light source and other shading parameters.

Restrictions

If the (X, Y) grid is not regular or nearly regular, 
errors in hidden line removal will occur. If the T3D key-
word is set, the 3D to 2D transformation matrix contained 
in !P.T must project the Z axis to a line parallel to the 
device Y axis, or errors will occur. The User's Library 
routine SHADE_SURF_IRR can be used to render many datasets 
that do not meet these requirements. Irregularly-gridded 
data can also be made interpolated to a regular grid using 
the TRIGRID and TRIANGULATE routines.

Calling Sequence

        SHADE_SURF, Z [, X, Y]
        
Arguments

    Z
    
        A two-dimensional array that contains the values 
        that make up the surface. See the description of 
        SURFACE for details.
        
        This argument is converted to single-precision 
        floating-point before plotting. Plots created with 
        SHADE_SURF are limited to the range and precision of 
        single-precision floating-point values.
        
    X
    
        An optional vector or two-dimensional array that 
        specifies the X coordinates of the grid. Again, see 
        the description of SURFACE for details.
        
    Y
    
        An optional vector or two-dimensional array that 
        specifies the Y coordinates of each elevation.
        
Keywords

    AX
    
        This keyword specifies the angle of rotation, 
        about the X axis, in degrees towards the viewer. 
        This keyword is effective only if !P.T3D and the T3D 
        keyword are not set. If !P.T3D is set, the three-
        dimensional to two-dimensional transformation used 
        by SURFACE is contained in the 4 by 4 array !P.T.
        
        The surface represented by the two-dimensional 
        array is first rotated, AZ (see below) degrees about 
        the Z axis, then by AX degrees about the X axis, 
        tilting the surface towards the viewer (AX > 0), or 
        away from the viewer.
        
        The AX and AZ keyword parameters default to +30 
        degrees if omitted.
        
        The three-dimensional to two-dimensional trans-
        formation represented by AX and AZ, can be saved in 
        !P.T by including the SAVE keyword.
        
    AZ
    
        This keyword specifies the counterclockwise 
        angle of rotation about the Z axis. This keyword is 
        effective only if !P.T3D is not set. The order of 
        rotation is AZ first, then AX.
        
    IMAGE
    
        A named variable into which an image containing 
        the shaded surface is stored. If this keyword is 
        omitted, the image is displayed but not saved.
        
    MAX_VALUE
    
        The largest data value to be plotted. Data 
        larger than this value are treated as missing data 
        and are not plotted.
        
    PIXELS
    
        Use this keyword to specify a two-element vector 
        [width, height] that will control the resolution, in 
        pixels, of the image. PIXELS only applies when the 
        output device uses scalable pixels (the PostScript 
        device, for example).
        
    SAVE
    
        Set this keyword to save the 3D to 2D transfor-
        mation matrix established by SHADE_SURF in the sys-
        tem variable field !P.T. Use this keyword when 
        combining the output of SHADE_SURF with the output 
        of other routines in the same plot.
        
    SHADES
    
        An array expression, of the same dimensions as 
        Z, that contains the color index at each point. The 
        shading of each pixel is interpolated from the sur-
        rounding SHADE values. If this parameter is omitted, 
        light-source shading is used. For most displays, 
        this parameter should be scaled into the range of 
        bytes.
        
    XTYPE
    
        Set this keyword to specify a logarithmic X 
        axis.
        
    YTYPE
    
        Set this keyword to specify a logarithmic Y 
        axis.
        
Graphics Keywords Accepted

        See Chapter 2, Graphics Keywords and System 
        Variables, for the description of graphics and plot-
        ting keywords not listed above. CHANNEL CHARSIZE 
        CHARTHICK CLIP COLOR DATA DEVICE FONT NOCLIP NODATA 
        NOERASE NORMAL POSITION SUBTITLE T3D THICK TICKLEN 
        TITLE XCHARSIZE XGRIDSTYLE XMARGIN XMINOR XRANGE 
        XSTYLE XTHICK XTICKFORMAT XTICKLEN XTICKNAME XTICKS 
        XTICKV XTICK_GET XTITLE YCHARSIZE YGRIDSTYLE YMARGIN 
        YMINOR YRANGE YSTYLE YTHICK YTICKFORMAT YTICKLEN 
        YTICKNAME YTICKS YTICKV YTICK_GET YTITLE ZCHARSIZE 
        ZGRIDSTYLE ZMARGIN ZMINOR ZRANGE ZSTYLE ZTHICK 
        ZTICKFORMAT ZTICKLEN ZTICKNAME ZTICKS ZTICKV 
        ZTICK_GET ZTITLE ZVALUE.
        
Example

Create a simple dataset by entering:

D = DIST(40)

Display the dataset as a light-source shaded surface 
by entering:

SHADE_SURF, D, TITLE = 'Shaded Surface'

Instead of light-source shading, an array of the same 
size as the elevation dataset can be used to color the 
surface. This technique creates four-dimensional dis-
plays. Create an array of shades to use by entering the 
command:

S = SIN(D)

Now create a new shaded surface that uses the array of 
shading values instead of the light source. Enter:

SHADE_SURF, D, SHADES = BYTSCL(S)

Note that the BYTSCL function is used to scale S into 
the range of bytes.

;-
;+
SHADE_VOLUME

Given a 3D volume and a contour value, SHADE_VOLUME 
produces a list of vertices and polygons describing the 
contour surface. This surface can then be displayed as a 
shaded surface by the POLYSHADE procedure. Shading is 
obtained from either a single light-source model or from 
user-specified values.

SHADE_VOLUME computes the polygons that describe a 
three dimensional contour surface. Each volume element 
(voxel) is visited to find the polygons formed by the 
intersections of the contour surface and the voxel edges. 
The method used by SHADE VOLUME is that of Klemp, McIrvin 
and Boyd, 1990: "PolyPaint-A Three-Dimensional Rendering 
Package," American Meteorology Society Proceedings, Sixth 
International Conference on Interactive Information and 
Processing Systems. This method is similar to the marching 
cubes algorithm described by Lorenson and Cline, 1987: 
"Marching Cubes: A High Resolution 3D Surface Construc-
tion Algorithm," Computer Graphics 21, 163-169.

This routine is limited to processing datasets that 
will fit in memory.

Calling Sequence

        SHADE_VOLUME, Volume, Value, Vertex, Poly
        
Arguments

    Volume
    
        A three-dimensional array that contains the 
        dataset to be contoured. If the Volume array is 
        dimensioned (D0, D1, D2), the resulting vertex coor-
        dinates range between 0 and D0-1 in X, 0 and D1-1 in 
        Y, and 0 and D2-1 in Z.
        
    Value
    
        The scalar contour value. This value specifies 
        the constant-density surface (also called an isosur-
        face) to be rendered.
        
    Vertex
    
        The name of a variable to receive the vertex 
        array. On output, this variable is set to a (3, n) 
        floating-point array, suitable for input to POLY-
        SHADE.
        
    Poly
    
        A named variable to receive the polygon list, an 
        m-element, longword array. This list describes the 
        vertices of each polygon and is suitable for input 
        to POLYSHADE.
        
Keywords

    LOW
    
        Set this keyword to display the low side of the 
        contour surface (i.e., the contour surfaces enclose 
        high data values). If this keyword is omitted or is 
        0, the high side of the contour surface is displayed 
        and the contour encloses low data values. If this 
        parameter is incorrectly specified, errors in shad-
        ing will result.
        
    SHADES
    
        An optional array, converted to byte type before 
        use, that contains the user-specified shading color 
        index for each voxel. This array must have the same 
        dimensions as Volume. On exit, this array is 
        replaced by another array, that contains the shading 
        value for each vertex, contained in Vertex.
        
    VERBOSE
    
        Set this keyword to print a message indicating 
        the number of polygons and vertices that are pro-
        duced.
        
    XRANGE
    
        An optional two-element vector that contains the 
        limits, over the first dimension, of the sub-volume 
        to be considered.
        
    YRANGE
    
        An optional two-element vector that contains the 
        limits, over the second dimension, of the sub-volume 
        to be considered.
        
    ZRANGE
    
        An optional two-element vector containing the 
        limits, over the third dimension, of the sub-volume 
        to be considered.
        
Example

The following procedure shades a volume passed as a 
parameter. It uses the SURFACE procedure to establish the 
viewing transformation. It then calls SHADE_VOLUME to 
produce the vertex and polygon lists, and POLYSHADE to 
draw the contour surface.

Pro SHOWVOLUME, vol, thresh, LOW = low
Display the contour surface of a volume.

s = SIZE(vol)	Get the dimensions of the volume.

IF s(0) NE 3 THEN ... ...	Error, must be a 3D array.

SCALE3, XRANGE=[0, S(1)], YRANGE=[0, S(2)], ZRANGE=[0, S(3)]

	Use SCALE3 to establish the 3D transforma-
tion and coordinate ranges.



IF N_ELEMENTS(low) EQ 0 THEN low = 0
Default = view high side of contour surface.

SHADE_VOLUME, vol, thresh, v, p, LOW = low
Produce vertices and polygons.

TV, POLYSHADE(v,p,/T3D)	Produce image of surface and display.

END

;-
;+
SHIFT

The SHIFT function shifts elements of vectors or 
arrays along any dimension by any number of elements. The 
result is a vector or array of the same structure and type 
as Array. Positive shifts are to the right while left 
shifts are expressed as a negative number. All shifts are 
circular.

Elements shifted off one end wrap around and are shifted onto the other end. Call-
ing Sequence

        Result = SHIFT(Array, S1, ..., Sn)
        
Arguments

    Array
    
        The array to be shifted.
        
    Si
    
        The shift parameters. For arrays of more than 
        one dimension, the parameter Sn specifies the shift 
        applied to the nth dimension. S1 specifies the shift 
        along the first dimension and so on. If only one 
        shift parameter is present and the parameter is an 
        array, the array is treated as a vector (i.e., the 
        array is treated as having one-dimensional sub-
        scripts).
        
        A shift specification of 0 means that no shift 
        is to be performed along that dimension.
        
Example

The following example demonstrates using SHIFT with a 
vector. Create a 5- element, integer vector by entering:

A = INDGEN(5)

Print the original vector, the vector shifted one 
position to the right, and the vector shifted one position 
to the left:

PRINT, A, SHIFT(A, 1), SHIFT(A, -1)

Executing these statements gives the result:

  0   1   2   3   4

  4   0   1   2   3

  1   2   3   4   0

Notice how elements of the vector that shift off the 
end wrap around to the other end. This "wrap around" 
occurs when shifting arrays of any dimension.

;-
;+
SIN

The periodic function SIN returns the trigonometric 
sine of X.

Calling Sequence

        Result = SIN(X)
        
Arguments

    X
    
        The angle for which the sine is desired, speci-
        fied in radians. If X is double-precision-floating 
        or complex, the result is of the same type. All 
        other types are converted to single-precision float-
        ing-point and yield floating-point results. When 
        applied to complex numbers:
        
        sin x = COMPLEX(sin R cosh I, cos R sinh I)
        
        where R and I are the real and imaginary parts 
        of x.
        
        If input argument X is an array, the result has 
        the same structure, with each element containing the 
        sine of the corresponding element of X.
        
Examples

To find the sine of 0.5 radians and print the result, 
enter:

PRINT, SIN(0.5)

The following example plots the SIN function between 0 
and 2*pi with 100 intervals:

X = 2*!PI/100 * FINDGEN(100)

PLOT, X, SIN(X)

Note that !PI is a read-only system variable that con-
tains the single-precision value for pi.

;-
;+
SINDGEN

The SINDGEN function returns a string array with the 
specified dimensions. Each element of the array is set to 
the string representation of the value of its one-dimen-
sional subscript, using IDL's default formatting rules.

Calling Sequence

        Result = SINDGEN(D1, ..., Dn)
        
Arguments

    Di
    
        The dimensions of the result. The dimension 
        parameters can be any scalar expression. Up to eight 
        dimensions can be specified.
        
Example

To create S, a six-element string vector with each 
element set to the string value of its subscript, enter:

S = SINDGEN(6)

;-
;+
SINH

The SINH function returns the hyperbolic sine of X.

Calling Sequence

        Result = SINH(X)
        
Arguments

    X
    
        The angle for which the hyperbolic sine is 
        desired, specified in radians. If X is double-preci-
        sion floating-point, the result is also double-pre-
        cision. Complex values are not allowed. All other 
        types are converted to single-precision floating-
        point and yield floating-point results. SINH is 
        defined as:
        
        sinh x = (e^u - e^9-u))/2
        
        If X is an array, the result has the same struc-
        ture, with each element containing the hyperbolic 
        sine of the corresponding element of X.
        
Examples

To find the hyperbolic sine of each element in the 
array [.5, .2, .4] and print the result, enter:

PRINT, SINH([.5, .2, .4])

To plot the SINH function between 0 and 2*pi with 100 
intervals, enter:

X = 2*!PI/100 * FINDGEN(100)

PLOT, X, SINH(X)

Note the !PI is a read-only system variable that con-
tains the single-precision value of pi.

;-
;+
SIZE

The SIZE function returns a vector that contains size 
and type information for its argument.

The returned vector is always of longword type. The 
first element is equal to the number of dimensions of 
Expression. This value is zero if Expression is scalar or 
undefined. The next elements contain the size of each 
dimension, one element per dimension (none if Expression 
is scalar or undefined). After the dimension sizes, the 
last two elements contain the type code (zero if unde-
fined) and the number of elements in Expression, respec-
tively. The type code is described in the table below.

Type Code  Data Type
--------------------------------------
0          Undefined
1          Byte
2          Integer
3          Longword integer
4          Floating-point
5          Double-precision floating
6          Complex floating
7          String
8          Structure

Calling Sequence

        Result = SIZE(Expression)
        
Arguments

    Expression
    
        The expression for which size information is 
        requested.
        
Example

Print the size information for a 10 by 20 floating-
point array by entering:

PRINT, SIZE(FINDGEN(10, 20))

IDL prints:

   2   10   20   4   200

IDL shows that the array has 2 dimensions, equal to 10 
and 20, a type code of 4, and 200 elements total.

;-
;+
SKIPF (VMS Only)

The SKIPF procedure skips records or files on the des-
ignated magnetic tape unit. If two parameters are sup-
plied, files are skipped. If three parameters are present, 
individual records are skipped.

The number of files or records actually skipped is 
stored in the system variable !ERR. Note that when skip-
ping records, the operation terminates immediately when 
the end of a file is encountered. See the description of 
the magnetic tape routines in Chapter 17 of the IDL User's 
Guide.

Calling Sequence

        SKIPF, Unit, Files
        
        or
        
        SKIPF, Unit, Records, R
        
Arguments

    Unit
    
        The magnetic tape unit to rewind. Unit must be a 
        number between 0 and 9, and should not be confused 
        with the standard file Logical Unit Numbers (LUNs).
        
    Files
    
        The number of files to be skipped. Skipping is 
        in the forward direction if the second parameter is 
        positive, otherwise files are skipped backwards.
        
    Records
    
        The number of records to be skipped. Skipping is 
        in the forward direction if the second parameter is 
        positive, otherwise records are skipped backwards.
        
    R
    
        If this argument is present, records are 
        skipped, otherwise files are skipped. The value of R 
        is never examined. Its presence serves only to indi-
        cate that records are to be skipped.
        
;-
;+
SMOOTH

The SMOOTH function returns a copy of Array smoothed with a boxcar average of 
the specified width. The result has the same type and dimensions as Array. Calling 
Sequence

        Result = SMOOTH(Array, Width)
        
Arguments

    Array
    
        The array to be smoothed. Array can have any 
        number of dimensions.
        
    Width
    
        The width of the smoothing window. Width should 
        be an odd number, smaller than the smallest dimen-
        sion of Array. If Width is an even number, one plus 
        the given value of Width is used. The value of Width 
        does not affect the running time of SMOOTH to a 
        great extent.
        
Example

Create and display a simple image by entering:

D = SIN(DIST(256)/3) & TVSCL, D

Now display the same dataset smoothed with a width of 
9 by entering:

TVSCL, SMOOTH(D, 9), 256, 256

;-
;+
SOBEL

The SOBEL function implements an approximation of the 
3 by 3, nonlinear edge-enhancement operator. See the IDL 
Referene Guide for a deciption of the algorithm used by 
this function.

The result of this function is a two-dimensional array 
of short integer type, with the same dimensions as Image. 
Large original data values cause overflow if the absolute 
value of the result is larger than 32768.

Calling Sequence

        Result = SOBEL(Image)
        
Arguments

    Image
    
        The two-dimensional array containing the image 
        to which edge enhancement will be applied.
        
Example

If the variable IM contains an image, a Sobel edge-
enhanced version can be displayed with the command:

TVSCL, SOBEL(IM)

;-
;+
SORT

The SORT function returns a vector of subscripts that 
allow access to the elements of Array in ascending order. 
The result is always a vector of longword type with the 
same number of elements as Array.

Calling Sequence

        Result = SORT(Array)
        
Arguments

    Array
    
        The array to be sorted. Array can be any basic 
        type of vector or array. String arrays are sorted 
        using the ASCII collating sequence.
        
Example

To illustrate, assume the vector A contains the ele-
ments [4, 3, 7, 1, 2]. Then:

SORT(A) = [3, 4, 1, 0, 2]

because:

A(3) < A(4) < A(1) < A(0) < A(2)

To see the elements of A in sorted order use the 
expression enter:

PRINT, A(SORT(A))

which prints:

     1     2     3     4     7

To obtain the elements in descending order enter:

PRINT, A(REVERSE(SORT(A)))

which prints:

     7     4     3     2     1

;-
;+
SPAWN

The SPAWN procedure spawns a child process to execute 
a command or series of commands. Under Unix, the shell 
used (if any) is obtained from the SHELL environment vari-
able. Under VMS, the DCL command language interpreter is 
used.

Calling Sequence

        SPAWN [, Command [, Result]]
        
Arguments

    Command
    
        A string containing the command(s) to be exe-
        cuted.
        
        If Command is not present, SPAWN starts an 
        interactive command interpreter process. Under Unix, 
        the default shell is used. IDL execution suspends 
        until the new shell process terminates. Under Unix, 
        shells that handle process suspension (e.g., /bin/
        csh) offer a more efficient way to get the same 
        effect.
        
        Command must be of type string. Under VMS, it is 
        restricted to being a scalar. Under Unix, it can be 
        a string array-each element is passed to the child 
        process as a separate argument.
        
    Result
    
        A named variable in which to place the output 
        from the child process. Each line of output becomes 
        a single array element. If Result is not present, 
        the output from the child shell process goes to the 
        standard output.
        
Keywords

    COUNT
    
        If Result is present and this keyword is also 
        specified, COUNT specifies a named variable into 
        which the number of lines of output is placed. This 
        value gives the number of elements placed into 
        Result.
        
    PID
    
        A named variable into which the Process IDenti-
        fication number of the child process is stored.
        
Unix Keywords

    NOSHELL
    
        Set this keyword to specify that Command should 
        execute directly as a child process without an 
        intervening shell process. In this case, Command 
        should be specified as a string array in which the 
        first element is the name of the command to execute 
        and the following arguments are the arguments to be 
        passed to the command (C programmers will recognize 
        this as these are the elements of the argv argument 
        that Unix passes to the child process main func-
        tion). Since no shell is present, wildcard charac-
        ters are not expanded, and other tasks normally 
        performed by the shell do not occur. NOSHELL is use-
        ful when performing many SPAWNed operations from a 
        program and speed is a primary concern.
        
    NOTTYRESET
    
        Some Unix systems drop characters when the tty 
        mode is switched between normal and raw modes. IDL 
        switches between these modes when reading command 
        input and when using the GET_KBRD function. On such 
        systems, IDL avoids losing characters by delaying 
        the switch back to normal mode until it is truly 
        needed. This method has the benefit of avoiding the 
        large number of mode changes that would otherwise be 
        necessary. Routines that cause output to be sent to 
        the standard output (e.g., I/O operations, user 
        interaction and SPAWN) ensure that the tty is in its 
        normal mode before performing their operations.
        
        If the NOTTYRESET keyword is set, SPAWN does not 
        switch the tty back to normal mode before launching 
        the child process assuming instead that the child 
        will not send output to the tty. Use this keyword to 
        avoid characters being dropped in a loop of the 
        form:
        
        WHILE (GET_KBRD(0) NE 'q') SPAWN, command
        
        This keyword has no effect on systems that don't 
        suffer from dropped characters.
        
    SH
    
        Set this keyword to force the use of the /bin/sh 
        shell. Usually, the shell used is determined by the 
        SHELL environment variable.
        
    UNIT
    
        If UNIT is present, SPAWN creates a child pro-
        cess in the usual manner, but instead of waiting for 
        the specified command to finish, it attaches a bidi-
        rectional pipe between the child process and IDL. 
        From the IDL session, the pipe appears as a logical 
        file unit. The other end of the pipe is attached to 
        the child process standard input and output. The 
        UNIT keyword specifies a named variable into which 
        the number of the file unit is stored.
        
        Once the child process is started, the IDL ses-
        sion can communicate with it through the usual 
        input/output facilities. After the child process has 
        done its task, the CLOSE procedure can be used to 
        kill the process and close the pipe. Since SPAWN 
        uses GET_LUN to allocate the file unit, FREE_LUN 
        should be used to free the unit.
        
        If UNIT is present, Command must be present, and 
        Result is not allowed.
        
VMS Keywords

    NOCLISYM
    
        If this keyword is set, the spawned subprocess 
        does not inherit command language interpreter sym-
        bols from its parent process. You can specify this 
        keyword to prevent commands redefined by symbol 
        assignments from affecting the spawned commands, or 
        to speed process startup.
        
    NOLOGNAM
    
        If this keyword is set, the spawned subprocess 
        does not inherit process logical names from its par-
        ent process. You can specify this keyword to prevent 
        commands redefined by logical name assignments from 
        affecting the spawned commands, or to speed process 
        startup.
        
    NOTIFY
    
        If this keyword is set, a message is broadcast 
        to SYS$OUTPUT when the child process completes or 
        aborts. NOTIFY should be set in conjunction with the 
        NOWAIT keyword.
        
    NOWAIT
    
        If this keyword is set, the IDL process contin-
        ues executing in parallel with the subprocess. Nor-
        mally, the IDL process hibernates until the 
        subprocess completes.
        
Example

To simply spawn a process from within IDL enter the 
command:

SPAWN

To execute the UNIX ls command and return to the IDL 
prompt, enter:

SPAWN, 'ls'

To execute the UNIX ls command and store the result in 
the IDL string variable listing, enter:

SPAWN, 'ls', listing

;-
;+
SQRT

The SQRT function returns the square root of X.

Calling Sequence

        Result = SQRT(X)
        
Arguments

    X
    
        The value for which the square root is desired. 
        If X is double-precision floating-point or complex, 
        the result is of the same type. All other types are 
        converted to single-precision floating-point and 
        yield floating-point results. When applied to com-
        plex numbers, z = x+iy:
        
        z^(1/2) = [(1/2)(r+x)]^(1/2) +/- i[(1/2)(r-
        x)]^(1/2)
        
        r = sqrt(x^2 + y^2)
        
        The ambiguous sign is taken to be the same as 
        the sign of y. The result has the same structure as 
        X.
        
Example

To find the square root of 145 and store the result in 
variable S, enter:

S = SQRT(145)

;-
;+
STOP

The STOP procedure stops the execution of a running 
program or batch file. Control reverts to the interactive 
mode.

Calling Sequence

        STOP [, Expr1, ..., Exprn]
        
Arguments

    Expri
    
        One or more expressions whose value is printed. 
        If no parameters are present, a brief message 
        describing where the STOP was encountered is 
        printed.
        
Example

Suppose that you want to stop the execution of a pro-
cedure and print the values of the variables A, B, C and 
NUM. At the appropriate location in your procedure include 
the command:

STOP, A, B, C, NUM

To continue execution of the procedure (if possible) 
enter the IDL executive command:

.CONT

;-
;+
STRARR

The STRARR function returns a string array containing 
zero-length strings.

Calling Sequence

        Result = STRARR(D1, ..., Dn)
        
Arguments

    Di
    
        The dimensions of the result. The dimension 
        parameters can be any scalar expression. Up to eight 
        dimensions can be specified.
        
Example

To create S, a 20-element string vector, enter:

S = STRARR(20)

;-
;+
STRCOMPRESS

The STRCOMPRESS function returns a copy of String with 
all whitespace (blanks and tabs) compressed to a single 
space or completely removed.

Calling Sequence

        Result = STRCOMPRESS(String)
        
Arguments

    String
    
        The string to be compressed. If not of type 
        string, it is converted using IDL's default format-
        ting rules. If String is an array, the result is an 
        array with the same structure-each element contains 
        a compressed copy of the corresponding element of 
        String.
        
Keywords

    REMOVE_ALL
    
        Set this keyword to remove all whitespace. Nor-
        mally, all whitespace is compressed to a single 
        space.
        
Example

Create a string variable S by entering:

S = 'This is a string with spaces in it.'

Now print S with all of the whitespace removed by 
entering:

PRINT, STRCOMPRESS(S, /REMOVE_ALL)

IDL prints:

Thisisastringwithspacesinit.

;-
;+
STRING

The STRING function returns its arguments converted 
to string type. It is similar to the PRINT procedure, 
except that its output is placed in a string rather than 
being output to the terminal. The case in which a single 
expression of type byte is specified without the FORMAT 
keyword is special-see the discussion of STRING below, and 
in Chapter 17 and Chapter 8 of the IDL User's Guide for 
details.

Calling Sequence

        Result = STRING(Expression1, ..., Expressionn)
        
Arguments

    Expressionn
    
        The expressions to be converted to string type.
        
Keywords

    FORMAT
    
        A format string to be used in formatting the 
        expressions. See "Explicitly Formatted Input/Output" 
        on page 17-15 of the IDL User's Guide. Note that 
        formatted output from STRING is limited to a maximum 
        of 1024 lines.
        
    PRINT
    
        Set this keyword to specify that any special 
        case processing should be ignored and that STRING 
        should behave exactly as the PRINT procedure would.
        
Differences Between STRING and PRINT

The behavior of STRING differs from the behavior of 
the PRINT procedure in the following ways (unless the 
PRINT keyword is set):

    When called with a single non-byte argument and 
    no format specification, STRING returns a result 
    that has the same dimensions as the original argu-
    ment. For example, the statement:
    
    HELP, STRING(INDGEN(5))
    
        gives the result:
        
        <Expression> STRING = Array(5)
        
        while:
        
        HELP, STRING(INDGEN(5), /PRINT)
        
        results in:
        
        <Expression> STRING =' 0 1 2 3 4'
        
    If called with a single argument of byte type 
    and the FORMAT keyword is not used, STRING simply 
    stores the unmodified values of each byte element in 
    the result. This result is a string containing the 
    byte values from the original argument. Thus, the 
    result has one less dimension than the original 
    argument. For example, a 2-dimensional byte array 
    becomes a vector of strings, a byte vector becomes a 
    scalar string. However, a byte scalar also becomes a 
    string scalar. For example, the statement:
    
    PRINT, STRING([72B, 101B, 108B, 108B, 111B])
    
        produces the output:
        
        Hello
        
        because the argument to STRING, is a byte vec-
        tor. Its first element is a 72B which is the ASCII 
        code for "H", the second is 101B which is an ASCII 
        "e", and so forth.
        
    If both the FORMAT and PRINT keywords are not 
    present and STRING is called with more than one 
    argument, and the last argument is a scalar string 
    starting with the characters "$(" or "(", this final 
    argument is taken to be the format specification, 
    just as if it had been specified via the FORMAT key-
    word. This feature is maintained for compatibility 
    with version 1 of VMS IDL.
    
Example

To convert the contents of variable A to string type 
and store the result in the variable B, enter:

B = STRING(A)

;-
;+
STRLEN

The STRLEN function returns the length of its string-
type argument. If the argument is not a string, it is 
first converted to string type.

Calling Sequence

        Result = STRLEN(Expression)
        
Arguments

    Expression
    
        The expression for which the string length is 
        desired. If this parameter is not a string, it is 
        converted using IDL's default formatting rules in 
        order to determine the length. The result is an 
        integer. If Expression is an array, the result is an 
        integer array with the same structure, where each 
        element contains the length of the corresponding 
        Expression element.
        
Example

To find the length of the string "IDL is fun" and 
print the result, enter:

PRINT, STRLEN('IDL is fun')

IDL prints:

   10

;-
;+
STRLOWCASE

The STRLOWCASE function returns a copy of String con-
verted to lowercase characters. Only uppercase characters 
are modified-lowercase and non-alphabetic characters are 
copied without change.

Calling Sequence

        Result = STRLOWCASE(String)
        
Arguments

    String
    
        The string to be converted. If this argument is 
        not a string, it is converted using IDL's default 
        formatting rules. If String is an array, the result 
        is an array with the same structure-each element 
        contains a lower case copy of the corresponding ele-
        ment of String.
        
Example

To convert the string "IDL is fun" to all lowercase 
characters and print the result, enter:

PRINT, STRLOWCASE('IDL is fun')

IDL prints:

idl is fun

;-
;+
STRMESSAGE

The STRMESSAGE function returns the text of the error 
message specified by Errno. This function is especially 
useful in conjunction with the !ERROR system variable 
which always contains the error number of the last error. 
(Also see the description of the !ERR_STRING system vari-
able.)

Calling Sequence

        Result = STRMESSAGE(Errno)
        
Arguments

    Errno
    
        The error number for which the message text is 
        desired. Programs must not make the assumption that 
        certain error numbers are always related to certain 
        error messages the actual correspondence changes 
        over time as IDL is modified.
        
Example

Print the error message associated with error number 4 
by entering:

PRINT, STRMESSAGE(4)

;-
;+
STRMID

The STRMID function extracts a substring from a string 
expression. The result of the function is a string of 
Length characters taken from Expression, starting at 
character position First_Character.

Calling Sequence

        Result = STRMID(Expression, First_Character, 
        Length)
        
Arguments

    Expression
    
        The expression from which the substring is to be 
        extracted. If this argument is not a string, it is 
        converted using IDL's default formatting rules. If 
        Expression is an array, the result is an array with 
        the same structure, where each element contains the 
        substring of the corresponding Expression element.
        
    First_Character
    
        The starting position within Expression at which 
        the substring starts. The first character position 
        is 0.
        
    Length
    
        The length of the substring. If there are not 
        enough characters left in the main string to obtain 
        Length characters, the substring is truncated.
        
Example

If the variable B contains the string "IDL is fun", 
the substring "is" can be extracted and stored in the 
variable C with the command:

C = STRMID(B, 4, 2)

;-
;+
STRPOS

The STRPOS function finds the first occurrence of a 
substring within an object string. If Search_String 
occurs in Expression, STRPOS returns the character posi-
tion of the match, otherwise it returns -1.

Calling Sequence

        Result = STRPOS(Expression, Search String [, 
        Pos])
        
Arguments

    Expression
    
        The expression in which to search for the sub-
        string. If this argument is not a string, it is con-
        verted using IDL's default formatting rules. If 
        Expression is an array, the result is an array with 
        the same structure, where each element contains the 
        position of the substring within the corresponding 
        element Expression. If Expression is the null 
        string, STRPOS returns the value -1.
        
    Search_String
    
        The substring to be searched for within Expres-
        sion. If this argument is not a string, it is con-
        verted using IDL's default formatting rules. If 
        Search_String is the null string, STRPOS returns the 
        smaller of Pos or one less than the length of 
        Expression.
        
    Pos
    
        The character position at which the search is 
        begun. If Pos is omitted, the search begins at the 
        first character (character position 0). If Pos is 
        less than zero, zero is used for the starting posi-
        tion.
        
Example

Find the position of the string "fun" within the 
string "IDL is fun" and print the result by entering:

PRINT, STRPOS('IDL is fun', 'fun')

IDL prints:

   7

;-
;+
STRPUT

The STRPUT procedure inserts the contents of one 
string into another. The source string, Source, is 
inserted into the destination string, Destination, start-
ing at the given position, Position. Characters in Desti-
nation before the starting position and after the starting 
position plus the length of Source remain unchanged. The 
length of the destination string is not changed. If the 
insertion extends past the end of the destination, it is 
clipped at the end.

Calling Sequence

        STRPUT, Destination, Source [, Position]
        
Arguments

    Destination
    
        The named string variable into which Source is 
        inserted. Destination must be a named variable of 
        type string. If it is an array, Source is inserted 
        into every element of the array.
        
    Source
    
        A scalar string to be inserted into Destination. 
        If this argument is not a string, it is converted 
        using IDL's default formatting rules.
        
    Position
    
        The character position at which the insertion is 
        begun. If Position is omitted, the insertion begins 
        at the first character (character position 0). If 
        Position is less than zero, zero is used for the 
        initial position.
        
Examples

If the variable A contains the string "IBM is fun", 
the substring "IBM" can be overwritten with the string 
"IDL" by entering:

STRPUT, A, 'IDL', 0

The following commands demonstrate the clipping of 
output that extends past the end of the destination 
string:

STRPUT, A, 'FUNNY', 7

PRINT, A

IDL prints:

IDL is FUN

;-
;+
STRTRIM

The STRTRIM function returns a copy of String with 
leading and/or trailing blanks removed.

Calling Sequence

        Result = STRTRIM(String, [Flag])
        
Arguments

    String
    
        The string to have leading and/or trailing 
        blanks removed. If this argument is not a string, it 
        is converted using IDL's default formatting rules. 
        If it is an array, the result is an array with the 
        same structure where each element contains a trimmed 
        copy of the corresponding element of String.
        
    Flag
    
        A value that controls the action of STRTRIM. If 
        Flag is zero or not present, trailing blanks are 
        removed. Leading blanks are removed if it is equal 
        to 1. Both are removed if it is equal to 2.
        
Example

Converting variables to string type often results in 
undesirable leading blanks. For example, the following 
command converts the integer 56 to string type:

C = STRING(56)

Entering the command:

HELP, C

IDL prints:

C         STRING = '      56'

which shows that there are six leading spaces before 
the characters 5 and 6. To remove these leading blanks, 
enter the command:

C = STRTRIM(C, 1)

To confirm that the blanks were removed, enter:

HELP, C

IDL prints:

C         STRING = '56'

;-
;+
STRUPCASE

The STRUPCASE function returns a copy of String con-
verted to upper case. Only lowercase characters are modi-
fied-uppercase and non-alphabetic characters are copied 
without change.

Calling Sequence

        Result = STRUPCASE(String)
        
Arguments

    String
    
        The string to be converted. If this argument is 
        not a string, it is converted using IDL's default 
        formatting rules. If it is an array, the result is 
        an array with the same structure where each element 
        contains an uppercase copy of the corresponding ele-
        ment of String.
        
Example

To print an uppercase version of the string "IDL is 
fun", enter:

PRINT, STRUPCASE('IDL is fun')

IDL prints:

IDL IS FUN

;-
;+
SURFACE

The SURFACE procedure draws a wire-mesh representa-
tion of a two-dimensional array projected into two dimen-
sions, with hidden lines removed.

Restrictions

If the (X, Y) grid is not regular or nearly regular, 
errors in hidden line removal occur. The TRIGRID and TRI-
ANGULATE routines can be used to interpolate irregularly-
gridded data points to a regular grid before plotting.

If the T3D keyword is set, the 3D to 2D transformation 
matrix contained in !P.T must project the Z axis to a line 
parallel to the device Y axis, or errors will occur.

The surface lines may blend together when drawing 
large arrays, especially on low or medium resolution dis-
plays. Use REBIN or the User's Library CONGRID function to 
resample the array to a lower resolution before plotting.

Calling Sequence

        SURFACE, Z [, X, Y]
        
Arguments

    Z
    
        The two-dimensional array to be displayed. If X 
        and Y are provided, the surface is plotted as a 
        function of the (X, Y) locations specified by their 
        contents. Otherwise, the surface is generated as a 
        function of the array index of each element of Z.
        
        This argument is converted to single-precision 
        floating-point before plotting. Plots created with 
        SURFACE are limited to the range and precision of 
        single-precision floating-point values.
        
    X
    
        A vector or two-dimensional array specifying the 
        X coordinates of the grid. If this argument is a 
        vector, each element of X specifies the X coordinate 
        for a column of Z (e.g., X(0) specifies the X coor-
        dinate for Z(0,*)). If X is a two-dimensional array, 
        each element of X specifies the X coordinate of the 
        corresponding point in Z (Xij specifies the X coordi-
        nate for Zij).
        
        This argument is converted to single-precision 
        floating-point before plotting.
        
    Y
    
        A vector or two-dimensional array specifying the 
        Y coordinates of the grid. If this argument is a 
        vector, each element of Y specifies the Y coordinate 
        for a row of Z (e.g., Y(0) specifies the Y coordi-
        nate for Z(*,0)). If Y is a two-dimensional array, 
        each element of Y specifies the Y coordinate of the 
        corresponding point in Z (Yij specifies the Y coordi-
        nate for Zij).
        
        This argument is converted to single-precision 
        floating-point before plotting.
        
Keywords

    AX
    
        This keyword specifies the angle of rotation, 
        about the X axis, in degrees towards the viewer. 
        This keyword is effective only if !P.T3D is not set. 
        If !P.T3D is set, the three-dimensional to two-
        dimensional transformation used by SURFACE is taken 
        from the 4 by 4 array !P.T.
        
        The surface represented by the two-dimensional 
        array is first rotated, AZ (see below) degrees about 
        the Z axis, then by AX degrees about the X axis, 
        tilting the surface towards the viewer (AX > 0), or 
        away from the viewer.
        
        The AX and AZ keyword parameters default to +30 
        degrees if omitted and !P.T3D is 0.
        
        The three-dimensional to two-dimensional trans-
        formation represented by AX and AZ, can be saved in 
        !P.T by including the SAVE keyword.
        
    AZ
    
        This keyword specifies the counterclockwise 
        angle of rotation about the Z axis. This keyword is 
        effective only if !P.T3D is not set. The order of 
        rotation is AZ first, then AX.
        
    BOTTOM
    
        The color index used to draw the bottom surface. 
        If not specified, the bottom is drawn with the same 
        color as the top.
        
    HORIZONTAL
    
        A keyword flag which if set causes SURFACE to 
        only draw lines across the plot perpendicular to the 
        line of sight. The default is for SURFACE to draw 
        both across the plot and from front to back.
        
    LEGO
    
        Set this keyword to produce "Lego" style plots. 
        Each data value is rendered as a box covering the XY 
        extent of the cell and with a height proportional to 
        the Z value.
        
    LOWER_ONLY
    
        Set this keyword to draw only the lower surface 
        of the object. By default, both surfaces are drawn.
        
    MAX_VALUE
    
        The largest data value to be plotted. Data 
        larger than this value are treated as missing data 
        and are not plotted.
        
    SAVE
    
        Set this keyword to save the 3D to 2D transfor-
        mation matrix established by SURFACE in the system 
        variable field !P.T. Use this keyword when combining 
        the output of SURFACE with additional output from 
        other routines in the same plot.
        
        When used with AXIS, the SAVE keyword parameter 
        saves the scaling parameters established by the call 
        in the appropriate axis system variable, !X, !Y, or 
        !Z. This causes subsequent overplots to be scaled to 
        the new axis.
        
        Example
        
        To display a two-dimensional array using SUR-
        FACE, and to then superimpose contours over the sur-
        face (this example assumes that !P.T3D is zero, its 
        default value.), enter the following commands:
        
        SURFACE, Z, /SAVE	Make a surface plot and save the 
        transformation.
        
        CONTOUR, Z, /NOERASE, /T3D	Make contours, don't erase, use the 
        3D to 2D transform placed in !P.T 
        by SURFACE.
        
        To display a surface and to then display a flat 
        contour plot, registered above the surface:
        
        SURFACE, Z, /SAVE	Make the surface, save transform.
        
        CONTOUR, Z, /NOERASE, /T3D, ZVALUE=1.0
        Now display a flat contour plot, at 
        the maximum Z value (normalized 
        coordinates). You can display the 
        contour plot below the surface with 
        by using a ZVALUE of 0.0.
        
    SHADES
    
        This keyword allows user-specified coloring of 
        the mesh surfaces. Set this keyword to an array that 
        specifies the color index of the lines emanating 
        from each data point toward the top and right.
        
    SKIRT
    
        This keyword represents a Z-value at which to 
        draw a skirt around the array. The Z value is 
        expressed in data units. The default is no skirt.
        
        If the skirt is drawn, each point on the four 
        edges of the surface is connected to a point on the 
        skirt which has the given Z value, and the same X 
        and Y values as the edge point. In addition, each 
        point on the skirt is connected to its neighbor.
        
    UPPER_ONLY
    
        Set this keyword to draw only the upper surface 
        of the object. By default, both surfaces are drawn.
        
    XTYPE
    
        Set this keyword to specify a logarithmic X 
        axis.
        
    YTYPE
    
        Set this keyword to specify a logarithmic Y 
        axis.
        
    ZAXIS
    
        This keyword specifies the placement of the Z 
        axis for the SURFACE plot. 
        
        By default, SURFACE draws the Z axis at the 
        upper left corner of the axis box. To suppress the Z 
        axis, use ZAXIS=-1 in the call. The position of the 
        Z axis is determined from the value of ZAXIS as fol-
        lows: 1 = lower right, 2 = lower left, 3 = upper 
        left, and 4 = upper right.
        
Graphics Keywords Accepted

        See Chapter 2, Graphics Keywords and System 
        Variables, for the description of graphics and plot-
        ting keywords not listed above. BACKGROUND CHANNEL 
        CHARSIZE CHARTHICK CLIP COLOR DATA DEVICE FONT LINE-
        STYLE NOCLIP NODATA NOERASE NORMAL POSITION SUBTITLE 
        T3D THICK TICKLEN TITLE XCHARSIZE XMARGIN XMINOR 
        XRANGE XSTYLE XTHICK XTICKLEN XTICKNAME XTICKS 
        XTICKV XTICK_GET XTITLE YCHARSIZE YMARGIN YMINOR 
        YRANGE YSTYLE YTHICK YTICKLEN YTICKNAME YTICKS 
        YTICKV YTICK_GET YTITLE ZCHARSIZE ZMARGIN ZMINOR 
        ZRANGE ZSTYLE ZTHICK ZTICKLEN ZTICKNAME ZTICKS 
        ZTICKV ZTICK_GET ZTITLE ZVALUE.
        
Example

Create a simple dataset to display by entering:

D = DIST(30)

Plot a simple wire-mesh surface representation of D by 
entering:

SURFACE, D

Create a wire-mesh plot of D with a title and a 
"skirt" around the edges of the dataset at Z=0 by enter-
ing:

SURFACE, D, SKIRT=0.0, TITLE = 'Surface Plot', CHARSIZE = 2

;-
;+
SYSTIME

The SYSTIME function returns the current system time 
as either a string that contains the current day, date and 
time, or as the number of seconds elapsed since January 1, 
1970.

Calling Sequence

        Result = SYSTIME(Arg)
        
Arguments

    Arg
    
        If Arg is present and nonzero, the number of 
        seconds elapsed since January 1, 1970 is returned as 
        a double-precision, floating-point value.
        
        Otherwise, a scalar string containing the cur-
        rent date/time in standard 24-character system for-
        mat is returned. This format is:
        
        DOW MON DD HH:MM:SS YEAR
        
        where DOW is the day of the week, MON is the 
        month, DD is the day of the month, HH is the hour, MM 
        is the minute, SS is the second, and YEAR is the 
        year.
        
Examples

Print the day of the week by entering:

PRINT, STRMID(SYSTIME(0), 0, 3)

The following code fragment could be used to determine 
the time required by a 16,384 point FFT:

T = SYSTIME(1)

A = FFT(FINDGEN(16384), -1)

PRINT, SYSTIME(1) - T, ' Seconds'

;-
;+
TAG_NAMES

The TAG_NAMES function returns a string array con-
taining the names of the tags in a structure expression. 
It can also be used to determine the expression's struc-
ture name (if the structure has a name).

Calling Sequence

        Result = TAG_NAMES(Expression)
        
Arguments

    Expression
    
        The structure expression for which the tag names 
        are returned. This argument must be of structure 
        type. TAG_NAMES does not search for tags recur-
        sively, so if Expression is a structure containing 
        nested structures, only the names of tags in the 
        outermost structure are returned.
        
Keywords

    STRUCTURE_NAME
    
        Set this keyword to return a scalar string that 
        contains the name of the structure instead of the 
        names of the tags in the structure. If the structure 
        is "anonymous", a null string is returned.
        
Example

Print the names of the tags in the system variable !P 
by entering:

PRINT, TAG_NAMES(!P)

;-
;+
TAN

The TAN function returns the tangent of X.

Calling Sequence

        Result = TAN(X)
        
Arguments

    X 
    
        The angle for which the tangent is desired, 
        specified in radians. If X is double-precision 
        floating-point, the result is of the same type. Com-
        plex values are not allowed. All other types are 
        converted to single-precision floating-point and 
        yield floating-point results. If X is an array, the 
        result has the same structure, with each element 
        containing the tangent of the corresponding element 
        of X.
        
Examples

Find the tangent of 0.5 radians and store the result 
in the variable T by entering:

T = TAN(0.5)

;-
;+
TANH

The TANH function returns the hyperbolic tangent of X.

Calling Sequence

        Result = TANH(X)
        
Arguments

    X
    
        The value for which the hyperbolic tangent is 
        desired, specified in radians. If X is double-preci-
        sion floating-point, the result is also double-pre-
        cision. Complex values are not allowed. All other 
        types are converted to single-precision floating-
        point and yield floating-point results. TANH is 
        defined as:
        
        tanh(x) = (e^x - e^(-x))/(e^x + e^(-x))
        
        If X is an array, the result has the same struc-
        ture, with each element containing the hyperbolic 
        tangent of the corresponding element of X.
        
Example

Find the hyperbolic tangent of 1 radian and print the 
result by entering:

PRINT, TANH(1)

Plot the hyperbolic tangent from -5 to +5 with an 
increment of 0.1 by entering:

PLOT, TANH(FINDGEN(101)/10. - 5)

;-
;+
TAPRD (VMS Only)

The TAPRD procedure reads the next record on the 
selected tape unit into the specified array. No data or 
format conversion, with the exception of optional byte 
reversal, is performed. The array must be defined with the 
desired type and dimensions. If the read is successful, 
the system variable !ERR is set to the number of bytes 
read. See the description of the magnetic tape routines in 
Chapter 17 of the IDL User's Guide.

Calling Sequence

        TAPRD, Array, Unit [, Byte_Reverse]
        
Arguments

    Unit
    
        The magnetic tape unit to read. This argument 
        must be a number between 0 and 9, and should not be 
        confused with standard file Logical Unit Numbers 
        (LUN's).
        
    Array
    
        A named variable into which the data is read. If 
        Array is larger than the tape record, the extra ele-
        ments of the array are not changed. If the array is 
        shorter than the tape record, a data overrun error 
        occurs. The length of Array and the records on the 
        tape can range from 14 bytes to 65,235 bytes.
        
    Byte_Reverse
    
        If this parameter is present, the even and odd 
        numbered bytes are swapped after reading, regardless 
        of the type of data or variables. This enables read-
        ing tapes containing short integers that were writ-
        ten on machines with different byte ordering. You 
        can also use the BYTORDER routine to re-order dif-
        ferent data types.
        
;-
;+
TAPWRT (VMS Only)

The TAPWRT procedure writes data from the Array param-
eter to the selected tape unit. One physical record con-
taining the same number of bytes as the array is written 
each time TAPWRT is called. The parameters and usage are 
identical to those in the TAPRD procedure with the excep-
tion that here the Array parameter can be an expression. 
Consult the TAPRD procedure for details. See the descrip-
tion of the magnetic tape routines in Chapter 17 of the 
IDL User's Guide.

Calling Sequence

        TAPWRT, Array, Unit [, Byte_Reverse]
        
Arguments

    Unit
    
        The magnetic tape unit to write. This argument 
        must be a number between 0 and 9, and should not be 
        confused with standard file Logical Unit Numbers 
        (LUNs).
        
    Array
    
        The expression representing the data to be out-
        put. The length of Array and the records on the tape 
        can range from 14 bytes to 65,235 bytes.
        
    Byte_Reverse
    
        If this parameter is present, the even and odd 
        numbered bytes are swapped on output, regardless of 
        the type of data or variables. This enables writing 
        tapes that are compatible with other machines.
        
;-
;+
TEMPORARY

The TEMPORARY function returns a temporary copy of a 
variable, and sets the original variable to "undefined". 
This function can be used to conserve memory when perform-
ing operations on large arrays, as it avoids making a new 
copy of results that are only temporary. In general, the 
TEMPORARY routine can be used to advantage whenever a 
variable containing an array that on the left hand side of 
an assignment statement is also referenced on the right 
hand side.

Calling Sequence

Result = TEMPORARY(Variable)

Arguments

    Variable
    
        The variable to be referenced and deleted.
        
Example

Assume the variable a is a large array. The statement:

A = A + 1

creates a new array for the result of the addition, 
places the sum into the new array, assigns it to a, and 
then frees the old allocation of a. Total storage required 
is twice the size of a. The statement:

A = TEMPORARY(A) + 1

requires no additional space.

;-
;+
THIN

The THIN function returns the "skeleton" of a bi-level 
image. The skeleton of an object in an image is a set of 
lines that reflect the shape of the object. The set of 
skeletal pixels can be considered to be the medial axis of 
the object. For a much more extensive discussion of skel-
etons and thinning algorithms, see Algorithms for Graph-
ics and Image Processing, Theo Pavlidis, Computer Science 
Press, 1982. The THIN function is adapted from Algorithm 
9.1 (the classical thinning algorithm).

On input, the bi-level image is a rectangular array in 
which pixels that compose the object have a nonzero value. 
All other pixels are zero. The result is a byte type image 
in which skeletal pixels are set to 2 and all other pixels 
are zero.

Calling Sequence

        Result = THIN(Image)
        
Arguments

    Image
    
        The two-dimensional image (array) to be thinned.
        
Example

The following commands display the "thinned" edges of 
a Sobel filtered image:

OPENR, 1, FILEPATH('people.dat', SUBDIR='images')
Open a file for reading.

A = BYTARR(192, 192)	Create a byte array in which to store the 
image.

READU, 1, A	Read first 192 by 192 image.

CLOSE, 1	Close the file.

TV, A, 0	Display the image.

TVSCL, THIN(SOBEL(A) GT 75), 1	Apply the Sobel filter, threshold the image 
at value 75, and display the thinned edges.

;-
;+
TOTAL

The TOTAL function returns the sum of the elements of 
Array. The sum of the array elements over a given dimen-
sion is returned if the Dimension argument is present.

Calling Sequence

        Result = TOTAL(Array [, Dimension])
        
Arguments

    Array
    
        The array to be summed. This array can be of any 
        basic type except string. If Array is double-preci-
        sion floating-point or complex, the result is of the 
        same type. Otherwise, the result is single-precision 
        floating-point.
        
    Dimension
    
The dimension over which to sum, starting at one. If this argument is not present or 
zero, the scalar sum of all the array elements is returned. If this argument is present, the result 
is an array with one less dimension than Array. Keywords

    DOUBLE
    
        Set this keyword to perform the summation in 
        double-precision floating-point. If this keyword is 
        set, TOTAL returns a double-precision result, unless 
        the operand is of complex type.
        
Example

Sum the elements of the array [20, 10, 5, 5, 3] and 
print the result by entering:

PRINT, TOTAL([20, 10, 5, 5, 3])

IDL prints:

   43.0000

When a multi-dimensional array is used, the results 
are different, as shown in the following example. Create a 
five-element by five-element array filled with floating-
point values by entering:

A = FINDGEN(5,5)

Display the sums of each of the rows in A by entering:

PRINT, TOTAL(A, 1)

IDL prints:

   10.0000   35.0000   60.0000   85.0000   110.000

Display the sums of each of the columns in A by enter-
ing:

PRINT, TOTAL(A, 2)

IDL prints:

   50.0000   55.0000   60.0000   65.0000   70.0000

;-
;+
TRANSPOSE

The TRANSPOSE function returns the transpose of 
Array.

Calling Sequence

        Result = TRANSPOSE(Array)
        
Arguments

    Array
    
        The array to be transposed. Array must have one 
        or two dimensions.
        
Example

Print a simple array and its transpose by entering:

PRINT, INDGEN(4,4)

PRINT, TRANSPOSE(INDGEN(4,4))

IDL prints the original array:

   0   1   2   3

   4   5   6   7

   8   9  10  11

  12  13  14  15

and its transpose:

   0   4   8  12

   1   5   9  13

   2   6  10  14

   3   7  11  15

;-
;+
TRIANGULATE

The TRIANGULATE procedure constructs a Delaunay tri-
angulation of a planar set of points. Delaunay triangula-
tions are very useful for the interpolation, analysis, and 
visual display of irregularly-gridded data. In most 
applications, after the irregularly gridded data points 
have been triangulated, the function TRIGRID is invoked to 
interpolate surface values to a regular grid.

Since Delaunay triangulations have the property that 
the circumcircle of any triangle in the triangulation con-
tains no other vertices in its interior, interpolated val-
ues are only computed from nearby points.

TRIANGULATE can, optionally, return the adjacency 
list that describes, for each node, the adjacent nodes in 
the Delaunay triangulation. With this list, the Voronoi 
polygon (the polygon described by the set of points which 
are closer to that node than to any other node) can be 
computed for each node. This polygon contains the area 
influenced by its associated node. Tiling of the region in 
this manner is also called Dirichlet, Wigner-Seithz, or 
Thiessen tessellation.

The grid returned by the TRIGRID function can be input 
to various routines such as SURFACE, TV, and CONTOUR. See 
the description of TRIGRID for an example.

Calling Sequence

        TRIANGULATE, X, Y, Triangles [, B]
        
Arguments

    X
    
        An array that contains the X coordinates of the 
        points to be triangulated.
        
    Y
    
        An array that contains the Y coordinates of the 
        points to be triangulated. Parameters X and Y must 
        have the same number of elements.
        
    Triangles
    
        A named variable that, on exit, contains the 
        list of triangles in the Delaunay triangulation of 
        the points specified by X and Y. Triangles is a 
        longword array dimensioned (3, Number-of-Triangles), 
        where Triangles(0, i), Triangles(1, i), and Trian-
        gles(2, i) contain the indices of the vertices of 
        the i-th triangle (i.e., X(Tr(*, i)) and Y(Trian-
        gles(*, i)) are the X and Y coordinates of the ver-
        tices of the i-th triangle).
        
    B
    
        An optional, named variable that, upon return, 
        contains a list of the indices of the boundary 
        points in counterclockwise order.
        
Keywords

    CONNECTIVITY
    
        Set this keyword to a named variable in which 
        the adjacency list for each of the N nodes (xy 
        point) is returned. The list has the following form:
        
        Each element i, , contains the starting 
        index of the connectivity list for node i within the 
        list array. To obtain the adjacency list for node i, 
        extract the list elements from LIST(i) to LIST(i+1)-
        1.
        
        The adjacency list is ordered in the counter-
        clockwise direction. The first item on the list of 
        boundary nodes is the subscript of the node itself. 
        For interior nodes, the list contains the subscripts 
        of the adjacent nodes in counter-clockwise order.
        
        For example, the call:
        
        TRIANGULATE, X, Y, CONNECTIVITY = LIST
        
        returns the adjacency list in the variable LIST. 
        The subscripts of the nodes adjacent to X(i) and 
        Y(i) are contained in the array:
        
        LIST(LIST(i) : LIST(i+1)-1)
        
    REPEATS
    
        Set this keyword to a named variable to return a 
        (2, n) list of the indices of duplicated points. 
        That is, for each i,
        
        X(REPEATS(0,i)) = X(REPEATS(1,i))
        
        and
        
        Y(REPEATS(0,i)) = Y(REPEATS(1,i))
        
;-
;+
TRIGRID

Given data points defined by the parameters X, Y, and 
Z and a triangulation of the planar set of points deter-
mined by X and Y, the TRIGRID function returns a regular 
grid of interpolated Z values. Linear or smooth quintic 
polynomial interpolation may be selected. Extrapolation 
for grid points outside of the triangulation area is also 
an option. The resulting grid is a two-dimensional array 
of the same data type as Z, with user specified bounds and 
spacing. An input triangulation can be constructed using 
the procedure TRIANGULATE. Together the TRIANGULATE pro-
cedure and the TRIGRID function constitute IDL's solution 
to the problem of irregularly-gridded data.

Calling Sequence

        Result = TRIGRID(X, Y, Z, Triangles [, GS, Lim-
        its])
        
Arguments

    X, Y, Z
    
        Input arrays of X, Y, and Z coordinates of data 
        points. Integer, long, double-precision and float-
        ing-point values are allowed. In addition, Z can be 
        a complex array. All three arrays must have the same 
        number of elements.
        
    Triangles
    
        A longword array of the form output by TRIANGU-
        LATE. That is, Triangles has the dimensions (3, Num-
        ber-of-Triangles) and, for each i, Triangles(0,i), 
        Triangles(1,i), and Triangles(2,i) are the indices 
        of the vertices of the i-th triangle.
        
    GS
    
        If present, GS should be a two-element vector 
        [XS, YS], where XS is the horizontal spacing between 
        grid points and YS is the vertical spacing. The 
        default is based on the extents of X and Y. If the 
        grid starts at X value x0 and ends at x1,then the 
        horizontal spacing is
        
        (X1- X0)/50
        
        The default for YS is computed in the same way. 
        Since the default grid spacing divides each axis 
        into 50 intervals and produces 51 samples, TRIGRID 
        returns a grid with dimensions (51, 51).
        
    Limits
    
        If present, Limits should be a four-element vec-
        tor [x0, y0, x1, y1], where x0 and y0 are the lower X 
        and Y grid limits, and x1 and y1 are the upper lim-
        its. The default for Limits is:
        
        [MIN(X), MIN(Y), MAX(X), MAX(Y)]
        
Keywords

    EXTRAPOLATE
    
        This keyword sets the quintic interpolation 
        mode. TRIGRID extrapolates to grid points outside 
        the triangulation if this keyword is assigned to the 
        array of boundary node indices returned by the 
        optional parameter B of the TRIANGULATE procedure. 
        The extrapolation is not smooth, but should give 
        acceptable results in most cases.
        
    MISSING
    
        The Z value to be used for grid points that lie 
        outside the triangles in Triangles. The default is 
        0.
        
    QUINTIC
    
        If QUINTIC is set, smooth interpolation is per-
        formed using Akima's quintic polynomials from "A 
        Method of Bivariate Interpolation and Smooth Surface 
        Fitting for Irregularly Distributed Data Points" in 
        ACM Transactions on Mathematical Software, 4, 148-
        159. The default method is linear interpolation.
        
        Derivatives are estimated by Renka's global 
        method in "A Triangle-Based C1 Interpolation Method" 
        in Rocky Mountain Journal of Mathematics, vol. 14, 
        no. 1, 1984.
        
        QUINTIC is not available for complex data val-
        ues. 
        
Example

The following example creates and displays a 50 point 
random normal distribution. The random points are then 
triangulated, with the triangulation displayed. Next, the 
interpolated surface is computed and displayed using lin-
ear and quintic interpolation. Finally, the smooth 
extrapolated surface is generated and shown.

x = RANDOMN(seed, 50)	Make 50 normal XY points.

y = RANDOMN(seed, 50)

z = EXP(-(x^2 + y^2))	Make the Gaussian.

PLOT, x, y, psym=1	Show points.

TRIANGULATE, x, y, tr, b	Obtain triangulation.

FOR i=0, N_ELEMENTS(tr)/3-1 DO BEGIN
Show the triangles.

  t = [tr(*,i), tr(0,i)]	Subscripts of vertices [0,1,2,0].

  PLOTS, x(t), y(t)	Connect triangles.

ENDFOR

SURFACE, TRIGRID(x, y, z, tr)	Show linear surface.

SURFACE, TRIGRID(x, y, z, tr, /QUINTIC)
Show smooth quintic surface.

SURFACE, TRIGRID(x, y, z, tr, EXTRA = b)
Show smooth extrapolated surface.

;-
;+
TRNLOG (VMS Only)

The TRNLOG function searches the VMS logical name 
tables for a specified logical name and returns the equiv-
alence string(s) in an IDL variable. TRNLOG also returns 
the VMS status code associated with the translation as a 
longword value. As with all VMS status codes, success is 
indicated by an odd value (least significant bit is set) 
and failure by an even value.

Calling Sequence

        Result = TRNLOG(Lognam, Value)
        
Arguments

    Lognam
    
        A scalar string containing the name of the logi-
        cal to be translated.
        
    Value
    
        A named variable into which the equivalence 
        string is placed. If Lognam has more than one equiv-
        alence string, the first one is used. The 
        FULL_TRANSLATION keyword can be used to obtain all 
        equivalence strings.
        
Keywords

    ACMODE
    
    The access mode to be used in the translation. The possible access modes 
    are:Mode        Value
    
    -----------------
    
    Kernal      0
    
    Executive   1
    
    Supervisor  2
    
    User        3
    
        When you specify the ACMODE keyword, all names 
        at access modes less privileged than the specified 
        mode are ignored. If you do not specify ACMODE, the 
        translation proceeds without regard to access mode. 
        However, the search proceeds from the outermost 
        (User) to the innermost (Kernal) mode. Thus, if two 
        logical names with the same name but different 
        access modes exist in the same table, the name with 
        the outermost access mode is used.
        
    FULL_TRANSLATION
    
        Set this keyword to obtain the full set of 
        equivalence strings for Lognam. By default, when 
        translating a multivalued logical name, Value only 
        receives the first equivalence string as a scalar 
        value. When this keyword is set, Value instead 
        returns a string array. Each element of this array 
        contains one of the equivalence strings. For exam-
        ple, under recent versions of VMS, the SYS$SYSROOT 
        logical can have multiple values. To see these val-
        ues from within IDL, enter:
        
        ret = TRNLOG('SYS$SYSROOT', trans, /FULL, /ISSUE_ERROR)
        Translate the logical.
        
        PRINT, trans	View the equivalence strings.
        
    ISSUE_ERROR
    
        Set this keyword to issue an error message if 
        the translation fails. Normally, no error is issued 
        and the user must examine the return value to deter-
        mine if the operation failed.
        
    RESULT_ACMODE
    
        If present, this keyword specifies a named vari-
        able in which to place the access mode of the trans-
        lated logical. The access modes are summarized 
        above.
        
    RESULT_TABLE
    
        If present, this keyword specifies a named vari-
        able. The name of the logical table containing the 
        translated logical is placed in this variable as a 
        scalar string.
        
    TABLE
    
        A scalar string giving the name of the logical 
        table in which to search for Lognam. If TABLE is not 
        specified, the standard VMS logical tables are 
        searched until a match is found, starting with 
        LNM$PROCESS_TABLE and ending with LNM$SYSTEM_TABLE.
        
;-
;+
TV

The TV procedure displays images on the image display 
without scaling the intensity. To display an image with 
scaling, use the TVSCL procedure.

Calling Sequence

        TV, Image [, Position]
        
        or
        
        TV, Image [, X, Y [, Channel]]
        
Arguments

    Image 
    
        A vector or two-dimensional array to be dis-
        played as an image. If this argument is not already 
        of byte type, it is converted prior to use.
        
    X, Y
    
        If X and Y are present, they specify the lower-
        left coordinate of the displayed image, relative to 
        the lower-left corner of the screen.
        
    Position
    
        An integer specifying the position for Image 
        within the graphics window. Image positions run from 
        the top left of the screen to the bottom right. 
        Note, when using a device with scalable pixels 
        (e.g., PostScript), the XSIZE and YSIZE keywords 
        should also be used.
        
    Channel
    
        The memory channel to be written. It is assumed 
        to be zero if not specified. This parameter is 
        ignored on display systems that have only one memory 
        channel. When using a "decomposed" display system, 
        the red channel is 1, the green channel is 2, and 
        the blue channel is 3. Channel 0 indicates all chan-
        nels.
        
Keywords

    CENTIMETERS
    
        Set this keyword to indicate that the X, Y, 
        Xsize, Ysize, and Z arguments are given in centime-
        ters from the origin. This system is useful when 
        dealing with devices, such as PostScript printers, 
        that do not provide a direct relationship between 
        image pixels and the size of the resulting image.
        
    CHANNEL
    
        The memory channel to be written. The effect of 
        this keyword parameter is identical to the Channel 
        positional parameter. Either one can be used.
        
    DATA
    
        Set this keyword to indicate that all position 
        and size values are given in data coordinates. This 
        system is useful when drawing an image over an 
        existing plot, since the plot establishes the data 
        scaling.
        
    DEVICE
    
        Set this keyword to indicate that all position 
        and size values are given in device coordinates (the 
        default).
        
    INCHES
    
        Set this keyword to indicate that all position 
        and size values are given in inches from the origin. 
        This system is useful when dealing with devices, 
        such as PostScript printers, that do not provide a 
        direct relationship between image pixels and the 
        size of the resulting image.
        
    NORMAL 
    
        Set this keyword to indicate that all position 
        and size values are given in normalized coordinates 
        in the range 0 to 1.0, inclusive. This system is 
        useful when it is desired to position the image in a 
        device-independent manner.
        
    ORDER
    
        If specified, ORDER overrides the current set-
        ting of the !ORDER system variable for the current 
        image only. If set, the image is drawn from the top 
        down instead of the normal bottom up.
        
    T3D
    
        Set this keyword to use the generalized trans-
        formation matrix stored in !P.T. If not present, the 
        user-supplied coordinates are simply scaled to 
        screen coordinates. For a description of !P.T and 
        how it is used, see the description of the SAVE key-
        word to the SURFACE procedure (page -267).
        
    TRUE
    
        Set this keyword to a nonzero value to indicate 
        that a true-color image is to be displayed. The 
        value assigned to TRUE specifies the index of the 
        dimension over which color is interleaved. The image 
        parameter must have three dimensions, one of which 
        must be equal to three. For example, set TRUE to 1 
        to display an image that is pixel interleaved and 
        has dimensions of (3, m, n). Specify 2 for row-
        interleaved images, of size (m, 3, n), and 3 for 
        band-interleaved images of the form (m, n, 3).
        
        Use this keyword to write 24-bit images to the 
        PostScript device. See page 3-40 for an example.
        
    WORDS
    
        Set this keyword to indicate that words (short 
        integers) instead of 8-bit bytes are to be trans-
        ferred to the device. This keyword is valid only 
        when using devices that can transfer 16-bit pixels. 
        The normal transfer uses 8-bit pixels. If this key-
        word is set, the Image parameter is converted to 
        short integer type, if necessary, and then written 
        to the display.
        
    XSIZE
    
        The width of the resulting image. This keyword 
        is ignored by pixel-based devices that are unable to 
        change the size of their pixels, and is intended for 
        use by devices with scalable pixel size (such as 
        PostScript).
        
    YSIZE
    
        The height of the resulting image. This keyword 
        has the same restrictions as XSIZE.
        
    Z
    
        The Z position for the image. The value of Z is 
        used only if the three-dimensional transformation 
        made active via the T3D keyword.
        
Example

Create and display a simple image by entering:

D = BYTSCL(DIST(256)) & TV, D

Erase the screen by entering:

ERASE

Use the position parameter to display a number of 
images in the same window. Display the image in the upper 
left corner by entering:

TV, D, 0

Display another copy of the image in the next position 
by entering:

TV, D, 1

;-
;+
TVCRS

The TVCRS procedure manipulates the display device 
cursor. The initial state of the cursor is device depen-
dent. Call TVCRS with one argument to enable or disable 
the cursor. Call TVCRS with two parameters to enable the 
cursor and place it on pixel location (X, Y).

Calling Sequence

        TVCRS [, ON_OFF]
        
        or
        
        TVCRS [, X, Y]
        
Arguments

    ON_OFF
    
        This argument specifies whether the cursor 
        should be on or off. If this argument is present and 
        nonzero, the cursor is enabled. If ON_OFF is zero or 
        no parameters are specified, the cursor is turned 
        off.
        
    X
    
        The column to which the cursor is set.
        
    Y
    
        The row to which the cursor is set.
        
Keywords

    HIDE_CURSOR
    
        By default, disabling the cursor works differ-
        ently for window systems than for other devices. For 
        window systems, the cursor is restored to the stan-
        dard cursor used for non-IDL windows (and remains 
        visible), while for other devices it is completely 
        blanked out. If the HIDE keyword is set, disabling 
        the cursor causes it to always be blanked out.
        
Graphics Keywords Accepted

        See Chapter 2, Graphics Keywords and System 
        Variables, for the description of graphics and plot-
        ting keywords not listed above. CENTIMETERS DATA 
        DEVICE INCHES NORMAL T3D Z.
        
Example

To enable the graphics cursor and position it at 
device coordinate (100, 100), enter:

TVCRS, 100, 100

To position the cursor at data coordinate (0.5, 3.2), 
enter:

TVCRS, 0.5, 3.2, /DATA

;-
;+
TVLCT

The TVLCT procedure loads the display color transla-
tion tables from the specified variables. Although IDL 
uses the RGB color system internally, color tables can be 
specified to TVLCT using any of the following color sys-
tems: RGB (Red, Green, Blue), HLS (Hue, Lightness, Satura-
tion), and HSV (Hue, Saturation, Value). The type and 
meaning of each argument is dependent upon the color sys-
tem selected, as described below. Color arguments can be 
either scalar or vector expressions. If no color-system 
keywords are present, the RGB color system is used. See 
Chapter 16 of the IDL User's Guide for a more complete 
explanation of color systems.

Calling Sequence

        TVLCT, V1, V2, V3 [, Start]
        
        or
        
        TVLCT, V [, Start]
        
Arguments

        TVLCT will accept either three n-element vectors 
        (V1, V2, and V3) or a single n by 3 array (V) as an 
        argument. If an array V is specified, V(*,0) is the 
        same as V1, V(*,1) is the same as V2, and V(*,2) is 
        the same as V3. In the description below we assume 
        that three vectors V1, V2, and V3 are specified.
        
        The V1, V2, and V3 arguments have different mean-
        ings depending upon which color system they repre-
        sent. 
        
    R, G, B Color System
    
        The parameters V1, V2, and V3 contain the Red, 
        Green, and Blue values respectively. Values are 
        interpreted as integers in the range 0 (lowest 
        intensity) to 255 (highest intensity). The parame-
        ters can be scalars or vectors of up to 256 ele-
        ments. By default, the three arguments are assumed 
        to be R, G, and B values.
        
    H, L, S Color System
    
        Parameters V1, V2, and V3 contain the Hue, Light-
        ness, and Saturation values respectively. All param-
        eters are floating-point. Hue is expressed in 
        degrees and is reduced modulo 360. V2 (lightness) 
        and V3 (saturation) can range from 0 to 1.0. Set the 
        HLS keyword to have the arguments interpreted this 
        way.
        
    H, S, V Color System
    
        Parameters V1, V2, and V3 contain values for Hue, 
        Saturation, and Value (similar to intensity). All 
        parameters are floating-point. Hue is in degrees. 
        The Saturation and Value can range from 0 to 1.0. 
        Set the HSV keyword to have the arguments inter-
        preted this way.
        
    Start
    
        An integer value that specifies the starting 
        point in the color translation table into which the 
        color intensities are loaded. If this argument is 
        not specified, a value of zero is used, causing the 
        tables to be loaded starting at the first element of 
        the translation tables.
        
Keywords

    GET
    
        Set this keyword to return the RGB values from 
        the internal color tables into the V1, V2, and V3 
        parameters. For example, the statements:
        
        TVLCT, H, S, V, /HSV
        
        TVLCT, R, G, B, /GET
        
        load a color table based in the HSV system, and 
        then read the equivalent RGB values into the vari-
        ables R, G, and B.
        
    HLS
    
        Set this keyword to indicate that the parameters 
        specify color using the HLS color system.
        
    HSV
    
        Set this keyword to indicate that the parameters 
        specify color using the HSV color system.
        
Example

Create a set of R, G, and B colormap vectors by enter-
ing the following commands:

R = BYTSCL(SIN(FINDGEN(256)))

G = BYTSCL(COS(FINDGEN(256)))

B = BINDGEN(256)

Load these vectors into the color table by entering:

TVLCT, R, G, B

Display an image to see the effect of the new color 
table:

TVSCL, DIST(400)

;-
;+
TVRD

The TVRD function returns the contents of the speci-
fied rectangular portion of the display subsystem's mem-
ory. (X0, Y0) is the coordinate of the lower left corner 
of the area to be read and Nx, Ny is the size of the rect-
angle in columns and rows. The result is a byte array of 
dimensions Nx by Ny. All parameters are optional. If no 
arguments are supplied, the entire display device area is 
read.

Calling Sequence

        Result = TVRD([X0 [, Y0 [, Nx [, Ny [, Chan-
        nel]]]]])
        
Arguments

    X0
    
        The starting column of data to read. The default 
        is 0.
        
    Y0
    
        The starting row of data to read. The default is 
        0.
        
    Nx
    
        The number of columns to read. The default is 
        the width of the display device or window less X0.
        
    Ny
    
        The number of rows to read. The default is the 
        height of the display device or window less Y0.
        
    Channel
    
        The memory channel to be read. If not specified, 
        this argument is assumed to be zero. This parameter 
        is ignored on display systems that have only one 
        memory channel.
        
Keywords

    CHANNEL
    
        The memory channel to be written. This keyword 
        parameter is identical to the Channel positional 
        parameter.
        
        Note: if the display is a 24-bit display, and 
        both the CHANNEL and TRUE parameters are absent, the 
        maximum RGB value in each pixel is returned.
        
    ORDER
    
        Set this keyword to override the current setting 
        of the !ORDER system variable for the current image 
        only. If set, it causes the image to be read from 
        the top down instead of the normal bottom up.
        
    TRUE
    
        If this keyword is present, it indicates that a 
        true-color image is to be read, if the display is 
        capable. The value assigned to TRUE specifies the 
        index of the dimension over which color is inter-
        leaved. The result is an (3, Nx, Ny) pixel-inter-
        leaved array if TRUE is 1; or an (Nx, 3, Ny) line-
        interleaved array if TRUE is 2; or an (Nx, Ny, 3) 
        image-interleaved array if TRUE is 3.
        
    WORDS
    
        Set this keyword to indicate that words are to 
        be transferred from the device. This keyword is 
        valid only when using devices that can transfer 16-
        bit pixels. The normal transfer uses 8-bit pixels. 
        If this keyword is set, the function result is an 
        integer array.
        
Example

To read the entire contents of the current display 
device into the variable T, enter:

T = TVRD()

;-
;+
TVSCL

The TVSCL procedure scales the intensity values of 
Image into the range of the image display and outputs the 
data to the image display at the specified location. The 
array is scaled so the minimum data value becomes 0 and 
the maximum value becomes the maximum number of available 
colors (held in the system variable !D.TABLE_SIZE) as fol-
lows:Output = !D.TABLE_SIZE(Data - Datamin)/(Datamax - 
Datamin)

where the maximum and minimum are found by scanning 
the array. The parameters and keywords of the TVSCL proce-
dure are identical to those accepted by the TV procedure. 
For additional information about each parameter, consult 
the description of TV.

Calling Sequence

        TVSCL, Image [, Position]
        
        or
        
        TVSCL, Image [, X, Y [, Channel]]
        
Arguments

    Image
    
        A two-dimensional array to be displayed as an 
        image. If this argument is not already of byte type, 
        it is converted prior to use.
        
    X, Y
    
        If X and Y are present, they specify the lower 
        left coordinate of the displayed image.
        
    Position
    
        Image position. See the discussion of the TV 
        procedure for a full description.
        
    Channel
    
        The memory channel to be written. This argument 
        is assumed to be zero if not specified. This parame-
        ter is ignored on display systems that have only one 
        memory channel.
        
Keywords

        See the description of the TV procedure for a 
        list and description of accepted keyword parameters.
        
Example

Display a floating-point array as an image using the 
TV command. Enter:

TV, DIST(200)

Note that the image is not easily visible because the 
values in the array have not been scaled into the full 
range of display values. Now display the image with the 
TVSCL command by entering:

TVSCL, DIST(200)

Notice how much brighter the image appears.

;-
;+
USERSYM

The USERSYM procedure is used to define the plotting 
symbol that marks points when the plotting symbol is set 
to plus or minus 8. Symbols can be drawn with vectors or 
can be filled. Symbols can be of any size and can have up 
to 50 vertices. See "Defining Your Own Plotting Symbols" 
on page 14-12 of the IDL User's Guide.

Calling Sequence

        USERSYM, X [, Y]
        
Arguments

    X, Y
    
        The X and/or Y parameters define the vertices of 
        the symbol as offsets from the data point in units 
        of approximately the size of a character. In the 
        case of a vector drawn symbol, the symbol is formed 
        by connecting the vertices in order. If only one 
        argument is specified, it must be a (2, N) array of 
        vertices, with element (0, i) containing the X coor-
        dinate of the vertex, and element (1, i) containing 
        the Y. If both arguments are provided, X contains 
        only the X coordinates.
        
Keywords

    COLOR
    
        The color used to draw the symbols, or used to 
        fill the polygon. The default color is the same as 
        the line color.
        
    FILL
    
        Set this keyword to fill the polygon defined by 
        the vertices. If FILL is not set, lines are drawn 
        connecting the vertices.
        
    THICK
    
        The thickness of the lines used in drawing the 
        symbol. The default thickness is 1.0.
        
Example

Make a large, diamond-shaped plotting symbol. Define 
the vectors of X values by entering:

X = [-6, 0, 6, 0, -6]

Define the vectors of Y values by entering:

Y = [0, 6, 0, -6, 0]

Now call USERSYM to create the new plotting symbol 8. 
Enter:

USERSYM, X, Y

Generate a simple plot to test the plotting symbol by 
entering:

PLOT, FINDGEN(20), PSYM = 8

;-
;+
VOIGT

The VOIGT function returns the intensity of a VOIGT 
profile based on the Voigt a parameter and the frequency, 
u, in units of the Doppler frequency. The result is always 
floating-point and has the same structure as the argu-
ments. Note that a and u should not both be vectors.For 
information on the algorithm used by VOIGT, see the IDL 
Reference Guide.

Calling Sequence

        Result = VOIGT(A, U)
        
Arguments

    A
    
        The Voigt a parameter.
        
    U
    
        The frequency u.
        
;-
;+
VOXEL_PROJ

The VOXEL_PROJ function generates visualizations of 
volumetric data by computing 2D projections of a colored, 
semi-transparent volume. Parallel rays from any given 
direction are cast through the volume, onto the viewing 
plane. User-selected colors and opacities can be assigned 
to arbitrary data ranges, simulating the appearance of the 
materials contained within the volume.

The VOXEL_PROJ function can be combined with the Z-
buffer to render volume data over objects. Cutting planes 
can also be specified to view selected portions of the 
volume. Other options include: selectable resolution to 
allow quick "preview" renderings, and average and maximum 
projections.

VOXEL_PROJ renders volumes using an algorithm similar 
to the one described by Drebin, Carpenter, and Hanrahan, 
in "Volume Rendering", Computer Graphics, Volume 22, Num-
ber 4, August 1988, pp. 125-134, but without the surface 
extraction and enhancement step.

Voxel rendering can be quite time consuming. The time 
required to render a volume is proportional to the viewing 
area's size, in pixels, times the thickness of the volume 
cube in the viewing direction, divided by the product of 
the user-specified X, Y, and Z steps.

Calling Sequence

        Result = VOXEL_PROJ(V [, RGBO])
        
Arguments

    V
    
        A three-dimensional array containing the volume 
        to be rendered. This array is converted to byte type 
        if necessary.
        
    RGBO
    
        This optional parameter is used to specify the 
        look-up tables that indicate the color and opacity 
        of each voxel value. This argument can be one of the 
        following types:
        
        A (256, 4) byte array for true-color rendering. 
        This array represents 256 sets of red, green, blue, 
        and opacity (RGBO) components for each voxel value, 
        scaled into the range of bytes (0 to 255). The R, G, 
        and B components should already be scaled by the 
        opacity. For example, if a voxel value of 100 con-
        tains a material that is red, and 35% opaque, the 
        RGBO values should be, respectively: [89, 0, 0, 89] 
        because 255 * 0.35 = 89. If more than one material 
        is present, the RGBO arrays contain the sum of the 
        individual RGBO arrays. The content and shape of the 
        RGBO curves is highly dependent upon the volume data 
        and experimentation is often required to obtain the 
        best display.
        
        A (256, 2) byte array for volumes with only one 
        material or monochrome rendering. This array repre-
        sents 256 sets of pixel values and their correspond-
        ing opacities for each voxel value.
        
        If this argument is omitted, the average projec-
        tion method, or maximum intensity method (if the 
        MAXIMUM_INTENSITY keyword is set) is used.
        
Keywords

    BACKGROUND
    
        A one- or three-element array containing the 
        background color indices. The default is (0,0,0), 
        yielding a black background with most color tables.
        
    CUTTING_PLANE
    
        A floating-point array specifying the coeffi-
        cients of additional cutting planes. The array has 
        dimensions of (4, N), where N is the number of addi-
        tional cutting planes from 1 to 6. Cutting planes 
        are constraints in the form of:
        
        C(0) * X + C(1) * Y + C(2) * Z + D > 0
        
        The X, Y, and Z coordinates are specified in 
        voxel coordinates. For example, to specify a cutting 
        plane that excludes all voxels with an X value 
        greater than 10:
        
        CUTTING_PLANE = [-1.0, 0, 0, 10.], for the con-
        straint: -X + 10 > 0.
        
    INTERPOLATE
    
        Set this keyword to use tri-linear interpolation 
        to determine the data value for each step on a ray. 
        Otherwise, the nearest-neighbor method is used. Set-
        ting this keyword improves the quality of images 
        produced, especially when the volume has low resolu-
        tion in relation to the size of the viewing plane, 
        at the cost of more computing time.
        
    MAXIMUM_INTENSITY
    
        Set this keyword to make the value of each pixel 
        in the viewing plane the maximum data value along 
        the corresponding ray. The RGBO argument is ignored 
        if present.
        
    STEP
    
        Set this keyword to a three-element vector, [Sx, 
        Sy, Sz], that controls the resolution of the result-
        ing projection. The first two elements contain the 
        step size in the X and Y view plane, in pixels. The 
        third element is the sampling step size in the Z 
        direction, given in voxels. Sx and Sy must be inte-
        gers equal to or greater than one, while Sz can con-
        tain a fractional part. If Sx or Sy are greater than 
        one, the values of intermediate pixels in the output 
        image are linearly interpolated. Higher step sizes 
        require less time because fewer rays are cast, at 
        the expense of lower resolution in the output image. 
        
    XSIZE
    
        The width, in pixels, of the output image. If 
        this keyword is omitted, the output image is as wide 
        as the currently-selected output device.
        
    YSIZE
    
        The height, in pixels, of the output image. If 
        this keyword is omitted, the output image is as tall 
        as the currently selected output device. 
        
    ZBUFFER
    
        An integer array, with the same width and height 
        as the output image, that contains the depth portion 
        of the Z-buffer. Include this parameter to combine 
        the previously-read contents of a Z-buffer with a 
        voxel rendering. See the third example, below, for 
        details.
        
    ZPIXELS
    
        A byte array, with the same width and height as 
        the output image, that contains the image portion of 
        the Z-buffer. Include this parameter to combine the 
        contents of a Z-buffer with a voxel rendering. See 
        the third example, below, for details.
        
Examples

In the following example, assume that variable V con-
tains a volume of data, with dimensions Vx by Vy by Vz. 
The volume contains two materials, muscle tissue repre-
sented by a voxel range of 50 to 70, that we want to ren-
der with red color, and an opacity of 20; and bone tissue 
represented by a voxel range of 220-255, that we want to 
render with white color, and an opacity of 50:

rgbo = BYTARR(256,4)	Create the opacity vector.

rgbo(50:70, [0,3]) = 20	Red and opacity for muscle.

rgbo(220:255, *) = 50	White and opacity for bone.

Although it is common to use trapezoidal or Gaussian 
functions when forming the RGBO arrays, this example uses 
rectangular functions for simplicity.

SCALE3, XRANGE=[0, Vx-1], YRANGE=[0, Vy-1], ZRANGE=[0, Vz-
1]
Set up the axis scaling and default rotation.

C = VOXEL_PROJ(V, rgbo)	Compute projected image.

TV, COLOR_QUAN(C, 3, R, G, B)	Convert from 24-bit to 8-bit image and dis-
play.

TVLCT, R, G, B	Load quantized color tables.

This example required approximately 27 seconds on a 
typical workstation to compute the view in a 640- by 512-
pixel viewing window. Adding the keyword STEP=[2,2,1] in 
the call to VOXEL_PROJ decreased the computing time to 
about 8 seconds, at the expense of slightly poorer resolu-
tion.



When viewing a volume with only one constituent, the 
RGBO array should contain only an intensity/opacity value 
pair. To illustrate, if in the above example, only muscle 
was of interest we create the RGBO argument as follows:

rgbo = BYTARR(256,2)	Create an empty 256 x 2 array.

rgbo(50:70, *) = 20	Intensity and opacity for muscle

SCALE3, XRANGE=[0, Vx-1], YRANGE=[0, Vy-1], ZRANGE=[0, Vz-
1]

TV, VOXEL_PROJ(V, rgbo)	Compute and display the projected image.

C = (FINDGEN(256)/255.) # [255., 0., 0]
Create color table array for red.

TVLCT, C(*,0), C(*,1), C(*,2)	Load colors.



The following example demonstrates combining a volume 
with the contents of the Z-buffer:

SET_PLOT, 'Z'	Set plotting to Z-buffer.

DEVICE, /Z_BUFFER	Turn on Z buffering.

SCALE3, XRANGE=[0, Vx-1], YRANGE=[0, Vy-1], ZRANGE=[0, Vz-
1]
Set scaling.

POLYFILL, [0, Vx-1, Vx-1, 0], [0, 0, Vy-1, Vy-1], Vz/2., /
T3D
Draw a polygon at z equal to half the depth

zpix = TVRD()	Read pixel values from the Z-buffer.

zbuff = TVRD(/WORDS,/CHAN)	Read depth values from the Z-buffer.

SET_PLOT, 'X'
Back to display window

C = VOXEL_PROJ(V, rgbo, ZPIX=zpix, ZBUFF=zbuff)
Compute the voxel projection and use the 
ZPIXELS nad ZBUFFER keywords to com-
bine the volume with the previously-read 
contents of the Z-buffer.

TV, COLOR_QUAN(C, 3, R, G, B)	Convert from 24-bit to 8-bit image and dis-
play.

TVLCT, R, G, B	Load the quantized color tables. 



;-
;+
WAIT

The WAIT procedure suspends execution of an IDL pro-
gram for a specified period. Note that because of other 
activity on the system, the duration of program suspension 
may be longer than requested.

Calling Sequence

        WAIT, Seconds
        
Arguments

    Seconds
    
        The duration of the wait, specified in seconds. 
        This parameter can be a floating-point value to 
        specify a fractional number of seconds.
        
Example

To make an IDL program suspend execution for about 
five and one half seconds, use the command:

WAIT, 5.5

;-
;+
WDELETE

The WDELETE procedure deletes IDL windows.

Calling Sequence

        WDELETE [, Window_Index [, ...]]
        
Arguments

    Window_Index
    
        A list of one or more window indices to delete. 
        If this argument is not specified, the current win-
        dow (as specified by the system variable !D.WINDOW) 
        is deleted. If the window being deleted is not the 
        active window, the value of !D.WINDOW remains 
        unchanged. If the window being deleted is the active 
        window, !D.WINDOW is set to the highest numbered 
        window index or to -1 if no windows remain open.
        
        If this window index is the widget ID of a draw 
        widget, that widget is deleted.
        
Example

Create IDL graphics window number 5 by entering:

WINDOW, 5

Delete window 5 by entering:

WDELETE, 5

;-
;+
WEOF (VMS Only)

The WEOF procedure writes an end of file mark, some-
times called a tape mark, on the designated tape unit at 
the current position. The tape must be mounted as a for-
eign volume. See the description of the magnetic tape rou-
tines in Chapter 17 of the IDL User's Guide.

Calling Sequence

        WEOF, Unit
        
Arguments

    Unit
    
        The magnetic tape unit on which the end of file 
        mark is written. This argument must be a number 
        between 0 and 9, and should not be confused with 
        standard file Logical Unit Numbers (LUNs).
        
;-
;+
WHERE

The WHERE function returns a longword vector that con-
tains the one-dimensional subscripts of the nonzero ele-
ments of Array_Expression. The length of the resulting 
vector is equal to the number of nonzero elements in the 
parameter. Frequently the result of WHERE is used as a 
vector subscript to select elements of an array using 
given criteria. If all elements of Array_Expression are 
zero the result of WHERE is a scalar integer with the 
value -1.

Note that the system variable !ERR is set to the num-
ber of nonzero elements. This effect is for compatibility 
with previous versions of IDL and should not be used in 
new code. Use the COUNT argument to return this value 
instead.

Calling Sequence

        Result = WHERE(Array_Expression [, Count])
        
Arguments

    Array_Expression
    
        The array to be searched. This argument can be 
        of any basic type except string. Both the real and 
        imaginary parts of a complex number must be zero for 
        the number to be considered zero.
        
    Count
    
        A named variable that, on exit, is set to the 
        number of nonzero elements found in 
        Array_Expression. This value is returned as a long-
        word integer.
        
When WHERE Returns -1

If all the elements of Array_Expression are zero, 
WHERE returns a scalar integer with a value of -1. 
Attempting to use this result as an index into another 
array results in a "subscripts out of bounds" error. In 
situations where this is possible, code similar to the 
following can be used to avoid errors:

index = WHERE(array, count)	Use Count to get the number of nonzero ele-
ments.

IF count NE 0 THEN result = array(index)
Only subscript the array if it's safe.

Example

Create a 100-element, floating-point array where each 
element is set to the value of its subscript by entering:

array = FINDGEN(100)

To find the subscripts of all the elements in the 
array that have values greater than 20, enter:

B = WHERE(array GT 20, count)

To see how many elements meeting the search criteria 
were found, enter:

PRINT, count

To see the subscripts of the found elements, enter:

PRINT, B

To make an array containing the values of array 
referred to by B, enter:

values = array(B)

;-
;+
WIDGET_BASE

The WIDGET_BASE function is used to create base wid-
gets. Base widgets serve as containers for other widgets.

The returned value of this function is the widget ID 
of the newly-created base.

Calling Sequence

        Result = WIDGET_BASE([Parent])
        
Arguments

    Parent
    
        The widget ID of the parent widget. To create a 
        top-level widget, omit the Parent argument.
        
Keywords

    COLUMN
    
        If this keyword is included, the base lays out 
        its children in columns. The value of this keyword 
        specifies the number of columns to be used. When one 
        column is filled, a new one is started.
        
        Note that the standard base widget does not 
        impose any placement constraints on its child wid-
        gets. However, laying out widgets using the XSIZE, 
        YSIZE, XOFFSET, and YOFFSET keywords can be both 
        tedious and error-prone. Also, if you want your wid-
        get application to display properly on different 
        platforms, you should use the COLUMN and ROW key-
        words to influence child widget layouts instead of 
        explicitly formatting your interfaces.
        
    EVENT_FUNC
    
        A string containing the name of a function to be 
        called by the WIDGET_EVENT function when an event 
        arrives from a widget in the widget hierarchy rooted 
        at the newly-created widget.
        
    EVENT_PRO
    
        A string containing the name of a procedure to 
        be called by the WIDGET_EVENT function when an event 
        arrives from a widget in the widget hierarchy rooted 
        at the newly-created widget.
        
    EXCLUSIVE
    
        Set this keyword to specify that the base can 
        have only button-widget children and that only one 
        button can be set at a time. These buttons, unlike 
        normal button widgets, have two states-set and 
        unset.
        
        When one exclusive button is pressed, any other 
        exclusive buttons (in the same base) that are cur-
        rently set are automatically released. Hence, only 
        one button can ever be set at one time.
        
        This keyword can be used to create exclusive 
        button menus. See the User's Library routine 
        CW_BGROUP and CW_PDMENU for high-level menu-creation 
        utilities.
        
    FRAME
    
        The value of this keyword specifies the width of 
        a frame (in pixels) to be drawn around the borders 
        of the widget. Note that this keyword is only a hint 
        to the toolkit, and may be ignored in some 
        instances.
        
    FUNC_GET_VALUE
    
        A string containing the name of a function to be 
        called when the GET_VALUE keyword to the 
        WIDGET_CONTROL procedure is called for this widget. 
        Using this technique allows you to change the value 
        that should be returned for a widget. Compound wid-
        gets use this ability to define their values trans-
        parently to the user.
        
    GROUP_LEADER
    
        The widget ID of an existing widget that serves 
        as "group leader" for the newly-created widget. When 
        a group leader is killed, for any reason, all wid-
        gets in the group are also destroyed.
        
        A given widget can be in more than one group. 
        The WIDGET_CONTROL procedure can be used to add 
        additional group associations to a widget. It is not 
        possible to remove a widget from an existing group.
        
    KILL_NOTIFY
    
        A string containing the name of a procedure to 
        be called automatically when the specified widget 
        dies. Each widget is allowed a single such "call-
        back" procedure. It can be removed by setting the 
        routine to the null string ('').
        
        The callback routine is called with the widget 
        identifier as its only argument. At that point, the 
        widget identifier can only be used with the 
        WIDGET_CONTROL procedure to get or set the user 
        value. All other requests that require a widget ID 
        are disallowed for the target widget. The callback 
        is not issued until the WIDGET_EVENT function is 
        called. If a "kill notify" procedure causes an error 
        that halts the execution of the procedure, the halt 
        occurs in the procedure that called WIDGET_EVENT, 
        not in the kill notify procedure itself.
        
    MAP
    
        Once a widget hierarchy has been realized, it 
        can be mapped (visible) or unmapped (invisible). 
        This keyword specifies the initial map state for the 
        given base and its descendants. Specifying a non-
        zero value indicates that the base should be mapped 
        when realized (the default). A zero value indicates 
        that the base should be unmapped initially.
        
        After the base is realized, its map state can be 
        altered using the MAP keyword to the WIDGET_CONTROL 
        procedure.
        
    NO_COPY
    
        Usually, when the SET_UVALUE, GET_UVALUE, or 
        SEND_EVENT keywords are used, the source variable 
        memory is copied. When the NO_COPY keyword is set, 
        the source variable dynamic memory is used by the 
        destination, without copying. This feature can be 
        used by compound widgets to obtain state information 
        from a UVALUE without all the memory copying that 
        would otherwise occur.
        
    NONEXCLUSIVE
    
        Set this keyword to specify that the base can 
        only have button widget children. These buttons, 
        unlike normal button widgets, have two states-set 
        and unset.
        
        Non-exclusive bases allow any number of the tog-
        gle buttons to be set at one time.
        
    PRO_SET_VALUE
    
        A string containing the name of a procedure to 
        be called when the SET_VALUE keyword to the 
        WIDGET_CONTROL procedure is called for this widget. 
        Using this technique allows you to designate a rou-
        tine that sets the value for a widget. Compound wid-
        gets use this ability to define their values 
        transparently to the user.
        
    RESOURCE_NAME
    
        A string containing an X Window System resource 
        name to be applied to the widget. Once defined, this 
        name can be used in the user's .Xdefaults file to 
        customize widget resources not directly supported 
        via the IDL widget routines. This keyword is 
        accepted by all widget creation routines. This key-
        word only works with the "X" device and is ignored 
        on platforms that do not use the X Window System 
        (i.e., IDL for Windows, IDL for Macintosh).
        
        RESOURCE_NAME allows unrestricted access to the 
        underlying Motif widgets within the following limi-
        tations:
        
        Users must have the appropriate resources 
        defined in their .Xdefaults or application default 
        resource file, or IDL will not see the definitions 
        and they will not take effect.
        
        Motif resources are documented in the OSF/Motif 
        Programmer's Reference Manual. To use them with 
        RESOURCE_NAME, the IDL programmer must determine the 
        type of widget being used by IDL, and then look up 
        the resources that apply to them. Hence, 
        RESOURCE_NAME requires some programmer-level famil-
        iarity with Motif.
        
        Only resources that are not set within IDL can 
        be modified using this mechanism. Although it is not 
        an error to set resources also set by IDL, the IDL 
        settings will silently override user settings. 
        Research Systems does not document the resources 
        used by IDL since the actual resources used may dif-
        fer from release to release as the IDL widgets 
        evolve. Therefore, you should set only those 
        resources that are obviously not being set by IDL. 
        Among the resources that are not being set by IDL 
        are those that control colors, menu mnemonics, and 
        accelerator keys.
        
        Example of Using RESOURCE_NAME
        
        The sample code below produces a pulldown menu 
        named "Menu" with 2 entries named "Item 1" and "Item 
        2".
        
        Using the RESOURCE_NAME keyword in conjunction 
        with X resource definitions, we can alter "Item 1" 
        in several ways not possible through the standard 
        IDL widgets interface. We'll give Item 1 a red back-
        ground color. We'll also assign "I" as the keyboard 
        mnemonic. Note that Motif automatically underlines 
        the "I" in the title to indicate this. We'll also 
        select Meta-F4 as the keyboard accelerator for 
        selecting "Item 1". If Meta-F4 is pressed while the 
        pointer is anywhere over this application, the 
        effect will be as if the menu was pulled down and 
        "Item 1" was selected with the mouse.
        
        PRO test_event, ev	Simple event handler.
        
        HELP, /STRUCTURE, ev
        
        END
        
        PRO test	Simple widget creation routine.
        
        a = WIDGET_BASE(RESOURCE_NAME = 'test')
        The base gets the resource name 
        "test".
        
        b = WIDGET_BUTTON(a, VALUE='Menu', /MENU)
        
        c = WIDGET_BUTTON(b, VALUE='Item 1', $
        
                          RESOURCE_NAME='item1')
        Assign the Item 1 button the resource 
        name "item1".
        
        c = WIDGET_BUTTON(b, VALUE='Item 2')
        
        WIDGET_CONTROL, /REALIZE, a 
        
        XMANAGER, 'test', a 
        
        END
        
        Note that we gave the overall application the 
        resource name "test", and the "Item 1" button the 
        resource name "item1". Now we can use these names in 
        the following .Xdefaults file entries:
        
        Idl*test*item1*mnemonic: I
        
        Idl*test*item1*accelerator: Meta<Key>F4
        
        Idl*test*item1*acceleratorText: Meta-F4
        
        Idl*test*item1*background: red
        
    ROW
    
        If this keyword is included, the base lays out 
        its children in rows. The value of this keyword 
        specifies the number of rows to be used. When one 
        row is filled, a new one is started.
        
        This keyword is similar to the COLUMN keyword 
        described above.
        
    SCROLL
    
        Set this keyword to give the widget scroll bars 
        that allow viewing portions of the widget contents 
        that are not currently on the screen.
        
    SPACE
    
        The space, in pixels, between children of a row 
        or column major base. This keyword is ignored if 
        either the EXCLUSIVE or NONEXCLUSIVE keyword is 
        present.
        
    TITLE
    
        A string containing the title to be used for the 
        widget. Base widgets use the title only if they are 
        top-level widgets.
        
        Note that if the widget base is not wide enough 
        to contain the specified title, the title may appear 
        truncated. If you must be able to see the full 
        title, you have several alternatives:
        
        Rearrange the widgets in the base so that the 
        base becomes naturally wide enough. This is the best 
        solution.
        
        Most X windows programs don't worry about this 
        issue. If the user needs to see the entire label, 
        they can resize the window using the mouse.
        
        Create the base without using the COLUMN or ROW 
        keywords. Instead, use the XSIZE keyword to explic-
        itly set a usable width. This is an undesirable 
        solution that can lead to strange-looking widget 
        layouts.
        
    TLB_SIZE_EVENTS
    
        Set this keyword, when creating a top-level 
        base, to make that base return an event when the 
        base is resized by the user. See the "Events" sec-
        tion below for more information.
        
    UVALUE
    
        The "user value" to be assigned to the widget.
        
        Each widget can contain a user-specified value 
        of any data type and organization. This value is not 
        used by the widget in any way, but exists entirely 
        for the convenience of the IDL programmer. This key-
        word allows you to set this value when the widget is 
        first created.
        
        If UVALUE is not present, the widget's initial 
        user value is undefined.
        
        The user value for a widget can be accessed and 
        modified at any time by using the GET_UVALUE and 
        SET_UVALUE keywords to the WIDGET_CONTROL procedure.
        
    XOFFSET
    
        The horizontal offset of the widget (in pixels) 
        relative to its parent.
        
        Specifying an offset relative to a row or column 
        major base widget does not work because those wid-
        gets enforce their own layout policies. This keyword 
        is primarily of use relative to a plain base widget. 
        Note that it is best to avoid using this style of 
        widget layout.
        
    XPAD
    
        The horizontal space, in pixels, between child 
        widgets and the edges of a row or column major base. 
        This keyword is ignored if either the EXCLUSIVE or 
        NONEXCLUSIVE keyword is present.
        
    XSIZE
    
        The width of the widget (in pixels for most wid-
        gets, in characters for text widgets).
        
        Most widgets attempt to size themselves to fit 
        the situation. However, if the desired effect is not 
        produced, use this keyword to override it. This key-
        word is only a "hint" to the toolkit and may be 
        ignored in some situations.
        
    X_SCROLL_SIZE
    
        The XSIZE keyword always specifies the width of 
        a widget. When the SCROLL keyword is specified, this 
        size is not necessarily the same as the width of the 
        visible area. The X_SCROLL_SIZE keyword allows you 
        to set the width of the scrolling viewport indepen-
        dently of the actual width of the widget.
        
        Use of the X_SCROLL_SIZE keyword implies SCROLL.
        
    YOFFSET
    
        The vertical offset of the widget (in pixels) 
        relative to its parent. This offset is specified 
        relative to the upper left corner of the parent wid-
        get.
        
        Specifying an offset relative to a row or column 
        major base widget does not work because those wid-
        gets enforce their own layout policies. This keyword 
        is primarily of use relative to a plain base widget. 
        Note that it is best to avoid using this style of 
        widget layout.
        
    YPAD
    
        The vertical space, in pixels, between child 
        widgets and the edges of a row or column major base. 
        This keyword is ignored if either the EXCLUSIVE or 
        NONEXCLUSIVE keyword is present.
        
    YSIZE
    
        The height of the widget (in pixels for most 
        widgets, in characters for text widgets, is number 
        of visible items for list widgets).
        
        Most widgets attempt to size themselves to fit 
        the situation. However, if the desired effect is not 
        produced, use this keyword to override it. This key-
        word is only a "hint" to the toolkit and may be 
        ignored in some situations.
        
    Y_SCROLL_SIZE
    
        The YSIZE keyword always specifies the height of 
        a widget. When the SCROLL keyword is specified, this 
        size is not necessarily the same as the height of 
        the visible area. The Y_SCROLL_SIZE keyword allows 
        you to set the height of the scrolling viewport 
        independently of the actual height of the widget.
        
        Use of the Y_SCROLL_SIZE keyword implies SCROLL.
        
Exclusive And Non-Exclusive Bases

If the EXCLUSIVE or NONEXCLUSIVE keywords are speci-
fied, the base only allows button widget children.

Positioning Children Of Row And Column Bases

When the ROW or COLUMN keywords are specified, the 
base decides how to lay out its children, and any XSIZE 
and YSIZE keywords specified for such children are 
ignored.

Positioning Top-Level Bases

When locating a new top level window, some window man-
agers ignore the program's positioning requests and 
either choose a position or allow the user to choose. In 
such cases, the XOFFSET and YOFFSET keywords to 
WIDGET_BASE will not have an effect. The window manager 
may provide a way to disable this positioning style. The 
Motif window manager (mwm) can be told to honor position-
ing requests by placing the line:

*clientAutoPlace: off

in your .Xdefaults file.

Events

Top-level widget bases return the following event 
structure only when they are resized by the user and the 
base was created with the TLB_SIZE_EVENTS keyword set:

{ WIDGET_BASE_EVENT, ID:0L, TOP:0L, HANDLER:0L, X:0, Y:0 }

ID is the widget id of the base generating the event. 
TOP is the widget ID of the top level widget containing 
ID. HANDLER contains the widget ID of the widget associ-
ated with the handler routine. The X and Y fields return 
the new width of the base, not including any frame pro-
vided by the window manager.

;-
;+
WIDGET_BUTTON

The WIDGET_BUTTON function creates button widgets.

The returned value of this function is the widget ID 
of the newly-created button.

Calling Sequence

        Result = WIDGET_BUTTON(Parent)
        
Arguments

    Parent
    
        The widget ID of the parent for the new button 
        widget.
        
Keywords

    EVENT_FUNC
    
        A string containing the name of a function to be 
        called by the WIDGET_EVENT function when an event 
        arrives from a widget in the widget hierarchy rooted 
        at the newly-created widget.
        
    EVENT_PRO
    
        A string containing the name of a procedure to 
        be called by the WIDGET_EVENT function when an event 
        arrives from a widget in the widget hierarchy rooted 
        at the newly-created widget.
        
    FONT
    
        A string containing the name of the font to be 
        used by the widget. This name follows the standard X 
        Window System naming conventions and wildcards can 
        be used.
        
    FRAME
    
        The value of this keyword specifies the width of 
        a frame (in pixels) to be drawn around the borders 
        of the widget. Note that this keyword is only a 
        "hint" to the toolkit, and may be ignored in some 
        instances.
        
    FUNC_GET_VALUE
    
        A string containing the name of a function to be 
        called when the GET_VALUE keyword to the 
        WIDGET_CONTROL procedure is called for this widget. 
        Using this technique allows you to change the value 
        that should be returned for a widget. Compound wid-
        gets use this ability to define their values trans-
        parently to the user.
        
    GROUP_LEADER
    
        The widget ID of an existing widget that serves 
        as "group leader" for the newly-created widget. When 
        a group leader is killed, for any reason, all wid-
        gets in the group are also destroyed.
        
        A given widget can be in more than one group. 
        The WIDGET_CONTROL procedure can be used to add 
        additional group associations to a widget. It is not 
        possible to remove a widget from an existing group.
        
    KILL_NOTIFY
    
        A string containing the name of a procedure to 
        be called automatically when the specified widget 
        dies. Each widget is allowed a single such "call-
        back" procedure. It can be removed by setting the 
        routine to the null string ('').
        
        The callback routine is called with the widget 
        identifier as its only argument. At that point, the 
        widget identifier can only be used with the 
        WIDGET_CONTROL procedure to get or set the user 
        value. All other requests that require a widget ID 
        are disallowed for the target widget. The callback 
        is not issued until the WIDGET_EVENT function is 
        called. If a "kill notify" procedure causes an error 
        that halts the execution of the procedure, the halt 
        occurs in the procedure that called WIDGET_EVENT, 
        not in the kill notify procedure itself.
        
    MENU
    
        The presence of this keyword indicates that the 
        button will be used to activate a pull-down menu. 
        Such buttons can have button children that are then 
        placed into a pull-down menu.
        
        Under Motif, if the value specified for MENU is 
        greater than 1, the button label is enclosed in a 
        box to indicate that this button is a pull-down 
        menu. See the Users' Library routine CW_PDMENU for a 
        high-level pull-down menu creation utility.
        
    NO_COPY
    
        Usually, when the SET_UVALUE, GET_UVALUE, or 
        SEND_EVENT keywords are used, the source variable 
        memory is copied. When the NO_COPY keyword is set, 
        the source variable dynamic memory is used by the 
        destination, without copying. This feature can be 
        used by compound widgets to obtain state information 
        from a UVALUE without all the memory copying that 
        would otherwise occur.
        
    NO_RELEASE
    
        Set this keyword to make exclusive and non-
        exclusive buttons generate only select events (that 
        is, they only generate an event when they are first 
        pressed-no event is generated when they are 
        released). This keyword has no effect on regular 
        buttons.
        
    PRO_SET_VALUE
    
        A string containing the name of a procedure to 
        be called when the SET_VALUE keyword to the 
        WIDGET_CONTROL procedure is called for this widget. 
        Using this technique allows you to designate a rou-
        tine that sets the value for a widget. Compound wid-
        gets use this ability to define their values 
        transparently to the user.
        
    RESOURCE_NAME
    
        A string containing an X Window System resource 
        name to be applied to the widget. See the IDL Refer-
        ence Guide for a complete discussion of this key-
        word.
        
    UVALUE
    
        The "user value" to be assigned to the widget.
        
        Each widget can contain a user-specified value 
        of any data type and organization. This value is not 
        used by the widget in any way, but exists entirely 
        for the convenience of the IDL programmer. This key-
        word allows you to set this value when the widget is 
        first created.
        
        If UVALUE is not present, the widget's initial 
        user value is undefined.
        
    VALUE
    
        The initial value setting of the widget. The 
        value of a widget button is the label for that but-
        ton. This label can be a string or a bitmap as 
        described below under "Bitmap Button Labels".
        
    X_BITMAP_EXTRA
    
        When creating a bitmap button that is not of a 
        "byte-aligned" size (i.e., a dimension is not a mul-
        tiple of 8), this keyword specifies how many bits of 
        the supplied bitmap must be ignored (within the end 
        byte). For example, to create a 10 by 8 bitmap, you 
        need to supply a 2 by 8 array of bytes and ignore the 
        bottom 6 bits. Therefore, you would specify 
        X_BITMAP_EXTRA = 6.
        
    XOFFSET
    
        The horizontal offset of the widget (in pixels) 
        relative to its parent.
        
        Specifying an offset relative to a row or column 
        major base widget does not work because those wid-
        gets enforce their own layout policies. This keyword 
        is primarily of use relative to a plain base widget. 
        Note that it is best to avoid using this style of 
        widget programming.
        
    XSIZE
    
        The width of the widget (in pixels for most wid-
        gets, in characters for text widgets).
        
        Most widgets attempt to size themselves to fit 
        the situation. However, if the desired effect is not 
        produced, use this keyword to override it. This key-
        word is only a "hint" to the toolkit and may be 
        ignored in some situations.
        
    YOFFSET
    
        The vertical offset of the widget (in pixels) 
        relative to its parent. This offset is specified 
        relative to the upper left corner of the parent wid-
        get.
        
        Specifying an offset relative to a row or column 
        major base widget does not work because those wid-
        gets enforce their own layout policies. This keyword 
        is primarily of use relative to a plain base widget. 
        Note that it is best to avoid using this style of 
        widget programming.
        
    YSIZE
    
        The height of the widget (in pixels for most 
        widgets, in characters for text widgets, is number 
        of visible items for list widgets).
        
        Most widgets attempt to size themselves to fit 
        the situation. However, if the desired effect is not 
        produced, use this keyword to override it. This key-
        word is only a "hint" to the toolkit and may be 
        ignored in some situations.
        
Exclusive And Non-Exclusive Bases

Buttons placed into exclusive or non-exclusive bases 
(created via the EXCLUSIVE or NONEXCLUSIVE keywords to 
WIDGET_BASE procedure) are created as two-state "toggle" 
buttons, which are controlled by such bases.

Events Returned by Button Widgets

Pressing the mouse button while the mouse cursor is 
over a button widget causes the widget to generate an 
event. The event structure returned by the WIDGET_EVENT 
function is defined by the following statement:

{WIDGET_BUTTON, ID:0L, TOP:0L, HANDLER:0L, SELECT:0}

ID is the widget id of the button generating the 
event. TOP is the widget ID of the top level widget con-
taining ID. HANDLER contains the widget ID of the widget 
associated with the handler routine. SELECT is set to 1 if 
the button was set, and 0 if released. Normal buttons do 
not generate events when released, so SELECT will always 
be 1. However, toggle buttons (created by parenting a but-
ton to an exclusive or non-exclusive base) return separate 
events for the set and release actions.

Bitmap Button Labels

In addition to using a text string as the label of a 
button (set via the VALUE keyword), a button can have a 
bitmap label. This ability allows buttons to contain a 
graphic symbol. The bitmap is specified as a 2-dimensional 
byte array via the VALUE keyword. Appropriate bitmaps can 
be produced in 2 ways:

    The X Windows bitmap program can be used to cre-
    ate the bitmap. The READ_X11_BITMAP Users' Library 
    procedure is then used to read the bitmap into a 
    byte array.
    
    The XBM_EDIT Users' Library procedure can be 
    used to create the bitmap. This procedure offers 
    several alternatives for the form of the final bit-
    map.
    
Although IDL places no restriction on the size of bit-
map allowed, the various toolkits may prefer certain 
sizes.

;-
;+
WIDGET_CONTROL

The WIDGET_CONTROL procedure is used to realize, man-
age, and destroy widget hierarchies.

Calling Sequence

        WIDGET_CONTROL [, Widget_ID]
        
Arguments

    Widget_ID
    
        The widget ID of the widget to be manipulated. 
        This argument can be omitted when used with the 
        RESET keyword, but is required for all other opera-
        tions.
        
Keywords

    ALL_TEXT_EVENTS
    
        Along with the EDITABLE keyword, ALL_TEXT_EVENTS 
        controls the type of events generated by the text 
        widget. Set the ALL_TEXT_EVENTS keyword to cause the 
        full set of events to be generated. If 
        ALL_TEXT_EVENTS is not set, setting EDITABLE causes 
        only end-of-line events to be generated. If EDITABLE 
        is not set, all events are suppressed. See the table 
        below for additional details. Note that the equiva-
        lent keyword in the WIDGET_TEXT creation routine is 
        called ALL_EVENTS.
        
                  Keywords         |       Effects
        
        ---------------------------------------------------
        
                                   | Input
        
                                   | changes     Type of
        
                                   | widget      events
        
        ALL_TEXT_EVENTS   EDITABLE  | contents?   generated
        
        ---------------------------------------------------
        
        Not set           Not set   | No         None
        
        Not set           Set       | Yes        EOL insert
        
        Set               Not set   | No         None
        
        Set               Set       | Yes        All events
        
    APPEND
    
        When using the SET_VALUE keyword to set the con-
        tents of a text widget (as created with the 
        WIDGET_TEXT procedure), setting this keyword indi-
        cates that the supplied text should be appended to 
        the existing contents of the text widget rather than 
        replace it.
        
    BAD_ID
    
        If Widget_ID is not a valid widget identifier, 
        this WIDGET_CONTROL normally issues an error and 
        causes program execution to stop. However, if BAD_ID 
        is present and specifies a named variable, the 
        invalid ID is stored into the variable, and this 
        routine quietly returns. If no error occurs, a zero 
        is stored.
        
    CLEAR_EVENTS
    
        If set, any events generated by the widget hier-
        archy rooted at Widget_ID which have arrived but 
        have not been processed (via the WIDGET_EVENT proce-
        dure) are discarded.
        
    DEFAULT_FONT
    
        A string containing the name of the default font 
        to be used.
        
        If the font to be used for a given widget is not 
        explicitly specified (via the FONT keyword to the 
        widget creation function), a default supplied by the 
        X windows server is used. Use this keyword to change 
        the default.
        
    DELAY_DESTROY
    
        Normally, when the user destroys a widget hier-
        archy using the window manager, it is immediately 
        removed. This can cause problems for applications 
        that use the background task facility provided by 
        the XMANAGER Users' Library procedure if the hierar-
        chy is destroyed while a background task is using 
        it.
        
        If DELAY_DESTROY is set, attempts to destroy the 
        hierarchy are delayed until the next attempt to 
        obtain an event for it. Setting DELAY_DESTROY to 
        zero restores the default behavior.
        
        XMANAGER uses this keyword automatically when 
        managing background tasks. It is not expected that 
        applications will need to use it directly.
        
    DESTROY
    
        Set this keyword to destroy the widget and any 
        child widgets in its hierarchy. Any further attempts 
        to use the IDs for these widgets will cause an 
        error.
        
    DRAW_BUTTON_EVENTS
    
        Set this keyword to enable button press events 
        for draw widgets. Setting a zero value disables such 
        events.
        
    DRAW_MOTION_EVENTS
    
        Set this keyword to enable motion events for 
        draw widgets. Setting a zero value disables such 
        events.
        
    DRAW_VIEWPORT_EVENTS
    
        Set this keyword to enable viewport motion 
        events for draw widgets. Setting a zero value dis-
        ables such events.
        
    EDITABLE
    
        Set this keyword to allow direct user editing of 
        the contents of a text widget. Normally, the text in 
        text widgets is read-only. See the table above for a 
        description of how EDITABLE interacts with 
        ALL_TEXT_EVENTS.
        
    EVENT_FUNC
    
        A string containing the name of a function to be 
        called by the WIDGET_EVENT function when an event 
        arrives from a widget in the widget hierarchy given 
        by Widget_ID.
        
        This keyword overwrites any event routine sup-
        plied by previous uses of the EVENT_FUNC or 
        EVENT_PRO keywords. To specify no event routine, set 
        this keyword to a null string ('').
        
    EVENT_PRO
    
        A string containing the name of a procedure to 
        be called by the WIDGET_EVENT function when an event 
        arrives from a widget in the widget hierarchy given 
        by Widget_ID.
        
        This keyword overwrites any event routine sup-
        plied by previous uses of the EVENT_FUNC or 
        EVENT_PRO keywords. To specify no event routine, set 
        this keyword to a null string ('').
        
    FUNC_GET_VALUE
    
        A string containing the name of a function to be 
        called when the GET_VALUE keyword to the 
        WIDGET_CONTROL procedure is called for this widget. 
        Using this technique allows you to change the value 
        that should be returned for a widget. Compound wid-
        gets use this ability to define their values trans-
        parently to the user.
        
    GET_DRAW_VIEW
    
        Specifies a named variable which will be 
        assigned the current position of a draw widget view-
        port. The position is returned as a 2-element inte-
        ger array giving the X and Y position relative to 
        the lower left corner of the graphics area.
        
    GET_UVALUE
    
        Set this keyword to a named variable to contain 
        the current user value of the widget.
        
        Each widget can contain a user set value of any 
        data type and organization. This value is not used 
        by the widget in any way, and exists entirely for 
        the convenience of the IDL programmer. This keyword 
        allows you to obtain the current user value.
        
        The user value of a widget can be set with the 
        SET_UVALUE keyword to this routine, or with the 
        UVALUE keyword to the routine that created it.
        
        To improve the efficiency of the data transfer, 
        consider using the NO_COPY keyword (described below) 
        with GET_UVALUE.
        
    GET_VALUE
    
        Set this keyword to a named variable to contain 
        the current value of the widget. The type of value 
        returned depends on the widget type:
        
        Button: If the button label is text, it is 
        returned as a string. Attempts to obtain the value 
        of a button with a bitmap label is an error.
        
        Draw: The IDL window ID for the drawing area is 
        returned. This ID is used with procedures such as 
        WSET, WSHOW, etc., to direct graphics to the widget. 
        The window ID is assigned to drawing area widgets at 
        the time they are realized. If the widget has not 
        yet been realized, a value of 1 is returned.
        
        Label: The label text is returned as a string.
        
        Slider: The current value of the slider is 
        returned as an integer.
        
        Text: The current contents of the text widget 
        are returned as a string array. If the 
        USE_TEXT_SELECT keyword is also specified, only the 
        contents of the current selection are returned.
        
        Widget types not listed above do not return a 
        value. Attempting to retrieve the value of such a 
        widget causes an error.
        
        The value of a widget can be set with the 
        SET_VALUE keyword to this routine, or with the VALUE 
        keyword to the routine that created it.
        
    GROUP_LEADER
    
        The widget ID of an existing widget that serves 
        as "group leader" for the newly-created widget. When 
        a group leader is killed, for any reason, all wid-
        gets in the group are also destroyed.
        
        A given widget can be in more than one group. 
        The WIDGET_CONTROL procedure can be used to add 
        additional group associations to a widget. It is not 
        possible to remove a widget from an existing group.
        
    HOURGLASS
    
        Set this keyword to turn on an "hourglass-
        shaped" cursor for all IDL widgets and graphics win-
        dows. The hourglass remains in place until the 
        WIDGET_EVENT function attempts to process the next 
        event. Then the previous cursor is reinstated. If an 
        application starts a time-intensive calculation 
        inside an event-handling routine, the hourglass cur-
        sor should be used to indicate that the system is 
        not currently responding to events.
        
    ICONIFY
    
        Set this keyword to a non-zero value to cause 
        the specified widget to become iconified. Set this 
        keyword to zero to open an iconified widget.
        
    INPUT_FOCUS
    
        If Widget_ID is a text widget, you can set this 
        keyword to cause the widget to receive the keyboard 
        focus. If Widget_ID is a button widget, set this 
        keyword to position the mouse pointer over the but-
        ton. This keyword has no effect for other widget 
        types.
        
    KILL_NOTIFY
    
        A string containing the name of a procedure to 
        be called automatically when the specified widget 
        dies. Each widget is allowed a single such "call-
        back" procedure. It can be removed by setting the 
        routine to the null string ('').
        
        Use this keyword to change or remove a previ-
        ously-specified callback procedure for Widget_ID.
        
        The callback routine is called with the widget 
        identifier as its only argument. At that point, the 
        widget identifier can only be used with the 
        WIDGET_CONTROL procedure to get or set the user 
        value. All other requests that require a widget ID 
        are disallowed for the target widget. The callback 
        is not issued until the WIDGET_EVENT function is 
        called. If a "kill notify" procedure causes an error 
        that halts the execution of the procedure, the halt 
        occurs in the procedure that called WIDGET_EVENT, 
        not in the kill notify procedure itself.
        
    MANAGED
    
        This keyword is used by the XMANAGER Users' 
        Library procedure to mark those widgets that it is 
        currently managing. User applications should not use 
        this keyword directly.
        
    MAP
    
        Set this keyword to zero to unmap the widget 
        hierarchy rooted at the widget specified by 
        Widget_ID. The hierarchy disappears from the screen, 
        but still exists.
        
        The mapping operation applies only to base wid-
        gets. If the specified widget is not a base, IDL 
        searches upward in the widget hierarchy until it 
        finds the closest base widget. The map operation is 
        applied to that base.
        
        Set MAP to a nonzero value to re-map the widget 
        hierarchy and make it visible. Normally, the widget 
        is automatically mapped when it is realized, so use 
        of the MAP keyword is not required.
        
    NO_COPY
    
        Usually, when the SET_UVALUE, GET_UVALUE, or 
        SEND_EVENT keywords are used, the source variable 
        memory is copied. When the NO_COPY keyword is set, 
        the source variable dynamic memory is used by the 
        destination, without copying. This feature can be 
        used by compound widgets to obtain state information 
        from a UVALUE without all the memory copying that 
        would otherwise occur.
        
    NO_NEWLINE
    
        When setting the value of a multi-line text wid-
        get, newline characters are automatically appended 
        to the end of each line of text. The NO_NEWLINE key-
        word suppresses this action.
        
    PRO_SET_VALUE
    
        A string containing the name of a procedure to 
        be called when the SET_VALUE keyword to the 
        WIDGET_CONTROL procedure is called for this widget. 
        Using this technique allows you to designate a rou-
        tine that sets the value for a widget. Compound wid-
        gets use this ability to define their values 
        transparently to the user.
        
    REALIZE
    
        If set, the widget hierarchy is realized. Until 
        the realization step, the widget hierarchy exists 
        only within IDL. Realization is the step of actually 
        creating the widgets on the screen (and mapping them 
        if necessary).
        
        When a previously-realized widget gets a new 
        child widget, the new child is automatically real-
        ized.
        
    RESET
    
        The RESET keyword causes every currently active 
        widget to be destroyed. It should be used with cau-
        tion.
        
    SEND_EVENT
    
        Set this keyword to structure containing a valid 
        widget event to be sent to the specified widget. The 
        value of SEND_EVENT must be a structure and the 
        first three fields must be ID, TOP, and HANDLER (all 
        of LONG type). Additional fields can be of any type.
        
        To improve the efficiency of the data transfer, 
        consider using the NO_COPY keyword with SEND_EVENT.
        
    SENSITIVE
    
        When a widget is sensitive, it has normal 
        appearance and can receive user input. For instance, 
        a sensitive button widget can be activated by moving 
        the mouse cursor over it and pressing a mouse but-
        ton. When a widget is insensitive, it indicates the 
        fact by changing its appearance, and ignores any 
        input directed at it. If SENSITIVE is zero, the wid-
        get hierarchy becomes insensitive. If nonzero, it 
        becomes sensitive.
        
        Sensitivity can be used to control when a user 
        is allowed to manipulate a widget. It should be 
        noted that some widgets do not change their appear-
        ance when they are made insensitive, and simply 
        cease generating events.
        
    SET_BUTTON
    
        This keyword allows changing the current state 
        of toggle buttons. If zero, every toggle button in 
        the hierarchy specified by Widget_ID is set to the 
        unselected state. If nonzero, the action depends on 
        the type of base holding the buttons. Normally, all 
        buttons are selected. However, exclusive bases may 
        or may not allow more than a single button to be 
        selected in this manner, depending on the toolkit 
        implementation.
        
    SET_DRAW_VIEW
    
        A scrollable draw widget provides a large graph-
        ics area which is viewed through a smaller viewport. 
        This keyword allows changing the current position of 
        the viewport. The desired position is specified as a 
        2-element integer array giving the X and Y position 
        (in pixels) relative to the lower left corner of the 
        graphics area. For example, to position the viewport 
        to the lower left corner of the image:
        
        WIDGET_CONTROL, widget, SET_DRAW_VIEW=[0, 0]
        
    SET_LIST_SELECT
    
        Set this keyword to an integer that specifies 
        the list element to be highlighted. The previous 
        selection (if there is a selection) is cleared. 
        Positions start at zero. If the specified element is 
        outside the possible range, no new selection in set.
        
        If the selected position is not currently on the 
        screen, the list widget automatically move the cur-
        rent scrolling viewport to make it visible. The 
        resulting topmost visible element is toolkit spe-
        cific. If you wish to ensure a certain element is at 
        the top of the list, use the SET_LIST_TOP keyword 
        (described below) to explicitly set the viewport.
        
    SET_LIST_TOP
    
        Set this keyword to an integer that specifies 
        the element of the list widget to the positioned at 
        the top of the scrolling list. If the specified ele-
        ment is outside the range of list elements, nothing 
        happens.
        
    SET_SLIDER_MAX
    
        Set this keyword to a new maximum value for the 
        specified slider widget.
        
    SET_SLIDER_MIN
    
        Set this keyword to a new minimum value for the 
        specified slider widget.
        
    SET_TEXT_SELECT
    
        Use this keyword to clear any current selection 
        in the specified text widget, and either set a new 
        selection, or simply set the text insertion point. 
        To set a selection, specify a two-element integer 
        array containing the starting position and the 
        length of the selection. For example, to set a 
        selection covering characters 3 though 23:
        
        WIDGET_CONTROL, SET_TEXT_SELECT=[3, 23]
        
        To move the text insertion point without setting 
        a selection, omit the second element, or set it to 
        zero.
        
    SET_TEXT_TOP_LINE
    
        Set this keyword to the zero-based line number 
        of the line to be positioned on the topmost visible 
        line in the text widget's viewport. No horizontal 
        scrolling is performed. Note that this is a line 
        number, not a character offset.
        
    SET_UVALUE
    
        Each widget can contain a user-set value. This 
        value is not used by IDL in any way, and exists 
        entirely for the convenience of the IDL programmer. 
        This keyword allows you to set this value.
        
        To improve the efficiency of the data transfer, 
        consider using the NO_COPY keyword with SET_UVALUE.
        
    SET_VALUE
    
        Sets the value of the specified widget. The 
        meaning of the value differs between widget types:
        
        Button: The label to be used for the button. 
        This value can be either a scalar string, or a 2D 
        byte array containing a bitmap.
        
        Label: The text to be displayed by the label 
        widget.
        
        List: Set the selections for the list widget 
        (string or string array).
        
        Slider: Sets the current position of the slider 
        (integer).
        
        Text: Set the text to be displayed. If the 
        APPEND keyword is also specified, the text is 
        appended to the current contents instead of instead 
        of completely replacing it (string or string array). 
        If the USE_TEXT_SELECT keyword is specified, the new 
        string replaces only the currently-selected text in 
        the text widget.
        
        Widget types not listed above do not allow the 
        setting of a value. Attempting to set the value of 
        such a widget causes an error.
        
        The value of a widget can also be set with the 
        VALUE keyword to the routine that created it.
        
    SHOW
    
        Controls the visibility of a widget hierarchy. 
        If set to zero, the hierarchy containing Widget_ID 
        is pushed behind any other windows on the screen. If 
        nonzero, the hierarchy is pulled in front.
        
    TIMER
    
        If this keyword is present, a WIDGET_TIMER event 
        is generated. Set this keyword to a floating-point 
        value that represents the number of seconds before 
        the timer event arrives. Note that this event is 
        identical to any other widget event except that it 
        contains only the 3 standard event tags (ID, common, 
        and handler). It is left to the caller to tell the 
        difference between standard widget events and timer 
        events. The standard way to do this is to use a wid-
        get that doesn't normally generate events (e.g., a 
        base or label).
        
        This feature is more efficient than the back-
        ground task functionality found in the XMANAGER pro-
        cedure because it doesn't "poll" like the original 
        background task code. Research Systems will eventu-
        ally eliminate the background task functionality 
        from XMANAGER. We encourage all users to modify 
        their code to use the TIMER keyword instead.
        
    TLB_GET_OFFSET
    
        Set this keyword to a named variable in which 
        the offset of the top-level base of the specified 
        widget is returned. The offset is measured in device 
        coordinates relative to the upper-left corner of the 
        screen. This offset value does not include the size 
        of the enclosing frame (which is provided by the 
        window manager).
        
    TLB_GET_SIZE
    
        Set this keyword to a named variable in which 
        the size of the top level base of the specified wid-
        get is returned. The size is returned as a two-ele-
        ment vector that contains the horizontal and 
        vertical size of the base in device coordinates.
        
    TLB_SET_TITLE
    
        Set this keyword to a scalar string to change 
        the title of the specified top-level base after it 
        has been created.
        
    TLB_SET_XOFFSET
    
        Use this keyword to set the horizontal position 
        of the top level base of the specified widget. The 
        offset is measured from the upper-left corner of the 
        screen to the upper-left corner of the base, in 
        device coordinates.
        
    TLB_SET_YOFFSET
    
        Use this keyword to set the vertical position of 
        the top level base of the specified widget. The off-
        set is measured from the upper-left corner of the 
        screen to the upper-left corner of the base, in 
        device coordinates.
        
    USE_TEXT_SELECT
    
        Set this keyword to modify the behavior of the 
        GET_VALUE and SET_VALUE keywords. If USE_TEXT_SELECT 
        is set, GET_VALUE and SET_VALUE apply only to the 
        current text selection. Normally, these keywords 
        apply to the entire contents of a text widget.
        
    X_BITMAP_EXTRA
    
        When the value of a button widget is a bitmap, 
        the usual width is taken to be 8 times the number of 
        columns in the source byte array. This keyword can 
        be used to indicate the number of bits in the last 
        byte of each row that should be ignored. The value 
        can range between 0 and 7.
        
;-
;+
WIDGET_DRAW

The WIDGET_DRAW function is used to create draw wid-
gets. Draw widgets are rectangular areas that IDL treats 
as standard graphics windows. Any graphical output that 
can be produced by IDL can be directed to a draw widget. 
Draw widgets can have optional scroll bars to allow view-
ing a larger graphics area than could otherwise be dis-
played in the widget's visible area.

The returned value of this function is the widget ID 
of the newly-created draw widget.

Calling Sequence

        Result = WIDGET_DRAW(Parent)
        
Arguments

    Parent 
    
        The widget ID of the parent widget of the new 
        draw widget.
        
Keywords

    BUTTON_EVENTS
    
        Set this keyword to make the draw widget gener-
        ate event when the mouse buttons are pressed or 
        released (and the mouse pointer is in the draw wid-
        get).
        
        Normally, draw widgets do not generate events.
        
    COLORS
    
        The maximum number of color table indices to be 
        used. This parameter has effect only if it is sup-
        plied when the first IDL graphics window is created.
        
        If COLORS is not specified when the first window 
        is created, all or most of the available color indi-
        ces are allocated, depending upon the window system 
        in use.
        
        To use monochrome windows on a color display, 
        set COLORS equal to 2 when creating the first win-
        dow. One color table is maintained for all IDL win-
        dows. When using X windows, a negative value for 
        COLORS specifies that all but the given number of 
        colors from the shared color table should be used.
        
    EVENT_FUNC
    
        A string containing the name of a function to be 
        called by the WIDGET_EVENT function when an event 
        arrives from a widget in the widget hierarchy rooted 
        at the newly-created widget.
        
    EVENT_PRO
    
        A string containing the name of a procedure to 
        be called by the WIDGET_EVENT function when an event 
        arrives from a widget in the widget hierarchy rooted 
        at the newly-created widget.
        
    FRAME
    
        The value of this keyword specifies the width of 
        a frame (in pixels) to be drawn around the borders 
        of the widget. Note that this keyword is only a hint 
        to the toolkit, and may be ignored in some 
        instances.
        
    FUNC_GET_VALUE
    
        A string containing the name of a function to be 
        called when the GET_VALUE keyword to the 
        WIDGET_CONTROL procedure is called for this widget. 
        Using this technique allows you to change the value 
        that should be returned for a widget. Compound wid-
        gets use this ability to define their values trans-
        parently to the user.
        
    GROUP_LEADER
    
        The widget ID of an existing widget that serves 
        as "group leader" for the newly-created widget. When 
        a group leader is killed, for any reason, all wid-
        gets in the group are also destroyed.
        
        A given widget can be in more than one group. 
        The WIDGET_CONTROL procedure can be used to add 
        additional group associations to a widget. It is not 
        possible to remove a widget from an existing group.
        
    KILL_NOTIFY
    
        A string containing the name of a procedure to 
        be called automatically when the specified widget 
        dies. Each widget is allowed a single such "call-
        back" procedure. It can be removed by setting the 
        routine to the null string ('').
        
        The callback routine is called with the widget 
        identifier as its only argument. At that point, the 
        widget identifier can only be used with the 
        WIDGET_CONTROL procedure to get or set the user 
        value. All other requests that require a widget ID 
        are disallowed for the target widget. The callback 
        is not issued until the WIDGET_EVENT function is 
        called. If a "kill notify" procedure causes an error 
        that halts the execution of the procedure, the halt 
        occurs in the procedure that called WIDGET_EVENT, 
        not in the kill notify procedure itself.
        
    MOTION_EVENTS
    
        Set this keyword to make the draw widget gener-
        ate events when the mouse cursor moves across the 
        widget. Normally, draw widgets do not generate 
        events.
        
        Draw widgets that return motion events can gen-
        erate a large number of events that can result in 
        poor performance on slower machines.
        
    NO_COPY
    
        Usually, when the SET_UVALUE, GET_UVALUE, or 
        SEND_EVENT keywords are used, the source variable 
        memory is copied. When the NO_COPY keyword is set, 
        the source variable dynamic memory is used by the 
        destination, without copying. This feature can be 
        used by compound widgets to obtain state information 
        from a UVALUE without all the memory copying that 
        would otherwise occur.
        
    PRO_SET_VALUE
    
        A string containing the name of a procedure to 
        be called when the SET_VALUE keyword to the 
        WIDGET_CONTROL procedure is called for this widget. 
        Using this technique allows you to designate a rou-
        tine that sets the value for a widget. Compound wid-
        gets use this ability to define their values 
        transparently to the user.
        
    RESOURCE_NAME
    
        A string containing an X Window System resource 
        name to be applied to the widget. See the IDL Refer-
        ence Guide for a complete discussion of this key-
        word.
        
    RETAIN
    
    This keyword specifies how backing store should be handled for the draw 
    widget. Possible values for this key-
    word are shown in the table 
    below.Value  Description
    
    -----------------------------------------------
    
    0      No backing store
    
    1      The server or window system is requested
    
           to make the window retained
    
    2      IDL provides backing store
    
    SCROLL
    
        Set this keyword to give the draw widget scroll 
        bars that allow viewing portions of the widget con-
        tents that are not currently on the screen.
        
    UVALUE
    
        The "user value" to be assigned to the widget.
        
        Each widget can contain a user-specified value 
        of any data type and organization. This value is not 
        used by the widget in any way, but exists entirely 
        for the convenience of the IDL programmer. This key-
        word allows you to set this value when the widget is 
        first created.
        
        If UVALUE is not present, the widget's initial 
        user value is undefined.
        
    VALUE
    
        The initial value setting of the widget. The 
        value of a draw widget is the IDL window number for 
        use with graphics routines, such as WSET. This value 
        cannot be set or modified by the user.
        
        To obtain the window number for a newly-created 
        draw widget, use the GET_VALUE keyword to 
        WIDGET_CONTROL after the draw widget has been real-
        ized. Draw widgets do not have a window number 
        assigned to them until they are realized. For exam-
        ple, to return the window number of a draw widget in 
        the variable win_num, use the command:
        
        WIDGET_CONTROL, my_drawwidget, GET_VALUE = win_num
        
        where my_drawwidget is the widget ID of the 
        desired draw widget.
        
    VIEWPORT_EVENTS
    
        Set this keyword to enable viewport motion 
        events for draw widgets.
        
    XOFFSET
    
        The horizontal offset of the widget (in pixels) 
        relative to its parent.
        
        Specifying an offset relative to a row or column 
        major base widget does not work because those wid-
        gets enforce their own layout policies. This keyword 
        is primarily of use relative to a plain base widget. 
        Note that it is best to avoid using this style of 
        widget layout.
        
    XSIZE
    
        The width of the widget (in pixels for most wid-
        gets, in characters for text widgets).
        
        Most widgets attempt to size themselves to fit 
        the situation. However, if the desired effect is not 
        produced, use this keyword to override it. This key-
        word is only a "hint" to the toolkit and may be 
        ignored in some situations.
        
    X_SCROLL_SIZE
    
        The XSIZE keyword always specifies the width of 
        a widget. When the SCROLL keyword is specified, this 
        size is not necessarily the same as the width of the 
        visible area. The X_SCROLL_SIZE keyword allows you 
        to set the width of the scrolling viewport indepen-
        dently of the actual width of the widget.
        
        Use of the X_SCROLL_SIZE keyword implies SCROLL.
        
    YOFFSET
    
        The vertical offset of the widget (in pixels) 
        relative to its parent. This offset is specified 
        relative to the upper left corner of the parent wid-
        get.
        
        Specifying an offset relative to a row or column 
        major base widget does not work because those wid-
        gets enforce their own layout policies. This keyword 
        is primarily of use relative to a plain base widget. 
        Note that it is best to avoid using this style of 
        widget layout.
        
    YSIZE
    
        The height of the widget (in pixels for most 
        widgets, in characters for text widgets, is number 
        of visible items for list widgets).
        
        Most widgets attempt to size themselves to fit 
        the situation. However, if the desired effect is not 
        produced, use this keyword to override it. This key-
        word is only a hint to the toolkit and may be 
        ignored in some situations.
        
    Y_SCROLL_SIZE
    
        The YSIZE keyword always specifies the height of 
        a widget. When the SCROLL keyword is specified, this 
        size is not necessarily the same as the height of 
        the visible area. The Y_SCROLL_SIZE keyword allows 
        you to set the height of the scrolling viewport 
        independently of the actual height of the widget.
        
        Use of the Y_SCROLL_SIZE keyword implies SCROLL.
        
Widget Events Returned by Draw Widgets

By default, draw widgets do not generate events. If 
the BUTTON_EVENTS keyword is set when the widget is cre-
ated, pressing or releasing any mouse button while the 
mouse cursor is over the draw widget causes events to be 
generated. Specifying the MOTION_EVENTS keyword causes 
events to be generated continuously as the mouse cursor 
moves across the draw widget.

The event structure returned by the WIDGET_EVENT 
function is defined by the following statement:

{WIDGET_DRAW, ID:0L, TOP:0L, HANDLER:0L, TYPE: 0, X:0, Y:0, 
PRESS:0B, RELEASE:0B}

ID, TOP, and HANDLER are the three standard fields 
found in every widget event. TYPE returns a value that 
describes the type of draw widget interaction that gener-
ated an event. The values for TYPE are shown in the table 
below.

Value

Meaning

0

Button Press

1

Button Release

2

Motion

3

Viewport Moved (Scrollbars)

Table 0.1 Values for the TYPE field.

The X and Y fields give the device coordinates at 
which the event occurred, measured from the lower left 
corner of the drawing area. PRESS and RELEASE are bitmasks 
in which the least significant bit represents the leftmost 
mouse button. The corresponding bit of PRESS is set when a 
mouse button is pressed, and in RELEASE when the button is 
released. If the event is a motion event, both PRESS and 
RELEASE are zero.

Note that the CURSOR procedure is only for use with 
IDL graphics windows. It should not be used with draw wid-
gets. To obtain the cursor position and button state 
information from a draw widget, examine the X, Y, PRESS, 
and RELEASE fields in the structures returned by the draw 
widget in response to cursor events.

Backing Store

Draw widgets with scroll bars rely on backing store to 
repaint the visible area of the window as it is moved. 
Their performance is best on systems that provide backing 
store. However, if your system does not automatically pro-
vide backing store, you can make IDL supply it with the 
statement:

DEVICE, RETAIN=2

or by using the RETAIN keyword to WIDGET_DRAW.

;-
;+
WIDGET_EVENT

The WIDGET_EVENT function returns events for the wid-
get hierarchy rooted at Widget_ID. Widgets communicate 
information by generating events. Events are generated 
when a button is pressed, a slider position is changed, 
and so forth.

Note: Widget applications should use the XMANAGER 
Users' Library procedure in preference to calling 
WIDGET_EVENT directly.

Calling Sequence

        Result = WIDGET_EVENT([Widget_ID])
        
Arguments

    Widget_ID
    
        Widget_ID specifies the widget hierarchy for 
        which events are desired. The first available event 
        for the specified widget or any of its children is 
        returned. If this argument is not specified, 
        WIDGET_EVENT processes events for all existing wid-
        gets.
        
        Widget_ID can also be an array of widget identi-
        fiers, in which case all of the specified widget 
        hierarchies are searched.
        
        Note: Attempting to obtain events for a widget 
        hierarchy which is not producing events will hang 
        IDL, unless the NOWAIT keyword is used.
        
Keywords

    BAD_ID
    
        If one of the values supplied via Widget_ID is 
        not a valid widget identifier, this function nor-
        mally issues an error and causes program execution 
        to stop. However, if BAD_ID is present and specifies 
        a named variable, the invalid ID is stored into the 
        variable, and this routine quietly returns. If no 
        error occurs, a zero is stored.
        
        This keyword can be used to handle the situation 
        in which IDL is waiting within WIDGET_EVENT when the 
        user kills the widget hierarchy.
        
        This keyword has meaning only if Widget_ID is 
        explicitly specified.
        
    NOWAIT
    
        When no events are currently available for the 
        specified widget hierarchy, WIDGET_EVENT normally 
        waits until one is available and then returns it. 
        However, if NOWAIT is set and no events are present, 
        it immediately returns. In this case, the ID field 
        of the returned structure will be zero.
        
    SAVE_HOURGLASS
    
        Set this keyword to prevent the hourglass cursor 
        from being cleared by WIDGET_EVENT. This keyword can 
        be of use if a program has to poll a widget periodi-
        cally during a long computation.
        
    YIELD_TO_TTY
    
        Unless the NOWAIT keyword is specified, 
        WIDGET_EVENT does not return until the asked for 
        event is available. If the user should enter a line 
        of input from the keyboard, it cannot be processed 
        until WIDGET_EVENT returns. If the YIELD_TO_TTY key-
        word is specified and the user enters a line of 
        input, WIDGET_EVENT returns immediately. In this 
        case, the ID field of the returned structure will be 
        zero.
        
        Note: This keyword is supported under Unix only, 
        and there are no plans to extend it to other operat-
        ing systems. Do not use it if you intend to use non-
        Unix systems.
        
Event Processing

All events for a given widget are processed in the 
order that they are generated. The event processing per-
formed by WIDGET_EVENT consists of the following steps:

    Wait for an event from one of the specified wid-
    gets to arrive.
    
    Starting with the widget that the event belongs 
    to, move up the widget hierarchy looking for a wid-
    get that has an event handling procedure or function 
    associated with it. Such routines are associated 
    with a widget via the EVENT_PRO and EVENT_FUNC key-
    words to the widget creation functions or the 
    WIDGET_CONTROL procedure.
    
    If an event handling procedure is found, it is 
    called with the widget ID as its argument. When the 
    procedure returns, WIDGET_EVENT returns to the first 
    step. Hence, event procedures are said to "swallow" 
    events.
    
    If an event handling function is found, it is 
    called with the widget ID as its argument. When the 
    function returns, its value is examined. If the 
    value is a non-structure, it is discarded and 
    WIDGET_EVENT returns to the first step.
    
    This behavior allows event functions to selec-
    tively act like event procedures and swallow events. 
    If the returned value is a structure, it is checked 
    to ensure that it has the standard first 3 fields: 
    ID, TOP, and HANDLER. If not an error is issued. Oth-
    erwise the value replaces the event found in the first 
    step and WIDGET_EVENT returns to the second step.
    
    Hence, event functions are said to "rewrite" 
    events. This ability to rewrite events is the basis 
    of the "compound widget" in which several widgets are 
    combined to give the appearance of a single, more com-
    plicated widget.
    
    If an event reaches the top of a widget hierar-
    chy without being swallowed by an event handler, it 
    is returned as the value of WIDGET_EVENT.
    
Events

A widget event is returned in a structure. The exact 
contents of this structure vary depending upon the type of 
widget involved. The first three elements of this struc-
ture, however, are always the same. Any other elements 
vary from widget type to type. The three fixed elements 
are:

ID

        The widget ID of the widget that generated the 
        event.
        
        TOP
        
        The widget ID of the top level base for the wid-
        get hierarchy containing ID.
        
        HANDLER
        
        When an event is passed as the argument to an 
        event handling procedure or function, as discussed 
        in the previous section, this field contains the 
        identifier of the widget associated with the handler 
        routine. When an event is returned from 
        WIDGET_EVENT, this value is always zero to indicate 
        that no handler routine was found.
        
;-
;+
WIDGET_INFO

The WIDGET_INFO function is used to obtain informa-
tion about the widget subsystem and individual widgets. 
The specific area for which information is desired is 
selected by setting the appropriate keyword.

Calling Sequence

        Result = WIDGET_INFO([Widget_ID])
        
Arguments

    Widget_ID
    
        Usually this argument should be the widget ID of 
        the widget for which information is desired. If the 
        ACTIVE or VERSION keywords are specified, this argu-
        ment is not required.
        
        Widget_ID can also be an array of widget identi-
        fiers, in which case the result is an array with the 
        same structure in which information on all the spec-
        ified widgets is returned.
        
Keywords

    ACTIVE
    
        Set this keyword to return 1 if there is at 
        least one realized, top-level widget on the screen. 
        Otherwise, 0 is returned.
        
    CHILD
    
        Set this keyword to return the widget ID of the 
        first child of the widget specified by Widget_ID. If 
        the widget has no children, 0 is returned.
        
    DRAW_BUTTON_EVENTS
    
        Set this keyword to return 1 if Widget_ID is a 
        draw widget with the BUTTON_EVENTS attribute set. 
        Otherwise, 0 is returned.
        
    DRAW_MOTION_EVENTS
    
        Set this keyword to return 1 if Widget_ID is a 
        draw widget with the MOTION_EVENTS attribute set. 
        Otherwise, 0 is returned.
        
    DRAW_VIEWPORT_EVENTS
    
        Set this keyword to return 1 if Widget_ID is a 
        draw widget with the VIEWPORT_EVENTS attribute set. 
        Otherwise, 0 is returned.
        
    EVENT_FUNC
    
        Set this keyword to return a string containing 
        the name of the event handler function associated 
        with Widget_ID. A null string is returned if no 
        event handler function exists.
        
    EVENT_PRO
    
        Set this keyword to return a string containing 
        the name of the event handler procedure associated 
        with Widget_ID. A null string is returned if no 
        event handler procedure exists.
        
    LIST_NUMBER
    
        Set this keyword to return the number of ele-
        ments currently contained in the specified list wid-
        get.
        
    LIST_NUM_VISIBLE
    
        Set this keyword to return the number of ele-
        ments that can be visible in the scrolling viewport 
        of the specified list widget. Note that this value 
        can be larger than the total number of elements 
        actually in the list.
        
    LIST_SELECT
    
        Set this keyword to return the number of the 
        currently-selected (highlighted) element in the 
        specified list widget. Note that this offset is 
        zero-based. If no element is currently selected, -1 
        is returned.
        
    LIST_TOP
    
        Set this keyword to return the zero-based offset 
        of the topmost element currently visible in the 
        specified list widget.
        
    PARENT
    
        Set this keyword to return the widget ID of the 
        parent of the widget specified by Widget_ID. If the 
        widget is a top-level base (i.e., it has no parent), 
        0 is returned.
        
    REALIZED
    
        Set this keyword to return 1 if the widget spec-
        ified by Widget_ID has been realized. If the widget 
        has not been realized, 0 is returned.
        
    SIBLING
    
        Set this keyword to return the widget ID of the 
        first sibling of the widget specified by Widget_ID. 
        If the widget is the last sibling in the chain, 0 is 
        returned.
        
    SLIDER_MIN_MAX
    
        Set this keyword to return the current minimum 
        and maximum values of the specified slider as a two-
        element integer array. Element 0 is the minimum 
        value and element 1 is the maximum value.
        
    TEXT_ALL_EVENTS
    
        Set this keyword to return 1 if Widget_ID is a 
        text widget with the ALL_EVENTS attribute set. Oth-
        erwise, 0 is returned.
        
    TEXT_EDITABLE
    
        Set this keyword to return 1 if Widget_ID is a 
        text widget that allows user editing of its con-
        tents. Otherwise, 0 is returned.
        
    TEXT_NUMBER
    
        Set this keyword to return the number of charac-
        ters currently contained in the specified text wid-
        get.
        
    TEXT_OFFSET_TO_XY
    
        Use this keyword to translate a text widget 
        character offset into column and line form. The 
        value of this keyword should be set to the character 
        offset (an integer) to be translated. WIDGET_INFO 
        returns a two-element integer array giving the col-
        umn (element 0) and line (element 1) corresponding 
        to the offset. If the offset specified is out of 
        range, the array [-1,-1] is returned.
        
    TEXT_SELECT
    
        Set this keyword to return the character start-
        ing and ending character offsets of the selected 
        (highlighted) text in the specified text widget. 
        WIDGET_INFO returns a two-element integer array con-
        taining the starting (element 0) and ending (element 
        1) positions of the current selection as offsets 
        from the start (position 0).
        
    TEXT_XY_TO_OFFSET
    
        Use this keyword to translate a text widget 
        position given in line and column form into a char-
        acter offset. The value of this keyword should be 
        set to a two-element integer array specifying the 
        column (element 0) and line (element 1) position. 
        WIDGET_INFO returns the character offset (as a long-
        word integer) corresponding to the position. If the 
        position specified is out of range, -1 is returned.
        
    TEXT_TOP_LINE
    
        Set this keyword to return the zero-based line 
        number of the line currently at the top of a text 
        widget's display viewport. Note that this value is 
        different from the zero-based character offset of 
        the characters in the line. The character offset can 
        be calculated from the line offset via the 
        TEXT_XY_TO_OFFSET keyword.
        
    TYPE
    
    
Set this keyword to return the type code of the specified Widget_ID. Possible 
    values are given 
    below:Value  Type
    
    ----------------
    
    0      Base
    
    1      Button
    
    2      Slider
    
    3      Text
    
    4      Draw
    
    5      Label
    
    6      List
    
    VALID_ID
    
        Set this keyword to return 1 if Widget_ID repre-
        sents a currently-valid widget. Otherwise, 0 is 
        returned.
        
    VERSION
    
        Set this keyword to return a structure that 
        gives information about the widget implementation. 
        This structure has the following definition:
        
        { WIDGET_VERSION, STYLE:'', TOOLKIT:'', RELEASE:'' }
        
        STYLE is the style of widget toolkit used. TOOL-
        KIT is the implementation of the toolkit. RELEASE is 
        the version level of the toolkit. This field can be 
        used to distinguish between different releases of a 
        given toolkit, such as Motif 1.0 and Motif 1.1.
        
;-
;+
WIDGET_LABEL

The WIDGET_LABEL function is used to create label wid-
gets.

The returned value of this function is the widget ID 
of the newly-created label widget.

Calling Sequence

        Result = WIDGET_LABEL(Parent)
        
Arguments

    Parent 
    
        The widget ID of the parent widget for the new 
        label widget.
        
Keywords

    EVENT_FUNC
    
        A string containing the name of a function to be 
        called by the WIDGET_EVENT function when an event 
        arrives from a widget in the widget hierarchy rooted 
        at the newly-created widget.
        
    EVENT_PRO
    
        A string containing the name of a procedure to 
        be called by the WIDGET_EVENT function when an event 
        arrives from a widget in the widget hierarchy rooted 
        at the newly-created widget.
        
    FONT
    
        A string containing the name of the font to be 
        used by the widget. This name follows the standard X 
        Window System naming conventions and wildcards can 
        be used.
        
    FRAME
    
        The value of this keyword specifies the width of 
        a frame (in pixels) to be drawn around the borders 
        of the widget. Note that this keyword is only a 
        "hint" to the toolkit, and may be ignored in some 
        instances.
        
    FUNC_GET_VALUE
    
        A string containing the name of a function to be 
        called when the GET_VALUE keyword to the 
        WIDGET_CONTROL procedure is called for this widget. 
        Using this technique allows you to change the value 
        that should be returned for a widget. Compound wid-
        gets use this ability to define their values trans-
        parently to the user.
        
    GROUP_LEADER
    
        The widget ID of an existing widget that serves 
        as "group leader" for the newly-created widget. When 
        a group leader is killed, for any reason, all wid-
        gets in the group are also destroyed.
        
        A given widget can be in more than one group. 
        The WIDGET_CONTROL procedure can be used to add 
        additional group associations to a widget. It is not 
        possible to remove a widget from an existing group.
        
    KILL_NOTIFY
    
        A string containing the name of a procedure to 
        be called automatically when the specified widget 
        dies. Each widget is allowed a single such "call-
        back" procedure. It can be removed by setting the 
        routine to the null string ('').
        
        The callback routine is called with the widget 
        identifier as its only argument. At that point, the 
        widget identifier can only be used with the 
        WIDGET_CONTROL procedure to get or set the user 
        value. All other requests that require a widget ID 
        are disallowed for the target widget. The callback 
        is not issued until the WIDGET_EVENT function is 
        called. If a "kill notify" procedure causes an error 
        that halts the execution of the procedure, the halt 
        occurs in the procedure that called WIDGET_EVENT, 
        not in the kill notify procedure itself.
        
    NO_COPY
    
        Usually, when the SET_UVALUE, GET_UVALUE, or 
        SEND_EVENT keywords are used, the source variable 
        memory is copied. When the NO_COPY keyword is set, 
        the source variable dynamic memory is used by the 
        destination, without copying. This feature can be 
        used by compound widgets to obtain state information 
        from a UVALUE without all the memory copying that 
        would otherwise occur.
        
    PRO_SET_VALUE
    
        A string containing the name of a procedure to 
        be called when the SET_VALUE keyword to the 
        WIDGET_CONTROL procedure is called for this widget. 
        Using this technique allows you to designate a rou-
        tine that sets the value for a widget. Compound wid-
        gets use this ability to define their values 
        transparently to the user.
        
    RESOURCE_NAME
    
        A string containing an X Window System resource 
        name to be applied to the widget. See the IDL Refer-
        ence Guide for a complete discussion of this key-
        word.
        
    UVALUE
    
        The "user value" to be assigned to the widget.
        
        Each widget can contain a user-specified value 
        of any data type and organization. This value is not 
        used by the widget in any way, but exists entirely 
        for the convenience of the IDL programmer. This key-
        word allows you to set this value when the widget is 
        first created.
        
        If UVALUE is not present, the widget's initial 
        user value is undefined.
        
    VALUE
    
        The initial value setting of the widget. The 
        value of a widget label is a string containing the 
        text for the label.
        
    XOFFSET
    
        The horizontal offset of the widget (in pixels) 
        relative to its parent.
        
        Specifying an offset relative to a row or column 
        major base widget does not work because those wid-
        gets enforce their own layout policies. This keyword 
        is primarily of use relative to a plain base widget. 
        Note that it is best to avoid using this style of 
        widget programming.
        
    XSIZE
    
        The width of the widget (in pixels for most wid-
        gets, in characters for text widgets).
        
        Most widgets attempt to size themselves to fit 
        the situation. However, if the desired effect is not 
        produced, use this keyword to override it. This key-
        word is only a "hint" to the toolkit and may be 
        ignored in some situations.
        
    YOFFSET
    
        The vertical offset of the widget (in pixels) 
        relative to its parent. This offset is specified 
        relative to the upper left corner of the parent wid-
        get.
        
        Specifying an offset relative to a row or column 
        major base widget does not work because those wid-
        gets enforce their own layout policies. This keyword 
        is primarily of use relative to a plain base widget. 
        Note that it is best to avoid using this style of 
        widget programming.
        
    YSIZE
    
        The height of the widget (in pixels for most 
        widgets, in characters for text widgets, is number 
        of visible items for list widgets).
        
        Most widgets attempt to size themselves to fit 
        the situation. However, if the desired effect is not 
        produced, use this keyword to override it. This key-
        word is only a "hint" to the toolkit and may be 
        ignored in some situations.
        
Widget Events Returned by Label Widgets

        Label widgets do not return an event structure.
        
;-
;+
WIDGET_LIST

The WIDGET_LIST function is used to create list wid-
gets. A list widget offers the user a list of text ele-
ments from which to choose. The user can select an item by 
pointing at it with the mouse cursor and pressing a but-
ton. This action generates an event containing the index 
of the selected item, which ranges from 0 to the number of 
elements in the list minus one.

The returned value of this function is the widget ID 
of the newly-created list widget.

Calling Sequence

        Result = WIDGET_LIST(Parent)
        
Arguments

    Parent 
    
        Parent specifies the widget that will be the 
        parent for the new list widget.
        
Keywords

    EVENT_FUNC
    
        A string containing the name of a function to be 
        called by the WIDGET_EVENT function when an event 
        arrives from a widget in the widget hierarchy rooted 
        at the newly-created widget.
        
    EVENT_PRO
    
        A string containing the name of a procedure to 
        be called by the WIDGET_EVENT function when an event 
        arrives from a widget in the widget hierarchy rooted 
        at the newly-created widget.
        
    FONT
    
        A string containing the name of the font to be 
        used by the widget. This name follows the standard X 
        Window System naming conventions and wildcards can 
        be used.
        
    FRAME
    
        The value of this keyword specifies the width of 
        a frame (in pixels) to be drawn around the borders 
        of the widget. Note that this keyword is only a 
        "hint" to the toolkit, and may be ignored in some 
        instances.
        
    FUNC_GET_VALUE
    
        A string containing the name of a function to be 
        called when the GET_VALUE keyword to the 
        WIDGET_CONTROL procedure is called for this widget. 
        Using this technique allows you to change the value 
        that should be returned for a widget. Compound wid-
        gets use this ability to define their values trans-
        parently to the user.
        
    GROUP_LEADER
    
        The widget ID of an existing widget that serves 
        as "group leader" for the newly-created widget. When 
        a group leader is killed, for any reason, all wid-
        gets in the group are also destroyed.
        
        A given widget can be in more than one group. 
        The WIDGET_CONTROL procedure can be used to add 
        additional group associations to a widget. It is not 
        possible to remove a widget from an existing group.
        
    KILL_NOTIFY
    
        A string containing the name of a procedure to 
        be called automatically when the specified widget 
        dies. Each widget is allowed a single such "call-
        back" procedure. It can be removed by setting the 
        routine to the null string ('').
        
        The callback routine is called with the widget 
        identifier as its only argument. At that point, the 
        widget identifier can only be used with the 
        WIDGET_CONTROL procedure to get or set the user 
        value. All other requests that require a widget ID 
        are disallowed for the target widget. The callback 
        is not issued until the WIDGET_EVENT function is 
        called. If a "kill notify" procedure causes an error 
        that halts the execution of the procedure, the halt 
        occurs in the procedure that called WIDGET_EVENT, 
        not in the kill notify procedure itself.
        
    NO_COPY
    
        Usually, when the SET_UVALUE, GET_UVALUE, or 
        SEND_EVENT keywords are used, the source variable 
        memory is copied. When the NO_COPY keyword is set, 
        the source variable dynamic memory is used by the 
        destination, without copying. This feature can be 
        used by compound widgets to obtain state information 
        from a UVALUE without all the memory copying that 
        would otherwise occur.
        
    PRO_SET_VALUE
    
        A string containing the name of a procedure to 
        be called when the SET_VALUE keyword to the 
        WIDGET_CONTROL procedure is called for this widget. 
        Using this technique allows you to designate a rou-
        tine that sets the value for a widget. Compound wid-
        gets use this ability to define their values 
        transparently to the user.
        
    RESOURCE_NAME
    
        A string containing an X Window System resource 
        name to be applied to the widget. See the IDL Refer-
        ence Guide for a complete discussion of this key-
        word.
        
    UVALUE
    
        The "user value" to be assigned to the widget.
        
        Each widget can contain a user-specified value 
        of any data type and organization. This value is not 
        used by the widget in any way, but exists entirely 
        for the convenience of the IDL programmer. This key-
        word allows you to set this value when the widget is 
        first created.
        
        If UVALUE is not present, the widget's initial 
        user value is undefined.
        
    VALUE
    
        The initial value setting of the widget. The 
        value of a list widget is a scalar string or array 
        of strings that contains the text of the list items-
        one list item per array element. List widgets are 
        sized based on the length (in characters) of the 
        longest item specified in the array of values for 
        the VALUE keyword.
        
        Note that the value of a list widget can only be 
        set. It cannot be retrieved using WIDGET_CONTROL.
        
    XOFFSET
    
        The horizontal offset of the widget (in pixels) 
        relative to its parent.
        
        Specifying an offset relative to a row or column 
        major base widget does not work because those wid-
        gets enforce their own layout policies. This keyword 
        is primarily of use relative to a plain base widget. 
        Note that it is best to avoid using this style of 
        widget programming.
        
    XSIZE
    
        The width of the widget (in pixels for most wid-
        gets, in characters for text widgets).
        
        Most widgets attempt to size themselves to fit 
        the situation. However, if the desired effect is not 
        produced, use this keyword to override it. This key-
        word is only a "hint" to the toolkit and may be 
        ignored in some situations.
        
        Currently, the XSIZE keyword to WIDGET_LIST is 
        ignored. The width of a list widget is determined by 
        the length (in characters) of the longest item spec-
        ified in the array of values for the VALUE keyword.
        
    YOFFSET
    
        The vertical offset of the widget (in pixels) 
        relative to its parent. This offset is specified 
        relative to the upper left corner of the parent wid-
        get.
        
        Specifying an offset relative to a row or column 
        major base widget does not work because those wid-
        gets enforce their own layout policies. This keyword 
        is primarily of use relative to a plain base widget. 
        Note that it is best to avoid using this style of 
        widget programming.
        
    YSIZE
    
        The height of the widget (in pixels for most 
        widgets, in characters for text widgets, is number 
        of visible items for list widgets).
        
        Most widgets attempt to size themselves to fit 
        the situation. However, if the desired effect is not 
        produced, use this keyword to override it. This key-
        word is only a "hint" to the toolkit and may be 
        ignored in some situations.
        
Widget Events Returned by List Widgets

Pressing the mouse button while the mouse cursor is 
over an element of a list widget causes the widget to 
highlight the appearance of that element and to generate 
an event. The appearance of any previously selected ele-
ment is restored to normal at the same time. The event 
structure returned by the WIDGET_EVENT function is 
defined by the following statement:

{ WIDGET_LIST, ID:0L, TOP:0L, HANDLER:0L, INDEX:0L }

The first three fields are the standard fields found 
in every widget event. INDEX returns the index of the 
selected item. This can be used to index the array of 
names originally used to set the widget's value.

;-
;+
WIDGET_SLIDER

The WIDGET_SLIDER function is used to create slider 
widgets. Slider widgets are used to indicate an integer 
value from a range of possible values. They consist of a 
rectangular region which represents the possible range of 
values. Inside this region is a sliding pointer that dis-
plays the current value. This pointer can be manipulated 
by the user via the mouse, or from within IDL via the 
WIDGET_CONTROL procedure.

The returned value of this function is the widget ID 
of the newly-created slider widget.

Calling Sequence

        Result = WIDGET_SLIDER(Parent)
        
Arguments

    Parent 
    
        The widget ID of the parent for the new slider 
        widget.
        
Keywords

    DRAG
    
        Set this keyword to cause events to be generated 
        continuously while the slider is being dragged by 
        the user. Normally, slider widgets generate position 
        events only when the slider comes to rest at its 
        final position and the mouse button is released.
        
        When a slider widget is set to return drag 
        events, a large number of events can be generated. 
        On slower machines, poor performance can result. 
        Therefore, this option should only be used when 
        detailed or truly interactive control is really 
        required.
        
    EVENT_FUNC
    
        A string containing the name of a function to be 
        called by the WIDGET_EVENT function when an event 
        arrives from a widget in the widget hierarchy rooted 
        at the newly-created widget.
        
    EVENT_PRO
    
        A string containing the name of a procedure to 
        be called by the WIDGET_EVENT function when an event 
        arrives from a widget in the widget hierarchy rooted 
        at the newly-created widget.
        
    FONT
    
        A string containing the name of the font to be 
        used by the widget. This name follows the standard X 
        Window System naming conventions and wildcards can 
        be used.
        
    FRAME
    
        The value of this keyword specifies the width of 
        a frame (in pixels) to be drawn around the borders 
        of the widget. Note that this keyword is only a 
        "hint" to the toolkit, and may be ignored in some 
        instances.
        
    FUNC_GET_VALUE
    
        A string containing the name of a function to be 
        called when the GET_VALUE keyword to the 
        WIDGET_CONTROL procedure is called for this widget. 
        Using this technique allows you to change the value 
        that should be returned for a widget. Compound wid-
        gets use this ability to define their values trans-
        parently to the user.
        
    GROUP_LEADER
    
        The widget ID of an existing widget that serves 
        as "group leader" for the newly-created widget. When 
        a group leader is killed, for any reason, all wid-
        gets in the group are also destroyed.
        
        A given widget can be in more than one group. 
        The WIDGET_CONTROL procedure can be used to add 
        additional group associations to a widget. It is not 
        possible to remove a widget from an existing group.
        
    KILL_NOTIFY
    
        A string containing the name of a procedure to 
        be called automatically when the specified widget 
        dies. Each widget is allowed a single such "call-
        back" procedure. It can be removed by setting the 
        routine to the null string ('').
        
        The callback routine is called with the widget 
        identifier as its only argument. At that point, the 
        widget identifier can only be used with the 
        WIDGET_CONTROL procedure to get or set the user 
        value. All other requests that require a widget ID 
        are disallowed for the target widget. The callback 
        is not issued until the WIDGET_EVENT function is 
        called. If a "kill notify" procedure causes an error 
        that halts the execution of the procedure, the halt 
        occurs in the procedure that called WIDGET_EVENT, 
        not in the kill notify procedure itself.
        
    MAXIMUM
    
        The maximum value of the range encompassed by 
        the slider. If this keyword is not supplied, a 
        default of 100 is used.
        
    MINIMUM
    
        The minimum value of the range encompassed by 
        the slider. If this keyword is not supplied, a 
        default of 0 is used.
        
    NO_COPY
    
        Usually, when the SET_UVALUE, GET_UVALUE, or 
        SEND_EVENT keywords are used, the source variable 
        memory is copied. When the NO_COPY keyword is set, 
        the source variable dynamic memory is used by the 
        destination, without copying. This feature can be 
        used by compound widgets to obtain state information 
        from a UVALUE without all the memory copying that 
        would otherwise occur.
        
    PRO_SET_VALUE
    
        A string containing the name of a procedure to 
        be called when the SET_VALUE keyword to the 
        WIDGET_CONTROL procedure is called for this widget. 
        Using this technique allows you to designate a rou-
        tine that sets the value for a widget. Compound wid-
        gets use this ability to define their values 
        transparently to the user.
        
    RESOURCE_NAME
    
        A string containing an X Window System resource 
        name to be applied to the widget. See the IDL Refer-
        ence Guide for a complete discussion of this key-
        word.
        
    SCROLL
    
        Under the Motif window manager, the value pro-
        vided for SCROLL specifies how many units the scroll 
        bar should move when the user clicks the left mouse 
        button inside the slider area, but not on the slider 
        itself. This keyword has no effect under other win-
        dow systems.
        
    SUPPRESS_VALUE
    
        Set this keyword to inhibit the display of the 
        current slider value.
        
        Sliders work only with integer units. This key-
        word can be used to suppress the actual value of a 
        slider so that a program can present the user with a 
        slider that seems to work in other units (such as 
        floating-point) or with a non-linear scale.
        
    UVALUE
    
        The "user value" to be assigned to the widget.
        
        Each widget can contain a user-specified value 
        of any data type and organization. This value is not 
        used by the widget in any way, but exists entirely 
        for the convenience of the IDL programmer. This key-
        word allows you to set this value when the widget is 
        first created.
        
        If UVALUE is not present, the widget's initial 
        user value is undefined.
        
    VALUE
    
        The initial value setting of the widget. The 
        value of a widget slider is the current position of 
        the slider.
        
    TITLE
    
        A string containing the title to be used for the 
        slider widget.
        
    VERTICAL
    
        Set this keyword to crate a vertical slider. If 
        this keyword is omitted, the slider is horizontal.
        
    XOFFSET
    
        The horizontal offset of the widget (in pixels) 
        relative to its parent.
        
        Specifying an offset relative to a row or column 
        major base widget does not work because those wid-
        gets enforce their own layout policies. This keyword 
        is primarily of use relative to a plain base widget. 
        Note that it is best to avoid using this style of 
        widget programming.
        
    XSIZE
    
        The width of the widget (in pixels for most wid-
        gets, in characters for text widgets).
        
        Most widgets attempt to size themselves to fit 
        the situation. However, if the desired effect is not 
        produced, use this keyword to override it. This key-
        word is only a "hint" to the toolkit and may be 
        ignored in some situations.
        
    YOFFSET
    
        The vertical offset of the widget (in pixels) 
        relative to its parent. This offset is specified 
        relative to the upper left corner of the parent wid-
        get.
        
        Specifying an offset relative to a row or column 
        major base widget does not work because those wid-
        gets enforce their own layout policies. This keyword 
        is primarily of use relative to a plain base widget. 
        Note that it is best to avoid using this style of 
        widget programming.
        
    YSIZE
    
        The height of the widget (in pixels for most 
        widgets, in characters for text widgets, is number 
        of visible items for list widgets).
        
        Most widgets attempt to size themselves to fit 
        the situation. However, if the desired effect is not 
        produced, use this keyword to override it. This key-
        word is only a "hint" to the toolkit and may be 
        ignored in some situations.
        
Slider Widget Events

Slider widgets generate events when the mouse is used 
to change their value. The event structure returned by the 
WIDGET_EVENT function is defined by the following state-
ment:

{ WIDGET_SLIDER, ID:0L, TOP:0L, HANDLER:0L, VALUE:0L, 
DRAG:0}

ID is the widget ID of the button generating the 
event. TOP is the widget ID of the top level widget con-
taining ID. HANDLER contains the widget ID of the widget 
associated with the handler routine. VALUE returns the new 
value of the slider. DRAG returns integer 1 if the slider 
event was generated as part of a drag operation (i.e., if 
the user holds down the select button and drags the slider 
"thumb", or if the select button was released as part of 
the event. The DRAG field can be used to avoid computa-
tionally expensive operations until the user releases the 
slider.

Known Implementation Problems

Under Motif 1.0, vertical sliders with a title orga-
nized in row bases get horizontally truncated and the 
slider doesn't show (the title does). Use the XSIZE key-
word to work around this.

;-
;+
WIDGET_TEXT

The WIDGET_TEXT function creates text widgets. Text 
widgets display text and optionally get textual input from 
the user. They can have 1 or more lines, and can option-
ally contain scroll bars to allow viewing more text than 
can otherwise be displayed on the screen.

The returned value of this function is the widget ID 
of the newly-created text widget.

Calling Sequence

        Result = WIDGET_TEXT(Parent)
        
Arguments

    Parent
    
        The widget ID of the parent widget for the new 
        text widget.
        
Keywords

    ALL_EVENTS
    
        Along with the EDITABLE keyword, ALL_EVENTS con-
        trols the type of events generated by the text wid-
        get. Set the ALL_EVENTS keyword to cause the full 
        set of events to be generated. If ALL_EVENTS is not 
        set, setting EDITABLE causes only end-of-line events 
        to be generated. If EDITABLE is not set, all events 
        are suppressed. See the table below for additional 
        details.
        
                  Keywords         |       Effects
        
        ---------------------------------------------------
        
                                   | Input
        
                                   | changes     Type of
        
                                   | widget      events
        
        ALL_TEXT_EVENTS   EDITABLE  | contents?   generated
        
        ---------------------------------------------------
        
        Not set           Not set   | No         None
        
        Not set           Set       | Yes        EOL insert
        
        Set               Not set   | No         None
        
        Set               Set       | Yes        All events
        
    EDITABLE
    
        Set this keyword to allow direct user editing of 
        the text widget contents. Normally, the text in text 
        widgets is read-only. See the table above for a 
        description of how EDITABLE interacts with the 
        ALL_EVENTS keyword.
        
    EVENT_FUNC
    
        A string containing the name of a function to be 
        called by the WIDGET_EVENT function when an event 
        arrives from a widget in the widget hierarchy rooted 
        at the newly-created widget.
        
    EVENT_PRO
    
        A string containing the name of a procedure to 
        be called by the WIDGET_EVENT function when an event 
        arrives from a widget in the widget hierarchy rooted 
        at the newly-created widget.
        
    FONT
    
        A string containing the name of the font to be 
        used by the widget. This name follows the standard X 
        Window System naming conventions and wildcards can 
        be used.
        
    FRAME
    
        The value of this keyword specifies the width of 
        a frame (in pixels) to be drawn around the borders 
        of the widget. Note that this keyword is only a 
        "hint" to the toolkit, and may be ignored in some 
        instances.
        
    FUNC_GET_VALUE
    
        A string containing the name of a function to be 
        called when the GET_VALUE keyword to the 
        WIDGET_CONTROL procedure is called for this widget. 
        Using this technique allows you to change the value 
        that should be returned for a widget. Compound wid-
        gets use this ability to define their values trans-
        parently to the user.
        
    GROUP_LEADER
    
        The widget ID of an existing widget that serves 
        as "group leader" for the newly-created widget. When 
        a group leader is killed, for any reason, all wid-
        gets in the group are also destroyed.
        
        A given widget can be in more than one group. 
        The WIDGET_CONTROL procedure can be used to add 
        additional group associations to a widget. It is not 
        possible to remove a widget from an existing group.
        
    KILL_NOTIFY
    
        A string containing the name of a procedure to 
        be called automatically when the specified widget 
        dies. Each widget is allowed a single such "call-
        back" procedure. It can be removed by setting the 
        routine to the null string ('').
        
        The callback routine is called with the widget 
        identifier as its only argument. At that point, the 
        widget identifier can only be used with the 
        WIDGET_CONTROL procedure to get or set the user 
        value. All other requests that require a widget ID 
        are disallowed for the target widget. The callback 
        is not issued until the WIDGET_EVENT function is 
        called. If a "kill notify" procedure causes an error 
        that halts the execution of the procedure, the halt 
        occurs in the procedure that called WIDGET_EVENT, 
        not in the kill notify procedure itself.
        
    NO_COPY
    
        Usually, when the SET_UVALUE, GET_UVALUE, or 
        SEND_EVENT keywords are used, the source variable 
        memory is copied. When the NO_COPY keyword is set, 
        the source variable dynamic memory is used by the 
        destination, without copying. This feature can be 
        used by compound widgets to obtain state information 
        from a UVALUE without all the memory copying that 
        would otherwise occur.
        
    NO_NEWLINE
    
        Normally, when setting the value of a multi-line 
        text widget, newline characters are automatically 
        appended to the end of each line of text. Set this 
        keyword to suppress this action.
        
    PRO_SET_VALUE
    
        A string containing the name of a procedure to 
        be called when the SET_VALUE keyword to the 
        WIDGET_CONTROL procedure is called for this widget. 
        Using this technique allows you to designate a rou-
        tine that sets the value for a widget. Compound wid-
        gets use this ability to define their values 
        transparently to the user.
        
    RESOURCE_NAME
    
        A string containing an X Window System resource 
        name to be applied to the widget. See the IDL Refer-
        ence Guide for a complete discussion of this key-
        word.
        
    SCROLL
    
        Set this keyword to give the widget scroll bars 
        that allow viewing portions of the widget contents 
        that are not currently on the screen.
        
    UVALUE
    
        The "user value" to be assigned to the widget.
        
        Each widget can contain a user-specified value 
        of any data type and organization. This value is not 
        used by the widget in any way, but exists entirely 
        for the convenience of the IDL programmer. This key-
        word allows you to set this value when the widget is 
        first created.
        
        If UVALUE is not present, the widget's initial 
        user value is undefined.
        
    VALUE
    
        The initial value setting of the widget. The 
        value of a text widget is the current text displayed 
        by the widget.
        
    XOFFSET
    
        The horizontal offset of the widget (in pixels) 
        relative to its parent.
        
        Specifying an offset relative to a row or column 
        major base widget does not work because those wid-
        gets enforce their own layout policies. This keyword 
        is primarily of use relative to a plain base widget. 
        Note that it is best to avoid using this style of 
        widget programming.
        
    XSIZE
    
        The width of the widget (in pixels for most wid-
        gets, in characters for text widgets).
        
        Most widgets attempt to size themselves to fit 
        the situation. However, if the desired effect is not 
        produced, use this keyword to override it. This key-
        word is only a "hint" to the toolkit and may be 
        ignored in some situations.
        
    YOFFSET
    
        The vertical offset of the widget (in pixels) 
        relative to its parent. This offset is specified 
        relative to the upper left corner of the parent wid-
        get.
        
        Specifying an offset relative to a row or column 
        major base widget does not work because those wid-
        gets enforce their own layout policies. This keyword 
        is primarily of use relative to a plain base widget. 
        Note that it is best to avoid using this style of 
        widget programming.
        
    YSIZE
    
        The height of the widget (in pixels for most 
        widgets, in characters for text widgets, is number 
        of visible items for list widgets).
        
        Most widgets attempt to size themselves to fit 
        the situation. However, if the desired effect is not 
        produced, use this keyword to override it. This key-
        word is only a "hint" to the toolkit and may be 
        ignored in some situations.
        
Text Widget Events

 There are several variations of the text widget event 
structure depending on the specific event being reported. 
All of these structures contain the standard three fields 
(ID, TOP, and HANDLER) as well as an integer TYPE field 
that indicates which type of structure has been returned. 
Programs should always check the type field before refer-
encing fields that are not present in all text event 
structures. The different text widget event structures 
are described below.

    Insert Single Character (TYPE = 0)
    
        This is the type of structure returned when 
        characters are typed into a text widget by a user.
        
        { WIDGET_TEXT_CH, ID:0L, TOP:0L, HANDLER:0L, TYPE:0, 
        OFFSET:0L, CH:0B }
        
        OFFSET is the insertion position that will 
        result after the character is inserted. CH is the 
        ASCII value of the character.
        
    Insert Multiple Characters (TYPE = 1)
    
        This is the type of structure returned when mul-
        tiple characters are pasted into a text widget by 
        the window system.
        
        { WIDGET_TEXT_STR, ID:0L, TOP:0L, HANDLER:0L, 
        TYPE:1, OFFSET:0L, STR:'' }
        
        OFFSET is the insertion position that will 
        result after the text is inserted. STR is the string 
        to be inserted.
        
    Delete Text (TYPE = 2)
    
        This is the type of structure returned when any 
        amount of text is deleted from a text widget.
        
        { WIDGET_TEXT_DEL, ID:0L, TOP:0L, HANDLER:0L, 
        TYPE:2, OFFSET:0L, LENGTH:0L }
        
        OFFSET is the (zero-based) character position of 
        the first character to be deleted. It is also the 
        insertion position that will result when the charac-
        ter is inserted. LENGTH gives the number of charac-
        ters involved.
        
    Selection (TYPE = 3)
    
        This is the type of structure returned when an 
        area of text is selected (highlighted) by the user.
        
        { WIDGET_TEXT_SEL, ID:0L, TOP:0L, HANDLER:0L, 
        TYPE:3, OFFSET:0L, LENGTH:0L }
        
        The event announces a change in the insertion 
        point. OFFSET is the (zero-based) character position 
        of the first character to be selected. LENGTH gives 
        the number of characters involved. A LENGTH of zero 
        indicates that the widget has lost its previous 
        selection, and the new insertion position is given 
        by OFFSET.
        
Note that text insertion, text deletion, or any change 
in the current insertion point causes any current selec-
tion to be lost. In such cases, the loss of selection is 
implied by the text event reporting the insert/delete/
movement and a separate zero length selection event is not 
sent.

;-
;+
WINDOW

The WINDOW procedure creates a window for the display 
of graphics or text. It is only necessary to use WINDOW if 
more than one simultaneous window or a special size window 
is desired because a window is created automatically the 
first time any display procedure attempts to access the 
window system. The newly-created window becomes the cur-
rent window, and the system variable !D.WINDOW is set to 
that window's window index. (See the description of the 
WSET procedure for a discussion of the current IDL win-
dow.)

The behavior of WINDOW varies slightly depending on 
the window system in effect. See the discussion of IDL 
graphics devices in Chapter 3 for additional details.

Calling Sequence

        WINDOW [, Window_Index]
        
Arguments

    Window_Index
    
        The window index for the newly-created window. A 
        window index is an integer value between 0 and 31 
        that is used to refer to the window. If this parame-
        ter is omitted, window index 0 is used. If the value 
        of Window_Index specifies an existing window, the 
        existing window is deleted and a new one is created. 
        If you need to create more than 32 windows, use the 
        FREE keyword described below.
        
Keywords

    COLORS
    
        The maximum number of color table indices to be 
        used when drawing. This parameter has effect only if 
        supplied when the first window is created. If COLORS 
        is not present when the first window is created, all 
        or most of the available color indices are allocated 
        depending upon the window system in use.
        
        To use monochrome windows on a color display use 
        COLORS = 2, when creating the first window. One 
        color table is maintained for all windows. When 
        using X windows, a negative value for COLORS speci-
        fies that all but the given number of colors from 
        the shared color table should be allocated.
        
    FREE
    
        Set this keyword to create a window using the 
        smallest unused window index above 32. If this key-
        word is present, the Window_Index argument can be 
        omitted. The default position of the new window is 
        opposite that of the current window. Using the FREE 
        keyword allows the creation of a large number of 
        windows. The system variable !D.WINDOW is set to the 
        index of the newly-created window.
        
    PIXMAP
    
        If the current graphics device is the X Window 
        system, setting the PIXMAP keyword specifies that 
        the window being created is actually an invisible 
        portion of the display memory called a pixmap.
        
    RETAIN
    
    
This keyword specifies how backing store for the window should be handled. 
    The possible values for this keyword are given in the table 
    below:Value  Description
    -----------------------------------------------
    0      No backing store
    1      The server or window system is requested
           to make the window retained
    2      IDL provides backing store
    
    TITLE
    
        A scalar string that contains the window's 
        label. If not specified, the window is given a label 
        of the form "IDL n", where n is the index number of 
        the window. For example, to create a window with the 
        label "IDL Graphics", enter:
        
        WINDOW, TITLE='IDL Graphics'
        
    XPOS 
    
        The X position of the lower left corner of the 
        window, specified in device coordinates. If no posi-
        tion is specified, the position of the window is 
        determined from the value of Window Index using the 
        following rules:
        
    Window 0 is placed in the upper right hand cor-
    ner.
    
    Even numbered windows are placed on the top half 
    of the screen and odd numbered windows are placed on 
    the bottom half.
    
    Windows 0,1,4,5,8, and 9 are placed on the right 
    side of the screen and windows 2,3,6, and 7 are 
    placed on the left.
    
    YPOS
    
        The Y position of the lower left window corner, 
        specified in device coordinates. See the description 
        of XPOS for details.
        
    XSIZE
    
        The width of the window in pixels.
        
    YSIZE
    
        The height of the window in pixels. 
        
Example

Create graphics window number 0 with a size of 400 by 
400 pixels and a title that reads "Square Window" by 
entering:

WINDOW, 0, XSIZE=400, YSIZE=400, TITLE='Square Window'

;-
;+
WMENU

The WMENU function displays a menu whose choices are 
given by the elements of a string array and returns the 
index of the user's response. The user must select a menu 
item with the mouse and click the left mouse button. The 
returned value ranges from 0 to the number of elements in 
Strings minus one. This function is only available with X 
windows and SunView.

Note that this is a very old and primitive menu cre-
ation routine. Much better results can be obtained using 
the "widget" routines.

Calling Sequence

        Result = WMENU(Strings)
        
Arguments

    Strings
    
        A string array where each element contains the 
        text of one menu choice. The maximum number of ele-
        ments, and the maximum element length are computer-
        dependent.
        
Keywords

    INITIAL_SELECTION
    
        The index of the initially highlighted selec-
        tion. When using the SunView window system, if this 
        parameter is not specified the menu is initially 
        displayed with the mouse cursor at the immediate 
        left of the first (top) selection. If this parameter 
        is specified and within the range of Strings indi-
        ces, then the initial menu display is made with the 
        designated item selected.
        
    TITLE
    
        The index of the Strings element that is the 
        title, normally 0. The title element is not select-
        able and is displayed reversed and centered. If this 
        parameter is omitted, all items are selectable.
        
Example

The following statement displays a menu entitled "Do 
you wish to continue?" containing the selections "Yes" and 
"No":

i = WMENU(['Do you wish to continue?', 'Yes', 'No'], TITLE=0, INIT=1)

The menu is displayed with "Yes" initially selected. 
The result is 1 if the user clicks the mouse on "Yes", and 
2 if the user clicks on "No".

;-
;+
WRITE_JPEG

The WRITE_JPEG procedure writes compressed images to 
files. JPEG (Joint Photographic Experts Group) is a stan-
dardized compression method for full-color and gray-scale 
images. This procedure is based in part on the work of the 
"Independent JPEG Group".

As the Independent JPEG Group states, JPEG is intended 
for "real-world" scenes (such as digitized photographs). 
Line art, such as drawings or IDL plots, and other "unre-
alistic" images are not its strong suit. Note also that 
JPEG is a "lossy" compression scheme. That is, the output 
image is not identical to the input image. Hence you must 
not use JPEG if you have to have identical output bits. 
However, on typical images of real-world scenes, very good 
compression levels can be obtained with no visible change, 
and amazingly high compression levels are possible if you 
can tolerate a low-quality image. You can trade off output 
image quality against compressed file size by adjusting a 
compression parameter. Files are encoded in JFIF, the JPEG 
File Interchange Format (however, such files are usually 
simply called "JPEG" files).

If you need to store images in a compressed format 
that is not lossy, consider using the WRITE_GIF Users' 
Library routine. This procedure writes 8-bit (256 color) 
images in the Graphics Interchange Format. To store 8-bit 
or 24-bit images without compression, consider using the 
WRITE_BMP (for Microsoft Bitmap format files) or 
TIFF_WRITE (to write Tagged Image Format Files) UserS' 
Library routines.

For a short technical introduction to the JPEG com-
pression algorithm, see: Wallace, Gregory K. "The JPEG 
Still Picture Compression Standard", Communications of 
the ACM, April 1991 (vol. 34, no. 4), pp. 30-44.

To read JPEG files, use the READ_JPEG procedure (page 
-206).

Calling Sequence

        WRITE_JPEG, [Filename,] Image
        
Arguments

    Filename
    
        A string containing the name of file to be writ-
        ten in JFIF (JPEG) format. If this parameter is not 
        present, the UNIT keyword must be specified.
        
    Image
    
        A byte array of either two or three dimensions, 
        containing the image to be written. Grayscale images 
        must have two dimensions. True-color images must 
        have three dimensions with the index of the dimen-
        sion that contains the color specified with the TRUE 
        keyword.
        
Keywords

    ORDER
    
        JPEG/JFIF images are normally written in top-to-
        bottom order. If the image array is in the standard 
        IDL order (i.e., from bottom-to-top) set ORDER to 0, 
        its default value. If the image array is in top-to-
        bottom order, ORDER must be set to 1.
        
    QUALITY
    
        This keyword specifies the quality index, in the 
        range of 0 ("terrible") to 100 ("excellent") for the 
        JPEG file. The default value is 75, to obtain "very 
        good" quality. Lower values of QUALITY produce 
        higher compression ratios and smaller files.
        
    TRUE
    
        This keyword specifies the index, starting at 1, 
        of the dimension over which the color is inter-
        leaved. For example, for an image that is pixel 
        interleaved and has dimensions of (3, m, n), set 
        TRUE to 1. Specify 2 for row-interleaved images (m, 
        3, n); and 3 for band-interleaved images (m, n, 3). 
        
    UNIT
    
        This keyword designates the logical unit number 
        of an already open file to receive the output, 
        allowing multiple JFIF images per file or the embed-
        ding of JFIF images in other data files. If this 
        keyword is used, Filename should not be specified. 
        When using VMS, open the file with the /STREAM key-
        word.
        
Examples

Write the image contained in the array A, using JPEG 
compression with a quality index of 25. The image is 
stored in bottom-to-top order:

WRITE_JPEG, 'test.dat', a, QUALITY=25

Write a true-color image to a JPEG file. The image is 
contained in the band-interleaved array A with dimensions 
(m,n,3). Assume it is stored in top-to-bottom order:

WRITE_JPEG, 'test1.dat', a, TRUE=3, /ORDER

;-
;+
WRITEU

The WRITEU procedure writes unformatted binary data 
from an expression into a file. This procedure performs a 
direct transfer with no processing of any kind being done 
to the data.

Calling Sequence

        WRITEU, Unit, Expr1 ..., Exprn
        
Arguments

    Unit
    
        The IDL file unit to which the output is sent.
        
    Expri
    
        The expressions to be output. For non-string 
        variables, the number of bytes implied by the data 
        type is output. When WRITEU is used with a variable 
        of type string, IDL outputs exactly the number of 
        bytes contained in the existing string.
        
Unix Keywords

    TRANSFER_COUNT
    
        Set this keyword to a named variable in which to 
        return the number of elements transferred by the 
        output operation. Note that the number of elements 
        is not the same as the number of bytes (except in 
        the case where the data type being transferred is 
        bytes). For example, transferring 256 floating-point 
        numbers yields a transfer count of 256, not 1024 
        (the number of bytes transferred).
        
        This keyword is useful with files opened with 
        the NOSTDIO keyword to the OPEN routines. Normally, 
        writing more data than an output device will accept 
        causes an error. Files opened with the NOSTDIO key-
        word will not generate such an error. Instead, the 
        programmer must keep track of the transfer count to 
        judge the success or failure of a WRITEU operation.
        
VMS Keywords

        Note that the obsolete FORWRT routine has been 
        replaced by WRITEU.
        
    REWRITE
    
        When writing data to a file with indexed organi-
        zation, setting the REWRITE keyword specifies that 
        the data should update the contents of the most 
        recently input record instead of creating a new 
        record.
        
Example

Create some data to store in a file by entering:

D = BYTSCL(DIST(200))

Open a new file for writing as IDL file unit number 1 
by entering:

OPENW, 1, 'newfile'

To write the data in D to the file, enter:

WRITEU, 1, D

Close file unit 1 by entering:

CLOSE, 1

;-
;+
WSET

The WSET procedure selects the current window. Most 
IDL graphics routines do not explicitly require the IDL 
window to be specified. Instead, they use the window known 
as the current window. The window index number of the cur-
rent window is contained in the read-only system variable 
!D.WINDOW. WSET only works with devices that have window-
ing systems.

Calling Sequence

        WSET [, Window_Index]
        
Arguments

    Window_Index
    
        This argument specifies the window index of the 
        window to be made current. If this argument is not 
        specified, a default of 0 is used.
        
Example

Create IDL windows 1 and 2 by entering:

WINDOW, 1 & WINDOW, 2

Set the current window to window 1 and display an 
image by entering:

WSET, 1 & TVSCL, DIST(100)

Set the current window to window 2 and display an 
image by entering:

WSET, 2 & TVSCL, DIST(100)

;-
;+
WSHOW

The WSHOW procedure exposes or hides the designated 
window.

Calling Sequence

        WSHOW [, Window_Index [, Show]]
        
Arguments

    Window_Index
    
        The window index of the window to be hidden or 
        exposed. If this argument is not specified, the cur-
        rent window is assumed. If this index is the widget 
        ID of a draw widget, the widget base associated with 
        that drawable is brought to the front of the screen.
        
    Show
    
        Set Show to 0 to hide the window. Omit this 
        argument or set it to 1 to expose the window.
        
Keywords

    ICONIC
    
        Set this keyword to iconify the window. Set 
        ICONIC to 0 to de-iconify the window.
        
        Under X Windows, iconification is the task of 
        the window manager, and client applications such as 
        IDL have no direct control over it. The ICONIC key-
        word serves as a hint to the window manager, which 
        is free to iconify the window or ignore the request 
        as it sees fit.
        
Example

To bring IDL window number 0 to the front, enter:

WSHOW, 1

;-
;+
XYOUTS

The XYOUTS procedure draws text on the currently-
selected graphics device starting at the designated coor-
dinate.

Arguments X, Y, and String can be any combination of 
scalars or arrays. If the arguments are arrays, multiple 
strings are output.

If the optional X and Y arguments are omitted, the 
text is positioned at the end of the most recently output 
text string.

Important keywords that control the appearance and 
positioning of the text include: ALIGNMENT, the justifi-
cation of the text; CHARSIZE, the size of the text; FONT, 
chooses between vector drawn and hardware fonts; COLOR, 
the color of the text; and ORIENTATION, the angle between 
the baseline of the text and the horizontal. With hardware 
fonts, most of the text attributes, (e.g., size and orien-
tation), are predetermined and not changeable.

Note: specify the Z coordinate with the Z keyword when 
positioning text in three dimensions.

Calling Sequence

        XYOUTS, [X, Y,] String
        
Arguments

    X, Y
    
        The horizontal and vertical coordinates used to 
        position the string(s). X and Y are normally inter-
        preted in data coordinates. The DEVICE and NORMAL 
        keywords can be used to specify the coordinate 
        units.
        
        X and Y can be arrays of positions if String is 
        an array.
        
    String
    
        The string(s) to be output. This argument can be 
        a scalar string or an array of strings. If this 
        argument is not a string, it is converted prior to 
        use using the default formatting rules.
        
        If String is an array, X, Y, and the COLOR key-
        word can also be arrays so that each string can have 
        a separate location and color.
        
Keywords

    ALIGNMENT
    
        Specifies the alignment of the text baseline. An 
        alignment of 0.0 (the default) aligns the left edge 
        of the text baseline with the given (x, y) coordi-
        nate. An alignment of 1.0 right-justifies the text, 
        while 0.5 results in text centered over the point 
        (x, y).
        
    CHARSIZE
    
        The overall character size for the annotation. A 
        CHARSIZE of 1.0 is normal. Setting CHARSIZE = -1 
        suppresses output of the text string.
        
    CHARTHICK
    
        The line thickness of the vector drawn font 
        characters.This keyword has no effect when used with 
        the hardware drawn fonts. The default value is 1.0.
        
    TEXT_AXES
    
        This keyword specifies the plane of vector drawn 
        text when three-dimensional plotting is enabled. By 
        default, text is drawn in the plane of the XY axes. 
        The horizontal text direction is in the X plane, and 
        the vertical text direction is in the Y plane. Val-
        ues for this keyword can range from 0 to 5, with the 
        following effects: 0 for XY, 1 for XZ, 2 for YZ, 3 
        for YX, 4 for ZX, and 5 for ZY. The notation ZY means 
        that the horizontal direction of the text lies in 
        the Z plane, and the vertical direction of the text 
        is drawn in the Y plane.
        
    WIDTH
    
        Set this keyword to a named variable in which to 
        return the width of the text string, in normalized 
        coordinate units.
        
Graphics Keywords Accepted

        See Chapter 2, Graphics Keywords and System 
        Variables, for the description of graphics and plot-
        ting keywords not listed above. CHANNEL CLIP COLOR 
        DATA DEVICE FONT NOCLIP NORMAL ORIENTATION T3D Z.
        
Example

Print the string "This is text" at device coordinate 
position (100,100) by entering:

XYOUTS, 100, 100, 'This is text', /DEVICE

Print an array of strings with each element of the 
array printed at a different location. Use larger text 
than in the previous example. Enter:

XYOUTS, [0, 200, 250], [200, 50, 100], ['This', 'is', 'text'], 
CHARSIZE = 3, /DEVICE


;-