%VERSION:2 %TITLE:ROUTINES 214 1499 0: 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 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 [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