NAME: .COMPILE The .COMPILE command compiles and saves procedures and programs in the same manner as .RUN. If one or more filenames are specified, the procedures and functions contained therein are compiled but not executed. If you enter this command at the Command Input Line of the IDLDE and the files are not yet open, IDL opens the files within Editor windows and compiles the procedures and functions contained therein. See RESOLVE_ROUTINE for a way to invoke the same operation from within an IDL routine, and RESOLVE_ALL for a way to automatically compile all user-written or library functions called by all currently-compiled routines. If the -f flag is specified, File is compiled from the source stored temporarily in TempFile rather than on disk in File itself. This allows you to make changes to File (in an IDLDE editor window, for example), store the modified source into the temporary file (IDLDE does it automatically), compile, and test the changes without overwriting the original code stored in File. Note .COMPILE is an executive command. Executive commands can only be used at the IDL command prompt, not in programs. Syntax .COMPILE [File1, ..., Filen] .COMPILE -f File TempFile .CONTINUE [Previous Routine] [Next Routine] [List of Routines] NAME: .CONTINUE The .CONTINUE command continues execution of a program that has stopped because of an error, a stop statement, or a keyboard interrupt. IDL saves the location of the beginning of the last statement executed before an error. If it is possible to correct the error condition in the interactive mode, the offending statement can be re- executed by entering .CONTINUE. After STOP statements, .CONTINUE continues execution at the next statement. The .CONTINUE command can be abbreviated; for example, .C. Execution of a program interrupted by typing Ctrl+C also can be resumed at the point of interruption with the .CONTINUE command. Note .CONTINUE is an executive command. Executive commands can only be used at the IDL command prompt, not in programs. Syntax .CONTINUE .EDIT [Previous Routine] [Next Routine] [List of Routines] NAME: .EDIT The .EDIT command opens files in IDL Editor windows when called from the Command Input Line of the IDLDE. This functionality is only available on the Windows and Motif platforms. Note that filenames are separated by spaces, not commas. Note .EDIT is an executive command. Executive commands can only be used at the IDL command prompt, not in programs. Syntax .EDIT File1 [File2 ... Filen] .FULL_RESET_SESSION [Previous Routine] [Next Routine] [List of Routines] NAME: .FULL_RESET_SESSION The .FULL_RESET_SESSION command does everything .RESET_SESSION does, plus the following: * Removes all system routines installed via LINKIMAGE or a DLM. * Removes all structure definitions installed via a DLM. * Removes all message blocks added by DLMs. * Unloads all sharable libraries loaded into IDL via CALL_EXTERNAL, LINKIMAGE, or a DLM. * Re-initializes all DLMs to their unloaded initial state. Note The VMS operating system does not support unloading sharable libraries. Therefore, .FULL_RESET_SESSION is identical to .RESET_SESSION under VMS, and these extra steps are not performed. Note .FULL_RESET_SESSION is an executive command. Executive commands can only be used at the IDL command prompt, not in programs. Syntax .FULL_RESET_SESSION .GO [Previous Routine] [Next Routine] [List of Routines] NAME: .GO The .GO command starts execution at the beginning of a previously-compiled main program. Note .GO is an executive command. Executive commands can only be used at the IDL command prompt, not in programs. Syntax .GO .OUT [Previous Routine] [Next Routine] [List of Routines] NAME: .OUT The .OUT command continues executing statements in the current program until it returns. Note .OUT is an executive command. Executive commands can only be used at the IDL command prompt, not in programs. Syntax .OUT .RESET_SESSION [Previous Routine] [Next Routine] [List of Routines] NAME: .RESET_SESSION The .RESET_SESSION command resets much of the state of an IDL session without requiring the user to exit and restart the IDL session. .RESET_SESSION does the following: * Returns current execution point to $MAIN$ (RETALL). * Removes all breakpoints. * Closes all files except the standard 3 units, the JOURNAL file (if any), and any files in use by graphics drivers. * Destroys/Removes the following: * All local variables in $MAIN$. * All widgets. Exit handlers are not called. * All windows and pixmaps for the current window system graphics device are closed. No other graphics state is reset. * All common blocks. * All handles * All user defined system variables * All pointer and object reference heap variables. * Object destructors are not called. * All user defined structure definitions. * All user defined object definitions. * All compiled user functions and procedures, including the main program ($MAIN$), if any. The following are not reset: * The current values of intrinsic system variables are retained. * The saved commands and output log are preserved. * Graphics drivers are not reset to their full uninitialized state. However, all windows and pixmaps for the current window system device are closed. * The following files are not closed: * Stdin (LUN 0) * Stdout (LUN -1) * Stderr (LUN -2) * The journal file (!JOURNAL) if one is open. * Any files in use by graphics drivers (e.g. PostScript). * Dynamically loaded graphics drivers (LINKIMAGE) are not removed, nor are any dynamic sharable libraries containing such drivers, even if the same library was also used for another purpose such as CALL_EXTERNAL, LINKIMAGE system routines, or DLMs. See the .FULL_RESET_SESSION executive command to unload dynamic libraries. Note .RESET_SESSION is an executive command. Executive commands can only be used at the IDL command prompt, not in programs. Syntax .RESET_SESSION .RETURN [Previous Routine] [Next Routine] [List of Routines] NAME: .RETURN The .RETURN command continues execution of a program until encountering a RETURN statement. This is convenient for debugging programs since it allows the whole program to run, stopping before returning to the next-higher program level so you can examine local variables. Also see the RETURN command. Note .RETURN is an executive command. Executive commands can only be used at the IDL command prompt, not in programs. Syntax .RETURN .RNEW [Previous Routine] [Next Routine] [List of Routines] NAME: .RNEW The .RNEW command compiles and saves procedures and functions in the same manner as .RUN. In addition, all variables in the main program unit, except those in common blocks, are erased. The -T and -L filename switches have the same effect as with .RUN. Note .RNEW is an executive command. Executive commands can only be used at the IDL command prompt, not in programs. Syntax .RNEW [File1, ..., Filen] To save listing in a file: .RNEW -L ListFile.lis File1 [, File2, ..., Filen] To display listing on screen: .RNEW -T File1 [, File2, ..., Filen] Example Some statements using the .RUN and .RNEW commands are shown below. Statement Description .RUN Accept a program from the keyboard. Retain the present variables. .RUN myfile Compile the file myfile.pro. If it is not found in the current directory, try to find it in the directory search path. .RUN -T A, B, C Compile the files a.pro, b.pro and c.pro. List the files on the terminal. Table 2: Examples using .RUN and .RNEW Statement Description .RNEW -L myfile.lis myfile, yourfile Erase all variables and compile the files myfile.pro and yourfile.pro. Produce a listing on myfile.lis. Table 2: Examples using .RUN and .RNEW .RUN [Previous Routine] [Next Routine] [List of Routines] NAME: .RUN The .RUN command compiles procedures, functions, and/or main programs in memory. Main programs are executed immediately. The command can be followed by a list of files to be compiled. Filenames are separated by blanks, tabs, or commas. If a file specification is included in the command, IDL searches for the file first in the current directory, then in the directories specified by the system variable !PATH. See "Executing Program Files" in Chapter 2 of Using IDL for more information on IDL's search strategy. If a main program unit is encountered, execution of the program will begin after all files have been read if there were no errors. The values of all of the variables are retained. If the file isn't found, input is accepted from the keyboard until a complete program unit is entered. Files containing IDL procedures, programs, and functions are assumed to have the file extension (suffix) .pro. Files created with the SAVE procedure are assumed to have the extension .sav. See "Preparing and Running Programs" in Chapter 2 of Using IDL for further information. Note .RUN is an executive command. Executive commands can only be used at the IDL command prompt, not in programs. Syntax .RUN [File1, ..., Filen] To save listing in a file: .RUN -L ListFile.lis File1 [, File2, ..., Filen] To display listing on screen: .RUN -T File1 [, File2, ..., Filen] Note Subsequent calls to .RUN compile the procedure again. Using .RUN to Make Program Listings The command arguments -T for terminal listing or -L filename for listing to a named file can appear after the command name and before the program filenames to produce a numbered program listing directed to the terminal or to a file. For instance, to see a listing on the screen as a result of compiling a procedure contained in a file named analyze.pro, use the following command: .RUN -T analyze To compile the same procedure and save the listing in a file named analyze.lis, use the following command: .RUN -L analyze.lis analyze In listings produced by IDL, the line number of each statement is printed at the left margin. This number is the same as that printed in IDL error statements, simplifying location of the statement causing the error. Note If the compiled file contains more than one procedure or function, line numbering is reset to "1" each time the end of a program segment is detected. Each level of block nesting is indented four spaces to the right of the preceding block level to improve the legibility of the program's structure. .SKIP [Previous Routine] [Next Routine] [List of Routines] NAME: .SKIP The .SKIP command skips one or more statements and then executes a single step. It is useful for continuing over a program statement that caused an error. If the optional argument n is present, it gives the number of statements to skip; otherwise, a single statement is skipped. Note that .SKIP does not skip into a called routine. For example, consider the following program segment: ...... ... ... OPENR, 1, 'missing' READF, 1, xxx, ..., ... ... ... ... If the OPENR statement fails because the specified file does not exist, program execution will halt with the OPENR statement as the current statement. Execution can not be resumed with the executive command .CONTINUE because it attempts to re-execute the offending OPENR statement, causing the same error. The remainder of the program can be executed by entering .SKIP, which skips over the incorrect OPEN statement. Note .SKIP is an executive command. Executive commands can only be used at the IDL command prompt, not in programs. Syntax .SKIP [n] .STEP [Previous Routine] [Next Routine] [List of Routines] NAME: .STEP The .STEP command executes one or more statements in the current program starting at the current position, stops, and returns control to the interactive mode. This command is useful in debugging programs. The optional argument n indicates the number of statements to execute. If n is omitted, a single statement is executed. Note .STEP is an executive command. Executive commands can only be used at the IDL command prompt, not in programs. Syntax .STEP [n] or .S [n] .STEPOVER [Previous Routine] [Next Routine] [List of Routines] NAME: .STEPOVER The .STEPOVER command executes one or more statements in the current program starting at the current position, stops, and returns control to the interactive mode. Unlike .STEP, if .STEPOVER executes a statement that calls another routine, the called routine runs until it ends before control returns to interactive mode. That is, a statement calling another routine is treated as a single statement. The optional argument n indicates the number of statements to execute. If n is omitted, a single statement (or called routine) is executed. Note .STEPOVER is an executive command. Executive commands can only be used at the IDL command prompt, not in programs. Syntax .STEPOVER [n] or .SO [n] .TRACE [Previous Routine] [Next Routine] [List of Routines] NAME: .TRACE The .TRACE command continues execution of a program that has stopped because of an error, a stop statement, or a keyboard interrupt. Note .TRACE is an executive command. Executive commands can only be used at the IDL command prompt, not in programs. Syntax .TRACE A_CORRELATE [Previous Routine] [Next Routine] [List of Routines] NAME: A_CORRELATE The A_CORRELATE function computes the autocorrelation Px(L) or autocovariance Rx(L) of a sample population X as a function of the lag L. N ­ L ­ 1 (x k ­ x)(xk+L ­ x) P k = 0 x(L) = Px(­L) = ------------------------ N ­ 1 (x k ­ x)2 k = 0 N ­ L ­ 1 Rx(L) = Rx(­L) 1 = ---- N (x k ­ x)(xk+L ­ x) k = 0 where x is the mean of the sample population x = (x0, x1, x2, ... , xN-1). Note This routine is primarily designed for use in 1-D time-series analysis. The mean is subtracted before correlating. For image processing, methods based on FFT should be used instead if more than a few tens of points exist. For example: Function AutoCorrelate, X Temp = FFT(X,-1) RETURN, FFT(Temp * CONJ(Temp), 1) END This routine is written in the IDL language. Its source code can be found in the file a_correlate.pro in the lib subdirectory of the IDL distribution. Syntax Result = A_CORRELATE(X, Lag [, /COVARIANCE] [, /DOUBLE] ) Arguments X An n-element integer, single-, or double-precision floating-point vector. Lag An n-element integer vector in the interval [-(n-2), (n-2)], specifying the signed distances between indexed elements of X. Keywords COVARIANCE Set this keyword to compute the sample autocovariance rather than the sample autocorrelation. DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. Example ; Define an n-element sample population: X = [3.73, 3.67, 3.77, 3.83, 4.67, 5.87, 6.70, 6.97, 6.40, 5.57] ; Compute the autocorrelation of X for LAG = -3, 0, 1, 3, 4, 8: lag = [-3, 0, 1, 3, 4, 8] result = A_CORRELATE(X, lag) PRINT, result IDL prints: 0.0146185 1.00000 0.810879 0.0146185 -0.325279 -0.151684 See Also CORRELATE, C_CORRELATE, M_CORRELATE, P_CORRELATE, R_CORRELATE ABS [Previous Routine] [Next Routine] [List of Routines] NAME: ABS The ABS function returns the absolute value of its argument. Syntax 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: Real2 Imaginary2 + If X is of complex type, the result is returned as the corresponding 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 structure, with each element containing the absolute value of the corresponding element of X. ABS applied to any of the unsigned integer types results in the unaltered value of X being returned. Example To print the absolute value of -25, enter: PRINT, ABS(-25) IDL prints: 25 ACOS [Previous Routine] [Next Routine] [List of Routines] NAME: 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 . ACOS now supports complex input. Syntax Result = ACOS(X) Arguments X The cosine of the desired angle in the range (-1 X 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) See Also COS ADAPT_HIST_EQUAL [Previous Routine] [Next Routine] [List of Routines] NAME: ADAPT_HIST_EQUAL The ADAPT_HIST_EQUAL function performs adaptive histogram equalization, a form of automatic image contrast enhancement. The algorithm is described in Pizer et. al., "Adaptive Histogram Equalization and its Variations.", Computer Vision, Graphics and Image Processing, 39:355-368. Adaptive histogram equalization involves applying contrast enhancement based on the local region surrounding each pixel. Each pixel is mapped to an intensity proportional to its rank within the surrounding neighborhood. This method of automatic contrast enhancement has proven to be broadly applicable to a wide range of images and to have demonstrated effectiveness. Syntax Result = ADAPT_HIST_EQUAL (Image [, FCN] [, CLIP=value] [, NREGIONS=nregions] [, TOP=value] ) Return Value The result of the function is a byte image with the same dimensions as the input image parameter. Arguments Image A two-dimensional array representing the image for which adaptive histogram equalization is to be performed. This parameter is interpreted as unsigned 8-bit data, so be sure that the input values are properly scaled into the range of 0 to 255. Keywords FCN Set this keyword to the desired cumulative probability distribution function in the form of a 256 element vector. If omitted, a linear ramp, which yields equal probability bins results. This function is later normalized, so magnitude is inconsequential, though it should increase monotonically. CLIP Set this keyword to a nonzero value to clip the histogram by limiting its slope to the given CLIP value, thereby limiting contrast. For example, if CLIP is set to 3, the slope of the histogram is limited to 3. By default, the slope and/or contrast is not limited. Noise over-enhancement in nearly homogeneous regions is reduced by setting this parameter to values larger than 1.0. NREGIONS Set this keyword to the size of the overlapped tiles, as a fraction of the largest dimensions of the image size. The default is 12, which makes each tile 1/12 the size of the largest image dimension. TOP Set this keyword to the maximum value of the scaled output array. The default is 255. Example The following code snippet reads a data file in the examples/data subdirectory of the IDL distribution containing a cerebral angiogram, and then displays both the original image and the adaptive histogram equalized image: OPENR, 1, FILEPATH('cereb.dat', $ SUBDIRECTORY=['examples','data']) ;Image size = 512 x 512 a = BYTARR(512,512, /NOZERO) ;Read it READU, 1, a CLOSE, 1 ; Reduce size of image for comparison a = CONGRID(a, 256,256) ;Show original TVSCL, a, 0 ;Show processed TV, ADAPT_HIST_EQUAL(a, TOP=!D.TABLE_SIZE-1), 1 See Also H_EQ_CT, H_EQ_INT, HIST_2D, HIST_EQUAL, HISTOGRAM ALOG [Previous Routine] [Next Routine] [List of Routines] NAME: ALOG The ALOG function returns the natural logarithm of X. The result has the same structure as X. Syntax 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 See Also ALOG10 ALOG10 [Previous Routine] [Next Routine] [List of Routines] NAME: ALOG10 The ALOG10 function returns the logarithm to the base 10 of X. This function operates in the same manner as the ALOG function. Syntax 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) See Also ALOG AMOEBA [Previous Routine] [Next Routine] [List of Routines] NAME: AMOEBA The AMOEBA function performs multidimensional minimization of a function Func(x), where x is an n-dimensional vector, using the downhill simplex method of Nelder and Mead, 1965, Computer Journal, Vol 7, pp 308-313. The downhill simplex method is not as efficient as Powell's method, and usually requires more function evaluations. However, the simplex method requires only function evaluations-not derivatives-and may be more reliable than Powell's method. If the minimum is found, AMOEBA returns an n-element vector corresponding to the function's minimum value. If a minimum within the given tolerance is not found within the specified number of iterations, AMOEBA returns a scalar value of -1. Results are returned with the same precision (single- or double-precision floating- point) as is returned by the user-supplied function to be minimized. This routine is written in the IDL language. Its source code can be found in the file amoeba.pro in the lib subdirectory of the IDL distribution. AMOEBA is based on the routine amoeba described in section 10.4 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press, and is used by permission. Syntax Result = AMOEBA( Ftol [, FUNCTION_NAME=string] [, FUNCTION_VALUE=variable] [, NCALLS=value] [, NMAX=value] [, P0=vector, SCALE=vector | , SIMPLEX=array] ) Arguments Ftol The fractional tolerance to be achieved in the function value-that is, the fractional decrease in the function value in the terminating step. If the function you supply returns a single-precision result, Ftol should never be less than your machine's floating-point precision-the value contained in the EPS field of the structure returned by the MACHAR function. If the function you supply returns a double- precision floating-point value, Ftol should not be less than your machine' double- precision floating-point precision. See MACHAR for details. Keywords FUNCTION_NAME Set this keyword equal to a string containing the name of the function to be minimized. If this keyword is omitted, AMOEBA assumes that an IDL function named "FUNC" is to be used. The function to be minimized must be written as an IDL function and compiled prior to calling AMOEBA. This function must accept an n-element vector as its only parameter and return a scalar single- or double precision floating-point value as its result. See the Example section below for an example function. FUNCTION_VALUE Set this keyword equal to a named variable that will contain an (n+1)-element vector of the function values at the simplex points. The first element contains the function minimum. NCALLS Set this keyword equal to a named variable that will contain a count of the number of times the function was evaluated. NMAX Set this keyword equal to a scalar value specifying the maximum number of function evaluations allowed before terminating. The default is 5000. P0 Set this keyword equal to an n-element single- or double-precision floating-point vector specifying the initial starting point. Note that if you specify P0, you must also specify SCALE. For example, in a 3-dimensional problem, if the initial guess is the point [0,0,0], and you know that the function's minimum value occurs in the interval: -10 < X[0] < 10, -100 < X[1] < 100, -200 < X[(2] < 200, specify: P0=[0,0,0] and SCALE=[10, 100, 200]. Alternately, you can omit P0 and SCALE and specify SIMPLEX. SCALE Set this keyword equal to a scalar or n-element vector containing the problem's characteristic length scale for each dimension. SCALE is used with P0 to form an initial (n+1) point simplex. If all dimensions have the same scale, set SCALE equal to a scalar. If SCALE is specified as a scalar, the function's minimum lies within a distance of SCALE from P0. If SCALE is an N-dimensional vector, the function's minimum lies within the Ndim+1 simplex with the vertices P0, P0 + [1,0,...,0] * SCALE, P0 + [0,1,0,...,0] * SCALE, ..., and P0+[0,0,...,1] * SCALE. SIMPLEX Set this keyword equal to an n by n+1 single- or double-precision floating-point array containing the starting simplex. After AMOEBA has returned, the SIMPLEX array contains the simplex enclosing the function minimum. The first point in the array, SIMPLEX[*,0], corresponds to the function's minimum. This keyword is ignored if the P0 and SCALE keywords are set. Example Use AMOEBA to find the slope and intercept of a straight line that fits a given set of points, minimizing the maximum error. The function to be minimized (FUNC, in this case) returns the maximum error, given p[0] = intercept, and p[1] = slope. ; First define the function FUNC: FUNCTION FUNC, P COMMON FUNC_XY, X, Y RETURN, MAX(ABS(Y - (P[0] + P[1] * X))) END ; Put the data points into a common block so they are accessible to ; the function: COMMON FUNC_XY, X, Y ; Define the data points: X = FINDGEN(17)*5 Y = [ 12.0, 24.3, 39.6, 51.0, 66.5, 78.4, 92.7, 107.8, $ 120.0, 135.5, 147.5, 161.0, 175.4, 187.4, 202.5, 215.4, 229.9] ; Call the function. Set the fractional tolerance to 1 part in ; 10^5, the initial guess to [0,0], and specify that the minimum ; should be found within a distance of 100 of that point: R = AMOEBA(1.0e-5, SCALE=1.0e2, P0 = [0, 0], FUNCTION_VALUE=fval) ; Check for convergence: IF N_ELEMENTS(R) EQ 1 THEN MESSAGE, 'AMOEBA failed to converge' ; Print results: PRINT, 'Intercept, Slope:', r, $ 'Function value (max error): ', fval[0] IDL prints: Intercept, Slope: 11.4100 2.72800 Function value: 1.33000 See Also POWELL ANNOTATE [Previous Routine] [Next Routine] [List of Routines] NAME: ANNOTATE The ANNOTATE procedure starts an IDL widget program that allows you to interactively annotate images and plots with text and drawings. Drawing objects include lines, arrows, polygons, rectangles, circles, and ellipses. Annotation files can be saved and restored, and annotated displays can be written to TIFF or PostScript files. The Annotation widget will work on any IDL graphics window or draw widget. This routine is written in the IDL language. Its source code can be found in the file annotate.pro in the lib subdirectory of the IDL distribution. Using the Annotation Widget Before calling the Annotation widget, plot or display your data in an IDL graphics window or draw widget. Unless you specify otherwise (using the DRAWABLE or WINDOW keywords), annotations will be made in the current graphics window. For information on using the Annotation widget, click on the widget's "Help" button. Syntax ANNOTATE [, COLOR_INDICES=array] [, DRAWABLE=widget_id | , WINDOW=index] [, LOAD_FILE=filename] [/TEK_COLORS] Arguments This procedure has no required arguments. Keywords COLOR_INDICES An array of color indices from which the user can choose colors. For example, to allow the user to choose 10 colors, spread evenly over the available indices, set the keyword as follows: COLOR_INDICES = INDGEN(10) * (!D.N_COLORS-1) / 9 If neither TEK_COLORS or COLOR_INDICES are specified, the default is to load 10 colors, evenly distributed over those available. DRAWABLE The widget ID of the draw widget for the annotations. Do not set both DRAWABLE and WINDOW. If neither WINDOW or DRAWABLE are specified, the current window is used. LOAD_FILE The name of an annotation format file to load after initialization. TEK_COLORS Set this keyword and the Tektronix color table is loaded starting at color index TEK_COLORS(0), with TEK_COLORS(1) color indices. The Tektronix color table contains up to 32 distinct colors suitable for graphics. If neither TEK_COLORS or COLOR_INDICES are specified, the default is to load 10 colors, evenly distributed over those available. WINDOW The window index number of the window to receive the annotations. Do not set both DRAWABLE and WINDOW. If neither WINDOW or DRAWABLE are specified, the current window is used. Example ; Output an image in the current window: TVSCL, HANNING(300,200) ; Annotate it: ANNOTATE See Also PLOTS, XYOUTS ARG_PRESENT [Previous Routine] [Next Routine] [List of Routines] NAME: ARG_PRESENT The ARG_PRESENT function returns a nonzero value if the following conditions are met: * The argument to ARG_PRESENT was passed as a plain or keyword argument to the current routine by its caller, and * The argument to ARG_PRESENT is a named variable into which a value will be copied when the current routine exits. In other words, ARG_PRESENT returns TRUE if the value of the specified variable will be passed back to the caller. This function is useful in user-written procedures that need to know if the lifetime of a value they are creating extends beyond the current routine's lifetime. This can be important for two reasons: 1. To avoid expensive computations that the caller is not interested in. 2. To prevent heap variable leakage that would result if the routine creates pointers or object references and assigns them to arguments that are not passed back to the caller. Syntax Result = ARG_PRESENT(Variable) Arguments Variable The variable to be tested. Example Suppose that you are writing an IDL procedure that has the following procedure definition line: PRO myproc, RET_PTR = ret_ptr The intent of the RET_PTR keyword is to pass back a pointer to a new pointer heap variable. The following command could be used to avoid creating (and possibly losing) a pointer if no named variable is provided by the caller: IF ARG_PRESENT(ret_ptr) THEN BEGIN The commands that follow would only be executed if ret_ptr is supplied and will be copied into a variable in the scope of the calling routine. See Also KEYWORD_SET, N_ELEMENTS, N_PARAMS ARRAY_EQUAL [Previous Routine] [Next Routine] [List of Routines] NAME: ARRAY_EQUAL The ARRAY_EQUAL function is a fast way to compare data for equality in situations where the index of the elements that differ are not of interest. This operation is much faster than using TOTAL(A NE B), because it stops the comparison as soon as the first inequality is found, an intermediate array is not created, and only one pass is made through the data. For best speed, ensure that the operands are of the same data type. Arrays may be compared to scalars, in which case each element is compared to the scalar. For two arrays to be equal, they must have the same number of elements. If the types of the operands differ, the type of the least precise is converted to that of the most precise, unless the NO_TYPECONV keyword is specified to prevent it. This function works on all numeric types and strings. Syntax Result = ARRAY_EQUAL( Op1 , Op2 [, /NO_TYPECONV ] ) Return Value Returns 1 (true) if, and only if, all elements of Op1 are equal to Op2; returns 0 (false) at the first instance of inequality. Arguments Op1, Op2 The variables to be compared. Keywords NO_TYPECONV By default, ARRAY_EQUAL converts operands of different types to a common type before performing the equality comparison. Set NO_TYPECONV to disallow this implicit type conversion. If NO_TYPECONV is specified, operands of different types are never considered to be equal, even if their numeric values are the same. Example ; Return True (1) if all elements of a are equal to a 0 byte: IF ARRAY_EQUAL(a, 0b) THEN ... ; Return True (1) if all elements of a are equal all elements of b: IF ARRAY_EQUAL(a, b) THEN ... ARROW [Previous Routine] [Next Routine] [List of Routines] NAME: ARROW The ARROW procedure draws one or more vectors with arrow heads. This routine is written in the IDL language. Its source code can be found in the file arrow.pro in the lib subdirectory of the IDL distribution. Syntax ARROW, X0, Y0, X1, Y1 [, /DATA | , /NORMALIZED] [, HSIZE=length] [, COLOR=index] [, HTHICK=value] [, /SOLID] [, THICK=value] Arguments X0, Y0 Arrays or scalars containing the coordinates of the tail end of the vector or vectors. Coordinates are in DEVICE coordinates unless otherwise specified. X1,Y1 Arrays or scalars containing the coordinates of the arrowhead end of the vector or vectors. X1 and Y1 must have the save number of elements as X0 and Y0. Keywords DATA Set this keyword if vector coordinates are DATA coordinates. NORMALIZED Set this keyword if vector coordinates are NORMALIZED coordinates. HSIZE Use this keyword to set the length of the lines used to draw the arrowhead. The default is 1/64th the width of the display (!D.X_SIZE / 64.). If the HSIZE is positive, the value is assumed to be in device coordinate units. If HSIZE is negative, the arrowhead length is set to the vector length * ABS(HSIZE). The lines are separated by 60 degrees to make the arrowhead. COLOR The color of the arrow. The default is the highest color index. HTHICK The thickness of the arrowheads. The default is 1.0. SOLID Set this keyword to make a solid arrow, using polygon fills, looks better for thick arrows. THICK The thickness of the body. The default is 1.0. Examples Draw an arrow from (100,150) to (300,350) in DEVICE units: ARROW, 100, 150, 300, 350 Draw a sine wave with arrows from the line Y = 0 to SIN(X/4): X = FINDGEN(50) Y = SIN(x/4) PLOT, X, Y ARROW, X, REPLICATE(0,50), X, Y, /DATA See Also ANNOTATE, PLOTS, VELOVECT ASCII_TEMPLATE [Previous Routine] [Next Routine] [List of Routines] NAME: ASCII_TEMPLATE The ASCII_TEMPLATE function presents a graphical user interface (GUI) which generates a template defining an ASCII file format. Templates are IDL structure variables that may be used when reading ASCII files with the READ_ASCII routine. See READ_ASCII for details on reading ASCII files. This routine is written in the IDL language. Its source code can be found in the file ascii_template.pro in the lib subdirectory of the IDL distribution. Syntax Result = ASCII_TEMPLATE( [Filename] [, BROWSE_LINES=lines] [, CANCEL=variable] [, GROUP=widget_id] ) Arguments Filename A string containing the name of a file to base the template on. If Filename is not specified, a dialog allows you to choose a file. Keywords BROWSE_LINES Set this keyword equal to the number of lines that will be read in at a time when the "Browse" button is selected. The default is 50 lines. CANCEL Set this keyword to a named variable that will contain the byte value 1 if the user clicked the "Cancel" button, or 0 otherwise. GROUP The widget ID of an existing widget that serves as "group leader" for the ASCII_TEMPLATE graphical user interface. When a group leader is killed, for any reason, all widgets in the group are also destroyed. Example Use the following command to generate a template structure from the file "myFile": myTemplate = ASCII_TEMPLATE(myFile) See Also READ_ASCII, BINARY_TEMPLATE ASIN [Previous Routine] [Next Routine] [List of Routines] NAME: 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 - /2 and /2. Rules for the type and structure of the result are the same as those given for the ACOS function. ASIN now supports complex input. Syntax Result = ASIN(X) Arguments X The sine of the desired angle, -1 X 1. Example To print the arc-sine of 0.707, enter: PRINT, ASIN(0.707) IDL prints: 0.785247 See Also SIN ASSOC [Previous Routine] [Next Routine] [List of Routines] NAME: 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. Note Unformatted data files generated by FORTRAN programs under UNIX contain an extra long word before and after each logical record in the file. ASSOC does not interpret these extra bytes but considers them to be part of the data. This is true even if the F77_UNFORMATTED keyword is specified in the OPEN statement. Therefore, ASSOC should not be used with such files. Instead, such files should be processed using READU and WRITEU. An example of using IDL to read such data is given in "Using Unformatted Input/Output" in Chapter 8 of Building IDL Applications. Note Associated file variables cannot be used for output with files opened using the COMPRESS keyword to OPEN. This is due to the fact that it is not possible to move the current file position backwards in a compressed file that is currently open for writing. ASSOC is allowed with compressed files opened for input only. However, such operations may be slow due to the large amount of work required to change the file position in a compressed file. Effective use of ASSOC requires the ability to rapidly position the file to arbitrary positions. In general, files that require random access may not be good candidates for compression. If this is necessary however, such files can be processed using READU and WRITEU. Syntax Result = ASSOC( Unit, Array_Structure [, Offset] [, /PACKED] ) 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 followed by the actual data. Keywords PACKED When ASSOC is applied to structures, the default action is to map the actual definition of the structure for the current machine, including any holes required to properly align the fields. (IDL uses the same rules for laying out structures as the C language). If the PACKED keyword is specified, I/O using the resulting variable instead works in the same manner as READU and WRITEU, and data is moved one field at a time and there are no alignment gaps between the fields. 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 displayed. Note that the data associated with A[0] is not held in memory. It is read in every time there is a reference to A[0]. To store the image in the memory-resident array B, you could enter: B = A[0] See Also OPEN, READU ATAN [Previous Routine] [Next Routine] [List of Routines] NAME: 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 - /2 and /2 for the single argument case, and between - and if two arguments are given. ATAN now supports complex input. Syntax Result = ATAN(X) or Result = ATAN(Y, X) Arguments X The tangent of the desired angle. Y An optional argument. If this argument is supplied, ATAN returns the angle whose tangent is equal to Y/X. If both arguments are zero, the result is undefined. Example 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: ;Define function TO_POLAR that accepts X and Y as arguments: FUNCTION TO_POLAR, X, Y ;Return the distance and angle as a two-element array: RETURN, [SQRT(X^2 + Y^2), ATAN(Y, X)] END See Also TAN, TANH AXIS [Previous Routine] [Next Routine] [List of Routines] NAME: 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. By default, AXIS draws an X axis. The XAXIS, YAXIS, and ZAXIS keywords can be used to select a specific axis type and position. Syntax AXIS [, X [, Y [, Z]]] [, /SAVE] [, XAXIS={0 | 1} | YAXIS={0 | 1} | ZAXIS={0 | 1 | 2 | 3}] [, /XLOG] [, /YNOZERO] [, /YLOG] [, /ZLOG] Graphics Keywords: [, CHARSIZE=value] [, CHARTHICK=integer] [, COLOR=value] [, /DATA | , /DEVICE | , /NORMAL] [, FONT=integer] [, /NODATA] [, /NOERASE] [, SUBTITLE=string] [, /T3D] [, TICKLEN=value] [, {X | Y | Z}CHARSIZE=value] [, {X | Y | Z}GRIDSTYLE=integer{0 to 5}] [, {X | Y | Z}MARGIN=[left, right]] [, {X | Y | Z}MINOR=integer] [, {X | Y | Z}RANGE=[min, max]] [, {X | Y | Z}STYLE=value] [, {X | Y | Z}THICK=value] [, {X | Y | Z}TICKFORMAT=string] [, {X | Y | Z}TICKINTERVAL= value] [, {X | Y | Z}TICKLAYOUT=scalar] [, {X | Y | Z}TICKLEN=value] [, {X | Y | Z}TICKNAME=string_array] [, {X | Y | Z}TICKS=integer] [, {X | Y | Z}TICKUNITS=string] [, {X | Y | Z}TICKV=array] [, {X | Y | Z}TICK_GET=variable] [, {X | Y | Z}TITLE=string] [, ZVALUE=value{0 to 1}] 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 arguments 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 draw an X axis. If the X argument is not present, setting XAXIS equal to 0 draws an axis under the plot window with the tick marks pointing up, and setting XAXIS equal to one draws an axis above the plot window with the tick marks pointing down. If the X argument is present, the X axis is positioned accordingly, and setting XAXIS equal to 0 or 1 causes the tick marks to point up or down, respectively. XLOG Set this keyword to specify a logarithmic X axis YAXIS Set this keyword to draw a Y axis. If the Y argument is not present, setting YAXIS equal to 0 draws an axis on the left side of the plot window with the tick marks pointing right, and setting YAXIS equal to one draws an axis on the right side of the plot window with the tick marks pointing left. If the Y argument is present, the Y axis is positioned accordingly, and setting YAXIS equal to 0 or 1 causes the tick marks to point right or left, respectively. Note The YAXIS keyword must be specified in order use any Y* graphics keywords. See the note under "Graphics Keywords Accepted" on page 93 for more information. YLOG Set this keyword to specify a logarithmic Y axis. YNOZERO Set this keyword to inhibit setting the minimum Y axis value to zero when the Y data are all positive 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 maximum value of Y, in the case of positive Y data. Set bit 4 in !Y.STYLE to make this option the default. ZAXIS Set this keyword to draw a Z axis. If the Z argument is not present, setting ZAXIS has the following meanings: * 0 = lower (front) right, with tickmarks pointing left * 1 = lower (front) left, with tickmarks pointing right * 2 = upper (back) left, with tickmarks pointing right * 3 = upper (back) right, with tickmarks pointing left If the Z argument is present, the Z axis is positioned accordingly, and setting ZAXIS equal to 0 or 1 causes the tick marks to point left or right, respectively. Note that AXIS uses the 3D plotting transformation stored in the system variable field !P.T. Note The ZAXIS keyword must be specified in order use any Z* graphics keywords. See the note under Graphics Keywords Accepted for more information. Graphics Keywords Accepted See Appendix C, "Graphics Keywords" for the description of graphics and plotting keywords not listed above. Note In order for the Y* or Z* graphics keywords to work with the AXIS procedure, the corresponding YAXIS or ZAXIS keyword must be specified. For example, the following code will not draw a title for the Y axis: AXIS, YTITLE ='Y-axis Title' To use the YTITLE graphics keyword, you must specify the YAXIS keyword to AXIS: AXIS, YAXIS = 0, YTITLE ='Y-axis Title' Because the AXIS procedure draws an X axis by default, it is not necessary to specify the XAXIS keyword in order to use the X* graphics keywords. CHARSIZE, CHARTHICK, COLOR, DATA, DEVICE, FONT, NODATA, NOERASE, NORMAL, SUBTITLE, T3D, TICKLEN, [XYZ]CHARSIZE, [XYZ]GRIDSTYLE, [XYZ]MARGIN, [XYZ]MINOR, [XYZ]RANGE, [XYZ]STYLE, [XYZ]THICK, [XYZ]TICKFORMAT, [XYZ]TICKINTERVAL, [XYZ]TICKLAYOUT, [XYZ]TICKLEN, [XYZ]TICKNAME, [XYZ]TICKS, [XYZ]TICKUNITS, [XYZ]TICKV, [XYZ]TICK_GET, [XYZ]TITLE, 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: ; Make the plot, polar in this example, and suppress the X and Y ; axes using the XSTYLE and YSTYLE keywords: PLOT, /POLAR, XSTYLE=4, YSTYLE=4, TITLE='Polar Plot', r, theta ; 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,XAX=0,/DATA ; Similarly, draw the Y axis through data X = 0. The tick marks ; point left: AXIS,0,0,0,YAX=0,/DATA See Also LABEL_DATE, PLOT BAR_PLOT [Previous Routine] [Next Routine] [List of Routines] NAME: BAR_PLOT The BAR_PLOT procedure creates a bar graph. This routine is written in the IDL language. Its source code can be found in the file bar_plot.pro in the lib subdirectory of the IDL distribution. Syntax BAR_PLOT, Values [, BACKGROUND=color_index] [, BARNAMES=string_array] [, BAROFFSET=scalar] [, BARSPACE=scalar] [, BARWIDTH=value] [, BASELINES=vector] [, BASERANGE=scalar{0.0 to 1.0}] [, COLORS=vector] [, /OUTLINE] [, /OVERPLOT] [, /ROTATE] [, TITLE=string] [, XTITLE=string] [, YTITLE=string] Arguments Values A vector containing the values to be represented by the bars. Each element in Values corresponds to a single bar in the output. Keywords BACKGROUND A scalar that specifies the color index to be used for the background color. By default, the normal IDL background color is used. BARNAMES A string array, containing one string label per bar. If the bars are vertical, the labels are placed beneath them. If horizontal (rotated) bars are specified, the labels are placed to the left of the bars. BAROFFSET A scalar that specifies the offset to be applied to the first bar, in units of "nominal bar width". This keyword allows, for example, different groups of bars to be overplotted on the same graph. If not specified, the default offset is equal to BARSPACE. BARSPACE A scalar that specifies, in units of "nominal bar width", the spacing between bars. For example, if BARSPACE is 1.0, then all bars will have one bar-width of space between them. If not specified, the bars are spaced apart by 20% of the bar width. BARWIDTH A floating-point value that specifies the width of the bars in units of "nominal bar width". The nominal bar width is computed so that all the bars (and the space between them, set by default to 20% of the width of the bars) will fill the available space (optionally controlled with the BASERANGE keyword). BASELINES A vector, the same size as Values, that contains the base value associated with each bar. If not specified, a base value of zero is used for all bars. BASERANGE A floating-point scalar in the range 0.0 to 1.0, that determines the fraction of the total available plotting area (in the direction perpendicular to the bars) to be used. If not specified, the full available area is used. COLORS A vector, the same size as Values, containing the color index to be used for each bar. If not specified, the colors are selected based on spacing the color indices as widely as possible within the range of available colors (specified by !D.N_COLORS). OUTLINE If set, this keyword specifies that an outline should be drawn around each bar. OVERPLOT If set, this keyword specifies that the bar plot should be overplotted on an existing graph. ROTATE If set, this keyword indicates that horizontal rather than vertical bars should be drawn. The bases of horizontal bars are on the left, "Y" axis and the bars extend to the right. TITLE A string containing the main title for the bar plot. XTITLE A string containing the title for the X axis. YTITLE A string containing the title for the Y axis. Example By using the overplotting capability, it is relatively easy to create stacked bar charts, or different groups of bars on the same graph. The following example creates a two-dimensional array of 5 columns and 8 rows, and creates a plot with 5 bars, each of which is a "stacked" composite of 8 sections. ;Handle TrueColor displays: DEVICE, DECOMPOSED=0 ;Load color table: LOADCT, 5 ;Make axes black: !P.COLOR=0 ;Create 5-column by 8-row array: array = INDGEN(5,8) ;Create a 2D array, equal in size to array, that has identical ;color index values across each row to ensure that the same item is ;represented by the same color in all bars: colors = INTARR(5,8) FOR I = 0, 7 DO colors[*,I]=(20*I)+20 ;With arrays and colors defined, create stacked bars (note that ;the number of rows and columns is arbitrary): ;Scale range to accommodate the total bar lengths: !Y.RANGE = [0, MAX(array)] nrows = N_ELEMENTS(array[0,*]) base = INTARR(nrows) FOR I = 0, nrows-1 DO BEGIN BAR_PLOT, array[*,I], COLORS=colors[*,I], BACKGROUND=255, $ BASELINES=base, BARWIDTH=0.75, BARSPACE=0.25, OVER=(I GT 0) base = array[*,I] ENDFOR ;To plot each row of array as a clustered group of bars within the ;same graph, use the BASERANGE keyword to restrict the available ;plotting region for each set of bars, where NCOLS is the number of ;columns in array. (In this example, each group uses the same set ;of colors, but this could easily be changed.): ncols = N_ELEMENTS(array[*,0]) FOR I = 0, nrows-1 DO BEGIN BAR_PLOT, array[*,I], COLORS=colors[*,I], BACKGROUND=255, $ BARWIDTH=0.75, BARSPACE=0.25, BAROFFSET=I*(1.4*ncols), $ OVER=(I GT 0), BASERANGE=0.12 ENDFOR See Also PLOT, PSYM BEGIN...END [Previous Routine] [Next Routine] [List of Routines] NAME: BEGIN...END The BEGIN...END statement defines a block of statements. A block of statements is a group of statements that is treated as a single statement. Blocks are necessary when more than one statement is the subject of a conditional or repetitive statement. For more information on using BEGIN...END and other IDL program control statements, see Chapter 11, "Program Control" in Building IDL Applications. Syntax BEGIN statements END | ENDIF | ENDELSE | ENDFOR | ENDREP | ENDWHILE The END identifier used to terminate the block should correspond to the type of statement in which BEGIN is used. The following table lists the correct END identifiers to use with each type of statement. Statement END Identifier Example ELSE BEGIN ENDELSE IF (0) THEN A=1 ELSE BEGIN A=2 ENDELSE FOR variable=init, limit DO BEGIN ENDFOR FOR i=1,5 DO BEGIN PRINT, array[i] ENDFOR IF expression THEN BEGIN ENDIF IF (0) THEN BEGIN A=1 ENDIF REPEAT BEGIN ENDREP REPEAT BEGIN A = A * 2 ENDREP UNTIL A GT B WHILE expression DO BEGIN ENDWHILE WHILE NOT EOF(1) DO BEGIN READF, 1, A, B, C ENDWHILE LABEL: BEGIN END LABEL1: BEGIN PRINT, A END Table 3: Types of END Identifiers Statement END Identifier Example case_expression: BEGIN END CASE name OF 'Moe': BEGIN PRINT, 'Stooge' END ENDCASE switch_expression: BEGIN END SWITCH name OF 'Moe': BEGIN PRINT, 'Stooge' END ENDSWITCH Table 3: Types of END Identifiers Note CASE and SWITCH also have their own END identifiers. CASE should always be ended with ENDCASE, and SWITCH should always be ended with ENDSWITCH. BESELI [Previous Routine] [Next Routine] [List of Routines] NAME: BESELI The BESELI function returns the I Bessel function of order N for the argument X. The BESELI function is adapted from "SPECFUN - A Portable FORTRAN Package of Special Functions and Test Drivers", W. J. Cody, Algorithm 715, ACM Transactions on Mathematical Software, Vol 19, No. 1, March 1993. Syntax Result = BESELI(X, N) Return Value If X is double-precision, the result is double precision, otherwise the argument is converted to floating-point and the result is floating-point. Arguments X The expression for which the I Bessel function is required. The result will have the same dimensions as X. N The order of the I Bessel function to calculate. N should be greater than or equal to 0 and less than 20, and can be either an integer or a real number. Keywords None Example The following example plots the I and K Bessel functions for orders 0, 1 and 2: X = FINDGEN(40)/10 ;Plot I and K Bessel Functions: PLOT, X, BESELI(X, 0), MAX_VALUE=4, $ TITLE = 'I and K Bessel Functions' OPLOT, X, BESELI(X, 1) OPLOT, X, BESELI(X, 2) OPLOT, X, BESELK(X, 0), LINESTYLE=2 OPLOT, X, BESELK(X, 1), LINESTYLE=2 OPLOT, X, BESELK(X, 2), LINESTYLE=2 ;Annotate plot: xcoords = [.18, .45, .95, 1.4, 1.8, 2.4] ycoords = [2.1, 2.1, 2.1, 1.8, 1.6, 1.4] labels = ['!8K!X!D0','!8K!X!D1','!8K!X!D2','!8I!X!D0', '!8I!X!D1','!8I!X!D2'] XYOUTS, xcoords, ycoords, labels, /DATA This results in the following plot: Figure 1: I and K Bessel Functions. See Also BESELJ, BESELK, BESELY BESELJ [Previous Routine] [Next Routine] [List of Routines] NAME: BESELJ The BESELJ function returns the J Bessel function of order N for the argument X. The BESELJ function is adapted from "SPECFUN - A Portable FORTRAN Package of Special Functions and Test Drivers", W. J. Cody, Algorithm 715, ACM Transactions on Mathematical Software, Vol 19, No. 1, March 1993. Syntax Result = BESELJ(X, N) Return Value If X is double-precision, the result is double precision, otherwise the argument is converted to floating-point and the result is floating-point. Arguments X The expression for which the J Bessel function is required. The result has the same dimensions as X. N The order of the J Bessel function to calculate. N should be greater than or equal to 0 and less than 20, and can be either an integer or a real number. Keywords None Example The following example plots the J and Y Bessel functions for orders 0, 1, and 2: X = FINDGEN(100)/10 ;Plot J and Y Bessel Functions: PLOT, X, BESELJ(X, 0), TITLE = 'J and Y Bessel Functions' OPLOT, X, BESELJ(X, 1) OPLOT, X, BESELJ(X, 2) OPLOT, X, BESELY(X, 0), LINESTYLE=2 OPLOT, X, BESELY(X, 1), LINESTYLE=2 OPLOT, X, BESELY(X, 2), LINESTYLE=2 ;Annotate plot: xcoords = [1, 1.66, 3, .7, 1.7, 2.65] ycoords = [.8, .62,.52, -.42, -.42, -.42] labels = ['!8J!X!D0','!8J!X!D1','!8J!X!D2','!8Y!X!D0', '!8Y!X!D1','!8Y!X!D2'] XYOUTS, xcoords, ycoords, labels, /DATA This results in the following plot: Figure 2: The J and Y Bessel Functions. See Also BESELI, BESELK, BESELY BESELK [Previous Routine] [Next Routine] [List of Routines] NAME: BESELK The BESELK function returns the K Bessel function of order N for the argument X. The BESELK function is adapted from "SPECFUN - A Portable FORTRAN Package of Special Functions and Test Drivers", W. J. Cody, Algorithm 715, ACM Transactions on Mathematical Software, Vol 19, No. 1, March 1993. Syntax Result = BESELK( X, N ) Return Value If X is double-precision, the result is double precision, otherwise the argument is converted to floating-point and the result is floating-point. Arguments X The expression for which the K Bessel function is required. The result will have the same dimensions as X. N The order of the K Bessel function to calculate. N should be greater than or equal to 0 and less than 20, and can be either an integer or a real number. Keywords None Example The following example plots the I and K Bessel functions for orders 0, 1 and 2: X = FINDGEN(40)/10 ;Plot I and K Bessel Functions: PLOT, X, BESELI(X, 0), MAX_VALUE=4, $ TITLE = 'I and K Bessel Functions' OPLOT, X, BESELI(X, 1) OPLOT, X, BESELI(X, 2) OPLOT, X, BESELK(X, 0), LINESTYLE=2 OPLOT, X, BESELK(X, 1), LINESTYLE=2 OPLOT, X, BESELK(X, 2), LINESTYLE=2 ;Annotate plot: xcoords = [.18, .45, .95, 1.4, 1.8, 2.4] ycoords = [2.1, 2.1, 2.1, 1.8, 1.6, 1.4] labels = ['!8K!X!D0','!8K!X!D1','!8K!X!D2','!8I!X!D0', '!8I!X!D1','!8I!X!D2'] XYOUTS, xcoords, ycoords, labels, /DATA This results in the following plot: Figure 3: I and K Bessel Functions. See Also BESELI, BESELJ, BESELY BESELY [Previous Routine] [Next Routine] [List of Routines] NAME: BESELY The BESELY function returns the Y Bessel function of order N for the argument X. The BESELY function is adapted from "SPECFUN - A Portable FORTRAN Package of Special Functions and Test Drivers", W. J. Cody, Algorithm 715, ACM Transactions on Mathematical Software, Vol 19, No. 1, March 1993. Syntax Result = BESELY(X, N) Return Value If X is double-precision, the result is double precision, otherwise the argument is converted to floating-point and the result is floating-point. 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 should be greater than or equal to 0 and less than 20, and can be either an integer or a real number. Keywords None. Example The following example plots the J and Y Bessel functions for orders 0, 1, and 2: X = FINDGEN(100)/10 ;Plot J and Y Bessel Functions: PLOT, X, BESELJ(X, 0), TITLE = 'J and Y Bessel Functions' OPLOT, X, BESELJ(X, 1) OPLOT, X, BESELJ(X, 2) OPLOT, X, BESELY(X, 0), LINESTYLE=2 OPLOT, X, BESELY(X, 1), LINESTYLE=2 OPLOT, X, BESELY(X, 2), LINESTYLE=2 ;Annotate plot: xcoords = [1, 1.66, 3, .7, 1.7, 2.65] ycoords = [.8, .62,.52, -.42, -.42, -.42] labels = ['!8J!X!D0','!8J!X!D1','!8J!X!D2','!8Y!X!D0', '!8Y!X!D1','!8Y!X!D2'] XYOUTS, xcoords, ycoords, labels, /DATA This results in the following plot: Figure 4: The J and Y Bessel Functions. See Also BESELI, BESELJ, BESELK BETA [Previous Routine] [Next Routine] [List of Routines] NAME: BETA The BETA function returns the value of the beta function B(Z, W). This routine is written in the IDL language. Its source code can be found in the file beta.pro in the lib subdirectory of the IDL distribution. Syntax Result = BETA( Z, W [, /DOUBLE] ) Arguments Z, W The point at which the beta function is to be evaluated. Z and W can be scalar or array. Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. Example To evaluate the beta function at the point (1.0, 1.1) and print the result: PRINT, BETA(1.0, 1.1) IDL prints: 0.909091 The exact solution is: ((1.00 * .95135077) / (1.10 * .95135077)) = 0.909091. See Also GAMMA, IBETA, IGAMMA, LNGAMMA BILINEAR [Previous Routine] [Next Routine] [List of Routines] NAME: BILINEAR The BILINEAR function uses a bilinear interpolation algorithm to compute the value of a data array at each of a set of subscript values. The function returns a two- dimensional interpolated array of the same type as the input array. This routine is written in the IDL language. Its source code can be found in the file bilinear.pro in the lib subdirectory of the IDL distribution. Syntax Result = BILINEAR(P, IX, JY) Arguments P A two-dimensional data array. IX and JY Arrays containing the X and Y "virtual subscripts" of P for which to interpolate values. IX and JY can be either of the following: * One-dimensional, n-element floating-point arrays of subscripts to look up in P. One-dimensional arrays will be converted to two-dimensional arrays in such a way that IX contains n identical rows and JY contains n identical columns. * Two-dimensional, n-element floating-point arrays that uniquely specify the X subscripts (the IX array) and the Y subscripts (the JY array) of the points to be computed from the input array P. In either case, IX must satisfy the expressions 0 <= MIN(IX) < N0 and 0 < MAX(IX) <= N0 where N0 is the total number of columns in the array P. JY must satisfy the expressions 0 <= MIN(JY) < M0 and 0 < MAX(JY) <= M0 where M0 is the total number of rows in the array P. It is better to use two-dimensional arrays for IX and JY because the algorithm is somewhat faster. If IX and JY are specified as one-dimensional, the returned two- dimensional arrays IX and JY can be re-used on subsequent calls to take advantage of the faster 2D algorithm. Example Create a 3 x 3 floating point array P: P = FINDGEN(3,3) Suppose we wish to find the value of a point half way between the first and second elements of the first row of P. Create the subscript arrays IX and JY: IX = 0.5 ;Define the X subscript. JY = 0.0 ;Define the Y subscript. Z = BILINEAR(P, IX, JY) ;Interpolate. PRINT, Z ;Print the value at the point IX,JY within P. IDL prints: 0.500000 Suppose we wish to find the values of a 2 x 2 array of points in P. Create the subscript arrays IX and JY: IX = [[0.5, 1.9], [1.1, 2.2]] ;Define the X subscripts. JY = [[0.1, 0.9], [1.2, 1.8]] ;Define the Y subscripts. Z = BILINEAR(P, IX, JY) ;Interpolate. PRINT, Z ;Print the array of values. IDL prints: 0.800000 4.60000 4.70000 7.40000 See Also INTERPOL, INTERPOLATE, KRIG2D BIN_DATE [Previous Routine] [Next Routine] [List of Routines] NAME: BIN_DATE The BIN_DATE function converts a standard form ASCII date/time string to a binary string. The function returns a six-element integer array where: * Element 0 is the year (e.g., 1994) * Element 1 is the month (1-12) * Element 2 is the day (1-31) * Element 3 is the hour (0-23) * Element 4 is minutes (0-59) * Element 5 is seconds (0-59) This routine is written in the IDL language. Its source code can be found in the file bin_date.pro in the lib subdirectory of the IDL distribution. Syntax Result = BIN_DATE(Ascii_Time) Arguments Ascii_Time A string containing the date/time to convert in standard ASCII format. If this argument is omitted, the current date/time is used. Standard form is a 24 character string: DOW MON DD HH:MM:SS YYYY where DOW is the day of the week, MON is the month, DD is the day of month, HH:MM:SS is the time in hours, minutes, second, and YYYY is the year. See Also CALDAT, JULDAY, SYSTIME BINARY_TEMPLATE [Previous Routine] [Next Routine] [List of Routines] NAME: BINARY_TEMPLATE The BINARY_TEMPLATE function presents a graphical user interface which allows the user to interactively generate a template structure for use with READ_BINARY. The graphical user interface allows the user to define one or more fields in the binary file. The file may be big, little, or native byte ordering. Individual fields can be edited by the user to define the dimensionality and type of data to be read. Where necessary, fields can be defined in terms of other previously defined fields using IDL expressions. Fields can also be designated as "Verify". When a file is read using a template with "Verify" fields, those fields will be checked against a user defined value supplied via the template. Syntax Template = BINARY_TEMPLATE ( [Filename] [, CANCEL=variable] [, GROUP=widget_id] [, N_ROWS=rows] [, TEMPLATE=variable] ) Arguments Filename A scalar string containing the name of a binary file which may be used to test the template. As the user interacts with the BINARY_TEMPLATE graphical user interface, the user's input will be tested for correctness against the binary data in the file. If filename is not specified, a dialog allows the user to choose the file. Keywords CANCEL Set this keyword to a named variable that will contain the byte value 1 if the user clicked the "Cancel" button, or 0 otherwise. GROUP The widget ID of an existing widget that serves as "group leader" for the BINARY_TEMPLATE interface. When a group leader is killed, for any reason, all widgets in the group are also destroyed. N_ROWS Set this keyword to the number of rows to be visible in the BINARY_TEMPLATE's table of fields. Note The N_ROWS keyword is analogous to the WIDGET_TABLE and the Y_SCROLL_SIZE keywords. TEMPLATE Set this keyword to a named variable that will contain the template structure gererated by BINARY_TEMPLATE. This variable can then be specified for the TEMPLATE keyword to READ_BINARY. Note A greater than (">") or less than ("<") symbol can appear in the BINARY_TEMPLATE's "New Field" and the "Modify Field" dialogs where the offset value is displayed. The presence of either symbol indicates that the supplied offset value is "relative" from the end of the previous field or from the initial position in the file. Greater than means offset forward. Less than means offset backward. ">0" and "<0" are synonymous and mean "offset zero bytes". The user can delete these special symbols (thereby indicating that their corresponding offset value is not "relative") by typing over them in the "New Field" or "Modify Field" dialogs where the offset value is displayed. See Also READ_BINARY, ASCII_TEMPLATE BINDGEN [Previous Routine] [Next Routine] [List of Routines] NAME: 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. Syntax Result = BINDGEN(D1, ...,D8) Arguments Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. The dimensions of the result. The dimension parameters can be any scalar expression. Up to eight dimensions can be specified. If the dimension arguments are not integer values, IDL will convert them to integer values before creating the new array. 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-dimensional 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 See Also CINDGEN, DCINDGEN, DINDGEN, FINDGEN, INDGEN, LINDGEN, SINDGEN, UINDGEN, UL64INDGEN, ULINDGEN BINOMIAL [Previous Routine] [Next Routine] [List of Routines] NAME: BINOMIAL The BINOMIAL function computes the probability that in a cumulative binomial (Bernoulli) distribution, a random variable X is greater than or equal to a user- specified value V, given N independent performances and a probability of occurrence or success P in a single performance: N Probability(X V ) N! = ------------------------- ( ­ ) x!(N ­ x)!Px(1 ­ P) N x x = V This routine is written in the IDL language. Its source code can be found in the file binomial.pro in the lib subdirectory of the IDL distribution. Syntax Result = BINOMIAL(V, N, P [, /DOUBLE] [, /GAUSSIAN] ) Arguments V A non-negative integer specifying the minimum number of times the event occurs in N independent performances. N A non-negative integer specifying the number of performances. P A non-negative single- or double-precision floating-point scalar or array, in the interval [0.0, 1.0], that specifies the probability of occurrence or success of a single independent performance. Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. GAUSSIAN Set this keyword to use the Gaussian approximation, by using the normalized variable Z = (V ­ NP)/SQRT(NP(1 ­ P)). Note The Gaussian approximation is useful when N is large and neither P nor (1­P) is close to zero, where the binomial summation may overflow. If GAUSSIAN is not explicitly set, and the binomial summation overflows, then BINOMIAL will automatically switch to using the Gaussian approximation. Examples Compute the probability of obtaining at least two 6s in rolling a die four times. The result should be 0.131944. result = BINOMIAL(2, 4, 1.0/6.0) Compute the probability of obtaining exactly two 6s in rolling a die four times. The result should be 0.115741. result = BINOMIAL(2, 4, 1./6.) - BINOMIAL(3, 4, 1./6.) Compute the probability of obtaining three or fewer 6s in rolling a die four times. The result should be 0.999228. result = BINOMIAL(0, 4, 1./6.) - BINOMIAL(4, 4, 1./6.) See Also CHISQR_PDF, F_PDF, GAUSS_PDF, T_PDF BLAS_AXPY [Previous Routine] [Next Routine] [List of Routines] NAME: BLAS_AXPY The BLAS_AXPY procedure updates an existing array by adding a multiple of another array. It can also be used to update one or more one-dimensional subvectors of an array according to the following vector operation: Y = aX + Y where a is a scale factor and X is an input vector. BLAS_AXPY can be faster and use less memory than the usual IDL array notation (e.g. Y=Y+A*X) for updating existing arrays. Note BLAS_AXPY is much faster when operating on entire arrays and rows, than when used on columns or higher dimensions. Syntax BLAS_AXPY, Y, A, X [, D1, Loc1 [, D2, Range]] Arguments Y The array to be updated. Y can be of any numeric type. BLAS_AXPY does not change the size and type of Y. A The scaling factor to be multiplied with X. A may be any scalar or one-element array that IDL can convert to the type of X. BLAS_AXPY does not change A. X The array to be scaled and added to array Y, or the vector to be scaled and added to subvectors of Y. D1 An optional parameter indicating which dimension of Y is to be updated. Loc1 A variable with the same number of elements as the number of dimensions of Y. The Loc1 and D1 arguments together determine which one-dimensional subvector (or subvectors, if D1 and Range are provided) of Y is to be updated. D2 An optional parameter, indicating in which dimension of Y a group of one- dimensional subvectors are to be updated. D2 should be different from D1. Range A variable containing D2 indices indicating where to put one-dimensional updates of Y. Example ;A seed value needs to be defined: seed = 5L ;Create a multidimensional array: A = FINDGEN(40, 90, 10) ;Create a random update: B = RANDOMU(seed, 40, 90, 10) ;Add a multiple of B to A.(i.e., A = A + 4.5*B ): BLAS_AXPY, A, 4.5, B ;Add a constant to a subvector of A ;(i.e. A[*,4,9] = A[*,4,9] + 4.3): BLAS_AXPY, A, 1., REPLICATE(4.3, 40), 1, [0,4,9] ;Create a vector update: C = FINDGEN(90) ;Add C to a group of subvectors of A ;( i.e. A[ 9,*,*] = A[ 9,*,*] + C): BLAS_AXPY, A, 1., C, 2, [9,0,0], 3, LINDGEN(10) See Also REPLICATE_INPLACE BLK_CON [Previous Routine] [Next Routine] [List of Routines] NAME: BLK_CON The BLK_CON function computes a "fast convolution" of a digital signal and an impulse-response sequence. It returns the filtered signal. This routine is written in the IDL language. Its source code can be found in the file blk_con.pro in the lib subdirectory of the IDL distribution. Syntax Result = BLK_CON( Filter, Signal [, B_LENGTH=scalar] [, /DOUBLE] ) Return Value This function returns a vector with the same length as Signal. If either of the input arguments are double-precision or the DOUBLE keyword is set, the result is double- precision, otherwise the result is single-precision. Arguments Filter A P-element floating-point vector containing the impulse-response sequence of the digital filter. Signal An n-element floating-point vector containing the discrete signal samples. Keywords B_LENGTH A scalar specifying the block length of the subdivided signal segments. If this parameter is not specified, a near-optimal value is chosen by the algorithm based upon the length P of the impulse-response sequence. If P is a value less than 11 or greater than 377, then B_LENGTH must be specified. B_LENGTH must be greater than the filter length, P, and less than the number of signal samples. DOUBLE Set this keyword to force the computation to be done using double-precision arithmetic. Example ; Create a filter of length P = 32: filter = REPLICATE(1.0,32);Set all points to 1.0 filter(2*INDGEN(16)) = 0.5;Set even points to 0.5 ; Create a sampled signal with random noise: signal = SIN((FINDGEN(1000)/35.0)^2.5) noise = (RANDOMU(SEED,1000)-.5)/2. signal = signal + noise ; Convolve the filter and signal using block convolution: result = BLK_CON(filter, signal) See Also CONVOL BOX_CURSOR [Previous Routine] [Next Routine] [List of Routines] NAME: BOX_CURSOR The BOX_CURSOR procedure emulates the operation of a variable-sized box cursor (also known as a "marquee" selector). Warning BOX_CURSOR does not function properly when used within a draw widget. See the BUTTON_EVENTS and MOTION_EVENTS keywords in WIDGET_DRAW. This routine is written in the IDL language. Its source code can be found in the file box_cursor.pro in the lib subdirectory of the IDL distribution. Using BOX_CURSOR Once the box cursor has been realized, hold down the left mouse button to move the box by dragging. Hold down the middle mouse button to resize the box by dragging. (The corner nearest the initial mouse position is moved.) Press the right mouse button to exit the procedure and return the current box parameters. On machines with only two mouse buttons, hold down the left and right buttons simultaneously to resize the box. Syntax BOX_CURSOR, [ X0, Y0, NX, NY [, /INIT] [, /FIXED_SIZE]] [, /MESSAGE] Arguments X0, Y0 Named variables that will contain the coordinates of the lower left corner of the box cursor. NX, NY Named variables that will contain the width and height of the cursor, in pixels. Keywords INIT If this keyword is set, the arguments X0, Y0, NX, and NY contain the initial position and size of the box. FIXED_SIZE If this keyword is set, NX and NY contain the initial size of the box. This size may not be changed by the user. MESSAGE If this keyword is set, IDL prints a message describing operation of the cursor. See Also CURSOR BREAK [Previous Routine] [Next Routine] [List of Routines] NAME: BREAK The BREAK statement provides a convenient way to immediately exit from a loop (FOR, WHILE, REPEAT), CASE, or SWITCH statement without resorting to GOTO statements. Note BREAK is an IDL statement. For information on using statements, see Chapter 11, "Program Control" in Building IDL Applications. Syntax BREAK Example This example exits the enclosing WHILE loop when the value of i hits 5. I = 0 WHILE (1) DO BEGIN i = i + 1 IF (i eq 5) THEN BREAK ENDWHILE BREAKPOINT [Previous Routine] [Next Routine] [List of Routines] NAME: BREAKPOINT The BREAKPOINT procedure allows you to insert and remove breakpoints in programs for debugging. A breakpoint causes program execution to stop after the designated statement is executed. Breakpoints are specified using the source file name and line number. For multiple-line statements (statements containing "$", the continuation character), specify the line number of the last line of the statement. You can insert breakpoints in programs without editing the source file. Enter the following: HELP, /BREAKPOINT to display the breakpoint table which gives the index, module and source file locations of each breakpoint. Syntax BREAKPOINT [, File], Index [, ON_RECOMPILE] [, AFTER=integer] [, /CLEAR] [, CONDITION=`expression'] [, /DISABLE] [, /ENABLE] [, /ONCE] [, /SET] Arguments File An optional string argument that contains the name of the source file. Note that if File is not in the current directory, the full path name must be specified even if File is in one of the directories specified by !PATH. Index The line number at which to clear or set a breakpoint. Keywords ON_RECOMPILE This new keyword allows you to specify that a breakpoint will not take effect until the next time the file containing it is compiled. AFTER Set this keyword equal to an integer n. Execution will stop only after the nth time the breakpoint is hit. For example: BREAKPOINT, /SET, 'test.pro', 8, AFTER=3 sets a breakpoint at the eighth line of the file test.pro, but only stops execution after the breakpoint has been encountered three times. 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: ; Clear breakpoint with an index of 3: BREAKPOINT, /CLEAR, 3 ; Clear the breakpoint corresponding to the statement in the file ; test.pro, line number 8: BREAKPOINT, /CLEAR, 'test.pro',8 CONDITION Set this keyword to a string containing an IDL expression. When a breakpoint is encountered, the expression is evaluated. If the expression is true (if it returns a non- zero value), program execution is interrupted. The expression is evaluated in the context of the program containing the breakpoint. For example: BREAKPOINT, 'myfile.pro', 6, CONDITION='i gt 2' If i is greater than 2 at line 6 of myfile.pro, the program is interrupted. DISABLE Set this keyword to disable the specified breakpoint, if it exists. The breakpoint can be specified using the breakpoint index or file and line number: ; Disable breakpoint with an index of 3: BREAKPOINT, /DISABLE, 3 ; Disable the breakpoint corresponding to the statement in the file ; test.pro, line number 8: BREAKPOINT, /DISABLE, 'test.pro',8 ENABLE Set this keyword to enable the specified breakpoint if it exists. The breakpoint can be specified using the breakpoint index or file and line number: ; Enable breakpoint with an index of 3: BREAKPOINT, /ENABLE, 3 ; Enable the breakpoint corresponding to the statement in the file ; test.pro, line number 8: BREAKPOINT, /ENABLE, 'test.pro',8 ONCE Set this keyword to make the breakpoint temporary. If ONCE is set, the breakpoint is cleared as soon as it is hit. For example: BREAKPOINT, /SET, 'file.pro', 12, AFTER=3, /ONCE sets a breakpoint at line 12 of file.pro. Execution stops when line 12 is encountered the third time, and the breakpoint is automatically cleared. SET Set this keyword to set a breakpoint at the designated 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 BROYDEN [Previous Routine] [Next Routine] [List of Routines] NAME: BROYDEN The BROYDEN function solves a system of n nonlinear equations (where n 2) in n dimensions using a globally-convergent Broyden's method. The result is an n- element vector containing the solution. BROYDEN is based on the routine broydn described in section 9.7 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press, and is used by permission. Syntax Result = BROYDEN( X, Vecfunc [, CHECK=variable] [, /DOUBLE] [, EPS=value] [, ITMAX=value] [, STEPMAX=value] [, TOLF=value] [, TOLMIN=value] [, TOLX=value] ) Arguments X An n-element vector (where n 2) containing an initial guess at the solution of the system. Vecfunc A scalar string specifying the name of a user-supplied IDL function that defines the system of non-linear equations. This function must accept a vector argument X and return a vector result. For example, suppose we wish to solve the following system: 3x ­ cos(yz) ­ 1 2 x2 81(y + 0.1)2 ­ + sin(z) + 1.06 = 0 e­xy + 20z 10 ­ 3 + ------------------ 3 To represent this system, we define an IDL function named BROYFUNC: FUNCTION broyfunc, X RETURN, [3.0 * X[0] - COS(X[1]*X[2]) - 0.5,$ X[0]^2 - 81.0*(X[1] + 0.1)^2 + SIN(X[2]) + 1.06,$ EXP(-X[0]*X[1]) + 20.0 * X[2] + (10.0*!PI - 3.0)/3.0] END Keywords CHECK BROYDEN calls an internal function named fmin() to determine whether the routine has converged to a local rather than a global minimum (see Numerical Recipes, section 9.7). Use the CHECK keyword to specify a named variable which will be set to 1 if the routine has converged to a local minimum or to 0 if not. If the routine does converge to a local minimum, try restarting from a different initial guess to obtain the global minimum. DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. EPS Set this keyword to a number close to machine accuracy, used to remove noise from each iteration. The default is 10-7 for single precision, and 10-14 for double precision. ITMAX Use this keyword to specify the maximum allowed number of iterations. The default is 200. STEPMAX Use this keyword to specify the scaled maximum step length allowed in line searches. The default value is 100.0. TOLF Set the convergence criterion on the function values. The default value is 1.0 × 10-4. TOLMIN Set the criterion for deciding whether spurious convergence to a minimum of the function fmin() has occurred. The default value is 1.0 × 10-6. TOLX Set the convergence criterion on X. The default value is 1.0 × 10-7. Example We can use BROYDEN to solve the non-linear system of equations defined by the BROYFUNC function above: ;Provide an initial guess as the algorithm's starting point: X = [-1.0, 1.0, 2.0] ;Compute the solution: result = BROYDEN(X, 'BROYFUNC') ;Print the result: PRINT, result IDL prints: 0.500000 -1.10731e-07 -0.523599 The exact solution (to eight-decimal accuracy) is [0.5, 0.0, -0.52359877]. See Also FX_ROOT, FZ_ROOTS, NEWTON BYTARR [Previous Routine] [Next Routine] [List of Routines] NAME: BYTARR The BYTARR function returns a byte vector or array. Syntax Result = BYTARR( D1, ..., D8 [, /NOZERO] ) Arguments Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. 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) See Also COMPLEXARR, DBLARR, FLTARR, INTARR, LON64ARR, LONARR, MAKE_ARRAY, STRARR, UINTARR, ULON64ARR, ULONARR BYTE [Previous Routine] [Next Routine] [List of Routines] NAME: 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 "Type Conversion Functions" on page 49 for details. Syntax Result = BYTE( Expression[, Offset [, Dim1, ..., Dim8]] ) Arguments Expression The expression to be converted to type byte. Offset The byte offset from the beginning of Expression. Specifying this argument allows fields of data extracted from Expression to be treated as byte data without conversion. Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. 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 arguments 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) See Also COMPLEX, DCOMPLEX, DOUBLE, FIX, FLOAT, LONG, LONG64, STRING, UINT, ULONG, ULONG64 BYTEORDER [Previous Routine] [Next Routine] [List of Routines] NAME: 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 routine 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 expression or constant, and may not contain strings. The contents of Variable are overwritten by the result. Network byte ordering is "big endian". That is, multiple byte integers are stored in memory beginning with the most significant byte. Syntax BYTEORDER, Variable1, ..., Variablen [, /DTOVAX] [, /DTOXDR] [, /FTOVAX] [, /FTOXDR] [, /HTONL] [, /HTONS] [, /L64SWAP] [, /LSWAP] [, /NTOHL] [, /NTOHS] [, /SSWAP] [, /SWAP_IF_BIG_ENDIAN] [, /SWAP_IF_LITTLE_ENDIAN] [, /VAXTOD] [, /VAXTOF] [, /XDRTOD] [, /XDRTOF] VMS keywords: [, /DTOGFLOAT] [, /GFLOATTOD] 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 DTOVAX Set this keyword to convert native (IEEE) double-precision floating-point format to VAX D float format. See "Note On IEEE to VAX Format Conversion" on page 136. DTOXDR Set this keyword to convert native double-precision floating-point format to XDR (IEEE) format. FTOVAX Set this keyword to convert native (IEEE) single-precision floating-point format to VAX F float format. See "Note On IEEE to VAX Format Conversion" on page 136. FTOXDR Set this keyword to convert native single-precision floating-point format to XDR (IEEE) format. HTONL Set this keyword to perform host to network conversion, longwords. HTONS Set this keyword to perform host to network conversion, short integers. L64SWAP Set this keyword to perform a 64-bit swap (8 bytes). Swap the order of the bytes within each 64-bit word. For example, the eight bytes within a 64-bit word are changed from (B0, B1, B2, B3 B4, B5, B6, B7), to (B7, B6, B5, B4, B3, B2, B1, B0). LSWAP Set this keyword to perform a 32-bit 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 conversion, longwords. NTOHS Set this keyword to perform network to host conversion, 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. SWAP_IF_BIG_ENDIAN If this keyword is set, the BYTEORDER request will only be performed if the platform running IDL uses "big endian" byte ordering. On little endian machines, the BYTEORDER request quietly returns without doing anything. Note that this keyword does not refer to the byte ordering of the input data, but to the computer hardware. SWAP_IF_LITTLE_ENDIAN If this keyword is set, the BYTEORDER request will only be performed if the platform running IDL uses "little endian" byte ordering. On big endian machines, the BYTEORDER request quietly returns without doing anything. Note that this keyword does not refer to the byte ordering of the input data, but to the computer hardware. VAXTOD Set this keyword to convert VAX D float format to native (IEEE) double-precision floating-point format. See "Note On IEEE to VAX Format Conversion" on page 136. Note If you have VAX G float format data, see the "VMS-Only Keywords" on page 135. VAXTOF Set this keyword to convert VAX F float format to native (IEEE) single-precision floating-point format. See "Note On IEEE to VAX Format Conversion" on page 136. Note If you have VAX G float format data, see the "VMS-Only Keywords" on page 135. XDRTOD Set this keyword to convert XDR (IEEE) format to native double-precision floating- point. XDRTOF Set this keyword to convert XDR (IEEE) format to native single-precision floating- point. VMS-Only Keywords DTOGFLOAT Set this keyword to convert native (IEEE) double-precision floating-point format to VAX G float format. Note that IDL does not support the VAX G float format via any other mechanism. See "Note On IEEE to VAX Format Conversion" on page 136. GFLOATTOD Set this keyword to convert VAX G float format to native (IEEE) double-precision floating-point format. Note that IDL does not support the VAX G float format via any other mechanism. Note On IEEE to VAX Format Conversion Translation of floating-point values from the IDL's native (IEEE) format to the VAX formats and back (IEEE to VAX to IEEE) is not a completely reversible operation, and should be avoided when possible. There are many cases where the recovered values will differ from the original, including: * The VAX floating point format lacks support for the IEEE special values (NaN, Infinity). Hence, their special meaning is lost when they are converted to VAX format and cannot be recovered. * Differences in precision and range can also cause information to be lost in both directions. Research Systems recommends using IEEE/VAX conversions only to read existing VAX format data, and strongly recommends that all new files be created using the IEEE format. See Also SWAP_ENDIAN BYTSCL [Previous Routine] [Next Routine] [List of Routines] NAME: BYTSCL The BYTSCL function scales all values of Array that lie in the range (Min x Max) into the range (0 x Top). The returned result has the same structure as the original parameter and is of byte type. Syntax Result = BYTSCL( Array [, MAX=value] [, MIN=value] [, /NAN] [, TOP=value] ) Arguments Array The array to be scaled and converted to bytes. Keywords MAX Set this keyword to the maximum value of Array to be considered. If MAX is not provided, Array is searched for its maximum value. All values greater or equal to MAX are set equal to TOP in the result. Note The data type of the value specified for MAX should match the data type of the input array. Since MAX is converted to the data type of the input array, specifying mismatched data types may produce undesired results. MIN Set this keyword to the minimum value of Array to be considered. If MIN is not provided, Array is searched for its minimum value. All values less than or equal to MIN are set equal to 0 in the result. Note The data type of the value specified for MIN should match the data type of the input array. Since MIN is converted to the data type of the input array, specifying mismatched data types may produce undesired results. NAN Set this keyword to cause the routine to check for occurrences of the IEEE floating- point value NaN in the input data. Elements with the value NaN are treated as missing data. (See "Special Floating-Point Values" on page 434 for more information on IEEE floating-point values.) TOP Set this keyword to 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 appropriate range for 8-bit displays. As an example, enter the following commands: ; Create a simple image array: IM = DIST(200) ; Display the array as an image: TV, IM ; Scale the image into the full range of bytes (0 to 255) and ; re-display it: IM = BYTSCL(IM) ; Display the new image: TV, IM See Also BYTE, TVSCL C_CORRELATE [Previous Routine] [Next Routine] [List of Routines] NAME: C_CORRELATE The C_CORRELATE function computes the cross correlation Pxy(L) or cross covariance Rxy(L) of two sample populations X and Y as a function of the lag L N ­ L ­ 1 (x k+L ­ x)(yk ­ y) k = 0 -------------------------------------------------------------------------------- For L < 0 N ­ 1 N ­ 1 (x k ­ x)2 (y k ­ y)2 k = 0 k = 0 Pxy(L) = N­L­1 (x k ­ x)(yk+L ­ y) k = 0 ---------------------------------- For L 0 N ­ 1 N ­ 1 (x k ­ x)2 (y k ­ y)2 k = 0 k = 0 1N­L­1 ---- N (x k+L ­ x)(yk ­ y) For L < 0 R k = 0 xy(L) = 1N­L­1 ---- N (x k ­ x)(yk+L ­ y) For L 0 k = 0 where x and y are the means of the sample populations x = (x0, x1, x2, ... , xN-1) and y = (y0, y1, y2, ... , yN-1), respectively. This routine is written in the IDL language. Its source code can be found in the file c_correlate.pro in the lib subdirectory of the IDL distribution. Syntax Result = C_CORRELATE( X, Y, Lag [, /COVARIANCE] [, /DOUBLE] ) Arguments X An n-element integer, single-, or double-precision floating-point vector. Y An n-element integer, single-, or double-precision floating-point vector. Lag A scalar or n-element integer vector in the interval [-(n-2), (n-2)], specifying the signed distances between indexed elements of X. Keywords COVARIANCE Set this keyword to compute the sample cross covariance rather than the sample cross correlation. DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. Example ; Define two n-element sample populations: X = [3.73, 3.67, 3.77, 3.83, 4.67, 5.87, 6.70, 6.97, 6.40, 5.57] Y = [2.31, 2.76, 3.02, 3.13, 3.72, 3.88, 3.97, 4.39, 4.34, 3.95] ; Compute the cross correlation of X and Y for LAG = -5, 0, 1, 5, ; 6, 7: lag = [-5, 0, 1, 5, 6, 7] result = C_CORRELATE(X, Y, lag) PRINT, result IDL prints: -0.428246 0.914755 0.674547 -0.405140 -0.403100 -0.339685 See Also A_CORRELATE, CORRELATE, M_CORRELATE, P_CORRELATE, R_CORRELATE CALDAT [Previous Routine] [Next Routine] [List of Routines] NAME: CALDAT The CALDAT procedure computes the month, day, year, hour, minute, or second corresponding to a given Julian date. The inverse of this procedure is JULDAY. Note The Julian calendar, established by Julius Caesar in the year 45 BCE, was corrected by Pope Gregory XIII in 1582, excising ten days from the calendar. The CALDAT procedure reflects the adjustment for dates after October 4, 1582. See the example below for an illustration. This routine is written in the IDL language. Its source code can be found in the file caldat.pro in the lib subdirectory of the IDL distribution. Syntax CALDAT, Julian, Month [, Day [, Year [, Hour [, Minute [, Second]]]]] Arguments Julian A numeric value or array that specifies the Julian Day Number (which begins at noon) to be converted to a calendar date. Note Julian values must be in the range -1095 to 1827933925, which corresponds to calendar dates 1 Jan 4716 B.C.E. and 31 Dec 5000000, respectively. Month A named variable that, on output, contains the number of the desired month (1 = January, ..., 12 = December). Day A named variable that, on output, contains the number of the day of the month (1-31). Year A named variable that, on output, contains the number of the desired year (e.g., 1994). Hour A named variable that, on output, contains the number of the hour of the day (0-23). Minute A named variable that, on output, contains the number of the minute of the hour (0-59). Second A named variable that, on output, contains the number of the second of the minute (0-59). Examples In 1582, Pope Gregory XIII adjusted the Julian calendar to correct for its inaccuracy of slightly more than 11 minutes per year. As a result, the day following October 4, 1582 was October 15, 1582. CALDAT follows this convention, as illustrated by the following commands: CALDAT, 2299160, Month, Day, Year PRINT, Month, Day, Year IDL prints: 10 4 1582 Warning You should be aware of this discrepancy between the original and revised Julian calendar reckonings if you calculate dates before October 15, 1582. Be sure to distinguish between Month and Minute when assigning variable names. For example, the following code would cause the Minute value to be the same as the Month value: ;Find date corresponding to Julian day 2529161.36: CALDAT, 2529161.36, M, D, Y, H, M, S PRINT, M, D, Y, H, M, S IDL prints: 7 4 2212 18 7 0.00000000 Instead, use something like: CALDAT, 2529161.36, Month, Day, Year, Hour, Minute, Second PRINT, Month, Day, Year, Hour, Minute, Second You can use arrays for the Julian argument: CALDAT,FINDGEN(4)+2449587L, m, d, y PRINT, m, d, y IDL prints: 8 8 8 8 22 23 24 25 1994 1994 1994 1994 See Also BIN_DATE, JULDAY, SYSTIME CALENDAR [Previous Routine] [Next Routine] [List of Routines] NAME: CALENDAR The CALENDAR procedure displays a calendar for a month or an entire year on the current plotting device. This IDL routine imitates the UNIX cal command. This routine is written in the IDL language. Its source code can be found in the file calendar.pro in the lib subdirectory of the IDL distribution. Syntax CALENDAR [[, Month] , Year] Arguments Month The number of the month for which a calendar is desired (1 is January, 2 is February, ..., 12 is December). If called without arguments, CALENDAR draws a calendar for the current month. Year The number of the year for which a calendar should be drawn. If YEAR is provided without MONTH, a calendar for the entire year is drawn. If called without arguments, CALENDAR draws a calendar for the current month. Example ; Display a calendar for May, 1995. CALENDAR, 5, 1995 See Also SYSTIME CALL_EXTERNAL [Previous Routine] [Next Routine] [List of Routines] NAME: 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 7, "CALL_EXTERNAL" in the External Development Guide for examples. CALL_EXTERNAL is supported under all operating systems supported by IDL, although there are system specific details of which you must be aware. This function requires no interface routines and is much simpler and easier to use than the LINKIMAGE procedure. 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. Warning Input and output actions should be performed within IDL code, using IDL's built-in input/output facilities, or by using the internal IDL_Message() function. Performing input or output from external code, especially to the user console or tty (e.g. using printf() or equivalent functionality in other languages to send text to stdout) may create errors or generate unexpected results. CALL_EXTERNAL supports the IDL Portable Convention, a portable calling convention that works on all platforms. This convention passes two arguments to the called routine, an argument count (argc) and an array of arguments (argv). On non- VMS systems, this is the only available convention. Under VMS, the VMS LIB$CALLG convention is also available. This convention, which is the default under VMS, uses the VMS LIB$CALLG runtime library routine to call functions without requiring a special (argc, argv) convention. On UNIX, VMS, and Windows platforms, but not the Macintosh, CALL_EXTERNAL also offers a feature called Auto Glue that can greatly simplify use of the CALL_EXTERNAL portable convention if you have the appropriate C compiler installed on your system. Auto glue automatically writes the glue function required to convert the (argc, argv) arguments to the actual function call, and then compiles and loads the glue function transparently. If you want IDL to simply write the glue function for you, but not compile it, the WRITE_WRAPPER keyword can be used. The result of the CALL_EXTERNAL function is a scalar value returned by the external function. By default, this is a scalar long (32-bit) integer. This default can be changed by specifying one of the keywords described below that alter the result type. Syntax Result = CALL_EXTERNAL(Image, Entry [, P0, ..., PN-1] [, /ALL_VALUE] [, /B_VALUE | , /D_VALUE | , /F_VALUE | , /I_VALUE | , /L64_VALUE | , /S_VALUE | , /UI_VALUE | , /UL_VALUE | , /UL64_VALUE] [, /CDECL] [, RETURN_TYPE=value] [, /UNLOAD] [, VALUE=byte_array] [, WRITE_WRAPPER=wrapper_file] ) VMS keywords: [, DEFAULT=string] [, /PORTABLE] [, /VAX_FLOAT] Auto Glue keywords: [, /AUTOGLUE] [, CC=string] [, COMPILE_DIRECTORY=string] [, EXTRA_CFLAGS=string] [, EXTRA_LFLAGS=string] [, /IGNORE_EXISTING_GLUE] [, LD=string] [, /NOCLEANUP] [, /SHOW_ALL_OUTPUT] [, /VERBOSE] Arguments Image The name of the file, which must be a sharable image (VMS), sharable library (UNIX and Macintosh), or DLL (Windows), which contains the routine to be called. Under VMS the full interpretation of this argument is discussed in "VMS CALL_EXTERNAL and LIB$FIND_IMAGE_SYMBOL" on page 156. Entry A string containing the name of the symbol in the library which is the entry point of the routine to be called. P0, ..., PN-1 The parameters to be passed to the external routine. All array and structure arguments are passed by reference (address). The default is to also pass scalars by reference, but the ALL_VALUE or VALUE keywords can be used to pass them 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. There are some restrictions on data types that can be passed by value, and the user needs to be aware of how IDL passes strings. Both issues discussed in further detail below. Keywords ALL_VALUE Set this keyword to indicate that all parameters are passed by value. There are some restrictions on data types that should be considered when using this keyword, as discussed below. B_VALUE If set, this keyword indicates that the called function returns a byte value. CDECL The Microsoft Windows operating system has two distinct system defined standards that govern how routines pass arguments: stdcall, which is used by much of the operating system as well as languages such as Visual Basic, and cdecl, which is used widely for programming in the C language. These standards differ in how and when arguments are pushed and removed from the system stack. The standard used by a given function is determined when the function is compiled, and can usually be controlled by the programmer. If you call a function using the wrong standard (e.g. calling a stdcall function as if it were cdecl, or the reverse), you could get incorrect results, corrupted memory, or you could crash IDL. Unfortunately, there is no way for IDL to know which convention a given function uses; this information must be supplied by the user of CALL_EXTERNAL. If the CDECL keyword is present, IDL will use the cdecl convention to call the function. Otherwise, stdcall is used. DEFAULT This keyword is ignored on non-VMS platforms. Under VMS, it is a string containing the default device, directory, file name, and file type information for the file that contains the sharable image. See "VMS CALL_EXTERNAL and LIB$FIND_IMAGE_SYMBOL" on page 156 for additional information. D_VALUE If set, this keyword indicates that the called function returns a double-precision floating value. F_VALUE If set, this keyword indicates that the called function returns a single-precision floating value. I_VALUE If set, this keyword indicates that the called function returns an integer value. L64_VALUE If set, this keyword indicates that the called function returns a 64-bit integer value. PORTABLE Under VMS, causes CALL_EXTERNAL to use the IDL Portable calling convention for passing arguments to the called function instead of the default VMS LIB$CALLG convention. Under other operating systems, only the portable convention is available, so this keyword is quietly ignored. The details of these calling conventions are described in "Calling Convention" on page 152. If you are using the IDL Portable calling convention, the AUTO_GLUE or WRITE_WRAPPER keywords are available to simplify the task of matching the form in which IDL passes the arguments to the interface of your target function. RETURN_TYPE The type code to set the type of the result. See the description of the SIZE function for a list of the IDL type codes. S_VALUE If set, this keyword indicates that the called function returns a pointer to a null-terminated string. UI_VALUE If set, this keyword indicates that the called function returns an unsigned integer value. UL_VALUE If set, this keyword indicates that the called function returns an unsigned long integer value. UL64_VALUE If set, this keyword indicates that the called function returns an unsigned 64-bit integer value. UNLOAD Normally, IDL keeps Image loaded in memory after the call to CALL_EXTERNAL completes. This is done for efficiency-loading a sharable object can be a slow operation. Setting the UNLOAD keyword will cause IDL to unload Image after the call to it is complete. This is useful if you are debugging code in Image, as it allows you to iterate on your code without having to exit IDL between tests. It can also be a good idea if you do not intend to make any subsequent calls to routines within Image. If IDL is unable to unload the sharable object, it will issue an error to that effect. In addition to any operating system reported problem that might occur, there are 2 situations in which IDL cannot perform the UNLOAD operation: * If the sharable library has been used for any other purpose in addition to CALL_EXTERNAL (e.g. LINKIMAGE). * The VMS operating system does not offer a mechanism for unloading sharable objects from a running program. Use of the UNLOAD keyword under VMS will therefore cause an error to be issued. VALUE A byte array, with as many elements as there are optional parameters, indicating the method of parameter passing. Arrays are always passed by reference. If parameter Pi is a scalar, it is passed by reference if VALUE[i] is 0; and by value if it is non-zero. There are some restrictions on data types that should be considered when using this keyword, as discussed below. VAX_FLOAT (VMS Only) If specified, all data passed to the called function is first converted to VAX F (single) or D (double) floating point formats. On return, any data passed by reference is converted back to the IEEE format used by IDL. This feature allow you to call code compiled to work with earlier versions of IDL, which used the old VAX formats. The default setting for this keyword is FALSE, unless IDL was started with the VAX_FLOAT startup option, in which case the default is TRUE. See "Command Line Options" in Chapter 4 of Using IDL for details on this qualifier. You can change this setting at runtime using the VAX_FLOAT function. WRITE_WRAPPER If set, WRITE_WRAPPER supplies the name of a file for CALL_EXTERNAL to create containing the C function required to convert the (argc, argv) interface used by the CALL_EXTERNAL portable calling convention to the interface of the target function. If WRITE_WRAPPER is specified, CALL_EXTERNAL writes the specified file, but does not attempt to actually call the function specified by Entry. The result from CALL_EXTERNAL is an integer 0 in this case, and has no special meaning. Use of WRITE_WRAPPER implies the PORTABLE keyword. Note This is similar to Auto Glue only in that CALL_EXTERNAL writes a function on your behalf. Unlike auto glue, WRITE_WRAPPER does not attempt to compile the resulting function or to use it. You might want to use WRITE_WRAPPER to generate IDL interfaces for an external library in cases where you intend to combine the interfaces with other code or otherwise modify it before using it with IDL. Auto Glue Keywords (UNIX, VMS, and Windows) Auto Glue, discussed in the section "Auto Glue" on page 153, offers a simplified way to use the CALL_EXTERNAL portable calling convention. The following keywords control its use. Many of these keywords correspond to the same keywords to the MAKE_DLL procedure, and are covered in more detail in the documentation for that routine. AUTO_GLUE Set this keyword to enable the CALL_EXTERNAL Auto Glue feature. Use of AUTO_GLUE implies the PORTABLE keyword. CC If present, a template string to be used in generating the C compiler command(s) to compile the automatically generated glue function. For a more complete description of this keyword, see MAKE_DLL. COMPILE_DIRECTORY Specifies the directory to use for creating the necessary intermediate files and the final glue function sharable library. For a more complete description of this keyword, see MAKE_DLL. EXTRA_CFLAGS If present, a string supplying extra options to the command used to execute the C compiler. For a more complete description of this keyword, see MAKE_DLL. EXTRA_LFLAGS If present, a string supplying extra options to the command used to execute the linker. For a more complete description of this keyword, see MAKE_DLL. IGNORE_EXISTING_GLUE Normally, if Auto Glue finds a pre-existing glue function, it will use it without attempting to build it again. Set IGNORE_EXISTING_GLUE to override this caching behavior and force CALL_EXTERNAL to rebuild the glue function sharable library. LD If present, a template string to be used in generating the linker command to build the glue function sharable library. For a more complete description of this keyword, see MAKE_DLL. NOCLEANUP If set, CALL_EXTERNAL will not remove intermediate files generated in order to build the glue function sharable library after the library has been built. This keyword can be used to preserve information for debugging in case of error, or for additional information on how Auto Glue works. For a more complete description of this keyword, see MAKE_DLL. SHOW_ALL_OUTPUT Auto Glue normally produces no output unless an error prevents successful building of the glue function sharable library. Set SHOW_ALL_OUTPUT to see all output produced by the process of building the library. For a more complete description of this keyword, see MAKE_DLL. VERBOSE If set, VERBOSE causes CALL_EXTERNAL to issue informational messages as it carries out the task of locating, building, and executing the glue function. For a more complete description of this keyword, see MAKE_DLL. Note On IEEE to VAX Format Conversion Translation of floating-point values from the IDL's native (IEEE) format to the VAX format and back (IEEE to VAX to IEEE) is not a completely reversible operation, and should be avoided when possible. There are many cases where the recovered values will differ from the original, including: * The VAX floating point format lacks support for the IEEE special values (NaN, Infinity). Hence, their special meaning is lost when they are converted to VAX format and cannot be recovered. * Differences in precision and range can also cause information to be lost in both directions. Research Systems recommends using IEEE/VAX conversions only to read existing VAX format data, and strongly recommends that all new files be created using the IEEE format. String Parameters IDL represents strings internally as IDL_STRING descriptors, which are defined in the C language as: typedef struct { unsigned short slen; unsigned short stype; char *s; } IDL_STRING; To pass a string by reference, IDL passes the address of its IDL_STRING descriptor. To pass a string by value the string pointer (the s field of the descriptor) is passed. Programmers should be aware of the following when manipulating IDL strings: * Called code should treat the information in the passed IDL_STRING descriptor and the string itself as read-only, and should not modify these values. * The slen field contains the length of the string without including the NULL termination that is required at the end of all C strings. * The stype field is used internally by IDL to know keep track of how the memory for the string was obtained, and should be ignored by CALL_EXTERNAL users. * s is the pointer to the actual C string represented by the descriptor. If the string is NULL, IDL represents it as a NULL (0) pointer, not as a pointer to an empty null terminated string. Hence, called code that expects a string pointer should check for a NULL pointer before dereferencing it. These issues are examined in greater detail in the IDL External Development Guide. Calling Convention CALL_EXTERNAL supports two distinct calling conventions for calling user- supplied routines. The primary convention is the IDL Portable convention, which is supported on all platforms. The second is the VMS LIB$CALLG convention which is only available under VMS. Portable The portable interface convention passes all arguments as elements of an array of C void pointers (void *). The C language prototype for a user function called this way looks like one of the following: RET_TYPE xxx(int argc, void *argv[]) Where RET_TYPE is one of the following: UCHAR, short, IDL_UINT, IDL_LONG, IDL_ULONG, IDL_LONG64, IDL_ULONG64, float, double, or char *. The return type used must agree with the type assumed by CALL_EXTERNAL as specified via the keywords described above. Argc is the number of arguments, and the vector argv contains the arguments themselves, one argument per element. Arguments passed by reference map directly to these (void *) pointers, and can be cast to the proper type and then dereferenced directly by the called function. Passing arguments by value is allowed, but since the values are passed in (void *) pointers, there are some limitations and restrictions on what is possible: * Types that are larger than a pointer cannot be passed by value, and CALL_EXTERNAL will issue an error if this is attempted. This limitation applies only to the standard portable calling convention. Auto Glue does not have this limitation, and is able to pass such variables by value. * Integer values can be easily passed by value. IDL widens any of the integer types to the C int type and they are then converted to a (void *) pointer using a C cast operation. * There is no C language-defined conversion between pointers and floating point types, so IDL copies the data for the value directly into the pointer element. Although such values can be retrieved by the called routine with the correct C casting operations, this is inconvenient and error prone. It is best to pass non- integer data by reference. Auto Glue Auto Glue is an extension to the IDL Portable Calling Convention that makes it easier to use. It is supported under UNIX, VMS, and Microsoft Windows, but not on the Macintosh at this time. The portable calling convention requires your function to use the IDL defined (argc, argv) interface for passing arguments. However, functions not explicitly written for use with CALL_EXTERNAL do not have this interface. VMS users can solve this problem by using the LIB$CALLG calling convention described in the following section, but that method only works under VMS and has other limitations as well. A common solution using the portable convention is for the IDL user to write a glue function that interfaces between IDL and the actual function. The entire purpose of this glue function, which is usually very simple, is to convert the IDL (argc, argv) method of passing parameters to a form acceptable to the desired function. Writing this wrapper function is easy for programmers that understand the C language, the system C compiler and linker, and how sharable libraries work on their target operating system. However, it is also tedious and error prone, and can be difficult for users that do not already have these skills. Auto Glue uses the MAKE_DLL procedure to automate the process of using glue code to call functions via the CALL_EXTERNAL portable calling convention. Since it depends so closely on MAKE_DLL, an understanding of how MAKE_DLL works is necessary to fully understand Auto Glue. As with MAKE_DLL, Auto Glue requires that your system have a suitable C compiler installed. Please refer to the documentation for MAKE_DLL. Auto Glue maintains a cache of previously built glue functions, and will reuse them on subsequent requests, even between IDL sessions. The process works as follows: * CALL_EXTERNAL finds a suitable glue function by performing the following steps in order, stopping after the first one that works. Glue function libraries can be recognized by their name, which starts with the prefix idl_ce, and end with the proper suffix for a sharable library on the target system (most UNIX: .so, AIX: .a, HP-UX: .sl, VMS: .exe, Windows: .dll). 1. Look for a ce_glue subdirectory within the IDL distribution bin subdirectory for the current platform. If this directory exists, it looks there for a sharable library containing the appropriate glue function. Note For customer security reasons, the ce_glue subdirectory does not exist in the IDL distribution as shipped by RSI, and IDL does not use it to create glue functions. However, if an individual site creates this directory and places glue library files within it, IDL will use them. Multiple IDL sessions on a given system can all share these same glue files, even when run by different users on a multi-user system. If you keep your IDL distribution on a network based file server shared by multiple clients, and if you provide a sufficient selection of glue files, it is possible that your users will not require a locally installed C compiler to use Auto Glue. If you do create the ce_glue subdirectory on a multi-user system, we recommend that you make it along with all files contained within belong to the owner of the IDL distribution, and apply file protections that prevent non- privileged users from creating files in the directory or modifying them. 2. Look in the directory given by the COMPILE_DIRECTORY keyword, or if COMPILE_DIRECTORY is not present, in the directory given by the !MAKE_DLL.COMPILE_DIRECTORY system variable for the appropriate glue function. 3. If this step is reached, there is no pre-existing glue function available. CALL_EXTERNAL will create one in the same directory searched in the previous step by generating a C language file containing the needed glue function, and then compiling and linking it into a sharable library using the functionality of the MAKE_DLL procedure. * IDL loads the sharable library containing the glue function found in the previous step, as well as the library you specified with the Image argument. * CALL_EXTERNAL calls the glue function, causing your function to be called with the correct parameters. The first time CALL_EXTERNAL encounters the need for a glue function that does not already exist, it will automatically build it, and then use it without any external indication that this has happened. You may notice a brief hesitation in IDL's execution as it waits for this process to occur. Once a glue function exists, IDL can load it immediately on subsequent calls (even in unrelated later IDL sessions), and no delay will occur. Example: Using Auto Glue To Call System Library Routines Under Sun Solaris, there is a function in the system math library called hypot() that computes the length of the hypotenuse of a right-angled triangle: sqrt(x*x + y*y) This function has the C prototype: double hypot(double x, double y) The following IDL function uses Auto Glue to call this routine: FUNCTION HYPOT, X, Y ; Use the 32-bit or the 64-bit math library? LIBM=(!VERSION.MEMORY_BITS EQ 64) $ ? '/usr/lib/sparcv9/libm.so' : '/usr/lib/libm.so' RETURN, CALL_EXTERNAL(LIBM, 'hypot', double(x), double(y), $ /ALL_VALUE, /D_VALUE, /AUTO_GLUE) END VMS LIB$CALLG The LIB$CALLG calling convention is built directly upon the VMS LIB$CALLG runtime library function. This function allows calling functions with a natural interface without requiring a special (argc, argv) convention. In FORTRAN, a typical routine might be declared: INTEGER *4 FUNCTION XXX(P1, P2, ..., PN) As with the Portable convention described above, the return type for the function must be one of the following types: UCHAR, short, IDL_UINT, IDL_LONG, IDL_ULONG, IDL_LONG64, IDL_ULONG64, float, double, or char *. It is possible to pass arguments of any data type by reference, but there are some limitations and restrictions on passing arguments by value. Unfortunately, the interface to LIB$CALLG was designed explicitly for the VAX hardware architecture, and does not provide sufficient information to the operating system to pass all data types by value properly on ALPHA Risc CPUs which pass arguments in registers as well as on the system stack. To the best of our knowledge, Compaq (formerly Digital Equipment Corporation) has no plans to supply an updated version of LIB$CALLG that does not have these limitations. Therefore, this calling convention has the following restrictions on ALPHA/VMS: * A single or double-precision floating-point argument can only be passed by value if it is one of the first six arguments to the function. * Single- and double-precision complex arguments cannot be passed by value. The LIB$CALLG calling convention is the default for VMS IDL because it was the original convention supported on that platform, and because it allows calling routines that do not adhere to the (argc, argv) style interface required by the portable convention. The Portable convention, described above, can be used under VMS by setting the PORTABLE keyword. If you are writing external code to be used under operating systems other than VMS, using the portable interface simplifies cross platform development. VMS CALL_EXTERNAL and LIB$FIND_IMAGE_SYMBOL The VMS implementation of CALL_EXTERNAL uses the system runtime library function LIB$FIND_IMAGE_SYMBOL to perform the dynamic linking. This function has a complicated interface in which the name of the library to be linked is given in two separate arguments. We encourage VMS users wishing to use CALL_EXTERNAL to read and fully understand the documentation for LIB$FIND_IMAGE_SYMBOL in order to understand how it is used by IDL. The following discussion assumes that you have a copy of the LIB$FIND_IMAGE_SYMBOL documentation available to consult as you read. LIB$FIND_IMAGE_SYMBOL uses an argument called filename to specify the name of the sharable library or executable to be loaded. This means that none of the file specification punctuation characters (:, [, <, ;, .) are allowed. Filename can also be a logical name, in which case its translated value is the name of the file to be loaded. The translation of such a logical name is allowed to contain additional file specification information. VMS uses this information to find the file to load, using SYS$SHARE as the default location if a location is not specified via a logical name. Alternatively, the user can supply the image-name argument, which is used as a default file specification to fill in the parts of the file specification not contained in filename. IDL uses the following rules, in the order listed, to determine how to call LIB$FIND_IMAGE_SYMBOL: 1. If CALL_EXTERNAL is called with both the Image argument and DEFAULT keyword, Image is passed to LIB$FIND_IMAGE_SYMBOL as filename, and DEFAULT is passed as image-name. Both are passed directly to the function without any interpretation. 2. If DEFAULT is not present and Image does not contain a file specification character (:, [, <, ;, .) then it is passed to LIB$CALL_IMAGE_SYMBOL as it's filename argument without any further interpretation. 3. If DEFAULT is not present and Image contains a file specification character, then IDL examines it and locates the filename part. The filename part is passed to LIB$FIND_IMAGE_SYMBOL as filename and the entire string from Image is passed as image-name. This means that although LIB$CALL_IMAGE_SYMBOL has a complicated interface, the CALL_EXTERNAL user can supply a simple file specification for Image and it will be properly loaded by IDL. Full control of LIB$CALL_IMAGE_SYMBOL is still available for those who require it. Important Changes Since IDL 5.0 The current version of CALL_EXTERNAL differs from IDL versions up to and including IDL 5.0 in a few ways that are important to users moving code to the current version: * Under Windows, CALL_EXTERNAL would pass IDL strings by value no matter how the ALL_VALUE or VALUE keywords were set. This was inconsistent with all the other platforms and created unnecessary confusion. IDL now uses these keywords to decide how to pass strings on all platforms. Windows users with existing code that expects strings to be passed by value without having specified it via one of these keywords will need to adjust their use of CALL_EXTERNAL or their code. * VMS IDL through version 5.0 was only capable of using the LIB$CALLG calling convention. Newer versions can also use the portable convention. * Older versions of IDL would quietly pass by value arguments that are larger than a pointer without issuing an error when using the portable calling convention. Although this might work on some hardware, it is error prone and can cause IDL to crash. IDL now issues an error in this case. Programmers with existing code moving to a current version of IDL should change their code to pass such data by reference. Example See Chapter 7, "CALL_EXTERNAL" in the External Development Guide. See Also LINKIMAGE, VAX_FLOAT CALL_FUNCTION [Previous Routine] [Next Routine] [List of Routines] NAME: 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. Syntax 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 runtime. Pi The arguments to be passed to the function given by Name. These arguments are the positional and keyword 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 function SQRT (the square root function) with an argument of 4 and stores the result in the variable R: R = CALL_FUNCTION('SQRT', 4) See Also CALL_PROCEDURE, CALL_METHOD, EXECUTE CALL_METHOD [Previous Routine] [Next Routine] [List of Routines] NAME: CALL_METHOD CALL_METHOD calls the object method specified by Name, passing any additional parameters as its arguments. CALL_METHOD can be used as either a function or a procedure, depending on whether the called method is a function or procedure. Although not as flexible as the EXECUTE function, CALL_METHOD is much faster. Therefore, CALL_METHOD should be used in preference to EXECUTE whenever possible. Syntax CALL_METHOD, Name, ObjRef, [, P1, ..., Pn] or Result = CALL_METHOD(Name, ObjRef, [, P1, ..., Pn]) Arguments Name A string containing the name of the method to be called. This argument can be a variable, which allows the called method to be determined at runtime. ObjRef A scalar object reference that will be passed to the method as the Self argument. Pi The arguments to be passed to the method given by Name. These arguments are the positional and keyword arguments documented for the called method, and are passed to the called method exactly as if it had been called directly. See Also CALL_FUNCTION, CALL_PROCEDURE, EXECUTE CALL_PROCEDURE [Previous Routine] [Next Routine] [List of Routines] NAME: 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. Syntax 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 procedure, 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 procedure indirectly with a number of arguments. First, create a dataset for plotting by entering: B = FINDGEN(100) Call PLOT indirectly to create a polar plot by entering: CALL_PROCEDURE, 'PLOT', B, B, /POLAR A "spiral" plot should appear. See Also CALL_FUNCTION, CALL_METHOD, EXECUTE CASE [Previous Routine] [Next Routine] [List of Routines] NAME: CASE The CASE statement selects one, and only one, statement for execution, depending on the value of an expression. This expression is called the case selector expression. Each statement that is part of a CASE statement is preceded by an expression that is compared to the value of the selector expression. CASE executes by comparing the CASE expression with each selector expression in the order written. If a match is found, the statement is executed and control resumes directly below the CASE statement. The ELSE clause of the CASE statement is optional. If included, it matches any selector expression, causing its code to be executed. For this reason, it is usually written as the last clause in the CASE statement. The ELSE statement is executed only if none of the preceding statement expressions match. If an ELSE clause is not included and none of the values match the selector, an error occurs and program execution stops. The BREAK statement can be used within CASE statements to force an immediate exit from the CASE. In this CASE statement, only one clause is selected, and that clause is the first one whose value is equal to the value of the case selector expression. Tip Each clause is tested in order, so it is most efficient to order the most frequently selected clauses first. CASE is similar to the SWITCH statement. For more information on using CASE and other IDL program control statements, as well as the differences between CASE and SWITCH, see Chapter 11, "Program Control" in Building IDL Applications. Syntax CASE expression OF expression: statement ... expression: statement [ ELSE: statement ] ENDCASE Example This example illustrates how the CASE statement, unlike SWITCH, executes only the one statement that matches the case expression: x=2 CASE x OF 1: PRINT, 'one' 2: PRINT, 'two' 3: PRINT, 'three' 4: PRINT, 'four' ENDCASE IDL Prints: two CATCH [Previous Routine] [Next Routine] [List of Routines] NAME: 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, beginning 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_STATE system variable is also set. If no error handlers are found, program execution stops, an error message 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 facilities in C++. Error handling is discussed in more detail in Chapter 17, "Controlling Errors" in Building IDL Applications. Syntax CATCH, Variable [, /CANCEL] 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 control is transferred to the statement after the call to CATCH. The error index is also returned in the CODE field of the !ERROR_STATE system variable, i.e., !ERROR_STATE.CODE. 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 CATCH_EXAMPLE ; Define variable A: A = FLTARR(10) ; Establish error handler. When errors occur, the index of the ; error is returned in the variable Error_status: CATCH, Error_status ;This statement begins the error handler: IF Error_status NE 0 THEN BEGIN PRINT, 'Error index: ', Error_status PRINT, 'Error message: ', !ERROR_STATE.MSG ; Handle the error by extending A: A=FLTARR(12) ENDIF ; Cause an error: A[11]=12 ; 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. HELP, A END Running the ABC procedure causes IDL to produce the following output and control returns to the interactive prompt: Error index: -144 Error message: Attempt to subscript A with is out of range. A FLOAT = Array[12] See Also !ERROR_STATE, ON_ERROR, ON_IOERROR CD [Previous Routine] [Next Routine] [List of Routines] NAME: CD The CD procedure is used to set and/or change the current 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 procedures provide a convenient interface to CD. Syntax CD [, Directory] [, CURRENT=variable] 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 (UNIX and VMS) or to the directory specified by !DIR (Windows and Macintosh). If this argument is not specified, 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 Note On Windows and UNIX, the return value of the CURRENT keyword does not include a directory separator at the end of the string. On Macintosh, the return value of the CURRENT keyword includes an appended `:' character on the end of the string, and on VMS, the return value of the CURRENT keyword includes an appended `]' character on the end of the string. Examples Windows To change drives: CD, 'C:' To specify a full path: CD, 'C:\MyData\January' To change from the C:\MyData directory to the C:\MyData\January directory: CD, 'January' To go back up a directory, use "..". For example, if the current directory is C:\MyData\January, you could go up to the C:\MyData directory with the following command: CD, '..' If the current directory is C:\MyData\January, you could change to the C:\MyData\February directory with the following command: CD, '..\February' Unix To specify a full path: CD, '/home/data/' To change to the january subdirectory of the current directory: CD, 'january' To go back up a directory, use "..". For example, if the current directory is /home/data/january, you could go up to the /home/data/ directory with the following command: CD, '..' If the current directory is /home/data/january, you could change to the /home/data/february directory with the following command: CD, '../february' Macintosh To change drives, provide a path that begins with a volume name: CD, 'Macintosh volume:' To specify a full path, separate the folders with colons. CD, 'Macinotsh volume:My Data Folder:January:' To specify a partial path from the current folder, begin your path with a colon. For example, to change to the "January" subfolder of the current folder, use: CD, ':January:' To go back up the folder hierarchy, use a leading colon and then add one colon for each level you want to go up. For example, if the current folder is Macinotsh volume:My Data Folder:January:, you would go up to the folder Macinotsh volume:My Data Folder: with the following command: CD, '::' To go up two folders, use: CD, ':::' You can append a new folder path after a series of colons to go back up the folder hierarchy and then down into a subfolder. For example, to go from the folder Macinotsh volume:My Data Folder:January: to the folder Macinotsh volume:My Data Folder:Febuary:, use the following command: CD, '::Febuary:' You cannot specify multiple colons in the middle of a path-they must appear at the beginning of the path specifier. VMS To change to the data subdirectory of the current directory: CD, '[.data]' See Also PUSHD, POPD CDF ROUTINES [Previous Routine] [Next Routine] [List of Routines] NAME: CDF Routines See "Alphabetical Listing of CDF Routines" in the Scientific Data Formats manual. NAME: CEIL The CEIL function returns the closest integer greater than or equal to its argument. Syntax Result = CEIL(X [, /L64] ) Return Value If the input value X is integer type, Result has the same value and type as X. Otherwise, Result is a 32-bit longword integer with the same structure as X. Arguments X The value for which the ceiling function is to be evaluated. This value can be any numeric type (integer, floating, or complex). Keywords L64 If set, the result type is 64-bit integer regardless of the input type. This is useful for situations in which a floating point number contains a value too large to be represented in a 32-bit integer. Example To print the ceiling function of 5.1, enter: PRINT, CEIL(5.1) ; IDL prints: 6 To print the ceiling function of 3000000000.1, the result of which is too large to represent in a 32-bit integer: PRINT, CEIL(3000000000.1D, /L64) ; IDL prints: 3000000001 See Also COMPLEXROUND, FLOOR, ROUND CHEBYSHEV [Previous Routine] [Next Routine] [List of Routines] NAME: CHEBYSHEV The CHEBYSHEV function returns the forward or reverse Chebyshev polynomial expansion of a set of data. Note: Results from this function are subject to roundoff error given discontinuous data. This routine is written in the IDL language. Its source code can be found in the file chebyshev.pro in the lib subdirectory of the IDL distribution. Syntax Result = CHEBYSHEV(D, N) Arguments D A vector containing the values at the zeros of Chebyshev polynomial. N A flag that, if set to -1, returns a set of Chebyshev polynomials. If set to +1, the original data is returned. See Also FFT, WTN CHECK_MATH [Previous Routine] [Next Routine] [List of Routines] NAME: CHECK_MATH The CHECK_MATH function returns and clears the accumulated math error status. Syntax Result = CHECK_MATH( [, MASK=bitmask] [, /NOCLEAR] [, /PRINT] ) Return Value The returned value is the sum of the bit values (described in the following table) of the accumulated errors. Note that not all machines detect all errors. Value Condition 0 No errors detected since the last interactive 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. An illegal operand was encountered, such as a negative operand to the SQRT or ALOG functions, or an attempt to convert to integer a number whose absolute value is greater than 231 - 1 Table 4: Math Error Status Values Note that each type of error is only represented once in the return value-any number of "Integer divided by zero" errors will result in a return value of 1. The math error status is cleared (reset to zero) when CHECK_MATH is called, or when errors are reported. Math errors are reported either never, when the interpreter returns to an interactive prompt, or after execution of each IDL statement, depending on the value of the !EXCEPT system variable (see "!EXCEPT" on page 2426). See "Examples" below for further discussion. Keywords MASK If present, the mask of exceptions to check. Otherwise, all exceptions are checked. Exceptions that are pending but not specified by MASK are not reported, and not cleared. Set this keyword equal to the sum of the bit values for each exception to be checked. For a list of the bit values corresponding to various exceptions, see CHECK_MATH. NOCLEAR If set, CHECK_MATH returns the pending exceptions (as specified via the MASK keyword) and clears them from its list of pending exceptions. If NOCLEAR is set, the exceptions are not cleared and remain pending. PRINT Set this keyword to print an error message to the IDL command log if any accumulated math errors exist. If this keyword is not present, CHECK_MATH executes silently. Examples To simply check and clear the accumulated math error status using all the defaults, enter: PRINT, CHECK_MATH() IDL prints the accumulated math error status code and resets to zero. CHECK_MATH and !EXCEPT Because the accumulated math error status is cleared when it is reported, the behavior and appropriate use of CHECK_MATH depends on the value of the system variable !EXCEPT. * If !EXCEPT is set equal to 0, math exceptions are not reported automatically, and thus CHECK_MATH will always return the error status accumulated since the last time it was called. * If !EXCEPT is set equal to 1, math exceptions are reported when IDL returns to the interactive command prompt. In this case, CHECK_MATH will return appropriate error codes when used within an IDL procedure, but will always return zero when called at the IDL prompt. * If !EXCEPT is set equal to 2, math exceptions are reported after each IDL statement. In this case, CHECK_MATH will return appropriate error codes only when used within an IDL statement, and will always return zero otherwise. For example: ;Set value of !EXCEPT to zero. !EXCEPT=0 ;Both of these operations cause errors. PRINT, 1./0., 1/0 IDL prints: Inf 1 The special floating-point value Inf is returned for 1./0. There is no integer analogue to the floating-point Inf. ;Check the accumulated error status. PRINT, CHECK_MATH() IDL prints: 17 CHECK_MATH reports floating-point and integer divide-by-zero errors. ;Set value of !EXCEPT to one. !EXCEPT=1 ;Both of these operations cause errors. PRINT, 1./0., 1/0 IDL prints: Inf 1 % Program caused arithmetic error: Integer divide by 0 % Program caused arithmetic error: Floating divide by 0 This time IDL also prints error messages. ;Check the accumulated error status. PRINT, CHECK_MATH() IDL prints: 0 The status was reset. However, if we do not allow IDL to return to an interactive prompt before checking the math error status: ;Set value of !EXCEPT to one. !EXCEPT=1 ;Call to CHECK_MATH happens before returning to the ;IDL command prompt. PRINT, 1./0., 1/0 & PRINT, CHECK_MATH() IDL prints: Inf 1 17 In this case, the math error status code (17) is printed, but because the error status has been cleared by the call to CHECK_MATH, no error messages are printed when IDL returns to the interactive command prompt. Finally, ;Set value of !EXCEPT to two. !EXCEPT=2 ;Call to CHECK_MATH happens before returning to the ;IDL command prompt. PRINT, 1./0., 1/0 & PRINT, CHECK_MATH() IDL prints: Inf 1 % Program caused arithmetic error: Integer divide by 0 % Program caused arithmetic error: Floating divide by 0 % Detected at $MAIN$ 0 Errors are printed before executing the CHECK_MATH function, so CHECK_MATH reports no errors. However, if we include the call to CHECK_MATH in the first PRINT command, we see the following: ;Call to CHECK_MATH is part of a single IDL statement. PRINT, 1./0., 1/0, CHECK_MATH() IDL prints: Inf 1 17 Printing Error Messages The following code fragment prints abbreviated names of errors that have occurred: ;Create a string array of error names. ERRS = ['Divide by 0', 'Underflow', 'Overflow', $ 'Illegal Operand'] ;Get math error status. J = CHECK_MATH() FOR I = 4, 7 DO IF ISHFT(J, -I) AND 1 THEN $ ;Check to see if an error occurred and print the corresponding ;error message. PRINT, ERRS(I-4), ' Occurred' Testing Critical Code Example 1 Assume you have a critical section of code that is likely to produce an error. The following example shows how to check for errors, and if one is detected, how to repeat the code with different parameters. ; Clear error status from previous operations, and print error ; messages if an error exists: JUNK = CHECK_MATH(/PRINT) ; Disable automatic printing of subsequent math errors: !EXCEPT=0 ;Critical section goes here. AGAIN: ... ; Did an arithmetic error occur? If so, print error message and ; request new values: IF CHECK_MATH() NE 0 THEN BEGIN PRINT, 'Math error occurred in critical section.' ; Get new parameters from user: READ, 'Enter new values.',... ; Enable automatic printing of math errors: !EXCEPT=2 ;And retry: GOTO, AGAIN ENDIF Example 2 This example demonstrates the use of the MASK keyword to check for a specific error, and the NOCLEAR keyword to prevent exceptions from being cleared: PRO EXAMPLE2_CHECKMATH PRINT, 1./0 PRINT, CHECK_MATH(MASK=16,/NOCLEAR) PRINT, CHECK_MATH(MASK=2,/NOCLEAR) END IDL prints: Inf 16 0% Program caused arithmetic error: Floating divide by 0 See Also FINITE, ISHFT, MACHAR, !VALUES, !EXCEPT CHISQR_CVF [Previous Routine] [Next Routine] [List of Routines] NAME: CHISQR_CVF The CHISQR_CVF function computes the cutoff value V in a Chi-square distribution with Df degrees of freedom such that the probability that a random variable X is greater than V is equal to a user-supplied probability P. This routine is written in the IDL language. Its source code can be found in the file chisqr_cvf.pro in the lib subdirectory of the IDL distribution. Syntax Result = CHISQR_CVF(P, Df) Arguments P A non-negative single- or double-precision floating-point scalar, in the interval [0.0, 1.0], that specifies the probability of occurrence or success. Df A positive integer, single- or double-precision floating-point scalar that specifies the number of degrees of freedom of the Chi-square distribution. Example Use the following command to compute the cutoff value in a Chi-square distribution with three degrees of freedom such that the probability that a random variable X is greater than the cutoff value is 0.100. The result should be 6.25139. PRINT, CHISQR_CVF(0.100, 3) IDL prints: 6.25139 See Also CHISQR_PDF, F_CVF, GAUSS_CVF, T_CVF CHISQR_PDF [Previous Routine] [Next Routine] [List of Routines] NAME: CHISQR_PDF The CHISQR_PDF function computes the probability P that, in a Chi-square distribution with Df degrees of freedom, a random variable X is less than or equal to a user-specified cutoff value V. This routine is written in the IDL language. Its source code can be found in the file chisqr_pdf.pro in the lib subdirectory of the IDL distribution. Syntax Result = CHISQR_PDF(V, Df) Return Value If both arguments are scalar, the function returns a scalar. If both arguments are arrays, the function matches up the corresponding elements of V and Df, returning an array with the same dimensions as the smallest array. If one argument is a scalar and the other argument is an array, the function uses the scalar value with each element of the array, and returns an array with the same dimensions as the input array. If any of the arguments are double-precision, the result is double-precision, otherwise the result is single-precision. Arguments V A scalar or array that specifies the cutoff value(s). Df A positive scalar or array that specifies the number of degrees of freedom of the Chi- square distribution. Examples Use the following command to compute the probability that a random variable X, from the Chi-square distribution with three degrees of freedom, is less than or equal to 6.25. The result should be 0.899939. result = CHISQR_PDF(6.25, 3) PRINT, result IDL prints: 0.899939 Compute the probability that a random variable X from the Chi-square distribution with three degrees of freedom, is greater than 6.25. The result should be 0.100061. PRINT, 1 - chisqr_pdf(6.25, 3) IDL prints: 0.100061 See Also BINOMIAL, CHISQR_CVF, F_PDF, GAUSS_PDF, T_PDF CHOLDC [Previous Routine] [Next Routine] [List of Routines] NAME: CHOLDC Given a positive-definite symmetric n by n array A, the CHOLDC procedure constructs its Cholesky decomposition A = LLT, where L is a lower triangular array and LT is the transpose of L. CHOLDC is based on the routine choldc described in section 2.9 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press, and is used by permission. Syntax CHOLDC, A, P [, /DOUBLE] Arguments A An n by n array. On input, only the upper triangle of A need be given. On output, L is returned in the lower triangle of A, except for the diagonal elements, which are returned in the vector P. P An n-element vector containing the diagonal elements of L. Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. Example See "CHOLSOL" on page 182. See Also CHOLSOL CHOLSOL [Previous Routine] [Next Routine] [List of Routines] NAME: CHOLSOL The CHOLSOL function returns an n-element vector containing the solution to the set of linear equations Ax = b, where A is the positive-definite symmetric array returned by the CHOLDC procedure. CHOLSOL is based on the routine cholsl described in section 2.9 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press, and is used by permission. Syntax Result = CHOLSOL( A, P, B [, /DOUBLE] ) Arguments A An n by n positive-definite symmetric array, as output by CHOLDC. Only the lower triangle of A is accessed. P The diagonal elements of the Cholesky factor L, as computed by CHOLDC. B An n-element vector containing the right-hand side of the equation. Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. Example To solve a positive-definite symmetric system Ax = b: ;Define the coefficient array: A = [[ 6.0, 15.0, 55.0], $ [15.0, 55.0, 225.0], $ [55.0, 225.0, 979.0]] ;Define the right-hand side vector B: B = [9.5, 50.0, 237.0] ;Compute Cholesky decomposition of A: CHOLDC, A, P ;Compute and print the solution: PRINT, CHOLSOL(A, P, B) IDL prints: -0.499998 -1.00000 0.500000 The exact solution vector is [-0.5, -1.0, 0.5]. See Also CHOLDC, CRAMER, GS_ITER, LU_COMPLEX, LUSOL, SVSOL, TRISOL CINDGEN [Previous Routine] [Next Routine] [List of Routines] NAME: CINDGEN The CINDGEN function returns a complex, single-precision, 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. Syntax Result = CINDGEN(D1, ..., D8) Arguments Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. The dimensions of the result. The dimension parameters can be any scalar expression. Up to eight dimensions can be specified. If the dimension arguments are not integer values, IDL will convert them to integer values before creating the new array. 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) See Also BINDGEN, DCINDGEN, DINDGEN, FINDGEN, INDGEN, LINDGEN, SINDGEN, UINDGEN, UL64INDGEN, ULINDGEN CIR_3PNT [Previous Routine] [Next Routine] [List of Routines] NAME: CIR_3PNT The CIR_3PNT procedure returns the radius and center of a circle, given 3 points on the circle. This is analogous to finding the circumradius and circumcircle of a triangle; the center of the circumcircle is the point at which the three perpendicular bisectors of the triangle formed by the points meet. This routine is written in the IDL language. Its source code can be found in the file cir_3pnt.pro in the lib subdirectory of the IDL distribution. Syntax CIR_3PNT, X, Y, R, X0, Y0 Arguments X A three-element vector containing the X-coordinates of the points. Y A three-element vector containing the Y-coordinates of the points. R A named variable that will contain the radius of the circle. The procedure returns 0.0 if the points are co-linear. X0 A named variable that will contain the X-coordinate of the center of the circle. The procedure returns 0.0 if the points are co-linear. Y0 A named variable that will contain the Y-coordinate of the center of the circle. The procedure returns 0.0 if the points are co-linear. Example X = [1.0, 2.0, 3.0] Y = [1.0, 2.0, 1.0] CIR_3PNT, X, Y, R, X0, Y0 PRINT, 'The radius is: ', R PRINT, 'The center of the circle is at: ', X0, Y0 See Also PNT_LINE, SPH_4PNT CLOSE [Previous Routine] [Next Routine] [List of Routines] NAME: CLOSE The CLOSE procedure closes the file units specified as arguments. All open files are also closed when IDL exits. Syntax CLOSE[, Unit1, ..., Unitn] [, /ALL] [, EXIT_STATUS=variable] [, /FILE] [, /FORCE] 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. EXIT_STATUS Set this keyword to a named varible that will contain the exit status reported by a UNIX child process started via the UNIT keyword to SPAWN. This value is the exit value reported by the process by calling EXIT, and is analogous to the value returned by $? under most UNIX shells. If used with any other type of file, 0 is returned. EXIT_STATUS is not allowed in conjunction with the ALL or FILE keywords. FILE Set this keyword to close all file units from 1 to 99. File units greater than 99, which are associated with the GET_LUN and FREE_LUN procedures, are not affected. FORCE Overrides the IDL file output buffer and forces the file to be closed no matter what errors occur in the process. IDL buffers file output for performance reasons. If it is not possible to properly flush this data when a file close is requested, an error is normally issued and the file remains open. An example of this might be that your disk does not have room to write the remaining data. This default behavior prevents data from being lost. To override it and force the file to be closed no matter what errors occur in the process, specify FORCE. 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 See Also OPEN CLUST_WTS [Previous Routine] [Next Routine] [List of Routines] NAME: CLUST_WTS The CLUST_WTS function computes the weights (the cluster centers) of an m- column, n-row array, where m is the number of variables and n is the number of observations or samples. The result is an m-column, N_CLUSTERS-row array of cluster centers. This routine is written in the IDL language. Its source code can be found in the file clust_wts.pro in the lib subdirectory of the IDL distribution. For more information on cluster analysis, see: Everitt, Brian S. Cluster Analysis. New York: Halsted Press, 1993. ISBN 0-470- 22043-0 Syntax Result = CLUST_WTS( Array [, /DOUBLE] [, N_CLUSTERS=value] [, N_ITERATIONS=integer] [, VARIABLE_WTS=vector] ) Arguments Array An m-column, n-row array of any data type except string, single- or double-precision complex. Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. N_CLUSTERS Set this keyword equal to the number of cluster centers. The default is to compute n cluster centers. N_ITERATIONS Set this keyword equal to the number of iterations used when in computing the cluster centers. The default is to use 20 iterations. VARIABLE_WTS Set this keyword equal to an m-element vector of floating-point variable weights. The elements of this vector are used to give greater or lesser importance to each variable (each column) in determining the cluster centers. The default is to give all variables equal weighting using a value of 1.0. Example See "CLUSTER" on page 191. See Also CLUSTER CLUSTER [Previous Routine] [Next Routine] [List of Routines] NAME: CLUSTER The CLUSTER function computes the classification of an m-column, n-row array, where m is the number of variables and n is the number of observations or samples. The classification is based upon a cluster analysis of sample-based distances. The result is a 1-column, n-row array of cluster number assignments that correspond to each sample. This routine is written in the IDL language. Its source code can be found in the file cluster.pro in the lib subdirectory of the IDL distribution. For more information on cluster analysis, see: Everitt, Brian S. Cluster Analysis. New York: Halsted Press, 1993. ISBN 0-470- 22043-0 Syntax Result = CLUSTER( Array, Weights [, /DOUBLE] [, N_CLUSTERS=value] ) Arguments Array An M-column, N-row array of type float or double. Weights An array of weights (the cluster centers) computed using the CLUST_WTS function. The dimensions of this array vary according to keyword values. Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. N_CLUSTERS Set this keyword equal to the number of clusters. The default is based upon the row dimension of the Weights array. Example ; Define an array with 4 variables and 10 observations: array = $ [[ 1.5, 43.1, 29.1, 1.9], $ [24.7, 49.8, 28.2, 22.8], $ [30.7, 51.9, 7.0, 18.7], $ [ 9.8, 4.3, 31.1, 0.1], $ [19.1, 42.2, 0.9, 12.9], $ [25.6, 13.9, 3.7, 21.7], $ [ 1.4, 58.5, 27.6, 7.1], $ [ 7.9, 2.1, 30.6, 5.4], $ [22.1, 49.9, 3.2, 21.3], $ [ 5.5, 53.5, 4.8, 19.3]] ; Compute the cluster weights, using two distinct clusters: weights = CLUST_WTS(array, N_CLUSTERS=2) ; Compute the classification of each sample: result = CLUSTER(array, weights, N_CLUSTERS=2) ; Print each sample (each row) of the array and its corresponding ; cluster assignment: FOR k = 0, N_ELEMENTS(result)-1 DO PRINT, $ array[*,k], result(k), FORMAT = '(4(f4.1, 2x), 5x, i1)' IDL prints: 1.5 43.1 29.1 1.9 1 24.7 49.8 28.2 22.8 0 30.7 51.9 7.0 18.7 0 9.8 4.3 31.1 0.1 1 19.1 42.2 0.9 12.9 0 25.6 13.9 3.7 21.7 0 1.4 58.5 27.6 7.1 1 7.9 2.1 30.6 5.4 1 22.1 49.9 3.2 21.3 0 5.5 53.5 4.8 19.3 0 See Also CLUST_WTS, PCOMP, STANDARDIZE COLOR_CONVERT [Previous Routine] [Next Routine] [List of Routines] NAME: COLOR_CONVERT The COLOR_CONVERT procedure converts colors to and from the RGB (Red Green Blue), HLS (Hue Lightness Saturation), 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 containing a discussion of the various color systems is: Foley and Van Dam, Fundamentals of Interactive Computer Graphics, Addison-Wesley Publishing Co., 1982. Syntax COLOR_CONVERT, I0, I1, I2, O0, O1, O2 {, /HLS_RGB | , /HSV_RGB | , /RGB_HLS | , /RGB_HSV} 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. See Also HLS, HSV COLOR_QUAN [Previous Routine] [Next Routine] [List of Routines] NAME: COLOR_QUAN The COLOR_QUAN function quantizes a TrueColor 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, TrueColor images, that contain a palette of up to 224 colors, on pseudo-color displays that can only display 256 (or fewer) simultaneous colors. Syntax Result = COLOR_QUAN( Image_R, Image_G, Image_B, R, G, B) or Result = COLOR_QUAN( Image, Dim, R, G, B ) Keywords: [, COLORS=integer{2 to 256}] [, CUBE={2 | 3 | 4 | 5 | 6} | , GET_TRANSLATION=variable [, /MAP_ALL]] [, /DITHER] [, ERROR=variable] [, TRANSLATION=vector] 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. Using COLOR_QUAN 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 Display", 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 nearest output color, and the original image is resampled to the new palette with optional Floyd-Steinberg color dithering. The resulting pseudo-color image and palette are usually a good approximation of the original image. The number of colors in the output palette defaults to the number of colors supported by the currently-selected graphics output device. The number of colors can also be specified by the COLOR keyword parameter. * Method 2, selected by setting the keyword parameter CUBE, divides the three- dimensional color space into equal-volume cubes. Each color axis is divided into CUBE segments, resulting in CUBE3 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 image, so that multiple quantized images can be viewed simultaneously. The statistical method usually provides 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. Arguments Image_R, Image_G, Image_B Arrays containing the red, green, and blue components of the decomposed TrueColor 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 TrueColor 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). A value of 2 indicates interleaving by row: (n, 3, m). A value of 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 be 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 CUBE3 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 23 = 8, to 63 = 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 TrueColor 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 TrueColor, row interleaved, image from a disk file, and displays it on the current graphics display, using a palette of 128 colors: ;Open an input file: OPENR, unit, 'XXX.DAT', /GET_LUN ;Dimensions of the input image: a = BYTARR(512, 3, 480) ;Read the image: READU, unit, a ;Close the file: FREE LUN, unit ;Show the quantized image. The 2 indicates that the colors are ;interleaved by row: TV, COLOR_QUAN(a, 2, r, g, b, COLORS=128) ;Load the new palette: TVLCT, r, g, b 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) See Also PSEUDO COLORMAP_APPLICABLE [Previous Routine] [Next Routine] [List of Routines] NAME: COLORMAP_APPLICABLE The COLORMAP_APPLICABLE function determines whether the current visual class supports the use of a colormap, and if so, whether colormap changes affect pre- displayed Direct Graphics or if the graphics must be redrawn to pick up colormap changes. This routine is written in the IDL language. Its source code can be found in the file colormap_applicable.pro in the lib subdirectory of the IDL distribution. Syntax Result = COLORMAP_APPLICABLE( redrawRequired ) Return Value The function returns a long value of 1 if the current visual class allows modification of the color table, and 0 otherwise. Arguments redrawRequired A named variable to retrieve a value indicating whether the visual class supports automatic updating of graphics. The value is 0 if the graphics are updated automatically, or 1 if the graphics must be redrawn to pick up changes to the colormap. Keywords None. Example To determine whether to redisplay an image after a colormap change: result = COLORMAP_APPLICABLE(redrawRequired) IF ((result GT 0) AND (redrawRequired GT 0)) THEN BEGIN my_redraw ENDIF COMFIT [Previous Routine] [Next Routine] [List of Routines] NAME: COMFIT The COMFIT function fits the paired data {xi, yi} to one of six common types of approximating models using a gradient-expansion least-squares method. The result is a vector containing the model parameters a0, a1, a2, etc. This routine is written in the IDL language. Its source code can be found in the file comfit.pro in the lib subdirectory of the IDL distribution. Syntax Result = COMFIT( X, Y, A {, /EXPONENTIAL | , /GEOMETRIC | , /GOMPERTZ | , /HYPERBOLIC | , /LOGISTIC | , /LOGSQUARE} [, SIGMA=variable] [, WEIGHTS=vector] [, YFIT=variable] ) Arguments X An n-element integer, single-, or double-precision floating-point vector. Y An n-element integer, single-, or double-precision floating-point vector. A A vector of initial estimates for each model parameter. The length of this vector depends upon the type of model selected. Keywords Note One of the following keywords specifying a type of model must be set when using COMFIT. If you do not specify a model, IDL will display a warning message when COMFIT is called. EXPONENTIAL Set this keyword to compute the parameters of the exponential model. y = a x 0a1 + a2 GEOMETRIC Set this keyword to compute the parameters of the geometric model. y = a0xa1 + a2 GOMPERTZ Set this keyword to compute the parameters of the Gompertz model. y = a a 0a12x + a3 HYPERBOLIC Set this keyword to compute the parameters of the hyperbolic model. y 1 = -------------------- a0 + a1x LOGISTIC Set this keyword to compute the parameters of the logistic model. y 1 = ---------------------- a x 0a1 + a2 LOGSQUARE Set this keyword to compute the parameters of the logsquare model. y = a0 + a1log(x) + a2 (x)2 log SIGMA Set this keyword to a named variable that will contain a vector of standard deviations for the computed model parameters. WEIGHTS Set this keyword equal to a vector of weights for Yi. This vector should be the same length as X and Y. The error for each term is weighted by WEIGHTSi when computing the fit. Frequently, WEIGHTSi = 1.0/ 2i, where is the measurement error or standard deviation of Yi (Gaussian or instrumental weighting), or WEIGHTS = 1/Y (Poisson or statistical weighting). If WEIGHTS is not specified, WEIGHTSi is assumed to be 1.0. YFIT Set this keyword to a named variable that will contain an n-element vector of y-data corresponding to the computed model parameters. Example ; Define two n-element vectors of paired data: X = [ 2.27, 15.01, 34.74, 36.01, 43.65, 50.02, 53.84, 58.30, $ 62.12, 64.66, 71.66, 79.94, 85.67, 114.95] Y = [ 5.16, 22.63, 34.36, 34.92, 37.98, 40.22, 41.46, 42.81, $ 43.91, 44.62, 46.44, 48.43, 49.70, 55.31] ; Define a 3-element vector of initial estimates for the logsquare ; model: A = [1.5, 1.5, 1.5] ; Compute the model parameters of the logsquare model, A[0], A[1], ; & A[2]: result = COMFIT(X, Y, A, /LOGSQUARE) The result should be the 3-element vector: [1.42494, 7.21900, 9.18794]. See Also CURVEFIT, LADFIT, LINFIT, LMFIT, POLY_FIT, SVDFIT COMMON [Previous Routine] [Next Routine] [List of Routines] NAME: COMMON The COMMON statement creates a common block. Note For more information on using COMMON, see Chapter 3, "Constants and Variables" in Building IDL Applications. Syntax COMMON Block_Name, Variable1, ..., Variablen COMPILE_OPT [Previous Routine] [Next Routine] [List of Routines] NAME: COMPILE_OPT The COMPILE_OPT statement allows the author to give the IDL compiler information that changes some of the default rules for compiling the function or procedure within which the COMPILE_OPT statement appears. Research Systems recommends the use of COMPILE_OPT IDL2 in all new code intended for use in a reusable library. We further recommend the use of COMPILE_OPT idl2, HIDDEN in all such routines that are not intended to be called directly by regular users (e.g. helper routines that are part of a larger package). Note For information on using COMPILE_OPT, see Chapter 12, "Procedures and Functions" in Building IDL Applications. Syntax COMPILE_OPT opt1 [, opt2, ..., optn] Arguments optn This argument can be any of the following: * IDL2 - A shorthand way of saying: COMPILE_OPT DEFINT32, STRICTARR * DEFINT32 - IDL should assume that lexical integer constants default to the 32-bit type rather than the usual default of 16-bit integers. This takes effect from the point where the COMPILE_OPT statement appears in the routine being compiled and remains in effect until the end of the routine. The following table illustrates how the DEFINT32 argument changes the interpretation of integer constants: Constant Normal Type DEFINT32 Type Without type specifier: 42 INT LONG '2a'x INT LONG 42u UINT ULONG '2a'xu UINT ULONG With type specifier: 0b BYTE BYTE 0s INT INT 0l LONG LONG 42.0 FLOAT FLOAT 42d DOUBLE DOUBLE 42us UINT UINT 42ul ULONG ULONG 42ll LONG64 LONG64 42ull ULONG64 ULONG64 Table 5: Examples of the effect of the DEFINT32 argument * HIDDEN - This routine should not be displayed by HELP, unless the FULL keyword to HELP is used. This directive can be used to hide helper routines that regular IDL users are not interested in seeing. A side-effect of making a routine hidden is that IDL will not print a "Compile module" message for it when it is compiled from the library to satisfy a call to it. This makes hidden routines appear built-in to the user. * OBSOLETE - If the user has !WARN.OBS_ROUTINES set to True, attempts to compile a call to this routine will generate warning messages that this routine is obsolete. This directive can be used to warn people that there may be better ways to perform the desired task. * STRICTARR - While compiling this routine, IDL will not allow the use of parentheses to index arrays, reserving their use only for functions. Square brackets are then the only way to index arrays. Use of this directive will prevent the addition of a new function in future versions of IDL, or new libraries of IDL code from any source, from changing the meaning of your code, and is an especially good idea for library functions. Use of STRICTARR can eliminate many uses of the FORWARD_FUNCTION definition. Note STRICTARR has no effect on the use of parentheses to reference structure tags using the tag index, which is not an array indexing operation. For example, no syntax error will occur when compiling the following code: COMPILE_OPT STRICTARR mystruct = {a:0, b:1} byindex_0 = mystruct.(0) For more on referencing structure tags by index, see "Advanced Structure Usage" in Chapter 6 of Building IDL Applications. COMPLEX [Previous Routine] [Next Routine] [List of Routines] NAME: 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-precision 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 Expression. Syntax Result = COMPLEX( Real [, Imaginary] [, DOUBLE]) or Result = COMPLEX(Expression, Offset, Dim1 [, ..., Dim8]) Keywords DOUBLE Set this keyword to return a double-precision complex result. This is equivalent to using the DCOMPLEX function, and is provided as a programming convenience. 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 3, "Constants and Variables" of Using IDL for details. Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. 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 arguments 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 warning message and return 0. The ON_IOERROR procedure can be used to establish a statement to be jumped to in case of such errors. Example Create a complex array from two integer arrays by entering the following commands: ; Create the first integer array: A = [1,2,3] ; Create the second integer array: B = [4,5,6] ; Make A the real parts and B the imaginary parts of the new ; complex array: C = COMPLEX(A, B) ; See how the two arrays were combined: PRINT, C IDL prints: ( 1.00000, 4.00000)( 2.00000, 5.00000) ( 3.00000, 6.00000) The real and imaginary parts of the complex array can be extracted as follows: ; Print the real part of the complex array C: PRINT, 'Real Part: ', FLOAT(C) ; Print the imaginary part of the complex array C: PRINT, 'Imaginary Part: ', IMAGINARY(C) IDL prints: Real Part: 1.00000 2.00000 3.00000 Imaginary Part: 4.00000 5.00000 6.00000 See Also BYTE, CONJ, DCOMPLEX, DOUBLE, FIX, FLOAT, LONG, LONG64, STRING, UINT, ULONG, ULONG64 COMPLEXARR [Previous Routine] [Next Routine] [List of Routines] NAME: COMPLEXARR The COMPLEXARR function returns a complex, single-precision, floating-point vector or array. Syntax Result = COMPLEXARR( D1, ..., D8 [, /NOZERO] ) Arguments Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. 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) See Also DBLARR, DCOMPLEXARR, FLTARR, INTARR, LON64ARR, LONARR, MAKE_ARRAY, STRARR, UINTARR, ULON64ARR, ULONARR COMPLEXROUND [Previous Routine] [Next Routine] [List of Routines] NAME: COMPLEXROUND The COMPLEXROUND function rounds real and imaginary components of a complex array and returns the resulting array. If the array is double-precision complex, then the result is also double-precision complex. This routine is written in the IDL language. Its source code can be found in the file complexround.pro in the lib subdirectory of the IDL distribution. Syntax Result = COMPLEXROUND(Input) Arguments Input The complex array to be rounded. Example X = [COMPLEX(1.245, 3.88), COMPLEX(9.1, 0.3345)] PRINT, COMPLEXROUND(X) IDL prints: ( 1.00000, 4.00000)( 9.00000, 0.00000) See Also ROUND COMPUTE_MESH_NORMALS [Previous Routine] [Next Routine] [List of Routines] NAME: COMPUTE_MESH_NORMALS The COMPUTE_MESH_NORMALS function computes normal vectors for a set of polygons described by the input array. The return value is a 3 x M array containing a unit normal for each vertex in the input array. Syntax Result = COMPUTE_MESH_NORMALS( fVerts[, iConn] ) Arguments fVerts A 3 x M array of vertices. iConn A connectivity array (see the POLYGONS keyword to IDLgrPolygon::Init). If no iConn array is provided, it is assumed that the vertices in fVerts constitute a single polygon. Keywords None. COND [Previous Routine] [Next Routine] [List of Routines] NAME: COND The COND function returns the condition number of an n by n real or complex array A by explicitly computing NORM(A)·NORM(A-1). If A is real and A-1 is invalid (due to the singularity of A or floating-point errors in the INVERT function), COND returns -1. If A is complex and A-1 is invalid (due to the singularity of A), calling COND results in floating-point errors. This routine is written in the IDL language. Its source code can be found in the file cond.pro in the lib subdirectory of the IDL distribution. Syntax Result = COND( A [, LNORM] [, /DOUBLE] ) Arguments A An n by n real or complex array. Keywords LNORM Set this keyword to indicate which norm to use for the computation. The possible values of this keyword are: * LNORM = 0 Use the L norm (the maximum absolute row sum norm). * LNORM = 1 Use the L1 norm (the maximum absolute column sum norm). * LNORM = 2 Use the L2 norm (the spectral norm). For LNORM = 2, A cannot be complex. LNORM is set to 0 by default. DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. Example ; Define a complex array A: A = [[COMPLEX(1, 0), COMPLEX(2,-2), COMPLEX(-3, 1)], $ [COMPLEX(1,-2), COMPLEX(2, 2), COMPLEX(1, 0)], $ [COMPLEX(1, 1), COMPLEX(0, 1), COMPLEX(1, 5)]] ; Compute the condition number of the array using internal ; double-precision arithmetic: PRINT, COND(A, /DOUBLE) IDL prints: 5.93773 See Also DETERM, INVERT CONGRID [Previous Routine] [Next Routine] [List of Routines] NAME: CONGRID The CONGRID function shrinks or expands the size of an array by an arbitrary amount. CONGRID is similar to REBIN in that it can resize a one, two, or three dimensional array, but where REBIN requires that the new array size must be an integer multiple of the original size, CONGRID will resize an array to any arbitrary size. (REBIN is somewhat faster, however.) REBIN averages multiple points when shrinking an array, while CONGRID just resamples the array. The returned array has the same number of dimensions as the original array and is of the same data type. This routine is written in the IDL language. Its source code can be found in the file congrid.pro in the lib subdirectory of the IDL distribution. Syntax Result = CONGRID( Array, X, Y, Z [, CENTER] [, CUBIC=value{-1 to 0}] [, /INTERP] [, /MINUS_ONE] ) Arguments Array A 1-, 2-, or 3-dimensional array to resize. Array can be any type except string or structure. X The new X-dimension of the resized array. X must be an integer or a long integer, and must be greater than or equal to 2. Y The new Y-dimension of the resized array. If the original array has only 1 dimension, Y is ignored. If the original array has 2 or 3 dimensions Y MUST be present. Z The new Z-dimension of the resized array. If the original array has only 1 or 2 dimensions, Z is ignored. If the original array has 3 dimensions then Z MUST be present. Keywords CENTER If this keyword is set, the interpolation is shifted so that points in the input and output arrays are assumed to lie at the midpoint of their coordinates rather than at their lower-left corner. CUBIC Set this keyword to a value between -1 and 0 to use the cubic convolution interpolation method with the specified value as the interpolation parameter. Setting this keyword equal to a value greater than zero specifies a value of -1 for the interpolation parameter. Park and Schowengerdt (see reference below) suggest that a value of -0.5 significantly improves the reconstruction properties of this algorithm. This keyword has no effect when used with 3-dimensional arrays. Cubic convolution is an interpolation method that closely approximates the theoretically optimum sinc interpolation function using cubic polynomials. According to sampling theory, details of which are beyond the scope of this document, if the original signal, f, is a band-limited signal, with no frequency component larger than 0, and f is sampled with spacing less than or equal to 1/(2 0), then f can be reconstructed by convolving with a sinc function: sinc(x) = sin( x) / ( x). In the one-dimensional case, four neighboring points are used, while in the two- dimensional case 16 points are used. Note that cubic convolution interpolation is significantly slower than bilinear interpolation. For further details see: Rifman, S.S. and McKinnon, D.M., "Evaluation of Digital Correction Techniques for ERTS Images; Final Report", Report 20634-6003-TU-00, TRW Systems, Redondo Beach, CA, July 1974. S. Park and R. Schowengerdt, 1983 "Image Reconstruction by Parametric Cubic Convolution", Computer Vision, Graphics & Image Processing 23, 256. INTERP Set this keyword to force CONGRID to use linear interpolation when resizing a 1- or 2-dimensional array. CONGRID automatically uses linear interpolation if the input array is 3-dimensional. When the input array is 1- or 2-dimensional, the default is to employ nearest-neighbor sampling. MINUS_ONE Set this keyword to prevent CONGRID from extrapolating one row or column beyond the bounds of the input array. For example, if the input array has the dimensions (i, j) and the output array has the dimensions (x, y), then by default the array is resampled by a factor of (i/x) in the X direction and (j/y) in the Y direction. If MINUS_ONE is set, the array will be resampled by the factors (i-1)/(x-1) and (j- 1)/(y-1). Example Given vol is a 3-D array with the dimensions (80, 100, 57), resize it to be a (90, 90, 80) array vol = CONGRID(vol, 90, 90, 80) See Also REBIN CONJ [Previous Routine] [Next Routine] [List of Routines] NAME: 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. Syntax 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) See Also CINDGEN, COMPLEX, COMPLEXARR, DCINDGEN, DCOMPLEX, DCOMPLEXARR CONSTRAINED_MIN [Previous Routine] [Next Routine] [List of Routines] NAME: CONSTRAINED_MIN The CONSTRAINED_MIN procedure solves nonlinear optimization problems of the following form: Minimize or maximize gp(X), subject to: glbi gi(X) gubi for i = 0,...,nfuns-1, i p xlbj xj xubj for j = 0,...,nvars-1 X is a vector of nvars variables, x0 ,...,xnvars-1, and G is a vector of nfuns functions g0 ,...,gnfuns-1, which all depend on X. Any of these functions may be nonlinear. Any of the bounds may be infinite and any of the constraints may be absent. If there are no constraints, the problem is solved as an unconstrained optimization problem. The program solves problems of this form by the Generalized Reduced Gradient Method. See References 1-4. CONSTRAINED_MIN uses first partial derivatives of each function gi with respect to each variable xj. These are automatically computed by finite difference approximation (either forward or central differences). CONSTRAINED_MIN is based on an implementation of the GRG algorithm supplied by Windward Technologies, Inc. See Reference 11. Syntax CONSTRAINED_MIN, X, Xbnd, Gbnd, Nobj, Gcomp, Inform [, ESPTOP=value] [, LIMSER=value] [, /MAXIMIZE] [, NSTOP=value] [, REPORT=filename] [, TITLE=string] Arguments X An nvars-element vector. On input, X contains initial values for the variables. On output, X contains final values of the variable settings determined by CONSTRAINED_MIN. Xbnd Bounds on variables. Xbnd is an nvars x 2 element array. * Xbnd[j,0] is the lower bound for variable x[j]. * Xbnd[j,1] is the upper bound for variable x[j]. * Use -1.0e30 to denote no lower bound and 1.0e30 for no upper bound. Gbnd Bounds on constraint functions. Gbnd is an nfuns x 2 element array. * Gbnd[i,0] is the lower bound for function g[i]. * Gbnd[i,1] is the upper bound for function g[i]. * use -1.0e30 to denote no lower bound and 1.0e30 for no upper bound. Bounds on the objective function are ignored; set them to 0. Nobj Index of the objective function. Gcomp A scalar string specifying the name of a user-supplied IDL function. This function must accept an nvars-element vector argument x of variable values and return an nfuns-element vector G of function values. Inform Termination status returned from CONSTRAINED_MIN. Inform value Message 0 Kuhn-Tucker conditions satisfied. This is the best possible indicator that an optimal point has been found. 1 Fractional change in objective less than EPSTOP for NSTOP consecutive iterations. See Keywords below. This is not as good as Inform=0, but still indicates the likelihood that an optimal point has been found. 2 All remedies have failed to find a better point. User should check functions and bounds for consistency and, perhaps, try other starting values. Table 6: Inform argument values Inform value Message 3 Number of completed 1-dimensional searches exceeded LIMSER. See Keywords below. User should check functions and bounds for consistency and, perhaps, try other starting values. It might help to increase LIMSER. Use LIMSER=larger_value to do this. 4 Objective function is unbounded. CONSTRAINED_MIN has observed dramatic change in the objective function over several steps. This is a good indication that the objective function is unbounded. If this is not the case, the user should check functions and bounds for consistency. 5 Feasible point not found. CONSTRAINED_MIN was not able to find a feasible point. If the problem is believed to be feasible, the user should check functions and bounds for consistency and perhaps try other starting values. 6 Degeneracy has been encountered. The point returned may be close to optimal. The user should check functions and bounds for consistency and perhaps try other starting values. 7 Noisy and nonsmooth function values. Possible singularity or error in the function evaluations. 8 Optimization process terminated by user request. 9 Maximum number of function evaluations exceeded. ­1 Fatal Error. Some condition, such as nvars < 0, was encountered. CONSTRAINED_MIN documented the condition in the report and terminated. In this case, the user needs to correct the input and rerun CONSTRAINED_MIN. ­2 Fatal Error. The report file could not be opened. Check the filename specified via the REPORT keyword, and make sure you have write privileges to the specified path. Table 6: Inform argument values Inform value Message ­3 Fatal Error. Same as Inform = ­1. In this case, the REPORT keyword was not specified. Specify the REPORT keyword and rerun CONSTRAINED_MIN, then check the report file for more detail on the error. Table 6: Inform argument values Keywords EPSTOP Set this keyword to specify the CONSTRAINED_MIN convergence criteria. If the fractional change in the objective function is less than EPSTOP for NSTOP consecutive iterations, the program will accept the current point as optimal. CONSTRAINED_MIN will accept the current point as optimal if the Kuhn-Tucker optimality conditions are satisfied to EPSTOP. By default, EPSTOP = 1.0e-4. LIMSER If the number of completed one dimensional searches exceeds LIMSER, CONSTRAINED_MIN terminates and returns inform = 3. By default: LIMSER = 10000. MAXIMIZE By default, the CONSTRAINED_MIN procedure performs a minimization. Set the MAXIMIZE keyword to perform a maximization instead. NSTOP Set this keyword to specify the CONSTRAINED_MIN convergence criteria. If the fractional change in the objective function is less than EPSTOP for NSTOP consecutive iterations, CONSTRAINED_MIN will accept the current point as optimal. By default, NSTOP = 3. REPORT Set this keyword to specify a name for the CONSTRAINED_MIN report file. If the specified file does not exist, it will be created. Note that if the file cannot be created, no error message will be generated. If the specified file already exists, it will be overwritten. By default, CONSTRAINED_MIN does not create a report file. TITLE Set this keyword to specify a title for the problem in the CONSTRAINED_MIN report. Example This example has 5 variables {X0, X1, ..., X4}, bounded above and below, a quadratic objective function {G3}, and three quadratic constraints {G0, G1, G2}, with both upper and lower bounds. See the Himmelblau text [7], problem 11. Minimize: G3 = 5.3578547X2X2 + 0.8356891X0X4 + 37.293239X0 - 40792.141 Subject to: 0 < G0 = 85.334407 + 0.0056858X1X4 + 0.0006262X0X3 - 0.0022053X2X4 < 92 90 < G1 = 80.51249 + 0.0071317X1X4 + 0.0029955X0X1 + 0.0021813X2X2 < 110 20 < G2 = 9.300961 + 0.0047026X2X4 + 0.0012547X0X2 + 0.0019085X2X3 < 25 and, 78 < X0 < 102 33 < X1 < 45 27 < X2 < 45 27 < X3 < 45 27 < X4 < 45 This problem is solved starting from X = {78, 33, 27, 27, 27} which is infeasible because constraint G2 is not satisfied at this point. The constraint functions and objective function are evaluated by HMBL11: ; Himmelblau Problem 11 ; 5 variables and 4 functions FUNCTION HMBL11, x g = DBLARR(4) g[0] = 85.334407 + 0.0056858*x[1]*x[4] + 0.0006262*x[0] $ *x[3] - 0.0022053*x[2]*x[4] g[1] = 80.51249 + 0.0071317*x[1]*x[4] + 0.0029955*x[0] $ *x[1] + 0.0021813*x[2]*x[2] g[2] = 9.300961 + 0.0047026*x[2]*x[4] + 0.0012547*x[0]* $ x[2] + 0.0019085*x[2]*x[3] g[3] = 5.3578547*x[2]*x[2] + 0.8356891*x[0]*x[4] $ + 37.293239*x[0] - 40792.141 RETURN, g END ; Example problem for CONSTRAINED_MIN ; Himmelblau Problem 11 ; 5 variables and 3 constraints ; Constraints and objective defined in HMBL11 xbnd = [[78, 33, 27, 27, 27], [102, 45, 45, 45, 45]] gbnd = [[0, 90, 20, 0], [92, 110, 25, 0 ]] nobj = 3 gcomp = 'HMBL11' title = 'IDL: Himmelblau 11' report = 'hmbl11.txt' x = [78, 33, 27, 27, 27] CONSTRAINED_MIN, x, xbnd, gbnd, nobj, gcomp, inform, $ REPORT = report, TITLE = title g = HMBL11(x) ; Print minimized objective function for HMBL11 problem: PRINT, g[nobj] References 1. Lasdon, L.S., Waren, A.D., Jain, A., and Ratner, M., "Design and Testing of a Generalized Reduced Gradient Code for Nonlinear Programming", ACM Transactions on Mathematical Software, Vol. 4, No. 1, March 1978, pp. 34-50. 2. Lasdon, L.S. and Waren, A.D., "Generalized Reduced Gradient Software for Linearly and Nonlinearly Constrained Problems", in "Design and Implementation of Optimization Software", H. Greenberg, ed., Sijthoff and Noordhoff, pubs, 1979. 3. Abadie, J. and Carpentier, J. "Generalization of the Wolfe Reduced Gradient Method to the Case of Nonlinear Constraints", in Optimization, R. Fletcher (ed.), Academic Press London; 1969, pp. 37-47. 4. Murtagh, B.A. and Saunders, M.A. "Large-scale Linearly Constrained Optimization", Mathematical Programming, Vol. 14, No. 1, January 1978, pp. 41-72. 5. Powell, M.J.D., "Restart Procedures for the Conjugate Gradient Method," Mathematical Programming, Vol. 12, No. 2, April 1977, pp. 241-255. 6. Colville, A.R., "A Comparative Study of Nonlinear Programming Codes," I.B.M. T.R. no. 320-2949 (1968). 7. Himmelblau, D.M., Applied Nonlinear Programming, McGraw-Hill Book Co., New York, 1972. 8. Fletcher, R., "A New Approach to Variable Metric Algorithms", Computer Journal, Vol. 13, 1970, pp. 317-322. 9. Smith, S. and Lasdon, L.S., Solving Large Sparse Nonlinear Programs Using GRG, ORSA Journal on Computing, Vol. 4, No. 1,Winter 1992, pp. 1-15. 10. Luenbuerger, David G., Linear and Nonlinear Programming, Second Edition, Addison-Wesley, Reading Massachusetts, 1984. 11. Windward Technologies, GRG2 Users's Guide, 1997. CONTINUE [Previous Routine] [Next Routine] [List of Routines] NAME: CONTINUE The CONTINUE statement provides a convenient way to immediately start the next iteration of the enclosing FOR, WHILE, or REPEAT loop. Note Do not confuse the CONTINUE statement described here with the .CONTINUE executive command. The two constructs are not related, and serve completely different purposes. Note CONTINUE is not allowed within CASE or SWITCH statements. This is in contrast with the C language, which does allow this. For more information on using CONTINUE and other IDL program control statements, see Chapter 11, "Program Control" in Building IDL Applications. Syntax CONTINUE Example This example presents one way (not necessarily the best) to print the even numbers between 1 and 10. FOR I = 1,10 DO BEGIN ; If odd, start next iteration: IF (I AND 1) THEN CONTINUE PRINT, I ENDFOR CONTOUR [Previous Routine] [Next Routine] [List of Routines] NAME: CONTOUR The CONTOUR procedure draws a contour plot from data stored in a rectangular array or from a set of unstructured points. 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 OVERPLOT keyword. Contours can be smoothed by using the MIN_CURVE_SURF function on the contour data before contouring. Using various keywords, described below, it is possible to specify contour levels, labeling, colors, line styles, and other options. CONTOUR draws contours by searching for each contour line and then following the line until it reaches a boundary or closes. Smoothing Contours The MIN_CURVE_SURF function can be used to smoothly interpolate both regularly and irregularly 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. Syntax CONTOUR, Z [, X, Y] [, C_CHARSIZE=value] [, C_CHARTHICK=integer] [, C_COLORS=vector] [, C_LABELS=vector{each element 0 or 1}] [, C_LINESTYLE=vector] [{, /FILL | , /CELL_FILL} | [, C_ANNOTATION=vector_of_strings] [, C_ORIENTATION=degrees] [, C_SPACING=value]] [, C_THICK=vector] [, /CLOSED] [, /DOWNHILL] [, /FOLLOW] [, /IRREGULAR] [, LEVELS=vector] [, NLEVELS=integer{1 to 60}] [, MAX_VALUE=value] [, MIN_VALUE=value] [, /OVERPLOT] [{, /PATH_DATA_COORDS, PATH_FILENAME=string, PATH_INFO=variable, PATH_XY=variable} | , TRIANGULATION=variable] [, /PATH_DOUBLE] [, /XLOG] [, /YLOG] [, /ZAXIS] [, /ZLOG] Graphics Keywords: Accepts all graphics keywords accepted by PLOT except for: LINESTYLE, PSYM, SYMSIZE. See "Graphics Keywords Accepted" on page 235. Arguments Z A one- or 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. If the IRREGULAR keyword is set, X, Y, and Z are treated as vectors. Each point has a value of Zi and a location of (Xi, Yi) This argument is converted to double-precision floating-point before plotting. Plots created with CONTOUR are limited to the range and precision of double-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 coordinate 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 vector, each element of Y specifies the Y coordinate for a row of Z (e.g., Y[0] specifies the Y coordinate 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 coordinate for Zij). Keywords C_ANNOTATION The label to be drawn on each contour. Usually, contours are labeled with their value. This parameter, 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 correspond 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. Note This keyword has no effect if the FILL or CELL_FILL keyword is set (i.e., if the contours are drawn with solid-filled or line-filled polygons). 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 contour 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 variable. This keyword allows the contour label size to be specified directly. Use of this keyword implies use of the FOLLOW keyword. C_CHARTHICK The thickness of the characters used to annotate contour labels. Set this keyword equal to an integer value specifying the line thickness of the vector drawn font characters. This keyword has no effect when used with the hardware drawn fonts. The default value is 1. 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 vector 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 levels. 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 specified, the elements of C_LABELS correspond directly to the levels specified, otherwise, they correspond to the default levels chosen by the CONTOUR procedure. Setting an element of the vector to zero causes that contour label to not be labeled. A nonzero 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 "LINESTYLE" on page 2405 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 levels directly specified in a vector V, with all negative 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 nor 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. CELL_FILL Set this keyword to produce a filled contour plot using a "cell filling" algorithm. Use this keyword instead of FILL when you are drawing filled contours over a map, when you have missing data, or when contours that extend off the edges of the contour plot. CELL_FILL is less efficient than FILL because it makes one or more polygons for each data cell. It also gives poor results when used with patterned (line) fills, because each cell is assigned its own pattern. Otherwise, this keyword operates identically to the FILL keyword, described below. Tip In order for CONTOUR to fill the contours properly when using a map projection, the X and Y arrays (if supplied) must be arranged in increasing order. This ensures that the polygons generated will be in counterclockwise order, as required by the mapping graphics pipeline. Warning Do not draw filled contours over the poles on Cylindrical map projections. In this case, the polar points map to lines on the map, and the interpolation becomes ambiguous, causing errors in filling. One possible work-around is to limit the latitudes to the range of -89.9 degrees to + 89.9 degrees, avoiding the poles. CLOSED Set this keyword to a nonzero value to close contours that intersect the plot boundaries. After a contour hits a boundary, it follows the plot boundary until it connects with its other boundary intersection. Set CLOSED=0 along with PATH_INFO and/or PATH_XY to return path information for contours that are not closed. 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 contours. 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 contours should not be used in these cases. Note If the current graphics device is the Z-buffer, the algorithm used when the FILL keyword is specified will not work when a Z value is also specified with the graphics keyword ZVALUE. In this situation, use the CELL_FILL keyword instead of the FILL keyword. FOLLOW In IDL version 5, CONTOUR always uses a line-following method. The FOLLOW keyword remains available for compatibility with existing code, but is no longer necessary. As in previous versions of IDL, setting FOLLOW will cause CONTOUR to draw contour labels. IRREGULAR Set this keyword to indicate that the input data is irregularly gridded. Setting IRREGULAR is the same as performing an explicit triangulation. That is: CONTOUR, Z, X, Y, /IRREGULAR is the same as TRIANGULATE, X, Y, tri ;Get triangulation CONTOUR, Z, X, Y, TRIANGULATION=tri ISOTROPIC Set this keyword to force the scaling of the X and Y axes to be equal. Note The X and Y axes will be scaled isotropically and then fit within the rectangle defined by the POSITION keyword; one of the axes may be shortened. See "POSITION" on page 2407 for more information. 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 above this value are ignored (i.e., treated as missing data) when contouring. Cells containing one or more corners with values above MAX_VALUE will have no contours drawn through them. Note that the IEEE floating-point value NaN is also treated as missing data. (See "Special Floating-Point Values" in Chapter 17 of Building IDL Applications for more information on IEEE floating-point values.) MIN_VALUE Data points with values less than this value are ignored (i.e., treated as missing data) when contouring. Cells containing one or more corners with values below MIN_VALUE will have no contours drawn through them. Note that the IEEE floating-point value NaN is also treated as missing data. (See "Special Floating-Point Values" in Chapter 17 of Building IDL Applications for more information on IEEE floating-point values.) 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 levels are drawn. NLEVELS should be a positive integer. 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 specify either the values of the contour levels or the number of levels (via the NLEVELS keyword) when using this option, unless geographic mapping coordinates are in effect. PATH_DATA_COORDS Set this keyword to cause the output contour positions to be measured in data units rather than the default normalized units. This keyword is useful only if the PATH_XY or PATH_FILENAME keywords are set. PATH_DOUBLE Set this keyword to indicate that the PATH_FILENAME, PATH_INFO, and PATH_XY keywords should return vertex and contour value information as double- precision floating-point values. The default is to return this information as single- precision floating-point values. PATH_FILENAME Specifies the name of a file to contain the contour positions. If PATH_FILENAME is present, CONTOUR does not draw the contours, but rather, opens the specified file and writes the coordinates of the contours, 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: If the PATH_DOUBLE keyword is not set: {CONTOUR_HEADER, TYPE:0B, HIGH:0B, LEVEL:0, NUM:0L, VALUE:0.0} If the PATH_DOUBLE keyword is set: {CONTOUR_DBL_HEADER, TYPE:0B, HIGH:0B, LEVEL:0, NUM:0L, VALUE:0.0D} The fields are: Field Description 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. If the PATH_DOUBLE keyword is not set, this is a single-precision floating-point value; if the PATH_DOUBLE keyword is set, this is a double- precision floating-point value. Table 7: CONTOUR Fields Following the header in each record are NUM X-coordinate values followed by NUM Y-coordinate values. By default, these values are specified in normalized coordinates unless the PATH_DATA_COORDS keyword is set. 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. To get PATH_INFO and PATH_XY with contours that are not closed, set the CLOSED keyword to 0. 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: If the PATH_DOUBLE keyword is not set: {CONTOUR_PATH_STRUCTURE, TYPE:0B, HIGH_LOW:0B, $ LEVEL:0, N:0L, OFFSET:0L, VALUE:0.0} If the PATH_DOUBLE keyword is set: {COUNTOUR_DBL_PATH_STRUCTURE, TYPE:0B, HIGH_LOW:0B, LEVEL:0, N: 0L, OFFSET:0L, VALUE:0.0D} The fields are: Field Description TYPE A byte that is zero if the contour is open, and one if it is closed. In the present implementation, 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. If the PATH_DOUBLE keyword is not set, this is a single-precision floating-point value; if the PATH_DOUBLE keyword is set, this is a double- precision floating-point value. Table 8: PATH_INFO Fields 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 coordinates of a set of closed polygons defining 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. To get PATH_XY and PATH_INFO with contours that are not closed, set the CLOSED keyword to 0. If PATH_XY is present, CONTOUR does not draw the contours, but rather records the path coordinates in the named array. If the PATH_DOUBLE keyword is not set, the array will contain single-precision floating point values; if the PATH_DOUBLE keyword is set, the array will contain double- precision floating point values. By default, the values in the array are specified in normalized coordinates unless the PATH_DATA_COORDS keyword is set. 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, without gridding. XLOG Set this keyword to specify a logarithmic X axis. YLOG Set this keyword to specify a logarithmic Y axis. ZAXIS Set this keyword to draw a Z axis for the CONTOUR plot. CONTOUR draws no Z axis by default. This keyword is of use only if a three-dimensional transformation is established. GRAPHICS KEYWORDS ACCEPTED [Previous Routine] [Next Routine] [List of Routines] NAME: Graphics Keywords See Appendix C, "Graphics Keywords" for the description of graphics and plotting keywords not listed above. BACKGROUND, CHARSIZE, CHARTHICK, CLIP, COLOR, DATA, DEVICE, FONT, NOCLIP, NODATA, NOERASE, NORMAL, POSITION, SUBTITLE, T3D, THICK, TICKLEN, TITLE, [XYZ]CHARSIZE, [XYZ]GRIDSTYLE, [XYZ]MARGIN, [XYZ]MINOR, [XYZ]RANGE, [XYZ]STYLE, [XYZ]THICK, [XYZ]TICKFORMAT, [XYZ]TICKINTERVAL, [XYZ]TICKLAYOUT, [XYZ]TICKLEN, [XYZ]TICKNAME, [XYZ]TICKS, [XYZ]TICKUNITS, [XYZ]TICKV, [XYZ]TICK_GET, [XYZ]TITLE, ZVALUE. EXAMPLES [Previous Routine] [Next Routine] [List of Routines] NAME: CONTOUR Examples Example 1 This example creates a contour plot with 10 contour levels where every other contour is labeled: ;Create a simple dataset to plot: Z = DIST(100) ;Draw the plot: CONTOUR, Z, NLEVELS=10, /FOLLOW, TITLE='Simple Contour Plot' Example 2 This example shows the use of polygon filling and smoothing. ;Handle TrueColor displays: DEVICE, DECOMPOSED=0 ;Create a surface to contour (2D array of random numbers): A = RANDOMU(seed, 5, 6) ;Smooth the dataset before contouring: B = MIN_CURVE_SURF(A) ;Load discrete colors for contours: TEK_COLOR ;Draw filled contours: CONTOUR, B, /FILL, NLEVELS=5, C_COLOR=INDGEN(5)+2 ;Overplot the contour lines with tickmarks: CONTOUR, B, NLEVELS=5, /DOWNHILL, /OVERPLOT Alternatively, we could draw line-filled contours by replacing the last two commands with: CONTOUR, B, C_ORIENTATION=[0, 22, 45] CONTOUR, B, /OVERPLOT, NLEVELS=5 Example 3 The following example saves the closed path information of a set of contours and plots the result: ; Create a 2D array of random numbers: A = RANDOMU(seed, 8, 10) ; Smooth the dataset before contouring: B = MIN_CURVE_SURF(A) ; Compute contour paths: CONTOUR, B, PATH_XY=xy, PATH_INFO=info FOR I = 0, (N_ELEMENTS(info) - 1 ) DO BEGIN S = [INDGEN(info(I).N), 0] ; Plot the closed paths: PLOTS, xy(*,INFO(I).OFFSET + S ), /NORM ENDFOR Example 4 This example contours 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: ;Make 50 normal X, Y points: x = RANDOMN(seed, 50) y = RANDOMN(seed, 50) ;Make the Gaussian: Z = EXP(-(x^2 + y^2)) ;Get triangulation: TRIANGULATE, X, Y, tri ;Draw the contours: CONTOUR, Z, X, Y, TRIANGULATION = tri See Also IMAGE_CONT, SHADE_SURF, SHOW3, SURFACE CONVERT_COORD [Previous Routine] [Next Routine] [List of Routines] NAME: 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. Warning For devices that support windows, CONVERT_COORD can only provide valid results if a window is open and current. Also, CONVERT_COORD only applies to Direct Graphics devices. Syntax Result = CONVERT_COORD( X [, Y [, Z]] [, /DATA | , /DEVICE | , /NORMAL] [, /DOUBLE][, /T3D] [, /TO_DATA | , /TO_DEVICE | , /TO_NORMAL] ) Arguments X A vector or scalar argument providing the X components of the input coordinates. If only one argument is specified, X must be an array of either two or three vectors (i.e., (2,*) or (3,*)). In this special case, X[0,*] are taken as the X values, X[1,*] are taken as the Y values, and, if present, X[2,*] are taken as the Z values. Y An optional argument providing the Y input coordinate(s). Z An optional argument providing the Z input coordinate(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. DOUBLE Set this keyword to indicate that the returned coordinates should be double-precision. If this keyword is not set, the default is to return single-precision coordinates (unless double-precision arguments are input, in which case the returned coordinates will be double-precision). 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 = t2, along the interval [0, 1] from data coordinates to device coordinates: ; Establish a valid transformation matrix: SURFACE, DIST(20), /SAVE ; Make a vector of X values: X = FINDGEN(11)/10. ; Convert the coordinates. D will be a (3,11) element array: D = CONVERT_COORD(X, 2*X, X^2, /T3D, /TO_DEVICE) See Also CV_COORD CONVOL [Previous Routine] [Next Routine] [List of Routines] NAME: 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 CENTER keyword controls the alignment of the kernel with the array and the ordering of the kernel elements. If CENTER is explicitly set to 0, convolution is performed in the strict mathematical sense, otherwise the kernel is centered over each data point. Syntax Result = CONVOL( Array, Kernel [, Scale_Factor] [, MISSING] [, NAN] [, /CENTER] [, /EDGE_WRAP] [, /EDGE_TRUNCATE]) Using CONVOL Assume R = CONVOL(A, K, S), where A is an n-element vector, K is an m-element vector (m < n), and S is the scale factor. If the CENTER keyword is omitted or set to 1: 1 --- m ­ 1 A K t < n ­ m 2 R if m 2 i = 0 t + i ­ m 2 i t = S 0 otherwise where the value m/2 is determined by integer division. This means that the result of the division is the largest integer value less than or equal to the fractional number. If CENTER is explicitly set to 0: 1 --- m ­ 1 A K ­ R i if t m 1 = 0 t ­ i i t = S 0 otherwise In the two-dimensional, zero CENTER case where A is an m by n-element array, and K is the l by l element kernel; the result R is an m by n-element array: The centered case is similar, except the t-i and u-j subscripts are replaced by t+i-l/2 and u+j-l/2. 1 --- l ­ 1 l ­ 1 A K ­ and u l ­ 1 R i if t l 1 = 0 j = 0 t ­ i, u ­ j i, j t, u = S 0 otherwise 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 that is divided into each resulting value. This argument allows the use of fractional kernel values and avoids overflow with byte or integer arguments. If omitted, a scale factor of 1 is used. Keywords NAN Set this keyword to cause the routine to check for occurrences of the IEEE floating-point value NaN in the input data. Elements with the value NaN are treated as missing data, and are ignored when computing the convolution for neighboring elements. In the Result, missing elements are replaced by the convolution of all other valid points within the kernel. If all points within the kernel are missing, then the result at that point is given by the MISSING keyword. Note that CONVOL should never be called without the NAN keyword if the input array may possibly contain NaN values. MISSING The value to return for elements that contain no valid points within the kernel. The default is the IEEE floating-point value NaN. This keyword is only used if the NAN keyword is set. 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 conventional 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. Note that for the kernel to be centered, it must be symmetric about the point K(FLOOR(m/2), where m is the number of elements in the kernel. EDGE_WRAP Set this keyword to make CONVOL compute the values of elements at the edge of Array by "wrapping" the subscripts of Array at the edge. For example, if CENTER is set to zero: R 1 m ­ 1 t = --- S[ A ] i = 0 ((t­i)mod(n))Ki where n is the number of elements in Array. The mod operator in the formula above is defined as a mod b = a - b * floor(a/b). For example, -1 mod 5 is 4. 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 values of elements at the edge of Array by repeating the subscripts of Array at the edge. For example, if CENTER is set to zero: R 1 m t = --- S A i = 0 ((t­i)>0<(n­1))Ki where n is the number of elements in Array. The "<" and ">" operators in the above formula return the smaller and larger of their operands, respectively. 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-dimensional 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)) See Also BLK_CON COORD2TO3 [Previous Routine] [Next Routine] [List of Routines] NAME: COORD2TO3 The COORD2TO3 function returns a three-element vector containing 3D data coordinates given the normalized X and Y screen coordinates and one of the three data coordinates. Note A valid 3D transform must exist in !P.T or be specified by the PTI keyword. The axis scaling variables, !X.S, !Y.S and !Z.S must be valid. This routine is written in the IDL language. Its source code can be found in the file coord2to3.pro in the lib subdirectory of the IDL distribution. Syntax Result = COORD2TO3( Mx, My, Dim, D0 [, PTI] ) Arguments Mx, My The normalized X and Y screen coordinates. Dim A parameter used to specify which data coordinate is fixed. Use 0 for a fixed X data coordinate, 1 for a fixed Y data coordinate, or 2 for a fixed Z data coordinate. D0 The value of the fixed data coordinate. PTI The inverse of !P.T. If this parameter is not supplied, or set to 0, COORD2TO3 computes the inverse. If this routine is to be used in a loop, the caller should supply PTI for highest efficiency. Example To return the data coordinates of the mouse, fixing the data Z value at 10, enter the commands: ;Make sure a transformation matrix exists. CREATE_VIEW ;Get the normalized mouse coords. CURSOR, X, Y, /NORM ;Print the 3D coordinates. PRINT, COORD2TO3(X, Y, 2, 10.0) See Also CONVERT_COORD, CREATE_VIEW, CV_COORD, SCALE3, T3D CORRELATE [Previous Routine] [Next Routine] [List of Routines] NAME: CORRELATE The CORRELATE function computes the linear Pearson correlation coefficient of two vectors or the correlation matrix of an m x n array. If vectors of unequal lengths are specified, the longer vector is truncated to the length of the shorter vector and a single correlation coefficient is returned. If an m x n array is specified, the result will be an m x m array of linear Pearson correlation coefficients, with the element i,j corresponding to correlation of the ith and jth columns of the input array. Alternatively, this function computes the covariance of two vectors or the covariance matrix of an m x n array. This routine is written in the IDL language. Its source code can be found in the file correlate.pro in the lib subdirectory of the IDL distribution. Syntax Result = CORRELATE( X [, Y] [, /COVARIANCE] [, /DOUBLE] ) Arguments X A vector or an m x n array. X can be integer, single-, or double-precision floating- point. Y An integer, single-, or double-precision floating-point vector. If X is an m x n array, Y should not be supplied. Keywords COVARIANCE Set this keyword to compute the sample covariance rather than the correlation coefficient. DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. Examples Define the data vectors. X = [65, 63, 67, 64, 68, 62, 70, 66, 68, 67, 69, 71] Y = [68, 66, 68, 65, 69, 66, 68, 65, 71, 67, 68, 70] Compute the linear Pearson correlation coefficient of x and y. The result should be 0.702652: PRINT, CORRELATE(X, Y) IDL prints: 0.702652 Compute the covariance of x and y. The result should be 3.66667. PRINT, CORRELATE(X, Y, /COVARIANCE) IDL prints: 3.66667 Define an array with x and y as its columns. A = TRANSPOSE([[X],[Y]]) Compute the correlation matrix. PRINT, CORRELATE(A) IDL prints: 1.00000 0.702652 0.702652 1.00000 See Also A_CORRELATE, C_CORRELATE, M_CORRELATE, P_CORRELATE, R_CORRELATE COS [Previous Routine] [Next Routine] [List of Routines] NAME: COS The periodic function COS returns the trigonometric cosine of X. Syntax Result = COS(X) Arguments X The angle for which the cosine is desired, specified 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 floating-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 structure, 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 See Also ACOS, COSH COSH [Previous Routine] [Next Routine] [List of Routines] NAME: COSH The COSH function returns the hyperbolic cosine of X. Syntax Result = COSH(X) Arguments X The value for which the hyperbolic cosine is desired, specified in radians. If X is double-precision 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) = (eu + e-u) / 2 If X is an array, the result has the same structure, 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 See Also ACOS, COS CRAMER [Previous Routine] [Next Routine] [List of Routines] NAME: CRAMER The CRAMER function solves an n by n linear system of equations using Cramer's rule. This routine is written in the IDL language. Its source code can be found in the file cramer.pro in the lib subdirectory of the IDL distribution. Syntax Result = CRAMER( A, B [, /DOUBLE] [, ZERO=value] ) Arguments A An n by n single- or double-precision floating-point array. B An n-element single- or double-precision floating-point vector. Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. ZERO Use this keyword to set the value of the floating-point zero. A floating-point zero on the main diagonal of a triangular array results in a zero determinant. A zero determinant results in a "Singular matrix" error and stops the execution of CRAMER. For single-precision inputs, the default value is 1.0 × 10-6. For double-precision inputs, the default value is 1.0 × 10-12. Example Define an array A and right-hand side vector B. A = [[ 2.0, 1.0, 1.0], $ [ 4.0, -6.0, 0.0], $ [-2.0, 7.0, 2.0]] B = [3.0, 10.0, -5.0] ;Compute the solution and print. PRINT, CRAMER(A,B) IDL prints: 1.00000 -1.00000 2.00000 See Also CHOLSOL, GS_ITER, LU_COMPLEX, LUSOL, SVSOL, TRISOL CREATE_STRUCT [Previous Routine] [Next Routine] [List of Routines] NAME: 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. Syntax Result = CREATE_STRUCT( [Tag1, Value1, ..., Tagn, Valuen] ) or Result = CREATE_STRUCT( NAME=string, [Tag1, ..., Tagn], Value1, ..., Valuen ) Arguments Tags The structure tag names. Tag names may be specified 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. Tag names must be enclosed in quotes. Note If a tag name contains spaces, CREATE_STRUCT will replace the spaces with underscores. For example, if you specify a tag name of 'my tag', the tag will be created with the name 'my_tag'. 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, enter: p = CREATE_STRUCT('A', 1, 'B', 'xxx') To add the fields "FIRST" and "LAST" to the structure, enter 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}. See Also N_TAGS, TAG_NAMES CREATE_VIEW [Previous Routine] [Next Routine] [List of Routines] NAME: CREATE_VIEW The CREATE_VIEW procedure sets the various system variables required to define a coordinate system and a 3D view. This procedure builds the system viewing matrix (!P.T) in such a way that the correct aspect ratio of the data is maintained even if the display window is not square. CREATE_VIEW also sets the "Data" to "Normal" coordinate conversion factors (!X.S, !Y.S, and !Z.S) so that center of the unit cube will be located at the center of the display window. CREATE_VIEW sets the following IDL system variables: !P.T, !P.T3D, !P.Position, !P.Clip, !P.Region !X.S, !X.Style, !X.Range, !X.Margin !Y.S, !Y.Style, !Y.Range, !Y.Margin, !Z.S, !Z.Style, !Z.Range, !Z.Margin. This routine is written in the IDL language. Its source code can be found in the file create_view.pro in the lib subdirectory of the IDL distribution. Syntax CREATE_VIEW [, AX=value] [, AY=value] [, AZ=value] [, PERSP=value] [, /RADIANS] [, WINX=pixels] [, WINY=pixels] [, XMAX=scalar] [, XMIN=scalar] [, YMAX=scalar] [, YMIN=scalar] [, ZFAC=value] [, ZMAX=scalar] [, ZMIN=scalar] [, ZOOM=scalar or 3-element vector] Arguments This procedure has no required arguments. Keywords AX A floating-point value specifying the orientation (X rotation) of the view. The default is 0.0. AY A floating-point value specifying the orientation (Y rotation) of the view. The default is 0.0. AZ A floating-point value specifying the orientation (Z rotation) of the view. The default is 0.0. PERSP A floating-point value specifying the perspective projection distance. A value of 0.0 indicates an isometric projection (NO perspective). The default is 0.0. RADIANS Set this keyword if AX, AY, and AZ are specified in radians. The default is degrees. WINX A long integer specifying the X size, in pixels, of the window that the view is being set up for. The default is 640. WINY A long integer specifying the Y size, in pixels, of the window that the view is being set up for. The default is 512. XMAX A scalar specifying the maximum data value on the X axis. The default is 1.0. XMIN A scalar specifying the minimum data value on the X axis. The default is 0.0. YMAX A scalar specifying the maximum data value on the Y axis. The default is 1.0. YMIN A scalar specifying the minimum data value on the Y axis. The default is 0.0. ZFAC Set this keyword to a floating-point value to expand or contract the view in the Z dimension. The default is 1.0. ZMAX A scalar specifying the maximum data value on the Z axis. The default is 1.0. ZMIN A scalar specifying the minimum data value on the Z axis. The default is 0.0. ZOOM A floating-point number or 3-element vector specifying the view zoom factor. If zoom is a single value then the view will be zoomed equally in all 3 dimensions. If zoom is a 3-element vector then the view will be scaled zoom[0] in X, zoom[1] in Y, and zoom[2] in Z. The default is 1.0. Example Set up a view to display an iso-surface from volumetric data. First, create some data: vol = FLTARR(40, 50, 30) vol(3:36, 3:46, 3:26) = RANDOMU(S, 34, 44, 24) FOR I = 0, 10 DO vol = SMOOTH(vol, 3) Generate the iso-surface. SHADE_VOLUME, vol, 0.2, polygon_list, vertex_list, /LOW Set up the view. Note that the subscripts into the Vol array range from 0 to 39 in X, 0 to 49 in Y, and 0 to 29 in Z. As such, the 3-D coordinates of the iso-surface (vertex_list) may have the same range. Set XMIN, YMIN, and ZMIN to zero (the default), and set XMAX=39, YMAX=49, and ZMAX=29. WINDOW, XSIZE = 600, YSIZE = 400 CREATE_VIEW, XMAX = 39, YMAX = 49, ZMAX = 29, $ AX = (-60.0), AZ = (30.0), WINX = 600, WINY = 400, $ ZOOM = (0.7), PERSP = (1.0) Display the iso-surface in the specified view. img = POLYSHADE(polygon_list, vertex_list, /DATA, /T3D) TVSCL, img See Also SCALE3, T3D CROSSP [Previous Routine] [Next Routine] [List of Routines] NAME: CROSSP The CROSSP function returns a floating-point vector that is the vector (or cross) product of two 3-element vectors, V1 and V2. Syntax Result = CROSSP(V1, V2) Arguments V1, V2 Three-element vectors. CRVLENGTH [Previous Routine] [Next Routine] [List of Routines] NAME: CRVLENGTH The CRVLENGTH function computes the length of a curve with a tabular representation, Y[i] = F(X[i]). Warning Data that is highly oscillatory requires a sufficient number of samples for an accurate curve length computation. This routine is written in the IDL language. Its source code can be found in the file crvlength.pro in the lib subdirectory of the IDL distribution. Syntax Result = CRVLENGTH( X, Y [, /DOUBLE] ) Arguments X An n-element single- or double-precision floating-point vector. X must contain at least three elements, and values must be specified in ascending order. Duplicate X values will result in a warning message. Y An n-element single- or double-precision floating-point vector. Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. Example ;Define a 21-element vector of X-values: x = [-2.00, -1.50, -1.00, -0.50, 0.00, 0.50, 1.00, 1.50, 2.00, $ 2.50, 3.00, 3.50, 4.00, 4.50, 5.00, 5.50, 6.00, 6.50, $ 7.00, 7.50, 8.00] ;Define a 21-element vector of Y-values: y = [-2.99, -2.37, -1.64, -0.84, 0.00, 0.84, 1.64, 2.37, 2.99, $ 3.48, 3.86, 4.14, 4.33, 4.49, 4.65, 4.85, 5.13, 5.51, $ 6.02, 6.64, 7.37] ;Compute the length of the curve: result = CRVLENGTH(x, y) Print, result IDL prints: 14.8115 See Also INT_TABULATED, PNT_LINE CT_LUMINANCE [Previous Routine] [Next Routine] [List of Routines] NAME: CT_LUMINANCE The CT_LUMINANCE function calculates the luminance of colors. The function returns an array containing the luminance values of the specified colors. If the R, G, and B parameters are not specified, or if R is of integer, byte or long type, the result is a longword array with the same number of elements as the input arguments. Otherwise, the result is a floating-point array with the same number of elements as the input arguments. This routine is written in the IDL language. Its source code can be found in the file ct_luminance.pro in the lib subdirectory of the IDL distribution. Syntax Result = CT_LUMINANCE( [R, G, B] [, BRIGHT=variable] [, DARK=variable] [, /READ_TABLES] ) Arguments R An array representing the red color table. If omitted, the color values from either the COLORS common block, or the current color table are used. G An array representing the green color table. This parameter is optional. B An array representing the blue color table. This parameter is optional. Keywords BRIGHT Set this keyword to a named variable in which the array index of the brightest color is returned. DARK Set this keyword to a named variable in which the array index of the darkest color is returned. READ_TABLES Set this keyword, and don't specify the R, G, and B arguments, to read colors directly from the current colortable (using TVLCT, /GET) instead of using the COLORS common block. See Also GAMMA_CT, STRETCH CTI_TEST [Previous Routine] [Next Routine] [List of Routines] NAME: CTI_TEST The CTI_TEST function constructs a "contingency table" from an array of observed frequencies and tests the hypothesis that the rows and columns are independent using an extension of the chi-square goodness-of-fit test. The result is a two-element vector containing the chi-square test statistic X2 and the one-tailed probability of obtaining a value of X2 or greater. This routine is written in the IDL language. Its source code can be found in the file cti_test.pro in the lib subdirectory of the IDL distribution. Syntax Result = CTI_TEST( Obfreq [, COEFF=variable] [, /CORRECTED] [, CRAMV=variable] [, DF=variable] [, EXFREQ=variable] [, RESIDUAL=variable] ) Arguments Obfreq An m x n array containing observed frequencies. Obfreq can contain either integer, single-, double-precision floating-point values. Keywords COEFF Set this keyword to a named variable that will contain the Coefficient of Contingency. The Coefficient of Contingency is a non-negative scalar, in the interval [0.0, 1.0], which measures the degree of dependence within a contingency table. The larger the value of COEFF, the greater the degree of dependence. CORRECTED Set this keyword to use the "Yate's Correction for Continuity" when computing the Chi-squared test statistic, X2. The Yate's correction always decreases the magnitude of X2. In general, this keyword should be set for small sample sizes. CRAMV Set this keyword to a named variable that will contain Cramer's V. Cramer's V is a non-negative scalar, in the interval [0.0, 1.0], which measures the degree of dependence within a contingency table. DF Set this keyword to a named variable that will contain the number of degrees of freedom used to compute the probability of obtaining the value of the Chi-squared test statistic or greater. DF = (n - 1) * (m - 1) where m and n are the number of columns and rows of the contingency table, respectively. EXFREQ Set this keyword to a named variable that will contain an array of m-columns and n- rows containing expected frequencies. The elements of this array are often referred to as the "cells" of the expected frequencies. The expected frequency of each cell is computed as the product of row and column marginal frequencies divided by the overall total of observed frequencies. RESIDUAL Set this keyword to a named variable that will contain an array of m-columns and n- rows containing signed differences between corresponding cells of observed frequencies and expected frequencies. Example Define a 5-column and 4-row array of observed frequencies. obfreq = [[748, 821, 786, 720, 672], $ [ 74, 60, 51, 66, 50], $ [ 31, 25, 22, 16, 15], $ [ 9, 10, 6, 5, 7]] Test the hypothesis that the rows and columns of "obfreq" contain independent data at the 0.05 significance level. result = CTI_TEST(obfreq, COEFF = coeff) The result should be the two-element vector [14.3953, 0.276181]. The computed value of 0.276181 indicates that there is no reason to reject the proposed hypothesis at the 0.05 significance level. The Coefficient of Contingency returned in the parameter "coeff" (coeff = 0.0584860) also indicates the lack of dependence between the rows and columns of the observed frequencies. Setting the CORRECTED keyword returns the two-element vector [12.0032, 0.445420] and (coeff = 0.0534213) resulting in the same conclusion of independence. See Also CORRELATE, M_CORRELATE, XSQ_TEST CURSOR [Previous Routine] [Next Routine] [List of Routines] NAME: 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 interactive 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 !MOUSE is set to the button status. Each mouse button is assigned a bit in !MOUSE, bit 0 is the left most button, bit 1 the next, etc. See "!MOUSE" on page 2427 for details. 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 widgets. 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 command, DEVICE, GIN_CHARS=6. Syntax CURSOR, X, Y [, Wait | [, /CHANGE | , /DOWN | , /NOWAIT | , /UP | , /WAIT]] [, /DATA | , /DEVICE, | , /NORMAL] 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 Corresponding Value Keyword Action 0 NOWAIT Return immediately. 1 WAIT Return if a button is down. 2 CHANGE Return if a button is pressed, released, or the pointer is moved. 3 DOWN Return when a button down transition is detected. 4 UP Return when a button up transition is detected. Table 9: Values for CURSOR Wait Parameter Keywords CHANGE Set this keyword to wait for pointer movement or button transition within the currently selected window. DATA Set this keyword to return X and Y in data coordinates. DOWN Set this keyword to wait for a button down transition 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 transition 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 coordinates is stored in the variables X and Y. To label the location, enter: XYOUTS, X, Y, 'X marks the spot.', /DEVICE See Also RDPIX, TVCRS, CURSOR_CROSSHAIR, WIDGET_DRAW, !MOUSE CURVEFIT [Previous Routine] [Next Routine] [List of Routines] NAME: CURVEFIT The CURVEFIT function uses a gradient-expansion algorithm to compute a non- linear least squares fit to a user-supplied function with an arbitrary number of parameters. The user-supplied function may be any non-linear function where the partial derivatives are known or can be approximated. Iterations are performed until the chi square changes by a specified amount, or until a maximum number of iterations have been performed. This routine is written in the IDL language. Its source code can be found in the file curvefit.pro in the lib subdirectory of the IDL distribution. Syntax Result = CURVEFIT( X, Y, Weights, A [, Sigma] [, CHISQ=variable] [, /DOUBLE] [, FUNCTION_NAME=string] [, ITER=variable] [, ITMAX=value] [, /NODERIVATIVE] [, TOL=value] ) Return Value CURVEFIT returns a vector of values for the dependent variables, as fitted by the function fit. If A is double-precision or if the DOUBLE keyword is set, calculations are performed in double-precision arithmetic, otherwise they are performed in single- precision arithmetic. Arguments X An n-element vector of independent variables. Y A vector of dependent variables. Y must have the same number of elements as F returned by the user-defined function. Weights For instrumental (Gaussian) weighting, set Weightsi = 1.0/standard_deviation(Yi)2. For statistical (Poisson) weighting, Weightsi = 1.0/Yi. For no weighting, set Weightsi = 1.0. A A vector with as many elements as the number of terms in the user-supplied function, containing the initial estimate for each parameter. On return, the vector A contains the fitted model parameters. Sigma A named variable that will contain a vector of standard deviations for the elements of the output vector A. Keywords CHISQ Set this keyword equal to a named variable that will contain the value of the reduced chi-squared. DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. FUNCTION_NAME Use this keyword to specify the name of the function to fit. If this keyword is omitted, CURVEFIT assumes that the IDL procedure FUNCT is to be used. If FUNCT is not already compiled, IDL compiles the function from the file funct.pro, located in the lib subdirectory of the IDL distribution. FUNCT evaluates the sum of a Gaussian and a second-order polynomial. The function to be fit must be written as an IDL procedure and compiled prior to calling CURVEFIT. The procedure must accept values of X (the independent variable), and A (the fitted function's initial parameter values). It must return values for F (the function's value at X), and optionally PDER (a 2D array of partial derivatives). The return value for F must have the same number of elements as Y. The return value for PDER (if supplied) must be a 2D array with dimensions [N_ELEMENTS(Y), N_ELEMENTS(A)]. See the Example section below for an example function. ITER Set this keyword equal to a named variable that will contain the actual number of iterations performed. ITMAX Set this keyword to specify the maximum number of iterations. The default value is 20. NODERIVATIVE If this keyword is set, the routine specified by the FUNCTION_NAME keyword will not be requested to provide partial derivatives. The partial derivatives will be estimated by CURVEFIT using forward differences. If analytical derivatives are available they should always be used. TOL Use this keyword to specify the desired convergence tolerance. The routine returns when the relative decrease in chi-squared is less than TOL in one iteration. The default value is 1.0 × 10-3. Example Fit a function of the form F(x) = a * exp(b*x) + c to sample pairs contained in arrays X and Y. The partial derivatives are easily computed symbolically: df/da = exp(b*x) df/db = a * x * exp(b*x) df/dc = 1.0 First, define a procedure to return F(x) and the partial derivatives, given X. Note that A is an array containing the values a, b, and c. PRO gfunct, X, A, F, pder bx = EXP(A[1] * X) F = A[0] * bx + A[2] ;If the procedure is called with four parameters, calculate the ;partial derivatives. IF N_PARAMS() GE 4 THEN $ pder = [[bx], [A[0] * X * bx], [replicate(1.0, N_ELEMENTS(X))]] END Compute the fit to the function we have just defined. First, define the independent and dependent variables: X = FLOAT(INDGEN(10)) Y = [12.0, 11.0, 10.2, 9.4, 8.7, 8.1, 7.5, 6.9, 6.5, 6.1] ;Define a vector of weights. weights = 1.0/Y ;Provide an initial guess of the function's parameters. A = [10.0,-0.1,2.0] ;Compute the parameters. yfit = CURVEFIT(X, Y, weights, A, SIGMA, FUNCTION_NAME='gfunct') ;Print the parameters returned in A. PRINT, 'Function parameters: ', A IDL prints: Function parameters: 9.91120 -0.100883 2.07773 Thus, the function that best fits the data is: f (x) = 9.91120(e-0.100883x) + 2.07773 See Also COMFIT, GAUSS2DFIT, GAUSSFIT, LMFIT, POLY_FIT, REGRESS, SFIT, SVDFIT CV_COORD [Previous Routine] [Next Routine] [List of Routines] NAME: CV_COORD The CV_COORD function converts 2D and 3D coordinates between the rectangular, polar, cylindrical, and spherical coordinate systems. This routine is written in the IDL language. Its source code can be found in the file cv_coord.pro in the lib subdirectory of the IDL distribution. Syntax Result = CV_COORD( [, /DEGREES] [, /DOUBLE] [, FROM_CYLIN=cyl_coords | , FROM_POLAR=pol_coords | , FROM_RECT=rect_coords | , FROM_SPHERE=sph_coords] [, /TO_CYLIN | , /TO_POLAR | , /TO_RECT | , /TO_SPHERE] ) Return Value If the value specified in the "FROM_" keyword is double precision, or if the DOUBLE keyword is set, then all calculations are performed in double precision and the returned value is double precision. Otherwise, single precision is used. If none of the "FROM_" keyword are specified, 0 is returned. If none of the "TO_" keywords are specified, the input coordinates are returned. Arguments This function has no required arguments. All data is passed in via keywords. Keywords DEGREES If set, then the input and output coordinates are in degrees (where applicable). Otherwise, the angles are in radians. DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. FROM_CYLIN A vector of the form [angle, radius, z], or a (3, n) array of cylindrical coordinates to convert. FROM_POLAR A vector of the form [angle, radius], or a (2, n) array of polar coordinates to convert. FROM_RECT A vector of the form [x, y] or [x, y, z], or a (2, n) or (3, n) array containing rectangular coordinates to convert. FROM_SPHERE A vector of the form [longitude, latitude, radius], or a (3, n) array of spherical coordinates to convert. TO_CYLIN If set, cylindrical coordinates are returned in a vector of the form [angle, radius, z], or a (3, n) array. TO_POLAR If set, polar coordinates are returned in a vector of the form [angle, radius], or a (2, n) array. TO_RECT If set, rectangular coordinates are returned in a vector of the form [x, y] or [x, y, z], or a (2, n) or (3, n) array. TO_SPHERE If set, spherical coordinates are returned in a vector of the form [longitude, latitude, radius], or a (3, n) array. Examples Convert from spherical to cylindrical coordinates: sph_coord = [[45.0, -60.0, 10.0], [0.0, 0.0, 0.0]] rect_coord = CV_COORD(FROM_SPHERE=sph_coord, /TO_CYLIN, /DEGREES) Convert from rectangular to polar coordinates: rect_coord = [10.0, 10.0] polar_coord = CV_COORD(FROM_RECT=rect_coord, /TO_POLAR) See Also CONVERT_COORD, COORD2TO3, CREATE_VIEW, SCALE3, T3D CVTTOBM [Previous Routine] [Next Routine] [List of Routines] NAME: CVTTOBM The CVTTOBM function converts a byte array in which each byte represents one pixel into a "bitmap byte array" in which each bit represents one pixel. This is useful when creating bitmap labels for buttons created with the WIDGET_BUTTON function. Bitmap byte arrays are monochrome; by default, CVTTOBM converts pixels that are darker than the median value to black and pixels that are lighter than the median value to white. You can supply a different threshold value via the THRESHOLD keyword. Most of IDL's image file format reading functions (READ_BMP, READ_PICT, etc.) return a byte array which must be converted before use as a button label. Note that there is one exception to this rule; the READ_X11_BITMAP routine returns a bitmap byte array that needs no conversion before use. This routine is written in the IDL language. Its source code can be found in the file cvttobm.pro in the lib subdirectory of the IDL distribution. Note IDL supports color bitmaps for button labels. The IDL GUIBuilder has a Bitmap Editor that allows you to create color bitmaps for button labels. The BITMAP keyword to WIDGET_BUTTON specifies that the button label is a color bitmap. Syntax Result = CVTTOBM( Array [, THRESHOLD=value{0 to 255}] ) Arguments Array A 2-dimensional pixel array, one byte per pixel. Keywords THRESHOLD A byte value (or an integer value between 0 and 255) to be used as a threshold value when determining if a particular pixel is black or white. If THRESHOLD is not specified, the threshold is calculated to be the average of the input array. Example The following example creates a bitmap button label from a byte array: ; Create a byte array: image = BYTSCL(DIST(100)) ; Create a widget base: base = WIDGET_BASE(/COLUMN) ; Use CVTTOBM to create a bitmap byte array for a button label: button = WIDGET_BUTTON(base, VALUE = CVTTOBM(image)) ; Realize the widget: WIDGET_CONTROL, base, /REALIZE See Also WIDGET_BUTTON CW_ANIMATE [Previous Routine] [Next Routine] [List of Routines] NAME: CW_ANIMATE The CW_ANIMATE function creates a compound widget that displays an animated sequence of images using off-screen windows knows as pixmaps. The speed and direction of the display can be adjusted using the widget interface. CW_ANIMATE provides the graphical interface used by the XINTERANIMATE procedure, which is the preferred routine for displaying animation sequences in most situations. Use this widget instead of XINTERANIMATE when you need to run multiple instances of the animation widget simultaneously. Note that if more than one animation widget is running, they will have to share resources and will display images more slowly than a single instance of the widget. This routine is written in the IDL language. Its source code can be found in the file cw_animate.pro in the lib subdirectory of the IDL distribution. Syntax Result = CW_ANIMATE( Parent, Sizex, Sizey, Nframes [, /NO_KILL] [, OPEN_FUNC=string] [, PIXMAPS=vector] [, /TRACK] [, UNAME=string] [, UVALUE=value] ) Return Value This function returns the widget ID of the newly-created animation widget. Using CW_ANIMATE Unlike XINTERANIMATE, using the CW_ANIMATE widget requires calls to two separate procedures, CW_ANIMATE_LOAD and CW_ANIMATE_RUN, to load the images to be animated and to run the animation. Alternatively, you can supply a vector of pre-existing pixmap window IDs, eliminating the need to use CW_ANIMATE_LOAD. The vector of pixmaps is commonly obtained from a call to CW_ANIMATE_GETP applied to a previous animation widget. Once the images are loaded, they are displayed by copying the images from the pixmap or buffer to the visible draw widget. See the documentation for CW_ANIMATE_LOAD, CW_ANIMATE_RUN, and CW_ANIMATE_GETP for more information. The only event returned by CW_ANIMATE indicates that the user has clicked on the "End Animation" button. The parent application should use this as a signal to kill the animation widget via WIDGET_CONTROL. When the widget is destroyed, the pixmaps used in the animation are destroyed as well, unless they were saved by a call to CW_ANIMATE_GETP. See the animation widget's help file (available by clicking the "Help" button on the widget) for more information about the widget's controls. Arguments Parent The widget ID of the parent widget. Sizex The width of the displayed image, in pixels. Sizey The height of the displayed image, in pixels Nframes The number of frames in the animation sequence. Keywords NO_KILL Set this keyword to omit the "End Animation" button from the animation widget. OPEN_FUNC Set this keyword equal to a scalar string specifying the name of a user-written function that loads animation data. If a function is specified, an "Open ..." button is added to the animation widget. PIXMAPS Use this keyword to provide the animation widget with a vector of pre-existing pixmap (off screen window) IDs. This vector is usually obtained from a call to CW_ANIMATE_GETP applied to a previous animation widget. TRACK Set this keyword to cause the frame slider to track the frame number of the currently- displayed frame. UNAME Set this keyword to a string that can be used to identify the widget in your code. You can associate a name with each widget in a specific hierarchy, and then use that name to query the widget hierarchy and get the correct widget ID. To query the widget hierarchy, use the WIDGET_INFO function with the FIND_BY_UNAME keyword. The UNAME should be unique to the widget hierarchy because the FIND_BY_UNAME keyword returns the ID of the first widget with the specified name. UVALUE The "user value" to be assigned to the widget. Keywords to WIDGET_CONTROL and WIDGET_INFO The widget ID returned by most compound widgets is actually the ID of the compound widget's base widget. This means that many keywords to the WIDGET_CONTROL and WIDGET_INFO routines that affect or return information on base widgets can be used with compound widgets. See "Compound Widgets" in Chapter 22 of Building IDL Applications for a more complete discussion of controlling compound widgets using WIDGET_CONTROL and WIDGET_INFO. Widget Events Returned by the CW_ANIMATE Widget The only event returned by this widget indicates that the user has pressed the DONE button. The parent application should use this as a signal to kill the animation widget via WIDGET_CONTROL. Example Assume the following event handler procedure exists: PRO EHANDLER, EV WIDGET_CONTROL, /DESTROY, EV.TOP end Tip If you wish to create this event handler starting from the IDL command prompt, remember to begin with the .RUN command. Enter the following commands to open the file ABNORM.DAT (a series of images of a human heart) and load the images it contains into an array H. OPENR, 1, FILEPATH('abnorm.dat', SUBDIR = ['examples','data']) H = BYTARR(64, 64, 16) READU, 1, H CLOSE, 1 H = REBIN(H, 128, 128, 16) Create an instance of the animation widget and load the frames. Note that because the animation widget is realized before the call to CW_ANIMATE_LOAD, the frames are displayed as they are loaded. This provides the user with an indication of how things are progressing. base = WIDGET_BASE(TITLE = 'Animation Widget') animate = CW_ANIMATE(base, 128, 128, 16) WIDGET_CONTROL, /REALIZE, base FOR I=0,15 DO CW_ANIMATE_LOAD, animate, FRAME=I, IMAGE=H[*,*,I] Save the pixmap window IDs for future use: CW_ANIMATE_GETP, animate, pixmap_vect Start the animation: CW_ANIMATE_RUN, animate XMANAGER, 'CW_ANIMATE Demo', base, EVENT_HANDLER = 'EHANDLER' Pressing the "End Animation" button kills the application. Figure 5: The animation interface created by CW_ANIMATE See Also CW_ANIMATE_LOAD, CW_ANIMATE_RUN, CW_ANIMATE_GETP, XINTERANIMATE CW_ANIMATE_GETP [Previous Routine] [Next Routine] [List of Routines] NAME: CW_ANIMATE_GETP The CW_ANIMATE_GETP procedure gets a copy of the vector of pixmap window IDs being used by a CW_ANIMATE animation widget. If this routine is called, CW_ANIMATE does not destroy the pixmaps when it is destroyed. You can then provide the pixmaps to a later instance of CW_ANIMATE to re-use them, skipping the pixmap creation and rendering step (CW_ANIMATE_LOAD). CW_ANIMATE provides the graphical interface used by the XINTERANIMATE procedure, which is the preferred routine for displaying animation sequences in most situations. Use this widget instead of XINTERANIMATE when you need to run multiple instances of the animation widget simultaneously. Note that if more than one animation widget is running, they will have to share resources and will display images more slowly than a single instance of the widget. This routine is written in the IDL language. Its source code can be found in the file cw_animate.pro in the lib subdirectory of the IDL distribution. Syntax CW_ANIMATE_GETP, Widget, Pixmaps [, /KILL_ANYWAY] Arguments Widget The widget ID of the animation widget (created with CW_ANIMATE) that contains the pixmaps. Pixmaps A named variable that will contain a vector of the window IDs of the pixmap windows. Keywords KILL_ANYWAY Set this keyword to ensure that the pixmaps are destroyed anyway when CW_ANIMATE exits, despite the fact that CW_ANIMATE_GETP has been called. Example See "CW_ANIMATE" on page 276. See Also CW_ANIMATE, CW_ANIMATE_LOAD, CW_ANIMATE_RUN, XINTERANIMATE CW_ANIMATE_LOAD [Previous Routine] [Next Routine] [List of Routines] NAME: CW_ANIMATE_LOAD The CW_ANIMATE_LOAD procedure creates an array of pixmaps which are loaded into a CW_ANIMATE compound widget. CW_ANIMATE provides the graphical interface used by the XINTERANIMATE procedure, which is the preferred routine for displaying animation sequences in most situations. Use this widget instead of XINTERANIMATE when you need to run multiple instances of the animation widget simultaneously. Note that if more than one animation widget is running, they will have to share resources and will display images more slowly than a single instance of the widget. This routine is written in the IDL language. Its source code can be found in the file cw_animate.pro in the lib subdirectory of the IDL distribution. Syntax CW_ANIMATE_LOAD, Widget [, /CYCLE] [, FRAME=value{0 to NFRAMES}] [, IMAGE=value] [, /ORDER] [, WINDOW=[window_num [, X0, Y0, Sx, Sy]]] [, XOFFSET=pixels] [, YOFFSET=pixels] Arguments Widget The widget ID of the animation widget (created with CW_ANIMATE) into which the image should be loaded. Keywords CYCLE Set this keyword to cause the animation to cycle. Normally, frames are displayed going either forward or backward. If CYCLE is set, the animation reverses direction after the last frame in either direction is displayed. FRAME The frame number to be loaded. This is a value between 0 and NFRAMES. If not supplied, frame 0 is loaded. IMAGE The image to be loaded. ORDER Set this keyword to display images from the top down instead of the default bottom up. This keyword is only used when loading images with the IMAGE keyword. WINDOW When this keyword is specified, an image is copied from an existing window to the animation pixmap. Under some windowing systems, this technique is much faster than reading from the display and then loading with the IMAGE keyword. The value of this parameter is either an IDL window number (in which case the entire window is copied), or a vector containing the window index and the rectangular bounds of the area to be copied. For example: WINDOW = [Window_Number, X0, Y0, Sx, Sy] XOFFSET The horizontal offset, in pixels from the left of the frame, of the image in the destination window. YOFFSET The vertical offset, in pixels from the bottom of the frame, of the image in the destination window. Example See the documentation for CW_ANIMATE for an example using this procedure. Note that if the widget is realized before calls to CW_ANIMATE_LOAD, the frames are displayed as they are loaded. This provides the user with an indication of how things are progressing. See Also CW_ANIMATE, CW_ANIMATE_GETP, CW_ANIMATE_RUN, XINTERANIMATE CW_ANIMATE_RUN [Previous Routine] [Next Routine] [List of Routines] NAME: CW_ANIMATE_RUN The CW_ANIMATE_RUN procedure displays a series of images that have been loaded into a CW_ANIMATE compound widget by a call to CW_ANIMATE_LOAD. CW_ANIMATE provides the graphical interface used by the XINTERANIMATE procedure, which is the preferred routine for displaying animation sequences in most situations. Use this widget instead of XINTERANIMATE when you need to run multiple instances of the animation widget simultaneously. Note that if more than one animation widget is running, they will have to share resources and will display images more slowly than a single instance of the widget. This routine is written in the IDL language. Its source code can be found in the file cw_animate.pro in the lib subdirectory of the IDL distribution. Syntax CW_ANIMATE_RUN, Widget [, Rate{0 to 100}] [, NFRAMES=value] [, /STOP] Arguments Widget The widget ID of the animation widget (created with CW_ANIMATE) that will display the animation. Rate A value between 0 and 100 that represents the speed of the animation as a percentage of the maximum display rate. The fastest animation has a value of 100 and the slowest has a value of 0. The default animation rate is 100. The animation rate can also be adjusted after the animation has begun by changing the value of the "Animation Speed" slider. Keywords NFRAMES Set this keyword equal to the number of frames to animate. This number must be less than or equal to the Nframes argument to CW_ANIMATE. STOP If this keyword is set, the animation is stopped. Example See "CW_ANIMATE" on page 276. See Also CW_ANIMATE, CW_ANIMATE_GETP, CW_ANIMATE_LOAD, XINTERANIMATE CW_ARCBALL [Previous Routine] [Next Routine] [List of Routines] NAME: CW_ARCBALL The CW_ARCBALL function creates a compound widget for intuitively specifying three-dimensional orientations. The user drags a simulated track-ball with the mouse to interactively obtain arbitrary rotations. Sequences of rotations may be cascaded. The rotations may be unconstrained (about any axis), constrained to the view X, Y, or Z axes, or constrained to the object's X, Y, or Z axis. This widget is based on "ARCBALL: A User Interface for Specifying Three- Dimensional Orientation Using a Mouse," by Ken Shoemake, Computer Graphics Laboratory, University of Pennsylvania, Philadelphia, PA 19104. This widget can generate any rotation about any axis. Note, however, that not all rotations are compatible with the IDL SURFACE procedure, which is restricted to rotations that project the object Z axis parallel to the view Y axis. This routine is written in the IDL language. Its source code can be found in the file cw_arcball.pro in the lib subdirectory of the IDL distribution. Syntax Result = CW_ARCBALL( Parent [, COLORS=array] [, /FRAME] [, LABEL=string] [, RETAIN={0 | 1 | 2}] [, SIZE=pixels] [, /UPDATE] [, UNAME=string] [, UVALUE=value] [, VALUE=array] ) Return Value This function returns the widget ID of the newly-created ARCBALL widget. Using CW_ARCBALL Use the command: WIDGET_CONTROL, id, GET_VALUE = matrix to return the current 3x3 rotation matrix in the variable matrix. You can set the arcball to new rotation matrix using the command: WIDGET_CONTROL, id, SET_VALUE = matrix after the widget is initially realized. Arguments Parent The widget ID of the parent widget. Keywords COLORS A 6-element array containing the color indices to be used. * Colors[0] = view axis color, * Colors[1] = object axis color, * Colors[2] = XZ plane +Y side (body top) color, * Colors[3] = YZ plane (fin) color, * Colors[4] = XZ plane -Y side (body bottom), * Colors[5] = background color. For devices that are using indexed color (i.e., DECOMPOSED=0), the default value for COLORS is [1,7,2,3,7,0], which yields good colors with the TEK_COLOR table: (white, yellow, red, green, yellow, black). For devices that are using decomposed color (i.e., DECOMPOSED=1), the default value is an array of corresponding decomposed (rather than indexed) colors: (white, yellow, red, green, yellow, black). For more information on decomposed color, refer to the DECOMPOSED keyword to the DEVICE routine. FRAME Set this keyword to draw a frame around the widget. LABEL Set this keyword to a string containing the widget's label. RETAIN Set this keyword to zero, one, or two to specify how backing store should be handled for the draw widget. RETAIN=0 specifies no backing store. RETAIN=1 requests that the server or window system provide backing store. RETAIN=2 specifies that IDL provide backing store directly. See "Backing Store" on page 2351 for details. SIZE The size of the square drawable area containing the arcball, in pixels. The default is 192. UPDATE Set this keyword to cause the widget will send an event each time the mouse button is released after a drag operation. By default, events are only sent when the "Update" button is pressed. UNAME Set this keyword to a string that can be used to identify the widget in your code. You can associate a name with each widget in a specific hierarchy, and then use that name to query the widget hierarchy and get the correct widget ID. To query the widget hierarchy, use the WIDGET_INFO function with the FIND_BY_UNAME keyword. The UNAME should be unique to the widget hierarchy because the FIND_BY_UNAME keyword returns the ID of the first widget with the specified name. UVALUE The "user value" to be assigned to the widget. VALUE Set this keyword to a 3 x 3 array that will be the initial value for the rotation matrix. VALUE must be a valid rotation matrix (no translation or perspective) where TRANSPOSE(VALUE) = INVERSE(VALUE). This can be the upper-left corner of !P.T after executing the command T3D, /RESET, ROTATE = [x,y,z]. The default is the identity matrix. Keywords to WIDGET_CONTROL and WIDGET_INFO The widget ID returned by most compound widgets is actually the ID of the compound widget's base widget. This means that many keywords to the WIDGET_CONTROL and WIDGET_INFO routines that affect or return information on base widgets can be used with compound widgets. In addition, you can use the GET_VALUE and SET_VALUE keywords to WIDGET_CONTROL to obtain or set the 3 x 3 rotation matrix in the arcball widget. See "Compound Widgets" in Chapter 22 of Building IDL Applications for a more complete discussion of controlling compound widgets using WIDGET_CONTROL and WIDGET_INFO. Widget Events Returned by the CW_ARCBALL Widget Arcball widgets generate event structures with the following definition: event = {ID:0L, TOP:0L, HANDLER:0L, VALUE:fltarr(3,3) } The VALUE field contains the 3 x 3 array representing the new rotation matrix. Example See the procedure ARCBALL_TEST, contained in the cw_arcball.pro file. To test CW_ARCBALL, enter the following commands: .RUN cw_arcball ARCBALL_TEST This results in the following: Figure 6: The CW_ARCBALL widget. See Also CREATE_VIEW, SCALE3, T3D CW_BGROUP [Previous Routine] [Next Routine] [List of Routines] NAME: CW_BGROUP The CW_BGROUP function creates a widget base of buttons. It handles the details of creating the proper base (standard, exclusive, or non-exclusive) and filling in the desired buttons. Events for the individual buttons are handled transparently, and a CW_BGROUP event returned. This event can return any one of the following: * the index of the button within the base, * the widget ID of the button, * the name of the button, * an arbitrary value taken from an array of user values. Only buttons with textual names are handled by this widget. Bitmaps are not understood. This routine is written in the IDL language. Its source code can be found in the file cw_bgroup.pro in the lib subdirectory of the IDL distribution. Syntax Result = CW_BGROUP( Parent, Names [, BUTTON_UVALUE=array] [, COLUMN=value] [, EVENT_FUNC=string] [{, /EXCLUSIVE | , /NONEXCLUSIVE} | [, SPACE=pixels] [, XPAD=pixels] [, YPAD=pixels]] [, FONT=font] [, FRAME=width] [, IDS=variable] [, /LABEL_LEFT | , /LABEL_TOP] [, /MAP] [, /NO_RELEASE] [, /RETURN_ID | , /RETURN_INDEX | , /RETURN_NAME] [, ROW=value] [, /SCROLL] [, X_SCROLL_SIZE=width] [, Y_SCROLL_SIZE=height] [, SET_VALUE=value] [, UNAME=string] [, UVALUE=value] [, XOFFSET=value] [, XSIZE=width] [, YOFFSET=value] [, YSIZE=value] ) Return Value This function returns the widget ID of the newly-created button group widget. Arguments Parent The widget ID of the parent widget. Names A string array, one string per button, giving the name of each button. Keywords BUTTON_UVALUE An array of user values to be associated with each button and returned in the event structure. If this keyword is set, the user values are always returned, even if the any of the RETURN_ID, RETURN_INDEX, or RETURN_NAME keywords are set. COLUMN Buttons will be arranged in the number of columns specified by this keyword. EVENT_FUNC A string containing the name of a function to be called by the WIDGET_EVENT function when an event arrives from a widget in the widget hierarchy rooted at the newly-created widget. This function is called with the return value structure whenever a button is pressed, and follows the conventions for user-written event functions. EXCLUSIVE Set this keyword to cause buttons to be placed in an exclusive base, in which only one button can be selected at a time. FONT The name of the font to be used for the button titles. The font specified is a "device font" (an X Windows font on Motif systems; a TrueType or PostScript font on Windows or Macintosh systems). See "About Device Fonts" on page 2482 for details on specifying names for device fonts. If this keyword is omitted, the default font is used. FRAME Specifies the width of the frame to be drawn around the base. IDS A named variable in which the button IDs will be stored, as a longword vector. LABEL_LEFT Creates a text label to the left of the buttons. LABEL_TOP Creates a text label above the buttons. MAP Set this keyword to cause the base to be mapped when the widget is realized (the default). NONEXCLUSIVE Set this keyword to cause buttons to be placed in an non-exclusive base, in which any number of buttons can be selected at once. NO_RELEASE If set, button release events will not be returned. RETURN_ID Set this keyword to return the widget ID of the button in the VALUE field of returned events. This keyword is ignored if the BUTTON_UVALUE keyword is set. RETURN_INDEX Set this keyword to return the zero-based index of the button within the base in the VALUE field of returned events. This keyword is ignored if the BUTTON_UVALUE keyword is set. THIS IS THE DEFAULT. RETURN_NAME Set this keyword to return the name of the button within the base in the VALUE field of returned events. This keyword is ignored if the BUTTON_UVALUE keyword is set. ROW Buttons will be arranged in the number of rows specified by this keyword. SCROLL If set, the base will include scroll bars to allow viewing a large base through a smaller viewport. SET_VALUE Allows changing the current state of toggle buttons (i.e., exclusive and nonexclusive groups of buttons). The behavior of SET_VALUE differs between EXCLUSIVE and NONEXCLUSIVE CW_BGROUP widgets. With EXCLUSIVE CW_BGROUP widgets, the argument to SET_VALUE is the id of the widget to be turned on. With NONEXCLUSIVE CW_BGROUP widgets the argument to SET_VALUE should be an array of on/off flags for the array of buttons. SPACE The space, in pixels, to be left around the edges of a row or column major base. This keyword is ignored if EXCLUSIVE or NONEXCLUSIVE are specified. UNAME Set this keyword to a string that can be used to identify the widget in your code. You can associate a name with each widget in a specific hierarchy, and then use that name to query the widget hierarchy and get the correct widget ID. To query the widget hierarchy, use the WIDGET_INFO function with the FIND_BY_UNAME keyword. The UNAME should be unique to the widget hierarchy because the FIND_BY_UNAME keyword returns the ID of the first widget with the specified name. UVALUE The "user value" to be assigned to the widget. XOFFSET The X offset of the widget relative to its parent. XPAD The horizontal space, in pixels, between children of a row or column major base. This keyword is ignored if EXCLUSIVE or NONEXCLUSIVE are specified. XSIZE The width of the base. X_SCROLL_SIZE The width of the viewport if SCROLL is specified. YOFFSET The Y offset of the widget relative to its parent. YPAD The vertical space, in pixels, between children of a row or column major base. This keyword is ignored if EXCLUSIVE or NONEXCLUSIVE are specified. YSIZE The height of the base. Y_SCROLL_SIZE The height of the viewport if SCROLL is specified. KEYWORDS TO WIDGET_CONTROL AND WIDGET_INFO [Previous Routine] [Next Routine] [List of Routines] NAME: Keywords to WIDGET_CONTROL and WIDGET_INFO The widget ID returned by most compound widgets is actually the ID of the compound widget's base widget. This means that many keywords to the WIDGET_CONTROL and WIDGET_INFO routines that affect or return information on base widgets can be used with compound widgets. In addition, you can use the GET_VALUE and SET_VALUE keywords to WIDGET_CONTROL to obtain or set the value of the button group. The values for different types of CW_BGROUP widgets is shown in the table below: Type Value normal None exclusive Index of currently set button non-exclusive Vector indicating the position of each button (1-set, 0-unset) Table 10: Button Group Values See "Compound Widgets" in Chapter 22 of Building IDL Applications for a more complete discussion of controlling compound widgets using WIDGET_CONTROL and WIDGET_INFO. WIDGET EVENTS RETURNED BY THE CW_BGROUP WIDGET [Previous Routine] [Next Routine] [List of Routines] NAME: Widget Events Returned by the CW_BGROUP Widget Button Group widgets generates event structures with the following definition: event = {ID:0L, TOP:0L, HANDLER:0L, SELECT:0, VALUE:0 } The SELECT field is passed through from the button event. VALUE is either the INDEX, ID, NAME, or BUTTON_UVALUE of the button, depending on how the widget was created. CW_CLR_INDEX [Previous Routine] [Next Routine] [List of Routines] NAME: CW_CLR_INDEX The CW_CLR_INDEX function creates a compound widget for the selection of a color index. A horizontal color bar is displayed. Clicking on the bar sets the color index. This routine is written in the IDL language. Its source code can be found in the file cw_clr_index.pro in the lib subdirectory of the IDL distribution. Syntax Result = CW_CLR_INDEX( Parent [, COLOR_VALUES=vector | [, NCOLORS=value] [, START_COLOR=value]] [, EVENT_FUNC=`function_name'] [, /FRAME] [, LABEL=string] [, UNAME=string] [, UVALUE=value] [, VALUE=value] [, XSIZE=pixels] [, YSIZE=pixels] ) Return Value This function returns the widget ID of the newly-created color index widget. Arguments Parent The widget ID of the parent widget. Keywords COLOR_VALUES A vector of color indices containing the colors to be displayed in the color bar. If omitted, NCOLORS and START_COLOR specify the range of color indices. EVENT_FUNC A string containing the name of a function to be called by the WIDGET_EVENT function when an event arrives from a widget in the widget hierarchy rooted at the newly-created widget. This function is called with the return value structure whenever a button is pressed, and follows the conventions for user-written event functions. FRAME If set, a frame will be drawn around the widget. LABEL A text label that appears to the left of the color bar. NCOLORS The number of colors to place in the color bar. The default is !D.N_COLORS. START_COLOR Set this keyword to the starting color index, placed at the left of the bar. UNAME Set this keyword to a string that can be used to identify the widget in your code. You can associate a name with each widget in a specific hierarchy, and then use that name to query the widget hierarchy and get the correct widget ID. To query the widget hierarchy, use the WIDGET_INFO function with the FIND_BY_UNAME keyword. The UNAME should be unique to the widget hierarchy because the FIND_BY_UNAME keyword returns the ID of the first widget with the specified name. UVALUE The "user value" to be assigned to the widget. VALUE Set this keyword to the index of the color that is to be initially selected. The default is the START_COLOR. XSIZE The width of the color bar in pixels. The default is 192. YSIZE The height of the color bar in pixels. The default is 12. Keywords to WIDGET_CONTROL and WIDGET_INFO The widget ID returned by most compound widgets is actually the ID of the compound widget's base widget. This means that many keywords to the WIDGET_CONTROL and WIDGET_INFO routines that affect or return information on base widgets can be used with compound widgets. In addition, you can use the GET_VALUE and SET_VALUE keywords to WIDGET_CONTROL to obtain or set the value of the color selection widget. The value of a CW_CLR_INDEX widget is the index of the color selected. See "Compound Widgets" in Chapter 22 of Building IDL Applications for a more complete discussion of controlling compound widgets using WIDGET_CONTROL and WIDGET_INFO. Widget Events Returned by the CW_CLR_INDEX Widget This widget generates event structures with the following definition: Event = {CW_COLOR_INDEX, ID: base, TOP: ev.top, HANDLER: 0L, VALUE:c} The VALUE field is the color index selected. See Also CW_COLORSEL, XLOADCT, XPALETTE CW_COLORSEL [Previous Routine] [Next Routine] [List of Routines] NAME: CW_COLORSEL The CW_COLORSEL function creates a compound widget that displays all the colors in the current colormap in a 16 x 16 (320 x 320 pixels) grid. To select a color index, the user moves the mouse pointer over the desired color square and presses any mouse button. Alternatively, the color index can be selected by moving one of the three sliders provided around the grid. This routine is written in the IDL language. Its source code can be found in the file cw_colorsel.pro in the lib subdirectory of the IDL distribution. Using CW_COLORSEL The command: WIDGET_CONTROL, widgetID, SET_VALUE = -1 informs the widget to initialize itself and redraw. It should be called when any of the following happen: * the widget is realized, * the widget needs redrawing, * the brightest or darkest color has changed. To set the current color index, use the command: WIDGET_CONTROL, widgetID, SET_VALUE = index To retrieve the current color index and store it in the variable var, use the command: WIDGET_CONTROL, widgetID, GET_VALUE = var Syntax Result = CW_COLORSEL( Parent [, /FRAME] [, UNAME=string] [, UVALUE=value] [, XOFFSET=value] [, YOFFSET=value] ) Return Value This function returns the widget ID of the newly-created color index widget. Arguments Parent The widget ID of the parent widget. Keywords FRAME If set, a frame is drawn around the widget. UNAME Set this keyword to a string that can be used to identify the widget in your code. You can associate a name with each widget in a specific hierarchy, and then use that name to query the widget hierarchy and get the correct widget ID. To query the widget hierarchy, use the WIDGET_INFO function with the FIND_BY_UNAME keyword. The UNAME should be unique to the widget hierarchy because the FIND_BY_UNAME keyword returns the ID of the first widget with the specified name. UVALUE The "user value" to be assigned to the widget. XOFFSET The X offset position YOFFSET The Y offset position Widget Events Returned by the CW_COLORSEL Widget This widget generates event structures with the following definition: Event = {COLORSEL_EVENT, ID: base, TOP: ev.top, HANDLER: 0L, VALUE:c} The VALUE field is the color index selected. See Also CW_CLR_INDEX, XLOADCT, XPALETTE CW_DEFROI [Previous Routine] [Next Routine] [List of Routines] NAME: CW_DEFROI The CW_DEFROI function creates a compound widget that allows the user to define a region of interest within a widget draw window. Warning This is a modal widget. No other widget applications will be responsive while this widget is in use. Also, since CW_DEFROI has its own event-handling loop, it should not be created as a child of a modal base. This routine is written in the IDL language. Its source code can be found in the file cw_defroi.pro in the lib subdirectory of the IDL distribution. Syntax Result = CW_DEFROI( Draw [, IMAGE_SIZE=vector] [, OFFSET=vector] [, /ORDER] [, /RESTORE] [, ZOOM=vector] ) Return Value The is function returns an array of subscripts defining the region. If no region is defined, the scalar -1 is returned. Arguments Draw The widget ID of draw window in which to draw the region. Note that the draw window must have both BUTTON and MOTION events enabled (see WIDGET_DRAW for more information). Keywords IMAGE_SIZE The size of the underlying array, expressed as a two element vector: [columns, rows]. Default is the size of the draw window divided by the value of ZOOM. OFFSET The offset of lower left corner of image within the draw window. Default = [0,0]. ORDER Set this keyword to return inverted subscripts, as if the array were output from top to bottom. RESTORE Set this keyword to restore the draw window to its previous appearance on exit. Otherwise, the regions remain on the drawable. ZOOM If the image array was expanded (using REBIN, for example) specify this two element vector containing the expansion factor in X and Y. Default = [1,1]. Both elements of ZOOM must be integers. Widget Events Returned by the CW_DEFROI Widget Region definition widgets do not return an event structure. Example The following two procedures create a region-of-interest widget and its event handler. Create a file containing the program code using a text editor and compile using the .RUN command, or type .RUN at the IDL prompt and enter the lines interactively. First, create the event handler: PRO test_event, ev ; The common block holds variables that are shared between the ; routine and its event handler: COMMON T, draw, dbutt, done, image ; Define what happens when you click the "Draw ROI" button: IF ev.id EQ dbutt THEN BEGIN ; The ROI definition will be stored in the variable Q: Q = CW_DEFROI(draw) IF (Q[0] NE -1) then BEGIN ; Show the size of the ROI definition array: HELP, Q ; Duplicate the original image. image2 = image ; Set the points in the ROI array Q equal to a single ; color value: image2(Q)=!P.COLOR-1 ; Get the window ID of the draw widget: WIDGET_CONTROL, draw, GET_VALUE=W ; Set the draw widget as the current graphics window: WSET, W ; Load the image plus the ROI into the draw widget: TV, image2 ENDIF ENDIF ; Define what happens when you click the "Done" button: IF ev.id EQ done THEN WIDGET_CONTROL, ev.top, /DESTROY END Next, create a draw widget that can call CW_DEFROI. Note that you must specify both button events and motion events when creating the draw widget, if it is to be used with CW_DEFROI. PRO test COMMON T, draw, dbutt, done, image ; Create a base to hold the draw widget and buttons: base = WIDGET_BASE(/COLUMN) ; Create a draw widget that will return both button and ; motion events: draw = WIDGET_DRAW(base, XSIZE=256, YSIZE=256, /BUTTON, /MOTION) dbutt = WIDGET_BUTTON(base, VALUE='Draw ROI') done = WIDGET_BUTTON(base, VALUE='Done') WIDGET_CONTROL, base, /REALIZE ; Get the widget ID of the draw widget: WIDGET_CONTROL, draw, GET_VALUE=W ; Set the draw widget as the current graphics window: WSET, W ; Create an original image: image = BYTSCL(SIN(DIST(256))) ; Display the image in the draw widget: TV, image ; Start XMANAGER: XMANAGER, "test", base END This results in the following: Figure 7: The Region of Interest Definition Widget See Also DEFROI CW_FIELD [Previous Routine] [Next Routine] [List of Routines] NAME: CW_FIELD The CW_FIELD function creates a widget data entry field. The field consists of a label and a text widget. CW_FIELD can create string, integer, or floating-point fields. The default is an editable string field. This routine is written in the IDL language. Its source code can be found in the file cw_field.pro in the lib subdirectory of the IDL distribution. Syntax Result = CW_FIELD( Parent [, TEXT_FRAME] [, /ALL_EVENTS] [, /COLUMN] [, FIELDFONT=font] [, /FLOATING | , /INTEGER | , /LONG | , /STRING] [, FONT=string] [, FRAME=pixels] [, /NOEDIT] [, /RETURN_EVENTS] [, /ROW] [, /TEXT_FRAME] [, TITLE=string] [, UNAME=string] [, UVALUE=value] [, VALUE=value] [, XSIZE=characters] [, YSIZE=lines] ) Return Value This function returns the widget ID of the newly-created field widget. Arguments Parent The widget ID of the parent widget. Keywords ALL_EVENTS Like RETURN_EVENTS but return an event whenever the contents of a text field have changed. COLUMN Set this keyword to center the label above the text field. The default is to position the label to the left of the text field. FIELDFONT A string containing the name of the font to use for the TEXT part of the field. FLOATING Set this keyword to have the field accept only floating-point values. Any number or string entered is converted to its floating-point equivalent. FONT A string containing the name of the font to use for the TITLE of the field. The font specified is a "device font" (an X Windows font on Motif systems; a TrueType or PostScript font on Windows or Macintosh systems). See "About Device Fonts" on page 2482 for details on specifying names for device fonts. If this keyword is omitted, the default font is used. FRAME The width, in pixels, of a frame to be drawn around the entire field cluster. The default is no frame. INTEGER Set this keyword to have the field accept only integer values. Any number or string entered is converted to its integer equivalent (using FIX). For example, if 12.5 is entered in this type of field, it is converted to 12. LONG Set this keyword to have the field accept only long integer values. Any number or string entered is converted to its long integer equivalent (using LONG). NOEDIT Normally, the value in the text field can be edited. Set this keyword to make the field non-editable. RETURN_EVENTS Set this keyword to make CW_FIELD return an event when a carriage return is pressed in a text field. The default is not to return events. Note that the value of the text field is always returned when the following command is used: WIDGET_CONTROL, field, GET_VALUE = X ROW Set this keyword to position the label to the left of the text field. This is the default. STRING Set this keyword to have the field accept only string values. Numbers entered in the field are converted to their string equivalents. This is the default. TEXT_FRAME Set this keyword to the width in pixels of a frame to be drawn around the text field. This keyword is only a "hint" to the toolkit, and may be ignored in some instances. Under Microsoft Windows, text widgets always have a frame of width 1 pixel. Set this keyword to draw a frame around the text field. Note that on Windows, a frame is always drawn around the text field. TITLE A string containing the text to be used as the label for the field. The default is "Input Field". UNAME Set this keyword to a string that can be used to identify the widget in your code. You can associate a name with each widget in a specific hierarchy, and then use that name to query the widget hierarchy and get the correct widget ID. To query the widget hierarchy, use the WIDGET_INFO function with the FIND_BY_UNAME keyword. The UNAME should be unique to the widget hierarchy because the FIND_BY_UNAME keyword returns the ID of the first widget with the specified name. UVALUE The "user value" to be assigned to the widget. VALUE The initial value in the text widget. This value is automatically converted to the type set by the STRING, INTEGER, and FLOATING keywords described below. XSIZE An explicit horizontal size (in characters) for the text input area. The default is to let the window manager size the widget. Using the XSIZE keyword is not recommended. YSIZE An explicit vertical size (in lines) for the text input area. The default is 1. Keywords to WIDGET_CONTROL and WIDGET_INFO The widget ID returned by most compound widgets is actually the ID of the compound widget's base widget. This means that many keywords to the WIDGET_CONTROL and WIDGET_INFO routines that affect or return information on base widgets can be used with compound widgets. In addition, you can use the GET_VALUE and SET_VALUE keywords to WIDGET_CONTROL to obtain or set the value of the field. If one of the FLOATING, INTEGER, LONG, or STRING keywords to CW_FIELD is set, values set with the SET_VALUE keyword to WIDGET_CONTROL will be forced to the appropriate type. Values returned by the GET_VALUE keyword to WIDGET_CONTROL will be of the type specified when the field widget is created. Note that if the field contains string information, returned values will be contained in a string array even if the field contains only a single string. See "Compound Widgets" in Chapter 22 of Building IDL Applications for a more complete discussion of controlling compound widgets using WIDGET_CONTROL and WIDGET_INFO. Widget Events Returned by the CW_FIELD Widget This widget generates event structures with the following definition: event = { ID:0L, TOP:0L, HANDLER: 0L, VALUE:'', TYPE:0 , UPDATE:0} The VALUE field is the value of the field. TYPE specifies the type of data contained in the field and can be any of the following: 0=string, 1=floating-point, 2=integer, 3=long integer (the value of TYPE is determined by setting one of the STRING, FLOAT, INTETER, or LONG keywords). UPDATE contains a zero if the field has not been altered or a one if it has. Example The code below creates a main base with a field cluster attached to it. The cluster accepts string input, has the title "Name", and has a frame around it: base = WIDGET_BASE() field = CW_FIELD(base, TITLE = "Name", /FRAME) WIDGET_CONTROL, base, /REALIZE See Also WIDGET_LABEL, WIDGET_TEXT CW_FILESEL [Previous Routine] [Next Routine] [List of Routines] NAME: CW_FILESEL The CW_FILESEL function is a compound widget for file selection. This routine is written in the IDL language. Its source code can be found in the file cw_filesel.pro in the lib subdirectory of the IDL distribution. Syntax Result = CW_FILESEL ( Parent [, /FILENAME] [, FILTER=string array] [, /FIX_FILTER] [, /FRAME] [, /IMAGE_FILTER] [, /MULTIPLE | , /SAVE] [, PATH=string] [, UNAME=string] [, UVALUE=value] [, /WARN_EXIST] ) Return Value CW_FILESEL returns its widget ID. Arguments Parent The widget ID of the parent. Keywords FILENAME Set this keyword to have the initial filename filled in the filename text area. FILTER Set this keyword to an array of strings determining the filter types. If not set, the default is "All Files". All files containing the chosen filter string will be displayed as possible selections. "All Files" is a special filter which returns all files in the current directory. Example: FILTER=["All Files", ".txt"] Multiple filter types may be used per filter entry, using a comma as the separator. Example: FILTER=[".jpg, .jpeg", ".txt, .text"] FIX_FILTER If set, the user can not change the file filter. FRAME If set, a frame is drawn around the widget. IMAGE_FILTER If set, the filter "Image Files" will be added to the end of the list of filters. If set, and FILTER is not set, "Image Files" will be the only filter displayed. Valid image files are determined from QUERY_IMAGE. MULTIPLE If set, the file selection list will allow multiple filenames to be selected. The filename text area will not be editable in this case. It is illegal to specify both /SAVE and /MULTIPLE. PATH Set this keyword to the initial path the widget is to start in. The default is the current directory. SAVE Set this keyword to create a widget with a "Save" button instead of an "Open" button. It is illegal to specify both /SAVE and /MULTIPLE. UNAME Set this keyword to a string that can be used to identify the widget in your code. You can associate a name with each widget in a specific hierarchy, and then use that name to query the widget hierarchy and get the correct widget ID. To query the widget hierarchy, use the WIDGET_INFO function with the FIND_BY_UNAME keyword. The UNAME should be unique to the widget hierarchy because the FIND_BY_UNAME keyword returns the ID of the first widget with the specified name. UVALUE The `user value' to be assigned to the widget. WARN_EXIST Set this keyword to produce a question dialog if the user selects a file that already exists. This keyword is useful when creating a "write" dialog. The default is to allow any filename to be quietly accepted, whether it exists or not. Keywords to WIDGET_CONTROL You can use the GET_UVALUE and SET_UVALUE keywords to WIDGET_CONTROL to obtain or set the user value of this widget. Use the command to read the currently selected filename including the full path: WIDGET_CONTROL, id, GET_VALUE=filename To set the value of the filename, use the following command: WIDGET_CONTROL, id, SET_VALUE=string where string is the filename including the full path. See "Compound Widgets" in Chapter 22 of Building IDL Applications for a more complete discussion of controlling compound widgets using WIDGET_CONTROL and WIDGET_INFO. Widget Events Returned by CW_FILESEL This widget generates event structures with the following definition: Event = {FILESEL_EVENT, ID:0L, TOP:0L, HANDLER:0L,VALUE:'', DONE:0L, FILTER:''} The ID field is the widget ID of the CW_FILESEL widget. The TOP field contains the widget ID of the top-level widget. The HANDLER field is always set to zero. The VALUE field is a string containing the filename(s) selected, if any. The DONE field can be any of the following: * 0 = User selected a file but didn't double-click, or the user changed filters (in this case the VALUE field will be an empty string.) * 1 = User pressed "Open"/"Save" or double-clicked on a file. * 2 = User pressed "Cancel". The FILTER field is a string containing the current filter. Example This example creates a CW_FILESEL widget that is used to select image files for display. Note how the DONE tag of the event structure returned by CW_FILESEL is used to determine which button was pressed, and how the VALUE tag is used to obtain the file that was selected: PRO image_opener_event, event WIDGET_CONTROL, event.top, GET_UVALUE=state, /NO_COPY CASE event.DONE OF 0: BEGIN state.file = event.VALUE WIDGET_CONTROL, event.top, SET_UVALUE=state, /NO_COPY END 1: BEGIN IF (state.file NE '') THEN BEGIN img = READ_IMAGE(state.file) TV, img ENDIF WIDGET_CONTROL, event.top, SET_UVALUE=state, /NO_COPY END 2: WIDGET_CONTROL, event.top, /DESTROY ENDCASE END PRO image_opener DEVICE, DECOMPOSED=0, RETAIN=2 base = WIDGET_BASE(TITLE ='Open Image', /COLUMN) filesel = CW_FILESEL(base, /IMAGE_FILTER, FILTER='All Files') file='' state = {file:file} WIDGET_CONTROL, base, /REALIZE WIDGET_CONTROL, base, SET_UVALUE=state, /NO_COPY XMANAGER, 'image_opener', base END See Also DIALOG_PICKFILE, FILEPATH CW_FORM [Previous Routine] [Next Routine] [List of Routines] NAME: CW_FORM The CW_FORM function is a compound widget that simplifies creating small forms which contain text, numeric fields, buttons, lists, and droplists. Event handling is also simplified. This routine is written in the IDL language. Its source code can be found in the file cw_form.pro in the lib subdirectory of the IDL distribution. Using CW_FORM The form has a value that is a structure with a tag/value pair for each field in the form. Use the command WIDGET_CONTROL, id, GET_VALUE=v to read the current value of the form. To set the value of one or more tags, use the command WIDGET_CONTROL, id, SET_VALUE={ Tag:value, ..., Tag:value} Syntax Result = CW_FORM( [Parent,] Desc [, /COLUMN] [, IDS=variable] [, TITLE=string] [, UNAME=string] [, UVALUE=value] ) Return Value If the argument Parent is present, the returned value of this function is the widget ID of the newly-created form widget. If Parent is omitted, the form realizes itself as a modal, top-level widget and CW_FORM returns a structure containing the value of each field in the form when the user finishes. Arguments Parent The widget ID of the parent widget. Omit this argument to created a modal, top-level widget. Desc A string array describing the form. Each element of the string array contains two or more comma-delimited fields. Each string has the following format: 'Depth, Item, Initial value, Settings' Use the backslash character ("\") to escape commas that appear within fields. To include the backslash character, escape it with another backslash. The fields are defined as follows: * Depth A digit defining the level at which the element will be placed on the form. Nesting is used primarily for layout, with row or column bases. This field must contain the digit 0, 1, or 2, with the following effects: * 0 = continue the current nesting level. * 1 = begin a new level under the current level. * 2 = last element at the current level. * Item A label defining the type of element to be placed in the form. Item must be one of the following: BASE, BUTTON, DROPLIST, FLOAT, INTEGER, LABEL, LIST, or TEXT. BASEs and LABELs do not return a value in the widget value structure. The other items return the following value types: Item Description BUTTON An integer or integer array. For single buttons, the value is 1 if the button is set, or 0 if it is not set. For exclusive button groups, the value is the index of the currently set button. For non-exclusive button groups, the value is an array containing an element for each button. Array elements are set to 1 if the corresponding button is set, or 0 if it is not set. DROPLIST An integer. The value set in the widget value structure is the zero-based index of the item is selected. FLOAT A floating-point value. The value set in the widget value structure is the floating-point value of the field. Table 11: Values for the Item field Item Description INTEGER An integer. The value set in the widget value structure is the integer value of the field. LIST An integer. The value set in the widget value structure is the zero-based index of the item is selected. TEXT A string. The value set in the widget value structure is the string value of the field. Table 11: Values for the Item field * Initial value The initial value of the field. The Initial value field is left empty for BASEs. For BUTTON, DROPLIST, and LIST items, the value field contains one or more item names, separated by the | character. Strings do not need to be enclosed in quotes. For example, the following line defines an exclusive button group with buttons labeled "one," "two," and "three." '0, BUTTON, one|two|three, EXCLUSIVE' For FLOAT, INTEGER, LABEL, and TEXT items, the value field contains the initial value of the field. * Settings The Settings field contains one of the following keywords or keyword=value pairs. Keywords are used to specify optional attributes or options. Any number of keywords may be included in the description string. Note that preceding keywords with a "/" character has no effect. Simply including a keyword in the Settings field enables that option. Keyword Description CENTER Specifies alignment of LABEL items. COLUMN If present, specifies column layout in BASES or for BUTTON groups. Table 12: Values for the Settings field Keyword Description EXCLUSIVE If present, makes an exclusive set of BUTTONs. The default is nonexclusive. FONT=font name If present, the font for the item is specified. The font specified is a "device font" (an X Windows font on Motif systems; a TrueType or PostScript font on Windows or Macintosh systems). See "About Device Fonts" on page 2482 for details on specifying names for device fonts. If this keyword is omitted, the default font is used. EVENT=function Specifies the name of a user-written event function that is called whenever the element is changed. The event function is called with the widget event structure as a parameter. It may return an event structure or zero to indicate that no further event processing is desired. FRAME If present, a frame is drawn around the item. Valid only for BASEs. LABEL_LEFT=label Place a label to the left of the item. This keyword is valid with BUTTON, DROPLIST, FLOAT, INTEGER and TEXT items. LABEL_TOP=label Place a label above the item. This keyword is valid with BUTTON, DROPLIST, FLOAT, INTEGER and TEXT items. LEFT Specifies alignment of LABEL items. NO_RELEASE If present, exclusive and non-exclusive buttons generate only select events. This keyword has no effect on regular buttons. Table 12: Values for the Settings field Keyword Description QUIT If the form widget is created as a top-level, modal widget, when the user activates an item defined with this keyword, the form is destroyed and its widget value returned in the widget value structure of CW_FORM. For non-modal form widgets, events generated by changing this item have their QUIT field set to 1. RIGHT Specifies alignment of LABEL items. ROW If present, specifies row layout in BASES or for BUTTON groups. SET_VALUE=value Sets the initial value of BUTTON groups or DROPLISTs. For droplists and exclusive button groups, value should be the zero-based index of the item selected. TAG=name The tag name of this element in the widget's value structure. If not specified, the tag name is TAGnnn, where nnn is the zero-based index of the item in the Desc array. WIDTH=n Specifies the width, in characters, of a TEXT, INTEGER, or FLOAT item. Table 12: Values for the Settings field Keywords COLUMN Set this keyword to make the orientation of the form vertical. If COLUMN is not set, the form is laid out in a horizontal row. IDS Set this keyword equal to a named variable into which the widget id of each widget corresponding to an element in the Desc array is stored. TITLE Set this keyword equal to a scalar string containing the title of the top level base. TITLE is not used if the form widget has a parent widget. UNAME Set this keyword to a string that can be used to identify the widget in your code. You can associate a name with each widget in a specific hierarchy, and then use that name to query the widget hierarchy and get the correct widget ID. To query the widget hierarchy, use the WIDGET_INFO function with the FIND_BY_UNAME keyword. The UNAME should be unique to the widget hierarchy because the FIND_BY_UNAME keyword returns the ID of the first widget with the specified name. UVALUE Set this keyword equal to the user value associated with the form widget. Keywords to WIDGET_CONTROL and WIDGET_INFO The widget ID returned by most compound widgets is actually the ID of the compound widget's base widget. This means that many keywords to the WIDGET_CONTROL and WIDGET_INFO routines that affect or return information on base widgets can be used with compound widgets. In addition, you can use the GET_VALUE and SET_VALUE keywords to WIDGET_CONTROL to obtain or set the value of the form. The form has a value that is a structure with a tag/value pair for each field in the form. Use the command WIDGET_CONTROL, id, GET_VALUE=v to read the current value of the form. To set the value of one or more tags, use the command WIDGET_CONTROL, id, SET_VALUE={ Tag:value, ..., Tag:value} See "Compound Widgets" in Chapter 22 of Building IDL Applications for a more complete discussion of controlling compound widgets using WIDGET_CONTROL and WIDGET_INFO. Widget Events Returned by the CW_FORM Widget This widget generates event structures each time the value of the form is changed. The event structure has the following definition: Event = { ID:0L, TOP:0L, HANDLER:0L, TAG:'', VALUE:0, QUIT:0} The ID field is the widget ID of the CW_FORM widget. The TOP field is the widget ID of the top-level widget. The TAG field contains the tag name of the field that changed. The VALUE field contains the new value of the changed field. The QUIT field contains a zero if the quit flag is not set, or one if it is set. Example Define a form with a label, two groups of vertical buttons (one non-exclusive and the other exclusive), a text field, an integer field, and "OK" and "Done" buttons. If either the "OK" or "Done" buttons are pressed, the form exits. Begin by defining a string array describing the form: desc = [ $ '0, LABEL, Centered Label, CENTER', $ '1, BASE,, ROW, FRAME', $ '0, BUTTON, B1|B2|B3, LABEL_TOP=Nonexclusive:,' $ + 'COLUMN, TAG=bg1', $ '2, BUTTON, E1|E2|E2, EXCLUSIVE,LABEL_TOP=Exclusive:,' $ + 'COLUMN,TAG=bg2', $ '0, TEXT, , LABEL_LEFT=Enter File name:, WIDTH=12,' $ + 'TAG=fname', $ '0, INTEGER, 0, LABEL_LEFT=File size:, WIDTH=6, TAG=fsize', $ '1, BASE,, ROW', $ '0, BUTTON, OK, QUIT,' $ + 'TAG=OK', $ '2, BUTTON, Cancel, QUIT'] To use the form as a modal widget: a = CW_FORM(desc, /COLUMN) When the form is exited, (when the user presses the OK or Cancel buttons), a structure is returned as the function's value. We can examine the structure by entering: HELP, /STRUCTURE, a IDL Output Meaning BG1 INT Array[3] Set buttons = 1, unset = 0. BG2 INT 1 Second button of exclusive button group was set. FNAME STRING 'test.dat' Value of the text field FSIZE LONG 120 Value of the integer field Table 13: Output from HELP, /STRUCTURE IDL Output Meaning OK LONG 1 This button was pressed TAG8 LONG 0 This button wasn't pressed Table 13: Output from HELP, /STRUCTURE Note that if the "Cancel" button is pressed, the "OK" field is set to 0. To use CW_FORM inside another widget: a = WIDGET_BASE(TITLE='Testing') b = CW_FORM(a, desc, /COLUMN) WIDGET_CONTROL, a, /REALIZE XMANAGER, 'Test', a The event handling procedure (in this example, called TEST_EVENT), may use the TAG field of the event structure to determine which field changed and perform any data validation or special actions required. It can also get and set the value of the widget by calling WIDGET_CONTROL. CW_FSLIDER [Previous Routine] [Next Routine] [List of Routines] NAME: CW_FSLIDER The CW_FSLIDER function creates a slider that selects floating-point values. This routine is written in the IDL language. Its source code can be found in the file cw_fslider.pro in the lib subdirectory of the IDL distribution. Using CW_FSLIDER To get or set the value of a CW_FSLIDER widget, use the GET_VALUE and SET_VALUE keywords to WIDGET_CONTROL. Note The CW_FSLIDER widget is based on the WIDGET_SLIDER routine, which accepts only integer values. Because conversion between integers and floating- point numbers necessarily involves round-off errors, the slider value returned by CW_FSLIDER may not exactly match the input value, even when a floating-point number is entered in the slider's text field as an ASCII value. For more information on floating-point issues, see "Accuracy & Floating-Point Operations" in Chapter 16 of Using IDL. Syntax Result = CW_FSLIDER( Parent [, DOUBLE] [, SCROLL] [, /DRAG] [, /EDIT] [, FORMAT=string] [, /FRAME] [, MAXIMUM=value] [, MINIMUM=value] [, SCROLL=units] [, /SUPRESS_VALUE] [, TITLE=string] [, UNAME=string] [, UVALUE=value] [, VALUE=initial_value] [, XSIZE=length | {, /VERTICAL [, YSIZE=height]}] ) Return Value This function returns the widget ID of the newly-created slider widget. Arguments Parent The widget ID of the parent widget. Keywords DOUBLE Set this keyword to return double-precision values for the GET_VALUE keyword to WIDGET_CONTROL, and for the VALUE field in widget events. If DOUBLE=0 then the GET_VALUE keyword and the VALUE field will return single-precision values. The default is /DOUBLE if one of the MINIMUM, MAXIMUM, or VALUE keywords is double precision, otherwise the default is DOUBLE=0. DRAG Set this keyword to zero if events should only be generated when the mouse is released. If DRAG is non-zero, events will be generated continuously when the slider is adjusted. Note: On slow systems, /DRAG performance can be inadequate. The default is DRAG = 0. EDIT Set this keyword to make the slider label be editable. The default is EDIT = 0. FORMAT Provides the format in which the slider value is displayed. This should be a format as accepted by the STRING procedure. The default FORMAT is '(G13.6)' FRAME Set this keyword to have a frame drawn around the widget. The default is FRAME = 0. MAXIMUM The maximum value of the slider. The default is MAXIMUM = 100. MINIMUM The minimum value of the slider. The default is MINIMUM = 0. SCROLL Under the Motif window manager, the SCROLL value specifies how many units the scroll bar should move when the user clicks the left mouse button inside the slider area, but not on the slider itself. On Macintosh and Microsoft Windows, the SCROLL value specifies how many units the scroll bar should move when the user clicks the left mouse button on the slider arrows, but not within the slider area or on the slider itself. The default SCROLL value is 1% of the slider width. Under the Motif window manager, the value provided for SCROLL specifies how many units the scroll bar should move when the user clicks the left mouse button inside the slider area, but not on the slider itself. This keyword has no effect under other window systems. SUPPRESS_VALUE If this keyword is set, the current slider value is not displayed. TITLE Set this keyword to a string defining the title of slider. UNAME Set this keyword to a string that can be used to identify the widget in your code. You can associate a name with each widget in a specific hierarchy, and then use that name to query the widget hierarchy and get the correct widget ID. To query the widget hierarchy, use the WIDGET_INFO function with the FIND_BY_UNAME keyword. The UNAME should be unique to the widget hierarchy because the FIND_BY_UNAME keyword returns the ID of the first widget with the specified name. UVALUE The "user value" to be assigned to the widget. VALUE The initial value of the slider VERTICAL If set, the slider will be oriented vertically. The default is horizontal. XSIZE For horizontal sliders, sets the length. YSIZE For vertical sliders, sets the height. Keywords to WIDGET_CONTROL and WIDGET_INFO The widget ID returned by most compound widgets is actually the ID of the compound widget's base widget. This means that many keywords to the WIDGET_CONTROL and WIDGET_INFO routines that affect or return information on base widgets can be used with compound widgets. In addition, you can use the GET_VALUE and SET_VALUE keywords to WIDGET_CONTROL to obtain or set the value of the slider. Note that the SET_SLIDER_MAX and SET_SLIDER_MIN keywords to WIDGET_CONTROL and the SLIDER_MIN_MAX keyword to WIDGET_INFO do not work with floating point sliders created with CW_FSLIDER. See "Compound Widgets" in Chapter 22 of Building IDL Applications for a more complete discussion of controlling compound widgets using WIDGET_CONTROL and WIDGET_INFO. Widget Events Returned by the CW_FSLIDER Widget This widget generates event structures with the following definition: Event = { ID:0L, TOP:0L, HANDLER:0L, VALUE:0.0, DRAG:0} The VALUE field is the floating-point value selected by the slider. The DRAG field reports on whether events are generated continuously (when the DRAG keyword is set) or only when the mouse button is released (the default). See Also WIDGET_SLIDER CW_LIGHT_EDITOR [Previous Routine] [Next Routine] [List of Routines] NAME: CW_LIGHT_EDITOR The CW_LIGHT_EDITOR function creates a compound widget to edit properties of existing IDLgrLight objects in a view. Lights cannot be added or removed from a view using this widget. However, lights can be "turned off or on" by hiding or showing them (i.e., HIDE property). Syntax Result = CW_LIGHT_EDITOR (Parent [, /DIRECTION_DISABLED] [, /DRAG_EVENTS] [, FRAME=width] [, /HIDE_DISABLED] [, LIGHT=objref(s)] [, /LOCATION_DISABLED] [, /TYPE_DISABLED] [, UVALUE=value] [, XSIZE=pixels] [, YSIZE=pixels] [, XRANGE=vector] [, YRANGE=vector] [, ZRANGE=vector] ) Return Value This function returns the widget ID of a newly-created light editor. Arguments Parent The widget ID of the parent widget for the new light editor. Keywords DIRECTION_DISABLED Set this keyword to make the direction widget portion of the compound widget unchangeable by the user. It will appear insensitive and will not generate an event. The default is to allow this property to be changed. DRAG_EVENTS Set this keyword to cause events to be generated continuously while a slider in the compound widget is being dragged or when the mouse cursor is being dragged across the draw widget portion of the compound widget. By default, events are only generated when the mouse comes to rest at its final position and the mouse button is released. When this keyword is set, a large number of events can be generated. On slower machines, poor performance can result. Therefore, this option should only be used when detailed or truly interactive control is required. Note Under Microsoft Windows and Macintosh, sliders do not generate these events, but behave just like regular sliders. FRAME The value of this keyword specifies the width of a frame (in pixels) to be drawn around the borders of the widget. Note that this keyword is only a `hint' to the toolkit, and may be ignored in some instances. The default is no frame. HIDE_DISABLED Set this keyword to make the hide widget portion of the compound widget unchangeable by the user. It will appear insensitive and will not generate an event. The default is to allow this property to be changed. LIGHT Set this keyword to one or more object references to IDLgrLight to edit. This will replace the current set of lights being edited with the list of lights from this keyword. LOCATION_DISABLED Set this keyword to make the location widget portion of the compound widget unchangeable by the user. It will appear insensitive and will not generate an event. The default is to allow this property to be changed. TYPE_DISABLED Set this keyword to make the light type widget portion of the compound widget unchangeable by the user. It will appear insensitive and will not generate an event. The default is to allow this property to be changed. UNAME Set this keyword to a string that can be used to identify the widget. You can associate a name with each widget in a specific hierarchy, and then use that name to query the widget hierarchy and get the correct widget ID. To query the widget hierarchy, use the WIDGET_INFO function with the FIND_BY_UNAME keyword. The UNAME should be unique to the widget hierarchy because the FIND_BY_UNAME keyword returns the ID of the first widget with the specified name. UVALUE The `user value' to be assigned to the widget. Each widget can contain a user- specified value of any data type and organization. This value is not used by the widget in any way, but exists entirely for the convenience of the IDL programmer. This keyword allows you to set this value when the widget is first created. If UVALUE is not present, the widget's initial user value is undefined. XRANGE A two-element vector defining the data range in the x direction. This keyword is used to determine the valid range for the light's location and direction properties XSIZE The width of the drawable area in pixels. The default width is 180. YRANGE A two-element vector defining the data range in the y direction. This keyword is used to determine the valid range for the light's location and direction properties. YSIZE The height of the drawable area in pixels. The default height is 180. ZRANGE A two-element vector defining the data range in the z direction. This keyword is used to determine the valid range for the light's location and direction properties Light Editor Events There are variations of the light editor event structure depending on the specific event being reported. All of these structures contain the standard three fields (ID, TOP, and HANDLER). The different light editor event structures are described below. Light Selected This is the type of structure returned when the light selected in the light list box is modified by a user. { CW_LIGHT_EDITOR_LS, ID:0L, TOP:0L, HANDLER:0L, LIGHT:OBJ_NEW()} LIGHT specifies the object ID of the new light selection. Light Modified This is the type of structure returned when the user has modified a light property. This event maybe generated continuously if the DRAG_EVENTS keyword was set. See DRAG_EVENTS above. { CW_LIGHT_EDITOR_LM, ID:0L, TOP:0L, HANDLER:0L} The value of the light editor will need to be retrieved (i.e., CW_LIGHT_EDITOR_GET) in order to determine the extent of the actual user modification. WIDGET_CONTROL Keywords The widget ID returned by this compound widget is actually the ID of the compound widget's base widget. This means that many keywords to the WIDGET_CONTROL and WIDGET_INFO routines that affect or return information on base widgets can be used with this compound widget (e.g., UNAME, UVALUE). GET_VALUE Set this keyword to a named variable to contain the current value of the widget. An IDLgrLight object reference of the currently selected light is returned. The value of a widget can be set with the SET_VALUE keyword to this routine. SET_VALUE Sets the value of the specified light editor compound widget. This widget accepts an IDLgrLight object reference of the light in the list of lights to make as the current selection. The property values are retrieved from the light object and the light editor controls are updated to reflect those properties. See Also CW_LIGHT_EDITOR_GET, CW_LIGHT_EDITOR_SET, IDLgrLight CW_LIGHT_EDITOR_GET [Previous Routine] [Next Routine] [List of Routines] NAME: CW_LIGHT_EDITOR_GET The CW_LIGHT_EDITOR_GET procedure gets the CW_LIGHT_EDITOR properties. Syntax CW_LIGHT_EDITOR_GET, WidgetID [, DIRECTION_DISABLED=variable] [, DRAG_EVENTS=variable] [, HIDE_DISABLED=variable] [, LIGHT=variable] [, LOCATION_DISABLED=variable] [, TYPE_DISABLED=variable] [, XSIZE=variable] [, YSIZE=variable] [, XRANGE=variable] [, YRANGE=variable] [, ZRANGE=variable] Arguments WidgetID The widget ID of the CW_ LIGHT_EDITOR compound widget. Keywords DIRECTION_DISABLED Set this keyword to a named variable that will contain a boolean value indicating whether this option has been set to make the direction widget portion of the compound widget unchangeable by the user. It will appear insensitive and will not generate an event. DRAG_ EVENTS Set this keyword to a named variable that will contain a boolean value indicating whether this option has been set to cause events to be generated continuously while a slider in the compound widget is being dragged or when the mouse cursor is being dragged across the draw widget portion of the compound widget. When this keyword is set, a large number of events can be generated. On slower machines, poor performance can result. Therefore, this option should only be used when detailed or truly interactive control is required. Note Under Microsoft Windows and Macintosh, sliders do not generate these events, but behave just like regular sliders. HIDE_DISABLED Set this keyword to a named variable that will contain a boolean value indicating whether this option has been set to make the hide widget portion of the compound widget unchangeable by the user. LIGHT Set this keyword to a named variable that will contain one or more object references to IDLgrLight. LOCATION_DISABLED Set this keyword to a named variable that will contain a boolean value indicating whether this option has been set to make the location widget portion of the compound widget unchangeable by the user. TYPE_DISABLED Set this keyword to a named variable that will contain a boolean value indicating whether this option has been set to make the light type widget portion of the compound widget unchangeable by the user. XRANGE Set this keyword to a named variable that will contain a two-element vector defining the data range in the x direction. XSIZE Set this keyword to a named variable that will contain the width of the drawable area in pixels. YRANGE Set this keyword to a named variable that will contain a two-element vector defining the data range in the y direction. YSIZE Set this keyword to a named variable that will contain the height of the drawable area in pixels. ZRANGE Set this keyword to a named variable that will contain a two-element vector defining the data range in the z direction. See Also CW_LIGHT_EDITOR, CW_LIGHT_EDITOR_SET, IDLgrLight CW_LIGHT_EDITOR_SET [Previous Routine] [Next Routine] [List of Routines] NAME: CW_LIGHT_EDITOR_SET The CW_LIGHT_EDITOR procedure sets the CW_LIGHT_EDITOR properties. Syntax CW_LIGHT_EDITOR_SET, WidgetID [, /DIRECTION_DISABLED] [, /DRAG_EVENTS] [, /HIDE_DISABLED] [, LIGHT=objref(s)] [, /LOCATION_DISABLED] [, /TYPE_DISABLED] [, XSIZE=pixels] [, YSIZE=pixels] [, XRANGE=vector] [, YRANGE=vector] [, ZRANGE=vector] Arguments WidgetID The widget ID of the CW_ LIGHT_EDITOR compound widget. Keywords DIRECTION_DISABLED Set this keyword to make the direction widget portion of the compound widget unchangeable by the user. It will appear insensitive and will not generate an event. DRAG_ EVENTS Set this keyword to cause events to be generated continuously while a slider in the compound widget is being dragged or when the mouse cursor is being dragged across the draw widget portion of the compound widget. When this keyword is set, a large number of events can be generated. On slower machines, poor performance can result. Therefore, this option should only be used when detailed or truly interactive control is required. Note Under Microsoft Windows and Macintosh, sliders do not generate these events, but behave just like regular sliders. HIDE_DISABLED Set this keyword to make the hide widget portion of the compound widget unchangeable by the user. It will appear insensitive and will not generate an event. LIGHT Set this keyword to one or more object references to IDLgrLight to edit. This will replace the current set of lights being edited with the list of lights from this keyword. LOCATION_DISABLED Set this keyword to make the location widget portion of the compound widget unchangeable by the user. It will appear insensitive and will not generate an event. TYPE_DISABLED Set this keyword to make the light type widget portion of the compound widget unchangeable by the user. It will appear insensitive and will not generate an event. XRANGE A two-element vector defining the data range in the x direction. This keyword is used to determine the valid range for the light's location and direction properties. XSIZE The width of the drawable area in pixels. YRANGE A two-element vector defining the data range in the y direction. This keyword is used to determine the valid range for the light's location and direction properties. YSIZE The height of the drawable area in pixels. ZRANGE A two-element vector defining the data range in the z direction. This keyword is used to determine the valid range for the light's location and direction properties. See Also CW_LIGHT_EDITOR, CW_LIGHT_EDITOR_GET, IDLgrLight CW_ORIENT [Previous Routine] [Next Routine] [List of Routines] NAME: CW_ORIENT The CW_ORIENT function creates a compound widget that provides a means to interactively adjust the three-dimensional drawing transformation and resets the !P.T system variable field to reflect the changed orientation. This routine is written in the IDL language. Its source code can be found in the file cw_orient.pro in the lib subdirectory of the IDL distribution. Syntax Result = CW_ORIENT( Parent [, AX=degrees] [, AZ=degrees] [, /FRAME] [, TITLE=string] [, UNAME=string] [, UVALUE=value] [, XSIZE=width] [, YSIZE=height] ) Return Value This function returns the widget ID of the newly-created orientation-adjustment widget. Arguments Parent The widget ID of the parent widget. Keywords AX The initial rotation in the X direction. The default is 30 degrees. AZ The initial rotation in the Z direction. The default is 30 degrees. FRAME Set this keyword to draw a frame around the widget. TITLE The title of the widget. UNAME Set this keyword to a string that can be used to identify the widget in your code. You can associate a name with each widget in a specific hierarchy, and then use that name to query the widget hierarchy and get the correct widget ID. To query the widget hierarchy, use the WIDGET_INFO function with the FIND_BY_UNAME keyword. The UNAME should be unique to the widget hierarchy because the FIND_BY_UNAME keyword returns the ID of the first widget with the specified name. UVALUE The "user value" to be assigned to the widget. XSIZE Determines the width of the widget. The default is 100. YSIZE Determines the height of the widget. The default is 100. Keywords to WIDGET_CONTROL and WIDGET_INFO The widget ID returned by most compound widgets is actually the ID of the compound widget's base widget. This means that many keywords to the WIDGET_CONTROL and WIDGET_INFO routines that affect or return information on base widgets can be used with compound widgets. See "Compound Widgets" in Chapter 22 of Building IDL Applications for a more complete discussion of controlling compound widgets using WIDGET_CONTROL and WIDGET_INFO. Widget Events Returned by the CW_ORIENT Widget CW_ORIENT only returns events when the three dimensional drawing transformation has been altered. The !P.T system variable field is automatically updated to reflect the new orientation. See Also CW_ARCBALL, T3D CW_PALETTE_EDITOR [Previous Routine] [Next Routine] [List of Routines] NAME: CW_PALETTE_EDITOR The CW_PALETTE_EDITOR function creates a compound widget to display and edit color palettes. The palette editor is a base that contains a drawable area to display the color palette, a set of vectors that represent the palette and an optional histogram. Syntax Result = CW_PALETTE_EDITOR (Parent [, DATA=array] [, FRAME=width] [, HISTOGRAM=vector] [, /HORIZONTAL] [, SELECTION=[start, end]] [, UNAME=string] [, UVALUE=value] [, XSIZE=width] [, YSIZE=height] ) Return Value This function returns the widget ID of the newly created palette editor. Graphics Area Components Reference Color bar A gray scale color bar is displayed at the top of the graphics area for reference purposes. Palette Colorbar A color bar containing a display of the current palette is displayed below the reference color bar. Channel and Histogram Display The palette channel vectors are displayed below the palette colorbar. The Red channel is displayed in red, the Green channel in green, the Blue channel in blue, and the optional Alpha channel in purple. The optional Histogram vector is displayed in Cyan. An area with a white background represents the current selection, with gray background representing the area outside of the current selection. Yellow drag handles are an additional indicator of the selection endpoints. These selection endpoints represent the range for some editing operations. In addition, cursor X,Y values and channel pixel values at the cursor location are displayed in a status area below the graphics area. Interactive Capabilities Color Space A droplist allows selection of RGB, HSV or HLS color spaces. RGB is the default color space. Note that regardless of the color space in use, the color vectors retrieved with the GET_VALUE keyword to widget control are always in the RGB color space. Editing Mode A droplist allows selection of the editing mode. Freehand is the default editing mode. Unless noted below, editing operations apply only to the channel vectors currently selected for editing. Unless noted below, editing operations apply only to the portion of the vectors within the selection indicators. In Freehand editing mode the user can click and drag in the graphics area to draw a new curve. Editable channel vectors will be modified to use the new curve for that part of the X range within the selection that was drawn in Freehand mode. In Line Segment editing mode a click, drag and release operation defines the start point and end point of a line segment. Editable channel vectors will be modified to use the new curve for that part of the X range within the selection that was drawn in Line Segment mode. In Barrel Shift editing mode click and drag operations in the horizontal direction cause the editable curves to be shifted right or left, with the portion which is shifted off the end of selection area wrapping around to appear on the other side of the selection area. Only the horizontal component of drag movement is used. In Slide editing mode click and drag operations in the horizontal direction cause the editable curves to be shifted right or left. Unlike the Barrel Shift mode, the portion of the curves shifted off the end of the selection area does not wrap around. Only the horizontal component of drag movement is used. In Stretch editing mode click and drag operations in the horizontal direction cause the editable curves to be compressed or expanded. Only the horizontal component of drag movement is used. A number of buttons provide editing operations which do not require cursor input: The Ramp operation causes the selected part of the editable curves to be replaced with a linear ramp from 0 to 255. The Smooth operation causes the selected part of the editable curves to be smoothed. The Posterize operation causes the selected part of the editable curves to be replaced with a series of steps. The Reverse operation causes the selected part of the editable curves to be reversed in the horizontal direction. The Invert operation causes the selected part of the editable curves to be flipped in the vertical direction. The Duplicate operation causes the selected part of the editable curves to be compressed by 50% and duplicated to produce two contiguous copies of the channel vectors within the initial selection. The Load PreDefined droplist choice leads to additional choices of pre-defined palettes. Loading a pre-defined palette replaces only the selected portion of the editable color channels, respecting of the settings of the selection endpoints and editable checkboxes. This allows loading only a single channel or only a portion of a pre-defined palette. Channel Display and Edit A row of checkboxes allows the user to indicate which channels of Red, Green, Blue and the optional Alpha channel should be displayed. A second row of checkboxes allows the user to indicate which channels should be edited by the current editing operation. The checkboxes for the Alpha channel will be sensitive only if an Alpha channel is loaded. Zoom Four buttons allow the user to zoom the display of the palette. The "| |" button zooms to show the current selection. The "+" button zooms in 50%. The "-" button zooms out 100%. The "1:1" button returns the display to the full palette. Scrolling of the Palette Window When the palette is zoomed to a scale greater than 1:1 the scroll bar at the bottom of the graphics area can be used to view a different part of the palette. Arguments Parent The widget ID of the parent widget for the new palette editor. Keywords DATA A 3x256 byte array containing the initial color values for Red, Green and Blue channels. The value supplied can also be a 4x256 byte array containing the initial color values and the optional Alpha channel. The value supplied can also be an IDLgrPalette object reference. If an IDLgrPalette object reference is supplied it is used internally and is not destroyed on exit. If an object reference is supplied the ALPHA keyword to the CW_PALETTE_EDITOR_SET routine can be used to supply the data for the optional Alpha channel. FRAME The value of this keyword specifies the width of a frame (in pixels) to be drawn around the borders of the widget. Note that this keyword is only a "hint" to the toolkit, and may be ignored in some instances. The default is no frame. HISTOGRAM A 256 element byte vector containing the values for the optional histogram curve. HORIZONTAL Set this keyword for a horizontal layout for the compound widget. This consists of the controls to the right of the display area. The default is a vertical layout with the controls below the display area. SELECTION The selection is a two element vector defining the starting and ending point of the selection region of color indexes. The default is [0,255]. UNAME Set this keyword to a string that can be used to identify the widget. You can associate a name with each widget in a specific hierarchy, and then use that name to query the widget hierarchy and get the correct widget ID. To query the widget hierarchy, use the WIDGET_INFO function with the FIND_BY_UNAME keyword. The UNAME should be unique to the widget hierarchy because the FIND_BY_UNAME keyword returns the ID of the first widget with the specified name. UVALUE The `user value' to be assigned to the widget. Each widget can contain a user- specified value of any data type and organization. This value is not used by the widget in any way, but exists entirely for the convenience of the IDL programmer. This keyword allows you to set this value when the widget is first created. If UVALUE is not present, the widget's initial user value is undefined. XSIZE The width of the drawable area in pixels. The default width is 256. YSIZE The height of the drawable area in pixels. The default height is 256. Palette Editor Events There are variations of the palette editor event structure depending on the specific event being reported. All of these structures contain the standard three fields (ID, TOP, and HANDLER). The different palette editor event structures are described below. Selection Moved This is the type of structure returned when one of the vertical bars that define the selection region is moved by a user. { CW_PALETTE_EDITOR_SM, ID:0L, TOP:0L, HANDLER:0L, SELECTION:[0,255]} SELECTION indicates a two element vector defining the starting and ending point of the selection region of color indexes. Palette Edited This is the type of structure returned when the user has modified the color palette. { CW_PALETTE_EDITOR_PM, ID:0L, TOP:0L, HANDLER:0L} The value of the palette editor will need to be retrieved (i.e., WIDGET_CONTROL, GET_VALUE) in order to determine the extent of the actual user modification. WIDGET_CONTROL Keywords for Palette Editor The widget ID returned by this compound widget is actually the ID of the compound widget's base widget. This means that many keywords to the WIDGET_CONTROL and WIDGET_INFO routines that affect or return information on base widgets can be used with this compound widget (e.g., UNAME, UVALUE). GET_VALUE Set this keyword to a named variable to contain the current value of the widget. A 3xn (RGB) or 4xn (i.e., RGB and ALPHA) array containing the palette is returned. The value of a widget can be set with the SET_VALUE keyword to this routine. SET_VALUE Sets the value of the specified palette editor compound widget. This widget accepts a 3xn (RGB) or 4xn (i.e., RGB and ALPHA) array representing the value of the palette to be set. Another type of argument accepted is an IDLgrPalette object reference. If an IDLgrPalette object reference is supplied it is used internally and is not destroyed on exit. See Also CW_PALETTE_EDITOR_GET, CW_PALETTE_EDITOR_SET, IDLgrPalette CW_PALETTE_EDITOR_GET [Previous Routine] [Next Routine] [List of Routines] NAME: CW_PALETTE_EDITOR_GET The CW_PALETTE_EDITOR_GET procedure gets the CW_PALETTE_EDITOR properties. Syntax CW_PALETTE_EDITOR_GET, WidgetID [, ALPHA=variable] [, HISTOGRAM=variable] Arguments WidgetID The widget ID of the CW_PALETTE_EDITOR compound widget. Keywords ALPHA Set this keyword to a named variable that will contains the optional alpha curve. HISTOGRAM Set this keyword to a named variable that will contains the optional histogram curve. See Also CW_PALETTE_EDITOR, CW_PALETTE_EDITOR_SET, IDLgrPalette CW_PALETTE_EDITOR_SET [Previous Routine] [Next Routine] [List of Routines] NAME: CW_PALETTE_EDITOR_SET The CW_PALETTE_EDITOR_SET procedure sets the CW_PALETTE_EDITOR properties. Syntax CW_PALETTE_EDITOR_SET, WidgetID [, ALPHA=byte_vector] [, HISTOGRAM=byte_vector] Arguments WidgetID The widget ID of the CW_PALETTE_EDITOR compound widget. Keywords ALPHA A 256 element byte vector that describes the alpha component of the color palette. The alpha value may also be set to the scalar value zero to remove the alpha curve from the display. HISTOGRAM The histogram is an vector to be plotted below the color palette. This keyword can be used to display a distribution of color index values to facilitate editing the color palette. The histogram value may also be set to the scalar value zero to remove the histogram curve from the display. See Also CW_PALETTE_EDITOR, CW_PALETTE_EDITOR_GET, IDLgrPalette CW_PDMENU [Previous Routine] [Next Routine] [List of Routines] NAME: CW_PDMENU The CW_PDMENU function creates widget pulldown menus. It has a simpler interface than the XPDMENU procedure, which it replaces. Events for the individual buttons are handled transparently, and a CW_PDMENU event returned. This event can return any one of the following: * the Index of the button within the base * the widget ID of the button * the name of the button. * the fully qualified name of the button. This allows different sub-menus to contain buttons with the same name in an unambiguous way. Only buttons with textual names are handled by this widget. Bitmaps are not understood. This routine is written in the IDL language. Its source code can be found in the file cw_pdmenu.pro in the lib subdirectory of the IDL distribution. Syntax Result = CW_PDMENU( Parent, Desc [, CONTEXT_MENU] [, /COLUMN] [, DELIMITER=string] [, FONT=value] [, /MBAR [, /HELP]] [, IDS=variable] [, /RETURN_ID | , /RETURN_INDEX | , /RETURN_NAME | , /RETURN_FULL_NAME] [, UNAME=string] [, UVALUE=value] [, XOFFSET=value] [, YOFFSET=value] ) Return Value This function returns the widget ID of the newly-created pulldown menu widget. Arguments Parent The widget ID of the parent widget. Desc An array of strings or structures. If Desc is an array of strings, each element contains the flag field, followed by a backslash character, followed by the name of the menu item, optionally followed by another backslash character and the name of an event- processing procedure for that element. A string element of the Desc array would look like: 'n\item_name' or 'n\item_name\event_proc' where n is the flag field and item_name is the name of the menu item. The flag field is a bitmask that controls how the button is interpreted; appropriate values for the flag field are shown in the following table. If the event_proc field is present, it is the name of an event-handling procedure for the menu element and all of its children. If Desc is an array of structures, each structure has the following definition: {CW_PDMENU_S, flags:0, name:''} The name tag is a string field with the following components: 'item_name' or 'item_name\event_proc' where item_name is the name of the menu item. If the event_proc field is present, it is the name of an event-handling procedure for the menu element and all of its children The flags field is a bitmask that controls how the button is interpreted; appropriate values for the flag field are shown in the following table. Note that if Desc is an array of structures, you cannot specify individual event-handling procedures for each element. Value Meaning 0 This button is neither the beginning nor the end of a pulldown level. 1 This button is the root of a sub-pulldown menu. The sub-buttons start with the next button. 2 This button is the last button at the current pulldown level. The next button belongs to the same level as the current parent button. If the name field is not specified (or is an empty string), no button is created, and the next button is created one level up in the hierarchy. 3 This button is the root of a sub-pulldown menu, but it is also the last entry of the current level. Table 14: Button Flag Bit Meanings Keywords CONTEXT_MENU (Windows, UNIX only) Set this new keyword to create a context menu pulldown. If CONTEXT_MENU is set, Parent must be the widget ID of a context menu base, and the return value of CW_PDMENU is this widget ID. Also see the CONTEXT_MENU keyword to WIDGET_BASE. COLUMN Set this keyword to create a vertical column of menu buttons. The default is to create a horizontal row of buttons. DELIMITER The character used to separate the parts of a fully qualified name in returned events. The default is to use the "." character. FONT The name of the font to be used for the button titles. The font specified is a "device font" (an X Windows font on Motif systems; a TrueType or PostScript font on Windows or Macintosh systems). See "About Device Fonts" on page 2482 for details on specifying names for device fonts. If this keyword is omitted, the default font is used. HELP If the MBAR keyword is set, and one of the buttons on the menubar has the label "help" (case insensitive) then that button is created with the /HELP keyword to give it any special appearance it is supposed to have on a menubar. For example, Motif expects help buttons to be on the right. IDS A named variable in which the button IDs will be stored as a longword vector. MBAR Set this keyword to create a menubar pulldown. If MBAR is set, Parent must be the widget ID of a menubar belonging to a top-level base, and the return value of CW_PDMENU is this widget ID. For an example demonstrating the use of the MBAR keyword, see Example 2 below. Also see the MBAR keyword to WIDGET_BASE. RETURN_ID If this keyword is set, the VALUE field of returned events will contain the widget ID of the button. RETURN_INDEX If this keyword is set, the VALUE field of returned events will contain the zero-based index of the button within the base. THIS IS THE DEFAULT. RETURN_NAME If this keyword is set, the VALUE field of returned events will be the name of the selected button. RETURN_FULL_NAME Set this keyword and the VALUE field of returned events will be the fully qualified name of the selected button. This means that the names of all the buttons from the topmost button of the pulldown menu to the selected one are concatenated with the delimiter specified by the DELIMITER keyword. For example, if the top button was named COLORS, the second level button was named BLUE, and the selected button was named LIGHT, the returned value would be COLORS.BLUE.LIGHT This allows different submenus to have buttons with the same name (e.g., COLORS.RED.LIGHT). UNAME Set this keyword to a string that can be used to identify the widget in your code. You can associate a name with each widget in a specific hierarchy, and then use that name to query the widget hierarchy and get the correct widget ID. To query the widget hierarchy, use the WIDGET_INFO function with the FIND_BY_UNAME keyword. The UNAME should be unique to the widget hierarchy because the FIND_BY_UNAME keyword returns the ID of the first widget with the specified name. UVALUE The "user value" to be assigned to the widget. If the MBAR keyword is set, the value specified for UVALUE is also assigned as the UVALUE of the parent menu (i.e., the widget specified by the Parent argument in the call to CW_PDMENU). XOFFSET The X offset of the widget relative to its parent. YOFFSET The Y offset of the widget relative to its parent. Keywords to WIDGET_CONTROL and WIDGET_INFO The widget ID returned by most compound widgets is actually the ID of the compound widget's base widget. This means that many keywords to the WIDGET_CONTROL and WIDGET_INFO routines that affect or return information on base widgets can be used with compound widgets. See "Compound Widgets" in Chapter 22 of Building IDL Applications for a more complete discussion of controlling compound widgets using WIDGET_CONTROL and WIDGET_INFO. Widget Events Returned by the CW_PDMENU Widget This widget generates event structures with the following definition: event = { ID:0L, TOP:0L, HANDLER:0L, VALUE:0 } VALUE is either the INDEX, ID, NAME, or FULL_NAME of the button, depending on how the widget was created. Examples Example 1 The following is the description of a menu bar with two buttons: "Colors" and "Quit". Colors is a pulldown containing the colors "Red", "Green", Blue", "Cyan", and "Magenta". Blue is a sub-pulldown containing "Light", "Medium", "Dark", "Navy", and "Royal." The following small program can be used with the above description to create the specified menu: PRO PD_EXAMPLE desc = [ '1\Colors' , $ '0\Red' , $ '0\Green' , $ '1\Blue' , $ '0\Light' , $ '0\Medium' , $ '0\Dark' , $ '0\Navy' , $ '2\Royal' , $ '0\Cyan' , $ '2\Magenta' , $ '2\Quit' ] ; Create the widget: base = WIDGET_BASE() menu = CW_PDMENU(base, desc, /RETURN_FULL_NAME) WIDGET_CONTROL, /REALIZE, base ;Provide a simple event handler: REPEAT BEGIN ev = WIDGET_EVENT(base) PRINT, ev.value END UNTIL ev.value EQ 'Quit' WIDGET_CONTROL, /DESTROY, base END The Desc array could also have been defined using a structure for each element. The following array of structures creates the same menu as the array of strings shown above. Note, however, that if the Desc array is composed of structures, you cannot specify individual event-handling routines. First, make sure CW_PDMENU_S structure is defined: junk = {CW_PDMENU_S, flags:0, name:'' } Define the menu: desc = [ { CW_PDMENU_S, 1, 'Colors' }, $ { CW_PDMENU_S, 0, 'Red' }, $ { CW_PDMENU_S, 0, 'Green' }, $ { CW_PDMENU_S, 1, 'Blue' }, $ { CW_PDMENU_S, 0, 'Light' }, $ { CW_PDMENU_S, 0, 'Medium' }, $ { CW_PDMENU_S, 0, 'Dark' }, $ { CW_PDMENU_S, 0, 'Navy' }, $ { CW_PDMENU_S, 2, 'Royal' }, $ { CW_PDMENU_S, 0, 'Cyan' }, $ { CW_PDMENU_S, 2, 'Magenta' }, $ { CW_PDMENU_S, 2, 'Quit' } ] Example 2 This example demonstrates the use of the MBAR keyword to CW_PDMENU to populate the "Colors" menu item on a menu bar created using WIDGET_BASE. PRO mbar_event, event WIDGET_CONTROL, event.id, GET_UVALUE=uval CASE uval OF 'Quit': WIDGET_CONTROL, /DESTROY, event.top ELSE: PRINT, event.value ENDCASE END PRO mbar ; Create the base widget: base = WIDGET_BASE(TITLE = 'Example', MBAR=bar, XSIZE=200, $ UVALUE='base') file_menu = WIDGET_BUTTON(bar, VALUE='File', /MENU) file_bttn1=WIDGET_BUTTON(file_menu, VALUE='Quit', $ UVALUE='Quit') colors_menu = WIDGET_BUTTON(bar, VALUE='Colors', /MENU) ; Define array for colors menu items: desc = [ '0\Red' , $ '0\Green' , $ '1\Blue' , $ '0\Light' , $ '0\Medium' , $ '0\Dark' , $ '0\Navy' , $ '2\Royal' , $ '0\Cyan' , $ '2\Magenta' ] ; Create colors menu items. Note that the Parent argument is ; set to the widget ID of the parent menu: colors = CW_PDMENU(colors_menu, desc, /MBAR, $ /RETURN_FULL_NAME, UVALUE='menu') WIDGET_CONTROL, /REALIZE, base XMANAGER, 'mbar', base, /NO_BLOCK END See Also CW_BGROUP, WIDGET_DROPLIST CW_RGBSLIDER [Previous Routine] [Next Routine] [List of Routines] NAME: CW_RGBSLIDER The CW_RGBSLIDER function creates a compound widget that provides three sliders for adjusting color values. The RGB, CMY, HSV, and HLS color systems can all be used. No matter which color system is in use, the resulting color is always supplied in RGB, which is the base system for IDL. This routine is written in the IDL language. Its source code can be found in the file cw_rgbslider.pro in the lib subdirectory of the IDL distribution. Using CW_RGBSLIDER The CW_RGBSLIDER widget consists of a pulldown menu which allows the user to change between the supported color systems, and three color adjustment sliders, allowing the user to select a new color value. Syntax Result = CW_RGBSLIDER( Parent [, /CMY | , /HSV | , /HLS | , /RGB] [, /COLOR_INDEX | , GRAPHICS_LEVEL={1 | 2}] [, /DRAG] [, /FRAME] [, LENGTH=value] [, UNAME=string] [, UVALUE=value] [, VALUE=[r, g, b]] [, /VERTICAL] ) Return Value This function returns the widget ID of the newly-created color adjustment widget. Arguments Parent The widget ID of the parent widget. Keywords CMY If set, the initial color system used is CMY. COLOR_INDEX Set this keyword to display a small rectangle with the selected color. The color is updated as the values are changed. The color initially displayed in this rectangle corresponds to the value specified with the VALUE keyword. If using Object Graphics, it is recommended that you set the GRAPHICS_LEVEL keyword to 2, in which case the COLOR_INDEX keyword is ignored. DRAG Set this keyword and events will be generated continuously when the sliders are adjusted. If not set, events will only be generated when the mouse button is released. Note: On slow systems, /DRAG performance can be inadequate. The default is DRAG = 0. FRAME If set, a frame will be drawn around the widget. The default is FRAME = 0. GRAPHICS_LEVEL Set this keyword to 2 to use Object Graphics. Set to 1 for Direct Graphics (the default). If set to 2, a small rectangle is displayed with the selected color. The color is updated as the values are changed. The color initially displayed in this rectangle corresponds to the value specified with the VALUE keyword. If this keyword is set, the COLOR_INDEX keyword is ignored. HSV If set, the initial color system used is HSV. HLS If set, the initial color system used is HLS. LENGTH The length of the sliders. The default = 256. RGB If set, the initial color system used is RGB. This is the default. UNAME Set this keyword to a string that can be used to identify the widget in your code. You can associate a name with each widget in a specific hierarchy, and then use that name to query the widget hierarchy and get the correct widget ID. To query the widget hierarchy, use the WIDGET_INFO function with the FIND_BY_UNAME keyword. The UNAME should be unique to the widget hierarchy because the FIND_BY_UNAME keyword returns the ID of the first widget with the specified name. UVALUE The "user value" to be assigned to the widget. VALUE Set this keyword to a 3-element [r, g, b] vector representing the initial RGB value for the CW_RGBSLIDER widget. If the GRAPHICS_LEVEL keyword is set to 2, the color swatch will also initially display this RGB value. VERTICAL If set, the sliders will be oriented vertically. The default is VERTICAL = 0. Keywords to WIDGET_CONTROL and WIDGET_INFO The widget ID returned by most compound widgets is actually the ID of the compound widget's base widget. This means that many keywords to the WIDGET_CONTROL and WIDGET_INFO routines that affect or return information on base widgets can be used with compound widgets. See "Compound Widgets" in Chapter 22 of Building IDL Applications for a more complete discussion of controlling compound widgets using WIDGET_CONTROL and WIDGET_INFO. Widget Events Returned by the CW_RGBSLIDER Widget This widget generates event structures with the following definition: event = {ID:0L, TOP:0L, HANDLER:0L, R:0B, G:0B, B:0B } The `R', `G', and `B' fields contain the Red, Green and Blue components of the selected color. Note that CW_RGBSLIDER reports back the Red, Green, and Blue values no matter which color system is selected. See Also CW_CLR_INDEX, XLOADCT, XPALETTE CW_TMPL [Previous Routine] [Next Routine] [List of Routines] NAME: CW_TMPL The CW_TMPL procedure is a template for compound widgets that use the XMANAGER. Use this template instead of writing your compound widgets from "scratch". This template can be found in the file cw_tmpl.pro in the lib subdirectory of the IDL distribution. Syntax Result = CW_TMPL( Parent [, UNAME=string] [, UVALUE=value] ) Arguments Parent The widget ID of the parent widget of the new compound widget. Keywords UNAME Set this keyword to a string that can be used to identify the widget in your code. You can associate a name with each widget in a specific hierarchy, and then use that name to query the widget hierarchy and get the correct widget ID. To query the widget hierarchy, use the WIDGET_INFO function with the FIND_BY_UNAME keyword. The UNAME should be unique to the widget hierarchy because the FIND_BY_UNAME keyword returns the ID of the first widget with the specified name. UVALUE A user-specified value for the compound widget. See Also XMNG_TMPL CW_ZOOM [Previous Routine] [Next Routine] [List of Routines] NAME: CW_ZOOM The CW_ZOOM function creates a compound widget that displays two images: an original image in one window and a portion of the original image in another. The user can select the center of the zoom region, the zoom scale, the interpolation style, and the method of indicating the zoom center. This routine is written in the IDL language. Its source code can be found in the file cw_zoom.pro in the lib subdirectory of the IDL distribution. Using CW_ZOOM The value of the CW_ZOOM widget is the original, un-zoomed image to be displayed (a two-dimensional array). To change the contents of the CW_ZOOM widget, use the command: WIDGET_CONTROL, id, SET_VALUE = array where id is the widget ID of the CW_ZOOM widget and array is the image array. The value of CW_ZOOM cannot be set until the widget has been realized. Note that the size of the original window, set with the XSIZE and YSIZE keywords to CW_ZOOM, must be the size of the input array. To return the current zoomed image as displayed by CW_ZOOM in the variable array, use the command: WIDGET_CONTROL, id, GET_VALUE = array Syntax Result = CW_ZOOM( Parent [, /FRAME] [, MAX=scale] [, MIN=scale] [, RETAIN={0 | 1 | 2}] [, SAMPLE=value] [, SCALE=value] [, /TRACK] [, UNAME=string] [, UVALUE=value] [, XSIZE=width] [, X_SCROLL_SIZE=width] [, X_ZSIZE=zoom_width] [, YSIZE=height] [, Y_SCROLL_SIZE=height] [, Y_ZSIZE=zoom_height] ) Return Value This function returns the widget ID of the newly-created zoom widget. Arguments Parent The widget ID of the parent widget. Keywords FRAME If set, a frame will be drawn around the widget. The default is FRAME = 0. MAX The maximum zoom scale, which must be greater than or equal to 1. The default is 20. MIN The minimum zoom scale, which must be greater than or equal to 1. The default is 1. RETAIN Set this keyword to zero, one, or two to specify how backing store should be handled for both windows. RETAIN=0 specifies no backing store. RETAIN=1 requests that the server or window system provide backing store. RETAIN=2 specifies that IDL provide backing store directly. See "Backing Store" on page 2351 for details. SAMPLE Set to zero for bilinear interpolation, or to a non-zero value for nearest neighbor interpolation. Bilinear interpolation gives higher quality results, but requires more time. The default is 0. SCALE The initial integer scale factor to use for the zoomed image. The default is SCALE = 4. The scale must be greater than or equal to 1. TRACK Set this keyword and events will be generated continuously as the cursor is moved across the original image. If not set, events will only be generated when the mouse button is released. Note: On slow systems, /TRACK performance can be inadequate. The default is 0. UNAME Set this keyword to a string that can be used to identify the widget in your code. You can associate a name with each widget in a specific hierarchy, and then use that name to query the widget hierarchy and get the correct widget ID. To query the widget hierarchy, use the WIDGET_INFO function with the FIND_BY_UNAME keyword. The UNAME should be unique to the widget hierarchy because the FIND_BY_UNAME keyword returns the ID of the first widget with the specified name. UVALUE The "user value" to be assigned to the widget. XSIZE The width of the window (in pixels) for the original image. The default is XSIZE = 500. Note that XSIZE must be set to the width of the original image array for the image to display properly. X_SCROLL_SIZE The width of the visible part of the original image. This may be smaller than the actual width controlled by the XSIZE keyword. The default is 0, for no scroll bar. X_ZSIZE The width of the window for the zoomed image. The default is 250. YSIZE The height of the window (in pixels) for the original image. The default is 500. Note that YSIZE must be set to the height of the original image array for the image to display properly. Y_SCROLL_SIZE The height of the visible part of the original image. This may be smaller than the actual height controlled by the YSIZE keyword. The default is 0, for no scroll bar. Y_ZSIZE The height of the window for the zoomed image. The default is 250. Keywords to WIDGET_CONTROL and WIDGET_INFO The widget ID returned by most compound widgets is actually the ID of the compound widget's base widget. This means that many keywords to the WIDGET_CONTROL and WIDGET_INFO routines that affect or return information on base widgets can be used with compound widgets. In addition, you can use the GET_VALUE and SET_VALUE keywords to WIDGET_CONTROL to obtain or set the value of the zoom widget. The value of the CW_ZOOM widget is the original, un-zoomed image to be displayed (a two- dimensional array). To change the contents of the CW_ZOOM widget, use the command: WIDGET_CONTROL, id, SET_VALUE = array where id is the widget ID of the CW_ZOOM widget and array is the image array. The value of CW_ZOOM cannot be set until the widget has been realized. Note that the size of the original window, set with the XSIZE and YSIZE keywords to CW_ZOOM, must be the size of the input array. To return the current zoomed image as displayed by CW_ZOOM in the variable array, use the command: WIDGET_CONTROL, id, GET_VALUE = array See "Compound Widgets" in Chapter 22 of Building IDL Applications for a more complete discussion of controlling compound widgets using WIDGET_CONTROL and WIDGET_INFO. Widget Events Returned by the CW_ZOOM Widget When the "Report Zoom to Parent" button is pressed, this widget generates event structures with the following definition: event = {ZOOM_EVENT, ID:0L, TOP:0L, HANDLER:0L, $ XSIZE:0L, YSIZE:0L, X0:0L, Y0:0L, X1:0L, Y1:0L } The XSIZE and YSIZE fields contain the dimensions of the zoomed image. The X0 and Y0 fields contain the coordinates of the lower left corner of the original image, and the X1 and Y1 fields contain the coordinates of the upper right corner of the original image. Example The following code samples illustrate a use of the CW_ZOOM widget. First, create an event-handler. Note that clicking on the widget's "Zoom" button displays IDL's help output on the console. PRO widzoom_event, event WIDGET_CONTROL, event.id, GET_UVALUE=uvalue CASE uvalue OF 'ZOOM': HELP, /STRUCT, event 'DONE': WIDGET_CONTROL, event.top, /DESTROY ENDCASE END Next, create the widget program: PRO widzoom OPENR, lun, FILEPATH('people.dat', $ SUBDIR = ['examples','data']), /GET_LUN image=BYTARR(192,192) READU, lun, image FREE_LUN, lun sz = SIZE(image) base=WIDGET_BASE(/COLUMN) zoom=CW_ZOOM(base, XSIZE=sz[1], YSIZE=sz[2], UVALUE='ZOOM') done=WIDGET_BUTTON(base, VALUE='Done', UVALUE='DONE') WIDGET_CONTROL, base, /REALIZE WIDGET_CONTROL, zoom, SET_VALUE=image XMANAGER, 'widzoom', base END Once you have entered these programs, type "widzoom" at the IDL command prompt to run the widget application. See Also ZOOM, ZOOM_24 DBLARR [Previous Routine] [Next Routine] [List of Routines] NAME: DBLARR The DBLARR function returns a double-precision, floating-point vector or array. Syntax Result = DBLARR( D1, ..., D8 [, /NOZERO] ) Arguments Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. 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-precision, floating-point array with every element set to 0.0, enter: D = DBLARR(3, 3) See Also COMPLEXARR, DCOMPLEXARR, FLTARR, INTARR, LON64ARR, LONARR, MAKE_ARRAY, STRARR, UINTARR, ULON64ARR, ULONARR DCINDGEN [Previous Routine] [Next Routine] [List of Routines] NAME: DCINDGEN The DCINDGEN function returns a complex, double-precision, 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. Syntax Result = DCINDGEN( D1, ..., D8 ) Arguments Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. The dimensions of the result. The dimension parameters can be any scalar expression. Up to eight dimensions can be specified. If the dimension arguments are not integer values, IDL will convert them to integer values before creating the new array. Example To create DC, a 4-element vector of complex values with the real parts set to the value of their subscripts, enter: DC = DCINDGEN(4) See Also BINDGEN, CINDGEN, DINDGEN, FINDGEN, INDGEN, LINDGEN, SINDGEN, UINDGEN, UL64INDGEN, ULINDGEN DCOMPLEX [Previous Routine] [Next Routine] [List of Routines] NAME: DCOMPLEX The DCOMPLEX function returns double-precision 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 double-precision 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, DCOMPLEX extracts fields of data from Expression. Syntax Result = DCOMPLEX( Real [, Imaginary] ) or Result = DCOMPLEX( Expression, Offset, Dim1 [, ..., Dim8] ) 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 3, "Constants and Variables" in Building IDL Applications for details. Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. 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 arguments 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 warning message and return 0. The ON_IOERROR procedure can be used to establish a statement to be jumped to in case of such errors. Example Create a complex array from two integer arrays by entering the following commands: ; Create the first integer array: A = [1,2,3] ; Create the second integer array: B = [4,5,6] ; Make A the real parts and B the imaginary parts of the new ; complex array: C = DCOMPLEX(A, B) ; See how the two arrays were combined: PRINT, C IDL prints: ( 1.0000000, 4.0000000)( 2.0000000, 5.0000000) ( 3.0000000, 6.0000000) The real and imaginary parts of the complex array can be extracted as follows: ; Print the real part of the complex array C: PRINT, 'Real Part: ', DOUBLE(C) ; Print the imaginary part of the complex array C: PRINT, 'Imaginary Part: ', IMAGINARY(C) IDL prints: Real Part: 1.0000000 2.0000000 3.0000000 Imaginary Part: 4.0000000 5.0000000 6.0000000 See Also BYTE, COMPLEX, CONJ, DOUBLE, FIX, FLOAT, IMAGINARY, LONG, LONG64, STRING, UINT, ULONG, ULONG64 DCOMPLEXARR [Previous Routine] [Next Routine] [List of Routines] NAME: DCOMPLEXARR The DCOMPLEXARR function returns a complex, double-precision, floating-point vector or array. Syntax Result = DCOMPLEXARR( D1, ..., D8 [, /NOZERO] ) Arguments Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. The dimensions of the result. The dimension parameters may be any scalar expression. Up to eight dimensions can be specified. Keywords NOZERO Normally, DCOMPLEXARR sets every element of the result to zero. If the NOZERO keyword is set, this zeroing is not performed, and DCOMPLEXARR executes faster. Example To create an empty, 5-element by 5-element, complex array DC, enter: DC = DCOMPLEXARR(5, 5) See Also COMPLEXARR, DBLARR, FLTARR, INTARR, LON64ARR, LONARR, MAKE_ARRAY, STRARR, UINTARR, ULON64ARR, ULONARR DEFINE_KEY [Previous Routine] [Next Routine] [List of Routines] NAME: DEFINE_KEY The DEFINE_KEY procedure programs the keyboard function Key with the string Value, or with one of the actions specified by the available keywords. DEFINE_KEY is primarily intended for use with IDL's command line interface (available under UNIX and VMS). IDL's graphical interface (IDLDE), which is available under all operating systems supported by IDL, uses different system- specific mechanisms. Syntax DEFINE_KEY, Key [, Value] [, /MATCH_PREVIOUS] [, /NOECHO] [, /TERMINATE] UNIX Keywords: [, /BACK_CHARACTER] [, /BACK_WORD] [, /CONTROL | , /ESCAPE] [, /DELETE_CHARACTER] [, /DELETE_CURRENT] [, /DELETE_EOL] [, /DELETE_LINE] [, /DELETE_WORD] [, /END_OF_LINE] [, /END_OF_FILE] [, /ENTER_LINE] [, /FORWARD_CHARACTER] [, /FORWARD_WORD] [, /INSERT_OVERSTRIKE_TOGGLE] [, /NEXT_LINE] [, /PREVIOUS_LINE] [, /RECALL] [, /REDRAW] [, /START_OF_LINE] Arguments Key A scalar string containing the name of a function key to be programmed. IDL maintains an internal list of function key names and the escape sequences they send. UNIX - Under UNIX, DEFINE_KEY allows you to set the values of two distinctly different types of keys: * Control characters: Any of the 26 control characters (CTRL+A through CTRL+Z) can be associated with specific actions by specifying the CONTROL keyword. Control characters are the unprintable ASCII characters at the beginning of the ASCII character set. They are usually entered by holding down the Control key while the corresponding letter key is pressed. * Function keys: Most terminals (and terminal emulators) send escape sequences when a function key is pressed. An escape sequence is a sequence of characters starting the ASCII Escape character. Escape sequences follow strict rules that allow applications such as IDL to determine when the sequence is complete. For instance, the left arrow key on most machines sends the sequence [D. The available function keys and the escape sequences they send vary from keyboard to keyboard; IDL cannot be built to recognize all of the different keyboards in existence. The ESCAPE keyword allows you to program IDL with the escape sequences for your keyboard. When you press the function key, IDL will recognize the sequence and take the appropriate action. UNIX - Under UNIX, if Key is not already on IDL's internal list, you must use the ESCAPE keyword to specify 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 procedure should be used once at the beginning of the session to enter the keys for the current keyboard. The following table describes the standard key definitions. Editing Key Function Ctrl+A Move cursor to start of line Ctrl+B Move cursor left one word Ctrl+D EOF if current line is empty, EOL otherwise Ctrl+E Move to end of line Ctrl+F Move cursor right one word Ctrl+K Erase from the cursor to the end of the line Ctrl+N Move back one line in the recall buffer Ctrl+R Retype current line Ctrl+U Delete from current position to start of line Ctrl+W Delete previous word Ctrl+X Delete current character Backspace, Delete Delete previous character ESC-I Overstrike/insert toggle ESC-Delete Delete previous word Up Arrow Move back one line in the recall buffer Down Arrow Move forward one line in the recall buffer Table 15: Standard Key Definitions for UNIX Editing Key Function Left Arrow Move left one character Right Arrow Move right one character R13 Move cursor left one word (Sun keyboards) R15 Move cursor right one word (Sun keyboards) ^text Recall the first line containing text. If text is blank, recall the previous line Other Characters Insert character at the current cursor position Table 15: Standard Key Definitions for UNIX VMS - Under VMS, the key names are those defined by the Screen Management utility (SMG). The following table describes some of these keys. For a complete description, refer to the VMS RTL Screen Management (SMG$) Manual. Key Name Description DELETE Delete previous character. PF1 Recall most recent command that matches supplied string. PF2-PF4 Top row of keypad. KP0-KP9 Keypad keys 0 through 9 ENTER Keypad ENTER key MINUS Keypad "-" key COMMA Keypad "," key PERIOD Keypad "." key FIND Editing keypad FIND key INSERT_HERE Editing keypad INSERT HERE key REMOVE Editing keypad REMOVE key SELECT Editing keypad SELECT key Table 16: VMS Line Editing Keys Key Name Description PREV_SCREEN Editing keypad PREV_SCREEN key NEXT_SCREEN Editing keypad NEXT_SCREEN key Table 16: VMS Line Editing Keys Windows - Under Windows, function keys F2, F4, F11, and F12 can be customized. In IDL for Windows, three special variables can be used to expand the current mouse selection, the current line, or the current filename into the output of defined keys. Variable Expansion %f filename of the currently-selected IDL Editor window %l number of the current line in an IDL Editor window %s Currently-selected text from an IDL Output Log or Editor window Table 17: Variable expansions for defined keys For example, to define F2 as a key that executes an IDL PRINT command with the current mouse selection as its argument, use the command: DEFINE_KEY, 'F2', 'PRINT, "%S"' Dragging the mouse over any text in an IDL Editor or Output Log window and pressing F1 causes the selected text to be printed. The %l and %f variables can be used in a similar fashion. 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, otherwise 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 current cursor position left one character. BACK_WORD Set this keyword to program Key to move the current cursor position left one word. CONTROL Set this keyword to indicate that Key is the name of a control key. The default is for Key to define a function key escape sequence. To view the names used by IDL for the control keys, type the following at the Command Input Line: HELP, /ALL_KEYS Warning The CONTROL and ESCAPE keywords are mutually exclusive and cannot be specified together. 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 cursor to the end of the line. END_OF_FILE Set this keyword to program Key to exit IDL if the current line is empty, and to end the current input line if the current line is not empty. 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 "Defining New Function Keys" on page 372 for further details. Warning The CONTROL and ESCAPE keywords are mutually exclusive and cannot be specified together. FORWARD_CHARACTER Set this keyword to program Key to move the current cursor position right one character. FORWARD_WORD Set this keyword to program Key to move the current cursor position right one word. INSERT_OVERSTRIKE_TOGGLE Set this keyword to program Key to toggle between "insert" and "overstrike" mode. When characters 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 corresponding to the entered number becomes the current command. In order to view the currently saved commands and the number currently associated with each, enter the IDL command: HELP, /RECALL COMMANDS Example 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. IDL> PRINT, 1 1IDL> PRINT, 2 2IDL> HELP, /RECALL_COMMANDS Recall buffer length: 20 1 PRINT, 2 2 PRINT, 1 User presses key tied to RECALL. IDL> Line 2 is requested. Recall Line #: 2 Saved command 2 is recalled. IDL> PRINT, 1 1 User presses return. Recall Line #: Saved command 2 is recalled again. IDL> PRINT, 2 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 cursor 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 command: 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 provided 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 definitions in a startup file, so that they will always be available. See "Startup File" in Chapter 2 of Using IDL. Usually, the SETUP_KEYS procedure 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 The CONTROL keyword alters the action that IDL takes when it sees the specified characters defining the control keys. IDL may not be able to alter the behavior of some control characters. For example, CTRL+S and CTRL+Q are usually reserved by the operating system for flow control. Similarly, CTRL+Z is usually The UNIX suspend character. Example CTRL+D is the UNIX end-of-file character. It is a common UNIX convention (followed by IDL) for programs to quit upon encountering CTRL+D.However, CTRL+D is also used by some text editors to delete characters. To disable IDL default handling of CTRL+D, type the following: DEFINE_KEY, /CONTROL, '^D' To print a reminder of how to exit IDL properly, type the following: DEFINE_KEY, /CONTROL, '^D', "print, 'Enter EXIT to quit IDL'", $ /NOECHO, /TERMINATE To use CTRL+D to delete characters, type the following: DEFINE_KEY, /CONTROL, '^D', /DELETE_CURRENT See Also GET_KBRD DEFROI [Previous Routine] [Next Routine] [List of Routines] NAME: DEFROI The DEFROI function defines an irregular region of interest of an image using the image display system and the cursor and mouse. The result is a vector of subscripts of the pixels inside the region. The lowest bit in which the write mask is enabled is changed. DEFROI only works for interactive, pixel oriented devices with a cursor and an exclusive or writing mode. Regions may have at most 1000 vertices. Warning DEFROI does not function correctly when used with draw widgets. See CW_DEFROI. This routine is written in the IDL language. Its source code can be found in the file defroi.pro in the lib subdirectory of the IDL distribution. Using DEFROI After calling DEFROI, click in the image with the left mouse button to mark points on the boundary of the region of interest. The points are connected in sequence. Alternatively, press and hold the left mouse button and drag to draw a curved region. Click the middle mouse button to erase points. The most recently-placed point is erased first. Click the right mouse button to close the region. The function returns after the region has been closed. Syntax Result = DEFROI( Sx, Sy [, Xverts, Yverts] [, /NOREGION] [, /NOFILL] [, /RESTORE] [, X0=device_coord, Y0=device_coord] [, ZOOM=factor] ) Arguments Sx, Sy Integers specifying the horizontal and vertical size of image, in pixels. Xverts, Yverts Named vectors that will contain the vertices of the enclosed region. Keywords NOREGION Set this keyword to inhibit the return of the pixel subscripts. NOFILL Set this keyword to inhibit filling of the defined region on completion. RESTORE Set this keyword to restore the display to its original state upon completion. X0, Y0 Set these keywords equal to the coordinates of the lower left corner of the displayed image (in device coordinates). If omitted, the default value (0,0) is used. ZOOM Set this keyword equal to the zoom factor. If not specified, a value of 1 is assumed. Example ; Create an image: TVSCL, DIST(200,200) ; Call DEFROI. The cursor becomes active in the graphics window. ; Define a region and click the right mouse button: X = DEFROI(200, 200) ; Print subscripts of points included in the defined region: PRINT, X See Also CW_DEFROI DEFSYSV [Previous Routine] [Next Routine] [List of Routines] NAME: DEFSYSV The DEFSYSV procedure creates a new system variable called Name initialized to Value. Syntax DEFSYSV, Name, Value [, Read_Only] [, EXISTS=variable] Arguments Name A scalar string containing the name of the system 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 nonzero, 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 modified. 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 variable called !NEWVAR with an initial value of 2.0, enter: DEFSYSV, '!NEWVAR', 2.0 You can both define and use a system variable within a single procedure: PRO foo DEFSYSV, '!foo', $ 'Rocky, watch me pull a squirrel out of my hat!' ; Print !foo after defining it: PRINT, !foo END DELETE_SYMBOL [Previous Routine] [Next Routine] [List of Routines] NAME: DELETE_SYMBOL The DELETE_SYMBOL procedure deletes a DCL (Digital Command Language) interpreter symbol for the current process. Note This procedure is available on VMS only. Syntax DELETE_SYMBOL, Name [, TYPE={1 | 2}] Arguments Name A scalar string containing the name of the symbol 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. See Also DELLOG, SET_SYMBOL, SETLOG DELLOG [Previous Routine] [Next Routine] [List of Routines] NAME: DELLOG The DELLOG procedure deletes a VMS logical name. Note This procedure is available on VMS only. Syntax DELLOG, Lognam [, TABLE=string] Arguments Lognam A scalar string containing the name of the logical 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. See Also DELETE_SYMBOL, SET_SYMBOL, SETENV, SETLOG DELVAR [Previous Routine] [Next Routine] [List of Routines] NAME: 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 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. Syntax 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 See Also TEMPORARY DERIV [Previous Routine] [Next Routine] [List of Routines] NAME: DERIV The DERIV function performs numerical differentiation using 3-point, Lagrangian interpolation and returns the derivative. Syntax Result = DERIV([X,] Y) Arguments X Differentiate with respect to this variable. If omitted, unit spacing for Y (i.e., Xi = i) is assumed. Y The variable to be differentiated. Example X = [ 0.1, 0.3, 0.4, 0.7, 0.9] Y = [ 1.2, 2.3, 3.2, 4.4, 6.6] PRINT, DERIV(Y) PRINT, DERIV(X,Y) IDL prints: 1.20000 1.00000 1.05000 1.70000 2.70000 8.00000 6.66667 5.25000 6.80000 10.800 See Also DERIVSIG DERIVSIG [Previous Routine] [Next Routine] [List of Routines] NAME: DERIVSIG The DERIVSIG function computes the standard deviation of a derivative as found by the DERIV function, using the input variables of DERIV and the standard deviations of those input variables. Syntax Result = DERIVSIG( [X, Y, Sigx,] Sigy ) Arguments X Differentiate with respect to this variable. If omitted, unit spacing for Y (i.e., Xi = i) is assumed. Y The variable to be differentiated. Omit if X is omitted. Sigx The standard deviation of X (either vector or constant). Use "0.0" if the abscissa is exact; omit if X is omitted. Sigy The standard deviation of Y. Sigy must be a vector if the other arguments are omitted, but may be either a vector or a constant if X, Y, and Sigx are supplied. See Also DERIV DETERM [Previous Routine] [Next Routine] [List of Routines] NAME: DETERM The DETERM function computes the determinant of an n by n array. LU decomposition is used to represent the input array in triangular form. The determinant is then computed as the product of diagonal elements of the triangular form. Row interchanges are tracked during the LU decomposition to ensure the correct sign. This routine is written in the IDL language. Its source code can be found in the file determ.pro in the lib subdirectory of the IDL distribution. Syntax Result = DETERM( A [, /CHECK] [, /DOUBLE] [, ZERO=value] ) Arguments A An n by n single- or double-precision floating-point array. Keywords CHECK Set this keyword to check A for singularity. The determinant of a singular array is returned as zero if this keyword is set. Run-time errors may result if A is singular and this keyword is not set. DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. ZERO Use this keyword to set the absolute value of the floating-point zero. A floating-point zero on the main diagonal of a triangular array results in a zero determinant. For single-precision inputs, the default value is 1.0 × 10-6. For double-precision inputs, the default value is 1.0 × 10-12. Setting this keyword to a value less than the default may improve the precision of the result. Example ; Define an array A: A = [[ 2.0, 1.0, 1.0], $ [ 4.0, -6.0, 0.0], $ [-2.0, 7.0, 2.0]] ; Compute the determinant: PRINT, DETERM(A) IDL prints: -16.0000 See Also COND, INVERT DEVICE [Previous Routine] [Next Routine] [List of Routines] NAME: DEVICE The DEVICE procedure provides device-dependent control over the current graphics device (as set by the SET_PLOT routine). The IDL graphics procedures and functions 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 various keywords that differ from device to device. See Appendix B, "IDL Graphics Devices" for a description of the keywords available for each graphics device. Syntax Note Each keyword to DEVICE is followed by the device(s) to which it applies. DEVICE [, LANUAGE_LEVEL] [, TRUE_COLOR] [, /AVANTGARDE | , /BKMAN | , /COURIER | , /HELVETICA | , /ISOLATIN1 | , /PALATINO | , /SCHOOLBOOK | , /SYMBOL | , TIMES | , ZAPFCHANCERY | , ZAPFDINGBATS {PS}] [, /AVERAGE_LINES{REGIS}] [, /BINARY | , /NCAR | , /TEXT {CGM}] [, BITS_PER_PIXEL={1 | 2 | 4 | 8}{PS}] [, /BOLD{PS}] [, /BOOK{PS}] [, /BYPASS_TRANSLATION{MAC, WIN, X}] [, /CLOSE{Z}] [, /CLOSE_DOCUMENT{PRINTER}] [, /CLOSE_FILE{CGM, HP, LJ, METAFILE, PCL, PS, REGIS, TEK}] [, /COLOR{PCL, PS}] [, COLORS=value{CGM, TEK}] [, COPY=[Xsource, Ysource, cols, rows, Xdest, Ydest [, Window_index]]{MAC, WIN, X}] [, /CURSOR_CROSSHAIR{WIN, X}] [, CURSOR_IMAGE=value{16-element short int vector}{MAC, WIN, X}] [, CURSOR_MASK=value{MAC, WIN, X}] [, /CURSOR_ORIGINAL{MAC, WIN, X}] [, CURSOR_STANDARD=value{MAC: crosshair=1}{WIN: arrow=32512, I-beam=32513, hourglass=32514, black cross=32515, up arrow=32516, size(NT)=32640, icon(NT)=32641, size NW-SE=32642, size NE-SW=32643, size E- W=32644, size N-S=32645}{X: one of the values in file cursorfonts.h}] [, CURSOR_XY=[x,y]{MAC, WIN, X}] [, /DECOMPOSED{MAC, WIN, X}] [, DEPTH=value{significant bits per pixel}{LJ}] [, /DIRECT_COLOR{X}] [, EJECT={0 | 1 | 2}{HP}] [, ENCAPSULATED={0 | 1}{PS}] [, ENCODING={1 (binary) | 2 (text) | 3 (NCAR binary)}{CGM}] [, FILENAME=filename{CGM, HP, LJ, METAFILE, PCL, PS, REGIS, TEK}] [, /FLOYD{LJ, MAC, PCL, X}] [, FONT_INDEX=integer{PS}] [, FONT_SIZE=points{PS}] [, GET_CURRENT_FONT=variable{MAC, METAFILE, PRINTER, WIN, X}] [, GET_DECOMPOSED=variable{MAC, WIN, X}] [, GET_FONTNAMES=variable{MAC, METAFILE, PRINTER, WIN, X}] [, GET_FONTNUM=variable{MAC, METAFILE, PRINTER, WIN, X}] [, GET_GRAPHICS_FUNCTION=variable{MAC, WIN, X, Z}] [, GET_PAGESIZE=variable{PRINTER}] [, GET_SCREEN_SIZE=variable{MAC, WIN, X}] [, GET_VISUAL_DEPTH=variable{MAC, WIN, X}] [, GET_VISUAL_NAME=variable{MAC, WIN, X}] [, GET_WINDOW_POSITION=variable{MAC, WIN, X}] [, GET_WRITE_MASK=variable{X, Z}] [, GIN_CHARS=number_of_characters{TEK}] [, GLYPH_CACHE=number_of_glyphs{MAC, METAFILE, PRINTER, PS, WIN, Z}] [, /INCHES{HP, LJ, PCL, METAFILE, PRINTER, PS}] [, /INDEX_COLOR{METAFILE, PRINTER}] [, /ITALIC{PS}] [, /LANDSCAPE | , /PORTRAIT{HP, LJ, PCL, PRINTER, PS}] [, /DEMI | , /LIGHT | , /MEDIUM | , /NARROW | , /OBLIQUE{PS}] [, OPTIMIZE={0 | 1 | 2}{PCL}] [, /ORDERED{LJ, MAC, PCL, X}] [, OUTPUT=scalar string{HP, PS}] [, /PIXELS{LJ, PCL}] [, PLOT_TO=logical unit num{REGIS, TEK}] [, /PLOTTER_ON_OFF{HP}] [, /POLYFILL{HP}] [, PRE_DEPTH=value{PS}] [, PRE_XSIZE=width{PS}] [, PRE_YSIZE=height{PS}] [, /PREVIEW{PS}] [, PRINT_FILE=filename{WIN}] [, /PSEUDO_COLOR{MAC, X}] [, RESET_STRING=string{TEK}] [, RESOLUTION=value{LJ, PCL}] [, RETAIN={0 | 1 | 2}{MAC, WIN, X}] [, SCALE_FACTOR=value{PRINTER, PS}] [, SET_CHARACTER_SIZE=[font size, line spacing]{CGM, HP, LJ, MAC, METAFILE, PCL, PS, REGIS, TEK, WIN, X, Z}] [, SET_COLORMAP=value{14739-element byte vector}{PCL}] [, SET_COLORS=value{2 to 256}{Z}] [, SET_FONT=scalar string{MAC, METAFILE, PRINTER, PS, WIN, Z}] [, SET_GRAPHICS_FUNCTION=code{0 to 15}{MAC, WIN, X, Z}] [, SET_RESOLUTION=[width, height]{Z}] [, SET_STRING=string{TEK}] [, SET_TRANSLATION=variable{X}] [, SET_WRITE_MASK=value{0 to 2n-1 for n-bit system}{X, Z}] [, STATIC_COLOR=value{bits per pixel}{X}] [, STATIC_GRAY=value{bits per pixel}{X}] [, /TEK4014{TEK}] [, TEK4100{TEK}] [, THRESHOLD=value{LJ, MAC, PCL, X}] [, TRANSLATION=variable{MAC, WIN, X}] [, TRUE_COLOR=value{bits per pixel}{MAC, METAFILE, PRINTER, X}] [, /TT_FONT{MAC, METAFILE, PRINTER, WIN, X, Z}] [, /TTY{REGIS, TEK}] [, /VT240 | , /VT241 | , /VT340 | , /VT341 {REGIS}] [, WINDOW_STATE=variable{MAC, WIN, X}] [, XOFFSET=value{HP, LJ, PCL, PRINTER, PS}] [, XON_XOFF={0 | 1 (default)}{HP}] [, XSIZE=width{HP, LJ, METAFILE, PCL, PRINTER, PS}] [, YOFFSET=value{HP, LJ, PCL, PRINTER, PS}] [, YSIZE=height{HP, LJ, PCL, METAFILE, PRINTER, PS}] [, Z_BUFFERING={0 | 1 (default)}{Z}] Keywords TRUE_COLOR You can now use this keyword to specify any TrueColor visual depth. The most common are 15, 16, and 24. LANUAGE_LEVEL Set this keyword to indicate the language level of the PostScript output that is to be generated by the device. Valid values include 1 (the default) and 2 (required for some features, such as filled patterns for polygons). See "Keywords Accepted by the IDL Devices" on page 2311. Example The following example retains the name of the current graphics device, sets plotting to the PostScript device, makes a PostScript file, then resets plotting to the original device: ; The NAME field of the !D system variable contains the name of the ; current plotting device. mydevice = !D.NAME ; Set plotting to PostScript: SET_PLOT, 'PS' ; Use DEVICE to set some PostScript device options: DEVICE, FILENAME='myfile.ps', /LANDSCAPE ; Make a simple plot to the PostScript file: PLOT, FINDGEN(10) ; Close the PostScript file: DEVICE, /CLOSE ; Return plotting to the original device: SET_PLOT, mydevice DFPMIN [Previous Routine] [Next Routine] [List of Routines] NAME: DFPMIN The DFPMIN procedure minimizes a user-written function Func of two or more independent variables using the Broyden-Fletcher-Goldfarb-Shanno variant of the Davidon-Fletcher-Powell method, using its gradient as calculated by a user-written function Dfunc. DFPMIN is based on the routine dfpmin described in section 10.7 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press, and is used by permission. Syntax DFPMIN, X, Gtol, Fmin, Func, Dfunc [, /DOUBLE] [, EPS=value] [, ITER=variable] [, ITMAX=value] [, STEPMAX=value] [, TOLX=value] Arguments X On input, X is an n-element vector specifying the starting point. On output, it is replaced with the location of the minimum. Gtol An input value specifying the convergence requirement on zeroing the gradient. Fmin On output, Fmin contains the value at the minimum-point X of the user-supplied function specified by Func. Func A scalar string specifying the name of a user-supplied IDL function of two or more independent variables to be minimized. This function must accept a vector argument X and return a scalar result. For example, suppose we wish to find the minimum value of the function y = (x0 ­ 3)4 + (x1 ­ 2)2 To evaluate this expression, we define an IDL function named MINIMUM: FUNCTION minimum, X RETURN, (X[0] - 3.0)^4 + (X[1] - 2.0)^2 END Dfunc A scalar string specifying the name of a user-supplied IDL function that calculates the gradient of the function specified by Func. This function must accept a vector argument X and return a vector result. For example, the gradient of the above function is defined by the partial derivatives: y -------- = 4(x ­ )3 y , -------- = 2(x ­ ) x 0 3 1 2 0 x1 We can write a function GRAD to express these relationships in the IDL language: FUNCTION grad, X RETURN, [4.0*(X[0] - 3.0)^3, 2.0*(X[1] - 2.0)] END Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. EPS Use this keyword to specify a number close to the machine precision. For single- precision calculations, the default value is 3.0 × 10-8. For double-precision calculations, the default value is 3.0 × 10-16. ITER Use this keyword to specify a named variable which returns the number of iterations performed. ITMAX Use this keyword to specify the maximum number of iterations allowed. The default value is 200. STEPMAX Use this keyword to specify the scaled maximum step length allowed in line searches. The default value is 100.0 TOLX Use this keyword to specify the convergence criterion on X values. The default value is 4 x EPS. Example To minimize the function MINIMUM: PRO example_dfpmin ; Make an initial guess (the algorithm's starting point): X = [1.0, 1.0] ; Set the convergence requirement on the gradient: Gtol = 1.0e-7 ; Find the minimizing value: DFPMIN, X, Gtol, Fmin, 'minimum', 'grad' ; Print the minimizing value: PRINT, X END FUNCTION minimum, X RETURN, (X[0] - 3.0)^4 + (X[1] - 2.0)^2 END FUNCTION grad, X RETURN, [4.0*(X[0] - 3.0)^3, 2.0*(X[1] - 2.0)] END IDL prints: 3.00175 2.00000 See Also POWELL DIALOG_MESSAGE [Previous Routine] [Next Routine] [List of Routines] NAME: DIALOG_MESSAGE The DIALOG_MESSAGE function creates a modal (blocking) dialog box that can be used to display information for the user. The dialog must be dismissed, by clicking on one of its option buttons, before execution of the widget program can continue. This function differs from widgets in a number of ways. The DIALOG_MESSAGE dialog does not exist as part of a widget tree, has no children, does not exist in an unrealized state, and generates no events. Instead, the dialog is displayed whenever this function is called. While the DIALOG_MESSAGE dialog is displayed, widget activity is limited because the dialog is modal. The function does not return to its caller until the user selects one of the dialog's buttons. Once a button has been selected, the dialog disappears. DIALOG_MESSAGE returns a string containing the text of the label that the user selected. There are four basic dialogs that can be displayed. The default type is "Warning". Other types can be selected by setting one of the keywords described below. Each dialog type displays different buttons. Additionally any dialog can be made to show a "Cancel" button by setting the CANCEL keyword. The four types of dialogs are described in the table below: Dialog Type Default Buttons Error OK Warning OK Question Yes, No Information OK Table 18: Types of DIALOG_MESSAGE Dialogs Syntax Result = DIALOG_MESSAGE( Message_Text [, /CANCEL] [, /DEFAULT_CANCEL | , /DEFAULT_NO] [, DIALOG_PARENT=widget_id] [, DISPLAY_NAME=string] [, /ERROR | , /INFORMATION | , /QUESTION] [, RESOURCE_NAME=string] [, TITLE=string] ) Arguments Message_Text A scalar string or string array that contains the text of the message to be displayed. If this argument is set to an array of strings, each array element is displayed as a separate line of text. Keywords CANCEL Set this keyword to add a "Cancel" button to the dialog. DEFAULT_CANCEL Set this keyword to make the "Cancel" button the default selection for the dialog. The default selection is the button that is selected when the user presses the default keystroke (usually Space or Return depending on the platform). Setting DEFAULT_CANCEL implies that the CANCEL keyword is also set. DEFAULT_NO Set this keyword to make the "No" button the default selection for "Question" dialogs. Normally, the default is "Yes". DIALOG_PARENT Set this keyword to the widget ID of a widget over which the message dialog should be positioned. When displayed, the DIALOG_MESSAGE dialog will be positioned over the specified widget. Dialogs are often related to a non-dialog widget tree. The ID of the widget in that tree to which the dialog is most closely related should be specified. This keyword is ignored on Macintosh platforms. DISPLAY_NAME Set this keyword equal to a string indicating the name of the X Windows display on which the dialog is to appear. This keyword is ignored if the DIALOG_PARENT keyword is specified. This keyword is also ignored on Microsoft Windows and Macintosh platforms. ERROR Set this keyword to create an "Error" dialog. The default dialog type is "Warning". INFORMATION Set this keyword to create an "Information" dialog. The default dialog type is "Warning". QUESTION Set this keyword to create a "Question" dialog. The default dialog type is "Warning". RESOURCE_NAME A string containing an X Window System resource name to be applied to the dialog. See "RESOURCE_NAME" on page 1544 for a complete discussion of this keyword. TITLE Set this keyword to a scalar string that contains the text of a title to be displayed in the dialog frame. If this keyword is not specified, the dialog has the dialog type as its title as shown in the table under DIALOG_MESSAGE. This keyword is ignored on Macintosh platforms. See Also XDISPLAYFILE DIALOG_PICKFILE [Previous Routine] [Next Routine] [List of Routines] NAME: DIALOG_PICKFILE The DIALOG_PICKFILE function allows the user to interactively pick a file, or multiple files, using the platform's own native graphical file-selection dialog. The user can also enter the name of a file that does not exist (see the description of the WRITE keyword, below). Syntax Result = DIALOG_PICKFILE( [, /DIRECTORY] [, DIALOG_PARENT=widget_id] [, DISPLAY_NAME=string] [, FILE=string] [, FILTER=string/string array] [, /FIX_FILTER] [, GET_PATH=variable] [, GROUP=widget_id] [, /MULTIPLE_FILES] [, /MUST_EXIST] [, PATH=string] [, /READ | , /WRITE] [, /RESOURCE_NAME] [, TITLE=string] ) Return Value DIALOG_PICKFILE returns a string array that contains the full path name of the selected file or files. If no file is selected, DIALOG_PICKFILE returns a null string. Keywords DIALOG_PARENT Set this keyword to the widget ID of a widget to be used as the parent of this dialog. DIRECTORY Set this keyword to display only the existing directories in the current directory. Individual files are not displayed. DISPLAY_NAME Set this keyword equal to a string that specifies the name of the X Windows display on which the dialog should be displayed. This keyword is ignored on Microsoft Windows and Macintosh platforms. FILE Set this keyword to a scalar string that contains the name of the initial file selection. This keyword is useful for specifying a default filename. On Windows, this keyword also has the effect of filtering the file list if a wildcard is used, but this keyword should be used to specify a specific filename. To list only files of a certain type, use the FILTER keyword. FILTER Set this keyword to a string value or an array of strings specifying the file types to be displayed in the file list. This keyword is used to reduce the number of files displayed in the file list. The user can modify the filter unless the FIX_FILTER keyword is set. If the value contains a vector of strings, multiple filters are used to filter the files. The filter, *.*, is automatically added to any filter you specify. Under Microsoft Windows, the user cannot modify the filter. (The user can, however, enter a filter string in the filename field to filter the files displayed.) On the Macintosh, the filter is not displayed if the WRITE keyword is set. On UNIX, the FILTER keyword does not support specifying more than one filter. If you specify more than one filter, all files in the current directory will be displayed. For example, to display only files of type .jpg, .tif, or .png in the file selection window, you could use the following code: file = DIALOG_PICKFILE(/READ, $ FILTER = ['*.jpg', '*.tif', '*.png']) FIX_FILTER When this keyword is set, only files that satisfy the filter can be selected. The user has no ability to modify the filter and the filter is not shown. Under Microsoft Windows, the user cannot modify the filter even if FIX_FILTER is not set. Note that the user can enter a filter string in the filename field of the dialog to change the filter condition even if FIX_FILTER is set. GET_PATH Set this keyword to a named variable in which the path of the selection is returned. GROUP This keyword is obsolete and has been replaced by the DIALOG_PARENT keyword. Code that uses the GROUP keyword will continue to function as before, but we suggest that all new code use DIALOG_PARENT. MULTIPLE_FILES Set this keyword to allow for multiple file selection in the file-selection dialog. When you set this keyword, the user can select multiple files using the platform-specific selection method. The currently selected files appear in the selection text field of the dialog. With this keyword set, DIALOG_PICKFILE can return a string array that contains the full path name of the selected file or files. MUST_EXIST Set this keyword to allow only files that already exist to be selected. PATH Set this keyword to a string that contains the initial path from which to select files. If this keyword is not set, the current working directory is used. READ Set this keyword to make the title of the dialog "Select File to Read". TITLE Set this keyword to a scalar string to be used for the dialog title. If it is not specified, the default title is "Please Select a File". This keyword is ignored on Macintosh platforms. WRITE Set this keyword to make the title of the dialog "Select File to Write". Note On the Macintosh, you must set the WRITE keyword in order to be able to enter the name of a file that does not exist. As a result, the FILTER and FIX_FILTER keywords are ignored when the WRITE keyword is specified on a Macintosh. DIALOG_PRINTERSETUP [Previous Routine] [Next Routine] [List of Routines] NAME: DIALOG_PRINTERSETUP The DIALOG_PRINTERSETUP function opens a native dialog for setting the applicable properties for a particular printer. DIALOG_PRINTERSETUP returns a nonzero value if the user pressed the "OK" button in the dialog, or zero otherwise. You can use the result of this function to programmatically begin printing. Syntax Result = DIALOG_PRINTERSETUP( [PrintDestination] [, DIALOG_PARENT=widget_id] [, DISPLAY_NAME=string] [, RESOURCE_NAME=string] [, TITLE=string] ) Arguments PrintDestination An instance of the IDLgrPrinter object for which setup properties are to be set. If no PrintDestination is specified, the printer used by the IDL Direct Graphics printer device is modified. Keywords DIALOG_PARENT Set this keyword to the widget ID of a widget to be used as the parent of this dialog. DISPLAY_NAME Set this keyword equal to a string indicating the name of the X Windows display on which the dialog is to appear. This keyword is ignored if the DIALOG_PARENT keyword is specified, and is also ignored on Windows and Macintosh platforms. RESOURCE_NAME Set this keyword equal to a string containing an X Window System resource name to be applied to the dialog. TITLE Set this keyword equal to a string to be displayed on the dialog frame. This keyword is ignored on Windows and Macintosh platforms. See Also DIALOG_PRINTJOB DIALOG_PRINTJOB [Previous Routine] [Next Routine] [List of Routines] NAME : DIALOG_PRINTJOB The DIALOG_PRINTJOB function opens a native dialog that allows you to set parameters for a printing job (number of copies to print, for example). Syntax Result = DIALOG_PRINTJOB( [PrintDestination] [, DIALOG_PARENT=widget_id] [, DISPLAY_NAME=string] [, RESOURCE_NAME=string] [, TITLE=string] ) Return Value DIALOG_PRINTJOB returns a nonzero value if the user pressed the "OK" button in the dialog, or zero otherwise. You can use the result of this function to programmatically begin printing. Arguments PrintDestination An instance of the IDLgrPrinter object for which a printing job is to be initiated. If no PrintDestination is specified, the printer used by the IDL Direct Graphics printer device is modified. Keywords DIALOG_PARENT Set this keyword to the widget ID of a widget to be used as the parent of this dialog. DISPLAY_NAME Set this keyword to a string indicating the name of the X Windows display on which the dialog is to appear. This keyword is ignored if the DIALOG_PARENT keyword is specified, and is also ignored on Windows and Macintosh platforms. RESOURCE_NAME Set this keyword to a string containing an X Window System resource name to be applied to the dialog. TITLE Set this keyword to a string to be displayed on the dialog frame. This keyword is ignored on Windows and Macintosh platforms. See Also DIALOG_PRINTERSETUP DIALOG_READ_IMAGE [Previous Routine] [Next Routine] [List of Routines] NAME: DIALOG_READ_IMAGE The DIALOG_READ_IMAGE function is a graphical interface used for reading image files. The interface is created as a modal dialog with an optional parent widget. Syntax Result = DIALOG_READ_IMAGE ( [Filename] [, BLUE=variable] [, DIALOG_PARENT=widget_id] [, FILE=variable] [, FILTER_TYPE=string] [, /FIX_FILTER] [, GET_PATH=variable] [, GREEN=variable] [, IMAGE=variable] [, PATH=string] [, QUERY=variable] [, RED=variable] [ ,TITLE=string] ) Return Value This function returns 1 if the "Open" button was clicked, and 0 if the "Cancel" button was clicked. Arguments Filename An optional scalar string containing the full pathname of the file to be highlighted. Keywords BLUE Set this keyword to a named variable that will contain the blue channel vector (if any). DIALOG_PARENT The widget ID of a widget that calls DIALOG_READ_IMAGE. When this ID is specified, a death of the caller results in the death of the DIALOG_READ_IMAGE dialog. If DIALOG_PARENT is not specified, then the interface is created as a modal, top-level widget. FILE Set this keyword to a named variable that will contain the selected filename with full path when the dialog is created. FILTER_TYPE Set this keyword to a scalar string containing the format type the dialog filter should begin with. The default is "Image Files". The user cannot modify the filter if the FIX_FILTER keyword is set. Valid values are obtained from the list of supported image types returned from QUERY_IMAGE. In addition, there is also the "All Files" type. If set to "All Files", queries will only happen on filename clicks, making the dialog much more efficient. Example: FILTER='.jpg, .tiff' FIX_FILTER When this keyword is set, only files that satisfy the filter can be selected. The user has no ability to modify the filter. GET_PATH Set this keyword to a named variable in which the path of the selection is returned. GREEN Set this keyword to a named variable that will contain the green channel vector (if any). IMAGE Set this keyword to a named variable that will contain the image array read. If Cancel was clicked, no action is taken. PATH Set this keyword to a string that contains the initial path from which to select files. If this keyword is not set, the current working directory is used. QUERY Set this keyword to a named variable that will return the QUERY_IMAGE structure associated with the returned image. If the "Cancel" button was pressed, the variable set to this keyword is not changed. If an error occurred during the read, the FILENAME field of the structure will be a null string. RED Set this keyword to a named variable that will contain the red channel vector (if any). TITLE Set this keyword to a scalar string to be used for the dialog title. If it is not specified, the default title is "Select Image File". See Also DIALOG_WRITE_IMAGE DIALOG_WRITE_IMAGE [Previous Routine] [Next Routine] [List of Routines] NAME: DIALOG_WRITE_IMAGE The DIALOG_WRITE_IMAGE function is a graphical user interface used for writing image files. The interface is created as a modal dialog with an optional parent widget. Syntax Result = DIALOG_WRITE_IMAGE ( Image [, R, G, B] [, DIALOG_PARENT=widget_id] [, FILE=string] [, /FIX_TYPE] [, /NOWRITE] [, OPTIONS=variable] [, PATH=string] [ ,TITLE=string] [, TYPE=variable] [, /WARN_EXIST] ) Return Value This routine returns 1 if the "Save" button was clicked, and 0 if the "Cancel" button was clicked. Arguments Image The array to be written to the image file. R, G, B These are optional arguments defining the Red, Green, and Blue color tables to be associated with the image array. Keywords DIALOG_PARENT The widget ID of a widget that calls DIALOG_WRITE_IMAGE. When this ID is specified, a death of the caller results in the death of the DIALOG_WRITE_IMAGE dialog. If DIALOG_PARENT is not specified, then the interface is created as a modal, top-level widget. FILE Set this keyword to a scalar string that contains the name of the initial file selection. This keyword is useful for specifying a default filename. FIX_TYPE When this keyword is set, only files that satisfy the type can be selected. The user has no ability to modify the type. NOWRITE Set this keyword to prevent the dialog from writing the file when "Save" is clicked. No data conversions will take place when the save type is chosen. OPTIONS Set this keyword to a named variable to contain a structure of the chosen options by the user, including the filename and image type chosen. PATH Set this keyword to a string that contains the initial path from which to select files. If this keyword is not set, the current working directory is used. TITLE Set this keyword to a scalar string to be used for the dialog title. If it is not specified, the default title is "Save Image File". TYPE Set this keyword to a scalar string containing the format type the "Save as type" field should begin with. The default is "TIFF". The user can modify the type unless the FIX_TYPE keyword is set. Valid values are obtained from the list of supported image types returned from QUERY_IMAGE. The "Save as type" field will reflect the type of the selected file (if one is selected). WARN_EXIST Set this keyword to produce a question dialog if the user selects a file that already exists. The default is to quietly overwrite the file. See Also DIALOG_READ_IMAGE DIGITAL_FILTER [Previous Routine] [Next Routine] [List of Routines] NAME: DIGITAL_FILTER The DIGITAL_FILTER function returns the coefficients of a non-recursive, digital filter for evenly spaced data points. Frequencies are expressed in terms of the Nyquist frequency, 1/2T, where T is the time between data samples. Highpass, lowpass, bandpass and bandstop filters may be constructed with this function. This routine is written in the IDL language. Its source code can be found in the file digital_filter.pro in the lib subdirectory of the IDL distribution. Syntax Result = DIGITAL_FILTER( Flow, Fhigh, A, Nterms ) Return Value This function returns a vector of coefficients with (2 × Nterms + 1) elements. Arguments Flow The lower frequency of the filter as a fraction of the Nyquist frequency Fhigh The upper frequency of the filter as a fraction of the Nyquist frequency. The following conditions are necessary for various types of filters: * No Filtering: Flow = 0, Fhigh = 1 * Low Pass: Flow = 0, 0 < Fhigh < 1 * High Pass: 0 < Flow < 1, Fhigh =1 * Band Pass: 0 < Flow < Fhigh < 1 * Band Stop: 0 < Fhigh < Flow < 1 A The filter power relative to the Gibbs phenomenon wiggles in decibels. 50 is a good choice. Nterms The number of terms used to construct the filter. Example ; Get coefficients: Coeff = DIGITAL_FILTER(Flow, Fhigh, A, Nterms) ; Apply the filter: Yout = CONVOL(Yin, Coeff) See Also CONVOL, LEEFILT, MEDIAN, SMOOTH DILATE [Previous Routine] [Next Routine] [List of Routines] NAME: DILATE The DILATE function implements the morphologic dilation operator on both binary and grayscale images. For details on using DILATE, see "Using DILATE" on page 410. Syntax Result = DILATE( Image, Structure [, X0 [, Y0 [, Z0]]] [, /CONSTRAINED [, BACKGROUND=value]] [, /GRAY [, /PRESERVE_TYPE | , /UINT | , /ULONG]] [, VALUES=array] ) Arguments Image A one-, two-, or three-dimensional array upon which the dilation is to be performed. If the 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-, two-, or three-dimensional array that represents the structuring element. Elements are interpreted as binary: values are either zero or nonzero. This argument must have the same number of dimensions as Image. X0, Y0, Z0 Optional parameters specifying the one-, two-, or three-dimensional coordinate of the structuring element's origin. If omitted, the origin is set to the center, ([Nx/2], [Ny/2], [Nz/2]), where Nx, Ny, and Nz are the dimensions of the structuring element array. The origin need not be within the structuring element. Keywords BACKGROUND Set this keyword to the pixel value that is to be considered the background when dilation is being performed in constrained mode. The default value is 0. CONSTRAINED If this keyword is set and grayscale dilation has been selected, the dilation algorithm will operate in constrained mode. In this mode, a pixel is set to the value determined by normal grayscale dilation rules in the output image only if the current value destination pixel value matches the BACKGROUND pixel value. Once a pixel in the output image has been set to a value other than the BACKGROUND value, it cannot change. 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. PRESERVE_TYPE Set this keyword to return the same type as the input array. This keyword only applies if the GRAY keyword is set. UINT Set this keyword to return an unsigned integer array. This keyword only applies if the GRAY keyword is set. ULONG Set this keyword to return an unsigned longword integer array. This keyword only applies if the GRAY keyword is set. VALUES An array with the same dimensions as Structure providing the values of the structuring element. The presence of this parameter implies grayscale dilation. Each pixel of the result is the maximum of the sum of the corresponding elements of VALUE and the Image pixel value. If the resulting sum is greater than 255, the return value is 255. Using DILATE 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 reference is: Haralick, Sternberg, and Zhuang, "Image Analysis 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. Letting A B represent the dilation of an image A by structuring element B, dilation can be defined as: C = A B = (A)b b B where (A)b represents the translation of A by b. Intuitively, for each nonzero element bi,j of B, A is translated by i,j and summed into C using the "or" operator. For example: 0100 0110 0100 0110 0110 11 = 0111 1000 1100 0000 0000 In this example, the origin of the structuring element is at (0,0). Used with grayscale images, which are always converted 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 structuring element. Openings and Closings The opening of image B by structuring element K is defined as (B K) K. The closing of image B by K is defined as (B K) K where the "o times" symbol represents the erosion operator implemented by the IDL ERODE function. As stated by Haralick et al, the result of iteratively applied dilations and erosions is an elimination of specific image detail smaller than the structuring element without the global geometric distortion of unsuppressed features. For example, opening an image with a disk structuring element smooths the contour, breaks narrow isthmuses, and eliminates small islands and sharp peaks or capes. Closing an image with a disk structuring element smooths the contours, fuses narrow breaks and long thin gulfs, eliminates small holes, and fills gaps on the contours. Note MORPH_OPEN and MORPH_CLOSE can also be used to perform these tasks. Examples Example 1 This 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 operator, using the DILATE and ERODE operators. The effect is to remove holes, islands, and peninsula smaller than the shape operator: ; Threshold and make binary image: B = A GE ; Create the shape operator: S = REPLICATE(1, 3, 3) ; "Opening" operator: C = DILATE(ERODE(B, S), S) ; Show the result: TVSCL, C Example 2 For grayscale images, DILATE takes the neighborhood maximum, where the shape of the neighborhood is given by the structuring element. Elements for which the structuring element extends off the array are indeterminate. For example, assume you have the following image and structuring element: image = BYTE([2,1,3,3,3,3,1,2]) s = [1,1] If the origin of the structuring element is not specified in the call to DILATE, the origin defaults to one half the width of the structuring element, which is 1 in this case. Therefore, for the first element in the image array, the structuring element is aligned with the image as depicted below: [2,1,3,3,3,3,1,2] [1,1] This will cause an indeterminate value for the first element in the DILATE result. If edge values are important, you must pad the image with as many zeros as there are elements in the structuring element that extend off the array, in all dimensions. In this case, you would need to pad the image with a single leading zero. If the structuring element were s=[1,1,1,1], and you specified an origin of 2, the structuring element would align with the image as follows: [2,1,3,3,3,3,1,2] [1,1,1,1] [1,1,1,1] Therefore, you would need to pad the image with at least two leading zeros and at least one trailing zero. You would then perform the dilation operation on the padded image, and remove the padding from the result. The following code illustrates this method: image = BYTE([2,1,3,3,3,3,1,2]) s = [1,1] ; Structuring element PRINT, 'Image: ' PRINT, image PRINT, 'Dilation using no padding: ' PRINT, DILATE(image, s, /GRAY) result = DILATE([0, image], s, /GRAY) PRINT, 'Dilation using padding: ' PRINT, result[1:N_ELEMENTS(image)] IDL prints: Image: 2 1 3 3 3 3 1 2 Dilation using no padding: 1 3 3 3 3 3 2 2 Dilation using padding: 2 3 3 3 3 3 2 2 See Also ERODE, MORPH_CLOSE, MORPH_DISTANCE, MORPH_GRADIENT, MORPH_HITORMISS, MORPH_OPEN, MORPH_THIN, MORPH_TOPHAT DINDGEN [Previous Routine] [Next Routine] [List of Routines] NAME: 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- dimensional subscript. Syntax Result = DINDGEN(D1, ..., D8) Arguments Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. The dimensions of the result. The dimension parameters may be any scalar expression. Up to eight dimensions may be specified. If the dimension arguments are not integer values, IDL will convert them to integer values before creating the new array. Example To create D, a 100-element, double-precision, floating-point array with each element set to the value of its subscript, enter: D = DINDGEN(100) See Also BINDGEN, CINDGEN, DCINDGEN, FINDGEN, INDGEN, LINDGEN, SINDGEN, UINDGEN, UL64INDGEN, ULINDGEN DISSOLVE [Previous Routine] [Next Routine] [List of Routines] NAME: DISSOLVE The DISSOLVE procedure provides a digital "dissolve" effect for images. The routine copies pixels from the image (arranged into square tiles) to the display in pseudo-random order. This routine is written in the IDL language. Its source code can be found in the file dissolve.pro in the lib subdirectory of the IDL distribution. Syntax DISSOLVE, Image [, WAIT=seconds] [, /ORDER] [, SIZ=pixels] [, X0=pixels, Y0=pixels] Arguments Image The image to be displayed. It is assumed that the image is already scaled. Byte- valued images display most rapidly. Keywords DELAY The wait between displaying tiles. The default is 0.01 second. ORDER The Image display order: 0 = bottom up (the default), 1 = top-down. SIZ Size of square tile. The default is 32 x 32 pixels. X0, Y0 The X and Y offsets of the lower-left corner of the image on screen, in pixels. Example Display an image using 16 x 16 pixel tiles: DISSOLVE, DIST(200), SIZ=16 See Also ERASE, TV DIST [Previous Routine] [Next Routine] [List of Routines] NAME: DIST The DIST function creates a rectangular array in which the value of each element is proportional to its frequency. This array may be used for a variety of purposes, including frequency-domain filtering and making pretty pictures. This routine is written in the IDL language. Its source code can be found in the file dist.pro in the lib subdirectory of the IDL distribution. Syntax Result = DIST(N [, M]) Arguments N The number of columns in the resulting array. M The number of rows in the resulting array. If M is omitted, the resulting array will be N by N. Example ; Display the results of DIST as an image: TVSCL, DIST(100) See Also FFT DLM_LOAD [Previous Routine] [Next Routine] [List of Routines] NAME: DLM_LOAD Normally, IDL system routines that reside in dynamically loadable modules (DLMs) are automatically loaded on demand when a routine from a DLM is called. The DLM_LOAD procedure can be used to explicitly cause a DLM to be loaded. Syntax DLM_LOAD, DLMNameStr1 [, DLMNameStr2,..., DLMNameStrn] Arguments DLMNameStrn A string giving the name of the DLM to be loaded. DLM_LOAD causes each named DLM to be immediately loaded. Keywords None Example Force the JPEG DLM to be loaded: DLM_LOAD, 'jpeg' IDL prints: % Loaded DLM: JPEG. DLM_REGISTER [Previous Routine] [Next Routine] [List of Routines] NAME: DLM_REGISTER The DLM_REGISTER procedure registers a Dynamically Loadable Module (DLM) in IDL that was not registered when starting IDL. This allows you to create DLMs using the MAKE_DLL procedure and register them in your current session without having to exit and restart IDL. Note DLM_REGISTER is not the recommended way to make dynamic link modules known to your IDL session. The primary advantage of DLMs over the use of LINKIMAGE is that IDL knows about the routines from your DLM before it compiles a single line of PRO code. This avoids the LINKIMAGE pitfall in which code that calls the routine gets compiled before the LINKIMAGE call, causing IDL to interpret the call incorrectly. Use of DLM_REGISTER circumvents this benefit. Syntax DLM_REGISTER, DLMDefFilePath1 [, DLMDefFilePath2, ..., DLMDefFilePathn] Arguments DLMDefFilePathn The name of the DLM module definition file to read. Keywords None. DO_APPLE_SCRIPT [Previous Routine] [Next Routine] [List of Routines] NAME: DO_APPLE_SCRIPT The DO_APPLE_SCRIPT procedure compiles and executes an AppleScript script, possibly returning a result. DO_APPLE_SCRIPT is only available in IDL for Macintosh. Syntax DO_APPLE_SCRIPT, Script [, /AG_STRING] [, RESULT=variable] Arguments Script A string or array of strings to be compiled and executed by AppleScript. Keywords AS_STRING Set this keyword to cause the result to be returned as a decompiled string. Decompiled strings have the same format as the "The Result" window of Apple's Script Editor. RESULT Set this keyword equal to a named variable that will contain the results of the script. Example Suppose you wish to retrieve a range of cell data from a Microsoft Excel spreadsheet. The following AppleScript script and command retrieve the first through fifth rows of the first two columns of a spreadsheet titled "Worksheet 1", storing the result in the IDL variable A: script = [ 'tell application "Microsoft Excel"', $ 'get Value of Range "R1C1:R5C2" of Worksheet 1', $ 'end tell' ] DO_APPLE_SCRIPT, script, RESULT = a Similarly, the following lines would copy the contents of the IDL variable A to a range within the spreadsheet: A = [ 1, 2, 3, 4, 5 ] script = [ 'tell application "IDL" to copy variable "A"', $ 'into aVariable', $ 'tell application "Excel" to copy aVariable to', $ 'value of range "R1C1:R5C1" of worksheet 1' ] DO_APPLE_SCRIPT, script DOC_LIBRARY [Previous Routine] [Next Routine] [List of Routines] NAME: DOC_LIBRARY The DOC_LIBRARY procedure extracts documentation headers from one or more IDL programs (procedures or functions). This command provides a standard interface to the operating-system specific DL_DOS, DL_UNIX, and DL_VMS procedures. The documentation header of the .pro file in question must have the following format: * The first line of the documentation block contains only the characters ;+, starting in column 1. * The last line of the documentation block contains only the characters ;-, starting in column 1. * All other lines in the documentation block contain a ; in column 1. The file template.pro in the general subdirectory of the examples subdirectory of the IDL distribution contains a template for creating your own documentation headers. This routine is supplied for users to view online documentation from their own IDL programs. Though it could be used to view documentation headers from the lib subdirectory of the IDL distribution, we do not recommend doing so. The documentation headers on the files in the lib directory are used for historical purposes-most do not contain the most current or accurate documentation for those routines. The most current documentation for IDL's built-in and library routines is found in IDL's online help system (enter ? at the IDL prompt). This routine is written in the IDL language. Its source code can be found in the file doc_library.pro in the lib subdirectory of the IDL distribution. Syntax DOC_LIBRARY [, Name] [, /PRINT] UNIX keywords: [, DIRECTORY=string] [, /MULTI] VMS keywords: [, /FILE] [, PATH=string] [, /OUTPUTS] Arguments Name A string containing the name of the IDL routine in question. Under Windows or UNIX, Name can be "*" to get information on all routines. Keywords (All Platforms) PRINT Set this keyword to send the output of DOC_LIBRARY to the default printer. Under UNIX, if PRINT is a string, it is interpreted as a shell command used for output with the documentation from DOC_LIBRARY providing standard input (i.e., PRINT="cat > junk"). UNIX Keywords DIRECTORY A string containing the name of the directory to search. If omitted, the current directory and !PATH are used. MULTI Set this keyword to allow printing of more than one file if the requested module exists in more than one directory. VMS Keywords FILE If this keyword is set, the output is left in the file userlib.doc, in the current directory. PATH A string that describes an optional directory/library search path. This keyword uses the same format and semantics as !PATH. If omitted, !PATH is used. OUTPUTS If this keyword is set, documentation is sent to the standard output unless the PRINT keyword is set. Example To view the documentation header for the library function DIST, enter: DOC_LIBRARY, 'DIST' See Also MK_HTML_HELP DOUBLE [Previous Routine] [Next Routine] [List of Routines] NAME: DOUBLE The DOUBLE function returns a result equal to Expression converted to double- precision floating-point. If Expression is a complex number, DOUBLE returns the real part. Syntax Result = DOUBLE(Expression[, Offset [, Dim1, ..., Dimn]]) Arguments Expression The expression to be converted to double-precision, 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 3, "Constants and Variables" in Using IDL for details. Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. 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 arguments 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 warning message and return 0. The ON_IOERROR procedure can be used to establish a statement to be jumped to in case of such errors. Example Suppose that A contains the integer value 45. A double-precision, floating-point version of A can be stored in B by entering: B = DOUBLE(A) PRINT, B IDL prints: 45.000000 See Also BYTE, COMPLEX, DCOMPLEX, FIX, FLOAT, LONG, LONG64, STRING, UINT, ULONG, ULONG64 DRAW_ROI [Previous Routine] [Next Routine] [List of Routines] NAME: DRAW_ROI The DRAW_ROI procedure draws a region or group of regions to the current Direct Graphics device. The primitives used to draw each ROI are based on the TYPE property of the given IDLanROI object. The TYPE property selects between points, polylines, and filled polygons. Syntax DRAW_ROI, oROI [, /LINE_FILL] [, SPACING=value] Graphics Keywords: [, CLIP=[X0, Y0, X1, Y1]] [, COLOR=value] [, /DATA | , /DEVICE | , /NORMAL] [, LINESTYLE={0 | 1 | 2 | 3 | 4 | 5}] [, /NOCLIP] [, ORIENTATION=ccw_degrees_from_horiz] [, PSYM=integer{0 to 10}] [, SYMSIZE=value] [, /T3D] [, THICK=value] Arguments oROI A reference to an IDLanROI object to be drawn. Keywords LINE_FILL Set this keyword to indicate that polygonal regions are to be filled with parallel lines, rather than using the default solid fill. When using a line fill, the thickness, linestyle, orientation, and spacing of the lines may be specified by keywords. SPACING The spacing, in centimeters, between the parallel lines used to fill polygons. Graphics Keywords Accepted CLIP, COLOR, DATA, DEVICE, LINESTYLE, NOCLIP, NORMAL, ORIENTATION, PSYM, SYMSIZE, T3D, THICK Example The following example displays an image and collects data for a region of interest. The resulting ROI is displayed as a filled polygon. PRO roi_ex ; Load and display an image. TV, img ; Create a polygon region object. oROI = OBJ_NEW('IDLanROI', TYPE=2) ; Print instructions. PRINT,'To create a region:' PRINT,' Left mouse: select points for the region.' PRINT,' Right mouse: finish the region.' ; Collect first vertex for the region. CURSOR, xOrig, yOrig, /UP, /DEVICE oROI->AppendData, xOrig, yOrig PLOTS, xOrig, yOrig, PSYM=1, /DEVICE ;Continue to collect vertices for region until right mouse button. x1 = xOrig y1 = yOrig while !MOUSE.BUTTON ne 4 do begin x0 = x1 y0 = y1 CURSOR, x1, y1, /UP, /DEVICE PLOTS, [x0,x1], [y0,y1], /DEVICE oROI->AppendData, x1, y1 endwhile PLOTS, [x1,xOrig], [y1,yOrig], /DEVICE ; Draw the the region with a line fill. DRAW_ROI, oROI, /LINE_FILL, SPACING=0.2, ORIENTATION=45, /DEVICE END EFONT [Previous Routine] [Next Routine] [List of Routines] NAME: EFONT The EFONT procedure provides a simple widget-based vector font editor and display. Use this procedure to read and/or modify a local copy of the file hersh1.chr, located in the resource/fonts subdirectory of the main IDL directory, which contains the vector fonts used by IDL in plotting. This is a very rudimentary editor. Click the "Help" button on the EFONT main menu for more information. This routine is written in the IDL language. Its source code can be found in the file efont.pro in the lib subdirectory of the IDL distribution. Syntax EFONT [, Init_Font] [, /BLOCK] [, GROUP=widget_id] Arguments Init_Font The initial font index, from 3 to 29. The default is 3. Keywords BLOCK Set this keyword to have XMANAGER block when this application is registered. By default, BLOCK is set equal to zero, providing access to the command line if active command line processing is available. Note that setting BLOCK=1 will cause all widget applications to block, not just this application. For more information, see the documentation for the NO_BLOCK keyword to XMANAGER. Note Only the outermost call to XMANAGER can block. Therefore, to have EFONT block, any earlier calls to XMANAGER must have been called with the NO_BLOCK keyword. See the documentation for the NO_BLOCK keyword to XMANAGER for an example. GROUP The widget ID of the widget that calls EFONT. If GROUP is set, the death of the caller results in the death of EFONT. See Also SHOWFONT, XFONT EIGENQL [Previous Routine] [Next Routine] [List of Routines] NAME: EIGENQL The EIGENQL function computes the eigenvalues and eigenvectors of an n-by-n real, symmetric array using Householder reductions and the QL method with implicit shifts. Syntax Result = EIGENQL( A [, /ABSOLUTE] [, /ASCENDING] [, /DOUBLE] [, EIGENVECTORS=variable] [, /OVERWRITE | , RESIDUAL=variable] ) Return Value This function returns an n-element vector containing the eigenvalues. Arguments A An n-by-n symmetric single- or double-precision floating-point array. Keywords ABSOLUTE Set this keyword to sort the eigenvalues by their absolute value (their magnitude) rather than by their signed value. ASCENDING Set this keyword to return eigenvalues in ascending order (smallest to largest). If not set or set to zero, eigenvalues are returned in descending order (largest to smallest). The eigenvectors are correspondingly reordered. DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. EIGENVECTORS Set this keyword equal to a named variable that will contain the computed eigenvectors in an n-by-n array. The ith row of the returned array contains the ith eigenvalue. If no variable is supplied, the array will not be computed. OVERWRITE Set this keyword to use the input array for internal storage and to overwrite its previous contents. RESIDUAL Use this keyword to specify a named variable that will contain the residuals for each eigenvalue/eigenvector ( /x) pair. The residual is based on the definition Ax ­ ( )x = 0 and is an array of the same size as A and the same type as Result. The rows of this array correspond to the residuals for each eigenvalue/eigenvector pair. Note If the OVERWRITE keyword is set, the RESIDUAL keyword has no effect. Example ; Define an n-by-n real, symmetric array: A = [[ 5.0, 4.0, 0.0, -3.0], $ [ 4.0, 5.0, 0.0, -3.0], $ [ 0.0, 0.0, 5.0, -3.0], $ [-3.0, -3.0, -3.0, 5.0]] ; Compute the eigenvalues and eigenvectors: eigenvalues = EIGENQL(A, EIGENVECTORS = evecs, $ RESIDUAL = residual) ;Print the eigenvalues and eigenvectors: PRINT, 'Eigenvalues: ' PRINT, eigenvalues PRINT, 'Eigenvectors: ' PRINT, evecs IDL prints: Eigenvalues: 12.0915 6.18662 1.00000 0.721870 Eigenvectors: -0.554531 -0.554531 -0.241745 0.571446 -0.342981 -0.342981 0.813186 -0.321646 0.707107 -0.707107 -6.13503e-008-6.46503e-008 0.273605 0.273605 0.529422 0.754979 The accuracy of each eigenvalue/eigenvector ( /x) pair may be checked by printing the residual array: PRINT, residual The RESIDUAL array has the same dimensions as the input array and the same type as the result. The residuals are contained in the rows of the RESIDUAL array. All residual values should be floating-point zeros. See Also EIGENVEC, TRIQL EIGENVEC [Previous Routine] [Next Routine] [List of Routines] NAME: EIGENVEC The EIGENVEC function computes the eigenvectors of an n-by-n real, non- symmetric array using Inverse Subspace Iteration. Use ELMHES and HQR to find the eigenvalues of an n-by-n real, nonsymmetric array. This routine is written in the IDL language. Its source code can be found in the file eigenvec.pro in the lib subdirectory of the IDL distribution. Syntax Result = EIGENVEC( A, Eval [, /DOUBLE] [, ITMAX=value] [, RESIDUAL=variable] ) Return Value This function returns a complex array with a column dimension equal to n and a row dimension equal to the number of eigenvalues. Arguments A An n-by-n nonsymmetric, single- or double-precision floating-point array. EVAL An n-element complex vector of eigenvalues. Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. ITMAX The maximum number of iterations allowed in the computation of each eigenvector. The default value is 4. RESIDUAL Use this keyword to specify a named variable that will contain the residuals for each eigenvalue/eigenvector ( /x) pair. The residual is based on the definition Ax ­ x = 0 and is an array of the same size and type as that returned by the function. The rows of this array correspond to the residuals for each eigenvalue/eigenvector pair. Example ; Define an n-by-n real, nonsymmetric array: A = [[1.0, -2.0, -4.0, 1.0], $ [0.0, -2.0, 3.0, 4.0], $ [2.0, -6.0, -1.0, 4.0], $ [3.0, -3.0, 1.0, -2.0]] ; Compute the eigenvalues of A using double-precision complex ; arithmetic and print the result: eval = HQR(ELMHES(A), /DOUBLE) PRINT, 'Eigenvalues: ' PRINT, eval evec = EIGENVEC(A, eval, RESIDUAL = residual) ; Print the eigenvectors: PRINT, 'Eigenvectors:' PRINT, evec[*,0], evec[*,1], evec[*,2], evec[*,3] IDL prints: Eigenvalues: ( 0.26366255, -6.1925899)( 0.26366255, 6.1925899) ( -4.9384492, 0.0000000)( 0.41112406, 0.0000000) Eigenvectors: ( 0.0076733129, -0.42912489)( 0.40651652, 0.32973069) ( 0.54537624, -0.28856257)( 0.33149359, -0.22632585) ( -0.42145884, -0.081113711)( 0.23867007, 0.46584824) ( -0.39497143, 0.47402647)( -0.28990600, 0.27760747) ( -0.54965842, 0.0000000)( -0.18401243, 0.0000000) ( -0.58124548, 0.0000000)( 0.57111192, 0.0000000) ( 0.79297048, 0.0000000)( 0.50289130, 0.0000000) ( -0.049618509, 0.0000000)( 0.34034720, 0.0000000) You can check the accuracy of each eigenvalue/eigenvector ( /x) pair by printing the residual array. All residual values should be floating-point zeros. See Also ELMHES, HQR, TRIQL, TRIRED ELMHES [Previous Routine] [Next Routine] [List of Routines] NAME: ELMHES The ELMHES function reduces a real, nonsymmetric n by n array A to upper Hessenberg form. The result is an upper Hessenberg array with eigenvalues that are identical to those of the original array A. The Hessenberg array is stored in elements (j, i) with i j + 1. Elements with i > j + 1 are to be thought of as zero, but are returned with random values. ELMHES is based on the routine elmhes described in section 11.5 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press, and is used by permission. Syntax Result = ELMHES( A [, /COLUMN] [, /DOUBLE] [, /NO_BALANCE] ) Arguments A An n by n real, nonsymmetric array. Keywords COLUMN Set this keyword if the input array A is in column-major format (composed of column vectors) rather than in row-major format (composed of row vectors). DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. NO_BALANCE Set this keyword to disable balancing. By default, a balancing algorithm is applied to A. Balancing a nonsymmetric array is recommended to reduce the sensitivity of eigenvalues to rounding errors. Example See the description of HQR for an example using this function. See Also EIGENVEC, HQR, TRIQL, TRIRED EMPTY [Previous Routine] [Next Routine] [List of Routines] NAME: 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 graphics routine. IDL graphics routines generally handle flushing of buffered data transparently to the user, so the need for EMPTY is very rare. Syntax EMPTY See Also FLUSH ENABLE_SYSRTN [Previous Routine] [Next Routine] [List of Routines] NAME: ENABLE_SYSRTN The ENABLE_SYSRTN procedure enables/disables IDL system routines. This procedure is intended for use by runtime and callable IDL applications, and is not generally useful for interactive use. Syntax ENABLE_SYSRTN [, Routines ] [, /DISABLE] [, /EXCLUSIVE] [, /FUNCTIONS] Arguments Routines A string scalar or array giving the names of routines to be enabled or disabled. By default, these are procedures, but this can be changed by setting the FUNCTIONS keyword. Keywords DISABLE By default, the Routines are enabled. Setting this keyword causes them to be disabled instead. EXCLUSIVE By default, ENABLE_SYSRTN does not alter routines not listed in Routines. If EXCLUSIVE is set, the specified routines are taken to be the only routines that should be enabled or disabled, and all other routines have the opposite action applied. Therefore, setting EXCLUSIVE and not DISABLE means that the routines in the Routines argument are enabled and all other system routines of the same type (function or procedure) are disabled. Setting EXCLUSIVE and DISABLE means that all listed routines are disabled and all others are enabled. FUNCTIONS Normally, Routines specifies the names of procedures. Set the FUNCTIONS keyword to manipulate functions instead. Special Cases The following is a list of cases in which ENABLE_SYSRTN is unable to enable or disable a requested routine. All such attempts are simply ignored without issuing an error, allowing the application to run without error in different IDL environments: * Attempts to enable/disable non-existent system routines. * Attempts to enable a system routine disabled due to the mode in which IDL is licensed, as opposed to being disabled via ENABLE_SYSRTN, are quietly ignored (e.g. demo mode). * The routines CALL_FUNCTION, CALL_METHOD, CALL_PROCEDURE, and EXECUTE cannot be disabled via ENABLE_SYSRTN. However, anything that can be called from them can be disabled, so this is not a significant drawback. Examples To disable the PRINT procedure: ENABLE_SYSRTN, /DISABLE, 'PRINT' To enable the PRINT procedure and disable all other procedures: ENABLE_SYSRTN, /EXCLUSIVE, 'PRINT' To ensure all possible functions are enabled: ENABLE_SYSRTN, /DISABLE, /EXCLUSIVE, /FUNCTIONS In the last example, all named functions should be disabled and all other functions should be enabled. Since no Routines argument is provided, this means that all routines become enabled. EOF [Previous Routine] [Next Routine] [List of Routines] NAME: 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 The EOF function cannot be used with files opened with the RAWIO keyword to the OPEN routines. Many of the devices commonly used with RAWIO signal their end-of-file by returning a zero transfer count to the I/O operation that encounters the end-of-file. Syntax 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 organization (i.e., relative or indexed). The EOF procedure cannot 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 condition can be checked by examining the value of the expression EOF(1). For example, the following IDL code reads and prints a text file: ; Open the file test.lis: OPENR, 1, 'test.lis' ; Define a string variable: A = '' ; Loop until EOF is found: WHILE NOT EOF(1) DO BEGIN ; Read a line of text: READF, 1, A ; Print the line: PRINT, ENDWHILE ; Close the file: CLOSE, 1 See Also POINT_LUN ERASE [Previous Routine] [Next Routine] [List of Routines] NAME: 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). Syntax ERASE [, Background_Color] [, CHANNEL=value] [, COLOR=value] 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 operation. This parameter has meaning only when used with devices that support TrueColor or multiple-display channels. The default value is !P.CHANNEL. COLOR Specifies the background color. Using this keyword is analogous to using the Background_Color argument. Example ; Display a simple image in the current window: TV, DIST(255) ; Erase the image from the window: ERASE See Also SET_PLOT, WINDOW, WSET ERODE [Previous Routine] [Next Routine] [List of Routines] NAME: ERODE The ERODE function implements the erosion operator on binary and grayscale images and vectors. For details on using ERODE, see "Using ERODE" on page 445. Syntax Result = ERODE( Image, Structure [, X0 [, Y0 [, Z0]]] [, /GRAY [, /PRESERVE_TYPE | , /UINT | , /ULONG]] [, VALUES=array] ) Arguments Image A one-, two-, or three-dimensional array upon which the erosion is to be performed. 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-, two-, or three-dimensional array to be used as the structuring element. The elements are interpreted as binary values-either zero or nonzero. The structuring element must have the same number of dimensions as Image. X0, Y0, Z0 Optional parameters specifying the one-, two-, or three-dimensional coordinate of the structuring element's origin. If omitted, the origin is set to the center, ([Nx/2], [Ny/2], [Nz/2]), where Nx, Ny, and Nz 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 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 minimum operator. PRESERVE_TYPE Set this keyword to return the same type as the input array. This keyword only applies if the GRAY keyword is set. UINT Set this keyword to return an unsigned integer array. This keyword only applies if the GRAY keyword is set. ULONG Set this keyword to return an unsigned longword integer array. This keyword only applies if the GRAY keyword is set. 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. If the resulting difference is less than zero, the return value will be zero. Using ERODE See the description of the DILATE function for background 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. Over each pixel of the image, the origin of the structuring element is overlaid. If each nonzero element of the structuring element is contained in the image, the output pixel is set to one. Letting A B represent the erosion of an image A by structuring element B, erosion can be defined as: C = A B = (A)­b b B where (A)-b represents the translation of A by b. The structuring element B can be visualized as a probe that slides across image A, testing the spatial nature of A at each point. If B translated by i,j can be contained in A (by placing the origin of B at i,j), then i,j belongs to the erosion of A by B. For example: In this example, the origin of the structuring element is at (0, 0). 0100 0000 0100 0000 1110 11 = 1100 1000 0000 0000 0000 Used with grayscale images, which are always converted 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 operator with the shape of the neighborhood given by the structuring element. Examples Example 1 This example thresholds a grayscale image at the value of 100, producing a binary image. The result is then "opened" with a 3 pixel by 3 pixel square shape operator, using the ERODE and DILATE operators. The effect is to remove holes, islands, and peninsula smaller than the shape operator: ; Threshold and make binary image: B = A GE 100 ; Create the shape operator: S = REPLICATE(1, 3, 3) ; "Opening" operator: C = DILATE(ERODE(B, S), S) ; Show the result: TVSCL, C Example 2 For grayscale images, ERODE takes the neighborhood minimum, where the shape of the neighborhood is given by the structuring element. Elements for which the structuring element extends off the array are indeterminate. For example, assume you have the following image and structuring element: image = BYTE([2,1,3,3,3,3,1,2]) s = [1,1] If the origin of the structuring element is not specified in the call to ERODE, the origin defaults to one half the width of the structuring element, which is 1 in this case. Therefore, for the first element in the image array, the structuring element is aligned with the image as depicted below: [2,1,3,3,3,3,1,2] [1,1] This will cause an indeterminate value for the first element in the ERODE result. If edge values are important, you must pad the image with as many elements as there are elements in the structuring element that extend off the array, in all dimensions. The value of the padding elements must be the maximum value in the image, since ERODE calculates a neighborhood minimum. In this case, you would need to pad the image with a single leading 3. If the structuring element were s=[1,1,1,1], and you specified an origin of 2, the structuring element would align with the image as follows: [2,1,3,3,3,3,1,2] [1,1,1,1] [1,1,1,1] Therefore, you would need to pad the image with at least two leading 3s and at least one trailing 3. You would then perform the erosion operation on the padded image, and remove the padding from the result. The following code illustrates this method: image = BYTE([2,1,3,3,3,3,1,2]) s = [1,1] ; Structuring element PRINT, 'Image: ' PRINT, image PRINT, 'Erosion using no padding: ' PRINT, ERODE(image, s, /GRAY) result = ERODE([MAX(image), image], s, /GRAY) PRINT, 'Erosion using padding: ' PRINT, result[1:N_ELEMENTS(image)] IDL prints: Image: 2 1 3 3 3 3 1 2 Erosion using no padding: 0 1 1 3 3 3 1 1 Erosion using padding: 2 1 1 3 3 3 1 1 See Also DILATE, MORPH_CLOSE, MORPH_DISTANCE, MORPH_GRADIENT, MORPH_HITORMISS, MORPH_OPEN, MORPH_THIN, MORPH_TOPHAT ERRORF [Previous Routine] [Next Routine] [List of Routines] NAME: ERRORF The ERRORF function returns the value of the error function: x erf (x) = 2 e t2 ­ t d 0 The result is 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. Syntax 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 See Also GAMMA, IGAMMA, EXPINT ERRPLOT [Previous Routine] [Next Routine] [List of Routines] NAME: ERRPLOT The ERRPLOT procedure plots error bars over a previously drawn plot. This routine is written in the IDL language. Its source code can be found in the file errplot.pro in the lib subdirectory of the IDL distribution. Syntax ERRPLOT, [ X, ] Low, High [, WIDTH=value] Arguments X A vector containing the abscissa values at which the error bars are to be plotted. X only needs to be provided if the abscissa values are not the same as the index numbers of the plotted points. Low A vector of lower estimates, equal to data - error. High A vector of upper estimates, equal to data + error. Keywords WIDTH The width of the error bars. The default is 1% of plot width. Examples To plot symmetrical error bars where Y is a vector of data values and ERR is a symmetrical error estimate, enter: ; Plot data: PLOT, Y ; Overplot error bars: ERRPLOT, Y-ERR, Y+ERR If error estimates are non-symmetrical, provide actual error estimates in the upper and lower arguments. ; Plot data: PLOT,Y ; Provide custom lower and upper bounds: ERRPLOT, lower, upper To plot Y versus a vector of abscissas: ; Plot data (X versus Y): PLOT, X, Y ; Overplot error estimates: ERRPLOT, X, Y-ERR, Y+ERR See Also OPLOTERR, PLOT, PLOTERR EXECUTE [Previous Routine] [Next Routine] [List of Routines] NAME: 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 EXECUTE without imposing this limitation, and should be used instead of EXECUTE whenever possible. Syntax Result = EXECUTE(String [, QuietCompile]) Arguments String A string containing the command(s) to be compiled and executed. QuietCompile If this argument is set to a non-zero value, EXECUTE will not print the compiler generated error messages (such as syntax errors). If QuietCompile is omitted or set to 0, EXECUTE will output such errors. 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. See Also CALL_FUNCTION, CALL_METHOD, CALL_PROCEDURE EXIT [Previous Routine] [Next Routine] [List of Routines] NAME: 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. Syntax EXIT [, /NO_CONFIRM] [, STATUS=code] Keywords NO_CONFIRM Set this keyword to suppress any confirmation dialog that would otherwise be displayed in a GUI version of IDL such as the IDL Development Environment. STATUS Set this keyword equal to an exit status code that will be returned when IDL exits. For example, on a UNIX system using the Bourne shell: Start IDL: $ idl Exit IDL specifying exit status 45: IDL> exit, status=45 Display last exit status code: $ echo $? The following displays: 45 See Also CLOSE, FLUSH, STOP, WAIT EXP [Previous Routine] [Next Routine] [List of Routines] NAME: EXP The EXP function returns the natural exponential function of Expression. Syntax 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(eR cos I, eR 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) See Also ALOG EXPAND [Previous Routine] [Next Routine] [List of Routines] NAME: EXPAND The EXPAND procedure shrinks or expands a two-dimensional array, using bilinear interpolation. It is similar to the CONGRID and REBIN routines. This routine is written in the IDL language. Its source code can be found in the file expand.pro in the lib subdirectory of the IDL distribution. Syntax EXPAND, A, Nx, Ny, Result [, FILLVAL=value] [, MAXVAL=value] Arguments A A two-dimensional array to be magnified. Nx Desired size of the X dimension, in pixels. Ny Desired size of the Y dimension, in pixels. Result A named variable that will contain the magnified array. Keywords FILLVAL Set this keyword equal to the value to use when elements larger than MAXVAL are encountered. The default is -1. MAXVAL Set this keyword equal to the largest desired value. Elements greater than this value are set equal to the value of the FILLVAL keyword. See Also CONGRID, REBIN EXPAND_PATH [Previous Routine] [Next Routine] [List of Routines] NAME: 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 system variable.!PATH is a list of locations where IDL searches for currently undefined procedures and functions. Syntax Result = EXPAND_PATH( String [, /ALL_DIRS] [, /ARRAY] [, COUNT=variable] [, /DLM] [, /HELP] ) 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. 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 containing a list of directories (and in the case of VMS, text library files that are prefixed with the "@" character), 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 subdirectories 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 searches the directory and all of its subdirectories for files of the appropriate type for the path. Any directory containing at least one file of the desired type is added to the search path. A Note on Order within !PATH IDL ensures only that all directories containing IDL files are placed in !PATH. The order in which they appear is completely unspecified, and does not necessarily correspond to any specific order (such as top-down alphabetized). This allows IDL to construct the path in the fastest possible way and speeds startup. This is only a problem if two subdirectories in such a hierarchy contain a file with the same name. Such hierarchies usually are a collection of cooperative routines designed to work together, so such duplication is rare. If the order in which "+" expands directories is a problem for your application, you should add the directories to the path explicitly and not use "+". Only the order of the files within a given "+" entry are determined by IDL. It never reorders !PATH in any other way. You can therefore obtain any search order you desire by writing the path explicitly. UNIX - The directory name is expanded to remove wildcards (~ and *). This avoids overhead IDL would otherwise 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. 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). 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 otherwise 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. Macintosh - The folder name is expanded to remove wildcards (*). This avoids overhead IDL would otherwise 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. Arguments String A scalar string containing the path-definition string to be expanded. See "The Path Definition String" above for details. Keywords ALL_DIRS Set this keyword to return all directories without concern for their contents, otherwise, EXPAND_PATH only returns those directories that contain .pro or .sav files. 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 separator character and none is supplied. Normally, the result is a string array with the various path segments 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. DLM Set this keyword to return those directories that contain IDL Dynamically Loadable Module (.dlm) description files. HELP Set this keyword to return those directories that contain help (.help or .hlp) files. Example Example 1 Assume you have the following directory structure: /home myfile.txt /programs /promyfile.pro Seach the /home directroy and all its subdirectories, and return the directories containing .pro and .sav files: PRINT, EXPAND_PATH('+/home') IDL prints: /home/programs/pro Example 2 Search the same directory, but this time return all directories, not just those containing .pro and .sav files: PRINT, EXPAND_PATH('+home', /ALL_DIRS) IDL prints: /home/programs/pro:/home/programs EXPINT [Previous Routine] [Next Routine] [List of Routines] NAME: EXPINT The EXPINT function returns the value of the exponential integral En(x). EXPINT is based on the routine expint described in section 6.3 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press, and is used by permission. Syntax Result = EXPINT( N, X [, /DOUBLE] [, EPS=value] [, ITMAX=value] ) Arguments N An integer specifying the order of En(x). N can be either a scalar or an array. X The value at which En(x) is evaluated. X can be either a scalar or an array. Note: If an array is specified for both N and X, then EXPINT evaluates En(x) for each Ni and Xi. If either N or X is a scalar and the other an array, the scalar is paired with each array element in turn. Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. EPS Use this keyword to specify a number close to the desired relative error. For single- precision calculations, the default value is 1.0 × 10-7. For double-precision calculations, the default value is 1.0 × 10-14. ITMAX An input integer specifying the maximum allowed number of iterations. The default value is 100. Example To compute the value of the exponential integral at the following X values: ; Define the parametric X values: X = [1.00, 1.05, 1.27, 1.34, 1.38, 1.50] ; Compute the exponential integral of order 1: result = EXPINT(1, X) ; Print the result: PRINT, result IDL prints: 0.219384 0.201873 0.141911 0.127354 0.119803 0.100020 This is the exact solution vector to six-decimal accuracy. See Also ERRORF EXTRAC [Previous Routine] [Next Routine] [List of Routines] NAME: EXTRAC The EXTRAC function returns as its result any rectangular sub-matrix or portion of the parameter array. Note that it is usually more efficient to use the array subscript ranges (the ":" operator; see "Subscript Ranges" in Chapter 5 of Building IDL Applications) to perform such operations. The main advantage to EXTRAC is that, when parts of the specified subsection lie outside the bounds of the array, zeros are entered into these outlying elements. EXTRAC was originally a built-in system procedure in the PDP-11 version of IDL, and was retained in that form in the original VAX/VMS IDL for compatibility. Most applications of the EXTRAC function are more concisely written using subscript ranges (e.g., X(10:15)). EXTRAC has been rewritten as a library function that provides the same interface as the previous versions. Note If you know that the subarray will never lie beyond the edges of the array, it is more efficient to use array subscript ranges (the ":" operator) to extract the data instead of EXTRAC. This routine is written in the IDL language. Its source code can be found in the file extrac.pro in the lib subdirectory of the IDL distribution. Syntax Result = EXTRAC( Array, C1, C2, ..., Cn, S1, S2, ..., Sn ) Arguments Array The array from which the subarray will be copied. Ci The starting subscript in Array for the subarray. There should be one Ci for each dimension of Array. These arguments must be integers. Si The size of each dimension. The result will have dimensions of (S1, S2, ..., Sn). There should be one Si for each dimension of Array. These arguments must be non- negative. Examples Extracting elements from a vector: ; Create a 1000 element floating-point vector with each element set ; to the value of its subscript: A = FINDGEN(1000) ; Extract 300 points starting at A[200] and extending to A[499]: B = EXTRAC(A, 200, 300) In the next example, the first 49 points extracted - B[0] to B[49] - lie outside the bounds of the vector and are set to 0. B[50] is gets the value of A[0], B[51] gets the value of A[1]which is 1. Enter: ; Create a 1000 element vector: A = FINDGEN(1000) ; Extract 50 elements, 49 of which lie outside the bounds of A: B = EXTRAC(A, -50, 100) The following commands illustrate the use of EXTRAC with multi-dimensional arrays: ; Make a 64 by 64 array: A = INTARR(64,64) ; Extract a 32 by 32 portion starting at A(20,30): B = EXTRAC(A, 20, 30, 32, 32) As suggested in the discussion above, a better way to perform the same operation as the previous line is: ; Use the array subscript operator instead of EXTRAC: B = A(20:51, 30:61) Extract the 20th column and 32nd row of A: ; Extract 20th column of A: B = EXTRAC(A, 19, 0, 1, 64) ; Extract 32nd row of A: B = EXTRAC(A, 0, 31, 64, 1) Take a 32 BY 32 matrix from A starting at A(40,50): ; Note that those points beyond the boundaries of A are set to 0: B = EXTRAC(A, 40, 50, 32, 32) EXTRACT_SLICE [Previous Routine] [Next Routine] [List of Routines] NAME: EXTRACT_SLICE This EXTRACT_SLICE function returns a two-dimensional planar slice extracted from 3D volumetric data. This function allows for a rotation or vector form of the slice equation. In the vector form, the slice plane is governed by the plane equation (ax+by+cz+d = 0) and a single vector which defines the x direction. This form is more common throughout the IDL polygon interface. In the rotation form, the slicing plane can be oriented at any angle and pass through any desired location in the volume. This function allows for a vertex grid to be generated without sampling the data. In this form, the return value would be an array of [3,n] vertices which could be used to sample additional dataset or used to form polygonal meshes. It would also be useful to return the planar mesh connectivity in this case. Support for anisotropic data volumes is included via an ANISOTROPY keyword. This is an important feature in the proper interpolation of common medical imaging data. This routine is written in the IDL language. Its source code can be found in the file extract_slice.pro in the lib subdirectory of the IDL distribution. Syntax Result = EXTRACT_SLICE( Vol, Xsize, Ysize, Xcenter, Ycenter, Zcenter, Xrot, Yrot, Zrot [, ANISOTROPY=[xspacing, yspacing, zspacing]] [, /CUBIC] [, OUT_VAL=value] [, /RADIANS] [, /SAMPLE] [, VERTICES=variable] ) or Result = EXTRACT_SLICE( Vol, Xsize, Ysize, Xcenter, Ycenter, Zcenter, PlaneNormal, Xvec [, ANISOTROPY=[xspacing, yspacing, zspacing]] [, /CUBIC] [, OUT_VAL=value] [, /RADIANS] [, /SAMPLE] [, VERTICES=variable] ) Arguments PlaneNormal Set this input argument to a 3 element array. The values are interpreted as the normal of the slice plane. Xvec Set this input argument to a 3 element array. The three values are interpreted as the 0 dimension directional vector. This should be a unit vector. Vol The volume of data to slice. This argument is a three-dimensional array of any type except string or structure. The planar slice returned by EXTRACT_SLICE has the same data type as Vol. Xsize The desired X size (dimension 0) of the returned slice. To preserve the correct aspect ratio of the data, Xsize should equal Ysize. For optimal results, set Xsize and Ysize to be greater than or equal to the largest of the three dimensions of Vol. Ysize The desired Ysize (dimension 1) of the returned slice. To preserve the correct aspect ratio of the data, Ysize should equal Xsize. For optimal results, set Xsize and Ysize to be greater than or equal to the largest of the three dimensions of Vol. Xcenter The X coordinate (index) of the point within the volume that the slicing plane passes through. The center of the slicing plane passes through Vol at the coordinate (Xcenter, YCenter, Zcenter). Ycenter The Y coordinate (index) of the point within the volume that the slicing plane passes through. The center of the slicing plane passes through Vol at the coordinate (Xcenter, YCenter, Zcenter). Zcenter The Z coordinate (index) of the point within the volume that the slicing plane passes through. The center of the slicing plane passes through Vol at the coordinate (Xcenter, YCenter, Zcenter). Xrot The X-axis rotation of the slicing plane, in degrees. Before transformation, the slicing plane is parallel to the X-Y plane. The slicing plane transformations are performed in the following order: * Rotate Z_rot degrees about the Z axis. * Rotate Y_rot degrees about the Y axis. * Rotate X_rot degrees about the X axis. * Translate the center of the plane to Xcenter, Ycenter, Zcenter. Yrot The Y-axis rotation of the slicing plane, in degrees. Zrot The orientation Z-axis rotation of the slicing plane, in degrees. Keywords ANISOTROPY Set this keyword to a three-element array. This array specifies the spacing between the planes of the input volume in grid units of the (isotropic) output image. CUBIC Set this keyword to use cubic interpolation. The default is to use tri-linear interpolation. If the SAMPLE keyword is set, then the CUBIC keyword is ignored. OUT_VAL Set this keyword to a value that will be assigned to elements of the returned slice that lie outside of the original volume. RADIANS Set this keyword to indicate that Xrot, Yrot, and Zrot are in radians. The default is degrees. SAMPLE Set this keyword to perform nearest neighbor sampling when computing the returned slice. The default is to use bilinear interpolation. A small reduction in execution time results when SAMPLE is set and the OUT_VAL keyword is not used. VERTICES Set this output keyword to a named variable in which to return a [3,Xsize,Ysize] floating point array. This is an array of the x, y, z sample locations for each pixel in the normal output. Example Display an oblique slice through volumetric data: ; Create some data: vol = RANDOMU(s, 40, 40, 40) ; Smooth the data: FOR i=0, 10 DO vol = SMOOTH(vol, 3) ; Scale the smoothed part into the range of bytes: vol = BYTSCL(vol(3:37, 3:37, 3:37)) ; Extract a slice: slice = EXTRACT_SLICE(vol, 40, 40, 17, 17, 17, 30.0, 30.0, 0.0, $ OUT_VAL=0B) ; Display the 2D slice as a magnified image: TVSCL, REBIN(slice, 400, 400) See Also SLICER3 F_CVF [Previous Routine] [Next Routine] [List of Routines] NAME: F_CVF The F_CVF function computes the cutoff value V in an F distribution with Dfn and Dfd degrees of freedom such that the probability that a random variable X is greater than V is equal to a user-supplied probability P. This routine is written in the IDL language. Its source code can be found in the file f_cvf.pro in the lib subdirectory of the IDL distribution. Syntax Result = F_CVF(P, Dfn, Dfd) Arguments P A non-negative single- or double-precision floating-point scalar, in the interval [0.0, 1.0], that specifies the probability of occurrence or success. Dfn A positive integer, single- or double-precision floating-point scalar that specifies the number of degrees of freedom of the F distribution numerator. Dfd A positive integer, single- or double-precision floating-point scalar that specifies the number of degrees of freedom of the F distribution denominator. Example Use the following command to compute the cutoff value in an F distribution with ten degrees of freedom in the numerator and six degrees of freedom in the denominator such that the probability that a random variable X is greater than the cutoff value is 0.01. The result should be 7.87413: PRINT, F_CVF(0.01, 10, 6) See Also CHISQR_CVF, F_PDF, GAUSS_CVF, T_CVF F_PDF [Previous Routine] [Next Routine] [List of Routines] NAME: F_PDF The F_PDF function computes the probability P that, in an F distribution with Dfn and Dfd degrees of freedom, a random variable X is less than or equal to a user- specified cutoff value V. This routine is written in the IDL language. Its source code can be found in the file f_pdf.pro in the lib subdirectory of the IDL distribution. Syntax Result = F_PDF(V, Dfn, Dfd) Return Value If all arguments are scalar, the function returns a scalar. If all arguments are arrays, the function matches up the corresponding elements of V, Dfn, and Dfd, returning an array with the same dimensions as the smallest array. If one argument is a scalar and the other arguments are arrays, the function uses the scalar value with each element of the arrays, and returns an array with the same dimensions as the smallest input array. If any of the arguments are double-precision, the result is double-precision, otherwise the result is single-precision. Arguments V A scalar or array that specifies the cutoff value(s). Dfn A positive scalar or array that specifies the number of degrees of freedom of the F distribution numerator. Dfd A positive scalar or array that specifies the number of degrees of freedom of the F distribution denominator. Example Use the following command to compute the probability that a random variable X, from the F distribution with five degrees of freedom in the numerator and 24 degrees of freedom in the denominator, is less than or equal to 3.90. The result should be 0.990059: PRINT, F_PDF(3.90, 5, 24) See Also BINOMIAL, CHISQR_PDF, F_CVF, GAUSS_PDF, T_PDF FACTORIAL [Previous Routine] [Next Routine] [List of Routines] NAME: FACTORIAL The FACTORIAL function computes the factorial N! For integers, the factorial is computed as (N) (N ­ 1) (N ­ 2) ... 3 2 1. For non-integers the factorial is computed using GAMMA( N+1 ). This routine is written in the IDL language. Its source code can be found in the file factorial.pro in the lib subdirectory of the IDL distribution. Syntax Result = FACTORIAL( N [, /STIRLING] [, /UL64] ) Arguments N A non-negative scalar or array of values. Note Large values of N will cause floating-point overflow errors. The maximum size of N varies with machine architecture. On machines that support the IEEE standard for floating-point arithmetic, the maximum value of N is 170. See MACHAR for a discussion of machine-specific parameters affecting floating-point arithmetic. Keywords STIRLING Set this keyword to use Stirling's asymptotic formula to approximate N!: N N! = 2 N N ----e where e is the base of the natural logarithm. UL64 Set this keyword to return the results as unsigned 64-bit integers. This keyword is ignored if STIRLING is set. Note Unsigned 64-bit integers will overflow for values of N greater than 20. Example Compute 20!: PRINT, FACTORIAL(20) IDL prints: 2.4329020e+18 See Also BINOMIAL, TOTAL FFT [Previous Routine] [Next Routine] [List of Routines] NAME: FFT The FFT function returns a result equal to the complex, discrete Fourier transform of Array. The result of this function is a single- or double-precision complex array. The discrete Fourier transform, F(u), of an N-element, one-dimensional function, f(x), is defined as: N ­ 1 F u ( ) 1 = ---- N f(x)exp[­j2 ux N] x = 0 And the inverse transform, (Direction > 0), is defined as: N ­ 1 f(x) = F u ( )exp[ j2 ux N] u = 0 If the keyword OVERWRITE is set, the transform is performed in-place, and the result overwrites the original contents of the array. The result returned by FFT is a complex array that has the same dimensions as the input array. The output array is ordered in the same manner as almost all discrete Fourier transforms. Element 0 contains the zero frequency component, F0. F1 contains the smallest nonzero positive frequency, which is equal to 1/(Ni Ti), where Ni and Ti are the number of elements and the sampling interval of the ith dimension, respectively. F2 corresponds to a frequency of 2/(Ni Ti). Negative frequencies are stored in the reverse order of positive frequencies, ranging from the highest to lowest negative frequencies (see storage scheme below). Note The FFT can be performed on functions of up to eight (8) dimensions in size. If a function has n dimensions, IDL performs a transform in each dimension separately, starting with the first dimension and progressing sequentially to dimension n. For example, if the function has two dimensions, IDL first does the FFT row by row, and then column by column. For an even number of points in the ith dimension, the storage scheme of returned complex values is as follows: F 1/(2Ti) 0 1/(NiTi) ... (Ni-2)/2NiTi (Nyquist) -(Ni-2)/2NiTi ... -1/(NiTi) REAL, IMAG REAL, IMAG [Previous Routine] [Next Routine] [List of Routines] NAME: Real, Imag Real, Imag Table 19: Even Number of Points For an odd number of points in the ith dimension, the storage scheme of returned complex values is as follows: F0 1/(NiTi) ... (Ni-1)/2NiTi -(Ni-1)/2NiTi ... -1/(NiTi) Real, Imag Real, Imag Real, Imag Real, Imag Real, Imag Table 20: Odd Number of Points Syntax Result = FFT( Array [, Direction] [, DIMENSION] [, /DOUBLE] [, /INVERSE] [, /OVERWRITE] ) Arguments Array The array to which the Fast Fourier Transform should be applied. If Array is not of complex type, it is converted to complex type. The dimensions of the result are identical to those of Array. The size of each dimension may be any integer value and does not necessarily have to be an integer power of 2, although powers of 2 are certainly the most efficient. Direction Direction is a scalar indicating the direction of the transform, which is negative by convention for the forward transform, and positive for the inverse transform. If Direction is not specified, the forward transform is performed. A normalization factor of 1/N, where N is the number of points, is applied during the forward transform. Note When transforming from a real vector to complex and back, it is slightly faster to set Direction to 1 in the real to complex FFT. Note also that the value of Direction is ignored if the INVERSE keyword is set. Keywords DIMENSION Set this keyword to the dimension across which to calculate the FFT. If this keyword is not present or is zero, then the FFT is computed across all dimensions of the input array. If this keyword is present, then the FFT is only calculated only across a single dimension. For example, if the dimensions of Array are N1, N2, N3, and DIMENSION is 2, the FFT is calculated only across the second dimension. DOUBLE Set this keyword to a value other than zero to force the computation to be done in double-precision arithmetic, and to give a result of double-precision complex type. If DOUBLE is set equal to zero, computation is done in single-precision arithmetic and the result is single-precision complex. If DOUBLE is not specified, the data type of the result will match the data type of Array. INVERSE Set this keyword to perform an inverse transform. Setting this keyword is equivalent to setting the Direction argument to a positive value. Note, however, that setting INVERSE results in an inverse transform even if Direction is specified as negative. OVERWRITE If this keyword is set, and the Array parameter is a variable of complex type, the transform is done "in-place". The result overwrites the previous contents of the variable. For example, to perform a forward, in-place FFT on the variable a: a = FFT(a, -1, /OVERWRITE) Running Time For a one-dimensional FFT, running time is roughly proportional to the total number of points in Array times the sum of its prime factors. Let N be the total number of elements in Array, and decompose N into its prime factors: N = 2K2 3K3 5K5... Running time is proportional to: T0 + N(T1 + 2K2T2 + T3(3K3 + 5K5 + ...)) where T3 ~ 4T2. For example, the running time of a 263 point FFT is approximately 10 times longer than that of a 264 point FFT, even though there are fewer points. The sum of the prime factors of 263 is 264 (1 + 263), while the sum of the prime factors of 264 is 20 (2 + 2 + 2 + 3 + 11). Example Display the log of the power spectrum of a 100-element index array by entering: PLOT, /YLOG, ABS(FFT(FINDGEN(100), -1)) As a more complex example, display the power spectrum of a 100-element vector sampled at a rate of 0.1 seconds per point. Show the 0 frequency component at the center of the plot and label the abscissa with frequency: ; Define the number of points: N = 100 ; Define the interval: T = 0.1 ; Midpoint+1 is the most negative frequency subscript: N21 = N/2 + 1 ; The array of subscripts: F = INDGEN(N) ; Insert negative frequencies in elements F(N/2 +1), ..., F(N-1): F[N21] = N21 -N + FINDGEN(N21-2) ; Compute T0 frequency: F = F/(N*T) ; Shift so that the most negative frequency is plotted first: PLOT, /YLOG, SHIFT(F, -N21), SHIFT(ABS(FFT(F, -1)), -N21) See Also HILBERT FILE_CHMOD [Previous Routine] [Next Routine] [List of Routines] NAME: FILE_CHMOD The FILE_CHMOD procedure allows you to change the current access permissions (sometimes known as modes on UNIX platforms) associated with a file or directory. File modes are specified using the standard Posix convention of three protection classes (user, group, other), each containing three attributes (read, write, execute). These permissions can be specified as an octal bitmask in which desired permissions have their associated bit set and unwanted ones have their bits cleared. This is the same format familiar to users of the UNIX chmod(1) command). Keywords are available to specify permissions without the requirement to specify a bitmask, providing a simpler way to handle many situations. All of the keywords share a similar behavior: Setting them to a non-zero value adds the specified permission to the Mode argument. Setting the keyword to 0 removes that permission. To find the current protection settings for a given file, you can use the GET_MODE keyword to the FILE_TEST function. Syntax FILE_CHMOD, File [, Mode] [, NOEXPAND_PATH] [, /A_EXECUTE |, /A_READ |, /A_WRITE] [, /G_EXECTUE | /G_READ | , /G_WRITE] [, /O_EXECTUE | /O_READ | , /O_WRITE] [, /U_EXECTUE | /U_READ | , /U_WRITE] UNIX-Only Keywords: [, /SETGID] [, /SETUID] [, /STICKY_BIT] Arguments File A scalar or array of file or directory names for which protection modes will be changed. Mode An optional bit mask specifying the absolute protection settings to be applied to the files. If Mode is not supplied, FILE_CHMOD looks up the current modes for the file and uses it instead. Any additional modes specified via keywords are applied relative to the value in Mode. Setting a keyword adds the necessary mode bits to Mode, and clearing it by explicitly setting a keyword to 0 removes those bits from Mode. The values of the bits in these masks correspond to those used by the UNIX chmod(2) system call and chmod(1) user command, and are given in the following table. Since these bits are usually manipulated in groups of three, octal notation is commonly used when referring to them. When constructing a mode, the following platform specific considerations should be kept in mind: * The setuid, setgid, and sticky bits are specific to the UNIX operating system, and have no meaning elsewhere. FILE_CHMOD ignores them on non-UNIX systems. The UNIX kernel may quietly refuse to set the sticky bit if you are not the root user. Consult the chmod(2) man page for details. * The VMS operating system has four permission classes, unlike the 3 supported by UNIX. Furthermore, each class has an additional bit (DELETE) not supported by UNIX. IDL uses the C runtime library chmod() function supplied by the operating system to translate between the UNIX convention used by IDL and the native VMS permission masks. It maps the VMS SYSTEM and OWNER classes to the user class, GROUP to group, and WORLD to other. The DELETE bit is combined with the WRITE bit. * The Microsoft Windows and Macintosh operating systems do not have 3 permission classes like UNIX does. Therefore, setting for all three classes are combined into a single request. * The Microsoft Windows and Macintosh operating systems always allow read access to any files visible to a program. FILE_CHMOD therefore ignores any requests to remove read access. * The Microsoft Windows and Macintosh operating systems do not maintain an execute bit for their files. Windows uses the file suffix to decide if a file is executable, and Macintosh IDL only considers files of type APPL to be executable. Therefore, FILE_CHMOD cannot change the execution status of a file on these platforms. Such requests are quietly ignored. Bit Octal Mask Meaning 12 '4000'o Setuid: Set user ID on execution. 11 '2000'o Setgid: Set group ID on execution. 10 '1000'o Turn on sticky bit. See the UNIX documentation on chmod(2) for details. 9 '0400'o Allow read by owner. 8 '0200'o Allow write by owner. Table 21: UNIX chmod(2) mode bits Bit Octal Mask Meaning 7 '0100'o Allow execute by owner. 6 '0040'o Allow read by group. 5 '0020'o Allow write by group. 4 '0010'o Allow execute by group. 3 '0004'o Allow read by others. 2 '0002'o Allow write by others. 1 '0001'o Allow execute by others. Table 21: UNIX chmod(2) mode bits Keywords NOEXPAND_PATH If specified, FILE_CHMOD uses File exactly as specified, without applying the usual file path expansion. A_EXECUTE Execute access for all three (user, group, other) categories. A_READ Read access for all three (user, group, other) categories. A_WRITE Write access for all three (user, group, other) categories. G_EXECUTE Execute access for the group category. G_READ Read access for the group category. G_WRITE Write access for the group category. O_EXECUTE Execute access for the other category. O_READ Read access for the other category. O_WRITE Write access for the other category. U_EXECUTE Execute access for the user category. U_READ Read access for the user category. U_WRITE Write access for the user category. UNIX-Only Keywords SETGID The Set Group ID bit. SETUID The Set User ID bit. STICKY_BIT Sets the sticky bit. Example In the first example, we make the file moose.dat read only to everyone except the owner of the file, but not change any other settings: FILE_CHMOD, 'moose.dat', /U_WRITE, G_WRITE=0, O_WRITE=0 In the next example, we make the file readable and writable to the owner and group, but read-only to anyone else, and remove any other modes: FILE_CHMOD, 'moose.dat', '664'o FILE_DELETE [Previous Routine] [Next Routine] [List of Routines] NAME: FILE_DELETE The FILE_DELETE procedure deletes a file or empty directory, if the process has the necessary permissions to remove the file as defined by the current operating system. FILE_CHMOD can be used to change file protection settings. Syntax FILE_DELETE, File1 [,... FileN] [, NOEXPAND_PATH] [, /QUIET] Arguments FileN A scalar or array of file or directory names to be deleted, one name per string element. Directories must be specified in the native syntax for the current operating system. See "Operating System Syntax" below for additional details. Keywords NOEXPAND_PATH If specified, FILE_DELETE uses File exactly as specified, without applying the usual file path expansion. QUIET FILE_DELETE will normally issue an error if it is unable to remove a requested file or directory. If QUIET is set, no error is issued and FILE_DELETE simply moves on to the next requested item. Operating System Syntax The syntax used to specify directories for removal depends on the operating system in use, and is in general the same as you would use when issuing commands to the operating system command interpreter. Microsoft Windows users must be careful to not specify a trailing backslash at the end of a specification. For example: FILE_DELETE, 'c:\mydir\myfile' and not: FILE_DELETE, 'c:\mydir\myfile\' For VMS users, the syntax for creating a subdirectory (as with the CREATE/DIRECTORY DCL command) is not symmetric with that used to delete it (using the DELETE,/DIRECTORY). FILE_DELETE follows the same rules. For instance, to create a subdirectory of the current working directory named bullwinkle and then remove it: FILE_MKDIR,'[.bullwinkle]' FILE_DELETE,'bullwinkle.dir' Example In this example, we remove an empty directory named moose. On the Macintosh, UNIX, or Windows operating systems: FILE_DELETE, 'moose' To do the same thing under VMS: FILE_DELETE, 'moose.dir' FILE_EXPAND_PATH [Previous Routine] [Next Routine] [List of Routines] NAME: FILE_EXPAND_PATH The FILE_EXPAND_PATH function expands a given file or partial directory name to its fully qualified name regardless of the current working directory. Note This routine should be used only to make sure that file paths are fully qualified, but not to expand wildcard characters (e.g. *). The behavior of FILE_EXPAND_PATH when it encounters a wildcard is platform dependent, and should not be depended on. These differences are due to the underlying operating system, and are beyond IDL's control. To expand wildcards and obtain fully qualified paths, combine the FINDFILE function with FILE_EXPAND_PATH: A = FILE_EXPAND_PATH(FINDFILE('*.pro')) Syntax Result = FILE_EXPAND_PATH (Path) Return Value FILE_EXPAND_PATH returns a fully qualified file path that completely specifies the location of Path without the need to consider the user's current working directory. Arguments Path A scalar or array of file or directory names to be fully qualified. Keywords None. Example In this example, we change directories to the IDL lib directory and expand the file path for the DIST function: cd, FILEPATH('', SUBDIRECTORY=['lib']) print, FILE_EXPAND_PATH('dist.pro') This results in the following if run on a UNIX system: /usr/local/rsi/idl_5.4/lib/dist.pro See Also FINDFILE FILE_MKDIR [Previous Routine] [Next Routine] [List of Routines] NAME: FILE_MKDIR The FILE_MKDIR procedure creates a new directory, or directories, with the default access permissions for the current process. Note Use the FILE_CHMOD procedure to alter access permissions. If a specified directory has non-existent parent directories, FILE_MKDIR automatically creates all the intermediate directories as well. Syntax FILE_MKDIR, File1 [,... FileN][, NOEXPAND_PATH] Arguments FileN A scalar or array of directory names to be created, one name per string element. Directories must be specified in the native syntax for the current operating system. Keywords NOEXPAND_PATH If specified, FILE_MKDIR uses File exactly as specified, without applying the usual file path expansion. None. Example To create a subdirectory named moose in the current working directory on the Macintosh, UNIX, or Windows operating systems: FILE_MKDIR, 'moose' To do the same thing under VMS: FILE_MKDIR, '[.moose]' FILE_TEST [Previous Routine] [Next Routine] [List of Routines] NAME: FILE_TEST The FILE_TEST function checks files for existence and other attributes without having to first open the file. Syntax Result = FILE_TEST( File [, NOEXPAND_PATH] [, /DIRECTORY | , /EXECUTABLE | , /READ | , /REGULAR | , /WRITE | , /ZERO_LENGTH] [, GET_MODE=variable] ) UNIX-Only Keywords: [, /BLOCK_SPECIAL | , /CHARACTER_SPECIAL | , /DANGLING_SYMLINK | , /NAMED_PIPE | , /SETGID | , /SETUID | , /SOCKET | , /STICKY_BIT | , /SYMLINK] UNIX and VMS-Only Keywords: [, /GROUP | , /USER] Return Value FILE_TEST returns 1 (true), if the specified file exists and all of the attributes specified by the keywords are also true. If no keywords are present, a simple test for existence is performed. If the file does not exist or one of the specified attributes is not true, then FILE_TEST returns 0 (false). Arguments File A scalar or array of file names to be tested. The result is of type integer with the same number of elements as File. Keywords NOEXPAND_PATH If specified, FILE_TEST uses File exactly as specified, without applying the usual file path expansion. DIRECTORY Set this keyword to return 1 (true) if File exists and is a directory. EXECUTABLE Set this keyword to return 1 (true) if File exists and is executable. The source of this information differs between operating systems: * UNIX and VMS: IDL checks the per-file information (the execute bit) maintained by the operating system. * Microsoft Windows: The determination is made on the basis of the file name extension (e.g. .exe). * Macintosh: Files of type `APPL' (proper applications) are reported as executable. This corresponds to "Double Clickable" applications. GET_MODE Set this keyword to a named variable to receive the UNIX style mode (permission) mask for the specified file. The bits in these masks correspond to those used by the UNIX chmod(2) system call, and are explained in detail in the description of the Mode argument to the FILE_CHMOD procedure. When interpreting the value returned by this keyword, the following platform specific details should be kept in mind: * The setuid, setgid, and sticky bits are specific to the UNIX operating system, and will never be returned on any other platform. Consult the chmod(2) man page and/or other UNIX programming documentation for more details. * The VMS operating system has four permission classes, unlike the three supported by UNIX. Furthermore, each class has an additional bit (DELETE) not supported by UNIX. IDL uses the C runtime library stat() function supplied by the operating system to translate between the UNIX convention used by IDL and the native VMS permission masks. It maps the VMS OWNER to the user class, GROUP to group, and WORLD to other. The DELETE bit is combined with the WRITE bit. * The Microsoft Windows and Macintosh operating systems do not have 3 permission classes like UNIX does. Therefore, IDL returns the same settings for all three classes. * The Microsoft Windows and Macintosh operating systems to not maintain an execute bit for their files. Windows uses the file suffix to decide if a file is executable, and Macintosh IDL only considers files of type `APPL' to be executable. READ Set this keyword to return 1 (true) if File exists and is readable by the user. REGULAR Set this keyword to return 1 (true) if File exists and is a regular disk file and not a directory, pipe, socket, or other special file type. WRITE Set this keyword to return 1 (true) if File exists and is writable by the user. ZERO_LENGTH Set this keyword to return 1 (true) if File exists and has zero length. Note The length of a directory is highly system dependent and does not necessarily correspond to the number of files it contains. In particular, it is possible for an empty directory to report a non-zero length. RSI does not recommend using the ZERO_LENGTH keyword on directories, as the information returned cannot be used in a meaningful way. UNIX-Only Keywords BLOCK_SPECIAL Set this keyword to return 1 (true) if File exists and is a block special device. CHARACTER_SPECIAL Set this keyword to return 1 (true) if File exists and is a character special device. DANGLING_SYMLINK Set this keyword to return 1 (true) if File is a symbolic link that points at a non- existent file. NAMED_PIPE Set this keyword to return 1 (true) if File exists and is a named pipe (fifo) device. SETGID Set this keyword to return 1 (true) if File exists and has its Set-Group-ID bit set. SETUID Set this keyword to return 1 (true) if File exists and has its Set-User-ID bit set. SOCKET Set this keyword to return 1 (true) if File exists and is a UNIX domain socket. STICKY_BIT Set this keyword to return 1 (true) if File exists and has its sticky bit set. SYMLINK Set this keyword to return 1 (true) if File exists and is a symbolic link that points at an existing file. UNIX and VMS-Only Keywords GROUP Set this keyword to return 1 (true) if File exists and belongs to the same effective group ID (GID) as the IDL process. USER Set this keyword to return 1 (true) if File exists and belongs to the same effective user ID (UID) as the IDL process. Example Does my IDL distribution support the IRIX operating system? result = FILE_TEST(!DIR + '/bin/bin.sgi', /DIRECTORY) PRINT, 'IRIX IDL Installed: ', result ? 'yes' : 'no' NAME: FILE_WHICH The FILE_WHICH function separates a specified file path into its component directories, and searches each directory in turn for a specific file. This command is modeled after the UNIX which(1) command. This routine is written in the IDL language. Its source code can be found in the file file_which.pro in the lib subdirectory of the IDL distribution. Syntax Result = FILE_WHICH( [Path, ] File [, /INCLUDE_CURRENT_DIR] ) Return Value Returns the path for the first file for the given name found by searching the specified path. If FILE_WHICH does not find the desired file, a NULL string is returned. Arguments Path A search path to be searched. If Path is not present, the value of the IDL !PATH system variable is used. File The file to look for in the directories given by Path. Keywords INCLUDE_CURRENT_DIR If set, FILE_WHICH looks in the current directory before starting to search Path for File. When IDL searches for a routine to compile, it looks in the current working directory before searching !PATH. The INCLUDE_CURRENT_DIR keyword allows FILE_WHICH to mimic this behavior. Example To find the location of this routine: Result = FILE_WHICH('file_which.pro') To find the location of the UNIX ls command: Result = FILE_WHICH(getenv('PATH'), 'ls') FILEPATH [Previous Routine] [Next Routine] [List of Routines] NAME: FILEPATH The FILEPATH function returns the fully-qualified path to a file found in the IDL distribution. Operating system dependencies are taken into consideration. This routine is used by Research Systems to make the library routines portable. This routine is written in the IDL language. Its source code can be found in the file filepath.pro in the lib subdirectory of the IDL distribution. Syntax Result = FILEPATH( Filename [, ROOT_DIR=string] [, SUBDIRECTORY=string/string_array] [, /TERMINAL] [, /TMP] ) Arguments Filename A string containing the name of the file to be found. The file should be specified in all lowercase characters. No device or directory information should be included. Keywords ROOT_DIR A string containing the name of the directory from which the resulting path should be based. If not present, the value of !DIR is used. This keyword is ignored if TERMINAL or TMP are specified. SUBDIRECTORY The name of the subdirectory in which the file should be found. If this keyword is omitted, the main IDL directory is used. This variable can be either a scalar string or a string array with the name of each level of subdirectory depth represented as an element of the array. For example, to get a path to the file filepath.pro in IDL's lib subdirectory, enter: path = FILEPATH('filepath.pro',SUBDIR=['lib']) TERMINAL Set this keyword to return the filename of the user's terminal. TMP Set this keyword to indicate that the specified file is a scratch file. Returns a path to the proper place for temporary files under the current operating system. On the Macintosh, this keyword accesses a true temporary directory. This creates an invisible Temp folder which follows the Macintosh convention for temporary files. Under Microsoft Windows, FILEPATH checks to see if the following environment variables are set-TMP, TEMP, WINDIR-and uses the value of the first one it finds. If none of these environment variables exists, \TMP is used as the temporary directory. Example Open the IDL distribution file people.dat: OPENR, 1, FILEPATH('people.dat', See Also FINDFILE FINDFILE [Previous Routine] [Next Routine] [List of Routines] NAME: FINDFILE The FINDFILE function returns a string array containing the names of all files matching File_Specification. All matched filenames are returned in a string array, one file name per array element. If no files exist with names matching the File_Specification, a null scalar string is returned instead of a string array. Except for VMS, described below, FINDFILE returns the full path only if the path itself is specified in File_Specification. See the "Examples" section below for details. Note Platform specific differences are described below: * Under Macintosh, FINDFILE function brackets the returned filename in colons if the file is a folder (e.g., :lib:) * Under UNIX, to include all the files in any subdirectories, use the * wildcard character in the File_Specification, such as in result = FINDFILE('/path/*'). If File_Specification contains only a directory, with no file information, only files in that directory are returned. * Under VMS, FINDFILE returns the full path specification for any file it finds. * Under Windows, FINDFILE appends a "\" character to the end of the returned file name if the file is a directory. To refer to all the files in a specific directory only, use result = FINDFILE('\path\*'). Syntax Result = FINDFILE( File_Specification [, COUNT=variable] ) Arguments File_Specification A scalar string used to find files. The string can contain any valid command- interpreter wildcard characters. If File_Specification contains path information, that path information is included in the returned value. If File_Specification is omitted, the names of all files in the current directory are returned. Keywords COUNT A named variable into which the number of files found is placed. If no files are found, a value of 0 is returned. Examples To print the file names of all the UNIX files with "dat" extensions in the current directory, use the command: PRINT, FINDFILE('*.dat') To print the full path names of all .pro files in the IDL lib directory that begin with the letter "x", use the command: PRINT, FINDFILE('/usr/local/rsi/idl/lib/x*.pro') To print the path names of all .pro files in the profiles subdirectory of the current directory (a relative path), use the command: PRINT, FINDFILE('profiles/*.pro') Note that the values returned are (like the File_Specification) relative path names. Use caution when comparing values against this type of relative path specification. See Also FILEPATH FINDGEN [Previous Routine] [Next Routine] [List of Routines] NAME: FINDGEN The FINDGEN function returns a single-precision, floating-point array with the specified dimensions. Each element of the array is set to the value of its one- dimensional subscript. Syntax Result = FINDGEN(D1, ..., D8) Arguments Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. The dimensions of the result. The dimension parameters can be any scalar expression. Up to eight dimensions can be specified. If the dimension arguments are not integer values, IDL will convert them to integer values before creating the new array. Example To create F, a 6-element vector of single-precision, floating-point values where each element is set to the value of its subscript, enter: F = FINDGEN(6) The value of F[0] is 0.0, F[1] is 1.0, and so on. See Also BINDGEN, CINDGEN, DCINDGEN, DINDGEN, INDGEN, LINDGEN, SINDGEN, UINDGEN, UL64INDGEN, ULINDGEN FINITE [Previous Routine] [Next Routine] [List of Routines] NAME: FINITE The FINITE function returns 1 (True) if its argument is finite. If the argument is infinite or not a defined number (NaN), 0 (False) is returned. (See "Special Floating- Point Values" in Chapter 17 of Building IDL Applications for more information on IEEE floating-point values.) The result is a byte expression of the same structure as the argument X. Syntax Result = FINITE( X [, SIGN] [, /INFINITY] [, /NAN] ) Arguments X A floating-point, double-precision, or complex scalar or array expression. Strings are first converted to floating-point. This function is meaningless for byte, integer, or longword arguments. Keywords SIGN If the INFINITY or NAN keyword is set, then set this keyword to one of the following values: * SIGN > 0: For /INFINITY, return True (1) if X is positive infinity, False (0) otherwise. For /NAN, return True (1) if X is +NaN (negative sign bit is not set), False (0) otherwise. * SIGN = 0 (the default): The sign of X (positive or negative) is ignored. * SIGN < 0: For /INFINITY, return True (1) if X is negative infinity, False (0) otherwise. For /NAN, return True (1) if X is -NaN (negative sign bit is set), False (0) otherwise. If neither the INFINITY nor NAN keyword is set, then this keyword is ignored. INFINITY If INFINITY is set, FINITE returns True if X is positive or negative infinity, and it returns False otherwise. NAN If NAN is set, FINITE returns True if X is "Not A Number" (NaN), otherwise it returns False. Examples Example 1 To find out if the logarithm of 5.0 is finite, enter: PRINT, FINITE(ALOG(5.0)) IDL prints "1" because the argument is finite. Example 2 To determine which elements of an array are infinity or NaN (Not a Number) values: A = FLTARR(10) ; Set A[5] to NaN: A[5] = !VALUES.F_NAN ; Find all values in A that are Infinity: B = FINITE(A, /INFINITY) PRINT, B IDL prints the following, indicating that none of the elements are equal to infinity: 0 0 0 0 0 0 0 0 0 0 ; Find all values in A that are NaN: B = FINITE(A, /NAN) PRINT, B IDL prints the following, indicating that A[5] is NaN: 0 0 0 0 0 1 0 0 0 0 ; Set A[5] to infinity: A[5] = !VALUES.F_INFINITY ; Find all values in A that are NaN: B = FINITE(A, /NAN) PRINT, B IDL prints the following, indicating that none of the elements are equal to NaN: 0 0 0 0 0 0 0 0 0 0 ; Find all values in A that are Infinity: B = FINITE(A, /INFINITY) PRINT, B IDL prints the following, indicating that A[5] is equal to infinity: 0 0 0 0 0 1 0 0 0 0 See Also CHECK_MATH, MACHAR, !VALUES FIX [Previous Routine] [Next Routine] [List of Routines] NAME: FIX The FIX function returns a result equal to Expression converted to integer type. Optionally, the conversion type can be specified at runtime, allowing flexible runtime type-conversion to arbitrary types. Syntax Result = FIX( Expression [, Offset [, Dim1, ..., Dim8]] [, /PRINT] [, TYPE=type code{0 to 15}] ) Arguments Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. Expression The expression to be converted. Offset Offset from beginning of the Expression data area. Specifying this argument allows fields of data extracted from Expression to be treated as integer data. See the description in Chapter 3, "Constants and Variables" in Building IDL Applications for details. The Offset and Dimi arguments are not allowed when converting to or from the string type. Dimi 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 arguments are given, the result is taken to be scalar. The Offset and Dimi arguments are not allowed when converting to or from the string type. When converting from a string argument, it is possible that the string does not contain a valid integer and no conversion is possible. The default action in such cases is to print a warning message and return 0. The ON_IOERROR procedure can be used to establish a statement to be jumped to in case of such errors. Keywords PRINT Set this keyword to specify that any special-case processing when converting between string and byte data, or the reverse, should be suppressed. The PRINT keyword is ignored unless the TYPE keyword is used to convert to these types. TYPE FIX normally converts Expression to the integer type. If TYPE is specified, it is the type code to set the type of the conversion. This feature allows dynamic type conversion, where the desired type is not known until runtime, to be carried out without the use of large CASE or IF...THEN logic. When TYPE is specified, FIX behaves as if the appropriate type conversion routine for the desired type had been called. See the "See Also" list below for the complete list of such routines. When using the TYPE keyword to convert BYTE data to STRING or the reverse, you should be aware of the special-case processing that the BYTE and STRING functions do in this case. To prevent this, and get a simple type conversion in these cases, you must specify the PRINT keyword. Example Convert the floating-point array [2.2, 3.0, 4.5] to integer type and store the new array in the variable I by entering: I = FIX([2.2, 3.0, 4.5]) See Also BYTE, COMPLEX, DCOMPLEX, DOUBLE, FLOAT, LONG, LONG64, STRING, UINT, ULONG, ULONG64 FLICK [Previous Routine] [Next Routine] [List of Routines] NAME: FLICK The FLICK procedure causes the display to flicker between two output images at a given rate. This routine is written in the IDL language. Its source code can be found in the file flick.pro in the lib subdirectory of the IDL distribution. Syntax FLICK, A, B [, Rate] Arguments A Byte image number 1, scaled from 0 to 255. B Byte image number 2, scaled from 0 to 255. Rate The flicker rate. The default is 1.0 sec/frame See Also CW_ANIMATE, XINTERANIMATE FLOAT [Previous Routine] [Next Routine] [List of Routines] NAME: FLOAT The FLOAT function returns a result equal to Expression converted to single- precision floating-point. If Expression is a complex number, FLOAT returns the real part. Syntax Result = FLOAT( Expression [, Offset [, Dim1, ..., Dim8]] ) Arguments Expression The expression to be converted to single-precision floating-point. Offset Offset from beginning of the Expression data area. Specifying this argument allows fields of data extracted from Expression to be treated as single-precision floating point data. Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. 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 arguments 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 warning message and return 0. The ON_IOERROR procedure can be used to establish a statement to be jumped to in case of such errors. Example If A contains the integer value 6, it can be converted to floating-point and stored in the variable B by entering: B = FLOAT(A) See Also BYTE, COMPLEX, DCOMPLEX, DOUBLE, FIX, LONG, LONG64, STRING, UINT, ULONG, ULONG64 FLOOR [Previous Routine] [Next Routine] [List of Routines] NAME: FLOOR The FLOOR function returns the closest integer less than or equal to its argument. Syntax Result = FLOOR(X [, /L64 ] ) Return Value If the input argument X is an integer type, Result has the same value and type as X. Otherwise, Result is a 32-bit longword integer with the same structure as X. Arguments X The value for which the FLOOR function is to be evaluated. This value can be any numeric type (integer, floating, or complex). Keywords L64 If set, the result type is 64-bit integer regardless of the input type. This is useful for situations in which a floating point number contains a value too large to be represented in a 32-bit integer. Example To print the floor function of 5.9, enter: PRINT, FLOOR(5.9) ; IDL prints: 5 To print the floor function of 3000000000.1, the result of which is too large to represent in a 32-bit integer: PRINT, FLOOR(3000000000.1D, /L64) ; IDL prints: 3000000000 FLOW3 [Previous Routine] [Next Routine] [List of Routines] NAME: FLOW3 The FLOW3 procedure draws lines representing a 3D flow/velocity field. Note that the 3D scaling system must be in place before calling FLOW3. This procedure works best with Z buffer output device. This routine is written in the IDL language. Its source code can be found in the file flow3.pro in the lib subdirectory of the IDL distribution. Syntax FLOW3, Vx, Vy, Vz [, ARROWSIZE=value] [, /BLOB] [, LEN=value] [, NSTEPS=value] [, NVECS=value] [, SX=vector, SY=vector, SZ=vector] Arguments Vx, Vy, Vz 3D arrays containing X, Y, and Z components of the field. Keywords ARROWSIZE Size of arrowheads (default = 0.05). BLOB Set this keyword to draw a blob at the beginning of each flow line and suppress the arrows. LEN Length of each step used to follow flow lines (default = 2.0). Expressed in units of largest field vector (i.e., the length of the longest step is set to len times the grid spacing. NSTEPS Number of steps used to follow the flow lines (default = largest dimension of Vx / 5). NVECS Number of random flow lines to draw (default = 200). Only used if Sx, Sy, Sz are not present. SX, SY, SZ Optional vectors containing the starting coordinates of the flow lines. If omitted random starting points are chosen. Example ; Create a set of random three-dimensional arrays to represent ; the field: vx = RANDOMU(seed, 5, 5, 5) vy = RANDOMU(seed, 5, 5, 5) vz = RANDOMU(seed, 5, 5, 5) ; Set up the 3D scaling system: SCALE3, xr=[0,4], yr=[0,4], zr = [0,4] ; Plot the vector field: FLOW3, vx, vy, vz See Also VEL, VELOVECT FLTARR [Previous Routine] [Next Routine] [List of Routines] NAME: FLTARR The FLTARR function returns a single-precision, floating-point vector or array. Syntax Result = FLTARR( D1, ..., D8 [, /NOZERO] ) Arguments Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. The dimensions of the result. The dimension parameters can be any scalar expression. Up to eight dimensions can be specified. Keywords NOZERO Normally, FLTARR sets every element of the result to zero. Set this keyword to inhibit zeroing of the array elements and cause FLTARR to execute faster. Example Create F, a 3-element by 3-element floating-point array with each element set to 0.0 by entering: F = FLTARR(3, 3) See Also BYTARR, COMPLEXARR, DBLARR, DCOMPLEXARR, INTARR, LON64ARR, LONARR, MAKE_ARRAY, STRARR, UINTARR, ULON64ARR, ULONARR FLUSH [Previous Routine] [Next Routine] [List of Routines] NAME: FLUSH The FLUSH procedure causes all buffered output on the specified file units to be written. IDL uses buffered output for reasons of efficiency. This buffering leads to rare occasions where a program needs to be certain that output data are not waiting in a buffer, but have actually been output. Syntax FLUSH, Unit1, ..., Unitn Arguments Uniti The file units (logical unit numbers) to flush. See Also CLOSE, EMPTY, EXIT FOR [Previous Routine] [Next Routine] [List of Routines] NAME: FOR The FOR statement executes one or more statements repeatedly, incrementing or decrementing a variable with each repetition, until a condition is met. Note For more information on using FOR and other IDL program control statements, see Chapter 11, "Program Control" in Building IDL Applications. Syntax FOR variable = init, limit [, Increment] DO statement or FOR variable = init, limit [, Increment] DO BEGIN statements ENDFOR Example The following example iterates over the elements of an array, printing the value of each element: array = ['one', 'two', 'three'] n = N_ELEMENTS(array) FOR i=0,n-1 DO BEGIN PRINT, array[i] ENDFOR FORMAT_AXIS_VALUES [Previous Routine] [Next Routine] [List of Routines] NAME: FORMAT_AXIS_VALUES The FORMAT_AXIS_VALUES function accepts a vector of numeric values as an input argument, and returns a vector of formatted string values. This routine uses the same rules for formatting as do the axis routines that label tick marks given a set of tick values. Syntax Result = FORMAT_AXIS_VALUES( Values ) Arguments Values Set this argument to a vector of numeric values to be formatted. Keywords None. Example Suppose we have a vector of axis values: axis_values = [7.9, 12.1, 15.3, 19.0] Convert these values into an array of strings: new_values = FORMAT_AXIS_VALUES(axis_values) HELP, new_values PRINT, new_values PRINT, axis_values IDL prints: NEW_VALUES STRING = Array[4] 7.9 12.1 15.3 19.0 7.90000 12.1000 15.3000 19.0000 FORWARD_FUNCTION [Previous Routine] [Next Routine] [List of Routines] NAME: FORWARD_FUNCTION The FORWARD_FUNCTION statement causes argument(s) to be interpreted as functions rather than variables (versions of IDL prior to 5.0 used parentheses to declare arrays). Note For information on using the FORWARD_FUNCTION statement, see Chapter 12, "Procedures and Functions" in Building IDL Applications. Syntax FORWARD_FUNCTION Name1, Name2, ..., Namen FREE_LUN [Previous Routine] [Next Routine] [List of Routines] NAME: FREE_LUN The FREE_LUN procedure deallocates previously-allocated file units. This routine is usually used with file units allocated with GET_LUN, but it will also close any other specified file unit. If the specified file units are open, they are closed prior to the deallocation. Syntax FREE_LUN [, Unit1, ..., Unitn] [, EXIT_STATUS=variable] [, /FORCE] Arguments Uniti The IDL file units (logical unit numbers) to deallocate. Keywords EXIT_STATUS Set this keyword to a named variable that will contain the exit status reported by a UNIX child process started via the UNIT keyword to SPAWN. This value is the exit value reported by the process by calling EXIT, and is analogous to the value returned by $? under most UNIX shells. FORCE Set this keyword to override the IDL file output buffer and force the file to be closed no matter what errors occur in the process. IDL buffers file output for performance reasons. If it is not possible to properly flush this data when a file close is requested, an error is normally issued and the file remains open. An example of this might be that your disk does not have room to write the remaining data. This default behavior prevents data from being lost. To override it and force the file to be closed no matter what errors occur in the process, specify FORCE. Example See the example for the GET_LUN procedure. See Also CLOSE, GET_LUN FSTAT [Previous Routine] [Next Routine] [List of Routines] NAME: FSTAT The FSTAT function returns status information about a specified file unit. Syntax Result = FSTAT(Unit) Return Value The FSTAT function returns a structure expression of type FSTAT (or FSTAT64 in the case of files that are longer than 2^31-1 bytes in length) containing status information about a specified file unit. The contents of this structure are documented in "The FSTAT Function" in Chapter 8 of Building IDL Applications. Fields of the FSTAT Structure The following descriptions are of fields in the structure returned by the FSTAT function. They are not keywords to FSTAT. * UNIT - The IDL logical unit number (LUN). * NAME - The name of the file. * OPEN - Nonzero if the file unit is open. If OPEN is zero, the remaining fields in FSTAT will not contain useful information. * ISATTY - Nonzero if the file is actually a terminal instead of a normal file. For example, if you are using an xterm window on a UNIX system and you invoke FSTAT on logical unit 0 (standard input), ISATTY will be set to 1. * ISAGUI - Nonzero if the file is actually a Graphical User Interface (for example, a logical unit associated with the IDL Development Environment). Thus, if you are using the IDLDE and you invoke FSTAT on logical unit 0 (standard input), ISAGUI will be set to 1. * INTERACTIVE - Nonzero if either ISATTY or ISAGUI is nonzero. * XDR - Nonzero if the file was opened with the XDR keyword, and is therefore considered to contain data in the XDR format. * COMPRESS - Nonzero if the file was opened with the COMPRESS keyword, and is therefore considered to contain compressed data in the GZIP format. * READ - Nonzero if the file is open for read access. * WRITE - Nonzero if the file is open for write access. * ATIME, CTIME, MTIME - The date of last access, date of creation, and date of last modification given in seconds since 1 January 1970 UTC. Use the SYSTIME function to convert these dates into a textual representation. Note Some file systems do not maintain all of these dates (e.g. MS DOS FAT file systems), and may return 0. On some non-UNIX operating systems, access time is not maintained, and ATIME and MTIME will always return the same date. * TRANSFER_COUNT - The number of scalar IDL data items transferred in the last input/output operation on the unit. This is set by the following IDL routines: READU, WRITEU, PRINT, PRINTF, READ, and READF. TRANSFER_COUNT is useful when attempting to recover from input/output errors. * CUR_PTR - The current position of the file pointer, given in bytes from the start of the file. If the device is a terminal (ISATTY is nonzero), the value of CUR_PTR will not contain useful information. When reporting on file units opened with the COMPRESS keyword to OPEN, the position reported by CUR_PTR is the "logical" position-the position it would be at in the uncompressed version of the same file. * SIZE - The current length of the file in bytes. If the device is a terminal (ISATTY is nonzero), the value of SIZE will not contain useful information. When reporting on file units opened with the COMPRESS keyword to OPEN, the size reported by SIZE is the compressed size of the actual file, and not the logical length of the uncompressed data contained within. This is inconsistent with the position reported by CUR_PTR. The reason for reporting the size in this way is that the logical length of the data cannot be known without reading the entire file from beginning to end and counting the uncompressed bytes, and this would be extremely inefficient. Warning VMS variable length records have a 2-byte record-length descriptor at the beginning of each record. Because the SIZE field contains the length of the data file including the record descriptors, reading a file with VMS variable length records into a byte array of the size returned by FSTAT will result in an RMS EOF error. * REC_LEN - If the file is record-oriented (VMS), this field contains the record length; otherwise, it is zero. Arguments Unit The file unit about which information is required. This parameter can be an integer or an associated variable, in which case information about the variable's associated file is returned. Keywords None. Examples If file unit number 1 is open, the FSTAT information on that unit can be seen by entering: PRINT, FSTAT(1) Specific information can be obtained by referring to single fields within the structure returned by FSTAT. The following code prints the name and length of the file open on unit 1: ; Put FSTAT information in variable A: A = FSTAT(1) ; Print the name and size fields: PRINT, 'File: ', A.NAME, ' is ', A.SIZE, ' bytes long.' See Also ASSOC, OPEN FULSTR [Previous Routine] [Next Routine] [List of Routines] NAME: FULSTR The FULSTR restores a row-indexed sparse array to full storage mode. If the sparse array was created with the SPRSIN function using the THRESH keyword, any values in the original array that were below the specified threshold are replaced with zeros. Syntax Result = FULSTR(A) Arguments A A row-indexed sparse array created by the SPRSIN function. Example Suppose we have converted an array to sparse storage format with the following commands: A = [[ 5.0, -0.2, 0.1], $ [ 3.0, -2.0, 0.3], $ [ 4.0, -1.0, 0.0]] ; Convert to sparse storage mode. All elements of the array A that ; have absolute values less than THRESH are set to zero: sparse = SPRSIN(A, THRESH=0.5) The variable SPARSE now contains a representation of the array A in structure form. To restore the array from the sparse-format structure: ; Restore the array: result = FULSTR(sparse) ; Print the result: PRINT, result IDL prints: 5.00000 0.00000 0.00000 3.00000 -2.00000 0.00000 4.00000 -1.00000 0.00000 Note that the elements with an absolute value less than the specified threshold have been set to zero. See Also LINBCG, SPRSAB, SPRSAX, SPRSIN, SPRSTP, READ_SPR, WRITE_SPR FUNCT [Previous Routine] [Next Routine] [List of Routines] NAME: FUNCT The FUNCT procedure evaluates the sum of a Gaussian and a 2nd-order polynomial and optionally returns the value of its partial derivatives. Normally, this function is used by CURVEFIT to fit the sum of a line and a varying background to actual data. This routine is written in the IDL language. Its source code can be found in the file funct.pro in the lib subdirectory of the IDL distribution. Syntax FUNCT, X, A, F [, Pder] Arguments X A vector of values for the independent variable. A A vector of coefficients for the equations: F = A 0e Z2 ­ 2 A3 A4X A5X2 + + + Z = (X ­ A1) A2 F A named variable that will contain the value of the function at each Xi. Pder A named variable that will contain an array of the size (N_ELEMENTS(X),6) that contains the partial derivatives. Pder(i,j) represents the derivative at the ith point with respect to jth parameter. See Also CURVEFIT FUNCTION [Previous Routine] [Next Routine] [List of Routines] NAME: FUNCTION The FUNCTION statement defines a function. Note For information on using the FUNCTION statement, see Chapter 12, "Procedures and Functions" in Building IDL Applications. Syntax FUNCTION Function_Name, parameter1, ..., parametern FV_TEST [Previous Routine] [Next Routine] [List of Routines] NAME: FV_TEST The FV_TEST function computes the F-statistic and the probability that two sample populations X and Y have significantly different variances. X and Y may be of different lengths. The result is a two-element vector containing the F-statistic and its significance. The significance is a value in the interval [0.0, 1.0]; a small value (0.05 or 0.01) indicates that X and Y have significantly different variances. This type of test is often referred to as the F-variance test. The F-statistic formula for sample populations x and y with means x and y is defined as: N ­ 1 N ­ 1 2 (x j ­ x)2 1 ­ ---- N (x j ­ x) F M ­ 1 = -------------- j = 0 j = 0 N ­ 1 M ­ 1 M ­ 1 2 (y j ­ y)2 1 ­ ----- M (y j ­ y) j = 0 j = 0 where x = (x0, x1, x2, ..., xN-1) and y = (y0, y1, y2 ..., yM-1) This routine is written in the IDL language. Its source code can be found in the file fv_test.pro in the lib subdirectory of the IDL distribution. Syntax Result = FV_TEST(X, Y) Arguments X An n-element integer, single- or double-precision floating-point vector. Y An m-element integer, single- or double-precision floating-point vector. Example ; Define two n-element sample populations: X = [257, 208, 296, 324, 240, 246, 267, 311, 324, 323, 263, $ 305, 270, 260, 251, 275, 288, 242, 304, 267] Y = [201, 56, 185, 221, 165, 161, 182, 239, 278, 243, 197, $ 271, 214, 216, 175, 192, 208, 150, 281, 196] ; Compute the F-statistic (of X and Y) and its significance: PRINT, FV_TEST(X, Y) IDL prints: 2.48578 0.0540116 The result indicates that X and Y have significantly different variances. See Also KW_TEST, MOMENT, RS_TEST, S_TEST, TM_TEST FX_ROOT [Previous Routine] [Next Routine] [List of Routines] NAME: FX_ROOT The FX_ROOT function computes real and complex roots of a univariate nonlinear function using an optimal Müller's method. This routine is written in the IDL language. Its source code can be found in the file fx_root.pro in the lib subdirectory of the IDL distribution. Syntax Result = FX_ROOT(X, Func [, /DOUBLE] [, ITMAX=value] [, /STOP] [, TOL=value] ) Arguments X A 3-element real or complex initial guess vector. Real initial guesses may result in real or complex roots. Complex initial guesses will result in complex roots. Func A scalar string specifying the name of a user-supplied IDL function that defines the univariate nonlinear function. This function must accept the vector argument X. For example, suppose we wish to find a root of the following function: y = e(sinx2 + cosx2 ­ 1) ­ 1 We write a function FUNC to express the function in the IDL language: FUNCTION func, X RETURN, EXP(SIN(X)^2 + COS(X)^2 - 1) - 1 END Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. ITMAX The maximum allowed number of iterations. The default is 100. STOP Use this keyword to specify the stopping criterion used to judge the accuracy of a computed root r(k). Setting STOP = 0 (the default) checks whether the absolute value of the difference between two successively-computed roots, | r(k) - r(k+1) | is less than the stopping tolerance TOL. Setting STOP = 1 checks whether the absolute value of the function FUNC at the current root, | FUNC(r(k)) |, is less than TOL. TOL Use this keyword to specify the stopping error tolerance. The default is 1.0 × 10-4. Example This example finds the roots of the function FUNC defined above: ; First define a real 3-element initial guess vector: x = [0.0, -!pi/2, !pi] ; Compute a root of the function using double-precision ; arithmetic: root = FX_ROOT(X, 'FUNC', /DOUBLE) ; Check the accuracy of the computed root: PRINT, EXP(SIN(ROOT)^2 + COS(ROOT)^2 - 1) - 1 IDL prints: 0.0000000 We can also define a complex 3-element initial guess vector: x = [COMPLEX(-!PI/3, 0), COMPLEX(0, !PI), COMPLEX(0, -!PI/6)] ; Compute the root of the function: root = FX_ROOT(x, 'FUNC') ; Check the accuracy of the computed complex root: PRINT, EXP(SIN(ROOT)^2 + COS(ROOT)^2 - 1) - 1 IDL prints: ( 0.00000, 0.00000) See Also BROYDEN, NEWTON, FZ_ROOTS FZ_ROOTS [Previous Routine] [Next Routine] [List of Routines] NAME: FZ_ROOTS The FZ_ROOTS function is used to find the roots of an m-degree complex polynomial, using Laguerre's method. The result is an m-element complex vector. FZ_ROOTS is based on the routine zroots described in section 9.5 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press, and is used by permission. Syntax Result = FZ_ROOTS(C [, /DOUBLE] [, EPS=value] [, /NO_POLISH] ) Arguments C A vector of length m+1 containing the coefficients of the polynomial, in ascending order (see example). The type can be real or complex. Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. EPS The desired fractional accuracy. The default value is 2.0 × 10-6. NO_POLISH Set this keyword to suppress the usual polishing of the roots by Laguerre's method. Examples Example 1: Real coefficients yielding real roots. Find the roots of the polynomial: P (x) = 6x3 - 7x2 - 9x - 2 The exact roots are -1/2, -1/3, 2.0. coeffs = [-2.0, -9.0, -7.0, 6.0] roots = FZ_ROOTS(coeffs) PRINT, roots IDL prints: ( -0.500000, 0.00000)( -0.333333, 0.00000)( 2.00000, 0.00000) Example 2: Real coefficients yielding complex roots. Find the roots of the polynomial: P (x) = x4 + 3x2 + 2 The exact roots are: 0.0 ­ i 2.0, 0.0 + i 2.0 , 0.0 ­ i , 0.0 + i coeffs = [2.0, 0.0, 3.0, 0.0, 1.0] roots = FZ_ROOTS(coeffs) PRINT, roots IDL Prints: (0.00000, -1.41421)(0.00000, 1.41421) (0.00000, -1.00000)(0.00000, 1.00000) Example 3: Real and complex coefficients yielding real and complex roots. Find the roots of the polynomial: P (x) = x3 + (­4 ­ i4)x2 +s (­3 + i4)x + (18 + i24) The exact roots are ­2.0, 3.0, (3.0 + i4.0) coeffs = [COMPLEX(18,24), COMPLEX(-3,4), COMPLEX(-4,-4), 1.0] roots = FZ_ROOTS(coeffs) PRINT, roots IDL Prints: ( -2.00000, 0.00000) ( 3.00000, 0.00000) ( 3.00000, 4.00000) See Also FX_ROOT, BROYDEN, NEWTON, POLY GAMMA [Previous Routine] [Next Routine] [List of Routines] NAME: GAMMA The GAMMA function returns the gamma function of X. The gamma function is defined as: (x) tx ­ 1e­t t d 0 If X is double-precision, the result is double-precision, otherwise the argument is converted to floating-point and the result is floating-point. Use the LNGAMMA function to obtain the natural logarithm of the gamma function when there is a possibility of overflow. Syntax Result = GAMMA(X) Arguments X The expression for which the gamma function will be evaluated. Example Plot the gamma function over the range 0.01 to 1.0 with a step size of 100 by entering: X = FINDGEN(99)/100. + 0.01 PLOT, X, GAMMA(X) See Also BETA, IBETA, IGAMMA, LNGAMMA GAMMA_CT [Previous Routine] [Next Routine] [List of Routines] NAME: GAMMA_CT The GAMMA_CT procedure applies gamma correction to a color table. This routine is written in the IDL language. Its source code can be found in the file gamma_ct.pro in the lib subdirectory of the IDL distribution. Syntax GAMMA_CT, Gamma [, /CURRENT] [, /INTENSITY] Arguments Gamma The value of gamma correction. A value of 1.0 indicates a linear ramp (i.e., no gamma correction). Higher values of Gamma give more contrast. Values less than 1.0 yield lower contrast. Keywords CURRENT Set this keyword to apply correction from the "current" color table (i.e., the values R_CURR, G_CURR, and B_CURR in the COLORS common block). Otherwise, correction is applied from the "original" color table (i.e., the values R_ORIG, G_ORIG, and B_ORIG in the COLORS common block). The gamma corrected color table is always saved in the "current" table (R_CURR, G_CURR, B_CURR) and the new table is loaded. INTENSITY Set this keyword to correct the individual intensities of each color in the colortable. Otherwise, the colors are shifted according to the gamma function. See Also PSEUDO, STRETCH, XLOADCT GAUSS_CVF [Previous Routine] [Next Routine] [List of Routines] NAME: GAUSS_CVF The GAUSS_CVF function computes the cutoff value V in a standard Gaussian (normal) distribution with a mean of 0.0 and a variance of 1.0 such that the probability that a random variable X is greater than V is equal to a user-supplied probability P. This routine is written in the IDL language. Its source code can be found in the file gauss_cvf.pro in the lib subdirectory of the IDL distribution. Syntax Result = GAUSS_CVF(P) Arguments P A non-negative single- or double-precision floating-point scalar, in the interval [0.0, 1.0], that specifies the probability of occurrence or success. Example Use the following command to compute the cutoff value in a Gaussian distribution such that the probability that a random variable X is greater than the cutoff value is 0.025: PRINT, GAUSS_CVF(0.025) IDL prints: 1.95997 See Also CHISQR_CVF, F_CVF, GAUSS_PDF, T_CVF GAUSS_PDF [Previous Routine] [Next Routine] [List of Routines] NAME: GAUSS_PDF The GAUSS_PDF function computes the probability P that, in a standard Gaussian (normal) distribution with a mean of 0.0 and a variance of 1.0, a random variable X is less than or equal to a user-specified cutoff value V. This routine is written in the IDL language. Its source code can be found in the file gauss_pdf.pro in the lib subdirectory of the IDL distribution. Syntax Result = GAUSS_PDF(V) Return Value This function returns a scalar or array with the same dimensions as V. If V is double- precision, the result is double-precision, otherwise the result is single-precision. Arguments V A scalar or array that specifies the cutoff value(s). Examples Example 1 Compute the probability that a random variable X, from the standard Gaussian (normal) distribution, is less than or equal to 2.44: PRINT, GAUSS_PDF(2.44) IDL Prints: 0.992656 Example 2 Compute the probability that a random variable X, from the standard Gaussian (normal) distribution, is less than or equal to 10.0 and greater than or equal to 2.0: PRINT, GAUSS_PDF(10.0) - GAUSS_PDF(2.0) IDL Prints: 0.0227501 Example 3 Compute the probability that a random variable X, from the Gaussian (normal) distribution with a mean of 0.8 and a variance of 4.0, is less than or equal to 2.44: PRINT, GAUSS_PDF( (2.44 - 0.80)/SQRT(4.0) ) IDL Prints: 0.793892 See Also BINOMIAL, CHISQR_PDF, F_PDF, GAUSS_CVF, T_PDF GAUSS2DFIT [Previous Routine] [Next Routine] [List of Routines] NAME: GAUSS2DFIT The GAUSS2DFIT function fits a two-dimensional, elliptical Gaussian equation to rectilinearly gridded data. Z = F(x, y) where: F(x, y) = A ­ 0 + A1e U 2 And the elliptical function is: U = (x' a)2 (y' b)2 + The parameters of the ellipse U are: * Axis lengths are 2a and 2b, in the unrotated X and Y axes, respectively. * Center is at (h, k). * Rotation of T radians from the X axis, in the clockwise direction. The rotated coordinate system is defined as: x' = (x ­ h)cosT ­ (y ­ k)sinT y' = (x ­ h)sinT + (y ­ k)cosT The rotation is optional, and can be forced to 0, making the major and minor axes of the ellipse parallel to the X and Y axes. Coefficients of the computed fit are returned in argument A. Procedure Used and Other Notes The peak/valley is found by first smoothing Z and then finding the maximum or minimum, respectively. GAUSSFIT is then applied to the row and column running through the peak/valley to estimate the parameters of the Gaussian in X and Y. Finally, CURVEFIT is used to fit the 2D Gaussian to the data. Be sure that the 2D array to be fit contains the entire peak/valley out to at least 5 to 8 half-widths, or the curve-fitter may not converge. This is a computationally-intensive routine. The time required is roughly proportional to the number of elements in Z. This routine is written in the IDL language. Its source code can be found in the file gauss2dfit.pro in the lib subdirectory of the IDL distribution. Syntax Result = GAUSS2DFIT( Z, A [, X, Y] [, /NEGATIVE] [, /TILT] ) Arguments Z The dependent variable. Z should be a two-dimensional array with dimensions (Nx, Ny). Gridding in the array must be rectilinear. A A named variable in which the coefficients of the fit are returned. A is returned as a seven element vector the coefficients of the fitted function. The meanings of the seven elements in relation to the discussion above is: * A[0] = A0 = constant term * A[1] = A1 = scale factor * A[2] = a = width of Gaussian in the X direction * A[3] = b = width of Gaussian in the Y direction * A[4] = h = center X location * A[5] = k = center Y location. * A[6] = T = Theta, the rotation of the ellipse from the X axis in radians, counter- clockwise. X An optional vector with Nx elements that contains the X values of Z (i.e., Xi is the X value for Zi,j. If this argument is omitted, a regular grid in X is assumed, and the X location of Zi,j = i. Y An optional vector with Ny elements that contains the Y values of Z (i.e., Yj is the Y value for Zi,j. If this argument is omitted, a regular grid in Y is assumed, and the Y location of Zi,j = j. Keywords NEGATIVE Set this keyword to indicate that the Gaussian to be fitted is a valley (such as an absorption line). By default, a peak is fit. TILT Set this keyword to allow the orientation of the major and minor axes of the ellipse to be unrestricted. The default is that the axes of the ellipse must be parallel to the X and Y axes. Therefore, in the default case, A[6] is always returned as 0. Example This example creates a 2D gaussian, adds random noise and then applies GAUSS2DFIT. ; Define array dimensions: nx = 128 & ny = 100 ; Define input function parameters: A = [ 5., 10., nx/6., ny/10., nx/2., .6*ny] ; Create X and Y arrays: X = FINDGEN(nx) # REPLICATE(1.0, ny) Y = REPLICATE(1.0, nx) # FINDGEN(ny) ; Create an ellipse: U = ((X-A[4])/A[2])^2 + ((Y-A[5])/A[3])^2 ; Create gaussian Z: Z = A[0] + A[1] * EXP(-U/2) ; Add random noise, SD = 1: Z = Z + RANDOMN(seed, nx, ny) ; Fit the function, no rotation: yfit = GAUSS2DFIT(Z, B) ; Report results: PRINT, 'Should be: ', STRING(A, FORMAT='(6f10.4)') PRINT, 'Is: ', STRING(B(0:5), FORMAT='(6f10.4)') See Also COMFIT, GAUSSFIT, POLY_FIT, REGRESS, SFIT, SVDFIT GAUSSFIT [Previous Routine] [Next Routine] [List of Routines] NAME: GAUSSFIT The GAUSSFIT function computes a non-linear least-squares fit to a function f (x) with from three to six unknown parameters. f (x) is a linear combination of a Gaussian and a quadratic; the number of terms is controlled by the keyword parameter NTERMS. This routine is written in the IDL language. Its source code can be found in the file gaussfit.pro in the lib subdirectory of the IDL distribution. Syntax Result = GAUSSFIT( X, Y [, A] [, ESTIMATES] [, ESTIMATES=array] [, NTERMS=integer{3 to 6}] ) Arguments X An n-element vector of independent variables. Y A vector of dependent variables, the same length as X. A A named variable that will contain the coefficients A of the fit. Keywords ESTIMATES The way the estimates are constructed in GAUSSFIT if not provided by the user has been improved. If the ESTIMATES array is not specified, estimates are calculated by first subtracting a polynomial of degree NTERMS-4 (only if NTERMS is greater than 3) and then forming a simple estimate of the Gaussian coefficients. Set this keyword equal to an array of starting estimates for the parameters of the equation. If the NTERMS keyword is specified, the ESTIMATES array should have NTERMS elements. If NTERMS is not specified, the ESTIMATES array should have six elements. If the ESTIMATES array is not specified, estimates are calculated by the GAUSSFIT routine. NTERMS Set this keyword to an integer value between three and six to specify the function to be used for the fit. The values correspond to the functions shown below. In all cases: x ­ A z 1 = --------------- A2 NTERMS=6 z2 ­-------- f(x) = A 2 0e A3 A4x A5x2 + + + NTERMS=6 is the default setting. Here, A0 is the height of the Gaussian, A1 is the center of the Gaussian, A2 is the width of the Gaussian, A3 is the constant term, A4 is the linear term, and A5 is the quadratic term. NTERMS=5 z2 ­-------- f(x) = A 2 0e + A3 + A4x NTERMS=4 z2 ­-------- f(x) = A 2 0e + A3 NTERMS=3 z2 ­-------- f(x) = A 2 0e Example ; Define the independent variables: X = FINDGEN(13)/5 - 1.2 ; Define the dependent variables: Y = [0.0, 0.1, 0.2, 0.5, 0.8, 0.9, $ 0.99, 0.9, 0.8, 0.5, 0.2, 0.1, 0.0] ; Fit the data to the default function, storing coefficients in A: yfit = GAUSSFIT(X, Y, A) ; Print the coefficients: PRINT, A IDL prints: 2.25642 -1.62041e-07 0.703372 -1.25634 3.04487e-07 0.513596 We can compare original and fitted data by plotting one on top of the other: ; Load an appropriate color table: LOADCT, 30 ; Plot the original data: PLOT, X, Y ; Overplot the fitted data in a different color: OPLOT, X, yfit, COLOR = 100 See Also COMFIT, CURVEFIT, GAUSS2DFIT, POLY_FIT, REGRESS, SFIT, SVDFIT GAUSSINT [Previous Routine] [Next Routine] [List of Routines] NAME: GAUSSINT The GAUSSINT function evaluates the integral of the Gaussian probability function and returns the result. The Gaussian integral is defined as: x Gaussint x ( ) 1 ---------- e t2 ­ 2 t d 2 ­ If X is double-precision, the result is double-precision, otherwise the argument is converted to floating-point and the result is floating-point. The result has the same structure as the input argument, X. Syntax Result = GAUSSINT(X) Arguments X The expression for which the Gaussian integral is to be evaluated. Example Plot the Gaussian probability function over the range -5 to 5 with a step size of 0.1by entering: X = FINDGEN(101)/10. - 5. PLOT, X, GAUSSINT(X) See Also GAUSS_CVF, GAUSS_PDF GET_DRIVE_LIST [Previous Routine] [Next Routine] [List of Routines] NAME: GET_DRIVE_LIST The GET_DRIVE_LIST function returns a string array of the names of valid drives / volumes for the file system (Windows / Macintosh only). Syntax Result = GET_DRIVE_LIST( [, FIXED] [, COUNT] [, REMOTE] [, CDROM] [, REMOVABLE]) Return Value This function returns a string array of the names of valid drives/volumes for the file system. Arguments None. Keywords REMOVABLE This new keyword reports removable media devices (e.g. floppy, zip drive) other than CDROMs. Note - This is a Windows only keyword. REMOTE This new keyword specifies that remote (i.e. network) drives should be reported. Note - This is a Windows only keyword. FIXED If set by this new keyword, hard drives physically attached to the current system are reported. Note - This is a Windows only keyword. COUNT This new keyword is named variable into which the number of drives/volumes found is placed. If no drives/volumes are found, a value of 0 is returned. CDROM If set by this new keyword, compact disk drives are reported. Note that although CDROM devices are removable, they are treated as a special case, and the REMOVABLE keyword does not apply to them. Note - This is a Windows only keyword. None. GET_KBRD [Previous Routine] [Next Routine] [List of Routines] NAME: GET_KBRD The GET_KBRD function returns the next character available from the standard input (IDL file unit 0) as a one-character string. Syntax Result = GET_KBRD(Wait) Arguments Wait If Wait is zero, GET_KBRD returns the null string if there are no characters in the terminal type-ahead buffer. If it is nonzero, the function waits for a character to be typed before returning. Examples To wait for keyboard input and store one character in the variable R, enter: R = GET_KBRD(1) Press any key to return to the IDL prompt. To see the character that was typed, enter: PRINT, R The following code fragment reads one character at a time and echoes that character's numeric code. It quits when a "q" is entered: REPEAT BEGIN A = GET_KBRD(1) PRINT, BYTE(A) ENDREP UNTIL A EQ 'q' Note The GET_KBRD function can be used to return Windows special characters (in addition to standard keyboard characters), created by holding down the Alt key and entering the character's ANSI equivalent. For example, to return the paragraph marker (¶), ANSI number 0182, enter: C = GET_KBRD(1) While GET_KBRD is waiting, press and hold the Alt key and type 0182 on the numeric keypad. When the IDL prompt returns, enter: PRINT, C IDL prints the paragraph marker,"¶". GET_KBRD cannot be used to return control characters or other editing keys (e.g., Delete, Backspace, etc.). These characters are used for keyboard shortcuts and command line editing only. GET_KBRD can be used to return the Enter key. See Also READ/READF GET_LUN [Previous Routine] [Next Routine] [List of Routines] NAME: GET_LUN The GET_LUN procedure allocates a file unit from a pool of free units. Instead of writing routines to assume the use of certain file units, IDL functions and procedures should use GET_LUN to reserve unit numbers in order to avoid conflicts with other routines. Use FREE_LUN to free the file units when finished. Syntax GET_LUN, Unit Arguments Unit The named variable into which GET_LUN should place the file unit number. Unit is converted into a longword integer in the process. The file unit number obtained is in the range 100 to 128. Example Instead of explicitly specifying a file unit number that may already be used, use GET_LUN to obtain a free one and store the result in the variable U by entering: GET_LUN, U Now U can be used in opening a file: OPENR, U, 'file.dat' Once the data from "file.dat" has been read, the file can be closed and the file unit can be freed with the command: FREE_LUN, U Note also that OPENR has a GET_LUN keyword that allows you to simultaneously obtain a free file unit and open a file. The following command performs the same tasks as the first two commands above: OPENR, U, 'file.dat', /GET_LUN See Also FREE_LUN, OPEN GET_SCREEN_SIZE [Previous Routine] [Next Routine] [List of Routines] NAME: GET_SCREEN_SIZE The GET_SCREEN_SIZE function returns a two-element vector of the form [width, height] that represents the dimensions, measured in device units, of the screen. Syntax Result = GET_SCREEN_SIZE( [Display_name] [, RESOLUTION=variable] ) X Windows Keywords: [, DISPLAY_NAME=string] Arguments Display_name (X Only) A string indicating the name of the X WIndows display that should be used to determine the screen size. Keywords DISPLAY_NAME (X Only) Set this keyword equal to a string indicating the name of the X WIndows display that should be used to determine the screen size. Setting this keyword is equivalent to setting the optional Display_name argument. RESOLUTION Set this keyword equal to a named variable that will contain a two-element vector, [xres, yres], specifying the screen resolution in cm/pixel. Example You can find the dimensions and screen resolution of your screen by entering the following: dimensions = GET_SCREEN_SIZE(RESOLUTION=resolution) PRINT, dimensions, resolution For the screen on which this was tested, IDL prints: 1280.00 1024.00 0.0282031 0.0281250 GET_SYMBOL [Previous Routine] [Next Routine] [List of Routines] NAME: GET_SYMBOL The GET_SYMBOL function returns the value of a VMS DCL (Digital Command Language) interpreter symbol as a scalar string. If the symbol is undefined, the null string is returned. Note This procedure is available on VMS only. Syntax Result = GET_SYMBOL( Name [, TYPE={1 | 2}] ) Arguments Name A scalar string containing the name of the symbol to be translated. Keywords TYPE The table from which Name is translated. Set TYPE to 1 to specify the local symbol table. A value of 2 specifies the global symbol table. The default is to search the local table. See Also GETENV GETENV [Previous Routine] [Next Routine] [List of Routines] NAME: GETENV The GETENV function returns the equivalence string for Name from the environment of the IDL process. Returns the equivalence string for Name from the environment of the IDL process, or a null string if Name does not exist in the environment. If Name is an array, the result has the same structure, with each element containing the equivalence string for the corresponding element of Name. Syntax Result = GETENV( Name ) UNIX-Only Keywords: [, /ENVIRONMENT] Return Value Returns the equivalence string for Name from the environment of the IDL process, or a null string if Name does not exist in the environment. Arguments Name The scalar string for which an equivalence string from the environment is desired. UNIX-Only Keywords ENVIRONMENT If set, returns a string array containing all entries in the current process, one variable per entry, in the SETENV format (Variable=Value). If ENVIRONMENT is set, the Name argument should not be supplied. Environment Variables Under VMS VMS does not directly support the concept of environment variables. Instead, it is emulated (by using the standard C getenv() function) as described below, enabling you to use GETENV portably between UNIX and VMS: * If Name is one of HOME, TERM, PATH, or USER, an appropriate response is generated. This mimics the most common UNIX environment variables. * An attempt is made to translate Name as a logical name. All four logical name tables are searched in the standard order. * An attempt is made to translate Name as a command-language interpreter symbol. Special Handling of the IDL_TMPDIR Environment Variable If you specify 'IDL_TMPDIR' as the value of Name, and an environment variable with that name exists, GETENV returns its defined value as usual. However, if TMP_DIR is not defined, GETENV returns the path of the location where IDL's internals believe temporary files should be written on your system. Using IDL_TMPDIR in this manner makes it simple for code written in IDL to follow the same conventions as IDL itself, and provides the user with an easy way to override this decision. The actual location used is system dependent. When possible, IDL tries to follow operating system and vendor conventions. Example To print the name of the current UNIX shell, enter the command: PRINT, 'The current shell is: ', GETENV('SHELL') The UNIX Environment Every UNIX process has an environment. The environment consists of environment variables, each of which has a string value associated with it. Some environment variables always exist, such as PATH that tells the shell where to look for programs or TERM that specifies the kind of terminal being used. Others can be added by the user, usually from an interactive shell and often from the .login file that is executed when you log in. When a process is created, it is given a copy of the environment from its parent process. IDL is no exception to this; when started, it inherits a copy of its parent's environment. The parent process to IDL is usually the interactive shell from which it was started. In turn, any child process created by IDL (such as those from the SPAWN procedure) inherits a copy of IDL's current environment. Note It is important to realize that environment variables are not an IDL feature; they are part of every UNIX process. Although they can serve as a form of global memory, it is best to avoid using them in that way. Instead, IDL heap variables (pointers or object references), IDL system variables, or common blocks should be used in that role. This will make your IDL code portable to non-UNIX-based IDL systems. Environment variables should be used for communicating with child processes. One example is setting the value of the SHELL environment variable prior to calling SPAWN to change the shell executed by SPAWN. IDL provides two routines for manipulating the environment: GETENV The GETENV function returns the equivalence string from the environment of the IDL process. It has the form: GETENV(Name) where Name is the name of the environment variable for which the translation is desired. If Name does not exist in the environment, a null string is returned. For example, to determine the type of terminal being used, you can enter the IDL statement: PRINT, 'The terminal type is: ', GETENV('TERM') Executing this statement on a Sun workstation give the following result: The terminal type is: sun SETENV The SETENV function adds a new environment variable or changes the value of an existing environment variable in the IDL process. It has the form: SETENV, Environment_Expression where Environment_Expression is a scalar string containing an environment expression to be added to the environment. For example, you can change the shell used by SPAWN by changing the value of the SHELL environment variable. An IDL statement to change to using the Bourne shell /bin/sh would be: SETENV, 'shell=/bin/sh' See Also GET_SYMBOL, SETENV, TRNLOG GOTO [Previous Routine] [Next Routine] [List of Routines] NAME: GOTO The GOTO statement transfers program control to point specified by a label. The GOTO statement is generally considered to be a poor programming practice that leads to unwieldy programs. Its use should be avoided. However, for those cases in which the use of a GOTO is appropriate, IDL does provide the GOTO statement. Note that using a GOTO to jump into the middle of a loop results in an error. Warning You must be careful in programming with GOTO statements. It is not difficult to get into a loop that will never terminate, especially if there is not an escape (or test) within the statements spanned by the GOTO. For information on using GOTO and other IDL program control statements, see Chapter 11, "Program Control" in Building IDL Applications. Syntax GOTO, label Example In the following example, the statement at label JUMP1 is executed after the GOTO statement, skipping any intermediate statements: GOTO, JUMP1 PRINT, 'Skip this' ; This statement is skipped PRINT, 'Skip this' ; This statement is also skipped JUMP1: PRINT, 'Do this' The label can also occur before the GOTO statement that refers to the label, but you must be careful to avoid an endless loop. GOTO statements are frequently the subjects of IF statements, as in the following statement: IF A NE G THEN GOTO, MISTAKE GRID_TPS [Previous Routine] [Next Routine] [List of Routines] NAME: GRID_TPS The GRID_TPS function uses thin plate splines to interpolate a set of values over a regular two dimensional grid, from irregularly sampled data values. Thin plate splines are ideal for modeling functions with complex local distortions, such as warping functions, which are too complex to be fit with polynomials. Given n points, (xi, yi) in the plane, a thin plate spline can be defined as: n ­ 1 f (x, y) = a 2 2 0 + a + + --- 1x a2y 12 b iri logri i = 0 with the constraints: n ­ 1 n ­ 1 n ­ 1 b i = b ixi= b iyi= 0 i = 1 i = 1 i = 0 where r 2i = (x-xi)2 + (y-yi)2. A thin plate spline (TPS) is a smooth function, which implies that it has continuous first partial derivatives. It also grows almost linearly when far away from the points (xi, yi). The TPS surface passes through the original points: f(xi, yi) = zi. Note GRID_TPS requires at least 7 noncolinear points. Syntax Interp = GRID_TPS (Xp, Yp, Values [, COEFFICIENTS=variable] [, NGRID=[nx, ny]] [, START=[x0, y0]] [, DELTA=[dx, dy]] ) Return Value The function returns an array of dimension (nx, ny) of interpolated values. If the values argument is a two-dimensional array, the output array has dimensions (nz, nx, ny), where nz is the leading dimension of the values array allowing for the interpolation of arbitrarily sized vectors in a single call. Keywords can be used to specify the grid dimensions, size, and location. Arguments Xp A vector of x points. Yp A vector of y points, with the same number of elements as the Xp argument. Values A vector or two-dimensional array of values to interpolate. If values are a two- dimensional array, the leading dimension is the number of values for which interpolation is performed. Keywords COEFFICIENTS A named variable in which to store the resulting coefficients of the thin plate spline function for the last set of Values. The first N elements, where N is the number of input points, contain the coefficients bi, in the previous equation. Coefficients with subscripts n, n+1, and n+2, contain the values of a0, a1, and a2, in the above equation. DELTA A two-element array of the distance between grid points (dx, dy). If a scalar is passed, the value is used for both dx and dy. The default is the range of the xp and yp arrays divided by (nx ­ 1, ny ­ 1). NGRID A two-element array of the size of the grid to interpolate (nx, ny). If a scalar is passed, the value is used for both nx and ny. The default value is [25, 25]. START A two-element array of the location of grid point (x0, y0). If a scalar is passed, the value is used for both x0 and y0. The default is the minimum values in the xp and yp arrays. References I. Barrodale, et al, "Note: Warping digital images using thin plate splines", Pattern Recognition, Vol 26, No. 2, pp 375-376, 1993. M. J. D. Powell, "Tabulation of thin plate splines on a very fine two-dimensional grid", Report No. DAMTP 1992/NA2, University of Cambridge, Cambridge, U.K. (1992). Example The following example creates a set of 25 random values defining a surface on a square, 100 units on a side, starting at the origin. Then, we use GRID_TPS to create a regularly gridded surface, with dimensions of 101 by 101 over the square, which is then displayed. The same data set is then interpolated using TRIGRID, and the two results are displayed for comparison. ;X values x = RANDOMU(seed, 25) * 100 ;Y values y = RANDOMU(seed, 25) * 100 ;Z values z = RANDOMU(seed, 25) * 10 z1 = GRID_TPS(x, y, z, NGRID=[101, 101], START=[0,0], DELTA=[1,1]) ;Show the result LIVE_SURFACE, z1, TITLE='TPS' ;Grid using TRIGRID TRIANGULATE, x, y, tr, bounds z2 = TRIGRID(x, y, z, tr, [1,1], [0,0,100, 100], $ EXTRAPOLATE=bounds) ;Show triangulated surface LIVE_SURFACE, z2, TITLE='TRIGRID - Quintic' See Also MIN_CURVE_SURF GRID3 [Previous Routine] [Next Routine] [List of Routines] NAME: GRID3 The GRID3 function fits a smooth function to a set of 3D scattered nodes (xi, yi, zi) with associated data values (fi). The function can be sampled over a set of user- specified points, or over an arbitrary 3D grid which can then be viewed using the SLICER3 procedure. GRID3 uses the method described in Renka, R. J., "Multivariate Interpolation of Large Sets of Scattered Data," ACM Transactions on Mathematical Software, Vol. 14, No. 2, June 1988, Pages 139-148, which has been referred to as the Modified Shepard's Method. The function described by this method has the advantages of being equal to the values of fi, at each (xi, yi, zi), and being smooth (having continuous first partial derivatives). If no optional or keyword parameters are supplied, GRID3 produces a regularly- sampled volume with dimensions of (25, 25, 25), made up of single-precision, floating-point values, enclosing the original data points. Syntax Result = GRID3( X, Y, Z, F, Gx, Gy, Gz [, DELTA=scalar/vector] [, DTOL=value] [, GRID=value] [, NGRID=value] [, START=[x, y, z]] ) Arguments X, Y, Z and F Arrays containing the locations of the data points, and the value of the variable to be interpolated at that point. X, Y, Z, and F must have the same number of elements (with a minimum of 10 elements per array) and are converted to floating-point if necessary. Note: For the greatest possible accuracy, the arrays X, Y, and Z should be scaled to fit in the range [0,1]. Gx, Gy, and Gz Optional arrays containing the locations within the volume to be sampled (if the GRID keyword is not set), or the locations along each axis of the sampling grid (if the GRID keyword is set). If these parameters are supplied, the keywords DELTA, NGRID, and START are ignored. If the keyword GRID is not set, the result has the same number of elements as Gx, Gy, and Gz. The ith element of the result contains the value of the interpolate at (Gxi, Gyi, Gzi). The result has the same dimensions as Gx. If the GRID keyword is set, the result of GRID3 is a three-dimensional, single- precision, floating-point array with dimensions of (Nx, Ny, Nz), where Nx, Ny, and Nz are the number of elements in Gx, Gy, and Gz, respectively. Keywords DELTA Set this keyword to a three-element vector or a scalar that specifies the grid spacing in the X, Y, and Z dimensions. The default spacing produces NGRID samples within the range of each axis. DTOL The tolerance for detecting an ill-conditioned system of equations. The default value is 0.01, which is appropriate for small ranges of X, Y, and Z. For large ranges of X, Y, or Z, it may be necessary to decrease the value of DTOL. If you receive the error message "GRID3: Ill-conditioned matrix or all nodes co-planar," try decreasing the value of DTOL. GRID This keyword specifies the interpretation of Gx, Gy, and Gz. The default value for GRID is zero if Gx, Gy, and Gz are supplied, otherwise a regularly-gridded volume is produced. NGRID The number of samples along each axis. NGRID can be set to a scalar, in which case each axis has the same number of samples, or to a three-element array containing the number of samples for each axis. The default value for NGRID is 25. START A three-element array that specifies the starting value for each grid. The default value for START is the minimum value in the respective X, Y, and Z array. Examples Produce a set random points within the (0,1) unit cube and simulate a function: ; Number of irregular samples: N = 300 ; Generate random values between 0 and 1: X = RANDOMU(SEED, N) Y = RANDOMU(SEED, N) Z = RANDOMU(SEED, N) ; The function to simulate: F = (X-.5)^2 + (Y-.5)^2 + Z ; Return a cube with 25 equal-interval samples along each axis: Result = GRID3(X, Y, Z, F) ; Return a cube with 11 elements along each dimension, which ; samples each axis at (0, 0.1, ..., 1.0): Result = GRID3(X, Y, Z, F, START=[0., 0., 0], $ DELTA=0.1, NGRID=10) The same result is produced by the statements: ; Create sample values: S = FINDGEN(11) / 10. Result = GRID3(X, Y, Z, F, S, S, S, /GRID) See Also SLICER3 GS_ITER [Previous Routine] [Next Routine] [List of Routines] NAME: GS_ITER The GS_ITER function solves an n by n linear system of equations using Gauss- Seidel iteration with over- and under-relaxation to enhance convergence. Note that the equations must be entered in diagonally dominant form to guarantee convergence. A system is diagonally dominant if the diagonal element in a given row is greater than the sum of the absolute values of the non-diagonal elements in that row. This routine is written in the IDL language. Its source code can be found in the file gs_iter.pro in the lib subdirectory of the IDL distribution. Syntax Result = GS_ITER( A, B [, /CHECK] [, /DOUBLE] [, LAMBDA=value{0.0 to 2.0}] [, MAX_ITER=value] [, TOL=value] [, X_0=vector] ) Arguments A An n by n integer, single-, or double-precision floating-point array. On output, A is divided by its diagonal elements. Integer input values are converted to single- precision floating-point values. B A vector containing the right-hand side of the linear system Ax=b. On output, B is divided by the diagonal elements of A. Keywords CHECK Set this keyword to check the array A for diagonal dominance. If A is not in diagonally dominant form, GS_ITER reports the fact but continues processing on the chance that the algorithm may converge. DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. LAMBDA A scalar value in the range: [0.0, 2.0]. This value determines the amount of relaxation. Relaxation is a weighting technique used to enhance convergence. * If LAMBDA = 1.0, no weighting is used. This is the default. * If 0.0 LAMBDA < 1.0, convergence improves in oscillatory and non- convergent systems. * If 1.0 < LAMBDA 2.0, convergence improves in systems already known to converge. MAX_ITER The maximum allowed number of iterations. The default value is 30. TOL The relative error tolerance between current and past iterates calculated as: ( (current-past)/current ) . The default is 1.0 × 10-4. X_0 An n-element vector that provides the algorithm's starting point. The default is [1.0, 1.0, ... , 1.0]. Example ; Define an array A: A = [[ 1.0, 7.0, -4.0], $ [ 4.0, -4.0, 9.0], $ [12.0, -1.0, 3.0]] ; Define the right-hand side vector B: B = [12.0, 2.0, -9.0] ; Compute the solution to the system: RESULT = GS_ITER(A, B, /CHECK) IDL prints: Input matrix is not in Diagonally Dominant form. Algorithm may not converge. % GS_ITER: Algorithm failed to converge within given parameters. Since the A represents a system of linear equations, we can reorder it into diagonally dominant form by rearranging the rows: A = [[12.0, -1.0, 3.0], $ [ 1.0, 7.0, -4.0], $ [ 4.0, -4.0, 9.0]] ; Make corresponding changes in the ordering of B: B = [-9.0, 12.0, 2.0] ; Compute the solution to the system: RESULT = GS_ITER(A, B, /CHECK) IDL prints: -0.999982 2.99988 1.99994 See Also CRAMER, LU_COMPLEX, CHOLSOL, LUSOL, SVSOL, TRISOL H_EQ_CT [Previous Routine] [Next Routine] [List of Routines] NAME: H_EQ_CT The H_EQ_CT procedure histogram-equalizes the color tables for an image or a region of the display. A pixel-distribution histogram is obtained, the cumulative integral is taken and scaled, and the result is applied to the current color table. This routine is written in the IDL language. Its source code can be found in the file h_eq_ct.pro in the lib subdirectory of the IDL distribution. Syntax H_EQ_CT [, Image] Arguments Image A two-dimensional byte array representing the image whose histogram is to be used in determining the new color tables. If this value is omitted, the user is prompted to mark the diagonal corners of a region of the display. If Image is specified, it is assumed that the image is loaded into the current IDL window. Image must be scaled the same way as the image loaded to the display. See Also H_EQ_INT H_EQ_INT [Previous Routine] [Next Routine] [List of Routines] NAME: H_EQ_INT The H_EQ_INT procedure interactively histogram-equalizes the color tables of an image or a region of the display. By moving the cursor across the screen, the amount of histogram-equalization can be varied. Either the image parameter or a region of the display marked by the user is used to obtain a pixel-distribution histogram. The cumulative integral is taken and scaled and the result is applied to the current color tables. This routine is written in the IDL language. Its source code can be found in the file h_eq_int.pro in the lib subdirectory of the IDL distribution. Using the H_EQ_INT Interface A window is created and the histogram equalization function is plotted. A linear ramp is overplotted. Move the cursor from left to right to vary the amount of histogram equalization applied to the color tables from 0 to 100%. Press the right mouse button to exit. Syntax H_EQ_INT [, Image] Arguments Image A two-dimensional byte array representing the image whose histogram is to be used in determining the new color tables. If this value is omitted, the user is prompted to mark the diagonal corners of a region of the display. If Image is specified, it is assumed that the image is loaded into the current IDL window. Image must be scaled the same way as the image loaded to the display. See Also H_EQ_CT HANNING [Previous Routine] [Next Routine] [List of Routines] NAME: HANNING The HANNING function is used to create a "window" for Fourier Transform filtering. It can be used to create both Hanning and Hamming windows. This routine is written in the IDL language. Its source code can be found in the file hanning.pro in the lib subdirectory of the IDL distribution. Syntax Result = HANNING( N1 [, N2] [, ALPHA=value{0.5 to 1.0}] [, /DOUBLE] ) Return Value If only N1 is specified, this function returns an array of dimensions [N1]. If both N1 and N2 are specified, this function returns an array of dimensions [N1, N2]. If any of the inputs are double-precision or if the DOUBLE keyword is set, the result is double-precision, otherwise the result is single-precision. Arguments N1 The number of columns in the resulting array. N2 The number of rows in the resulting array. Keywords ALPHA Set this keyword equal to the width parameter of a generalized Hamming window. ALPHA must be in the range of 0.5 to 1.0. If ALPHA = 0.5 (the default) the function is called a "Hanning" window. If ALPHA = 0.54, the result is called a "Hamming" window. DOUBLE Set this keyword to force the computations to be done in double-precision arithmetic. See Also FFT HDF_BROWSER [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_BROWSER The HDF_BROWSER function presents a graphical user interface (GUI) that allows the user to view the contents of a Hierarchical Data Format (HDF), HDF-EOS, or NetCDF file, and prepare a template for the extraction of HDF data and metadata into IDL. The output template is an IDL structure that may be used when reading HDF files with the HDF_READ routine. If you have several HDF files of identical form, the returned template from HDF_BROWSER may be reused to extract data from these files with HDF_READ. If you do not need a multi-use template, you may call HDF_READ directly. Syntax Template = HDF_BROWSER([Filename] [, CANCEL=variable] [, GROUP=widget_id] [, PREFIX=string]) Return Value Returns a template structure containing heap variable references, or 0 if no file was selected. The user is required to clean up the heap variable references when done with them. Arguments Filename A string containing the name of an HDF file to browse. If Filename is not specified, a dialog allows you to choose a file. Keywords CANCEL Set this keyword to a named variable that will contain the byte value 1 (one) if the user clicked the "Cancel" button or the byte value 0 (zero) otherwise. GROUP Set this keyword to the widget ID of a widget that calls HDF_BROWSER. When this ID is specified, a death of the caller results in the death of the HDF_BROWSER. The following example demonstrates how to use the GROUP keyword to properly call HDF_BROWSER from within a widget application. To run this example, save the following code as browser_example.pro: PRO BROWSER_EXAMPLE_EVENT,ev WIDGET_CONTROL,ev.id,GET_VALUE=val CASE val of 'Browser':BEGIN a=HDF_BROWSER(GROUP=ev.top) HELP,a,/st END 'Exit': WIDGET_CONTROL,ev.top,/DESTROY ENDCASE END PRO BROWSER_EXAMPLE a=WIDGET_BASE(/ROW) b=WIDGET_BUTTON(a,VALUE='Browser') c=WIDGET_BUTTON(a,VALUE='Exit') WIDGET_CONTROL,a,/REALIZE XMANAGER,'browser_example',a END PREFIX When HDF_BROWSER reviews the contents of an HDF file, it creates default output names for the various data elements. By default these default names begin with a prefix derived from the filename. Set this keyword to a string value to be used in place of the default prefix. Graphical User Interface Menu Options The following options are available from the graphical user interface menus. Pulldown Menu The following table shows the options available with the pulldown menu. Menu Selection Description HDF/NetCDF Summary DF24 (24-bit Images) 24-bit images and their attributes DFR8 (8-bit Images) 8-bit images and their attributes Table 22: HDF_BROWSER Pulldown Menu Options Menu Selection Description DFP (Palettes) Image palettes SD (Variables/Attributes) Scientific Datasets and attributes AN (Annotations) Annotations GR (Generic Raster) Images GR Global (File) Attributes Image attributes VGroups Generic data groups VData Generic data and attributes HDF-EOS Summary Point EOS point data and attributes Swath EOS swath data and attributes Grid EOS grid data and attributes Table 22: HDF_BROWSER Pulldown Menu Options Preview Button If you have selected an image, 2D data set, or 3xnxm data set from the pulldown menu, click on this button to view the image. If you have selected a data item that can be plotted in two dimensions, click on this button to view a 2D plot of the data (the default) or click on the "Surface" radio button to display a surface plot, click on the "Contour" radio button to display a contour plot, or click on the "Show3" radio button for an image, surface, and contour display. You can also select the "Fit to Window" checkbox to fit the image to the window. Read Checkbox Select this checkbox to extract the current data or metadata item from the HDF file. Extract As Specify a name for the extracted data or metadata item Note The Read Checkbox must be selected for the item to be extracted. Default names are generated for all data items, but may be changed at any time by the user. Example template = HDF_BROWSER('test.hdf') output_structure = HDF_READ(TEMPLATE=template) or, output_structure = HDF_READ('test.hdf', TEMPLATE=template) See Also HDF_READ HDF_READ [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_READ The HDF_READ function allows extraction of Hierarchical Data Format (HDF), HDF-EOS, and NetCDF data and metadata into an output structure based upon information provided through a graphical user interface or through a file template generated by HDF_BROWSER. The output structure is a single level structure corresponding to the data elements and names specified by HDF_BROWSER or its output template. Templates generated by HDF_BROWSER may be re-used for HDF files of identical format. Syntax Result = HDF_READ( [Filename] [, DFR8=variable] [, DF24=variable] [, PREFIX=string] [, TEMPLATE =value] ) Arguments Filename A string containing the name of a HDF file to extract data from. If Filename is not specified, a dialog allows you to specify a file. Note that if a template is specified, the template must match the HDF file selected. Keywords DFR8 Set this keyword to a named variable that will contain a 2 x n string array of extracted DFR8 images and their palettes. The first column will contain the extracted DFR8 image names, while the second column will contain the extracted name of the associated palette. If no palette is associated with a DFR8 image the palette name will be set to the null string. If no DFR8 images were extracted from the HDF file, this returned string will be the null string array ['', '']. DF24 Set this keyword to a named variable that will contain a string array of the names of all the extracted DF24 24-bit images. This is useful in determining whether a (3,n,m) extracted data element is a 24-bit image or another type of data. If no DF24 24-bit images were extracted from the HDF file, the returned string will be the null string (''). PREFIX When HDF_READ is called without a template, it calls HDF_BROWSER to review the contents of an HDF file and create the default output names for the various data elements. By default, these names begin with a prefix derived from the filename. Set this keyword to a string value to be used in place of the default prefix. TEMPLATE Set this keyword to specify the HDF file template (generated by the function HDF_BROWSER), that defines which data elements to extract from the selected HDF file. Templates may be used on any files that have a format identical to the file the template was created from. Graphical User Interface Menu Options The following options are available from the graphical user interface menus. Pulldown Menu The following table shows the options available with the pulldown menu. Menu Selection Description HDF/NetCDF Summary DF24 (24-bit Images) 24-bit images and their attributes DFR8 (8-bit Images) 8-bit images and their attributes DFP (Palettes) Image palettes SD (Variables/Attributes) Scientific Datasets and attributes AN (Annotations) Annotations GR (Generic Raster) Images GR Global (File) Attributes Image attributes VGroups Generic data groups VData Generic data and attributes HDF-EOS Summary Point EOS point data and attributes Table 23: HDF_BROWSER Pulldown Menu Options Menu Selection Description Swath EOS swath data and attributes Grid EOS grid data and attributes Table 23: HDF_BROWSER Pulldown Menu Options Preview Button If you have selected an image, 2D data set, or 3xnxm data set from the pulldown menu, click on this button to view the image. If you have selected a data item that can be plotted in two dimensions, click on this button to view a 2D plot of the data (the default) or click on the "Surface" radio button to display a surface plot, click on the "Contour" radio button to display a contour plot, or click on the "Show3" radio button for an image, surface, and contour display. You can also select the "Fit to Window" checkbox to fit the image to the window. Read Checkbox Select this checkbox to extract the current data or metadata item from the HDF file. Extract As Specify a name for the extracted data or metadata item Note The Read Checkbox must be selected for the item to be extracted. Default names are generated for all data items, but may be changed at any time by the user. Example template = HDF_BROWSER('my.hdf') output_structure = HDF_READ(TEMPLATE=template) or, output_structure = HDF_READ('my.hdf') or, ;Select'my.hdf' with the file locator output_structure = HDF_READ() or, output_structure = HDF_READ('just_like_my.hdf', TEMPLATE=template) See Also HDF_BROWSER HEAP_GC [Previous Routine] [Next Routine] [List of Routines] NAME: HEAP_GC The HEAP_GC procedure performs garbage collection on heap variables. It searches all current IDL variables (including common blocks, widget user values, etc.) for pointers and object references and determines which heap variables have become inaccessible. Pointer heap variables are freed (via PTR_FREE) and all memory used by the heap variable is released. Object heap variables are destroyed (via OBJ_DESTROY), also freeing all used memory. The default action is to perform garbage collection on all heap variables regardless of type. Use the POINTER and OBJECT keywords to remove only specific types. Note Garbage collection is an expensive operation. When possible, applications should be written to avoid losing pointer and object references and avoid the need for garbage collection. Warning HEAP_GC uses a recursive algorithm to search for unreferenced heap variables. If HEAP_GC is used to manage certain data structures, such as large linked lists, a potentially large number of operations may be pushed onto the system stack. If so many operations are pushed that the stack runs out of room, IDL will crash. Syntax HEAP_GC [, /OBJ | , /PTR] [, /VERBOSE] Keywords OBJ Set this keyword to perform garbage collection on object heap variables only. PTR Set this keyword to perform garbage collection on pointer heap variables only. Note Setting both the PTR and OBJ keywords is the same a setting neither. VERBOSE If this keyword is set, HEAP_GC writes a one line description of each heap variable, in the format used by the HELP procedure, as the variable is destroyed. This is a debugging aid that can be used by program developers to check for heap variable leaks that need to be located and eliminated. HELP [Previous Routine] [Next Routine] [List of Routines] NAME: HELP The HELP procedure gives the user information on many aspects of the current IDL session. The specific area for which help is desired is selected by specifying the appropriate keyword. If no arguments or keywords are specified, the default is to show the current nesting of procedures and functions, all current variables at the current program level, and open files. Only one keyword can be specified at a time. Syntax HELP, Expression1, ..., Expressionn [, DEVICE] [, /ALL_KEYS] [, /BREAKPOINTS] [, /BRIEF] [, CALLS=variable] [, /DEVICE] [, /DLM] [, /FILES] [, /FULL] [, /FUNCTIONS] [, /HEAP_VARIABLES] [, /KEYS] [, /LAST_MESSAGE] [, /MEMORY] [, /MESSAGES] [, N [, /OBJECTS] [, OUTPUT=variable] [, /PROCEDURES] [, /RECALL_COMMANDS] [, /ROUTINES] [, /SOURCE_FILES] [, /STRUCTURES] [, /SYSTEM_VARIABLES] [, /TRACEBACK] Arguments Expression(s) The arguments are interpreted differently depending on the keyword selected. If no keyword is selected, HELP displays basic information for its parameters. For example, to see the type and structure of the variable A, enter: HELP, A Keywords Note that the use of some of the following keywords causes any arguments to HELP to be ignored and HELP provides other types of information instead. If the description of the keyword does not explicitly mention the arguments, the arguments are ignored. ALL_KEYS Set this keyword to show current function-key definitions as set by DEFINE_KEY. If no arguments are supplied, information on all function keys is displayed. If arguments are provided, they must be scalar strings containing the names of function keys, and information on the specified keys is given. Under UNIX, this keyword is different from KEYS because every key is displayed, no matter what its current programming. Under VMS and Windows, the two keywords mean the same thing. On the Macintosh, keys cannot be defined via DEFINE_KEY. ALL_KEYS is equivalent to "/KEYS, /FULL". BREAKPOINTS Set this keyword to display the breakpoint table which shows the program module and location for each breakpoint. BRIEF If set in conjunction with one of the following keywords, BRIEF produces very terse summary style output instead of the output normally displayed by those keywords: * DLM * HEAP_VARIABLES * MESSAGES * OBJECTS * ROUTINES * SOURCE_FILES * STRUCTURES * SYSTEM_VARIABLES CALLS Set this keyword to a named variable in which to store the procedure call stack. Each string element contains the name of the program module, source file name, and line number. Array element zero contains the information about the caller of HELP, element one contains information about its caller, etc. This keyword is useful for programs that require traceback information. DEVICE On UNIX systems, a new field (Bits Per RGB) has been added to the output from the DEVICE keyword. This Bits Per RGB field indicates the amount of bits utilized for each RGB component. Set this keyword to show information about the currently selected graphics device. This information is dependent on the abilities of the current device, but the name of the device is always given. Arguments to HELP are ignored when DEVICE is specified. DLM Set this keyword to display all known dynamically loadable modules and their state (loaded or not loaded). FILES Set this keyword to display information about file units. If no arguments are supplied in the call to HELP, information on all open file units (except the special units 0, -1, and -2) is displayed. If arguments are provided, they are taken to be integer file unit numbers, and information on the specified file units is given. For example, the command: HELP, /FILES, -2, -1, 0 gives information below about the default file units: Unit Attributes Name -2 Write, Truncate, Tty, Reserved -1 Write, Truncate, Tty, Reserved 0 Read, Tty, Reserved The attributes column tells about the characteristics of the file. For instance, the file connected to logical file unit 2 is called "stderr" and is the standard error file. It is opened for write access (Write), is a new file (Truncate), is a terminal (Tty), and cannot be closed by the CLOSE command (Reserved). FULL By default, HELP filters its output in an attempt to only display information likely to be of use to the IDL end user. Specify FULL to see all available information on a given topic without any such filtering. The filtering applied by default depends on the type of information being requested: * Function keys: By default, IDL will not display undefined function keys. * Structure Definitions And Objects: Structures and objects that have had their definition hidden using the STRUCT_HIDE procedure are not usually listed. * Functions and Procedures: Functions and procedures compiled with the COMPILE_OPT HIDDEN directive are not usually included in HELP output. FUNCTIONS Normally, the ROUTINES or SOURCE_FILES keywords produce information on both functions and procedures. If FUNCTIONS is specified, only output on functions is produced. If FUNCTIONS is used without either ROUTINES or SOURCE_FILES, ROUTINES is assumed. HEAP_VARIABLES Set this keyword to display help information for all the current heap variables. KEYS Set this keyword to show current function key definitions as set by DEFINE_ KEY, for those function keys that are currently programmed to perform a function. Under UNIX, this keyword is different from ALL_KEYS because that keyword displays every key, no matter what its current programming. Under VMS and Windows, the two keywords mean the same thing. On the Macintosh, keys cannot be defined via DEFINE_KEY. If no arguments are supplied, information on all function keys is displayed. If arguments are provided, they must be scalar strings containing the names of function keys, and information on the specified keys is given. LAST_MESSAGE Set this keyword to display the last error message issued by IDL. MEMORY Set this keyword to see a report on the amount of dynamic memory (in bytes) currently in use by the IDL session; the maximum amount of dynamic memory allocated since the last call to HELP, /MEMORY; and the number of times dynamic memory has been allocated and deallocated. Arguments to HELP are ignored when MEMORY is specified. MESSAGES Set this keyword to display all known message blocks and the error space range into which they are loaded. NAMES A string used to determine the names of the variables, whose values are to be printed. A string match (equivalent to the STRMATCH function with the FOLD_CASE keyword set) is used to decide if a given variable will be displayed. The match string can contain any wildcard expression supported by STRMATCH, including "*" and "?". For example, to print only the values of variables beginning with "A", use the command HELP,/NAME='a*'. Similarly, HELP,NAME='?' prints the values of all variables with a single-character name. NAMES also works with the output from the following keywords: * DLM * HEAP_VARIABLES * MESSAGES * OBJECTS * ROUTINES * SOURCE_FILES * STRUCTURES * SYSTEM_VARIABLES OBJECTS Set this keyword to display information on defined object classes. If no arguments are provided, all currently-defined object classes are shown. If no arguments are provided, and the information you are looking for is not displayed, use the FULL keyword to prevent HELP from filtering the output. If arguments are provided, the definition of the object class for the heap variables referred to is displayed. Information is provided on inherited superclasses and all known methods. A method is known to IDL only if it has been compiled in the current IDL session and called by its own class or a subclass. Methods that have not been compiled yet will not be shown. Thus, the list of methods displayed by HELP is not necessarily a complete list of all possible method for the object class. If called within a class' method, the OBJECTS keyword also displays the instance data of the object on which it was called. OUTPUT Set this keyword equal to a named variable that will contain a string array containing the formatted output of the HELP command. Each line of formatted output becomes a single element in the string array. Warning The OUTPUT keyword is primarily for use in capturing HELP output in order to display it someplace else, such as in a text widget. This keyword is not intended to be used in obtaining programmatic information about the IDL session, and is formatted to be human readable. Research Systems reserves the right to change the format and content of this text at any time, without warning. If you find yourself using OUTPUT for a non-display purpose, you should consider submitting an enhancement request for a function that will provide the information you require in a safe form. PROCEDURES Normally, the ROUTINES or SOURCE_FILES keywords produce information on both functions and procedures. If PROCEDURES is specified, only output on procedures is produced. If PROCEDURES is used without either ROUTINES or SOURCE_FILES, ROUTINES is assumed. RECALL_COMMANDS Set this keyword to display the saved commands in the command input buffer. By default, IDL saves the last 20 lines of input in a buffer from which they can be recalled for command line editing. Arguments to HELP are ignored when RECALL is specified. The number of lines saved can be changed by assigning the desired number of lines to the environment variable !EDIT_INPUT in the IDL startup file. See "!EDIT_INPUT" on page 2429 for details. ROUTINES Set this keyword to show a list of all compiled procedures and functions with their parameter names. Keyword parameters accepted by each module are shown to the right of the routine name. If no arguments are provided, and the information you are looking for is not displayed, use the FULL keyword to prevent HELP from filtering the output. SOURCE_FILES Set this keyword to display information on procedures and functions written in the IDL language that have been compiled during the current IDL session. Full path names (relative to the current directory) of compiled .pro files are displayed. If no arguments are provided, and the information you are looking for is not displayed, use the FULL keyword to prevent HELP from filtering the output. STRUCTURES Set this keyword to display information on structure-type variables. If no arguments are provided, all currently-defined structures are shown. If no arguments are provided, and the information you are looking for is not displayed, use the FULL keyword to prevent HELP from filtering the output. If arguments are provided, the structure definition for those expressions is displayed. It is often more convenient to use HELP, /STRUCTURES instead of PRINT to look at the contents of a structure variable because it shows the names of the fields as well as the data. SYSTEM_VARIABLES Set this keyword to display information on all system variables. Arguments are ignored. TRACEBACK Set this keyword to display the current nesting of procedures and functions. Example To see general information on the current IDL session, enter: HELP To see information on the structure definition of the system variable !D, enter: HELP, !D, /STRUCTURES See Also ch HILBERT [Previous Routine] [Next Routine] [List of Routines] NAME: HILBERT The HILBERT function returns a series that has all periodic terms phase-shifted by 90 degrees. The output is a complex-valued vector with the same size as the input vector. This transform has the interesting property that the correlation between a series and its own Hilbert transform is mathematically zero. HILBERT generates the fast Fourier transform using the FFT function, and shifts the first half of the transform products by +90 degrees and the second half by -90 degrees. The constant elements in the transform are not changed. Angle shifting is accomplished by multiplying or dividing by the complex number, i = (0.0000, 1.0000). The shifted vector is then submitted to FFT for transformation back to the "time" domain and the output is divided by the number elements in the vector to correct for multiplication effect peculiar to the FFT algorithm. Note: Because HILBERT uses FFT, it exhibits the same side effects with respect to input arguments as that function. This routine is written in the IDL language. Its source code can be found in the file hilbert.pro in the lib subdirectory of the IDL distribution. Syntax Result = HILBERT(X [, D]) Arguments X An n-element floating-point or complex-valued vector. D A flag for rotation direction. Set D = +1 for a positive rotation (the default). Set D = - 1 for a negative rotation. See Also FFT HIST_2D [Previous Routine] [Next Routine] [List of Routines] NAME: HIST_2D The HIST_2D function returns the two dimensional density function (histogram) of two variables, a longword array of dimensions (MAX(V1)+1, MAX(V2)+1). Result(i,j) is equal to the number of simultaneous occurrences of V1 = i and V2 = j at the specified element. This routine is written in the IDL language. Its source code can be found in the file hist_2d.pro in the lib subdirectory of the IDL distribution. Syntax Result = HIST_2D( V1, V2 [, BIN1=width] [, BIN2=height] [, MAX1=value] [, MAX2=value] [, MIN1=value] [, MIN2=value] ) Arguments V1, V2 Arrays containing the variables. V1 and V2 must be of byte, integer, or longword type, and must contain no negative elements. Keywords BIN1 The size of each bin in the V1 direction (column width). If this keyword is not specified, the size is set to 1. BIN2 The size of each bin in the V2 direction (row height). If this keyword is not specified, the size is set to 1. MAX1 MAX1 is the maximum V1 value to consider. If this keyword is not specified, then V1 is searched for its largest value. MAX2 MAX2 is the maximum V2 value to consider. If this keyword is not specified, then V2 is searched for its largest value. MIN1 MIN1 is the minimum V1 value to consider. If this keyword is not specified, then it is set to 0. MIN2 MIN2 is the minimum V2 value to consider. If this keyword is not specified, then it is set to 0. Example To return the 2D histogram of two byte images: R = HIST_2D(image1, image2) To return the 2D histogram made from two floating point images with range of -1 to +1, and with 100 bins: R = HIST_2D(LONG((F1+1) * 50), LONG((F2+1) * 50)) See Also H_EQ_CT, H_EQ_INT, HIST_EQUAL, HISTOGRAM HIST_EQUAL [Previous Routine] [Next Routine] [List of Routines] NAME: HIST_EQUAL The HIST_EQUAL function returns a histogram-equalized byte array. The HISTOGRAM function is used to obtain the density distribution of the input array. The histogram is integrated to obtain the cumulative density-probability function and finally the lookup function is used to transform to the output image. Note The first element of the histogram is always zeroed to remove the background. This routine is written in the IDL language. Its source code can be found in the file hist_equal.pro in the lib subdirectory of the IDL distribution. Syntax Result = HIST_EQUAL( A [, FCN] [, BINSIZE=value] [, /HISTOGRAM_ONLY] [, MAXV=value] [, MINV=value] [, OMAX=variable] [, OMIN=variable] [, PERCENT=value] [, TOP=value] ) Return Value This function returns a histogram-equalized array of type byte, with the same dimensions as the input array. If the HISTOGRAM_ONLY keyword is set, then the output will be a vector of type LONG. Arguments A The array to be histogram-equalized. Keywords FCN Set this keyword to the desired cumulative probability distribution function in the form of a 256 element vector. If omitted, a linear ramp, which yields equal probability bins results. This function is later normalized, so magnitude is inconsequential, though it should increase monotonically. BINSIZE Set this keyword to the size of the bin to use. The default is BINSIZE=1 if A is a byte array, or, for other input types, the default is (MAXV ­ MINV)/5000. HISTOGRAM_ONLY Set this keyword to return a vector of type LONG containing the cumulative distribution histogram, rather than the histogram equalized array. MAXV Set this keyword to the maximum value to consider. The default is 255 if A is a byte array, otherwise the maximum data value is used. Input elements greater than or equal to MAXV are output as 255. MINV Set this keyword to the minimum value to consider. The default is 0 if A is a byte array, otherwise the minimum data value is used. Input elements less than or equal to MINV are output as 0. OMAX Set this keyword to a named variable that, upon exit, will contain the maximum data value used in constructing the histogram. OMIN Set this keyword to a named variable that, upon exit, will contain the minimum data value used in constructing the histogram. PERCENT Set this keyword to a value between 0 and 100 to stretch the image histogram. The histogram will be stretched linearly between the limits that exclude the PERCENT fraction of the lowest values, and the PERCENT fraction of the highest values. This is an automatic, semi-robust method of contrast enahncement. 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 Create a sample image using the DIST function and display it: image = DIST(100) TV, image Create a histogram-equalized version of the byte array, image, and display the new version. Use a minimum input value of 10, a maximum input value of 200, and limit the top value of the output array to 220: new = HIST_EQUAL(image, MINV = 10, MAXV = 200, TOP = 220) TV, new See Also H_EQ_CT, H_EQ_INT, HIST_2D, HISTOGRAM HISTOGRAM [Previous Routine] [Next Routine] [List of Routines] NAME: HISTOGRAM The HISTOGRAM function computes the density function of Array. In the simplest case, the density function, at subscript i, is the number of Array elements in the argument with a value of i. Let Fi= the value of element i, 0 i < n. Let Hv = result of histogram function, an integer vector. The definition of the histogram function becomes: 1, v (F ­ ) Binsize < v + 1 P(F i Min i, v) = 0, Otherwise n ­ 1 H ­ v = P F ( i, v), v = 0, 1, 2, ... Max Min , --------------------------- Binsize i = 0 Warning There may not always be enough virtual memory available to find the density functions of arrays that contain a large number of bins. For bivariate probability distributions, use the HIST_2D function. HISTOGRAM can optionally return an array containing a list of the original array subscripts that contributed to each histogram bin. This list, commonly called the reverse (or backwards) index list, efficiently determines which array elements are accumulated in a set of histogram bins. A typical application of the reverse index list is reverse histogram or scatter plot interrogation-a histogram bin or 2D scatter plot location is marked with the cursor and the original data items within that bin are highlighted. Syntax Result = HISTOGRAM( Array [, BINSIZE=value] [, INPUT=variable] [, MAX=value] [, MIN=value] [, /NAN] [, NBINS=value] [, OMAX=variable] [, OMIN=variable] [, /L64 | REVERSE_INDICES=variable] ) Return Value Returns a 32-bit or a 64-bit integer vector equal to the density function of the input Array. Arguments Array The vector or array for which the density function is to be computed. Keywords BINSIZE Set this keyword to the size of the bin to use. If this keyword is not specified, and NBINS is not set, then a bin size of 1 is used. If NBINS is set, the default is BINSIZE = (MAX ­ MIN) / (NBINS ­ 1). Note The data type of the value specified for BINSIZE should match the data type of the Array argument. Since BINSIZE is converted to the data type of Array, specifying mismatched data types may produce undesired results. INPUT Set this keyword to a named variable that contains an array to be added to the output of HISTOGRAM. The density function of Array is added to the existing contents of INPUT and returned as the result. The array is converted to longword type if necessary and must have at least as many elements as are required to form the histogram. Multiple histograms can be efficiently accumulated by specifying partial sums via this keyword. L64 By default, the return value of HISTOGRAM is 32-bit integer when possible, and 64- bit integer if the number of elements being processed requires it. Set L64 to force 64- bit integers to be returned in all cases. L64 controls the type of Result as well as the output from the REVERSE_INDICES keyword. Note Only 64-bit versions of IDL are capable of creating variables requiring a 64-bit result. Check the value of !VERSION.MEMORY_BITS to see if your IDL is 64-bit or not. MAX Set this keyword to the maximum value to consider. If this keyword is not specified, Array is searched for its largest value. Note The data type of the value specified for MAX should match the data type of the input array. Since MAX is converted to the data type of the input array, specifying mismatched data types may produce undesired results. Note If NBINS is specified, the value for MAX will be adjusted to NBINS*BINSIZE + MIN. This ensures that the last bin has the same width as the other bins. MIN Set this keyword to the minimum value to consider. If this keyword is not specified, and Array is of type byte, 0 is used. If this keyword is not specified and Array is not of byte type, Array is searched for its smallest value. Note The data type of the value specified for MIN should match the data type of the input array. Since MIN is converted to the data type of the input array, specifying mismatched data types may produce undesired results. NAN Set this keyword to cause the routine to check for occurrences of the IEEE floating- point value NaN (not a number) in the input data. Elements with the value NaN are treated as missing data. (See "Special Floating-Point Values" in Chapter 17 of Building IDL Applications for more information on IEEE floating-point values.) NBINS Set this keyword to the number of bins to use. If BINSIZE is specified, the number of bins in Result is NBINS, starting at MIN and ending at MIN+(NBINS­1)*BINSIZE. If MAX is specified, the bins will be evenly spaced between MIN and MAX. It is an error to specify NBINS with both BINSIZE and MAX. OMAX Set this keyword to a named variable that will contain the maximum data value used in constructing the histogram. OMIN A named variable that, upon exit, contains the minimum data value used in constructing the histogram. REVERSE_INDICES Set this keyword to a named variable in which the list of reverse indices is returned. When possible, this list is returned as a 32-bit integer vector whose number of elements is the sum of the number of elements in the histogram, N, and the number of array elements included in the histogram, plus one. If the number of elements is too large to be contained in a 32-bit integer, or if the L64 keyword is set, REVERSE_INDICES is returned as a 64-bit integer. The subscripts of the original array elements falling in the ith bin, 0 i < N, are given by the expression: R(R[i] : R[i+1]-1), where R is the reverse index list. If R[i] is equal to R[i+1], no elements are present in the ith bin. For example, make the histogram of array A: H = HISTOGRAM(A, REVERSE_INDICES = R) ;Set all elements of A that are in the ith bin of H to 0. IF R[i] NE R[i+1] THEN A[R[R[I] : R[i+1]-1]] = 0 The above is usually more efficient than the following: bini = WHERE(A EQ i, count) IF count NE 0 THEN A[bini] = 0 Examples ; Create a simple, 2D dataset: D = DIST(200) ; Plot the histogram of D with a bin size of 1 and the default ; minimum and maximum: PLOT, HISTOGRAM(D) ; Plot a histogram considering only those values from 10 to 50 ; using a bin size of 4: PLOT, HISTOGRAM(D, MIN = 10, MAX = 50, BINSIZE = 4) The HISTOGRAM function can also be used to increment the elements of one vector whose subscripts are contained in another vector. To increment those elements of vector A indicated by vector B, use the command: A = HISTOGRAM(B, INPUT=A, MIN=0, MAX=N_ELEMENTS(A)-1) This method works for duplicate subscripts, whereas the following statement never adds more than 1 to any element, even if that element is duplicated in vector B: A[B] = A[B]+1 For example, for the following commands: A = LONARR(5) B = [2,2,3] PRINT, HISTOGRAM(B, INPUT=A, MIN=0, MAX=4) IDL prints: 0 0 2 1 0 The commands: A = LONARR(5) A[B] = A[B]+1 PRINT, A give the result: 0 0 1 1 0 The following example demonstrates how to use HISTOGRAM: PRO t_histogram data = [[-5, 4, 2, -8, 1], $ [ 3, 0, 5, -5, 1], $ [ 6, -7, 4, -4, -8], $ [-1, -5, -14, 2, 1]] hist = HISTOGRAM(data) bins = FINDGEN(N_ELEMENTS(hist)) + MIN(data) PRINT, MIN(hist) PRINT, bins PLOT, bins, hist, YRANGE = [MIN(hist)-1, MAX(hist)+1], PSYM = 10, $ XTITLE = 'Bin Number', YTITLE = 'Density per Bin' END IDL prints: 0 -14.0000 -13.0000 -12.0000 -11.0000 -10.0000 - 9.00000 -8.00000 -7.00000 -6.00000 -5.00000 -4.00000 - 3.00000 -2.00000 -1.00000 0.00000 1.00000 2.00000 3.00000 4.00000 5.00000 6.00000 See Also H_EQ_CT, H_EQ_INT, HIST_2D, HIST_EQUAL HLS [Previous Routine] [Next Routine] [List of Routines] NAME: HLS The HLS procedure creates a color table based on the HLS (Hue, Lightness, Saturation) color system. Using the input parameters, a spiral through the double-ended HLS cone is traced. Points along the cone are converted from HLS to RGB. The current colortable (and the COLORS common block) contains the new colortable on exit. This routine is written in the IDL language. Its source code can be found in the file hls.pro in the lib subdirectory of the IDL distribution. Syntax HLS, Litlo, Lithi, Satlo, Sathi, Hue, Loops [, Colr] Arguments Litlo Starting lightness, from 0 to 100%. Lithi Ending lightness, from 0 to 100%. Satlo Starting saturation, from 0 to 100%. Sathi Ending saturation, from 0 to 100%. Hue Starting Hue, from 0 to 360 degrees. Red = 0 degs, green = 120, blue = 240. Loops The number of loops through the color spiral. This parameter does not have to be an integer. A negative value causes the loops to traverse the spiral in the opposite direction. Colr An optional (256,3) integer array in which the new R, G, and B values are returned. Red = Colr[*,0], green = Colr[*,1], blue = Colr[*,2]. See Also COLOR_CONVERT, HSV, PSEUDO HOUGH [Previous Routine] [Next Routine] [List of Routines] NAME: HOUGH The HOUGH function implements the Hough transform, used to detect straight lines within a two-dimensional image. This function can be used to return either the Hough transform, which transforms each nonzero point in an image to a sinusoid in the Hough domain, or the Hough backprojection, where each point in the Hough domain is transformed to a straight line in the image. Syntax Hough Transform: Result = HOUGH( Array [, /DOUBLE] [, DRHO=scalar] [, DX=scalar] [, DY=scalar] [, /GRAY] [, NRHO=scalar] [, NTHETA=scalar] [, RHO=variable] [, RMIN=scalar] [, THETA=variable] [, XMIN=scalar] [, YMIN=scalar] ) Hough Backprojection: Result = HOUGH( Array, /BACKPROJECT, RHO=variable, THETA=variable [, /DOUBLE] [, DX=scalar] [, DY=scalar] [, NX=scalar] [, NY=scalar] [, XMIN=scalar] [, YMIN=scalar] ) Return Value The result of this function is a two-dimensional floating-point array, or a complex array if the input image is complex. If Array is double-precision, or if the DOUBLE keyword is set, the result is double-precision, otherwise, the result is single-precision. Hough Transform Theory The Hough transform is defined for a function A(x, y) as: H ( , )= A (x,y) ( ­ xcos ­ ysin ) dx dy ­ ­ where is the Dirac delta-function. With A(x, y), each point (x, y) in the original image, A, is transformed into a sinusoid = xcos ­ ysin , where is the perpendicular distance from the origin of a line at an angle : Figure 8: Hough Transform Points that lie on the same line in the image will produce sinusoids that all cross at a single point in the Hough transform. For the inverse transform, or backprojection, each point in the Hough domain is transformed into a straight line in the image. Usually, the Hough function is used with binary images, in which case H( , ) gives the total number of sinusoids that cross at point ( , ), and hence, the total number of points making up the line in the original image. By choosing a threshold T for H( , ), and using the inverse Hough function, you can filter the original image to keep only lines that contain at least T points. How IDL Implements the Hough Transform Consider an image Amn of dimensions M by N, with array indices m = 0,..., M­1 and n = 0,..., N­1. The discrete formula for the HOUGH function for Amn is: H ( , ) = A mn ( , [ ']) m n where the brackets [ ] indicate rounding to the nearest integer, and ' = (m x + xmin)cos + (n y + ymin)sin The pixels are assumed to have spacing x and y in the x and y directions. The delta-function is defined as: ( [, ']) 1 = [ '] = 0 otherwise How IDL Implements the Hough Backprojection The backprojection, Bmn, contains all of the straight lines given by the ( , ) points given in H( , ). The discrete formula is H ( ,) (n,[am + b]) sin 2 > -- 2 B mn = H ( , ) (m,[a'n + b']) sin 2 2 where the slopes and offsets are given by: ­ x cos ­ y sin a x = ­ ------ cos ------------ min min y sin b = ------------------------------------------------------------ ysin ­ x cos ­ y sin a' 1 = --- min min a b' = ------------------------------------------------------------ xcos Arguments Array The two-dimensional array of size M by N which will be transformed. If the keyword GRAY is not set, then, for the forward transform, Array is treated as a binary image with all nonzero pixels considered as 1. Keywords BACKPROJECT If set, the backprojection is computed, otherwise, the forward transform is computed. When BACKPROJECT is set, Result will be an array of dimension NX by NY. Note The Hough transform is not one-to-one: each point (x, y) is not mapped to a single ( , ). Therefore, instead of the original image, the backprojection, or inverse transform, returns an image containing the set of all lines given by the ( , ) points. DOUBLE Set this keyword to force the computation to be done using double-precision arithmetic. DRHO Set this keyword equal to a scalar specifying the spacing between coordinates, expressed in the same units as Array. The default is 1/SQRT(2) times the diagonal distance between pixels, [(DX2 + DY2 )/2]1/2 . A larger value produces a coarser resolution by mapping multiple pixels onto a single ; this is useful for images that do not contain perfectly straight lines. A smaller value may produce undersampling by trying to map fractional pixels onto , and is not recommended. If BACKPROJECT is specified, this keyword is ignored. DX Set this keyword equal to a scalar specifying the spacing between the horizontal (X) coordinates. The default is 1.0. DY Set this keyword equal to a scalar specifying the spacing between the vertical (Y) coordinates. The default is 1.0. GRAY Set this keyword to perform a weighted Hough transform, with the weighting given by the pixel values. If GRAY is not set, the image is treated as a binary image with all nonzero pixels considered as 1. If BACKPROJECT is specified, this keyword is ignored. NRHO Set this keyword equal to a scalar specifying the number of coordinates to use. The default is 2 CEIL([MAX(X2 + Y2 )]1/2 / DRHO) + 1. If BACKPROJECT is specified, this keyword is ignored. NTHETA Set this keyword equal to a scalar specifying the number of coordinates to use over the interval [0, ]. The default is CEIL( [MAX(X2 + Y2 )]1/2 / DRHO). A larger value will produce smoother results, and is useful for filtering before backprojection. A smaller value will result in broken lines in the transform, and is not recommended. If BACKPROJECT is specified, this keyword is ignored. NX If BACKPROJECT is specified, set this keyword equal to a scalar specifying the number of horizontal coordinates in the output array. The default is FLOOR(2 MAX(|RHO|)(DX2 + DY2 )­1/2 + 1). For the forward transform this keyword is ignored. NY If BACKPROJECT is specified, set this keyword equal to a scalar specifying the number of vertical coordinates in the output array. The default is FLOOR(2 MAX(|RHO|)(DX2 + DY2 )­1/2 + 1). For the forward transform, this keyword is ignored. RHO For the forward transform, set this keyword to a named variable that, on exit, will contain the radial ( ) coordinates. If BACKPROJECT is specified, this keyword must contain the coordinates of the input Array. RMIN Set this keyword equal to a scalar specifying the minimum coordinate to use for the forward transform. The default is ­0.5(NRHO ­ 1) DRHO. If BACKPROJECT is specified, this keyword is ignored. THETA For the forward transform, set this keyword to a named variable containing a vector of angular ( ) coordinates to use for the transform. If NTHETA is specified instead, and THETA is set to a named variable, then on exit THETA will contain the coordinates. If BACKPROJECT is specified, this keyword must contain the coordinates of the input Array. XMIN Set this keyword equal to a scalar specifying the X coordinate of the lower-left corner of the input Array. The default is ­(M­1)/2, where Array is an M by N array. If BACKPROJECT is specified, set this keyword equal to a scalar specifying the X coordinate of the lower-left corner of the Result. In this case the default is ­DX (NX­1)/2. YMIN Set this keyword equal to a scalar specifying the Y coordinate of the lower-left corner of the input Array. The default is ­(N­1)/2, where Array is an M by N array. If BACKPROJECT is specified, set this keyword equal to a scalar specifying the Y coordinate of the lower-left corner of the Result. In this case the default is ­DY (NY­1)/2. Example This example computes the Hough transform of a random set of pixels: PRO hough_example ;Create an image with a random set of pixels seed = 12345 ; remove this line to get different random images array = RANDOMU(seed,128,128) GT 0.95 ;Draw three lines in the image x = FINDGEN(32)*4 array[x,0.5*x+20] = 1b array[x,0.5*x+30] = 1b array[-0.5*x+100,x] = 1b ;Create display window, set graphics properties WINDOW, XSIZE=330,YSIZE=630, TITLE='Hough Example' !P.BACKGROUND = 255 ; white !P.COLOR = 0 ; black !P.FONT=2 ERASE XYOUTS, .1, .94, 'Noise and Lines', /NORMAL ;Display the image. 255b changes black values to white: TVSCL, 255b - array, .1, .72, /NORMAL ;Calculate and display the Hough transform result = HOUGH(array, RHO=rho, THETA=theta) XYOUTS, .1, .66, 'Hough Transform', /NORMAL TVSCL, 255b - result, .1, .36, /NORMAL ;Keep only lines that contain more than 20 points: result = (result - 20) > 0 ;Find the Hough backprojection and display the output backproject = HOUGH(result, /BACKPROJECT, RHO=rho, THETA=theta) XYOUTS, .1, .30, 'Hough Backprojection', /NORMAL TVSCL, 255b - backproject, .1, .08, /NORMAL END The following figure displays the output of this example. The top image shows three lines drawn within a random array of pixels that represent noise. The center image shows the Hough transform, displaying sinusoids for points that lie on the same line in the original image. The bottom image shows the Hough backprojection, after setting the threshold to retain only those lines that contain more than 20 points. The Hough inverse transform, or backprojection, transforms each point in the Hough domain into a straight line in the image. Figure 9: HOUGH example showing random pixels (top), Hough transform (center) and Hough backprojection (bottom) References 1. Gonzalez, R.C., and R.E. Woods. Digital Image Processing. Reading, MA: Addison Wesley, 1992. 2. Jain, Anil K. Fundamentals of Digital Image Processing. Englewood Cliffs, NJ: Prentice-Hall, 1989. 3. Toft, Peter. The Radon Transform: Theory and Implementation. Denmark: Technical University; 1996. Ph.D. Thesis. 4. Weeks, Arthur. R. Fundamentals of Electronic Image Processing. New York: SPIE Optical Engineering Press, 1996. See Also RADON HQR [Previous Routine] [Next Routine] [List of Routines] NAME: HQR The HQR function returns all eigenvalues of an upper Hessenberg array. Using the output produced by the ELMHES function, this function finds all eigenvalues of the original real, nonsymmetric array. The result is an n-element complex vector. HQR is based on the routine hqr described in section 11.6 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press, and is used by permission. Syntax Result = HQR( A [, /COLUMN] [, /DOUBLE] ) Arguments A An n by n upper Hessenberg array. Typically, A would be an array resulting from an application of ELMHES. Keywords COLUMN Set this keyword if the input array A is in column-major format (composed of column vectors) rather than in row-major format (composed of row vectors). DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. Example To compute the eigenvalues of a real, non-symmetric unbalanced array, first define the array A: A = [[ 1.0, 2.0, 0.0, 0.0, 0.0], $ [-2.0, 3.0, 0.0, 0.0, 0.0], $ [ 3.0, 4.0, 50.0, 0.0, 0.0], $ [-4.0, 5.0, -60.0, 7.0, 0.0], $ [-5.0, 6.0, -70.0, 8.0, -9.0]] ; Compute the upper Hessenberg form of the array: hes = ELMHES(A) ; Compute the eigenvalues: evals = HQR(hes) ; Sort the eigenvalues into ascending order based on their ; real components: evals = evals(SORT(FLOAT(evals))) ;Print the result. PRINT, evals IDL prints: ( -9.00000, 0.00000)( 2.00000, -1.73205) ( 2.00000, 1.73205)( 7.00000, 0.00000) ( 50.0000, 0.00000) This is the exact solution vector to five-decimal accuracy. See Also EIGENVEC, ELMHES, TRIQL, TRIRED HSV [Previous Routine] [Next Routine] [List of Routines] NAME: HSV The HSV procedure creates a color table based on the HSV (Hue and Saturation Value) color system. Using the input parameters, a spiral through the single-ended HSV cone is traced. Points along the cone are converted from HLS to RGB. The current colortable (and the COLORS common block) contains the new colortable on exit. This routine is written in the IDL language. Its source code can be found in the file hsv.pro in the lib subdirectory of the IDL distribution. Syntax HSV, Vlo, Vhi, Satlo, Sathi, Hue, Loops [, Colr] Arguments Vlo Starting value, from 0 to 100%. Vhi Ending value, from 0 to 100%. Satlo Starting saturation, from 0 to 100%. Sathi Ending saturation, from 0 to 100%. Hue Starting Hue, from 0 to 360 degrees. Red = 0 degs, green = 120, blue = 240. Loops The number of loops through the color spiral. This parameter does not have to be an integer. A negative value causes the loops to traverse the spiral in the opposite direction. Colr An optional (256,3) integer array in which the new R, G, and B values are returned. Red = Colr[*,0], green = Colr[*,1], blue = Colr[*,2]. See Also COLOR_CONVERT, HLS, PSEUDO IBETA [Previous Routine] [Next Routine] [List of Routines] NAME: IBETA The IBETA function computes the incomplete beta function. x ta ­ 1(1 ­ t)b ­ 1 td I 0 x(a, b) ------------------ 1 ta ­ 1(1 ­ t)b ­ 1 td 0 This routine is written in the IDL language. Its source code can be found in the file ibeta.pro in the lib subdirectory of the IDL distribution. Syntax Result = IBETA( A, B, X [, /DOUBLE] [, EPS=value] [, ITER=variable] [, ITMAX=value] ) Return Value If all arguments are scalar, the function returns a scalar. If all arguments are arrays, the function matches up the corresponding elements of A, B, and X, returning an array with the same dimensions as the smallest array. If one argument is a scalar and the other arguments are arrays, the function uses the scalar value with each element of the arrays, and returns an array with the same dimensions as the smallest input array. If any of the arguments are double-precision or if the DOUBLE keyword is set, the result is double-precision, otherwise the result is single-precision. Arguments A A positive scalar or array that specifies the parametric exponent of the integrand. B A positive scalar or array that specifies the parametric exponent of the integrand. X A scalar or array, in the interval [0, 1], that specifies the upper limit of integration. Keywords DOUBLE Set this keyword to force the computation to be done in double precision. EPS Set this keyword to the desired relative accuracy, or tolerance. The default tolerance is 3.0e-7 for single precision, and 3.0d-12 for double precision. ITER Set this keyword to a named variable that will contain the actual number of iterations performed. ITMAX Set this keyword to specify the maximum number of iterations. The default value is 100. Example Compute the incomplete beta function for the corresponding elements of A, B, and X. ; Define an array of parametric exponents: A = [0.5, 0.5, 1.0, 5.0, 10.0, 20.0] B = [0.5, 0.5, 0.5, 5.0, 5.0, 10.0] ; Define the upper limits of integration: X = [0.01, 0.1, 0.1, 0.5, 1.0, 0.8] ; Compute the incomplete beta functions: result = IBETA(A, B, X) PRINT, result IDL prints: [0.0637686, 0.204833, 0.0513167, 0.500000, 1.00000, 0.950736] See Also BETA, GAMMA, IGAMMA, LNGAMMA IDENTITY [Previous Routine] [Next Routine] [List of Routines] NAME: IDENTITY The IDENTITY function returns an n by n identity array (an array with ones along the main diagonal and zeros elsewhere). This routine is written in the IDL language. Its source code can be found in the file identity.pro in the lib subdirectory of the IDL distribution. Syntax Result = IDENTITY( N [, /DOUBLE] ) Arguments N The desired column and row dimensions. Keywords DOUBLE Set this keyword to return a double-precision identity array. Example ; Define an array, A: A = [[ 2.0, 1.0, 1.0, 1.5], $ [ 4.0, -6.0, 0.0, 0.0], $ [-2.0, 7.0, 2.0, 2.5], $ [ 1.0, 0.5, 0.0, 5.0]] ; Compute the inverse of A using the INVERT function: inverse = INVERT(A) ; Verify the accuracy of the computed inverse using the ; mathematical identity, A x A^-1 - I(4) = 0, where A^-1 is the ; inverse of A, I(4) is the 4 by 4 identity array and 0 is a 4 by 4 ; array of zeros: PRINT, A ## inverse - IDENTITY(4) See Also FINDGEN, FLTARR IDLGR* OBJECT CLASSES [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgr* Object Classes The following IDLgr* object classes are documented in Appendix A, "IDL Object Class & Method Reference": * IDLgrAxis * IDLgrModel * IDLgrROIGroup * IDLgrVRML * IDLgrBuffer * IDLgrMPEG * IDLgrScene * IDLgrWindow * IDLgrClipboard * IDLgrPalette * IDLgrSurface * IDLgrColorbar * IDLgrPattern * IDLgrSymbol * IDLgrContour * IDLgrPlot * IDLgrTessellator * IDLgrFont * IDLgrPolygon * IDLgrText * IDLgrImage * IDLgrPolyline * IDLgrView * IDLgrLegend * IDLgrPrinter * IDLgrViewgroup * IDLgrLight * IDLgrROI * IDLgrVolume IF...THEN...ELSE [Previous Routine] [Next Routine] [List of Routines] NAME: IF...THEN...ELSE The IF...THEN...ELSE statement conditionally executes a statement or block of statements. Note For information on using IF...THEN...ELSE and other IDL program control statements, see Chapter 11, "Program Control" in Building IDL Applications. Syntax IF expression THEN statement [ ELSE statement ] or IF expression THEN BEGIN statements ENDIF [ ELSE BEGIN statements ENDELSE ] Example The following example illustrates the use of the IF statement using the ELSE clause. Notice that the IF statement is ended with ENDIF, and the ELSE statement is ended with ENDELSE. Also notice that the IF statement can be used with or without the BEGIN...END block: A = 2 B = 4 IF (A EQ 2) AND (B EQ 3) THEN BEGIN PRINT, 'A = ', A PRINT, 'B = ', B ENDIF ELSE BEGIN IF A NE 2 THEN PRINT, 'A <> 2' ELSE PRINT, 'B <> 3' ENDELSE IDL Prints: B <> 3 IGAMMA [Previous Routine] [Next Routine] [List of Routines] NAME: IGAMMA The IGAMMA function computes the incomplete gamma function. x e­tta ­ 1 td P 0 x(a) ----------------------------- e­tta ­ 1 td 0 IGAMMA uses either a power series representation or a continued fractions method. If X is less than or equal to A+1, a power series representation is used. If X is greater than A+1, a continued fractions method is used. This routine is written in the IDL language. Its source code can be found in the file igamma.pro in the lib subdirectory of the IDL distribution. Syntax Result = IGAMMA( A, X [, /DOUBLE] [, EPS=value] [, ITER=variable] [, ITMAX=value] [, METHOD=variable] ) Return Value If both arguments are scalar, the function returns a scalar. If both arguments are arrays, the function matches up the corresponding elements of A and X, returning an array with the same dimensions as the smallest array. If one argument is a scalar and the other argument is an array, the function uses the scalar value with each element of the array, and returns an array with the same dimensions as the input array. If any of the arguments are double-precision or if the DOUBLE keyword is set, the result is double-precision, otherwise the result is single-precision. Arguments A A positive scalar or array that specifies the parametric exponent of the integrand. X A scalar or array that specifies the upper limit of integration. Keywords DOUBLE Set this keyword to force the computation to be done in double precision. EPS Set this keyword to the desired relative accuracy, or tolerance. The default tolerance is 3.0e-7 for single precision, and 3.0d-12 for double precision. ITER Set this keyword to a named variable that will contain the actual number of iterations performed. ITMAX Set this keyword to specify the maximum number of iterations. The default value is 100. METHOD Set this keyword to a named variable that will contain the method used to compute the incomplete gamma function. A value of 0 indicates that a power series representation was used. A value of 1 indicates that a continued fractions method was used. Example Compute the incomplete gamma function for the corresponding elements of A and X. ; Define an array of parametric exponents: A = [0.10, 0.50, 1.00, 1.10, 6.00, 26.00] ; Define the upper limits of integration: X = [0.0316228, 0.0707107, 5.00000, 1.04881, 2.44949, 25.4951] ; Compute the incomplete gamma functions: result = IGAMMA(A, X) PRINT, result IDL prints: [0.742026, 0.293128, 0.993262, 0.607646, 0.0387318, 0.486387] See Also BETA, GAMMA, IBETA, LNGAMMA IMAGE_CONT [Previous Routine] [Next Routine] [List of Routines] NAME: IMAGE_CONT The IMAGE_CONT procedure overlays an image with a contour plot. This routine is written in the IDL language. Its source code can be found in the file image_cont.pro in the lib subdirectory of the IDL distribution. Syntax IMAGE_CONT, A [, /ASPECT] [, /INTERP] [, /WINDOW_SCALE] Arguments A The two-dimensional array to display and overlay. Keywords ASPECT Set this keyword to retain the image's aspect ratio. Square pixels are assumed. If WINDOW_SCALE is set, the aspect ratio is automatically retained. INTERP If this keyword is set, bilinear interpolation is used if the image is resized. WINDOW_SCALE Set this keyword to scale the window size to the image size. Otherwise, the image size is scaled to the window size. This keyword is ignored when outputting to devices with scalable pixels (e.g., PostScript). Example ; Create an image to display: A = BYTSCL(DIST(356)) ; Display image and overplot contour lines: IMAGE_CONT, A, /WINDOW See Also CONTOUR, TV IMAGE_STATISTICS [Previous Routine] [Next Routine] [List of Routines] NAME: IMAGE_STATISTICS The IMAGE_STATISTICS procedure computes sample statistics for a given array of values. An optional mask may be specified to restrict computations to a spatial subset of the input data. Syntax IMAGE_STATISTICS, Data [, /LABELED | [, /WEIGHTED] [, WEIGHT_SUM=variable]] [, /VECTOR] [, LUT=array] [, MASK=array] [, COUNT=variable] [, MEAN=variable] [, STDDEV=variable] [, DATA_SUM=variable] [, SUM_OF_SQUARES=variable] [, MINIMUM=variable] [, MAXIMUM=variable] [, VARIANCE=variable] Arguments Data An N-dimensional input data array. Keywords COUNT Set this keyword to a named variable to contain the number of samples that correspond to nonzero values within the mask. DATA_SUM Set this keyword to a named variable to contain the sum of the samples that lie within the mask. LABELED When set, this keyword indicates values in the mask representing region labels, where each pixel of the mask is set to the index of the region in which that pixel belongs (see the LABEL_REGION function in the IDL Reference Guide). If the LABELED keyword is set, each statistic's value is computed for each region index. Thus, a vector containing the results is provided for each statistic with one element per region. By default, this keyword is set to zero, indicating that all samples with a corresponding nonzero mask value are used to form a scalar result for each statistic. Note The LABELED keyword cannot be used with either the WEIGHT_SUM or the WEIGHTED keywords. LUT Set this keyword to a one-dimensional array. For non-floating point input Data, the pixel values are looked up through this table before being used in any of the statistical computations. This allows an integer image array to be calibrated to any user specified intensity range for the sake of calculations. The length of this array must include the range of the input array. This keyword may not be set with floating point input data. When signed input data types are used, they are first cast to the corresponding IDL unsigned type before being used to access this array. For example, the integer value ­1 looks up the value 65535 in the LUT array. MASK An array of N, or N­1 (when the VECTOR keyword is used) dimensions representing the mask array. If the LABELED keyword is set, MASK contains the region indices of each pixel; otherwise statistics are only computed for data values where the MASK array is non-zero. MAXIMUM Set this keyword to a named variable to contain the maximum value of the samples that lie within the mask. MEAN Set this keyword to a named variable to contain the mean of the samples that lie within the mask. MINIMUM Set this keyword to a named variable to contain the minimum value of the samples that lie within the mask. STDDEV Set this keyword to a named variable to contain the standard deviation of the samples that lie within the mask. SUM_OF_SQUARES Set this keyword to a named variable to contain the sum of the squares of the samples that lie within the mask. VARIANCE Set this keyword to a named variable to contain the variance of the samples that lie within the mask. VECTOR Set this keyword to specify that the leading dimension of the input array is not to be considered spatial but consists of multiple data values at each pixel location. In this case, the leading dimension is treated as a vector of samples at the spatial location determined by the remainder of the array dimensions. WEIGHT_SUM Set the WEIGHT_SUM keyword to a named variable to contain the sum of the weights in the mask. Note The WEIGHT_SUM keyword cannot be used if the LABELED keyword is specified. WEIGHTED If the WEIGHTED keyword is set, the values in the MASK array are used to weight individual pixels with respect to their count value. If a MASK array is not provided, all pixels are assigned a weight of 1.0. Note The WEIGHTED keyword cannot be used if the LABELED keyword is specified. IMAGINARY [Previous Routine] [Next Routine] [List of Routines] NAME: IMAGINARY The IMAGINARY function returns the imaginary part of its complex-valued argument. If the complex-valued argument is double-precision, the result will be double-precision, otherwise the result will be single-precision floating-point. Syntax Result = IMAGINARY(Complex_Expression) Arguments Complex_Expression The complex-valued expression for which the imaginary part is desired. Example ; Create an array of complex values: C = COMPLEX([1,2,3],[4,5,6]) ; Print just the imaginary parts of each element in C: PRINT, IMAGINARY(C) IDL prints: 4.00000 5.00000 6.00000 Tip The real part of a complex number can be returned using one of IDL's type conversion functions. For example, FLOAT can be used to return the real part of a complex number in single precision, and DOUBLE can be used to return the real part of a complex number in double precision. See COMPLEX and DCOMPLEX for examples of extracting the real part of a complex number. See Also COMPLEX, DCOMPLEX INDGEN [Previous Routine] [Next Routine] [List of Routines] NAME: INDGEN The INDGEN function returns an integer array with the specified dimensions. Each element of the array is set to the value of its one-dimensional subscript. Syntax Result = INDGEN(D1, ..., D8) [, /BYTE | , /COMPLEX | , /DCOMPLEX | , /DOUBLE | , /FLOAT | , /L64 | , /LONG | , /STRING | , /UINT | , /UL64 | , /ULONG] [, TYPE=value] Arguments Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. The dimensions of the result. The dimension parameters can be any scalar expression. Up to eight dimensions can be specified. If the dimension arguments are not integer values, IDL will convert them to integer values before creating the new array. Keywords BYTE Set this keyword to create a byte array. COMPLEX Set this keyword to create a complex, single-precision, floating-point array. DCOMPLEX Set this keyword to create a complex, double-precision, floating-point array. DOUBLE Set this keyword to create a double-precision, floating-point array. FLOAT Set this keyword to create a single-precision, floating-point array. L64 Set this keyword to create a 64-bit integer array. LONG Set this keyword to create a longword integer array. STRING Set this keyword to create a string array. TYPE The type code to set the type of the result. See the description of the SIZE function for a list of IDL type codes. UINT Set this keyword to create an unsigned integer array. UL64 Set this keyword to create an unsigned 64-bit integer array. ULONG Set this keyword to create an unsigned longword integer array. Example Create I, a 5-element vector of integer values with each element set to the value of its subscript by entering: I = INDGEN(5) See Also BINDGEN, CINDGEN, DCINDGEN, DINDGEN, FINDGEN, LINDGEN, SINDGEN, UINDGEN, UL64INDGEN, ULINDGEN INT_2D [Previous Routine] [Next Routine] [List of Routines] NAME: INT_2D The INT_2D function computes the double integral of a bivariate function using iterated Gaussian quadrature. The algorithm's transformation data is provided in tabulated form with 15 decimal accuracy. This routine is written in the IDL language. Its source code can be found in the file int_2d.pro in the lib subdirectory of the IDL distribution. Syntax Result = INT_2D( Fxy, AB_Limits, PQ_Limits, Pts [, /DOUBLE] [, /ORDER] ) Arguments Fxy A scalar string specifying the name of a user-supplied IDL function that defines the bivariate function to be integrated. The function must accept X and Y and return a scalar result. For example, if we wish to integrate the following function: f(x, y) e x2 ­ y2 ­ = We define a function FXY to express this relationship in the IDL language: FUNCTION fxy, X, Y RETURN, EXP(-X^2. -Y^2.) END AB_Limits A two-element vector containing the lower (A) and upper (B) limits of integration with respect to the variable x. PQ_Limits A scalar string specifying the name of a user-supplied IDL function that defines the lower (P(x)) and upper (Q(x)) limits of integration with respect to the variable y. The function must accept x and return a two-element vector result. For example, we might write the following IDL function to represent the limits of integration with respect to y: FUNCTION PQ_limits, X RETURN, [-SQRT(16.0 - X^2), SQRT(16.0 - X^2)] END Pts The number of transformation points used in the computation. Possible values are: 6, 10, 20, 48, or 96. Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. ORDER A scalar value of either 0 or 1. If set to 0, the integral is computed using a dy-dx order of integration. If set to 1, the integral is computed using a dx-dy order of integration. Example Example 1 Compute the double integral of the bivariate function. x = 2.0 y x2 = I = y cos x5 ( ) y d x d x = 0.0 y = 0.0 ; Define the limits of integration for y as a function of x: FUNCTION PQ_Limits, x RETURN, [0.0, x^2] END ; Define limits of integration for x: AB_Limits = [0.0, 2.0] ; Using the function and limits defined above, integrate with 48 ; and 96 point formulas using a dy-dx order of integration and ; double-precision arithmetic: PRINT, INT_2D('Fxy', AB_Limits, 'PQ_Limits', 48, /DOUBLE) PRINT, INT_2D('Fxy', AB_Limits, 'PQ_Limits', 96, /DOUBLE) INT_2D with 48 transformation points yields: 0.055142668 INT_2D with 96 transformation points yields: 0.055142668 Example 2 Compute the double integral of the bivariate function: ; Define the limits of integration for y as a function of x: FUNCTION PQ_Limits, y x = 2.0 y x2 = I = y cos x5 ( ) x d y d x = 0.0 y = 0.0 RETURN, [sqrt(y), 2.0] END ; Define limits of integration for x: AB_Limits = [0.0, 4.0] ; Using the function and limits defined above, integrate with 48 ; and 96 point formulas using a dy-dx order of integration and ; double-precision arithmetic: PRINT, INT_2D('Fxy', AB_Limits, 'PQ_Limits', 48, /DOUBLE, /ORDER) PRINT, INT_2D('Fxy', AB_Limits, 'PQ_Limits', 96, /DOUBLE, ORDER) INT_2D with 48 transformation points yields: 0.055142678 INT_2D with 96 transformation points yields: 0.055142668 The exact solution (7 decimal accuracy) is: 0.055142668 See Also INT_3D, INT_TABULATED, QROMB, QROMO, QSIMP INT_3D [Previous Routine] [Next Routine] [List of Routines] NAME: INT_3D The INT_3D function computes the triple integral of a trivariate function using iterated Gaussian quadrature. The algorithm's transformation data is provided in tabulated form with 15 decimal accuracy. This routine is written in the IDL language. Its source code can be found in the file int_3d.pro in the lib subdirectory of the IDL distribution. Syntax Result = INT_3D( Fxyz, AB_Limits, PQ_Limits, UV_Limits, Pts [, /DOUBLE] ) Arguments Fxyz A scalar string specifying the name of a user-supplied IDL function that defines the trivariate function to be integrated. The function must accept X, Y, and Z, and return a scalar result. For example, if we wish to integrate the following function: f(x, y, z) = z (x2 y2 z2 + + )3/2 We define a function FXY to express this relationship in the IDL language: FUNCTION fxyz, X, Y, Z RETURN, z*(x^2+y^2+z^2)^1.5 END AB_Limits A two-element vector containing the lower (A) and upper (B) limits of integration with respect to the variable x. PQ_Limits A scalar string specifying the name of a user-supplied IDL function that defines the lower (P(x)) and upper (Q(x)) limits of integration with respect to the variable y. The function must accept x and return a two-element vector result. For example, we might write the following IDL function to represent the limits of integration with respect to y: FUNCTION PQ_limits, X RETURN, [-SQRT(4.0 - X^2), SQRT(4.0 - X^2)] END UV_Limits A scalar string specifying the name of a user-supplied IDL function that defines the lower (U(x,y)) and upper (V(x,y)) limits of integration with respect to the variable z. The function must accept x and y and return a two-element vector result. For example, we might write the following IDL function to represent the limits of integration with respect to z: FUNCTION UV_limits, X, Y RETURN, [0, SQRT(4.0 - X^2 - Y^2)] END Pts The number of transformation points used in the computation. Possible values are: 6, 10, 20, 48, or 96. Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. Example Compute the triple integral of the trivariate function x = 2 I y = 4 x2 ­ z = 4 x2 ­ y2 ­ = z (x2 y2 z2 + + )3/2 z d y d x d x = ­2 y = ­ 4 x2 ­ z = 0 Using the functions and limits defined above, integrate with 10, 20, 48, and 96 point formulas (using double-precision arithmetic): PRINT, INT_3D('Fxyz', [-2.0, 2.0], 'PQ_Limits', 'UV_Limits', 10,$ /D) PRINT, INT_3D('Fxyz', [-2.0, 2.0], 'PQ_Limits', 'UV_Limits', 20,$ /D) PRINT, INT_3D('Fxyz', [-2.0, 2.0], 'PQ_Limits', 'UV_Limits', 48,$ /D) PRINT, INT_3D('Fxyz', [-2.0, 2.0], 'PQ_Limits', 'UV_Limits', 96,$ /D) INT_3D with 10 transformation points yields: 57.444248 INT_3D with 20 transformation points yields: 57.446201 INT_3D with 48 transformation points yields: 57.446265 INT_3D with 96 transformation points yields: 57.446266 The exact solution (6 decimal accuracy) is: 57.446267 See Also INT_2D, INT_TABULATED, QROMB, QROMO, QSIMP INT_TABULATED [Previous Routine] [Next Routine] [List of Routines] NAME: INT_TABULATED The INT_TABULATED function integrates a tabulated set of data { xi , fi } on the closed interval [MIN(x) , MAX(x)], using a five-point Newton-Cotes integration formula. Warning Data that is highly oscillatory requires a sufficient number of samples for an accurate integral approximation. This routine is written in the IDL language. Its source code can be found in the file int_tabulated.pro in the lib subdirectory of the IDL distribution. Syntax Result = INT_TABULATED( X, F [, /DOUBLE] [, /SORT] ) Arguments X The tabulated single- or double-precision floating-point x-value data. Data may be irregularly gridded and in random order. (If the data is randomly ordered, set the SORT keyword.) Warning Each X value must be unique; if duplicate X values are detected, the routine will exit and display a warning message. F The tabulated single- or double-precision floating-point f-value data. Upon input to the function, xi and fi must have corresponding indices for all values of i. If x is reordered, f is also reordered. Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. SORT Set this keyword to sort the tabulated x-value data into ascending order. If SORT is set, both x and f values are sorted. Example Define 11 x-values on the closed interval [0.0 , 0.8]: X = [0.0, .12, .22, .32, .36, .40, .44, .54, .64, .70, .80] Define 11 f-values corresponding to xi: F = [0.200000, 1.30973, 1.30524, 1.74339, 2.07490, 2.45600, $ 2.84299, 3.50730, 3.18194, 2.36302, 0.231964] result = INT_TABULATED(X, F) In this example, the f-values are generated from a known function f = 0.2 + 25x - 200x2 + 675x3 - 900x4 + 400x5 which allows the determination of an exact solution. A comparison of methods yields the following results: * The Multiple Application Trapezoid Method yields: 1.5648 * The Multiple Application Simpson's Method yields: 1.6036 * INT_TABULATED yields: 1.6271 The exact solution (4 decimal accuracy) is: 1.6405 See Also INT_2D, INT_3D, QROMB, QROMO, QSIMP INTARR [Previous Routine] [Next Routine] [List of Routines] NAME: INTARR The INTARR function returns an integer vector or array. Syntax Result = INTARR( D1, ..., D8 [, /NOZERO] ) Arguments Di The dimensions of the result. The dimension parameters can be any scalar expression. Up to eight dimensions can be specified. Keywords NOZERO Normally, INTARR sets every element of the result to zero. If NOZERO is nonzero, this zeroing is not performed and INTARR executes faster. Example Create I, a 3-element by 3-element integer array with each element set to 0 by entering: I = INTARR(3, 3) See Also BYTARR, COMPLEXARR, DBLARR, DCOMPLEXARR, FLTARR, LON64ARR, LONARR, MAKE_ARRAY, STRARR, UINTARR, ULON64ARR, ULONARR INTERPOL [Previous Routine] [Next Routine] [List of Routines] NAME: INTERPOL The INTERPOL function performs linear, quadratic, or spline, interpolation on vectors with a regular or irregular grid. The result is a single- or double-precision floating-point vector, or a complex vector if the input vector is complex. This routine is written in the IDL language. Its source code can be found in the file interpol.pro in the lib subdirectory of the IDL distribution. Syntax For regular grids: Result = INTERPOL( V, N [, /LSQUADRATIC] [, /QUADRATIC] [, /SPLINE] ) For irregular grids: Result = INTERPOL( V, X, U [, /LSQUADRATIC] [, /QUADRATIC] [, /SPLINE] ) Arguments V An input vector of any type except string. N The number of points in the result when both input and output grids are regular. The abscissa values for the output grid will contain the same endpoints as the input. X The abscissa values for V, in the irregularly-gridded case. X must have the same number of elements as V, and the values must be monotonically ascending or descending. U The abscissa values for the result. The result will have the same number of elements as U. U does not need to be monotonic. Keywords LSQUADRATIC If set, interpolate using a least squares quadratic fit to the equation y = a + bx + cx2, for each 4 point neighborhood (x[i-1], x[i], x[i+1], x[i+2]) surrounding the interval of the interpolate, x[i] u < x[i+1]. QUADRATIC If set, interpolate by fitting a quadratic y = a + bx + cx2, to the three point neighborhood (x[i-1], x[i], x[i+1]) surrounding the interval x[i] u < x[i+1]. SPLINE If set, interpolate by fitting a cubic spline to the 4 point neighborhood (x[i-1], x[i], x[i+1], x[i+2]) surrounding the interval, x[i] u < x[i+1]. Note If LSQUADRATIC or QUADRATIC or SPLINE is not set, the default is to use linear interpolation. Example Create a floating-point vector of 61 elements in the range [-3, 3]. X = FINDGEN(61)/10 - 3 ; Evaluate V[x] at each point: V = SIN(X) ; Define X-values where interpolates are desired: U = [-2.50, -2.25, -1.85, -1.55, -1.20, -0.85, -0.50, -0.10, $ 0.30, 0.40, 0.75, 0.85, 1.05, 1.45, 1.85, 2.00, 2.25, 2.75 ] ; Interpolate: result = INTERPOL(V, X, U) ; Plot the function: PLOT, X, V ; Plot the interpolated values: OPLOT, U, result See Also BILINEAR, INTERPOLATE, KRIG2D INTERPOLATE [Previous Routine] [Next Routine] [List of Routines] NAME: INTERPOLATE The INTERPOLATE function returns an array of linear, bilinear or trilinear interpolates, depending on the dimensions of the input array P. Linear interpolates are returned in the one-dimensional case, bilinear in the two-dimensional case and trilinear interpolates in the three-dimensional case. The returned array has the same type as P and its dimensions depend on those of the location parameters X, Y, and Z, as explained below. Interpolates outside the bounds of P can be set to a user-specified value by using the MISSING keyword. Syntax Result = INTERPOLATE( P, X [, Y [, Z]] [, CUBIC=value{-1 to 0}] [, /GRID] [, MISSING=value] ) Arguments P The array of data values. P can be an array of any dimensions. Interpolation occurs in the M rightmost indices of P, where M is the number of interpolation arrays. X, Y, Z Arrays of numeric type containing the locations for which interpolates are desired. For linear interpolation (P is a vector), the result has the same dimensions as X. The i- th element of the result is P interpolated at location Xi. The Y and Z parameters should be omitted. For bilinear interpolation Z should not be present. Note INTERPOLATE considers location points with values between zero and n, where n is the number of values in the input array P, to be valid. Location points outside this range are considered missing data. Location points x in the range n-1 x < n return the last data value in the array P. If the keyword GRID is not set, all location arrays must have the same number of elements. See the description of the GRID keyword below for more details on how interpolates are computed from P and these arrays. Keywords CUBIC Set this keyword to a value between -1 and 0 to use the cubic convolution interpolation method with the specified value as the interpolation parameter. Setting this keyword equal to a value greater than zero specifies a value of -1 for the interpolation parameter. Park and Schowengerdt (see reference below) suggest that a value of -0.5 significantly improves the reconstruction properties of this algorithm. Cubic convolution is an interpolation method that closely approximates the theoretically optimum sinc interpolation function using cubic polynomials. According to sampling theory, details of which are beyond the scope of this document, if the original signal, f, is a band-limited signal, with no frequency component larger than 0, and f is sampled with spacing less than or equal to 1/(2 0), then f can be reconstructed by convolving with a sinc function: sinc(x) = sin( x) / ( x). The number of neighboring points used varies according to the dimension: * 1-dimensional: 4 points * 2-dimensional: 16 points * 3-dimensional: not supported Note Cubic convolution interpolation is significantly slower than bilinear interpolation. Also note that cubic interpolation is not supported for three-dimensional data. For further details see: Rifman, S.S. and McKinnon, D.M., "Evaluation of Digital Correction Techniques for ERTS Images; Final Report", Report 20634-6003-TU-00, TRW Systems, Redondo Beach, CA, July 1974. S. Park and R. Schowengerdt, 1983 "Image Reconstruction by Parametric Cubic Convolution", Computer Vision, Graphics & Image Processing 23, 256. GRID The GRID keyword controls how the location arrays specify where interpolates are desired. This keyword has no effect in the case of linear interpolation. If GRID is not set: The location arrays, X, Y, and, if present, Z must have the same number of elements. The result has the same structure and number of elements as X. In the case of bilinear interpolation, the result is obtained as follows: Let l = Xi and k = Yi . Element i of the result is computed by interpolating between P(l, k), P(l+1, k), P(l, k+1), and P(l+1, k+1). to obtain the estimated value at (Xi, Yi). Trilinear interpolation is a direct extension of the above. If GRID is set: Let Nx be the number of elements in X, let Ny be the number of elements in Y, and Nz be the number of elements in Z. The result has dimensions (Nx, Ny) for bilinear interpolation, and (Nx, Ny, Nz) for trilinear interpolation. For bilinear interpolation, element (i,j) of the result contains the value of P interpolated at position (Xi, Yi). For trilinear interpolation, element (i, j, k) of the result is P interpolated at (Xi, Yi, Zi). MISSING The value to return for elements outside the bounds of P. If this keyword is not specified, interpolated positions that fall outside the bounds of the array P-that is, elements of the X, Y, or Z arguments that are either less than zero or greater than the largest subscript in the corresponding dimension of P-are set equal to the value of the nearest element of P. Examples The example below computes bilinear interpolates with the keyword GRID set: p = FINDGEN(4,4) PRINT, INTERPOLATE(p, [.5, 1.5, 2.5], [.5, 1.5, 2.5], /GRID) and prints the 3 by 3 array: 2.50000 3.50000 4.50000 6.50000 7.50000 8.50000 10.5000 11.5000 12.5000 corresponding to the locations: (.5,.5), (1.5, .5), (2.5, .5), (.5,1.5), (1.5, 1.5), (2.5, 1.5), (.5,2.5), (1.5, 2.5), (2.5, 2.5) Another example computes interpolates, with GRID not set and a parameter outside the bounds of P: PRINT, INTERPOLATE(p, [.5, 1.5, 2.5, 3.1], [.5, 1.5, 2.5, 2]) and prints the result: 2.50000 7.50000 12.5000 11.0000 corresponding to the locations (.5,.5), (1.5, 1.5), (2.5, 2.5) and (3.1, 2.0). Note that the last location is outside the bounds of P and is set from the value of the last column. The following command uses the MISSING keyword to set such values to -1: PRINT, INTERPOLATE(p, [.5, 1.5, 2.5, 3.1], [.5, 1.5, 2.5, 2], $ MISSING = -1) and gives the result: 2.50000 7.50000 12.5000 -1.00000 See Also BILINEAR, INTERPOL, KRIG2D INVERT [Previous Routine] [Next Routine] [List of Routines] NAME: INVERT The INVERT function uses the Gaussian elimination method to compute the inverse of a square array. Errors from singular or near-singular arrays are accumulated in the optional Status argument. Syntax Result = INVERT( Array [, Status] [, /DOUBLE] ) Return Value The result is a single- or double-precision array of floating or complex values. Arguments Array The array to be inverted. Array must have two dimensions of equal size (i.e., a square array) and can be of any type except string. Note that the resulting array will be composed of single- or double-precision floating-point or complex values, depending on whether the DOUBLE keyword is set. Status A named variable to receive the status of the operation. Possible status values are: * 0 = Successful completion. * 1 = Singular array (which indicates that the inversion is invalid). * 2 = Warning that a small pivot element was used and that significant accuracy was probably lost. Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. Example ; Create an array A: A = [[ 5.0, -1.0, 3.0], $ [ 2.0, 0.0, 1.0], $ [ 3.0, 2.0, 1.0]] result = INVERT(A) ; We can check the accuracy of the inversion by multiplying the ; inverted array by the original array. The result should be a 3 x ; 3 identity array. PRINT, result # A IDL prints: 1.00000 0.00000 0.00000 0.00000 1.00000 0.00000 0.00000 9.53674e-07 1.00000 See Also COND, DETERM, INVERT, REVERSE, ROTATE, TRANSPOSE IOCTL [Previous Routine] [Next Routine] [List of Routines] NAME: IOCTL The IOCTL function provides a thin wrapper over the UNIX ioctl(2) system call. IOTCL performs special functions on the specified file. The set of functions actually available depends on your version of UNIX and the type of file (tty, tape, disk file, etc.) referred to. To use IOCTL, read the C programmer's documentation describing the ioctl(2) function for the desired device and convert all constants and data to their IDL equivalents. The value returned by the system ioctl function is returned as the value of the IDL IOCTL function. Syntax Result = IOCTL( File_Unit [, Request, Arg] [, /BY_VALUE] [, /MT_OFFLINE] [, /MT_REWIND] [, MT_SKIP_FILE=[-]number_of_files] [, MT_SKIP_RECORD=[-]number_of_records] [, /MT_WEOF] [, /SUPRESS_ERROR] ) Arguments File_Unit The IDL logical unit number (LUN) for the open file on which the ioctl request is made. Request A longword integer that specifies the ioctl request code. These codes are usually contained in C language header files provided by the operating system, and are not generally portable between UNIX versions. If one of the "MT" keywords is used, this argument can be omitted. Arg A named variable through which data if passed to and from ioctl. IOCTL requests usually request data from the system or supply the system with information. The user must make Arg the correct type and size. Errors in typing or sizing Arg can corrupt the IDL address space and/or make IDL crash. If one of the MT keywords is used, this argument can be omitted. Keywords Note that the keywords below that start with "MT" can be used to issue commonly used magnetic tape ioctl() calls. When these keywords are used, the Request and Arg arguments are ignored and an be omitted. Magnetic tape operations not available via these keywords can still be executed by supplying the appropriate Request and Arg values. When issuing magnetic tape IOCTL calls, be aware that different devices have different rules for which ioctl calls are allowed, and when. The documentation for your computer system explains those rules. BY_VALUE If this keyword is set, Arg is converted to a scalar longword and this longword is passed by value. Normally, Arg is passed to ioctl by reference (i.e., by address). MT_OFFLINE Set this keyword to rewind and unload a tape. MT_REWIND Set this keyword to rewind a tape. MT_SKIP_FILE Use this keyword to skip files on a tape. A positive value skips forward that number of files. A negative value skips backward. MT_SKIP_RECORD Use this keyword to skip records on tape. A positive value skips forward that number of files. A negative value skips backward. MT_WEOF Set this keyword to write an end of file ("tape mark") on the tape at the current location. SUPPRESS_ERROR Set this keyword to log errors quietly and cause a value of -1 to be returned. The default is for IDL to notice any failures associated with the use of ioctl and issue the appropriate IDL error and halt execution. Example The following example prints the size of the terminal being used by the current IDL session. It is known to work under SunOS 4.1.2. Changes may be necessary for other operating systems or even other versions of SunOS. ; Variable to receive result. This structure is described in ; Section 4 of the SunOS manual pages under termios(4): winsize = { row:0, col:0, xpixel:0, ypixel:0 } ; The request code for obtaining the tty size, as determined by ; reading the termios(4) documentation, and reading the system ; include files in the /usr/include/sys directory: TIOCGWINSZ = 1074295912L ; Make the information request. -1 is the IDL logical file unit for ; the standard output: ret = IOCTL(-1, TIOCGWINSZ, winsize) ; Output the results: PRINT,winsize.row, winsize.col, $ format='("TTY has ", I0," rows and ", I0," columns.")' The following points should be noted in this example: * Even though we only want the number of rows and columns, we must include all the fields required by the TIOCGWINSIZ ioctl in the winsize variable (as documented in the termio(4) manual page). Not providing a large enough result buffer would cause IDL's memory to be corrupted. * The value of TIOCGWINSZ was determined by examining the system header files provided in the /usr/include/sys directory. Such values are not always portable between major operating system releases. See Also OPEN ISHFT [Previous Routine] [Next Routine] [List of Routines] NAME: ISHFT The ISHFT function performs the bit shift operation on bytes, integers and longwords. If P2 is positive, P1 is left shifted P2 bit positions with 0 bits filling vacated positions. If P2 is negative, P1 is right shifted with 0 bits filling vacated positions. Syntax Result = ISHFT(P1, P2) Arguments P1 The scalar or array to be shifted. P2 The scalar or array containing the number of bit positions and direction of the shift. Example Bit shift each element of the integer array [1, 2, 3, 4, 5] three bits to the left and store the result in B by entering: B = ISHFT([1,2,3,4,5], 3) The resulting array B is [8, 16, 24, 32, 40]. See Also SHIFT ISOCONTOUR [Previous Routine] [Next Routine] [List of Routines] NAME: ISOCONTOUR The ISOCONTOUR procedure interprets the contouring algorithm found in the IDLgrContour object. The algorithm allows for contouring on arbitrary meshes and returns line or orientated tessellated polygonal output. The interface will also allow secondary data values to be interpolated and returned at the output vertices as well. Syntax ISOCONTOUR, Values, Outverts, Outconn [, AUXDATA_IN=array, AUXDATA_OUT=variable] [, C_VALUE=scalar or vector][, /DOUBLE][, GEOMX=vector] [, GEOMY=vector] [, GEOMZ=vector] [, /FILL] [, LEVEL_VALUES=variable] [, N_LEVELS=levels] [, OUTCONN_INDICES=variable] [, POLYGONS=array of polygon descriptions] Arguments Values An input vector or a two-dimensional array specifying the values to be contoured. Outconn Output variable to contain the connectivity information of the contour geometry in the form: [n0, i(0, 0), i(0, 1)..., i(0, n0­1), n1, i(1, 0), ...]. Outverts Output variable to contain the contour vertices. The vertices are returned in double- precision floating point if the DOUBLE keyword is specified with a non-zero value. Otherwise, the vertices are returned in single-precision floating point. Keywords AUXDATA_IN The auxiliary values to be interpolated at contour vertices. If p is the dimensionality of the auxiliary values, set this argument to a p-by-n array (if the Values argument is a vector of length n), or to a p-by-m-by-n array (if the Values argument is an m-by-n two-dimensional array). AUXDATA_OUT If the AUXDATA_IN keyword was specified, set this keyword to a named output variable to contain the interpolated auxiliary values at the contour vertices. If p is the dimensionality of the auxiliary values, the output is a p-by-n array of values, where n is the number of vertices in Outverts. C_VALUE Set this keyword to a scalar value or a vector of values for which contour levels are to be generated. If this keyword is set to 0, contour levels will be evenly sampled across the range of the Values argument, using the value of the N_LEVELS keyword to determine the number of samples. DOUBLE Set this keyword to use double-precision to compute the contours. IDL converts any data supplied by the Values argument or GEOMX, GEOMY, and GEOMZ keywords to double precision and returns the Outverts argument in double precision. The default behavior is to convert the input to single precision and return the Outverts in single precision. FILL Set this keyword to generate an output connectivity as a set of polygons (Outconn is in the form used by the IDLgrPolygon POLYGONS keyword). The resulting representation is as a set of filled contours. The default is to generate line contours (Outconn is in the form used by the IDLgrPolyline POLYLINES keyword). GEOMX Set this keyword to a vector or two-dimensional array specifying the X coordinates of the geometry with which the contour values correspond. If X is a vector, it must match the number of elements in the Values argument, or it must match the first of the two dimensions of the Values argument (in which case the X coordinates will be repeated for each column of data values). GEOMY Set this keyword to a vector or two-dimensional array specifying the Y coordinates of the geometry with which the contour values correspond. If Y is a vector, it must match the number of elements in the Values argument, or it must match the first of the two dimensions of the Values argument (in which case the Y coordinates will be repeated for each column of data values). GEOMZ Set this keyword to a vector or two-dimensional array specifying the Z coordinates of the geometry with which the contour values correspond. If GEOMZ is a vector or an array, it must match the number of elements in the Values argument. If GEOMZ is not set, the geometry will be derived from the Values argument (if it is set to a two-dimensional array). In this case connectivity is implied. The X and Y coordinates match the row and column indices of the array, and the Z coordinates match the data values. LEVEL_VALUES Set this keyword to a named output variable to receive a vector of values corresponding to the values used to generate the contours. The length of this vector is equal to the number of contour levels generated. This vector is returned in double precision floating point. N_LEVELS Set this keyword to the number of contour levels to generate. This keyword is ignored if the C_VALUE keyword is set to a vector, in which case the number of levels is derived from the number of elements in that vector. Set this keyword to 0 to indicate that IDL should compute a default number of levels based on the range of data values. This is the default. OUTCONN_INDICES Set this keyword to a named output variable to receive an array of beginning and ending indices of connectivity for each contour level. The output array is of the form: [start0, end0, start1, end1, ..., startnc­1, endnc­1], where nc is the number of contour levels. If a level has no contour lines, the start and stop pair is set to 0 and 0 for that level. POLYGONS Set this keyword to an array of polygonal descriptions that represents the connectivity information for the data to be contoured (as specified in the Values argument). A polygonal description is an integer or long array of the form: [n, i0, i1, ..., in­1], where n is the number of vertices that define the polygon, and i0...in­1 are indices into the GEOMX, GEOMY, and GEOMZ keywords that represent the polygonal vertices. To ignore an entry in the POLYGONS array, set the vertex count, n to 0. To end the drawing list, even if additional array space is available, set n to ­1. ISOSURFACE [Previous Routine] [Next Routine] [List of Routines] NAME: ISOSURFACE The ISOSURFACE procedure algorithm expands on the SHADE_VOLUME algorithm. It returns topologically consistent triangles by using oriented tetrahedral decomposition internally. This also allows the algorithm to isosurface any arbitrary tetrahedral mesh. If the user provides an optional auxiliary array, the data in this array is interpolated onto the output vertices and is returned as well. This auxiliary data array is allowed to have more than one value at each vertex. Any size leading dimension is allowed as long as the number of values in the subsequent dimensions matches the number of elements in the input Data array. Syntax ISOSURFACE, Data, Value, Outverts, Outconn [, GEOM_XYZ=array, TETRAHEDRA=array] [, AUXDATA_IN=array, AUXDATA_OUT=variable] Arguments Data Input three-dimensional array of scalars which are to be contoured. Value Input scalar contour value. This value specifies the constant-density surface (also called an iso-surface) to be extracted. Outverts A named variable to contain an output [3, n] array of floating point vertices making up the triangle surfaces. Outconn A named variable to contain an output array of polygonal connectivity values (see IDLgrPolygon, POLYGONS keyword). If no polygons were extracted, this argument returns the array [­1]. Keywords AUXDATA_IN Input array of auxiliary data with trailing dimensions being the number of values in Data. Note If AUXDATA_IN is specified then AUXDATA_OUT must also be specified. AUXDATA_OUT Set this keyword to a named variable that will contain an output array of auxiliary data sampled at the locations in Outverts. Note If AUXDATA_OUT is specified then AUXDATA_IN must also be specified. GEOM_XYZ A [3,n] input array of vertex coordinates (one for each value in the Data array). This array is used to define the spatial location of each scalar. If this keyword is omitted, Data must be a three-dimensional array and the scalar locations are assumed to be on a uniform grid. Note If GEOM_XYZ is specified then TETRAHEDRA must also be specified if either is to be specified. TETRAHEDRA An input array of tetrahedral connectivity values. If this array is not specified, the connectivity is assumed to be a rectilinear grid over the input three-dimensional array. If this keyword is specified, the input data array need not be a three- dimensional array. Each tetrahedron is represented by four values in the connectivity array. Every four values in the array correspond to the vertices of a single tetrahedron. See Also SHADE_VOLUME, XVOLUME JOURNAL [Previous Routine] [Next Routine] [List of Routines] NAME: JOURNAL The JOURNAL procedure provides a record of an interactive session by saving, in a file, all text entered from the terminal in response to the IDL prompt. The first call to JOURNAL starts the logging process. The read-only system variable !JOURNAL is set to the file unit used. To stop saving commands and close the file, call JOURNAL with no parameters. If logging is in effect and JOURNAL is called with a parameter, the parameter is simply written to the journal file. Syntax JOURNAL [, Arg] Arguments Arg A string containing the name of the journal file to be opened or text to be written to an open journal file. If Arg is not supplied, and a journal file is not already open, the file idlsave.pro is used. Once journaling is enabled, a call to JOURNAL with Arg supplied causes Arg to be written into the journal file. Calling JOURNAL without Arg while journaling is in progress closes the journal file and ends the logging process. Example To begin journaling to the file myjournal.pro, enter: JOURNAL, 'myjournal.pro' Any commands entered at the IDL prompt are recorded in the file until IDL is exited or the JOURNAL command is entered without an argument. See Also RESTORE, SAVE JULDAY [Previous Routine] [Next Routine] [List of Routines] NAME: JULDAY The JULDAY function calculates the Julian Day Number (which begins at noon) for the specified date. This is the inverse of the CALDAT procedure. Note The Julian calendar, established by Julius Caesar in the year 45 BCE, was corrected by Pope Gregory XIII in 1582, excising ten days from the calendar. The CALDAT procedure reflects the adjustment for dates after October 4, 1582. See the example below for an illustration. Note A small offset is added to the returned Julian date to eliminate roundoff errors when calculating the day fraction from hours, minutes, seconds. This offset is given by the larger of EPS and EPS*Julian, where Julian is the integer portion of the Julian date, and EPS is the EPS field from MACHAR. For typical Julian dates, this offset is approximately 6x10­10 (which corresponds to 5x10­5 seconds). This offset ensures that if the Julian date is converted back to hour, minute, and second, then the hour, minute, and second will have the same integer values as were originally input. Note Calendar dates must be in the range 1 Jan 4716 B.C.E. to 31 Dec 5000000, which corresponds to Julian values -1095 and 1827933925, respectively. This routine is written in the IDL language. Its source code can be found in the file julday.pro in the lib subdirectory of the IDL distribution. Syntax Result = JULDAY(Month, Day, Year, Hour, Minute, Second) Return Value Result is of type double-precision if Hour, Minute, or Second is specified, otherwise Result is of type long integer. If all arguments are scalar, the function returns a scalar. If all arguments are arrays, the function matches up the corresponding elements of the arrays, returning an array with the same dimensions as the smallest array. If the inputs contain both scalars and arrays, the function uses the scalar value with each element of the arrays, and returns an array with the same dimensions as the smallest input array. Arguments Month Number of the desired month (1 = January, ..., 12 = December). Month can be either a scalar or an array. Day Number of the day of the month (1-31). Day can be either a scalar or an array. Year Number of the desired year (e.g., 1994). Year can be either a scalar or an array. Hour Number of the hour of the day (0-23). Hour can be either a scalar or an array. Minute Number of the minute of the hour (0-59). Minute can be either a scalar or an array. Second Number of the second of the minute (0-59). Second can be either a scalar or an array. Example In 1582, Pope Gregory XIII adjusted the Julian calendar to correct for its inaccuracy of slightly more than 11 minutes per year. As a result, the day following October 4, 1582 was October 15, 1582. JULDAY follows this convention, as illustrated by the following commands: PRINT, JULDAY(10,4,1582), JULDAY(10,5,1582), JULDAY(10,15,1582) IDL prints: 2299160 2299161 2299161 Using arrays, this can also be calculated as follows: PRINT, JULDAY(10, [4, 5, 15], 1582) If you are using JULDAY to calculate an absolute number of days elapsed, be sure to account for the Gregorian adjustment. See Also BIN_DATE, CALDAT, SYSTIME KEYWORD_SET [Previous Routine] [Next Routine] [List of Routines] NAME: KEYWORD_SET The KEYWORD_SET function returns a nonzero value if Expression is defined and nonzero or an array, otherwise zero is returned. This function is especially useful in user-written procedures and functions that process keywords that are interpreted as being either true (keyword is present and nonzero) or false (keyword was not used, or was set to zero). Syntax Result = KEYWORD_SET(Expression) Arguments Expression The expression to be tested. Expression is usually a named variable. Example Suppose that you are writing an IDL procedure that has the following procedure definition line: PRO myproc, KEYW1 = keyw1, KEYW2 = keyw2 The following command could be used to execute a set of commands only if the keyword KEYW1 is set (i.e., it is present and nonzero): IF KEYWORD_SET(keyw1) THEN BEGIN The commands to be executed only if KEYW1 is set would follow. See Also N_ELEMENTS, N_PARAMS KRIG2D [Previous Routine] [Next Routine] [List of Routines] NAME: KRIG2D The KRIG2D function interpolates a regularly- or irregularly-gridded set of points z = f (x, y) using kriging. It returns a two dimensional floating-point array containing the interpolated surface, sampled at the grid points. The parameters of the data model ­ the range, nugget, and sill ­ are highly dependent upon the degree and type of spatial variation of your data, and should be determined statistically. Experimentation, or preferably rigorous analysis, is required. For n data points, a system of n+1 simultaneous equations are solved for the coefficients of the surface. For any interpolation point, the interpolated value is: f(x, y) = w i C(xi, yi, x, y) The following formulas are used to model the variogram functions: d(i,j) = the distance from point i to point j. V = the variance of the samples. C(i,j) = the covariance of sample i with sample j. C(x0,y0,x1,y1) = the covariance of point (x0,y0) with point (x1,y1). Exponential covariance: (­ ) C(d) C1 e 3 d A if d 0 = C1+C0 if d = 0 Spherical covariance: 1.0 ­ (1.5 d A) + (0.5 (d A)3 ) if d < a C(d) = C1 + C0 if d = 0 0 if d > a Note The accuracy of this function is limited by the single-precision floating-point accuracy of the machine. This routine is written in the IDL language. Its source code can be found in the file krig2d.pro in the lib subdirectory of the IDL distribution. Syntax Result = KRIG2D( Z [, X, Y] [, EXPONENTIAL=vector] [, SPHERICAL=vector] [, /REGULAR] [, XGRID=[xstart, xspacing]] [, XVALUES=array] [, YGRID=[ystart, yspacing]] [, YVALUES=array] [, GS=[xspacing, yspacing]] [, BOUNDS=[xmin, ymin, xmax, ymax]] [, NX=value] [, NY=value] ) Arguments Z, X, Y Arrays containing the Z, X, and Y coordinates of the data points on the surface. Points need not be regularly gridded. For regularly gridded input data, X and Y are not used: the grid spacing is specified via the XGRID and YGRID (or XVALUES and YVALUES) keywords, and Z must be a two dimensional array. For irregular grids, all three parameters must be present and have the same number of elements. Keywords Model Parameters: EXPONENTIAL Set this keyword to a two- or three-element vector of model parameters [A,C0, C1] to use an exponential semivariogram model. The model parameters are as follows: * A - The range. At distances beyond A, the semivariogram or covariance remains essentially constant. * C0 - The nugget, which provides a discontinuity at the origin. * C1 - If specified, C1 is the covariance value for a zero distance, and the variance of the random sample z variable. If only a two element vector is supplied, C1 is set to the sample variance. (C0 + C1) = the sill, which is the variogram value for very large distances. SPHERICAL Set this keyword to a two- or three-element vector of model parameters [A,C0, C1] to use a spherical semivariogram model. The model parameters are as follows: * A - The range. At distances beyond A, the semivariogram or covariance remains essentially constant. * C0 - The nugget, which provides a discontinuity at the origin. * C1 - If specified, C1 is the covariance value for a zero distance, and the variance of the random sample z variable. If only a two element vector is supplied, C1 is set to the sample variance. (C0 + C1) = the sill, which is the variogram value for very large distances. Input Grid Description: REGULAR If set, the Z parameter is a two dimensional array of dimensions (n,m), containing measurements over a regular grid. If any of XGRID, YGRID, XVALUES, or YVALUES are specified, REGULAR is implied. REGULAR is also implied if there is only one parameter, Z. If REGULAR is set, and no grid specifications are present, the grid is set to (0, 1, 2, ...). XGRID A two-element array, [xstart, xspacing], defining the input grid in the x direction. Do not specify both XGRID and XVALUES. XVALUES An n-element array defining the x locations of Z[i,j]. Do not specify both XGRID and XVALUES. YGRID A two-element array, [ystart, yspacing], defining the input grid in the y direction. Do not specify both YGRID and YVALUES. YVALUES An n-element array defining the y locations of Z[i,j]. Do not specify both YGRID and YVALUES. Output Grid Description: GS The output grid spacing. If present, GS must be a two-element vector [xs, ys], where xs is the horizontal spacing between grid points and ys is the vertical spacing. The default is based on the extents of x and y. If the grid starts at x value xmin and ends at xmax, then the default horizontal spacing is (xmax - xmin)/(NX-1). ys is computed in the same way. The default grid size, if neither NX or NY are specified, is 26 by 26. BOUNDS If present, BOUNDS must be a four-element array containing the grid limits in x and y of the output grid: [xmin, ymin, xmax, ymax]. If not specified, the grid limits are set to the extent of x and y. NX The output grid size in the x direction. NX need not be specified if the size can be inferred from GS and BOUNDS. The default value is 26. NY The output grid size in the y direction. NY need not be specified if the size can be inferred from GS and BOUNDS. The default value is 26. Examples ; Make a random set of points that lie on a Gaussian: N = 15 X = RANDOMU(seed, N) Y = RANDOMU(seed, N) ; The Gaussian: Z = EXP(-2 * ((X-.5)^2 + (Y-.5)^2)) ; Get a 26 by 26 grid over the rectangle bounding x and y: ; Range is 0.25 and nugget is 0. These numbers are dependent on ; your data model: E = [ 0.25, 0.0] ; Get the surface: R = KRIG2D(Z, X, Y, EXPON = E) Alternatively, get a surface over the unit square, with spacing of 0.05: R = KRIG2D(Z, X, Y, EXPON=E, GS=[0.05, 0.05], BOUNDS=[0,0,1,1]) See Also BILINEAR, INTERPOLATE KURTOSIS [Previous Routine] [Next Routine] [List of Routines] NAME: KURTOSIS The KURTOSIS function computes the statistical kurtosis of an n-element vector. If the variance of the vector is zero, the kurtosis is not defined, and KURTOSIS returns !VALUES.F_NAN as the result. KURTOSIS calls the IDL function MOMENT. Syntax Result = KURTOSIS(X [, /DOUBLE] [, /NAN] ) Arguments X An n-element, floating-point or double-precision vector. Keywords DOUBLE If this keyword is set, computations are performed in double precision arithmetic. NAN Set this keyword to cause the routine to check for occurrences of the IEEE floating- point value NaN in the input data. Elements with the value NaN are treated as missing data. (See "Special Floating-Point Values" in Chapter 17 of Building IDL Applications for more information on IEEE floating-point values.) Example ; Define the n-element vector of sample data: x = [65, 63, 67, 64, 68, 62, 70, 66, 68, 67, 69, 71, 66, 65, 70] ; Compute the kurtosis: result = KURTOSIS(x) ; Print the result: PRINT, result IDL prints -1.18258 See Also MEAN, MEANABSDEV, MOMENT, STDDEV, SKEWNESS, VARIANCE KW_TEST [Previous Routine] [Next Routine] [List of Routines] NAME: KW_TEST The KW_TEST function tests the hypothesis that three or more sample populations have the same mean of distribution against the hypothesis that they differ. The populations may be of equal or unequal lengths. The result is a two-element vector containing the test statistic H and the one-tailed probability of obtaining a value of H or greater from a Chi-square distribution. This test is an extension of the Rank Sum Test implemented in the RS_TEST function. When each sample population contains at least five observations, the H test statistic is approximated very well by a Chi-square distribution with DF degrees of freedom. The hypothesis that three of more sample populations have the same mean of distribution is rejected if two or more populations differ with statistical significance. This type of test is often referred to as the Kruskal-Wallis H-Test. The test statistic H is defined as follows: M ­ 1 R2 H 12 = ----------------------------- i N ------ ­ 3(NT + 1) T(NT + 1) Ni i = 0 where Ni is the number of observations in the ith sample population, NT is the total number of observations in all sample populations, and Ri is the overall rank sum of the ith sample population. This routine is written in the IDL language. Its source code can be found in the file kw_test.pro in the lib subdirectory of the IDL distribution. Syntax Result = KW_TEST( X [, DF=variable] [, MISSING=nonzero_value] ) Arguments X An integer, single-, or double-precision floating-point array of m-columns (with m 3) and n-rows. The columns of this two-dimensional array correspond to the sample populations. If the sample populations are of unequal length, any columns of X that are shorter than the longest column must be "filled in" by appending a user-specified missing data value. This method requires the use of the MISSING keyword. See the Example section below for an example of this case. Keywords DF Use this keyword to specify a named variable that will contain the number of degrees of freedom used to compute the probability of obtaining a value of H or greater from the corresponding Chi-square distribution MISSING Set this keyword equal to a non-zero numeric value that has been appended to some columns of X to make them all a common length of n. Example Test the hypothesis that three sample populations have the same mean of distribution against the hypothesis that they differ at the 0.05 significance level. Assume we have the following sample populations: sp0 = [24.0, 16.7, 22.8, 19.8, 18.9] sp1 = [23.2, 19.8, 18.1, 17.6, 20.2, 17.8] sp2 = [18.2, 19.1, 17.3, 17.3, 19.7, 18.9, 18.8, 19.3] Since the sample populations are of unequal lengths, a missing value must be appended to sp0 and sp1. In this example the missing value is -1.0 and the 3-column, 8-row input array X is defined as: X = [[24.0, 23.2, 18.2], $ [16.7, 19.8, 19.1], $ [22.8, 18.1, 17.3], $ [19.8, 17.6, 17.3], $ [18.9, 20.2, 19.7], $ [-1.0, 17.8, 18.9], $ [-1.0, -1.0, 18.8], $ [-1.0, -1.0, 19.3]] PRINT, KW_TEST(X, MISSING = -1) IDL prints: [1.65862, 0.436351] The computed probability (0.436351) is greater than the 0.05 significance level and therefore we do not reject the hypothesis that the three sample populations sp0, sp1, and sp2 have the same mean of distribution. See Also FV_TEST, RS_TEST, S_TEST, TM_TEST L64INDGEN [Previous Routine] [Next Routine] [List of Routines] NAME: L64INDGEN The L64INDGEN function returns a 64-bit integer array with the specified dimensions. Each element of the array is set to the value of its one-dimensional subscript. Syntax Result = L64INDGEN(D1, ..., D8) Arguments Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. The dimensions of the result. These parameters can be any scalar expression, and up to eight dimensions can be specified. If the dimension arguments are not integer values, IDL converts them to integer values before creating the new array. Example To create L, a 10-element by 10-element 64-bit array where each element is set to the value of its one-dimensional subscript, enter: L = L64INDGEN(10, 10) See Also BINDGEN, CINDGEN, DCINDGEN, DINDGEN, FINDGEN, INDGEN, LINDGEN, SINDGEN, UINDGEN, UL64INDGEN, ULINDGEN LABEL_DATE [Previous Routine] [Next Routine] [List of Routines] NAME: LABEL_DATE The LABEL_DATE function can be used, in conjunction with the [XYZ]TICKFORMAT keyword to IDL plotting routines, to easily label axes with dates and times. This routine is written in the IDL language. Its source code can be found in the file label_date.pro in the lib subdirectory of the IDL distribution. Syntax Result = LABEL_DATE( [DATE_FORMAT=string/string array] [, AM_PM=2-element vector of strings] [, DAYS_OF_WEEK=7-element vector of strings] [, MONTHS=12-element vector of strings] [, OFFSET=value] [, /ROUND_UP] ) and then, PLOT, x, y, XTICKFORMAT = 'LABEL_DATE' Arguments If LABEL_DATE is being called to initialize string formats, it should be called with no arguments and the DATE_FORMAT keyword should be set. Keywords Note The settings for LABEL_DATE remain in effect for all subsequent calls to LABEL_DATE. To restore any default settings, call LABEL_DATE again with the appropriate keyword set to either a null string ('') or to 0, depending uopn the data type of that keyword. AM_PM Set this keyword to a two-element string array that contains the names to be used with '%A'. The default is ['am','pm']. DATE_FORMAT Set this keyword to a format string or array of format strings. Each string corresponds to an axis level as provided by the [XYZ]TICKUNITS keyword to the plotting routine. If there are fewer strings than axis levels, then the strings are cyclically repeated. A string can contain any of the following codes: Code Description %M Month name. %N Month number (2 digits). %D Day of month (2 digits). %Y Year (4 digits, or 5 digits for negative years). %Z Last 2 digits of the year. %W Day of the week. %A AM or PM (%H is then 12-hour instead of 24-hour). %H Hours (2 digits). %I Minutes (2 digits). %S Seconds (2 digits), followed optionally by %n where n is an integer 0-9 representing the number of digits after the decimal point for seconds; the default is no decimal places. %% Represents the % character. Table 10: DATE_FORMAT Codes Other items you can include can consist of: * Any other text characters in the format string. * Any vector font positioning and font change commands. For more information, see "Embedded Formatting Commands" in Appendix H. If DATE_FORMAT is not specified then the default is the standard 24-character system format, '%W %M %D %H:%I:%S %Y'. The following table contains some examples of DATE_FORMAT strings and the resulting output: DATE_FORMAT String Example Result '%D/%N/%Y' 11/12/1993 '%M!C%Y' Dec Note - !C is the code for a 1993 newline character. '%H:%I:%S' 21:33:58 '%H:%I:%S%3' 21:33:58.125 '%W, %M %D, %H %A' Sat, Jan 01, 9 pm '%S seconds' 60 seconds Table 11: DATE_FORMAT Examples DAYS_OF_WEEK Set this keyword to a seven-element string array that contains the names to be used with '%W'. The default is the three-letter English abbreviations, ['Sun, 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat']. MONTHS Set this keyword to a twelve-element string array that contains the names to be used with '%M'. The default is the three-letter English abbreviations, ['Jan', 'Feb',..., 'Dec']. OFFSET Set this keyword to a value representing the offset to be added to each tick value before conversion to a label. This keyword is usually used when your axis values are measured relative to a certain starting time. In this case, OFFSET should be set to the Julian date of the starting time. ROUND_UP Set this keyword to force times to be rounded up to the smallest time unit that is present in the DATE_FORMAT string. The default is for times to be truncated to the smallest time unit. Example This example creates a sample plot that has a date axis from Jan 1 to June 30, 2000: ; Create format strings for a two-level axis: dummy = LABEL_DATE(DATE_FORMAT=['%D-%M','%Y']) ;Generate the Date/Time data time = TIMEGEN(START=JULDAY(1,1,2000), FINAL=JULDAY(6,30,2000)) ;Generate the Y-axis data data = RANDOMN(seed, N_ELEMENTS(time)) ;Plot the data PLOT, time, data, XTICKUNITS = ['Time', 'Time'], $ XTICKFORMAT='LABEL_DATE', XSTYLE=1, XTICKS=6, YMARGIN=[6,2] For more examples, see "[XYZ]TICKFORMAT" on page 2413. See Also CALDAT, JULDAY, SYSTIME, TIMEGEN LABEL_REGION [Previous Routine] [Next Routine] [List of Routines] NAME: LABEL_REGION The LABEL_REGION function consecutively labels all of the regions, or blobs, of a bi-level image with a unique region index. This process is sometimes called "blob coloring". A region is a set of non-zero pixels within a neighborhood around the pixel under examination. The argument for LABEL_REGION is an n-dimensional bi-level integer type array-only zero and non-zero values are considered. The result of the function is an integer array of the same dimensions with each pixel containing its region index. A region index of zero indicates that the original pixel was zero and belongs to no region. Output values range from 0 to the number of regions. Statistics on each of the regions may be easily calculated using the HISTOGRAM function as shown in the examples below. Syntax Result = LABEL_REGION( Data [, /ALL_NEIGHBORS] [, /ULONG] ) Arguments Data A n-dimensional image to be labeled. Data is converted to integer type if necessary. Pixels at the edges of Data are considered to be zero. Keywords ALL_NEIGHBORS Set this keyword to indicate that all adjacent neighbors to a given pixel should be searched. (This is sometimes called 8-neighbor searching when the image is 2- dimensional). The default is to search only the neighbors that are exactly one unit in distance from the current pixel (sometimes called 4-neighbor searching when the image is 2-dimensional). EIGHT This keyword is now obsolete. It has been replaced by the ALL_NEIGHBORS keyword (because this routine now handles N-dimensional data). ULONG Set this keyword to specify that the output array should be an unsigned long integer. Examples Example 1 This example counts the number of distinct regions within an image, and their population. Note that region 0 is the set of zero pixels that are not within a region: image = DIST(40) ; Get blob indices: b = LABEL_REGION(image) ; Get population of each blob: h = HISTOGRAM(b) FOR i=0, N_ELEMENTS(h)-1 DO PRINT, 'Region ',i, $ ', Population = ', h(i) Example 2 This example also prints the average value and standard deviation of each region: image = DIST(40) ; Get blob indices: b = LABEL_REGION(image) ; Get population and members of each blob: h = HISTOGRAM(b, REVERSE_INDICES=r) ; Each region FOR i=0, N_ELEMENTS(h)-1 DO BEGIN ;Find subscripts of members of region i. p = r(r[i]:r[i+1]-1) ; Pixels of region i q = image[p] PRINT, 'Region ', i, $ ', Population = ', h[i], $ ', Standard Deviation = ', STDEV(q, mean), $ ', Mean = ', mean ENDFOR See Also ANNOTATE, DEFROI, HISTOGRAM, SEARCH2D LADFIT [Previous Routine] [Next Routine] [List of Routines] NAME: LADFIT The LADFIT function fits the paired data {xi, yi} to the linear model, y = A + Bx, using a "robust" least absolute deviation method. The result is a two-element vector containing the model parameters, A and B. The figure below displays a two-dimensional distribution that is fitted to the model y = A + Bx, using a minimized Chi-square error criterion (left) and a "robust" least absolute deviation technique (right). The use of the Chi-square error statistic can result in a poor fit due to an undesired sensitivity to outlying data. This routine is written in the IDL language. Its source code can be found in the file ladfit.pro in the lib subdirectory of the IDL distribution. Syntax Result = LADFIT( X, Y [, ABSDEV=variable] [, /DOUBLE] ) Arguments X An n-element integer, single-, or double-precision floating-point vector. Note that the X vector must be sorted into ascending order. Y An n-element integer, single-, or double-precision floating-point vector. Note that the elements of the Y vector must be paired with the appropriate elements of X. Keywords ABSDEV Set this keyword to a named variable that will contain the mean absolute deviation for each data-point in the y-direction. DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. Example ; Define two n-element vectors of paired data: X = [-3.20, 4.49, -1.66, 0.64, -2.43, -0.89, -0.12, 1.41, $ 2.95, 2.18, 3.72, 5.26] Y = [-7.14, -1.30, -4.26, -1.90, -6.19, -3.98, -2.87, -1.66, $ -0.78, -2.61, 0.31, 1.74] ; Sort the X values into ascending order, and sort the Y values to ; match the new order of the elements in X: XX = X(SORT(X)) YY = Y(SORT(X)) ; Compute the model parameters, A and B: PRINT, LADFIT(XX, YY) IDL prints: -3.15301 0.930440 See Also COMFIT, CURVEFIT, LINFIT, SORT LAGUERRE [Previous Routine] [Next Routine] [List of Routines] NAME: LAGUERRE The LAGUERRE function returns the value of the associated Laguerre polynomial Lk( ) . The associated Laguerre polynomials are solutions to the differential n x equation: xy + (k + 1 ­ x)y + ny = 0 with orthogonality constraint: e­xxk +1Lk (n + k)! m( x)Lkn(x)dx = ------------------- 0 n! mn Laguerre polynomials are used in quantum mechanics, for example, where the wave function for the hydrogen atom is given by the Laguerre differential equation. This routine is written in the IDL language. Its source code can be found in the file laguerre.pro in the lib subdirectory of the IDL distribution. This routine is written in the IDL language. Its source code can be found in the file laguerre.pro in the lib subdirectory of the IDL distribution. Syntax Result = LAGUERRE( X, N [, K] [, COEFFICIENTS=variable] [, /DOUBLE] ) Return Value This function returns a scalar or array with the same dimensions as X. If X is double- precision or if the DOUBLE keyword is set, the result is double-precision complex, otherwise the result is single-precision complex. Arguments X The value(s) at which Lk( ) is evaluated. X can be either a scalar or an array. n x N A scalar integer, N 0, specifying the order n of Lk( ) . If N is of type float, it will n x be truncated. K A scalar, K 0, specifying the order k of Lk( ) . If K is not specified, the default n x K = 0 is used and the Laguerre polynomial, Ln(x), is returned. Keywords COEFFICIENTS Set this keyword to a named variable that will contain the polynomial coefficients in the expansion C[0] + C[1]x + C[2]x2 + ... . DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. Example To compute the value of the Laguerre polynomial at the following X values: ;Define the parametric X values: X = [0.0, 0.2, 0.4, 0.6, 0.8, 1.0] ;Compute the Laguerre polynomial of order N=2, K=1: result = LAGUERRE(X, 2, 1) ;Print the result: PRINT, result IDL prints: 3.00000 2.42000 1.88000 1.38000 0.920000 0.500000 This is the exact solution vector to six-decimal accuracy. See Also LEGENDRE, SPHER_HARM LEEFILT [Previous Routine] [Next Routine] [List of Routines] NAME: LEEFILT The LEEFILT function performs the Lee filter algorithm on an image array using a box of size 2N+1. This function can also be used on vectors. The Lee technique smooths additive image noise by generating statistics in a local neighborhood and comparing them to the expected values. This routine is written in the IDL language. It is based upon the algorithm published by Lee (Optical Engineering 25(5), 636-646, May 1986). Its source code can be found in the file leefilt.pro in the lib subdirectory of the IDL distribution. Syntax Result = LEEFILT( A [, N [, Sig]] [, /DOUBLE] [, /EXACT] ) Return Value This function returns an array with the same dimensions as A. If any of the inputs are double-precision or if the DOUBLE keyword is set, the result is double-precision, otherwise the result is single-precision. Arguments A The input image array or one-dimensional vector. N The size of the filter box is 2N+1. The default value is 5. Sig Estimate of the standard deviation. The default is 5. If Sig is negative, IDL interactively prompts for a value of sigma, and displays the resulting image using TVSCL (for arrays) or PLOT (for vectors). To end this cycle, enter a value of 0 (zero) for sigma. Keywords DOUBLE Set this keyword to force the computations to be done in double-precision arithmetic. EXACT Set this keyword to apply a more accurate (but slower) implementation of the Lee filter. See Also DIGITAL_FILTER, MEDIAN, SMOOTH, VOIGT LEGENDRE [Previous Routine] [Next Routine] [List of Routines] NAME: LEGENDRE The LEGENDRE function returns the value of the associated Legendre polynomial P m(x) . The associated Legendre functions are solutions to the differential equation: l (1 x2 ­ )y ­ 2xy + l(l + 1) m2 ­ ------------------- y = 0 (1 x2 ­ ) with orthogonality constraints: +1 Pm(x)Pn(x)dx 2 = -------------- (l + m)! ------------------- l k ­1 2l + 1 (l ­ m)! lk mn The Legendre polynomials are the solutions to the Legendre equation with m = 0. For positive m, the associated Legendre functions can be written in terms of the Legendre polynomials as: m 2 Pm(x) = (­1)m(1 x2 ­ ) dm --------- P ( ) l dxm l x Associated polynomials for negative m are related to positive m by: P­m(x) = (­1)m (l ­ m)! -------------------Pm(x) l (l + m)! l LEGENDRE is based on the routine plgndr described in section 6.8 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press, and is used by permission. Syntax Result = LEGENDRE( X, L [, M] [, /DOUBLE] ) Return Value If all arguments are scalar, the function returns a scalar. If all arguments are arrays, the function matches up the corresponding elements of X, L, and M, returning an array with the same dimensions as the smallest array. If one argument is a scalar and the other arguments are arrays, the function uses the scalar value with each element of the arrays, and returns an array with the same dimensions as the smallest input array. If any of the arguments are double-precision or if the DOUBLE keyword is set, the result is double-precision, otherwise the result is single-precision. Arguments X The expression for which P m( ) is evaluated. Values for X must be in the range ­ l x 1 X 1. L An integer scalar or array, L 0, specifying the order l of P m( ) . If L is of type float, l x it will be truncated. M An integer scalar or array, ­L M L, specifying the order m of P m( ) . If M is not l x specified, then the default M = 0 is used and the Legendre polynomial, Pl(x), is returned. If M is of type float, it will be truncated. Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. Examples Example 1 Compute the value of the Legendre polynomial at the following X values: ; Define the parametric X values: X = [-0.75, -0.5, -0.25, 0.25, 0.5, 0.75] ; Compute the Legendre polynomial of order L=2: result = LEGENDRE(X, 2) ; Print the result: PRINT, result The result of this is: 0.343750 -0.125000 -0.406250 -0.406250 -0.125000 0.343750 Example 2 Compute the value of the associated Legendre polynomial at the same X values: ; Compute the associated Legendre polynomial of order L=2, M=1: result = LEGENDRE(X, 2, 1) ; Print the result: PRINT, result IDL prints: 1.48824 1.29904 0.726184 -0.726184 -1.29904 -1.48824 This is the exact solution vector to six-decimal accuracy. See Also SPHER_HARM, LAGUERRE LINBCG [Previous Routine] [Next Routine] [List of Routines] NAME: LINBCG The LINBCG function is used in conjunction with SPRSIN to solve a set of n sparse linear equations with n unknowns using the iterative biconjugate gradient method. The result is an n-element vector. LINBCG is based on the routine linbcg described in section 2.7 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press, and is used by permission. Note Numerical Recipes recommends using double-precision arithmetic to perform this computation. Syntax Result = LINBCG( A, B, X [, /DOUBLE] [, ITOL={4 | 5 | 6 | 7}] [, TOL=value] [, ITER=variable] [, ITMAX=value] ) Arguments A A row-indexed sparse array created by the SPRSIN function. B An n-element vector containing the right-hand side of the linear system Ax=b. X An n-element vector containing the initial solution of the linear system. Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. ITOL Use this keyword to specify which convergence test should be used. Set ITOL to one of the following: 1. Iteration stops when A x - b / b is less than the value specified by TOL. 2. Iteration stops when -1 (A x - b) / -1 b (where is a "preconditioning" matrix close to A) is less than the value specified by TOL. 3. The routine uses its own estimate of error in x. Iteration stops when the magnitude of the error divided by the magnitude of x is less than the value specified by TOL. This is the default setting. 4. The same as 3, except that the routine uses the largest (in absolute value) component of the error and the largest component of x rather than the vector magnitudes. TOL Use this keyword to specify the desired convergence tolerance. For single-precision calculations, the default value is 1.0 × 10-7. For double-precision values, the default is 1.0 × 10-14. ITER Use this keyword to specify an output variable that will be set to the number of iterations performed. ITMAX The maximum allowed number of iterations. The default is n2. Example ; Begin with an array A: A = [[ 5.0, 0.0, 0.0, 1.0, -2.0], $ [ 3.0, -2.0, 0.0, 1.0, 0.0], $ [ 4.0, -1.0, 0.0, 2.0, 0.0], $ [ 0.0, 3.0, 3.0, 1.0, 0.0], $ [-2.0, 0.0, 0.0, -1.0, 2.0]] ; Define a right-hand side vector B: B = [7.0, 1.0, 3.0, 3.0, -4.0] ; Start with an initial guess at the solution: X = REPLICATE(1.0, N_ELEMENTS(B)) ; Solve the linear system Ax=b: result = LINBCG(SPRSIN(A), B, X) ; Print the result: PRINT, result IDL prints: 1.00000 1.00000 8.94134e-008 -2.37107e-007 -1.00000 The exact solution is [1, 1, 0, 0, -1]. See Also FULSTR, READ_SPR, SPRSAB, SPRSAX, SPRSIN, SPRSTP, WRITE_SPR LINDGEN [Previous Routine] [Next Routine] [List of Routines] NAME: LINDGEN The LINDGEN function returns a longword integer array with the specified dimensions. Each element of the array is set to the value of its one-dimensional subscript. Syntax Result = LINDGEN(D1, ..., D8) Arguments Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. The dimensions of the result. The dimension parameters can be any scalar expression. Up to eight dimensions can be specified. If the dimension arguments are not integer values, IDL will convert them to integer values before creating the new array. Example To create L, a 10-element by 10-element longword array where each element is set to the value of its one-dimensional subscript, enter: L = LINDGEN(10, 10) See Also BINDGEN, CINDGEN, DCINDGEN, DINDGEN, FINDGEN, L64INDGEN, SINDGEN, UINDGEN, UL64INDGEN, ULINDGEN LINFIT [Previous Routine] [Next Routine] [List of Routines] NAME: LINFIT The LINFIT function fits the paired data {xi, yi} to the linear model, y = A + Bx, by minimizing the chi-square error statistic. The result is a two-element vector containing the model parameters [A, B]. This routine is written in the IDL language. Its source code can be found in the file linfit.pro in the lib subdirectory of the IDL distribution. Syntax Result = LINFIT( X, Y [, CHISQ=variable] [, COVAR=variable] [, /DOUBLE] [, MEASURE_ERRORS=vector] [, PROB=variable] [, SIGMA=variable] [, YFIT=variable] ) Arguments X An n-element integer, single-, or double-precision floating-point vector. Y An n-element integer, single-, or double-precision floating-point vector. Keywords CHISQ Set this keyword to a named variable that will contain the value of the chi-square goodness-of-fit. COVAR Set this keyword to a named variable that will contain the Covariance matrix of the coefficients. DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. MEASURE_ERRORS Set this keyword to a vector containing standard measurement errors for each point Y[i]. This vector must be the same length as X and Y. Note For Gaussian errors (e.g., instrumental uncertainties), MEASURE_ERRORS should be set to the standard deviations of each point in Y. For Poisson or statistical weighting, MEASURE_ERRORS should be set to SQRT(ABS(Y)). PROB Set this keyword to a named variable that will contain the probability that the computed fit would have a value of CHISQ or greater. If PROB is greater than 0.1, the model parameters are "believable". If PROB is less than 0.1, the accuracy of the model parameters is questionable. SDEV The SDEV keyword is obsolete and has been replaced by the MEASURE_ERRORS keyword. Code that uses the SDEV keyword will continue to work as before, but new code should use the MEASURE_ERROS keyword. The definition of the MEASURE_ERRORS keyword is identical to that of the SDEV keyword. SIGMA Set this keyword to a named variable that will contain the 1-sigma uncertainty estimates for the returned parameters Note If MEASURE_ERRORS is omitted, then you are assuming that a straight line is the correct model for your data, and therefore, no independent goodness-of-fit test is possible. In this case, the values returned in SIGMA are multiplied by SQRT(CHISQ/(N­M)), where N is the number of points in X, and M is the number of coefficients. See section 15.2 of Numerical Recipes in C (Second Edition) for details. YFIT Set this keyword equal to a named variable that will contain the vector of calculated Y values. Example ; Define two n-element vectors of paired data: X = [-3.20, 4.49, -1.66, 0.64, -2.43, -0.89, -0.12, 1.41, $ 2.95, 2.18, 3.72, 5.26] Y = [-7.14, -1.30, -4.26, -1.90, -6.19, -3.98, -2.87, -1.66, $ -0.78, -2.61, 0.31, 1.74] ; Define an n-element vector of Poisson measurement errors: measure_errors = SQRT(ABS(Y)) ; Compute the model parameters, A and B, and print the result: result = LINFIT(X, Y, MEASURE_ERRORS=measure_errors) PRINT, result IDL prints: -3.16574 0.829856 See Also COMFIT, CURVEFIT, GAUSSFIT, LADFIT, LMFIT, POLY_FIT, REGRESS, SFIT, SVDFIT LINKIMAGE [Previous Routine] [Next Routine] [List of Routines] NAME: LINKIMAGE The LINKIMAGE procedure merges routines written in other languages with IDL at run-time. Each call to LINKIMAGE defines a new system procedure or function by specifying the routine's name, the name of the file containing the code, and the entry point name. The name of your routine is added to IDL's internal system routine table, making it available in the same manner as any other IDL built-in routine. LINKIMAGE can also be used to add graphics device drivers. Warning Using LINKIMAGE requires intimate knowledge of the internals of IDL, and is not for use by the novice user. We recommend use of CALL_EXTERNAL, which has a simpler interface, instead of LINKIMAGE unless your application specifically requires it. To use LINKIMAGE, you should be familiar with the material in the IDL External Development Guide. LINKIMAGE uses the dynamic linking interface supported by the operating system to do its work. Programmers should be familiar with the services supported by their system in order to better understand LINKIMAGE: * Under VMS, the LIB$FIND_IMAGE_SYMBOL run-time library routine is used to activate your sharable image and merge it into the IDL address space, as described in VMS LINKIMAGE and LIB$FIND_IMAGE_SYMBOL, below. * Under UNIX, LINKIMAGE uses the dlopen() interface to the dynamic linker in all cases except for HP-UX (which uses shl_load()) and AIX (which uses load()). * Under Windows, LINKIMAGE uses LoadLibrary() to load a 32-bit, Win32 DLL. * On the PowerPC Macintosh, LINKIMAGE uses the Code Fragment Manager routines GetDiskFragment() and FindSymbol() to load shared libraries. Note Modules must be merged via LINKIMAGE before other procedures and functions that call them are compiled, or the compilation of those routines will fail. Note that because routines merged via LINKIMAGE are considered built-in routines by IDL, declaring the routine with the FORWARD_FUNCTION statement will not eliminate this restriction. Syntax LINKIMAGE, Name, Image [, Type [, Entry]] [, /DEVICE] [, /FUNCT] [, /KEYWORDS] [, MAX_ARGS=value] [, MIN_ARGS=value] VMS Keywords: [, DEFAULT=string] Arguments Name A string containing the IDL name of the function, procedure or device routine which is to be merged. When loading a device driver, Name contains the name of the global (also called "universal" under VMS) DEVICE_DEF structure in the driver. Upon successful loading of the routine, a new procedure or function with the given name will exist, or the new device driver will be loaded. Image A string that holds the name of the file containing the code to be dynamically linked. Under VMS, the full interpretation of this argument is discussed in "VMS LINKIMAGE and LIB$FIND_IMAGE_SYMBOL" on page 691. Under other operating systems, this argument contains the full path specification of the dynamically loaded object file. See your system documentation on sharable libraries or DLLs for details. Type An optional scalar integer parameter that contains 0 (zero) for a procedure, 1 (one) for a function, and 2 for a device driver. The keyword parameters DEVICE and FUNCT can also be used to indicate the type of routine being merged. The default value is 0, for procedure. Entry An optional string that contains the name of the symbol which is the entry point of the procedure or function. With some compilers or operating systems, this name may require the addition of leading or trailing characters. For example, some UNIX C compilers add a leading underscore to the beginning of a function name, and some UNIX FORTRAN compilers add a trailing underscore. If Entry is not supplied, LINKIMAGE will provide a default name by converting the value suppled for Name to lower case and adding any special characters (leading or trailing underscores) typical of the system. Warning Under Microsoft Windows operating systems, only cdecl functions can by used with LINKIMAGE. Attempting to use routines with other calling conventions will yield undefined results, including memory corruption or even IDL crashing. The Windows operating system has two distinct system defined standards that govern how routines pass arguments: stdcall, which is used by much of the operating system as well as languages such as Visual Basic, and cdecl, which is used widely for programming in the C language. These standards differ in how and when arguments are pushed onto the system stack. The standard used by a given function is determined when the function is compiled, and can be controlled by the programmer. LINKIMAGE can only be used with cdecl functions. Unfortunately, there is no way for IDL to know which convention a given function uses, meaning that LINKIMAGE will quietly accept an entry point of the wrong type. The LINKIMAGE user is responsible for ensuring that Entry is a cdecl function. Keywords DEFAULT This keyword is ignored on non-VMS platforms. Under VMS, it is a string containing the default device, directory, file name, and file type information for the file that contains the sharable image. See "VMS LINKIMAGE and LIB$FIND_IMAGE_SYMBOL" on page 691 for additional information. DEVICE Set this keyword to indicate that the module being loaded contains a device driver. FUNCT Set this keyword to indicate that the module being loaded contains a function. KEYWORDS Set this keyword to indicate that the procedure or function being loaded accepts keyword parameters. MAX_ARGS Set this keyword equal to the maximum number of non-keyword arguments the procedure or function accepts. If this keyword is not present, the maximum number of parameters is not checked when the routine is called. Note It is a very good idea to specify a value for MAX_ARGS. Passing the wrong number of arguments to an external routine may cause unexpected results, including causing IDL to crash. By forcing IDL to check the number of arguments before passing them to the linked routine, you will avoid parameter mismatch problems. MIN_ARGS Set this keyword equal to the minimum number of non-keyword arguments accepted by the procedure or function. VMS LINKIMAGE and LIB$FIND_IMAGE_SYMBOL Specifying The Library Name The VMS implementation of LINKIMAGE uses the system runtime library function LIB$FIND_IMAGE_SYMBOL to perform the dynamic linking. This function has a complicated interface in which the name of the library to be linked is given in two separate arguments. We encourage VMS users wishing to use LINKIMAGE to read and fully understand the documentation for LIB$FIND_IMAGE_SYMBOL in order to understand how it is used by IDL. The following discussion assumes that you have a copy of the LIB$FIND_IMAGE_SYMBOL documentation available to consult as you read. LIB$FIND_IMAGE_SYMBOL uses an argument called filename to specify the name of the sharable library or executable to be loaded. Only the actual file name itself is allowed, meaning that none of the file specification punctuation characters (:, [, <, ;, .) are allowed. Filename can also be a logical name, in which case its translated value is the name of the file to be loaded. The translation of such a logical name is allowed to contain additional file specification information. VMS uses this information to find the file to load, using SYS$SHARE as the default location if a location is not specified via a logical name. Alternatively, the user can also supply the optional image-name argument, which is used as a "default filespec" to fill in the parts of the file specification not contained in filename. IDL uses the following rules, in the order listed, to determine how to call LIB$FIND_IMAGE_SYMBOL: 1. If LINKIMAGE is called with both the Image argument and DEFAULT keyword, Image is passed to LIB$FIND_IMAGE_SYMBOL as filename, and DEFAULT is passed as image-name. Both are passed directly to the function without any interpretation. 2. If DEFAULT is not present and Image does not contain a file specification character (:, [, <, ;, .) then it is passed to LIB$CALL_IMAGE_SYMBOL as it's filename argument without any further interpretation. 3. If DEFAULT is not present and Image contains a file specification character, then IDL examines it and locates the filename part. The filename part is passed to LIB$FIND_IMAGE_SYMBOL as filename and the entire string from Image is passed as image-name. This means that although LIB$CALL_IMAGE_SYMBOL has a complicated interface, the LINKIMAGE user can supply a simple file specification for Image and it will be properly loaded by IDL. Full control of LIB$CALL_IMAGE_SYMBOL is still available for those who require it. Linking To The IDL Executable LINKIMAGE routines invariably need to call functions supplied by the IDL program. In order to do this, you must link your sharable library with IDL. This requires you to supply the linker with the path (file specification) of the IDL program. The VMS linker in turn includes the path you specify in the resulting library. This can be inconvenient because a library linked this way can only run with the exact IDL executable that it was linked with. This means that you cannot move your IDL installation or keep multiple installations for use with your library. The standard VMS solution to this problem is to use a logical name instead of an actual path. For example, IDL users frequently use the logical name IDL_EXE to point at their IDL executable. To make this process easier and less trouble prone, IDL defines this logical name in the users process logical table when it starts running. Therefore, you can always link with the IDL_EXE logical and know that it will refer to the IDL executable you are actually running when the LINKIMAGE call is made. Example To add a procedure called MY_PROC, whose entry symbol is also named MY_PROC, and whose file is pointed to by the logical name MY_PROC_EXE: LINKIMAGE, 'MY_PROC', 'MY_PROC_EXE' Under VMS, to add a device driver contained in the file DRA0:[SMITH]XXDRIV.EXE: LINKIMAGE, 'XX_DEV', 'XXDRIV', $ /DEVICE, DEFAULT='DRA0:[SMITH].EXE' The global symbol XX_DEV, which contains the device definition structure, must be defined as universal within the sharable image. See Also CALL_EXTERNAL, SPAWN LIVE_Tools [Previous Routine] [Next Routine] [List of Routines] NAME: LIVE_Tools The LIVE tools allow you to create, modify, and export visualizations directly from the IDL command line. In many cases, you can modify your visualizations using the LIVE tools' graphical user interface directly without ever needing to return the IDL command line. In some cases, however, you may wish to alter your visualizations programmatically rather than using the graphical user interface. Several LIVE routines allow you to do this easily. The process of using the LIVE tools begins with the creation of a LIVE window via one of the four main LIVE routines: LIVE_CONTOUR, LIVE_IMAGE, LIVE_PLOT, and LIVE_SURFACE. When you use one of these four routines at the IDL command line, you specify some data to be visualized and a LIVE window appears. You can modify many of the properties of the items in your visualization by double-clicking on the item to call up a Properties dialog. If you find that the graphical user interface does not allow you to perform the operation you wish to perform - saving your visualization as an image file, say - you can use the auxiliary LIVE routines. These routines can be divided into two groups: * Overplotting and Annotation Routines that allow you to add annotations to an existing LIVE window. These routines include LIVE_LINE, LIVE_OPLOT, LIVE_RECT, and LIVE_TEXT. (Lines, rectangles, and text can also be added to LIVE windows using the graphical user interface.) * Information and Control Routines that allow you to get information about an existing LIVE window, alter its properties, or export visualizations. These routines include LIVE_CONTROL, LIVE_DESTROY, LIVE_EXPORT, LIVE_INFO, LIVE_PRINT, and LIVE_STYLE. To use the auxiliary routines, you will need to know the Name of the LIVE window or item you wish to alter. To create an IDL variable containing the names of the elements of a LIVE window, set the REFERENCE_OUT keyword equal to a named variable when you first create your LIVE window. The returned variable will be a structure that contains the names of all of the elements in the visualization you have created. Use the contents of this structure to determine the value of the Name argument for the auxiliary LIVE tools, or to determine the name of the LIVE window you wish to alter. Note The LIVE tools do not utilize the !X, !Y, and !Z conventions. Setting these system variables will have no effect on LIVE tool display. LIVE_CONTOUR [Previous Routine] [Next Routine] [List of Routines] NAME: LIVE_CONTOUR The LIVE_CONTOUR procedure displays contour visualizations in an interactive environment. Because the interactive environment requires extra system resources, this routine is most suitable for relatively small data sets. If you find that performance does not meet your expectations, consider using the Direct Graphics CONTOUR routine or the Object Graphics IDLgrContour class directly. After LIVE_CONTOUR has been executed, you can double-click on a contour line to display a properties dialog. A set of buttons in the upper left corner of the window allows you to print, undo the last operation, redo the last "undone" operation, copy, draw a line, draw a rectangle, or add text. Print Undo Redo Copy Line Rectangle Text Figure 12: LIVE_CONTOUR Properties Dialog You can control your LIVE window after it is created using any of several auxiliary routines. See "LIVE_Tools" on page 694 for an explanation. Syntax LIVE_CONTOUR [, Z1,..., Z25] [, /BUFFER] [, DIMENSIONS=[width, height]{normal units}] [, /DOUBLE] [, DRAW_DIMENSIONS=[width, height]{devive units}] [, ERROR=variable] [, /INDEXED_COLOR] [, INSTANCING={-1 | 0 | 1}] [, LOCATION=[x, y]{normal units}] [, /MANAGE_STYLE] [, NAME=structure] [, /NO_DRAW] [, /NO_SELECTION] [, /NO_STATUS] [, /NO_TOOLBAR] [, PARENT_BASE=widget_id | , TLB_LOCATION=[Xoffset, Yoffset]{device units}] [, PREFERENCE_FILE=filename{full path}] [, REFERENCE_OUT=variable] [, RENDERER={0 | 1}] [, REPLACE={structure | {0 | 1 | 2 | 3 | 4}}] [, STYLE=name_or_reference] [, TEMPLATE_FILE=filename] [, TITLE=string] [, WINDOW_IN=string] [, {X | Y}INDEPENDENT=value] [, {/X | /Y}LOG] [, {X | Y}RANGE=[min, max]{data units}] [, {X | Y}_TICKNAME=array] Arguments Zn A vector of data. Up to 25 of these arguments may be specified. If any of the data is stored in IDL variables of type DOUBLE, LIVE_CONTOUR uses double-precision to store the data and to draw the result. Keywords BUFFER Set this keyword to bypass the creation of a LIVE window and send the visualization to an offscreen buffer. The WINDOW field of the reference structure returned by the REFERENCE_OUT keyword will contain the name of the buffer. DOUBLE Set this keyword to force LIVE_CONTOUR to use double-precision to draw the result. This has the same effect as specifying data in the Zn argument using IDL variables of type DOUBLE. DIMENSIONS Set this keyword to a two-element, floating-point vector of the form [width, height] specifying the dimensions of the visualization in normalized coordinates. The default is [1.0, 1.0]. DRAW_DIMENSIONS Set this keyword equal to a vector of the form [width, height] representing the desired size of the LIVE tools draw widget (in pixels). The default is [452, 452]. ERROR Set this keyword to a named variable to contain the returned error message (string). An empty string is returned if no errors occurred during the operation. By default, errors are reported via a GUI. Note If a named variable is passed in this keyword and an error occurs, the error GUI will not be displayed. INDEXED_COLOR If set, the indexed color mode will be used. The default is TrueColor. INSTANCING Set this keyword to 1 to instance drawing on, or 0 to turn it off. The default (-1) is to use instancing if and only if the "software renderer" is being used (see RENDERER). For more information, see "Instancing" in the Objects and Object Graphics manual. LOCATION Set this keyword to a two-element, floating-point vector of the form [X, Y] specifying the location of the visualization (relative to the lower left hand corner within the visualization window) in normalized coordinates. The default is [0.0, 0.0]. Note LOCATION may be adjusted to take into account window decorations. MANAGE_STYLE Set this keyword to have the passed in style item destroyed when the LIVE tool window is destroyed. This keyword has no effect if the STYLE keyword is not set to a style item. NAME Set this keyword to a structure containing suggested names for the data items to be created for this visualization. See the REPLACE keyword for details on how they will be used. The fields of the structure are as follows. (Any or all tags may be set.) Tag Description DATA Dependent Data Name(s) IX Independent X Data Name IY Independent Y Data Name Table 24: Fields of the NAME keyword The default for a field is to use the given variable name. If the variable does not have a name (i.e., is an expression), a default name is automatically generated. The dependent data names will be used in a round-robin fashion if more data than names are input. NO_DRAW Set this keyword to inhibit the visualization window from drawing results of LIVE_CONTOUR. This is useful if multiple visualizations and/or annotations are being created via calls to other LIVE_Tools in order to reduce unwanted draws and help speed the display. NO_STATUS Set this keyword to prevent the creation of the status bar. NO_TOOLBAR Set this keyword to prevent the creation of the toolbar. PARENT_BASE Set this keyword to the widget ID of an existing base widget to bypass the creation of a LIVE window and create the visualization within the specified base widget. Note The location of the draw widget is not settable. It is expected that the user who wishes to insert a tool into their own widget application will determine the setting from the parent base sent to the tool. Note LIVE_DESTROY on a window is recommended when using PARENT_BASE so that proper memory cleanup is done. Simply destroying the parent base is not sufficient. Note When specifying a PARENT_BASE, that parent base must be running in a non- blocking mode. Putting a LIVE tool into a realized base already controlled by XMANAGER will override the XMANAGER mode to /NO_BLOCK even if blocking had been in effect. REFERENCE_OUT Set this keyword to a variable to return a structure defining the names of the created items. The fields of the structure are shown in the following table. Tag Description WIN Window Name VIS Visualization Name XAXIS X-Axis Name YAXIS Y-Axis Name GRAPHIC Graphic Name(s) LEGEND Legend Name DATA Dependent Data Name(s) IX Independent X Data Name IY Independent Y Data Name Table 25: Fields of the LIVE_CONTOUR Reference Structure Note You can also determine the name of an item by opening its properties dialog and checking the "Name" field (or for Windows, by clicking the title bar). RENDERER Set this keyword to 1 to use the "software renderer", or 0 to use the "hardware renderer". The default (-1) is to use the setting in the IDE (IDL Development Environment) preferences; if the IDE is not running, however, the default is hardware rendering. For more information, see "Hardware vs. Software Rendering" in the Objects and Object Graphics manual. REPLACE Set this keyword to a structure containing tags as listed for the NAME keyword, with scalar values corresponding to the replacement options listed below. (Any or all of the tags may be set.) The replacement settings are used to determine what action to take when an item (such as data) being input would have the same name as one already existing in the given window or buffer (WINDOW_IN). Alternatively, this keyword may be set to a single scalar value, which is equivalent to setting each tag of the structure to that choice. Setting Action Taken 0 New items will be given unique names. 1 Existing items will be replaced by new items (i.e., the old items will be deleted and new ones created). 2 User will be prompted for the action to take. 3 The values of existing items will be replaced. This will cause dynamic updating to occur for any current uses, e.g., a visualization would redraw to show the new value. 4 Default. Option 0 will be used for items that do not have names (e.g., data input as an expression rather than a named variable, with no name provided via the NAME keyword). Option 3 will be used for all named items. Table 26: REPLACE keyword Settings and Action Taken STYLE Set this keyword to either a string specifying a style name created using LIVE_STYLE. TITLE Set this keyword to a string specifying the title to give the main window. It must not already be in use. A default will be chosen if no title is specified. TLB_LOCATION Set this keyword to a two-element vector of the form [Xoffset, Yoffset] specifying the offset (in pixels) of the LIVE window from the upper left corner of the screen. This keyword has no effect if the PARENT_BASE keyword is set. The default is [0, 0]. WINDOW_IN Set this keyword equal to a name (string, case-sensitive) of a LIVE tool window or a LIVE tool buffer, in which to display the visualization. The WIN tag of the REFERENCE_OUT structure from the creation of the LIVE tool will provide the window or buffer name. Window names are also visible in visualization window titlebars. The default is to create a new window. XINDEPENDENT Set this keyword to a vector specifying the X values for LIVE_CONTOUR. The default is the data's index values. Note Only one independent vector is allowed; all dependent vectors will use the independent vector. YINDEPENDENT Set this keyword to a vector specifying the Y values for LIVE_CONTOUR. The default is the data's index values. Note Only one independent vector is allowed; all dependent vectors will use the independent vector. XLOG Set this keyword to make the X axis a log axis. The default is 0 (linear axis). YLOG Set this keyword to make the Y axis a log axis. The default is 0 (linear axis). XRANGE Set this keyword equal to a two-element array that defines the minimum and maximum values of the X axis range. The default equals the values computed from the data range. YRANGE Set this keyword equal to a two-element array that defines the minimum and maximum values of the Y axis range. The default equals the values computed from the data range. X_TICKNAME Set this keyword equal to an array of strings to be used to label the tick mark for the X axis. The default equals the values computed from the data range. Y_TICKNAME Set this keyword equal to an array of strings to be used to label the tick mark for the Yaxis. The default equals the values computed from the data range. Example ; Create a dataset to display: Z=DIST(10) ; Display the contour. To manipulate contour lines, click on the ; plot to access a graphical user interface. LIVE_CONTOUR, Z Note This is a "Live" situation. When data of the same name is used multiple times within the same window, it always represents the same internal data item. For example, if one does the following: Y=indgen(10) LIVE_PLOT, Y, WINDOW_IN=w, DIMENSIONS=d, LOCATION=loc1 Y=indgen(20) LIVE_PLOT, Y, WINDOW_IN=w, DIMENSIONS=d, LOCATION=loc2 The first plot will update to use the Y of the second plot when the second plot is drawn. If the user wants to display 2 "tweaks" of the same data, a different variable name must be used each time, or at least one should be an expression (thus not a named variable). For example: LIVE_PLOT, Y1,... LIVE_PLOT, Y2,... or; LIVE_PLOT, Y,... LIVE_PLOT, myFunc(Y),... In last example, the data of the second visualization will be given a default unique name since an expression rather than a named variable is input. Note The above shows the default behavior for naming and replacing data, which can be overridden using the NAME and REPLACE keywords. See Also CONTOUR LIVE_CONTROL [Previous Routine] [Next Routine] [List of Routines] NAME: LIVE_CONTROL The LIVE_CONTROL procedure allows you to set the properties of (or elements within) a visualization in a LIVE tool from the IDL command line. See "LIVE_Tools" on page 694 for additional discussion of the routines that control the LIVE_ tools. Note The LIVE tools do not utilize the !X, !Y, and !Z conventions. Setting these system variables will have no effect on LIVE tool display. Syntax LIVE_CONTROL, [Name] [, /DIALOG] [, ERROR=variable] [, /NO_DRAW] [, PROPERTIES=structure] [, /SELECT] [, /UPDATE_DATA] [, WINDOW_IN=string] Arguments Name If keywords DIALOG and/or PROPERTIES are used, Name is a string (case- insensitive) containing the name of a window visualization or graphic to operate on. WINDOW_IN will default to the window or buffer, if only one is present in the IDL session. If keyword UPDATE_DATA is used, Name must be an IDL variable with the same name as one already used in the given window or buffer (WINDOW_IN). In this case there is no default. If UPDATE_DATA is not set, the parameter must be a name of a window, visualization or visualization element. Keywords DIALOG Set this keyword to have the editable properties dialog of the visualization or graphic appear. ERROR Set this keyword to a named variable to contain the returned error message (string). An empty string is returned if no errors occurred during the operation. By default, errors are reported via a GUI. Note If a named variable is passed in this keyword and an error occurs, the error GUI will not be displayed. NO_DRAW Set this keyword to inhibit the visualization window from drawing. This is useful if multiple visualizations and/or annotations are being created via calls to other LIVE_Tools in order to reduce unwanted draws and help speed the display. PROPERTIES Set this keyword to a properties structure with which to modify the given visualization or graphic. The structure should contain one or more tags as returned from a LIVE_INFO call on the same type of item. UPDATE_DATA Set this keyword to force the window to update all of its visualizations that contain the given data passed in the parameter to LIVE_CONTROL. WINDOW_IN Set this keyword equal to a name (string, case-sensitive) of a LIVE tool window or a LIVE tool buffer. The WIN tag of the REFERENCE_OUT structure from the creation of the LIVE tool will provide the window or buffer name. Window names are also visible in visualization window titlebars. If only one LIVE tool window (or buffer) is present in the IDL session, this keyword will default to it. Example ; Create a dataset to display: X=indgen(10) ; Plot the dataset: LIVE_PLOT, X ; Modify the dataset: X=X+2 ; Replace old values of X: LIVE_CONTROL, X, /UPDATE_DATA See Also LIVE_INFO, LIVE_STYLE LIVE_DESTROY [Previous Routine] [Next Routine] [List of Routines] NAME: LIVE_DESTROY The LIVE_DESTROY procedure allows you to destroy a window visualization or an element in a visualization. Syntax LIVE_DESTROY, [Name1,..., Name25] [, /ENVIRONMENT] [, ERROR=variable] [, /NO_DRAW] [, /PURGE] [, WINDOW_IN=string] Arguments Name A string containing the name of a valid LIVE visualization or element. If a visualization is supplied, all components in the visualization will be destroyed. Up to 25 components may be specified in a single call. If not specified, the entire window or buffer (WINDOW_IN) and its contents will be destroyed. Warning Using WIDGET_CONTROL to destroy the parent base of a LIVE tool before using LIVE_DESTROY to clean up will leave hanging object references. Keywords ENVIRONMENT Destroys the LIVE_ Tools environment (background processes). ERROR Set this keyword to a named variable to contain the returned error message (string). An empty string is returned if no errors occurred during the operation. By default, errors are reported via a GUI. Note If a named variable is passed in this keyword and an error occurs, the error GUI will not be displayed. NO_DRAW Set this keyword to inhibit the visualization window from drawing. This is useful if multiple visualizations and/or annotations are being created via calls to other LIVE_Tools in order to reduce unwanted draws and help speed the display. PURGE Destroys LIVE_ Tools (use this keyword for cleaning up the system after fatal errors in LIVE_ Tools). This keyword may cause the loss of data if not used correctly. WINDOW_IN Set this keyword equal to a name (string, case-sensitive) of a LIVE tool window or a LIVE tool buffer. The WIN tag of the REFERENCE_OUT structure from the creation of the LIVE tool will provide the window or buffer name. Window names are also visible in visualization window titlebars. If only one LIVE tool window (or buffer) is present in the IDL session, this keyword will default to it. Example LIVE_DESTROY, 'Line Plot Visualization' ; Destroy window (if only one window present): LIVE_DESTROY LIVE_EXPORT [Previous Routine] [Next Routine] [List of Routines] NAME: LIVE_EXPORT The LIVE_EXPORT procedure allows the user to export a given visualization or window to an image file. Syntax LIVE_EXPORT [, /APPEND] [, COMPRESSION={0 | 1 | 2}{TIFF only}] [, /DIALOG] [, DIMENSIONS=[width, height]] [, ERROR=variable] [, FILENAME=string] [, ORDER={0 | 1}{JPEG or TIFF}] [, /PROGRESSIVE{JPEG only}] [, QUALITY={0 | 1 | 2}{for VRML} | {0 to 100}{for JPEG}] [, RESOLUTION=value] [, TYPE={'BMP' | 'JPG' | 'PIC' | 'SRF' | 'TIF' | 'XWD' | 'VRML'}] [, UNITS={0 | 1 | 2}] [, VISUALIZATION_IN=string] [, WINDOW_IN=string] Arguments None Keywords APPEND Specifies that the image should be added to the existing file, creating a multi-image TIFF file. COMPRESSION (TIFF) Set this keyword to select the type of compression to be used: * 0 = none (default) * 2 = PackBits. DIALOG Set this keyword to have a dialog appear allowing the user to choose the image type and specifications. DIMENSIONS Set this keyword to a two-element vector of the form [width, height] to specify the dimensions of the image in units specified by the UNITS keyword. The default is [640, 480] pixels. ERROR Set this keyword to a named variable to contain the returned error message (string). An empty string is returned if no errors occurred during the operation. By default, errors are reported via a GUI. Note If a named variable is passed in this keyword and an error occurs, the error GUI will not be displayed. FILENAME Set this keyword equal to a string specifying the desired name of the image file. The default is live_export.extension, where extension is one of the following: bmp, jpg, jpeg, pic, pict, srf, tif, tiff, xwd, vrml ORDER (JPEG, TIFF) Set this keyword to have the image written from top to bottom. Default is bottom to top. PROGRESSIVE (JPEG) Set this keyword to write the image as a series of scans of increasing quality. When used with a slow communications link, a decoder can generate a low-quality image very quickly, and then improve its quality as more scans are received. QUALITY (JPEG, VRML) This keyword specifies the quality index of VRML images and JPEG images. For VRML, the values are 0=Low, 1=Medium, 2=High. For JPEG the range is 0 ("terrible") to 100 ("excellent"). This keyword has no effect on non-JPEG or non- VRML images. RESOLUTION Set this keyword to a floating-point value specifying the device resolution in centimeters per pixel. The default is 72 DPI=2.54 (cm/in)/ 0.0352778 (cm/pixel). Note It is important to match the eventual output device's resolution so that text is scaled properly. TYPE Set this keyword equal to a string specifying the image type to write. Valid strings are: `BMP', `JPG', `JPEG' (default), `PIC', `PICT', `SRF', `TIF', `TIFF', `XWD', and `VRML'. UNITS Set this keyword to indicate the units of measure for the DIMENSIONS keyword. Valid values are 0=Device (default), 1=Inches, 2=Centimeters. VISUALIZATION_IN Set this keyword equal to the name (string, case-insensitive) of a LIVE tool visualization to export. The VIS field from the REFERENCE_OUT keyword from the creation of the LIVE tool will provide the visualization name. If VISUALIZATION_IN is not specified, the whole window or buffer (WINDOW_IN) will be exported. WINDOW_IN Set this keyword equal to a name (string, case-sensitive) of a LIVE tool window or a LIVE tool buffer, to export. The WIN tag of the REFERENCE_OUT structure from the creation of the LIVE tool will provide the window or buffer name. Window names are also visible in visualization window titlebars. If only one LIVE tool window (or buffer) is present in the IDL session, this keyword will default to it. Example LIVE_EXPORT, WINDOW_IN='Live Plot 2' LIVE_IMAGE [Previous Routine] [Next Routine] [List of Routines] NAME: LIVE_IMAGE The LIVE_IMAGE procedure displays visualizations in an interactive environment. Double-click on the image to display a properties dialog. A set of buttons in the upper left corner of the image window allows you to print, undo the last operation, redo the last "undone" operation, copy, draw a line, draw a rectangle, or add text. Print Undo Redo Copy Line Rectangle Text Figure 13: LIVE_IMAGE Properties Dialog You can control your LIVE window after it is created using any of several auxiliary routines. See "LIVE_Tools" on page 694 for an explanation. Syntax LIVE_IMAGE, Image [, RED=byte_vector] [, GREEN=byte_vector] [, BLUE=byte_vector] [, /BUFFER] [, DIMENSIONS=[width, height]{normal units}] [, DRAW_DIMENSIONS=[width, height]{devive units}] [, ERROR=variable] [, /INDEXED_COLOR] [, INSTANCING={-1 | 0 | 1}] [, LOCATION=[x, y]{normal units}] [, /MANAGE_STYLE] [, NAME=structure] [, /NO_DRAW] [, /NO_SELECTION] [, /NO_STATUS] [, /NO_TOOLBAR] [, PARENT_BASE=widget_id | , TLB_LOCATION=[Xoffset, Yoffset]{device units}] [, PREFERENCE_FILE=filename{full path}] [, REFERENCE_OUT=variable] [, RENDERER={0 | 1}] [, REPLACE={structure | {0 | 1 | 2 | 3 | 4}}] [, STYLE=name_or_reference] [, TEMPLATE_FILE=filename] [, TITLE=string] [, WINDOW_IN=string] Arguments Image A two- or three-dimensional array of image data. The three-dimensional array must be for the form [3,X,Y] or [X,3,Y] or [X,Y,3]. Keywords BLUE Set this keyword equal to a byte vector of blue values. Note The BLUE, GREEN, and RED keywords are only used for 2D image data. They are used to form the color table. The 2D array is a set of values that are just indexes into this table. BUFFER Set this keyword to bypass the creation of a LIVE window and send the visualization to an offscreen buffer. The WINDOW field of the reference structure returned by the REFERENCE_OUT keyword will contain the name of the buffer. DIMENSIONS Set this keyword to a two-element vector of the form [width, height] to specify the dimensions of the image in units specified by the UNITS keyword. The default is [1.0, 1.0]. DRAW_DIMENSIONS Set this keyword to a two-element vector of the form [width, height] to specify the size of the LIVE tools draw widget (in pixels). The default is [452, 452]. Note This default value may be different depending on previous template projects. ERROR Set this keyword to a named variable to contain the returned error message (string). An empty string is returned if no errors occurred during the operation. By default, errors are reported via a GUI. Note If a named variable is passed in this keyword and an error occurs, the error GUI will not be displayed. GREEN Set this keyword equal to a byte vector of green values. Note The BLUE, GREEN, and RED keywords are only used for 2D image data. They are used to form the color table. The 2D array is a set of values that are just indexes into this table. INDEXED_COLOR If set, the indexed color mode will be used. The default is TrueColor. (See Using IDL for more information on color modes.) INSTANCING Set this keyword to 1 to instance drawing on, or 0 to turn it off. The default (-1) is to use instancing if and only if the "software renderer" is being used (see RENDERER). For more information, see "Instancing" in the Objects and Object Graphics manual. LOCATION Set this keyword to a two-element, floating-point vector of the form [X, Y] specifying the location of the visualization (relative to the lower left hand corner within the visualization window) in normalized coordinates. The default is [0.0, 0.0]. Note LOCATION may be adjusted to take into account window decorations. MANAGE_STYLE Set this keyword to have the passed in style item destroyed when the LIVE tool window is destroyed. This keyword will have no effect if the STYLE keyword is not set to a style item. NAME Set this keyword to a structure containing suggested names for the items to be created for this visualization. See the REPLACE keyword for details on how they will be used. The fields of the structure are as follows. (Any or all of the tags may be set.) Tag Description DATA Dependent Data Name(s) CT Color Table Name Table 27: Fields of the NAME keyword The default for a field is to use the given variable name. If the variable does not have a name (i.e., is an expression), a default name is automatically generated. NO_DRAW Set this keyword to inhibit the visualization window from drawing results of LIVE_CONTOUR. This is useful if multiple visualizations and/or annotations are being created via calls to other LIVE_Tools in order to reduce unwanted draws and help speed the display. NO_STATUS Set this keyword to prevent the creation of the status bar. NO_TOOLBAR Set this keyword to prevent the creation of the toolbar. PARENT_BASE Set this keyword to the widget ID of an existing base widget to bypass the creation of a LIVE window and create the visualization within the specified base widget. Note The location of the draw widget is not settable. It is expected that the user who wishes to insert a tool into their own widget application will determine the setting from the parent base sent to the tool. Note LIVE_DESTROY on a window is recommended when using PARENT_BASE so that proper memory cleanup is done. Simply destroying the parent base is not sufficient. Note When specifying a PARENT_BASE, that parent base must be running in a non- blocking mode. Putting a LIVE tool into a realized base already controlled by XMANAGER will override the XMANAGER mode to /NO_BLOCK even if blocking had been in effect. RED Set this keyword equal to a byte vector of red values. Note The BLUE, GREEN, and RED keywords are only used for 2D image data. They are used to form the color table. The 2D array is a set of values that are just indexes into this table. REFERENCE_OUT Set this keyword to a variable to return a structure defining the names of the created items. The fields of the structure are shown in the following table. Note that the COLORBAR* field does not show up with TrueColor images: Tag Description WIN Window Name VIS Visualization Name GRAPHIC Graphic Name CT Color Table Name COLORBAR* Colorbar Name DATA Data Name Table 28: Fields of the LIVE_IMAGE Reference Structure RENDERER Set this keyword to 1 to use the "software renderer", or 0 to use the "hardware renderer". The default (-1) is to use the setting in the IDE (IDL Development Environment) preferences; if the IDE is not running, however, the default is hardware rendering. For more information, see "Hardware vs. Software Rendering" in the Objects and Object Graphics manual. REPLACE Set this keyword to a structure containing tags as listed for the NAME keyword, with scalar values corresponding to the replacement options listed below. (Any or all of the tags may be set.) The replacement settings are used to determine what action to take when an item (such as data) being input would have the same name as one already existing in the given window or buffer (WINDOW_IN). Setting Action Taken 0 New items will be given unique names. 1 Existing items will be replaced by new items (i.e., the old items will be deleted and new ones created). 2 User will be prompted for the action to take. 3 The values of existing items will be replaced. This will cause dynamic updating to occur for any current uses, e.g., a visualization would redraw to show the new value. 4 Default. Option 0 will be used for items that do not have names (e.g., data input as an expression rather than a named variable, with no name provided via the NAME keyword). Option 3 will be used for all named items. Table 29: REPLACE keyword Settings and Action Taken STYLE Set this keyword to either a string specifying a style name created using LIVE_STYLE. TITLE Set this keyword to a string specifying the title to give the main window. It must not already be in use. A default will be chosen if no title is specified. TLB_LOCATION Set this keyword to a two-element vector of the form [Xoffset, Yoffset] specifying the offset (in pixels) of the LIVE window from the upper left corner of the screen. This keyword has no effect if the PARENT_BASE keyword is set. The default is [0, 0]. WINDOW_IN Set this keyword equal to a name (string, case-sensitive) of a LIVE tool window, or a LIVE tool buffer, in which to display the visualization. The WIN tag of the REFERENCE_OUT structure from the creation of the LIVE tool will provide the window or buffer name. Window names are also visible in visualization window titlebars. The default is to create a new window. Example LIVE_IMAGE, myImage See Also TV, TVSCL LIVE_INFO [Previous Routine] [Next Routine] [List of Routines] NAME: LIVE_INFO The LIVE_INFO procedure allows the user to get the properties of a LIVE tool. Syntax LIVE_INFO, [Name] [, ERROR=variable] [, PROPERTIES=variable] [, WINDOW_IN=string] Arguments Name A string containing the name of a visualization or element (case-insensitive). The default is to use the window or buffer (WINDOW_IN). Keywords ERROR Set this keyword to a named variable to contain the returned error message (string). An empty string is returned if no errors occurred during the operation. By default, errors are reported via a GUI. Note If a named variable is passed in this keyword and an error occurs, the error GUI will not be displayed. PROPERTIES Set this keyword to a named variable to contain the returned properties structure. For a description of the structures, see Properties Structures below. WINDOW_IN Set this keyword equal to a name (string, case-sensitive) of a LIVE tool window or a LIVE tool buffer. The WIN tag of the REFERENCE_OUT structure from the creation of the LIVE tool will provide the window or buffer name. Window names are also visible in visualization window titlebars. If only one LIVE tool window (or buffer) is present in the IDL session, this keyword will default to it. Structure Tables for LIVE_INFO and LIVE CONTROL The following tables describe the properties structures used by LIVE_INFO and LIVE_CONTROL (via the PROPERTIES keyword) for: * Color Names * Line Annotations * Rectangle Annotations * Text Annotations * Axes * Colorbars * Images * Legends * Surfaces * Entire Visualizations * Windows Color Names The following color names are the possible values for color properties: * Black * Red * Green * Yellow * Blue * Magenta * Cyan * Dark Gray * Light Gray * Brown * Light Red * Light Green * Light Blue * Light Cyan * Light Magenta * White Line Annotations The fields in the properties structure of Line Annotations are as follows: Tag Description thick 1 to 10 pixels Table 30: Line Annotation Properties Structure Tag Description arrow_start 1 = arrow head at line start, 0 = no arrowhead arrow_end 1 = arrow head at line start, 0 = no arrowhead arrow_size 0.0 to 0.3 normalized units arrow_angle 1.0 to 179.0 degrees linestyle 0=solid, 1=dotted, 2=dashed, 3=dash dot, 4=dash dot dot, 5=long dash hide 1 = hidden, 0 = visible name scalar string (unique within all graphics) color see "Color Names" on page 719 location [x, y] normalized units dimensions [width, height] normalized units uvalue any value of any type (only returned in structure if defined) Table 30: Line Annotation Properties Structure Rectangle Annotations The fields in the properties structure of Rectangle Annotations are as follows: Tag Description thick 1 to 10 pixels linestyle 0=solid, 1=dotted, 2=dashed, 3=dash dot, 4=dash dot dot, 5=long dash hide 1=hidden, 0=visible name scalar string (unique within all graphics) color see "Color Names" on page 719 location [x, y] normalized units dimensions [width, height] normalized units Tag Description uvalue any value of any type (only returned in structure if defined) Table 31: Rectangle Annotation Properties Structure Text Annotations The fields in the properties structure of Text Annotations are as follows: Tag Description fontsize 9 to 72 points fontname Helvetica, Courier, Times, Symbol, and Other (where Other is a valid name of a font on the local system) textangle 0.0 to 360.0 degrees alignment 0.0 to 1.0 where 0.0 = right justified and 1.0 = left justified location [x, y] normalized units hide 1=hidden, 0=visible name scalar string (unique within all graphics) value string (scalar or vector) annotation formula (see note below) enable_formatting set to allow "!" chars for font commands color see "Color Names" on page 719 uvalue any value of any type (only returned in structure if defined) Table 32: Text Annotation Properties Structure Note Each vector element of the annotation formula (see "value" tag above) is parsed once, left to right, for vertical bars (|). * Two vertical bars surrounding a data item name will be replaced by the corresponding data value(s), possibly requiring multiple lines. * Two adjacent bars will be replaced by a single bar. * Two bars surrounding text that is not a data item name will be left as is. Axes The fields in the properties structure of Axes are as follows: Tag Description title_FontSize 9 to 72 points title_Fontname Helvetica, Courier, Times, Symbol, and Other (where Other is a valid name of a font on the local system) title_Color see "Color Names" on page 719 tick_FontSize 9 to 72 points tick_Fontname Helvetica, Courier, Times, Symbol, and Other (where Other is a valid name of a font on the local system) tick_FontColor see "Color Names" on page 719 gridStyle see linestyle color see "Color Names" on page 719 thick 1 to 10 pixels location [x, y] data units minor number of minor ticks (minimum 0) major number of major ticks (minimum 0) default_minor set to compute default number of minor ticks default_major set to compute default number of major ticks tickLen normalized units * 100 = percent of visualization dimensions subticklen normalized units * 100 = percent of ticklen tickDir 0 = up (or right), 1 = down (or left) textPos 0 = below (or left), 1 = above (or right) tickFormat standard IDL FORMAT string (See STRING function) excluding parentheses exact set to use exact range specified log set to display axis as log Table 33: Axis Properties Structure Tag Description hide 1=hidden, 0=visible name scalar string (unique within all graphics) compute_range set to compute axis range from data min/max tickName if defined, vector of strings to use at major tick marks uvalue any value of any type (only returned in structure if defined) Table 33: Axis Properties Structure Colorbars The fields in the properties structure of Colorbars are as follows: Tag Description title_Fontsize 9 to 72 points title_Fontname Helvetica, Courier, Times, Symbol, and Other (where Other is a valid name of a font on the local system) title_Color see "Color Names" on page 719 tick_FontSize see fontsize tick_Fontname see fontname tick_FontColor see "Color Names" on page 719 color see "Color Names" on page 719 thick 1 to 10 pixels location [x, y]; where [0, 0] = lower left and [1, 1] = position where the entire colorbar fits into the upper right of the visualization minor number of minor ticks (minimum 0) major number of major ticks (minimum 0) default_minor set to compute default number of minor ticks default_major set to compute default number of major ticks Table 34: Colorbar Properties Structure Tag Description tickLen normalized units * 100 = percent of visualization dimensions subticklen normalized units * 100 = percent of ticklen tickFormat standard IDL FORMAT string (See STRING function) excluding parentheses show_axis set to display the colorbar axis show_outline set to display the colorbar outline axis_thick see thick dimensions [width, height] normalized units hide 1=hidden, 0=visible name scalar string (unique within all graphics) uvalue any value of any type (only returned in structure if defined) Table 34: Colorbar Properties Structure Contours The fields in the properties structure of Contours are as follows: Tag Description min_value minimum contour value to display max_value maximum contour value to display downhill set to display downhill tick marks fill set to display contour levels as filled c_thick vector of thickness values (see thick) c_linestyle vector of linestyle values (see linestyle) c_color vector of color names (see "Color Names" on page 719) default_n_levels set to default the number of levels n_levels* specify a positive number for a specific number of levels Table 35: Contour Properties Structure Tag Description hide 1=hidden, 0=visible name scalar string (unique within all graphics) uvalue any value of any type (only returned in structure if defined) *The MIN and MAX value of the data are returned as contour levels when N_LEVELS is set. Because of this, when setting N_LEVELS, contour plots appear to have N-2 contour levels because the first (MIN) and last (MAX) level is not shown. With LIVE_CONTOUR, this results in a legend that contains unnecessary items in the legend (the MIN and the MAX contour level). Table 35: Contour Properties Structure Images The fields in the properties structure of Images are as follows: Tag Description order set to draw from top to bottom sizing_constraint [0|1|2] 0=Natural, 1=Aspect, 2=Unrestricted dont_byte_scale set to inhibit byte scaling the image palette name of managed colortable hide 1=hidden, 0=visible name scalar string (unique within all graphics) uvalue any value of any type (only returned in LIVE_INFO structure if defined) Table 36: Image Properties Structure Legends The fields in the properties structure of Legends are as follows: Tag Description title_FontSize 9 to 72 points Table 37: Legend Properties Structure Tag Description title_Fontname Helvetica, Courier, Times, Symbol, and Other (where Other is a valid name of a font on the local system) title_Color see "Color Names" on page 719 item_fontSize see fontsize item_fontName Helvetica, Courier, Times, Symbol, and Other (where Other is a valid name of a font on the local system) text_color color of item text (see "Color Names" on page 719) border_gap normalized units * 100 = percent of item text height columns number of columns to display the items in (minimum 0) gap normalized units * 100 = percent of item text height glyph_Width normalized units * 100 = percent of item text height fill_color see "Color Names" on page 719 outline_color see "Color Names" on page 719 outline_thick see thick location [x, y]; where [0, 0] = lower left and [1, 1] = position where the entire legend fits into the upper right of the visualization show_fill set to display the fill color show_outline set to display the legend outline title_text String to display in the legend title item_format standard IDL FORMAT string (See STRING function) excluding parentheses (contour legends only) hide 1=hidden, 0=visible name scalar string (unique within all graphics) uvalue any value of any type (only returned in structure if defined) Table 37: Legend Properties Structure Surfaces The fields in the properties structure of Surfaces are as follows: Tag Description min_value minimum plot line value to display max_value maximum plot line value to display lineStyle 0=solid, 1=dotted, 2=dashed, 3=dash dot, 4=dash dot dot, 5=long dash color see "Color Names" on page 719 thick 1 to 10 pixels bottom see "Color Names" on page 719 style 0=point, 1=wire, 2=solid, 3=ruledXZ, 4=ruledYZ, 5=lego (wire), 6=lego (solid) shading 0=flat, 1=Gouraud hidden_lines set to not display hidden lines or points show_skirt set to display the surface skirt skirt z value at which skirt is drawn (data units) hide 1=hidden, 0=visible name scalar string (unique within all graphics) uvalue any value of any type (only returned in structure if defined) Table 38: Surface Properties Structure Entire Visualizations The fields in the properties structure of Entire Visualizations are as follows: Tag Description location [x, y] normalized units dimensions [width, height] normalized units Table 39: Visualization Properties Structure Tag Description transparent set to avoid erasing to the background color color background color (see "Color Names" on page 719) hide 1=hidden, 0=visible name scalar string (unique within all graphics) uvalue any value of any type (only returned in structure if defined) Table 39: Visualization Properties Structure Windows The fields in the properties structure of Windows are as follows: Tag Description dimensions 2-element integer vector (pixels) hide boolean (0=show, 1=hide) location 2-element integer vector (pixels) from upper left corner of screen title string Table 40: Windows Properties Structure Example LIVE_INFO, 'x axis', PROPERTIES=myProps See Also LIVE_CONTROL, LIVE_STYLE LIVE_LINE [Previous Routine] [Next Routine] [List of Routines] NAME: LIVE_LINE The LIVE_LINE procedure is an interface for line annotation. Syntax LIVE_LINE [, ARROW_ANGLE=value{1.0 to 179.0}] [, /ARROW_END] [, ARROW_SIZE=value{0.0 to 0.3}] [, /ARROW_START] [, COLOR='color name' ] [, /DIALOG] [, DIMENSIONS=[width, height]] [, ERROR=variable] [, /HIDE] [, LINESTYLE={0 | 1 | 2 | 3 | 4 | 5}] [, LOCATION=[x, y]] [, NAME=string] [, /NO_DRAW] [, /NO_SELECTION] [, REFERENCE_OUT=variable] [, THICK=pixels{1 to 10}] [, VISUALIZATION_IN=string] [, WINDOW_IN=string] Arguments None Keywords ARROW_ANGLE Set this keyword to a floating-point number between 1.0 and 179.0 degrees to indicate the angle of the arrowheads. The default is 30.0. ARROW_END Set this keyword to indicate an arrowhead should be drawn at the end of the line. It is not drawn by default. ARROW_SIZE Set this keyword to a floating-point number between 0.0 and 0.3 (normalized coordinates) to indicate the size of the arrowheads. The default is 0.02. ARROW_START Set this keyword to indicate an arrowhead should be drawn at the start of the line. It is not drawn by default. COLOR Set this keyword to a string (case-sensitive) of the color to be used for the line. The default is `Black'. The following colors are available: * Black * Red * Green * Yellow * Blue * Magenta * Cyan * Dark Gray * Light Gray * Brown * Light Red * Light Green * Light Blue * Light Cyan * Light Magenta * White DIALOG Set this keyword to display the line properties dialog appear. The dialog will have all known properties supplied by keywords filled in. DIMENSIONS Set this keyword to a two-element vector of the form [width, height] to specify the X and Y components of the line in normalized coordinates. The default is [0.2, 0.2]. ERROR Set this keyword to a named variable to contain the returned error message (string). An empty string is returned if no errors occurred during the operation. By default, errors are reported via a GUI. Note If a named variable is passed in this keyword and an error occurs, the error GUI will not be displayed. HIDE Set this keyword to a boolean value indicating whether this item should be hidden. * 0 = Visible (default) * 1 = Hidden LINESTYLE Set this keyword to a pre-defined line style integer: * 0 = solid line (default) * 1 = dotted * 2 = dashed * 3 = dash dot * 4 = dash dot dot * 5 = long dash LOCATION Set this keyword to a two-element, floating-point vector of the form [X, Y] specifying the location of the visualization (relative to the lower left hand corner within the visualization window) in normalized coordinates. The default is [0.5, 0.5]. Note LOCATION may be adjusted to take into account window decorations. NAME Set this keyword equal to a string containing the name to be associated with this item. The name must be unique within the given window or buffer (WINDOW_IN). If not specified, a unique name will be assigned automatically. NO_DRAW Set this keyword to inhibit the visualization window from drawing. This is useful if multiple visualizations and/or annotations are being created via calls to other LIVE_Tools in order to reduce unwanted draws and help speed the display. REFERENCE_OUT Set this keyword to a variable to return a structure defining names of the modified visualization's properties. The fields of the structure are shown in the following table. Tag Description WIN Window Name VIS Visualization Name GRAPHIC Graphic Name the line created Table 41: Fields of the LIVE_LINE Reference Structure THICK Set this keyword to an integer value between 1 and 10, specifying the line thickness to be used to draw the line, in pixels. The default is one pixel. VISUALIZATION_IN Set this keyword equal to the name (string, case-insensitive) of a LIVE tool visualization. The VIS field from the REFERENCE_OUT keyword from the creation of the LIVE tool will provide the visualization name. If only one visualization is present in the window or buffer (WINDOW_IN), this keyword will default to it. WINDOW_IN Set this keyword equal to a name (string, case-sensitive) of a LIVE tool window or a LIVE tool buffer. The WIN tag of the REFERENCE_OUT structure from the creation of the LIVE tool will provide the window or buffer name. Window names are also visible in visualization window titlebars. If only one LIVE tool window (or buffer) is present in the IDL session, this keyword will default to it. Example LIVE_LINE, WINDOW_IN='Live Plot 2', $ VISUALIZATION_IN='line plot visualization' ; Units are in the visualization units ( based on axis ranges). See Also LIVE_RECT, LIVE_TEXT LIVE_LOAD [Previous Routine] [Next Routine] [List of Routines] NAME: LIVE_LOAD The LIVE_LOAD procedure loads into memory the complete set of routines necessary to run all LIVE tools. By default, portions of the set are loaded when first needed during the IDL session. If you expect to frequently use the tools, you may wish to call LIVE_LOAD from your IDL "startup file". Syntax LIVE_LOAD Arguments None Keywords None LIVE_OPLOT [Previous Routine] [Next Routine] [List of Routines] NAME: LIVE_OPLOT The LIVE_OPLOT procedure allows the insertion of data into pre-existing plots. Syntax LIVE_OPLOT, Yvector1 [,... , Yvector25] [, ERROR=variable] [, INDEPENDENT=vector] [, NAME=structure] [, /NEW_AXES] [, /NO_DRAW] [, /NO_SELECTION] [, REFERENCE_OUT=variable] [, REPLACE={structure | {0 | 1 | 2 | 3 | 4}}] [, SUBTYPE={`LinePlot' | `ScatterPlot' | `Histogram' | `PolarPlot'}] [, VISUALIZATION_IN=string] [, WINDOW_IN=string] [, {X | Y}_TICKNAME=array] [, {X | Y}AXIS_IN=string] Arguments YVector A vector argument of data. Up to 25 of these arguments may be specified. Keywords ERROR Set this keyword to a named variable to contain the returned error message (string). An empty string is returned if no errors occurred during the operation. By default, errors are reported via a GUI. Note If a named variable is passed in this keyword and an error occurs, the error GUI will not be displayed. INDEPENDENT Set this keyword to an independent vector specifying the X-Values for LIVE_OPLOT. NAME Set this keyword to a structure containing suggested names for the data items to be created for this visualization. See the REPLACE keyword for details on how they will be used. The fields of the structure are as follows. (Any or all of the tags may be set.) Tag Description DATA Dependent Data Name(s) I Independent Data Name Table 42: Fields of the NAME keyword The default for a field is to use the given variable name. If the variable does not have a name (i.e., is an expression), a default name is automatically generated. The dependent data names will be used in a round-robin fashion if more data than names are input. Note Only one independent vector is allowed; all dependent vectors will use the independent vector. NEW_AXES Set this keyword to generate a new set of axes for this plot line. If this keyword is specified, the [XY]AXIS_IN keywords will not be used. NO_DRAW Set this keyword to inhibit the visualization window from drawing. This is useful if multiple visualizations and/or annotations are being created via calls to other LIVE_Tools in order to reduce unwanted draws and help speed the display. REFERENCE_OUT Set this keyword to a variable to return a structure defining the names of the modified items. The fields of the structure are shown in the following table. Tag Description WIN Window Name VIS Visualization Name Table 43: Fields of the LIVE_OPLOT Reference Structure Tag Description XAXIS X-Axis Name YAXIS Y-Axis Name GRAPHIC Graphic Name(s) LEGEND Legend Name DATA Dependent Data Name(s) I Independent Data Name Table 43: Fields of the LIVE_OPLOT Reference Structure REPLACE Set this keyword to a structure containing tags as listed for the NAME keyword, with scalar values corresponding to the replacement options listed below. (Any or all of the tags may be set.) The replacement settings are used to determine what action to take when an item (such as data) being input would have the same name as one already existing in the given window or buffer (WINDOW_IN). Setting Action Taken 0 New items will be given unique names. 1 Existing items will be replaced by new items (i.e., the old items will be deleted and new ones created). 2 User will be prompted for the action to take. 3 The values of existing items will be replaced. This will cause dynamic updating to occur for any current uses, e.g., a visualization would redraw to show the new value. 4 Default. Option 0 will be used for items that do not have names (e.g., data input as an expression rather than a named variable, with no name provided via the NAME keyword). Option 3 will be used for all named items. Table 44: REPLACE keyword Settings and Action Taken SUBTYPE Set this keyword to a string (case-insensitive) containing the desired type of plot. SUBTYPE defaults to whatever is being inserted into, if the [XY]AXIS_IN keyword is set. If the keywords are not set, then the default is line plot. Valid strings are: * `LinePlot' (default) * `ScatterPlot' * `Histogram' * `PolarPlot' Note If inserting into a group (defined by the set of axes) that is polar, SUBTYPE cannot be defined as line, scatter, or histogram. The opposite is also true: if inserting into a line, scatter, or histogram group, then SUBTYPE cannot be defined as polar. VISUALIZATION_IN Set this keyword equal to the name (string, case-insensitive) of a LIVE tool visualization. The VIS field from the REFERENCE_OUT keyword from the creation of the LIVE tool will provide the visualization name. If only one visualization is present in the window or buffer (WINDOW_IN), this keyword will default to it. WINDOW_IN Set this keyword equal to a name (string, case-sensitive) of a LIVE tool window or a LIVE tool buffer. The WIN tag of the REFERENCE_OUT structure from the creation of the LIVE tool will provide the window or buffer name. Window names are also visible in visualization window titlebars. If only one LIVE tool window (or buffer) is present in the IDL session, this keyword will default to it. X_TICKNAME Set this keyword equal to an array of strings to be used to label the tick mark for the X axis. The default equals the values computed from the data range. Y_TICKNAME Set this keyword equal to an array of strings to be used to label the tick mark for the Yaxis. The default equals the values computed from the data range. XAXIS_IN Set this keyword equal to the string name of an existing axis. The name can be obtained from the REFERENCE_OUT keyword, or visually from the GUI. The default is to use the first set of axes in the plot. Note If this keyword is set, you must also set the YAXIS_IN keyword, and both keywords must be set to a "pair" of axes. The X and Y axes given must be associated with the same plot line. YAXIS_IN Set this keyword equal to the string name of an existing axis. The name can be obtained from the REFERENCE_OUT keyword, or visually from the GUI. The default is to use the first set of axes in the plot. Note If this keyword is set, you must also set the XAXIS_IN keyword, and both keywords must be set to a "pair" of axes. The X and Y axes given must be associated with the same plot line. Example LIVE_OPLOT, tempData, pressureData See Also LIVE_PLOT, PLOT, OPLOT LIVE_PLOT [Previous Routine] [Next Routine] [List of Routines] NAME: LIVE_PLOT The LIVE_PLOT procedure creates an interactive plotting environment. Click on a section of the plot to display a properties dialog. A set of buttons in the upper left corner of the image window allows you to print, undo the last operation, redo the last "undone" operation, copy, draw a line, draw a rectangle, or add text. Print Undo Redo Copy Line Rectangle Text Figure 14: LIVE_PLOT Properties Dialog You can control your LIVE window after it is created using any of several auxiliary routines. See "LIVE_Tools" on page 694 for an explanation. Syntax LIVE_PLOT, Yvector1 [, Yvector2,..., Yvector25] [, /BUFFER] [, DIMENSIONS=[width, height]{normal units}] [, /DOUBLE] [, DRAW_DIMENSIONS=[width, height]{devive units}] [, ERROR=variable] [, /HISTOGRAM | , /LINE | , /POLAR | , /SCATTER] [, /INDEXED_COLOR] [, INSTANCING={-1 | 0 | 1}] [, LOCATION=[x, y]{normal units}] [, INDEPENDENT=vector] [, /MANAGE_STYLE] [, NAME=structure] [, /NO_DRAW] [, /NO_SELECTION] [, /NO_STATUS] [, /NO_TOOLBAR] [, PARENT_BASE=widget_id | , TLB_LOCATION=[Xoffset, Yoffset]{device units}] [, PREFERENCE_FILE=filename{full path}] [, REFERENCE_OUT=variable] [, RENDERER={0 | 1}] [, REPLACE={structure | {0 | 1 | 2 | 3 | 4}}] [, STYLE=name_or_reference] [, TEMPLATE_FILE=filename] [, TITLE=string] [, WINDOW_IN=string] [, {/X | /Y}LOG] [, {X | Y}RANGE=[min, max]{data units}] [, {X | Y}_TICKNAME=array] Arguments YVector A vector of data. Up to 25 of these arguments may be specified. If any of the data is stored in IDL variables of type DOUBLE, LIVE_PLOT uses double precision to store the data and to draw the result. Keywords BUFFER Set this keyword to bypass the creation of a LIVE window and send the visualization to an offscreen buffer. The WINDOW field of the reference structure returned by the REFERENCE_OUT keyword will contain the name of the buffer. DIMENSIONS Set this keyword to a two-element, floating-point vector specifying the dimensions of the visualization in normalized coordinates. The default is [1.0, 1.0]. DOUBLE Set this keyword to force LIVE_PLOT to use double-precision to draw the result. This has the same effect as specifying data in the YVector argument using IDL variables of type DOUBLE. DRAW_DIMENSIONS Set this keyword equal to a vector of the form [width, height] representing the desired size of the LIVE tools draw widget (in pixels). The default is [452, 452]. Note This default value may be different depending on previous template projects. ERROR Set this keyword to a named variable to contain the returned error message (string). An empty string is returned if no errors occurred during the operation. By default, errors are reported via a GUI. Note If a named variable is passed in this keyword and an error occurs, the error GUI will not be displayed. HISTOGRAM Set this keyword to represent plot values as a histogram. INDEPENDENT Set this keyword to an independent vector specifying X-values for LIVE_PLOT. INDEXED_COLOR If set, the indexed color mode will be used. The default is TrueColor. (See Using IDL for more information on color modes.) INSTANCING Set this keyword to 1 to instance drawing on, or 0 to turn it off. The default (-1) is to use instancing if and only if the "software renderer" is being used (see RENDERER). For more information, see "Instancing" in the Objects and Object Graphics manual. LINE Set this keyword to represent plot values as a line plot. This is the default. Alternate choices are provided by keywords HISTOGRAM, POLAR, and SCATTER. LOCATION Set this keyword to a two-element, floating-point vector of the form [X, Y] specifying the location of the visualization (relative to the lower left hand corner within the visualization window) in normalized coordinates. The default is [0.0, 0.0]. Note LOCATION may be adjusted to take into account window decorations. MANAGE_STYLE Set this keyword to have the passed in style item destroyed when the LIVE tool window is destroyed. This keyword will have no effect if the STYLE keyword is not set to a style item. NAME Set this keyword to a structure containing suggested names for the data items to be created for this visualization. See the REPLACE keyword for details on how they will be used. The fields of the structure are as follows. (Any or all of the tags may be set.) Tag Description DATA Dependent Data Name(s) I Independent Data Name Table 45: Fields of the NAME keyword The default for a field is to use the given variable name. If the variable does not have a name (i.e., is an expression), a default name is automatically generated. The dependent data names will be used in a round-robin fashion if more data than names are input. NO_DRAW Set this keyword to inhibit the visualization window from drawing. This is useful if multiple visualizations and/or annotations are being created via calls to other LIVE_Tools in order to reduce unwanted draws and help speed the display. NO_STATUS Set this keyword to prevent the creation of the status bar. NO_TOOLBAR Set this keyword to prevent the creation of the toolbar. PARENT_BASE Set this keyword to the widget ID of an existing base widget to bypass the creation of a LIVE window and create the visualization within the specified base widget. Note The location of the draw widget is not settable. To insert a tool into your widget application, you must determine the setting from the parent base sent to the tool. LIVE_DESTROY on a window is recommended when using PARENT_BASE so that proper memory cleanup is done. Destroying the parent base is not sufficient. Note When specifying a PARENT_BASE, that parent base must be running in a non- blocking mode. Putting a LIVE tool into a realized base already controlled by XMANAGER will override the XMANAGER mode to /NO_BLOCK even if blocking had been in effect. POLAR Set this keyword to represent plot values as a polar plot. In this case, the arguments to LIVE_PLOT represent values of r (radius), while the INDEPENDENT keyword represents the values of T (angle theta). If POLAR is set, you must specify INDEPENDENT. REFERENCE_OUT Set this keyword to a variable to return a structure defining the names of the modified items. The fields of the structure are shown in the following table. Tag Description WIN Window Name VIS Visualization Name XAXIS X-Axis Name YAXIS Y-Axis Name GRAPHIC Graphic Name(s) LEGEND Legend Name DATA Dependent Data Name(s) I Independent Data Name Table 46: Fields of the LIVE_PLOT Reference Structure RENDERER Set this keyword to 1 to use the "software renderer", or 0 to use the "hardware renderer". The default (-1) is to use the setting in the IDE (IDL Development Environment) preferences; if the IDE is not running, however, the default is hardware rendering. For more information, see "Hardware vs. Software Rendering" in the Objects and Object Graphics manual. REPLACE Set this keyword to a structure containing tags as listed for the NAME keyword, with scalar values corresponding to the replacement options listed below. (Any or all of the tags may be set.) The replacement settings are used to determine what action to take when an item (such as data) being input would have the same name as one already existing in the given window or buffer (WINDOW_IN). Setting Action Taken 0 New items will be given unique names. 1 Existing items will be replaced by new items (i.e., the old items will be deleted and new ones created). 2 User will be prompted for the action to take. 3 The values of existing items will be replaced. This will cause dynamic updating to occur for any current uses, e.g., a visualization would redraw to show the new value. 4 Default. Option 0 will be used for items that do not have names (e.g., data input as an expression rather than a named variable, with no name provided via the NAME keyword). Option 3 will be used for all named items. Table 47: REPLACE keyword Settings and Action Taken SCATTER Set this keyword to represent plot values as a scatter plot. STYLE Set this keyword to either a string specifying a style name created with LIVE_STYLE. Note If STYLE is not set, the default plot style will be used. TITLE Set this keyword to a string specifying the title to give the main window. It must not already be in use. A default will be chosen if no title is specified. TLB_LOCATION Set this keyword to a two-element vector of the form [Xoffset, Yoffset] specifying the offset (in pixels) of the LIVE window from the upper left corner of the screen. This keyword has no effect if the PARENT_BASE keyword is set. The default is [0, 0]. WINDOW_IN Set this keyword equal to a name (string, case-sensitive) of a LIVE tool window or a LIVE tool buffer, in which to display the visualization. The WIN tag of the REFERENCE_OUT structure from the creation of the LIVE tool will provide the window or buffer name. Window names are also visible in visualization window titlebars. The default is to create a new window. XLOG Set this keyword to make the X axis a log axis. The default is 0 (linear axis). YLOG Set this keyword to make the Y axis a log axis. The default is 0 (linear axis). XRANGE Set this keyword equal to a two-element array that defines the minimum and maximum values of the X axis range. The default equals the values computed from the data range. YRANGE Set this keyword equal to a two-element array that defines the minimum and maximum values of the Y axis range. The default equals the values computed from the data range. X_TICKNAME Set this keyword equal to an array of strings to be used to label the tick mark for the X axis. The default equals the values computed from the data range. Y_TICKNAME Set this keyword equal to an array of strings to be used to label the tick mark for the Yaxis. The default equals the values computed from the data range. Example ; Plot two data sets simultaneously: LIVE_PLOT, tempdata, pressureData Note This is a "Live" situation. When data of the same name is used multiple times within the same window, it always represents the same internal data item. For example, if one does the following: Y= indgen(10) LIVE_PLOT, Y, WINDOW_IN=w, DIMENSIONS=d, LOCATION=loc1 Y = indgen(20) LIVE_PLOT, Y, WINDOW_IN=w, DIMENSIONS=d, LOCATION=loc2 The first plot will update to use the Y of the second plot when the second plot is drawn. If the user wants to display 2 "tweaks" of the same data, a different variable name must be used each time, or at least one should be an expression (thus not a named variable). For example: LIVE_PLOT, Y1,... LIVE_PLOT, Y2,... or LIVE_PLOT, Y,... LIVE_PLOT, myFunc(Y),... In last example, the data of the second visualization will be given a default unique name since an expression rather than a named variable is input. Note The above shows the default behavior for naming and replacing data, which can be overridden using the NAME and REPLACE keywords. See Also LIVE_OPLOT, PLOT, OPLOT LIVE_PRINT [Previous Routine] [Next Routine] [List of Routines] NAME: LIVE_PRINT The LIVE_PRINT procedure allows the user to print a given window to the printer. Syntax LIVE_PRINT [, /DIALOG] [, ERROR=variable] [, WINDOW_IN=string] Macintosh Keywords: [, /SETUP] Arguments None Keywords DIALOG Set this keyword to have a print dialog appear. ERROR Set this keyword to a named variable to contain the returned error message (string). An empty string is returned if no errors occurred during the operation. By default, errors are reported via a GUI. Note If a named variable is passed in this keyword and an error occurs, the error GUI will not be displayed. SETUP (Macintosh users only) Set this keyword to have a printer setup dialog appear. This keyword allows the user to setup the page for printing. WINDOW_IN Set this keyword equal to a name (string, case-sensitive) of a LIVE tool window or a LIVE tool buffer. The WIN tag of the REFERENCE_OUT structure from the creation of the LIVE tool will provide the window or buffer name. Window names are also visible in visualization window titlebars. If only one LIVE tool window (or buffer) is present in the IDL session, this keyword will default to it. Example LIVE_PRINT, WINDOW_IN='Live Plot 2' See Also DIALOG_PRINTJOB, DIALOG_PRINTERSETUP LIVE_RECT [Previous Routine] [Next Routine] [List of Routines] NAME: LIVE_RECT The LIVE_RECT procedure is an interface for insertion of rectangles. Syntax LIVE_RECT [, COLOR='color name' ] [, /DIALOG] [, DIMENSIONS=[width, height]] [, ERROR=variable] [, /HIDE] [, LINESTYLE={0 | 1 | 2 | 3 | 4 | 5}] [, LOCATION=[x, y]] [, NAME=string] [, /NO_DRAW] [, /NO_SELECTION] [, REFERENCE_OUT=variable] [, THICK=pixels{1 to 10}] [, VISUALIZATION_IN=string] [, WINDOW_IN=string] Arguments None Keywords COLOR Set this keyword to a string (case-sensitive) of the color to be used for the rectangle. The default is `Black'. The following colors are available: * Black * Red * Green * Yellow * Blue * Magenta * Cyan * Dark Gray * Light Gray * Brown * Light Red * Light Green * Light Blue * Light Cyan * Light Magenta * White DIALOG Set this keyword to have the rectangle dialog appear. This dialog will fill in known attributes from set keywords. DIMENSIONS Set this keyword to a two-element, floating-point vector of the form [width, height] to specify the dimensions of the rectangle in normalized coordinates. The default is [0.2, 0.2]. ERROR Set this keyword to a named variable to contain the returned error message (string). An empty string is returned if no errors occurred during the operation. By default, errors are reported via a GUI. Note If a named variable is passed in this keyword and an error occurs, the error GUI will not be displayed. HIDE Set this keyword to a boolean value indicating whether this item should be hidden. * 0 = Visible (default) * 1 = Hidden LINESTYLE Set this keyword to a pre-defined line style integer: * 0 = Solid line (default) * 1 = dotted * 2 = dashed * 3 = dash dot * 4 = dash dot dot * 5 = long dash LOCATION Set this keyword to a two-element, floating-point vector of the form [X, Y] specifying the location of the visualization (relative to the lower left hand corner within the visualization window) in normalized coordinates. The default is [0.5, 0.5]. Note LOCATION may be adjusted to take into account window decorations. NAME Set this keyword equal to a string containing the name to be associated with this item. The name must be unique within the given window or buffer (WINDOW_IN). If not specified, a unique name will be assigned automatically. NO_DRAW Set this keyword to inhibit the visualization window from drawing. This is useful if multiple visualizations and/or annotations are being created via calls to other LIVE_Tools in order to reduce unwanted draws and help speed the display. REFERENCE_OUT Set this keyword to a variable to return a structure defining the names of the modified items. The fields of the structure are shown in the following table. Tag Description WIN Window Name VIS Visualization Name GRAPHIC Graphic Name the rectangle created Table 48: Fields of the LIVE_RECT Reference Structure THICK Set this keyword to an integer value between 1 and 10, specifying the line thickness to be used to draw the line, in pixels. The default is one pixel. VISUALIZATION_IN Set this keyword equal to the name (string, case-insensitive) of a LIVE tool visualization. The VIS field from the REFERENCE_OUT keyword from the creation of the LIVE tool will provide the visualization name. If only one visualization is present in the window or buffer (WINDOW_IN), this keyword will default to it. WINDOW_IN Set this keyword equal to a name (string, case-sensitive) of a LIVE tool window or a LIVE tool buffer. The WIN tag of the REFERENCE_OUT structure from the creation of the LIVE tool will provide the window or buffer name. Window names are also visible in visualization window titlebars. If only one LIVE tool window (or buffer) is present in the IDL session, this keyword will default to it. Example LIVE_RECT, LOCATION=[0.1,0.1],DIMENSIONS=[0.2,0.2],$ WINDOW_IN='Live Plot 2',VISUALIZATION_IN='line plot' See Also LIVE_LINE, LIVE_TEXT LIVE_STYLE [Previous Routine] [Next Routine] [List of Routines] NAME: LIVE_STYLE The LIVE_STYLE function allows the user to create a style. Syntax Style = LIVE_STYLE ({ 'contour' | 'image' | 'plot' | 'surface'} [, BASE_STYLE=style_name] [, COLORBAR_PROPERTIES=structure] [, ERROR=variable] [, GRAPHIC_PROPERTIES=structure] [, GROUP=widget_id] [, LEGEND_PROPERTIES=structure] [, NAME=string] [, /SAVE] [, TEMPLATE_FILE=filename] [, VI [, {X | Y | Z}AXIS_PROPERTIES=structure] ) Arguments Type A string (case-insensitive) specifying the visualization style type. Available types include: plot, contour, image, and surface. Keywords BASE_STYLE Set this keyword equal to a string (case-insensitive) containing the name of a previously saved style. It will be used for defaulting unspecified properties. If not specified, only those properties you provide will be put into the style. The basic styles that will always exist include: Visualization Type Style Name plot `Basic Plot' contour `Basic Contour' image `Basic Image' surface `Basic Surface' Table 49: Base Style Strings COLORBAR_PROPERTIES The table below lists the structure of the COLORBAR_PROPERTIES keyword. Tag Description title_FontSize 9 to 72 points title_Fontname Helvetica, Courier, Times, Symbol, and Other (where Other is a valid name of a font on the local system) title_Color see color table tick_FontSize see fontsize tick_Fontname see fontname tick_FontColor see color table color see color table thick 1 to 10 pixels location [x, y] normalized units minor number of minor ticks (minimum 0) major number of major ticks (minimum 0) default_minor set to compute default number of minor ticks default_major set to compute default number of major ticks tickLen normalized units * 100 = percent of visualization dimensions subticklen normalized units * 100 = percent of ticklen tickFormat see format show_axis set to display the colorbar axis show_outline set to display the colorbar outline axis_thick see thick dimensions [width, height] normalized units hide 1=hidden, 0=visible Table 50: Colorbar Properties Structure GRAPHIC_PROPERTIES Set this keyword equal to a scalar or vector of structures defining the graphic properties to use in creating the style. (Use a vector if you want successive graphics to have different properties, e.g., different colored lines in a line plot. The structures are used in a round-robin fashion.) Not all properties need be specified (see BASE_STYLE). The complete structure definitions are listed in the following tables. Plots Tag Data Type/Description color string (see color table) hide boolean (1=hidden, 0=visible) linestyle integer (0=solid, 1=dotted, 2=dashed, 3=dash dot, 4=dash dot dot, 5=long dash) nSum integer (1 to number of elements to average over) symbol_size [x,y] normalized units relative to the visualization symbol_type integer (1-7) thick integer (1 to 10 pixels) Table 51: Plot Graphic Properties Structure Images Tag Data Type/Description hide boolean (1=hidden, 0=visible) order boolean (set to draw from top to bottom) sizing_constraint integer (0=natural, 1=aspect, 2=unrestricted) Table 52: Image Graphic Properties Structure Contours Tag Data Type/Description downhill boolean (set to display downhill tick marks) fill boolean (set to display contour levels as filled) hide boolean (1=hidden, 0=visible) n_levels integer (number of levels) c_thick vector of thickness values c_linestyle vector of linestyle values c_color vector of color names default_n_levels integer (set to default number of levels) Table 53: Contour Graphic Properties Structure Surfaces Tag Data Type/Description bottom string (see color table) color string (see color table) hidden_lines boolean (1=don't show, 0=show) hide boolean (1=hidden, 0=visible) lineStyle integer (0=solid, 1=dotted, 2=dashed, 3=dash dot, 4=dash dot dot, 5=long dash) shading boolean (0=flat, 1=Gouraud) show_skirt boolean (1=show, 0=don't show) skirt float (z value at which skirt is drawn [data units]) style integer (0=point, 1=wire, 2=solid, 3=ruledXZ, 4=ruledYZ, 5=lego (wire), 6=lego (solid) ) thick integer (1 to 10 pixels) Table 54: Surface Graphic Properties Structure GROUP Set this keyword to the widget ID of the group leader for error message display. This keyword is used only when the ERROR keyword is not set. If only one LIVE tool window is present in the IDL session, it will default to that. LEGEND_PROPERTIES Set this keyword equal to a structure defining the legend properties to use in creating the style. Not all properties need be specified (see BASE_STYLE). The complete structure definitions for different types of styles are listed in the following tables. Tag Description title_FontSize 9 to 72 points title_Fontname Helvetica, Courier, Times, Symbol, and Other (where Other is a valid name of a font on the local system) title_Color see color table item_fontSize see fontsize item_fontName see fontname text_color see color border_gap normalized units * 100 = percent of item text height columns number of columns to display the items in (minimum 0) gap normalized units * 100 = percent of item text height glyph_Width normalized units * 100 = percent of item text height fill_color see color table outline_color see color table outline_thick see thick location [x, y] normalized units show_fill set to display the fill color show_outline set to display the legend outline hide 1=hidden, 0=visible Table 55: Legend Properties Structure NAME Set this keyword to a string containing a name for the returned style. If the SAVE keyword is set, the name must be unique template file. If not specified, a name will be automatically generated. SAVE Set this keyword to save the style in the template file. The supplied Name must not already exist in the template file or an error will be returned. VISUALIZATION_PROPERTIES Set this keyword equal to a structure defining the visualization properties to use in creating the style. Not all properties need be specified (see BASE_STYLE). The complete structure definition is in the following table. Tag Data Type color string (see color table) for background hide boolean transparent boolean Table 56: Visualization Properties Structure XAXIS_PROPERTIES, YAXIS_PROPERTIES, ZAXIS_PROPERTIES Set these keywords equal to a scalar or vector of structures defining the axis properties to use in creating the style. (Use a vector to specify property structures for successive axes of the same direction have different properties. The structures are used in a round-robin fashion.) Not all properties need be specified (see BASE_STYLE). The user need only define the fields of the structure they wish to be different from the BASE style. The complete structure definition is shown in the following table. Tag Data Type color string (see color table) default_major integer default_minor integer Table 57: Axis Properties Structure Tag Data Type exact boolean gridstyle integer (0-5) (linestyle) hide boolean location 3-element floating vector (normalized units) major integer (default=-1, computed by IDL) minor integer (default=-1, computed by IDL) thick integer (1-10) tickDir integer tickLen float (normalized units) tick_fontname string tick_fontsize integer Table 57: Axis Properties Structure Example Style=LIVE_STYLE('plot',BASE_STYLE='basic plot', $ GRAPHIC_PROPERTIES={color:'red'}) See Also LIVE_INFO, LIVE_CONTROL LIVE_SURFACE [Previous Routine] [Next Routine] [List of Routines] NAME: LIVE_SURFACE The LIVE_SURFACE procedure creates an interactive plotting environment for multiple surfaces. Because the interactive environment requires extra system resources, this routine is most suitable for relatively small data sets. If you find that performance does not meet your expectations, consider using the Direct Graphics SURFACE routine or the Object Graphics IDLgrSurface class directly. After LIVE_SURFACE has been executed, you can double-click on a section of the surface to display a properties dialog. A set of buttons in the upper left corner of the image window allows you to print, undo the last operation, redo the last "undone" operation, copy, draw a line, draw a rectangle, or add text. Print Undo Redo Copy Line Rectangle Text Figure 15: LIVE_SURFACE Properties Dialog You can control your LIVE window after it is created using any of several auxiliary routines. See "LIVE_Tools" on page 694 for an explanation. Syntax LIVE_SURFACE, Data, Data2,... [, /BUFFER] [, DIMENSIONS=[width, height]{normal units}] [, /DOUBLE] [, DRAW_DIMENSIONS=[width, height]{devive units}] [, ERROR=variable] [, /INDEXED_COLOR] [, INSTANCING={-1 | 0 | 1}] [, LOCATION=[x, y]{normal units}] [, /MANAGE_STYLE] [, NAME=structure] [, /NO_DRAW] [, /NO_SELECTION] [, /NO_STATUS] [, /NO_TOOLBAR] [, PARENT_BASE=widget_id | , TLB_LOCATION=[Xoffset, Yoffset]{device units}] [, PREFERENCE_FILE=filename{full path}] [, REFERENCE_OUT=variable] [, RENDERER={0 | 1}] [, REPLACE={structure | {0 | 1 | 2 | 3 | 4}}] [, STYLE=name_or_reference] [, TEMPLATE_FILE=filename] [, TITLE=string] [, WINDOW_IN=string] [, {X | Y}INDEPENDENT=vector] [, {/X | /Y}LOG] [, {X | Y}RANGE=[min, max]{data units}] [, {X | Y}_TICKNAME=array] Arguments Data A vector of data. Up to 25 of these arguments may be specified. If any of the data is stored in IDL variables of type DOUBLE, LIVE_SURFACE uses double-precision to store the data and to draw the result. Keywords BUFFER Set this keyword to bypass the creation of a LIVE window and send the visualization to an offscreen buffer. The WINDOW field of the reference structure returned by the REFERENCE_OUT keyword will contain the name of the buffer. DIMENSIONS Set this keyword to a two-element, floating-point vector of the form [width, height] specifying the dimensions of the visualization in normalized coordinates. The default is [1.0, 1.0]. DOUBLE Set this keyword to force LIVE_SURFACE to use double-precision to draw the result. This has the same effect as specifying data in the Data argument using IDL variables of type DOUBLE. DRAW_DIMENSIONS Set this keyword equal to a vector of the form [width, height] representing the desired size of the LIVE tools draw widget (in pixels). The default is [452, 452]. Note This default value may be different depending on previous template projects. ERROR Set this keyword to a named variable to contain the returned error message (string). An empty string is returned if no errors occurred during the operation. By default, errors are reported via a GUI. Note If a named variable is passed in this keyword and an error occurs, the error GUI will not be displayed. INDEXED_COLOR If set, the indexed color mode will be used. The default is TrueColor. (See Using IDL for more information on color modes.) INSTANCING Set this keyword to 1 to instance drawing on, or 0 to turn it off. The default (-1) is to use instancing if and only if the "software renderer" is being used (see RENDERER). For more information, see "Instancing" in the Objects and Object Graphics manual. LOCATION Set this keyword to a two-element, floating-point vector of the form [X, Y] specifying the location of the visualization (relative to the lower left hand corner within the visualization window) in normalized coordinates. The default is [0.0, 0.0]. Note LOCATION may be adjusted to take into account window decorations. MANAGE_STYLE Set this keyword to have the passed in style item destroyed when the LIVE tool window is destroyed. This keyword will have no effect if the STYLE keyword is not set to a style item. NAME Set this keyword to a structure containing suggested names for the data items to be created for this visualization. See the REPLACE keyword for details on how they will be used. The fields of the structure are as follows. (Any or all of the tags may be set.) Tag Description DATA Dependent Data Name(s) Table 58: Fields of the NAME keyword Tag Description IX Independent X Data Name IY Independent Y Data Name Table 58: Fields of the NAME keyword The default for a field is to use the given variable name. If the variable does not have a name (i.e., is an expression), a default name is automatically generated. The dependent data names will be used in a round-robin fashion if more data than names are input. NO_DRAW Set this keyword to inhibit the visualization window from drawing. This is useful if multiple visualizations and/or annotations are being created via calls to other LIVE_Tools in order to reduce unwanted draws and help speed the display NO_STATUS Set this keyword to prevent the creation of the status bar. NO_TOOLBAR Set this keyword to prevent the creation of the toolbar. PARENT_BASE Set this keyword to the widget ID of an existing base widget to bypass the creation of a LIVE window and create the visualization within the specified base widget. Note The location of the draw widget is not settable. It is expected that the user who wishes to insert a tool into their own widget application will determine the setting from the parent base sent to the tool. Note LIVE_DESTROY on a window is recommended when using PARENT_BASE so that proper memory cleanup is done. Simply destroying the parent base is not sufficient. Note When specifying a PARENT_BASE, that parent base must be running in a non- blocking mode. Putting a LIVE tool into a realized base already controlled by XMANAGER will override the XMANAGER mode to /NO_BLOCK even if blocking had been in effect. REFERENCE_OUT Set this keyword to a variable to return a structure defining the names of the created items. The fields of the structure are shown in the following table. Tag Description WIN Window Name VIS Visualization Name GRAPHIC Graphic Name(s) XAXIS X-Axis Name YAXIS Y-Axis Name ZAXIS Z-Axis Name LEGEND Legend Name DATA Dependent Data Name(s) IX Independent X Data Name IY Independent Y Data Name Table 59: Fields of the LIVE_SURFACE Reference Structure RENDERER Set this keyword to 1 to use the "software renderer", or 0 to use the "hardware renderer". The default (-1) is to use the setting in the IDE (IDL Development Environment) preferences; if the IDE is not running, however, the default is hardware rendering. For more information, see "Hardware vs. Software Rendering" in the Objects and Object Graphics manual. REPLACE Set this keyword to a structure containing tags as listed for the NAME keyword, with scalar values corresponding to the replacement options listed below. (Any or all of the tags may be set.) The replacement settings are used to determine what action to take when an item (such as data) being input would have the same name as one already existing in the given window or buffer (WINDOW_IN). Setting Action Taken 0 New items will be given unique names. 1 Existing items will be replaced by new items (i.e., the old items will be deleted and new ones created). 2 User will be prompted for the action to take. 3 The values of existing items will be replaced. This will cause dynamic updating to occur for any current uses, e.g., a visualization would redraw to show the new value. 4 Default. Option 0 will be used for items that do not have names (e.g., data input as an expression rather than a named variable, with no name provided via the NAME keyword). Option 3 will be used for all named items. Table 60: REPLACE keyword Settings and Action Taken STYLE Set this keyword to either a string specifying a style name created with LIVE_STYLE. TITLE Set this keyword to a string specifying the title to give the main window. It must not already be in use. A default will be chosen if no title is specified. TLB_LOCATION Set this keyword to a two-element vector of the form [Xoffset, Yoffset] specifying the offset (in pixels) of the LIVE window from the upper left corner of the screen. This keyword has no effect if the PARENT_BASE keyword is set. The default is [0, 0]. WINDOW_IN Set this keyword equal to a name (string, case-sensitive) of a LIVE tool window or a LIVE tool buffer, in which to display the visualization. The WIN tag of the REFERENCE_OUT structure from the creation of the LIVE tool will provide the window or buffer name. Window names are also visible in visualization window titlebars. The default is to create a new window. XINDEPENDENT Set this keyword to a vector specifying X values for LIVE_SURFACE. The default is the data's index values. Note Only one independent vector is allowed; all dependent vectors will use the independent vector. YINDEPENDENT Set this keyword to a vector specifying Y values for LIVE_SURFACE. The default is the data's index values. Note Only one independent vector is allowed; all dependent vectors will use the independent vector. XLOG Set this keyword to make the X axis a log axis. The default is 0 (linear axis). YLOG Set this keyword to make the Y axis a log axis. The default is 0 (linear axis). XRANGE Set this keyword equal to a two-element array that defines the minimum and maximum values of the X axis range. The default equals the values computed from the data range. YRANGE Set this keyword equal to a two-element array that defines the minimum and maximum values of the Y axis range. The default equals the values computed from the data range. X_TICKNAME Set this keyword equal to an array of strings to be used to label the tick mark for the X axis. The default equals the values computed from the data range. Y_TICKNAME Set this keyword equal to an array of strings to be used to label the tick mark for the Yaxis. The default equals the values computed from the data range. Example This example visualizes two surface representations. To manipulate any part of the surface, double click on surface to access a graphical user interface: LIVE_SURFACE, tempData, pressureData Note This is a "Live" situation. When data of the same name is used multiple times within the same window, it always represents the same internal data item. For example, if one does the following: Y = indgen(10) LIVE_PLOT, Y, WINDOW_IN=w, DIMENSIONS=d, LOCATION=loc1 Y = indgen(20) LIVE_PLOT, Y, WINDOW_IN=w, DIMENSIONS=d, LOCATION=loc2 The first plot will update to use the Y of the second plot when the second plot is drawn. If the user wants to display 2 "tweaks" of the same data, a different variable name must be used each time, or at least one should be an expression (thus not a named variable). For example: LIVE_PLOT, Y1,... LIVE_PLOT, Y2,... or; LIVE_PLOT, Y,... LIVE_PLOT, myFunc(Y),... In last example, the data of the second visualization will be given a default unique name since an expression rather than a named variable is input. Note The above shows the default behavior for naming and replacing data, which can be overridden using the NAME and REPLACE keywords. See Also SURFACE, SHADE_SURF LIVE_TEXT [Previous Routine] [Next Routine] [List of Routines] NAME: LIVE_TEXT The LIVE_TEXT procedure is an interface for text annotation. You can control your LIVE window after it is created using any of several auxiliary routines. See "LIVE_Tools" on page 694 for an explanation. Syntax LIVE_TEXT[, Text] [, ALIGNMENT=value{0.0 to 1.0}] [, COLOR='color name' ] [, /DIALOG] [, /ENABLE_FORMATTING] [, ERROR=variable] [, FONTNAME=string] [, FONTSIZE=points{9 to 72}] [, /HIDE] [, LOCATION=[x, y]] [, NAME=string] [, /NO_DRAW] [, /NO_SELECTION] [, REFERENCE_OUT=variable] [, TEXTANGLE=value{0.0 to 360.0}] [, VERTICAL_ALIGNMENT=value{0.0 to 1.0}] [, VISUALIZATION_IN=string] [, WINDOW_IN=string] Arguments Text The string to be used for the text annotation. The default is "Text". If Text is an array of strings, each element of the string array will appear on a separate line. Keywords ALIGNMENT Set this keyword to a floating-point value between 0.0 and 1.0 to indicate the horizontal alignment of the text. The alignment scheme is as follows: 1.0---- -----0.5----- ---0.0 Left Middle Right COLOR Set this keyword to a string (case-sensitive) of the foreground color to be used for the text. The default is `Black'. The following colors are available: * Black * Red * Green * Yellow * Blue * Magenta * Cyan * Dark Gray * Light Gray * Brown * Light Red * Light Green * Light Blue * Light Cyan * Light Magenta * White DIALOG Set this keyword to have the text annotation dialog appear. This dialog will fill in known attributes from set keywords. ENABLE_FORMATTING Set this keyword to have LIVE_TEXT interpret "!" (exclamation mark) as font and positioning commands. ERROR Set this keyword to a named variable to contain the returned error message (string). An empty string is returned if no errors occurred during the operation. By default, errors are reported via a GUI. Note If a named variable is passed in this keyword and an error occurs, the error GUI will not be displayed. FONTNAME Set this keyword to a string containing the name of the desired font. The default is Helvetica. FONTSIZE Set this keyword to an integer scalar specifying the font point size to be used. The default is 12. Available point sizes are 9 through 72. HIDE Set this keyword to a boolean value indicating whether this item should be drawn: * 0 = Draw (default) * 1 = Do not draw LOCATION Set this keyword to a two-element, floating-point vector of the form [X, Y] specifying the location of the visualization (relative to the lower left hand corner within the visualization window) in normalized coordinates. The default is [0.5, 0.5]. Note LOCATION may be adjusted to take into account window decorations. NAME Set this keyword equal to a string containing the name to be associated with this item. The name must be unique within the given window or buffer (WINDOW_IN). If not specified, a unique name will be assigned automatically. NO_DRAW Set this keyword to inhibit the visualization window from drawing. This is useful if multiple visualizations and/or annotations are being created via calls to other LIVE_Tools in order to reduce unwanted draws and help speed the display. REFERENCE_OUT Set this keyword to a variable to return a structure defining the names of the created items. The fields of the structure are shown in the following table Tag Description WIN Window Name VIS Visualization Name GRAPHIC Graphic Name the text created Table 61: Fields of the LIVE_TEXT Reference Structure TEXTANGLE Set this keyword to a floating-point value defining the angle of rotation of the text. The valid range is from 0.0 to 360.0. The default is 0.0. VERTICAL_ALIGNMENT Set this keyword to a floating-point value between 0.0 and 1.0 to indicate the vertical alignment of the text baseline. The alignment scheme is as follows: 0.0 Top ... 0.5 Middle ... 1.0 Bottom VISUALIZATION_IN Set this keyword equal to the name (string, case-insensitive) of a LIVE tool visualization. The VIS field from the REFERENCE_OUT keyword from the creation of the LIVE tool will provide the visualization name. If only one visualization is present in the window or buffer (WINDOW_IN), this keyword will default to it. WINDOW_IN Set this keyword equal to a name (string, case-sensitive) of a LIVE tool window or a LIVE tool buffer. The WIN tag of the REFERENCE_OUT structure from the creation of the LIVE tool will provide the window or buffer name. Window names are also visible in visualization window titlebars. If only one LIVE tool window (or buffer) is present in the IDL session, this keyword will default to it. Example LIVE_TEXT, 'My Annotation', WINDOW_IN='Live Plot 2', $ VISUALIZATION_IN='line plot visualization' See Also LIVE_LINE, LIVE_RECT LJLCT [Previous Routine] [Next Routine] [List of Routines] NAME: LJLCT The LJLCT procedure loads standard color tables for LJ-250/252 printer. The color tables are modified only if the device is currently set to "LJ". The default color maps used are for the 90 dpi color palette. There are only 8 colors available at 180 dpi. If the current device is `LJ', the !D.N_COLORS system variable is used to determine how many bit planes are in use (1 to 4). The standard color map for that number of planes is loaded. These maps are described in Chapter 7 of the LJ250/LJ252 Companion Color Printer Programmer Reference Manual, Table 7-5. That manual gives the values scaled from 1 to 100, LJLCT scales them from 0 to 255. This routine is written in the IDL language. Its source code can be found in the file ljlct.pro in the lib subdirectory of the IDL distribution. Syntax LJLCT Example ; Set plotting to the LJ device: SET_PLOT, 'LJ' ; Load the LJ color tables: LJLCT See Also SET_PLOT LL_ARC_DISTANCE [Previous Routine] [Next Routine] [List of Routines] NAME: LL_ARC_DISTANCE The LL_ARC_DISTANCE function returns a two-element vector containing the longitude and latitude [lon, lat] of a point given arc distance (- Arc_Dist ), and azimuth (Az), from a specified location Lon_lat0. Values are in radians unless the keyword DEGREES is set. This routine is written in the IDL language. Its source code can be found in the file ll_arc_distance.pro in the lib subdirectory of the IDL distribution. Syntax Result = LL_ARC_DISTANCE( Lon_lat0, Arc_Dist, Az [, /DEGREES] ) Arguments Lon_lat0 A 2-element vector containing the longitude and latitude of the starting point. Values are assumed to be in radians unless the keyword DEGREES is set. Arc_Dist The arc distance from Lon_lat0. The value must be between - and + . To express distances in arc units, divide by the radius of the globe expressed in the original units. For example, if the radius of the earth is 6371 km, divide the distance in km by 6371 to obtain the arc distance. Az The azimuth from Lon_lat0. The value is assumed to be in radians unless the keyword DEGREES is set. Keywords DEGREES Set this keyword to express all measurements and results in degrees. Example ; Initial point specified in radians: Lon_lat0 = [1.0, 2.0] ; Arc distance in radians: Arc_Dist = 2.0 ; Azimuth in radians: Az = 1.0 Result = LL_ARC_DISTANCE(Lon_lat0, Arc_Dist, Az) PRINT, Result IDL prints: 2.91415 -0.622234 See Also MAP_SET LMFIT [Previous Routine] [Next Routine] [List of Routines] NAME: LMFIT The LMFIT function does a non-linear least squares fit to a function with an arbitrary number of parameters. LMFIT uses the Levenberg-Marquardt algorithm, which combines the steepest descent and inverse-Hessian function fitting methods. The function may be any non-linear function. Iterations are performed until three consecutive iterations fail to change the chi square value by more than the specified tolerance amount, or until a maximum number of iterations have been performed. The LMFIT function returns a vector of values for the dependent variables, as fitted by the function fit. The initial guess of the parameter values should be as close to the actual values as possible or the solution may not converge. Test the value of the variable specified by the CONVERGENCE keyword to determine whether the algorithm converged, failed to converge, or encountered a singular matrix. This routine is written in the IDL language. Its source code can be found in the file lmfit.pro in the lib subdirectory of the IDL distribution. LMFIT is based on the routine mrqmin described in section 15.5 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press, and is used by permission. Syntax Result = LMFIT( X, Y, A [, ALPHA=variable] [, CHISQ=variable] [, CONVERGENCE=variable] [, COVAR=variable] [, /DOUBLE] [, FITA=vector] [, FUNCTION_NAME=string] [, ITER=variable] [, ITMAX=value] [, ITMIN=value] [, MEASURE_ERRORS=vector] [, SIGMA=variable] [, TOL=value] ) Arguments X A row vector of independent variables. LMFIT does not manipulate or use values in X, it simply passes X to the user-written function. Y A row vector containing the dependent variables. A A vector that contains the initial estimate for each coefficient. Upon return, A will contain the final estimates for the coefficients. Keywords ALPHA Set this keyword equal to a named variable that will contain the value of the curvature matrix. CHISQ Set this keyword equal to a named variable that will contain the final value of the chi-square goodness-of-fit. CONVERGENCE Set this keyword equal to a named variable that will indicate whether the LMFIT algorithm converged. The possible returned values are: * 1 = the algorithm converged. * 0 = the algorithm did not converge. * -1 = the algorithm encountered a singular matrix and did not converge. Tip If LMFIT fails to converge, try setting the DOUBLE keyword. COVAR Set this keyword equal to a named variable that will contain the value of the covariance matrix. DOUBLE Set this keyword to force the computations to be performed in double precision. FITA Set this keyword equal to a vector, with as many elements as A, which contains a zero for each fixed parameter, and a non-zero value for elements of A to fit. If FITA is not specified, all parameters are taken to be non-fixed. FUNCTION_NAME Use this keyword to specify the name of the function to fit. If this keyword is omitted, LMFIT assumes that the IDL procedure LMFUNCT is to be used. If LMFUNCT is not already compiled, IDL compiles the function from the file lmfunct.pro, located in the lib subdirectory of the IDL distribution. LMFUNCT is designed to fit a quadratic equation. The function to be fit must be written as an IDL procedure and compiled prior to calling LMFIT. The function must accept a vector X (the independent variables) and a vector A containing the fitted function's parameter values. It must return an A+1- element vector in which the first (zeroth) element is the evaluated function value and the remaining elements are the partial derivatives with respect to each parameter in A. Note The returned value must be of the same data type as the input X value. ITER Set this keyword equal to a named variable that will contain the actual number of iterations which were performed ITMAX Set this keyword equal to the maximum number of iterations. The default is 50. ITMIN Set this keyword equal to the minimum number of iterations. The default is 5. MEASURE_ERRORS Set this keyword to a vector containing standard measurement errors for each point Y[i]. This vector must be the same length as X and Y. Note For Gaussian errors (e.g., instrumental uncertainties), MEASURE_ERRORS should be set to the standard deviations of each point in Y. For Poisson or statistical weighting, MEASURE_ERRORS should be set to SQRT(ABS(Y)). SIGMA Set this keyword to a named variable that will contain the 1-sigma uncertainty estimates for the returned parameters Note If MEASURE_ERRORS is omitted, then you are assuming that your user-supplied model (or the default quadratic) is the correct model for your data, and therefore, no independent goodness-of-fit test is possible. In this case, the values returned in SIGMA are multiplied by SQRT(CHISQ/(N­M)), where N is the number of points in X, and M is the number of coefficients. See section 15.2 of Numerical Recipes in C (Second Edition) for details. TOL Set this keyword to the convergence tolerance. The routine returns when the relative decrease in chi-squared is less than TOL in an iteration. The default is 1.0 x10-6 for single-precision, and 1.0 x10-12 for double-precision. WEIGHTS The WEIGHTS keyword is obsolete and has been replaced by the MEASURE_ERRORS keyword. Code that uses the WEIGHTS keyword will continue to work as before, but new code should use the MEASURE_ERRORS keyword. Note that the definition of the MEASURE_ERRORS keyword is not the same as the WEIGHTS keyword. Using the WEIGHTS keyword, SQRT(1/WEIGHTS[i]) represents the measurement error for each point Y[i]. Using the MEASURE_ERRORS keyword, the measurement error for each point is represented as simply MEASURE_ERRORS[i]. Example In this example, we fit a function of the form: f(x)=a[0] * exp(a[1]*x) + a[2] + a[3] * sin(x) ; First, define a return function for LMFIT: FUNCTION myfunct, X, A bx = A[0]*EXP(A[1]*X) RETURN,[ [bx+A[2]+A[3]*SIN(X)], [EXP(A[1]*X)], [bx*X], $ [1.0] ,[SIN(X)] ] END PRO lmfit_example ; Compute the fit to the function we have just defined. First, ; define the independent and dependent variables: X = FINDGEN(40)/20.0 Y = 8.8 * EXP(-9.9 * X) + 11.11 + 4.9 * SIN(X) measure_errors = 0.05 * Y ; Provide an initial guess for the function's parameters: A = [10.0, -0.1, 2.0, 4.0] fita = [1,1,1,1] ; Plot the initial data, with error bars: PLOTERR, X, Y, measure_errors coefs = LMFIT(X, Y, A, MEASURE_ERRORS=measure_errors, /DOUBLE, $ FITA = fita, FUNCTION_NAME = 'myfunct') ; Overplot the fitted data: OPLOT, X, coefs END See Also CURVEFIT, GAUSSFIT, LINFIT, POLY_FIT, REGRESS, SFIT, SVDFIT LMGR [Previous Routine] [Next Routine] [List of Routines] NAME: LMGR The LMGR function tests whether a particular licensing mode is in effect. The function returns True (1) if the mode specified is in effect, or False (0) otherwise. Different licensing modes are specified by keyword; see the "Keywords" section below for a description of each licensing mode. The LMGR function can also force IDL into time demo mode or report the LMHostid number for the machine in use. For more information on IDL's licensing methods, consult the IDL License Management Guide, which is included in Adobe Acrobat Portable Document Format on your IDL CD-ROM. Syntax Result = LMGR( [, /CLIENTSERVER | , /DEMO | , /EMBEDDED | , /RUNTIME | , /STUDENT | , /TRIAL] [, EXPIRE_DATE=variable] [, /FORCE_DEMO] [, INSTALL_NUM=variable] [, LMHOSTID=variable] [, SITE_NOTICE=variable] ) Arguments None Keywords CLIENTSERVER Set this keyword to test whether the current IDL session is using Client/Server licensing (as opposed to Desktop licensing). DEMO Set this keyword to test whether the current IDL session is running in timed demo mode. Unlicensed copies of IDL and copies running directly from a CD-ROM run in timed demo mode. EMBEDDED Set this keyword to test whether the current IDL session is running in embedded mode. Embedded-mode applications contain a built-in version of the IDL license. Examples of applications running in embedded mode are the IDL demo and the IDL registration program. EXPIRE_DATE Set this keyword to a named variable that will receive a string containing the expiration date of the current IDL session if the session is a trial session. This named variable will be undefined if the IDL session has a permanent license. FORCE_DEMO Set this keyword to force the current session into timed demo mode. Forcing an IDL session into demo mode can be useful if you are testing an application that will be run with an unlicensed copy of IDL. Note that you must exit IDL and restart to return to normal licensed mode after forcing IDL into demo mode. INSTALL_NUM Set this keyword to a named variable that will receive a string containing the installation number of the current IDL session. This named variable will be undefined if the IDL session is unlicensed. LMHOSTID Set this keyword equal to a named variable that will contain a string value representing the LMHostid for the machine in use. The LMHostid is used when creating client/server IDL licenses. This keyword returns the string "0" on machines which do not have a unique LMHostid (Macintoshes and some Windows machines that use Desktop licensing.) RUNTIME Set this keyword to test whether the current IDL session is running in runtime mode. Runtime-mode applications do not provide access to the IDL command line. See Building IDL Applications for additional details on runtime applications. SITE_NOTICE Set this keyword to a named variable that will receive a string containing the site notice of the current IDL session. This named variable will be undefined if the IDL session is unlicensed. STUDENT Set this keyword to test whether the current IDL session is running in student mode. The IDL Student version, which provides a subset of IDL's full functionality, is currently the only product that runs in student mode. TRIAL Set this keyword to test whether the current IDL session is running in trial mode. Trial mode licenses allow IDL to operate for a limited time period (generally 30 days) but do not otherwise restrict functionality. Example Use the following commands to test whether the current IDL session is running in timed demo mode: Result = LMGR(/DEMO) IF (Result GT 0) THEN PRINT, "IDL is in Demo Mode" Use the following commands to generate the LMHostid number for the machine in use: Result = LMGR(LMHOSTID = myId) PRINT, "LMHostid for this machine is: ", myId LNGAMMA [Previous Routine] [Next Routine] [List of Routines] NAME: LNGAMMA The LNGAMMA function returns the logarithm of the gamma function of X. This function is undefined for negative integers. If the argument is double-precision, the result is double-precision. Otherwise, this function yields floating-point results. Syntax Result = LNGAMMA(X) Arguments X The expression for which the logarithm of the gamma function will be evaluated. Example To find the logarithm of the gamma function of 0.5 and store the result in variable A, enter: A = LNGAMMA(0.5) See Also BETA, GAMMA, IBETA, IGAMMA LNP_TEST [Previous Routine] [Next Routine] [List of Routines] NAME: LNP_TEST The LNP_TEST function computes the Lomb Normalized Periodogram of two sample populations X and Y and tests the hypothesis that the populations represent a significant periodic signal against the hypothesis that they represent random noise. The result is a two-element vector containing the maximum peak in the Lomb Normalized Periodogram and its significance. The significance is a value in the interval [0.0, 1.0]; a small value indicates that a significant periodic signal is present. LNP_TEST is based on the routine fasper described in section 13.8 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press, and is used by permission. Syntax Result = LNP_TEST( X, Y [, /DOUBLE] [, HIFAC=scale_factor] [, JMAX=variable] [, OFAC=value] [, WK1=variable] [, WK2=variable] ) Arguments X An n-element integer, single-, or double-precision floating-point vector containing equally or unequally spaced time samples. Y An n-element integer, single-, or double-precision floating-point vector containing amplitudes corresponding to Xi. Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. HIFAC Use this keyword to specify the scale factor of the average Nyquist frequency. The default value is 1. JMAX Use this keyword to specify a named variable that will contain the index of the maximum peak in the Lomb Normalized Periodogram. OFAC Use this keyword to specify the oversampling factor. The default value is 4. WK1 Use this keyword to specify a named variable that will contain a vector of increasing linear frequencies. WK2 Use this keyword to specify a named variable that will contain a vector of values from the Lomb Normalized Periodogram corresponding to the frequencies in WK1. Example This example tests the hypothesis that two sample, n-element populations X and Y represent a significant periodic signal against the hypothesis that they represent random noise: ; Define two n-element sample populations: X = [ 1.0, 2.0, 5.0, 7.0, 8.0, 9.0, $ 10.0, 11.0, 12.0, 13.0, 14.0, 15.0, $ 16.0, 17.0, 18.0, 19.0, 20.0, 22.0, $ 23.0, 24.0, 25.0, 26.0, 27.0, 28.0] Y = [ 0.69502, -0.70425, 0.20632, 0.77206, -2.08339, 0.97806, $ 1.77324, 2.34086, 0.91354, 2.04189, 0.53560, -2.05348, $ -0.76308, -0.84501, -0.06507, -0.12260, 1.83075, 1.41403, $ -0.26438, -0.48142, -0.50929, 0.01942, -1.29268, 0.29697] ; Test the hypothesis that X and Y represent a significant periodic ; signal against the hypothesis that they represent random noise: result = LNP_TEST(X, Y, WK1 = wk1, WK2 = wk2, JMAX = jmax) PRINT, result IDL prints: 4.69296 0.198157 The small value of the significance represents the possibility of a significant periodic signal. A larger number of samples for X and Y would produce a more conclusive result. WK1 and WK2 are both 48-element vectors containing linear frequencies and corresponding Lomb values, respectively. JMAX is the indexed location of the maximum Lomb value in WK2. See Also CTI_TEST, FV_TEST, KW_TEST, MD_TEST, R_TEST, RS_TEST, S_TEST, TM_TEST, XSQ_TEST LOADCT [Previous Routine] [Next Routine] [List of Routines] NAME: LOADCT The LOADCT procedure loads one of 41 predefined IDL color tables. These color tables are defined in the file colors1.tbl, located in the \resource\colors subdirectory of the main IDL directory, unless the FILE keyword is specified. The selected colortable is loaded into the COLORS common block as both the "current" and "original" colortable. If the current device has fewer than 256 colors, the color table data is interpolated to cover the number of colors in the device. This routine is written in the IDL language. Its source code can be found in the file loadct.pro in the lib subdirectory of the IDL distribution. Syntax LOADCT [, Table] [, BOTTOM=value] [, FILE=string] [, GET_NAMES=variable] [, NCOLORS=value] [, /SILENT] Arguments Table The number of the pre-defined color table to load, from 0 to 40. If this value is omitted, a menu of the available tables is printed and the user is prompted to enter a table number. Keywords BOTTOM The first color index to use. LOADCT will use color indices from BOTTOM to BOTTOM+NCOLORS-1. The default is BOTTOM=0. FILE Set this keyword to the name of a colortable file to be used instead of the file colors1.tbl. See MODIFYCT to create and modify colortable files. GET_NAMES Set this keyword to a named variable in which the names of the color tables are returned as a string array. No changes are made to the color table. NCOLORS The number of colors to use. The default is all available colors (this number is stored in the system variable !D.TABLE_SIZE). SILENT If this keyword is set, the Color Table message is suppressed. See Also MODIFYCT, XLOADCT, TVLCT LOCALE_GET [Previous Routine] [Next Routine] [List of Routines] NAME: LOCALE_GET The LOCALE_GET function returns the current locale (string) of the operating platform. Syntax Result = LOCALE_GET( ) Arguments None Keywords None LON64ARR [Previous Routine] [Next Routine] [List of Routines] NAME: LON64ARR The LON64ARR function returns a 64-bit integer vector or array. Syntax Result = LON64ARR( D1, ..., D8 [, /NOZERO] ) 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, LON64ARR sets every element of the result to zero. If NOZERO is set, this zeroing is not performed and LON64ARR executes faster. Example To create L, a 100-element, 64-bit vector with each element set to 0, enter: L = LON64ARR(100) See Also BYTARR, COMPLEXARR, DBLARR, DCOMPLEXARR, FLTARR, INTARR, LONARR, MAKE_ARRAY, STRARR, UINTARR, ULON64ARR, ULONARR LONARR [Previous Routine] [Next Routine] [List of Routines] NAME: LONARR The LONARR function returns a longword integer vector or array. Syntax Result = LONARR( D1, ..., D8 [, /NOZERO] ) Arguments Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. The dimensions of the result. The dimension parameters can be any scalar expression. Up to eight dimensions can be specified. Keywords NOZERO Normally, LONARR sets every element of the result to zero. If NOZERO is set, this zeroing is not performed and LONARR executes faster. Example To create L, a 100-element, longword vector with each element set to 0, enter: L = LONARR(100) See Also BYTARR, COMPLEXARR, DBLARR, DCOMPLEXARR, FLTARR, INTARR, LON64ARR, MAKE_ARRAY, STRARR, UINTARR, ULON64ARR, ULONARR LONG [Previous Routine] [Next Routine] [List of Routines] NAME: LONG The LONG function returns a result equal to Expression converted to longword integer type. Syntax Result = LONG( Expression[, Offset [, Dim1, ..., Dim8]] ) Arguments Expression The expression to be converted to longword integer. Offset Offset from beginning of the Expression data area. Specifying this argument allows fields of data extracted from Expression to be treated as longword integer data. Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. 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 arguments are given, the result is taken to be scalar. When converting from a string argument, it is possible that the string does not contain a valid longword integer and no conversion is possible. The default action in such cases is to print a warning message and return 0. The ON_IOERROR procedure can be used to establish a statement to be jumped to in case of such errors. Example If A contains the floating-point value 32000.0, it can converted to a longword integer and stored in the variable B by entering: B = LONG(A) See Also BYTE, COMPLEX, DCOMPLEX, DOUBLE, FIX, FLOAT, STRING, UINT, ULONG, ULONG64 LONG64 [Previous Routine] [Next Routine] [List of Routines] NAME: LONG64 The LONG64 function returns a result equal to Expression converted to 64-bit integer type. Syntax Result = LONG64( Expression[, Offset [, D1, ..., D8]] ) Arguments Expression The expression to be converted to 64-bit integer. Offset Offset from beginning of the Expression data area. Specifying this argument allows fields of data extracted from Expression to be treated as 64-bit integer data. Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. 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 arguments are given, the result is taken to be scalar. When converting from a string argument, it is possible that the string does not contain a valid integer and no conversion is possible. The default action in such cases is to print a warning message and return 0. The ON_IOERROR procedure can be used to establish a statement to be executed in case of such errors. Example If A contains the floating-point value 32000.0, it can converted to a 64-bit integer and stored in the variable B by entering: B = LONG64(A) See Also BYTE, COMPLEX, DCOMPLEX, DOUBLE, FIX, FLOAT, LONG, STRING, UINT, ULONG, ULONG64 LSODE [Previous Routine] [Next Routine] [List of Routines] NAME: LSODE The LSODE function uses adaptive numerical methods to advance a solution to a system of ordinary differential equations one time-step H, given values for the variables Y and X. Syntax Result = LSODE( Y, X, H, Derivs[, Status] [, ATOL=value] [, RTOL=value] ) Arguments Y A vector of values for Y at X X A scalar value for the initial condition. H A scalar value giving interval length or step size. Derivs A scalar string specifying the name of a user-supplied IDL function that calculates the values of the derivatives Dydx at X. This function must accept two arguments: A scalar floating value X, and one n-element vector Y. It must return an n-element vector result. For example, suppose the values of the derivatives are defined by the following relations: dy0 / dx = ­0.5y0, dy1 / dx = 4.0 ­ 0.3y1 ­ 0.1y0 We can write a function called differential to express these relationships in the IDL language: FUNCTION differential, X, Y RETURN, [-0.5 * Y[0], 4.0 - 0.3 * Y[1] - 0.1 * Y[0]] END Status An index used for input and output to specify the state of the calculation. This argument contains a positive value if the function was successfully completed. Negative values indicate different errors. Input Value Description 1 This is the first call for the problem; initializations will occur. This is the default value. 2 This is not the first call. The calculation is to continue normally. 3 This is not the first call. The calculation is to continue normally, but with a change in input parameters. Table 62: Input Values for Status Note A preliminary call with tout = t is not counted as a first call here, as no initialization or checking of input is done. (Such a call is sometimes useful for the purpose of outputting the initial condition s.) Thus, the first call for which tout t requires STATUS = 1 on input. Output Value Description 1 Nothing occurred. (However, an internal counter was set to detect and prevent repeated calls of this type.) 2 The integration was performed successfully, and no roots were found. 3 The integration was successful, and one or more roots were found. -1 An excessive amount of work was done on this call, but the integration was otherwise successful. To continue, reset STATUS to a value greater than1 and begin again (the excess work step counter will be reset to 0). Table 63: Output Values for Status Output Value Description -2 The precision of the machine being used is insufficient for the requested amount of accuracy. Integration was successful. To continue, the tolerance parameters must be reset, and STATUS must be set to 3. (If this condition is detected before taking any steps, then an illegal input return (STATUS = -3) occurs instead.) -3 Illegal input was detected, before processing any integration steps. If the solver detects an infinite loop of calls to the solver with illegal input, it will cause the run to stop. -4 There were repeated error test failures on one attempted step, before completing the requested task, but the integration was successful. The problem may have a singularity, or the input may be inappropriate. -5 There were repeated convergence test failures on one attempted step, before completing the requested task, but the integration was successful. This may be caused by an inaccurate jacobian matrix, if one is being used. -6 ewt(i) became zero for some i during the integration. Pure relative error control was requested on a variable which has now vanished. Integration was successful. Table 63: Output Values for Status Note Since the normal output value of STATUS is 2, it does not need to be reset for normal continuation. Also, since a negative input value of STATUS will be regarded as illegal, a negative output value requires the user to change it, and possibly other inputs, before calling the solver again. Keywords ATOL A scalar or array value that specifies the absolute tolerance. The default value is 1.0e- 7. Use ATOL = 0.0 (or ATOL[i] = 0.0) for pure relative error control, and use RTOL = 0.0 for pure absolute error control. For an explanation of how to use ATOL and RTOL together, see RTOL below. RTOL A scalar value that specified the relative tolerance. The default value is 1.0e-7. Use RTOL = 0.0 for pure absolute error control, and use ATOL = 0.0 (or ATOL[i] = 0.0) for pure relative error control. The estimated local error in the Y[i] argument will be controlled to be less than ewt[i] = RTOL*abs(Y[i]) + ATOL ; If ATOL is a scalar. ewt[i] = RTOL*abs(Y[i]) + ATOL[i] ; If ATOL is an array. Thus, the local error test passes if, in each component, either the absolute error is less than ATOL (or ATOL[i]), or if the relative error is less than RTOL. Warning Actual, or global, errors might exceed these local tolerances, so choose values for ATOL and RTOL conservatively. Example To integrate the example system of differential equations for one time step, H: PRO LSODETEST ; Define the step size: H = 0.5 ; Define an initial X value: X = 0.0 ; Define initial Y values: Y = [4.0, 6.0] ; Integrate over the interval (0, 0.5): result = LSODE(Y, X, H, 'differential') ; Print the result: PRINT, result END FUNCTION differential, X, Y RETURN, [-0.5 * Y[0], 4.0 - 0.3 * Y[1] - 0.1 * Y[0]] END IDL prints: 3.11523 6.85767 This is the exact solution vector to 5-decimal precision. References 1. Alan C. Hindmarsh, ODEPACK, A Systematized Collection of ODE Solvers, in Scientific Computing, R. S. Stepleman et al. (eds.), North-Holland, Amsterdam, 1983, pp. 55-64. 2. Linda R. Petzold, Automatic Selection of Methods for Solving Stiff and Nonstiff Systems of Ordinary Differential Equations, SIAM J. SCI. STAT. COMPUT. 4 (1983), pp. 136-148. 3. Kathie L. Hiebert and Lawrence F. Shampine, Implicitly Defined Output Points for Solutions of ODE's, Sandia Report SAND80-0180, February, 1980. See Also DERIV, DERIVSIG, RK4 LU_COMPLEX [Previous Routine] [Next Routine] [List of Routines] NAME: LU_COMPLEX The LU_COMPLEX function solves an n by n complex linear system Az = b using LU decomposition. The result is an n-element complex vector z. Alternatively, LU_COMPLEX computes the generalized inverse of an n by n complex array. The result is an n by n complex array. This routine is written in the IDL language. Its source code can be found in the file lu_complex.pro in the lib subdirectory of the IDL distribution. Syntax Result = LU_COMPLEX( A, B [, /DOUBLE] [, /INVERSE] [, /SPARSE] ) Arguments A An n by n complex array. B An n-element right-hand side vector (real or complex). Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. INVERSE Set this keyword to compute the generalized inverse of A. If INVERSE is specified, the input argument B is ignored. SPARSE Set this keyword to convert the input array to row-indexed sparse storage format. Computations are done using the iterative biconjugate gradient method. This keyword is effective only when solving complex linear systems. This keyword has no effect when calculating the generalized inverse. Example ; Define a complex array A and right-side vector B: A = [[COMPLEX(1, 0), COMPLEX(2,-2), COMPLEX(-3,1)], $ [COMPLEX(1,-2), COMPLEX(2, 2), COMPLEX(1, 0)], $ [COMPLEX(1, 1), COMPLEX(0, 1), COMPLEX(1, 5)]] B = [COMPLEX(1, 1), COMPLEX(3,-2), COMPLEX(1,-2)] ; Solve the complex linear system Az = b: Z = LU_COMPLEX(A, B) PRINT, 'Z:' PRINT, Z ; Compute the inverse of the complex array A by supplying a scalar ; for B (in this example -1): inv = LU_COMPLEX(A, B, /INVERSE) PRINT, 'Inverse:' PRINT, inv IDL prints: Z: ( 0.552267, 1.22818)( -0.290371, -0.600974) ( -0.629824, -0.340952) Inverse: ( 0.261521, -0.0303485)( 0.0138629, 0.329337) ( -0.102660, -0.168602) ( 0.102660, 0.168602)( 0.0340952, -0.162982) ( 0.125890, -0.0633196) ( -0.0689397, 0.0108655)( -0.0666916, -0.0438366) ( 0.0614462, -0.161858) See Also CRAMER, CHOLSOL, GS_ITER, LUSOL, SVSOL, TRISOL LUDC [Previous Routine] [Next Routine] [List of Routines] NAME: LUDC The LUDC procedure replaces an n by n array, A, with the LU decomposition of a row-wise permutation of itself. LUDC is based on the routine ludcmp described in section 2.3 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press, and is used by permission. Syntax LUDC, A, Index [, /COLUMN] [, /DOUBLE] [, INTERCHANGES=variable] Arguments A An n by n array of any type except string. Upon output, A is replaced with its LU decomposition. Index An output vector that records the row permutations which occurred as a result of partial pivoting. Keywords COLUMN Set this keyword if the input array A is in column-major format (composed of column vectors) rather than in row-major format (composed of row vectors). DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. INTERCHANGES An output variable that is set to positive 1 if the number of row interchanges was even, or to negative 1 if the number of interchanges was odd. Example See the description of LUSOL for an example using this procedure. See Also LUSOL LUMPROVE [Previous Routine] [Next Routine] [List of Routines] NAME: LUMPROVE The LUMPROVE function uses LU decomposition to iteratively improve an approximate solution X of a set of n linear equations in n unknowns Ax = b. The result is a vector, whose type and length are identical to X, containing the improved solution. LUMPROVE is based on the routine mprove described in section 2.5 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press, and is used by permission. Syntax Result = LUMPROVE( A, Alud, Index, B, X [, /COLUMN] [, /DOUBLE] ) Arguments A The n by n coefficient array of the linear system Ax = b. Alud The n by n LU decomposition of A created by the LUDC procedure. Index An input vector, created by the LUDC procedure, containing a record of the row permutations which occurred as a result of partial pivoting. B An n-element vector containing the right-hand side of the linear system Ax = b. X An n-element vector containing the approximate solution of the linear system Ax = b. Keywords COLUMN Set this keyword if the input array A is in column-major format (composed of column vectors) rather than in row-major format (composed of row vectors). DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. Example This example uses LUMPROVE to improve an approximate solution X to the linear system Ax = B: ; Create coefficient array A: A = [[ 2.0, 1.0, 1.0], $ [ 4.0, -6.0, 0.0], $ [-2.0, 7.0, 2.0]] ; Create a duplicate of A: alud = A ; Define the right-hand side vector B: B = [3.0, -8.0, 10.0] ; Begin with an estimated solution X: X = [.89, 1.78, -0.88] ; Decompose the duplicate of A: LUDC, alud, INDEX ; Compute an improved solution: result = LUMPROVE(A, alud, INDEX, B, X) ; Print the result: PRINT, result IDL prints: 1.00000 2.00000 -1.00000 This is the exact solution vector. See Also GS_ITER, LUDC LUSOL [Previous Routine] [Next Routine] [List of Routines] NAME: LUSOL The LUSOL function is used in conjunction with the LUDC procedure to solve a set of n linear equations in n unknowns Ax = b. The parameter A is input not as the original array, but as its LU decomposition, created by the routine LUDC. The result is an n-element vector whose type is identical to A. LUSOL is based on the routine lubksb described in section 2.3 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press, and is used by permission. Syntax Result = LUSOL(A, Index, B [, /COLUMN] [, /DOUBLE]) Arguments A The n by n LU decomposition of an array created by the LUDC procedure. Index An input vector, created by the LUDC procedure, containing a record of the row permutations which occurred as a result of partial pivoting. B An n-element vector containing the right-hand side of the linear system Ax = b. Keywords COLUMN Set this keyword if the input array A is in column-major format (composed of column vectors) rather than in row-major format (composed of row vectors). DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. Example This example solves the linear system Ax = b using LU decomposition and back substitution: ; Define array A: A = [[ 2.0, 1.0, 1.0], $ [ 4.0, -6.0, 0.0], $ [-2.0, 7.0, 2.0]] ; Define right-hand side vector B: B = [3.0, -8.0, 10.0] ; Decompose A: LUDC, A, INDEX ; Compute the solution using back substitution: result = LUSOL(A, INDEX, B) ; Print the result: PRINT, result IDL prints: 1.00000 2.00000 -1.00000 This is the exact solution vector. See Also CHOLSOL, CRAMER, GS_ITER, LU_COMPLEX, LUDC, SVSOL, TRISOL M_CORRELATE [Previous Routine] [Next Routine] [List of Routines] NAME: M_CORRELATE The M_CORRELATE function computes the multiple correlation coefficient of a dependent variable and two or more independent variables. This routine is written in the IDL language. Its source code can be found in the file m_correlate.pro in the lib subdirectory of the IDL distribution. Syntax Result = M_CORRELATE( X, Y [, /DOUBLE] ) Arguments X An integer, single-, or double-precision floating-point array of m-columns and n-rows that specifies the independent variable data. The columns of this two dimensional array correspond to the n-element vectors of independent variable data. Y An n-element integer, single-, or double-precision floating-point vector that specifies the dependent variable data. Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. Example PRO MCORRELATE_TEST ; Define the independent (X) and dependent (Y) data: X = [[0.477121, 2.0, 13.0], $ [0.477121, 5.0, 6.0], $ [0.301030, 5.0, 9.0], $ [0.000000, 7.0, 5.5], $ [0.602060, 3.0, 7.0], $ [0.698970, 2.0, 9.5], $ [0.301030, 2.0, 17.0], $ [0.477121, 5.0, 12.5], $ [0.698970, 2.0, 13.5], $ [0.000000, 3.0, 12.5], $ [0.602060, 4.0, 13.0], $ [0.301030, 6.0, 7.5], $ [0.301030, 2.0, 7.5], $ [0.698970, 3.0, 12.0], $ [0.000000, 4.0, 14.0], $ [0.698970, 6.0, 11.5], $ [0.301030, 2.0, 15.0], $ [0.602060, 6.0, 8.5], $ [0.477121, 7.0, 14.5], $ [0.000000, 5.0, 9.5]] Y = [97.682, 98.424, 101.435, 102.266, 97.067, 97.397, $ 99.481, 99.613, 96.901, 100.152, 98.797, 100.796, $ 98.750, 97.991, 100.007, 98.615, 100.225, 98.388, $ 98.937, 100.617] ; Compute the multiple correlation of Y on the first column of ; X. The result should be 0.798816. PRINT, 'Multiple correlation of Y on 1st column of X:' PRINT, M_CORRELATE(X[0,*], Y) ; Compute the multiple correlation of Y on the first two columns ; of X. The result should be 0.875872. PRINT, 'Multiple correlation of Y on 1st two columns of X:' PRINT, M_CORRELATE(X[0:1,*], Y) ; Compute the multiple correlation of Y on all columns of X. The ; result should be 0.877197. PRINT, 'Multiple correlation of Y on all columns of X:' PRINT, M_CORRELATE(X, Y) END IDL prints: Multiple correlation of Y on 1st column of X: 0.798816 Multiple correlation of Y on 1st two columns of X: 0.875872 Multiple correlation of Y on all columns of X: 0.877196 See Also A_CORRELATE, CORRELATE, C_CORRELATE, P_CORRELATE, R_CORRELATE MACHAR [Previous Routine] [Next Routine] [List of Routines] NAME: MACHAR The MACHAR function determines and returns machine-specific parameters affecting floating-point arithmetic. Information is returned in the form of a structure with the fields listed below under "MACHAR Fields". MACHAR is based on the routine machar described in section 20.1 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press, and is used by permission. See that section for more details on and sample values of the various parameters returned. Syntax Result = MACHAR( [, /DOUBLE] ) Arguments None Keywords DOUBLE The information returned is normally for single-precision floating-point arithmetic. Specify DOUBLE to see double-precision information. MACHAR Fields The following table lists the fields in the structure returned from the MACHAR function: Field Name Description IBETA The radix in which numbers are represented. A longword integer. IT The number of base-IBETA digits in the floating-point mantissa M. A longword integer. Table 64: MACHAR Fields Field Name Description IRND A code in the range 0 ­ 5 giving information on what type of rounding is done and how underflow is handled. A longword integer. NGRD The number of "guard digits" used when truncating the product of two mantissas. A longword integer. MACHEP The exponent of the smallest power of IBETA that, added to 1.0, gives something different from 1.0. A longword integer. NEGEP The exponent of the smallest power of IBETA that, subtracted from 1.0, gives something different from 1.0. A longword integer. IEXP The number of bits in the exponent. A longword integer. MINEXP The smallest value of IBETA consistent with there being no leading zeros in the mantissa. A longword integer. MAXEXP The smallest positive value of IBETA that causes overflow. A longword integer. EPS The floating-point number IBETAMACHEP, loosely referred to as the "floating-point precision." EPSNEG The floating-point number IBETANEGEP, which is another way of determining floating-point precision. XMIN The floating-point number IBETAMINEXP, generally the magnitude of the smallest usable floating-point value. XMAX The largest usable floating-point value, defined as the number (1-EPSNEG)xIBETAMAXEXP Table 64: MACHAR Fields See Also CHECK_MATH, !VALUES MAKE_ARRAY [Previous Routine] [Next Routine] [List of Routines] NAME: MAKE_ARRAY The MAKE_ARRAY function returns an array of the specified type, dimensions, and initialization. This function enables you to dynamically create an array whose characteristics are not known until run time. Syntax Result = MAKE_ARRAY ( [D1, ..., D8] [, DIMENSION] [, /BYTE | , /COMPLEX | , /DCOMPLEX | , /DOUBLE | , /FLOAT | , /INT | , /L64 | , /LONG | , /OBJ, | , /PTR | , /STRING | , /UINT | , /UL64 | , /ULONG] [, DIMENSION=vector] [, /INDEX] [, /NOZERO] [, SIZE=vector] [, TYPE=type_code] [, VALUE=value] ) Arguments Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. The dimensions of the result. The dimension parameters can be any scalar expression. Up to eight dimensions can be specified. Keywords BYTE Set this keyword to create a byte array. COMPLEX Set this keyword to create a complex, single-precision, floating-point array. DCOMPLEX Set this keyword to create a complex, double-precision, floating-point array. DIMENSION This modified keyword represents a vector of 1 to 8 elements specifying the dimensions of the result. This is equivalent to the array form of the Di plain arguments. A vector of 1 to 8 elements specifying the dimensions of the result. DOUBLE Set this keyword to create a double-precision, floating-point array. FLOAT Set this keyword to create a single-precision, floating-point array. L64 Set this keyword to create a 64-bit integer array. INDEX Set this keyword to initialize the array with each element set to the value of its one- dimensional subscript. INT Set this keyword to create an integer array. LONG Set this keyword to create a longword integer array. NOZERO Set this keyword to prevent the initialization of the array. Normally, each element of the resulting array is set to zero. OBJ Set this keyword to create an object reference array. PTR Set this keyword to create a pointer array. SIZE A size vector specifying the type and dimensions of the result. The format of a size vector is given in the description of the SIZE function. STRING Set this keyword to create a string array. TYPE The type code to set the type of the result. See the description of the SIZE function for a list of IDL type codes. UINT Set this keyword to create an unsigned integer array. UL64 Set this keyword to create an unsigned 64-bit integer array. ULONG Set this keyword to create an unsigned longword integer array. VALUE The value to initialize each element of the resulting array. VALUE can be a scalar of any type including structure types. The result type is taken from VALUE unless one of the other keywords that specify a type is also set. In that case, VALUE is converted to the type specified by the other keyword prior to initializing the resulting array. Example To create a 3-element by 4-element integer array with each element set to the value 5, enter: M = MAKE_ARRAY(3, 4, /INTEGER, VALUE = 5) See Also BYTARR, COMPLEXARR, DBLARR, DCOMPLEXARR, FLTARR, INTARR, LON64ARR, LONARR, STRARR, UINTARR, ULON64ARR, ULONARR MAKE_DLL [Previous Routine] [Next Routine] [List of Routines] NAME: MAKE_DLL The MAKE_DLL procedure builds a sharable library from C language code which is suitable for use by IDL's dynamic linking features such as CALL_EXTERNAL, LINKIMAGE, and dynamically loadable modules (DLMs). MAKE_DLL reduces the complexity of building sharable libraries by providing a stable cross-platform method for the user to describe the desired library, and issuing the necessary operating system commands to build the library. Note MAKE_DLL is supported under UNIX, VMS, and Microsoft Windows, but is not available for the Macintosh. Although MAKE_DLL is very convenient, it is not intended for use as a general purpose compiler. Instead, MAKE_DLL is specifically targeted to solving the most common IDL dynamic linking problem: building a sharable library from C language source files that are usable by IDL. Because of this, the following requirements apply: * You must have a C compiler installed on your system. It is easiest to use the compiler used to build IDL, because MAKE_DLL already knows how to use that compiler without any additional configuring. To determine which compiler was used, query the !MAKE_DLL system variable with a print statement such as the following: PRINT, !MAKE_DLL.COMPILER_NAME * MAKE_DLL only compiles programs written in the C language; it does not understand Fortran, C++, or any other languages. * MAKE_DLL provides only the functionality necessary to build C code intended to be linked with IDL. Not every possible option supported by the C compiler or system linker is addressed, only those commonly needed by IDL- related C code. MAKE_DLL solves the most common IDL-centric problem of linking C code with IDL. To do more than this or to use a different language requires a system-specific building process (e.g. make files, projects, etc...). Syntax MAKE_DLL, InputFiles [, OutputFile], ExportedRoutineNames [, CC=string] [, COMPILE_DIRECTORY=path] [, DLL_PATH=variable] [, EXPORTED_DATA=string] [, EXTRA_CFLAGS=string] [, EXTRA_LFLAGS=string] [, INPUT_DIRECTORY=path] [, LD=string] [, /NOCLEANUP] [, OUTPUT_DIRECTORY=path] [, /SHOW_ALL_OUTPUT] [, /VERBOSE] VMS-Only Keywords: [ /VAX_FLOAT] Arguments InputFiles A string (scalar or array) giving the names of the input C program files to be compiled by MAKE_DLL. These names should not include any directory path information or the .c suffix, they are simply the base file names. The input directory is specified using the INPUT_DIRECTORY keyword, and the .c file suffix is assumed. OutputFile The base name of the resulting sharable library. This name should not include any directory path information or the sharable library suffix, which differs between platforms (for example: .so, .a, .sl, .exe, .dll). The output directory can be specified using the OUTPUT_DIRECTORY keyword. If the OutputFile argument is omitted, the first name given by InputFile is used as the base name of output file. ExportedRoutineNames A string (scalar or array) specifying the names of the routines to be exported (i.e., are visible for linking) from the resulting sharable library. Keywords CC If present, a template string to use in generating the C compiler commands to compile InputFiles. If CC is not specified, the value given by the !MAKE_DLL.CC system variable is used by default. See the discussion of !MAKE_DLL for a description of how to write the format string for CC. COMPILE_DIRECTORY To build a sharable library, MAKE_DLL requires a place to create the necessary intermediate files and possibly the final library itself. If COMPILE_DIRECTORY is specified, the directory specified is used. If COMPILE_DIRECTORY is not specified, the directory given by the !MAKE_DLL.COMPILE_DIRECTORY system variable is used. DLL_PATH If present, the name of a variable to receive the complete file path for the newly created sharable library. The location of the resulting sharable library depends on the setting of the OUTPUT_DIRECTORY or COMPILE_DIRECTORY keywords as well as the !MAKE_DLL.COMPILE_DIRECTORY system variable, and different platforms use different file suffixes to indicate sharable libraries. Use of the DLL_PATH keyword makes it possible to determine the resulting file path in a simple and portable manner. EXPORTED_DATA A string (scalar or array) containing the names of variables to be exported (i.e., are visible for linking) from the resulting sharable library. EXTRA_CFLAGS If present, a string supplying extra options for the command used to execute the C compiler to compile the files given by InputFiles. This keyword is frequently used to specify header file include directories. This text is inserted in place of the %X format code in the compile string. See the discussion of the CC keyword and !MAKE_DLL.CC system variable for more information. EXTRA_LFLAGS If present, a string supplying extra options for the command used to execute the linker when combining the object files to produce the sharable library. This keyword is frequently used to specify libraries to be included in the link, and is inserted in place of the %X format code in the linker string. See the discussion of the LD keyword and !MAKE_DLL.LD system variable for more information. INPUT_DIRECTORY If present, the path to the directory containing the source C files listed in InputFiles. If INPUT_DIRECTORY is not specified, the directory given by COMPILE_DIRECTORY is assumed to contain the files. LD If present, a template string to use when generating the linker command to generate the resulting sharable library. If LD is not specified, the value given by the !MAKE_DLL.LD system variable is used by default. See the discussion of !MAKE_DLL for a description of how to write the format string for LD. NOCLEANUP To produce a sharable library, MAKE_DLL produces several intermediate files: 1. A shell script (UNIX), command file (VMS), or batch file (Windows) that is then executed via SPAWN to build the library. 2. A linker options file. This file is used to control the linker. MAKE_DLL uses it to cause the routines given by the ExportedRoutineNames argument (and EXPORTED_DATA keyword) to be exported from the resulting sharable library. The general platform terminology is shown below. Platform Linker Options File Terminology UNIX export file, or linker map file VMS linker options file (.OPT) Windows a .DEF file Table 65: Platform Terminology for Linker Options File 3. Object files, resulting from compiling the source C files given by the InputFiles argument. 4. A log file that captures the output from executing the script, and which can be used for debugging in case of error. By default, MAKE_DLL deletes all of these intermediate files once the sharable library has been successfully built. Setting the NOCLEANUP keyword prevents MAKE_DLL from removing them. Note Set the NOCLEANUP keyword (possibly in conjunction with VERBOSE) for trouble shooting, or to read the files for additional information on how MAKE_DLL works. OUTPUT_DIRECTORY By default, MAKE_DLL creates the resulting sharable library in the compile directory specified by the COMPILE_DIRECTORY keyword or the !MAKE_DLL.COMPILE_DIRECTORY system variable. The OUTPUT_DIRECTORY keyword can be used to override this and explicitly specify where the library file should go. SHOW_ALL_OUTPUT MAKE_DLL normally produces no output unless an error prevents successful building of the sharable library. Set SHOW_ALL_OUTPUT to see all output produced by the spawned process building the library. VERBOSE If set, VERBOSE causes MAKE_DLL to issue informational messages as it carries out the task of building the sharable library. These messages include information on the intermediate files created to build the library and how they are used. VMS-Only Keywords This keyword is for VMS platforms only, and is ignored on all other platforms. VAX_FLOAT If set, specifies the sharable library to be compiled for VAX F (single) or D (double) floating point formats. The default is to use the IEEE format used by IDL. Example 1 Testmodule DLM The IDL distribution contains an example of a simple DLM (dynamically loadable module) in the external/dlm subdirectory. This example consists of a single C source file, and the desired sharable library exports a single function called IDL_Load. The following MAKE_DLL statement builds this sharable library, leaving the resulting file in the directory given by !MAKE_DLL.COMPILE_DIRECTORY: ; Locate the source file: INDIR = FILEPATH('', SUBDIRECTORY=['external', 'dlm']) ; Build the sharable library: MAKE_DLL, 'testmodule', 'IDL_Load', INPUT_DIRECTORY=INDIR Example 2 Using GCC IDL is built with the standard vendor-supported C compiler in order to get maximum integration with the target system. MAKE_DLL assumes that you have the same compiler installed on your system and its defaults are targeted to use it. To use other compilers, you tell MAKE_DLL how to use them. For example, many IDL users have the gcc compiler installed on their systems. This example (tested under 32-bit Solaris 7 using gcc 2.95.2) shows how to use gcc to build the testmodule sharable library from the previous example: ; We need the include directory for the IDL export.h header ; file. One way to get this is to extract it from the ; !MAKE_DLL system variable using the STREGEX function INCLUDE=STREGEX(!MAKE_DLL.CC, '-I[^ ]+', /EXTRACT) ; Locate the source file INDIR = FILEPATH('', SUBDIRECTORY=['external', 'dlm']) ; Build the sharable library, using the CC keyword to specify gcc: MAKE_DLL, 'testmodule', 'IDL_Load', INPUT_DIRECTORY=INDIR, $ CC='gcc -c -fPIC '+ INCLUDE + '%C -o %O' See Also !MAKE_DLL MAP_2POINTS [Previous Routine] [Next Routine] [List of Routines] NAME: MAP_2POINTS The MAP_2POINTS function returns parameters such as distance, azimuth, and path relating to the great circle or rhumb line connecting two points on a sphere. This routine is written in the IDL language. Its source code can be found in the file map_2points.pro in the lib subdirectory of the IDL distribution. Syntax Result = MAP_2POINTS( lon0, lat0, lon1, lat1 [, DPATH=value | , /METERS | , /MILES | , NPATH=integer{2 or greater} | , /PARAMETERS | , RADIUS=value] [, /RADIANS] [, /RHUMB] ) Return Value This function returns a two-element vector containing the distance and azimuth of the great circle or rhumb line connecting the two points, P0 to P1, in the specified angular units, unless one or more of the keywords NPATH, DPATH, METERS, MILES, PARAMETERS, or RADIUS is specified. See the keyword descriptions for the return value associated with each of these keywords. If MILES, METERS, or RADIUS is not set, distances are angular distance, from 0 to 180 degrees (or 0 to !DPI if the RADIANS keyword is set). Azimuth is measured in degrees or radians, east of north. Arguments Lon0, Lat0 Longitude and latitude of the first point, P0. Lon1, Lat1 Longitude and latitude of the second point, P1. Keywords DPATH Set this keyword to a value specifying the maximum angular distance between the points on the path in the prevalent units, degrees or radians. METERS Set this keyword to return the distance between the two points in meters, calculated using the Clarke 1866 equatorial radius of the earth. MILES Set this keyword to return the distance between the two points in miles, calculated using the Clarke 1866 equatorial radius of the earth. NPATH Set this keyword to a value specifying the number of points to return. If this keyword is set, the function returns a (2, NPATH) array containing the longitude/latitude of the points on the great circle or rhumb line connecting P0 and P1. For a great circle, the points will be evenly spaced in distance, while for a rhumb line, the points will be evenly spaced in longitude. Note This keyword must be set to an integer of 2 or greater. PARAMETERS Set this keyword to return the parameters determining the great circle connecting the two points, [sin(c), cos(c), sin(az), cos(az)], where c is the great circle angular distance, and az is the azimuth of the great circle at P0, in degrees east of north. RADIANS Set this keyword if inputs and angular outputs are to be specified in radians. The default is degrees. RADIUS Set this keyword to a value specifying the radius of the sphere to be used to calculate the distance between the two points. If this keyword is specified, the function returns the distance between the two points calculated using the given radius. RHUMB Set this keyword to return the distance and azimuth of the rhumb line connecting the two points, P0 to P1. The default is to return the distance and azimuth of the great circle connecting the two points. A rhumb line is the line of constant direction connecting two points. Examples The following examples use the geocoordinates of two points, Boulder and London: B = [ -105.19, 40.02] ;Longitude, latitude in degrees. L = [ -0.07, 51.30] Example 1 Print the angular distance and azimuth, from B, of the great circle connecting the two points: PRINT, MAP_2POINTS(B[0], B[1], L[0], L[1]) IDL prints 67.854333 40.667833 Example 2 Print the angular distance and course (azimuth), connecting the two points: PRINT, MAP_2POINTS(B[0], B[1], L[0], L[1],/RHUMB) IDL prints 73.966283 81.228057 Example 3 Print the distance in miles between the two points: PRINT, MAP_2POINTS(B[0], B[1], L[0], L[1],/MILES) IDL prints 4693.5845 Example 4 Print the distance in miles along the rhumb line connecting the two points: PRINT, MAP_2POINTS(B[0], B[1], L[0], L[1], /MILES, /RHUMB) IDL prints 5116.3571 Example 5 Display a map containing the two points, and annotate the map with both the great circle and the rhumb line path between the points, drawn at one degree increments: MAP_SET, /MOLLWEIDE, 40,-50, /GRID, SCALE=75e6,/CONTINENTS PLOTS, MAP_2POINTS(B[0], B[1], L[0], L[1],/RHUMB, DPATH=1) PLOTS, MAP_2POINTS(B[0], B[1], L[0], L[1],DPATH=1) This displays the following map: Figure 16: Map annotated with great circle and rhumb line path between Boulder and London, drawn at one degree increments. See Also MAP_SET MAP_CONTINENTS [Previous Routine] [Next Routine] [List of Routines] NAME: MAP_CONTINENTS The MAP_CONTINENTS procedure draws continental boundaries, filled continents, political boundaries, coastlines, and/or rivers, over an existing map projection established by MAP_SET. Outlines can be drawn in low or high-resolution (if the optional high-resolution CIA World Map database is installed). If MAP_CONTINENTS is called without any keywords, it draws low-resolution, unfilled continent outlines. MAP_SET must be called before MAP_CONTINENTS to establish the projection type, the center of the projection, polar rotation and geographic limits. Syntax MAP_CONTINENTS [, /COASTS] [, COLOR=index] [, /CONTINENTS] [, /COUNTRIES] [ ,FILL_CONTINENTS={1 | 2}[, ORIENTATION=value]] [, /HIRES] [, LIMIT=vector] [, MLINESTYLE={0 | 1 | 2 | 3 | 4 | 5}] [, MLINETHICK=value] [, /RIVERS] [, SPACING=centimeters] [, /USA] Graphics Keywords: [, /T3D] [, ZVALUE=value{0 to 1}] Keywords COASTS Set this keyword to draw coastlines, islands, and lakes instead of the default continent outlines. Note that if you are using the low-resolution map database (if the HIRES keyword is not set), many islands are drawn even when COASTS is not set. If you are using the high-resolution map database (if the HIRES keyword is set), no islands are drawn unless COASTS is set. COLOR Set this keyword to the color index of the lines being drawn. CONTINENTS Set this keyword to plot the continental boundaries. This is the default, unless COASTS, COUNTRIES, RIVERS and/or USA is set. Note that if you are using the low-resolution map database (if the HIRES keyword is not set), outlines for continents, islands, and lakes are drawn when the CONTINENTS keyword is set. If you are using the high-resolution map database (if the HIRES keyword is set), only continental outlines are drawn when the CONTINENTS keyword is set. To draw islands and lakes when using the high- resolution map database, use the COASTS keyword. COUNTRIES Set this keyword to draw political boundaries as of 1993. FILL_CONTINENTS Set this keyword to 1 to fill continent boundaries with a solid color. The color is set by the COLOR keyword. Set this keyword to 2 to fill continent boundaries with a line fill. For line filling, the COLOR, MLINESTYLE, MLINETHICK, ORIENTATION, and SPACING keywords can be used to control the type of line fill. Note When using this keyword in conjunction with the HIRES keyword, lakes on continents will be filled and islands will not be filled. HIRES Set this keyword to use high-resolution map data instead of the default low-resolution data. This option is only available if you have installed the optional high-resolution map datasets. If the high-resolution data is not available, a warning is printed and the low-resolution data is used instead. This keyword can be used in conjunction with the COASTS, COUNTRIES, FILL_CONTINENTS, and RIVERS keywords. LIMIT Set this keyword to a four-element vector [Latmin, Lonmin, Latmax, Lonmax] to only plot continents that pass through the LIMIT rectangle. The points (Latmin, Lonmin) and (Latmax, Lonmax) are the latitudes and longitudes of two points diagonal from each other on the regionüs boundary. The default is to use the limits from the current map projection. Note Line segments for continents which extend outside of the LIMIT rectangle will still be plotted. MLINESTYLE The line style of the boundaries being drawn. The default is solid lines. Valid linestyles are shown in the table below: Index Linestyle 0 Solid 1 Dotted 2 Dashed 3 Dash Dot 4 Dash Dot Dot 5 Long Dashes Table 66: IDL Linestyles MLINETHICK The thickness of the boundary or fill lines. The default thickness is 1. ORIENTATION Set this keyword to the counterclockwise angle in degrees from horizontal that the line fill should be drawn. The default is 0. This keyword only has effect if the FILL_CONTINENTS keyword is set to 2. RIVERS Set this keyword to draw rivers. SPACING Set this keyword to the spacing, in centimeters, for a line fill. This keyword only has effect if the FILL_CONTINENTS keyword is set to 2. The default is 0.5 centimeters. USA Set this keyword to draw borders for each state in the United States in addition to continental boundaries. Graphics Keywords Accepted See Appendix C, "Graphics Keywords", for descriptions of graphics and plotting keywords not listed above. T3D, ZVALUE. Example The following example demonstrates the use of map outlines to embellish a map projection: ; Handle TrueColor displays: DEVICE, DECOMPOSED=0 ; Load discrete color table: tek_color ; Match color indices to colors we want to use: black=0 & white=1 & red=2 green=3 & dk_blue=4 & lt_blue=5 ; Set up an orthographic projection centered over the north ; Atlantic.Fill the hemisphere with dark blue. Specify black ; gridlines: MAP_SET, /ORTHO, 40, -30, 23, /ISOTROPIC, $ /HORIZON, E_HORIZON={FILL:1, COLOR:dk_blue}, $ /GRID, COLOR=black ; Fill the continent boundaries with solid white: MAP_CONTINENTS, /FILL_CONTINENTS, COLOR=white ; Overplot coastline data: MAP_CONTINENTS, /COASTS, COLOR=black ; Add rivers, in light blue: MAP_CONTINENTS, /RIVERS, COLOR=lt_blue ; Show national borders: MAP_CONTINENTS, /COUNTRIES, COLOR=red, MLINETHICK=2 See Also MAP_GRID, MAP_IMAGE, MAP_PATCH, MAP_SET MAP_GRID [Previous Routine] [Next Routine] [List of Routines] NAME: MAP_GRID The MAP_GRID procedure draws the graticule of parallels and meridians, according to the specifications established by MAP_SET. MAP_SET must be called before MAP_GRID to establish the projection type, the center of the projection, polar rotation and geographical limits. Syntax MAP_GRID [, /BOX_AXES | [, CLIP_TEXT=0] [, LATALIGN=value{0.0 to 1.0}] [, LONALIGN=value{0.0 to 1.0}] [, LATLAB=longitude] [, LONLAB=latitude] [, ORIENTATION=clockwise_degrees_from_horiz]] [, CHARSIZE=value] [, COLOR=index] [, /FILL_HORIZON] [, GLINESTYLE={0 | 1 | 2 | 3 | 4 | 5}] [, GLINETHICK=value] [, /HORIZON] [, INCREMENT=value] [, LABEL=n{label_every_nth_gridline}] [, LATDEL=degrees] [, LATNAMES=array, LATS=vector] [, LONDEL=degrees] [, LONNAMES=array, LONS=vector] [, /NO_GRID] Graphics Keywords: [, /T3D] [, ZVALUE=value{0 to 1}] Keywords BOX_AXES Set this keyword to create box-style axes for map plots where the parallels intersect the sides, and the meridians intersect the bottom and top edges of the box. CHARSIZE Set this keyword to the size of the characters used for the labels. The default is 1. CLIP_TEXT Set this keyword to a zero value to turn off clipping of text labels. By default, text labels are clipped. This keyword is ignored if the BOX_AXES keyword is set. COLOR Set this keyword to the color index for the grid lines. FILL_HORIZON Set this keyword to fill the current map_horizon. GLINESTYLE If set, the line style used to draw the grid of parallels and meridians. See "LINESTYLE" on page 2405 for a list of available linestyles. The default index is 1, drawing a dotted line. GLINETHICK Set this keyword to the thickness of the grid lines. Default is 1. HORIZON Set this keyword to draw the current map horizon. INCREMENT Set this keyword to the spacing between graticle points. LABEL Set this keyword to label the parallels and meridians with their corresponding latitudes and longitudes. Setting this keyword to an integer will cause every LABEL gridline to be labeled (that is, if LABEL=3 then every third gridline will be labeled). The starting point for determining which gridlines are labeled is the minimum latitude or longitude (-180 to 180), unless the LATS or LONS keyword is set to a single value. In this case, the starting point is the value of LATS or LONS. LATALIGN This keyword controls the alignment of the text baseline for latitude labels. A value of 0.0 left justifies the label, 1.0 right justifies it, and 0.5 centers it. This keyword is ignored if the BOX_AXES keyword is set. LATDEL Set this keyword equal to the spacing (in degrees) between parallels of latitude in the grid. If this keyword is not set, a suitable value is determined from the current map projection. LATLAB The longitude at which to place latitude labels. The default is the center longitude on the map. This keyword is ignored if the BOX_AXES keyword is set. LATNAMES Set this keyword equal to an array specifying the names to be used for the latitude labels. By default, this array is automatically generated in units of degrees. The LATNAMES array can be either type string or any single numeric type, but should not be of mixed type. When LATNAMES is specified, the LATS keyword must also be specified. The number of elements in the two arrays need not be equal. If there are more elements in the LATNAMES array than in the LATS array, the extra LATNAMES are ignored. If there are more elements in the LATS array than in the LATNAMES array, labels in degrees will be automatically provided for the missing latitude labels. The LATNAMES keyword can be also used when the LATS keyword is set to a single value. It this case, the first label supplied will be used at the specified latitude; subsequent names will be placed at the next latitude line to the north, wrapping around the globe if appropriate. Caution should be used when using LATNAMES in conjunction with a single LATS value, since the number of visible latitude gridlines is dependent on many factors. LATS Set this keyword equal to a one or more element vector of latitudes for which lines will be drawn (and optionally labeled). If LATS is omitted, appropriate latitudes will be generated based on the value of the (optional) LATDEL keyword. If LATS is set to a single value, that latitude and a series of automatically generated latitudes will be drawn (and optionally labeled). Automatically generated latitudes have the values: [...,LATS-LATDEL,LATS,LATS+LATDEL,...] over the extent of the map. If LATS is a single value, that value is taken to be the starting point for labelling (See the LABEL keyword). LONALIGN This keyword controls the alignment of the text baseline for longitude labels. A value of 0.0 left justifies the label, 1.0 right justifies it, and 0.5 centers it. This keyword is ignored if the BOX_AXES keyword is set. LONDEL Set this keyword equal to the spacing (in degrees) between meridians of longitude in the grid. If this keyword is not set, a suitable value is determined from the current map projection. LONLAB The latitude at which to place longitude labels. The default is the center latitude on the map. This keyword is ignored if the BOX_AXES keyword is set. LONNAMES Set this keyword equal to an array specifying the names to be used for the longitude labels. By default, this array is automatically generated in units of degrees. The LONNAMES array can be either type string or any single numeric type, but should not be of mixed type. When LONNAMES is specified, the LONS keyword must also be specified. The number of elements in the two arrays need not be equal. If there are more elements in the LONNAMES array than in the LONS array, the extra LONNAMES are ignored. If there are more elements in the LONS array than in the LONNAMES array, labels in degrees will be automatically provided for the missing longitude labels. The LONNAMES keyword can be also used when the LONS keyword is set to a single value. It this case, the first label supplied will be used at the specified longitude; subsequent names will be placed at the next longitude line to the east, wrapping around the globe if appropriate. Caution should be used when using LONNAMES in conjunction with a single LONS value, since the number of visible longitude gridlines is dependent on many factors. LONS Set this keyword equal to a one or more element vector of longitudes for which lines will be drawn (and optionally labeled). If LONS is omitted, appropriate longitudes will be generated based on the value of the (optional) LONDEL keyword. If LONS is set to a single value, that longitudes and a series of automatically generated longitudes will be drawn (and optionally labeled). Automatically generated longitudes have the values: [...,LONS-LONDEL,LONS,LONS+LONDEL,...] over the extent of the map. If LONS is a single value, that value is taken to be the starting point for labelling (See the LABEL keyword). NO_GRID Set this keyword if you only want labels but not gridlines. ORIENTATION Set this keyword equal to an angle in degrees from horizontal (in the clockwise direction) to rotate the labels. This keyword is ignored if the BOX_AXES keyword is set. Graphics Keywords Accepted See Appendix C, "Graphics Keywords", for descriptions of graphics and plotting keywords not listed above. T3D, ZVALUE. Example The following example creates an orthographic projection, defines which latitudes to label, and provides text labels. Note that the text labels are rotated to match the orientation of the map projection. ; Set up an orthographic projection: MAP_SET, /ORTHO, 10, 20, 30, /ISOTROPIC, /CONTINENTS, /HORIZON ; Define latitudes of interest: lats = [ -80, -45, -30, -20, 0, 15, 27, 35, 45, 55, 75] ; Create string equivalents of latitudes: latnames = strtrim(lats, 2) ; Label the equator: latnames(where(lats eq 0)) = 'Equator' ; Draw the grid: MAP_GRID, LABEL=2, LATS=lats, LATNAMES=latnames, LATLAB=7, $ LONLAB=-2.5, LONDEL=20, LONS=-15, ORIENTATION=-30 See Also MAP_CONTINENTS, MAP_IMAGE, MAP_PATCH, MAP_SET MAP_IMAGE [Previous Routine] [Next Routine] [List of Routines] NAME: MAP_IMAGE The MAP_IMAGE function returns an image (or other dataset) warped to fit the current map projection. This function provides an easy method for displaying geographical data as an image on a map. The MAP_SET procedure should be called prior to calling MAP_IMAGE. MAP_IMAGE works in image (graphic) space. For each destination pixel (when COMPRESS is set to one) MAP_IMAGE calculates the latitude and longitude by applying the inverse map projection. This latitude and longitude are then used to index and interpolate the Image argument, obtaining an interpolated value for the destination pixel. The time required by MAP_IMAGE depends mainly on the number of pixels in the destination and the setting of the COMPRESS parameter. MAP_IMAGE is more efficient than MAP_PATCH when the input data set is large compared to the destination area. If the converse is true, MAP_PATCH is more efficient. For more information, see "Image Display" in Chapter 14 of Using IDL. Syntax Result = MAP_IMAGE( Image [, Startx, Starty [, Xsize, Ysize]] [, LATMIN=degrees{-90 to 90}] [, LATMAX=degrees{-90 to 90}] [, LONMIN=degrees{-180 to 180}] [, LONMAX=degrees{-180 to 180}] [, /BILINEAR] [, COMPRESS=value] [, SCALE=value] [, MAX_VALUE=value] [, MIN_VALUE=value] [, MISSING=value] ) Arguments Image A two-dimensional array containing the image to be overlaid on the map. Startx A named variable that, upon return, contains the X coordinate position where the left edge of the image should be placed on the screen. Starty A named variable that, upon return, contains the Y coordinate position where the left edge of the image should be placed on the screen. Xsize A named variable that, upon return, contains the width of the image expressed in graphic coordinate units. If the current graphics device uses scalable pixels, the values of Xsize and Ysize should be passed to the TV procedure. Ysize A named variable that, upon return, contains the height of the image expressed in graphic coordinate units. If the current graphics device uses scalable pixels, the values of Xsize and Ysize should be passed to the TV procedure. Keywords LATMIN The latitude corresponding to the first row of Image. The default is -90 degrees. Note also that -90 LATMIN < LATMAX 90 . LATMAX The latitude corresponding to the last row of Image. The default value is 90 degrees. Note also that -90 LATMIN < LATMAX 90 . LONMIN The longitude corresponding to the first (leftmost) column of the Image argument. Select LONMIN so that -180 LONMIN 180 . The default value is -180. LONMAX The longitude corresponding to the last (rightmost) column of the Image argument. Select LONMAX so that it is larger than LONMIN. If the longitude of the last column is equal to (LONMIN - (360. /Nx)) MODULO 360, it is assumed that the image covers all longitudes (Nx being the total number of columns in the Image argument). BILINEAR Set this flag to use bilinear interpolation to soften edges in the returned image, otherwise, nearest neighbor sampling is used. COMPRESS This keyword, the interpolation compression flag, controls the accuracy of the results from MAP_IMAGE. The default is 4 for output devices with fixed pixel sizes. The inverse projection transformation is applied to each ith row and column. Setting this keyword to a higher number saves time while lower numbers produce more accurate results. Setting this keyword to 1 solves the inverse map transformation for every pixel of the output image. SCALE Set this keyword to the pixel/graphics scale factor for devices with scalable pixels (e.g., PostScript). The default is 0.02 pixels/graphic coordinate. This setting yields an approximate output image size of 350 x 250. Make this number larger for more resolution (and larger PostScript files and images), or smaller for faster, smaller, and less accurate images. MAX_VALUE Data points with values equal to or greater than this value will be treated as missing data, and will be set to the value specified by the MISSING keyword. MIN_VALUE Data points with values equal to or less than this value will be treated as missing data, and will be set to the value specified by the MISSING keyword. MISSING The pixel value to set areas outside the valid map coordinates. If this keyword is omitted, areas outside the map are set to 255 (white) if the current graphics device is PostScript, otherwise they are set to 0. Example The following lines of code set up an orthographic map projection and warp a simple image to it. ; Create a simple image to be warped: image = BYTSCL(SIN(DIST(400)/10)) ; Display the image so we can see what it looks like before ; warping: TV, image latmin = -65 latmax = 65 ; Left edge is 160 East: lonmin = 160 ; Right edge is 70 West = +360: lonmax = -70 + 360 MAP_SET, 0, -140, /ORTHOGRAPHIC, /ISOTROPIC, $ LIMIT=[latmin, lonmin, latmax, lonmax] result = MAP_IMAGE(image,Startx,Starty, COMPRESS=1, $ LATMIN=latmin, LONMIN=lonmin, $ LATMAX=latmax, LONMAX=lonmax) ; Display the warped image on the map at the proper position: TV, result, Startx, Starty ; Draw continent outlines: MAP_GRID, latdel=10, londel=10, /LABEL, /HORIZON ; Draw gridlines over the map and image: MAP_CONTINENTS, /coasts See Also MAP_CONTINENTS, MAP_GRID, MAP_PATCH, MAP_SET MAP_PATCH [Previous Routine] [Next Routine] [List of Routines] NAME: MAP_PATCH The MAP_PATCH function returns an image (or other dataset) warped to fit the current map projection. Mapping coordinates should be setup via a call to MAP_SET before using MAP_PATCH. MAP_PATCH works in object (data) space. It divides the input data set, Image_Orig, into triangular patches, either directly from the implicit rectangular grid, or by triangulating the data points on the surface of the sphere using the TRIANGULATE procedure. These triangular patches are then projected to the map plane in the image space of the destination array and then interpolated. The time required by MAP_PATCH depends mainly on the number of elements in the input array. MAP_PATCH is more efficient than MAP_IMAGE when the destination area is large compared to the input data set. If the converse is true, MAP_IMAGE is more efficient. This routine is written in the IDL language. Its source code can be found in the file map_patch.pro in the lib subdirectory of the IDL distribution. Syntax Result = MAP_PATCH( Image_Orig [, Lons, Lats] [, LAT0=value] [, LAT1=value] [, LON0=value] [, LON1=value] [, MAX_VALUE=value] [, MISSING=value] [, /TRIANGULATE] [, XSIZE=variable] [, XSTART=variable] [, YSIZE=variable] [, YSTART=variable] ) Arguments Image_Orig A one- or two-dimensional array that contains the data to be overlaid on the map. If the TRIANGULATE keyword is not set, Image_Orig must be a two-dimensional array. Rows and columns must be arranged in increasing longitude and latitude order. Also, the corner points of each cell must be contiguous. This means that the seam of a map must lie on a cell boundary, not in its interior, splitting the cell. Lons An optional vector that contains the longitude value for each column in Image_Orig. If Lons is a one-dimensional vector, longitude (Image_Orig[i,j]) = Lons[i]; if Lons is a two-dimensional vector, longitude (Image_Orig[i,j]) = Lons[i,j]. This argument can be omitted if the longitudes are equally-spaced and the beginning and ending longitudes are specified with the LON0 and LON1 keywords. Lats An optional vector that contains the latitude value for each row in Image_Orig. If Lats is a one-dimensional vector, latitude (Image_Orig[i,j]) = Lats[i]; if Lats is a two- dimensional vector, latitude (Image_Orig[i,j]) = Lats[i,j]. This argument can be omitted if the latitudes are equally-spaced and the beginning and ending latitudes are specified with the LAT0 and LAT1 keywords. Keywords LAT0 The latitude of the first row of data. The default is -90. LAT1 The latitude of the last row of data. The default is +90. LON0 The longitude of the first column of data. The default is -180. LON1 The longitude of the last column of data. The default is 180 - (360/Number-of-Rows) MAX_VALUE The largest data value to be warped. Values in Image_Orig greater than this value are considered missing. Pixels in the output image that correspond to these missing values are set to the value specified by the MISSING keyword. MISSING Set this keyword to a value to be used for areas outside the valid map coordinates (i.e., the "background color"). If the current plotting device is PostScript, the default is 255 (white). Otherwise, the default is 0 (usually black). TRIANGULATE Set this keyword to convert the input data to device space and triangulate them. This keyword must be specified if the connectivity of the data points is not rectangular and monotonic in device space. XSIZE Set this keyword to a named variable in which the width of the output image is returned, in graphic coordinate units. If the current graphics device has scalable pixels (e.g., PostScript), the values returned by XSIZE and YSIZE should be passed to the TV procedure. XSTART Set this keyword to a named variable in which the X coordinate where the left edge of the image should be placed on the screen is returned. YSIZE Set this keyword to a named variable in which the height of the output image is returned, in graphic coordinate units. If the current graphics device has scalable pixels (e.g., PostScript), the values returned by XSIZE and YSIZE should be passed to the TV procedure. YSTART Set this keyword to a named variable in which the Y coordinate where the bottom edge of the image should be placed on the screen is returned. Example ; Form a 24 x 24 dataset on a sphere: n = 24 ; Specify equally gridded latitudes: lat = replicate(180./(n-1),n) # findgen(n) - 90 ; Specify equally gridded longitudes: lon = findgen(n) # replicate(360./(n-1), n) ; Convert to Cartesian coordinates: x = cos(lon * !dtor) * cos(lat * !dtor) y = sin(lon * !dtor) * cos(lat * !dtor) z = sin(lat * !dtor) ; Set interpolation function to scaled distance squared ; from (1,1,0): f = BYTSCL((x-1)^2 + (y-1)^2 + z^2) ; Set up projection: MAP_SET, 90, 0, /STEREO, /ISOTROPIC, /HORIZ ; Grid and display the data: TV, MAP_PATCH(f, XSTART=x0, YSTART=y0), x0, y0 ; Draw gridlines over the map and image: MAP_GRID ; Draw continent outlines: MAP_CONTINENTS ; Draw a horizon line: MAP_HORIZON See Also MAP_CONTINENTS, MAP_GRID, MAP_IMAGE, MAP_SET MAP_PROJ_INFO [Previous Routine] [Next Routine] [List of Routines] NAME: MAP_PROJ_INFO The MAP_PROJ_INFO procedure returns information about the current map and/or the available projections. To establish a current projection, mapping parameters should be setup via a call to MAP_SET. Syntax MAP_PROJ_INFO [, iproj] [, AZIMUTHAL=variable] [, CIRCLE=variable] [, CYLINDRICAL=variable] [, /CURRENT] [, LL_LIMITS=variable] [, NAME=variable] [, PROJ_NAMES=variable] [, UV_LIMITS=variable] [, UV_RANGE=variable] Arguments Iproj The projection index. If the CURRENT keyword is set, then the index of the current map projection is returned in Iproj. Keywords AZIMUTHAL Set this keyword to a named variable that, upon return, will be set to 1 if the projection is azimuthal and 0 otherwise. CIRCLE Set this keyword to a named variable that, upon return, will be set to 1 if the projection is circular or elliptical and 0 otherwise. CURRENT Set this keyword to use the current projection index and return that index in Iproj. CYLINDRICAL Set this keyword to a named variable that, upon return, will be set to 1 if the projection is cylindrical and 0 otherwise. LL_LIMITS Set this keyword to a named variable that will contain the geocoordinate rectangle of the current map in degrees, [Latmin, Lonmin, Latmax, Lonmax]. This range may not always be available, especially if the LIMIT keyword was not specified in the call to MAP_SET. If either or both the longitude and latitude range are not available, the minimum and maximum values will be set to zero. NAME Set this keyword to a named variable that will contain the name of the projection. PROJ_NAMES Set this keyword to a named variable that will contain a string array containing the names of the available projections, ordered by their indices. The first projection name is stored in element one. UV_LIMITS Set this keyword to a named variable that will contain the UV bounding box of the current map, [Umin, Vmin, Umax, Vmax]. UV_RANGE Set this keyword to a named variable that will contain the UV coordinate limits of the selected map projection, [Umin, Vmin, Umax, Vmax]. UV coordinates are mapped to normalized coordinates using the system variables !X.S and !Y.S. These limits are dependent upon the selected projection, but independent of the current map. Example ; Establish a projection MAP_SET, /MERCATOR ;Obtain projection characteristics MAP_PROJ_INFO, /CURRENT, NAME=name, AZIMUTHAL=az, $ CYLINDRICAL=cyl, CIRCLE=cir On return, the variables will be set as follows: AZIM INT = 0 CIRC INT = 0 CYL INT = 1 NAME STRING 'Mercator' See Also MAP_SET MAP_SET [Previous Routine] [Next Routine] [List of Routines] NAME: MAP_SET The MAP_SET procedure establishes the axis type and coordinate conversion mechanism for mapping points on the earth's surface, expressed in latitude and longitude, to points on a plane, according to one of several possible map projections. The type of map projection, the map center, polar rotation and geographical limits can all be customized. The system variable !MAP retains the information needed to effect coordinate conversions to the plane and, inversely, from the projection plane to points on the earth in latitude and longitude. Users should not change the values of the fields in !MAP directly. MAP_SET can also be made to plot the grid of latitude and longitude lines and continental boundaries by setting the keywords GRID and CONTINENTS. Many other types of boundaries can be overplotted on maps using the MAP_CONTINENTS procedure. Note If the graphics device is changed, MAP_SET (and all other mapping calls) must be re-called for the projection to be set up properly for the new device. Syntax MAP_SET [, P0lat, P0lon, Rot] Keywords-Projection Types: [ [, /AITOFF | , /ALBERS | , /AZIMUTHAL | , /CONIC | , /CYLINDRICAL | , /GNOMIC | , /GOODESHOMOLOSINE | , /HAMMER | , /LAMBERT | , /MERCATOR | , /MILLER_CYLINDRICAL | , /MOLLEWIDE | , /ORTHOGRAPHIC | , /ROBINSON | , /SATELLITE | , /SINUSOIDAL | , /STEREOGRAPHIC | , /TRANSVERSE_MERCATOR] | NAME=string] ] Keywords-Map Characteristics: [, /ADVANCE] [, CHARSIZE=value] [, /CLIP] [, COLOR=index] [, /CONTINENTS [, CON_COLOR=index] [, /HIRES]] [, E_CONTINENTS=structure] [, E_GRID=structure] [, E_HORIZON=structure] [, GLINESTYLE={0 | 1 | 2 | 3 | 4 | 5}] [, GLINETHICK=value] [, /GRID] [, /HORIZON] [, LABEL=n{label every nth gridline}] [, LATALIGN=value{0.0 to 1.0}] [, LATDEL=degrees] [, LATLAB=longitude] [, LONDEL=degrees] [, LONLAB=latitude] [, MLINESTYLE={0 | 1 | 2 | 3 | 4 | 5}] [, MLINETHICK=value] [, /NOBORDER] [, /NOERASE] [, REVERSE={0 | 1 | 2 | 3}] [, TITLE=string] [, /USA] [, XMARGIN=value] [, YMARGIN=value] Keywords-Projection Parameters: [, CENTRAL_AZIMUTH=degrees_east_of_north] [, ELLIPSOID=array] [, /ISOTROPIC] [, LIMIT=vector] [, SAT_P=vector] [, SCALE=value] [, STANDARD_PARALLELS=array] Graphics Keywords: [, POSITION=[X0, Y0, X1, Y1]] [, /T3D] [, ZVALUE=value{0 to 1}] Arguments P0lat The latitude of the point on the earth's surface to be mapped to the center of the projection plane. Latitude is measured in degrees North of the equator and P0lat must be in the range: -90 P0lat 90 . If P0lat is not set, the default value is 0. P0lon The longitude of the point on the earth's surface to be mapped to the center of the map projection. Longitude is measured in degrees east of the Greenwich meridian and P0lon must be in the range: -180 P0lon 180 . If P0lon is not set, the default value is zero. Rot Rot is the angle through which the North direction should be rotated around the line L between the earth's center and the point (P0lat, P0lon). Rot is measured in degrees with the positive direction being clockwise rotation around line L. Rot can have values from -180 to 180 . If the center of the map is at the North pole, North is in the direction P0lon + 180 . If the origin is at the South pole, North is in the direction P0lon. The default value of Rot is 0 degrees. Keywords: Projection Types AITOFF Set this keyword to select the Aitoff projection. ALBERS Set this keyword to select the Albers equal-area conic projection. To specify the latitude of the standard parallels, see "STANDARD_PARALLELS" on page 852. AZIMUTHAL Set this keyword to select the azimuthal equidistant projection. CONIC Set this keyword to select Lambert's conformal conic projection with one or two standard parallels. To specify the latitude of the standard parallels, see "STANDARD_PARALLELS" on page 852. This keyword can be used with the ELLIPSOID keyword. CYLINDRICAL Set this keyword to select the cylindrical equidistant projection. Cylindrical is the default map projection. GOODESHOMOLOSINE Set this keyword to select the Goode's Homolosine Projection. The central latitude for this projection is fixed on the equator, 0 degrees latitude. This projection is interrupted, as the inventor originally intended, and is best viewed with the central longitude set to 0. GNOMIC Set this keyword to select the gnomonic projection. If default clipping is enabled, this projection will display a maximum of 60 from the center of the projection area when the center is at either the equator or one of the poles. HAMMER Set this keyword to select the Hammer-Aitoff equal area projection. LAMBERT Set this keyword to select Lambert's azimuthal equal area projection. MERCATOR Set this keyword to select the Mercator projection. Note that this projection will not display regions within 10 of the poles of projection. MILLER_CYLINDRICAL Set this keyword to select the Miller Cylindrical projection. MOLLWEIDE Set this keyword to select the Mollweide projection. NAME Set this keyword to a string indicating the projection that you wish to use. A list of available projections can be found using MAP_PROJ_INFO, PROJ_NAMES=names. This keyword will override any of the individual projection keywords. ORTHOGRAPHIC Set this keyword to select the orthographic projection. Note that this projection will display a maximum of 90 from the center of the projection area. ROBINSON Set this keyword to select the Robinson pseudo-cylindrical projection. SATELLITE Set this keyword to select the satellite projection. For the satellite projection, P0LAT and P0LON represent the latitude and longitude of the sub-satellite point. Three additional parameters, P, Omega, and Gamma (supplied as a three-element vector argument to the SAT_P keyword), are also required. Note Since all meridians and parallels are oblique lines or arcs, the LIMIT keyword must be supplied as an eight-element vector representing four points that delineate the limits of the map. The extent of the map limits, when expressed in latitude/longitude is a complicated polygon, rather than a simple quadrilateral. SINUSOIDAL Set this keyword to select the sinusoidal projection. STEREOGRAPHIC Set this keyword to select the stereographic projection. Note that if default clipping is enabled, this projection will display a maximum of 90 from the center of the projection area. TRANSVERSE_MERCATOR Set this keyword to select the Transverse Mercator projection, also called the UTM or Gauss-Krueger projection. This projection works well with the ellipsoid form. The default ellipsoid is the Clarke 1866 ellipsoid. To change the default ellipsoid characteristics, see "ELLIPSOID" on page 851. Keywords: Map Characteristics ADVANCE Set this keyword to advance to the next frame when the screen is set to display multiple plots. Otherwise the entire screen is erased. CHARSIZE The size of the characters used for the labels. The default is 1. CLIP Set this keyword to clip the map using the map-specific graphics technique. The default is to perform map-specific clipping. Set CLIP=0 to disable clipping. Note Clipping controlled by the CLIP keyword to MAP_SET applies only to the map itself. In order to disable general clipping within the plot window, you must set the system variable !P.NOCLIP=1. For more information, see "NOCLIP" on page 2406. COLOR The color index of the map border in the plotting window. CONTINENTS Set this keyword to plot the continental boundaries. Note that if you are using the low-resolution map database (if the HIRES keyword is not set), outlines for continents, islands, and lakes are drawn when the CONTINENTS keyword is set. If you are using the high-resolution map database (if the HIRES keyword is set), only continental outlines are drawn when the CONTINENTS keyword is set. To draw islands and lakes when using the high-resolution map database, use the COASTS keyword to the MAP_CONTINENTS procedure. CON_COLOR The color index for continent outlines if CONTINENTS is set. E_CONTINENTS Set this keyword to a structure containing extra keywords to be passed to MAP_CONTINENTS. For example, to fill continents, the FILL keyword of MAP_CONTINENTS is set to 1. To fill the continents with MAP_SET, specify E_CONTINENTS={FILL:1}. E_GRID Set this keyword to a structure containing extra keywords to be passed to MAP_GRID. For example, to label every other gridline on a grid of parallels and meridians, the LABEL keyword of MAP_GRID is set to 2. To do the same with MAP_SET, specify E_GRID={LABEL:2}. E_HORIZON Set this keyword to a structure containing extra keywords to be set as modifiers to the HORIZON keyword. Example To draw a Stereographic map, with the sphere filled in color index 3, enter: MAP_SET, 0, 0, /STEREO, /HORIZON, /ISOTROPIC, $ E_HORIZON={FILL:1, COLOR:3} GLINESTYLE Set this keyword to a line style index used to draw the grid of parallels and meridians. See MLINESTYLE for a list of available linestyles. The default is 1, drawing a grid of dotted lines. GLINETHICK Set this keyword to the thickness of the gridlines drawn if the GRID keyword is set. The default is 1. GRID Set this keyword to draw the grid of parallels and meridians. HIRES Set this keyword to use the high-resolution continent outlines when drawing continents. This keyword only has effect if the CONTINENTS keyword is also set. HORIZON Set this keyword to draw a horizon line, when the projection in use permits. The horizon delineates the boundary of the sphere. See E_HORIZON for more options. LABEL Set this keyword to label the parallels and meridians with their corresponding latitudes and longitudes. Setting this keyword to an integer will cause every LABEL gridline to be labeled (that is, if LABEL=3 then every third gridline will be labeled). The starting point for determining which gridlines are labeled is the minimum latitude or longitude (-180 to 180). LATALIGN The alignment of the text baseline for latitude labels. A value of 0.0 left justifies the label, 1.0 right justifies it, and 0.5 centers it. LATLAB The longitude at which to place latitude labels. The default is the center longitude of the map. LATDEL Set this keyword equal to the spacing (in degrees) between parallels of latitude drawn by the MAP_GRID procedure. If this keyword is not set, a suitable value is determined from the current map projection. LONALIGN The alignment of the text baseline for longitude labels. A value of 0.0 left justifies the label, 1.0 right justifies it, and 0.5 centers it. LONDEL Set this keyword equal to the spacing (in degrees) between meridians of longitude drawn by the MAP_GRID procedure. If this keyword is not set, a suitable value is determined from the current map projection. LONLAB The latitude at which to place longitude labels. The default is the center latitude of the map. MLINESTYLE The line style index used for continental boundaries. Linestyles are described in the table below. The default is 0 for solid. Index Linestyle 0 Solid 1 Dotted 2 Dashed 3 Dash Dot 4 Dash Dot Dot 5 Long Dashes Table 67: IDL Linestyles MLINETHICK The line thickness used for continental boundaries. The default is 2. NOBORDER Set this keyword to not draw a border around the map. The map will fill the extent of the plotting region. If NOBORDER is not specified, a margin equalling 1% of the plotting region will be placed between the map and the border. NOERASE Set this keyword to have MAP_SET not erase the current plot window. The default is to erase before drawing the map. REVERSE Set this keyword to one of the following values to reverse the X and/or Y axes: * 0 = no reversal (the default) * 1 = reverse X * 2 = reverse Y * 3 = reverse both. TITLE A string containing the main title for the map. The title appears centered above the map window. USA Set this keyword to draw borders for each state in the United States. XMARGIN A scalar or two-element vector that specifies the vertical margin between the map and screen border in character units. If a scalar is specified, the same margin will be used on both sides of the map. YMARGIN A scalar or two-element vector that specifies in the horizontal margin between the map and screen border in character units. If a scalar is specified, the same margin will be used on the top and bottom of the map. Keywords: Projection Parameters CENTRAL_AZIMUTH Set this keyword to the angle of the central azimuth, in degrees east of North. This keyword can be used with the following projections: Cylindrical, Mercator, Miller, Mollweide, and Sinusoidal. The default is 0 degrees. The pole is placed at an azimuth of CENTRAL_AZIMUTH degrees CCW of North, as specified by the Rot argument. ELLIPSOID Set this keyword to a 3-element array, [a, e2, k0], defining the ellipsoid for the Transverse Mercator or Lambert Conic projections. * a: equatorial radius, in meters. * e2: eccentricity squared. e2 = 2 * f - f2, where f = 1 - b/a (a: equatorial radius, b: polar radius; in meters). * k0: scale on the central meridian. The default is the Clarke 1866 ellipsoid, [6378206.4, 0.00676866, 0.9996]. This keyword can be used with the CONIC keyword. ISOTROPIC Set this keyword to produce a map that has the same scale in the X and Y directions. Note The X and Y axes will be scaled isotropically and then fit within the rectangle defined by the POSITION keyword; one of the axes may be shortened. See "POSITION" on page 2407 for more information. LIMIT A four- or eight-element vector that specifies the limits of the map. As a four-element vector, LIMIT has the form [Latmin, Lonmin, Latmax, Lonmax] that specifies the boundaries of the region to be mapped. (Latmin, Lonmin) and (Latmax, Lonmax) are the latitudes and longitudes of two points diagonal from each other on the region's boundary. As an eight-element vector, LIMIT has the form: [Lat0, Lon0, Lat1, Lon1, Lat2, Lon2, Lat3, Lon3]. These four latitude/longitude pairs describe, respectively, four points on the left, top, right, and bottom edges of the map extent. SAT_P A three-element vector containing three parameters, P, Omega, and Gamma, that must be supplied when using the SATELLITE projection where: * P is the distance of the point of perspective (camera) from the center of the globe, expressed in units of the radius of the globe. * Omega is the downward tilt of the camera, in degrees from the new horizontal. If both Gamma and Omega are 0, a Vertical Perspective projection results. * Gamma is the angle, expressed in degrees clockwise from north, of the rotation of the projection plane. SCALE Set this keyword to construct an isotropic map with the given scale, set to the ratio of 1:scale. If SCALE is not specified, the map is fit to the window. The typical scale for global maps is in the ratio of between 1:100 million and 1:200 million. For continents, the typical scale is in the ratio of approximately 1:50 million. For example, SCALE=100E6 sets the scale at the center of the map to 1:100 million, which is in the same ratio as 1 inch to 1578 miles (1 cm to 1000 km). STANDARD_PARALLELS Set this keyword to a one- or two-element array defining, respectively, one or two standard parallels for conic projections. Graphics Keywords Accepted See Appendix C, "Graphics Keywords", for descriptions of graphics and plotting keywords not listed above. POSITION, T3D, ZVALUE. Examples To draw a Stereographic map, with the sphere filled in color index 3: MAP_SET, 0, 0, /STEREO, /HORIZON, /ISOTROPIC, E_HORIZON={FILL:1, COLOR:3} See Also MAP_CONTINENTS, MAP_GRID, MAP_IMAGE MATRIX_MULTIPLY [Previous Routine] [Next Routine] [List of Routines] NAME: MATRIX_MULTIPLY The MATRIX_MULTIPLY function calculates the IDL # operator of two (possibly transposed) arrays. The transpose operation (if desired) is done simultaneously with the multiplication, thus conserving memory and increasing the speed of the operation. If the arrays are not transposed, then MATRIX_MULTIPLY is equivalent to using the # operator. Syntax Result = MATRIX_MULTIPLY( A, B [, /ATRANSPOSE] [, /BTRANSPOSE] ) Return Value The type for the result depends upon the input type. For byte or integer arrays, the result has the type of the next-larger integer type that could contain the result (for example, byte, integer, or long input returns type long integer). For floating-point, the result has the same type as the input. For the case of no transpose, the resulting array has the same number of columns as the first array and the same number of rows as the second array. The second array must have the same number of columns as the first array has rows. Note If A and B arguments are vectors, then C = MATRIX_MULTIPLY(A, B) is a matrix with Cij = AiBj. Mathematically, this is equivalent to the outer product, usually denoted by A . Arguments A The left operand for the matrix multiplication. Dimensions higher than two are ignored. B The right operand for the matrix multiplication. Dimensions higher than two are ignored. Keywords ATRANSPOSE Set this keyword to multiply using the transpose of A. BTRANSPOSE Set this keyword to multiply using the transpose of B. The # Operator vs. MATRIX_MULTIPLY The following table illustrates how various operations are performed using the # operator versus the MATRIX_MULTIPLY function: # Operator Function A # B MATRIX_MULTIPLY(A, B) transpose(A) # B MATRIX_MULTIPLY(A, B, /ATRANSPOSE) A # transpose(B) MATRIX_MULTIPLY(A, B, /BTRANSPOSE) transpose(A) # transpose(B) MATRIX_MULTIPLY(A, B, /ATRANSPOSE, /BTRANSPOSE) Table 68: The # Operator vs. MATRIX_MULTIPLY Note MATRIX_MULTIPLY can also be used in place of the ## operator. For example, A ## B is equivalent to MATRIX_MULTIPLY(B, A), and A ## TRANSPOSE(B) is equivalent to MATRIX_MULTIPLY(B, A, /ATRANSPOSE). MAX [Previous Routine] [Next Routine] [List of Routines] NAME: MAX The MAX function returns the value of the largest element of Array. The type of the result is the same as the type of Array. Syntax Result = MAX( Array [, Max_Subscript] [, SUBSCRIPT_MIN] [, DIMENSION] [, MIN=variable] [, /NAN] ) Arguments Array The array to be searched. Max_Subscript A named variable that, if supplied, is converted to a long integer containing the one- dimensional subscript of the maximum element. Otherwise, the system variable !C is set to the one-dimensional subscript of the maximum element. Keywords SUBSCRIPT_MIN A named variable that, if supplied, is converted to an integer containing the one-dimensional subscript of the minimum element, the value of which is available via the MIN keyword. DIMENSION Set this new keyword to the dimension over which to find the maximum values for an array. If this keyword is not present or is zero, then the maximum is found over the entire array. If this keyword is present, then the return values for Result, Max_Subscript, MIN, and SUBSCRIPT_MIN will all be arrays of one dimension less than the input array. For example, if the dimensions of Array are N1, N2, N3, and DIMENSION is 2, the dimensions of the result are (N1, N3), and element (i,j) of the result contains the maximum value of Array[i, *, j]. MIN A named variable to receive the value of the minimum array element. If you need to find both the minimum and maximum array values, use this keyword to avoid scanning the array twice with separate calls to MAX and MIN. NAN Set this keyword to cause the routine to check for occurrences of the IEEE floating- point value NaN in the input data. Elements with the value NaN are treated as missing data. (See "Special Floating-Point Values" in Chapter 17 of Building IDL Applications for more information on IEEE floating-point values.) Note If the MAX function is run on an array containing NaN values and the NAN keyword is not set, an invalid result will occur. Example Example 1 This example prints the maximum value in an array, and the subscript of that value: ; Create a simple two-dimensional array: D = DIST(100) ; Print the maximum value in array D and its linear subscript: PRINT, 'Maximum value in array D is:', MAX(D, I) PRINT, 'The subscript of the maximum value is', I IDL Output Maximum value in array D is: 70.7107 The subscript of the maximum value is 5050 Example 2 To convert I to a two-dimensional subscript, use the commands: IX = I MOD 100 IY = I/100 PRINT, 'The maximum value of D is at location ('+ STRTRIM(IX, 1) $ + ', ' + STRTRIM(IY, 1) + ')' IDL Output The maximum value of D is at location (50, 50) See Also MIN MD_TEST [Previous Routine] [Next Routine] [List of Routines] NAME: MD_TEST The MD_TEST function tests the hypothesis that a sample population is random against the hypothesis that it is not random. The result is a two-element vector containing the nearly-normal test statistic Z and its associated probability. This two- tailed function is an extension of the "Runs Test for Randomness" and is often referred to as the Median Delta Test. This routine is written in the IDL language. Its source code can be found in the file md_test.pro in the lib subdirectory of the IDL distribution. Syntax Result = MD_TEST( X [, ABOVE=variable] [, BELOW=variable] [, MDC=variable] ) Arguments X An n-element integer, single- or double-precision floating-point vector. Keywords ABOVE Use this keyword to specify a named variable that will contain the number of sample population values greater than the median of X. BELOW Use this keyword to specify a named variable that will contain the number of sample population values less than the median of X. MDC Use this keyword to specify a named variable that will contain the number of Median Delta Clusters (sequential values of X above and below the median). Example This example tests the hypothesis that X represents a random population against the hypothesis that it does not represent a random population at the 0.05 significance level: ; Define a sample population: X = [ 2.00, 0.90, -1.44, -0.88, -0.24, 0.83, -0.84, -0.74, $ 0.99, -0.82, -0.59, -1.88, -1.96, 0.77, -1.89, -0.56, $ -0.62, -0.36, -1.01, -1.36] ; Test the hypothesis that X represents a random population against ; the hypothesis that it does not represent a random population at ; the 0.05 significance level: result = MD_TEST(X, MDC = mdc) PRINT, result IDL prints: 0.459468 0.322949 The computed probability (0.322949) is greater than the 0.05 significance level and therefore we do not reject the hypothesis that X represents a random population. See Also CTI_TEST, FV_TEST, KW_TEST, R_TEST, RS_TEST, S_TEST, TM_TEST, XSQ_TEST MEAN [Previous Routine] [Next Routine] [List of Routines] NAME: MEAN The MEAN function computes the mean of a numeric vector. MEAN calls the IDL function MOMENT. Syntax Result = MEAN( X [, /DOUBLE] [, /NAN] ) Arguments X An n-element, integer, double-precision or floating-point vector. Keywords DOUBLE If this keyword is set, computations are done in double precision arithmetic. NAN Set this keyword to cause the routine to check for occurrences of the IEEE floating- point value NaN in the input data. Elements with the value NaN are treated as missing data. (See "Special Floating-Point Values" in Chapter 17 of Building IDL Applications for more information on IEEE floating-point values.) Example ; Define the n-element vector of sample data: x = [65, 63, 67, 64, 68, 62, 70, 66, 68, 67, 69, 71, 66, 65, 70] ; Compute the standard deviation: result = MEAN(x) ; Print the result: PRINT, result IDL prints: 66.7333 See Also KURTOSIS, MEANABSDEV, MOMENT, STDDEV, SKEWNESS, VARIANCE MEANABSDEV [Previous Routine] [Next Routine] [List of Routines] NAME: MEANABSDEV The MEANABSDEV function computes the mean absolute deviation (average deviation) of an n-element vector. Syntax Result = MEANABSDEV( X [, /DOUBLE] [, /MEDIAN] [, /NAN] ) Arguments X An n-element, floating-point or double-precision vector. Keywords DOUBLE Set this keyword to force computations to be done in double precision arithmetic and to return a double precision result. If this keyword is not set, the computations and result depend upon the type of the input data (integer and float data return float results, while double data returns double results). This has no effect if the MEDIAN keyword is set. MEDIAN Set this keyword to return the average deviation from the median. By default, if MEDIAN is not set, MEANABSDEV will return the average deviation from the mean. NAN Set this keyword to cause the routine to check for occurrences of the IEEE floating- point value NaN in the input data. Elements with the value NaN are treated as missing data. (See "Special Floating-Point Values" in Chapter 17 of Building IDL Applications for more information on IEEE floating-point values.) Example ; Define an n-element vector: x = [1, 1, 1, 2, 5] ; Compute average deviation from the mean: result = MEANABSDEV(x) ; Print the result: PRINT, result IDL prints: 1.20000 See Also KURTOSIS, MEAN, MOMENT, STDDEV, SKEWNESS, VARIANCE MEDIAN [Previous Routine] [Next Routine] [List of Routines] NAME: MEDIAN The MEDIAN function returns the median value (element n/2) of Array if one parameter is present, or applies a one- or two-dimensional median filter of the specified width to Array and returns the result. In an ordered set of values, the median is a value with an equal number of values above and below it. Median smoothing replaces each point with the median of the one- or two-dimensional neighborhood of a given width. It is similar to smoothing with a boxcar or average filter but does not blur edges larger than the neighborhood. In addition, median filtering is effective in removing salt and pepper noise, (isolated high or low values). The scalar median is simply the middle value, which should not be confused with the average value (e.g., the median of the array [1,10,4] is 4, while the average is 5.) Note The MEDIAN function treats NaN values as missing data. Syntax Result = MEDIAN( Array [, Width] [, /EVEN] ) Arguments Array The array to be processed. If Width is also supplied, and Array is of byte type, the result is of byte type. All other types are converted to single-precision floating-point, and the result is floating-point. Array can have only one or two dimensions. If Width is not given, Array can have any valid number of dimensions. The array is converted to single-precision floating-point, and the median value is returned as a floating-point value. Width The size of the one or two-dimensional neighborhood to be used for the median filter. The neighborhood has the same number of dimensions as Array. Keywords EVEN If the EVEN keyword is set when Array contains an even number of points (i.e. there is no middle number), MEDIAN returns the average of the two middle numbers. The returned value may not be an element of Array. If Array contains an odd number of points, MEDIAN returns the median value. The returned value will always be an element of Array-even if the EVEN keyword is set-since an odd number of points will always have a single middle value. Example ; Create a simple image and display it: D = SIN(DIST(200)^0.8) & TVSCL, D ; Display D median-filtered with a width of 9: TVSCL, MEDIAN(D, 9) ; Print the median of a four-element array, with and without ; the EVEN keyword: PRINT, MEDIAN([1, 2, 3, 4], /EVEN) PRINT, MEDIAN([1, 2, 3, 4]) IDL prints: 2.50000 3.00000 See Also DIGITAL_FILTER, LEEFILT, MOMENT, SMOOTH MEMORY [Previous Routine] [Next Routine] [List of Routines] NAME: MEMORY The MEMORY function returns information on the amount of dynamic memory currently in use by the IDL session if no keywords are set. If a keyword is set, MEMORY returns the specified quantity. Syntax Result = MEMORY( [, /CURRENT | , /HIGHWATER | , /NUM_ALLOC | , /NUM_FREE | , /STRUCTURE ] [, /L64] ) Return Value The return value is a vector that is always of integer type. The following table describes the information returned if no keywords are set: Element Contents Result[0] Amount of dynamic memory (in bytes) currently in use by the IDL session. Result[1] The number of times IDL has made a memory allocation request from the underlying system. Result[2] The number of times IDL has made a request to free memory from the underlying system. Result[3] High water mark: The maximum amount of dynamic memory used since the last time the MEMORY function or HELP, /MEMORY procedure was called. Table 69: MEMORY Function Return Values Arguments None. Keywords The following keywords determine the return value of the MEMORY function. Except for L64, all of the keywords are mutually exclusive - specify at most one of the following. CURRENT Set this keyword to return the amount of dynamic memory (in bytes) currently in use by the IDL session. HIGHWATER Set this keyword to return the maximum amount of dynamic memory used since the last time the MEMORY function or HELP,/MEMORY procedure was called. This can be used to determine maximum memory use of a code sequence as shown in the example below. L64 By default, the result of MEMORY is 32-bit integer when possible, and 64-bit integer if the size of the returned values requires it. Set L64 to force 64-bit integers to be returned in all cases. Note Only 64-bit versions of IDL are capable of using enough memory to require 64-bit MEMORY output. Check the value of !VERSION.MEMORY_BITS to see if your IDL is 64-bit or not. NUM_ALLOC Returns the number of times IDL has requested dynamic memory from the underlying system. NUM_FREE Returns the number of times IDL has returned dynamic memory to the underlying system. STRUCTURE Set this keyword to return all available information about Expression in a structure. The result will be an IDL_MEMORY (32-bit) structure when possible, and an IDL_MEMORY64 structure otherwise. Set L64 to force an IDL_MEMORY64 structure to be returned in all cases. The following are descriptions of the fields in the returned structure: Field Description CURRENT Current dynamic memory in use. NUM_ALLOC Number of calls to allocate memory. NUM_FREE Number of calls to free memory. HIGHWATER Maximum dynamic memory used since last call for this information. Table 70: STRUCTURE Field Descriptions Example To determine how much dynamic memory is required to execute a sequence of IDL code: ; Get current allocation and reset the high water mark: start_mem = MEMORY(/CURRENT) ; Arbitrary code goes here. PRINT, 'Memory required: ', MEMORY(/HIGHWATER) - start_mem The MEMORY function can also be used in conjunction with DIALOG_MESSAGE as follows: ; Get current dymanic memory in use: mem = MEMORY(/CURRENT) ; Prepare dialog message: message = 'Current amount of dynamic memory used is ' sentence = message + STRTRIM(mem,2)+' bytes.' ; Display the dialog message containing memory usage statement: status = DIALOG_MESSAGE (sentence, /INFORMATION) See Also HELP MESH_CLIP [Previous Routine] [Next Routine] [List of Routines] NAME: MESH_CLIP The MESH_CLIP function clips a polygonal mesh to an arbitrary plane in space and returns a polygonal mesh of the remaining portion. An auxiliary array of data may also be passed and clipped. This array can have multiple values for each vertex. Syntax Result = MESH_CLIP (Plane, Vertsin, Connin, Vertsout, Connout [, AUXDATA_IN=array, AUXDATA_OUT=variable] [, CUT_VERTS=variable] ) Return Value The return value is the number of triangles in the returned mesh. Arguments Plane Input four element array describing the equation of the plane to be clipped to. The elements are the coefficients (a,b,c,d) of the equation ax+by+cz+d=0. Vertsin Input array of polygonal vertices [3, n]. Connin Input polygonal mesh connectivity array. Vertsout Output array of polygonal vertices. Connout Output polygonal mesh connectivity array. Keywords AUXDATA_IN Input array of auxiliary data. If present, these values are interpolated and returned through AUXDATA_OUT. The trailing array dimension must match the number of vertices in the Vertsin array. AUXDATA_OUT Set this keyword to a named variable that will contain an output array of interpolated auxiliary data. CUT_VERTS Set this keyword to a named variable that will contain an output array of vertex indices (into Vertsout) of the vertices which are considered to be "on" the clipped surface. See Also MESH_DECIMATE, MESH_ISSOLID, MESH_MERGE, MESH_NUMTRIANGLES, MESH_OBJ, MESH_SMOOTH, MESH_SURFACEAREA, MESH_VALIDATE, MESH_VOLUME MESH_DECIMATE [Previous Routine] [Next Routine] [List of Routines] NAME: MESH_DECIMATE The MESH_DECIMATE function reduces the density of geometry while preserving as much of the original data as possible. The classic case is to thin out a polygonal mesh to use fewer polygons while preserving the mesh form. The decimation algorithm removes triangles from the mesh. This is done in such a way as to preserve the mesh edges and to remove roughly planar polygons. Decimation is a memory and CPU intensive process. Expect the decimation of large models to require large amounts of memory and dozens of seconds to complete. As a reference, a model with approximately 36,000 vertices and 70,000 faces requires 20- 30 seconds to decimate to 10% of its original size on a typical NT PC with 64Mb RAM and 333MHz Pentium processor. If the input polygons are not all triangles, IDL converts the polygons to triangles before decimating. For best results, the polygons should all be convex. Note that if the input polygons are not all triangles, then IDL may return more polygons (as triangles) than were submitted as input, even after decimating a percentage of the polygons. IDL applies the PERCENT_POLYGONS keyword value to the polygon list after converting the list to triangles to approximate the same visual effect of decimating the requested percentage of polygons. IDL takes steps to deal with input data with a wide variation in magnitude. For example, a troublesome input polygon list may have X and Y values in the 10^1 to 10^2 range, while the Z values may have magnitudes of about 10^20. If the results of the decimation are unacceptable, consider scaling the input data so that the magnitudes of the data are closer together. Syntax Result = MESH_DECIMATE (Verts, Conn, Connout [, VERTICES=variable] [, PERCENT_VERTICES=percent | , PERCENT_POLYGONS=percent] ) Return Value The return value is the number of triangles in the output connectivity array. Arguments Verts Input array of polygonal vertices [3, n]. Conn Input polygonal mesh connectivity array. Connout Output polygonal mesh connectivity array. Note Some of the vertices in the Verts array may not be referenced by the Connout array. Keywords PERCENT_VERTICES Set this keyword to the percent of the original vertices to be returned in the Connout array. It specifies the amount of decimation to perform. PERCENT_POLYGONS Set this keyword to the percent of the original polygons to be returned in the Connout array. It specifies the amount of decimation to perform. Note PERCENT_VERTICES and PERCENT_POLYGONS are mutually exclusive keywords. VERTICES Set this keyword to a named variable that will contain an output array of the vertices generated by the MESH_DECIMATE function. If this keyword is specified, the function is not restricted to using the original set of vertices specified in the Verts parameter when generating the decimated mesh, allowing it to generate a more optimal mesh by determining its own placement of vertices. If this keyword is specified, the Connout argument will consist of a polygon connectivity list whose indices refer to the vertex list stored in the named variable specified with this keyword. Otherwise, the Connout argument will consist of a polygon connectivity list that refers to the original vertex list Verts. See Also MESH_CLIP, MESH_ISSOLID, MESH_MERGE, MESH_NUMTRIANGLES, MESH_OBJ, MESH_SMOOTH, MESH_SURFACEAREA, MESH_VALIDATE, MESH_VOLUME MESH_ISSOLID [Previous Routine] [Next Routine] [List of Routines] NAME: MESH_ISSOLID The MESH_ISSOLID function computes various mesh properties and enables IDL to determine if a mesh encloses space (is a solid). If the mesh can be considered a solid, routines can compute the volume of the mesh. Syntax Result = MESH_ISSOLID (Conn) Return Value Returns 1 if the input mesh fully encloses space (assuming no polygonal interpenetration) or 0 otherwise. A mesh is defined to fully enclose space if each edge in the input mesh appears an even number of times in the mesh. Note The input polygonal mesh is assumed to contain only planar, convex polygons. Arguments Conn This is an integer or longword array that represents a series of polygon descriptions. Each polygon description takes the form [n, i0, i1, ..., in-1], where n is the number of vertices that define the polygon, and i0...in-1 are indices into the vertex array. Keywords None. See Also MESH_CLIP, MESH_DECIMATE, MESH_MERGE, MESH_NUMTRIANGLES, MESH_OBJ, MESH_SMOOTH, MESH_SURFACEAREA, MESH_VALIDATE, MESH_VOLUME MESH_MERGE [Previous Routine] [Next Routine] [List of Routines] NAME: MESH_MERGE The MESH_MERGE function merges two polygonal meshes. Syntax Result = MESH_MERGE (Verts, Conn, Verts1, Conn1 [, /COMBINE_VERTICES] [, TOLERANCE=value] ) Return Value The function return value is the number of triangles in the modified polygonal mesh connectivity array. Arguments Verts Input/Output array of polygonal vertices [3, n]. These are potentially modified and returned to the user. Conn Input/Output polygonal mesh connectivity array. This array is modified and returned to the user. Verts1 Additional input polygonal vertex array [3, n]. Conn1 Additional input polygonal mesh connectivity array. Keywords COMBINE_VERTICES If this keyword is set, the routine will attempt to collapse vertices which are at the same location in space into single vertices. If the expression max( xi ­ xi + 1 , yi ­ yi + 1 , zi ­ zi + 1 ) < tolerance is true, the points (i) and (i+1) can be collapsed into a single vertex. The result is returned as a modification of the Verts argument. TOLERANCE This keyword is used to specify the tolerance value used with the COMBINE_VERTICES keyword. The default value is 0.0. See Also MESH_CLIP, MESH_DECIMATE, MESH_ISSOLID, MESH_NUMTRIANGLES, MESH_OBJ, MESH_SMOOTH, MESH_SURFACEAREA, MESH_VALIDATE, MESH_VOLUME MESH_NUMTRIANGLES [Previous Routine] [Next Routine] [List of Routines] NAME: MESH_NUMTRIANGLES The MESH_NUMTRIANGLES function computes the number of triangles in a polygonal mesh. Syntax Result = MESH_NUMTRIANGLES (Conn) Return Value Returns the number of triangles in the mesh (a quad is considered two triangles). Arguments Conn Polygonal mesh connectivity array. Keywords None. See Also MESH_CLIP, MESH_DECIMATE, MESH_ISSOLID, MESH_MERGE, MESH_OBJ, MESH_SMOOTH, MESH_SURFACEAREA, MESH_VALIDATE, MESH_VOLUME MESH_OBJ [Previous Routine] [Next Routine] [List of Routines] NAME: MESH_OBJ The MESH_OBJ procedure generates a polygon mesh (vertex list and polygon list) that represent the desired primitive object. The available primitive objects are: triangulated surface, rectangular surface, polar surface, cylindrical surface, spherical surface, surface of extrusion, surface of revolution, and ruled surface. This routine is written in the IDL language. Its source code can be found in the file mesh_obj.pro in the lib subdirectory of the IDL distribution. Syntax MESH_OBJ, Type, Vertex_List, Polygon_List, Array1 [, Array2] [, CLOSED] [, /DEGREES] [, P1=value] [, P2=value] [, P3=value] [, P4=value] [, P5=value] Arguments Type An integer that specifies what type of object to create. The various surface types are described in the table below. Type Surface Type 0 Triangulated 1 Rectangular 2 Polar 3 Cylindrical 4 Spherical 5 Extrusion 6 Revolution 7 Ruled Other values None Table 71: Surface Types Vertex_List A named variable that will contain the mesh vertices. Vertex_List has the same format as the lists returned by the SHADE_VOLUME procedure. Polygon_List A named variable that will contain the mesh indexes. Polygon_List has the same format as the lists returned by the SHADE_VOLUME procedure. Array1 An array whose use depends on the type of object being created. The following table describes the differences. Surface Type Array1 Type Triangulated A (3, n) array containing random [x, y, z] points to build a triangulated surface from. The resulting polygon mesh will have n vertices. When shading a triangulated mesh, the shading array should have (n) elements. Rectangular A two dimensional (n, m) array containing z values. The resulting polygon mesh will have n x m vertices. When shading a rectangular mesh, the shading array should have (n, m) elements. Polar A two dimensional (n, m) array containing z values. The resulting polygon mesh will have n x m vertices. The n dimension of the array is mapped to the polar angle, and the m dimension is mapped to the polar radius. When shading a polar mesh, the shading array should have (n, m) elements. Cylindrical A two dimensional (n, m) array containing radius values. The resulting polygon mesh will have n x m vertices. The n dimension of the array is mapped to the polar angle, and the m dimension is mapped to the Z axis. When shading a cylindrical mesh, the shading array should have (n, m) elements. Table 72: Array 1 Type Surface Type Array1 Type Spherical A two dimensional (n, m) array containing radius values. The resulting polygon mesh will have n x m vertices. The n dimension of the array is mapped to the longitude (0.0 to 360.0 degrees), and the m dimension is mapped to the latitude (-90.0 to +90.0 degrees). When shading a spherical mesh, the shading array should have (n, m) elements. Extrusion A (3, n) array of connected 3D points which define the shape to extrude. The resulting polygon mesh will have n x (steps+1) vertices (where steps is the number of "segments" in the extrusion). (See the P1 keyword). If the order of the elements in Array1 is reversed, then the polygon facing is reversed. When shading an extrusion mesh, the shading array should have (n, steps+1) elements. Revolution A (3, n) array of connected 3D points which define the shape to revolve. The resulting polygon mesh will have n x ((steps>3)+1) vertices (where steps is the number of "steps" in the revolution). (See the P1 keyword). If the order of the elements in Array1 is reversed, then the polygon facing is reversed. When shading a revolution mesh, the shading array should have (n, (steps>3)+1) elements. Ruled A (3, n) array of connected 3D points which define the shape of the first ruled vector. The optional (3, m) Array2 parameter defines the shape of the second ruled vector. The resulting polygon mesh will have (n > m)*(steps+1) vertices (where steps is the number of intermediate "steps"). (See the P1 keyword). When shading a ruled mesh, the shading array should have (n > m, steps+1) elements. Table 72: Array 1 Type Array2 If the object type is 7 (Ruled Surface) then Array2 is a (3, m) array containing the 3D points which define the second ruled vector. If Array2 has fewer elements than Array1 then Array2 is processed with CONGRID to give it the same number of elements as Array1. If Array1 has fewer elements than Array2 then Array1 is processed with CONGRID to give it the same number of elements as Array2. Array2 must be supplied if the object type is 7. Otherwise, Array2 is ignored. Keywords CLOSED This new keyword, if set, "closes" the polygonal mesh topologically by using the first vertex in a row for both the first and last polygons in that row. This keyword parameter is only applicable to the CYLINDRICAL, SPHERICAL, REVOLUTION, and EXTRUSION surface types. This keyword parameter removes the discontinuity where the mesh wraps back around on itself, which can improve the mesh's appearance when viewing it as a shaded object. For the EXTRUSION surface type, this procedure handles input polygons that form a closed loop with the last vertex being a copy of the first vertex, as well as those that do not. DEGREES If set, then the input parameters are in degrees (where applicable). Otherwise, the angles are in radians. P1 - P5 The meaning of the keywords P1 through P5 vary depending upon the object type. The table below describes the differences. Surface Type Keywords Triangulated P1 through P5 are ignored. Rectangular If Array1 is an (n, m) array, and if P1 has n elements, then the values contained in P1 are the X coordinates for each column of vertices. Otherwise, FINDGEN(n) is used for the X coordinates. If P2 has m elements, then the values contained in P2 are the Y coordinates for each row of vertices. Otherwise, FINDGEN(m) is used for the Y coordinates. The polygon facing is reversed if the order of either P1 or P2 (but not both) is reversed. P3, P4, and P5 are ignored. Polar P1 specifies the polar angle of the first column of Array1 (the default is 0). P2 specifies the polar angle of the last column of Array1 (the default is 2*PI). If P2 is less than P1 then the polygon facing is reversed. P3 specifies the radius of the first row of Array1 (the default is 0). P4 specifies the radius of the last row of Array1 (the default is m-1). If P4 is less than P3 then the polygon facing is reversed. P5 is ignored. Cylindrical P1 specifies the polar angle of the first column of Array1 (the default is 0). P2 specifies the polar angle of the last column of Array1 (the default is 2*PI). If P2 is less than P1 then the polygon facing is reversed. P3 specifies the Z coordinate of the first row of Array1 (the default is 0). P4 specifies the Z coordinate of the last row of Array1 (the default is m-1). If P4 is less than P3 then the polygon facing is reversed. P5 is ignored. Table 73: P1-P5 Keywords Surface Type Keywords Spherical P1 specifies the longitude of the first column of Array1 (the default is 0). P2 specifies the longitude of the last column of Array1 (the default is 2*PI). IF P2 is less than P1 then the polygon facing is reversed. P3 specifies the latitude of the first row of Array1 (the default is -PI/2). P4 specifies the latitude of the last row of Array1 (the default is +PI/2). If P4 is less than P3 then the polygon facing is reversed. P5 is ignored. Extrusion P1 specifies the number of steps in the extrusion (the default is 1). P2 is a three element vector specifying the direction (and length) of the extrusion (the default is [0, 0, 1]). P3, P4, and P5 are ignored. Revolution P1 specifies the number of "facets" in the revolution (the default is 3). If P1 is less than 3 then 3 is used. P2 is a three element vector specifying a point that the rotation vector passes through (the default is [0, 0, 0]). P3 is a three element vector specifying the direction of the rotation vector (the default is [0, 0, 1]). P4 specifies the starting angle for the revolution (the default is 0). P5 specifies the ending angle for the revolution (the default is 2*PI). If P5 is less than P4 then the polygon facing is reversed. Ruled P1 specifies the number of "steps" in the ruling (the default is 1). P2, P3, P4, and P5 are ignored. Table 73: P1-P5 Keywords Examples ; Create a 48x64 cylinder with a constant radius of 0.25: MESH_OBJ, 3, Vertex_List, Polygon_List, $ Replicate(0.25, 48, 64), P4=0.5 ; Transform the vertices: T3D, /RESET T3D, ROTATE=[0.0, 30.0, 0.0] T3D, ROTATE=[0.0, 0.0, 40.0] T3D, TRANSLATE=[0.25, 0.25, 0.25] VERTEX_LIST = VERT_T3D(Vertex_List) ; Create the window and view: WINDOW, 0, XSIZE=512, YSIZE=512 CREATE_VIEW, WINX=512, WINY=512 ; Render the mesh: SET_SHADING, LIGHT=[-0.5, 0.5, 2.0], REJECT=0 TVSCL, POLYSHADE(Vertex_List, Polygon_List, /NORMAL) ; Create a cone (surface of revolution): MESH_OBJ, 6, Vertex_List, Polygon_List, $ [[0.75, 0.0, 0.25], [0.5, 0.0, 0.75]], $ P1=16, P2=[0.5, 0.0, 0.0] ; Create the window and view: WINDOW, 0, XSIZE=512, YSIZE=512 CREATE_VIEW, WINX=512, WINY=512, AX=30.0, AY=(140.0), ZOOM=0.5 ; Render the mesh: SET_SHADING, LIGHT=[-0.5, 0.5, 2.0], REJECT=0 TVSCL, POLYSHADE(Vertex_List, Polygon_List, /DATA, /T3D) See Also CREATE_VIEW, MESH_CLIP, MESH_DECIMATE, MESH_ISSOLID, MESH_MERGE, MESH_NUMTRIANGLES, MESH_SMOOTH, MESH_SURFACEAREA, MESH_VALIDATE, MESH_VOLUME, SET_SHADING, VERT_T3D MESH_SMOOTH [Previous Routine] [Next Routine] [List of Routines] NAME: MESH_SMOOTH The MESH_SMOOTH function performs spatial smoothing on a polygon mesh. This function smoothes a mesh by applying Laplacian smoothing to each vertex, as described by the following formula: M x i = x + ----- (x ­ x ) (n + 1) in M jn in j = 0 where: xi is vertex i for iteration n n is the smoothing factor M is the number of vertices that share a common edge with xin. Syntax Result = MESH_SMOOTH (Verts, Conn [, ITERATIONS=value] [, FIXED_VERTICES=array] [, /FIXED_EDGE_VERTICES] [, LAMBDA=value]) Return Value The output of this function is resulting [3, n] array of modified vertices. Arguments Verts Input array of polygonal vertices [3, n]. Conn Input polygonal mesh connectivity array. Keywords ITERATIONS Number of iterations to smooth. The default value is 50. FIXED_VERTICES Set this keyword to an array of vertex indices which are not to be modified by the smoothing. FIXED_EDGE_VERTICES Set this keyword to specify that mesh outer edge vertices are not to be modified by the smoothing. LAMBDA Smoothing factor. The default value is 0.05. See Also MESH_CLIP, MESH_DECIMATE, MESH_ISSOLID, MESH_MERGE, MESH_NUMTRIANGLES, MESH_OBJ, MESH_SURFACEAREA, MESH_VALIDATE, MESH_VOLUME MESH_SURFACEAREA [Previous Routine] [Next Routine] [List of Routines] NAME: MESH_SURFACEAREA The MESH_SURFACEAREA function computes various mesh properties to determine the mesh surface area, including integration of other properties interpolated on the surface of the mesh. Syntax Result = MESH_SURFACEAREA ( Verts, Conn [, AUXDATA=array] [, MOMENT=variable] ) Return Value Returns the cumulative (weighted) surface area of the polygons in the mesh. Note The input polygonal mesh is assumed to contain only planar, convex polygons. Arguments Verts Array of polygonal vertices [3, n]. Conn Polygonal mesh connectivity array. Keywords AUXDATA Array of input auxiliary data (one value per vertex). If present, these values are used to weight a vertex for the purpose of the area computation. The surface area integral will linearly interpolate these values over the surface of each triangle. The default weight is 1.0 which results in the basic polygon area. MOMENT If this keyword is present, it will return a three element float vector which corresponds to the first order moments computed with respect to the X, Y and Z axis. The computation is: m = a ici ntris where a is the (weighted) area of the triangle and c is the centroid of the triangle, thus m sarea yields the (weighted) centroid of the polygon mesh. See Also MESH_CLIP, MESH_DECIMATE, MESH_ISSOLID, MESH_MERGE, MESH_NUMTRIANGLES, MESH_OBJ, MESH_SMOOTH, MESH_VALIDATE, MESH_VOLUME MESH_VALIDATE [Previous Routine] [Next Routine] [List of Routines] NAME: MESH_VALIDATE The MESH_VALIDATE function checks for NaN values in vertices, removes unused vertices, and combines close vertices. Syntax Result = MESH_VALIDATE ( Verts, Conn [, /REMOVE_NAN] [, /PACK_VERTICES] [, /COMBINE_VERTICES] [, TOLERANCE=value] ) Return Value The function return value is the number of triangles in the modified polygonal mesh connectivity array. Arguments Verts Input/Output array of polygonal vertices [3, n]. These are potentially modified and returned to the user. Conn Input/Output polygonal mesh connectivity array. This array is modified and returned to the user. Keywords COMBINE_VERTICES If this keyword is set, the routine will attempt to collapse vertices which are at the same location in space into single vertices. If the expression max( xi ­ xi + 1 , yi ­ yi + 1 , zi ­ zi + 1 ) < tolerance is true, the points (i) and (i+1) can be collapsed into a single vertex. The result is returned as a modification of the Verts argument. PACK_VERTICES If this keyword is set, the Verts input array will be packed to exclude any non- referenced vertices. The result is returned in the Verts argument. REMOVE_NAN If this keyword is set, the function will remove any polygons from CONN which reference vertices containing NaN values. TOLERANCE This keyword is used to specify the tolerance value used with the COMBINE_VERTS keyword. The default value is 0.0. See Also MESH_CLIP, MESH_DECIMATE, MESH_ISSOLID, MESH_MERGE, MESH_NUMTRIANGLES, MESH_OBJ, MESH_SMOOTH, MESH_SURFACEAREA, MESH_VOLUME MESH_VOLUME [Previous Routine] [Next Routine] [List of Routines] NAME: MESH_VOLUME The MESH_VOLUME function computes the volume that the mesh encloses. Syntax Result = MESH_VOLUME ( Verts, Conn [, /SIGNED] ) Return Value Returns the volume that the mesh encloses. If the mesh does not enclose space (i.e. MESH_ISSOLID( ) would return 0), this function returns 0.0. Note The input polygonal mesh is assumed to contain only planar, convex polygons. Arguments Verts Array of polygonal vertices [3, n]. Conn Polygonal mesh connectivity array. Keywords SIGNED Set this keyword to compute the signed volume. The sign will be negative for a mesh consisting of inward facing polygons. See Also MESH_CLIP, MESH_DECIMATE, MESH_ISSOLID, MESH_MERGE, MESH_NUMTRIANGLES, MESH_OBJ, MESH_SMOOTH, MESH_SURFACEAREA, MESH_VALIDATE MESSAGE [Previous Routine] [Next Routine] [List of Routines] NAME: MESSAGE The MESSAGE procedure issues error and informational messages using the same mechanism employed by built-in IDL routines. By default, the message is issued as an error, the message is output, and IDL takes the action specified by the ON_ERROR procedure. As a side-effect of issuing the error, the system variable !ERROR_STATE is set and the text of the error message is placed in !ERROR_STATE.MSG or in !ERROR_STATE.SYS_MSG for the operating system's component of the error message. If the call to the MESSAGE procedure causes execution to halt, traceback information is displayed automatically. Syntax MESSAGE, [Text] [, NAME] [, BLOCK] [, /CONTINUE] [, /INFORMATIONAL] [, /IOERROR] [, /NONAME] [, /NOPREFIX] [, /NOPRINT] [, /RESET] Arguments Text The text of the message to be issued. If Text is not supplied, MESSAGE returns quietly. Keywords NAME If specified, NAME supplies the name of the message to throw. NAME is often used in conjunction with the BLOCK keyword. BLOCK If specified, BLOCK supplies the name of the message block to use. The BLOCK keyword is ignored unless the NAME keyword is also specified. CONTINUE Set this keyword to return after issuing the error instead of taking the action specified by ON_ERROR. Use this option when it is desirable to report an error and then continue processing. INFORMATIONAL Set this keyword to issue informational text instead of an error. In this case, !ERROR_STATE is not set. The !QUIET system variable controls the printing of informational messages. IOERROR Set this keyword to indicate that the error occurred while performing I/O. The action specified by the ON_IOERROR procedure is executed instead of ON_ERROR. NONAME Set this keyword to suppress printing of the issuing routine's name at the beginning of the error message. NOPREFIX Usually, the message includes the message prefix string (as specified by the MSG_PREFIX field of the !ERROR_STATE system variable) at the beginning. Set this keyword to omit the prefix. NOPRINT Set this keyword to prevent the message from printing to the screen and cause the other actions to proceed quietly. The error system variables are updated as usual. RESET Set this keyword to set the "!ERROR_STATE" on page 2425 system variable back to the "success" state and clear any internal traceback information being saved for use by the LAST_ERROR keyword to the HELP procedure. TRACEBACK This keyword is obsolete and is included for compatibility with existing code only. Traceback information is provided by default. Example As an example, assume the statement: message, 'Unexpected value encountered.' is executed in a procedure named CALC. If an error occurs, the following message would be printed: % CALC: Unexpected value encountered. and execution would halt. See Also CATCH, ON_ERROR, ON_IOERROR, STRMESSAGE MIN [Previous Routine] [Next Routine] [List of Routines] NAME: MIN The MIN function returns the value of the smallest element of Array. The type of the result is the same as that of Array. Syntax Result = MIN( Array [, Min_Subscript] [, SUBSCRIPT_MAX] [, DIMENSION] [, MAX=variable] [, /NAN] ) Arguments Array The array to be searched. Min_Subscript A named variable that, if supplied, is converted to a long integer containing the one- dimensional subscript of the minimum element. Otherwise, the system variable !C is set to the one-dimensional subscript of the minimum element. Keywords SUBSCRIPT_MAX A named variable that, if supplied, is converted to an integer containing the one-dimensional subscript of the maximum element, the value of which is available via the MAX keyword. DIMENSION Set this new keyword to the dimension over which to find the minimum values of an array. If this keyword is not present or is zero, then the minimum is found over the entire array. If this keyword is present, then the return values for Result, Min_Subscript, MAX, and SUBSCRIPT_MAX will all be arrays of one dimension less than the input array. For example, if the dimensions of Array are N1, N2, N3, and DIMENSION is 2, the dimensions of the result are (N1, N3), and element (i,j) of the result contains the minimum value of Array[i, *, j]. MAX The name of a variable to receive the value of the maximum array element. If you need to find both the minimum and maximum array values, use this keyword to avoid scanning the array twice with separate calls to MAX and MIN. NAN Set this keyword to cause the routine to check for occurrences of the IEEE floating- point value NaN in the input data. Elements with the value NaN are treated as missing data. (See "Special Floating-Point Values" in Chapter 17 of Building IDL Applications for more information on IEEE floating-point values.) Note If the MIN function is run on an array containing NaN values and the NAN keyword is not set, an invalid result will occur. Example ; Create a simple two-dimensional array: D = DIST(100) ; Find the minimum value in array D and print the result: PRINT, MIN(D) See Also MAX MIN_CURVE_SURF [Previous Routine] [Next Routine] [List of Routines] NAME: MIN_CURVE_SURF The MIN_CURVE_SURF function interpolates a regularly- or irregularly-gridded set of points, over either a plane or a sphere, with either a minimum curvature surface or a thin-plate-spline surface. Note The accuracy of this function is limited by the single-precision floating-point accuracy of the machine. This routine is written in the IDL language. Its source code can be found in the file min_curve_surf.pro in the lib subdirectory of the IDL distribution. Syntax Result = MIN_CURVE_SURF(Z [, X, Y] [, /DOUBLE] [, /TPS] [, /REGULAR] [, /SPHERE [, /CONST]] [, XGRID=[xstart, xspacing] | , XVALUES=array] [, YGRID=[ystart, yspacing] | , YVALUES=array] [, GS=[xspace,yspace]] [, BOUNDS=[xmin, ymin, xmax, ymax]] [, NX=value] [, NY=value] [, XOUT=vector] [, YOUT=vector] [, XPOUT=array, YPOUT=array]) Return Value This function returns a two-dimensional floating-point array containing the interpolated surface, sampled at the grid points. Theory A minimum curvature spline surface is fitted to the data points described by x, y, and z. The basis function is: C (x0, x1, y0, y1) = d2 log(dk) where d is the distance between (x0, y0), (x1, y1) and k = 1 for minimum curvature surface or k = 2 for Thin Plate Splines. For n data points, a system of n+3 simultaneous equations are solved for the coefficients of the surface. For any interpolation point, the interpolated value is: f(x, y) = b0 + b1 x + b2 y + a i C(xi, x, yi, y) For a sphere the value is: f(l, t) = b0 + b1 x + b2 y + b3 z + a i C(Li, l, Ti, t) On the sphere, l and t are longitude and latitude. C(Li,l, Ti,t) is the basis function above, with distance between the two points, (Li,Ti), and (l , t), measured in radians of arc length. x, y, and z are the 3D cartesian coordinates of the point (l,t) on the unit sphere. For a sphere with the CONST keyword set, the value is: f(l, t) = b0 + a i CLi, l, Ti, t The results obtained with the thin plate spline (TPS) and the minimum curvature surface (MCS) methods are very similar. The only difference is in the basis functions: TPS uses d2*alog(d2), and MCS uses d2*alog(d), where d is the distance from point (xi,yi). Arguments Z, X, Y Arrays containing the Z, X, and Y coordinates of the data points on the surface. Points need not be regularly gridded. For regularly gridded input data, X and Y are not used: the grid spacing is specified via the XGRID and YGRID (or XVALUES and YVALUES) keywords, and Z must be a two-dimensional array. For irregular grids, all three parameters must be present and have the same number of elements. If Z is specified as a double-precision value, the computation will be performed in double- precision arithmetic. If the SPHERE keyword is set, X and Y are given in degrees of longitude and latitude, respectively. Keywords CONST Set this keyword to fit data on the sphere with a constant baseline, otherwise, data on the sphere is fit with a basline that contains a constant term plus linear X, Y, and Z terms. This keyword has an effect only if SPHERE is set. See Theory above for the formulae. DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. If Z is double precision, the computations will also be done in double precision. SPHERE Set this keyword to perform interpolation on the surface of a sphere. The inputs X and Y should be given in degrees of longitude and latitude, respectively. TPS Set this keyword to use the thin-plate-spline method. The default is to use the minimum curvature surface method. Input Grid Description: REGULAR If set, the Z parameter is a two-dimensional array of dimensions (n,m), containing measurements over a regular grid. If any of XGRID, YGRID, XVALUES, or YVALUES are specified, REGULAR is implied. REGULAR is also implied if there is only one parameter, Z. If REGULAR is set, and no grid specifications are present, the grid is set to (0, 1, 2, ...). XGRID A two-element array, [xstart, xspacing], defining the input grid in the x direction. Do not specify both XGRID and XVALUES. XVALUES An n-element array defining the x locations of Z[i,j]. Do not specify both XGRID and XVALUES. YGRID A two-element array, [ystart, yspacing], defining the input grid in the y direction. Do not specify both YGRID and YVALUES. YVALUES An n-element array defining the y locations of Z[i,j]. Do not specify both YGRID and YVALUES. Output Grid Description: GS The output grid spacing. If present, GS must be a two-element vector [xs, ys], where xs is the horizontal spacing between grid points and ys is the vertical spacing. The default is based on the extents of x and y. If the grid starts at x value xmin and ends at xmax, then the default horizontal spacing is (xmax - xmin)/(NX-1). ys is computed in the same way. The default grid size, if neither NX or NY are specified, is 26 by 26. BOUNDS If present, BOUNDS must be a four-element array containing the grid limits in x and y of the output grid: [xmin, ymin, xmax, ymax]. If not specified, the grid limits are set to the extent of x and y. NX The output grid size in the x direction. NX need not be specified if the size can be inferred from GS and BOUNDS. The default value is 26. NY The output grid size in the y direction. NY need not be specified if the size can be inferred from GS and BOUNDS. The default value is 26. XOUT Use the XOUT keyword to specify a vector containing the output grid x values. If this parameter is supplied, GS, BOUNDS, and NX are ignored for the x output grid. XOUT allows you to specify irregularly-spaced output grids. YOUT Use the YOUT keyword to specify a vector containing the output grid y values. If this parameter is supplied, GS, BOUNDS, and NY are ignored for the y output grid. YOUT allows you to specify irregularly-spaced output grids. XPOUT, YPOUT Use the XPOUT and YPOUT keywords to specify arrays that contain the x and y values for the output points. If these keywords are used, the output grid need not be regular, and all other output grid parameters are ignored. XPOUT and YPOUT must have the same number of points, which is also the number of points returned in the result. Examples Example 1: Irregularly gridded cases ; Make a random set of points that lie on a Gaussian: N = 15 X = RANDOMU(seed, N) Y = RANDOMU(seed, N) ; The Gaussian: Z = EXP(-2 * ((X-.5)^2 + (Y-.5)^2)) Use a 26 by 26 grid over the rectangle bounding x and y: ;Get the surface. R = MIN_CURVE_SURF(Z, X, Y) Alternatively, get a surface over the unit square, with spacing of 0.05: R = MIN_CURVE_SURF(Z, X, Y, GS=[0.05, 0.05], BOUNDS=[0,0,1,1]) Alternatively, get a 10 by 10 surface over the rectangle bounding x and y: R = MIN_CURVE_SURF(Z, X, Y, NX=10, NY=10) Example 2: Regularly gridded cases ; Make some random data: z = RANDOMU(seed, 5, 6) ; Interpolate to a 26 x 26 grid: CONTOUR, MIN_CURVE_SURF(z, /REGULAR) See Also CONTOUR, GRID_TPS, TRI_SURF MK_HTML_HELP [Previous Routine] [Next Routine] [List of Routines] NAME: MK_HTML_HELP The MK_HTML_HELP procedure, given a list of IDL procedure filenames (.pro files), VMS text library filenames (.TLB files), or the names of directories containing such files, generates a file in HTML (HyperText Markup Language) format that contains documentation for those routines that contain standard IDL documentation headers. The resulting file can then be viewed with a "World Wide Web" browser such as Mosaic or Netscape. MK_HTML_HELP procedure makes single HTML file that starts with a list of the routines documented in the file. The names of routines in that list are hypertext links to the documentation for those routines. The documentation for each routine is simply the text of the documentation header copied from the corresponding .pro file-no reformatting is performed. The documentation headers of the .pro files in question must have the following format: * The first line of the documentation block contains only the characters ;+, starting in column 1. * The last line of the documentation block contains only the characters ;-, starting in column 1. * All other lines in the documentation block contain a ; in column 1. * If a line containing the string "NAME:" exists in the documentation block, the contents of the following line are used as the name of the routine being described. If the NAME: field is not present, the name of the source file is used as the routine name. The file template.pro in the examples subdirectory of the IDL distribution contains a template for creating your own documentation headers. This routine is supplied for users to make online documentation from their own IDL programs. Although it could be used to create an HTML documentation file from the lib subdirectory of the IDL distribution, we do not recommend doing so. The documentation headers on the files in the lib directory are used for historical purposes-most do not contain the most current or accurate documentation for those routines. The most current documentation for IDL's built-in and library routines is found in IDL's online help system (enter ? at the IDL prompt). This routine is written in the IDL language. Its source code can be found in the file mk_html_help.pro in the lib subdirectory of the IDL distribution. Syntax MK_HTML_HELP, Sources, Filename [, /STRICT] [, TITLE=string] [, /VERBOSE] Arguments Sources A string array containing the names of IDL procedure files (.pro files), VMS text libraries (.TLB files), or directories containing such files. The Sources array may contain both individual file and directory names. Each IDL procedure file must have the file extension .pro, and each VMS text library must include the file extension .TLB. Elements of the Sources array that do not have either of these extensions are assumed to be directories. All .pro files found in Sources are searched for documentation headers. The documentation headers are extracted and saved in HTML format in the file specified by Filename. Note More than one documentation block may exist in a single input file. Filename A string containing the name of the output file to be generated. HTML files are usually saved in files named with a .html or .htm extension. Keywords STRICT Set this keyword to force MK_HTML_HELP to adhere strictly to the HTML format by scanning the documentation blocks for HTML reserved characters and replacing them in the output file with the appropriate HTML syntax. HTML reserved characters include < , > , & , and ". By default, this keyword is set to zero to allow for faster processing of the input files. TITLE A string that supples the name to be used as the title of the HTML document. The default is "Extended IDL Help". VERBOSE Set this keyword to display informational messages as MK_HTML_HELP generates the HTML file. Normally, MK_HTML_HELP works silently. Example To generate an HTML help file named myhelp.html from the .pro files in the directory /usr/home/dave/myroutines, use the command: MK_HTML_HELP, '/usr/home/dave/myroutines', 'myhelp.html' To generate an HTML help file for all routines in a given directory whose file names contain the word "plot", use the following commands: plotfiles=FINDFILE('/usr/home/dave/myroutines/*plot*.pro') MK_HTML_HELP, plotfiles, 'myplot.html' See Also DOC_LIBRARY MODIFYCT [Previous Routine] [Next Routine] [List of Routines] NAME: MODIFYCT The MODIFYCT procedure updates the distribution color table file colors1.tbl, located in the \resource\colors subdirectory of the main IDL directory, or a user-designated file with a new, or modified, colortable. This routine is written in the IDL language. Its source code can be found in the file modifyct.pro in the lib subdirectory of the IDL distribution. Syntax MODIFYCT, Itab, Name, R, G, B [, FILE=filename] Arguments Itab The index of the table to be updated, numbered from 0 to 255. If the specified entry is greater than the next available location in the table, the entry will be added to the table in the available location rather than the index specified by Itab. On return, Itab contains the index for the location that was modified or extended. The modified table can be then be loaded with the IDL command: LOADCT, Itab. Name A string, up to 32 characters long, that contains the name for the new color table. R A 256-element vector that contains the values for the red colortable. G A 256-element vector that contains the values for the green colortable. B A 256-element vector that contains the values for the blue colortable. Keywords FILE Set this keyword to the name of a colortable file to be modified instead of the file colors1.tbl. See Also LOADCT, XLOADCT MOMENT [Previous Routine] [Next Routine] [List of Routines] NAME: MOMENT The MOMENT function computes the mean, variance, skewness, and kurtosis of a sample population contained in an n-element vector X. If the vector contains n identical elements, MOMENT computes the mean and variance, and returns the IEEE value NaN for the skewness and kurtosis, which are not defined. (See "Special Floating-Point Values" in Chapter 17 of Building IDL Applications.) When x = (x0, x1, x2, ..., xn-1), the various moments are defined as follows: N ­ 1 Mean = x 1 = ---- N x j j = 0 N ­ 1 Variance 1 = ------------- N ­ 1 (x j ­ x)2 j = 0 N ­ 1 x ­ 3 Skewness 1 = ---- j x ---------------------------- N Variance j = 0 N ­ 1 x ­ 4 Kurtosis 1 = ---- j x ---------------------------- N ­ 3 Variance j = 0 N ­ 1 Mean Absolute Deviation 1 = ---- N x j ­ x j = 0 Standard Deviation = Variance This routine is written in the IDL language. Its source code can be found in the file moment.pro in the lib subdirectory of the IDL distribution. Syntax Result = MOMENT( X [, /DOUBLE] [, MDEV=variable] [, /NAN] [, SDEV=variable] ) Arguments X An n-element integer, single-, or double-precision floating-point vector. Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. MDEV Set this keyword to a named variable that will contain the mean absolute deviation of X. NAN Set this keyword to cause the routine to check for occurrences of the IEEE floating- point value NaN in the input data. Elements with the value NaN are treated as missing data. (See "Special Floating-Point Values" in Chapter 17 of Building IDL Applications for more information on IEEE floating-point values.) SDEV Set this keyword to a named variable that will contain the standard deviation of X. Example ; Define an n-element sample population: X = [65, 63, 67, 64, 68, 62, 70, 66, 68, 67, 69, 71, 66, 65, 70] ; Compute the mean, variance, skewness and kurtosis: result = MOMENT(X) PRINT, 'Mean: ', result[0] & PRINT, 'Variance: ', result[1] & $ PRINT, 'Skewness: ', result[2] & PRINT, 'Kurtosis: ', result[3] IDL prints: Mean: 66.7333 Variance: 7.06667 Skewness: -0.0942851 Kurtosis: -1.18258 See Also KURTOSIS, HISTOGRAM, MAX, MEAN, MEANABSDEV, MEDIAN, MIN, MOMENT, STDDEV, SKEWNESS, VARIANCE MORPH_CLOSE [Previous Routine] [Next Routine] [List of Routines] NAME: MORPH_CLOSE The MORPH_CLOSE function applies the closing operator to a binary or grayscale image. MORPH_CLOSE is simply a dilation operation followed by an erosion operation. The result of a closing operation is that small holes and gaps within the image are filled, yet the original sizes of the primary foreground features are maintained. The closing operation is an idempotent operator-applying it more than once produces no further effect. Both the opening and the closing operators have the effect of smoothing the image, with the opening operation removing pixels, and the closing operation adding pixels. Syntax Result = MORPH_CLOSE (Image, Structure [, /GRAY] [, PRESERVE_TYPE=bytearray | /UINT | /ULONG] [, VALUES=array] ) Arguments Image A one-, two-, or three-dimensional array upon which the closing operation is to be performed. 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-, two-, or three-dimensional array to be used as the structuring element. The elements are interpreted as binary values - either zero or nonzero. The structuring element must have the same number of dimensions as the Image argument. Keywords GRAY Set this keyword to perform a grayscale, rather than binary, operation. Nonzero elements of the Structure parameter determine the shape of the structuring element. If the VALUES keyword is not present, all elements of the structuring element are 0. PRESERVE_TYPE Set this keyword to return the same type as the input array. The input array must be of type BYTE, UINT, or ULONG. This keyword only applies for grayscale erosion/dilation, and is mutually exclusive of UINT and ULONG. UINT Set this keyword to return an unsigned integer array. This keyword only applies for grayscale operations, and is mutually exclusive of the ULONG and PRESERVE_TYPE keywords. ULONG Set this keyword to return an unsigned longword integer array. This keyword only applies for grayscale operations, and is mutually exclusive of the UINT and PRESERVE_TYPE keywords. VALUES An array of the same dimensions as Structure providing the values of the structuring element. The presence of this keyword implies a grayscale operation. Example The following code reads a data file in the IDL Demo data directory containing a magnified image of grains of pollen. It then applies a threshold and a morphological closing operator with a 3 by 3 square kernel to the original image. Notice that most of the holes in the pollen grains have been filled by the closing operator. ;Handle TrueColor displays: DEVICE, DECOMPOSED=0 ;Read the image READ_JPEG, path, img ;Create window: WINDOW, 0, XSIZE=700, YSIZE=540 ;Show original image XYOUTS, 180, 525, 'Original Image', ALIGNMENT=.5, /DEVICE TVSCL, img, 20, 280 ;Apply the threshold creating a binary image thresh = img GE 140B ;Load a simple color table TEK_COLOR ;Display Edges XYOUTS, 520, 525, 'Edges', ALIGNMENT=.5, /DEVICE TV, thresh, 360, 280 ;Apply closing operator closing = MORPH_CLOSE(thresh, REPLICATE(1,3,3)) ;Show the result XYOUTS, 180, 265, 'Closing Operator', ALIGNMENT=.5, /DEVICE TV, closing, 20, 20 ;Show added pixels in white XYOUTS, 520, 265, 'Added Pixels in White', ALIGNMENT=.5, /DEVICE TV, closing + thresh, 360, 20 See Also DILATE, ERODE, MORPH_DISTANCE, MORPH_GRADIENT, MORPH_HITORMISS, MORPH_OPEN, MORPH_THIN, MORPH_TOPHAT MORPH_DISTANCE [Previous Routine] [Next Routine] [List of Routines] NAME: MORPH_DISTANCE The MORPH_DISTANCE function estimates N-dimensional distance maps, which contain for each foreground pixel the distance to the nearest background pixel, using a given norm. Available norms include: Euclidean, which is exact and is also known as the Euclidean Distance Map (EDM), and two more efficient approximations, chessboard and city block. The distance map is useful for a variety of morphological operations: thinning, erosion and dilation by discs of radius "r", and granulometry. Syntax Result = MORPH_DISTANCE (Data [, /BACKGROUND] [, NEIGHBOR_SAMPLING={1 | 2 | 3 }] [, /NO_COPY] ) Return Value The returned variable is an array of the same dimension as the input array. Arguments Data An input binary array. Zero-valued pixels are considered to be part of the background. Keywords BACKGROUND By default, the EDM is computed for the foreground (non-zero) features in the Data argument. Set this keyword to compute the EDM of the background features instead of the foreground features. If the keyword is set, elements of Result that are on an edge are set to 0. NEIGHBOR_SAMPLING Set this keyword to indicate how the distance of each neighbor from a given pixel is determined. Valid values include: * 0 = default. No diagonal neighbors. Each neighbor is assigned a distance of 1. * 1 = chessboard. Each neighbor is assigned a distance of 1. * 2 = city block. Each neighbor is assigned a distance corresponding to the number of pixels to be visited when travelling from the current pixel to the neighbor. (The path can only take 90 degree turns; no diagonal paths are allowed.) * 3 = actual distance. Each neighbor is assigned its actual distance from the current pixel (within the limitations of floating point representations). Default Two Dimensional Example 1 1 X 1 1 Chessboard Two-Dimensional Example 1 1 1 1 X 1 1 1 1 City Block Two-Dimensional Example: 2 1 2 1 X 1 2 1 2 Actual Distance Two-Dimensional Example sqrt(2) 1 sqrt(2) 1 X 1 sqrt(2) 1 sqrt(2) NO_COPY Set this keyword to request that the input array be reused, if possible. If this keyword is set, the input argument is undefined upon return. Example The following code reads a data file in the IDL Demo data directory containing a magnified image of grains of pollen. It then applies a threshold and the morphological distance operator. Thresholding the result distance operator with a value of "n" produces the equivalent of eroding the thresholded image with a disc of radius "n". ;Handle TrueColor displays: DEVICE, DECOMPOSED=0 ;Read the image READ_JPEG, path, img ; Create window: WINDOW, 0, XSIZE=700, YSIZE=540 ; Display the original image XYOUTS, 180, 525, 'Original Image', ALIGNMENT=.5, /DEVICE TV, img, 20, 280 ; Apply the threshold: thresh = img GE 140B ; Display the thresholded image XYOUTS, 520, 525, 'Thresholded Image', ALIGNMENT=.5, /DEVICE TVSCL, thresh, 360, 280 ;Create Euclidean distance function edist = MORPH_DISTANCE(thresh, NEIGHBOR_SAMPLING = 3) ; Display the distance function XYOUTS, 180, 265, 'Distance Function', ALIGNMENT=.5, /DEVICE TVSCL, edist, 20, 20 ; Display image after erosion with a disc of radius 5: XYOUTS, 520, 265, 'After erosion with disc of radius 5', ALIGNMENT=.5, /DEVICE TVSCL, edist GT 5, 360, 20 See Also DILATE, ERODE, MORPH_CLOSE, MORPH_GRADIENT, MORPH_HITORMISS, MORPH_OPEN, MORPH_THIN, MORPH_TOPHAT MORPH_GRADIENT [Previous Routine] [Next Routine] [List of Routines] NAME: MORPH_GRADIENT The MORPH_GRADIENT function applies the morphological gradient operator to a grayscale image. MORPH_GRADIENT is the subtraction of an eroded version of the original image from a dilated version of the original image. The practical result of a morphological gradient operation is that the boundaries of features are highlighted. Syntax Result = MORPH_GRADIENT (Image, Structure [, PRESERVE_TYPE=bytearray | /UINT | /ULONG] [, VALUES=array] ) Arguments Image A one-, two-, or three-dimensional array upon which the morphological gradient operation is to be performed. Structure A one-, two-, or three-dimensional array to be used as the structuring element. The elements are interpreted as binary values - either zero or nonzero. The structuring element must have the same number of dimensions as the Image argument. Keywords PRESERVE_TYPE Set this keyword to return the same type as the input array. The input array must be of type BYTE, UINT, or ULONG. This keyword only applies for grayscale erosion/dilation, and is mutually exclusive of the UINT and ULONG keywords. UINT Set this keyword to return an unsigned integer array. This keyword is mutually exclusive of the ULONG and PRESERVE_TYPE keywords. ULONG Set this keyword to return an unsigned longword integer array. This keyword is mutually exclusive of the UINT and PRESERVE_TYPE keywords. VALUES An array of the same dimensions as the Structure argument providing the values of the structuring element. If the VALUES keyword is not present, all elements of the structuring element are 0. Example The following code reads a data file in the IDL Demo data directory containing a magnified image of grains of pollen. It then creates disc of radius 2, in a 5 by 5 array, with all elements within a radius of 2 from the center set to 1. This disc is used as the structuring element for the morphological gradient which is then displayed as both a gray scale image, and as a thresholded image. ;Handle TrueColor displays: DEVICE, DECOMPOSED=0 ;Read the image READ_JPEG, path, img ; Create window: WINDOW, 0, XSIZE=700, YSIZE=540 ;Show original image XYOUTS, 180, 525, 'Original Image', ALIGNMENT=.5, /DEVICE TVSCL, img, 20, 280 ;Define disc radius r = 2 ;Create a binary disc of given radius. disc = SHIFT(DIST(2*r+1), r, r) LE r bdisc = MORPH_GRADIENT(img, disc) ;Show edges XYOUTS, 520, 525, 'Edges', ALIGNMENT=.5, /DEVICE TVSCL, bdisc, 360, 280 ;Show thresholded edges XYOUTS, 180, 265, 'Threshold Edges', ALIGNMENT=.5, /DEVICE TVSCL, bdisc ge 100, 20, 20 See Also DILATE, ERODE, MORPH_CLOSE, MORPH_DISTANCE, MORPH_HITORMISS, MORPH_OPEN, MORPH_THIN, MORPH_TOPHAT MORPH_HITORMISS [Previous Routine] [Next Routine] [List of Routines] NAME: MORPH_HITORMISS The MORPH_HITORMISS function applies the hit-or-miss operator to a binary image. The hit-or-miss operator is implemented by first applying an erosion operator with a hit structuring element to the original image. Then an erosion operator is applied to the complement of the original image with a secondary miss structuring element. The result is the intersection of the two results. The resulting image corresponds to the positions where the hit structuring element lies within the image, and the miss structure lies completely outside the image. The two structures must not overlap. Syntax Result = MORPH_HITORMISS (Image, HitStructure, MissStructure) Arguments Image A one-, two-, or three-dimensional array upon which the morphological operation is to be performed. The image is treated as a binary image with all nonzero pixels considered as 1. HitStructure A one-, two-, or three-dimensional array to be used as the hit structuring element. The elements are interpreted as binary values - either zero or nonzero. This structuring element must have the same number of dimensions as the Image argument. MissStructure A one-, two-, or three-dimensional array to be used as the miss structuring element. The elements are interpreted as binary values - either zero or nonzero. This structuring element must have the same number of dimensions as the Image argument. Note It is assumed that the HitStructure and the MissStructure arguments are disjoint. Keywords None. Example The following code snippet identifies blobs with a radius of at least 2, but less than 4 in the pollen image. These regions totally enclose a disc of radius 2, contained in the 5 x 5 kernel named "hit", and in turn, fit within a hole of radius 4, contained in the 9 x 9 array named "miss". Executing this specific example identifies four blobs in the image with these attributes. ;Handle TrueColor displays: DEVICE, DECOMPOSED=0 ;Read the image READ_JPEG, path, img WINDOW, 0, XSIZE=700, YSIZE=540 ; Display the original image XYOUTS, 180, 525, 'Original Image', ALIGNMENT=.5, /DEVICE TV, img, 20, 280 rh = 2 ;Radius of hit disc rm = 4 ;Radius of miss disc ;Create a binary disc of given radius. hit = SHIFT(DIST(2*rh+1), rh, rh) LE rh ;Complement of disc for miss miss = SHIFT(DIST(2*rm+1), rm, rm) GT rm ;Load discrete color table TEK_COLOR ;Apply the threshold thresh = img GE 140B ; Display the thresholded image XYOUTS, 520, 525, 'Thresholded Image', ALIGNMENT=.5, /DEVICE TV, thresh, 360, 280 ;Compute matches matches = MORPH_HITORMISS(thresh, hit, miss) ;Expand matches to size of hit disc matches = DILATE(matches, hit) ;Show matches. XYOUTS, 180, 265, 'Matches', ALIGNMENT=.5, /DEVICE TV, matches, 20, 20 ;Superimpose, showing hit regions in blue. ;(Blue = color index 4 for tek_color.) XYOUTS, 520, 265, 'Superimposed, hit regions in blue',$ ALIGNMENT=.5, /DEVICE TV, thresh + 3*matches, 360, 20 See Also DILATE, ERODE, MORPH_CLOSE, MORPH_DISTANCE, MORPH_GRADIENT, MORPH_OPEN, MORPH_THIN, MORPH_TOPHAT MORPH_OPEN [Previous Routine] [Next Routine] [List of Routines] NAME: MORPH_OPEN The MORPH_OPEN function applies the opening operator to a binary or grayscale image. MORPH_OPEN is simply an erosion operation followed by a dilation operation. The result of an opening operation is that small features (e.g., noise) within the image are removed, yet the original sizes of the primary foreground features are maintained. The opening operation is an idempotent operator, applying it more than once produces no further effect. An alternative definition of the opening, is that it is the union of all sets containing the structuring element in the original image. Both the opening and the closing operators have the effect of smoothing the image, with the opening operation removing pixels, and the closing operation adding pixels. Syntax Result = MORPH_OPEN (Image, Structure [, /GRAY] [, PRESERVE_TYPE=bytearray | /UINT | /ULONG] [, VALUES=array] ) Arguments Image A one-, two-, or three-dimensional array upon which the opening operation is to be performed. 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-, two-, or three-dimensional array to be used as the structuring element. The elements are interpreted as binary values - either zero or nonzero. The structuring element must have the same number of dimensions as the Image argument. Keywords GRAY Set this keyword to perform a grayscale, rather than binary, operation. Nonzero elements of the Structure parameter determine the shape of the structuring element. If the VALUES keyword is not present, all elements of the structuring element are 0. PRESERVE_TYPE Set this keyword to return the same type as the input array. The input array must be of type BYTE, UINT, or ULONG. This keyword only applies for grayscale erosion/dilation, and is mutually exclusive of the UINT and ULONG keywords. UINT Set this keyword to return an unsigned integer array. This keyword only applies for grayscale operations, and is mutually exclusive of the ULONG and PRESERVE_TYPE keywords. ULONG Set this keyword to return an unsigned longword integer array. This keyword only applies for grayscale operations and is mutually exclusive of the UINT and PRESERVE_TYPE keywords. VALUES An array of the same dimensions as Structure providing the values of the structuring element. The presence of this keyword implies a grayscale operation. Example The following code reads a data file in the IDL Demo data directory containing an magnified image of grains of pollen. It then applies a threshold and a morphological opening operator with a 3 by 3 square kernel to the original image. Notice that much of the irregular borders of the grains have been smoothed by the opening operator. ; Handle TrueColor displays: DEVICE, DECOMPOSED=0 ;Read the image READ_JPEG, path, img ; Create window: WINDOW, 0, XSIZE=700, YSIZE=540 ;Show original image XYOUTS, 180, 525, 'Original Image', ALIGNMENT=.5, /DEVICE TV, img, 20, 280 ;Apply the threshold thresh = img GE 140B ;Load a simple color table TEK_COLOR ;Display edges XYOUTS, 520, 525, 'Edges', ALIGNMENT=.5, /DEVICE TV, thresh, 360, 280 ;Apply opening operator open = MORPH_OPEN(thresh, REPLICATE(1,3,3)) ;Show the result XYOUTS, 180, 265, 'Opening Operator', ALIGNMENT=.5, /DEVICE TV, open, 20, 20 ;Show pixels that have been removed in white XYOUTS, 520, 265, 'Removed Pixels in White', ALIGNMENT=.5, /DEVICE TV, open + thresh, 360, 20 See Also DILATE, ERODE, MORPH_CLOSE, MORPH_DISTANCE, MORPH_GRADIENT, MORPH_HITORMISS, MORPH_THIN, MORPH_TOPHAT MORPH_THIN [Previous Routine] [Next Routine] [List of Routines] NAME: MORPH_THIN The MORPH_THIN function performs a thinning operation on binary images. The thinning operator is implemented by first applying a hit or miss operator to the original image with a pair of structuring elements, and then subtracting the result from the original image. In typical applications, this operator is repeatedly applied with the two structuring elements, while rotating them after each application, until the result remains unchanged. Syntax Result = MORPH_THIN ( Image, HitStructure, MissStructure ) Arguments Image A one-, two-, or three-dimensional array upon which the thinning operation is to be performed. The image is treated as a binary image with all nonzero pixels considered as 1. HitStructure A one-, two-, or three-dimensional array to be used as the hit structuring element. The elements are interpreted as binary values - either zero or nonzero. This structuring element must have the same number of dimensions as the Image argument. MissStructure A one-, two-, or three-dimensional array to be used as the miss structuring element. The elements are interpreted as binary values - either zero or nonzero. This structuring element must have the same number of dimensions as the Image argument. Note It is assumed that the HitStructure and the MissStructure arguments are disjoint. Keywords None. See Also DILATE, ERODE, MORPH_CLOSE, MORPH_DISTANCE, MORPH_GRADIENT, MORPH_HITORMISS, MORPH_OPEN, MORPH_TOPHAT MORPH_TOPHAT [Previous Routine] [Next Routine] [List of Routines] NAME: MORPH_TOPHAT The MORPH_TOPHAT function applies the top-hat operator to a grayscale image. The top-hat operator is implemented by first applying the opening operator to the original image, then subtracting the result from the original image. Applying the top- hat operator provides a result that shows the bright peaks within the image. Syntax Result = MORPH_TOPHAT ( Image, Structure [, PRESERVE_TYPE=bytearray | /UINT | /ULONG] [, VALUES=array] ) Arguments Image A one-, two-, or three-dimensional array upon which the top-hat operation is to be performed. Structure A one-, two-, or three-dimensional array to be used as the structuring element. The elements are interpreted as binary values - either zero or nonzero. The structuring element must have the same number of dimensions as the Image argument. Keywords PRESERVE_TYPE Set this keyword to return the same type as the input array. The input array must be of type BYTE, UINT, or ULONG. This keyword only applies for grayscale erosion/dilation, and is mutually exclusive of the UINT and ULONG keywords. UINT Set this keyword to return an unsigned integer array. This keyword is mutually exclusive of the ULONG and PRESERVE_TYPE keywords. ULONG Set this keyword to return an unsigned longword integer array. This keyword is mutually exclusive of the UINT and PRESERVE_TYPE keywords. VALUES An array of the same dimensions as the Structure argument providing the values of the structuring element. If the VALUES keyword is not present, all elements of the structuring element are 0. Example The following example illustrates an application of the top-hat operator to an image in the examples/demo/demodata directory: ; Handle TrueColor displays: DEVICE, DECOMPOSED=0 ;Read the image READ_JPEG, path, img ; Create window: WINDOW, 0, XSIZE=700, YSIZE=280 ;Show original XYOUTS, 180, 265, 'Original Image', ALIGNMENT=.5, /DEVICE TVSCL, img, 20, 20 ;Radius of disc r = 2 ;Create a binary disc of given radius. disc = SHIFT(DIST(2*r+1), r, r) LE r ;Apply top-hat operator tophat = MORPH_TOPHAT(img, disc) ;Display stretched result. XYOUTS, 520, 265, 'Stretched Result', ALIGNMENT=.5, /DEVICE TVSCL, tophat < 50, 360, 20 See Also DILATE, ERODE, MORPH_CLOSE, MORPH_DISTANCE, MORPH_GRADIENT, MORPH_HITORMISS, MORPH_OPEN, MORPH_THIN MPEG_CLOSE [Previous Routine] [Next Routine] [List of Routines] NAME: MPEG_CLOSE The MPEG_CLOSE procedure closes an MPEG sequence opened with the MPEG_OPEN routine. Note that MPEG_CLOSE does not save the MPEG file associated with the MPEG sequence; use MPEG_SAVE to save the file. The specified MPEG sequence identifier will no longer be valid after calling MPEG_CLOSE. This routine is written in the IDL language. Its source code can be found in the file mpeg_close.pro in the lib subdirectory of the IDL distribution. Syntax MPEG_CLOSE, mpegID Arguments mpegID The unique identifier of the MPEG sequence to be freed. (MPEG sequence identifiers are returned by the MPEG_OPEN routine.) Example See MPEG_OPEN for an example using this routine. See Also MPEG_OPEN, MPEG_PUT, MPEG_SAVE, XINTERANIMATE MPEG_OPEN [Previous Routine] [Next Routine] [List of Routines] NAME: MPEG_OPEN The MPEG_OPEN function initializes an IDLgrMPEG object for MPEG encoding and returns the object reference. The MPEG routines provide a wrapper around the IDL Object Graphics IDLgrMPEG object, eliminating the need to use the Object Graphics interface to create MPEG files. Note The MPEG standard does not allow movies with odd numbers of pixels to be created. This routine is written in the IDL language. Its source code can be found in the file mpeg_open.pro in the lib subdirectory of the IDL distribution. Note MPEG support in IDL requires a special license. For more information, contact your Research Systems sales representative or technical support. Syntax mpegID = MPEG_OPEN( Dimensions [, BITRATE=value] [, FILENAME=string] [, IFRAME_GAP=integer value] [, MOTION_VEC_LENGTH={1 | 2 | 3}] [ QUALITY=value{0 to 100}] ) Arguments Dimensions A two-element vector of the form [xsize, ysize] indicating the dimensions of the images to be used as frames in the MPEG movie file. All images in the MPEG file must have the same dimensions. Note When creating MPEG files, you must be aware of the capabilities of the MPEG decoder you will be using to view it. Some decoders only support a limited set of sampling and bitrate parameters to normalize computational complexity, buffer size, and memory bandwidth. For example, the Windows Media Player supports a limited set of sampling and bitrate parameters. In this case, it is best to use 352 x 240 x 30 fps or 352 x 288 x 25 fps when determining the dimensions and frame rate for your MPEG file. When opening a file in Windows Media Player that does not use these dimensions, you will receive a "Bad Movie File" error message. The file is not "bad", this decoder just doesn't support the dimensions of the MPEG. Keywords BITRATE Set this keyword to a double-precision value to specify the MPEG movie bit rate. Higher bit rates will create higher quality MPEGs but will increase file size. The following table describes the valid values: MPEG Version Range MPEG 1 0.1 to 104857200.0 MPEG 2 0.1 to 429496729200.0 Table 74: BITRATE Value Range If you do not set this keyword, IDL computes the BITRATE value based upon the value you have specified for the QUALITY keyword. Note Only use the BITRATE keyword if changing the QUALITY keyword value does not produce the desired results. It is highly recommended to set the BITRATE to at least several times the frame rate to avoid unusable MPEG files or file generation errors. FILENAME Set this keyword equal to a string representing the name of the file in which the encoded MPEG sequence is to be saved. The default file name is idl.mpg. IFRAME_GAP Set this keyword to a positive integer value that specifies the number of frames between I frames to be created in the MPEG file. I frames are full-quality image frames that may have a number of predicted or interpolated frames between them. If you do not specify this keyword, IDL computes the IFRAME_GAP value based upon the value you have specified for the QUALITY keyword. Note Only use the IFRAME_GAP keyword if changing the QUALITY keyword value does not produce the desired results. MOTION_VEC_LENGTH Set this keyword to an integer value specifying the length of the motion vectors to be used to generate predictive frames. Valid values include: * 1 = Small motion vectors. * 2 = Medium motion vectors. * 3 = Large motion vectors. If you do not set this keyword, IDL computes the MOTION_VEC_LENGTH value based upon the value you have specified for the QUALITY keyword. Note Only use the MOTION_VEC_LENGTH keyword if changing the QUALITY value does not produce the desired results. QUALITY Set this keyword to an integer value between 0 (low quality) and 100 (high quality) inclusive to specify the quality at which the MPEG stream is to be stored. Higher quality values result in lower rates of time compression and less motion prediction which provide higher quality MPEGs but with substantially larger file size. Lower quality factors may result in longer MPEG generation times. The default is 50. Note Since MPEG uses JPEG (lossy) compression, the original picture quality can't be reproduced even when setting QUALITY to its highest setting. Example The following sequence of IDL commands illustrates the steps needed to create an MPEG movie file from a series of image arrays named image0, image1, .., imagen, where n is the zero-based index of the last image in the movie: ; Open an MPEG sequence: mpegID = MPEG_OPEN() ; Add the first frame: MPEG_PUT, mpegID, IMAGE=image0, FRAME=0 MPEG_PUT, mpegID, IMAGE=image1, FRAME=1 ; Subsequent frames: ... ; Last frame: MPEG_PUT, mpegID, IMAGE=imagen, FRAME=n ; Save the MPEG sequence in the file myMovie.mpg: MPEG_SAVE, mpegID, FILENAME='myMovie.mpg' ; Close the MPEG sequence: MPEG_CLOSE, mpegID See Also MPEG_CLOSE, MPEG_PUT, MPEG_SAVE, XINTERANIMATE MPEG_PUT [Previous Routine] [Next Routine] [List of Routines] NAME: MPEG_PUT The MPEG_PUT procedure stores the specified image array at the specified frame index in an MPEG sequence. This routine is written in the IDL language. Its source code can be found in the file mpeg_put.pro in the lib subdirectory of the IDL distribution. Syntax MPEG_PUT, mpegID [, /COLOR] [, FRAME=frame_number] [, IMAGE=array | , WINDOW=index] [, /ORDER] Arguments mpegID The unique identifier of the MPEG sequence into which the image will be inserted. (MPEG sequence identifiers are returned by the MPEG_OPEN routine.) Keywords COLOR Set this keyword to read off an 8-bit display and pass the information through the current color table to create a 24-bit image. FRAME Set this keyword equal to an integer specifying the frame at which the image is to be loaded. If the frame number matches a previously loaded frame, the previous frame is overwritten. The default is 0. IMAGE Set this keyword equal to an m x n image array or a 3 x m x n True Color image array representing the image to be loaded at the specified frame. This keyword is ignored if the WINDOW keyword is specified. ORDER Set this keyword to indicate that the rows of the image should be drawn from top to bottom. By default, the rows are drawn from bottom to top. WINDOW Set this keyword to the index of a Direct Graphics Window (or to an object reference to an IDLgrWindow or IDLgrBuffer object) to indicate that the image to be loaded is to be read from the given window or buffer. If this keyword is specified, it overrides the value of the IMAGE keyword. Example See MPEG_OPEN for an example using this routine. See Also MPEG_CLOSE, MPEG_OPEN, MPEG_SAVE, XINTERANIMATE MPEG_SAVE [Previous Routine] [Next Routine] [List of Routines] NAME: MPEG_SAVE The MPEG_SAVE procedure encodes and saves an open MPEG sequence. This routine is written in the IDL language. Its source code can be found in the file mpeg_save.pro in the lib subdirectory of the IDL distribution. Note MPEG support in IDL requires a special license. For more information, contact your Research Systems sales representative or technical support. Syntax MPEG_SAVE, mpegID [, FILENAME=string] Arguments mpegID The unique identifier of the MPEG sequence to be saved to a file. (MPEG sequence identifiers are returned by the MPEG_OPEN routine.) Keywords FILENAME Set this keyword to a string representing the name of the file to which the encoded MPEG sequence is to be saved. The default is idl.mpg. Note On VMS, if you do not include a file extension when specifying FILENAME, a period will be added to the filename. For example, if you set the FILENAME keyword to "myfile", the file will be saved as "myfile.". Example See MPEG_OPEN for an example using this routine. See Also MPEG_CLOSE, MPEG_OPEN, MPEG_PUT, XINTERANIMATE MSG_CAT_CLOSE [Previous Routine] [Next Routine] [List of Routines] NAME: MSG_CAT_CLOSE The MSG_CAT_CLOSE procedure closes a catalog file from the stored cache. Syntax MSG_CAT_CLOSE, object Arguments object The object reference returned from MSG_CAT_OPEN. Keywords None See Also MSG_CAT_COMPILE, MSG_CAT_OPEN, IDLffLanguageCat MSG_CAT_COMPILE [Previous Routine] [Next Routine] [List of Routines] NAME: MSG_CAT_COMPILE The MSG_CAT_COMPILE procedure creates an IDL language catalog file. Note The locale is determined from the system locale in effect when compilation takes place. Syntax MSG_CAT_COMPILE, input[, output] [, LOCALE_ALIAS=string] [, /MBCS] Arguments input The input file with which to create the catalog. The file is a text representation of the key/MBCS association. Each line in the file must have a key. The language string must then be surrounded by double quotes, then an optional comment. For example: VERSION "Version 1.0" My revision number of the file There are 2 special tags, one of which must be included when creating the file. APPLICATION (required) SUB_QUERY (optional) output The optional output file name (including path if necessary) of the IDL language catalog file. The naming convention for IDL language catalog files is as follows: idl_ + "Application name" + _ + "Locale" + .cat For example: idl_envi_usa_eng.cat If not set, a default filename is used based on the locale: idl_[locale].cat Keywords LOCALE_ALIAS Set this keyword to a scalar string containing any locale aliases for the locale on which the catalog is being compiled. A semi-colon is used to separate locales. For example: MSG_CAT_COMPILE,'input.txt', 'idl_envi_usa_eng.cat',$ LOCALE_ALIAS='C' MBCS If set, this procedure assumes language strings to be in MBCS format. The default is 8-bit ASCII. See Also MSG_CAT_CLOSE, MSG_CAT_OPEN, IDLffLanguageCat MSG_CAT_OPEN [Previous Routine] [Next Routine] [List of Routines] NAME: MSG_CAT_OPEN The MSG_CAT_OPEN function returns a catalog object for the given parameters if found. If a match is not found, an unset catalog object is returned. If unset, the IDLffLanguageCat::Query method will always return the empty string unless a default catalog is provided. Syntax Result = MSG_CAT_OPEN( application [, DEFAULT_FILENAME=filename] [, FILENAME=string] [, FOUND=variable] [, LOCALE=string] [, PATH=string] [, SUB_QUERY=value] ) Arguments application A scalar string representing the name of the desired application's catalog file. Keywords DEFAULT_FILENAME Set this keyword to a scalar string containing the full path and filename of the catalog file to open if the initial request was not found. FILENAME Set this keyword to a scalar string containing the full path and filename of the catalog file to open. If this keyword is set, application, PATH and LOCALE are ignored. FOUND Set this keyword to a named variable that will contain 1 if a catalog file was found, 0 otherwise. LOCALE Set this keyword to the desired locale for the catalog file. If not set, the current locale is used. PATH Set this keyword to a scalar string containing the path to search for language catalog files. The default is the current directory. SUB_QUERY Set this keyword equal to the value of the SUB_QUERY key to search against. If a match is found, it is used to further sub-set the possible return catalog choices. See Also MSG_CAT_CLOSE, MSG_CAT_COMPILE, IDLffLanguageCat MULTI [Previous Routine] [Next Routine] [List of Routines] NAME: MULTI The MULTI procedure expands the current color table to "wrap around" some number of times. This routine is written in the IDL language. Its source code can be found in the file multi.pro in the lib subdirectory of the IDL distribution. Syntax MULTI, N Arguments N The number of times the color table will wrap. This parameter does not have to be an integer. Example Display an image, load color table 1, and make that color table "wrap around" 3 times. Enter: ;Display a simple image. TVSCL, DIST(256) ;Load color table 1. LOADCT, 1 ;See how the new color table affects the image. MULTI, 3 See Also STRETCH, XLOADCT N_ELEMENTS [Previous Routine] [Next Routine] [List of Routines] NAME: N_ELEMENTS The N_ELEMENTS function returns the number of elements contained in an expression or variable. Syntax Result = N_ELEMENTS(Expression) Arguments Expression The expression for which the number of elements is to be returned. Scalar expressions always have one element. The number of elements in an array is equal to the product of its dimensions. If Expression is an undefined variable, N_ELEMENTS returns zero. Examples Example 1 This example finds the number of elements in an array: ; Create an integer array: I = INTARR(4, 5, 3, 6) ; Find the number of elements in I and print the result: PRINT, N_ELEMENTS(I) Example 2 A typical use of N_ELEMENTS is to check if an optional input is defined, and if not, set it to a default value: IF (N_ELEMENTS(roo) EQ 0) THEN roo=rooDefault The original value of roo may be altered by a called routine, passing a different value back to the caller. Unless you intend for the routine to behave in this manner, you should prevent it by differentiating N_ELEMENTS' parameter from your routine's variable: IF (N_ELEMENTS(roo) EQ 0) THEN rooUse=rooDefault $ ELSE rooUse=roo See Also N_TAGS N_PARAMS [Previous Routine] [Next Routine] [List of Routines] NAME: N_PARAMS The N_PARAMS function returns the number of non-keyword parameters used in calling an IDL procedure or function. This function is only useful within IDL procedures or functions. User-written procedures and functions can use N_PARAMS to determine if they were called with optional parameters. Note In the case of object method procedures and functions, the SELF argument is not counted by N_PARAMS. Syntax Result = N_PARAMS() Arguments None. This function always returns the number of parameters that were used in calling the procedure or function from which N_PARAMS is called. See Also KEYWORD_SET N_TAGS [Previous Routine] [Next Routine] [List of Routines] NAME: N_TAGS The N_TAGS function returns the number of structure tags contained in a structure expression. It optionally returns the size, in bytes, of the structure. Syntax Result = N_TAGS( Expression [, DATA_LENGTH] [, /LENGTH] ) Arguments Expression The expression for which the number of structure tags is to be returned. Expressions that are not of structure type are considered to have no tags. N_TAGS does not search for tags recursively, so if Expression is a structure containing nested structures, only the number of tags in the outermost structure are counted. Keywords DATA_LENGTH Set this new keyword to return the length of the data fields contained within the structure, in bytes. This differs from LENGTH in that it does not include any alignment padding required by the structure. The length of the data for a given structure will be the same on any system. LENGTH Set this keyword to return the length of the structure, in bytes. Note The length of a structure is machine dependent. The length of a given structure will vary depending upon the host machine. IDL pads and aligns structures in a manner consistent with the host machine's C compiler. Example Find the number of tags in the system variable !P and print the result by entering: PRINT, N_TAGS(!P) Find the length of !P, in bytes: PRINT, N_TAGS(!P, /LENGTH) See Also CREATE_STRUCT, N_ELEMENTS, TAG_NAMES NEWTON [Previous Routine] [Next Routine] [List of Routines] NAME: NEWTON The NEWTON function solves a system of n non-linear equations in n dimensions using a globally-convergent Newton's method. The result is an n-element vector containing the solution. NEWTON is based on the routine newt described in section 9.7 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press, and is used by permission. Syntax Result = NEWTON( X, Vecfunc [, CHECK=variable] [, /DOUBLE] [, ITMAX=value] [, STEPMAX=value] [, TOLF=value] [, TOLMIN=value] [, TOLX=value] ) Arguments X An n-element vector containing an initial guess at the solution of the system. Vecfunc A scalar string specifying the name of a user-supplied IDL function that defines the system of non-linear equations. This function must accept an n-element vector argument X and return an n-element vector result. For example, suppose the non-linear system is defined by the following equations: y 2 2 0 = x0 + x1 - 3, y1 = x0 + x1 - 9 We write a function NEWTFUNC to express these relationships in the IDL language: FUNCTION newtfunc, X RETURN, [X[0] + X[1] -3.0, X[0]^2 + X[1]^2 - 9.0] END Keywords CHECK NEWTON calls an internal function named fmin() to determine whether the routine has converged to a local minimum rather than to a global minimum (see Numerical Recipes, section 9.7). Use the CHECK keyword to specify a named variable which will be set to 1 if the routine has converged to a local minimum or to 0 if it has not. If the routine does converge to a local minimum, try restarting from a different initial guess to obtain the global minimum. DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. ITMAX The maximum allowed number of iterations. The default value is 200. STEPMAX The scaled maximum step length allowed in line search. The default value is 100.0. TOLF Set the convergence criterion on the function values. The default value is 1.0 × 10-4. TOLMIN Set the criterion for deciding whether spurious convergence to a minimum of the function fmin() has occurred. The default value is 1.0 × 10-6. TOLX Set the convergence criterion on X. The default value is 1.0 × 10-7. Example Use NEWTON to solve an n-dimensional system of n non-linear equations. Systems of non-linear equations may have multiple solutions; starting the algorithms with different initial guesses enables detection of different solutions. PRO TEST_NEWTON ; Provide an initial guess as the algorithm's starting point: X = [1.0, 5.0] ; Compute the solution: result = NEWTON(X, 'newtfunc') ; Print the result: PRINT, 'For X=[1.0, 5.0], result = ', result ;Try a different starting point. X = [1.0, -1.0] ; Compute the solution: result = NEWTON(X,'newtfunc') ;Print the result. PRINT, 'For X=[1.0, -1.0], result = ', result END FUNCTION newtfunc, X RETURN, [X[0] + X[1] -3.0, X[0]^2 + X[1]^2 - 9.0] END IDL prints: For X=[1.0, 5.0], result = 0.000398281 3.00000 For X=[1.0, -1.0], result = 3.00000 -6.45883e-005 See Also BROYDEN, FX_ROOT, FZ_ROOTS NORM [Previous Routine] [Next Routine] [List of Routines] NAME: NORM The NORM function computes the Euclidean norm of a vector. Alternatively, NORM computes the Infinity norm of an array. This routine is written in the IDL language. Its source code can be found in the file norm.pro in the lib subdirectory of the IDL distribution. Syntax Result = NORM( A [, LNORM] [, /DOUBLE] ) Arguments A A can be either of the following: * An n-element real or complex vector, if NORM is being used to compute the Euclidean norm of a vector. * An m by n real or complex array, if NORM is being used to compute the Infinity norm of an array. Keywords LNORM Set this keyword to indicate which norm to compute. If A is a vector, then the possible values of this keyword are: * LNORM = 0 Compute the L norm, defined as MAX(ABS(A)). * LNORM = 1 Compute the L1 norm, defined as TOTAL(ABS(A)). * LNORM = 2 Compute the L2 norm, defined as SQRT(TOTAL(ABS(A)^2)). * LNORM = n Compute the Ln norm, defined as (TOTAL(ABS(A)^n))^(1/n) where n is any number, float-point or integer. LNORM for vectors is set to 2 by default. If A is a two-dimensional array, then the possible values of this keyword are: * LNORM = 0 Compute the L norm (the maximum absolute row sum norm), defined as MAX(TOTAL(ABS(A), 1)). * LNORM = 1 Compute the L1 norm (the maximum absolute column sum norm), defined as MAX(TOTAL(ABS(A), 2)). * LNORM = 2 Compute the L2 norm (the spectral norm) defined as the largest singular value, computed from SVDC. For LNORM = 2, A cannot be complex. LNORM for two-dimensional arrays is set to 0 by default. DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. Examples ; Define an n-element complex vector A: A = [COMPLEX(1, 0), COMPLEX(2,-2), COMPLEX(-3,1)] ; Compute the Euclidean norm of A and print: PRINT, 'Euclidian Norm of A =', NORM(A) ; Define an m by n complex array B: B = [[COMPLEX(1, 0), COMPLEX(2,-2), COMPLEX(-3,1)], $ [COMPLEX(1,-2), COMPLEX(2, 2), COMPLEX(1, 0)]] ;Compute the Infinity norm of B and print. PRINT, 'Infinity Norm of B =', NORM(B, /DOUBLE) IDL prints: Euclidian Norm of A = 4.35890 Infinity Norm of B = 6.9907048 See Also COND OBJ_CLASS [Previous Routine] [Next Routine] [List of Routines] NAME: OBJ_CLASS The OBJ_CLASS function returns the name of the class or superclass of its argument, as a string. If the supplied argument is not an object, a null string is returned. If no argument is supplied, OBJ_CLASS returns an array containing the names of all known object classes in the current IDL session. Syntax Result = OBJ_CLASS( [Arg] [, COUNT=variable] [, /SUPERCLASS{must specify Arg}] ) Arguments Arg A scalar object reference or string variable for which the object class name is desired. If Arg is an object reference, it's object class definition is used. If Arg is a string, it is taken to be the name of the class for which information is desired. Passing a string argument is primarily useful in conjunction with the SUPERCLASS keyword. Keywords COUNT Set this keyword equal to a named variable that will contain the number of names returned by OBJ_CLASS. It can be used to determine how many superclasses a class has when the SUPERCLASS keyword is specified. SUPERCLASS Set this keyword to cause OBJ_CLASS to return the names of the object's direct superclasses as a string array, one element per superclass. The superclasses are ordered in the order they appear in the class structure declaration. In the case where the class has no superclasses, a scalar null string is returned, and the COUNT keyword (if specified) returns the value 0. If SUPERCLASS is specified, the Arg argument must also be supplied. OBJ_DESTROY [Previous Routine] [Next Routine] [List of Routines] NAME: OBJ_DESTROY The OBJ_DESTROY procedure is used to destroy an object. If the class (or one of its superclasses) supplies a procedure method named CLEANUP, the method is called and all arguments and keywords passed by the user are passed to it. This method should perform any required cleanup on the object and return. Whether a CLEANUP method actually exists or not, IDL will destroy the heap variable representing the object and return. Note that OBJ_DESTROY does not recurse. That is, if object1 contains a reference to object2, destroying object1 will not destroy object2. Take care not to lose the only reference to an object by destroying an object that contains that reference. Recursive cleanup of object hierarchies is a good job for a CLEANUP method. Syntax OBJ_DESTROY, ObjRef [, Arg1, ..., Argn] Arguments ObjRef The object reference for the object to be destroyed. ObjRef can be an array, in which case all of the specified objects are destroyed in turn. If the NULL object reference is passed, OBJ_DESTROY ignores it quietly. Arg1...Argn Any arguments accepted by the CLEANUP method for the object being destroyed can be specified as additional arguments to OBJ_DESTROY. Keywords Any keywords accepted by the CLEANUP method for the object being destroyed can be specified as keywords to OBJ_DESTROY. OBJ_ISA [Previous Routine] [Next Routine] [List of Routines] NAME: OBJ_ISA When one object class is subclassed (inherits) from another class, there is an "Is A" relationship between them. The OBJ_ISA function is used to determine if an object instance is subclassed from the specified class. OBJ_ISA returns True (1) if the specified variable is an object and has the specified class in its inheritance graph, or False (0) otherwise. Syntax Result = OBJ_ISA(ObjectInstance, ClassName) Arguments ObjectInstance A scalar or array variable for which the OBJ_ISA test should be performed. The result is of type byte, and has the same size and organization as ObjectInstance. ClassName A string giving the name of the class for which ObjectInstance is being tested. OBJ_NEW [Previous Routine] [Next Routine] [List of Routines] NAME: OBJ_NEW Given the name of a structure that defines an object class, the OBJ_NEW function returns an object reference to a new instance of the specified object type by carrying out the following operations in order: 1. If the class structure has not been defined, IDL will attempt to find and call a procedure to define it automatically. (See Chapter 20, "Object Basics" in Building IDL Applications for details.) If the structure is still not defined, OBJ_NEW fails and issues an error. 2. If the class structure has been defined, OBJ_NEW creates an object heap variable containing a zeroed instance of the class structure. 3. Once the new object heap variable has been created, OBJ_NEW looks for a method function named Class::INIT (where Class is the actual name of the class). If an INIT method exists, it is called with the new object as its implicit SELF argument, as well as any arguments and keywords specified in the call to OBJ_NEW. If the class has no INIT method, the usual method-searching rules are applied to find one from a superclass. For more information on methods and method-searching rules, see "Method Routines" in Chapter 20 of Building IDL Applications. The INIT method is expected to initialize the object instance data as necessary to meet the needs of the class implementation. INIT should return a scalar TRUE value (such as 1) if the initialization is successful, and FALSE (such as 0) if the initialization fails. Note OBJ_NEW does not call all the INIT methods in an object's class hierarchy. Instead, it simply calls the first one it finds. Therefore, the INIT method for a class should call the INIT methods of its direct superclasses as necessary. 4. If the INIT method returns true, or if no INIT method exists, OBJ_NEW returns an object reference to the heap variable. If INIT returns false, OBJ_NEW destroys the new object and returns the NULL object reference, indicating that the operation failed. Note that in this case the CLEANUP method is not called. See "Destruction" in Chapter 20 of Building IDL Applications for more on CLEANUP methods. If called without arguments, OBJ_NEW returns a NULL object reference. The NULL object reference is a special value that never refers to a value object. It is primarily used as a placeholder in structure definitions, and as the initial value for elements of object arrays created via OBJARR. The null object reference is useful as an indicator that an object reference is currently not usable. Syntax Result = OBJ_NEW( [ObjectClassName [, Arg1......Argn]] ) Arguments ObjectClassName String giving the name of the structure type that defines the object class for which a new object should be created. If ObjectClassName is not provided, OBJ_NEW does not create a new heap variable, and returns the Null Object, which is a special object reference that is guaranteed to never point at a valid object heap variable. The null object is a convenient value to use when defining structure definitions for fields that are object references, since it avoids the need to have a pre-existing valid object reference. Arg1...Argn Any arguments accepted by the INIT method for the class of object being created can be specified when the object is created. Keywords Any keywords accepted by the INIT method for the class of object being created can be specified when the object is created. OBJ_VALID [Previous Routine] [Next Routine] [List of Routines] NAME: OBJ_VALID The OBJ_VALID function verifies the validity of its argument object references, or alternatively returns a vector of references to all the existing valid objects. If called with an argument, OBJ_VALID returns a byte array of the same size as the argument. Each element of the result is set to True (1) if the corresponding object reference in the argument refers to an existing object, and False (0) otherwise. If called with an integer or array of integers as its argument and the CAST keyword is set, OBJ_VALID returns an array of object references. Each element of the result is a reference to the heap variable indexed by the integer value. Integers used to index heap variables are shown in the output of the HELP and PRINT commands. This is useful primarily in programming/debugging when the you have lost a reference but see it with HELP and need to get a reference to it interactively in order to determine what it is and take steps to fix the code. See the "Examples" section below for an example. If no argument is specified, OBJ_VALID returns a vector of references to all existing valid objects. If no valid objects exist, a scalar null object reference is returned. Syntax Result = OBJ_VALID( [Arg] [, CAST=integer] [, COUNT=variable] ) Arguments Arg Scalar or array argument of object reference type. Keywords CAST Set this keyword equal to an integer that indexes a heap variable to create a new pointer to that heap variable. Integers used to index heap variables are shown in the output of the HELP and PRINT commands. This is useful primarily in programming/debugging when the you have lost a reference but see it with HELP and need to get a reference to it interactively in order to determine what it is and take steps to fix the code. See the "Examples" section below for an example. COUNT Set this keyword equal to a named variable that will contain the number of currently valid objects. This value is returned as a longword integer. Examples To determine if a given object reference refers to a valid heap variable, use: IF (OBJ_VALID(obj)) THEN ... To destroy all existing pointer heap variables: OBJ_DESTROY, OBJ_VALID() You can use the CAST keyword to "reclaim" lost object references. For example: ; Create a class structure: junk = {junk, data1:0, data2:0.0} ; Create an object: A = OBJ_NEW('junk') ; Find the integer index: PRINT, A ; In this case, the integer index to the heap variable is 3. If we ; reassign the variable A, we will "lose" the object reference, but ; the heap variable will still exist. ; Lose the object reference: A = 0 PRINT, A, OBJ_VALID() ; We can reclaim the lost heap variable using the CAST keyword: A = OBJ_VALID(3, /CAST) PRINT, A IDL prints: 0 OBJARR [Previous Routine] [Next Routine] [List of Routines] NAME: OBJARR The OBJARR function returns an object reference vector or array. The individual elements of the array are set to the NULL object reference. Syntax Result = OBJARR( D1, ..., D8 [, /NOZERO] ) Arguments Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. The dimensions of the result. The dimension parameters can be any scalar expression. Up to eight dimensions can be specified. Keywords NOZERO OBJARR sets every element of the result to the null object reference. If NOZERO is nonzero, this initialization is not performed and OBJARR executes faster. Warning If you specify NOZERO, the resulting array will have whatever value happens to exist at the system memory location that the array is allocated from. You should be careful to initialize such an array to valid object reference values. Example Create a 3 element by 3 element object reference array with each element containing the null object reference: A = OBJARR(3, 3) ON_ERROR [Previous Routine] [Next Routine] [List of Routines] NAME: ON_ERROR The ON_ERROR procedure determines the action taken when an error is detected inside an IDL user procedure or function by setting state information applying to the current routine and all nested routines. If an override exists within the nested routine, it takes precedence over the ON_ERROR call. Syntax ON_ERROR, N Arguments N An integer that specifies the action to take. Valid values for N are: * 0: Stop at the statement in the procedure that caused the error, the default action. * 1: Return all the way back to the main program level. * 2: Return to the caller of the program unit that established the ON_ERROR condition. * 3: Return to the program unit that established the ON_ERROR condition. See Also CATCH, MESSAGE, ON_IOERROR ON_IOERROR [Previous Routine] [Next Routine] [List of Routines] NAME: ON_IOERROR The ON_IOERROR procedure specifies a statement to be jumped to if an I/O error occurs in the current procedure. Normally, when an I/O error occurs, an error message is printed and program execution is stopped. If ON_IOERROR is called and an I/O related error later occurs in the same procedure activation, control is transferred to the designated statement with the error code stored in the system variable !ERROR_STATE. The text of the error message is contained in !ERROR_STATE.MSG. The effect of ON_IOERROR can be canceled by using the label "NULL" in the call. Syntax ON_IOERROR, Label Label: Statement to perform upon I/O error Example The following code segment reads an integer from the keyboard. If an invalid number is entered, the program re-prompts. i = 0 ; Number to read: valid = 0 ; Valid flag WHILE valid EQ 0 DO BEGIN ON_IOERROR, bad_num READ, 'Enter Number: ', i ;If we get here, i is good. VALID = 1 bad_num: IF NOT valid THEN $ PRINT, 'You entered an invalid number.' ENDWHILE END See Also CATCH, MESSAGE, ON_ERROR ONLINE_HELP [Previous Routine] [Next Routine] [List of Routines] NAME: ONLINE_HELP The ONLINE_HELP procedure invokes the hypertext help viewer. If called with no arguments, it simply starts the help viewer with the default IDL help file displayed. Optionally, a different book, a keyword search string, or a context number can be specified. Note that this procedure is intended for use in user-written routines. To invoke IDL's online help from the command line, it is much simpler to use the ? command. Syntax ONLINE_HELP [, Value] [, BOOK=`filename'] [, /CONTEXT] [, /FULL_PATH] [, /HTML_HELP] [, /QUIT] [, /TOPICS] Arguments Value An optional string that contains text to be searched for using the viewer's Index dialog. If this argument is omitted, the specified or default file is displayed at its beginning. If the CONTEXT keyword is set, this argument should be an integer value (not a string) that represents the context number of the help topic to be displayed. Keywords BOOK Set this keyword to a string containing the name of the Help file to be displayed. If this keyword is omitted, the default IDL help file is displayed. Any file specified by this keyword must be in the appropriate format for the viewer being invoked: * On Windows, the file must be a Windows WinHelp (.hlp) or HTML Help (.chm) file. * On UNIX and VMS, the file must be a Bristol HyperHelp .hlp file. * On Macintosh, the file must be an Altura QuickHelp file. By default, this string should be the name of a file found in the default location for IDL's Help files (i.e., wherever the file idl.hlp is installed), without a path or file extension. You can set the !HELP_PATH system variable or the IDL_HELP_PATH environment variable to the directory where your Help file exists. However, if the FULL_PATH keyword is set, this string should be a complete path and filename to the online help file you wish to display. CONTEXT Set this keyword to indicate that the Value argument is an integer value that represents the context number of the help topic to be displayed. This keyword is intended for use with user-compiled help files that contain topics that have been mapped to specific context numbers when they were compiled using the [MAP] section of the help project file. Specifying a non-existent context number causes the first topic of the requested help file to be displayed. For more information on how to create Help files with context numbers, see the documentation for the Help system compiler that you are using. FULL_PATH Set this keyword to indicate that the string specified by the BOOK keyword is the full path to the file, rather than the default file path specification, as described above. HTML_HELP If set, the Windows HTML Help system is used. All other keywords to ONLINE_HELP behave as specified, but the HTML help system is utilized. Note that a default file extension of .chm is used, not .hlp. QUIT Set this keyword to close the Help viewer. TOPICS If set, the Topics dialog of the Help system will be shown for the specified help file. Examples In the following example, the ONLINE_HELP routine launches the Help viewer and displays the Index dialog at the entry for "handle" if it exists: ONLINE_HELP, 'handle' In the next example, the Help file named adg.hlp, located in the default directory, is displayed: ONLINE_HELP, BOOK='adg' In the next example, the Help file named myhelp.hlp, located in a directory named /usr/home/keith, is displayed: ONLINE_HELP, BOOK='/usr/home/keith/myfile.hlp', /FULL_PATH In the next example, the topic corresponding to context number 100 is displayed: ONLINE_HELP, 100, /CONTEXT, $ BOOK='/usr/home/keith/myfile.hlp', /FULL_PATH See Also MK_HTML_HELP, CH OPEN [Previous Routine] [Next Routine] [List of Routines] NAME: OPEN The three OPEN procedures open a specified file for input and/or output. * OPENR (OPEN Read) opens an existing file for input only. * OPENW (OPEN Write) opens a new file for input and output. When creating a new file under VMS, a new file with the same name and a higher version number is created. Under other operating systems, if the file exists, it is truncated and its old contents are destroyed. * OPENU (OPEN Update) opens an existing file for input and output. Syntax There are three forms of the OPEN procedure: OPENR, Unit, File [, Record_Length] OPENW, Unit, File [, Record_Length] OPENU, Unit, File [, Record_Length] Keywords (all platforms): [, NOEXPAND_PATH] [, /APPEND | , /COMPRESS] [, BUFSIZE={0 | 1 | value>512}] [, /DELETE] [, ERROR=variable] [, /F77_UNFORMATTED] [, /GET_LUN] [, /MORE] [, /STDIO] [, /SWAP_ENDIAN] [, SWAP_IF_BIG_ENDIAN] [, /SWAP_IF_LITTLE_ENDIAN] [, /VAX_FLOAT] [, WIDTH=value] [, /XDR] Macintosh-Only Keywords: [, MACCREATOR=string] [, MACTYPE= string] UNIX-Only Keywords: [, /RAWIO] VMS-Only Keywords: [, /BLOCK | , /SHARED | , /UDF_BLOCK] [, DEFAULT=`.extension'] [, /EXTENDSIZE] [, /FIXED] [, /FORTRAN] [, INITIALSIZE=blocks] [, /KEYED] [, /LIST] [, /NONE] [, /PRINT] [, /SEGMENTED] [, /STREAM] [, /SUBMIT] [, /SUPERSEDE] [, /TRUNCATE_ON_CLOSE] [, /VARIABLE] Arguments Unit The unit number to be associated with the opened file. File A string containing the name of the file to be opened. Note the following platform- specific behaviors: * Under UNIX, the filename can contain any wildcard characters recognized by the shell specified by the SHELL environment variable. However, it is faster not to use wildcards because IDL doesn't use the shell to expand file names unless it has to. No wildcard characters are allowed under VMS. * Under VMS, filenames that do not have a file extension are assumed to have the .DAT extension. No such processing of file names occurs under UNIX. Record_Length The Record_Length argument has meaning only under VMS. It specifies the file record size in bytes. This argument is required when creating new, fixed-length files, and is optional when opening existing files. If this argument is present when creating variable-length record files, it specifies the maximum allowed record size. If this argument is present and no file organization keyword is specified, fixed-length records are implied. Due to limitations in RMS (the VMS Record Management System), the length of records must always be an even number of bytes. Odd record lengths are therefore automatically rounded up to the nearest even boundary. Keywords NOEXPAND_PATH If specified, File is used exactly as specified, without applying the usual file path expansion. Note Platform-specific keywords are listed at the end of this section. APPEND Set this keyword to open the file with the file pointer at the end of the file, ready for data to be appended. Normally, the file is opened with the file pointer at the beginning of the file. Under UNIX, use of APPEND prevents OPENW from truncating existing file contents. The APPEND and COMPRESS keywords are mutually exclusive and cannot be specified together. BUFSIZE Set this keyword to a value greater than 512 to specify the size of the I/O buffer (in bytes) used when reading and writing files. Setting BUFSIZE=1 (or any other value less than 512) sets the buffer to the default size, which is platform-specific. Set BUFSIZE=0 to disable I/O buffering. Note that the buffer size is only changeable when reading and writing stream files. Under UNIX, the RAWIO keyword must not be set. Also not that the system stdio may choose to ignore the buffer size setting. COMPRESS If COMPRESS is set, IDL reads and writes all data to the file in the standard GZIP format. IDL's GZIP support is based on the freely available ZLIB library version 1.1.3 by Mark Adler and Jean-loup Gailly. This means that IDL's compressed files are 100% compatible with the widely available gzip and gunzip programs. COMPRESS cannot be used with the APPEND keyword. Note Under VMS, the COMPRESS keyword can only be used with stream files. DELETE Set this keyword to delete the file when it is closed. Warning Setting the DELETE keyword causes the file to be deleted even if it was opened for read-only access. In addition, once a file is opened with this keyword, there is no way to cancel its operation. ERROR A named variable to place the error status in. If an error occurs in the attempt to open File, IDL normally takes the error handling action defined by the ON_ERROR and/or ON_IOERROR procedures. OPEN always returns to the caller without generating an error message when ERROR is present. A nonzero error status indicates that an error occurred. The error message can then be found in !ERROR_STATE.MSG. For example, statements similar to the following can be used to detect errors: ; Try to open the file demo.dat: OPENR, 1, 'demo.dat', ERROR = err ; If err is nonzero, something happened. Print the error message to ; the standard error file (logical unit -2): IF (err NE 0) then PRINTF, -2, !ERROR_STATE.MSG F77_UNFORMATTED Unformatted variable-length record files produced by UNIX FORTRAN programs contain extra information along with the data in order to allow the data to be properly recovered. This method is necessary because FORTRAN input/output is based on record-oriented files, while UNIX files are simple byte streams that do not impose any record structure. Set the F77_UNFORMATTED keyword to read and write this extra information in the same manner as f77(1), so that data to be processed by both IDL and FORTRAN. See "UNIX-Specific Information" in Chapter 8 of Building IDL Applications for further details. Warning Do not confused this keyword with the VMS-only keyword FORTRAN. GET_LUN Set this keyword to use the GET_LUN procedure to set the value of Unit before the file is opened. Instead of using the two statements: GET_LUN, Unit OPENR, Unit, 'data.dat' you can use the single statement: OPENR, Unit, 'data.dat', /GET_LUN MORE If MORE is set, and the specified File is a terminal, then all output to this unit is formatted in a manner similar to the UNIX more(1) command and sent to the standard output stream. Output pauses at the bottom of each screen, at which point the user can press one of the following keys: * Space: Display the next page of text. * Return: Display the next line of text. * `q' or `Q': Suppress all remaining output. * `h' or `H': Display this list of options. For example, the following statements show how to output a file named text.dat to the terminal: ; Open the text file: OPENR, inunit, 'text.dat', /GET_LUN ; Open the terminal as a file: OPENW, outunit, '/dev/tty', /GET_LUN, /MORE ; Read the first line: line = '' & READF, inunit, line ; While there is text left, output it: WHILE NOT EOF(inunit) DO BEGIN PRINTF, outunit, line READF, inunit, line ENDWHILE ; Close the files and deallocate the units: FREE_LUN, inunit & FREE_LUN, outunit Under VMS, the MORE keyword is only allowed for stream mode files. STDIO Forces the file to be opened via the standard C I/O library (stdio) rather than any other more native OS API that might usually be used. This is primarily of interest to those who intend to access the file from external code, and is not necessary for most files. Note If you intend to use the opened file with the READ_JPEG or WRITE_JPEG procedures using their UNIT keyword, you must specify the STDIO keyword to OPEN to ensure that the file is compatible. The only exception to this rule is if the filename ends in .jpg or .jpeg and the STDIO keyword is not present in the call to OPEN. In this case OPEN, by default uses stdio which covers most uses of jpeg files without requiring the user to take special steps. SWAP_ENDIAN Set this keyword to swap byte ordering for multi-byte data when performing binary I/O on the specified file. This is useful when accessing files also used by another system with byte ordering different than that of the current host. SWAP_IF_BIG_ENDIAN Setting this keyword is equivalent to setting SWAP_ENDIAN; it only takes effect if the current system has big endian byte ordering. This keyword does not refer to the byte ordering of the input data, but to the computer hardware. SWAP_IF_LITTLE_ENDIAN Setting this keyword is equivalent to setting SWAP_ENDIAN; it only takes effect if the current system has little endian byte ordering. This keyword does not refer to the byte ordering of the input data, but to the computer hardware. VAX_FLOAT The opened file contains VAX format floating point values. This keyword implies little endian byte ordering for all data contained in the file, and supersedes any setting of the SWAP_ENDIAN, SWAP_IF_BIG_ENDIAN, or SWAP_IF_LITTLE_ENDIAN keywords. The default setting for this keyword is FALSE. Under VMS, starting the VAX_FLOAT option to the IDL command at startup has the effect of changing this default and making it TRUE. See "Command Line Options" in Chapter 4 of Using IDL for details on this qualifier. You can change this setting at runtime using the VAX_FLOAT function. Warning Please read "Note On IEEE to VAX Format Conversion" on page 969 before using this feature. WIDTH The desired output width. When using the defaults for formatted output, IDL uses the following rules to determine where to break lines: * If the output file is a terminal, the terminal width is used. Under VMS, if the file has fixed-length records or a maximum record length, the record length is used. * Otherwise, a default of 80 columns is used. The WIDTH keyword allows the user to override this default. XDR Set this keyword to open the file for unformatted XDR (eXternal Data Representation) I/O via the READU and WRITEU procedures. Use XDR to make binary data portable between different machine architectures by reading and writing all data in a standard format. When a file is open for XDR access, the only I/O data transfer procedures that can be used with it are READU and WRITEU. XDR is described in "Portable Unformatted Input/Output" in Chapter 8 of Building IDL Applications. Under VMS, the XDR keyword can only be used with stream files. Macintosh-Only Keywords MACCREATOR Use this keyword to specify a four-character scalar string identifying the Macintosh file creator code of the file being created. For example, set MACCREATOR = 'MSWD' to create a file with the creator code MSWD. The default creator code is MIDL. MACTYPE Use this keyword to specify a four-character scalar string identifying the Macintosh file type of the file being created. For example, set MACTYPE = 'PICT' to create a file of type PICT. The default file type is TEXT. Windows-Only Keywords The Windows-Only keywords BINARY and NOAUTOMODE are now obsolete. Input/Output on Windows is now handled indentically to Unix, and does not require you to be concerned about the difference between "text" and "binary" modes. These keywords are still accepted for backwards compatibility, but are ignored. UNIX-Only Keywords The previous keyword NOSTDIO is now obsolete. It has been renamed RAWIO to reflect the fact that stdio may or may not actually be used. All references to NOSTDIO should be changed to be RAWIO, but NOSTDIO will still be accepted as a synonym for RAWIO. RAWIO Set this keyword to disable all use of the standard UNIX I/O for the file, in favor of direct calls to the operating system. This allows direct access to devices, such as tape drives, that are difficult or impossible to use effectively through the standard I/O. Using this keyword has the following implications: * No formatted or associated (ASSOC) I/O is allowed on the file. Only READU and WRITEU are allowed. * Normally, attempting to read more data than is available from a file causes the unfilled space to be set to zero and an error to be issued. This does not happen with files opened with RAWIO. When using RAWIO, the programmer must check the transfer count, either via the TRANSFER_COUNT keywords to READU and WRITEU, or the FSTAT function. * The EOF and POINT_LUN functions cannot be used with a file opened with RAWIO. * Each call to READU or WRITEU maps directly to UNIX read(2) and write(2) system calls. The programmer must read the UNIX system documentation for these calls and documentation on the target device to determine if there are any special rules for I/O to that device. For example, the size of data that can be transferred to many cartridge tape drives is often forced to be a multiple of 512 bytes. VMS-Only Keywords BLOCK Set this keyword to process the file using RMS block mode. In this mode, most RMS processing is bypassed and IDL reads and writes to the file in disk block units. Such files can only be accessed via unformatted I/O commands. Block mode files are treated as an uninterpreted stream of bytes in a manner similar to UNIX stream files. For best performance, by default IDL uses RMS block mode for fixed length record files. However, when the SHARED keyword is present, IDL uses standard RMS mode. Do not specify both BLOCK and SHARED. This keyword is ignored when used with stream files. Note With some controller/disk combinations, RMS does not allow transfer of an odd number of bytes. DEFAULT A scalar string that provides a default file specification from which missing parts of the File argument are taken. For example, to make .LOG be the default file extension when opening a new file, use the command: OPENW, 'DATA', DEFAULT='.LOG' This statement will open the file DATA.LOG. EXTENDSIZE File extension is a relatively slow operation, and it is desirable to minimize the number of times it is done. In order to avoid the unacceptable performance that would result from extending a file a single block at a time, VMS extends its size by a default number of blocks in an attempt to trade a small amount of wasted disk space for better performance. The EXTENDSIZE keyword overrides the default, and specifies the number of disk blocks by which the file should be extended. This keyword is often used in conjunction with the INITIALSIZE and TRUNCATE_ON_CLOSE keywords. FIXED Set this keyword to indicate that the file has fixed-length records. The Record_Length argument is required when opening new, fixed-length files. FORTRAN Set this keyword to use FORTRAN-style carriage control when creating a new file. The first byte of each record controls the formatting. INITIALSIZE The initial size of the file allocation in blocks. This keyword is often used in conjunction with the EXTENDSIZE and TRUNCATE_ON_CLOSE keywords. KEYED Set this keyword to indicate that the file has indexed organization. Indexed files are discussed in "VMS-Specific Information" in Chapter 8 of Building IDL Applications. LIST Set this keyword to specify carriage-return carriage control when creating a new file. If no carriage-control keyword is specified, LIST is the default. NONE Set this keyword to specify explicit carriage control when creating a new file. When using explicit carriage control, VMS does not add any carriage control information to the file, and the user must explicitly add any desired carriage control to the data being written to the file. PRINT Set this keyword to send the file to SYS$PRINT, the default system printer, when it is closed. SEGMENTED Set this keyword to indicate that the file has VMS FORTRAN-style segmented records. Segmented records are a method by which FORTRAN allows logical records to exist with record sizes that exceed the maximum possible physical record sizes supported by VMS. Segmented record files are useful primarily for passing data between FORTRAN and IDL programs. SHARED Set this keyword to allow other processes read and write access to the file in parallel with IDL. If SHARED is not set, read-only files are opened for read sharing and read/write files are not shared. The SHARED keyword cannot be used with STREAM files. Warning It is not a good idea to allow shared write access to files open in RMS block mode. In block mode, VMS cannot perform the usual record locking that prevents file corruption. It is therefore possible for multiple writers to corrupt a block mode file. This warning also applies to fixed-length record disk files, which are also processed in block mode. When using SHARED, do not specify either BLOCK or UDF_BLOCK. STREAM Set this keyword to open the file in stream mode using the Standard C Library (stdio). SUBMIT Set this keyword to submit the file to SYS$BATCH, the default system batch queue, when it is closed. SUPERSEDE Set this keyword to allow an existing file to be superseded by a new file of the same name, type, and version. TRUNCATE_ON_CLOSE Set this keyword to free any unused disk space allocated to the file when the file is closed. This keyword can be used to get rid of excess allocations caused by the EXTENDSIZE and INITIALSIZE keywords. If the SHARED keyword is set, or the file is open for read-only access, TRUNCATE_ON_CLOSE has no effect. UDF_BLOCK Set this keyword to create a file similar to those created with the BLOCK keyword except that new files are created with the RMS undefined record type. Files created in this way can only be accessed by IDL in block mode, and cannot be processed by many VMS utilities. Do not specify both UDF_BLOCK and SHARED. VARIABLE Set this keyword to indicate that the file has variable-length records. If the Record_Length argument is present, it specifies the maximum record size. Otherwise, the only limit is that imposed by RMS (32767 bytes). If no file organization is specified, variable-length records are the default. Warning VMS variable length records have a 2-byte record-length descriptor at the beginning of each record. Because the FSTAT function returns the length of the data file including the record descriptors, reading a file with VMS variable length records into a byte array of the size returned by FSTAT will result in an RMS EOF error. Note On IEEE to VAX Format Conversion Translation of floating-point values from the IDL's native (IEEE) format to the VAX format and back (IEEE to VAX to IEEE) is not a completely reversible operation, and should be avoided when possible. There are many cases where the recovered values will differ from the original, including: * The VAX floating point format lacks support for the IEEE special values (NaN, Infinity). Hence, their special meaning is lost when they are converted to VAX format and cannot be recovered. * Differences in precision and range can also cause information to be lost in both directions. Research Systems recommends using IEEE/VAX conversions only to read existing VAX format data, and strongly recommends that all new files be created using the IEEE format. For more information, see Building IDL Applications Appendix A, "VMS Floating- Point Arithmetic in IDL". Example The following example opens the IDL distribution file people.dat and reads an image from that file: ; Open 'people.dat' on file unit number 1. The FILEPATH ; function is used to return the full path name to this ; distribution file. OPENR, 1, FILEPATH('people.dat', SUBDIR = ['examples','data']) ; Define a variable into which the image will be read: image=BYTARR(192, 192, /NOZERO) ; Read the data: READU, 1, image ; Display the image: TV, image See Also CLOSE, GET_LUN, POINT_LUN, PRINT/PRINTF, READ/READF, READU, VAX_FLOAT, WRITEU OPLOT [Previous Routine] [Next Routine] [List of Routines] NAME: OPLOT The OPLOT procedure plots vector data over a previously-drawn plot. It differs from PLOT only in that it does not generate a new axis. Instead, it uses the scaling established by the most recent call to PLOT and simply overlays a plot of the data on the existing axis. Syntax OPLOT, [X,] Y [, MAX_VALUE=value] [, MIN_VALUE=value] [, NSUM=value] [, /POLAR] [, THICK=value] Graphics Keywords: [, CLIP=[X0, Y0, X1, Y1]] [, COLOR=value] [, LINESTYLE={0 | 1 | 2 | 3 | 4 | 5}] [, /NOCLIP] [, PSYM=integer{0 to 10}] [, SYMSIZE=value] [, /T3D] [, ZVALUE=value{0 to 1}] Arguments X A vector argument. If X is not specified, Y is plotted as a function of point number (starting at zero). If both arguments are provided, Y is plotted as a function of X. This argument is converted to double-precision floating-point before plotting. Plots created with OPLOT are limited to the range and precision of double precision floating-point values. Y The ordinate data to be plotted. This argument is converted to double-precision floating-point before plotting. Keywords MAX_VALUE The maximum value to be plotted. If this keyword is present, data values greater than the value of MAX_VALUE are treated as missing and are not plotted. Note that the IEEE floating-point value NaN is also treated as missing data. (See "Special Floating-Point Values" in Chapter 17 of Building IDL Applications for more information on IEEE floating-point values.) MIN_VALUE The minimum value to be plotted. If this keyword is present, data values less than the value of MIN_VALUE are treated as missing and are not plotted. Note that the IEEE floating-point value NaN is also treated as missing data. (See "Special Floating-Point Values" in Chapter 17 of Building IDL Applications for more information on IEEE floating-point values.) NSUM The presence of this keyword indicates the number of data points to average when plotting. If NSUM is larger than 1, every group of NSUM points is averaged to produce one plotted point. If there are m data points, then m/NSUM points are displayed. On logarithmic axes a geometric average is performed. It is convenient to use NSUM when there is an extremely large number of data points to plot because it plots fewer points, the graph is less cluttered, and it is quicker. POLAR Set this keyword to produce polar plots. The X and Y vector parameters, both of which must be present, are first converted from polar to Cartesian coordinates. The first parameter is the radius, and the second is expressed in radians. For example, to make a polar plot, use the command: OPLOT, /POLAR, R, THETA THICK Controls the thickness of the lines connecting the points. A thickness of 1.0 is normal, 2.0 is double wide, etc. Graphics Keywords Accepted See Appendix C, "Graphics Keywords" for the description of graphics and plotting keywords not listed above. CLIP, COLOR, LINESTYLE, NOCLIP, PSYM, SYMSIZE, T3D, ZVALUE. Example ; Create a simple dataset: D = SIN(FINDGEN(100)/EXP(FINDGEN(100)/50)) ; Create an X-Y plot of vector D: PLOT, D ; Overplot the sine of D as a thick, dashed line: OPLOT, SIN(D), LINESTYLE = 5, THICK = 2 See Also OPLOTERR, PLOT OPLOTERR [Previous Routine] [Next Routine] [List of Routines] NAME: OPLOTERR The OPLOTERR procedure plots error bars over a previously drawn plot. A plot of X versus Y with error bars drawn from Y - Err to Y + Err is written to the output device over any plot already there. This routine is written in the IDL language. Its source code can be found in the file oploterr.pro in the lib subdirectory of the IDL distribution. Syntax OPLOTERR, [ X ,] Y , Err [, Psym ] Arguments X An optional array of X values. The procedure checks whether or not the third parameter passed is a vector to decide if X was passed. If X is not passed, then INDGEN(Y) is assumed for the X values. Y The array of Y values. Y cannot be of type string. Err The array of error bar values. Psym The plotting symbol to use (default = +7). Keywords None See Also ERRPLOT, OPLOT, PLOTERR P_CORRELATE [Previous Routine] [Next Routine] [List of Routines] NAME: P_CORRELATE The P_CORRELATE function computes the partial correlation coefficient of a dependent variable and one particular independent variable when the effects of all other variables involved are removed. This routine is written in the IDL language. Its source code can be found in the file p_correlate.pro in the lib subdirectory of the IDL distribution. Syntax Result = P_CORRELATE( X, Y, C [, /DOUBLE] ) Arguments X An n-element integer, single-, or double-precision floating-point vector that specifies the independent variable data. Y An n-element integer, single-, or double-precision floating-point vector that specifies the dependent variable data. C An integer, single-, or double-precision floating-point array that specifies the independent variable data whose effects are to be removed. The columns of this two- dimensional array correspond to the n-element vectors of independent variable data. Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. Example ; Define three sample populations: X0 = [64, 71, 53, 67, 55, 58, 77, 57, 56, 51, 76, 68] X1 = [57, 59, 49, 62, 51, 50, 55, 48, 52, 42, 61, 57] X2 = [ 8, 10, 6, 11, 8, 7, 10, 9, 10, 6, 12, 9] ; Compute the partial correlation of X0 and X1 with the effects ; of X2 removed. result = P_CORRELATE(X0, X1, REFORM(X2, 1, N_ELEMENTS(X2))) PRINT, result IDL prints: 0.533469 See Also A_CORRELATE, C_CORRELATE, CORRELATE, M_CORRELATE, R_CORRELATE PARTICLE_TRACE [Previous Routine] [Next Routine] [List of Routines] NAME: PARTICLE_TRACE The PARTICLE_TRACE procedure traces the path of a massless particle through a vector field. The function allows the user to specify a set of starting points and a vector field. The input seed points can come from any vertex-producing process. The points are tracked by treating the vector field as a velocity field and integrating. Each path is tracked until the path leaves the input volume or a maximum number of steps is reached. The vertices generated along the paths are returned packed into a single array along with a polyline connectivity array. The polyline connectivity array organizes the vertices into separate paths (one per seed). Each path has an orientation. The initial orientation may be set using the SEED_NORMAL keyword. As a path is tracked, the change in the normal is also computed and may be returned to the user as an optional argument. Path output can be passed directly to an IDLgrPolyline object or passed to the STREAMLINE procedure for generation of orientated ribbons. Control over aspects of the integration (e.g. method or stepsize) is also provided. Syntax PARTICLE_TRACE, Data, Seeds, Verts, Conn [, Normals] [, MAX_ITERATIONS=value] [, ANISOTROPY=array] [, INTEGRATION={0 | 1}] [, SEED_NORMAL=vector] [, TOLERANCE=value] [, MAX_STEPSIZE=value] [, /UNIFORM] Arguments Data Input data array. This array can be of dimensions [2, dx, dy] for two-dimensional vector fields or [3, dx, dy, dz] for three-dimensional vector fields. Seeds Input array of seed points ([3, n] or [2, n]). Verts Array of output path vertices ([3, n] or [2, n] array of floats). Conn Output path connectivity array in IDLgrPolyline POLYLINES keyword format. There is one set of line segments in this array for each input seed point. Normals Output normal estimate at each output vertex ([3, n] array of floats). Keywords ANISOTROPY Set this input keyword to a two- or three- element array describing the distance between grid points in each dimension. The default value is [1.0, 1.0, 1.0] for three- dimensional data and [1.0, 1.0] for two-dimensional data. INTEGRATION Set this keyword to one of the following values to select the integration method: * 0 = 2nd order Runge-Kutta (the default) * 1 = 4th order Runge-Kutta SEED_NORMAL Set this keyword to a three-element vector which selects the initial normal for the paths. The default value is [0.0, 0.0, 1.0]. This keyword is ignored for 2D data. TOLERANCE This keyword is used with adaptive step-size control in the 4th order Runge-Kutta integration scheme. It is ignored if the UNIFORM keyword is set or the 2nd order Runge-Kutta scheme is selected. MAX_ITERATIONS This keyword specifies the maximum number of line segments to return for each path. The default value is 200. MAX_STEPSIZE This keyword specifies the maximum path step size. The default value is 1.0. UNIFORM If this keyword is set, the step size will be set to a fixed value, set via the MAX_STEPSIZE keyword. If this keyword is not specified, and TOLERANCE is either unspecified or inapplicable, then the step size is computed based on the velocity at the current point on the path according to the formula: stepsize = MIN(MaxStepSize, MaxStepSize/MAX(ABS(U), ABS(V), ABS(W))) where (U,V,W) is the local velocity vector. PCOMP [Previous Routine] [Next Routine] [List of Routines] NAME: PCOMP The PCOMP function computes the principal components of an m-column, n-row array, where m is the number of variables and n is the number of observations or samples. The principal components of a multivariate data set may be used to restate the data in terms of derived variables or may be used to reduce the dimensionality of the data by reducing the number of variables (columns). The result is an nvariables- column (nvariables m), n-row array of derived variables. Syntax Result = PCOMP( A [, COEFFICIENTS=variable] [, /COVARIANCE] [, /DOUBLE] [, EIGENVALUES=variable] [, NVARIABLES=value] [, /STANDARDIZE] [, VARIANCES=variable] ) Arguments A An m-column, n-row, single- or double-precision floating-point array. Keywords COEFFICIENTS Use this keyword to specify a named variable that will contain the principal components used to compute the derived variables. The principal components are the coefficients of the derived variables and are returned in an m-column, m-row array. The rows of this array correspond to the coefficients of the derived variables. The coefficients are scaled so that the sums of their squares are equal to the eigenvalue from which they are computed. This keyword must be initialized to a nonzero value before calling PCOMP if the principal components are desired. COVARIANCE Set this keyword to compute the principal components using the covariances of the original data. The default is to use the correlations of the original data to compute the principal components. DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. EIGENVALUES Use this keyword to specify a named variable that will contain a one-column, m-row array of eigenvalues that correspond to the principal components. The eigenvalues are listed in descending order. This keyword must be initialized to a nonzero value before calling PCOMP if the eigenvalues are desired. NVARIABLES Use this keyword to specify the number of derived variables. A value of zero, negative values, and values in excess of the input array's column dimension result in a complete set (m-columns and n-rows) of derived variables. STANDARDIZE Set this keyword to convert the variables (the columns) of the input array to standardized variables (variables with a mean of zero and variance of one). VARIANCES Use this keyword to specify a named variable that will contain a one-column, m-row array of variances. The variances correspond to the percentage of the total variance for each derived variable. Example ; Define an array with 4 variables and 20 observations: array = [[19.5, 43.1, 29.1, 11.9], $ [24.7, 49.8, 28.2, 22.8], $ [30.7, 51.9, 37.0, 18.7], $ [29.8, 54.3, 31.1, 20.1], $ [19.1, 42.2, 30.9, 12.9], $ [25.6, 53.9, 23.7, 21.7], $ [31.4, 58.5, 27.6, 27.1], $ [27.9, 52.1, 30.6, 25.4], $ [22.1, 49.9, 23.2, 21.3], $ [25.5, 53.5, 24.8, 19.3], $ [31.1, 56.6, 30.0, 25.4], $ [30.4, 56.7, 28.3, 27.2], $ [18.7, 46.5, 23.0, 11.7], $ [19.7, 44.2, 28.6, 17.8], $ [14.6, 42.7, 21.3, 12.8], $ [29.5, 54.4, 30.1, 23.9], $ [27.7, 55.3, 25.7, 22.6], $ [30.2, 58.6, 24.6, 25.4], $ [22.7, 48.2, 27.1, 14.8], $ [25.2, 51.0, 27.5, 21.1]] ; Compute the derived variables based upon the principal ; components. The COEFFICENTS, EIGENVALUES, and VARIANCES keywords ; must be initialized as nonzero values prior to calling PCOMP: coefficients = 1 & eigenvalues = 1 & variances = 1 result = PCOMP(array, COEFFICIENTS = coefficients, $ EIGENVALUES = eigenvalues, VARIANCES = variances) PRINT, 'Result: ' PRINT, result, FORMAT = '(4(f5.1, 2x))' PRINT, 'Coefficients: ' PRINT, coefficients PRINT, 'Eigenvalues: ' PRINT, eigenvalues PRINT, 'Variances: ' PRINT, variances IDL prints: Result: 81.4 15.5 -5.5 0.5 102.7 11.1 -4.1 0.6 109.9 20.3 -6.2 0.5 110.5 13.8 -6.3 0.6 81.8 17.1 -4.9 0.6 104.8 6.2 -5.4 0.6 121.3 8.1 -5.2 0.6 111.3 12.6 -4.0 0.6 97.0 6.4 -4.4 0.6 102.5 7.8 -6.1 0.6 118.5 11.2 -5.3 0.6 118.9 9.1 -4.7 0.6 81.5 8.8 -6.3 0.6 88.0 13.4 -3.9 0.6 74.3 7.5 -4.8 0.6 113.4 12.0 -5.1 0.6 109.7 7.7 -5.6 0.6 117.5 5.5 -5.7 0.6 91.4 12.0 -6.1 0.6 102.5 10.6 -4.9 0.6 Coefficients: 0.983668 0.947119 0.358085 0.925647 0.118704 -0.265644 0.932897 -0.215227 -0.134015 -0.179266 0.0378060 0.311214 -0.0185792 0.0161747 0.00707525 0.000456858 Eigenvalues: 2.84969 1.00128 0.148380 0.000657078 Variances: 0.712422 0.250319 0.0370950 0.000164269 The first two derived variables account for 96.3% of the total variance of the original data. See Also CORRELATE, EIGENQL PLOT [Previous Routine] [Next Routine] [List of Routines] NAME: PLOT The PLOT procedure draws graphs of vector arguments. If one parameter is used, the vector parameter is plotted on the ordinate versus the point number on the abscissa. To plot one vector as a function of another, use two parameters. PLOT can also be used to create polar plots by setting the POLAR keyword. Syntax PLOT, [X,] Y [, MAX_VALUE=value] [, MIN_VALUE=value] [, NSUM=value] [, /POLAR] [, THICK=value] [, /XLOG] [, /YLOG] [, /YNOZERO] Graphics Keywords: [, BACKGROUND=color_index] [, CHARSIZE=value] [, CHARTHICK=integer] [, CLIP=[X0, Y0, X1, Y1]] [, COLOR=value] [, /DATA | , /DEVICE | , /NORMAL] [, FONT=integer] [, LINESTYLE={0 | 1 | 2 | 3 | 4 | 5}] [, /NOCLIP] [, /NODATA] [, /NOERASE] [, POSITION=[X0, Y0, X1, Y1]] [, PSYM=integer{0 to 10}] [, SUBTITLE=string] [, SYMSIZE=value] [, /T3D] [, THICK=value] [, TICKLEN=value] [, TITLE=string] [, {X | Y | Z}CHARSIZE=value] [, {X | Y | Z}GRIDSTYLE=integer{0 to 5}] [, {X | Y | Z}MARGIN=[left, right]] [, {X | Y | Z}MINOR=integer] [, {X | Y | Z}RANGE=[min, max]] [, {X | Y | Z}STYLE=value] [, {X | Y | Z}THICK=value] [, {X | Y | Z}TICK_GET=variable] [, {X | Y | Z}TICKFORMAT=string] [, {X | Y | Z}TICKINTERVAL= value] [, {X | Y | Z}TICKLAYOUT=scalar] [, {X | Y | Z}TICKLEN=value] [, {X | Y | Z}TICKNAME=string_array] [, {X | Y | Z}TICKS=integer] [, {X | Y | Z}TICKUNITS=string] [, {X | Y | Z}TICKV=array] [, {X | Y | Z}TITLE=string] [, ZVALUE=value{0 to 1}] Arguments X A vector argument. If X is not specified, Y is plotted as a function of point number (starting at zero). If both arguments are provided, Y is plotted as a function of X. This argument is converted to double precision floating-point before plotting. Plots created with PLOT are limited to the range and precision of double-precision floating-point values. Y The ordinate data to be plotted. This argument is converted to double-precision floating-point before plotting. Keywords ISOTROPIC Set this keyword to force the scaling of the X and Y axes to be equal. Note The X and Y axes will be scaled isotropically and then fit within the rectangle defined by the POSITION keyword; one of the axes may be shortened. See "POSITION" on page 2407 for more information. MAX_VALUE The maximum value to be plotted. If this keyword is present, data values greater than the value of MAX_VALUE are treated as missing and are not plotted. Note that the IEEE floating-point value NaN is also treated as missing data. (See "Special Floating-Point Values" in Chapter 17 of Building IDL Applications for more information on IEEE floating-point values.) MIN_VALUE The minimum value to be plotted. If this keyword is present, data values less than the value of MIN_VALUE are treated as missing and are not plotted. Note that the IEEE floating-point value NaN is also treated as missing data. (See "Special Floating-Point Values" in Chapter 17 of Building IDL Applications for more information on IEEE floating-point values.) NSUM The presence of this keyword indicates the number of data points to average when plotting. If NSUM is larger than 1, every group of NSUM points is averaged to produce one plotted point. If there are m data points, then m/NSUM points are displayed. On logarithmic axes a geometric average is performed. It is convenient to use NSUM when there is an extremely large number of data points to plot because it plots fewer points, the graph is less cluttered, and it is quicker. POLAR Set this keyword to produce polar plots. The X and Y vector parameters, both of which must be present, are first converted from polar to Cartesian coordinates. The first parameter is the radius, and the second is the angle (expressed in radians). For example, to make a polar plot, you would use a command such as: PLOT, /POLAR, R, THETA THICK Controls the thickness of the lines connecting the points. A thickness of 1.0 is normal, 2 is double wide, etc. XLOG Set this keyword to specify a logarithmic X axis, producing a log-linear plot. Set both XLOG and YLOG to produce a log-log plot. Note that logarithmic axes that have ranges of less than a decade are not labeled. YNOZERO Set this keyword to inhibit setting the minimum Y axis value to zero when the Y data are all positive and nonzero, and no explicit minimum Y value is specified (using YRANGE, or !Y.RANGE). By default, the Y axis spans the range of 0 to the maximum value of Y, in the case of positive Y data. Set bit 4 in !Y.STYLE to make this option the default. YLOG Set this keyword to specify a logarithmic Y axis, producing a linear-log plot. Set both XLOG and YLOG to produce a log-log plot. Note that logarithmic axes that have ranges of less than a decade are not labeled. Graphics Keywords Accepted See Appendix C, "Graphics Keywords", for the description of graphics and plotting keywords not listed above. BACKGROUND, CHARSIZE, CHARTHICK, CLIP, COLOR, DATA, DEVICE, FONT, LINESTYLE, NOCLIP, NODATA, NOERASE, NORMAL, POSITION, PSYM, SUBTITLE, SYMSIZE, T3D, THICK, TICKLEN, TITLE, [XYZ]CHARSIZE, [XYZ]GRIDSTYLE, [XYZ]MARGIN, [XYZ]MINOR, [XYZ]RANGE, [XYZ]STYLE, [XYZ]THICK, [XYZ]TICKFORMAT, [XYZ]TICKINTERVAL, [XYZ]TICKLAYOUT, [XYZ]TICKLEN, [XYZ]TICKNAME, [XYZ]TICKS, [XYZ]TICKUNITS, [XYZ]TICKV, [XYZ]TICK_GET, [XYZ]TITLE, ZVALUE. Example The PLOT procedure has many keywords that allow you to create a vast variety of plots. Here are a few simple examples using the PLOT command. ; Create a simple dataset: D = FINDGEN(100) ; Create a simple plot with the title "Simple Plot": PLOT, D, TITLE = 'Simple Plot' ; Plot one argument versus another: PLOT, SIN(D/3), COS(D/6) ; Create a polar plot: PLOT, D, D, /POLAR, TITLE = 'Polar Plot' ; Use plotting symbols instead of connecting lines by including the ; PSYM keyword. Label the X and Y axes with XTITLE and YTITLE: PLOT, SIN(D/10), PSYM=4, XTITLE='X Axis', YTITLE='Y Axis' See Also OPLOT, PLOTS PLOT_3DBOX [Previous Routine] [Next Routine] [List of Routines] NAME: PLOT_3DBOX The PLOT_3DBOX procedure plots a function of two variables (e.g., Z=f(X, Y)) inside a 3D box. Optionally, the data can be projected onto the "walls" surrounding the plot area. This routine is written in the IDL language. Its source code can be found in the file plot_3dbox.pro in the lib subdirectory of the IDL distribution. Syntax PLOT_3DBOX, X, Y, Z [, GRIDSTYLE={0 | 1 | 2 | 3 | 4 | 5}] [, PSYM=integer{1 to 10}] [, /SOLID_WALLS] [, /XY_PLANE] [, XYSTYLE={0 | 1 | 2 | 3 | 4 | 5}] [, /XZ_PLANE] [, XZSTYLE={0 | 1 | 2 | 3 | 4 | 5}] [, /YZ_PLANE] [, YZSTYLE={0 | 1 | 2 | 3 | 4 | 5}] [, AX=degrees] [, AZ=degrees] [, ZAXIS={1 | 2 | 3 | 4}] Graphics Keywords: Accepts all graphics keywords accepted by PLOT except for: FONT, PSYM, SYMSIZE, {XYZ}TICK_GET, and ZVALUE. Arguments X A vector (i.e., a one-dimensional array) of X coordinates. Y A vector of Y coordinates. Z A vector of Z coordinates. Z[i] is a function of X[i] and Y[i]. Keywords GRIDSTYLE Set this keyword to the linestyle index for the type of line to be used when drawing the gridlines. Linestyles are described in the following table: Index Linestyle 0 Solid 1 Dotted 2 Dashed 3 Dash Dot 4 Dash Dot Dot 5 Long Dashes Table 75: IDL Linestyles PSYM Set this keyword to a plotting symbol index to be used in plotting the data. For more information, see "PSYM" on page 2408. SOLID_WALLS Set this keyword to cause the boundary "walls" of the plot to be filled with the color index specified by the COLOR keyword. XY_PLANE Set this keyword to plot the X and Y values on the Z=0 axis plane. XYSTYLE Set this keyword to the linestyle used to draw the XY plane plot. See the table above for a list of linestyles. XZ_PLANE Set this keyword to plot the Y and Z values on the Y=MAX(Y) axis plane. XZSTYLE Set this keyword to the linestyle used to draw the XZ plane plot. See the table above for a list of linestyles. YZ_PLANE Set this keyword to plot the Y and Z values on the X=MAX(X) axis plane. YZSTYLE Set this keyword to the linestyle used to draw the YZ plane plot. See the table above for a list of linestyles. SURFACE Keywords In addition to the keywords described above, the AX, AZ, and ZAXIS keywords to the SURFACE procedure are accepted by PLOT_3DBOX. See "SURFACE" on page 1366. Graphics Keywords Accepted See Appendix C, "Graphics Keywords", for the description of graphics and plotting keywords not listed above. BACKGROUND, CHARSIZE, CHARTHICK, CLIP, COLOR, DATA, DEVICE, LINESTYLE, NOCLIP, NOERASE, NORMAL, POSITION, SUBTITLE, T3D, THICK, TICKLEN, TITLE, [XYZ]CHARSIZE, [XYZ]GRIDSTYLE, [XYZ]MARGIN, [XYZ]MINOR, [XYZ]RANGE, [XYZ]STYLE, [XYZ]THICK, [XYZ]TICKFORMAT, [XYZ]TICKLEN, [XYZ]TICKNAME, [XYZ]TICKS, [XYZ]TICKV, [XYZ]TITLE. Example ; Create some data to be plotted: X = REPLICATE(5., 10.) X1 = COS(FINDGEN(36)*10.*!DTOR)*2.+5. X = [X, X1, X] Y = FINDGEN(56) Z = REPLICATE(5., 10) Z1 = SIN(FINDGEN(36)*10.*!DTOR)*2.+5. Z = [Z, Z1, Z] ; Create the box plot with data projected on all of the walls. The ; PSYM value of -4 plots the data as diamonds connected by lines: PLOT_3DBOX, X, Y, Z, /XY_PLANE, /YZ_PLANE, /XZ_PLANE, $ /SOLID_WALLS, GRIDSTYLE=1, XYSTYLE=3, XZSTYLE=4, $ YZSTYLE=5, AZ=40, TITLE='Example Plot Box', $ XTITLE='X Coordinate', YTITLE='Y Coodinate', $ ZTITLE='Z Coordinate', SUBTITLE='Sub Title', $ /YSTYLE, ZRANGE=[0,10], XRANGE=[0,10], $ PSYM=-4, CHARSIZE=1.6 See Also PLOTS, SURFACE PLOT_FIELD [Previous Routine] [Next Routine] [List of Routines] NAME: PLOT_FIELD The PLOT_FIELD procedure plots a 2D field. N random points are picked, and from each point a path is traced along the field. The length of the path is proportional to the field vector magnitude. This routine is written in the IDL language. Its source code can be found in the file plot_field.pro in the lib subdirectory of the IDL distribution. Syntax PLOT_FIELD, U, V [, ASPECT=ratio] [, LENGTH=value] [, N=num_arrows] [, TITLE=string] Arguments U A 2D array giving the field vector at each point in the U(X) direction. V A 2D array giving the field vector at each point in the V(Y) direction. Keywords ASPECT Set this keyword to the aspect ratio of the plot (i.e., the ratio of the X size to Y size). The default is 1.0. LENGTH Set this keyword to the length of the longest field vector expressed as a fraction of the plotting area. The default is 0.1. N Set this keyword to the number of arrows to draw. The default is 200. TITLE Set this keyword to the title of plot. The default is "Velocity Field". Example ; Create array X: X = FINDGEN(20, 20) ; Create array Y: Y = FINDGEN(20, 20)*3 ; Plot X vs. Y: PLOT_FIELD, X, Y The above commands produce the following plot: See Also FLOW3, VEL, VELOVECT PLOTERR [Previous Routine] [Next Routine] [List of Routines] NAME: PLOTERR The PLOTERR procedure plots individual data points with error bars. This routine is written in the IDL language. Its source code can be found in the file ploterr.pro in the lib subdirectory of the IDL distribution. Syntax PLOTERR, [ X ,] Y , Err [, TYPE={1 | 2 | 3 | 4}] [, PSYM=integer{1 to 10}] Arguments X An optional array of X values. The procedure checks the number of arguments passed to decide if X was passed. If X is not passed, INDGEN(Y) is assumed for X values. Y The array of Y values. Y cannot be of type string. Err The array of error-bar values. Keywords TYPE The type of plot to be produced. The possible types are: * 1 = X Linear - Y Linear (default) * 2 = X Linear - Y Log * 3 = X Log - Y Linear * 4 = X Log - Y Log PSYM The plotting symbol to use. The default is +7. See Also ERRPLOT, OPLOTERR, PLOT PLOTS [Previous Routine] [Next Routine] [List of Routines] NAME: PLOTS The PLOTS procedure plots vectors or points on the current graphics device in either two or three dimensions. The coordinates can be given in data, device, or normalized form using the DATA (the default), DEVICE, or NORMAL keywords. The COLOR keyword can be set to a scalar or vector value. If it is set to a vector value, the line segment connecting (Xi, Yi) to (Xi+1, Yi+1) is drawn with a color index of COLORi+1. In this case, COLOR must have the same number of elements as X and Y. Syntax PLOTS, X [, Y [, Z]] [, /CONTINUE] Graphics Keywords: [, CLIP=[X0, Y0, X1, Y1]] [, COLOR=value] [, /DATA | , /DEVICE | , /NORMAL] [, LINESTYLE={0 | 1 | 2 | 3 | 4 | 5}] [, /NOCLIP] [, PSYM=integer{0 to 10}] [, SYMSIZE=value] [, /T3D] [, THICK=value] [, Z=value] Arguments X A vector or scalar argument providing the X components of the points to be connected. If only one argument is specified, X must be an array of either two or three vectors (i.e., (2,*) or (3,*)). In this special case, X[0,*] are taken as the X values, X[1,*] are taken as the Y values, and X[2,*] are taken as the Z values. Y An optional argument providing the Y coordinate(s) of the points to be connected. Z An optional argument providing the Z coordinates of the points to be connected. If Z is not provided, X and Y are used to draw lines in two dimensions. Z has no effect if the keyword T3D is not specified and the system variable !P.T3D= 0. Keywords CONTINUE Set this keyword to continue drawing a line from the last point of the most recent call to PLOTS. For example: ; Position at (0,0): PLOTS, 0, 0 ; Draws vector from (0,0) to (1,1): PLOTS, 1, 1, /CONTINUE ; Draws two vectors from (1,1) to (2,2) to (3,3): PLOTS, [2,3], [2,3], /CONTINUE Graphics Keywords Accepted See Appendix C, "Graphics Keywords", for the description of graphics and plotting keywords not listed above. CLIP, COLOR, DATA, DEVICE, LINESTYLE, NOCLIP, NORMAL, PSYM, SYMSIZE, T3D, THICK, Z. Examples ; Draw a line from (100, 200) to (600, 700), in device coordinates, ; using color index 12: PLOTS, [100,600], [200,700], COLOR=12, /DEVICE ; Draw a polyline where the line color is proportional to the ; ordinate that ends each line segment. ; First create datasets X and Y: X = SIN(FINDGEN(100)) & Y = COS(FINDGEN(100)) ; Now plot X and Y in normalized coordinates with colors as ; described above: PLOTS, X, Y, COLOR = BYTSCL(Y, TOP=!D.N COLORS-1), /NORMAL ; Load a good colortable to better show the result: LOADCT, 13 ; Draw 3D vectors over an established SURFACE plot. ; The SAVE keyword tells IDL to save the 3D transformation ; established by SURFACE. SURFACE, DIST(5), /SAVE ; Draw a line between (0,0,0) and (3,3,3). The T3D keyword makes ; PLOTS use the previously established 3D transformation: PLOTS, [0,3], [0,3], [0,3], /T3D ; Draw a line between (3,0,0) and (3,3,3): PLOTS, [3,3], [0,3], [0,3], /T3D ; Draw a line between (0,3,0) and (3,3,3): PLOTS, [0,3], [3,3], [0,3], /T3D See Also ANNOTATE, XYOUTS PNT_LINE [Previous Routine] [Next Routine] [List of Routines] NAME: PNT_LINE The PNT_LINE function returns the perpendicular distance between a point P0 and a line between points L0 and L1. This function is limited by the machine accuracy of single precision floating point. This routine is written in the IDL language. Its source code can be found in the file pnt_line.pro in the lib subdirectory of the IDL distribution. Syntax Result = PNT_LINE( P0, L0, L1 [, Pl] [, /INTERVAL] ) Arguments P0 The location of the point. P0 may have 2 to n elements, for n dimensions. L0 One end-point of the line. L0 must have same number of elements as P0. L1 The other end-point of the line. L1 must have the same number of elements as L0. Pl A named variable that will contain the location of the point on the line between L0 and L1 that is closest to P0. Pl is not necessarily in the interval (L0, L1). Keywords INTERVAL If set, and if the point on the line between L0 and L1 that is closest to P0 is not within the interval (L0, L1), PNT_LINE will return the distance from P0 to the closer of the two endpoints L0 and L1. Example To print the distance between the point (2,3) and the line from (-3,3) to (5,12), and also the location of the point on the line closest to (2,3), enter the following command: PRINT, PNT_LINE([2,3], [-3,3], [5,12], Pl), Pl IDL prints: 3.73705 -0.793104 5.48276 See Also CIR_3PNT, SPH_4PNT POINT_LUN [Previous Routine] [Next Routine] [List of Routines] NAME: POINT_LUN The POINT_LUN procedure sets or obtains the current position of the file pointer for the specified file. Note POINT_LUN cannot be used with files opened with the RAWIO keyword to the OPEN routines. Depending upon the device in question, the IOCTL function might be used instead for files of this type. Syntax POINT_LUN, Unit, Position Arguments Unit The file unit for the file in question. If Unit is positive, POINT_LUN sets the file position to the position given by Position. If negative, POINT_LUN gets the current file position and assigns it to the variable given by Position. Note that POINT_LUN cannot be used with the 3 standard file units (0, -1, and -2). Position If Unit is positive, Position gives the byte offset into the file at which the file pointer should be set. For example, to rewind the file to the beginning, specify 0. If Unit is negative, Position must be a named variable into which the current file position will be stored. The returned type will be a longword signed integer if the position is small enough to fit, and an unsigned 64-bit integer otherwise. Under VMS, be careful to move the file pointer only to record boundaries. It is always safe to move to a file position that was previously obtained via POINT_LUN or the FSTAT function. Files with indexed organization can only be positioned to the beginning of the file. Use Of POINT_LUN On Compressed Files In general, it is not possible to arbitrarily move the file pointer within a compressed file (files opened with the COMPRESS keyword to OPEN) because the file compression code needs to maintain a compression state for the file that includes all the data that has already been passed in the stream. This limitation results in the following constraints on the use of POINT_LUN with compressed files: * POINT_LUN is not allowed on compressed files open for output, except to positions beyond the current file position. The compression code emulates such motion by outputting enough zero bytes to move the pointer to the new position. * POINT_LUN is allowed to arbitrary positions on compressed files opened for input. However, this feature is emulated by positioning the file to the beginning of the file and then reading and discarding enough data to move the file pointer to the desired position. This can be extremely slow. For these reasons, use of POINT_LUN on compressed files, although possible under some circumstances, is best avoided. Example To move the file pointer 2048 bytes into the file associated with file unit number 1, enter: POINT_LUN, 1, 2048 To return the file pointer for file unit number 2, enter: POINT_LUN, -2, pos See Also GET_LUN, OPEN POLAR_CONTOUR [Previous Routine] [Next Routine] [List of Routines] NAME: POLAR_CONTOUR The POLAR_CONTOUR procedure draws a contour plot from data in polar coordinates. Data can be regularly- or irregularly-gridded. All of the keyword options supported by CONTOUR are available to POLAR_CONTOUR. This routine is written in the IDL language. Its source code can be found in the file polar_contour.pro in the lib subdirectory of the IDL distribution. Syntax POLAR_CONTOUR, Z, Theta, R [, [, C_CHARSIZE=value] [, C_CHARTHICK=integer] [, C_COLORS=vector] [, C_LINESTYLE=vector] [, /FILL | , CELL_FILL [, C_ORIENTATION=degrees] [, C_SPACING=value]] [, C_THICK=vector] [, /CLOSED] [, /IRREGULAR] [, LEVELS=vector | NLEVELS=integer{1 to 29}] [, MAX_VALUE=value] [, MIN_VALUE=value] [, /OVERPLOT] [, /PATH_DATA_COORDS | ,TRIANGULATION=variable] [, /XLOG] [, /YLOG] [, /ZAXIS] [, SHOW_TRIANGULATION=color_index] Arguments Z The data values to be contoured. If the data is regularly gridded, Z must have the dimensions (N_ELEMENTS(Theta), N_ELEMENTS(R). Note that the ordering of the elements in the array Z is opposite that used by the POLAR_SURFACE routine. Theta A vector of angles in radians. For regularly-gridded data, Theta must have the same number of elements as the first dimension of Z. For a scattered grid, Theta must have the same number of elements as Z. R A vector of radius values. For regularly-gridded data, R must have the same number of elements as the second dimension of Z. For a scattered grid, R must have the same number of elements as Z. Keywords POLAR_CONTOUR accepts all of the keywords accepted by the CONTOUR routine except C_LABELS, DOWNHILL, FOLLOW, PATH_FILENAME, PATH_INFO, and PATH_XY. See "CONTOUR" on page 225. In addition, there is one unique keyword: SHOW_TRIANGULATION Set this keyword to a color index to be used in overplotting the triangulation between datapoints. Example This example uses POLAR_CONTOUR with regularly-gridded data: ;Handle TrueColor displays: DEVICE, DECOMPOSED=0 ;Load color table TEK_COLOR nr = 12 ; number of radii nt = 18 ; number of Thetas ; Create a vector of radii: r = FINDGEN(nr)/(nr-1) ; Create a vector of Thetas: theta = 2*!PI * FINDGEN(nt)/(nt-1) ; Create some data values to be contoured: z = COS(theta*3) # (r-0.5)^2 ; Create the polar contour plot: POLAR_CONTOUR, z, theta, r, /FILL, c_color=[2, 3, 4, 5] See Also CONTOUR POLAR_SURFACE [Previous Routine] [Next Routine] [List of Routines] NAME: POLAR_SURFACE The POLAR_SURFACE function interpolates a surface from polar coordinates (R, Theta, Z) to rectangular coordinates (X, Y, Z). The function returns a two- dimensional array of the same type as Z. This routine is written in the IDL language. Its source code can be found in the file polar_surface.pro in the lib subdirectory of the IDL distribution. Syntax Result = POLAR_SURFACE( Z, R, Theta [, /GRID] [, SPACING=[xspacing, yspacing]] [, BOUNDS=[x0, y0, x1, y1]] [, /QUINTIC] [, MISSING=value] ) Arguments Z An array containing the surface value at each point. If the data are regularly gridded in R and Theta, Z is a two dimensional array, where Zi,j has a radius of Ri and an azimuth of Thetaj. If the data are irregularly-gridded, Ri and Thetai contain the radius and azimuth of each Zi. Note that the ordering of the elements in the array Z is opposite that used by the POLAR_CONTOUR routine. R The radius. If the data are regularly gridded in R and Theta, Zi,j has a radius of Ri. If the data are irregularly-gridded, R must have the same number of elements as Z, and contains the radius of each point. Theta The azimuth, in radians. If the data are regularly gridded in R and Theta, Zi,j has an azimuth of Thetaj. If the data are irregularly-gridded, Theta must have the same number of elements as Z, and contains the azimuth of each point. Keywords GRID Set this keyword to indicate that Z is regularly gridded in R and Theta. SPACING A two element vector containing the desired grid spacing of the resulting array in x and y. If omitted, the grid will be approximately 51 by 51. BOUNDS A four element vector, [x0, y0, x1, y1], containing the limits of the xy grid of the resulting array. If omitted, the extent of input data sets the limits of the grid. QUINTIC Set this keyword to use quintic interpolation, which is slower but smoother than the default linear interpolation. MISSING Use this keyword to specify a value to use for areas within the grid but not within the convex hull of the data points. The default is 0.0. Example ; The radius: R = FINDGEN(50) / 50.0 ; Theta: THETA = FINDGEN(50) * (2 * !PI / 50.0) ; Make a function (tilted circle): Z = R # SIN(THETA) ; Show it: SURFACE, POLAR_SURFACE(Z, R, THETA, /GRID) See Also POLAR keyword to PLOT POLY [Previous Routine] [Next Routine] [List of Routines] NAME: POLY The POLY function evaluates a polynomial function of a variable. The result is equal to: C0 + C1x + C2x2 + ... This routine is written in the IDL language. Its source code can be found in the file poly.pro in the lib subdirectory of the IDL distribution. Syntax Result = POLY(X, C) Arguments X The variable. This value can be a scalar, vector or array. C The vector of polynomial coefficients. The degree of the polynomial is N_ELEMENTS(C) - 1. See Also FZ_ROOTS POLY_2D [Previous Routine] [Next Routine] [List of Routines] NAME: POLY_2D The POLY_2D function performs polynomial warping of images. This function performs a geometrical transformation in which the resulting array is defined by: g [x, y] = f [x', y'] = f [a [x, y], b [x, y]] where g[x, y] represents the pixel in the output image at coordinate (x, y), and f [x', y'] is the pixel at (x', y') in the input image that is used to derive g[x, y]. The functions a (x, y) and b (x, y) are polynomials in x and y of degree N, whose coefficients are given by P and Q, and specify the spatial transformation: N N x = a(x, y) = P i, jxjyi i = 0 j = 0 N N y = b(x, y) = Q i, jxjyi i = 0 j = 0 Either the nearest neighbor or bilinear interpolation methods can be selected. Syntax Result = POLY_2D( Array, P, Q [, Interp [, Dimx, Dimy]] [, CUBIC={-1 to 0}] [, MISSING=value] ) Arguments Array A two-dimensional array of any basic type except string. The result has the same type as Array. P and Q P and Q are arrays containing the polynomial coefficients. Each array must contain (N+1)2 elements (where N is the degree of the polynomial). For example, for a linear transformation, P and Q contain four elements and can be a 2 x 2 array or a 4-element vector. Pi,j contains the coefficient used to determine x', and is the weight of the term xjyi. The POLYWARP procedure can be used to fit (x', y') as a function of (x, y) and determines the coefficient arrays P and Q. Interp Set this argument to a 1to perform bilinear interpolation. Set this argument to 2 to perform cubic convolution interpolation (as described under the CUBIC keyword, below). Otherwise, the nearest neighbor method is used. For the linear case, (N=1), bilinear interpolation requires approximately twice as much time as does the nearest neighbor method. Dimx If present, Dimx specifies the number of columns in the output. If omitted, the output has the same number of columns as Array. Dimy If present, Dimy specifies the number of rows in the output. If omitted, the output has the same number of rows as Array. Keywords CUBIC Set this keyword to a value between -1 and 0 to use the cubic convolution interpolation method with the specified value as the interpolation parameter. Setting this keyword equal to a value greater than zero specifies a value of -1 for the interpolation parameter. Park and Schowengerdt (see reference below) suggest that a value of -0.5 significantly improves the reconstruction properties of this algorithm. Note that cubic convolution interpolation works only with one- and two-dimensional arrays. Cubic convolution is an interpolation method that closely approximates the theoretically optimum sinc interpolation function using cubic polynomials. According to sampling theory, details of which are beyond the scope of this document, if the original signal, f, is a band-limited signal, with no frequency component larger than 0, and f is sampled with spacing less than or equal to 1/2 0, then f can be reconstructed by convolving with a sinc function: sinc (x) = sin ( x) / ( x). In the one-dimensional case, four neighboring points are used, while in the two- dimensional case 16 points are used. Note that cubic convolution interpolation is significantly slower than bilinear interpolation. For further details see: Rifman, S.S. and McKinnon, D.M., "Evaluation of Digital Correction Techniques for ERTS Images; Final Report", Report 20634-6003-TU-00, TRW Systems, Redondo Beach, CA, July 1974. S. Park and R. Schowengerdt, 1983 "Image Reconstruction by Parametric Cubic Convolution", Computer Vision, Graphics & Image Processing 23, 256. MISSING Specifies the output value for points whose x', y' is outside the bounds of Array. If MISSING is not specified, the resulting output value is extrapolated from the nearest pixel of Array. Example Some simple linear (degree one) transformations are: P0,0 P1,0 P0,1 P1,1 Q0,0 Q1,0 Q0,1 Q1,1 Effect 0 0 1 0 0 1 0 0 Identity 0 0 0.5 0 0 1 0 0 Stretch X by a factor of 2 0 0 1 0 0 2.0 0 0 Shrink Y by a factor of 2 z 0 1 0 0 1 0 0 Shift left by z pixels 0 1 0 0 0 0 1 0 Transpose Table 76: Simple Transformations for Use with POLY_2D POLY_2D is often used in conjunction with the POLYWARP procedure to warp images. ; Create and display a simple image: A = BYTSCL(SIN(DIST(250)), TOP=!D.TABLE_SIZE) & TV, A ; Set up the arrays of original points to be warped: XO = [61, 62, 143, 133] YO = [89, 34, 38, 105] ; Set up the arrays of points to be fit: XI = [24, 35, 102, 92] YI = [81, 24, 25, 92] ; Use POLYWARP to generate the P and Q inputs to POLY_2D: POLYWARP, XI, YI, XO, YO, 1, P, Q ; Perform an image warping based on P and Q: B = POLY_2D(A, P, Q) ; Display the new image: TV, B, 250, 250 Images can also be warped over irregularly gridded control points using the WARP_TRI procedure. See Also POLYWARP POLY_AREA [Previous Routine] [Next Routine] [List of Routines] NAME: POLY_AREA The POLY_AREA function returns the area of a polygon given the coordinates of its vertices. This value is always positive. It is assumed that the polygon has n vertices with n sides and the edges connect the vertices in the order: [(x1,y1), (x2,y2), ... , (xn,yn), (x1,y1)] such that the last vertex is connected to the first vertex. This routine is written in the IDL language. Its source code can be found in the file poly_area.pro in the lib subdirectory of the IDL distribution. Syntax Result = POLY_AREA( X, Y [, DOUBLE] [, /SIGNED] ) Arguments X An n-element vector of X coordinate locations for the vertices. Y An n-element vector of Y coordinate locations for the vertices. Keywords DOUBLE Set this keyword to use double-precision for computations and to return a double-precision result. Set DOUBLE = 0 to use single-precision for computations and to return a single-precision result. If either of the inputs are double-precision, the default is /DOUBLE (DOUBLE = 1), otherwise the default is DOUBLE = 0. SIGNED If set, returns a signed area. Polygons with edges traversed in counterclockwise order have a positive area; polygons traversed in the clockwise order have a negative area. See Also DEFROI, POLYFILLV POLY_FIT [Previous Routine] [Next Routine] [List of Routines] NAME: POLY_FIT The POLY_FIT function performs a least-square polynomial fit with optional weighting and returns a vector of coefficients. The POLY_FIT routine uses matrix inversion to determine the coefficients. A different version of this routine, SVDFIT, uses singular value decomposition (SVD). The SVD technique is more flexible and robust, but may be slower. This routine is written in the IDL language. Its source code can be found in the file poly_fit.pro in the lib subdirectory of the IDL distribution. Syntax Result = POLY_FIT( X, Y, Degree [, CHISQ=variable] [, COVAR=variable] [, /DOUBLE] [, MEASURE_ERRORS=vector] [, SIGMA=variable] [, STATUS=variable] [, YBAND=variable] [, YERROR=variable] [, YFIT=variable] ) Return Value POLY_FIT returns a vector of coefficients of length Degree+1. If the DOUBLE keyword is set, or if X or Y are double precision, then the result will be double precision, otherwise the result will be single precision. Arguments X An n-element vector of independent variables. Y A vector of dependent variables, the same length as X. Degree The degree of the polynomial to fit. Yfit, Yband, Sigma, Corrm The Yfit, Yband, Sigma, and Corrm arguments are obsolete, and have been replaced by the YFIT, YBAND, YERROR, and COVAR keywords, respectively. Code using these arguments will continue to work as before, but new code should use the keywords instead. Keywords CHISQ Set this keyword to a named variable that will contain the value of the chi-sqaure goodness-of-fit. COVAR Set this keyword to a named variable that will contain the Covariance matrix of the coefficients. DOUBLE Set this keyword to force computations to be done in double-precision arithmetic. MEASURE_ERRORS Set this keyword to a vector containing standard measurement errors for each point Y[i]. This vector must be the same length as X and Y. Note For Gaussian errors (e.g., instrumental uncertainties), MEASURE_ERRORS should be set to the standard deviations of each point in Y. For Poisson or statistical weighting, MEASURE_ERRORS should be set to SQRT(Y). SIGMA Set this keyword to a named variable that will contain the 1-sigma uncertainty estimates for the returned parameters. Note If MEASURE_ERRORS is omitted, then you are assuming that a polynomial is the correct model for your data, and therefore, no independent goodness-of-fit test is possible. In this case, the values returned in SIGMA are multiplied by SQRT(CHISQ/(N­M)), where N is the number of points in X, and M is the number of coefficients. See section 15.2 of Numerical Recipes in C (Second Edition) for details. STATUS Set this keyword to a named variable to receive the status of the operation. Possible status values are: * 0 = Successful completion. * 1 = Singular array (which indicates that the inversion is invalid). Result is NaN. * 2 = Warning that a small pivot element was used and that significant accuracy was probably lost. * 3 = Undefined (NaN) error estimate was encountered. Note If STATUS is not specified, any error messages will be output to the screen. Tip Status values of 2 or 3 can often be resolved by setting the DOUBLE keyword. YBAND Set this keyword to a named variable that will contain the 1 standard deviation error estimate for each point. YERROR Set this keyword to a named variable that will contain the standard error between YFIT and Y. YFIT Set this keyword to a named variable that will contain the vector of calculated Y values. These values have an error of + or ­ YBAND. Example In this example, we use X and Y data corresponding to the known polynomial f (x) = 0.25 - x + x2. Using POLY_FIT to compute a second degree polynomial fit returns the exact coefficients (to within machine accuracy). ; Define an 11-element vector of independent variable data: X = [0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0] ; Define an 11-element vector of dependent variable data: Y = [0.25, 0.16, 0.09, 0.04, 0.01, 0.00, 0.01, 0.04, 0.09, $ 0.16, 0.25] ; Define a vector of measurement errors: measure_errors = REPLICATE(0.01, 11) ; Compute the second degree polynomial fit to the data: result = POLY_FIT(X, Y, 2, MEASURE_ERRORS=measure_errors, $ SIGMA=sigma) ; Print the coefficients: PRINT, 'Coefficients: ', result PRINT, 'Standard errors: ', sigma IDL prints: Coefficients: 0.250000 -1.00000 1.00000 Standard errors: 0.00761853 0.0354459 0.0341395 See Also COMFIT, CURVEFIT, GAUSSFIT, LINFIT, REGRESS, SFIT, SVDFIT POLYFILL [Previous Routine] [Next Routine] [List of Routines] NAME: POLYFILL The POLYFILL procedure fills the interior of a region of the display enclosed by an arbitrary two or three-dimensional polygon. The available filling methods are: solid fill, hardware-dependent fill pattern, parallel lines, or a pattern contained in an array. Not all methods are available on every hardware output device. See "Fill Methods" below. The polygon is defined by a list of connected vertices stored in X, Y, and Z. The coordinates can be given in data, device, or normalized form using the DATA, DEVICE, or NORMAL keywords. Syntax POLYFILL, X [, Y [, Z]] [, IMAGE_COORD=array] [, /IMAGE_INTERP] [, /LINE_FILL] [, PATTERN=array] [, SPACING=centimeters] [, TRANSPARENT=value] Graphics Keywords: [, CLIP=[X0, Y0, X1, Y1]] [, COLOR=value] [, /DATA | , /DEVICE | , /NORMAL] [, LINESTYLE={0 | 1 | 2 | 3 | 4 | 5}] [, /NOCLIP] [, ORIENTATION=ccw_degrees_from_horiz] [, /T3D] [, THICK=value] [, Z=value] Fill Methods Line-fill method: Filling using parallel lines is device-independent and works on all devices that can draw lines. Crosshatching can be simulated by performing multiple fills with different orientations. The spacing, linestyle, orientation, and thickness of the filling lines can be specified using the corresponding keyword parameters. The LINE_FILL keyword selects this filling style, but is not required if either the ORIENTATION or SPACING parameters are present. Solid fill method: Most, but not all, devices can fill with a solid color. Solid fill is performed using the line-fill method for devices that don't have this hardware capability. Method specifying keyword parameters are not required for solid filling. Patterned fill: The method of patterned filling and the usage of various fill patterns is hardware dependent. The fill pattern array can be explicitly specified with the PATTERN keyword parameter for some output devices. Arguments X A vector argument providing the X coordinates of the points to be connected. The vector must contain at least three elements. If only one argument is specified, X must be an array of either two or three vectors (i.e., (2,*) or (3,*)). In this special case, the vector X[0,*] specifies the X values, X[1,*] specifies Y, and X[2,*] contain the Z values. Y A vector argument providing the Y coordinates of the points to be connected. Y must contain at least three elements. Z An optional vector argument providing the Z coordinates of the points to be connected. If Z is not provided, X and Y are used to draw lines in two dimensions. Z must contain at least three elements. Z has no effect if the keyword T3D is not specified and the system variable !P.T3D= 0. Keywords IMAGE_COORD (Z-Buffer output only) A 2 x n array containing the fill pattern array subscripts of each of the n polygon vertices. Use this keyword in conjunction with the PATTERN keyword to warp images over 2D and 3D polygons. IMAGE_INTERP (Z-Buffer output only) Specifies the method of sampling the PATTERN array when the IMAGE_COORD keyword is present. The default method is to use nearest- neighbor sampling. Bilinear interpolation sampling is performed if IMAGE_INTERP is set. LINE_FILL Set this keyword to indicate that polygons are to be filled with parallel lines, rather than using solid or patterned filling methods.When using the line-drawing method of filling, the thickness, linestyle, orientation, and spacing of the lines may be specified with keywords. PATTERN A rectangular array of pixels giving the fill pattern. If this keyword parameter is omitted, POLYFILL fills the area with a solid color. The pattern array may be of any size; if it is smaller than the filled area the pattern array is cyclically repeated. Note When the display device selected is PostScript (PS), POLYFILL can only fill with solid colors. For example, to fill the current plot window with a grid of dots, enter the following commands: ; Define pattern array as 10 by 10: PAT = BYTARR(10,10) ; Set center pixel to bright: PAT[5,5] = 255 ; Fill the rectangle defined by the four corners of the window with ; the pattern: POLYFILL, !X.WINDOW([0,1,1,0]), $ !Y.WINDOW([0,0,1,1]), /NORM, PAT = PAT SPACING The spacing, in centimeters, between the parallel lines used to fill polygons. TRANSPARENT (Z-Buffer output only) Specifies the minimum pixel value to draw in conjunction with the PATTERN and IMAGE_COORD keywords. Pixels less than this value are not drawn and the Z- buffer is not updated. Graphics Keywords Accepted See Appendix C, "Graphics Keywords", for the description of graphics and plotting keywords not listed above. CLIP, COLOR, DATA, DEVICE, LINESTYLE, NOCLIP, NORMAL, ORIENTATION, T3D, THICK, Z. Z-Buffer-Specific Keywords Certain keyword parameters are only active when the Z-buffer is the currently selected graphics device: IMAGE_COORD, IMAGE_INTERP, TRANSPARENT and COLOR. These parameters allow images to be warped over 2D or 3D polygons, and the output of shaded polygons. For examples, see "The Z-Buffer Device" on page 62. For shaded polygons, the COLOR keyword can specify an array that contains the color index at each vertex. Color indices are linearly interpolated between vertices. If COLOR contains a scalar, the entire polygon is drawn with the given color index, just as with the other graphics output devices. Images can be warped over polygons by passing in the image with the PATTERN parameter, and a (2, n) array containing the image space coordinates that correspond to each of the N vertices with the IMAGE_COORD keyword. The IMAGE_INTERP keyword indicates that bilinear interpolation is to be used, rather than the default nearest-neighbor sampling. Pixels less than the value of TRANSPARENT are not drawn, simulating transparency. Example Fill a rectangular polygon that has the vertices (30,30), (100, 30), (100, 100), and (30, 100) in device coordinates: ; Create the vectors of X and Y values: X = [30, 100, 100, 30] & Y = [30, 30, 100, 100] ; Fill the polygon with color index 175: POLYFILL, X, Y, COLOR = 175, /DEVICE See Also POLYFILLV POLYFILLV [Previous Routine] [Next Routine] [List of Routines] NAME: POLYFILLV The POLYFILLV function returns a vector containing the one-dimensional subscripts of the array elements contained inside a polygon defined by vectors X and Y. If no points are contained within the polygon, a -1 is returned and an informational message is printed. The X and Y parameters are vectors that contain the subscripts of the vertices that define the polygon in the coordinate system of the two-dimensional Sx by Sy array. The Sx and Sy parameters define the number of columns and rows in the array enclosing the polygon. At least three points must be specified, and all points should lie within the limits: 0 Xi < Sx and 0 Yi < Sy i. As with the POLYFILL procedure, the polygon is defined by connecting each point with its successor and the last point with the first. This function is useful for defining, analyzing, and displaying regions of interest within a two-dimensional array. The scan line coordinate system defined by Rogers in Procedural Elements for Computer Graphics, McGraw-Hill, 1985, page 71, is used. In this system, the scan lines are considered to pass through the center of each row of pixels. Pixels are activated if the center of the pixel is to the right of the intersection of the scan line and the polygon edge within the interval. Syntax Result = POLYFILLV( X, Y, Sx, Sy [, Run_Length] ) Arguments X A vector containing the X subscripts of the vertices that define the polygon. Y A vector containing the Y subscripts of the vertices that define the polygon. Sx The number of columns in the array surrounding the polygon. Sy The number of rows in the array surrounding the polygon. Run_Length Set this optional parameter to a nonzero value to make POLYFILLV return a vector of run lengths, rather than subscripts. For large polygons, a considerable savings in space results. When run-length encoded, each element with an even subscript result contains the length of the run, and the following element contains the starting index of the run. Example To determine the mean and standard deviation of the elements within a triangular region defined by the vertices at pixel coordinates (100, 100), (200, 300), and (300, 100), inside a 512 x 512 array called DATA, enter the commands: ; Get the subscripts of the elements inside the triangle: P = DATA[POLYFILLV([100,200,300], [100,300,100], 512, 512)] ; Use the STDEV function to obtain the mean and standard deviation ; of the selected elements: STD = STDEV(P,MEAN) See Also POLYFILL POLYSHADE [Previous Routine] [Next Routine] [List of Routines] NAME: POLYSHADE The POLYSHADE function returns a shaded-surface representation of one or more solids described by a set of polygons. This function accepts, as arguments, an array of three-dimensional vertices and a list of the indices of the vertices that describe each polygon. Output is a two-dimensional byte array containing the shaded image unless the current graphics output device is the Z-buffer. If the current output device is the Z-buffer, the results are merged with the Z-buffer's contents and the function result contains a dummy value. Shading values are determined from one of three sources: a light source model, a user-specified array containing vertex shade values, or a user-specified array containing polygon shade values. The shaded surface is constructed using the scan line algorithm. The default shading model is a combination of diffuse reflection and depth cueing. With this shading model, polygons are shaded using either constant shading, in which each polygon is given a constant intensity, or with Gouraud shading where the intensity is computed at each vertex and then interpolated over the polygon. Use the SET_SHADING procedure to control the direction of the light source and other shading parameters. User-specified shading arrays allow "4-dimensional" displays that consist of a surface defined by a set of polygons, shaded with values from another variable. Syntax Result = POLYSHADE( Vertices, Polygons) or Result = POLYSHADE(X, Y, Z, Polygons) Keywords: [, /DATA | , /NORMAL] [, POLY_SHADES=array] [, SHADES=array] [, /T3D] [, TOP=value] [, XSIZE=columns] [, YSIZE=rows] Arguments Vertices A (3, n) array containing the X, Y, and Z coordinates of each vertex. Coordinates can be in either data or normalized coordinates, depending on which keywords are present. X, Y, Z The X, Y, and Z coordinates of each vertex can, alternatively, be specified as three array expressions of the same dimensions. Polygons An integer or longword array containing the indices of the vertices for each polygon. The vertices of each polygon should be listed in counterclockwise order when observed from outside the surface. The vertex description of each polygon is a vector of the form: [n, i0, i1, ..., in-1] and the array Polygons is the concatenation of the lists of each polygon. For example, to render a pyramid consisting of four triangles, Polygons would contain 16 elements, made by concatenating four, four-element vectors of the form [3, V0, V1, V2]. V0, V1, and V2 are the indices of the vertices describing each triangle. Keywords DATA Set this keyword to indicate that the vertex coordinates are in data units, the default coordinate system. NORMAL Set this keyword to indicate that coordinates are in normalized units, within the three dimensional (0,1) cube. POLY_SHADES An array expression, with the same number of elements as there are polygons defined in the Polygons array, containing the color index used to render each polygon. No interpolation is performed if all pixels within a given polygon have the same shade value. For most displays, this parameter should be scaled into the range of bytes. SHADES An array expression, with the same number of elements as Vertices, containing the color index at each vertex. The shading of each pixel is interpolated from the surrounding SHADE values. For most displays, this parameter should be scaled into the range of bytes. Warning When using the SHADES keyword on TrueColor devices, we recommend that decomposed color support be turned off by setting DECOMPOSED=0 for DEVICE. T3D Set this keyword to use the three-dimensional to two-dimensional transformation contained in the homogeneous 4 by 4 matrix !P.T. Note that if T3D is set, !P.T must contain a valid transformation matrix. The SURFACE, SCALE3, and T3D procedures (and others) can all be used to set up transformations. TOP The maximum shading value when light source shading is in effect. The default value is one less than the number of colors available in the currently selected graphics device. XSIZE The number of columns in the output image array. If this parameter is omitted, the number of columns is equal to the X size of the currently selected display device. Warning: The size parameters should be explicitly specified when the current graphics device is PostScript or any other high-resolution device. Making the output image the default full device size is likely to cause an insufficient memory error. YSIZE The number of rows in the output image array. If this parameter is omitted, the number of rows is equal to the Y resolution of the currently selected display device. Example POLYSHADE is often used in conjunction with SHADE_VOLUME for volume visualization. The following example creates a spherical volume dataset and renders an isosurface from that dataset: ; Create an empty, 3D array: SPHERE = FLTARR(20, 20, 20) ; Create the spherical dataset: FOR X=0,19 DO FOR Y=0,19 DO FOR Z=0,19 DO $ SPHERE(X, Y, Z) = SQRT((X-10)^2 + (Y-10)^2 + (Z-10)^2) ; Find the vertices and polygons for a density level of 8: SHADE_VOLUME, SPHERE, 8, V, P ; Set up an appropriate 3D transformation so we can see the ; sphere. This step is very important: SCALE3, XRANGE=[0,20], YRANGE=[0,20], ZRANGE=[0,20] ; Render the image. Note that the T3D keyword has been set so that ; the previously-established 3D transformation is used: image = POLYSHADE(V, P, /T3D) ; Display the image: TV, image See Also PROJECT_VOL, RECON3, SET_SHADING, SHADE_SURF, SHADE_VOLUME, VOXEL_PROJ POLYWARP [Previous Routine] [Next Routine] [List of Routines] NAME: POLYWARP The POLYWARP procedure performs polynomial spatial warping. Using least squares estimation, POLYWARP determines the coefficients Kx(i,j) and Ky(i,j) of the polynomial functions: Xi = Kx i, j Xoj Yoi i, j Yi = Ky i, j Xoj Yoi i, j Kx and Ky can be used as inputs P and Q to the built-in function POLY_2D. This coordinate transformation may be then used to map from Xo, Yo coordinates into Xi, Yi coordinates. This routine is written in the IDL language. Its source code can be found in the file polywarp.pro in the lib subdirectory of the IDL distribution. Syntax POLYWARP, Xi, Yi, Xo, Yo, Degree, Kx, Ky[, DOUBLE] [, STATUS] Keywords DOUBLE Set this keyword to use double-precision for computations and to return a double-precision result. Set DOUBLE=0 to use single-precision for computations and to return a single-precision result. The default is /DOUBLE if any of the inputs are double precision, otherwise the default is DOUBLE=0. Keywords STATUS Set this keyword to a named variable to receive the status of the operation. Possible status values are: 0 = Successful completion. 1 = Singular array (which indicates that the inversion is invalid). 2 = Warning that a small pivot element was used and that significant accuracy was probably lost. Note - If STATUS is not specified, any warning messages will be output to the screen. Arguments Xi, Yi Vectors of X and Y coordinates to be fit as a function of Xo and Yo. Xo, Yo Vectors of X and Y independent coordinates. These vectors must have the same number of elements as Xi and Yi. Degree The degree of the fit. The number of coordinate pairs must be greater than or equal to (Degree+1)2. Kx A named variable that will contain the array of coefficients for Xi as a function of (Xo, Yo). This parameter is returned as a (Degree+1) by (Degree+1) element array. Ky A named variable that will contain the array of coefficients for Yi. This parameter is returned as a (Degree+1) by (Degree+1) element array. Example The following example shows how to display an image and warp it using the POLYWARP and POLY_2D routines. ; Create and display the original image: A = BYTSCL(SIN(DIST(250))) TVSCL, A ; Now set up the Xi's and Yi's: XI = [24, 35, 102, 92] YI = [81, 24, 25, 92] ; Enter the Xo's and Yo's: XO = [61, 62, 143, 133] YO = [89, 34, 38, 105] ; Run POLYWARP to obtain a Kx and Ky: POLYWARP, XI, YI, XO, YO, 1, KX, KY ; Create a warped image based on Kx and Ky with POLY_2D: B = POLY_2D(A, KX, KY) ; Display the new image: TV, B See Also POLY_2D, WARP_TRI POPD [Previous Routine] [Next Routine] [List of Routines] NAME: POPD The POPD procedure changes the current working directory to the directory saved on the top of the directory stack maintained by the PUSHD and POPD procedures. This top entry is then removed from the stack. Attempting to pop a directory when the stack is empty causes a warning message to be printed. The current directory is not changed in this case. The common block DIR_STACK is used to store the directory stack. This routine is written in the IDL language. Its source code can be found in the file popd.pro in the lib subdirectory of the IDL distribution. Syntax POPD See Also CD, PRINTD, PUSHD POWELL [Previous Routine] [Next Routine] [List of Routines] NAME: POWELL The POWELL procedure minimizes a user-written function Func of two or more independent variables using the Powell method. POWELL does not require a user- supplied analytic gradient. POWELL is based on the routine powell described in section 10.5 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press, and is used by permission. Syntax POWELL, P, Xi, Ftol, Fmin, Func [, /DOUBLE] [, ITER=variable] [, ITMAX=value] Arguments P On input, P is an n-element vector specifying the starting point. On output, it is replaced with the location of the minimum. Xi On input, Xi is an initial n by n element array whose columns contain the initial set of directions (usually the n unit vectors). On output, it is replaced with the then-current directions. Ftol An input value specifying the fractional tolerance in the function value. Failure to decrease by more than Ftol in one iteration signals completeness. For single- precision computations, a value of 1.0 × 10-4 is recommended; for double-precision computations, a value of 1.0 × 10-8 is recommended. Fmin On output, Fmin contains the value at the minimum-point P of the user-supplied function specified by Func. Func A scalar string specifying the name of a user-supplied IDL function of two or more independent variables to be minimized. This function must accept a vector argument X and return a scalar result. For example, suppose we wish to minimize the function f(x, y) (x + 2y)e x2 ­ y2 ­ = To evaluate this expression, we define an IDL function named POWFUNC: FUNCTION powfunc, X RETURN, (X[0] + 2.0*X[1]) * EXP(-X[0]^2 -X[1]^2) END Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. ITER Use this keyword to specify an output variable that will be set to the number of iterations performed. ITMAX Use this keyword to specify the maximum allowed number of iterations. The default is 200. Warning POWELL halts once the value specified with ITMAX has been reached. Example We can use POWELL to minimize the function POWFUNC given above. PRO TEST_POWELL ; Define the fractional tolerance: ftol = 1.0e-4 ; Define the starting point: P = [.5d, -.25d] ; Define the starting directional vectors in column format: xi = TRANSPOSE([[1.0, 0.0],[0.0, 1.0]]) ; Minimize the function: POWELL, P, xi, ftol, fmin, 'powfunc' ; Print the solution point: PRINT, 'Solution point: ', P ; Print the value at the solution point: PRINT, 'Value at solution point: ', fmin END FUNCTION powfunc, X RETURN, (X[0] + 2.0*X[1]) * EXP(-X[0]^2 -X[1]^2) END IDL prints: Solution point: -0.31622777 -0.63245552 Value at solution point: -0.95900918 The exact solution point is [-0.31622777, -0.63245553]. The exact minimum function value is -0.95900918. See Also AMOEBA, DFPMIN PRIMES [Previous Routine] [Next Routine] [List of Routines] NAME: PRIMES The PRIMES function computes the first K prime numbers. The result is a K-element long integer vector. This routine is written in the IDL language. Its source code can be found in the file primes.pro in the lib subdirectory of the IDL distribution. Syntax Result = PRIMES(K) Arguments K An integer or long integer scalar that specifies the number of primes to be computed. Example To compute the first 25 prime numbers: PRINT, PRIMES(25) IDL prints: 2 3 5 7 11 13 17 19 23 29 31 37 41 43 47 53 59 61 67 71 73 79 83 89 97 PRINT/PRINTF [Previous Routine] [Next Routine] [List of Routines] NAME: PRINT/PRINTF The two PRINT procedures perform formatted output. PRINT performs output to the standard output stream (IDL file unit -1), while PRINTF requires a file unit to be explicitly specified. Syntax PRINT [, Expr1, ..., Exprn] PRINTF [, Unit, Expr1, ..., Exprn] Keywords: [, AM_PM=[string, string]] [, DAYS_OF_WEEK=string_array{7 names}] [, FORMAT=value] [, MONTHS=string_array{12 names}] [, /STDIO_NON_FINITE] VMS Keywords: [, /REWRITE] Arguments Unit For PRINTF, Unit specifies the file unit to which the output is sent. Expri The expressions to be output. Keywords AM_PM Supplies a string array of 2 names to be used for the names of the AM and PM string when processing explicitly formatted dates (CAPA, CApA, and CapA format codes) with the FORMAT keyword. DAYS_OF_WEEK Supplies a string array of 7 names to be used for the names of the days of the week when processing explicitly formatted dates (CDWA, CDwA, and CdwA format codes) with the FORMAT keyword. FORMAT If FORMAT is not specified, IDL uses its default rules for formatting the output. FORMAT allows the format of the output to be specified in precise detail, using a FORTRAN-style specification. See "Using Explicitly Formatted Input/Output" in Chapter 8 of Building IDL Applications. MONTHS Supplies a string array of 12 names to be used for the names of the months when processing explicitly formatted dates (CMOA, CMoA, and CmoA format codes) with the FORMAT keyword. STDIO_NON_FINITE Set this keyword to allow the writing of data files readable by C or FORTRAN programs on a given platform; it is otherwise unnecessary.The various systems supported by IDL differ widely in the representation used for non-finite floating point values (i.e., NaN and Infinity). Consider that the following are all possible representations for NaN on at least one IDL platform: NaN, NanQ, ?.0000, nan0x2, nan0x7, 1.#QNAN, -1.#IND0. And the following are considered to be Infinity: Inf, Infinity, ++.0000, ----.0000, 1.#INF On input, IDL can recognize any of these, but on output, it uses the same standard representation on all platforms. This promotes cross-platform consistency. To cause IDL to use the system C library sprintf() function to format such values, yielding the native representation for that platform, set the STDIO_NON_FINITE keyword. VMS Keywords REWRITE When writing data to a file with indexed organization, set the REWRITE keyword to specify that the data should update the contents of the most recently input record instead of creating a new record. Format Compatibility If the FORMAT keyword is not present and PRINT is called with more than one argument, and the first argument is a scalar string starting with the characters "$(", this initial argument is taken to be the format specification, just as if it had been specified via the FORMAT keyword. This feature is maintained for compatibility with version 1 of VMS IDL. Example To print the string "IDL is fun." enter the command: PRINT, 'IDL is fun.' To print the same message to the open file associated with file unit number 2, use the command: PRINTF, 2, 'IDL is fun.' See Also ANNOTATE, MESSAGE, WRITEU, XYOUTS PRINTD [Previous Routine] [Next Routine] [List of Routines] NAME: PRINTD The PRINTD procedure prints the contents of the directory stack maintained by the PUSHD and POPD procedures. The contents of the directory stack are listed on the default output device. The common block DIR_STACK is used to store the directory stack. This routine is written in the IDL language. Its source code can be found in the file printd.pro in the lib subdirectory of the IDL distribution. Syntax PRINTD See Also CD, POPD, PUSHD PRO [Previous Routine] [Next Routine] [List of Routines] NAME: PRO The PRO statement defines an IDL procedure. Note For information on using the PRO statement, see Chapter 12, "Procedures and Functions" in Building IDL Applications. Syntax PRO Procedure_Name, argument1, ..., argumentn END Arguments argumentn A parameter that is passed to the procedure. Example The following example demonstrates the use of arguments in a PRO statement: PRO MYPROCEDURE X = 5 ; Call the ADD procedure: ADD, 3, X END PRO ADD, A, B PRINT, 'A = ', A PRINT, 'B = ', B A = A + B PRINT, 'A = ', A END After running myprocedure.pro, IDL returns: A = 3 B = 5 A = 8 PROFILE [Previous Routine] [Next Routine] [List of Routines] NAME: PROFILE The PROFILE function extracts a profile from an image and returns a floating-point vector containing the values of the image along the profile line marked by the user. This routine is written in the IDL language. Its source code can be found in the file profile.pro in the lib subdirectory of the IDL distribution. Using PROFILE To mark a profile line after calling PROFILE, click in the image with the left mouse button to mark the beginning and ending points. The pixel coordinates of the selected points are displayed in the IDL command log. Syntax Result = PROFILE( Image [, XX, YY] [, /NOMARK] [, XSTART=value] [, YSTART=value] ) Arguments Image The data array representing the image. This array can be of any type except complex. XX A named variable that will contain the X coordinates of the points along the selected profile. YY A named variable that will contain the Y coordinates of the points along the selected profile. Keywords NOMARK Set this keyword to inhibit marking the image with the profile line. XSTART The starting X location of the lower-left corner of Image. If this keyword is not specified, 0 is assumed. YSTART The starting Y location of the lower-left corner of Image. If this keyword is not specified, 0 is assumed. Example This example displays an image, selects a profile, and plots that profile in a new window: ; Create an image: A = BYTSCL(DIST(256)) ; Display the image: TV, A ; Extract a profile from the image: R = PROFILE(A) Mark two points on the image with the mouse. ; Create a new plotting window: WINDOW, /FREE ; Plot the profile: PLOT, R Note The PROFILES procedure is an interactive version of this routine. See Also PROFILES PROFILER [Previous Routine] [Next Routine] [List of Routines] NAME: PROFILER The PROFILER procedure allows you to access the IDL Code Profiler. The IDL Code Profiler helps you analyze the performance of your applications. You can easily monitor the calling frequency and execution time for procedures and functions. Syntax PROFILER [, Module] [, /CLEAR] [, DATA=variable] [, OUTPUT=variable] [, /REPORT] [, /RESET] [, /SYSTEM] Arguments Module The program to which changes in profiling will be applied. If Module is not specified, profiling changes will be applied to all currently-compiled programs. Note The Module is often named with respect to the file in which it is stored. For example, the file build_it.pro may contain the module, build_it. If you specify the file name, you will incur a syntax error. Keywords CLEAR Set this keyword to disable profiling of Module or of all compiled modules if Module is not specified. OUTPUT Set this keyword to a specified variable in which to store the results of the REPORT keyword. REPORT Set this keyword to report the results of profiling. If you enter a program at the command line, the PROFILER procedure will report the status of all the specified modules used either since the beginning of the IDL session, or since the PROFILER was reset. RESET Set this keyword to clear the results of profiling. SYSTEM Set this keyword to profile IDL system procedures and functions. By default, only user-written or library files, which have been compiled, are profiled. Example ; Include IDL system procedures and functions when profiling: PROFILER, /SYSTEM ; Create a dataset using the library function DIST. Note that DIST ; is immediately compiled: A= DIST(500) ; Display the image: TV, A ; Retrieve the profiling results: PROFILER, /REPORT IDL prints: Module Type Count Only(s) Avg.(s) Time(s) Avg.(s) FINDGEN (S) 1 0.000239 0.000239 0.000239 0.000239 FLTARR (S) 1 0.010171 0.010171 0.010171 0.010171 N_ELEMENTS (S) 1 0.000104 0.000104 0.000104 0.000104 ON_ERROR (S) 1 0.000178 0.000178 0.000178 0.000178 SQRT (S) 251 0.099001 0.000394 0.099001 0.000394 TV (S) 1 2.030000 2.030000 2.030000 2.030000 PROFILES [Previous Routine] [Next Routine] [List of Routines] NAME: PROFILES The PROFILES procedure interactively draws row or column profiles of an image in a separate window. A new window is created and the mouse location in the original window is used to plot profiles in the new window. This routine is written in the IDL language. Its source code can be found in the file profiles.pro in the lib subdirectory of the IDL distribution. Using PROFILES Moving the mouse within the original image interactively creates profile plots in the newly-created profile window. Pressing the left mouse button toggles between row and column profiles. The right mouse button exits. Syntax PROFILES, Image [, /ORDER] [, SX=value] [, SY=value] [, WSIZE=value] Arguments Image The variable that represents the image displayed in the current window. This data need not be scaled into bytes. The profile graphs are made from this array, even if it is not currently displayed. Keywords ORDER Set this keyword to 1 for images written top down or 0 for bottom up. Default is the current value of !ORDER. SX Starting X position of the image in the window. If this keyword is omitted, 0 is assumed. SY Starting Y position of the image in the window. If this keyword is omitted, 0 is assumed. WSIZE The size of the PROFILES window as a fraction or multiple of 640 by 512. Example Create and display an image and use the PROFILES routine on it. ; Create an image: A = BYTSCL(DIST(256)) ; Display the image: TV, A ; Run the PROFILES routine: PROFILES, A, WSIZE = .5 A 320 x 256 pixel PROFILES window should appear. Move the cursor over the original image to see the profile at the cursor position. Press the left mouse button to toggle between row and column profiles. Press the right mouse button (with the cursor over the original image) to exit the routine. See Also PROFILE PROJECT_VOL [Previous Routine] [Next Routine] [List of Routines] NAME: PROJECT_VOL The PROJECT_VOL function returns a two-dimensional image that is the projection of a 3D volume of data onto a plane (similar to an X-ray). The returned image is a translucent rendering of the volume (the highest data values within the volume show up as the brightest regions in the returned image). Depth queuing and opacity may be used to affect the image. The volume is projected using a 4x4 matrix, so any type of projection may be used including perspective. Typically the system viewing matrix (!P.T) is used as the 4x4 matrix. Note that the VOXEL_PROJ procedure performs many of the same functions as this routine, and is faster. This routine is written in the IDL language. Its source code can be found in the file project_vol.pro in the lib subdirectory of the IDL distribution. Syntax Return = PROJECT_VOL( Vol, X_Sample, Y_Sample, Z_Sample [, DEPTH_Q=value] [, OPAQUE=3D_array] [, TRANS=array] ) Arguments Vol A 3D array of any type except string or structure containing the three dimensional volume of data to project. X_Sample A long integer specifying the number of rays to project along the X dimension of the image. The returned image will have the dimensions X_sample by Y_sample. Y_Sample A long integer specifying the number of rays to project along the Y dimension of the image. To preserve the correct aspect ratio of the data, Y_sample should equal X_sample. Z_Sample A long integer specifying the number of samples to take along each ray. Higher values for X_sample, Y_sample, and Z_sample increase the image resolution as well as execution time. Keywords DEPTH_Q Set this keyword to indicate that the image should be created using depth queuing. The depth queuing should be a single floating-point value between 0.0 and 1.0. This value specifies the brightness of the farthest regions of the volume relative to the closest regions of the volume. A value of 0.0 will cause the back side of the volume to be completely blacked out, while a value of 1.0 indicates that the back side will show up just as bright as the front side. The default is 1.0 (indicating no depth queuing). OPAQUE A 3D array of any type except string or structure, with the same size and dimensions as Vol. This array specifies the opacity of each cell in the volume. OPAQUE values of 0 allow all light to pass through. OPAQUE values are cumulative. For example, if a ray emanates from a data value of 50, and then passes through 10 opaque cells (each with a data value of 0 and an opacity value of 5) then that ray would be completely blocked out (the cell with the data value of 50 would be invisible on the returned image). The default is no opacity. TRANS A 4x4 floating-point array to use as the transformation matrix when projecting the volume. The default is to use the system viewing matrix (!P.T). Example Use the T3D routine to set up a viewing projection and render a volume of data using PROJECT_VOL. ; First, create some data: vol = RANDOMU(S, 40, 40, 40) FOR I=0, 10 DO vol = SMOOTH(vol, 3) vol = BYTSCL(vol(3:37, 3:37, 3:37)) opaque = RANDOMU(S, 40, 40, 40) FOR I=0, 10 DO opaque = SMOOTH(opaque, 3) opaque = BYTSCL(opaque(3:37, 3:37, 3:37), TOP=25B) ; Set up the view: xmin = 0 & ymin = 0 & zmin = 0 xmax = 34 & ymax = 34 & zmax = 34 !X.S = [-xmin, 1.0] / (xmax - xmin) !Y.S = [-ymin, 1.0] / (ymax - ymin) !Z.S = [-zmin, 1.0] / (zmax - zmin) T3D, /RESET T3D, TRANSLATE=[-0.5, -0.5, -0.5] T3D, SCALE=[0.7, 0.7, 0.7] T3D, ROTATE=[30, -30, 60] T3D, TRANSLATE=[0.5, 0.5, 0.5] WINDOW, 0, XSIZE=512, YSIZE=512 ; Generate and display the image: img = PROJECT_VOL(vol, 64, 64, 64, DEPTH_Q=0.7, $ OPAQUE=opaque, TRANS=(!P.T)) TVSCL, img See Also POLYSHADE, VOXEL_PROJ PS_SHOW_FONTS [Previous Routine] [Next Routine] [List of Routines] NAME: PS_SHOW_FONTS The PS_SHOW_FONTS procedure displays all the PostScript fonts that IDL knows about, with both the StandardAdobe and ISOLatin1 encodings. Each display takes a separate page, and each character in each font is shown with its character index. A PostScript file is produced, one page per font/mapping combination. The output file contains almost 70 pages of output. A PostScript previewer is recommended rather than sending it to a printer. This routine is written in the IDL language. Its source code can be found in the file ps_show_fonts.pro in the lib subdirectory of the IDL distribution. Syntax PS_SHOW_FONTS [, /NOLATIN] Keywords NOLATIN Set this keyword to prevent output of ISOLatin1 encodings. See Also PSAFM PSAFM [Previous Routine] [Next Routine] [List of Routines] NAME: PSAFM The PSAFM procedure takes an Adobe Font Metrics file as input and generates a new AFM file in the format that IDL likes. This new file differs from the original in the following ways: * Information not used by IDL is removed. * AFM files with the AdobeStandardEncoding are supplemented with an ISOLatin1Encoding. This routine is written in the IDL language. Its source code can be found in the file psafm.pro in the lib subdirectory of the IDL distribution. Syntax PSAFM, Input_Filename, Output_Filename Arguments Input_Filename A string that contains the name of existing AFM file from Adobe. Output_Filename A string that specifies the name of new IDL-format AFM file to be created. See Also PS_SHOW_FONTS PSEUDO [Previous Routine] [Next Routine] [List of Routines] NAME: PSEUDO The PSEUDO procedure creates a pseudo-color table based on the LHB (Lightness, Hue, and Brightness) system and loads it. The pseudo-color mapping used is generated by first translating from the LHB coordinate system to the LAB coordinate system, finding N colors spread out along a helix that spans this LAB space (supposedly a near maximal entropy mapping for the eye, given a particular N) and remapping back into the RGB (Red, Green, and Blue) colorspace. The result is loaded as the current colortable. This routine is written in the IDL language. Its source code can be found in the file pseudo.pro in the lib subdirectory of the IDL distribution. Syntax PSEUDO, Litlo, Lithi, Satlo, Sathi, Hue, Loops [, Colr] Arguments Litlo Starting lightness, from 0 to 100%. Lithi Ending lightness, from 0 to 100%. Satlo Starting saturation, from 0 to 100%. Sathi Ending saturation, from 0 to 100%. Hue Starting hue, in degrees, from 0 to 360. Loops The number of loops of hue to make in the color helix. This value can range from 0 to around 3 to 5 and need not be an integer. Colr An optional (256,3) integer array in which the new R, G, and B values are returned. Red = Colr[*,0], green = Colr[*,1], blue = Colr[*,2]. See Also COLOR_CONVERT, COLOR_QUAN PSYM [Previous Routine] [Next Routine] [List of Routines] NAME: PSYM Set this keyword to a plotting symbol index to be used in plotting the data. For more information, see "PSYM" on page 2408. PTR_FREE [Previous Routine] [Next Routine] [List of Routines] NAME: PTR_FREE The PTR_FREE procedure destroys the heap variables pointed at by its pointer arguments. Any memory used by the heap variable is released, and the variable ceases to exist. No change is made to the arguments themselves and all pointers to the destroyed variables continue to exist. Such pointers are known as dangling references. PTR_FREE is the only way that pointer heap variables can be destroyed. If PTR_FREE is not called on a heap variable, it continues to exist until the IDL session ends, even if no pointers remain that can be used to reference it. Note that PTR_FREE does not recurse. That is, if the heap variable pointed at by pointer1 contains pointer2, destroying pointer1 will not destroy the heap variable pointed at by pointer2. Take care not to lose the only pointer to a heap variable by destroying a pointer to a heap variable that contains that pointer. Syntax PTR_FREE, P1, ... ..., Pn Arguments Pi Scalar or array arguments of pointer type. If the NULL pointer is passed, PTR_FREE ignores it quietly. PTR_NEW [Previous Routine] [Next Routine] [List of Routines] NAME: PTR_NEW The PTR_NEW function provides the primary mechanism for creating heap variables. It returns a pointer to the created variable. Syntax Result = PTR_NEW( [InitExpr] [, /ALLOCATE_HEAP] [, /NO_COPY] ) Arguments InitExpr If InitExpr is provided, PTR_NEW uses it to initialize the newly created heap variable. Note that the new heap variable does not point at the InitExpr variable in any sense-the new heap variable simply contains a copy of its value. If InitExpr is not provided, PTR_NEW does not create a new heap variable, and returns the Null Pointer, a special pointer with a fixed known value that can never point at a heap variable. The null pointer is useful as a terminator in dynamic data structures, or as a placeholder in structure definitions. Keywords ALLOCATE_HEAP Set this keyword to cause PTR_NEW to allocate an undefined heap variable rather than return a null pointer when InitExpr is not specified. NO_COPY Usually, when the InitExpr argument is provided, PTR_NEW allocates additional memory to make a copy. If the NO_COPY keyword is set, the value data is taken away from the InitExpr variable and attached directly to the heap variable. This feature can be used to move data very efficiently. However, it has the side effect of causing the InitExpr variable to become undefined. Using the NO_COPY keyword is completely equivalent to the statement: Result = PTR_NEW(TEMPORARY(InitExpr)) and is provided as a syntactic convenience. PTR_VALID [Previous Routine] [Next Routine] [List of Routines] NAME: PTR_VALID The PTR_VALID function verifies the validity of its pointer arguments, or alternatively returns a vector of pointers to all the existing valid pointer heap variables. If called with an pointer or array of pointers as its argument, PTR_VALID returns a byte array of the same size as the argument. Each element of the result is set to True (1) if the corresponding pointer in the argument refers to an existing valid heap variable, or to False (0) otherwise. If called with an integer or array of integers as its argument and the CAST keyword is set, PTR_VALID returns an array of pointers. Each element of the result is a pointer to the heap variable indexed by the integer value. Integers used to index heap variables are shown in the output of the HELP and PRINT commands. This is useful primarily in programming/debugging when you have lost a reference but see it with HELP and need to get a reference to it interactively in order to determine what it is and take steps to fix the code. See the "Examples" section below for an example. If no argument is specified, PTR_VALID returns a vector of pointers to all existing valid pointer heap variables-even if there are currently no pointers to the heap variable. This usage allows you to "reclaim" pointer heap variables to which all pointers have been lost. If no valid pointer heap variables exist, a scalar null pointer is returned. Syntax Result = PTR_VALID( [Arg] [, /CAST] [, COUNT=variable] ) Arguments Arg Arg can be one of the following: 1. A scalar or array argument of pointer type. 2. If the CAST keyword is set, an integer index or array of integer indices to heap variables. Integers used to index heap variables are shown in the output of the HELP and PRINT commands. Keywords CAST Set this keyword to create a new pointer to each heap variable index specified in Arg. COUNT Set this keyword equal to a named variable that will contain the number of currently valid heap variables. This value is returned as a longword integer. Examples To determine if a given pointer refers to a valid heap variable: IF (PTR_VALID(p)) THEN ... To destroy all existing pointer heap variables: PTR_FREE, PTR_VALID() You can use the CAST keyword to "reclaim" lost heap variables. For example: A = PTR_NEW(10) PRINT, A IDL prints: In this case, the integer index to the heap variable is 2. If we reassign the variable A, we will "lose" the pointer, but the heap variable will still exist: A=0 PRINT, A, PTR_VALID() IDL prints: 0 We can reclaim the lost heap variable using the CAST keyword: A = PTR_VALID(2, /CAST) PRINT, A IDL prints: PTRARR [Previous Routine] [Next Routine] [List of Routines] NAME: PTRARR The PTRARR function returns a pointer vector or array. The individual elements of the array are set to the Null Pointer. Syntax Result = PTRARR( D1, ... ..., D8 [, /ALLOCATE_HEAP | , /NOZERO] ) Arguments Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. The dimensions of the result. The dimension parameters can be any scalar expression. Up to eight dimensions can be specified. Keywords ALLOCATE_HEAP Normally, PTRARR sets every element of the result to the null pointer. It you wish IDL to allocate heap variables for every element of the array instead, set the ALLOCATE_HEAP keyword. In this case, every element of the array will be initialized to point at an undefined heap variable. NOZERO If ALLOCATE_HEAP is not specified, PTRARR sets every element of the result to the null pointer. If NOZERO is nonzero, this initialization is not performed and PTRARR executes faster. NOZERO is ignored if ALLOCATE_HEAP is specified. Warning If you specify NOZERO, the resulting array will have whatever value happens to exist at the system memory location that the array is allocated from. You should be careful to initialize such an array to valid pointer values. Example Create P, a 3 element by 3 element pointer array with each element containing the Null Pointer by entering: P = PTRARR(3, 3) PUSHD [Previous Routine] [Next Routine] [List of Routines] NAME: PUSHD The PUSHD procedure pushes a directory onto the top of the directory stack maintained by the PUSHD and POPD procedures. The name of the current directory is pushed onto the directory stack. This directory becomes the next directory used by POPD. IDL changes directories to the one specified by the Dir argument. The common block DIR_STACK is used to store the directory stack. This routine is written in the IDL language. Its source code can be found in the file pushd.pro in the lib subdirectory of the IDL distribution. Syntax PUSHD, Dir Arguments Dir A string containing the name of the directory to change to. The current directory is pushed onto the top of the directory stack. See Also CD, POPD, PRINTD QROMB [Previous Routine] [Next Routine] [List of Routines] NAME: QROMB The QROMB function evaluates the integral of a function over the closed interval [A, B] using Romberg integration. The result will have the same structure as the smaller of A and B, and the resulting type will be single- or double-precision floating, depending on the input types. QROMB is based on the routine qromb described in section 4.3 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press, and is used by permission. Syntax Result = QROMB( Func, A, B [, /DOUBLE] [, EPS=value] [, JMAX=value] [, K=value] ) Arguments Func A scalar string specifying the name of a user-supplied IDL function to be integrated. This function must accept a single scalar argument X and return a scalar result. It must be defined over the closed interval [A, B]. For example, if we wish to integrate the cubic polynomial y = x3 + (x - 1)2 + 3 we define a function CUBIC to express this relationship in the IDL language: FUNCTION cubic, X RETURN, X^3 + (X - 1.0)^2 + 3.0 END A The lower limit of the integration. A can be either a scalar or an array. B The upper limit of the integration. B can be either a scalar or an array. Note If arrays are specified for A and B, then QROMB integrates the user-supplied function over the interval [Ai, Bi] for each i. If either A or B is a scalar and the other an array, the scalar is paired with each array element in turn. Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. EPS The desired fractional accuracy. For single-precision calculations, the default value is 1.0 × 10-6. For double-precision calculations, the default value is 1.0 × 10-12. JMAX 2(JMAX - 1) is the maximum allowed number of steps. If this keyword is not specified, a default of 20 is used. K Integration is performed by Romberg's method of order 2K. If not specified, the default is K=5. (K=2 is Simpson's rule). Example To integrate the CUBIC function (listed above) over the interval [0, 3] and print the result: PRINT, QROMB('cubic', 0.0, 3.0) IDL prints: 32.2500 This is the exact solution. See Also INT_2D, INT_3D, INT_TABULATED, QROMO, QSIMP QROMO [Previous Routine] [Next Routine] [List of Routines] NAME: QROMO The QROMO function evaluates the integral of a function over the open interval (A, B) using a modified Romberg's method. QROMO is based on the routine qromo described in section 4.4 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press, and is used by permission. Syntax Result = QROMO(Func, A [, B] [, /DOUBLE] [, EPS=value] [, JMAX=value] [, K=value] [, /MIDEXP | , /MIDINF | , /MIDPNT | , /MIDSQL | , /MIDSQU] ) Arguments Func A scalar string specifying the name of a user-supplied IDL function to be integrated. This function must accept a single scalar argument X and return a scalar result. It must be defined over the open interval (A, B). For example, if we wish to integrate the fourth-order polynomial y = 1 / x4 we define a function HYPER to express this relationship in the IDL language: FUNCTION hyper, X RETURN, 1.0 / X^4 END A The lower limit of the integration. A can be either a scalar or an array. B The upper limit of the integration. B can be either a scalar or an array. If the MIDEXP keyword is specified, B is assumed to be infinite, and should not be supplied by the user. Note: If arrays are specified for A and B, then QROMO integrates the user-supplied function over the interval [Ai, Bi] for each i. If either A or B is a scalar and the other an array, the scalar is paired with each array element in turn. Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. EPS The fractional accuracy desired, as determined by the extrapolation error estimate. For single-precision calculations, the default value is 1.0 × 10-6. For double-precision calculations, the default value is 1.0 × 10-12. JMAX Set to specify the maximum allowed number of mid quadrature points to be 3(JMAX - 1). The default value is 14. K Integration is performed by Romberg's method of order 2K. If not specified, the default is K=5. MIDEXP Use the midexp() function (see Numerical Recipes, section 4.4) as the integrating function. If the MIDEXP keyword is specified, argument B is assumed to be infinite, and should not be supplied by the user. MIDINF Use the midinf() function (see Numerical Recipes, section 4.4) as the integrating function. MIDPNT Use the midpnt() function (see Numerical Recipes, section 4.4) as the integrating function. This is the default if no other integrating function keyword is specified. MIDSQL Use the midsql() function (see Numerical Recipes, section 4.4) as the integrating function. MIDSQU Use the midsqu() function (see Numerical Recipes, section 4.4) as the integrating function. Example Consider the following function: FUNCTION hyper, X RETURN, 1.0 / X^4 END This example integrates the HYPER function over the open interval (2, ) and prints the result: PRINT, QROMO('hyper', 2.0, /MIDEXP) IDL prints: 0.0412050 Warning When using the MIDEXP keyword, the upper integration limit is assumed to be infinity and is not supplied. See Also INT_2D, INT_3D, INT_TABULATED, QROMB, QSIMP QSIMP [Previous Routine] [Next Routine] [List of Routines] NAME: QSIMP The QSIMP function performs numerical integration of a function over the closed interval [A, B] using Simpson's rule. The result will have the same structure as the smaller of A and B, and the resulting type will be single- or double-precision floating, depending on the input types. QSIMP is based on the routine qsimp described in section 4.2 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press, and is used by permission. Syntax Result = QSIMP( Func, A, B [, /DOUBLE] [, EPS=value] [, JMAX=value] ) Arguments Func A scalar string specifying the name of a user-supplied IDL function to be integrated. This function must accept a single scalar argument X and return a scalar result. It must be defined over the closed interval [A, B]. For example, if we wish to integrate the fourth-order polynomial y = (x4 - 2x2) sin(x) we define a function SIMPSON to express this relationship in the IDL language: FUNCTION simpson, X RETURN, (X^4 - 2.0 * X^2) * SIN(X) END A The lower limit of the integration. A can be either a scalar or an array. B The upper limit of the integration. B can be either a scalar or an array. Note: If arrays are specified for A and B, then QSIMP integrates the user-supplied function over the interval [Ai, Bi] for each i. If either A or B is a scalar and the other an array, the scalar is paired with each array element in turn. Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. EPS The desired fractional accuracy. For single-precision calculations, the default value is 1.0 × 10-6. For double-precision calculations, the default value is 1.0 × 10-12. JMAX 2(JMAX - 1) is the maximum allowed number of steps. If not specified, a default of 20 is used. Example To integrate the SIMPSON function (listed above) over the interval [0, /2] and print the result: ; Define lower limit of integration: A = 0.0 ; Define upper limit of integration: B = !PI/2.0 PRINT, QSIMP('simpson', A, B) IDL prints: -0.479158 The exact solution can be found using the integration-by-parts formula: FB = 4.*B*(B^2-7.)*SIN(B) - (B^4-14.*B^2+28.)*COS(B) FA = 4.*A*(A^2-7.)*SIN(A) - (A^4-14.*A^2+28.)*COS(A) exact = FB - FA PRINT, exact IDL prints: -0.479156 See Also INT_2D, INT_3D, INT_TABULATED, QROMB, QROMO QUERY_* ROUTINES [Previous Routine] [Next Routine] [List of Routines] NAME: QUERY_* Routines Query routines allow users to obtain information about an image file without having to read the file. The following QUERY_* routines are available in IDL: * QUERY_BMP * QUERY_PNG * QUERY_DICOM * QUERY_PPM * QUERY_IMAGE * QUERY_SRF * QUERY_JPEG * QUERY_TIFF * QUERY_PICT * QUERY_WAV All of the QUERY_* routines return a result, which is a long with the value of 1 if the query was successful (and the file type was correct) or 0 on failure. If the query was successful, the return argument will be an anonymous structure containing all of the available information for that image format. The status is intended to be used to determine if it is appropriate to use the corresponding READ_ routine for a given file. The return status of the QUERY_* will indicate success if the corresponding READ_ routine is likely to be able to read the file. The return status will indicate failure for cases that contain formats that are not supported by the READ_ routines, even though the files may be valid outside of the IDL environment. For example, IDL's READ_BMP does not support 1-bit-deep images and so the QUERY_BMP function would return failure in the case of a monochrome BMP file. The returned anonymous structure will have (minimally) the following fields for all file formats. If the file does not support multiple images in a single file, the NUM_IMAGES field will always be 1 and the IMAGE_INDEX field will always be 0. Individual routines will document additional fields which are returned for a specific format. Field IDL data type Description CHANNELS Long Number of samples per pixel DIMENSIONS 2-D long array Size of the image in pixels HAS_PALETTE Integer True if a palette is present Table 77: Query Routines Info Structure Field IDL data type Description NUM_IMAGES Long Number of images in the file IMAGE_INDEX Long Image number for which this structure is valid PIXEL_TYPE Integer IDL basic type code for a pixel sample TYPE String String identifying the file format Table 77: Query Routines Info Structure All the routines accept the IMAGE_INDEX keyword although formats which do not support multiple images in a single file will ignore this keyword. QUERY_BMP [Previous Routine] [Next Routine] [List of Routines] NAME: QUERY_BMP QUERY_BMP is a method of obtaining information about a BMP image file without having to read the file. See "QUERY_* Routines" on page 1063 for more information. This routine returns a long with the value of 1 if the query was successful (and the file type was correct) or 0 on failure. Syntax Result = QUERY_BMP ( Filename [, Info] ) Arguments Filename A scalar string containing the pathname of the BMP file to query. Info Returns an anonymous structure containing information about the image in the file. The Info.TYPE field will return the value `BMP'. Note See "QUERY_* Routines" on page 1063 for detailed structure info. Keywords There are no keywords for this routine. See Also QUERY_* Routines, READ_BMP, WRITE_BMP QUERY_DICOM [Previous Routine] [Next Routine] [List of Routines] NAME: QUERY_DICOM The QUERY_DICOM function tests a file for compatibility with READ_DICOM and returns an optional structure containing information about images in the DICOM file. This function supports cases in which a blank DICOM tag is supplied. The result is 0 on failure, and 1 on success. A result of 1 means it is likely that the file can be read by READ_DICOM. This routine is written in the IDL language. Its source code can be found in the file query_dicom.pro in the lib subdirectory of the IDL distribution. Syntax Result = QUERY_DICOM( Filename [, Info] [, IMAGE_INDEX=index] ) Arguments Filename A scalar string containing the full pathname of the file to query. Info Returns an anonymous structure containing information about the image in the file. The Info.TYPE field will return the value `DICOM'. Note See "QUERY_* Routines" on page 1063 for detailed structure info. Keywords IMAGE_INDEX Set this keyword to the index (zero based) of the image being queried in the file. This keyword has no effect on files containing a single image. Example DICOM palette vectors are 16 bit quantities and may not cover the entire dynamic range of the image. To view a paletted DICOM image use the following: IF (QUERY_DICOM('file.dcm',info)) THEN BEGIN IF (info.has_palette) THEN BEGIN TV, READ_IMAGE('file.dcm',r, g, b), /ORDER TVLCT,r/256, g/256, b/256 ENDIF ENDIF See Also READ_DICOM QUERY_IMAGE [Previous Routine] [Next Routine] [List of Routines] NAME: QUERY_IMAGE The QUERY_IMAGE function determines whether a file is recognized as a supported image file. QUERY_IMAGE first checks the filename suffix, and if found, calls the corresponding QUERY_ routine. For example, if the specified file is image.bmp, QUERY_BMP is called to determine if the file is a valid .bmp file. If the file does not contain a filename suffix, or if the query fails on the specified filename suffix, QUERY_IMAGE checks against all supported file types. If the file is a supported image file, an optional structure containing information about the image is returned. If the file is not a supported image file, QUERY_IMAGE returns 0. Syntax Result = QUERY_IMAGE ( Filename[, Info] [, CHANNELS=variable] [, DIMENSIONS=variable] [, HAS_PALETTE=variable] [, IMAGE_INDEX=index] [, NUM_IMAGES=variable] [, PIXEL_TYPE=variable] [, SUPPORTED_READ=variable] [, SUPPORTED_WRITE=variable] [, TYPE=variable] ) Return Value Result is a long with the value of 1 if the query was successful (the file was recognized as an image file) or 0 on failure. The return status will indicate failure for files that contain formats that are not supported by the corresponding READ_* routine, even though the file may be valid outside the IDL environment. Arguments Filename A scalar string containing the name of the file to query. Info An optional anonymous structure containing information about the image. This structure is valid only when the return value of the function is 1. The Info structure for all image types has the following fields: Tag Type CHANNELS Long DIMENSIONS Two-dimensional long array FILENAME Scalar string HAS_PALETTE Integer IMAGE_INDEX Long NUM_IMAGES Long PIXEL_TYPE Integer TYPE Scalar string Table 78: The Info Structure for All Image Types Keywords CHANNELS Set this keyword to a named variable to retrieve the number of channels in the image. DIMENSIONS Set this keyword to a named variable to retrieve the image dimensions as a two- dimensional array. HAS_PALETTE Set this keyword to a named variable to equal to 1 if a palette is present, else 0. IMAGE_INDEX Set this keyword to the index of the image to query from the file. The default is 0, the first image. NUM_IMAGES Set this keyword to a named variable to retrieve the number of images in the file. PIXEL_TYPE Set this keyword to a named variable to retrieve the IDL Type Code of the image pixel format. See the documentation for the SIZE routine for a complete list of IDL Type Codes. The valid types for PIXEL_TYPE are: * 1 = Byte * 2 = Integer * 3 = Longword Integer * 4 = Floating Point * 5 = Double-precision Floating Point * 12 = Unsigned Integer * 13 - Unsigned Longword Integer * 14 - 64-bit Integer * 15 - Unsigned 64-bit Integer SUPPORTED_READ Set this keyword to a named variable to retrieve a string array of image types recognized by READ_IMAGE. If the SUPPORTED_READ keyword is used the filename and info arguments are optional. SUPPORTED_WRITE Set this keyword to a named variable to retrieve a string array of image types recognized by WRITE_IMAGE. If the SUPPORTED_WRITE keyword is used the filename and info arguments are optional. TYPE Set this keyword to a named variable to retrieve the image type as a scalar string. Possible return values are BMP, JPEG, PNG, PPM, SRF, TIFF, or DICOM. QUERY_JPEG [Previous Routine] [Next Routine] [List of Routines] NAME: QUERY_JPEG QUERY_JPG is a method of obtaining information about a JPEG image file without having to read the file. See "QUERY_* Routines" on page 1063 for more information. This routine returns a long with the value of 1 if the query was successful (and the file type was correct) or 0 on failure. Syntax Result = QUERY_JPEG ( Filename [, Info] ) Arguments Filename A scalar string containing the pathname of the JPEG file to query. Info Returns an anonymous structure containing information about the image in the file. The Info.TYPE field will return the value `JPEG'. Note See "QUERY_* Routines" on page 1063 for detailed structure info. Keywords None See Also QUERY_* Routines, READ_JPEG, WRITE_JPEG QUERY_PICT [Previous Routine] [Next Routine] [List of Routines] NAME: QUERY_PICT QUERY_PICT is a method of obtaining information about a PICT image file without having to read the file. See "QUERY_* Routines" on page 1063 for more information. This routine returns a long with the value of 1 if the query was successful (and the file type was correct) or 0 on failure. Syntax Result = QUERY_PICT ( Filename [, Info] ) Arguments Filename A scalar string containing the pathname of the PICT file to query. Info Returns an anonymous structure containing information about the image in the file. The Info.TYPE field will return the value `PICT'. Note See "QUERY_* Routines" on page 1063 for detailed structure info. Keywords None See Also QUERY_* Routines, READ_PICT, WRITE_PICT QUERY_PNG [Previous Routine] [Next Routine] [List of Routines] NAME: QUERY_PNG QUERY_PNG is a method of obtaining information about a PNG image file without having to read the file. See "QUERY_* Routines" on page 1063 for more information. This routine returns a long with the value of 1 if the query was successful (and the file type was correct) or 0 on failure. Syntax Result = QUERY_PNG ( Filename [, Info] ) Arguments Filename A scalar string containing the pathname of the PNG file to query. Info Returns an anonymous structure containing information about the image in the file. The Info.TYPE field will return the value `PNG'. Note See "QUERY_* Routines" on page 1063 for detailed structure info. Keywords None Example Query included in creating RGBA (16-bit/channel) and Color Indexed (8-bits/channel) image. rgbdata = UINDGEN(4,320,240) cidata = BYTSCL(DIST(256)) red = indgen(256) green = indgen(256) blue = indgen(256) WRITE_PNG,'rgb_image.png',rgbdata WRITE_PNG,'ci_image.png',cidata,red,green,blue ; Query and Read the data: names = ['rgb_image.png','ci_image.png','unknown.png'] FOR i=0,N_ELEMENTS(names)-1 DO BEGIN ok = QUERY_PNG(names[i],s) IF (ok) THEN BEGIN HELP,s,/STRUCTURE IF (s.HAS_PALETTE) THEN BEGIN img = READ_PNG(names[i],rpal,gpal,bpal) HELP,img,rpal,gpal,bpal ENDIF ELSE BEGIN img = READ_PNG(names[i]) HELP,img ENDELSE ENDIF ELSE BEGIN PRINT,names[i],' is not a PNG file' ENDELSE ENDFOR END See Also QUERY_* Routines, READ_PNG, WRITE_PNG QUERY_PPM [Previous Routine] [Next Routine] [List of Routines] NAME: QUERY_PPM QUERY_PPM is a method of obtaining information about a PPM image file without having to read the file. See "QUERY_* Routines" on page 1063 for more information. This routine returns a long with the value of 1 if the query was successful (and the file type was correct) or 0 on failure. Syntax Result = QUERY_PPM ( Filename [, Info] [, MAXVAL=variable] ) Arguments Filename A scalar string containing the pathname of the PPM file to query. Info Returns an anonymous structure containing information about the image. The Info.TYPE field will return the value `PPM'. Additional field in the Info structure: MAXVAL - maximum pixel value in the image. Note See "QUERY_* Routines" on page 1063 for detailed structure info. Keywords MAXVAL Set this keyword to a named variable to retrieve the maximum pixel value in the image. See Also QUERY_* Routines, READ_PPM, WRITE_PPM QUERY_SRF [Previous Routine] [Next Routine] [List of Routines] NAME: QUERY_SRF QUERY_SRF is a method of obtaining information about an SRF image file without having to read the file. See "QUERY_* Routines" on page 1063 for more information. This routine returns a long with the value of 1 if the query was successful (and the file type was correct) or 0 on failure. Syntax Result = QUERY_SRF (Filename [, Info] ) Arguments Filename A scalar string containing the pathname of the SRF file to query. Info Returns an anonymous structure containing information about the image in the file. The Info.TYPE field will return the value `SRF'. Note See "QUERY_* Routines" on page 1063 for detailed structure info. Keywords None See Also QUERY_* Routines, READ_SRF, WRITE_SRF QUERY_TIFF [Previous Routine] [Next Routine] [List of Routines] NAME: QUERY_TIFF QUERY_TIFF is a method of obtaining information about a TIFF image file without having to read the file. See "QUERY_* Routines" on page 1063 for more information. This routine returns a long with the value of 1 if the query was successful (and the file type was correct) or 0 on failure. Syntax Result = QUERY_TIFF ( Filename [, Info] [, IMAGE_INDEX=index] ) Arguments Filename A scalar string containing the pathname of the TIFF file to query. Info The Info argument to QUERY_TIFF returns an anonymous structure containing information about the image in the file. New Info structure fields have been added. See "New Returned Information for TIFF Queries" on page 45. Returns an anonymous structure containing information about the image in the file. The Info.TYPE field will return the value `TIFF'. Additional field in the Info structure: PLANAR_CONFIG. Note See "QUERY_* Routines" on page 1063 for detailed structure info. Keywords IMAGE_INDEX Image number index. If this value is larger than the number of images in the file, the function returns 0 (failure). Example This is an example of using QUERY_TIFF to write and read a multi-image TIFF file. The first image is a 16-bit, single channel image stored using compression. The second image is an RGB image stored using 32-bits/channel uncompressed. ; Write the image data: data = FIX(DIST(256)) rgbdata = LONARR(3,320,240) WRITE_TIFF,'multi.tif',data,COMPRESSION=1,/SHORT WRITE_TIFF,'multi.tif',rgbdata,/LONG,/APPEND ; Read the image data back: ok = QUERY_TIFF('multi.tif',s) IF (ok) THEN BEGIN FOR i=0,s.NUM_IMAGES-1 DO BEGIN imp = QUERY_TIFF('multi.tif',t,IMAGE_INDEX=i) img = READ_TIFF('multi.tif',IMAGE_INDEX=i) HELP,t,/STRUCTURE HELP,img ENDFOR ENDIF See Also QUERY_* Routines, READ_TIFF, WRITE_TIFF QUERY_WAV [Previous Routine] [Next Routine] [List of Routines] NAME: QUERY_WAV The QUERY_WAV function checks that the file is actually a .WAV file and that the READ_WAV function can read the data in the file. Optionally, it can return additional information about the data in the file. This function returns the value of 1 if the query was successful (and the file type was correct) or 0 on failure. Syntax Result = QUERY_WAV ( Filename[, Info] ) Arguments Filename A scalar string containing the full pathname of the .WAV file to read. Info An anonymous structure containing information about the data in the file. The fields are defined as: Tag Type Definition CHANNELS INT Number of data channels in the file. SAMPLES_PER_SEC LONG Data sampling rate in samples per second. BITS_PER_SAMPLE INT Number of valid bits in the data. Table 79: The Info Structure for Info Fields Keywords None. R_CORRELATE [Previous Routine] [Next Routine] [List of Routines] NAME: R_CORRELATE The R_CORRELATE function computes Spearman's (rho) or Kendalls's (tau) rank correlation of two sample populations X and Y. The result is a two-element vector containing the rank correlation coefficient and the two-sided significance of its deviation from zero. The significance is a value in the interval [0.0, 1.0]; a small value indicates a significant correlation. N ­ 1 (Rx i ­ Rx)(Ryi ­ Ry) rho i = 0 = ------------------------------------------- N ­ 1 N ­ 1 (Rx i ­ Rx)2 (Ry i ­ Ry)2 i = 0 i = 0 where Rxi and Ryi are the magnitude-based ranks among X and Y, respectively. Elements of identical magnitude are ranked using a rank equal to the mean of the ranks that would otherwise be assigned. This routine is written in the IDL language. Its source code can be found in the file r_correlate.pro in the lib subdirectory of the IDL distribution. Syntax Result = R_CORRELATE( X, Y [, D=variable] [, /KENDALL] [, PROBD=variable] [, ZD=variable] ) Arguments X An n-element integer, single-, or double-precision floating-point vector. Y An n-element integer, single-, or double-precision floating-point vector. Keywords D Set this keyword to a named variable that will contain the sum-squared difference of ranks. If the KENDALL keyword is set, this parameter is returned as zero. KENDALL Set this keyword to compute Kendalls's (tau) rank correlation. By default, Spearman's (rho) rank correlation is computed. PROBD Set this keyword to a named variable that will contain the two-sided significance level of ZD. If the KENDALL keyword is set, this parameter is returned as zero. ZD Set this keyword to a named variable that will contain the number of standard deviations by which D deviates from its null-hypothesis expected value. If the KENDALL keyword is set, this parameter is returned as zero. Example ; Define two n-element sample populations: X = [257, 208, 296, 324, 240, 246, 267, 311, 324, 323, 263, $ 305, 270, 260, 251, 275, 288, 242, 304, 267] Y = [201, 56, 185, 221, 165, 161, 182, 239, 278, 243, 197, $ 271, 214, 216, 175, 192, 208, 150, 281, 196] ; Compute Spearman's (rho) rank correlation of X and Y. result = R_CORRELATE(X, Y) PRINT, 'Spearman's (rho) rank correlation: ', result ; Compute Kendalls's (tau) rank correlation of X and Y: result = R_CORRELATE(X, Y, /KENDALL) PRINT, 'Kendalls's (tau) rank correlation: ', result IDL prints: Spearman's (rho) rank correlation: 0.835967 4.42899e-006 Kendalls's (tau) rank correlation: 0.624347 0.000118729 See Also A_CORRELATE, C_CORRELATE, CORRELATE, M_CORRELATE, P_CORRELATE R_TEST [Previous Routine] [Next Routine] [List of Routines] NAME: R_TEST The R_TEST function tests the hypothesis that a binary population (a sequence of 1s and 0s) represents a "random sampling". The result is a two-element vector containing the nearly-normal test statistic Z and its associated probability. This two- tailed test is based on the "theory of runs" and is often referred to as the "Runs Test for Randomness." This routine is written in the IDL language. Its source code can be found in the file r_test.pro in the lib subdirectory of the IDL distribution. Syntax Result = R_TEST( X [, N0=variable] [, N1=variable] [, R=variable] ) Arguments X An n-element integer, single-, or double-precision floating-point vector. Elements not equal to 0 or 1 are removed and the length of X is correspondingly reduced. Keywords N0 Set this keyword to a named variable that will contain the number of 0s in X. N1 Set this keyword to a named variable that will contain the number of 1s in X. R Set this keyword to a named variable that will contain the number of runs (clusters of 0s and 1s) in X. Example ; Define a binary population: X = [0, 1, 1, 0, 1, 0, 0, 0, 1, 0, 0, 1, 1, 0, 1, 0, 1, 0, 0, $ 1, 0, 1, 1, 0, 1, 0, 0, 1, 0, 1] ; Test the hypothesis that X represents a random sampling against ; the hypothesis that it does not represent a random sampling at ; the 0.05 significance level: result = R_TEST(X, R = r, N0 = n0, N1 = n1) PRINT, result IDL prints: [2.26487, 0.0117604] Print the values of the keyword parameters: PRINT, 'Runs: ', r & PRINT, 'Zeros: ', n0 & PRINT, 'Ones: ', n1 Runs: 22 Zeros: 16 Ones: 14 The computed probability (0.0117604) is less than the 0.05 significance level and therefore we reject the hypothesis that X represents a random sampling. The results show that there are too many runs, indicating a non-random cyclical pattern. See Also CTI_TEST, FV_TEST, KW_TEST, LNP_TEST, MD_TEST, RS_TEST, S_TEST, TM_TEST, XSQ_TEST RADON [Previous Routine] [Next Routine] [List of Routines] NAME: RADON The RADON function implements the Radon transform, used to detect features within a two-dimensional image. This function can be used to return either the Radon transform, which transforms lines through an image to points in the Radon domain, or the Radon backprojection, where each point in the Radon domain is transformed to a straight line in the image. Syntax Radon Transform: Result = RADON( Array [, /DOUBLE] [, DRHO=scalar] [, DX=scalar] [, DY=scalar] [, /GRAY] [, /LINEAR] [, NRHO=scalar] [, NTHETA=scalar] [, RHO=variable] [, RMIN=scalar] [, THETA=variable] [, XMIN=scalar] [, YMIN=scalar] ) Radon Backprojection: Result = RADON( Array, /BACKPROJECT, RHO=variable, THETA=variable [, /DOUBLE] [, DX=scalar] [, DY=scalar] [, /LINEAR] [, NX=scalar] [, NY=scalar] [, XMIN=scalar] [, YMIN=scalar] ) Return Value The result of this function is a two-dimensional floating-point array, or a complex array if the input image is complex. If Array is double-precision, or if the DOUBLE keyword is set, the result is double-precision, otherwise, the result is single-precision. Radon Transform Theory The Radon transform is used to detect features within an image. Given a function A(x, y), the Radon transform is defined as: R( , ) = A( cos ­s sin , sin + scos ) ds ­ This equation describes the integral along a line s through the image, where is the distance of the line from the origin and is the angle from the horizontal. Figure 17: The Radon Transform In medical imaging, each point R( , ) is called a ray-sum, while the resulting image is called a shadowgram. An image can be reconstructed from its ray-sums using the backprojection operator: B(x, y) = R( , xcos + ysin )d 0 where the output, B(x, y), is an image of A(x, y) blurred by the Radon transform. How IDL Implements the Radon Transform To avoid the use of a two-dimensional interpolation and decrease the interpolation errors, the Radon transform equation is rotated by , and the interpolation is then done along the line s. The transform is divided into two regions, one for nearly- horizontal lines (45 < < 135 ), and the other for steeper lines ( 45 ; 135 180 ), where is assumed to lie on the interval [0 ,180 ]. For nearest-neighbor interpolation (the default), the discrete transform formula for an image A(m, n) [m = 0, ..., M­1, n = 0, ..., N­1] is: x -------------- 2 sin A (m,[am + b]) sin > ------- R ( , ) m = y --------------- sin 2 cos A [(a'n + b'] n,) 2 n where brackets [ ] indicate rounding to the nearest integer, and the slope and offsets are given by: ­ x cos ­ y sin a x = ­ ------ cos ------------ min min y sin b = ------------------------------------------------------------ ysin ­ x cos ­ y sin a' 1 = --- min min a b' = ------------------------------------------------------------ xcos For linear interpolation, the transform is: x -------------- sin 2 > -- sin (1 ­ w ) A m ( , am + b ) + wA m ( , am + b + 1) 2 R( , ) m = y 2 --------------- sin ------- cos (1 ­ w)A ( a'n + b' n , ) + wA( a'n + b' + 1 n , ) 2 n where the slope and offsets are the same as above, and indicates flooring to the nearest lower integer. The weighting w is given by the difference between am + b and its floored value, or between a'n + b' and its floored value. How IDL Implements the Radon Backprojection For the backprojection transform, the discrete formula for nearest-neighbor interpolation is: B(m,n) = R (t [, ]) t with the nearest-neighbor for given by: {(m x + x ­ = min ) cos t + (n y + ymin) sin t­ min} 1 For backprojection with linear interpolation: B(m n , ) = (1 ­ w) R( t, ) + wR( t, + 1) t w = ­ and is the same as in the nearest-neighbor. Arguments Array The two-dimensional array of size M by N to be transformed. Keywords BACKPROJECT If set, the backprojection is computed, otherwise, the forward transform is computed. Note The Radon backprojection does not return the original image. Instead, it returns an image blurred by the Radon transform. Because the Radon transform is not one-to- one, multiple (x, y) points are mapped to a single ( , ). DOUBLE Set this keyword to force the computation to be done using double-precision arithmetic. DRHO Set this keyword equal to a scalar specifying the spacing between coordinates, expressed in the same units as Array. The default is one-half of the diagonal distance between pixels, 0.5[(DX2 + DY2 )]1/2 . Smaller values produce finer resolution, and are useful for zooming in on interesting features. Larger values may result in undersampling, and are not recommended. If BACKPROJECT is specified, this keyword is ignored. DX Set this keyword equal to a scalar specifying the spacing between the horizontal (x) coordinates. The default is 1.0. DY Set this keyword equal to a scalar specifying the spacing between the vertical (y) coordinates. The default is 1.0. GRAY Set or omit this keyword to perform a weighted Radon transform, with the weighting given by the pixel values. If GRAY is explicitly set to zero, the image is treated as a binary image with all nonzero pixels considered as 1. LINEAR Set this keyword to use linear interpolation rather than the default nearest-neighbor sampling. Results are more accurate but slower when linear interpolation is used. NRHO Set this keyword equal to a scalar specifying the number of coordinates to use. The default is 2 CEIL([MAX(x2 + y2 )]1/2 / DRHO) + 1. If BACKPROJECT is specified, this keyword is ignored. NTHETA Set this keyword equal to a scalar specifying the number of coordinates to use over the interval [0, ]. The default is CEIL( [(M2 + N2)/2]1/2 ). Larger values produce smoother results, and are useful for filtering before backprojection. Smaller values result in broken lines in the transform, and are not recommended. If BACKPROJECT is specified, this keyword is ignored. NX If BACKPROJECT is specified, set this keyword equal to a scalar specifying the number of horizontal coordinates in the output Result. The default is FLOOR(2 MAX(|RHO|)(DX2 + DY2 )-1/2 + 1). For the forward transform this keyword is ignored. NY If BACKPROJECT is specified, set this keyword equal to a scalar specifying the number of vertical coordinates in the output Result. The default is FLOOR(2 MAX(|RHO|)(DX2 + DY2 )-1/2 + 1). For the forward transform, this keyword is ignored. RHO For the forward transform, set this keyword to a named variable that will contain the radial ( ) coordinates. If BACKPROJECT is specified, this keyword must contain the coordinates of the input Array. The coordinates should be evenly spaced and in increasing order. RMIN Set this keyword equal to a scalar specifying the minimum coordinate to use for the forward transform. The default is ­0.5(NRHO ­ 1) DRHO. If BACKPROJECT is specified, this keyword is ignored. THETA For the forward transform, set this keyword to a named variable containing a vector of angular ( ) coordinates to use for the transform. If NTHETA is specified instead, and THETA is set to a named variable, on exit THETA will contain the coordinates. If BACKPROJECT is specified, this keyword must contain the coordinates of the input Array. XMIN Set this keyword equal to a scalar specifying the x-coordinate of the lower-left corner of the input Array. The default is ­ (M­1)/2, where Array is an M by N array. If BACKPROJECT is specified, set this keyword equal to a scalar specifying the x- coordinate of the lower-left corner of the Result. In this case the default is ­DX (NX­1)/2. YMIN Set this keyword equal to a scalar specifying the y-coordinate of the lower-left corner of the input Array. The default is ­ (N­1)/2, where Array is an M by N array. If BACKPROJECT is specified, set this keyword equal to a scalar specifying the y- coordinate of the lower-left corner of the Result. In this case, the default is ­DY (NY­1)/2. Example This example displays the Radon transform and the Radon backprojection: PRO radon_example DEVICE, DECOMPOSED=0 ;Create an image with a ring plus random noise: x = (LINDGEN(128,128) MOD 128) - 63.5 y = (LINDGEN(128,128)/128) - 63.5 radius = SQRT(x^2 + y^2) array = (radius GT 40) AND (radius LT 50) array = array + RANDOMU(seed,128,128) ;Create display window, set graphics properties: WINDOW, XSIZE=440,YSIZE=700, TITLE='Radon Example' !P.BACKGROUND = 255 ; white !P.COLOR = 0 ; black !P.FONT=2 ERASE XYOUTS, .05, .94, 'Ring and Random Pixels', /NORMAL ;Display the image. 255b changes black values to white: TVSCL, 255b - array, .05, .75, /NORMAL ;Calculate and display the Radon transform: XYOUTS, .05, .70, 'Radon Transform', /NORMAL result = RADON(array, RHO=rho, THETA=theta) TVSCL, 255b - result, .08, .32, /NORMAL PLOT, theta, rho, /NODATA, /NOERASE, $ POSITION=[0.08,0.32, 1, 0.68], $ XSTYLE=9,YSTYLE=9,XTITLE='Theta', YTITLE='R' ;For simplicity in this example, remove everything except ;the two stripes. A better (and more complicated) method would ;be to choose a threshold for the result at each value of theta, ;perhaps based on the average of the result over the theta ;dimension. result[*,0:55] = 0 result[*,73:181] = 0 result[*,199:*] = 0 ;Find the Radon backprojection and display the output: XYOUTS, .05, .26, 'Radon Backprojection', /NORMAL backproject = RADON(result, /BACKPROJECT, RHO=rho, THETA=theta) TVSCL, 255b - backproject, .05, .07, /NORMAL END The following figure displays the program output. The top image is an image of a ring and random pixels, or noise. The center image is the Radon transform, and displays the line integrals through the image. The bottom image is the Radon backprojection, after filtering all noise except for the two strong horizontal stripes in the middle image. Figure 18: Radon Example - Original image (top), Radon transform (center), and backprojection of the altered Radon transform (bottom). References 1. Herman, Gabor T. Image Reconstruction from Projections. New York: Academic Press, 1980. 2. Hiriyannaiah, H. P. X-ray computed tomography for medical imaging. IEEE Signal Processing Magazine, March 1997: 42-58. 3. Jain, Anil K. Fundamentals of Digital Image Processing. Englewood Cliffs, NJ: Prentice-Hall, 1989. 4. Toft, Peter. The Radon Transform: Theory and Implementation. Denmark: Technical University; 1996. Ph.D. Thesis. See Also HOUGH, VOXEL_PROJ RANDOMN [Previous Routine] [Next Routine] [List of Routines] NAME: RANDOMN The RANDOMN function returns one or more normally-distributed, floating-point, pseudo-random numbers with a mean of zero and a standard deviation of one. RANDOMN uses the Box-Muller method for generating normally-distributed (Gaussian) random numbers. Syntax Result = RANDOMN( Seed [, D1, ..., D8] [ [, BINOMIAL=[trials, probability]] [, /DOUBLE] [, GAMMA=integer{>0}] [, /NORMAL] [, POISSON=value] [, /UNIFORM] | [, /LONG] ] ) Arguments Seed A variable or constant used to initialize the random sequence on input, and in which the state of the random number generator is saved on output. The state of the random number generator is contained in a long integer vector. This state is saved in the Seed argument when the argument is a named variable. To continue the pseudo-random number sequence, input the variable containing the saved state as the Seed argument in the next call to RANDOMN or RANDOMU. Each independent random number sequence should maintain its own state variable. To maintain a state over repeated calls to a procedure, the seed variable may be stored in a COMMON block. In addition to states maintained by the user in variables, the RANDOMU and RANDOMN functions contain a single shared generic state that is used if a named variable is not supplied as the Seed argument or the named variable supplied is undefined. The generic state is initialized once using the time-of-day, and may be re- initialized by providing a Seed argument that is a constant or expression. If the Seed argument is: * an undefined variable - the generic state is used and the resulting generic state array is stored in the variable. * a named variable that contains a longword array of the proper length - it is used to continue the pseudo-random sequence, and is updated. * a named variable containing a scalar - the scalar value is used to start a new sequence and the resulting state array is stored back in the variable. * a constant or expression - the value is used to re-initialize the generic state. Note RANDOMN and RANDOMU use the same sequence. Starting or restarting the sequence for one starts or restarts the sequence for the other. Some IDL routines use the random number generator, so using them will initialize the seed sequence. An example of such a routine is CLUST_WTS. Note Do not alter the seed value returned by this function. The only valid use for the seed argument is to pass it back to a subsequent call. Changing the value of the seed will corrupt the random sequence. Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. The dimensions of the result. The dimension parameters can be any scalar expression. Up to eight dimensions can be specified. If no dimensions are specified, RANDOMN returns a scalar result Keywords The formulas for the binomial, gamma, and Poisson distributions are from section 7.3 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press. BINOMIAL Set this keyword to a 2-element array, [n, p], to generate random deviates from a binomial distribution. If an event occurs with probability p, with n trials, then the number of times it occurs has a binomial distribution. Note For n > 1.0 × 107, you should set the DOUBLE keyword. DOUBLE Set this keyword to force the computation to be done using double-precision arithmetic. Note RANDOMN constructs double-precision uniform random deviates using the formula: Y (i1 ­ 1) imax + i2 = ---------------------- imax2 + 1 where i1 and i2 are integer random deviates in the range [1...imax], and imax = 231 ­ 2 is the largest possible integer random deviate. The Y values will be in the range 0 < Y < 1. GAMMA Set this keyword to an integer order i > 0 to generate random deviates from a gamma distribution. The gamma distribution is the waiting time to the ith event in a Poisson random process of unit mean. A gamma distribution of order equal to 1 is the same as the exponential distribution. Note For GAMMA > 1.0 × 107, you should set the DOUBLE keyword. LONG Set this keyword to return integer uniform random deviates in the range [1...231 ­ 2]. If LONG is set, all other keywords are ignored. NORMAL Set this keyword to generate random deviates from a normal distribution. POISSON Set this keyword to the mean number of events occurring during a unit of time. The POISSON keyword returns a random deviate drawn from a Poisson distribution with that mean. Note For POISSON > 1.0 × 107, you should set the DOUBLE keyword. UNIFORM Set this keyword to generate random deviates from a uniform distribution. Examples If you start the sequence with an undefined variable-if RANDOMN has already been called, Seed is no longer undefined-IDL initializes the sequence with the system time: ; Generate one random variable and initialize the sequence with an ; undefined variable: randomValue = RANDOMN(seed) The new state is saved in seed. To generate repeatable experiments, begin the sequence with a particular seed: seed_value = 5L ; Generate one random variable and initialize the sequence with 5: randomValue = RANDOMN(seed_value) PRINT, randomValue IDL prints: 0.521414 To restart the sequence with a particular seed, re-initialize the variable: seed = 5L ;Get a normal random number, and restart the sequence with a seed ;of 5. randomValue = RANDOMN(seed) PRINT, randomValue IDL prints: 0.521414 To continue the same sequence: PRINT, RANDOMN(seed) IDL prints: -0.945489 To create a 10 by 10 array of normally-distributed, random numbers, type: R = RANDOMN(seed, 10, 10) Since seed is undefined, the generic state is used to initialize the random number generator. Print the resulting values by entering: PRINT, R A more interesting example plots the probability function of 2000 numbers returned by RANDOMN. Type: PLOT, HISTOGRAM(RANDOMN(SEED, 2000), BINSIZE=0.1) To obtain a sequence of 1000 exponential (gamma distribution, order 1) deviates, type: Result = RANDOMN(seed, 1000, GAMMA=1) Intuitively, the result contains a random series of waiting times for events occurring an average of one per time period. To obtain a series of 1000 random elapsed times required for the arrival of two events, type: ;Returns a series of 1000 random elapsed times required for the ;arrival of two events. Result = RANDOMN(seed, 1000, GAMMA=2) To obtain a 128 x 128 array filled with Poisson deviates, with a mean of 1.5, type: Result = RANDOMN(seed, 128, 128, POISSON=1.5) To simulate the count of "heads" obtained when flipping a coin 10 times, type: Result = RANDOMN(seed, BINOMIAL=[10,.5]) See Also RANDOMU RANDOMU [Previous Routine] [Next Routine] [List of Routines] NAME: RANDOMU The RANDOMU function returns one or more uniformly-distributed, floating-point, pseudo-random numbers in the range 0 < Y <1.0. The random number generator is taken from: "Random Number Generators: Good Ones are Hard to Find", Park and Miller, Communications of the ACM, Oct 1988, Vol 31, No. 10, p. 1192. To remove low-order serial correlations, a Bays-Durham shuffle is added, resulting in a random number generator similar to ran1() in Section 7.1 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press. Syntax Result = RANDOMU( Seed [, D1, ..., D8] [ [, BINOMIAL=[trials, probability]] [, /DOUBLE] [, GAMMA=integer{>0}] [, /NORMAL] [, POISSON=value] [, /UNIFORM] | [, /LONG] ] ) Arguments Seed A variable or constant used to initialize the random sequence on input, and in which the state of the random number generator is saved on output. The state of the random number generator is contained in a long integer vector. This state is saved in the Seed argument when the argument is a named variable. To continue the pseudo-random number sequence, input the variable containing the saved state as the Seed argument in the next call to RANDOMN or RANDOMU. Each independent random number sequence should maintain its own state variable. To maintain a state over repeated calls to a procedure, the seed variable may be stored in a COMMON block. In addition to states maintained by the user in variables, the RANDOMU and RANDOMN functions contain a single shared generic state that is used if a named variable is not supplied as the Seed argument or the named variable supplied is undefined. The generic state is initialized once using the time-of-day, and may be re- initialized by providing a Seed argument that is a constant or expression. If the Seed argument is: * an undefined variable - the generic state is used and the resulting generic state array is stored in the variable. * a named variable that contains a longword array of the proper length - it is used to continue the pseudo-random sequence, and is updated. * a named variable containing a scalar - the scalar value is used to start a new sequence and the resulting state array is stored back in the variable. * a constant or expression - the value is used to re-initialize the generic state. Note RANDOMN and RANDOMU use the same sequence, so starting or restarting the sequence for one starts or restarts the sequence for the other. Some IDL routines use the random number generator, so using them will initialize the seed sequence. An example of such a routine is CLUST_WTS. Note Do not alter the seed value returned by this function. The only valid use for the seed argument is to pass it back to a subsequent call. Changing the value of the seed will corrupt the random sequence. Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. The dimensions of the result. The dimension parameters can be any scalar expression. Up to eight dimensions can be specified. If no dimensions are specified, RANDOMU returns a scalar result. Keywords The formulas for the binomial, gamma, and Poisson distributions are from Section 7.3 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press. BINOMIAL Set this keyword to a 2-element array, [n, p], to generate random deviates from a binomial distribution. If an event occurs with probability p, with n trials, then the number of times it occurs has a binomial distribution. Note For n > 1.0 × 107, you should set the DOUBLE keyword. DOUBLE Set this keyword to force the computation to be done using double-precision arithmetic. Note RANDOMU constructs double-precision uniform random deviates using the formula: Y (i1 ­ 1) imax + i2 = ---------------------- imax2 + 1 where i1 and i2 are integer random deviates in the range [1...imax], and imax = 231 ­ 2 is the largest possible integer random deviate. The Y values will be in the range 0 < Y < 1. GAMMA Set this keyword to an integer order i > 0 to generate random deviates from a gamma distribution. The gamma distribution is the waiting time to the ith event in a Poisson random process of unit mean. A gamma distribution of order equal to 1 is the same as the exponential distribution. Note For GAMMA > 1.0 × 107, you should set the DOUBLE keyword. LONG Set this keyword to return integer uniform random deviates in the range [1...231 ­ 2]. If LONG is set, all other keywords are ignored. NORMAL Set this keyword to generate random deviates from a normal distribution. POISSON Set this keyword to the mean number of events occurring during a unit of time. The POISSON keyword returns a random deviate drawn from a Poisson distribution with that mean. Note For POISSON > 1.0 × 107, you should set the DOUBLE keyword. UNIFORM Set this keyword to generate random deviates from a uniform distribution. Example This example simulates rolling two dice 10,000 times and plots the distribution of the total using RANDOMU. Enter: PLOT, HISTOGRAM(FIX(6 * RANDOMU(S, 10000)) + $ FIX(6 * RANDOMU(S, 10000)) + 2) In the above statement, the expression RANDOMU(S, 10000) is a 10,000-element, floating-point array of random numbers greater than or equal to 0 and less than 1. Multiplying this array by 6 converts the range to 0 Y < 6. Applying the FIX function yields a 10,000-point integer vector with values from 0 to 5, one less than the numbers on one die. This computation is done twice, once for each die, then 2 is added to obtain a vector from 2 to 12, the total of two dice. The HISTOGRAM function makes a vector in which each element contains the number of occurrences of dice rolls whose total is equal to the subscript of the element. Finally, this vector is plotted by the PLOT procedure. An example of reusing a state vector to generate a repeatable sequence: ; Init seed for a repeatable sequence: seed = 1001L ; Print 1st 5 numbers of sequence: print,randomu(seed,5) IDL prints: 0.705884 0.285924 0.231151 0.715447 0.532836 Reuse a state vector: ; Re-init seed to same sequence: seed = 1001L ; Get 5 number of sequence with 5 calls: for i=0,4 do print, randomu(seed) IDL prints: 0.705884 0.285924 0.231151 0.715447 0.532836 See Also RANDOMN RANKS [Previous Routine] [Next Routine] [List of Routines] NAME: RANKS The RANKS function computes the magnitude-based ranks of a sample population X. Elements of identical magnitude "ties" are ranked according to the mean of the ranks that would otherwise be assigned. The result is a vector of ranks equal in length to X. This routine is written in the IDL language. Its source code can be found in the file ranks.pro in the lib subdirectory of the IDL distribution. Syntax Result = RANKS(X) Arguments X An n-element integer, single-, or double-precision floating-point vector. The elements of this vector must be in ascending order based on their magnitude. Example ; Define an n-element sample population: X = [-0.8, 0.1, -2.3, -0.6, 0.2, 1.1, -0.3, 0.6, -0.2, 1.1, $ -0.7, -0.2, 0.6, 0.4, -0.1, 1.1, -0.3, 0.3, -1.3, 1.1] ; Allocate a two-column, n-row array to store the results: array = FLTARR(2, N_ELEMENTS(X)) ; Sort the sample population and store in the 0th column of ARRAY: array[0, *] = X[SORT(X)] ; Compute the ranks of the sorted sample population and store in ; the 1st column of ARRAY: array[1, *] = RANKS(X[SORT(X)]) ; Display the sorted sample population and corresponding ranks ; with a two-decimal format: PRINT, array, FORMAT = '(2(5x, f5.2))' IDL prints: -2.30 1.00 -1.30 2.00 -0.80 3.00 -0.70 4.00 -0.60 5.00 -0.30 6.50 -0.30 6.50 -0.20 8.50 -0.20 8.50 -0.10 10.00 0.10 11.00 0.20 12.00 0.30 13.00 0.40 14.00 0.60 15.50 0.60 15.50 1.10 18.50 1.10 18.50 1.10 18.50 1.10 18.50 See Also R_CORRELATE RDPIX [Previous Routine] [Next Routine] [List of Routines] NAME: RDPIX The RDPIX procedure interactively displays the X position, Y position, and pixel value at the cursor. This routine is written in the IDL language. Its source code can be found in the file rdpix.pro in the lib subdirectory of the IDL distribution. Using RDPIX RDPIX displays a stream of X, Y, and pixel values when the mouse cursor is moved over a graphics window. Press the left or center mouse button to create a new line of output. Press the right mouse button to exit the procedure. Syntax RDPIX, Image [, X0, Y0] Arguments Image The array that contains the image being displayed. This array may be of any type. Rather than reading pixel values from the display, values are taken from this parameter, avoiding scaling difficulties. X0, Y0 The location of the lower-left corner of the image area on screen. If these parameters are not supplied, they are assumed to be zero. See Also CURSOR, TVRD READ/READF [Previous Routine] [Next Routine] [List of Routines] NAME: READ/READF The READ procedures perform formatted input into variables. READ performs input from the standard input stream (IDL file unit 0), while READF requires a file unit to be explicitly specified. Syntax READ, [Prompt,] Var1, ..., Varn READF, [Prompt,] Unit, Var1, ..., Varn Keywords: [, AM_PM=[string, string]] [, DAYS_OF_WEEK=string_array{7 names}] [, FORMAT=value] [, MONTHS=string_array{12 names}] [, PROMPT=string] VMS Keywords: [, KEY_ID=value] [, KEY_MATCH=relation] [, KEY_VALUE=value] Arguments Prompt Note that the PROMPT keyword should be used instead of the Prompt argument for compatibility with window-based versions of IDL. A string or explicit expression (i.e, not a named variable) to be used as a prompt. This argument should not be included if the FORMAT keyword is specified. Also, if this argument begins with the characters "$(", it is taken to be a format specification as described below under "Format Compatibility". Using the Prompt argument does not work well with IDL for Windows and IDL for Macintosh. The desired prompt string is written to the log window instead of the command input window. To create custom prompts compatible with these versions of IDL, use the PROMPT keyword, described below. Unit For READF, Unit specifies the file unit from which the input is taken. Vari The named variables to receive the input. Note If the variable specified for the Vari argument has not been previously defined, the input data is assumed to be of type float, and the variable will be cast as a float. Keywords AM_PM Supplies a string array of two names to be used for the names of the AM and PM string when processing explicitly formatted dates (CAPA, CApA, and CapA format codes) with the FORMAT keyword. DAYS_OF_WEEK Supplies a string array of 7 names to be used for the names of the days of the week when processing explicitly formatted dates (CDWA, CDwA, and CdwA format codes) with the FORMAT keyword. FORMAT If FORMAT is not specified, IDL uses its default rules for formatting the input. FORMAT allows the format of the input to be specified in precise detail, using a FORTRAN-style specification. See "Using Explicitly Formatted Input/Output" in Chapter 8 of Building IDL Applications. MONTHS Supplies a string array of 12 names to be used for the names of the months when processing explicitly formatted dates (CMOA, CMoA, and CmoA format codes) with the FORMAT keyword. PROMPT Set this keyword to a scalar string to be used as a customized prompt for the READ command. If the PROMPT keyword or Prompt argument is not supplied, IDL uses a colon followed by a space (": ") as the input prompt. VMS Keywords Note also that the obsolete VMS-only routine READ_KEY has been replaced by the keywords below. KEY_ID The index key to be used (primary = 0, first alternate key = 1, etc...) when accessing data from a file with indexed organization. If this keyword is omitted, the primary key is used. KEY_MATCH The relation to be used when matching the supplied key with key field values (EQ = 0, GE = 1, GT = 2) when accessing data from a file with indexed organization. If this keyword is omitted, the equality relation (0) is used. KEY_VALUE The value of a key to be found when accessing data from a file with indexed organization. This value must match the key definition that is determined when the file was created in terms of type and size-no conversions are performed. If this keyword is omitted, the next sequential record is used. Format Compatibility If the FORMAT keyword is not present and READ is called with more than one argument, and the first argument is a scalar string starting with the characters "$(", this initial argument is taken to be the format specification, just as if it had been specified via the FORMAT keyword. This feature is maintained for compatibility with version 1 of VMS IDL. Example To read a string value into the variable B from the keyboard, enter: ; Define B as a string before reading: B = '' ; Read input from the terminal: READ, B, PROMPT='Enter Name: ' To read formatted data from the previously-opened file associated with logical unit number 7 into variable C, use the command: READF, 7, C See Also READS, READU, WRITEU READ_ASCII [Previous Routine] [Next Routine] [List of Routines] NAME: READ_ASCII The READ_ASCII function reads data from an ASCII file into an IDL structure variable. READ_ASCII may be used with templates created by the ASCII_TEMPLATE function. This routine handles ASCII files consisting of an optional header of a fixed number of lines, followed by columnar data. One or more rows of data constitute a record. Each data element within a record is considered to be in a different column, or field. The data in one field must be of, or promotable to, a single type (e.g., FLOAT). Adjacent fields may be collected into multi-column fields, called groups. Files may also contain comments, which exist between a user-specified comment string and the corresponding end-of-line. READ_ASCII is designed to be used with templates created by the ASCII template function. This routine is written in the IDL language. Its source code can be found in the file read_ascii.pro in the lib subdirectory of the IDL distribution. Syntax Result = READ_ASCII( [Filename] [, COMMENT_SYMBOL=string] [, COUNT=variable] [, DATA_START=lines_to_skip] [, DELIMITER=string] [, HEADER=variable] [, MISSING_VALUE=value] [, NUM_RECORDS=value] [, RECORD_START=index] [, TEMPLATE=value] [, /VERBOSE] ) Arguments Filename A string containing the name of an ASCII file to read into an IDL variable. If filename is not specified, a dialog allows the user to choose a file. Keywords You can define the attributes of a field in two ways. If you use a template, you can either use a previously generated template, or create a template with ASCII_TEMPLATE. You can use COMMENT_SYMBOL, DATA_START, DELIMITER, or MISSING_VALUE to either override template attributes or to provide one-time attributes for the file to be read, without a template. COMMENT_SYMBOL Set this keyword to a string that identifies the character used to delineate comments in the ASCII file to be read. When READ_ASCII encounters the comment character, it discards data from that point until it reaches the end of the current line, identifying the rest of the line as a comment. The default character the null string, `', specifying that no comments will be recognized. COUNT Set this keyword equal to a named variable that will contain the number of records read. DATA_START Set this keyword equal to the number of header lines you want to skip. The default value is 0 if no template is specified. DELIMITER Set this keyword to a string that identifies the end of a field. If no delimiter is specified, READ_ASCII uses information provided by the template in use. The default is a space, ` ', specifying that an empty element constitutes the end of a field. HEADER Set this keyword equal to a named variable that will contain the header in a string array of length DATA_START. If no header exists, an empty string is returned. MISSING_VALUE Set this keyword equal to a value used to replace any missing or invalid data. The default value, if no template is supplied, is !VALUES.F_NAN. See "!VALUES" on page 2423 for details. NUM_RECORDS Set this keyword equal to the number of records to read. The default is to read up to and including the last record. RECORD_START Set this keyword equal to the index of the first record to read. The default is the first record of the file (record 0). TEMPLATE Use this keyword to specify the ASCII file template (generated by the function ASCII_TEMPLATE), that defines attributes of the file to be read. Specific attributes of the template may be overridden by the following keywords: COMMENT_SYMBOL, DATA_START, DELIMITER, MISSING_VALUE. VERBOSE Set this keyword to print runtime messages. Examples To read ASCII data using default file attributes, except for setting the number of skipped header lines to 10, type: data = READ_ASCII(file, DATA_START=10) To use a template to define file attributes, overriding the number of skipped header lines defined in the template, type: data = READ_ASCII(file, TEMPLATE=template, DATA_START=10) To use the ASCII_TEMPLATE GUI to generate a template within the function, type: data = READ_ASCII(myfile, TEM See Also ASCII_TEMPLATE READ_BINARY [Previous Routine] [Next Routine] [List of Routines] NAME: READ_BINARY The READ_BINARY function reads the contents of a binary file using a passed template or basic command line keywords. The result is an array or anonymous structure containing all of the entities read from the file. Data is read from the given filename or from the current file position in the open file pointed to by FileUnit. If no template is provided, keywords can be used to read a single IDL array of data. Note The READ_BINARY function does not work on VMS platforms due to limitations in the POINT_LUN procedure. For more information, see POINT_LUN. Syntax Result = READ_BINARY ([Filename] | FileUnit [, TEMPLATE=template] | [[, DATA_START=value] [, DATA_TYPE=typecodes] [, DATA_DIMS=array] [, ENDIAN=string]] ) Arguments Filename A scalar string containing the name of the binary file to read. If filename and file unit are not specified, a dialog allows the user to choose a file. FileUnit A scalar containing an open IDL file unit number to read from. Keywords DATA_DIMS Set this keyword to a scalar or array of up to eight elements specifying the size of the data to be read and returned. For example, DATA_DIMS=[512,512] specifies that a two-dimensional, 512 by 512 array be read and returned. DATA_DIMS=0 specifies that a single, scalar value be read and returned. Default is -1, which, if a TEMPLATE is not supplied that specifies otherwise, indicates that READ_BINARY will read to end-of-file and store the result in a 1D array. DATA_START Set this keyword to specify where to begin reading in a file. This value is as an offset, in bytes, that will be applied to the initial position in the file. Default is 0. DATA_TYPE Set this keyword to an IDL typecode of the data to be read. See documentation for the SIZE function for a listing of typecodes. Default is 1 (IDL's BYTE typecode). ENDIAN Set this keyword to one of three string values: `big", "little" or "native" which specifies the byte ordering of the file to be read. If the computer running READ_BINARY uses byte ordering that is different than that of the file, READ_BINARY will swap the order of bytes in multi-byte data types read from the file. (Default: "native" = perform no byte swapping.) TEMPLATE Set this keyword to a template structure describing the file to be read. A template can be created using BINARY_TEMPLATE. The TEMPLATE keyword cannot be used simultaneously with keywords DATA_START, DATA_TYPE, DATA_DIMS, or ENDIAN. When a template is used with READ_BINARY, the result of a successful call to READ_BINARY is a structure containing fields specified by the template. If a template is not used with READ_BINARY, the result of a successful call to READ_BINARY is an array. READ_BMP [Previous Routine] [Next Routine] [List of Routines] NAME: READ_BMP The READ_BMP function reads a Microsoft Windows Version 3 device independent bitmap file (.BMP) and returns a byte array containing the image. Dimensions are taken from the BITMAPINFOHEADER of the file. In the case of 4-bit or 8-bit images, the dimensions of the resulting array are (biWidth, biHeight). For 24-bit images, the dimensions are (3, biWidth, biHeight). Color interleaving is blue, green, red; i.e., Result[0,i,j] = blue, Result[1,i,j] = green, etc. READ_BMP does not handle 1-bit-deep images or compressed images, and is not fast for 4-bit images. The algorithm works best on images where the number of bytes in each scan-line is evenly divisible by 4. This routine is written in the IDL language. Its source code can be found in the file read_bmp.pro in the lib subdirectory of the IDL distribution. Note To find information about a potential BMP file before trying to read its data, use the QUERY_BMP function. Syntax Result = READ_BMP( Filename, [, R, G, B] [, Ihdr] [, /RGB] ) Arguments Filename A scalar string specifying the full path name of the bitmap file to read. R, G, B Named variables that will contain the color tables from the file. There 16 elements each for 4 bit images, 256 elements each for 8 bit images. Color tables are not defined or used for 24 bit images. Ihdr A named variable that will contain a structure holding the BITMAPINFOHEADER from the file. Tag names are as defined in the MS Windows Programmer's Reference Manual, Chapter 7. Keywords RGB If this keyword is set, color interleaving of 16- and 24-bit images will be R, G, B, i.e., Result[0,i,j] = red, Result[1,i,j] = green, Result[2,i,j] = blue. Example To open, read, and display the BMP file named foo.bmp in the current directory and store the color vectors in the variables R, G, and B, enter: ; Read and display an image: TV, READ_BMP('foo.bmp', R, G, B) ; Load its colors: TVLCT, R, G, B Many applications that use 24-bit BMP files outside IDL expect BMP files to be stored as BGR. For example, enter the following commands. ; Make a red square image: a = BYTARR(3, 200, 200) a[0, *, *] = 255 ;View the image: TV, a, /TRUE WRITE_BMP, 'foo.bmp', a If you open the .bmp file in certain bitmap editors, you may find that the square is blue. image = READ_BMP('foo.bmp') ; IDL reads the image back in and interprets it as red: TV, image, /TRUE ; Flip the order of the indices by adding the RGB keyword: image = READ_BMP('foo.bmp', /RGB) ; Displays the image in blue: TV, image, /TRUE See Also WRITE_BMP, QUERY_BMP READ_DICOM [Previous Routine] [Next Routine] [List of Routines] NAME: READ_DICOM The READ_DICOM function reads an image from a DICOM file along with any associated color table. The return value can be a 2D array for grayscale or a 3D array for TrueColor images. TrueColor images are always returned in pixel interleave format. The return array type depends on the DICOM image pixel type. This routine is written in the IDL language. Its source code can be found in the file read_dicom.pro in the lib subdirectory of the IDL distribution. Syntax Result = READ_DICOM (Filename [, Red, Green, Blue] [, IMAGE_INDEX=index]) Arguments Filename This argument is a scalar string that contains the full pathname of the file to read. Red, Green, Blue Named variables that will contain the red, green, and blue color vectors from the DICOM file if they exist. Note DICOM color vectors contain 16- bit color values that may need to be converted for use with IDL graphics routines. Keywords IMAGE_INDEX Set this keyword to the index of the image to read from the file. Example TVSCL,READ_DICOM(FILEPATH('mr_knee.dcm',$ SUBDIR=['examples','data'])) See Also QUERY_DICOM READ_IMAGE [Previous Routine] [Next Routine] [List of Routines] NAME: READ_IMAGE The READ_IMAGE function reads the image contents of a file and returns the image in an IDL variable. If the image contains a palette it can be returned as well in three IDL variables. READ_IMAGE returns the image in the form of a two-dimensional array (for grayscale images) or a (3, n, m) array (for TrueColor images). READ_IMAGE can read most types of image files supported by IDL. See QUERY_IMAGE for a list of supported formats. Syntax Result = READ_IMAGE (Filename [, Red, Green, Blue] [, IMAGE_INDEX=index] ) Return Value Result is the image array read from the file or scalar value of -1 if the file could not be read. Arguments Filename A scalar string containing the name of the file to read. Red An optional named variable to receive the red channel of the color table if a color table exists. Green An optional named variable to receive the green channel of the color table if a color table exists. Blue An optional named variable to receive the blue channel of the color table if a color table exists. Keywords IMAGE_INDEX Set this keyword to the index of the image to read from the file. The default is 0, the first image. READ_INTERFILE [Previous Routine] [Next Routine] [List of Routines] NAME: READ_INTERFILE The READ_INTERFILE procedure reads image data stored in Interfile (v3.3) format and returns a 3D array. READ_INTERFILE can only read a series of images if all images have the same height and width. It does not get additional keyword information beyond what is needed to read the image data. If any problems occur when reading the file, READ_INTERFILE prints a message and stops. If the data is stored on a bigendian machine and read on a littleendian machine (or vice versa) the order of bytes in each pixel element may be reversed, requiring a call to BYTEORDER This routine is written in the IDL language. Its source code can be found in the file read_interfile.pro in the lib subdirectory of the IDL distribution. Syntax READ_INTERFILE, File, Data Arguments File A scalar string containing the name of the Interfile to read. Note: if the Interfile has a header file and a data file, this should be the name of the header file (also called the administrative file). Data A named variable that will contain a 3D array of data as read from the file. Assumed to be a series of 2D images. Example READ_INTERFILE, '0_11.hdr', X READ_JPEG [Previous Routine] [Next Routine] [List of Routines] NAME: READ_JPEG The READ_JPEG procedure reads JPEG (Joint Photographic Experts Group) format compressed images from files or memory. JPEG is a standardized compression method for full-color and gray-scale images. This procedure reads JFIF, the JPEG File Interchange Format, including those produced by WRITE_JPEG. Such files are usually simply called JPEG files READ_JPEG can optionally quantize TrueColor images contained in files to a pseudo-color palette with a specified number of colors, and with optional color dithering. This procedure is based in part on the work of the Independent JPEG Group. For a brief explanation of JPEG, see "WRITE_JPEG" on page 1669. Note All JPEG files consist of byte data. Input data is converted to bytes before being written to a JPEG file. Note To find information about a potential JPEG file before trying to read its data, use the QUERY_JPEG function. Syntax READ_JPEG [, Filename | , UNIT=lun] , Image [, Colortable] [, BUFFER=variable] [, COLORS=value{8 to 256}] [, DITHER={0 | 1 | 2}] [, /GRAYSCALE] [, /ORDER] [, TRUE={1 | 2 | 3}] [, /TWO_PASS_QUANTIZE ] Arguments Filename A scalar string specifying the full pathname of the JFIF format (JPEG) file to be read. If this parameter is not present, the UNIT and/or the BUFFER keywords must be specified. Image A named variable to contain the image data read from the file. Colortable A named variable to contain the colormap, when reading a TrueColor image that is to be quantized. On completion, this variable contains a byte array with dimensions (NCOLORS, 3). This argument is filled only if the image is color quantized (refer to the COLORS keyword). Keywords BUFFER Set this keyword to a named variable that is used for a buffer. A buffer variable need only be supplied when reading multiple images per file. Initialize the buffer variable to empty by setting it to 0. COLORS If the image file contains a TrueColor image that is to be displayed on an indexed color destination, set COLORS to the desired number of colors to be quantized. COLORS can be set to a value from 8 to 256. The DITHER and TWO_PASS_QUANTIZE keywords affect the method, speed, and quality of the color quantization. These keywords have no effect if the file contains a grayscale image. DITHER Set this keyword to use dithering with color quantization (i.e., if the COLORS keyword is in use). Dithering is a method that distributes the color quantization error to surrounding pixels, to achieve higher-quality results. Set the DITHER keyword to one of the following values: * 0 = No dithering. Images are read quickly, but quality is low. * 1 = Floyd-Steinberg dithering. This method is relatively slow, but produces the highest quality results. This is the default behavior. * 2 = Ordered dithering. This method is faster than Floyd-Steinberg dithering, but produces lower quality results. GRAYSCALE Set this keyword to return a monochrome (grayscale) image, regardless of whether the file contains an RGB or grayscale image. ORDER JPEG/JFIF images are normally written in top-to-bottom order. If the image is to be stored into the Image array in the standard IDL order (from bottom-to-top) set ORDER to 0. This is the default. If the image array is to be top-to-bottom order, set ORDER to 1. TRUE Use this keyword to specify the index of the dimension for color interleaving when reading a TrueColor image. The default is 1, for pixel interleaving, (3, m, n). A value of 2 indicates line interleaving (m, 3, n), and 3 indicates band interleaving, (m, n, 3). TWO_PASS_QUANTIZE Set this keyword to use a two-pass color quantization method when quantization is in effect (i.e., the COLORS keyword is in use). This method requires more memory and time, but produces superior results to the default one-pass quantization method. UNIT This keyword can be used to designate the logical unit number of an already open JFIF file, allowing the reading of multiple images per file or the embedding of JFIF images in other data files. When using this keyword, Filename should not be specified. Note When using VMS, open the file with the /STREAM keyword. Note When opening a file intended for use with the UNIT keyword, if the filename does not end in .jpg, or .jpeg, you must specify the STDIO keyword to OPEN in order for the file to be compatible with READ_JPEG. Examples ; Read a JPEG grayscale image: READ_JPEG, 'test.jpg', a ; Display the image: TV, a ; Read and display a JPEG TrueColor image on a TrueColor display: READ_JPEG, 'test.jpg', a, TRUE=1 ; Display the image returned with pixel interleaving ; (i.e., with dimensions 3, m, n): TV, a, TRUE=1 Read the image, setting the number of colors to be quantized to the maximum number of available colors. ; Read a JPEG TrueColor image on an 8-bit pseudo-color display: READ_JPEG, 'test.jpg', a, ctable, COLORS=!D.N_COLORS-1 ; Display the image: TV, a ; Load the quantized color table: TVLCT, ctable We could have also included the TWO_PASS_QUANTIZE and DITHER keywords to improve the image's appearance. Using the BUFFER keyword on VMS. ; Initialize buffer: buff = 0 OPENR, 1, 'images.jpg', /STREAM ; Process each image: FOR i=1, nimages DO BEGIN ; Read next image: READ_JPEG, UNIT=1, BUFFER=buff, a ; Display the image: TV, a ENDFOR ; Done: CLOSE, 1 See Also WRITE_JPEG, QUERY_JPEG READ_PICT [Previous Routine] [Next Routine] [List of Routines] NAME: READ_PICT The READ_PICT procedure reads the contents of a PICT (version 2) format image file and returns the image and color table vectors (if present) in the form of IDL variables. The PICT format is used by Apple Macintosh computers. This routine is written in the IDL language. Its source code can be found in the file read_pict.pro in the lib subdirectory of the IDL distribution. Note To find information about a potential PICT file before trying to read its data, use the QUERY_PICT function. Syntax READ_PICT, Filename, Image [, R, G, B] Arguments Filename A scalar string specifying the full pathname of the PICT file to read. Image A named variable that will contain the 2D image read from Filename. R, G, B Named variables that will contain the Red, Green, and Blue color vectors read from the PICT file. Example To open and read the PICT image file named foo.pict in the current directory, store the image in the variable image1, and store the color vectors in the variables R, G, and B, enter: READ_PICT, 'foo.pict', image1, R, G, B To load the new color table and display the image, enter: TVLCT, R, G, B TV, image1 See Also WRITE_PICT, QUERY_PICT READ_PNG [Previous Routine] [Next Routine] [List of Routines] NAME: READ_PNG The READ_PNG routine reads the image contents of a Portable Network Graphics (PNG) file and returns the image in an IDL variable. If the image contains a palette (see QUERY_PNG), it can be returned as well in three IDL variables. READ_PNG supports 1, 2, 3 and 4 channel images with channel depths of 8 or 16 bits. Note IDL supports version 1.0.5 of the PNG Library. Note Only single channel 8-bit images may have palettes. If an 8-bit, single-channel image has index values marked as "transparent," these can be retrieved as well. Note To find information about a potential PNG file before trying to read its data, use the QUERY_PNG function. Syntax Result = READ_PNG ( Filename [, R, G, B] [,/ORDER] [, /VERBOSE] [, /TRANSPARENT] ) or READ_PNG, Filename, Image [, R, G, B] [,/ORDER] [, /VERBOSE] [, /TRANSPARENT] Note The procedure form of READ_PNG is available to ease the conversion of IDL code that uses the removed READ_GIF procedure. Instances of READ_GIF can be changed to READ_PNG by simply replacing "READ_GIF" with "READ_PNG". Note, however, that the CLOSE and MULTIPLE keywords to READ_GIF are not accepted by the READ_PNG procedure. Return Value For 8-bit images, Result will be a two- or three-dimensional array of type byte. For 16-bit images, Result will be of type unsigned integer (UINT). Arguments Filename A scalar string containing the full pathname of the PNG file to read. R, G, B Named variables that will contain the Red, Green, and Blue color vectors if a color table exists. Keywords ORDER Set this keyword to indicate that the rows of the image should be read from bottom to top. The rows are read from top to bottom by default. ORDER provides compatibility with PNG files written using versions of IDL prior to IDL 5.4, which wrote PNG files from bottom to top. VERBOSE Produces additional diagnostic output during the read. TRANSPARENT Returns an array of pixel index values that are to be treated as "transparent" for the purposes of image display. If there are no transparent values then TRANSPARENT will be set to a long-integer scalar with the value 0. Example Create an RGBA (16-bits/channel) and a Color Indexed (8-bit/channel) image with a palette: rgbdata = UINDGEN(4,320,240) cidata = BYTSCL(DIST(256)) red = indgen(256) green = indgen(256) blue = indgen(256) WRITE_PNG,'rgb_image.png',rgbdata WRITE_PNG,'ci_image.png',cidata,red,green,blue ;Query and read the data names = ['rgb_image.png','ci_image.png','unknown.png'] FOR i=0,N_ELEMENTS(names)-1 DO BEGIN ok = QUERY_PNG(names[i],s) IF (ok) THEN BEGIN HELP,s,/STRUCTURE IF (s.HAS_PALETTE) THEN BEGIN img = READ_PNG(names[i],rpal,gpal,bpal) HELP,img,rpal,gpal,bpal ENDIF ELSE BEGIN img = READ_PNG(names[i]) HELP,img ENDELSE ENDIF ELSE BEGIN PRINT,names[i],' is not a PNG file' ENDELSE ENDFOR END See Also WRITE_PNG, QUERY_PNG READ_PPM [Previous Routine] [Next Routine] [List of Routines] NAME: READ_PPM The READ_PPM procedure reads the contents of a PGM (gray scale) or PPM (portable pixmap for color) format image file and returns the image in the form of a 2D byte array (for grayscale images) or a (3, n, m) byte array (for TrueColor images). Files to be read should adhere to the PGM/PPM standard. The following file types are supported: P2 (graymap ASCII), P5 (graymap RAWBITS), P3 (TrueColor ASCII pixmaps), and P6 (TrueColor RAWBITS pixmaps). Maximum pixel values are limited to 255. Images are always stored with the top row first. PPM/PGM format is supported by the PBMPLUS toolkit for converting various image formats to and from portable formats, and by the Netpbm package. This routine is written in the IDL language. Its source code can be found in the file read_ppm.pro in the lib subdirectory of the IDL distribution. Note To find information about a potential PPM file before trying to read its data, use the QUERY_PPM function. Syntax READ_PPM, Filename, Image [, MAXVAL=variable] Arguments Filename A scalar string specifying the full path name of the PGM or PPM file to read. Image A named variable that will contain the image. For grayscale images, Image is a 2D byte array. For TrueColor images, Image is a (3, n, m) byte array. Keywords MAXVAL A named variable that will contain the maximum pixel value. Example To open and read the PGM image file named "foo.pgm" in the current directory and store the image in the variable IMAGE1: READ_PPM, 'foo.pgm', IMAGE1 See Also WRITE_PPM, QUERY_PPM READ_SPR [Previous Routine] [Next Routine] [List of Routines] NAME: READ_SPR The READ_SPR function reads a row-indexed sparse array from a specified file and returns the array as the result. Row-indexed sparse arrays are created using the SPRSIN function and written to a file using the WRITE_SPR function. This routine is written in the IDL language. Its source code can be found in the file read_spr.pro in the lib subdirectory of the IDL distribution. Syntax Result = READ_SPR(Filename) Arguments Filename A scalar string specifying the name of the file containing a row-indexed sparse array. Example Suppose we have already saved a row-indexed sparse array to a file named sprs.as, as described in the documentation for the WRITE_SPR routine. To read the sparse array from the file and store it in a variable sprs, use the following command: sprs = READ_SPR('sprs.as') See Also FULSTR, LINBCG, SPRSAB, SPRSAX, SPRSIN, WRITE_SPR READ_SRF [Previous Routine] [Next Routine] [List of Routines] NAME: READ_SRF The READ_SRF procedure reads the contents of a Sun rasterfile and returns the image and color table vectors (if present) in the form of IDL variables. READ_SRF only handles 1-, 8-, 24-, and 32-bit rasterfiles of type RT_OLD and RT_STANDARD. See the file /usr/include/rasterfile.h for the structure of Sun rasterfiles. This routine is written in the IDL language. Its source code can be found in the file read_srf.pro in the lib subdirectory of the IDL distribution. Note To find information about a potential SRF file before trying to read its data, use the QUERY_SRF function. Syntax READ_SRF, Filename, Image [, R, G, B] Arguments Filename A scalar string containing the name of the rasterfile to read. Image A named variable that will contain the 2D byte array (image). R, G, B Named variables that will contain the Red, Green, and Blue color vectors, if the rasterfile contains colormaps. Example To open and read the Sun rasterfile named sun.srf in the current directory, store the image in the variable image1, and store the color vectors in the variables R, G, and B, enter: READ_SRF, 'sun.srf', image1, R, G, B To load the new color table and display the image, enter: TVLCT, R, G, B TV, image1 See Also WRITE_SRF, QUERY_SRF READ_SYLK [Previous Routine] [Next Routine] [List of Routines] NAME: READ_SYLK The READ_SYLK function reads the contents of a SYLK (Symbolic Link) format spreadsheet data file and returns the contents of the file, or of a cell data range, in an IDL variable. READ_SYLK returns either a vector of structures or a 2D array containing the spreadsheet cell data. By default, READ_SYLK returns a vector of structures, each of which contains the data from one row of the table being read. In this case, the individual fields in the structures have the tag names "Col0", "Col1", ..., "Coln". If the COLMAJOR keyword is specified, each of the structures returned contains data from one column of the table, and the tag names are "Row0", "Row1", ..., "Rown". Note: This routine reads only numeric and string SYLK data. It ignores all spreadsheet and cell formatting information (cell width, text justification, font type, date, time, and monetary notations, etc). Note also that the data in a given cell range must be of the same data type (all integers, for example) in order for the read operation to succeed. See the example below for further information. This routine is written in the IDL language. Its source code can be found in the file read_sylk.pro in the lib subdirectory of the IDL distribution. Syntax Result = READ_SYLK( File [, /ARRAY] [, /COLMAJOR] [, NCOLS=columns] [, NROWS=rows] [, STARTCOL=column] [, STARTROW=row] [, /USEDOUBLES] [, /USELONGS] ) Arguments File A scalar string specifying the full path name of the SYLK file to read. Keywords ARRAY Set this keyword to return an IDL array rather than a vector of structures. Note that all the data in the cell range specified must be of the same data type to successfully return an array. COLMAJOR Set this keyword to create a vector of structures each containing data from a single column of the table being read. If you are creating an array rather than a vector of structures (the ARRAY keyword is set), setting COLMAJOR has the same effect as transposing the resulting array. This keyword should be set when importing spreadsheet data which has column major organization (data stored in columns rather than rows). NCOLS Set this keyword to the number of spreadsheet columns to read. If not specified, all of the cell columns found in the file are read. NROWS Set this keyword to the number of spreadsheet rows to read. If not specified, all of the cell rows found in the file are read. STARTCOL Set this keyword to the first column of spreadsheet cells to read. If not specified, the read operation begins with the first column found in the file (column 0). STARTROW Set this keyword to the first row of spreadsheet cells to read. If not specified, the read operation begins with the first row of cells found in the file (row 0). USEDOUBLES Set this keyword to read any floating-point cell data as double-precision rather than the default single-precision. USELONGS Set this keyword to read any integer cell data as long integer type rather than the default integer type. Examples Suppose the following spreadsheet table, with the upper left cell (value = "Index") at location (0, 0), has been saved as the SYLK file "file.slk": Index Name Gender Platform 1 Beth F UNIX 2 Lubos M VMS 3 Louis M Windows 4 Thierry M Macintosh Note that the data format of the title row (string, string, string, string) is inconsistent with the following four rows (int, string, string, string) in the table. Because of this, it is impossible to read all of the table into a single IDL variable. The following two commands, however, will read all of the data: title = READ_SYLK("file.slk", NROWS = 1) table = READ_SYLK("file.slk", STARTROW = 1) ;Display the top row of the table. PRINT, title IDL prints: { Index Name Gender Platform} Print the table: PRINT, table IDL prints: {1 Beth F UNIX}{2 Lubos M VMS}{3 Louis M Windows}{4 Thierry M Macintosh} To retrieve only the "Name" column: names = READ_SYLK("file.slk", /ARRAY, STARTROW = 1, $ STARTCOL = 1, NCOLS = 1) PRINT, names IDL prints: Beth Lubos Louis Thierry To retrieve the "Name" column in column format: namescol = READ_SYLK("file.slk", /ARRAY, /COLMAJOR, $ STARTROW = 1, STARTCOL = 1, NCOLS = 1) PRINT, namescol IDL prints: Beth Lubos Louis Thierry See Also WRITE_SYLK READ_TIFF [Previous Routine] [Next Routine] [List of Routines] NAME: READ_TIFF The READ_TIFF function reads single or multi-channel images from TIFF format files and returns the image and color table vectors in the form of IDL variables. Note To find information about a potential TIFF file before trying to read its data, use the QUERY_TIFF function. The obsolete routine TIFF_DUMP may also be used to examine the structure and tags of a TIFF file. READ_TIFF now imports 1- and 4-bit images from TIFF files. For 1-bit (bi-level) images, the image values are 0 or 1. For 4-bit grayscale images, the image values are in the range 0 to 15. Syntax Result = READ_TIFF( Filename [, R, G, B] [, ORIENTATION] [, CHANNELS=scalar or vector] [, GEOTIFF=variable] [, IMAGE_INDEX=value] [, INTERLEAVE={0 | 1 |2}] [, ORDER=variable] [, PLANARCONFIG=variable] [, SUB_RECT=[x, y, width, height]] [, /UNSIGNED] [, /VERBOSE] ) Return Value READ_TIFF returns a byte, unsigned integer, long, or float array (based on the data format in the TIFF file) containing the image data. The dimensions of the Result are [Columns, Rows] for single-channel images, or [Channels, Columns, Rows] for multi-channel images, unless a different type of interleaving is specified with the INTERLEAVE keyword. RGB images are a special case of multi-channel images, and contain three channels. Most TIFF readers and writers can handle only images with one or three channels. As a special case, for three-channel TIFF image files that are stored in planar interleave format, and if four parameters are provided, READ_TIFF returns the integer value zero, sets the variable defined by the PLANARCONFIG keyword to 2, and returns three separate images in the variables defined by the R, G, and B arguments. Arguments Filename A scalar string specifying the full pathname of the TIFF file to read. R, G, B Named variables that will contain the Red, Green, and Blue color vectors of the color table from the file if one exists. If the TIFF file is written as a three-channel image, interleaved by plane, and the R, G, and B parameters are present, the three channels of the image are returned in the R, G, and B variables. Keywords ORIENTATION Set this keyword to a named variable that will contain the orientation value from the TIFF file. Possible return values are: * 1 = Column 0 represents the left-hand side, and row 0 represents the top. * 2 = Column 0 represents the right-hand side, and row 0 represents the top. * 3 = Column 0 represents the right-hand side, and row 0 represents the bottom. * 0 or 4 = Column 0 represents the left-hand side, and row 0 represents the bottom. * 5 = Column 0 represents the top, and row 0 represents the left-hand side. * 6 = Column 0 represents the top, and row 0 represents the right-hand side. * 7 = Column 0 represents the bottom, and row 0 represents the right-hand side. * 8 = Column 0 represents the bottom, and row 0 represents the left-hand side. If an orientation value does not appear in the TIFF file, an orientation of 0 is returned. CHANNELS Set this keyword to a scalar or vector giving the channel numbers to be returned for a multi-channel image, starting with zero. The default is to return all of the channels. This keyword is ignored for single-channel images, or for three-channel planar- interleaved images when the R, G, and B arguments are specified. GEOTIFF Returns an anonymous structure containing one field for each of the GeoTIFF tags and keys found in the file. If no GeoTIFF information is present in the file, the returned variable is undefined. The GeoTIFF structure is formed using fields named from the following table. Anonymous Structure Field Name IDLDatatype TAGS: "MODELPIXELSCALETAG" DOUBLE[3] "MODELTRANSFORMATIONTAG" DOUBLE[4,4] "MODELTIEPOINTTAG" DOUBLE[6,*] KEYS: "GTMODELTYPEGEOKEY" INT "GTRASTERTYPEGEOKEY" INT "GTCITATIONGEOKEY" STRING "GEOGRAPHICTYPEGEOKEY" INT "GEOGCITATIONGEOKEY" STRING "GEOGGEODETICDATUMGEOKEY" INT Table 80: GEOTIFF Structures Anonymous Structure Field Name IDLDatatype "GEOGPRIMEMERIDIANGEOKEY" INT "GEOGLINEARUNITSGEOKEY" INT "GEOGLINEARUNITSIZEGEOKEY" DOUBLE "GEOGANGULARUNITSGEOKEY" INT "GEOGANGULARUNITSIZEGEOKEY" DOUBLE "GEOGELLIPSOIDGEOKEY" INT "GEOGSEMIMAJORAXISGEOKEY" DOUBLE "GEOGSEMIMINORAXISGEOKEY" DOUBLE "GEOGINVFLATTENINGGEOKEY" DOUBLE "GEOGAZIMUTHUNITSGEOKEY" INT "GEOGPRIMEMERIDIANLONGGEOKEY" DOUBLE "PROJECTEDCSTYPEGEOKEY" INT "PCSCITATIONGEOKEY" STRING "PROJECTIONGEOKEY" INT "PROJCOORDTRANSGEOKEY" INT "PROJLINEARUNITSGEOKEY" INT "PROJLINEARUNITSIZEGEOKEY" DOUBLE "PROJSTDPARALLEL1GEOKEY" DOUBLE "PROJSTDPARALLEL2GEOKEY" DOUBLE "PROJNATORIGINLONGGEOKEY" DOUBLE "PROJNATORIGINLATGEOKEY" DOUBLE "PROJFALSEEASTINGGEOKEY" DOUBLE "PROJFALSENORTHINGGEOKEY" DOUBLE "PROJFALSEORIGINLONGGEOKEY" DOUBLE "PROJFALSEORIGINLATGEOKEY" DOUBLE Table 80: GEOTIFF Structures Anonymous Structure Field Name IDLDatatype "PROJFALSEORIGINEASTINGGEOKEY" DOUBLE "PROJFALSEORIGINNORTHINGGEOKEY" DOUBLE "PROJCENTERLONGGEOKEY" DOUBLE "PROJCENTERLATGEOKEY" DOUBLE "PROJCENTEREASTINGGEOKEY" DOUBLE "PROJCENTERNORTHINGGEOKEY" DOUBLE "PROJSCALEATNATORIGINGEOKEY" DOUBLE "PROJSCALEATCENTERGEOKEY" DOUBLE "PROJAZIMUTHANGLEGEOKEY" DOUBLE "PROJSTRAIGHTVERTPOLELONGGEOKEY" DOUBLE "VERTICALCSTYPEGEOKEY" INT "VERTICALCITATIONGEOKEY" STRING "VERTICALDATUMGEOKEY" INT "VERTICALUNITSGEOKEY" INT Table 80: GEOTIFF Structures Note If a GeoTIFF key appears multiple times in a file, only the value for the first instance of the key is returned. IMAGE_INDEX Selects the image number within the file to be read (see QUERY_TIFF to determine the number of images in the file). INTERLEAVE For multi-channel images, set this keyword to one of the following values to force the Result to have a specific interleaving, regardless of the type of interleaving in the file being read: * 0 = Pixel interleaved: Result will have dimensions [Channels, Columns, Rows]. * 1 = Scanline (row) interleaved: Result will have dimensions [Columns, Channels, Rows]. * 2 = Planar interleaved: Result will have dimensions [Columns, Rows, Channels]. If this keyword is not specified, the Result will always be pixel interleaved, regardless of the type of interleaving in the file being read. For files stored in planar- interleave format, this keyword is ignored if the R, G, and B arguments are specified. ORDER Set this keyword to a named variable that will contain the order value from the TIFF file. This value is returned as 0 for images written bottom to top, and 1 for images written top to bottom. If an order value does not appear in the TIFF file, an order of 1 is returned. The ORDER keyword can return any of the following additional values (depending on the source of the TIFF file): Rows Columns 1 top to bottom, left to right 2 top to bottom, right to left 3 bottom to top, right to left 4 bottom to top, left to right 5 top to bottom, left to right 6 top to bottom, right to left 7 bottom to top, right to left 8 bottom to top, left to right Table 81: Values for the ORDER keyword Reference: Aldus TIFF 6.0 spec (TIFF version 42). PLANARCONFIG Set this keyword to a named variable that will contain the interleave parameter for the TIFF file. This parameter is returned as 1 for TIFF files that are GrayScale, Palette, or interleaved by pixel. This parameter is returned as 2 for multi-channel TIFF files interleaved by image. SUB_RECT Set this keyword to a four-element array, [x, y, width, height], that specifies a rectangular region within the file to extract. Only the rectangular portion of the image selected by this keyword is read and returned. The rectangle is measured in pixels from the lower left corner (right hand coordinate system). UNSIGNED This keyword is now obsolete because older versions of IDL did not support the unsigned 16-bit integer data type. Set this keyword to return TIFF files containing unsigned 16-bit integers as signed 32-bit longword arrays. If not set, return an unsigned 16-bit integer for these files. This keyword has no effect if the input file does not contain 16-bit integers. VERBOSE Produce additional diagnostic output during the read. Examples Example 1 Read the file my.tif in the current directory into the variable image, and save the color tables in the variables, R, G, and B by entering: image = READ_TIFF('my.tif', R, G, B) To view the image, load the new color table and display the image by entering: TVLCT, R, G, B TV, image Example 2 Write and read a multi-image TIFF file. The first image is a 16-bit single-channel image stored using compression. The second image is an RGB image stored using 32- bits/channel uncompressed. ; Write the image data: data = FIX(DIST(256)) rgbdata = LONARR(3,320,240) WRITE_TIFF,'multi.tif',data,COMPRESSION=1,/SHORT WRITE_TIFF,'multi.tif',rgbdata,/LONG,/APPEND ; Read the image data back: ok = QUERY_TIFF('multi.tif',s) IF (ok) THEN BEGIN FOR i=0,s.NUM_IMAGES-1 DO BEGIN imp = QUERY_TIFF('multi.tif',t,IMAGE_INDEX=i) img = READ_TIFF('multi.tif',IMAGE_INDEX=i) HELP,t,/STRUCTURE HELP,img ENDFOR ENDIF Example 3 Write and read a multi-channel image: data = LINDGEN(10, 256, 256) ; 10 channels ; Write the image data: WRITE_TIFF, 'multichannel.tif', data, /LONG ; Read back only channels [0,2,4,6,8], using planar-interleaving img = READ_TIFF('multichannel.tif', CHANNELS=[0,2,4,6,8], $ INTERLEAVE=2) HELP, img IDL prints: IMG LONG = Array[256, 256, 5] See Also WRITE_TIFF, QUERY_TIFF READ_WAV [Previous Routine] [Next Routine] [List of Routines] NAME: READ_WAV The READ_WAV function reads the audio stream from the named .WAV file. Optionally, it can return the sampling rate of the audio stream. Syntax Result = READ_WAV ( Filename [, Rate] ) Return Value In the case of a single channel stream, the returned variable is a BYTE or INT (depending on the number of bits per sample) one-dimensional array. In the case of a file with multiple channels, a similar two-dimensional array is returned, with the leading dimension being the channel number. Arguments Filename A scalar string containing the full pathname of the .WAV file to read. Rate Returns an IDL long containing the sampling rate of the stream in samples per second. Keywords None. READ_WAVE [Previous Routine] [Next Routine] [List of Routines] NAME: READ_WAVE The READ_WAVE procedure reads a .wave or .bwave file created by the Wavefront Advanced Data Visualizer into an series of IDL variables. Note READ_WAVE only preserves the structure of the variables if they are regularly gridded. This routine is written in the IDL language. Its source code can be found in the file read_wave.pro in the lib subdirectory of the IDL distribution. Syntax READ_WAVE, File, Variables, Names, Dimensions [, MESHNAMES=variable] Arguments File A scalar string containing the name of the Wavefront file to read. Variables A named variable that will contain a block of the variables contained in the wavefront file. Since each variable in a wavefront file can have more than one field (for instance, a vector variable has 3 fields), the fields of each variable make up the major index into the variable block. For instance, if a Wavefront file had one scalar variable and one vector variable, the scalar would be extracted as follows: scalar_variable = variables[0,*,*,*] and the vector variable would be extracted as follows: vector_variable = variables[1:3,*,*,*] To find the dimensions of the returned variable, see the description of the Dimensions argument. Names A named variable that will contain the string names of each variable contained in the file. Dimensions A named variable that will contain a long array describing how many fields in the large returned variable block each variable occupies. In the above example of one scalar variable followed by a vector variable, the dimension variable would be [1,3]. This indicates that the first field of the returned variable block would be the scalar variable and the following 3 fields would comprise the vector variable. Keywords MESHNAMES Set this keyword to a named variable that will contain the name of the mesh used in the Wavefront file for each variable. See Also WRITE_WAVE READ_X11_BITMAP [Previous Routine] [Next Routine] [List of Routines] NAME: READ_X11_BITMAP The READ_X11_BITMAP procedure reads bitmaps stored in the X Windows X11 format. The X Windows bitmap program produces a C header file containing the definition of a bitmap produced by that program. This procedure reads such a file and creates an IDL byte array containing the bitmap. It is used primarily to read bitmaps to be used as IDL widget button labels. This routine is written in the IDL language. Its source code can be found in the file read_x11_bitmap.pro in the lib subdirectory of the IDL distribution. Syntax READ_X11_BITMAP, File, Bitmap [, X, Y] [, /EXPAND_TO_BYTES] Arguments File A scalar string containing the name of the file containing the bitmap. Bitmap A named variable that will contain the bitmap. This variable is returned as a byte array. X A named variable that will contain the width of the bitmap. Y A named variable that will contain the height of the bitmap. Keywords EXPAND_TO_BYTES Set this keyword to instruct READ_X11_BITMAP to return a 2D array which has one bit per byte (0 for a 0 bit, 255 for a 1 bit) instead. Example To open and read the X11 bitmap file named my.x11 in the current directory, store the bitmap in the variable bitmap1, and the width and height in the variables X and Y, enter: READ_X11_BITMAP, 'my.x11', bitmap1, X, Y To display the new bitmap, enter: READ_X11_BITMAP, 'my.x11', image, /EXPAND_TO_BYTES TV, image, /ORDER See Also READ_XWD READ_XWD [Previous Routine] [Next Routine] [List of Routines] NAME: READ_XWD The READ_XWD function reads the contents of a file created by the xwd (X Windows Dump) command and returns the image and color table vectors in the form of IDL variables. READ_XWD returns a 2D byte array containing the image. If the file cannot be open or read, the return value is zero. Note: this function is intended to be used only on files containing 8-bit pixmaps created with xwd version 6 or later. This routine is written in the IDL language. Its source code can be found in the file read_xwd.pro in the lib subdirectory of the IDL distribution. Syntax Result = READ_XWD( Filename[, R, G, B] ) Arguments Filename A scalar string specifying the full pathname of the XWD file to read. R, G, B Named variables that will contain the Red, Green, and Blue color vectors, if the XWD file contains color tables. Example To open and read the X Windows Dump file named my.xwd in the current directory, store the image in the variable image1, and store the color vectors in the variables, R, G, and B, enter: image1 = READ_XWD('my.xwd', R, G, B) To load the new color table and display the image, enter: TVLCT, R, G, B TV, image1 See Also READ_X11_BITMAP READS [Previous Routine] [Next Routine] [List of Routines] NAME: READS The READS procedure performs formatted input from a string variable and writes the results into one or more output variables. This procedure differs from the READ procedure only in that the input comes from memory instead of a file. This routine is useful when you need to examine the format of a data file before reading the information it contains. Each line of the file can be read into a string using READF. Then the components of that line can be read into variables using READS. Syntax READS, Input, Var1, ..., Varn [, AM_PM=[string, string]] [, DAYS_OF_WEEK=string_array{7 names}] [, FORMAT=value] [, MONTHS=string_array{12 names}] Arguments Input The string variable from which the input is taken. If the supplied argument is not a string, it is automatically converted. The argument can be scalar or array. If Input is an array, the individual string elements are treated as successive lines of input. Vari The named variables to receive the input. Note If the variable specified for the Vari argument has not been previously defined, the input data is assumed to be of type float, and the variable will be cast as a float. Keywords AM_PM Supplies a string array of 2 names to be used for the names of the AM and PM string when processing explicitly formatted dates (CAPA, CApA, and CapA format codes) with the FORMAT keyword. DAYS_OF_WEEK Supplies a string array of 7 names to be used for the names of the days of the week when processing explicitly formatted dates (CDWA, CDwA, and CdwA format codes) with the FORMAT keyword. FORMAT If FORMAT is not specified, IDL uses its default rules for formatting the input. FORMAT allows the format of the input to be specified in precise detail, using a FORTRAN-style specification. See "Using Explicitly Formatted Input/Output" in Chapter 8 of Building IDL Applications. MONTHS Supplies a string array of 12 names to be used for the names of the months when processing explicitly formatted dates (CMOA, CMoA, and CmoA format codes) with the FORMAT keyword. See Also READ/READF, READU READU [Previous Routine] [Next Routine] [List of Routines] NAME: READU The READU procedure reads unformatted binary data from a file into IDL variables. READU transfers data directly with no processing of any kind performed on the data. Syntax READU, Unit, Var1, ..., Varn [, TRANSFER_COUNT=variable] VMS-Only Keywords: [, KEY_ID=index] [, KEY_MATCH=relation] [, KEY_VALUE=value] Arguments Unit The IDL file unit from which input is taken. Vari Named variables to receive the data. For non-string variables, the number of bytes required for Var are read. When READU is used with a variable of type string, IDL reads exactly the number of bytes contained in the existing string. For example, to read a 5-character string, enter: temp = '12345' READU, unit, temp Keywords TRANSFER_COUNT Set this keyword to a named variable in which to return the number of elements transferred by the input operation. Note that the number of elements is not the same as the number of bytes (except in the case where the data type being transferred is bytes). For example, transferring 256 floating-point numbers yields a transfer count of 256, not 1024 (the number of bytes transferred). This keyword is useful with files opened with the RAWIO keyword to the OPEN routines. Normally, attempting to read more data than is available from a file causes the unfilled space to be zeroed and an error to be issued. This does not happen with files opened with the RAWIO keyword. Instead, the programmer must keep track of the transfer count. VMS-Only Keywords Note The obsolete VMS routines FORRD, and FORRD_KEY have been replaced by the READU command used with the following keywords. KEY_ID The index key to be used (primary = 0, first alternate key = 1, etc...) when accessing data from a file with indexed organization. If this keyword is omitted, the primary key is used. KEY_MATCH The relation to be used when matching the supplied key with key field values (EQ = 0, GE = 1, GT = 2) when accessing data from a file with indexed organization. If this keyword is omitted, the equality relation (0) is used. KEY_VALUE The value of a key to be found when accessing data from a file with indexed organization. This value must match the key definition that is determined when the file was created in terms of type and size-no conversions are performed. If this keyword is omitted, the previous key value is used. Example The following commands can be used to open the IDL distribution file people.dat and read an image from that file: ; Open the file for reading as file unit 1: OPENR, 1, FILEPATH('people.dat', SUBDIR = ['examples','data']) ; The image is a 192 by 192 byte array, so make B that size: B = BYTARR(192, 192) ; Read the data into B: READU, 1, B ; Close the file: CLOSE, 1 ; Display the image: TV, B See Also READ/READF, READS, WRITEU REBIN [Previous Routine] [Next Routine] [List of Routines] NAME: REBIN The REBIN function resizes a vector or array to dimensions given by the parameters Di. The supplied dimensions must be integral multiples or factors of the original dimension. The expansion or compression of each dimension is independent of the others, so that each dimension can be expanded or compressed by a different value. If the dimensions of the desired result are not integer multiples of the original dimensions, use the CONGRID function. Syntax Result = REBIN( Array, D1 [, ..., D8] [, /SAMPLE] ) Arguments Array The array to be resampled. Array can be of any basic type except complex or string. Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. The dimensions of the resulting resampled array. These dimensions must be integer multiples or factors of the corresponding original dimensions. Keywords SAMPLE Normally, REBIN uses bilinear interpolation when magnifying and neighborhood averaging when minifying. Set the SAMPLE keyword to use nearest neighbor sampling for both magnification and minification. Bilinear interpolation gives higher quality results but requires more time. Rules Used by REBIN Assume the original vector X has n elements and the result is to have m elements. Let f = n/m, the ratio of the size of the original vector, X to the size of the result. 1/f must be an integer if n < m (expansion). f must be an integer if compressing, (n > m). The various resizing options can be described as: * Expansion, n < m, SAMPLE = 0: Yi = F(X, f i) i = 0, 1, ... , m-1 The linear interpolation function, F(X, p) that interpolates X at location p, is defined as: X + ( ­ ) (X ­ X ) if p < n ­ 1 F(X, p) p p p p + 1 p = X p if p n ­ 1 * Expansion, n < m, SAMPLE = 1: Yi = X fi * Compression, n > m, SAMPLE = 0: f(i + 1) ­ 1 Yi = (1 f) X j j = fi * Compression, n > m, SAMPLE = 1: Yi = X fi * No change, n = m: Yi = Xi Endpoint Effects When Expanding When expanding an array, REBIN interpolates, it never extrapolates. Each of the n-1 intervals in the n-element input array produces m/n interpolates in the m-element output array. The last m/n points of the result are obtained by duplicating element n-1 of the input array because their interpolates would lie outside the input array. For example ; A four point vector: A = [0, 10, 20, 30] ; Expand by a factor of 3: B = REBIN(A, 12) PRINT, B IDL prints: 0 3 6 10 13 16 20 23 26 30 30 30 Note that the last element is repeated three times. If this effect is undesirable, use the INTERPOLATE function. For example, to produce 12 equally spaced interpolates from the interval 0 to 30: B = INTERPOLATE(A, 3./11. * FINDGEN(12)) PRINT, B IDL prints: 0 2 5 8 10 13 16 19 21 24 27 30 Here, the sampling ratio is (n - 1)/(m - 1). Example Create and display a simple image by entering: D = SIN(DIST(50)/4) & TVSCL, D Resize the image to be 5 times its original size and display the result by entering: D = REBIN(D, 250, 250) & TVSCL, D See Also CONGRID RECALL_COMMANDS [Previous Routine] [Next Routine] [List of Routines] NAME: RECALL_COMMANDS The RECALL_COMMANDS function returns a string array containing the entries in IDL's command recall buffer. The size of the returned array is the size of recall buffer, even if fewer than commands have been entered (any "empty" buffer entries will contain null strings). The default size of the command recall buffer is 20 lines. (See "!EDIT_INPUT" on page 2429 for more information about the command recall buffer.) Element zero of the returned array contains the most recent command. Syntax Result = RECALL_COMMANDS() RECON3 [Previous Routine] [Next Routine] [List of Routines] NAME: RECON3 The RECON3 function can reconstruct a three-dimensional data array from two or more images (or projections) of an object. For example, if you placed a dark object in front of a white background and then photographed it three times (each time rotating the object a known amount) then these three images could be used with RECON3 to approximate a 3D volumetric representation of the object. RECON3 also works with translucent projections of an object. RECON3 returns a 3D byte array. This routine is written in the IDL language. Its source code can be found in the file recon3.pro in the lib subdirectory of the IDL distribution. Using RECON3 Images used in reconstruction should show strong light/dark contrast between the object and the background. If the images contain low (dark) values where the object is and high (bright) values where the object isn't, the MODE keyword should be set to +1 and the returned volume will have low values where the object is, and high values where the object isn't. If the images contain high (bright) values where the object is and low (dark) values where the object isn't, the MODE keyword should be set to -1 and the returned volume will have high values where the object is, and low values where the object isn't. In general, the object must be CONVEX for a good reconstruction to be possible. Concave regions are not easily reconstructed. An empty coffee cup, for example, would be reconstructed as if it were full. The more images the better. Images from many different angles will improve the quality of the reconstruction. It is also important to supply images that are parallel and perpendicular to any axes of symmetry. Using the coffee cup as an example, at least one image should be looking through the opening in the handle. Telephoto images are also better for reconstruction purposes than wide angle images. Syntax Result = RECON3( Images, Obj_Rot, Obj_Pos, Focal, Dist,Vol_Pos, Img_Ref, Img_Mag, Vol_Size [, QUIET] [, /CUBIC] [, MISSING=value] [, MODE=value] ) Arguments Images A 3D array containing the images to use to reconstruct the volume. Execution time increases linearly with more images. Images must be an 8-bit (byte) array with dimensions (x, y, n) where x is the horizontal image dimension, y is the vertical image dimension, and n is the number of images. Note that n must be at least 2. Obj_Rot A 3 x n floating-point array specifying the amount the object is rotated to make it appear as it does in each image. The object is first rotated about the X axis, then about the Y axis, and finally about the Z axis (with the object's reference point at the origin). Obj_Rot[0, *] is the X rotation for each image, Obj_Rot[1, *] is the Y rotation, and Obj_Rot[2, *] is the Z rotation. Obj_Pos A 3 x n floating-point array specifying the position of the object's reference point relative to the camera lens. The camera lens is located at the coordinate origin and points in the negative Z direction (the view up vector points in the positive Y direction). Obj_Pos should be expressed in this coordinate system. Obj_Pos[0, *] is the X position for each image, Obj_Pos[1, *] is the Y position, and Obj_Pos[2, *] is the Z position. All the values in Obj_Pos[2, *] should be less than zero. Note that the values for Obj_Pos, Focal, Dist, and Vol_Pos should all be expressed in the same units (mm, cm, m, in, ft, etc.). Focal An n-element floating-point array specifying the focal length of the lens for each image. Focal may be set to zero to indicate a parallel image projection (infinite focal length). Dist An n-element floating-point array specifying the distance from the camera lens to the image plane (film) for each image. Dist should be greater than Focal. Vol_Pos A 3 x 2 floating-point array specifying the two opposite corners of a cube that surrounds the object. Vol_Pos should be expressed in the object's coordinate system relative to the object's reference point. Vol_Pos[*, 0] specifies one corner and Vol_Pos[*, 1] specifies the opposite corner. Img_Ref A 2 x n integer or floating-point array that specifies the pixel location at which the object's reference point appears in each of the images. Img_Ref[0, *] is the X coordinate for each image and Img_Ref[1, *] is the Y coordinate. Img_Mag A 2 x n integer or floating-point array that specifies the magnification factor for each image. This number is actually the length (in pixels) that a test object would appear in an image if it were n units long and n units distant from the camera lens. Img_Mag[0, *] is the X dimension (in pixels) of a test object for each image, and Img_Mag[1, *] is the Y dimension. All elements in Img_Mag should be greater than or equal to 1. Vol_Size A 3-element integer or floating-point array that specifies the size of the 3D byte array to return. Execution time (and resolution) increases exponentially with larger values for Vol_Size. Vol_Size[0] specifies the X dimension of the volume, Vol_Size[1] specifies the Y dimension, and Vol_Size[2] specifies the Z dimension. Keywords QUIET Set this keyword to suppress the output of informational messages when the processing of each image is completed. CUBIC Set this keyword to use cubic interpolation. The default is to use tri-linear interpolation, which is slightly faster. MISSING Set this keyword equal to a byte value for cells in the 3D volume that do not map to any of the supplied images. The value of MISSING is passed to the INTERPOLATE function. The default value is zero. MODE Set this keyword to a value less than zero to define each cell in the 3D volume as the minimum of the corresponding pixels in the images. Set MODE to a value greater than zero to define each cell in the 3D volume as the maximum of the corresponding pixels in the images. If MODE is set equal to zero then each cell in the 3D volume is defined as the average of the corresponding pixels in the images. MODE should usually be set to -1 when the images contain a bright object in front of a dark background or to +1 when the images contain a dark object in front of a light background. Setting MODE=0 (the default) requires more memory since the volume array must temporarily be kept as an integer array instead of a byte array. Example Assumptions for this example: * The object's major axis is parallel to the Z axis. * The object's reference point is at its center. * The camera lens is pointed directly at this reference point. * The reference point is 5000 mm in front of the camera lens. * The focal length of the camera lens is 200 mm. If the camera is focused on the reference point, then the distance from the lens to the camera's image plane must be dist = (d * f) / (d - f) = (5000 * 200) / (5000 - 200) = (1000000 / 4800) = 208.333 mm The object is roughly 600 mm wide and 600 mm high. The reference point appears in the exact center of each image. If the object is 600 mm high and 5000 mm distant from the camera lens, then the object image height must be hi = (h * f) / (d - f) = (600 * 200) / (5000 - 200) = (120000 / 4800) = 25.0 mm The object image appears 200 pixels high so the final magnification factor is img_mag = (200 / 25) = 8.0 From these assumptions, we can set up the following reconstruction: ; First, define the variables: imgx = 256 imgy = 256 frames = 3 images = BYTARR(imgx, imgy, frames) obj_rot = Fltarr(3, frames) obj_pos = Fltarr(3, frames) focal = Fltarr(frames) dist = Fltarr(frames) vol_pos = Fltarr(3, 2) img_ref = Fltarr(2, frames) img_mag = Fltarr(2, frames) vol_size = [40, 40, 40] ; The object is 5000 mm directly in front of the camera: obj_pos[0, *] = 0.0 obj_pos[1, *] = 0.0 obj_pos[2, *] = -5000.0 ; The focal length of the lens is constant for all the images: focal[*] = 200.0 ; The distance from the lens to the image plane is also constant: dist[*] = 208.333 ; The cube surrounding the object is 600 mm x 600 mm: vol_pos[*, 0] = [-300.0, -300.0, -300.0] vol_pos[*, 1] = [ 300.0, 300.0, 300.0] ; The image reference point appears at the center of all the ; images: img_ref[0, *] = imgx / 2 img_ref[1, *] = imgy / 2 ; The image magnification factor is constant for all images. ; (The images haven't been cropped or resized): img_mag[*,*] = 8.0 ; Only the object rotation changes from one image to the next. ; Note that the object is rotated about the X axis first, then Y, ; and then Z. Create some fake images for this example: images[30:160, 20:230, 0] = 255 images[110:180, 160:180, 0] = 180 obj_rot[*, 0] = [-90.0, 0.0, 0.0] images[70:140, 100:130, 1] = 255 obj_rot[*, 1] = [-70.0, 75.0, 0.0] images[10:140, 70:170, 2] = 255 images[80:90, 170:240, 2] = 150 obj_rot[*, 2] = [-130.0, 215.0, 0.0] ; Reconstruct the volume: vol = RECON3(images, obj_rot, obj_pos, focal, dist, $ vol_pos, img_ref, img_mag, vol_size, Missing=255B, Mode=(-1)) ; Display the volume: shade_volume, vol, 8, v, p scale3, xrange=[0,40], yrange=[0,40], zrange=[0,40] image = polyshade(v, p, /t3d, xs=400, ys=400) tvscl, image See Also POLYSHADE, SHADE_VOLUME, VOXEL_PROJ REDUCE_COLORS [Previous Routine] [Next Routine] [List of Routines] NAME: REDUCE_COLORS The REDUCE_COLORS procedure reduces the number of colors used in an image by eliminating pixel values without members. The pixel distribution histogram is obtained and the WHERE function is used to find bins with non-zero values. Next, a lookup table is made where table[old_pixel_value] contains new_pixel_value, and is then applied to the image. This routine is written in the IDL language. Its source code can be found in the file reduce_colors.pro in the lib subdirectory of the IDL distribution. Syntax REDUCE_COLORS, Image, Values Arguments Image On input, a variable that contains the original image array. On output, this variable contains the color-reduced image array, writing over the original. Values A named variable that, on output, contains a vector of non-zero pixel values. If Image contains pixel values from 0 to M, Values will be an M+1 element vector containing the mapping from the old values to the new. Values[i] contains the new color index of old pixel index i. Example To reduce the number of colors and display an image with the original color tables R, G, B enter the commands: REDUCE_COLORS, image, v TVLCT, R[V], G[V], B[V] See Also COLOR_QUAN REFORM [Previous Routine] [Next Routine] [List of Routines] NAME: REFORM The REFORM function changes the dimensions of an array without changing the total number of elements. If no dimensions are specified, REFORM returns a copy of Array with all dimensions of size 1 removed. If dimensions are specified, the result is given those dimensions. Only the dimensions of Array are changed-the actual data remains unmodified. Syntax Result = REFORM( Array, D1, ..., D8 [, /OVERWRITE] ) Arguments Array The array to have its dimensions modified. Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. The dimensions of the result. The Di arguments can be either a single array containing the new dimensions or a sequence of scalar dimensions. Array must have the same number of elements as specified by the product of the new dimensions. Keywords OVERWRITE Set this keyword to cause the specified dimensions to overwrite the present dimensions of the Array parameter. No data are copied, only the internal array descriptor is changed. The result of the function, in this case, is the Array parameter with its newly-modified dimensions. For example, to change the dimensions of the variable a, without moving data, enter: a = REFORM(a, n1, n2, /OVERWRITE) Example REFORM can be used to remove "degenerate" leading dimensions of size one. Such dimensions can appear when a subarray is extracted from an array with more dimensions. For example ; a is a 3-dimensional array: a = INTARR(10,10,10) ; Extract a "slice" from a: b = a[5,*,*] ; Use HELP to show what REFORM does: HELP, b, REFORM(b) Executing the above statements produces the output: B INT = Array[1, 10, 10] INT = Array[10, 10] The statements: b = REFORM(a,200,5) b = REFORM(a,[200,5]) have identical effect. They create a new array, b, with dimensions of (200, 5), from a. See Also REVERSE, ROT, ROTATE, TRANSPOSE REGRESS [Previous Routine] [Next Routine] [List of Routines] NAME: REGRESS The REGRESS function performs a multiple linear regression fit and returns an Nterm-element column vector of coefficients. REGRESS fits the function: yi = const + a0x0, i + a1x1, i + ... + aNterms-1xNterms-1, i This routine is written in the IDL language. Its source code can be found in the file regress.pro in the lib subdirectory of the IDL distribution. Syntax Result = REGRESS( X, Y, [, CHISQ=variable] [, CONST=variable] [, CORRELATION=variable] [, /DOUBLE] [, FTEST=variable] [, MCORRELATION=variable] [, MEASURE_ERRORS=vector] [, SIGMA=variable] [, STATUS=variable] [, YFIT=variable] ) Return Value REGRESS returns a 1 x Nterm array of coefficients. If the DOUBLE keyword is set, or if X or Y are double-precision, then the result will be double precision, otherwise the result will be single precision. Arguments X An Nterms by Npoints array of independent variable data, where Nterms is the number of coefficients (independent variables) and Npoints is the number of samples. Y An Npoints-element vector of dependent variable points. Weights The Weights argument is obsolete, and has been replaced by the MEASURE_ERRORS keyword. Code that uses the Weights argument will continue to work as before, but new code should use the MEASURE_ERRORS keyword instead. Note that the definition of the MEASURE_ERRORS keyword is different from that of the Weights argument. Using the Weights argument, SQRT(1/Weights[i]) represents the measurement error for each point Y[i]. Using the MEASURE_ERRORS keyword, the measurement error for each point is represented as simply MEASURE_ERRORS[i]. Also note that the RELATIVE_WEIGHTS keyword is not necessary when using the MEASURE_ERRORS keyword. Yfit, Const, Sigma, Ftest, R, Rmul, Chisq, Status The Yfit, Const, Sigma, Ftest, R, Rmul, Chisq, and Status arguments are obsolete, and have been replaced by the YFIT, CONST, SIGMA, FTEST, CORRELATION, MCORRELATION, CHISQ, and STATUS keywords, respectively. Code that uses these arguments will continue to work as before, but new code should use the keywords instead. Keywords CHISQ Set this keyword equal to a named variable that will contain the value of the chi-sqaure goodness-of-fit. CONST Set this keyword to a named variable that will contain the constant term of the fit. CORRELATION Set this keyword to a named variable that will contain the vector of linear correlation coefficients. DOUBLE Set this keyword to force computations to be done in double-precision arithmetic. FTEST Set this keyword to a named variable that will contain the F-value for the goodness- of-fit test. MCORRELATION Set this keyword to a named variable that will contain the multiple linear correlation coefficient. MEASURE_ERRORS Set this keyword to a vector containing standard measurement errors for each point Y[i]. This vector must be the same length as X and Y. Note For Gaussian errors (e.g., instrumental uncertainties), MEASURE_ERRORS should be set to the standard deviations of each point in Y. For Poisson or statistical weighting, MEASURE_ERRORS should be set to SQRT(Y). RELATIVE_WEIGHT This keyword is obsolete. Code using the Weights argument and RELATIVE_WEIGHT keyword will continue to work as before, but new code should use the MEASURE_ERRORS keyword, for which case the RELATIVE_WEIGHT keyword is not necessary. Using the Weights argument, it was necessary to specify the RELATIVE_WEIGHT keyword if no weighting was desired. This is not the case with the MEASURE_ERRORS keyword-when MEASURE_ERRORS is omitted, REGRESS assumes you want no weighting. SIGMA Set this keyword to a named variable that will contain the 1-sigma uncertainty estimates for the returned parameters. Note If MEASURE_ERRORS is omitted, then you are assuming that the regression model is the correct model for your data, and therefore, no independent goodness- of-fit test is possible. In this case, the values returned in SIGMA are multiplied by SQRT(CHISQ/(N­M)), where N is the number of points in X, and M is the number of coefficients. See section 15.2 of Numerical Recipes in C (Second Edition) for details. STATUS Set this keyword to a named variable that will contain the status of the operation. Possible status values are: * 0 = successful completion * 1 = singular array (which indicates that the inversion is invalid) * 2 = warning that a small pivot element was used and that significant accuracy was probably lost. Note If STATUS is not specified, any error messages will be output to the screen. YFIT Set this keyword to a named variable that will contain the vector of calculated Y values. Example ; Create two vectors of independent variable data: X1 = [1.0, 2.0, 4.0, 8.0, 16.0, 32.0] X2 = [0.0, 1.0, 2.0, 3.0, 4.0, 5.0] ; Combine into a 2x6 array X = [TRANSPOSE(X1), TRANSPOSE(X2)] ; Create a vector of dependent variable data: Y = 5 + 3*X1 - 4*X2 ; Assume Gaussian measurement errors for each point: measure_errors = REPLICATE(0.5, N_ELEMENTS(Y)) ; Compute the fit, and print the results: result = REGRESS(X, Y, SIGMA=sigma, CONST=const, $ MEASURE_ERRORS=measure_errors) PRINT, 'Constant: ', const PRINT, 'Coefficients: ', result[*] PRINT, 'Standard errors: ', sigma IDL prints: Constant: 4.99999 Coefficients: 3.00000 -3.99999 Standard errors: 0.0444831 0.282038 See Also CURVEFIT, GAUSSFIT, LINFIT, LMFIT, POLY_FIT, SFIT, SVDFIT REPEAT...UNTIL [Previous Routine] [Next Routine] [List of Routines] NAME: REPEAT...UNTIL The REPEAT...UNTIL statement repeats its subject statement(s) until an expression evaluates to true. The condition is checked after the subject statement is executed. Therefore, the subject statement is always executed at least once, even if the expression evaluates to true the first time. Note For information on using REPEAT_UNTIL and other IDL program control statements, see Chapter 11, "Program Control" in Building IDL Applications. Syntax REPEAT statement UNTIL expression or REPEAT BEGIN statements ENDREP UNTIL expression Example This example shows that because the subject of a REPEAT statement is evaluated before the expression, it is always executed at least once: i = 1 REPEAT BEGIN PRINT, i ENDREP UNTIL (i EQ 1) REPLICATE [Previous Routine] [Next Routine] [List of Routines] NAME: REPLICATE The REPLICATE function returns an array with the given dimensions, filled with the scalar value specified as the first parameter. Syntax Result = REPLICATE( Value, D1 [, ..., D8] ) Arguments Value The scalar value with which to fill the resulting array. The type of the result is the same as that of Value. Value can be any single element expression such as a scalar or 1 element array. This includes structures. Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. The dimensions of the result. Example Create D, a 5-element by 5-element array with every element set to the string "IDL" by entering: D = REPLICATE('IDL', 5, 5) REPLICATE can also be used to create arrays of structures. For example, the following command creates a structure named "emp" that contains a string name field and a long integer employee ID field: employee = {emp, NAME:' ', ID:0L} To create a 10-element array of this structure, enter: emps = REPLICATE(employee, 10) See Also MAKE_ARRAY REPLICATE_INPLACE [Previous Routine] [Next Routine] [List of Routines] NAME: REPLICATE_INPLACE The REPLICATE_INPLACE procedure updates an existing array by replacing all or selected parts of it with a specified value. REPLICATE_INPLACE can be faster and use less memory than the IDL function REPLICATE or the IDL array notation for large arrays that already exist. Note REPLICATE_INPLACE is much faster when operating on entire arrays and rows, than when used on columns or higher dimensions. Syntax REPLICATE_INPLACE, X, Value [, D1, Loc1 [, D2, Range]] Arguments X The array to be updated. X can be of any numeric type. REPLICATE_INPLACE does not change the size and type of X. Value The value which will fill all or part of X. Value may be any scalar or one-element array that IDL can convert to the type of X. REPLICATE_INPLACE does not change Value. D1 An optional parameter indicating which dimension of X is to be updated. Loc1 An array with the same number of elements as the number of dimensions of X. The Loc1 and D1 arguments together determine which one-dimensional subvector (or subvectors, if D1 and Range are provided) of X is to be updated. D2 An optional parameter, indicating in which dimension of X a group of one- dimensional subvectors are to be updated. D2 should be different from D1. Range An array of indices of dimension D2 of X, indicating where to put one-dimensional updates of X. Example ; Create a multidimensional zero array: A = FLTARR( 40, 90, 10) ; Populate it with the value 4.5. (i.e., A[*]= 4.5 ): REPLICATE_INPLACE, A, 4.5 ;Update a single subvector.(i.e., A[*,4,0]= 20. ): REPLICATE_INPLACE, A, 20, 1, [0,4,0] ; Update a group of subvectors.(i.e., A[ 0, [0, 5,89], * ] = -8 ): REPLICATE_INPLACE, A, -8, 3, [0,0,0], 2, [0,5,89] ; Update a 2-dimensional slice of A (i.e., A[9,*, *] = 0.): REPLICATE_INPLACE, A, 0., 3, [9,0,0] , 2, LINDGEN(90) See Also REPLICATE, BLAS_AXPY RESOLVE_ALL [Previous Routine] [Next Routine] [List of Routines] NAME: RESOLVE_ALL The RESOLVE_ALL procedure iteratively resolves (by compiling) any uncompiled user-written or library procedures or functions that are called in any already-compiled procedure or function. The process ends when there are no unresolved routines left to compile. If an unresolved procedure or function is not in the IDL search path, this routine exits with an error, and no additional routines are compiled. RESOLVE_ALL is useful when preparing SAVE/RESTORE files containing all the IDL routines required for an application. Note RESOLVE_ALL does not resolve procedures or functions that are called via CALL_PROCEDURE, CALL_FUNCTION, or EXECUTE. Class methods are not resolved either. Similarly, RESOLVE_ALL does not resolve widget event handler procedures based on a call to the widget routine that uses the event handler. In general, it is best to include the event handling routine in the same program file as the widget creation routine-building widget programs in this way ensures that RESOLVE_ALL will "catch" the event handler for a widget application. Note RESOLVE_ALL is of special interest when constructing an IDL SAVE file containing the compiled code for a package of routines. If you are constructing such a .sav file, that contains calls to built-in IDL system functions that are not present under all operating systems (e.g., IOCTL, TRNLOG), you must make sure to use FORWARD_FUNCTION to tell IDL that these names are functions. Otherwise, IDL may interpret them as arrays and generate unintended results. This routine is written in the IDL language. Its source code can be found in the file resolve_all.pro in the lib subdirectory of the IDL distribution. Syntax RESOLVE_ALL [, /CONTINUE_ON_ERROR] [, /QUIET] Keywords CONTINUE_ON_ERROR Set this keyword to allow continuation upon error. QUIET Set this keyword to suppress informational messages. See Also .COMPILE, RESOLVE_ROUTINE, ROUTINE_INFO RESOLVE_ROUTINE [Previous Routine] [Next Routine] [List of Routines] NAME: RESOLVE_ROUTINE The RESOLVE_ROUTINE procedure compiles user-written or library procedures or functions, given their names. Routines are compiled even if they are already defined. RESOLVE_ROUTINE looks for the given filename in IDL's search path. If the file is not found in the path, then the routine exits with an error. Syntax RESOLVE_ROUTINE, Name [, /COMPILE_FULL_FILE ] [, /EITHER | , /IS_FUNCTION] [, /NO_RECOMPILE] Arguments Name A scalar string or string array containing the name or names of the procedures to compile. If Name contains functions rather than procedures, set the IS_FUNCTION keyword. The Name argument cannot contain the path to the .pro file-it must contain only a .pro filename. If you want to specify a path to the .pro file, use the .COMPILE executive command. Keywords COMPILE_FULL_FILE When compiling a file to find a specified routine, IDL normally stops compiling when the desired routine (Name) is found. If set, COMPILE_FULL_FILE compiles the entire file. EITHER If set, indicates that the caller does not know whether the supplied routine names are functions or procedures, and will accept either. This keyword overrides the IS_FUNCTION keyword. IS_FUNCTION Set this keyword to compile functions rather than procedures. NO_RECOMPILE Normally, RESOLVE_ROUTINE compiles all specified routines even if they have already been compiled. Setting NO_RECOMPILE indicates that such routines are not recompiled. See Also .COMPILE, RESOLVE_ALL, ROUTINE_INFO RESTORE [Previous Routine] [Next Routine] [List of Routines] NAME: RESTORE The RESTORE procedure restores the IDL variables and routines saved in a file by the SAVE procedure. Warning While files containing IDL variables can be restored by any version of IDL that supports the data types of the variables (in particular, by any version of IDL later than the version that created the SAVE file), files containing IDL routines can only be restored by versions of IDL that share the same internal code representation. Since the internal code representation changes regularly, you should always archive the IDL language source files (.pro files) for routines you are placing in IDL SAVE files so you can recompile the code when a new version of IDL is released. Note to VMS Users When reading older VMS format files, IDL knows that all floating-point values are in VAX format. These floating values are automatically converted to IEEE format. Only VMS/IDL is able to restore the native VMS format. Note If you are restoring a file created with VAX IDL version 1, you must restore on a machine running VMS. Syntax RESTORE [, Filename] [, FILENAME=name] [, /RELAXED_STRUCTURE_ASSIGNMENT] [, RESTORED_OBJECTS=variable] [, /VERBOSE] Arguments Filename A scalar string that contains the name of the file from which the IDL objects should be restored. If not present, the file idlsave.dat is used. Keywords FILENAME The name of the file from which the IDL objects should be restored. If not present, the file idlsave.dat is used. This keyword serves exactly the same purpose as the Filename argument-only one of them needs to be provided. RELAXED_STRUCTURE_ASSIGNMENT Normally, RESTORE is unable to restore a structure variable if the definition of its type has changed since the SAVE file was written. A common case where this occurs is when objects are saved and the class structure of the objects change before they are restored in another IDL session. In such cases, RESTORE issues an error, skips the structure, and continues restoring the remainder of the SAVE file. Setting the RELAXED_STRUCTURE_ASSIGNMENT keyword causes RESTORE to restore such incompatible values using "relaxed structure assignment," in which all possible data are restored using a field-by-field copy. (See the description of the STRUCT_ASSIGN procedure for additional details.) RESTORED_OBJECTS Set this keyword equal to a named variable that will contain an array of object references for any objects restored. The resulting list of objects is useful for programmatically calling the objects' restore methods. If no objects are restored, the variable will contain a null object reference. VERBOSE Set this keyword to have IDL print an informative message for each restored object. Example Suppose that you have saved all the variables from a previous IDL session with the command: SAVE, /VARIABLES, FILENAME = 'session1.sav' The variables in the file session1.sav can be restored by entering: RESTORE, 'session1.sav' See Also JOURNAL, SAVE, STRUCT_ASSIGN RETALL [Previous Routine] [Next Routine] [List of Routines] NAME: RETALL The RETALL command returns control to the main program level. The effect is the same as entering the RETURN command at the interactive command prompt until the main level is reached. Syntax RETALL Arguments None See Also RETURN RETURN [Previous Routine] [Next Routine] [List of Routines] NAME: RETURN The RETURN command causes the program context to revert to the next-higher program level. RETURN can be called at the interactive command prompt (see ".RETURN" on page 56), inside a procedure definition, or inside a function definition. Calling RETURN from the main program level has no effect other than to print an informational message in the command log. Calling RETURN inside a procedure definition returns control to the calling routine, or to the main level. Since the END statement in a procedure definition also returns control to the calling routine, it is only necessary to use RETURN in a procedure definition if you wish control to revert to the calling routine before the procedure reaches its END statement. In a function definition, RETURN serves to define the value passed out of the function. Only a single value can be returned from a function. Note The value can be an array or structure containing multiple data items. Syntax RETURN [, Return_value] Arguments Return_value In a function definition, the Return_value is the value passed out of the function when it completes its processing. Return values are not allowed in procedure definitions, or when calling RETURN at the interactive command prompt. Examples You can use RETURN within a procedure definition to exit the procedure at some point other than the end. For example, note the following procedure: PRO RET_EXAMPLE, value IF value THEN BEGIN PRINT, value, ' is nonzero' RETURN END PRINT, 'Input argument was zero.' END If the input argument is non-zero, the routine prints the value and exits back to the calling procedure or main level. If the input argument is zero, control proceeds until the END statement is reached. When defining functions, use RETURN to specify the value returned from the function. For example, the following function: FUNCTION RET_EXAMPLE2, value RETURN, value * 2 END multiplies the input value by two and returns the result. If this function is defined at the main level, calling it from the IDL command prompt produces the following: PRINT, RET_EXAMPLE2(4) IDL prints: 8 See Also RETALL REVERSE [Previous Routine] [Next Routine] [List of Routines] NAME: REVERSE The REVERSE function reverses the order of one dimension of an array. This routine is written in the IDL language. Its source code can be found in the file reverse.pro in the lib subdirectory of the IDL distribution. Syntax Result = REVERSE( Array [, Subscript_Index] [, /OVERWRITE] ) Arguments Array The array containing the original data. Subscript_Index An integer specifying the dimension index (1, 2, 3, etc.) that will be reversed. This argument must be less than or equal to the number of dimensions of Array. If this argument is omitted, the first subscript is reversed. Keywords OVERWRITE Set this keyword to conserve memory by doing the transformation "in-place." The result overwrites the previous contents of the array. This keyword is ignored for one- or two-dimensional arrays. Example Reverse the order of an array where each element is set to the value of its subscript: ; Create an array: A = [[0,1,2],[3,4,5],[6,7,8]] ; Print the array: PRINT, 'Original Array:' PRINT, A ; Reverse the columns of A. PRINT, 'Reversed Columns:' PRINT, REVERSE(A) ; Reverse the rows of A: PRINT, 'Reversed Rows:' PRINT, REVERSE(A, 2) IDL prints: Original Array: 0 1 2 3 4 5 6 7 8 Reversed Columns: 2 1 0 5 4 3 8 7 6 Reversed Rows: 6 7 8 3 4 5 0 1 2 See Also INVERT, REFORM, ROT, ROTATE, SHIFT, TRANSPOSE REWIND [Previous Routine] [Next Routine] [List of Routines] NAME: REWIND The REWIND procedure rewinds the tape on the designated IDL tape unit. REWIND is available only under VMS. See the description of the magnetic tape routines in "VMS-Specific Information" in Chapter 8 of Building IDL Applications. Syntax REWIND, Unit Arguments Unit The magnetic tape unit to rewind. Unit must be a number between 0 and 9, and should not be confused with standard file Logical Unit Numbers (LUNs). See Also SKIPF, TAPRD RK4 [Previous Routine] [Next Routine] [List of Routines] NAME: RK4 The RK4 function uses the fourth-order Runge-Kutta method to advance a solution to a system of ordinary differential equations one time-step H, given values for the variables Y and their derivatives Dydx known at X. RK4 is based on the routine rk4 described in section 16.1 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press, and is used by permission. Syntax Result = RK4( Y, Dydx, X, H, Derivs [, /DOUBLE] ) Arguments Y A vector of values for Y at X Dydx A vector of derivatives for Y at X. X A scalar value for the initial condition. H A scalar value giving interval length or step size. Derivs A scalar string specifying the name of a user-supplied IDL function that calculates the values of the derivatives Dydx at X. This function must accept two arguments: A scalar floating value X, and one n-element vector Y. It must return an n-element vector result. For example, suppose the values of the derivatives are defined by the following relations: dy0 / dx = ­0.5y0, dy1 / dx = 4.0 ­ 0.3y1 ­ 0.1y0 We can write a function DIFFERENTIAL to express these relationships in the IDL language: FUNCTION differential, X, Y RETURN, [-0.5 * Y[0], 4.0 - 0.3 * Y[1] - 0.1 * Y[0]] END Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. Example To integrate the example system of differential equations for one time step, H: ; Define the step size: H = 0.5 ; Define an initial X value: X = 0.0 ; Define initial Y values: Y = [4.0, 6.0] ; Calculate the initial derivative values: dydx = DIFFERENTIAL(X,Y) ; Integrate over the interval (0, 0.5): result = RK4(Y, dydx, X, H, 'differential') ; Print the result: PRINT, result IDL prints: 3.11523 6.85767 This is the exact solution vector to five-decimal precision. See Also BROYDEN, NEWTON ROBERTS [Previous Routine] [Next Routine] [List of Routines] NAME: ROBERTS The ROBERTS function returns an approximation to the Roberts edge enhancement operator for images: G jk = F jk ­ F j + 1, k + 1 + F j, k + 1 ­ F j + 1, k where (j, k) are the coordinates of each pixel Fjk in the Image. This is equivalent to a convolution using the masks, 0 ­1 and 1 0 1 0 0 ­1 where the underline indicates the current pixel Fjk. The last column and row are set to zero. Syntax Result = ROBERTS(Image) Return Value ROBERTS returns a two-dimensional array of the same size as Image. If Image is of type byte or integer, then the result is of integer type, otherwise the result is of the same type as Image. Note To avoid overflow for integer types, the computation is done using the next larger signed type and the result is transformed back to the correct type. Values larger than the maximum for that integer type are truncated. For example, for integers the function is computed using type long, and on output, values larger than 32767 are set equal to 32767. Arguments Image The two-dimensional array containing the image to which edge enhancement is applied. Example If the variable myimage contains a two-dimensional image array, a Roberts sharpened version of myimage can be displayed with the command: TVSCL, ROBERTS(myimage) See Also SOBEL ROT [Previous Routine] [Next Routine] [List of Routines] NAME: ROT The ROT function rotates an image by an arbitrary amount. At the same time, it can magnify, demagnify, and/or translate an image. Note that if you want to rotate an array by a multiple of 90 degrees, you should use the ROTATE function for faster results. This routine is written in the IDL language. Its source code can be found in the file rot.pro in the lib subdirectory of the IDL distribution. Syntax Result = ROT( A, Angle, [Mag, X0, Y0] [, /INTERP] [, CUBIC=value{-1 to 0}] [, MISSING=value] [, /PIVOT] ) Arguments A The image array to be rotated. This array can be of any type, but must have two dimensions. The output image has the same dimensions and data type of the input image. ANGLE Angle of rotation in degrees clockwise. MAG An optional magnification factor. A value of 1.0 results in no change. A value greater than one performs magnification and a value less than one performs demagnification. X0 X subscript for the center of rotation. If omitted, X0 equals the number of columns in the image divided by 2. Y0 Y subscript for the center of rotation. If omitted, Y0 equals the number of rows in the image divided by 2. Keywords INTERP Set this keyword to use bilinear interpolation. The default is to use nearest neighbor sampling. CUBIC Set this keyword to a value between -1 and 0 to use the cubic convolution interpolation method with the specified value as the interpolation parameter. Setting this keyword equal to a value greater than zero specifies a value of -1 for the interpolation parameter. Park and Schowengerdt (see reference below) suggest that a value of -0.5 significantly improves the reconstruction properties of this algorithm. Cubic convolution is an interpolation method that closely approximates the theoretically optimum sinc interpolation function using cubic polynomials. According to sampling theory, details of which are beyond the scope of this document, if the original signal, f, is a band-limited signal, with no frequency component larger than 0, and f is sampled with spacing less than or equal to 1/(2 0), then f can be reconstructed by convolving with a sinc function: sinc(x) = sin( x) / ( x). In the one-dimensional case, four neighboring points are used, while in the two- dimensional case 16 points are used. Note that cubic convolution interpolation is significantly slower than bilinear interpolation. For further details see: Rifman, S.S. and McKinnon, D.M., "Evaluation of Digital Correction Techniques for ERTS Images; Final Report", Report 20634-6003-TU-00, TRW Systems, Redondo Beach, CA, July 1974. S. Park and R. Schowengerdt, 1983 "Image Reconstruction by Parametric Cubic Convolution", Computer Vision, Graphics & Image Processing 23, 256. MISSING Set this keyword to a value to be substituted for pixels in the output image that map outside the input image. PIVOT Set this keyword to cause the image to pivot around the point (X0, Y0) so that this point maps into the same point in the output image. By default, the point (X0, Y0 ) in the input image is mapped into the center of the output image. Example ; Create a byte image: A = BYTSCL(DIST(256)) ; Display it: TV, A ; Rotate the image 33 degrees, magnify it 15 times, and use ; bilinear interpolation to make the output look nice: B = ROT(A, 33, 1.5, /INTERP) ; Display the rotated image: TV, B See Also ROTATE ROTATE [Previous Routine] [Next Routine] [List of Routines] NAME: ROTATE The ROTATE function returns a rotated and/or transposed copy of Array. ROTATE can only rotate arrays in multiples of 90 degrees. To rotate by amounts other than multiples of 90 degrees, use the ROT function. Note, however, that ROTATE is more efficient. ROTATE can also be used to reverse the order of elements in vectors. For example, to reverse the order of elements in the vector X, use the expression ROTATE(X,2). If X = [0,1,2,3] then ROTATE(X,2)yields the resulting array, [3,2,1,0]. Transposition is performed before rotation. Rotations are viewed with the first row at the top. Syntax Result = ROTATE(Array, Direction) Arguments Array The array to be rotated. Array can have only one or two dimensions. The result has the same type as Array. The dimensions of the result are the same as those of Array if Direction is equal to 0 or 2. The dimensions are transposed if the direction is 4 or greater. Direction Direction specifies the operation to be performed as follows: Direction Transpose ? Rotation Counterclockwise X1 Y1 0 No None X0 Y0 1 No 90 -Y0 X0 2 No 180 -X0 -Y0 3 No 270 Y0 -X0 4 Yes None Y0 X0 Table 82: Rotation Directions Direction Transpose ? Rotation Counterclockwise X1 Y1 5 Yes 90 -X0 Y0 6 Yes 180 -Y0 -X0 7 Yes 270 X0 -Y0 Table 82: Rotation Directions In the table above, (X0, Y0) are the original subscripts, and (X1, Y1) are the subscripts of the resulting array. The notation -Y0 indicates a reversal of the Y axis, Y1 = Ny - Y0 - 1. Direction is taken modulo 8, so a rotation of -1 is the same as 7, 9 is the same as 1, etc. Note The assertion that Array is rotating counterclockwise may cause some confusion. Remember that when arrays are displayed on the screen (using TV or TVSCL, for example), the image is drawn with the origin (0,0) at the bottom left corner of the window. When arrays are printed on the console or command log window (using the PRINT command, for example), the (0,0) element is drawn in the upper left corner of the array. This means that while an image displayed in a window appears to rotate counterclockwise, an array printed in the command log appears to rotate clockwise. Example Create and display a wedge image by entering: F = REPLICATE(1, 256) # FINDGEN(256) & TVSCL, F To display the image rotated 90 degrees counterclockwise, enter: TVSCL, ROTATE(F, 1) See Also ROT, TRANSPOSE ROUND [Previous Routine] [Next Routine] [List of Routines] NAME: ROUND The ROUND function rounds the argument to its closest integer. Syntax Result = ROUND(X [, /L64 ] ) Return Value Returns the integer closest to its argument. If the input value X is integer type, Result has the same value and type as X. Otherwise, Result is returned as a 32-bit longword integer with the same structure as X. Arguments X The value for which the ROUND function is to be evaluated. This value can be any numeric type (integer, floating, or complex). Note that only the real part of a complex argument is rounded and returned. Keywords L64 If set, the result type is 64-bit integer no matter what type the input has. This is useful for situations in which a floating point number contains a value too large to be represented in a 32-bit integer. Example Print the rounded values of a 2-element vector: PRINT, ROUND([5.1, 5.9]) IDL prints: 5 6 Print the result of rounding 3000000000.1, a value that is too large to represent in a 32-bit integer: PRINT, ROUND(3000000000.1D, /L64) IDL prints: 3000000000 See Also CEIL, COMPLEXROUND, FLOOR ROUTINE_INFO [Previous Routine] [Next Routine] [List of Routines] NAME: ROUTINE_INFO The ROUTINE_INFO function provides information about currently-compiled procedures and functions. It returns a string array consisting of the names of defined procedures or functions, or of parameters or variables used by a single procedure or function. Syntax Result = ROUTINE_INFO( [Routine [[, /PARAMETERS{must specify Routine}] [, /SOURCE ] [, /UNRESOLVED] [, /VARIABLES] | , /SYSTEM]] [, /DISABLED] [, /ENABLED] [, /FUNCTIONS] ) Arguments Routine A scalar string containing the name of routine for which information will be returned. Routine can be either a procedure or a function. If Routine is not supplied, ROUTINE_INFO returns a list of all currently-compiled procedures. Keywords DISABLED Set this keyword to get the names of currently disabled system procedures or functions (in conjunction with the FUNCTIONS keyword). Use of DISABLED implies use of the SYSTEM keyword, since user routines cannot be disabled. ENABLED Set this keyword to get the names of currently enabled system procedures or functions (in conjunction with the FUNCTIONS keyword). Use of ENABLED implies use of the SYSTEM keyword, since user routines cannot be disabled. FUNCTIONS Set this keyword to return a string array containing currently-compiled functions. By default, ROUTINE_INFO returns a list of compiled procedures. If the SYSTEM keyword is also set, ROUTINE_INFO returns a list of all IDL built-in internal functions. PARAMETERS Set this keyword to return an anonymous structure with the following fields: * NUM_ARGS - An integer containing the number of positional parameters used in Routine. * NUM_KW_ARGS - An integer containing the number of keyword parameters used in Routine. * ARGS - A string array containing the names of the positional parameters used in Routine. * KW_ARGS - A string array containing the names of the keyword parameters used in Routine. You must supply the Routine argument when using this keyword. Note that specifying the SYSTEM keyword along with this keyword will generate an error. If Routine does not take any arguments, the ARGS field is not included in the anonymous structure. Similarly, if Routine does not take any keywords, the KW_ARGS field is not included. SOURCE Set this keyword to return an array of anonymous structures with the following fields: * NAME - A string containing the name of the procedure or function. * PATH - A string containing the full path specification of the file that contains the definition of the procedure or function. If Routine is specified, information for that one routine is returned. If Routine is not specified, information for all compiled routines is returned. If a routine is unresolved or its path information is unavailable, the PATH field will contain a null string. If a routine has been SAVEd and then RESTOREd, the PATH field will contain the path to the SAVE file. Note Specifying the SYSTEM keyword along with this keyword will generate an error. SYSTEM Set this keyword to return a string array listing all IDL built-in internal procedures. Built-in internal procedures are part of the IDL executable, and are not written in the IDL language. If the FUNCTIONS keyword is also set, ROUTINE_INFO returns a list of all IDL built-in internal functions. UNRESOLVED Set this keyword to return a string array listing procedures that are referenced in any currently-compiled procedure or function, but which are themselves not yet compiled. If the FUNCTIONS keyword is also set, ROUTINE_INFO returns a list of functions that are referenced but not yet compiled. Note that specifying the SYSTEM keyword along with this keyword will generate an error. VARIABLES Set this keyword to return a string array listing variables defined in the procedure or function. You must supply the Routine argument when using this keyword. Note that specifying the SYSTEM keyword along with this keyword will generate an error. See Also RESOLVE_ALL, RESOLVE_ROUTINE RS_TEST [Previous Routine] [Next Routine] [List of Routines] NAME: RS_TEST The RS_TEST function tests the hypothesis that two sample populations X and Y have the same mean of distribution against the hypothesis that they differ. X and Y may be of different lengths. The result is a two-element vector containing the nearly- normal test statistic Z and the one-tailed probability of obtaining a value of Z or greater. This type of test is often referred to as the "Wilcoxon Rank-Sum Test" or the "Mann-Whitney U-Test." The Mann-Whitney statistics for X and Y are defined as follows: N ( + ) U x Nx 1 x = NxNy + ---------------------------- ­ W 2 x N ( + ) U y Ny 1 y = NxNy + ---------------------------- ­ W 2 y where Nx and Ny are the number of elements in X and Y, respectively, and Wx and Wy are the rank sums for X and Y, respectively. The test statistic Z, which closely follows a normal distribution for sample sizes exceeding 10 elements, is defined as follows: U ­ ( ) 2 Z x NxNy = -------------------------------- (NxNy(Nx + Ny + 1)) 12 This routine is written in the IDL language. Its source code can be found in the file rs_test.pro in the lib subdirectory of the IDL distribution. Syntax Result = RS_TEST( X, Y [, UX=variable] [, UY=variable] ) Arguments X An n-element integer, single-, or double-precision floating-point vector. Y An m-element integer, single-, or double-precision floating-point vector. Keywords UX Set this keyword to a named variable that will contain the Mann-Whitney statistic for X. UY Set this keyword to a named variable that will contain the Mann-Whitney statistic for Y. Example ; Define two sample populations: X = [-14, 3, 1, -16, -21, 7, -7, -13, -22, -17, -14, -8, $ 7, -18, -13, -9, -22, -25, -24, -18, -13, -13, -18, -5] Y = [-18, -9, -16, -14, -3, -9, -16, 10, -11, -3, -13, $ -21, -2, -11, -16, -12, -13, -6, -9, -7, -11, -9] ; Test the hypothesis that two sample populations, {xi, yi}, have ; the same mean of distribution against the hypothesis in that they ; differ at the 0.05 significance level: PRINT, RS_TEST(X, Y, UX = ux, UY = uy) ; Print the Mann-Whitney statistics: PRINT, 'Mann-Whitney Statistics: Ux = ', ux, ', Uy = ', uy IDL prints: [1.45134, 0.0733429] Mann-Whitney Statistics: Ux = 330.000, Uy = 198.000 The computed probability (0.0733429) is greater than the 0.05 significance level and therefore we do not reject the hypothesis that X and Y have the same mean of distribution. See Also FV_TEST, KW_TEST, S_TEST, TM_TEST S_TEST [Previous Routine] [Next Routine] [List of Routines] NAME: S_TEST The S_TEST function tests the hypothesis that two sample populations X and Y have the same mean of distribution against the hypothesis that they differ. The result is a two-element vector containing the maximum number of signed differences between corresponding pairs of xi and yi and its one-tailed significance. This type of test is often referred to as the "Sign Test." This routine is written in the IDL language. Its source code can be found in the file s_test.pro in the lib subdirectory of the IDL distribution. Syntax Result = S_TEST( X, Y [, ZDIFF=variable] ) Arguments X An n-element integer, single-, or double-precision floating-point vector. Y An n-element integer, single-, or double-precision floating-point vector. Keywords ZDIFF Set this keyword to a named variable that will contain the number of differences between corresponding pairs of xi and yi resulting in zero. Paired data resulting in a difference of zero are excluded from the ranking and the sample size is correspondingly reduced. Example ; Define two n-element sample populations: X = [47, 56, 54, 49, 36, 48, 51, 38, 61, 49, 56, 52] Y = [71, 63, 45, 64, 50, 55, 42, 46, 53, 57, 75, 60] ; Test the hypothesis that the two sample populations have the same ; mean of distribution against the hypothesis that they differ at ; the 0.05 significance level: PRINT, S_TEST(X, Y, ZDIFF = zdiff) IDL prints: [9.00000, 0.0729981] The computed probability (0.0729981) is greater than the 0.05 significance level and therefore we do not reject the hypothesis that X and Y have the same mean of distribution. See Also FV_TEST, KW_TEST, MD_TEST, RS_TEST, TM_TEST SAVE [Previous Routine] [Next Routine] [List of Routines] NAME: SAVE The SAVE procedure saves variables, system variables, and IDL routines in a file using the XDR (eXternal Data Representation) format for later recovery by RESTORE. Note that variables and routines cannot be saved in the same file. Note also that save files containing routines may not be compatible between different versions of IDL, but that files containing data are always backwards-compatible. Syntax SAVE [, Var1, ..., Varn] [, /ALL] [, /COMM, /VARIABLES] [, /COMPRESS] [, FILENAME=string] [, ROUTINES] [, /SYSTEM_VARIABLES] [, /VERBOSE] Arguments Varn Optional named variables that are to be saved. Keywords ALL Set this keyword to save all common blocks, system variables, and local variables from the current IDL session. Note Routines and variables cannot be saved in the same file. Setting the ALL keyword does not save routines. COMM Set this keyword to save all main level common block definitions. Note that setting this keyword does not cause the contents of the common block to be saved unless the VARIABLES keyword is also set. COMPRESS If COMPRESS is set, IDL writes all data to the SAVE file using the ZLIB compression library to reduce its size. IDL's save file compression support is based on the freely available ZLIB library version 1.1.3 by Mark Adler and Jean-loup Gailly. Compressed save files can be restored by the RESTORE procedure in exactly the same manner as any other save file. The only visible differences are that the files will be smaller, and writing and reading them will be somewhat slower under typical conditions. FILENAME A string containing the name of the file into which the IDL objects should be saved. If this keyword is not specified, the file idlsave.dat is used. ROUTINES Set this keyword to save user defined procedures and functions in a machine independent, binary form. If parameters are present, they must be strings containing the names of the procedures and/or functions to be saved. If no parameters are present, all compiled routines are saved. If you are using VMS, see the XDR keyword below. Routines and variables cannot be saved in the same file. Warning Because SAVE stores routines in a binary format, save files containing routines are not guaranteed to be compatible between successive versions of IDL. You will not be able to RESTORE save files containing routines if they are made with incompatible versions of IDL. In this case, you should recompile your original code with the newer version of IDL. Save files containing data will always be restorable. SYSTEM_VARIABLES Set this keyword to save the current state of all system variables. Warning Saving system variables is not recommended, as the structure may change between versions of IDL. VARIABLES Set this keyword to save all variables in the current program unit. This option is the default. VERBOSE Set this keyword to print an informative message for each saved object. Example Save the status of all currently-defined variables in the file variables1.dat by entering: SAVE, /VARIABLES, FILENAME = 'variables1.dat' The variables can be restored with the RESTORE procedure. Save the user procedures MYPROC and MYFUN: SAVE, /ROUTINES, 'MYPROC', 'MYFUN' See Also JOURNAL, RESOLVE_ALL, RESTORE SAVGOL [Previous Routine] [Next Routine] [List of Routines] NAME: SAVGOL The SAVGOL function returns the coefficients of a Savitzky-Golay smoothing filter, which can then be applied using the CONVOL function. The Savitzky-Golay smoothing filter, also known as least squares or DISPO (digital smoothing polynomial), can be used to smooth a noisy signal. The filter is defined as a weighted moving average with weighting given as a polynomial of a certain degree. The returned coefficients, when applied to a signal, perform a polynomial least-squares fit within the filter window. This polynomial is designed to preserve higher moments within the data and reduce the bias introduced by the filter. The filter can use any number of points for this weighted average. This filter works especially well when the typical peaks of the signal are narrow. The heights and widths of the curves are generally preserved. Tip You can use this function in conjunction with the CONVOL function for smoothing and optionally for numeric differentiation. This routine is written in the IDL language. Its source code can be found in the file savgol.pro in the lib subdirectory of the IDL distribution. SAVGOL is based on the Savitzky-Golay Smoothing Filters described in section 14.8 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press, and is used by permission. Syntax Result = SAVGOL( Nleft, Nright, Order, Degree [, /DOUBLE] ) Return Value This function returns an array of floating-point numbers that are the coefficients of the smoothing filter. Arguments Nleft An integer specifying the number of data points to the left of each point to include in the filter. Nright An integer specifying the number of data points to the right of each point to include in the filter. Note Larger values of Nleft and Nright produce a smoother result at the expense of flattening sharp peaks. Order An integer specifying the order of the derivative desired. For smoothing, use order 0. To find the smoothed first derivative of the signal, use order 1, for the second derivative, use order 2, etc. Note Order must be less than or equal to the value specified for Degree. Degree An integer specifying the degree of smoothing polynomial. Typical values are 2 to 4. Lower values for Degree will produce smoother results but may introduce bias, higher values for Degree will reduce the filter bias, but may "over fit" the data and give a noisier result. Note Degree must be less than the filter width (Nleft + Nright + 1). Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. Tip The DOUBLE keyword is recommended for Degree greater than 9. Example The following example creates a noisy 400-point vector with 4 Gaussian peaks of decreasing width. It then plots the original vector, the vector smoothed with a 33- point Boxcar smoother (the SMOOTH function), and the vector smoothed with 33- point wide Savitzky-Golay filter of degree 4. The bottom plot shows the first derivative of the noisy signal and the first derivative using the Savitzky-Golay filter of degree 4: n = 401 ; number of points np = 4 ; number of peaks ; Form the baseline: y = REPLICATE(0.5, n) ; Index the array: x = FINDGEN(n) ; Add each Gaussian peak: FOR i=0, np-1 DO BEGIN c = (i + 0.5) * FLOAT(n)/np ; Center of peak peak = -(3 * (x-c) / (75. / 1.5 ^ i))^2 ; Add Gaussian. Cutoff of -50 avoids underflow errors for ; tiny exponentials: y = y + EXP(peak>(-50)) ENDFOR ; Add noise: y1 = y + 0.10 * RANDOMN(-121147, n) !P.MULTI=[0,1,3] ; Boxcar smoothing width 33: PLOT, x, y1, TITLE='Signal+Noise; Smooth (width33)' OPLOT, SMOOTH(y1, 33, /EDGE_TRUNCATE), THICK=3 ; Savitzky-Golay with 33, 4th degree polynomial: savgolFilter = SAVGOL(16, 16, 0, 4) PLOT, x, y1, TITLE='Savitzky-Golay (width 33, 4th degree)' OPLOT, x, CONVOL(y1, savgolFilter, /EDGE_TRUNCATE), THICK=3 ; Savitzky-Golay width 33, 4th degree, 1st derivative: savgolFilter = SAVGOL(16, 16, 1, 4) PLOT, x, DERIV(y1), YRANGE=[-0.2, 0.2], TITLE=$ 'First Derivative: Savitzky-Golay(width 33, 4th degree, order 1)' OPLOT, x, CONVOL(y1, savgolFilter, /EDGE_TRUNCATE), THICK=3 The following is the resulting plot. Notice how the Savitzky-Golay filter preserves the high peaks but does not do as much smoothing on the flatter regions. Note also that the Savitzky-Golay filter is able to construct a good approximation of the first derivative. Figure 19: SAVGOL Example See Also CONVOL, DIGITAL_FILTER, SMOOTH SCALE3 [Previous Routine] [Next Routine] [List of Routines] NAME: SCALE3 The SCALE3 procedure sets up transformation and scaling parameters for basic 3D viewing. This procedure is similar to SURFR and SCALE3D, except that the data ranges must be specified and the scaling does not vary with rotation. Results are stored in the system variables !P.T, !X.S, !Y.S, and !Z.S. This routine is written in the IDL language. Its source code can be found in the file scale3.pro in the lib subdirectory of the IDL distribution. Syntax SCALE3 [, XRANGE=vector] [, YRANGE=vector] [, ZRANGE=vector] [, AX=degrees] [, AZ=degrees] Keywords XRANGE A two-element vector containing the minimum and maximum X values. If omitted, the X-axis scaling remains unchanged. YRANGE A two-element vector containing the minimum and maximum Y values. If omitted, the Y-axis scaling remains unchanged. ZRANGE A two-element vector containing the minimum and maximum Z values. If omitted, the Z-axis scaling remains unchanged. AX Angle of rotation about the X axis. The default is 30 degrees. AZ Angle of rotation about the Z axis. The default is 30 degrees. Example Set up a 3D transformation where the data range is 0 to 20 for each of the 3 axes and the viewing area is rotated 20 degrees about the X axis and 55 degrees about the Z axis: SCALE3, XRANGE=[0, 20], YRANGE=[0, 20], ZRANGE=[0, 20], AX=20, AZ=55 See Also SCALE3D, SURFR, T3D SCALE3D [Previous Routine] [Next Routine] [List of Routines] NAME: SCALE3D The SCALE3D procedure scales the 3D unit cube (a cube with the length of each side equal to 1) into the viewing area. Eight data points are created at the vertices of the 3D unit cube. The vertices are then transformed by the value of the system variable !P.T. The system is translated to bring the minimum (x,y,z) point to the origin, and then scaled to make each coordinate's maximum value equal to 1. The !P.T system variable is modified as a result. This routine is written in the IDL language. Its source code can be found in the file scale3D.pro in the lib subdirectory of the IDL distribution. Syntax SCALE3D See Also SCALE3, SURFR, T3D SEARCH2D [Previous Routine] [Next Routine] [List of Routines] NAME: SEARCH2D The SEARCH2D function finds "objects" or regions of similar data values within a two-dimensional array. Given a starting location and a range of values to search for, SEARCH2D finds all the cells within the array that are within the specified range and have some path of connectivity through these cells to the starting location. In addition to searching for cells within a global range of data values, SEARCH2D can also search for adjacent cells whose values deviate from their neighbors within specified tolerances. SEARCH2D returns a longword array that contains a list of the array subscripts that define the located object or region. The original X and Y indices of the array subscripts returned by SEARCH2D can be found with the following IDL code: index_y = Result / (SIZE(Array))(1) index_x = Result - (index_y * (SIZE(Array))(1)) where Result is the array returned by SEARCH2D and Array is the original input array. The object within Array can be subscripted as Array(Region) or Array(index_x, index_y). This routine is written in the IDL language. Its source code can be found in the file search2d.pro in the lib subdirectory of the IDL distribution. Syntax Result = SEARCH2D( Array, Xpos, Ypos, Min_Val, Max_Val [, /DECREASE, /INCREASE [, LPF_BAND=integer{ 3}]] [, /DIAGONAL] ) Arguments Array A two-dimensional array, of any data type, to be searched. Xpos The X coordinate (dimension 0 of Array) of the starting location. Ypos The Y coordinate (dimension 1 of Array) of the starting location. Min_Val The minimum data value for which to search. All array subscripts of all cells that are connected to the starting cell, and have a value between Min_Val and Max_Val (inclusive) are returned. Max_Val The maximum data value for which to search. Keywords DECREASE This keyword and the INCREASE keyword allow you to compensate for changing intensities of data values within an object. An edge-enhanced copy of Array is made and compared to the orginal array if this keyword is set. When DECREASE or INCREASE is set, any adjacent cells are found if their corresponding data values in the edge enhanced array are greater than DECREASE and less than INCREASE. In any case, the adjacent cells will never be selected if their data values are not between Min_Val and Max_Val. The default for this keyword is 0.0 if INCREASE is specified. INCREASE This keyword and the DECREASE keyword allow you to compensate for changing intensities of data values within an object. An edge-enhanced copy of Array is made and compared to the orginal array if this keyword is set. When DECREASE or INCREASE is set, any adjacent cells are found if their corresponding data values in the edge enhanced array are greater than DECREASE and less than INCREASE. In any case, the adjacent cells will never be selected if their data values are not between Min_Val and Max_Val. The default for this keyword is 0.0 if DECREASE is specified. LPF_BAND Set this keyword to an integer value of 3 or greater to perform low-pass filtering on the edge-enhanced array. The value of LPF_BAND is used as the width of the smoothing window. This keyword is only effective when the DECREASE or INCREASE keywords are also specified. The default is no smoothing. DIAGONAL Set this keyword to cause SEARCH2D to find cells meeting the search criteria whose surrounding squares share a common corner. Normally, cells are considered adjacent only when squares surrounding the cells share a common edge. Setting this option requires more memory and execution time. Example Find all the indices corresponding to an object in an image: ; Create an image with different valued regions: img = FLTARR(512, 512) img[3:503, 9:488] = 0.7 img[37:455, 18:438] = 0.5 img[144:388, 90:400] = 0.7 img[200:301, 1:255] = 1.0 img[155:193, 333:387] = 0.3 TVSCL, img;Display the image. ; Search for an object starting at (175, 300) whose data values are ; between (0.6) and (0.8): region = SEARCH2D(img, 175, 300, 0.6, 0.8, /DIAGONAL) ; Scale the background cells into the range 0 to 127: img = BYTSCL(img, TOP=127B) ; Highlight the object region by setting it to 255: img[region] = 255B ; Display the array with the highlighted object in it: TVSCL, img See Also SEARCH3D SEARCH3D [Previous Routine] [Next Routine] [List of Routines] NAME: SEARCH3D The SEARCH3D function finds "objects" or regions of similar data values within a 3D array of data. Given a starting location and a range of values to search for, SEARCH3D finds all the cells within the volume that are within the specified range of values and have some path of connectivity through these cells to the starting location. In addition to searching for cells within a global range of data values, SEARCH3D can also search for adjacent cells whose values deviate from their neighbors within specified tolerances. SEARCH3D returns a longword array that contains a list of the array subscripts that define the selected object or region. The original X and Y indices of the array subscripts returned by SEARCH3D can be found with the following IDL code: S = SIZE(Array) index_z = Result / (S[1] * S[2]) index_y = (Result - (index_z * S[1] * S[2])) / S[1] index_x = (Result - (index_z * S[1] * S[2])) - (index_y * S[1]) where Result is the array returned by SEARCH3D and Array is the original input volume. The object within Array can be subscripted as Array[Region] or Array[index_x, index_y, index_z]. This routine is written in the IDL language. Its source code can be found in the file search3d.pro in the lib subdirectory of the IDL distribution. Syntax Result = SEARCH3D( Array, Xpos, Ypos, Zpos, Min_Val, Max_Val [, /DECREASE, /INCREASE [, LPF_BAND=integer{ 3}]] [, /DIAGONAL] ) Arguments Array The three-dimensional array, of any data type except string, to be searched. Xpos The X coordinate (dimension 0 or Array) of the starting location. Ypos The Y coordinate (dimension 1 of Array) of the starting location. Zpos The Z coordinate (dimension 2 of Array) of the starting location. Min_Val The minimum data value for which to search. All array subscripts of all the cells that are connected to the starting cell, and have a value between Min_Val and Max_Val (inclusive) are returned. Max_Val The maximum data value for which to search. Keywords DECREASE This keyword and the INCREASE keyword allow you to compensate for changing intensities of data values within an object. An edge-enhanced copy of Array is made and compared to the orginal array if this keyword is set. When DECREASE or INCREASE is set, any adjacent cells are found if their corresponding data values in the edge enhanced array are greater than DECREASE and less than INCREASE. In any case, the adjacent cells will never be selected if their data values are not between Min_Val and Max_Val. The default for this keyword is 0.0 if INCREASE is specified. INCREASE This keyword and the DECREASE keyword allow you to compensate for changing intensities of data values within an object. An edge-enhanced copy of Array is made and compared to the orginal array if this keyword is set. When DECREASE or INCREASE is set, any adjacent cells are found if their corresponding data values in the edge enhanced array are greater than DECREASE and less than INCREASE. In any case, the adjacent cells will never be selected if their data values are not between Min_Val and Max_Val. The default for this keyword is 0.0 if DECREASE is specified. LPF_BAND Set this keyword to an integer value of 3 or greater to perform low-pass filtering on the edge-enhanced array. The value of LPF_BAND is used as the width of the smoothing window. This keyword is only effective when the DECREASE or INCREASE keywords are also specified. The default is no smoothing. DIAGONAL Set this keyword to cause SEARCH3D to find cells meeting the search criteria whose surrounding cubes share a common corner or edge. Normally, cells are considered adjacent only when cubes surrounding the cells share a common edge. Setting this option requires more memory and execution time. Example Find all the indices corresponding to an object contained in a 3D array: ; Create some data. vol = RANDOMU(s, 40, 40, 40) vol[3:13, 1:15, 17:33] = 1.3 vol[15:25, 5:25, 15:25] = 0.2 vol[5:30,17:38,7:28] = 1.3 vol[9:23, 16:27, 7:33] = 1.5 ; Search for an object starting at (6, 22, 16) whose data values ; are between (1.2) and (1.4): region = SEARCH3D(vol, 6, 22, 16, 1.2, 1.4, /DIAGONAL) ; Scale the background cells into the range 0 to 127: vol = BYTSCL(vol, TOP=127B) ; Highlight the object region by setting it to 255: vol[Region] = 255B WINDOW, 0, XSIZE=640, YSIZE=512, RETAIN=2 ; Set up a 3-D view: CREATE_VIEW, XMAX=39, YMAX=39, ZMAX=39, AX=(-30), AZ=30, ZOOM=0.8 ; Display the volume with the highlighted object in it: TVSCL, PROJECT_VOL(vol, 64, 64, 40, DEPTH_Q=0.4) See Also SEARCH2D SET_PLOT [Previous Routine] [Next Routine] [List of Routines] NAME: SET_PLOT The SET_PLOT procedure sets the output device used by the IDL graphics procedures. Keyword parameters control how the color tables are transferred to the newly selected graphics device. SET_PLOT performs the following actions: * It sets the read-only system variable !D to reflect the configuration of the new device. * It sets the default color !P.COLOR to the maximum color index minus one or, in the case of devices with white backgrounds, such as PostScript, to 0 (black). * If the COPY keyword is set, the device color tables are copied directly from IDL's internal color tables. If the new device's color tables contain more indices than those of the old device, the new device's tables are not completely filled. * If the INTERPOLATE keyword is set, the internal color tables are interpolated to fill the range of the new device. * It sets the clipping rectangle to the entire device surface. Warning After calling SET_PLOT to change graphics devices, the scaling contained in the axis structures !X, !Y, and !Z is invalid. Any routines that rely on data coordinates should not be called until a new data coordinate system has been established. Be careful when switching devices as the number of color indices frequently differs between devices. When in doubt, reload the color table of the new device explicitly. Syntax SET_PLOT, Device [, /COPY] [, /INTERPOLATE] Arguments Device A scalar string containing the name of the device to use. The case of Device is ignored by IDL. See Appendix B, "IDL Graphics Devices" for a list of device names. Keywords COPY Set this keyword to copy the device's color table from the internal color table, preserving the current color mapping. The default is not to load the color table upon selection. Warning Unless this keyword is set, IDL's internal color tables will incorrectly reflect the state of the device's color tables until they are reloaded by TVLCT or the LOADCT procedure. Assuming that the previously-selected device's color table contains M elements, and the new device's color table contains N elements, then the minimum of M and N elements are loaded. INTERPOLATE Set this keyword to indicate that the current contents of the internal color table should be interpolated to cover the range of the newly-selected device. Otherwise, the internal color tables are not changed. Example Change the IDL graphics device to PostScript by entering: SET_PLOT, 'PS' After changing the plotting device, all graphics commands are sent to that device until changed again by another use of the SET_PLOT routine. SET_SHADING [Previous Routine] [Next Routine] [List of Routines] NAME: SET_SHADING The SET_SHADING procedure modifies the light source shading parameters that affect the output of SHADE_SURF and POLYSHADE. Parameters can be changed to control the light-source direction, shading method, and the rejection of hidden surfaces. SET_SHADING first resets the shading parameters to their default values. The parameter values specified in the call then overwrite the default values. To reset all parameters to their default values, simply call this procedure with no parameters. Syntax SET_SHADING [, /GOURAUD] [, LIGHT=[x, y, z]] [, /REJECT] [, VALUES=[darkest, brightest]] Arguments None. Keywords GOURAUD This keyword controls the method of shading the surface polygons by the POLYSHADE procedure. The SHADE_SURF procedure always uses the Gouraud method. Set this keyword to a nonzero value (the default), to use Gouraud shading. Set this keyword to zero to shade each polygon with a constant intensity. Gouraud shading interpolates intensities from each vertex along each edge. Then, when scan converting the polygons, the shading is interpolated along each scan line from the edge intensities. Gouraud shading is slower than constant shading but usually results in a more realistic appearance. LIGHT A three-element vector that specifies the direction of the light source. The default light source vector is [0,0,1], with the light rays parallel to the Z axis. REJECT Set this keyword (the default) to reject polygons as being hidden if their vertices are ordered in a clockwise direction as seen by the viewer. This keyword should always be set when rendering enclosed solids whose original vertex lists are in counterclockwise order. When rendering surfaces that are not closed or are not in counterclockwise order this keyword can be set to zero although shading anomalies at boundaries between visible and hidden surfaces may occur. VALUES A two-element array that specifies the range of pixel values (color indices) to use. The first element is the color index for the darkest pixel. The second element is the color index for the brightest pixel. For example, to render a shaded surface with the darkest shade set to pixel value 100 and the brightest value set to 150, use the commands: SET_SHADING, VALUES=[100, 150] SHADE_SURF, dataset Example Change the light source so that the light rays are parallel to the X axis: SET_SHADING, LIGHT = [1, 0, 0] See Also POLYSHADE, SHADE_SURF SET_SYMBOL [Previous Routine] [Next Routine] [List of Routines] NAME: SET_SYMBOL The SET_SYMBOL procedure defines a DCL (Digital Command Language) interpreter symbol for the current process. SET_SYMBOL is available only under VMS. Syntax SET_SYMBOL, Name, Value [, TYPE={1 | 2}] Arguments Name A scalar string containing the name of the symbol to be defined. Value A scalar string containing the value with which Name is defined. Keywords TYPE Indicates the table into which Name will be defined. Setting TYPE to 1 specifies the local symbol table, while a value of 2 specifies the global symbol table. The default is the local table. See Also DELLOG, DELETE_SYMBOL, SETLOG SETENV [Previous Routine] [Next Routine] [List of Routines] NAME: SETENV The SETENV procedure adds or changes an environment string in the process environment. Note This procedure is only available for UNIX and Windows platforms. Syntax SETENV, Environment_Expression Arguments Environment_Expression This argument may now be either a scalar or array string variable containing environment expressions to be added to the environment. A scalar string containing an environment expression to be added to the environment. Example Change the current shell variable by entering: SETENV,'SHELL=/bin/sh' Make sure to eliminate any whitespace around the equal sign: ; This is an incorrect usage--there are spaces around the equal ; sign: SETENV, 'VAR = H:\rsi' ; This is correct--VAR is set to H:\rsi: SETENV, 'VAR=H:\rsi' See Also DELLOG, GETENV, SETLOG SETLOG [Previous Routine] [Next Routine] [List of Routines] NAME: SETLOG The SETLOG procedure defines a logical name. Note This procedure is only available for the VMS platform. Syntax SETLOG, Lognam, Value [, /CONCEALED] [, /CONFINE] [, /NO_ALIAS] [, TABLE=string] [, /TERMINAL] Arguments Lognam A scalar string containing the name of the logical to be defined. Value A string containing the value to which the logical will be set. If Value is a string array, Lognam is defined as a multi-valued logical where each element of Value defines one of the equivalence strings. Keywords CONCEALED If this keyword is set, RMS (VMS Record Management Services) interprets the equivalence name as a device name. CONFINE If this keyword is set, the logical name is not copied from the IDL process to its spawned subprocesses. NO_ALIAS If this keyword is set, the logical name cannot be duplicated in the same logical table at an outer access mode. If another logical name with the same name already exists at an outer access mode, it is deleted. See the VMS System Services Manual for additional information on logical names and access modes. TABLE A scalar string containing the name of the logical table into which Lognam will be entered. If TABLE is not specified, LNM$PROCESS_TABLE is used. TERMINAL If this keyword is set, when attempting to translate the logical, further iterative logical name translation on the equivalence name is not to be performed. See Also DELETE_SYMBOL, DELLOG, SETENV, SET_SYMBOL SETUP_KEYS [Previous Routine] [Next Routine] [List of Routines] NAME: SETUP_KEYS The SETUP_KEYS procedure sets function keys for use with UNIX versions of IDL when used with the standard tty command interface. Under UNIX, the number of function keys, their names, and the escape sequences they send to the host computer vary enough between various keyboards that IDL cannot be written to understand all keyboards. Therefore, IDL provides a very general routine named DEFINE_KEY that allows the user to specify the names and escape sequences of function keys. SETUP_KEYS provides a convenient interface to DEFINE_KEY, using user input (via the keywords described below), the TERM environment variable and the type of machine the current IDL is running on to determine what kind of keyboard you are using, and then uses DEFINE_KEY to enter the proper definitions for the function keys. The new mappings for the keys can be viewed using the command HELP, /KEYS. The need for SETUP_KEYS has diminished in recent years because most UNIX terminal emulators have adopted the ANSI standard for function keys, as represented by VT100 terminals and their many derivatives, as well as xterm and the newer CDE based dtterm. The current version of IDL already knows the function keys of such terminals, so SETUP_KEYS is not required. However, SETUP_KEYS is still needed to define keys on non-ANSI terminals such as the Sun shelltool, SGI Iris-ansi terminal emulator, or IBM's aixterm. IDL does not support the function keys from the hpterm terminal emulator supplied on HP systems. Hpterm uses non ANSI-standard escape sequences which IDL cannot parse. Research Systems recommends the use of the xterm or dtterm terminal emulators instead. This routine is written in the IDL language. Its source code can be found in the file setup_keys.pro in the lib subdirectory of the IDL distribution. Syntax SETUP_KEYS [, /EIGHTBIT] [, /SUN | , /VT200 | , /HP9000 | , /MIPS | , /PSTERM | , /SGI] [, /APP_KEYPAD] [, /NUM_KEYPAD] Keywords Note If no keyword is specified, SETUP_KEYS uses !VERSION to determine the type of machine running IDL. It assumes that the keyboard involved is of the same type (this assumption is correct). ANSI Set this keyword to establish function key definitions for ANSI keyboards. EIGHTBIT Set this keyword to use the 8-bit versions of the escape codes (instead of the default 7-bit) when establishing VT200 function key definitions. SUN Set this keyword to establish function key definitions for a Sun3 keyboard. VT200 Set this keyword to establish function key definitions for a DEC VT200 keyboard. HP9000 Set this keyword to establish function key definitions for an HP 9000 series 300 keyboard. Although the HP 9000 series 300 supports both xterm and hpterm windows, IDL supports only user-definable key definitions in xterm windows- hpterm windows use non-standard escape sequences which IDL does not attempt to handle. IBM Set this keyword to establish function key definitions for IBM keyboards. MIPS Set this keyword to establish function key definitions for a Mips RS series keyboard. SGI Set this keyword to establish function key definitions for SGI keyboards. APP_KEYPAD Set this keyword to define escape sequences for the group of keys in the numeric keypad, enabling these keys to be programmed within IDL. NUM_KEYPAD Set this keyword to disable programmability of the numeric keypad. See Also DEFINE_KEY SFIT [Previous Routine] [Next Routine] [List of Routines] NAME: SFIT The SFIT function determines a polynomial fit to a surface and returns a fitted array. The function fitted is: f(x, y) = kxj, i xi yj This routine is written in the IDL language. Its source code can be found in the file sfit.pro in the lib subdirectory of the IDL distribution. Syntax Result = SFIT( Data, Degree [, KX=variable] ) Arguments Data The two-dimensional array of data to fit. The sizes of the dimensions may be unequal. Degree The maximum degree of fit (in one dimension). Keywords KX Set this keyword to a named variable that will contain the array of coefficients for a polynomial function of x and y to fit data. This parameter is returned as a Degree+1 by Degree+1 array. Example ; Create a grid from zero to six radians in the X and Y directions: X = (FINDGEN(61)/10) # REPLICATE(1,61) Y = TRANSPOSE(X) ; Evaluate a function at each point: F = -SIN(2*X) + COS(Y/2) ; Compute a sixth-degree polynomial fit to the function data: result = SFIT(F, 6) ; Display the original function on the left and the fitted function ; on the right, using identical axis scaling: WINDOW, XSIZE = 800, YSIZE = 400 ; Set up side-by-side plots: !P.MULTI = [0, 2, 1] ; Set background color to white: !P.BACKGROUND = 255 ; Set plot color to black: !P.COLOR = 0 SURFACE, F, X, Y, ZRANGE = [-3, 3], ZSTYLE = 1 SURFACE, result, X, Y The following figure shows the result of this example: Figure 20: The Original Function (Left) and the Fitted Function (Right) See Also CURVEFIT, GAUSSFIT, LINFIT, LMFIT, POLY_FIT, REGRESS, SVDFIT SHADE_SURF [Previous Routine] [Next Routine] [List of Routines] NAME: SHADE_SURF The SHADE_SURF procedure creates a shaded-surface representation of a regular or nearly-regular gridded surface with shading from either a light source model or from a user-specified array of intensities. This procedure and its parameters are similar to SURFACE. Given a regular or near-regular grid of elevations it produces a shaded- surface representation of the data with hidden surfaces removed. The SET_SHADING procedure can be used to control the direction of the light source and other shading parameters. If the graphics output device has scalable pixels (e.g., PostScript), the output image is scaled so that its largest dimension is less than or equal to 512 (unless the PIXELS keyword is set to some other value). This default resolution may not be high enough for some datasets. If your output looks jagged or "stair-stepped", try specifying a larger value with the PIXELS keyword. When outputting to a device that prints black on a white background, (e.g., PostScript), pixels that contain the background color index of 0 are set to white. Restrictions If the (X, Y) grid is not regular or nearly regular, errors in hidden line removal will occur. If the T3D keyword is set, the 3D to 2D transformation matrix contained in !P.T must project the Z axis to a line parallel to the device Y axis, or errors will occur. The SHADE_SURF_IRR procedure can be used to render many datasets that do not meet these requirements. Irregularly-gridded data can also be made interpolated to a regular grid using the TRIGRID and TRIANGULATE routines. Syntax SHADE_SURF, Z [, X, Y] [, AX=degrees] [, AZ=degrees] [, IMAGE=variable] [, MAX_VALUE=value] [, MIN_VALUE=value] [, PIXELS=pixels] [, /SAVE] [, SHADES=array] [, /XLOG] [, /YLOG] Graphics Keywords: [, CHARSIZE=value] [, CHARTHICK=integer] [, COLOR=value][, /DATA | , /DEVICE | , /NORMAL] [, FONT=integer] [, /NODATA] [, POSITION=[X0, Y0, X1, Y1]] [, SUBTITLE=string] [, /T3D] [, THICK=value] [, TICKLEN=value] [, TITLE=string] [, {X | Y | Z}CHARSIZE=value] [, {X | Y | Z}GRIDSTYLE=integer{0 to 5}] [, {X | Y | Z}MARGIN=[left, right]] [, {X | Y | Z}MINOR=integer] [, {X | Y | Z}RANGE=[min, max]] [, {X | Y | Z}STYLE=value] [, {X | Y | Z}THICK=value] [, {X | Y | Z}TICKFORMAT=string] [, {X | Y | Z}TICKINTERVAL= value] [, {X | Y | Z}TICKLAYOUT=scalar] [, {X | Y | Z}TICKLEN=value] [, {X | Y | Z}TICKNAME=string_array] [, {X | Y | Z}TICKS=integer] [, {X | Y | Z}TICKUNITS=string] [, {X | Y | Z}TICKV=array] [, {X | Y | Z}TICK_GET=variable] [, {X | Y | Z}TITLE=string] [, ZVALUE=value{0 to 1}] Arguments Z The two-dimensional array to be displayed. If X and Y are provided, the surface is plotted as a function of the (X, Y) locations specified by their contents. Otherwise, the surface is generated as a function of the array index of each element of Z. This argument is converted to double-precision floating-point before plotting. Plots created with SHADE_SURF are limited to the range and precision of double- precision floating-point values. X A vector or two-dimensional array specifying the X coordinates of the grid. If this argument is a vector, each element of X specifies the X coordinate for a column of Z (e.g., X[0] specifies the X coordinate for Z[0,*]). If X is a two-dimensional array, each element of X specifies the X coordinate of the corresponding point in Z (Xij specifies the X coordinate for Zij). This argument is converted to double-precision floating-point before plotting. Y A vector or two-dimensional array specifying the Y coordinates of the grid. If this argument is a vector, each element of Y specifies the Y coordinate for a row of Z (e.g., Y[0] specifies the Y coordinate 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 coordinate for Zij). This argument is converted to double-precision floating-point before plotting. Keywords AX This keyword specifies the angle of rotation, about the X axis, in degrees towards the viewer. This keyword is effective only if !P.T3D and the T3D keyword are not set. If !P.T3D is set, the three-dimensional to two-dimensional transformation used by SURFACE is contained in the 4 by 4 array !P.T. The surface represented by the two-dimensional array is first rotated, AZ (see below) degrees about the Z axis, then by AX degrees about the X axis, tilting the surface towards the viewer (AX > 0), or away from the viewer. The AX and AZ keyword parameters default to +30 degrees if omitted. The three-dimensional to two-dimensional transformation represented by AX and AZ, can be saved in !P.T by including the SAVE keyword. AZ This keyword specifies the counterclockwise angle of rotation about the Z axis. This keyword is effective only if !P.T3D is not set. The order of rotation is AZ first, then AX. IMAGE A named variable into which an image containing the shaded surface is stored. If this keyword is omitted, the image is displayed but not saved. MAX_VALUE The maximum value to be plotted. If this keyword is present, data values greater than the value of MAX_VALUE are treated as missing and are not plotted. Note that the IEEE floating-point value NaN is also treated as missing data. (See "Special Floating-Point Values" in Chapter 17 of Building IDL Applications for more information on IEEE floating-point values.) MIN_VALUE The minimum value to be plotted. If this keyword is present, data values less than the value of MIN_VALUE are treated as missing and are not plotted. Note that the IEEE floating-point value NaN is also treated as missing data. (See "Special Floating-Point Values" in Chapter 17 of Building IDL Applications for more information on IEEE floating-point values.) PIXELS Set this keyword to a scalar value that specifies the maximum size of the image dimensions, in pixels. PIXELS only applies when the output device uses scalable pixels (e.g., the PostScript device). Use this keyword to increase the resolution of the output image if the default looks jagged or "stair-stepped". SAVE Set this keyword to save the 3D to 2D transformation matrix established by SHADE_SURF in the system variable field !P.T. Use this keyword when combining the output of SHADE_SURF with the output of other routines in the same plot. SHADES An array expression, of the same dimensions as Z, that contains the color index at each point. The shading of each pixel is interpolated from the surrounding SHADE values. If this parameter is omitted, light-source shading is used. For most displays, this parameter should be scaled into the range of bytes. Warning When using the SHADES keyword on True Color devices, we recommend that decomposed color support be turned off, by setting DECOMPOSED=0 for DEVICE. XLOG Set this keyword to specify a logarithmic X axis. YLOG Set this keyword to specify a logarithmic Y axis. Graphics Keywords Accepted See Appendix C, "Graphics Keywords", for the description of graphics and plotting keywords not listed above. CHARSIZE, CHARTHICK, COLOR, DATA, DEVICE, FONT, NODATA, NORMAL, POSITION, SUBTITLE, T3D, THICK, TICKLEN, TITLE, [XYZ]CHARSIZE, [XYZ]GRIDSTYLE, [XYZ]MARGIN, [XYZ]MINOR, [XYZ]RANGE, [XYZ]STYLE, [XYZ]THICK, [XYZ]TICKFORMAT, [XYZ]TICKINTERVAL, [XYZ]TICKLAYOUT, [XYZ]TICKLEN, [XYZ]TICKNAME, [XYZ]TICKS, [XYZ]TICKUNITS, [XYZ]TICKV, [XYZ]TICK_GET, [XYZ]TITLE, ZVALUE. Example ; Create a simple dataset: D = DIST(40) ; Display the dataset as a light-source shaded surface: SHADE_SURF, D, TITLE = 'Shaded Surface' Instead of light-source shading, an array of the same size as the elevation dataset can be used to color the surface. This technique creates four-dimensional displays. ; Create an array of shades to use: S = SIN(D) ; Now create a new shaded surface that uses the array of shading ; values instead of the light source: SHADE_SURF, D, SHADES = BYTSCL(S) Note that the BYTSCL function is used to scale S into the range of bytes. See Also POLYSHADE, SET_SHADING, SHADE_VOLUME, SURFACE SHADE_SURF_IRR [Previous Routine] [Next Routine] [List of Routines] NAME: SHADE_SURF_IRR The SHADE_SURF_IRR procedure creates a shaded surface representation of an irregularly gridded elevation dataset. The data must be representable as an array of quadrilaterals. This routine should be used when the (X, Y, Z) arrays are too irregular to be drawn by SHADE_SURF, but are still semi-regular. This routine is written in the IDL language. Its source code can be found in the file shade_surf_irr.pro in the lib subdirectory of the IDL distribution. Syntax SHADE_SURF_IRR, Z, X, Y [, AX=degrees] [, AZ=degrees] [, IMAGE=variable] [, PLIST=variable] [, /T3D] Arguments Z An n x m array of elevations. X An n x m array containing the X location of each Z value. Y An n x m array containing the Y location of each Z value. Note The grid described by X and Y must consist of quadrilaterals, must be semi-regular, and must be in "clockwise" order. Clockwise ordering means that: ;for all j x[i,j] <= x[i+1, j] and ;for all i y[i,j] <= y[i, j+1] Keywords AX The angle of rotation about the X axis. The default is 30 degrees. AZ The angle of rotation about the Z axis. The default is 30 degrees. IMAGE Set this keyword to a named variable that will contain the resulting shaded surface image. The variable is returned as a byte array of the same size as the currently selected graphics device. PLIST Set this keyword to a named variable that will contain the polygon list on return. This feature is useful when you want to make a number of images from the same set of vertices and polygons. T3D Set this keyword to indicate that the generalized transformation matrix in !P.T is to be used (in which case the keyword values for AX and AZ are ignored) Example The following example creates a semi-regular data set in the proper format at displays the resulting irregular surface. ; Create some elevation data: z = DIST(10,10)*100.0 ; Create arrays to hold X and Y data: x = FLTARR(10,10) & y = FLTARR(10,10) ; Ensure that X and Y arrays are in "clockwise" order: FOR i = 0,9 do x[0:9,i] = FINDGEN(10) FOR j = 0,9 DO y[j,0:9] = FINDGEN(10) ; Make X and Y arrays irregular: x = x + RANDOMU(seed,10,10)*0.49 y = y + RANDOMU(seed,10,10)*0.49 ; Display the irregular surface: SHADE_SURF_IRR, z, x, y See Also SHADE_SURF, TRIGRID SHADE_VOLUME [Previous Routine] [Next Routine] [List of Routines] NAME: SHADE_VOLUME Given a 3D volume and a contour value, SHADE_VOLUME produces a list of vertices and polygons describing the contour surface. This surface can then be displayed as a shaded surface by the POLYSHADE procedure. Shading is obtained from either a single light-source model or from user-specified values. SHADE_VOLUME computes the polygons that describe a three dimensional contour surface. Each volume element (voxel) is visited to find the polygons formed by the intersections of the contour surface and the voxel edges. The method used by SHADE VOLUME is that of Klemp, McIrvin and Boyd, 1990: "PolyPaint-A Three-Dimensional Rendering Package," American Meteorology Society Proceedings, Sixth International Conference on Interactive Information and Processing Systems. This method is similar to the marching cubes algorithm described by Lorenson and Cline, 1987: "Marching Cubes: A High Resolution 3D Surface Construction Algorithm," Computer Graphics 21, 163-169. This routine is limited to processing datasets that will fit in memory. Syntax SHADE_VOLUME, Volume, Value, Vertex, Poly [, /LOW] [, SHADES=array] [, /VERBOSE] [, XRANGE=vector] [, YRANGE=vector] [, ZRANGE=vector] Arguments Volume A three-dimensional array that contains the dataset to be contoured. If the Volume array is dimensioned (D0, D1, D2), the resulting vertex coordinates are as follows: 0 < X < D0 - 1; 0 < Y < D1 - 1; 0 < Z < D2 - 1. If floating-point NaN values are present in Volume, then SHADE_VOLUME may generate inconsistent surfaces and may return NaN values in the Vertex argument. The surfaces generated by SHADE_VOLUME may also vary across platforms if NaN data is present in the Volume parameter. Value The scalar contour value. This value specifies the constant-density surface (also called an isosurface) to be rendered. Vertex The name of a variable to receive the vertex array. On output, this variable is set to a (3, n) floating-point array, suitable for input to POLYSHADE. Poly A named variable to receive the polygon list, an m-element, longword array. This list describes the vertices of each polygon and is suitable for input to POLYSHADE. The vertices of each polygon are listed in counterclockwise order when observed from outside the surface. The vertex description of each polygon is a vector of the form: [n, i0, i1, ..., in-1] and the Poly array is the concatenation of the lists of each polygon. For example, when rendering a pyramid consisting of four triangles, Poly would contain 16 elements, made by concatenating four, four-element vectors of the form [3, V0, V1, V2]. V0, V1, and V2 are the indices of the vertices describing each triangle. Keywords LOW Set this keyword to display the low side of the contour surface (i.e., the contour surfaces enclose high data values). If this keyword is omitted or is 0, the high side of the contour surface is displayed and the contour encloses low data values. If this parameter is incorrectly specified, errors in shading will result. SHADES An optional array, converted to byte type before use, that contains the user-specified shading color index for each voxel. This array must have the same dimensions as Volume. On exit, this array is replaced by another array, that contains the shading value for each vertex, contained in Vertex. Warning When using the SHADES keyword on True Color devices, we recommend that decomposed color support be turned off, by setting DECOMPOSED=0 for DEVICE. VERBOSE Set this keyword to print a message indicating the number of polygons and vertices that are produced. XRANGE An optional two-element vector that contains the limits, over the first dimension, of the sub-volume to be considered. YRANGE An optional two-element vector that contains the limits, over the second dimension, of the sub-volume to be considered. ZRANGE An optional two-element vector containing the limits, over the third dimension, of the sub-volume to be considered. Example The following procedure shades a volume passed as a parameter. It uses the SCALE3 procedure to establish the viewing transformation. It then calls SHADE_VOLUME to produce the vertex and polygon lists, and POLYSHADE to draw the contour surface. PRO SHOWVOLUME, vol, thresh, LOW = low ; Get the dimensions of the volume: s = SIZE(vol) ; Error, must be a 3D array: IF s[0] NE 3 THEN MESSAGE, 'Error: vol must be a 3D array' ; Establish the 3D transformation and coordinate ranges: SCALE3, XRANGE=[0, S[1]], YRANGE=[0, S[2]], ZRANGE=[0, S[3]] ; Default = view high side of contour surface: IF N_ELEMENTS(low) EQ 0 THEN low = 0 ; Produce vertices and polygons: SHADE_VOLUME, vol, thresh, v, p, LOW = low ; Produce image of surface and display: TV, POLYSHADE(v, p, /T3D) END See Also POLYSHADE, SHADE_SURF, XVOLUME SHIFT [Previous Routine] [Next Routine] [List of Routines] NAME: SHIFT The SHIFT function shifts elements of vectors or arrays along any dimension by any number of elements. The result is a vector or array of the same structure and type as Array. Positive shifts are to the right while left shifts are expressed as a negative number. All shifts are circular. Elements shifted off one end wrap around and are shifted onto the other end. In the case of vectors the action of SHIFT can be expressed: Result(i + s) modulation = Arrayi for (0 1 < n) where s is the amount of the shift, and n is the number of elements in the array. Syntax Result = SHIFT(Array, S1, ..., Sn) Arguments Array The array to be shifted. Si This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. The shift parameters. For arrays of more than one dimension, the parameter Sn specifies the shift applied to the nth dimension. S1 specifies the shift along the first dimension and so on. If only one shift parameter is present and the parameter is an array, the array is treated as a vector (i.e., the array is treated as having one- dimensional subscripts). A shift specification of 0 means that no shift is to be performed along that dimension. Example The following example demonstrates using SHIFT with a vector. by entering: A = INDGEN(5) ; Print the original vector, the vector shifted one position to the ; right, and the vector shifted one position to the left: PRINT, A, SHIFT(A, 1), SHIFT(A, -1) IDL prints: 0 1 2 3 4 4 0 1 2 3 1 2 3 4 0 Notice how elements of the vector that shift off the end wrap around to the other end. This "wrap around" occurs when shifting arrays of any dimension. See Also ISHFT SHOW3 [Previous Routine] [Next Routine] [List of Routines] NAME: SHOW3 The SHOW3 procedure combines an image, a surface plot of the image data, and a contour plot of the images data in a single tri-level display. This routine is written in the IDL language. Its source code can be found in the file show3.pro in the lib subdirectory of the IDL distribution. Syntax SHOW3, Image [, X, Y] [, /INTERP] [, E_CONTOUR=structure] [, E_SURFACE=structure] [, SSCALE=scale] Arguments Image The two-dimensional array to display. X A vector containing the X values of each column of Image. If the X argument is omitted, columns have values 0, 1, ..., ncolumns-1. Y A vector containing the Y values of each row of Image. If the Y argument is omitted, rows have values 0, 1, ..., nrows-1. Keywords INTERP Set this keyword to use bilinear interpolation on the pixel display. This technique is slightly slower, but for small images, it makes a better display. E_CONTOUR Set this keyword equal to an anonymous structure containing additional keyword parameters that are passed to the CONTOUR procedure. Tag names in the structure should be valid keyword arguments to CONTOUR, and the values associated with each tag should be valid keyword values. E_SURFACE Set this keyword equal to an anonymous structure containing additional keyword parameters that are passed to the SURFACE procedure. Tag names in the structure should be valid keyword arguments to SURFACE, and the values associated with each tag should be valid keyword values. SSCALE Reduction scale for surface. The default is 1. If this keyword is set to a value other than 1, the array size is reduced by this factor for the surface display. That is, the number of points used to draw the wire-mesh surface is reduced. If the array dimensions are not an integral multiple of SSCALE, the image is reduced to the next smaller multiple. Example ; Create a dataset: A = BESELJ(SHIFT(DIST(30,20), 15, 10)/2.,0) ; Show it with default display: SHOW3, A ; Specify X axis proportional to square root of values: SHOW3, A, SQRT(FINDGEN(30)) ; Label CONTOUR lines with double size characters, and include ;downhill tick marks: SHOW3, A, E_CONTOUR={C_CHARSIZE:2, DOWN:1} ; Draw a surface with a skirt and scale Z axis from -2 to 2: SHOW3, A, E_SURFACE={SKIRT:-1, ZRANGE:[-2,2]} See Also CONTOUR, SURFACE SHOWFONT [Previous Routine] [Next Routine] [List of Routines] NAME: SHOWFONT The SHOWFONT procedure displays a TrueType or vector-drawn font (from the file hersh1.chr, located in the resource/fonts subdirectory of the IDL distribution) on the current graphics device. This routine is written in the IDL language. Its source code can be found in the file showfont.pro in the lib subdirectory of the IDL distribution. Syntax SHOWFONT, Font, Name [, /ENCAPSULATED] [, /TT_FONT] Arguments Font The index number of the font (may range from 3 to 29) or, if the TT_FONT keyword is set, a string that contains the name of the TrueType font to display. Name A string that contains the text of a title to appear at the top of the font display. Keywords ENCAPSULATED Set this keyword, if the current graphics device is "PS", to make encapsulated PostScript output. TT_FONT If this keyword is set, the specified font will be interpreted as a TrueType font. Example To create a display of the Helvetica italic TrueType font on the screen: SHOWFONT, 'Helvetica Italic', 'Helvetica Italic', /TT_FONT To create a display of Font 3 for PostScript: ; Set output to PostScript: SET_PLOT, 'PS' ; Specify the output filename. If we didn't specify this, the file ; would be saved as idl.ps by default: DEVICE, FILENAME='font3.ps' ;Display font 3: SHOWFONT, 3, 'Simplex Roman' ; Close the new PS file: DEVICE, /CLOSE See Also EFONT, PS_SHOW_FONTS SIN [Previous Routine] [Next Routine] [List of Routines] NAME: SIN The periodic function SIN returns the trigonometric sine of X. Syntax Result = SIN(X) Arguments X The angle for which the sine is desired, specified 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 floating-point and yield floating-point results. When applied to complex numbers: sin x = COMPLEX(sin R cosh I, cos R sinh I) where R and I are the real and imaginary parts of x. If input argument X is an array, the result has the same structure, with each element containing the sine of the corresponding element of X. Examples To find the sine of 0.5 radians and print the result, enter: PRINT, SIN(0.5) The following example plots the SIN function between 0 and 2 with 100 intervals: X = 2*!PI/100 * FINDGEN(100) PLOT, X, SIN(X) Note !PI is a read-only system variable that contains the single-precision value for . See Also ASIN, SINH SINDGEN [Previous Routine] [Next Routine] [List of Routines] NAME: SINDGEN The SINDGEN function returns a string array with the specified dimensions. Each element of the array is set to the string representation of the value of its one- dimensional subscript, using IDL's default formatting rules. Syntax Result = SINDGEN(D1, ..., D8) Arguments Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. The dimensions of the result. The dimension parameters can be any scalar expression. Up to eight dimensions can be specified. If the dimension arguments are not integer values, IDL will convert them to integer values before creating the new array. Example To create S, a six-element string vector with each element set to the string value of its subscript, enter: S = SINDGEN(6) See Also BINDGEN, CINDGEN, DCINDGEN, DINDGEN, FINDGEN, L64INDGEN, LINDGEN, UINDGEN, UL64INDGEN, ULINDGEN SINH [Previous Routine] [Next Routine] [List of Routines] NAME: SINH The SINH function returns the hyperbolic sine of X. Syntax Result = SINH(X) Arguments X The angle for which the hyperbolic sine is desired, specified in radians. If X is double-precision floating-point, 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. SINH is defined as: sinh x = (eu - e-u) / 2 If X is an array, the result has the same structure, with each element containing the hyperbolic sine of the corresponding element of X. Examples To find the hyperbolic sine of each element in the array [.5, .2, .4] and print the result, enter: PRINT, SINH([.5, .2, .4]) To plot the SINH function between 0 and 2 with 100 intervals, enter: X = 2*!PI/100 * FINDGEN(100) PLOT, X, SINH(X) Note !PI is a read-only system variable that contains the single-precision value of . See Also ASIN, SIN SIZE [Previous Routine] [Next Routine] [List of Routines] NAME: SIZE The SIZE function returns size and type information for its argument if no keywords are set. If a keyword is set, SIZE returns the specified quantity. Syntax Result = SIZE( Expression [, /L64] [, /DIMENSIONS | , /FILE_LUN | , /N_DIMENSIONS | , /N_ELEMENTS | , /STRUCTURE | , /TNAME | , /TYPE] ) Return Value The returned vector is always of integer type. The first element is equal to the number of dimensions of Expression. This value is zero if Expression is scalar or undefined. The next elements contain the size of each dimension, one element per dimension (none if Expression is scalar or undefined). After the dimension sizes, the last two elements contain the type code (zero if undefined) and the number of elements in Expression, respectively. The type codes are listed below. IDL Type Codes The following table lists the IDL type codes returned by the SIZE function: Type Code Data Type 0 Undefined 1 Byte 2 Integer 3 Longword integer 4 Floating point 5 Double-precision floating 6 Complex floating 7 String 8 Structure 9 Double-precision complex Table 83: IDL Type Codes Type Code Data Type 10 Pointer 11 Object reference 12 Unsigned Integer 13 Unsigned Longword Integer 14 64-bit Integer 15 Unsigned 64-bit Integer Table 83: IDL Type Codes Arguments Expression The expression for which size information is requested. Keywords With the exception of L64, the following keywords determine the return value of the SIZE function and are mutually exclusive - specify at most one of the following. DIMENSIONS Set this keyword to return the dimensions of Expression. If Expression is scalar, the result is a scalar containing a 0. For arrays, the result is an array containing the array dimensions. The result is a 32-bit integer when possible, and 64-bit integer if the number of elements in Expression requires it. Set L64 to force 64-bit integers to be returned in all cases. FILE_LUN Set this keyword to return the file unit to which Expression is associated, if it is an IDL file variable, as created with the ASSOC function. If Expression is not a file variable, 0 is returned (0 is not a valid file unit for ASSOC). L64 By default, the result of SIZE is 32-bit integer when possible, and 64-bit integer if the number of elements in Expression requires it. Set L64 to force 64-bit integers to be returned in all cases. In addition to affecting the default result, L64 also affects the output from the DIMENSIONS, N_ELEMENTS, and STRUCTURE keywords. Note Only 64-bit versions of IDL are capable of creating variables requiring 64-bit SIZE output. Check the value of !VERSION.MEMORY_BITS to see if your IDL is 64- bit or not. N_DIMENSIONS Set this keyword to return the number of dimension in Expression, if it is an array. If Expression is scalar, 0 is returned. N_ELEMENTS Set this keyword to return the number of data elements in Expression. Setting this keyword is equivalent to using the N_ELEMENTS function. The result will be 32-bit integer when possible, and 64-bit integer if the number of elements in Expression requires it. Set L64 to force 64-bit integers to be returned in all cases. STRUCTURE Set this keyword to return all available information about Expression in a structure. Note Since the structure is a named structure, the size of its fields is fixed. The result is an IDL_SIZE (32-bit) structure when possible, and an IDL_SIZE64 structure otherwise. Set L64 to force an IDL_SIZE64 structure to be returned in all cases. The following are descriptions of the fields in the returned structure: Field Description TYPE_NAME Name of IDL type of Expression. TYPE Type code of Expression. FILE_LUN If Expression is an IDL file variable, as created with the ASSOC function, the file unit to which it is associated; otherwise, 0. N_ELEMENTS Number of data elements in Expression. Table 84: Structure Fields Field Description N_DIMENSIONS If Expression is an array, the number of dimensions; otherwise, Expression is 0. DIMENSIONS An 8-element array containing the dimensions of Expression. Table 84: Structure Fields TNAME Set this keyword to return the IDL type of Expression as a string. TYPE Set this keyword to return the IDL type code for Expression. See "IDL Type Codes" on page 1253 for details. For an example illustrating how to determine the type code of an expression, see "Determining the Size/Type of an Array" in Chapter 15 of Building IDL Applications. Example Print the size information for a 10 by 20 floating-point array by entering: PRINT, SIZE(FINDGEN(10, 20)) IDL prints: 2 10 20 4 200 This IDL output indicates the array has 2 dimensions, equal to 10 and 20, a type code of 4, and 200 elements total. Similarly, to print only the number of dimensions of the same array: PRINT, SIZE(FINDGEN(10, 20), /N_DIMENSIONS) IDL prints: 2 SKEWNESS [Previous Routine] [Next Routine] [List of Routines] NAME: SKEWNESS The SKEWNESS function computes the statistical skewness of an n-element vector. If the variance of the vector is zero, the skewness is not defined, and SKEWNESS returns !VALUES.F_NAN as the result. SKEWNESS calls the IDL function MOMENT. Syntax Result = SKEWNESS( X [, /DOUBLE] [, /NAN] ) Arguments X A numeric vector. Keywords DOUBLE Set this keyword to force computations to be done in double-precision arithmetic. NAN Set this keyword to cause the routine to check for occurrences of the IEEE floating- point value NaN in the input data. Elements with the value NaN are treated as missing data. (See "Special Floating-Point Values" in Chapter 17 of Building IDL Applications for more information on IEEE floating-point values.) Example ; Define the n-element vector of sample data: x = [65, 63, 67, 64, 68, 62, 70, 66, 68, 67, 69, 71, 66, 65, 70] ; Compute the skewness: result = SKEWNESS(x) PRINT, 'Skewness = ', result IDL prints: Skewness = -0.0942851 See Also KURTOSIS, MEAN, MEANABSDEV, MOMENT, STDDEV, VARIANCE SKIPF [Previous Routine] [Next Routine] [List of Routines] NAME: SKIPF The SKIPF procedure skips records or files on the designated magnetic tape unit. SKIPF is available only under VMS. If two parameters are supplied, files are skipped. If three parameters are present, individual records are skipped. The number of files or records actually skipped is stored in the system variable !ERR. Note that when skipping records, the operation terminates immediately when the end of a file is encountered. See the description of the magnetic tape routines in "VMS- Specific Information" in Chapter 8 of Building IDL Applications. Syntax SKIPF, Unit, Files or SKIPF, Unit, Records, R Arguments Unit The magnetic tape unit to rewind. Unit must be a number between 0 and 9, and should not be confused with the standard file Logical Unit Numbers (LUNs). Files The number of files to be skipped. Skipping is in the forward direction if the second parameter is positive, otherwise files are skipped backwards. Records The number of records to be skipped. Skipping is in the forward direction if the second parameter is positive, otherwise records are skipped backwards. R If this argument is present, records are skipped, otherwise files are skipped. The value of R is never examined. Its presence serves only to indicate that records are to be skipped. SLICER3 [Previous Routine] [Next Routine] [List of Routines] NAME: SLICER3 The IDL SLICER3 is a widget-based application to visualize three-dimensional datasets. This program supersedes the SLICER program. This routine is written in the IDL language. Its source code can be found in the file slicer3.pro in the lib subdirectory of the IDL distribution. Syntax SLICER3 [, hData3D] [, DATA_NAMES=string/string_array] [, /DETACH] [, GROUP=widget_id] [, /MODAL] Arguments hData3D A pointer to a three-dimensional data array, or an array of pointers to multiple three- dimensional arrays. If multiple arrays are specified, they all must have the same X, Y, and Z dimensions. If hData3D is not specified, SLICER3 creates a 2 x 2 x 2 array of byte data using the IDL BYTARR function. You can also load data interactively via the File menu of the SLICER3 application (see "Examples" on page 1274 for details). Note If data are loaded in this fashion, any data passed to SLICER3 via a pointer (or pointers) is deleted, and the pointers become invalid. Keywords DATA_NAMES Set this keyword equal to a string array of names for the data. The names appear on the droplist widget for the current data. If the number of elements of DATA_NAMES is less than the number of elements in hData3D then default names will be generated for the unnamed data. DETACH Set this keyword to place the drawing area in a window that is detached from the SLICER3 control panel. The drawing area can only be detached if SLICER3 is not run as a modal application. GROUP Set this keyword equal to the Widget ID of an existing widget that serves as the "group leader" for the SLICER3 graphical user interface. When a group leader is destroyed, all widgets in the group are also destroyed. If SLICER3 is started from a widget application, then GROUP should always be specified. MODAL Set this keyword to block user interaction with all other widgets (and block the command line) until the SLICER3 exits. If SLICER3 is started from some other widget-based application, then it is usually advisable to run SLICER3 with the MODAL keyword set. Note SLICER3 modifies the current color table, as well as various elements of the plotting system (i.e., the "!X", "!Y", "!Z", and "!P" system variables). If the MODAL keyword is set (recommended), then SLICER3 will, upon exit, restore these system variables (and the color tables) to the values they had when SLICER3 was started. The SLICER3 Graphical User Interface Figure 21: SLICER3 Graphical User Interface The following options are available via SLICER3's graphical user interface. File Menu Load Select this menu option to choose a file containing a 3D array (or arrays) to load into SLICER3. The file must have been written in the format specified in the following table. For each data array in the file, the following values must be included. Note that the first six values are returned by the IDL SIZE function; see "Examples" on page 1274 for an example of how to create a data file suitable for SLICER3 with just a few IDL commands. Data item Data Type Numberof Bytes Number of dimension in array. (Note: This is long 4 always 3 for valid SLICER3 data.) Size of first dimension. long 4 Size of second dimension. long 4 Size of third dimension. long 4 Data type (Must be type 1 through 5. See long 4 "SIZE" on page 1253 for a list of data types types.) Total number of elements (dimX, dimY, long 4 dimZ). Number of characters in data name. (See long 4 "STRLEN" on page 1343 for the easiest way to determine this number.) Data name byte strlen() 3D data array. varies varies Table 85: SLICER3 Data File Structure If multiple arrays are present in the file, they must all have the same dimensions. Note Files saved by the "Save Subset" operation (see below) are suitable for input via the "Load" operation. Data files that are moved from one platform to another may not load as expected, due to byte ordering differences. See the BYTEORDER and SWAP_ENDIAN for details. Save/Save Subset SLICER3 must be in BLOCK mode to for this option to be available. Select this menu option to save a subset of the 3D data enclosed in the current block to the specified file. Subsets saved in this fashion are suitable for loading via the "Load" menu option. If multiple 3D arrays are available when this option is selected, multiple subsets are saved to the file. Save/Save Tiff Image Select this menu option to save the contents of the current SLICER3 image window as a TIFF image in the specified file. When running in 8-bit mode, a "Class P" palette color TIFF file is created. In 24-bit mode, a "Class R" (interleaved by image) TIFF file is created. Quit Select this menu option to exit SLICER3. Tools Menu Erase Select this menu option to erase the display window and delete all the objects in the display list. Delete/... As graphical objects are created, they are added to the display list. Select this menu option to delete a specific object from the list. When an object is deleted, the screen is redrawn with the remaining objects. Colors/Reset Colors Select this menu option to restore the original color scheme. Colors/Differential Shading Use this menu option to change the percentage of differential shading applied to the X, Y, and Z slices. Colors/Slice/Block Use this menu option to launch the XLOADCT application to modify the colors used for slices and blocks Colors/Surface Use this menu option to launch the XLOADCT application to modify the colors used for isosurfaces. Colors/Projection Use this menu option to launch the XLOADCT application to modify the colors used for projections. Note On some platforms, the selected colors may not become visible until after you exit the "XLOADCT" application. Options Select this menu option to display a panel that allows you to set: * The axis visibility. * The wire-frame cube visibility. * The display window size. Main Draw Window Operations available in the Main Draw Window are dependent on the mode selected in the Mode Pulldown menu. In general, when coordinate input is required from the user, it is performed by clicking a mouse button on the "surface" of the wire-frame cube that surrounds the data. This 3D location is then used as the basis for whatever input is needed. In most cases, the "front" side of the cube is used. In a few cases, the coordinate input is on the "back" side of the cube. Data Pulldown Menu If multiple datasets are currently available in SLICER3, this menu allows you to select which data will be displayed in the Main Draw Window. Slices, blocks, iso- surfaces, etc. are created from the currently selected data. If only one dataset is loaded, this menu is inactive. Mode Pulldown Menu This menu is used to select the current mode of operation. Figure 22: Mode Pulldown Menu Slice Mode To display a slice, click and drag the left mouse button on the wire-frame cube. When the button is released, a slice through the data will be drawn at that location. Draw Radio Button When in Draw mode, new slices will be merged into the current Z-buffer contents. Expose Radio Button When in Expose mode, new slices will be drawn in front of everything else. Orthogonal Radio Button When in Orthogonal mode, use the left mouse button in the main draw window to position and draw an orthogonal slicing plane. Clicking the right mouse button in the main draw window (or any mouse button in the small window) will toggle the slicing plane orientation. X/Y/Z Radio Buttons * X: This sets the orthogonal slicing plane orientation to be perpendicular to the X axis. * Y: This sets the orthogonal slicing plane orientation to be perpendicular to the Y axis. * Z: This sets the orthogonal slicing plane orientation to be perpendicular to the Z axis. Oblique Radio Button Clicking any mouse button in the small window will reset the oblique slicing plane to its default orientation. Normal Radio Button When in this mode, click and drag the left mouse button in the big window to set the surface normal for the oblique slicing plane. Center Radio Button When in this mode, click and drag the left mouse button in the big window to set the center point for the surface normal. Display Button Clicking this button will cause an oblique slicing plane to be drawn. Block Mode Figure 23: Block Mode When in Block mode, use the left mouse button in the main draw window to set the location for the "purple" corner of the block. Use the right mouse button to locate the opposite "blue" corner of the block. When in Block mode, the "Save Subset" operation under the main "File" menu is available. Add When in this mode, the block will be "added" to the current Z-buffer contents. Subtract When in this mode, the block will be "subtracted" from the current Z-buffer contents. Subtract mode is only effective when the block intersects some other object in the display (such as an iso-surface). Display Button Clicking this button will cause the block to be drawn. Surface Mode Figure 24: Surface Mode An iso-surface is like a contour line on a contour map. On one side of the line, the elevation is higher than the contour level, and on the other side of the line, the elevation is lower than the contour level. An iso-surface, however, is a 3D surface that passes through the data such that the data values on one side of the surface are higher than the threshold value, and on the other side of the surface, the data values are lower than the threshold value. When in Surface mode, a logarithmic histogram plot of the data is displayed in the small draw window. Click and drag a mouse button on this plot to set the iso-surface threshold value. This value is also shown in the text widget below the plot. The threshold value may also be set by typing a new value in this text widget. The histogram plot is affected by the current threshold settings. (See Threshold mode, below). Low Selecting this mode will cause the iso-surface polygon facing to face towards the lower data values. Usually, this is the mode to use when the iso-surface is desired to surround high data values. High Selecting this mode will cause the iso-surface polygon facing to face towards the higher data values. Usually, this is the mode to use when the iso-surface is desired to surround low data values. Shading pulldown menu Iso-surfaces are normally rendered with light-source shading. If multiple datasets are currently loaded, then this menu allows the selection of a different 3D array for the source of the iso-surface shading values. If only one dataset is currently loaded, then this menu is inactive. Display Button Clicking this button will cause the iso-surface to be created and drawn. Iso-surfaces often consist of tens of thousands of polygons, and can sometimes take considerable time to create and render. Projection Mode Figure 25: Projection Mode A "voxel" projection of a 3D array is the projection of the data values within that array onto a viewing plane. This is similar to taking an X-ray image of a 3D object. Max Select this mode for a Maximum intensity projection. Avg Select this mode for an Average intensity projection. Low Select this mode for a Low resolution projection. Med Select this mode for a Medium resolution projection. High Select this mode for a High resolution projection. Depth Queue % Slider Use the slider to set the depth queue percent. A value of 50, for example, indicates that the farthest part of the projection will be 50% as bright as the closest part of the projection. Display Button Clicking this button will cause the projection to be calculated and drawn. Projections can sometimes take considerable time to display. Higher resolution projections take more computation time. Threshold Mode Figure 26: Threshold Mode When in Threshold mode, a logarithmic histogram plot of the data is displayed in the small draw window. Click and drag the left mouse button on this plot to set the minimum and maximum threshold values. To expand a narrow range of data values into the full range of available colors, set the threshold range before displaying slices, blocks, or projections. The threshold settings also affect the histogram plot in "Surface" mode. The minimum and maximum threshold values are also shown in the text widgets below the histogram plot. Click and drag the right mouse button on the histogram plot to set the transparency threshold. Portions of any slice, block, or projection that are less than the transparency value are not drawn (clear). Iso-surfaces are not affected by the transparency threshold. The transparency threshold value is also shown in a text widget below the histogram plot. Min In this text widget, a minimum threshold value can be entered. Max In this text widget, a maximum threshold value can be entered. Transp. In this text widget, a transparency threshold value can be entered. Profile Mode Figure 27: Profile Mode In Profile mode, a plot is displayed showing the data values along a line. This line is also shown superimposed on the data in the main draw window. The bottom of the plot corresponds to the "purple" end of the line, and the top of the plot corresponds to the "blue" end of the line. Orthogonal Click and drag the left mouse button to position the profile line, based upon a point on the "front" faces of the wire-frame cube. Click and drag the right mouse button to position the profile line, based upon a point on the "back" faces of the wire-frame cube. As the profile line is moved, The profile plot is dynamically updated. Oblique Click and drag the left mouse button to position the "purple" end of the profile line on one of the "front" faces of the wire-frame cube. Click and drag the right mouse button to position the "blue" end of the profile line on one of the "back" faces of the wire- frame cube. As the profile line is moved, The profile plot is dynamically updated. Probe Mode Figure 28: Probe Mode In Probe mode, click and drag a mouse button over an object in the main draw window. The actual X-Y-Z location within the data volume is displayed in the three text widgets. Also, the data value at that 3D location is displayed in the status window, above the main draw window. If the cursor is inside the wire-frame cube, but not on any object, then the status window displays "No data value", and the three text widgets are empty. If the cursor is outside the wire-frame cube, then the status window and text widgets are empty. X Use this text widget to enter the X coordinate for the probe. Y Use this text widget to enter the Y coordinate for the probe. Z Use this text widget to enter the Z coordinate for the probe. View Mode Figure 29: View Mode In view mode, a small window shows the orientation of the data cube in the current view. As view parameters are changed, this window is dynamically updated. The main draw window is then updated when the user clicks on "Display", or exits View mode. Display Clicking on this button will cause the objects in the main view window to be drawn in the new view. If any view parameters have been changed since the last time the main view was updated, the main view will be automatically redrawn when the user exits View mode. 1st Rotation Use this slider to set the angle of the first view rotation (in degrees). The droplist widget adjacent to the slider indicates which axis this rotation is about. 2nd Rotation Use this slider to set the angle of the second view rotation (in degrees). The droplist widget adjacent to the slider indicates which axis this rotation is about. Zoom % Slider Use this slider to set the zoom factor percent. Depending upon the view rotations, SLICER3 may override this setting to ensure that all eight corners of the data cube are within the window. Z % Slider Use this slider to set a scale factor for the Z axis (to compensate for the data's aspect ratio). Operational Details The SLICER3 procedure has the following side effects: * SLICER3 sets the position for the light source and enables back-facing polygons to be drawn (see the IDL "SET_SHADING" command). * SLICER3 overwrites the existing contents of the Z-buffer. Upon exiting SLICER3, the Z-buffer contents are the same as what was last displayed by SLICER3. * On 24-bit displays, SLICER3 sets the device to non-decomposed color mode (DEVICE, DECOMPOSED=0). * SLICER3 breaks the color table into 6 "bands", based upon the number of available colors (where max_color=!D.N_COLORS on 8-bit displays, and max_color=256 on 24-bit displays and nColor = (max_color - 9) / 5): Band Start Band End index index Used For 0 nColor-1 X Slices. nColor (2*nColor)-1 Y Slices. 2*nColor (3*nColor)-1 Z Slices. Table 86: SLICER3 Band Start/End Band Start Band End index index Used For 3*nColor (4*nColor)-1 Iso-surfaces 4*nColor (5*nColor)-1 Projections Table 86: SLICER3 Band Start/End Annotation colors are the last "band", and they are set up as shown in the table: Color index Color max_color - 1 White max_color - 2 Yellow max_color - 3 Cyan max_color - 4 Purple max_color - 5 Red max_color - 6 Green max_color - 7 Blue max_color - 8 Black Table 87: SLICER3 Color Bands On 24-bit displays, you can often improve performance by running SLICER3 in 8-bit mode. This can be accomplished (on some platforms) by entering the following command at the start of the IDL session (before any windows are created): Device, Pseudo_Color=8 Examples The following IDL commands open a data file from the IDL distribution and load it into SLICER3: ; Choose a data file: file=FILEPATH('head.dat', SUBDIR=['examples', 'data']) ; Open the data file: OPENR, UNIT, file, /GET_LUN ; Create an array to hold the data: data = BYTARR(80, 100, 57, /NOZERO) ; Read the data into the array: READU, UNIT, data ; Close the data file: CLOSE, UNIT ; Create a pointer to the data array: hData = PTR_NEW(data, /NO_COPY) ; Load the data into SLICER3: SLICER3, hdata, DATA_NAMES='Dave' Note If data are loaded via the File menu after SLICER3 is launched with a pointer argument (as shown above), the pointer becomes invalid. You can use an IDL statement like the following to "clean up" after calling SLICER3 in this fashion: if PTR_VALID(hdata) then PTR_FREE, hdata Because we did not launch SLICER3 with the MODAL keyword, the last contents of the main draw window still reside in IDL's Z-buffer. To retrieve this image after exiting SLICER3, use the following IDL statements: ; Save the current graphics device: current_device = !D.Name ; Change to the Z-buffer device: SET_PLOT, 'Z' ; Read the image from the Z-buffer: image_buffer = TVRD() ; Return to the original graphics device: SET_PLOT, current_device ; Display the image: TV, image_buffer The following IDL commands manually create a data save file suitable for dynamic loading into SLICER3. Note that if you load data into SLICER3 as shown above, you can also create save files by switching to BLOCK mode and using the Save Subset menu option. ; Store some 3D data in a variable called data_1: data_1 = INDGEN(20,30,40) ; Store some 3D data in a variable called data_2: data_2 = FINDGEN(20,30,40) ; Define the names for the datasets. Their names will appear in the ; "Data" pulldown menu in SLICER3: data_1_name ='Test Data 1' data_2_name ='Data 2' ; Select a data file name: dataFile = PICKFILE() ; Write the file: GET_LUN, lun OPENW, lun, dataFile WRITEU, lun, SIZE(data_1) WRITEU, lun, STRLEN(data_1_name) WRITEU, lun, BYTE(data_1_name) WRITEU, lun, data_1 WRITEU, lun, SIZE(data_2) WRITEU, lun, STRLEN(data_2_name) WRITEU, lun, BYTE(data_2_name) WRITEU, lun, data_2 CLOSE, lun FREE_LUN, lun See Also GRID3, EXTRACT_SLICE, SHADE_VOLUME, XVOLUME SLIDE_IMAGE [Previous Routine] [Next Routine] [List of Routines] NAME: SLIDE_IMAGE The SLIDE_IMAGE procedure creates a scrolling graphics window for examining large images. By default, 2 draw widgets are used. The draw widget on the left shows a reduced version of the complete image, while the draw widget on the right displays the actual image with scrollbars that allow sliding the visible window. This routine is written in the IDL language. Its source code can be found in the file slide_image.pro in the lib subdirectory of the IDL distribution. Syntax SLIDE_IMAGE [, Image] [, /BLOCK] [, CONGRID=0] [, FULL_WINDOW=variable] [, GROUP=widget_id] [, /ORDER] [, /REGISTER] [, RETAIN={0 | 1 | 2}] [, SLIDE_WINDOW=variable] [, SHOW_FULL=0] [, TITLE=string] [, TOP_ID=variable] [, XSIZE=width] [, XVISIBLE=width] [, YSIZE=height] [, YVISIBLE=height] Arguments Image A 2D image array to be displayed. If this argument is not specified, no image is displayed. The FULL_WINDOW and SCROLL_WINDOW keywords can be used to obtain the window numbers of the two draw widgets so they can be drawn into at a later time. Keywords BLOCK Set this keyword to have XMANAGER block when this application is registered. By default, BLOCK is set equal to zero, providing access to the command line if active command line processing is available. Note that setting BLOCK=1 will cause all widget applications to block, not just this application. For more information, see the documentation for the NO_BLOCK keyword to XMANAGER. Note Only the outermost call to XMANAGER can block. Therefore, to have SLIDE_IMAGE block, any earlier calls to XMANAGER must have been called with the NO_BLOCK keyword. See the documentation for the NO_BLOCK keyword to XMANAGER for an example. CONGRID Normally, the image is processed with the CONGRID procedure before it is written to the fully visible window on the left. Specifying CONGIRD=0 will force the image to be drawn as is. FULL_WINDOW Set this keyword to a named variable that will contain the IDL window number of the fully visible window. This window number can be used with the WSET procedure to draw to the scrolling window at a later point. GROUP Set this keyword to the widget ID of the widget that calls SLIDE_IMAGE. If set, the death of the caller results in the death of SLIDE_IMAGE. ORDER This keyword is passed directly to the TV procedure to control the order in which the images are drawn. Usually, images are drawn from the bottom up. Set this keyword to a non-zero value to draw images from the top down. REGISTER Set this keyword to create a "Done" button for SLIDE_IMAGE and register the widgets with the XMANAGER procedure. The basic widgets used in this procedure do not generate widget events, so it is not necessary to process events in an event loop. The default is therefore to simply create the widgets and return. Hence, when REGISTER is not set, SLIDE_IMAGE can be displayed and the user can still type commands at the IDL command prompt. RETAIN This keyword is passed directly to the WIDGET_DRAW function. Set RETAIN to zero, one, or two to specify how backing store should be handled for the window. RETAIN=0 specifies no backing store. RETAIN=1 requests that the server or window system provide backing store. RETAIN=2 specifies that IDL provide backing store directly. See "Backing Store" on page 2351 for details. SLIDE_WINDOW Set this keyword to a named variable that will contain the IDL window number of the sliding window. This window number can be used with the WSET procedure to draw to the scrolling window at a later time. SHOW_FULL Set this keyword to zero to show the entire image at full resolution in one scrolling graphics window. By default, SHOW_FULL is set, displaying two draw widgets. Note On Windows platforms only, using TVRD to return the array size of the displayed image will cause the returned array to be off by the size of the frame (one pixel per side). To return the dimensions of the original image, you must modify the slide_image.pro library routine so that the FRAME keyword is not used with SHOW_FULL. TITLE Set this keyword to the title to be used for the SLIDE_IMAGE widget. If this keyword is not specified, "Slide Image" is used. TOP_ID Set this keyword to a named variable that will contain the top widget ID of the SLIDE_IMAGE hierarchy. This ID can be used to kill the hierarchy as shown below: SLIDE_IMAGE, TOP_ID=base, ... WIDGET_CONTROL, /DESTROY, base XSIZE Set this keyword to the maximum width of the image that can be displayed by the scrolling window. This keyword should not be confused with the visible size of the image, controlled by the XVISIBLE keyword. If XSIZE is not specified, the width of Image is used. If Image is not specified, 256 is used. XVISIBLE Set this keyword to the width of the viewport on the scrolling window. If this keyword is not specified, 256 is used. YSIZE Set this keyword to the maximum height of the image that can be displayed by the scrolling window. This keyword should not be confused with the visible size of the image, controlled by the YVISIBLE keyword. If YSIZE is not present the height of Image is used. If Image is not specified, 256 is used. YVISIBLE Set this keyword to the height of the viewport on the scrolling window. If this keyword is not present, 256 is used. Example Open an image from the IDL distribution and load it into SLIDE_IMAGE: ; Create a variable to hold the image: image = BYTARR(768,512) OPENR, unit, FILEPATH('nyny.dat', SUBDIR=['examples','data']), /GET_LUN READU, unit, image CLOSE, unit ; Scale the image into byte range of the display: image = BYTSCL(image) ; Display the image: SLIDE_IMAGE, image See Also TV, TVSCL, WIDGET_DRAW, WINDOW SMOOTH [Previous Routine] [Next Routine] [List of Routines] NAME: SMOOTH The SMOOTH function returns a copy of Array smoothed with a boxcar average of the specified width. The result has the same type and dimensions as Array. The algorithm used by SMOOTH is: 1 w ­ 1 ---- A , i = w 2, ..., N ­ w R = w i + j ­ w 2 i j = 0 Ai, otherwise where N is the number of elements in A. Syntax Result = SMOOTH( Array, Width [, MISSING] [, NAN] [, /EDGE_TRUNCATE] [, /NAN] ) Arguments Array The array to be smoothed. Array can have any number of dimensions. Width This modified argument defines the width of the smoothing window. Width can either be a scalar or a vector with length equal to the number of dimensions of Array. If Width is a scalar then the same width is applied for each dimension that has length greater than 1 (dimensions of length 1 are skipped). If Width is a vector, then each element of Width is used to specify the smoothing width for each dimension of Array. Values for Width must be smaller than the corresponding Array dimension. If a Width value is even, then Width+1 will be used instead. The value of Width does not affect the running time of SMOOTH to a great extent. Note - A Width value of zero or 1 implies no smoothing. However, if the NAN keyword is set, then any NaN values within the Array will be treated as missing data and will be replaced. Tip - For a multidimenional array, set widths to 1 within the Width vector for dimensions that you don't want smoothed. The width of the smoothing window, in each dimension. Width should be an odd number, smaller than the smallest dimension of Array. If Width is an even number, one plus the given value of Width is used. For example, if you use a Width of 3 to smooth a two-dimensional array, the smoothing window will contain nine elements (including the element being smoothed). The value of Width does not affect the running time of SMOOTH to a great extent. Keywords MISSING The value to return for elements that contain no valid points within the kernel. The default is the IEEE floating-point value NaN. This keyword is only used if the NAN keyword is set. EDGE_TRUNCATE Set this keyword to apply the smoothing function to all points. If the neighborhood around a point includes a point outside the array, the nearest edge point is used to compute the smoothed result. If EDGE_TRUNCATE is not set, the end points are copied from the original array to the result with no smoothing. For example, when smoothing an n-element vector with a three point wide smoothing window, the first point of the result R0 is equal to A0 if EDGE_TRUNCATE is not set, but is equal to (A0+A0+A1)/3 if the keyword is set. In the same manner, point Rn- 1 is set to An-1 if EDGE_TRUNCATE is not set, or to (An-2+An-1+An-1)/3 if it is. Points not within a distance of Width/2 from an edge are not affected by this keyword. Note Normally, two-dimensional floating-point arrays are smoothed in one pass. If both the EDGE_TRUNCATE and NAN keywords are specified for a two-dimensional array, the result is obtained in two passes, one for each dimension. Therefore, the results may differ slightly when both the EDGE_TRUNCATE and NAN keywords are set. NAN Set this keyword to cause the routine to check for occurrences of the IEEE floating-point value NaN in the input data. Elements with the value NaN are treated as missing data, and are ignored when computing the smooth value for neighboring elements. In the Result, missing elements are replaced by the smoothed value of all other valid points within the smoothing window. If all points within the window are missing, then the result at that point is given by the MISSING keyword. Note that SMOOTH should never be called without the NAN keyword if the input array may possibly contain NaN values. Set this keyword to cause the routine to check for occurrences of the IEEE floating- point value NaN in the input data. Elements with the value NaN are treated as missing data. (See "Special Floating-Point Values" in Chapter 17 of Building IDL Applications for more information on IEEE floating-point values.) Note SMOOTH should never be called without the NAN keyword if the input array may possibly contain NaN values. Example Create and display a simple image by entering: D = SIN(DIST(256)/3) & TVSCL, D Now display the same dataset smoothed with a width of 9 by entering: TVSCL, SMOOTH(D, 9), 256, 256 See Also DIGITAL_FILTER, LEEFILT, MEDIAN, TS_DIFF, TS_FCAST, TS_SMOOTH SOBEL [Previous Routine] [Next Routine] [List of Routines] NAME: SOBEL The SOBEL function returns an approximation to the Sobel edge enhancement operator for images, G jk = Gx + Gy GX = F j + 1, k + 1 + 2F j + 1, k + F j + 1, k ­ 1 ­ (F j­1, k + 1 + 2F j ­ 1, k + F j­1, k ­ 1 GY = F j­1, k ­ 1 + 2F j, k ­ 1 + F j + 1, k ­ 1 ­ (F j­1, k + 1 + 2F j, k + 1 + F j + 1, k + 1) where (j, k) are the coordinates of each pixel Fjk in the Image. This is equivalent to a convolution using the masks, ­1 0 1 ­1 ­2 ­1 X mask = ­2 0 2 Y mask = 0 0 0 ­1 0 1 1 2 1 All of the edge points in the result are set to zero. Syntax Result = SOBEL(Image) Return Value SOBEL returns a two-dimensional array of the same size as Image. If Image is of type byte or integer then the result is of integer type, otherwise the result is of the same type as Image. Note To avoid overflow for integer types, the computation is done using the next larger signed type and the result is transformed back to the correct type. Values larger than the maximum for that integer type are truncated. For example, for integers the function is computed using type long, and on output, values larger than 32767 are set equal to 32767. Arguments Image The two-dimensional array containing the image to which edge enhancement is applied. Example If the variable myimage contains a two-dimensional image array, a Sobel sharpened version of myimage can be displayed with the command: TVSCL, SOBEL(myimage) See Also ROBERTS SOCKET [Previous Routine] [Next Routine] [List of Routines] NAME: SOCKET The SOCKET procedure, supported on UNIX and Microsoft Windows platforms, opens a client-side TCP/IP Internet socket as an IDL file unit. Such files can be used in the standard manner with any of IDL's Input/Output routines. Tip RSI recommends that you don't use the EOF procedure as a way to check to see if a socket is empty. It is recommended that you structure your communication across the socket so that using EOF is not necessary to know when the communication is complete. Syntax SOCKET, Unit, Host, Port [, CONNECT_TIMEOUT=value] [, ERROR=variable] [, /GET_LUN] [, /RAWIO] [, READ_TIMEOUT=value] [, /SWAP_ENDIAN] [, /SWAP_IF_BIG_ENDIAN] [, /SWAP_IF_LITTLE_ENDIAN] [, WIDTH=value] [, WRITE_TIMEOUT=value] UNIX-Only Keywords: [, /STDIO] Arguments Unit The unit number to associate with the opened socket. Host The name of the host to which the socket is connected. This can be either a standard Internet host name (e.g. ftp.ResearchSystems.com) or a dot-separated numeric address (e.g. 192.5.156.21). Port The port to which the socket is connected on the remote machine. If this is a well- known port (as contained in the /etc/services file on a UNIX host), then you can specify its name (e.g. daytime); otherwise, specify a number. Keywords CONNECT_TIMEOUT Set this keyword to the number of seconds to wait before giving up and issuing an error to shorten the connect timeout from the system-supplied default. Most experts recommend that you not specify an explicit timeout, and instead use your operating system defaults. Note Although you can use CONNECT_TIMEOUT to shorten the timeout, you cannot increase it past the system-supplied default. ERROR A named variable in which to place the error status. If an error occurs in the attempt to open File, IDL normally takes the error handling action defined by the ON_ERROR and/or ON_IOERROR procedures. SOCKET always returns to the caller without generating an error message when ERROR is present. A nonzero error status indicates that an error occurred. The error message can then be found in the system variable !ERR_STRING. GET_LUN Set this keyword to use the GET_LUN procedure to set the value of Unit before the file is opened. Instead of using the two statements: GET_LUN, Unit OPENR, Unit, 'data.dat' you can use the single statement: OPENR, Unit, 'data.dat', /GET LUN RAWIO Set this keyword to disable all use of the standard operating system I/O for the file, in favor of direct calls to the operating system. This allows direct access to devices, such as tape drives, that are difficult or impossible to use effectively through the standard I/O. Using this keyword has the following implications: * No formatted or associated (ASSOC) I/O is allowed on the file. Only READU and WRITEU are allowed. * Normally, attempting to read more data than is available from a file causes the unfilled space to be set to zero and an error to be issued. This does not happen with files opened with RAWIO. When using RAWIO, the programmer must check the transfer count, either via the TRANSFER_COUNT keywords to READU and WRITEU, or the FSTAT function. * The EOF and POINT_LUN functions cannot be used with a file opened with RAWIO. * Each call to READU or WRITEU maps directly to UNIX read(2) and write(2) system calls. The programmer must read the UNIX system documentation for these calls and documentation on the target device to determine if there are any special rules for I/O to that device. For example, the size of data that can be transferred to many cartridge tape drives is often forced to be a multiple of 512 bytes. READ_TIMEOUT Set this keyword to the number of seconds to wait for data to arrive before giving up and issuing an error. By default, IDL blocks indefinitely until the data arrives. Typically, this option is unnecessary on a local network, but it is useful with networks that are slow or unreliable. SWAP_ENDIAN Set this keyword to swap byte ordering for multi-byte data when performing binary I/O on the specified file. This is useful when accessing files also used by another system with byte ordering different than that of the current host. SWAP_IF_BIG_ENDIAN Setting this keyword is equivalent to setting SWAP_ENDIAN; it only takes effect if the current system has big endian byte ordering. This keyword does not refer to the byte ordering of the input data, but to the computer hardware. SWAP_IF_LITTLE_ENDIAN Setting this keyword is equivalent to setting SWAP_ENDIAN; it only takes effect if the current system has little endian byte ordering. This keyword does not refer to the byte ordering of the input data, but to the computer hardware. WIDTH The desired output width. When using the defaults for formatted output, IDL uses the following rules to determine where to break lines: * If the output file is a terminal, the terminal width is used. Under VMS, if the file has fixed-length records or a maximum record length, the record length is used. * Otherwise, a default of 80 columns is used. The WIDTH keyword allows the user to override this default. WRITE_TIMEOUT Set this keyword to the number of seconds to wait to send data before giving up and issuing an error. By default, IDL blocks indefinitely until it is possible to send the data. Typically, this option is unnecessary on a local network, but it is useful with networks that are slow or unreliable. UNIX-Only Keywords STDIO Under UNIX, forces the file to be opened via the standard C I/O library (stdio) rather than any other more native OS API that might usually be used. This is primarily of interest to those who intend to access the file from external code, and is not necessary for most uses. Note Under Windows, the STDIO feature is not possible. Requesting it causes IDL to throw an error. Example Most UNIX systems maintain a daytime server on the daytime port (port 13). There servers send a 1 line response when connected to, containing the current time of day. ; To obtain the current time from the host bullwinkle: SOCKET, 1, 'bullwinkle','daytime' date='' READF, 1, date CLOSE, 1 PRINT, date IDL prints: Wed Sep 15 17:20:27 1999 SORT [Previous Routine] [Next Routine] [List of Routines] NAME: SORT The SORT function returns a vector of subscripts that allow access to the elements of Array in ascending order. Syntax Result = SORT(Array [, /L64] ) Return Value The result is always a vector of integer type with the same number of elements as Array. Arguments Array The array to be sorted. Array can be any basic type of vector or array. String arrays are sorted using the ASCII collating sequence. Complex arrays are sorted by their magnitude. Array values which are Not A Number (NaN) are moved to the end of the resulting array. Keywords L64 By default, the result of SORT is 32-bit integer when possible, and 64-bit integer if the number of elements being sorted requires it. Set L64 to force 64-bit integers to be returned in all cases. Note Only 64-bit versions of IDL are capable of creating variables requiring a 64-bit sort. Check the value of !VERSION.MEMORY_BITS to see if your IDL is 64-bit or not. Example 1 A = [4, 3, 7, 1, 2] PRINT, 'SORT(A) = ', SORT(A) ; Display the elements of A in sorted order: PRINT, 'Elements of A in sorted order: ', A[SORT(A)] ; Display the elements of A in descending order: PRINT, 'Elements of A in descending order: ', A[REVERSE(SORT(A))] IDL prints: SORT(A) = 3 4 1 0 2 Elements of A in sorted order: 1 2 3 4 7 Elements of A in descending order: 7 4 3 2 1 SORT(A) returns "3 4 1 0 2" because: A[3] < A[4] < A[1] < A[0] < A[2] Example 2 Sorting NaN Values When sorting data including Not A Number (NaN) values, the NaN entries are moved to the end of the resulting array. For example: values = [ 500, !VALUES.F_NAN, -500 ] PRINT, SORT(values) IDL prints: 2 0 1 See Also REVERSE, UNIQ, WHERE SPAWN [Previous Routine] [Next Routine] [List of Routines] NAME: SPAWN The SPAWN procedure spawns a child process to execute a command or series of commands. The result of calling SPAWN depends on the platform on which it is being used: * Under UNIX, the shell used (if any) is obtained from the SHELL environment variable. The NOSHELL keyword can be used to execute a command directly as a child process without starting a shell process. * Under VMS, the DCL command language interpreter is used. * Under Windows 95/98, a DOS window is opened. Under Windows NT, a Command Shell is opened. The NOSHELL keyword can be used to execute the specified command directly without starting an intermediate command interpreter shell. * On the Macintosh, SPAWN opens specified files or applications. On all platforms, IDL execution suspends until the spawned process terminates. If SPAWN is called without arguments, an interactive command interpreter process is started, in which you can enter one or more operating system commands. While you use the command interpreter process, IDL is suspended. Note For more information on using SPAWN, see the External Development Guide. Syntax SPAWN [, Command [, Result] [, ErrResult] ] Keywords (all platforms): [, COUNT=variable] [, EXIT_STATUS=variable] [, /FORCE] [, PID=variable] Macintosh-Only Keywords: [, MACCREATOR=string] [, /NOWAIT] UNIX-Only Keywords: [, /NOSHELL] [, /NOTTYRESET] [, /NULL_STDIN] [, /SH] [, /STDERR] [, /UNIT{Command required, Result not allowed}] VMS-Only Keywords: [, /NOCLISYM] [, /NOLOGNAM] [ [, /NOTIFY] , /NOWAIT] Windows-Only Keywords: [, /HIDE] [, /LOG_OUTPUT] [, /NOSHELL] [, /NOWAIT] [, /NULL_STDIN] [, /STDERR] Arguments Command A string containing the commands to be executed. If Command is present, it must be specified as follows: * On UNIX, Command is expected to be scalar unless used in conjunction with the NOSHELL keyword, in which case Command is expected to be a string array where each element is passed to the child process as a separate argument. * On Windows, Command can be a scalar string or string array. If it is a string array, SPAWN glues together each element of the string array, with each element separated by whitespace. * On the Macintosh, Command must consist of a comma-separated list of strings containing the names of files to be opened. Each filename must be a separate scalar string. If the first filename is an application, it is used to open the remaining files specified. Otherwise, each file is opened by the application that owns it. IDL suspends execution until all spawned applications have terminated. The user can regain control of IDL before a spawned application terminates by issuing the Command Period escape sequence. * On VMS, Command must be a scalar. If Command is not present, SPAWN starts an interactive command interpreter process, which you can use to enter one or more operating system commands. While you use the command interpreter process, IDL is suspended. Under Windows, an interactive MS-DOS window or NT command shell window is created for this purpose. UNIX and VMS spawn do not create a separate window, but simply run on the user's current tty. Under UNIX, the default shell is used (as specified by the SHELL environment variable). The SH keyword can be used to force use of the Bourne shell (/bin/sh). When you exit the child process, control returns to IDL, which resumes at the point where it left off. The IDL session remains exactly as you left it. It should be noted that using SPAWN in this manner is equivalent to using the IDL $ command. The difference between these two is that $ can only be used interactively while SPAWN can be used interactively or in IDL programs Result Under Macintosh, Result has no effect. A named variable in which to place the output from the child process. Each line of output becomes a single array element. If Result is not present, the output from the child shell process goes to the standard output (usually the terminal). ErrResult ErrResult is allowed under UNIX and Windows. It is not allowed under VMS, and it has no effect under the Macintosh OS. A named variable in which to place the error output (stderr) from the child process. Each line of output becomes a single array element. If ErrResult is not present, the error output from the child shell process goes to the standard error file. See the STDERR keyword for another error stream option. Keywords COUNT If Result is present and this keyword is also specified, COUNT specifies a named variable into which the number of lines of output is placed. This value gives the number of elements placed into Result. EXIT_STATUS Set this keyword to a named variable in which the exit status for the child process is returned. The meaning of this value is operating system dependent: * Under UNIX, it is the value passed by the child to exit(2), and is analogous to the value returned by $? under most UNIX shells. If the UNIT keyword is used, this keyword always returns 0. In this case, use the EXIT_STATUS keyword to FREE_LUN or CLOSE to determine the final exit status of the process. * Under VMS, it is the process status returned by LIB$SPAWN. If the NOWAIT keyword is set, EXIT_STATUS returns 1 (SS$_NORMAL). * Under Windows, it is the value returned by the Win32 GetExitCodeProcess() system function. If the NOWAIT keyword is set, EXIT_STATUS returns 0. FORCE Set this keyword to override buffered file output in IDL and force the file to be closed no matter what errors occur in the process. If it is not possible to properly flush this data when a file close is requested, an error is normally issued and the file remains open. An example of this might be that your disk does not have room to write the remaining data. This default behavior prevents data from being lost, but the FORCE keyword overrides this behavior. NOWAIT If this keyword is set, the IDL process continues executing in parallel with the subprocess. Normally, the IDL process suspends execution until the subprocess completes. Note Because the & character is commonly used in Unix to execute a command in the background, the NO_WAIT keyword is not necessary, and is therefore not accepted under Unix. To spawn a separate shell process under Unix, include the & character at the end of the command. For example: SPAWN, 'xterm &' PID A named variable into which the Process Identification number of the child process is stored. Macintosh-Only Keywords MACCREATOR Use this keyword to specify a four-character scalar string containing the Macintosh file creator code of the application to be used to open the specified files. In no files were specified, the application is launched without any files. UNIX-Only Keywords NOSHELL Set this keyword to specify that Command should execute directly as a child process without an intervening shell process. In this case, Command should be specified as a string array in which the first element is the name of the command to execute and the following arguments are the arguments to be passed to the command (C programmers will recognize this as the elements of the argv argument that UNIX passes to the child process main function). Since no shell is present, wildcard characters are not expanded, and other tasks normally performed by the shell do not occur. NOSHELL is useful when performing many SPAWNed operations from a program and speed is a primary concern. NOTTYRESET Some UNIX systems drop characters when the tty mode is switched between normal and raw modes. IDL switches between these modes when reading command input and when using the GET_KBRD function. On such systems, IDL avoids losing characters by delaying the switch back to normal mode until it is truly needed. This method has the benefit of avoiding the large number of mode changes that would otherwise be necessary. Routines that cause output to be sent to the standard output (e.g., I/O operations, user interaction and SPAWN) ensure that the tty is in its normal mode before performing their operations. If the NOTTYRESET keyword is set, SPAWN does not switch the tty back to normal mode before launching the child process assuming instead that the child will not send output to the tty. Use this keyword to avoid characters being dropped in a loop of the form: WHILE (GET_KBRD(0) NE 'q') SPAWN, command This keyword has no effect on systems that don't suffer from dropped characters. NULL_STDIN If set, the null device /dev/null is connected to the standard input of the child process. SH Set this keyword to force the use of the /bin/sh shell. Usually, the shell used is determined by the SHELL environment variable. STDERR If set, the child's error output (stderr) is combined with the standard output and returned in Result. STDERR and the ErrResult argument are mutually exclusive. You should use one or the other, but not both. UNIT If UNIT is present, SPAWN creates a child process in the usual manner, but instead of waiting for the specified command to finish, it attaches a bidirectional pipe between the child process and IDL. From the IDL session, the pipe appears as a logical file unit. The other end of the pipe is attached to the child process standard input and output. The UNIT keyword specifies a named variable into which the number of the file unit is stored. Once the child process is started, the IDL session can communicate with it through the usual input/output facilities. After the child process has done its task, the CLOSE procedure can be used to kill the process and close the pipe. Since SPAWN uses GET_LUN to allocate the file unit, FREE_LUN should be used to free the unit. If UNIT is present, Command must be present, and Result is not allowed. Windows-Only Keywords HIDE If HIDE is set, the command interpreter shell window is minimized to prevent the user from seeing it. LOG_OUTPUT Normally, IDL starts a command interpreter shell, and output from the child process is displayed in the command interpreter's window. If LOG_OUTPUT is set, the command interpreter window is minimized (as with HIDE) and all output is diverted to the IDLDE log window. If the Result or ErrResult arguments are present, they take precedence over LOG_OUTPUT. NOSHELL If set, IDL starts the specified command directly without starting an intermediate command interpreter shell. This is useful for Windows programs that do not require a console, such as Notepad. Note Many common DOS commands (e.g. DIR) are not distinct programs, and are instead implemented as part of the command interpreter. Specifying NOSHELL with such commands results in the command not being found. In such cases, the HIDE keyword might be useful. NULL_STDIN If set, the null device NUL is connected to the standard input of the child process. STDERR If set, the child's error output (stderr) is combined with the standard output and returned in Result. STDERR and the ErrResult argument are mutually exclusive. You should use one or the other, but not both. VMS-Only Keywords NOCLISYM If this keyword is set, the spawned subprocess does not inherit command language interpreter symbols from its parent process. You can specify this keyword to prevent commands redefined by symbol assignments from affecting the spawned commands, or to speed process startup. NOLOGNAM If this keyword is set, the spawned subprocess does not inherit process logical names from its parent process. You can specify this keyword to prevent commands redefined by logical name assignments from affecting the spawned commands, or to speed process startup. NOTIFY If this keyword is set, a message is broadcast to SYS$OUTPUT when the child process completes or aborts. NOTIFY has no effect unless NOWAIT is set. Examples Example 1 To simply spawn a process from within IDL, enter the command: SPAWN To execute the UNIX ls command and return to the IDL prompt, enter: SPAWN, 'ls' To execute the UNIX ls command and store the result in the IDL string variable listing, enter: SPAWN, 'ls', listing Example 2 The UNIX grep(1) command is documented as providing an exit value of 0 if one or matches are found, 1 if no matches are found, and 2 if some other error prevents it from functioning. We can use this to determine if the word "Bullwinkle" appears in the text files in the current working directory: PRO test_for_moose SPAWN, 'grep Bullwinkle *.txt > /dev/null', EXIT_STATUS=e CASE e OF 0: PRINT, 'Bullwinkle exists' 1: PRINT, 'Bullwinkle does not exist' 2: PRINT, 'Grep encountered syntax or other errors' ELSE : PRINT, 'Unknown error in grep' ENDCASE END SPH_4PNT [Previous Routine] [Next Routine] [List of Routines] NAME: SPH_4PNT Given four 3-dimensional points, the SPH_4PNT procedure returns the center and radius necessary to define the unique sphere passing through those points. This routine is written in the IDL language. Its source code can be found in the file sph_4pnt.pro in the lib subdirectory of the IDL distribution. Syntax SPH_4PNT, X, Y, Z, Xc, Yc, Zc, R [, /DOUBLE] Arguments X, Y, Z 4-element floating-point or double-precision vectors containing the X, Y, and Z coordinates of the points. Xc, Yc, Zc Named variables that will contain the sphere's center X, Y, and Z coordinates. R A named variable that will contain the sphere's radius. Keywords DOUBLE Set this keyword to force computations to be done in double-precision arithmetic. Example Find the center and radius of the unique sphere passing through the points: (1, 1, 0), (2, 1, 2), (1, 0, 3), (1, 0, 1): ; Define the floating-point vectors containing the x, y and z ; coordinates of the points: X = [1, 2, 1, 1] + 0.0 Y = [1, 1, 0, 0] + 0.0 Z = [0, 2, 3, 1] + 0.0 ; Compute sphere's center and radius: SPH_4PNT, X, Y, Z, Xc, Yc, Zc, R ; Print the results: PRINT, Xc, Yc, Zc, R IDL prints: -0.500000 2.00000 2.00000 2.69258 See Also CIR_3PNT, PNT_LINE SPH_SCAT [Previous Routine] [Next Routine] [List of Routines] NAME: SPH_SCAT The SPH_SCAT function performs spherical gridding. Scattered samples on the surface of a sphere are interpolated to a regular grid. This routine is a convenient interface to the spherical gridding and interpolation provided by TRIANGULATE and TRIGRID. The returned value of the function is a regularly-interpolated grid. This routine is written in the IDL language. Its source code can be found in the file sph_scat.pro in the lib subdirectory of the IDL distribution. Syntax Result = SPH_SCAT( Lon, Lat, F [, BOUNDS=[lonmin, latmin, lonmax, latmax]] [, BOUT=variable] [, GOUT=variable] [, GS=[lonspacing, latspacing]] [, NLON=value] [, NLAT=value] ) Arguments Lon A vector of sample longitudes, in degrees. Note that Lon, Lat, and F must all have the same number of points. Lat A vector of sample latitudes, in degrees. F A vector of data values which are functions of Lon and Lat. Fi represents a value at (Loni, Lati). Keywords BOUNDS Set this keyword to a four-element vector containing the grid limits in longitude and latitude of the output grid. The four elements are: [Lonmin, Latmin, Lonmax, Latmax]. If this keyword is not set, the grid limits are set to the extent of Lon and Lat. Note that, to cover all longitudes, you must explicitly specify the values for the BOUNDS keyword. BOUT Set this keyword to a named variable that, on return, contains a four-element vector (similar to BOUNDS) that describes the actual extent of the regular grid. GOUT Set this keyword to a named variable that, on return, contains a two-element vector (similar to GS) that describes the actual grid spacing. GS Set this keyword to a two-element vector that specifies the spacing between grid points in longitude (the first element) and latitude (the second element). If this keyword is not set, the default value is based on the extents of Lon and Lat. The default longitude spacing is (Lonmax - Lonmin)/(NX-1). The default latitude spacing is (Latmax - Latmin)/(NY-1). If NX and NY are not set, the default grid size of 26 by 26 is used for NX and NY. NLON The output grid size in the longitude direction. The default value is 26. Note that NLON need not be specified if the size can be inferred from GS and BOUNDS. NLAT The output grid size in the latitude direction. The default value is 26. Note that NLAT need not be specified if the size can be inferred from GS and BOUNDS. Example ; Create some random longitude points: lon = RANDOMU(seed, 50) * 360. -180. ; Create some random latitude points: lat = RANDOMU(seed, 50) * 180. -90. ; Make a function to fit: z = SIN(lat*!DTOR) c = COS(lat*!DTOR) x = COS(lon*!DTOR) * c y = SIN(lon*!DTOR) * c ; The finished dependent variable: f = SIN(x+y) * SIN(x*z) ; Interpolate the data and return the result in variable r: r = SPH_SCAT(lon, lat, f, BOUNDS=[0, -90, 350, 85], GS=[10,5]) See Also TRIANGULATE, TRIGRID SPHER_HARM [Previous Routine] [Next Routine] [List of Routines] NAME: SPHER_HARM The SPHER_HARM function returns the value of the spherical harmonic Ylm( , ), ­l m l, l 0, which is a function of two coordinates on a spherical surface. The spherical harmonics are related to the associated Legendre polynomial by: Y + ( ­ )! lm( , ) 2l 1 -------------- l m ------------------- 4 (l + m)!Pm(cos )eim = l For negative m the following relation is used: Y1, ­m( , ) = (­1)mY * ( , ) lm where * represents the complex conjugate. This routine is written in the IDL language. Its source code can be found in the file spher_harm.pro in the lib subdirectory of the IDL distribution. Syntax Result = SPHER_HARM( Theta, Phi, L, M, [, /DOUBLE] ) Return Value SPHER_HARM returns a complex scalar or array containing the value of the spherical harmonic function. The return value has the same dimensions as the input arguments Theta and Phi. If one argument (Theta or Phi) is a scalar and the other argument is an array, the function uses the scalar value with each element of the array, and returns an array with the same dimensions as the input array. If either Theta or Phi are double-precision or if the DOUBLE keyword is set, the result is double-precision complex, otherwise the result is single-precision complex. Arguments Theta The value of the polar (colatitudinal) coordinate at which Ylm( , ) is evaluated. Theta can be either a scalar or an array. Phi The value of the azimuthal (longitudinal) coordinate at which Ylm( , ) is evaluated. Phi can be either a scalar or an array. L A scalar integer, L 0, specifying the order l of Ylm( , ). If L is of type float, it will be truncated. M A scalar integer, ­L M L, specifying the azimuthal order m of Ylm( , ). If M is of type float, it will be truncated. Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. Example This example visualizes the electron probability density for the hydrogen atom in state 3d0. (Feynman, Leighton, and Sands, 1965: The Feynman Lectures on Physics, Calif. Inst. Tech, Ch. 19): ; Define a data cube (N x N x N) n = 41L a = 60*FINDGEN(n)/(n-1) - 29.999 ; [-1,+1] x = REBIN(a, n, n, n) ; X-coordinates of cube y = REBIN(REFORM(a,1,n), n, n, n) ; Y-coordinates z = REBIN(REFORM(a,1,1,n), n, n, n); Z-coordinates ; Convert from rectangular (x,y,z) to spherical (phi, theta, r) spherCoord = CV_COORD(FROM_RECT= $ TRANSPOSE([[x[*]],[y[*]],[z[*]]]), /TO_SPHERE) phi = REFORM(spherCoord[0,*], n, n, n) theta = REFORM(!PI/2 - spherCoord[1,*], n, n, n) r = REFORM(spherCoord[2,*], n, n, n) ; Find electron probability density for hydrogen atom in state 3d0 ; Angular component L = 2 ; state "d" is electron spin L=2 M = 0 ; Z-component of spin is zero angularState = SPHER_HARM(theta, phi, L, M) ; Radial component for state n=3, L=2 radialFunction = EXP(-r/2)*(r^2) waveFunction = angularState*radialFunction probabilityDensity = ABS(waveFunction)^2 SHADE_VOLUME, probabilityDensity, $ 0.1*MEAN(probabilityDensity), vertex, poly oPolygon = OBJ_NEW('IDLgrPolygon', vertex, $ POLYGON=poly, COLOR=[180,180,180]) XOBJVIEW, oPolygon The results are shown in the following figure (rotated in XOBJVIEW for clarity): Figure 30: SPHER_HARM Example of Hydrogen Atom (object rotated in XOBJVIEW for clarity) See Also LEGENDRE, LAGUERRE SPL_INIT [Previous Routine] [Next Routine] [List of Routines] NAME: SPL_INIT The SPL_INIT function is called to establish the type of interpolating spline for a tabulated set of functional values Xi, Yi = F(Xi). SPL_INIT returns the values of the 2nd derivative of the interpolating function at the points Xi. It is important to realize that SPL_INIT should be called only once to process an entire tabulated function in arrays X and Y. Once this has been done, values of the interpolated function for any value of X can be obtained by calls (as many as desired) to the separate function SPL_INTERP. SPL_INIT is based on the routine spline described in section 3.3 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press, and is used by permission. Syntax Result = SPL_INIT( X, Y [, /DOUBLE] [, YP0=value] [, YPN_1=value] ) Arguments X An n-element input vector that specifies the tabulate points in ascending order. Y An n-element input vector that specifies the values of the tabulated function F(Xi) corresponding to Xi. Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. YP0 The first derivative of the interpolating function at the point X0. If YP0 is omitted, the second derivative at the boundary is set to zero, resulting in a "natural spline." YPN_1 The first derivative of the interpolating function at the point Xn-1. If YPN_1 is omitted, the second derivative at the boundary is set to zero, resulting in a "natural spline." Example Example 1 X = (FINDGEN(21)/20.) * 2.0*!PI Y = SIN(X) PRINT, SPL_INIT(X, Y, YP0 = -1.1, YPN_1 = 0.0) IDL Prints: 23.1552 -6.51599 1.06983 -1.26115 -0.839544 -1.04023 -0.950336 -0.817987 -0.592022 -0.311726 2.31192e-05 0.311634 0.592347 0.816783 0.954825 1.02348 0.902068 1.02781 -0.198994 3.26597 -11.0260 Example 2 PRINT, SPL_INIT(X, Y, YP0 = -1.1) IDL prints: 23.1552 -6.51599 1.06983 -1.26115 -0.839544 -1.04023 -0.950336 -0.817988 -0.592020 -0.311732 4.41521e-05 0.311555 0.592640 0.815690 0.958905 1.00825 0.958905 0.815692 0.592635 0.311567 0.00000 See Also SPL_INTERP, SPLINE, SPLINE_P SPL_INTERP [Previous Routine] [Next Routine] [List of Routines] NAME: SPL_INTERP Given the arrays X and Y, which tabulate a function (with the Xi in ascending order), and given the array Y2, which is the output from SPL_INIT, and given an input value of X2, the SPL_INTERP function returns a cubic-spline interpolated value for the given value of XI. The result has the same structure as X2, and is either single- or double-precision floating, based on the input type. SPL_INTERP is based on the routine splint described in section 3.3 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press, and is used by permission. Syntax Result = SPL_INTERP( X, Y, Y2, X2 [, /DOUBLE] ) Arguments X An input array that specifies the tabulated points in ascending order. Y An input array that specifies the values of the tabulate function corresponding to Xi. Y2 The output from SPL_INIT for the specified X and Y. X2 The input value for which an interpolated value is desired. X can be scalar or an array of values. The result of SPL_INIT will have the same structure. Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. Example To create a spline interpolation over a tabulated set of data, [Xi, Yi], first create the tabulated data. In this example, Xi will be in the range [0.0, 2 ] and Yi in the range [sin(0.0), sin(2 )]. X = (FINDGEN(21)/20.0) * 2.0 * !PI Y = SIN(X) ; Calculate interpolating cubic spline: Y2 = SPL_INIT(X, Y) ; Define the X values P at which we desire interpolated Y values: X2= FINDGEN(11)/11.0 * !PI ; Calculate the interpolated Y values corresponding to X2[i]: result = SPL_INTERP(X, Y, Y2, X2) PRINT, result IDL prints: 0.00000 0.281733 0.540638 0.755739 0.909613 0.989796 0.989796 0.909613 0.755739 0.540638 0.281733 The exact solution vector is sin(X2). To interpolate a line in the XY plane, see SPLINE_P. See Also SPL_INIT, SPLINE, SPLINE_P SPLINE [Previous Routine] [Next Routine] [List of Routines] NAME: SPLINE The SPLINE function performs cubic spline interpolation. This routine is written in the IDL language. Its source code can be found in the file spline.pro in the lib subdirectory of the IDL distribution. Syntax Result = SPLINE( X, Y, T [, Sigma] ) Arguments X The abscissa vector. Values must be monotonically increasing. Y The vector of ordinate values corresponding to X. T The vector of abscissa values for which the ordinate is desired. The values of T must be monotonically increasing. Sigma The amount of "tension" that is applied to the curve. The default value is 1.0. If sigma is close to 0, (e.g., .01), then effectively there is a cubic spline fit. If sigma is large, (e.g., greater than 10), then the fit will be like a polynomial interpolation. Example The commands below show a typical use of SPLINE: ; X values of original function: X = [2.,3.,4.] ; Make a quadratic Y = (X-3)^2 ;Values for interpolated points: T = FINDGEN(20)/10.+2 ; Do the interpolation: Z = SPLINE(X,Y,T) See Also SPL_INIT, SPLINE_P SPLINE_P [Previous Routine] [Next Routine] [List of Routines] NAME: SPLINE_P The SPLINE_P procedure performs parametric cubic spline interpolation with relaxed or clamped end conditions. This routine is both more general and faster than the SPLINE function. One call to SPLINE_P is equivalent to two calls to SPLINE, as both the X and Y are interpolated with splines. It is suited for interpolating between randomly placed points, and the abscissa values need not be monotonic. In addition, the end conditions may be optionally specified via tangents. This routine is written in the IDL language. Its source code can be found in the file spline_p.pro in the lib subdirectory of the IDL distribution. Syntax SPLINE_P, X, Y, Xr, Yr [, INTERVAL=value] [, TAN0=[X0, Y0]] [, TAN1=[Xn-1, Yn-1]] Arguments X The abscissa vector. X should be floating-point or double-precision. Y The vector of ordinate values corresponding to X. Y should be floating-point or double-precision. Neither X or Y need be monotonic. Xr A named variable that will contain the abscissa values of the interpolated function. Yr A named variable that will contain the ordinate values of the interpolated function. Keywords INTERVAL Set this keyword equal to the desired interval in XY space between interpolants. If omitted, approximately 8 interpolants per XY segment will result. TAN0 The tangent to the spline curve at X[0], Y[0]. If omitted, the tangent is calculated to make the curvature of the result zero at the beginning. TAN0 is a two element vector, containing the X and Y components of the tangent. TAN1 The tangent to the spline curve at X[n-1], Y[n-1]. If omitted, the tangent is calculated to make the curvature of the result zero at the end. TAN1 is a two element vector, containing the X and Y components of the tangent. Example The commands below show a typical use of SPLINE_P: ; Abscissas for square with a vertical diagonal: X = [0.,1,0,-1,0] ; Ordinates: Y = [0.,1,2,1,0] ; Interpolate with relaxed end conditions: SPLINE_P, X, Y, XR, YR ; Show it: PLOT, XR, YR As above, but with setting both the beginning and end tangents: SPLINE_P, X, Y, XR, YR, TAN0=[1,0], TAN1=[1,0] This yields approximately 32 interpolants. As above, but with setting the interval to 0.05, making more interpolants, closer together: SPLINE_P, X, Y, XR, YR, TAN0=[1,0], TAN1=[1,0], INTERVAL=0.05 This yields 116 interpolants and looks close to a circle. See Also SPL_INIT, SPLINE SPRSAB [Previous Routine] [Next Routine] [List of Routines] NAME: SPRSAB The SPRSAB function performs matrix multiplication on two row-indexed sparse arrays created by SPRSIN. The routine computes all components of the matrix products, but only stores those values whose absolute magnitude exceeds the threshold value. The result is a row-indexed sparse array. SPRSAB is based on the routine sprstm described in section 2.7 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press, and is used by permission. The difference between the two routines is that SPRSAB performs the matrix multiplication A.B rather than A.BT. Syntax Result = SPRSAB( A, B [, /DOUBLE] [, THRESHOLD=value] ) Arguments A, B Row-indexed sparse arrays created by the SPRSIN function. Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. THRESHOLD Use this keyword to set the criterion for deciding the absolute magnitude of the elements to be retained in sparse storage mode. For single-precision calculations, the default value is 1.0 × 10-7. For double-precision calculations, the default is 1.0 × 10- 14. Example ; Begin by creating two arrays: A = [[ 5.0, 0.0, 0.0, 1.0], $ [ 3.0, -2.0, 0.0, 1.0], $ [ 4.0, -1.0, 0.0, 2.0], $ [ 0.0, 3.0, 3.0, 1.0]] B = [[ 1.0, 2.0, 3.0, 1.0], $ [ 3.0, -3.0, 0.0, 1.0], $ [-1.0, 3.0, 1.0, 2.0], $ [ 0.0, 3.0, 3.0, 1.0]] ; Convert the arrays to sparse array format before multiplying. The ; variable SPARSE holds the result in sparse array form: sparse = SPRSAB(SPRSIN(A), SPRSIN(B)) ; Restore the sparse array structure to full storage mode: result = FULSTR(sparse) ; Print the result: PRINT, 'result:' PRINT, result ; Check this result by multiplying the original arrays: exact = B # A PRINT, 'exact:' PRINT, exact IDL prints: result: 5.00000 13.0000 18.0000 6.00000 -3.00000 15.0000 12.0000 2.00000 1.00000 17.0000 18.0000 5.00000 6.00000 3.00000 6.00000 10.0000 exact: 5.00000 13.0000 18.0000 6.00000 -3.00000 15.0000 12.0000 2.00000 1.00000 17.0000 18.0000 5.00000 6.00000 3.00000 6.00000 10.0000 See Also FULSTR, LINBCG, SPRSAX, SPRSIN, SPRSTP, READ_SPR, WRITE_SPR SPRSAX [Previous Routine] [Next Routine] [List of Routines] NAME: SPRSAX The SPRSAX function takes a row-indexed sparse array created by the SPRSIN function and multiplies it by an n-element vector to its right. The result is a n-element vector. SPRSAX is based on the routine sprsax described in section 2.7 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press, and is used by permission. Syntax Result = SPRSAX( A, X [, /DOUBLE] ) Arguments A A row-indexed sparse array created by the SPRSIN function. X An n-element right hand vector. Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. Example ; Begin by creating an array A: A = [[ 5.0, 0.0, 0.0], $ [ 3.0, -2.0, 0.0], $ [ 4.0, -1.0, 0.0]] ; Define the right-hand vector: X = [1.0, 2.0, -1.0] ; Convert to sparse format, then multiply by X: result = SPRSAX(SPRSIN(A),X) ; Print the result: PRINT, result IDL prints: 5.00000 -1.00000 2.00000 See Also FULSTR, LINBCG, SPRSAB, SPRSIN, SPRSTP, READ_SPR, WRITE_SPR SPRSIN [Previous Routine] [Next Routine] [List of Routines] NAME: SPRSIN The SPRSIN function converts an array, or list of subscripts and values, into a row- index sparse storage mode, retaining only elements with an absolute magnitude greater than or equal to the specified threshold. The list form is much more efficient than the array form if the density of the matrix is low. The result is a row-indexed sparse array contained in structure form. The structure consists of two linear sparse storage vectors: SA, a vector of array values, and IJA, a vector of subscripts to the SA vector. The length of these vectors is equal to 1 plus the number of diagonal elements of the array, plus the number of off-diagonal elements with an absolute magnitude greater that or equal to the threshold value. Diagonal elements of the array are always retained even if their absolute magnitude is less than the specified threshold. SPRSIN is based on the routine sprsin described in section 2.7 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press, and is used by permission. Syntax Result = SPRSIN( A [, /COLUMN] [, /DOUBLE] [, THRESHOLD=value] ) or Result = SPRSIN(Columns, Rows, Values, N [, /DOUBLE] [, THRESHOLD=value]) Arguments A An n by n array of any type except string or complex. Columns A vector containing the column subscripts of the non-zero elements. Values must be in the range of 0 to (N-1). Rows A vector, of the same length as Column, containing the row subscripts of the non- zero elements. Values must be in the range of 0 to (N-1). Values A vector, of the same length as Column, containing the values of the non-zero elements. N The size of the resulting sparse matrix. Keywords COLUMN Set this keyword if the input array A is in column-major format (composed of column vectors) rather than in row-major format (composed of row vectors). This keyword is not allowed in the list form of the call. DOUBLE Set this keyword to convert the sparse array to double-precision. THRESHOLD Use this keyword to set the criterion for deciding the absolute magnitude of the elements to be retained in sparse storage mode. For single-precision calculations, the default value is 1.0 × 10-7. For double-precision values, the default is 1.0 × 10-14. Examples Example1 Suppose we wish to convert the following array to sparse storage format: A = [[ 5.0, -0.2, 0.1], $ [ 3.0, -2.0, 0.3], $ [ 4.0, -1.0, 0.0]] ; Convert to sparse storage mode. All elements of the array A that ; have absolute values less than THRESH are set to zero. sparse = SPRSIN(A, THRESH = 0.5) The variable SPARSE now contains a representation of A in structure form. See the description of FULSTR for an example that restores such a structure to full storage mode. Example2 This example demonstrates how to use the list form of the call to SPRSIN. The following line of code creates a sparse matrix, equivalent to a 100 by 100 identity matrix, i.e. all diagonal elements are set to 1, all other elements are zero: I100 = SPRSIN(LINDGEN(100), LINDGEN(100), REPLICATE(1.0,100), 100) See Also FULSTR, LINBCG, SPRSAB, SPRSAX, SPRSTP, READ_SPR, WRITE_SPR SPRSTP [Previous Routine] [Next Routine] [List of Routines] NAME: SPRSTP The SPRSTP function constructs the transpose of a sparse matrix. Syntax Result = SPRSTP(A) Arguments A A row-indexed sparse array created by the SPRSIN function. Keywords None Example This example creates a 100 by 100 pseudo-random sparse matrix, with 1000 non-zero elements, and then computes the product of the matrix and its transpose: n = 100 ;Dimensions of matrix m = 1000 ;Number of non-zero elements a = SPRSIN(RANDOMU(seed, m)*n, RANDOMU(seed, m)*n, $ RANDOMU(seed, m),n) b = SPRSAB(a, SPRSTP(a)) ;Transpose and create the product See Also FULSTR, LINBCG, SPRSAB, SPRSAX, SPRSIN, READ_SPR, WRITE_SPR SQRT [Previous Routine] [Next Routine] [List of Routines] NAME: SQRT The SQRT function returns the square root of X. Syntax Result = SQRT(X) Arguments X The value for which the square root is desired. If X is double-precision floating-point or complex, the result is of the same type. All other types are converted to single- precision floating-point and yield floating-point results. When applied to complex numbers, z = x+iy: 1/2 1/2 z1/2 1 = --- --- 2(r + x) i 12(r ­ x) r = x2 y2 + The ambiguous sign is taken to be the same as the sign of y. The result has the same structure as X. Example To find the square root of 145 and store the result in variable S, enter: S = SQRT(145) STANDARDIZE [Previous Routine] [Next Routine] [List of Routines] NAME: STANDARDIZE The STANDARDIZE function computes standardized variables from an array of m variables (columns) and n observations (rows). The result is an m-column, n-row array where all columns have a mean of zero and a variance of one. This routine is written in the IDL language. Its source code can be found in the file standardize.pro in the lib subdirectory of the IDL distribution. Syntax Result = STANDARDIZE( A [, /DOUBLE] ) Arguments A An m-column, n-row single- or double-precision floating-point array. Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. Example ; Define an array with 4 variables and 20 observations: array = $ [[19.5, 43.1, 29.1, 11.9], $ [24.7, 49.8, 28.2, 22.8], $ [30.7, 51.9, 37.0, 18.7], $ [29.8, 54.3, 31.1, 20.1], $ [19.1, 42.2, 30.9, 12.9], $ [25.6, 53.9, 23.7, 21.7], $ [31.4, 58.5, 27.6, 27.1], $ [27.9, 52.1, 30.6, 25.4], $ [22.1, 49.9, 23.2, 21.3], $ [25.5, 53.5, 24.8, 19.3], $ [31.1, 56.6, 30.0, 25.4], $ [30.4, 56.7, 28.3, 27.2], $ [18.7, 46.5, 23.0, 11.7], $ [19.7, 44.2, 28.6, 17.8], $ [14.6, 42.7, 21.3, 12.8], $ [29.5, 54.4, 30.1, 23.9], $ [27.7, 55.3, 25.7, 22.6], $ [30.2, 58.6, 24.6, 25.4], $ [22.7, 48.2, 27.1, 14.8], $ [25.2, 51.0, 27.5, 21.1]] ; Compute the mean and variance of each variable using the MOMENT ; function. The skewness and kurtosis are also computed: FOR K = 0, 3 DO PRINT, MOMENT(array[K,*]) ; Compute the standardized variables: result = STANDARDIZE(array) ; Compute the mean and variance of each standardized variable using ; the MOMENT function. The skewness and kurtosis are also computed: FOR K = 0, 3 DO PRINT, MOMENT(result[K,*]) IDL prints: 25.3050 25.2331 -0.454763 -1.10028 51.1700 27.4012 -0.356958 -1.19516 27.6200 13.3017 0.420289 0.104912 20.1950 26.0731 -0.363277 -1.24886 -7.67130e-07 1.00000 -0.454761 -1.10028 -3.65451e-07 1.00000 -0.356958 -1.19516 -1.66707e-07 1.00000 0.420290 0.104913 4.21703e-07 1.00000 -0.363278 -1.24886 See Also MOMENT STDDEV [Previous Routine] [Next Routine] [List of Routines] NAME: STDDEV The STDDEV function computes the standard deviation of an n-element vector. Syntax Result = STDDEV( X [, /DOUBLE] [, /NAN] ) Arguments X A numeric vector. Keywords DOUBLE If this keyword is set, computations are performed in double precision arithmetic. NAN Set this keyword to cause the routine to check for occurrences of the IEEE floating- point value NaN in the input data. Elements with the value NaN are treated as missing data. (See "Special Floating-Point Values" in Chapter 17 of Building IDL Applications for more information on IEEE floating-point values.) Example ; Define the n-element vector of sample data: x = [65, 63, 67, 64, 68, 62, 70, 66, 68, 67, 69, 71, 66, 65, 70] ; Compute the standard deviation: result = STDDEV(x) PRINT, result IDL prints: 2.65832 See Also KURTOSIS, MEAN, MEANABSDEV, MOMENT, SKEWNESS, VARIANCE STOP [Previous Routine] [Next Routine] [List of Routines] NAME: STOP The STOP procedure stops the execution of a running program or batch file. Control reverts to the interactive mode. Syntax STOP [, Expr1, ..., Exprn] Arguments Expri One or more expressions whose value is printed. If no parameters are present, a brief message describing where the STOP was encountered is printed. Example Suppose that you want to stop the execution of a procedure and print the values of the variables A, B, C and NUM. At the appropriate location in your procedure include the command: STOP, A, B, C, NUM To continue execution of the procedure (if possible) enter the IDL executive command: .CONT See Also BREAKPOINT, EXIT, WAIT STRARR [Previous Routine] [Next Routine] [List of Routines] NAME: STRARR The STRARR function returns a string array containing zero-length strings. Syntax Result = STRARR(D1, ..., D8) Arguments Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. The dimensions of the result. The dimension parameters can be any scalar expression. Up to eight dimensions can be specified. Example To create S, a 20-element string vector, enter: S = STRARR(20) See Also BYTARR, COMPLEXARR, DBLARR, DCOMPLEXARR, FLTARR, INTARR, LON64ARR, LONARR, MAKE_ARRAY, UINTARR, ULON64ARR, ULONARR STRCMP [Previous Routine] [Next Routine] [List of Routines] NAME: STRCMP The STRCMP function performs string comparisons between its two String arguments, returning True (1) for those that match and False (0) for those that do not. Normally, the IDL equality operator (EQ) is used for such comparisons, but STRCMP can optionally perform case-insensitive comparisons and can be limited to compare only the first N characters of the two strings, both of which require extra steps using the EQ operator. Syntax Result = STRCMP( String1, String2 [, N] [, /FOLD_CASE] ) Return Value If all of the arguments are scalar, the result is scalar. If one of the arguments is an array, the result is an integer with the same structure. If more than one argument is an array, the result has the structure of the smallest array. Each element of the result contains True (1) if the corresponding elements of String1 and String2 are the same, and False (0) otherwise. Arguments String1, String2 The strings to be compared. N Normally String1 and String2 are compared in their entirety. If N is specified, the comparison is made on at most the first N characters of each string. Keywords FOLD_CASE String comparison is normally a case sensitive operation. Set FOLD_CASE to perform case insensitive comparisons instead. Example Compare two strings in a case-insensitive manner, considering only the first 3 characters: Result = STRCMP('Moose', 'moo', 3, /FOLD_CASE) PRINT, Result IDL prints: 1 See Also STREGEX, STRJOIN, STRMATCH, STRMID, STRPOS, STRSPLIT STRCOMPRESS [Previous Routine] [Next Routine] [List of Routines] NAME: STRCOMPRESS The STRCOMPRESS function returns a copy of String with all whitespace (blanks and tabs) compressed to a single space or completely removed. Syntax Result = STRCOMPRESS( String [, /REMOVE_ALL] ) Arguments String The string to be compressed. If not of type string, it is converted using IDL's default formatting rules. If String is an array, the result is an array with the same structure- each element contains a compressed copy of the corresponding element of String. Keywords REMOVE_ALL Set this keyword to remove all whitespace. Normally, all whitespace is compressed to a single space. Example ; Create a string variable S: S = 'This is a string with spaces in it.' ; Print S with all of the whitespace removed: PRINT, STRCOMPRESS(S, /REMOVE_ALL) IDL Output Thisisastringwithspacesinit. See Also STRTRIM STREAMLINE [Previous Routine] [Next Routine] [List of Routines] NAME: STREAMLINE The STREAMLINE procedure generates the visualization graphics from a path. The output is a polygonal ribbon which is tangent to a vector field along its length. The ribbon is generated by placing a line at each vertex in the direction specified by each normal value multiplied by the anisotropy factor. The input normal array is not normalized before use, making it possible to vary the ribbon width as well. Syntax STREAMLINE, Verts, Conn, Normals, Outverts, Outconn [, ANISOTROPY=array] [, SIZE=vector] [, PROFILE=array] Arguments Verts Input array of path vertices ([3, n] array). Conn Input path connectivity array in IDLgrPolyline POLYLINES keyword format. There is one set of line segments in this array for each streamline. Normals Normal estimate at each input vertex ([3, n] array). Outverts Output vertices ([3xM] float array). Useful if the routine is to be used with Direct Graphics or the user wants to manipulate the data directly. Outconn Output polygonal connectivity array to match the output vertices. Keywords ANISOTROPY Set this input keyword to a three-element array describing the distance between grid points in each dimension. The default value is [1.0, 1.0, 1.0] SIZE Set this keyword to a vector of values (one for each path point). These values are used to specify the width of the ribbon or the size of profile at each point along its path. This keyword is generally used to convey additional data parameters along the streamline. PROFILE Set this keyword an array of two-dimensional points which are treated as the cross section of the ribbon instead of a line segment. If the first and last points in the array are the same, a closed profile is generated. The profile is placed at each path vertex in the plane perpendicular to the line connecting each path vertex with the vertex normal defining the up direction. This allows for the generation of streamtubes and other geometries. STREGEX [Previous Routine] [Next Routine] [List of Routines] NAME: STREGEX The STREGEX function performs regular expression matching against the strings contained in StringExpression. STREGEX can perform either a simple boolean True/False evaluation of whether a match occurred, or it can return the position and offset within the strings for each match. The regular expressions accepted by this routine, which correspond to "Posix Extended Regular Expressions", are similar to those used by such UNIX tools as egrep, lex, awk, and Perl. For more information about regular expressions, see "Learning About Regular Expressions" in Chapter 4 of Building IDL Applications. STREGEX is based on the regex package written by Henry Spencer, modified by RSI only to the extent required to integrate it into IDL. This package is freely available at ftp://zoo.toronto.edu/pub/regex.shar. Syntax Result = STREGEX( StringExpression, RegularExpression [, /BOOLEAN | , /EXTRACT | , LENGTH=variable [, /SUBEXPR]] [, /FOLD_CASE] ) Return Value By default, STREGEX returns the position and length of the matched string within StringExpression. If no match is found, -1 is returned for both of these. Optionally, it can return a boolean True/False result of the match, or the matched strings. Arguments StringExpression String to be matched. RegularExpression A scalar string containing the regular expression to match. See "Learning About Regular Expressions" in Chapter 4 of Building IDL Applications for a description of the meta characters that can be used in a regular expression. Keywords BOOLEAN Normally, STREGEX returns the position of the first character in StringExpression that matches RegularExpression. Setting BOOLEAN modifies this behavior to simply return a True/False value indicating if a match occurred or not. EXTRACT Normally, STREGEX returns the position of the first character in StringExpression that matches RegularExpression. Setting EXTRACT modifies this behavior to simply return the matched substrings. The EXTRACT keyword cannot be used with either BOOLEAN or LENGTH. FOLD_CASE Regular expression matching is normally a case-sensitive operation. Set FOLD_CASE to perform case-insensitive matching instead. LENGTH If present, specifies a variable to receive the lengths of the matches. Together with this result of this function, which contains the starting points of the matches in StringExpression, LENGTH can be used with the STRMID function to extract the matched substrings. The LENGTH keyword cannot be used with either BOOLEAN or EXTRACT. SUBEXPR By default, STREGEX only reports the overall match. Setting SUBEXPR causes it to report the overall match as well as any subexpression matches. A subexpression is any part of a regular expression written within parentheses. For example, the regular expression `(a)(b)(c+)' has 3 subexpressions, whereas the functionally equivalent 'abc+' has none. The SUBEXPR keyword cannot be used with BOOLEAN. If a subexpression participated in the match several times, the reported substring is the last one it matched. Note, as an example in particular, that when the regular expression `(b*)+' matches `bbb', the parenthesized subexpression matches the three 'b's and then an infinite number of empty strings following the last `b', so the reported substring is one of the empties. This occurs because the `*' matches zero or more instances of the character that precedes it. In order to return multiple positions and lengths for each input, the result from SUBEXPR has a new first dimension added compared to StringExpression. Examples Example 1 To match a string starting with an "a", followed by a "b", followed by 1 or more "c": pos = STREGEX('aaabccc', 'abc+', length=len) PRINT, STRMID('aaabccc', pos, len) IDL Prints: abccc To perform the same match, and also find the locations of the three parts: pos = STREGEX('aaabccc', '(a)(b)(c+)', length=len, /SUBEXPR) print, STRMID('aaabccc', pos, len) IDL Prints: abccc a b ccc Or more simply: print,STREGEX('aaabccc','(a)(b)(c+)',/SUBEXPR,/EXTRACT) IDL Prints: abccc a b ccc Example 2 This example searches a string array for words of any length beginning with "f" and ending with "t" without the letter "o" in between: str = ['foot', 'Feet', 'fate', 'FAST', 'ferret', 'affluent'] PRINT, STREGEX(str, '^f[^o]*t$', /EXTRACT, /FOLD_CASE) This statement results in: Feet FAST ferret Note the following about this example: * Unlike the * wildcard character used by STRMATCH, the * meta character used by STREGEX applies to the item directly on its left, which in this case is [^o], meaning "any character except the letter `o' ". Therefore, [^o]* means "zero or more characters that are not `o' ", whereas the following statement would find only words whose second character is not "o": PRINT, str[WHERE(STRMATCH(str, 'f[!o]*t', /FOLD_CASE) EQ 1)] * The anchors (^ and $) tell STREGEX to find only words that begin with "f" and end with "t". If we left out the ^ anchor in the above example, STREGEX would also return "ffluent" (a substring of "affluent"). Similarly, if we left out the $ anchor, STREGEX would also return "fat" (a substring of "fate"). See Also STRCMP, STRJOIN, STRMATCH, STRMID, STRPOS, STRSPLIT STRETCH [Previous Routine] [Next Routine] [List of Routines] NAME: STRETCH The STRETCH procedure stretches the image display color tables so the full range runs from one color index to another. The modified colortable is loaded, but the COLORS common block is not changed. The original colortable can be restored by calling STRETCH with no arguments. A colortable must be loaded before STRETCH can be called. This routine is written in the IDL language. Its source code can be found in the file stretch.pro in the lib subdirectory of the IDL distribution. Syntax STRETCH [, Low, High [, Gamma]] [, /CHOP] Arguments Low The lowest pixel value to use. If this parameter is omitted, 0 is assumed. Appropriate values range from 0 to the number of available colors-1. If no parameters are supplied, the original color tables are restored. High The highest pixel value to use. If this parameter is omitted, the number of colors-1 is assumed. Appropriate values range from 0 to the number of available colors-1. Gamma An optional Gamma correction factor. If this value is omitted, 1.0 is assumed. Gamma correction works by raising the color indices to the Gamma power, assuming they are scaled into the range 0 to 1. Keywords CHOP Set this keyword to set color indices above the upper threshold to color index 0. Normally, values above the upper threshold are set to the maximum color index. Example Load the STD GAMMA-II color table by entering: LOADCT, 5 Create and display and image by entering: TVSCL, DIST(300) Now adjust the color table with STRETCH. Make the entire color table fit in the range 0 to 70 by entering: STRETCH, 0, 70 Notice that pixel values above 70 are now colored white. Restore the original color table by entering: STRETCH See Also GAMMA_CT, H_EQ_CT, MULTI, XLOADCT STRING [Previous Routine] [Next Routine] [List of Routines] NAME: STRING The STRING function returns its arguments converted to string type. It is similar to the PRINT procedure, except that its output is placed in a string rather than being output to the terminal. The case in which a single expression of type byte is specified without the FORMAT keyword is special-see the discussion below for details. Note Applying the STRING function to a byte array containing a null (zero) value will result in the resulting string being truncated at that position. Syntax Result = STRING( Expression1, ..., Expressionn [, AM_PM=[string, string]] [, DAYS_OF_WEEK=string_array{7 names}] [, FORMAT=value] [, MONTHS=string_array{12 names}] [, /PRINT] ) Arguments Expressionn The expressions to be converted to string type. Note If you supply a comma-separated list of expressions without specifying a FORMAT, and the combined length of the expressions is greater than the current width of your tty or command log window, STRING will create a string array with one element for each expression, rather than concatenating all expressions into a single string. In this case, you can either specify a FORMAT, or use the string concatenation operator, "+". Keywords AM_PM Supplies a string array of 2 names to be used for the names of the AM and PM string when processing explicitly formatted dates (CAPA, CApA, and CapA format codes) with the FORMAT keyword. DAYS_OF_WEEK Supplies a string array of 7 names to be used for the names of the days of the week when processing explicitly formatted dates (CDWA, CDwA, and CdwA format codes) with the FORMAT keyword. FORMAT A format string to be used in formatting the expressions. See "Using Explicitly Formatted Input/Output" in Chapter 8 of Building IDL Applications. MONTHS Supplies a string array of 12 names to be used for the names of the months when processing explicitly formatted dates (CMOA, CMoA, and CmoA format codes) with the FORMAT keyword. PRINT Set this keyword to specify that any special case processing should be ignored and that STRING should behave exactly as the PRINT procedure would. Differences Between STRING and PRINT The behavior of STRING differs from the behavior of the PRINT procedure in the following ways (unless the PRINT keyword is set): * When called with a single non-byte argument and no format specification, STRING returns a result that has the same dimensions as the original argument. For example, the statement: HELP, STRING(INDGEN(5)) gives the result: STRING = Array[5] while: HELP, STRING(INDGEN(5), /PRINT) results in: STRING =' 0 1 2 3 4' * If called with a single argument of byte type and the FORMAT keyword is not used, STRING simply stores the unmodified values of each byte element in the result. This result is a string containing the byte values from the original argument. Thus, the result has one less dimension than the original argument. For example, a 2-dimensional byte array becomes a vector of strings, a byte vector becomes a scalar string. However, a byte scalar also becomes a string scalar. For example, the statement: PRINT, STRING([72B, 101B, 108B, 108B, 111B]) produces the output: Hello because the argument to STRING, is a byte vector. Its first element is a 72B which is the ASCII code for "H", the second is 101B which is an ASCII "e", and so forth. * If both the FORMAT and PRINT keywords are not present and STRING is called with more than one argument, and the last argument is a scalar string starting with the characters "$(" or "(", this final argument is taken to be the format specification, just as if it had been specified via the FORMAT keyword. This feature is maintained for compatibility with version 1 of VMS IDL. Example To convert the contents of variable A to string type and store the result in the variable B, enter: B = STRING(A) See Also BYTE, COMPLEX, DCOMPLEX, DOUBLE, FIX, FLOAT, LONG, LONG64, UINT, ULONG, ULONG64 STRJOIN [Previous Routine] [Next Routine] [List of Routines] NAME: STRJOIN The STRJOIN function collapses a string scalar or array into merged strings. This function reduces the rank of its input array by one dimension. The strings in the removed first dimension are concatenated into a single string using the string in Delimiter to separate them. Syntax Result = STRJOIN( String [, Delimiter] [, /SINGLE] ) Arguments String A string scalar or array to be collapsed into merged strings. Delimiter The separator string to use between the joined strings. If Delimiter is not specified, an empty string is used. Keywords SINGLE If SINGLE is set, the entire String is joined into a single scalar string result. Example Replace all the blanks in a sentence with colons: str = 'Out, damned spot! Out I say!' print, (STRJOIN(STRSPLIT(str, /EXTRACT), ':')) IDL prints: Out,:damned:spot!:Out:I:say! See Also STRCMP, STREGEX, STRMATCH, STRMID, STRPOS, STRSPLIT STRLEN [Previous Routine] [Next Routine] [List of Routines] NAME: STRLEN The STRLEN function returns the length of its string-type argument. If the argument is not a string, it is first converted to string type. Syntax Result = STRLEN(Expression) Arguments Expression The expression for which the string length is desired. If this parameter is not a string, it is converted using IDL's default formatting rules in order to determine the length. The result is a long integer. If Expression is an array, the result is a long integer array with the same structure, where each element contains the length of the corresponding Expression element. Example To find the length of the string "IDL is fun" and print the result, enter: PRINT, STRLEN('IDL is fun') IDL prints: 10 STRLOWCASE [Previous Routine] [Next Routine] [List of Routines] NAME: STRLOWCASE The STRLOWCASE function returns a copy of String converted to lowercase characters. Only uppercase characters are modified-lowercase and non-alphabetic characters are copied without change. Syntax Result = STRLOWCASE(String) Arguments String The string to be converted. If this argument is not a string, it is converted using IDL's default formatting rules. If String is an array, the result is an array with the same structure-each element contains a lower case copy of the corresponding element of String. Example To convert the string "IDL is fun" to all lowercase characters and print the result, enter: PRINT, STRLOWCASE('IDL is fun') IDL prints: idl is fun See Also STRUPCASE STRMATCH [Previous Routine] [Next Routine] [List of Routines] NAME: STRMATCH The STRMATCH function compares its search string, which can contain wildcard characters, against the input string expression. The result is an array with the same structure as the input string expression. Those elements that match the corresponding input string are set to True (1), and those that do not match are set to False (0). The wildcards understood by STRMATCH are similar to those used by the standard UNIX shell: Wildcard Character Description * Matches any string, including the null string. ? Matches any single character. [...] Matches any one of the enclosed characters. A pair of characters separated by "-" matches any character lexically between the pair, inclusive. If the first character following the opening [ is a !, any character not enclosed is matched. To prevent one of these characters from acting as a wildcard, it can be quoted by preceding it with a backslash character (e.g. "\*" matches the asterisk character). Quoting any other character (including \ itself) is equivalent to the character (e.g. "\a" is the same as "a"). Table 88: Wilcard Characters used by STRMATCH Syntax Result = STRMATCH( String, SearchString [, /FOLD_CASE] ) Arguments String The String to be matched. SearchString The search string, which can contain wildcard characters as discussed above. Keywords FOLD_CASE The comparison is usually case sensitive. Setting the FOLD_CASE keyword causes a case insensitive match to be done instead. Examples Example 1 Find all 4-letter words in a string array that begin with "f" or "F" and end with "t" or "T": str = ['foot', 'Feet', 'fate', 'FAST', 'ferret', 'fort'] PRINT, str[WHERE(STRMATCH(str, 'f??t', /FOLD_CASE) EQ 1)] This results in: foot Feet FAST fort Example 2 Find words of any length that begin with "f" and end with "t": str = ['foot', 'Feet', 'fate', 'FAST', 'ferret', 'fort'] PRINT, str[WHERE(STRMATCH(str, 'f*t', /FOLD_CASE) EQ 1)] This results in: foot Feet FAST ferret fort Example 3 Find 4-letter words beginning with "f" and ending with "t", with any combination of "o" and "e" in between: str = ['foot', 'Feet', 'fate', 'FAST', 'ferret', 'fort'] PRINT, str[WHERE(STRMATCH(str, 'f[eo][eo]t', /FOLD_CASE) EQ 1)] This results in: foot Feet Example 4 Find all words beginning with "f" and ending with "t" whose second character is not the letter "o": str = ['foot', 'Feet', 'fate', 'FAST', 'ferret', 'fort'] PRINT, str[WHERE(STRMATCH(str, 'f[!o]*t', /FOLD_CASE) EQ 1)] This results in: Feet FAST ferret See Also STRCMP, STRJOIN, STREGEX, STRMID, STRPOS, STRSPLIT STRMESSAGE [Previous Routine] [Next Routine] [List of Routines] NAME: STRMESSAGE The STRMESSAGE function returns the text of the error message specified by Err. This function is especially useful in conjunction with the CODE field of the !ERROR_STATE system variable which always contains the error number of the last error. The MSG field of the !ERROR_STATE system variable contains the text of the last error message. Syntax Result = STRMESSAGE( Err [, /BLOCK | , /CODE | , /NAME] ) Arguments Err The error number or text. Programs must not make the assumption that certain error numbers are always related to certain error messages-the actual correspondence changes over time as IDL is modified. Keywords BLOCK Set this keyword to return the name of the message block that defines Err. If this keyword is specified, Err must be an error code. CODE Set this keyword to return the error code for the error message specified in Err. If this keyword is specified, Err must be an error name. NAME Set this keyword to return a string containing the error message that goes with Err. If this keyword is specified, Err must be an error code. Example Print the error message associated with error number 4 by entering: PRINT, STRMESSAGE(4) See Also MESSAGE STRMID [Previous Routine] [Next Routine] [List of Routines] NAME: STRMID The STRMID function extracts one or more substring from a string expression. Each extracted string is the result of removing characters. The result of the function is a string of Length characters taken from Expression, starting at character position First_Character. The form of First_Character and Length control how they are applied to Expression. Either argument can be a scalar or an array: * If a scalar value is supplied for First_Character and Length, then those values are applied to all elements of Expression. The result has the same structure and number of elements as Expression. * If First_Character or Length is an array, the size of their first dimension determines how many substrings are extracted from each element of Expression. We call this the "stride". If both are arrays, they must have the same stride. If First_Character or Length do not contain enough elements to process Expression, STRMID automatically loops back to the beginning as necessary. Excess values are ignored. If the stride is 1, the result will have the same structure and number of elements as Expression. If it is greater than 1, the result will have an additional dimension, with the new first dimension having the same size as the stride. Syntax Result = STRMID(Expression, First_Character [, Length] [, /REVERSE_OFFSET]) Arguments Expression The expression from which the substrings are to be extracted. If this argument is not a string, it is converted using IDL's default formatting rules. First_Character The starting position within Expression at which the substring starts. The first character position is 0. Length The length of the substring. If there are not enough characters left in the main string to obtain Length characters, the substring is truncated. If Length is not supplied, STRMID extracts all characters from the specified start position to the end of the string. Keywords REVERSE_OFFSET Specifies that First_Character should be counted from the end of the string backwards. This allows simple extraction of strings from the end. Example If the variable B contains the string "IDL is fun", the substring "is" can be extracted and stored in the variable C with the command: C = STRMID(B, 4, 2) See Also STRPOS, STRPUT, STRTRIM STRPOS [Previous Routine] [Next Routine] [List of Routines] NAME: STRPOS The STRPOS function finds the first occurrence of a substring within an object string. If Search_String occurs in Expression, STRPOS returns the character position of the match, otherwise it returns -1. Syntax Result = STRPOS( Expression, Search String [, Pos] [, /REVERSE_OFFSET] [, /REVERSE_SEARCH] ) Arguments Expression The expression in which to search for the substring. If this argument is not a string, it is converted using IDL's default formatting rules. If Expression is an array, the result is an array with the same structure, where each element contains the position of the substring within the corresponding element Expression. If Expression is the null string, STRPOS returns the value -1. Search_String The substring to be searched for within Expression. If this argument is not a string, it is converted using IDL's default formatting rules. If Search_String is the null string, STRPOS returns the smaller of Pos or one less than the length of Expression. Pos The character position at which the search is begun. If Pos is omitted and the REVERSE_SEARCH keyword is not set, the search begins at the first character (character position 0). If REVERSE_SEARCH is set, the default is to start at the last character in the string. If Pos is less than zero, zero is used for the starting position. Keywords REVERSE_OFFSET Normally, the value of Pos is used as an offset from the beginning of the expression towards the end. Set REVERSE_OFFSET to use it as an offset from the last character of the string moving towards the beginning. This keyword makes it easy to position the starting point of the search at a fixed offset from the end of the string. REVERSE_SEARCH STRPOS usually starts at Pos and moves toward the end of the string looking for a match. If REVERSE_SEARCH is set, the search instead moves towards the beginning of the string. Examples Example 1 Find the position of the string "fun" within the string "IDL is fun" and print the result by entering: PRINT, STRPOS('IDL is fun', 'fun') IDL prints: 7 Example 2 The REVERSE_SEARCH keyword to the STRPOS function makes it easy to find the last occurrence of a substring within a string. In the following example, we search for the last occurrence of the letter "I" (or "i") in a sentence: sentence = 'IDL is fun.' sentence = STRUPCASE(sentence) lasti = STRPOS(sentence, 'I', /REVERSE_SEARCH) PRINT, lasti This results in: 4 Note that although REVERSE_SEARCH tells STRPOS to begin searching from the end of the string, the STRPOS function still returns the position of the search string from the beginning of the string (where 0 is the position of the first character). See Also STRMID, STRPUT, STRTRIM STRPUT [Previous Routine] [Next Routine] [List of Routines] NAME: STRPUT The STRPUT procedure inserts the contents of one string into another. The source string, Source, is inserted into the destination string, Destination, starting at the given position, Position. Characters in Destination before the starting position and after the starting position plus the length of Source remain unchanged. The length of the destination string is not changed. If the insertion extends past the end of the destination, it is clipped at the end. Syntax STRPUT, Destination, Source [, Position] Arguments Destination The named string variable into which Source is inserted. Destination must be a named variable of type string. If it is an array, Source is inserted into every element of the array. Source A scalar string to be inserted into Destination. If this argument is not a string, it is converted using IDL's default formatting rules. Position The character position at which the insertion is begun. If Position is omitted, the insertion begins at the first character (character position 0). If Position is less than zero, zero is used for the initial position. Examples If the variable A contains the string "IBM is fun", the substring "IBM" can be overwritten with the string "IDL" by entering: STRPUT, A, 'IDL', 0 The following commands demonstrate the clipping of output that extends past the end of the destination string: STRPUT, A, 'FUNNY', 7 PRINT, A IDL prints: IDL is FUN See Also STRMID, STRPOS, STRTRIM STRSPLIT [Previous Routine] [Next Routine] [List of Routines] NAME: STRSPLIT The STRSPLIT function splits its input String argument into separate substrings, according to the specified delimiter or regular expression. By default, the position of the substrings is returned. The EXTRACT keyword can be used to cause STRSPLIT to return an array containing the substrings. Syntax Result = STRSPLIT( String [, Pattern] [, ESCAPE=string | , /REGEX [, /FOLD_CASE]] [, /EXTRACT | , LENGTH=variable] [, /PRESERVE_NULL] ) Arguments String A scalar string to be split into substrings. Pattern Pattern can contain one of two types of information: * A string containing the character codes that are considered to be separators. In this case, IDL performs a simple string search for those characters. This method is simple and fast. * A regular expression, as implemented by the STREGEX function, which is used by IDL to match the separators. This method is slower and more complex, but can handle extremely complicated input strings. Pattern is an optional argument. If it is not specified, STRSPLIT defaults to splitting on spans of whitespace (space or tab characters) in String. Keywords ESCAPE When doing simple pattern matching, the ESCAPE keyword can be used to specify any characters that should be considered to be "escape" characters. Preceding any character with an escape character prevents STRSPLIT from treating it as a separator character even if it is found in Pattern. Note that if the EXTRACT keyword is set, STRSPLIT will automatically remove the escape characters from the resulting substrings. If EXTRACT is not specified, STRSPLIT cannot perform this editing, and the returned position and offsets will include the escape characters. For example: print, STRSPLIT('a\,b', ',', ESCAPE='\', /EXTRACT) IDL prints: a,b ESCAPE cannot be specified with the FOLD_CASE or REGEX keywords. EXTRACT By default, STRSPLIT returns an array of character offsets into String that indicate where the substrings are located. These offsets, along with the lengths available from the LENGTH keyword can be used later with STRMID to extract the substrings. Set EXTRACT to bypass this step, and cause STRSPLIT to return the substrings. EXTRACT cannot be specified with the LENGTH keyword. FOLD_CASE Indicates that the regular expression matching should be done in a case-insensitive fashion. FOLD_CASE can only be specified if the REGEX keyword is set, and cannot be used with the ESCAPE keyword. LENGTH Set this keyword to a named variable to receive the lengths of the substrings. Together with this result of this function, LENGTH can be used with the STRMID function to extract the matched substrings. The LENGTH keyword cannot be used with the EXTRACT keyword. PRESERVE_NULL Normally, STRSPLIT will not return null length substrings unless there are no non- null values to report, in which case STRSPLIT will return a single null string. Set PRESERVE_NULL to cause all null substrings to be returned. REGEX For complex splitting tasks, the REGEX keyword can be specified. In this case, Pattern is taken to be a regular expression to be matched against String to locate the separators. If REGEX is specified and Pattern is not, the default Pattern is the regular expression: '[ ' + STRING(9B) + ']+' which means "any series of one or more space or tab characters" (9B is the byte value of the ASCII TAB character). Note that the default Pattern contains a space after the [ character. The REGEX keyword cannot be used with the ESCAPE keyword. Examples Example 1 To split a string on spans of whitespace and replace them with hyphens: Str = 'STRSPLIT chops up strings.' print, STRJOIN(STRSPLIT(Str, /EXTRACT), '-') IDL prints: STRSPLIT-chops-up-strings. Example 2 As an example of a more complex splitting task that can be handled with the simple character-matching mode of STRSPLIT, consider a sentence describing different colored ampersand characters. For unknown reasons, the author used commas to separate all the words, and used ampersands or backslashes to escape the commas that actually appear in the sentence (which therefore should not be treated as separators). The unprocessed string looks like: Str = 'There,was,a,red,&&&,,a,yellow,&&\,,and,a,blue,\&.' We use STRSPLIT to break this line apart, and STRJOIN to reassemble it as a standard blank-separated sentence: S = STRSPLIT(Str, ',', ESCAPE='&\', /EXTRACT) PRINT, STRJOIN(S, ' ') IDL prints: There was a red &, a yellow &, and a blue &. Example 3 Finally, suppose you had a complicated string, in which every token was preceded by the count of characters in that token, with the count enclosed in angle brackets: str = '<4>What<1>a<7>tangled<3>web<2>we<6>weave.' This is too complex to handle with simple character matching, but can be easily handled using the regular expression '<[0-9]+>' to match the separators. This regular expression can be read as "an opening angle bracket, followed by one or more numeric characters between 0 and 9, followed by a closing angle bracket." The STRJOIN function is used to glue the resulting substrings back together: S = STRSPLIT(str,'<[0-9]+>',/EXTRACT,/REGEX) PRINT, STRJOIN(S, ' ') IDL prints: What a tangled web we weave. See Also STRCMP, STRJOIN, STRMATCH, STREGEX, STRMID, STRPOS STRTRIM [Previous Routine] [Next Routine] [List of Routines] NAME: STRTRIM The STRTRIM function returns a copy of String with leading and/or trailing blanks removed. Syntax Result = STRTRIM( String [, Flag] ) Arguments String The string to have leading and/or trailing blanks removed. If this argument is not a string, it is converted using IDL's default formatting rules. If it is an array, the result is an array with the same structure where each element contains a trimmed copy of the corresponding element of String. Flag A value that controls the action of STRTRIM. If Flag is zero or not present, trailing blanks are removed. Leading blanks are removed if it is equal to 1. Both are removed if it is equal to 2. Example Converting variables to string type often results in undesirable leading blanks. For example, the following command converts the integer 56 to string type: C = STRING(56) Entering the command: HELP, C IDL prints: C STRING = ' 56' which shows that there are six leading spaces before the characters 5 and 6. To remove these leading blanks, enter the command: C = STRTRIM(C, 1) To confirm that the blanks were removed, enter: HELP, C IDL prints: C STRING = '56' See Also STRMID, STRPOS, STRPUT, STRSPLIT STRUCT_ASSIGN [Previous Routine] [Next Routine] [List of Routines] NAME: STRUCT_ASSIGN The IDL "=" operator is unable to assign a structure value to a structure of a different type. The STRUCT_ASSIGN procedure performs "relaxed structure assignment," which is a field-by-field copy of a structure to another structure. Fields are copied according to the following rules: 1. Any fields found in the destination structure that are not found in the source structure are "zeroed" (set to zero, the empty string, or a null pointer or object reference depending on the type of field). 2. Any fields in the source structure that are not found in the destination structure are quietly ignored. 3. Any fields that are found in both the source and destination structures are copied one at a time. If necessary, type conversion is done to make their types agree. If a field in the source structure has fewer data elements than the corresponding field in the destination structure, then the "extra" elements in the field in the destination structure are zeroed. If a field in the source structure has more elements than the corresponding field in the destination structure, the extra elements are quietly ignored. Relaxed structure assignment is especially useful when restoring structures from disk files into an environment where the structure definition has changed. See the description o f the RELAXED_STRUCTURE_ASSIGNMENT keyword to the RESTORE procedure for additional details. "Relaxed Structure Assignment" in Chapter 6 of Building IDL Applications provides a more in-depth discussion of the structure-definition process. Syntax STRUCT_ASSIGN, Source, Destination [, /NOZERO] [, /VERBOSE] Arguments Source A named variable or element of an array containing a structure, the contents of which will be assigned to the structure specified by the Destination argument. Source can be an object reference if STRUCT_ASSIGN is called inside an object method. Destination A named variable containing a structure into which the contents of the structure specified by the Source argument will be inserted. Destination can be an object reference if STRUCT_ASSIGN is called inside an object method. Keywords NOZERO Normally, any fields found in the destination structure that are not found in the source structure are zeroed. Set NOZERO to prevent this action and leave the original contents of such fields unchanged. VERBOSE Set this keyword to cause STRUCT_ASSIGN to issue informational messages about any incompatibilities that prevent data from being copied. Examples The following example creates two anonymous structures, then uses STRUCT_ASSIGN to insert the contents of the first into the second: source = { a:FINDGEN(4), b:12 } dest = { a:INDGEN(2), c:20 } STRUCT_ASSIGN, /VERBOSE, source, dest IDL prints: % STRUCT_ASSIGN: tag A is longer than destination. The end will be clipped. % STRUCT_ASSIGN: Destination lacks tag B. Not copied. After assignment, dest contains a two-element integer array [0, 1] in its field A and the integer 0 in its field C. Since dest does not have a field B, field B from source is not copied. STRUCT_HIDE [Previous Routine] [Next Routine] [List of Routines] NAME: STRUCT_HIDE The IDL HELP procedure displays information on all known structures or object classes when used with the STRUCTURES or OBJECTS keywords. Although this is usually the desired behavior, authors of large vertical applications or library routines may wish to prevent IDL from displaying information on structures or objects that are not part of their public interface, but which exist solely in support of the internal implementation. The STRUCT_HIDE procedure is used to mark such structures or objects as hidden. Items so marked are not displayed by HELP, /STRUCTURE unless the user sets the FULL keyword, but are otherwise unaltered. Note STRUCT_HIDE is primarily intended for use with named structures or objects. Although it can be safely used with anonymous structures, there is no visible benefit to doing so as anonymous structures are hidden by default. Tip Authors of objects will often place a call to STRUCT_HIDE in the _ _DEFINE procedure that defines the structure. Syntax STRUCT_HIDE, Arg1 [, Arg2, ..., Argn] Arguments Arg1, ..., Argn If an argument is a variable of one of the following types, its underlying structure and/or object definition is marked as being hidden from the HELP procedure's default output: * Structure * Pointer that refers to a heap variable of structure type * Object Reference Any arguments that are not one of these types are quietly ignored. No change is made to the value of any argument. Keywords None Example This example shows how a structure can be hidden if an application designer doesn't want end-users to be able to see it, but variables are not hidden. To create a named structure called bullwinkle and prevent it from appearing in the HELP procedure's default output, do the following. ; Define a variable containing the named structure: tmp = { bullwinkle, moose:1, squirrel:0 } ; IDL returns BULLWINKLE in addition to the other system variables. HELP, /STRUCTURE, /BRIEF ; Next, specifically hide the structure using ; the STRUCT_HIDE procedure. STRUCT_HIDE, tmp ; This time IDL returns the system variables but ; not the BULLWINKLE structure. HELP, /STRUCTURE, /BRIEF ; IDL returns the variable tmp showing that it is ; a named structure called BULLWINKLE. HELP, tmp See Also COMPILE_OPT STRUPCASE [Previous Routine] [Next Routine] [List of Routines] NAME: STRUPCASE The STRUPCASE function returns a copy of String converted to upper case. Only lowercase characters are modified-uppercase and non-alphabetic characters are copied without change. Syntax Result = STRUPCASE(String) Arguments String The string to be converted. If this argument is not a string, it is converted using IDL's default formatting rules. If it is an array, the result is an array with the same structure where each element contains an uppercase copy of the corresponding element of String. Example To print an uppercase version of the string "IDL is fun", enter: PRINT, STRUPCASE('IDL is fun') IDL prints: IDL IS FUN See Also STRLOWCASE SURFACE [Previous Routine] [Next Routine] [List of Routines] NAME: SURFACE The SURFACE procedure draws a wire-mesh representation of a two-dimensional array projected into two dimensions, with hidden lines removed. Restrictions If the (X, Y) grid is not regular or nearly regular, errors in hidden line removal occur. The TRIGRID and TRIANGULATE routines can be used to interpolate irregularly- gridded data points to a regular grid before plotting. If the T3D keyword is set, the 3D to 2D transformation matrix contained in !P.T must project the Z axis to a line parallel to the device Y axis, or errors will occur. The surface lines may blend together when drawing large arrays, especially on low or medium resolution displays. Use the REBIN or CONGRID procedure to resample the array to a lower resolution before plotting. Syntax SURFACE, Z [, X, Y] [, AX=degrees] [, AZ=degrees] [, BOTTOM=index] [, /HORIZONTAL] [, /LEGO] [, /LOWER_ONLY | , /UPPER_ONLY] [, MAX_VALUE=value] [, MIN_VALUE=value] [, /SAVE] [, SHADES=array] [, SKIRT=value] [, /XLOG] [, /YLOG] [, ZAXIS={1 | 2 | 3 | 4}] [, /ZLOG] Graphics Keywords: Accepts all graphics keywords accepted by PLOT except for: PSYM, SYMSIZE. See "Graphics Keywords Accepted" on page 1370. Arguments Z The two-dimensional array to be displayed. If X and Y are provided, the surface is plotted as a function of the (X, Y) locations specified by their contents. Otherwise, the surface is generated as a function of the array index of each element of Z. This argument is converted to double-precision floating-point before plotting. Plots created with SURFACE are limited to the range and precision of double-precision floating-point values. X A vector or two-dimensional array specifying the X coordinates of the grid. If this argument is a vector, each element of X specifies the X coordinate for a column of Z (e.g., X[0] specifies the X coordinate for Z[0,*]). If X is a two-dimensional array, each element of X specifies the X coordinate of the corresponding point in Z (Xij specifies the X coordinate for Zij). This argument is converted to double-precision floating-point before plotting. Y A vector or two-dimensional array specifying the Y coordinates of the grid. If this argument is a vector, each element of Y specifies the Y coordinate for a row of Z (e.g., Y[0] specifies the Y coordinate 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 coordinate for Zij). This argument is converted to double-precision floating-point before plotting. Keywords AX This keyword specifies the angle of rotation, about the X axis, in degrees towards the viewer. This keyword is effective only if !P.T3D is not set. If !P.T3D is set, the three- dimensional to two-dimensional transformation used by SURFACE is taken from the 4 by 4 array !P.T. The surface represented by the two-dimensional array is first rotated, AZ (see below) degrees about the Z axis, then by AX degrees about the X axis, tilting the surface towards the viewer (AX > 0), or away from the viewer. The AX and AZ keyword parameters default to +30 degrees if omitted and !P.T3D is 0. The three-dimensional to two-dimensional transformation represented by AX and AZ, can be saved in !P.T by including the SAVE keyword. AZ This keyword specifies the counterclockwise angle of rotation about the Z axis. This keyword is effective only if !P.T3D is not set. The order of rotation is AZ first, then AX. BOTTOM The color index used to draw the bottom surface. If not specified, the bottom is drawn with the same color as the top. HORIZONTAL A keyword flag which if set causes SURFACE to only draw lines across the plot perpendicular to the line of sight. The default is for SURFACE to draw both across the plot and from front to back. LEGO Set this keyword to produce stacked histogram-style plots. Each data value is rendered as a box covering the XY extent of the cell and with a height proportional to the Z value. If the X and Y arguments are specified, only Nx-1 columns and Ny-1 rows are drawn. (This means that the last row and column of array data are not displayed.) The rectangular area covered by Z[i, j] is given by X[i], X[i+1], Y[j], and Y[j+1]. LOWER_ONLY Set this keyword to draw only the lower surface of the object. By default, both surfaces are drawn. MAX_VALUE The maximum value to be plotted. If this keyword is present, data values greater than the value of MAX_VALUE are treated as missing and are not plotted. Note that the IEEE floating-point value NaN is also treated as missing data. (See "Special Floating-Point Values" in Chapter 17 of Building IDL Applications for more information on IEEE floating-point values.) MIN_VALUE The minimum value to be plotted. If this keyword is present, data values less than the value of MIN_VALUE are treated as missing and are not plotted. Note that the IEEE floating-point value NaN is also treated as missing data. (See "Special Floating-Point Values" in Chapter 17 of Building IDL Applications for more information on IEEE floating-point values.) SAVE Set this keyword to save the 3D to 2D transformation matrix established by SURFACE in the system variable field !P.T. Use this keyword when combining the output of SURFACE with additional output from other routines in the same plot. When used with AXIS, the SAVE keyword parameter saves the scaling parameters established by the call in the appropriate axis system variable, !X, !Y, or !Z. This causes subsequent overplots to be scaled to the new axis. For example, to display a two-dimensional array using SURFACE, and to then superimpose contours over the surface (this example assumes that !P.T3D is zero, its default value.), enter the following commands: ; Make a surface plot and save the transformation: SURFACE, Z, /SAVE ; Make contours, don't erase, use the 3D to 2D transform placed ; in !P.T by SURFACE: CONTOUR, Z, /NOERASE, /T3D To display a surface and to then display a flat contour plot, registered above the surface: ; Make the surface, save transform: SURFACE, Z, /SAVE ; Now display a flat contour plot, at the maximum Z value ; (normalized coordinates): CONTOUR, Z, /NOERASE, /T3D, ZVALUE=1.0 You can display the contour plot below the surface with by using a ZVALUE of 0.0. SHADES This keyword allows user-specified coloring of the mesh surfaces. Set this keyword to an array that specifies the color index of the lines emanating from each data point toward the top and right. Warning When using the SHADES keyword on True Color devices, we recommend that decomposed color support be turned off, by setting DEVICE, DECOMPOSED=0. See "DEVICE" on page 385 and "DECOMPOSED" on page 2322. SKIRT This keyword represents a Z-value at which to draw a skirt around the array. The Z value is expressed in data units. The default is no skirt. If the skirt is drawn, each point on the four edges of the surface is connected to a point on the skirt which has the given Z value, and the same X and Y values as the edge point. In addition, each point on the skirt is connected to its neighbor. UPPER_ONLY Set this keyword to draw only the upper surface of the object. By default, both surfaces are drawn. XLOG Set this keyword to specify a logarithmic X axis. YLOG Set this keyword to specify a logarithmic Yaxis. ZAXIS This keyword specifies the placement of the Z axis for the SURFACE plot. By default, SURFACE draws the Z axis at the upper left corner of the axis box. To suppress the Z axis, use ZAXIS=-1 in the call. The position of the Z axis is determined from the value of ZAXIS as follows: 1 = lower right, 2 = lower left, 3 = upper left, and 4 = upper right. ZLOG Set this keyword to specify a logarithmic Zaxis. Graphics Keywords Accepted See Appendix C, "Graphics Keywords", for the description of graphics and plotting keywords not listed above. BACKGROUND, CHARSIZE, CHARTHICK, CLIP, COLOR, DATA, DEVICE, FONT, LINESTYLE, NOCLIP, NODATA, NOERASE, NORMAL, POSITION, SUBTITLE, T3D, THICK, TICKLEN, TITLE, [XYZ]CHARSIZE, [XYZ]GRIDSTYLE, [XYZ]MARGIN, [XYZ]MINOR, [XYZ]RANGE, [XYZ]STYLE, [XYZ]THICK, [XYZ]TICKFORMAT, [XYZ]TICKINTERVAL, [XYZ]TICKLAYOUT, [XYZ]TICKLEN, [XYZ]TICKNAME, [XYZ]TICKS, [XYZ]TICKUNITS, [XYZ]TICKV, [XYZ]TICK_GET, [XYZ]TITLE, ZVALUE. Example ; Create a simple dataset to display: D = DIST(30) ; Plot a simple wire-mesh surface representation of D: SURFACE, D ; Create a wire-mesh plot of D with a title and a "skirt" around ; the edges of the dataset at Z=0: SURFACE, D, SKIRT=0.0, TITLE = 'Surface Plot', CHARSIZE = 2 See Also CONTOUR, SHADE_SURF SURFR [Previous Routine] [Next Routine] [List of Routines] NAME: SURFR The SURFR procedure sets up 3D transformations. This procedure duplicates the rotation, translation, and scaling features of the SURFACE routine, but does not display any data. The resulting transformations are stored in the !P.T system variable. This routine is written in the IDL language. Its source code can be found in the file surfr.pro in the lib subdirectory of the IDL distribution. Syntax SURFR [, AX=degrees] [, AZ=degrees] Keywords AX Angle of rotation about the X axis. The default is 30 degrees. AZ Angle of rotation about the Z axis. The default is 30 degrees. See Also SCALE3, SCALE3D, T3D SVDC [Previous Routine] [Next Routine] [List of Routines] NAME: SVDC The SVDC procedure computes the Singular Value Decomposition (SVD) of a square (n x n) or non-square (n x m) array as the product of orthogonal and diagonal arrays. SVD is a very powerful tool for the solution of linear systems, and is often used when a solution cannot be determined by other numerical algorithms. The SVD of an (m x n) non-square array A is computed as the product of an (m x n) column orthogonal array U, an (n x n) diagonal array SV, composed of the singular values, and the transpose of an (n x n) orthogonal array V: A = U SV VT SVDC is based on the routine svdcmp described in section 2.6 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press, and is used by permission. Syntax SVDC, A, W, U, V [, /COLUMN] [, /DOUBLE] [, ITMAX=value] Arguments A The square (n x n) or non-square (n x m) single- or double-precision floating-point array to decompose. W On output, W is an n-element output vector containing the "singular values." U On output, U is an n-column, m-row orthogonal array used in the decomposition of A. V On output, V is an n-column, n-row orthogonal array used in the decomposition of A. Keywords COLUMN Set this keyword if the input array A is in column-major format (composed of column vectors) rather than in row-major format (composed of row vectors). DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. ITMAX Set this keyword to specify the maximum number of iterations. The default value is 30. Example To find the singular values of an array A: ; Define the array A: A = [[1.0, 2.0, -1.0, 2.5], $ [1.5, 3.3, -0.5, 2.0], $ [3.1, 0.7, 2.2, 0.0], $ [0.0, 0.3, -2.0, 5.3], $ [2.1, 1.0, 4.3, 2.2], $ [0.0, 5.5, 3.8, 0.2]] ; Compute the Singular Value Decomposition: SVDC, A, W, U, V ; Print the singular values: PRINT, W IDL prints: 8.81973 2.65502 4.30598 6.84484 To verify the decomposition, use the relationship A = U ## SV ## TRANSPOSE(V), where SV is a diagonal array created from the output vector W: sv = FLTARR(4, 4) FOR K = 0, 3 DO sv[K,K] = W[K] result = U ## sv ## TRANSPOSE(V) PRINT, result IDL prints: 1.00000 2.00000 -1.00000 2.50000 1.50000 3.30000 -0.500001 2.00000 3.10000 0.700000 2.20000 0.00000 2.23517e-08 0.300000 -2.00000 5.30000 2.10000 0.999999 4.30000 2.20000 -3.91155e-07 5.50000 3.80000 0.200000 This is the input array, to within machine precision. See Also CHOLDC, LUDC, SVSOL SVDFIT [Previous Routine] [Next Routine] [List of Routines] NAME: SVDFIT The SVDFIT function performs a least squares fit with optional error estimates and returns a vector of coefficients. Either a user-supplied function written in the IDL language or a built-in polynomial can be used to fit the data. SVDFIT is based on the routine svdfit described in section 15.4 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press, and is used by permission. Syntax Result = SVDFIT( X, Y [, M] [, A=vector] [, CHISQ=variable] [, COVAR=variable] [, /DOUBLE] [, FUNCTION_NAME=string] [, /LEGENDRE] [, MEASURE_ERRORS=vector] [, SIGMA=variable] [, SINGULAR=variable] [, VARIANCE=variable] [, YFIT=variable] ) Arguments X An n-element vector of independent variables. Y A vector of dependent variables, the same length as X. M The number of coefficients in the fitting function. For polynomials, M is equal to the degree of the polynomial + 1. If the M argument is not specified, you must supply initial coefficient estimates using the A keyword. In this case, M is set equal to the number of elements of the array specified by the A keyword. Keywords A This keyword is both an input and output keyword. Set this keyword equal to a variable containing a vector of initial estimates for the fitted function parameters. On exit, SVDFIT returns in this variable a vector of coefficients that are improvements of the initial estimates. If A is supplied, the M argument will be set equal to the number of elements in the vector specified by A. CHISQ Set this keyword equal to a named variable that will contain the the value of the chi-sqaure goodness-of-fit. COVAR Set this keyword equal to a named variable that will contain the covariance matrix of the fitted coefficients. DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. FUNCTION_NAME Set this keyword equal to a string containing the name of a user-supplied IDL basis function with M coefficients. If this keyword is omitted, and the LEGENDRE keyword is not set, IDL assumes that the IDL procedure SVDFUNCT, found in the file svdfunct.pro, located in the lib subdirectory of the IDL distribution, is to be used. SVDFUNCT uses the basis functions for the fitting polynomial M y = A(i)xi i = 0 The function to be fit must be written as an IDL function and compiled prior to calling SVDFIT. The function must accept values of X (a scalar), and M (a scalar). It must return an M-element vector containing the basis functions. See the "Example" section below for an example function. LEGENDRE Set this keyword to use Legendre polynomials instead of the function specified by the FUNCTION_NAME keyword. If the LEGENDRE keyword is set, the IDL uses the function SVDLEG found in the file svdleg.pro, located in the lib subdirectory of the IDL distribution. MEASURE_ERRORS Set this keyword to a vector containing standard measurement errors for each point Y[i]. This vector must be the same length as X and Y. Note For Gaussian errors (e.g., instrumental uncertainties), MEASURE_ERRORS should be set to the standard deviations of each point in Y. For Poisson or statistical weighting, MEASURE_ERRORS should be set to SQRT(Y). SIGMA Set this keyword to a named variable that will contain the 1-sigma uncertainty estimates for the returned parameters. Note If MEASURE_ERRORS is omitted, then you are assuming that the polynomial (or your user-supplied model) is the correct model for your data, and therefore, no independent goodness-of-fit test is possible. In this case, the values returned in SIGMA are multiplied by SQRT(CHISQ/(N­M)), where N is the number of points in X, and M is the number of coefficients. See section 15.2 of Numerical Recipes in C (Second Edition) for details. SINGULAR Set this keyword equal to a named variable that will contain the number of singular values returned. This value should be 0. If not, the basis functions do not accurately characterize the data. VARIANCE Set this keyword equal to a named variable that will contain the variance (sigma squared) of each coefficient M. WEIGHTS The WEIGHTS keyword is obsolete and has been replaced by the MEASURE_ERRORS keyword. Code that uses the WEIGHTS keyword will continue to work as before, but new code should use the MEASURE_ERRORS keyword. Note that the definition of the MEASURE_ERRORS keyword is not the same as the WEIGHTS keyword. Using the WEIGHTS keyword, 1/WEIGHTS[i] represents the measurement error for each point Y[i]. Using the MEASURE_ERRORS keyword, the measurement error is represented as simply MEASURE_ERRORS[i]. YFIT Set this keyword equal to a named variable that will contain the vector of calculated Y values. Example This example fits a function of the following form: F(x) = A(0) + A(1) (2x) sin----------- A(2)cos(4x)2 + x First, create the function in IDL, then create a procedure to perform the fit. Create the following file called example_svdfit.pro: PRO example_svdfit ; Provide an array of coefficients: C = [7.77, 8.88, -9.99] X = FINDGEN(100)/15.0 + 0.1 Y = C[0] + C[1] * SIN(2*X)/X + C[2] * COS(4.*X)^2. ; Set uncertainties to 5%: measure_errors = 0.05 * Y ; Provide an initial guess: A=[1,1,1] result_a = SVDFIT(X, Y, A=A, MEASURE_ERRORS=measure_errors, $ FUNCTION_NAME='myfunct', SIGMA=SIGMA, YFIT=YFIT) ; Plot the results: PLOT, X, YFIT FOR I = 0, N_ELEMENTS(A)-1 DO $ PRINT, I, result_a[I], SIGMA[I], C[I],$ FORMAT = $ '(" result_a ( ",I1," ) = ",F7.4," +- ",F7.4," VS. ",F7.4)' END FUNCTION myfunct, X ,M RETURN,[ [1.0], [SIN(2*X)/X], [COS(4.*X)^2.] ] END Place the file example_svdfit.pro in a directory in the IDL search path, and enter example_svdfit at the command prompt to create the plot. In addition to creating the above plot, IDL prints: result_a ( 0 ) = 7.7700 +- 0.0390 VS. 7.7700 result_a ( 1 ) = 8.8800 +- 0.0468 VS. 8.8800 result_a ( 2 ) = -9.9900 +- 0.0506 VS. -9.9900 See Also CURVEFIT, GAUSSFIT, LINFIT, LMFIT, POLY_FIT, REGRESS, SFIT SVSOL [Previous Routine] [Next Routine] [List of Routines] NAME: SVSOL The SVSOL function uses "back-substitution" to solve a set of simultaneous linear equations Ax = b, given the U, W, and V arrays returned by the SVDC procedure. None of the input arguments are modified, making it possible to call SVSOL multiple times with different right hand vectors, B. SVSOL is based on the routine svbksb described in section 2.6 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press, and is used by permission. Syntax Result = SVSOL( U, W, V, B [, /COLUMN] [, /DOUBLE] ) Arguments U An n-column, m-row orthogonal array used in the decomposition of A. Normally, U is returned from the SVDC procedure. W An n-element vector containing "singular values." Normally, W is returned from the SVDC procedure. Small values (close to machine floating-point precision) should be set to zero prior to calling SVSOL. V An n-column, n-row orthogonal array used in the decomposition of A. Normally, V is returned from the SVDC procedure. B An m-element vector containing the right hand side of the linear system Ax = b. Keywords COLUMN Set this keyword if the input arrays U and V are in column-major format (composed of column vectors) rather than in row-major format (composed of row vectors). DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. Example To solve the linear system Ax = b using Singular-value decomposition and back substitution, begin with an array A which serves as the coefficient array: ; Define the array A: A = [[1.0, 2.0, -1.0, 2.5], $ [1.5, 3.3, -0.5, 2.0], $ [3.1, 0.7, 2.2, 0.0], $ [0.0, 0.3, -2.0, 5.3], $ [2.1, 1.0, 4.3, 2.2], $ [0.0, 5.5, 3.8, 0.2]] ; Define the right-hand side vector B: B = [0.0, 1.0, 5.3, -2.0, 6.3, 3.8] ; Decompose A: SVDC, A, W, U, V ; Compute the solution and print the result: PRINT, SVSOL(U, W, V, B) IDL prints: 1.00095 0.00881170 0.984176 -0.0100954 This is the correct solution. See Also CRAMER, GS_ITER, LU_COMPLEX, CHOLSOL, LUSOL, SVDC, TRISOL SWAP_ENDIAN [Previous Routine] [Next Routine] [List of Routines] NAME: SWAP_ENDIAN The SWAP_ENDIAN function reverses the byte ordering of arbitrary scalars, arrays or structures. It can make "big endian" number "little endian" and vice-versa. Note that the BYTEORDER procedure can be used to reverse the byte ordering of scalars and arrays (SWAP_ENDIAN also allows structures). SWAP_ENDIAN returns values of the same type and structure as the input value, with the pertinent bytes reversed. This routine is written in the IDL language. Its source code can be found in the file swap_endian.pro in the lib subdirectory of the IDL distribution. Syntax Result = SWAP_ENDIAN(Variable) Arguments Variable The named variable-scalar, array, or structure-to be swapped. Example ; Reverse the byte order of A: A = SWAP_ENDIAN(A) See Also BYTEORDER SWITCH [Previous Routine] [Next Routine] [List of Routines] NAME: SWITCH The SWITCH statement is used to select one statement for execution from multiple choices, depending upon the value of the expression following the word SWITCH. Each statement that is part of a SWITCH statement is preceded by an expression that is compared to the value of the SWITCH expression. SWITCH executes by comparing the SWITCH expression with each selector expression in the order written. If a match is found, program execution jumps to that statement and execution continues from that point. Whereas CASE executes at most one statement within the CASE block, SWITCH executes the first matching statement and any following statements in the SWITCH block. Once a match is found in the SWITCH block, execution falls through to any remaining statements. For this reason, the BREAK statement is commonly used within SWITCH statements to force an immediate exit from the SWITCH block. The ELSE clause of the SWITCH statement is optional. If included, it matches any selector expression, causing its code to be executed. For this reason, it is usually written as the last clause in the switch statement. The ELSE statement is executed only if none of the preceding statement expressions match. If an ELSE clause is not included and none of the values match the selector, program execution continues immediately below the SWITCH without executing any of the SWITCH statements. SWITCH is similar to the CASE statement. For more information on using SWITCH and other IDL program control statements, as well as the differences between SWITCH and CASE, see Chapter 11, "Program Control" in Building IDL Applications. Syntax SWITCH expression OF expression: statement ... expression: statement ELSE: statement ENDSWITCH Example This example illustrates how, unlike CASE, SWITCH executes the first matching statement and any following statements in the SWITCH block: x=2 SWITCH x OF 1: PRINT, 'one' 2: PRINT, 'two' 3: PRINT, 'three' 4: PRINT, 'four' ENDSWITCH IDL Prints: two three four See Also CASE SYSTIME [Previous Routine] [Next Routine] [List of Routines] NAME: SYSTIME The SYSTIME function returns the current time as either a date/time string, as the number of seconds elapsed since 1 January 1970, or as a Julian date/time value. Syntax String = SYSTIME( [0 [, ElaspedSeconds]] [, /UTC] ) or Seconds = SYSTIME( 1 | /SECONDS ) or Julian = SYSTIME( /JULIAN [, /UTC] ) Arguments SecondsFlag If SecondsFlag is present and nonzero, the number of seconds elapsed since 1 January 1970 UTC is returned as a double-precision, floating-point value. Otherwise, if SecondsFlag is not present or zero, a scalar string containing the date/time is returned in standard 24-character system format as follows: DOW MON DD HH:MM:SS YEAR where DOW is the day of the week, MON is the month, DD is the day of the month, HH is the hour, MM is the minute, SS is the second, and YEAR is the year. By default, the date/time string is adjusted for the local time zone; use the UTC keyword to override this default. Note If the JULIAN or SECONDS keyword is set, the SecondsFlag argument is ignored. ElapsedSeconds If the SecondsFlag argument is zero, the ElapsedSeconds argument may be set to the number of seconds past 1 January 1970 UTC. In this case, SYSTIME returns the corresponding date/time string (rather than the string for the current time). The returned date/time string is adjusted for the local time zone, unless the UTC keyword is set. If this argument is present, the JULIAN keyword is not allowed. Keywords JULIAN Set this keyword to specify that the current time is to be returned as a a double precision floating value containing the current Julian date/time. By default, the current time is adjusted for the local time zone; use the UTC keyword to override this default. This keyword is not allowed if the ElapsedSeconds argument is present. Note If the JULIAN keyword is set, a small offset is added to the returned Julian date to eliminate roundoff errors when calculating the day fraction from hours, minutes, and seconds. This offset is given by the larger of EPS and EPS*Julian, where Julian is the integer portion of the Julian date, and EPS is the EPS field from MACHAR. For typical Julian dates, this offset is approximately 6x10­10 (which corresponds to 5x10­5 seconds). This offset ensures that if the Julian date is converted back to hour, minute, and second, then the hour, minute, and second will have the same integer values as were originally input. SECONDS Set this keyword to specify that the current time is to be returned as the number of seconds elapsed since 1 January 1970 UTC. This option is equivalent to setting the SecondsFlag argument to a non-zero value. UTC Set this keyword to specify that the value returned by SYSTIME is to be returned in Universal Time Coordinated (UTC) rather than being adjusted for the current time zone. UTC time is defined as Greenwich Mean Time updated with leap seconds. Examples Print today's date as a string: PRINT, SYSTIME() Print today's date as a string in UTC (rather than local time zone): PRINT, SYSTIME(/UTC) Print today's date as a Julian date/time value in UTC: PRINT, SYSTIME(/JULIAN, /UTC), FORMAT='(f12.2)' Compute the seconds elapsed since 1 January 1970 UTC: seconds = SYSTIME(1) ; or seconds = SYSTIME(/SECONDS) Verify that the seconds from the previous example are correct: PRINT, SYSTIME(0, seconds) Print the day of the week: PRINT, STRMID(SYSTIME(0), 0, 3) Compute the time required to perform a 16,384 point FFT: T = SYSTIME(1) A = FFT(FINDGEN(16384), -1) PRINT, SYSTIME(1) - T, 'Seconds' See Also CALDAT, CALENDAR, JULDAY, TIMEGEN T_CVF [Previous Routine] [Next Routine] [List of Routines] NAME: T_CVF The T_CVF function computes the cutoff value V in a Student's t distribution with Df degrees of freedom such that the probability that a random variable X is greater than V is equal to a user-supplied probability P. This routine is written in the IDL language. Its source code can be found in the file t_cvf.pro in the lib subdirectory of the IDL distribution. Syntax Result = T_CVF(P, Df) Arguments P A non-negative single- or double-precision floating-point scalar, in the interval [0.0, 1.0], that specifies the probability of occurrence or success. Df A positive integer, single- or double-precision floating-point scalar that specifies the number of degrees of freedom of the Student's t distribution. Example Use the following command to compute the cutoff value in a Student's t distribution with five degrees of freedom such that the probability that a random variable X is greater than the cutoff value is 0.025. result = T_CVF(0.025, 5) PRINT, result IDL prints: 2.57058 See Also CHISQR_CVF, F_CVF, GAUSS_CVF, T_PDF T_PDF [Previous Routine] [Next Routine] [List of Routines] NAME: T_PDF The T_PDF function computes the probability P that, in a Student's t distribution with Df degrees of freedom, a random variable X is less than or equal to a user- specified cutoff value V. This routine is written in the IDL language. Its source code can be found in the file t_pdf.pro in the lib subdirectory of the IDL distribution. Syntax Result = T_PDF(V, Df) Return Value If both arguments are scalar, the function returns a scalar. If both arguments are arrays, the function matches up the corresponding elements of V and Df, returning an array with the same dimensions as the smallest array. If one argument is a scalar and the other argument is an array, the function uses the scalar value with each element of the array, and returns an array with the same dimensions as the input array. If any of the arguments are double-precision, the result is double-precision, otherwise the result is single-precision. Arguments V A scalar or array that specifies the cutoff value(s). Df A scalar or array that specifies the number of degrees of freedom of the Student's t distribution. Example Use the following command to compute the probability that a random variable X, from the Student's t distribution with 15 degrees of freedom, is less than or equal to 0.691: PRINT, T_PDF(0.691, 15) IDL prints: 0.749940 See Also BINOMIAL, CHISQR_PDF, F_PDF, GAUSS_PDF, T_CVF T3D [Previous Routine] [Next Routine] [List of Routines] NAME: T3D The T3D procedure implements three-dimensional transforms. This routine accumulates one or more sequences of translation, scaling, rotation, perspective, and oblique transformations and stores the result in !P.T, the 3D transformation system variable. All the IDL graphic routines use this (4,4) matrix for output. Note that !P.T3D is not set, so for the transformations to have effect you must set !P.T3D = 1 (or set the T3D keyword in subsequent calls to graphics routines). This procedure is based on that of Foley & Van Dam, Fundamentals of Interactive Computer Graphics, Chapter 8, "Viewing in Three Dimensions". The matrix notation is reversed from the normal IDL sense, i.e., here, the first subscript is the column, the second is the row, in order to conform with this reference. A right-handed system is used. Positive rotations are counterclockwise when looking from a positive axis position towards the origin. This routine is written in the IDL language. Its source code can be found in the file t3d.pro in the lib subdirectory of the IDL distribution. Syntax T3D [, Array | , /RESET] [, MATRIX=variable] [, OBLIQUE=vector] [, PERSPECTIVE=p{eye at (0,0,p)}] [, ROTATE=[x, y, z]] [, SCALE=[x, y, z]] [, TRANSLATE=[x, y, z]] [, /XYEXCH | , /XZEXCH | , /YZEXCH] Arguments Array An optional 4 x 4 matrix used as the starting transformation. If Array is missing, the current !P.T transformation is used. Array is ignored if /RESET is set. Keywords The transformation specified by each keyword is performed in the order of their descriptions below (e.g., if both TRANSLATE and SCALE are specified, the translation is done first). MATRIX Set this keyword to a named variable that will contain the result. If this keyword is specified, !P.T is not modified. OBLIQUE A two-element vector of oblique projection parameters. Points are projected onto the XY plane at Z=0 as follows: x' = x + z(d * COS(a)) y' = y + z(d * SIN(a)) where OBLIQUE[0] = d and OBLIQUE[1] = a. PERSPECTIVE Perspective transformation. This parameter is a scalar (p) that indicates the Z distance of the center of the projection. Objects are projected into the XY plane at Z=0, and the "eye" is at point (0,0,p). RESET Set this keyword to reset the transformation to the default identity matrix. ROTATE A three-element vector of the rotations, in DEGREES, about the X, Y, and Z axes. Rotations are performed in the order of X, Y, and then Z. SCALE A three-element vector of scale factors for the X, Y, and Z axes. TRANSLATE A three-element vector of the translations in the X, Y, and Z directions. XYEXCH Set this keyword to exchange the X and Y axes. XZEXCH Set this keyword to exchange the X and Z axes. YZEXCH Set this keyword to exchange the Y and Z axes. Examples To reset the transformation, rotate 30 degs about the X axis and do perspective transformation with the center of the projection at Z = -1, X=0, and Y=0, enter: T3D, /RESET, ROT = [ 30,0,0], PERS = 1. Transformations may be cascaded, for example: T3D, /RESET, TRANS = [-.5,-.5,0], ROT = [0,0,45] T3D, TRANS = [.5,.5,0] The first command resets, translates the point (.5,.5,0) to the center of the viewport, then rotates 45 degrees counterclockwise about the Z axis. The second call to T3D moves the origin back to the center of the viewport. See Also SCALE3, SCALE3D, SURFR TAG_NAMES [Previous Routine] [Next Routine] [List of Routines] NAME: TAG_NAMES The TAG_NAMES function returns a string array containing the names of the tags in a structure expression. It can also be used to determine the expression's structure name (if the structure has a name). Syntax Result = TAG_NAMES( Expression [, /STRUCTURE_NAME] ) Arguments Expression The structure expression for which the tag names are returned. This argument must be of structure type. TAG_NAMES does not search for tags recursively, so if Expression is a structure containing nested structures, only the names of tags in the outermost structure are returned. Keywords STRUCTURE_NAME Set this keyword to return a scalar string that contains the name of the structure instead of the names of the tags in the structure. If the structure is "anonymous", a null string is returned. Example Print the names of the tags in the system variable !P by entering: PRINT, TAG_NAMES(!P) IDL prints: BACKGROUND CHARSIZE CHARTHICK CLIP COLOR FONT LINESTYLE MULTI NOCLIP NOERASE NSUM POSITION PSYM REGION SUBTITLE SYMSIZE T T3D THICK TITLE TICKLEN CHANNEL Print the name of the structure in the system variable !P: PRINT, TAG_NAMES(!P, /STRUCTURE_NAME) IDL prints: !PLT See Also CREATE_STRUCT, N_TAGS TAN [Previous Routine] [Next Routine] [List of Routines] NAME: TAN The TAN function returns the tangent of X. Syntax Result = TAN(X) Arguments X The angle for which the tangent is desired, specified in radians. If X is double- precision floating-point, the result is of the same type. Complex values are not allowed. All other types are converted to single-precision floating-point and yield floating-point results. If X is an array, the result has the same structure, with each element containing the tangent of the corresponding element of X. Example ; Find the tangent of 0.5 radians and store the result in ; the variable T: T = TAN(0.5) See Also ATAN, TANH TANH [Previous Routine] [Next Routine] [List of Routines] NAME: TANH The TANH function returns the hyperbolic tangent of X. Syntax Result = TANH(X) Arguments X The value for which the hyperbolic tangent is desired, specified in radians. If X is double-precision floating-point, 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. TANH is defined as: ­ tanh x ( ) ex ­ e x = ------------------- ex + e­x If X is an array, the result has the same structure, with each element containing the hyperbolic tangent of the corresponding element of X. Example ; Find the hyperbolic tangent of 1 radian and print the result: PRINT, TANH(1) ; Plot the hyperbolic tangent from -5 to +5 with an increment ; of 0.1: PLOT, TANH(FINDGEN(101)/10. - 5) See Also ATAN, TAN TAPRD [Previous Routine] [Next Routine] [List of Routines] NAME: TAPRD The TAPRD procedure reads the next record on the selected tape unit into the specified array. TAPRD is available only under VMS. No data or format conversion, with the exception of optional byte reversal, is performed. The array must be defined with the desired type and dimensions. If the read is successful, the system variable !ERR is set to the number of bytes read. See the description of the magnetic tape routines in "VMS-Specific Information" in Chapter 8 of Building IDL Applications. Syntax TAPRD, Array, Unit [, Byte_Reverse] Arguments Unit The magnetic tape unit to read. This argument must be a number between 0 and 9, and should not be confused with standard file Logical Unit Numbers (LUN's). Array A named variable into which the data is read. If Array is larger than the tape record, the extra elements of the array are not changed. If the array is shorter than the tape record, a data overrun error occurs. The length of Array and the records on the tape can range from 14 bytes to 65,235 bytes. Byte_Reverse If this parameter is present, the even and odd numbered bytes are swapped after reading, regardless of the type of data or variables. This enables reading tapes containing short integers that were written on machines with different byte ordering. You can also use the BYTORDER routine to re-order different data types. See Also TAPWRT TAPWRT [Previous Routine] [Next Routine] [List of Routines] NAME: TAPWRT The TAPWRT procedure writes data from the Array parameter to the selected tape unit. TAPWRT is available only under VMS. One physical record containing the same number of bytes as the array is written each time TAPWRT is called. The parameters and usage are identical to those in the TAPRD procedure with the exception that here the Array parameter can be an expression. Consult the TAPRD procedure for details. See the description of the magnetic tape routines in "VMS- Specific Information" in Chapter 8 of Building IDL Applications. Syntax TAPWRT, Array, Unit [, Byte_Reverse] Arguments Unit The magnetic tape unit to write. This argument must be a number between 0 and 9, and should not be confused with standard file Logical Unit Numbers (LUNs). Array The expression representing the data to be output. The length of Array and the records on the tape can range from 14 bytes to 65,235 bytes. Byte_Reverse If this parameter is present, the even and odd numbered bytes are swapped on output, regardless of the type of data or variables. This enables writing tapes that are compatible with other machines. See Also TAPRD TEK_COLOR [Previous Routine] [Next Routine] [List of Routines] NAME: TEK_COLOR The TEK_COLOR procedure loads a 32-color colortable similar to the default Tektronix 4115 colortable. This colortable is useful because of its distinct colors. By default, this palette consists of 32 colors. The first 9 colors are: Index 0=black, 1=white, 2=red, 3=green, 4=blue, 5=cyan, 6=magenta, 8=orange. Syntax TEK_COLOR [, Start_Index, Colors] Arguments Start_Index An optional starting index for the palette. The default is 0. If this argument is included, the colors are loaded into the current colortable starting at the specified index. Colors The number of colors to load. The default is 32, which is also the maximum. See Also LOADCT, XLOADCT TEMPORARY [Previous Routine] [Next Routine] [List of Routines] NAME: TEMPORARY The TEMPORARY function returns a temporary copy of a variable, and sets the original variable to "undefined". This function can be used to conserve memory when performing operations on large arrays, as it avoids making a new copy of results that are only temporary. In general, the TEMPORARY routine can be used to advantage whenever a variable containing an array on the left hand side of an assignment statement is also referenced on the right hand side. Syntax Result = TEMPORARY(Variable) Arguments Variable The variable to be referenced and deleted. Example Assume the variable A is a large array. The statement: A = A + 1 creates a new array for the result of the addition, places the sum into the new array, assigns it to a, and then frees the old allocation of a. Total storage required is twice the size of a. The statement: A = TEMPORARY(A) + 1 requires no additional space. See Also DELVAR TETRA_CLIP [Previous Routine] [Next Routine] [List of Routines] NAME: TETRA_CLIP The TETRA_CLIP function clips a tetrahedral mesh to an arbitrary plane in space and returns a tetrahedral mesh of the remaining portion. An auxiliary array of data may also be passed and clipped. This array can have multiple values for each vertex (the trailing array dimension must match the number of vertices in the Vertsin array). A tetrahedral connectivity array consists of groups of four vertex index values. Each set of four index values specifies four vertices which define a single tetrahedron. Syntax Result = TETRA_CLIP ( Plane, Vertsin, Connin, Vertsout, Connout [, AUXDATA_IN=array, AUXDATA_OUT=variable] [, CUT_VERTS=variable] ) Return Value The return value is the number of tetrahedra returned. Arguments Plane Input four-element array describing the equation of the plane to be clipped to. The elements are the coefficients (a,b,c,d) of the equation ax+by+cz+d=0. Vertsin Input array of tetrahedral vertices [3, n]. Connin Input tetrahedral mesh connectivity array. Vertsout Output array of tetrahedral vertices [3, n]. Connout Output tetrahedral mesh connectivity array. Keywords AUXDATA_IN Input array of auxiliary data. If present, these values are interpolated and returned through AUXDATA_OUT. The trailing array dimension must match the number of vertices in the Vertsin array. AUXDATA_OUT Set this keyword to a named variable to contain an output array of interpolated auxiliary data. CUT_VERTS Set this keyword to a named variable to contain an output array of vertex indices (into Vertsout) of the vertices which are considered to be `on' the clipped surface. TETRA_SURFACE [Previous Routine] [Next Routine] [List of Routines] NAME: TETRA_SURFACE The TETRA_SURFACE function extracts a polygonal mesh as the exterior surface of a tetrahedral mesh. The output of this function is a polygonal mesh connectivity array that can be used with the input Verts array to display the outer surface of the tetrahedral mesh. Syntax Result = TETRA_SURFACE (Verts, Connin) Return Value Returns a polygonal mesh connectivity array. When used with the input vertex array, this function yields the exposed tetrahedral mesh surface. Arguments Verts Array of vertices [3, n]. Connin Tetrahedral connectivity array. TETRA_VOLUME [Previous Routine] [Next Routine] [List of Routines] NAME: TETRA_VOLUME The TETRA_VOLUME function computes properties of a tetrahedral mesh array. The basic property is the volume. An auxiliary data array may be supplied which specifies weights at each vertex which are interpolated through the volume during integration. Higher order moments (with respect to the X, Y, and Z axis) may be computed as well (with or without weights). Syntax Result = TETRA_VOLUME ( Verts, Conn [, AUXDATA=array] [, MOMENT=variable] ) Return Value Returns the cumulative (weighted) volume of the tetrahedrons in the mesh. Arguments Verts Array of vertices [3, n]. Conn Tetrahedral connectivity array. Keywords AUXDATA Array of input auxiliary data (one value per vertex). If present, these values are used to weight a vertex. The volume area integral will linearly interpolate these values. The volume integral will linearly interpolate these values within each tetrahedra. The default weight is 1.0 which results in a basic volume. MOMENT Set this keyword to a named variable that will contain a three-element float vector which corresponds to the first order moments computed with respect to the X, Y and Z axis. The computation is: m = v ici ntetras where v is the (weighted) volume of the tetrahedron and c is the centroid of the tetrahedron, thus m volume yields the (weighted) centroid of the tetrahedral mesh. THIN [Previous Routine] [Next Routine] [List of Routines] NAME: THIN The THIN function returns the "skeleton" of a bi-level image. The skeleton of an object in an image is a set of lines that reflect the shape of the object. The set of skeletal pixels can be considered to be the medial axis of the object. For a much more extensive discussion of skeletons and thinning algorithms, see Algorithms for Graphics and Image Processing, Theo Pavlidis, Computer Science Press, 1982. The THIN function is adapted from Algorithm 9.1 (the classical thinning algorithm). On input, the bi-level image is a rectangular array in which pixels that compose the object have a nonzero value. All other pixels are zero. The result is a byte type image in which skeletal pixels are set to 2 and all other pixels are zero. Syntax Result = THIN( Image [, /NEIGHBOR_COUNT] [, /PRUNE] ) Arguments Image The two-dimensional image (array) to be thinned. Keywords NEIGHBOR_COUNT Set this keyword to select an alternate form of output. In this form, output pixel values count the number of neighbors an individual skeletal pixel has (including itself). For example, a pixel that is part of a line will have the value 3 (two neighbors and itself). Terminal pixels will have the value 2, while isolated pixels have the value 1. PRUNE If the PRUNE keyword is set, pixels with single neighbors are removed iteratively until only pixels with 2 or more neighbors exist. This effectively removes (or "prunes") skeleton branches, leaving only closed paths. Example The following commands display the "thinned" edges of a Sobel filtered image: ; Open a file for reading: OPENR, 1, FILEPATH('people.dat', SUBDIR = ['examples','data']) ; Create a byte array in which to store the image: A = BYTARR(192, 192) ; Read first 192 by 192 image: READU, 1, A ; Close the file: CLOSE, 1 ; Display the image: TV, A, 0 ; Apply the Sobel filter, threshold the image at value 75, and ; display the thinned edges: TVSCL, THIN(SOBEL(A) GT 75), 1 See Also ROBERTS, SOBEL THREED [Previous Routine] [Next Routine] [List of Routines] NAME: THREED The THREED procedure plots a 2D array as a pseudo 3D plot. The orientation of the data is fixed. This routine is written in the IDL language. Its source code can be found in the file threed.pro in the lib subdirectory of the IDL distribution. Syntax THREED, A [, Sp] [, TITLE=string] [, XTITLE=string] [, YTITLE=string] Arguments A The two-dimensional array to plot. Sp The spacing between plot lines. If Sp is omitted, the spacing is set to: (MAX(A)- MIN(A))/ROWS. If Sp is negative, hidden lines are not removed. Keywords TITLE Set this keyword to the main plot title. XTITLE Set this keyword to the X axis title. YTITLE Set this keyword to the Y axis title. Example ; Create a 2D dataset: A = -SHIFT(DIST(30), 15, 15) ; Make a THREED plot: THREED, A ; Compare to SURFACE: SURFACE, A See Also SURFACE TIME_TEST2 [Previous Routine] [Next Routine] [List of Routines] NAME: TIME_TEST2 The TIME_TEST2 procedure is a general-purpose IDL benchmark program that performs approximately 20 common operations and prints the time required. This routine is written in the IDL language. Its source code can be found in the file time_test.pro in the lib subdirectory of the IDL distribution. This file also contains the procedure GRAPHICS_TIMES, used to time graphical operations. Syntax TIME_TEST2 [, Filename] Arguments Filename An optional string that contains the name of output file for the results of the time test. Example ; Run the computational tests: TIME_TEST2 ; Run the graphics tests. Note that TIME_TEST2 must be compiled ; before GRAPHICS_TIMES will run: GRAPHICS_TIMES See Also SYSTIME TIMEGEN [Previous Routine] [Next Routine] [List of Routines] NAME: TIMEGEN The TIMEGEN function returns an array, with specified dimensions, of double- precision floating-point values that represent times in terms of Julian dates. The Julian date is the number of days elapsed since Jan. 1, 4713 B.C.E., plus the time expressed as a day fraction. Following the astronomical convention, the day is defined to start at 12 PM (noon). Julian date 0.0d is therefore Jan. 1, 4713 B.C.E. at 12:00:00. The first value of the returned array corresponds to a Julian date start time, and each subsequent value corresponds to the next Julian date in the sequence. The sequence is determined by specifying the time unit (such as months or seconds) and the step size, or spacing, between the units. You can also construct more complicated arrays by including smaller time units within each major time interval. A small offset is added to each Julian date to eliminate roundoff errors when calculating the day fraction from the hour, minute, second. This offset is given by the larger of EPS and EPS*Julian, where Julian is the integer portion of the Julian date and EPS is the double-precision floating-point precision parameter from MACHAR. For typical Julian dates the offset is approximately 6x10-10 (which corresponds to 5x10-5 seconds). This offset ensures that when the Julian date is converted back to the hour, minute, and second, the hour, minute, and second will have the same integer values. Tip Because of the large magnitude of the Julian date (1 Jan 2000 is Julian day 2451545), the precision of most Julian dates is limited to 1 millisecond (0.001 seconds). If you are not interested in the date itself, you can improve the precision by subtracting a large offset or setting the START keyword to zero. Note Julian values must be in the range -1095 to 1827933925, which corresponds to calendar dates 1 Jan 4716 B.C.E. and 31 Dec 5000000, respectively. Syntax Result = TIMEGEN( [D1,...,D8 | , FINAL=value] [, DAYS=vector] [, HOURS=vector] [, MINUTES=vector] [, MONTHS=vector] [, SECONDS=vector] [, START=value] [, STEP_SIZE=value] [, UNITS=string] [, YEAR=value] ) Arguments Di The dimensions of the result. The dimension parameters may be any scalar expression. Up to eight dimensions may be specified. If the dimension arguments are not integer values, IDL will truncate them to integer values before creating the new array. The dimension arguments are required unless keyword FINAL is set, in which case they are ignored. Keywords DAYS Set this keyword to a scalar or a vector giving the day values that should be included within each month. This keyword is ignored if the UNITS keyword is set to "Days", "Hours", "Minutes", or "Seconds". Note Day values that are beyond the end of the month will be set equal to the last day for that month. For example, setting DAY=[31] will automatically return the last day in each month. FINAL Set this keyword to a double-precision value representing the Julian date/time to use as the last value in the returned array. In this case, the dimension arguments are ignored and Result is a one-dimensional array, with the number of elements depending upon the step size. The FINAL time may be less than the START time, in which case STEP_SIZE should be negative. Note If the step size is not an integer then the last element may not be equal to the FINAL time. In this case, TIMEGEN will return enough elements such that the last element is less than or equal to FINAL. HOURS Set this keyword to a scalar or a vector giving the hour values that should be included within each day. This keyword is ignored if UNITS is set to "Hours", "Minutes", or "Seconds". MINUTES Set this keyword to a scalar or a vector giving the minute values that should be included within each hour. This keyword is ignored if UNITS is set to "Minutes" or "Seconds". MONTHS Set this keyword to a scalar or a vector giving the month values that should be included within each year. This keyword is ignored if UNITS is set to "Months", "Days", "Hours", "Minutes", or "Seconds". SECONDS Set this keyword to a scalar or a vector giving the second values that should be included within each minute. This keyword is ignored if UNITS is set to "Seconds". START Set this keyword to a double-precision value representing the Julian date/time to use as the first value in the returned array. The default is 0.0d [corresponding to January 1, 4713 B.C.E. at 12 pm (noon)]. Note If subintervals are provided by MONTHS, DAYS, HOURS, MINUTES, or SECONDS, then the first element may not be equal to the START time. In this case the first element in the returned array will be greater than or equal to START. Tip Other array generation routines in IDL (such as FINDGEN) do not allow you to specify a starting value because the resulting array can be added to a scalar representing the start value. For TIMEGEN it is correct to add a scalar to the array if the units are days, hours, minutes, seconds, or sub-seconds. For example: MyTimes = TIMEGEN(365, UNITS="Days") + SYSTIME(/JULIAN) However, if the units are months or years, the start value is necessary because the number of days in a month or year can vary depending upon the year in which they fall (for instance, consider leap years). For example: MyTimes = TIMEGEN(12, UNITS="Months", START=JULDAY(1,1,2000)) STEP_SIZE Set this keyword to a scalar value representing the step size between the major intervals of the returned array. The step size may be negative. The default step size is 1. When the UNITS keyword is set to "Years" or "Months", the STEP_SIZE value is rounded to the nearest integer. UNITS Set this keyword to a scalar string indicating the time units to be used for the major intervals for the generated array. Valid values include: * "Years" or "Y" * "Months" or "M" * "Days" or "D" * "Hours" or "H" * "Minutes" or "I" * "Seconds" or "S" The case (upper or lower) is ignored. If this keyword is not specified, then the default for UNITS is the time unit that is larger than the largest keyword present: Largest Keyword Present Default UNITS SECONDS=vector "Minutes" MINUTES=vector "Hours" HOURS=vector "Days" DAYS=vector "Months" MONTHS=vector "Years" YEAR=value "Years" Table 89: Defaults for the UNITS keyword If none of the above keywords are present, the default is UNITS="Days". YEAR Set this keyword to a scalar giving the starting year. If YEAR is specified then the starting year from START is ignored. Examples * Generate an array of 366 time values that are one day apart starting with January 1, 2000: MyDates = TIMEGEN(366, START=JULDAY(1,1,2000)) * Generate an array of 20 time values that are 12 hours apart starting with the current time: MyTimes = TIMEGEN(20, UNITS='Hours', STEP_SIZE=12, $ START=SYSTIME(/JULIAN)) * Generate an array of time values that are 1 hour apart from 1 January 2000 until the current time: MyTimes = TIMEGEN(START=JULDAY(1,1,2000), $ FINAL=SYSTIME(/JULIAN), UNITS='Hours') * Generate an array of time values composed of seconds, minutes, and hours that start from the current hour: MyTimes = TIMEGEN(60, 60, 24, $ START=FLOOR(SYSTIME(/JULIAN)*24)/24d, UNITS='S') * Generate an array of 24 time values with monthly intervals, but with subintervals at 5 PM on the first and fifteenth of each month: MyTimes = TIMEGEN(24, START=FLOOR(SYSTIME(/JULIAN)), $ DAYS=[1,15], HOURS=17) See Also CALDAT, JULDAY, LABEL_DATE, SYSTIME TM_TEST [Previous Routine] [Next Routine] [List of Routines] NAME: TM_TEST The TM_TEST function computes the Student's T-statistic and the probability that two sample populations X and Y have significantly different means. X and Y may be of different lengths. The result is a two-element vector containing the T-statistic and its significance. The significance is a value in the interval [0.0, 1.0]; a small value (0.05 or 0.01) indicates that X and Y have significantly different means. The default assumption is that the data is drawn from populations with the same true variance. This type of test is often referred to as the t-means test. The T-statistic for sample populations x and y with means x and y is defined as: T x ­ y = ----------------------------------------------- N ­ 1 M ­ 1 (x i ­ x)2 + (y i ­ y)2 1 j = 0 j = 0 ---------------------------------------------------------------------- ---- 1 + - (N + M ­ 2) N M where x = (x0, x1, x2, ..., xN-1) and y = (y0, y1, y2 ..., yM-1) This routine is written in the IDL language. Its source code can be found in the file tm_test.pro in the lib subdirectory of the IDL distribution. Syntax Result = TM_TEST( X, Y [, /PAIRED] [, /UNEQUAL] ) Arguments X An n-element integer, single-, or double-precision floating-point vector. Y An m-element integer, single-, or double-precision floating-point vector. If the PAIRED keyword is set, X and Y must have the same number of elements. Keywords PAIRED If this keyword is set, X and Y are assumed to be paired samples and must have the same number of elements. UNEQUAL If this keyword is set, X and Y are assumed to be from populations with unequal variances. Example ; Define two n-element sample populations. X = [257, 208, 296, 324, 240, 246, 267, 311, 324, 323, 263, $ 305, 270, 260, 251, 275, 288, 242, 304, 267] Y = [201, 56, 185, 221, 165, 161, 182, 239, 278, 243, 197, $ 271, 214, 216, 175, 192, 208, 150, 281, 196] ; Compute the Student's t-statistic and its significance assuming ; that X and Y belong to populations with the same true variance: PRINT, TM_TEST(X, Y) IDL prints: 5.52839 2.52455e-06 The result indicates that X and Y have significantly different means. See Also FV_TEST, KW_TEST, RS_TEST, S_TEST TOTAL [Previous Routine] [Next Routine] [List of Routines] NAME: TOTAL The TOTAL function returns the sum of the elements of Array. The sum of the array elements over a given dimension is returned if the Dimension argument is present. Syntax Result = TOTAL( Array [, Dimension] [, /CUMULATIVE] [, /DOUBLE] [, /NAN] ) Arguments Array The array to be summed. This array can be of any basic type except string. If Array is double-precision floating-point, complex, or double-precision complex, the result is of the same type. Otherwise, the result is single-precision floating-point. Dimension The dimension over which to sum, starting at one. If this argument is not present or zero, the scalar sum of all the array elements is returned. If this argument is present, the result is an array with one less dimension than Array. For example, if the dimensions of Array are N1, N2, N3, and Dimension is 2, the dimensions of the result are (N1, N3), and element (i,j) of the result contains the sum: N2 ­ 1 A k = 0 i,k, j Keywords CUMULATIVE If this keyword is set, the result is an array of the same size as the input, with each element, i, containing the sum of the input array elements 0 to i. This keyword also works with the Dimension parameter, in which case the sum is performed over the given dimension. DOUBLE Set this keyword to perform the summation in double-precision floating-point. NAN Set this keyword to cause the routine to check for occurrences of the IEEE floating- point value NaN in the input data. Elements with the value NaN are treated as missing data. (See "Special Floating-Point Values" in Chapter 17 of Building IDL Applications for more information on IEEE floating-point values.) Example Example 1 This example sums the elements of a one-dimensional array: ; Define a one-dimensional array: A = [20, 10, 5, 5, 3] ; Sum the elements of the array: SUMA = TOTAL([20, 10, 5, 5, 3]) ; Print the results: PRINT, 'A = ', A PRINT, 'Sum of A = ', SUMA IDL prints: A = 20 10 5 5 3 Sum of A = 43.0000 Example 2 The results are different when a multi-dimensional array is used: ; Define a multi-dimensional array: A = FINDGEN(5,5) ; Sum each of the rows in A: SUMROWS = TOTAL(A, 1) ; Sum each of the columns in A: SUMCOLS = TOTAL(A, 2) ; Print the results: PRINT, 'A = ', A PRINT, 'Sum of each row:', SUMROWS PRINT, 'Sum of each column:', SUMCOLS IDL prints: A = 0.000000 1.00000 2.00000 3.00000 4.00000 5.00000 6.00000 7.00000 8.00000 9.00000 10.0000 11.0000 12.0000 13.0000 14.0000 15.0000 16.0000 17.0000 18.0000 19.0000 20.0000 21.0000 22.0000 23.0000 24.0000 Sum of each row: 10.0000 35.0000 60.0000 85.0000 110.000 Sum of each column: 50.0000 55.0000 60.0000 65.0000 70.0000 See Also FACTORIAL TRACE [Previous Routine] [Next Routine] [List of Routines] NAME: TRACE The TRACE function computes the trace of an n by n array. This routine is written in the IDL language. Its source code can be found in the file trace.pro in the lib subdirectory of the IDL distribution. Syntax Result = TRACE( A [, /DOUBLE] ) Arguments A An n by n real or complex array. Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. Example ; Define an array: A = [[ 2.0,1.0, 1.0, 1.5], $ [ 4.0, -6.0, 0.0, 0.0], $ [-2.0, 7.0, 2.0, 2.5], $ [ 1.0, 0.5, 0.0, 5.0]] ; Compute the trace of A: result = TRACE(A) ;Print the result: PRINT, 'TRACE(A) = ', result IDL prints: TRACE(A) = 3.00000 See Also TOTAL TRANSPOSE [Previous Routine] [Next Routine] [List of Routines] NAME: TRANSPOSE The TRANSPOSE function returns the transpose of Array. If an optional permutation vector is provided, the dimensions of Array are rearranged as well. Syntax Result = TRANSPOSE( Array [, P] ) Arguments Array The array to be transposed. P A vector specifying how the dimensions of Array will be permuted. The elements of P correspond to the dimensions of Array; the ith dimension of the output array is dimension P[i] of the input array. Each element of the vector P must be unique. Dimensions start at zero and can not be repeated. If P is not present, the order of the indices of Array is reversed. Example Example 1 Print a simple array and its transpose by entering: ; Create an array: A = INDGEN(3,3) TRANSA = TRANSPOSE(A) ; Print the array and its transpose: PRINT, 'A:' PRINT, A PRINT, 'Transpose of A:' PRINT, TRANSA IDL prints: A: 0 1 2 3 4 5 6 7 8 Transpose of A: 0 3 6 1 4 7 2 5 8 Example 2 This example demonstrates multi-dimensional transposition: ; Create the array: A = INDGEN(2, 3, 4) ; Take the transpose, reversing the order of the indices: B = TRANSPOSE(A) ; Re-order the dimensions of A, so that the second dimension ; becomes the first, the third becomes the second, and the first ; becomes the third: C = TRANSPOSE(A, [1, 2, 0]) ; View the sizes of the three arrays: HELP, A, B, C IDL prints: A INT = Array[2, 3, 4] B INT = Array[4, 3, 2] C INT = Array[3, 4, 2] See Also REFORM, ROT, ROTATE, REVERSE TRI_SURF [Previous Routine] [Next Routine] [List of Routines] NAME: TRI_SURF The TRI_SURF function interpolates a regularly- or irregularly-gridded set of points with a smooth quintic surface. The result is s a two-dimensional floating-point array containing the interpolated surface, sampled at the grid points. TRI_SURF is similar to MIN_CURVE_SURF but the surface fitted is a smooth surface, not a minimum curvature surface. TRI_SURF has the advantage of being much more efficient for larger numbers of points. Note The TRI_SURF function is designed to interpolate low resolution data. Large arrays may cause TRI_SURF to issue the following error message: Partial Derivative Approximation Failed to Converge" In such cases, interpolation is most likely unnecessary. This routine is written in the IDL language. Its source code can be found in the file tri_surf.pro in the lib subdirectory of the IDL distribution. Syntax Result = TRI_SURF( Z [, X, Y] [, /EXTRAPOLATE] [, MISSING=value] [, /REGULAR] [, XGRID=[xstart, xspacing] | [, XVALUES=array]] [, YGRID=[yxstart, yspacing] | [, YVALUES=array]] [, GS=[xspacing, yspacing]] [, BOUNDS=[xmin, ymin, xmax, ymax]] [, NX=value] [, NY=value] ) Arguments X, Y, Z arrays containing the X, Y, and Z coordinates of the data points on the surface. Points need not be regularly gridded. For regularly gridded input data, X and Y are not used: the grid spacing is specified via the XGRID and YGRID (or XVALUES and YVALUES) keywords, and Z must be a two dimensional array. For irregular grids, all three parameters must be present and have the same number of elements. Keywords EXTRAPOLATE Set this keyword to cause TRI_SURF to extrapolate the surface to points outside the convex hull of input points. This keyword has no effect if the input points are regularly gridded. LINEAR Set this keyword to use linear interpolation, without gradient estimates, instead of quintic interpolation. Linear interpolation does not extrapolate, although it is faster and more numerically stable. MISSING Set this keyword equal to the value to which points outside the convex hull of input points should be set. The default is 0. This keyword has no effect if the input points are regularly gridded. Input Grid Description: REGULAR If set, the Z parameter is a two-dimensional array of dimensions (n,m), containing measurements over a regular grid. If any of XGRID, YGRID, XVALUES, or YVALUES are specified, REGULAR is implied. REGULAR is also implied if there is only one parameter, Z. If REGULAR is set, and no grid specifications are present, the grid is set to (0, 1, 2, ...). XGRID A two-element array, [xstart, xspacing], defining the input grid in the x direction. Do not specify both XGRID and XVALUES. XVALUES An n-element array defining the x locations of Z[i,j]. Do not specify both XGRID and XVALUES. YGRID A two-element array, [ystart, yspacing], defining the input grid in the y direction. Do not specify both YGRID and YVALUES. YVALUES An n-element array defining the y locations of Z[i,j]. Do not specify both YGRID and YVALUES. Output Grid Description: Note The output grid must enclose the convex hull of the input points. GS The output grid spacing. If present, GS must be a two-element vector [xs, ys], where xs is the horizontal spacing between grid points and ys is the vertical spacing. The default is based on the extents of x and y. If the grid starts at x value xmin and ends at xmax, then the default horizontal spacing is (xmax - xmin)/(NX-1). YS is computed in the same way. The default grid size, if neither NX or NY are specified, is 26 by 26. BOUNDS If present, BOUNDS must be a four-element array containing the grid limits in x and y of the output grid: [xmin, ymin, xmax, ymax]. If not specified, the grid limits are set to the extent of x and y. NX The output grid size in the x direction. NX need not be specified if the size can be inferred from GS and BOUNDS. The default value is 26. NY The output grid size in the y direction. NY need not be specified if the size can be inferred from GS and BOUNDS. The default value is 26. Example Example 1 Regularly gridded case: ; Make some random data Z = randomu(seed, 5, 6) ; Interpolate to a 26 x 26 grid: CONTOUR, TRI_SURF(Z, /REGULAR) Example 2 Irregularly gridded case: ; Make a random set of points that lie on a Gaussian: N = 15 X = RANDOMU(seed, N) Y = RANDOMU(seed, N) ; The Gaussian: Z = EXP(-2 * ((X-.5)^2 + (Y-.5)^2)) ; Use a 26 by 26 grid over the rectangle bounding x and y. ; Get the surface: R = TRI_SURF(Z, X, Y) ; Alternatively, get a surface over the unit square, with spacing ; of 0.05: R = TRI_SURF(z, x, y, GS=[0.05, 0.05], BOUNDS=[0,0,1,1]) ; Alternatively, get a 10 by 10 surface over the rectangle bounding ; x and y: R = TRI_SURF(z, x, y, NX=10, NY=10) See Also CONTOUR, MIN_CURVE_SURF TRIANGULATE [Previous Routine] [Next Routine] [List of Routines] NAME: TRIANGULATE The TRIANGULATE procedure constructs a Delaunay triangulation of a planar set of points. Delaunay triangulations are very useful for the interpolation, analysis, and visual display of irregularly-gridded data. In most applications, after the irregularly gridded data points have been triangulated, the function TRIGRID is invoked to interpolate surface values to a regular grid. Since Delaunay triangulations have the property that the circumcircle of any triangle in the triangulation contains no other vertices in its interior, interpolated values are only computed from nearby points. TRIANGULATE can, optionally, return the adjacency list that describes, for each node, the adjacent nodes in the Delaunay triangulation. With this list, the Voronoi polygon (the polygon described by the set of points which are closer to that node than to any other node) can be computed for each node. This polygon contains the area influenced by its associated node. Tiling of the region in this manner is also called Dirichlet, Wigner-Seithz, or Thiessen tessellation. The grid returned by the TRIGRID function can be input to various routines such as SURFACE, TV, and CONTOUR. See the description of TRIGRID for an example. TRIANGULATE and TRIDGRID can also be used to perform gridding and interpolation over the surface of a sphere. The interpolation is C1 continuous, meaning that the result is continuous over both the function value and its first derivative. This feature is ideal for interpolating an irregularly-sampled dataset over part or all of the surface of the earth (or other (spherical) celestial bodies). Extrapolation outside the convex hull of sample points is also supported. To perform spherical gridding, you must include the FVALUE and SPHERE keywords described below. The spherical gridding technique used in IDL is based on the paper "Interpolation of Data on the Surface of a Sphere", R. Renka, Oak Ridge National Laboratory Report ORNL/CSD-108, 1982. Syntax TRIANGULATE, X, Y, Triangles [, B] [, CONNECTIVITY=variable] [, /DEGREES] [, FVALUE=variable] [, REPEATS=variable] [, SPHERE=variable] Arguments X An array that contains the X coordinates of the points to be triangulated. Y An array that contains the Y coordinates of the points to be triangulated. Parameters X and Y must have the same number of elements. Triangles A named variable that, on exit, contains the list of triangles in the Delaunay triangulation of the points specified by the X and Y arguments. Triangles is a longword array dimensioned (3, number of triangles), where Triangles[0, i], Triangles[1, i], and Triangles[2, i] contain the indices of the vertices of the i-th triangle (i.e., X[Tr[*, i]] and Y[Triangles[*, i]] are the X and Y coordinates of the vertices of the i-th triangle). B An optional, named variable that, upon return, contains a list of the indices of the boundary points in counterclockwise order. Keywords CONNECTIVITY Set this keyword to a named variable in which the adjacency list for each of the N nodes (xy point) is returned. The list has the following form: Each element i, i 0 < N, contains the starting index of the connectivity list for node i within the list array. To obtain the adjacency list for node i, extract the list elements from LIST[i] to LIST[i+1]-1. The adjacency list is ordered in the counter-clockwise direction. The first item on the list of boundary nodes is the subscript of the node itself. For interior nodes, the list contains the subscripts of the adjacent nodes in counter-clockwise order. For example, the call: TRIANGULATE, X, Y, CONNECTIVITY = LIST returns the adjacency list in the variable LIST. The subscripts of the nodes adjacent to X[i] and Y[i] are contained in the array: LIST[LIST[i] : LIST[i+1]-1] DEGREES Set this keyword to indicate that the X and Y arguments contain longitude and latitude coordinates specified in degrees. This keyword is only effective if the SPHERE keyword is also set. If DEGREES is not set, X and Y are assumed to be specified in radians when a spherical triangulation is performed. FVALUE Set this keyword to a named variable that contains sample values for each longitude/latitude point in a spherical triangulation. On output, the elements of FVALUE are rearranged to correspond to the new ordering of X and Y (as described in the SPHERE keyword, below). This reordered array can be passed to TRIGRID to complete the interpolation. REPEATS Set this keyword to a named variable to return a (2, n) list of the indices of duplicated points. That is, for each i, X[REPEATS[0,i]] = X[REPEATS[1,i]] and Y[REPEATS[0,i]] = Y[REPEATS[1,i]] SPHERE Set this keyword to a named variable in which the results from a spherical triangulation are returned. This result is a structure that can be passed to TRIGRID to perform spherical gridding. The structure contains the 3D Cartesian locations sample points and the adjacency list that describes the triangulation. When spherical triangulation is performed, X and Y are interpreted as longitude and latitude, in either degrees or radians (see the DEGREE keyword, above). Also, the order of the elements within the X and Y parameters is rearranged (see the FVALUE keyword, above). Example For a examples using the TRIANGULATE routine, see the TRIGRID function. See Also SPH_SCAT, TRIGRID TRIGRID [Previous Routine] [Next Routine] [List of Routines] NAME: TRIGRID Given data points defined by the parameters X, Y, and Z and a triangulation of the planar set of points determined by X and Y, the TRIGRID function returns a regular grid of interpolated Z values. Linear or smooth quintic polynomial interpolation can be selected. Extrapolation for gridpoints outside of the triangulation area is also an option. The resulting grid is a two-dimensional array of the same data type as Z, with user-specified bounds and spacing. An input triangulation can be constructed using the procedure TRIANGULATE. Together, the TRIANGULATE procedure and the TRIGRID function constitute IDL's solution to the problem of irregularly-gridded data, including spherical gridding. Syntax Result = TRIGRID( X, Y, Z, Triangles [, GS, Limits] ) For spherical gridding: Result = TRIGRID( F , GS, Limits, SPHERE=S ) Keywords: [, /DEGREES] [, EXTRAPOLATE=array | , /QUINTIC] [, INPUT=variable] [, MAX_VALUE=value] [, MIN_VALUE=value] [, MISSING=value] [, NX=value] [, NY=value] [, SPHERE=variable] [, XGRID=variable] [, YGRID=variable] [, XOUT=vector, YOUT=vector] Arguments X, Y, Z Input arrays of X, Y, and Z coordinates of data points. Integer, long, double-precision and floating-point values are allowed. In addition, Z can be a complex array. All three arrays must have the same number of elements. F When performing a spherical gridding, this argument should be the named variable that contains the rearranged sample values that were returned by TRIANGULATE's FVALUE keyword. Triangles A longword array of the form output by TRIANGULATE. That is, Triangles has the dimensions (3, number of triangles) and, for each i, Triangles[0,i], Triangles[1,i], and Triangles[2,i] are the indices of the vertices of the i-th triangle. GS If present, GS should be a two-element vector [XS, YS], where XS is the horizontal spacing between grid points and YS is the vertical spacing. The default is based on the extents of X and Y. If the grid starts at X value x0 and ends at x1,then the horizontal spacing is (x1- x0)/50 The default for YS is computed in the same way. Since the default grid spacing divides each axis into 50 intervals and produces 51 samples, TRIGRID returns a grid with dimensions (51, 51). If the NX or NY keywords are set to specify the output grid dimensions, either or both of the values of GS may be set to 0. In this case, the grid spacing is computed as the respective range divided by the dimension minus one: (x1- x0)/(NX-1) and (y1- y0)/(NY-1) For spherical gridding, GS is assumed to be specified in radians, unless the DEGREES keyword is set. Limits If present, Limits should be a four-element vector [x0, y0, x1, y1] that specifies the data range to be gridded (x0 and y0 are the lower X and Y data limits, and x1 and y1 are the upper limits). The default for Limits is: [MIN(X), MIN(Y), MAX(X), MAX(Y)] If the NX or NY keywords are not specified, the size of the grid produced is specified by the value of Limits. If the NX or NY keywords are set to specify the output grid dimensions, a grid of the specified size will be used regardless of the value of Limits. Keywords DEGREES For a spherical gridding, set this keyword to indicate that the grid spacing (the GS argument) is specified in degrees rather than radians. EXTRAPOLATE Set this keyword equal to an array of boundary node indices (as returned by the optional parameter B of the TRIANGULATE procedure) to extrapolate to grid points outside the triangulation. The extrapolation is not smooth, but should give acceptable results in most cases. Setting this keyword sets the quintic interpolation mode, as if the QUINTIC keyword has been specified. INPUT Set this keyword to a named variable (which must be an array of the appropriate size to hold the output from TRIGRID) in which the results of the gridding are returned. This keyword is provided to make it easy and memory-efficient to perform multiple calls to TRIGRID. The interpolates within each triangle overwrite the array and the array is not initialized. MAX_VALUE Set this keyword to a value that represents the maximum Z value to be gridded. Data larger than this value are treated as missing data and are not gridded. MIN_VALUE Set this keyword to a value that represents the minimum Z value to be gridded. Data smaller than this value are treated as missing data and are not gridded. MISSING The Z value to be used for grid points that lie outside the triangles in Triangles. The default is 0. This keyword also applies to data points outside the range specified by MIN_VALUE and MAX_VALUE. Note Letting MISSING default to 0 does not always produce the same result as explicitly setting it to 0. For example, if you specify INPUT and not EXTRAPOLATE, letting MISSING default to 0 will result in the INPUT values being used for data outside the Triangles; explicitly setting MISSSING to 0 will result in 0 being used for the data outside the Triangles. NX The output grid size in the x direction. The default value is 51. NY The output grid size in the y direction. The default value is 51. QUINTIC If QUINTIC is set, smooth interpolation is performed using Akima's quintic polynomials from "A Method of Bivariate Interpolation and Smooth Surface Fitting for Irregularly Distributed Data Points" in ACM Transactions on Mathematical Software, 4, 148-159. The default method is linear interpolation. Derivatives are estimated by Renka's global method in "A Triangle-Based C1 Interpolation Method" in Rocky Mountain Journal of Mathematics, vol. 14, no. 1, 1984. QUINTIC is not available for complex data values. Setting the EXTRAPOLATE keyword implies the use of quintic interpolation; it is not necessary to specify both. SPHERE For a spherical gridding, set this keyword to the named variable that contains the results of the spherical triangulation returned by TRIANGULATE's SPHERE keyword. XGRID Set this keyword to a named variable that will contain a vector of X values for the output grid. XOUT Set this keyword to a vector specifying the output grid X values. If this keyword is supplied, the GS and Limits arguments are ignored. Use this keyword to specify irregularly spaced rectangular output grids. If XOUT is specified, YOUT must also be specified. If keyword NX is also supplied then only the first NX points of XOUT will be used. YGRID Set this keyword to a named variable that will contain a vector of Y values for the output grid. The following table shows the interrelationships between the keywords EXATRAPOLATE, INPUT, MAX_VALUE, MIN_VALUE, MISSING, and QUINTIC. Beyond INPUT EXTRAPOLATE MISSING Not in Triangles MIN_VALUE, MAX_VALUE no no no uses 0 uses 0 no no yes uses MISSING uses MISSING no yes no EXTRAPOLATEs uses 0 no yes yes EXTRAPOLATEs uses MISSING yes no no uses INPUT uses INPUT yes no yes uses MISSING uses MISSING yes yes no EXTRAPOLATEs uses INPUT yes yes yes EXTRAPOLATEs uses MISSING Table 90: Keyword Interrelationships for the TRIGRID function YOUT Set this keyword to a vector specifying the output grid Y values. If this keyword is supplied, the GS and Limits arguments are ignored. Use this keyword to specify irregularly spaced rectangular output grids. If keyword NY is also supplied then only the first NY points of YOUT will be used. Examples Example 1 This example creates and displays a 50 point random normal distribution. The random points are then triangulated, with the triangulation displayed. Next, the interpolated surface is computed and displayed using linear and quintic interpolation. Finally, the smooth extrapolated surface is generated and shown. ; Make 50 normal x, y points: x = RANDOMN(seed, 50) y = RANDOMN(seed, 50) ; Make the Gaussian: z = EXP(-(x^2 + y^2)) ; Show points: PLOT, x, y, psym=1 ; Obtain triangulation: TRIANGULATE, x, y, tr, b ; Show the triangles: FOR i=0, N_ELEMENTS(tr)/3-1 DO BEGIN & $ ; Subscripts of vertices [0,1,2,0]: t = [tr[*,i], tr[0,i]] & $ ; Connect triangles: PLOTS, x[t], y[t] & $ ENDFOR ; Show linear surface: SURFACE, TRIGRID(x, y, z, tr) ; Show smooth quintic surface: SURFACE, TRIGRID(x, y, z, tr, /QUINTIC) ; Show smooth extrapolated surface: SURFACE, TRIGRID(x, y, z, tr, EXTRA = b) ; Output grid size is 12 x 24: SURFACE, TRIGRID(X, Y, Z, Tr, NX=12, NY=24) ; Output grid size is 20 x 11. The X grid is ; [0, .1, .2, ..., 19 * .1 = 1.9]. The Y grid goes from 0 to 1: SURFACE, TRIGRID(X, Y, Z, Tr, [.1, .1], NX=20) ; Output size is 20 x 40. The range of the grid in X and Y is ; specified by the Limits parameter. Grid spacing in X is ; [5-0]/(20-1) = 0.263. Grid spacing in Y is (4-0)/(40-1) = 0.128: SURFACE, TRIGRID(X, Y, Z, Tr, [0,0], [0,0,5,4],NX=20, NY=40) Example 2 This example shows how to perform spherical gridding: ; Create some random longitude points: lon = RANDOMU(seed, 50) * 360. - 180. ; Create some random latitude points: lat = RANDOMU(seed, 50) * 180. - 90. ; Make a fake function value to be passed to FVALUE. The system ; variable !DTOR contains the conversion value for degrees to ; radians. f = SIN(lon * !DTOR)^2 * COS(lat * !DTOR) ; Perform a spherical triangulation: TRIANGULATE, lon, lat, tr, $ SPHERE=s, FVALUE=f, /DEGREES ; Perform a spherical triangulation using the values returned from ; TRIANGULATE. The result, r, is a 180 by 91 element array: r=TRIGRID(f, SPHERE=s, [2.,2.],$ [-180.,-90.,178.,90.], /DEGREES) Example 3 This example demonstrates the use of the INPUT keyword: ; Make 50 normal x, y points: x = RANDOMN(seed, 50) y = RANDOMN(seed, 50) ; Make the Gaussian: z = EXP(-(x^2 + y^2)) ; Show points: PLOT, x, y, psym=1 ; Obtain triangulation: TRIANGULATE, x, y, tr, b ;Show the triangles. FOR i=0, N_ELEMENTS(tr)/3-1 DO BEGIN $ ; Subscripts of vertices [0,1,2,0]: t = [tr[*,i], tr[0,i]] & $ ; Connect triangles: PLOTS, x[t], y[t] ENDFOR ; The default size for the return value of trigrid. xtemp should be ; the same type as Z. xtemp provides temporary space for trigrid: xtemp=FLTARR(51,51) xtemp = TRIGRID(x, y, z, INPUT = xtemp, tr) ; Show linear surface: SURFACE, xtemp in=' ' READ,"Press enter",in xtemp = TRIGRID(x, y, z, tr, INPUT = xtemp, /QUINTIC) ; Show smooth quintic surface: SURFACE,xtemp in=' ' READ,"Press enter",in xtemp = TRIGRID(x, y, z, tr, INPUT = xtemp, EXTRA = b) ; Show smooth extrapolated surface: SURFACE,xtemp in=' ' READ,"Press enter",in END See Also SPH_SCAT, TRIANGULATE TRIQL [Previous Routine] [Next Routine] [List of Routines] NAME: TRIQL The TRIQL procedure uses the QL algorithm with implicit shifts to determine the eigenvalues and eigenvectors of a real, symmetric, tridiagonal array. The routine TRIRED can be used to reduce a real, symmetric array to the tridiagonal form suitable for input to this procedure. TRIQL is based on the routine tqli described in section 11.3 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press, and is used by permission. Syntax TRIQL, D, E, A [, /DOUBLE] Arguments D On input, this argument should be an n-element vector containing the diagonal elements of the array being analyzed. On output, D contains the eigenvalues. E An n-element vector containing the off-diagonal elements of the array. E0 is arbitrary. On output, this parameter is destroyed. A A named variable that returns the n eigenvectors. If the eigenvectors of a tridiagonal array are desired, A should be input as an identity array. If the eigenvectors of an array that has been reduced by TRIRED are desired, A is input as the array Q output by TRIRED. Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. Example To compute eigenvalues and eigenvectors of a real, symmetric, tridiagonal array, begin with an array A representing a symmetric array: ; Create the array A: A = [[ 3.0, 1.0, -4.0], $ [ 1.0, 3.0, -4.0], $ [-4.0, -4.0, 8.0]] ; Compute the tridiagonal form of A: TRIRED, A, D, E ; Compute the eigenvalues (returned in vector D) and the ; eigenvectors (returned in the rows of the array A): TRIQL, D, E, A ; Print eigenvalues: PRINT, 'Eigenvalues:' PRINT, D ; Print eigenvectors: PRINT, 'Eigenvectors:' PRINT, A IDL prints: Eigenvalues: 2.00000 4.76837e-7 12.0000 Eigenvectors: 0.707107 -0.707107 0.00000 -0.577350 -0.577350 -0.577350 -0.408248 -0.408248 0.816497 The exact eigenvalues are: [2.0, 0.0, 12.0] The exact eigenvectors are: [ 1.0/sqrt(2.0), -1.0/sqrt(2.0), 0.0/sqrt(2.0)], [-1.0/sqrt(3.0), -1.0/sqrt(3.0), -1.0/sqrt(3.0)], [-1.0/sqrt(6.0), -1.0/sqrt(6.0), 2.0/sqrt(6.0)] See Also EIGENVEC, ELMHES, HQR, TRIRED TRIRED [Previous Routine] [Next Routine] [List of Routines] NAME: TRIRED The TRIRED procedure uses Householder's method to reduce a real, symmetric array to tridiagonal form. TRIRED is based on the routine tred2 described in section 11.2 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press, and is used by permission. Syntax TRIRED, A, D, E [, /DOUBLE] Arguments A An n by n real, symmetric array that is replaced, on exit, by the orthogonal array Q effecting the transformation. The routine TRIQL can use this result to find the eigenvectors of the array A. D An n-element output vector containing the diagonal elements of the tridiagonal array. E An n-element output vector containing the off-diagonal elements. Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. Example See the description of TRIQL for an example using this function. See Also EIGENVEC, ELMHES, HQR, TRIQL TRISOL [Previous Routine] [Next Routine] [List of Routines] NAME: TRISOL The TRISOL function solves tridiagonal systems of linear equations that have the form: ATU = R Note Because IDL subscripts are in column-row order, the equation above is written ATU = R rather than AU = R. The result U is a vector of length n whose type is identical to A. TRISOL is based on the routine tridag described in section 2.4 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press, and is used by permission. Syntax Result = TRISOL( A, B, C, R [, /DOUBLE] ) Arguments A A vector of length n containing the n-1 sub-diagonal elements of AT. The first element of A, A0, is ignored. B An n-element vector containing the main diagonal elements of AT. C An n-element vector containing the n-1 super-diagonal elements of AT. The last element of C, Cn-1, is ignored. R An n-element vector containing the right hand side of the linear system ATU = R. Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. Example To solve a tridiagonal linear system, begin with an array representing a real tridiagonal linear system. (Note that only three vectors need be specified; there is no need to enter the entire array shown.) ­4.0 1.0 0.0 0.0 2.0 ­4.0 1.0 0.0 0.0 2.0 ­4.0 1.0 0.0 0.0 2.0 ­4.0 ; Define a vector A containing the sub-diagonal elements with a ; leading 0.0 element: A = [0.0, 2.0, 2.0, 2.0] ; Define B containing the main diagonal elements: B = [-4.0, -4.0, -4.0, -4.0] ; Define C containing the super-diagonal elements with a trailing ; 0.0 element: C = [1.0, 1.0, 1.0, 0.0] ; Define the right-hand side vector: R = [6.0, -8.0, -5.0, 8.0] ; Compute the solution and print: result = TRISOL(A, B, C, R) PRINT, result IDL prints: -1.00000 2.00000 2.00000 -1.00000 The exact solution vector is [-1.0, 2.0, 2.0, -1.0]. See Also CRAMER, GS_ITER, LU_COMPLEX, CHOLSOL, LUSOL, SVSOL, TRISOL TRNLOG [Previous Routine] [Next Routine] [List of Routines] NAME: TRNLOG The TRNLOG function searches the VMS logical name tables for a specified logical name and returns the equivalence string(s) in an IDL variable. TRNLOG is available only under VMS. TRNLOG also returns the VMS status code associated with the translation as a longword value. As with all VMS status codes, success is indicated by an odd value (least significant bit is set) and failure by an even value. Syntax Result = TRNLOG( Lognam, Value [, ACMODE={0 | 1 | 2 | 3}] [, /FULL_TRANSLATION] [, /ISSUE_ERROR] [, RESULT_ACMODE=variable] [, RESULT_TABLE=variable] [, TABLE=string] ) Arguments Lognam A scalar string containing the name of the logical to be translated. Value A named variable into which the equivalence string is placed. If Lognam has more than one equivalence string, the first one is used. The FULL_TRANSLATION keyword can be used to obtain all equivalence strings. Keywords ACMODE Set this keyword to a value specifying the access mode to be used in the translation. Valid values are: * 0 = Kernal * 1 = Executive * 2 = Supervisor * 3 = User When you specify the ACMODE keyword, all names at access modes less privileged than the specified mode are ignored. If you do not specify ACMODE, the translation proceeds without regard to access mode. However, the search proceeds from the outermost (User) to the innermost (Kernal) mode. Thus, if two logical names with the same name but different access modes exist in the same table, the name with the outermost access mode is used. FULL_TRANSLATION Set this keyword to obtain the full set of equivalence strings for Lognam. By default, when translating a multivalued logical name, Value only receives the first equivalence string as a scalar value. When this keyword is set, Value instead returns a string array. Each element of this array contains one of the equivalence strings. For example, under recent versions of VMS, the SYS$SYSROOT logical can have multiple values. To see these values from within IDL, enter: ; Translate the logical: ret = TRNLOG('SYS$SYSROOT', trans, /FULL, /ISSUE_ERROR) ; View the equivalence strings: PRINT, trans ISSUE_ERROR Set this keyword to issue an error message if the translation fails. Normally, no error is issued and the user must examine the return value to determine if the operation failed. RESULT_ACMODE If present, this keyword specifies a named variable in which to place the access mode of the translated logical. The access modes are summarized above. RESULT_TABLE If present, this keyword specifies a named variable. The name of the logical table containing the translated logical is placed in this variable as a scalar string. TABLE A scalar string giving the name of the logical table in which to search for Lognam. If TABLE is not specified, the standard VMS logical tables are searched until a match is found, starting with LNM$PROCESS_TABLE and ending with LNM$SYSTEM_TABLE. See Also GETENV TS_COEF [Previous Routine] [Next Routine] [List of Routines] NAME: TS_COEF The TS_COEF function computes the coefficients 1, 2, ... , P used in a Pth order autoregressive time-series forecasting model. The result is a P-element vector whose type is identical to X. This routine is written in the IDL language. Its source code can be found in the file ts_coef.pro in the lib subdirectory of the IDL distribution. Syntax Result = TS_COEF( X, P [, /DOUBLE] [, MSE=variable] ) Arguments X An n-element single- or double-precision floating-point vector containing time-series samples. P An integer or long integer scalar that specifies the number of coefficients to be computed. Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. MSE Set this keyword to a named variable that will contain the mean square error of the Pth order autoregressive model. Example ; Define an n-element vector of time-series samples: X = [6.63, 6.59, 6.46, 6.49, 6.45, 6.41, 6.38, 6.26, 6.09, 5.99, $ 5.92, 5.93, 5.83, 5.82, 5.95, 5.91, 5.81, 5.64, 5.51, 5.31, $ 5.36, 5.17, 5.07, 4.97, 5.00, 5.01, 4.85, 4.79, 4.73, 4.76] ; Compute the coefficients of a 5th order autoregressive model: PRINT, TS_COEF(X, 5) IDL prints: 1.30168 -0.111783 -0.224527 0.267629 -0.233363 See Also TS_FCAST TS_DIFF [Previous Routine] [Next Routine] [List of Routines] NAME: TS_DIFF The TS_DIFF function recursively computes the forward differences of an n-element time-series k times. The result is an n-element differenced time-series with its last k elements as zeros. This routine is written in the IDL language. Its source code can be found in the file ts_diff.pro in the lib subdirectory of the IDL distribution. Syntax Result = TS_DIFF( X, K [, /DOUBLE] ) Arguments X An n-element integer, single- or double-precision floating-point vector containing time-series samples. K A positive integer or long integer scalar that specifies the number of times X is to be differenced. K must be in the interval [1, N_ELEMENTS(X) - 1]. Keywords DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. Example ; Define an n-element vector of time-series samples: X = [389, 345, 303, 362, 412, 356, 325, 375, $ 410, 350, 310, 388, 399, 362, 325, 382, $ 399, 382, 318, 385, 437, 357, 310, 391] ; Compute the second forward differences of X: PRINT, TS_DIFF(X, 2) IDL prints: 2 101 -9 -106 25 81 -15 -95 20 118 -67 -48 0 94 -40 -34 -47 131 -15 -132 33 128 0 0 See Also SMOOTH, TS_FCAST TS_FCAST [Previous Routine] [Next Routine] [List of Routines] NAME: TS_FCAST The TS_FCAST function computes future or past values of a stationary time-series using a Pth order autoregressive model. The result is an Nvalues-element vector whose type is identical to X. A Pth order autoregressive model relates a forecasted value xt of the time series X = [x0, x1, x2, ... , xt-1], as a linear combination of P past values. xt = 1xt ­ 1 + 2xt ­ 2 + ... + Pxt ­ P + wt The coefficients 1, 2, ... , P are calculated such that they minimize the uncorrelated random error terms, wt. This routine is written in the IDL language. Its source code can be found in the file ts_fcast.pro in the lib subdirectory of the IDL distribution. Syntax Result = TS_FCAST( X, P, Nvalues [, /BACKCAST] [, /DOUBLE] ) Arguments X An n-element single- or double-precision floating-point vector containing time-series samples. P An integer or long integer scalar that specifies the number of actual time-series values to be used in the forecast. In general, a larger number of values results in a more accurate forecast. Nvalues An integer or long integer scalar that specifies the number of future or past values to be computed. Keywords BACKCAST Set this keyword to produce past values (backward forecasts or "backcasts") DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. Example ; Define an n-element vector of time-series samples: X = [6.63, 6.59, 6.46, 6.49, 6.45, 6.41, 6.38, 6.26, 6.09, 5.99, $ 5.92, 5.93, 5.83, 5.82, 5.95, 5.91, 5.81, 5.64, 5.51, 5.31, $ 5.36, 5.17, 5.07, 4.97, 5.00, 5.01, 4.85, 4.79, 4.73, 4.76] ; Compute and print five future values of the time-series using ten ; time-series values: PRINT, TS_FCAST(X, 10, 5) ; Compute five past values of the time-series using ten time-series ;values: PRINT, TS_FCAST(X, 10, 5, /BACKCAST) IDL prints: 4.65870 4.58380 4.50030 4.48828 4.46971 6.94862 6.91103 6.86297 6.77826 6.70282 See Also A_CORRELATE, COMFIT, CURVEFIT, SMOOTH, TS_COEF, TS_DIFF TS_SMOOTH [Previous Routine] [Next Routine] [List of Routines] NAME: TS_SMOOTH The TS_SMOOTH function computes central, backward, or forward moving averages of an n-element time-series. Autoregressive forecasting and backcasting are used to extrapolate the time-series and compute a moving average for each point. The result is an n-element vector of the same data type as the input vector. Note that central moving averages require Nvalues/2 forecasts and Nvalues/2 backcasts. Backward moving averages require Nvalues-1 backcasts. Forward moving averages require Nvalues-1 forecasts. This routine is written in the IDL language. Its source code can be found in the file ts_smooth.pro in the lib subdirectory of the IDL distribution. Syntax Result = TS_SMOOTH( X, Nvalues [, /BACKWARD] [, /DOUBLE] [, /FORWARD] [, ORDER=value] ) Arguments X An n-element single- or double-precision floating-point vector containing time-series samples. Note that n must be greater than or equal to 11. Nvalues A scalar of type integer or long integer that specifies the number of time-series values used to compute each moving-average. If central-moving averages are computed (the default), this parameter must be an odd integer greater than or equal to three. Keywords BACKWARD Set this keyword to compute backward-moving averages. If BACKWARD is set, the Nvalues argument must be an integer greater than one. DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. FORWARD Set this keyword to compute forward-moving averages. If FORWARD is set, the Nvalues argument must be an integer greater than one. ORDER An integer or long-integer scalar that specifies the order of the autoregressive model used to compute the forecasts and backcasts of the time-series. By default, a time- series with a length between 11 and 219 elements will use an autoregressive model with an order of 10. A time-series with a length greater than 219 will use an autoregressive model with an order equal to 5% of its length. The ORDER keyword is used to override this default. Example ; Define an n-element vector of time-series samples: X = [6.63, 6.59, 6.46, 6.49, 6.45, 6.41, 6.38, 6.26, 6.09, 5.99,$ 5.92, 5.93, 5.83, 5.82, 5.95, 5.91, 5.81, 5.64, 5.51, 5.31,$ 5.36, 5.17, 5.07, 4.97, 5.00, 5.01, 4.85, 4.79, 4.73, 4.76] ; Compute the 11-point central-moving-averages of the time-series: PRINT, TS_SMOOTH(X, 11) IDL prints: 6.65761 6.60592 6.54673 6.47646 6.40480 6.33364 6.27000 6.20091 6.14273 6.09364 6.04455 5.99000 5.92273 5.85455 5.78364 5.72636 5.65818 5.58000 5.50182 5.42727 5.34182 5.24545 5.15273 5.07000 5.00182 4.94261 4.87205 4.81116 4.75828 4.71280 See Also SMOOTH, TS_DIFF, TS_FCAST TV [Previous Routine] [Next Routine] [List of Routines] NAME: TV The TV procedure displays images on the image display without scaling the intensity. To display an image with scaling, use the TVSCL procedure. Note To display a TrueColor image (an image with 16, 24, or 32 bits per pixel) you must specify the TRUE keyword. While the TV procedure does not scale the intensity of an image, it does convert the input image data to byte type. Values outside the range [0,255] are "wrapped" during the conversion. In addition, for displays with less than 256 colors, elements of the input image with values between !D.TABLE_SIZE and 255 will be displayed using the color index !D.TABLE_SIZE-1. Syntax TV, Image [, Position] or TV, Image [, X, Y [, Channel]] Keywords: [, /CENTIMETERS | , /INCHES] [, CHANNEL=value] [, /ORDER] [, TRUE={1 | 2 | 3}] [, /WORDS] [, XSIZE=value] [, YSIZE=value] [, /DATA | , /DEVICE | , /NORMAL] [, /T3D | Z=value] Arguments Image A vector or two-dimensional array to be displayed as an image. If this argument is not already of byte type, it is converted prior to use. X, Y If X and Y are present, they specify the lower-left coordinate of the displayed image, relative to the lower-left corner of the screen. Position An integer specifying the position for Image within the graphics window. Image positions run from the top left of the screen to the bottom right. If a position number is used instead of X and Y, the position of the image is calculated from the dimensions of the image as follows (integer arithmetic is used). Xsize, Ysize = Size of display or window Xdim, Ydim = Dimensions of image to be displayed N Xsize x = ------------- = Images across screen Ydim X = XdimPositionmoduloN = Starting X x Y = Ysize ­ Ydim 1 Position + ------------------- = Starting Y Nx For example, when displaying 128 by 128 images on a 512 by 512 display, the position numbers run from 0 to 15 as follows: 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 Note When using a device with scalable pixels (e.g., PostScript), the XSIZE and YSIZE keywords should also be used. Channel The memory channel to be written. It is assumed to be zero if not specified. This parameter is ignored on display systems that have only one memory channel. When using a "decomposed" display system, the red channel is 1, the green channel is 2, and the blue channel is 3. Channel 0 indicates all channels. Keywords CENTIMETERS Set this keyword to indicate that the X, Y, Xsize, Ysize, and Z arguments are given in centimeters from the origin. This system is useful when dealing with devices, such as PostScript printers, that do not provide a direct relationship between image pixels and the size of the resulting image. CHANNEL The memory channel to be written to. The CHANNEL keyword is identical to the optional Channel argument. INCHES Set this keyword to indicate that all position and size values are given in inches from the origin. This system is useful when dealing with devices, such as PostScript printers, that do not provide a direct relationship between image pixels and the size of the resulting image. ORDER If specified, ORDER overrides the current setting of the !ORDER system variable for the current image only. If set, the image is drawn from the top down instead of the normal bottom up. TRUE Set this keyword to a nonzero value to indicate that a TrueColor (16-, 24-, or 32-bit) image is to be displayed. The value assigned to TRUE specifies the index of the dimension over which color is interleaved. The image parameter must have three dimensions, one of which must be equal to three. For example, set TRUE to 1 to display an image that is pixel interleaved and has dimensions of (3, m, n). Specify 2 for row-interleaved images, of size (m, 3, n), and 3 for band-interleaved images of the form (m, n, 3). See "TrueColor Images" on page 2373 for an example using this keyword to write 24-bit images to the PostScript device. WORDS Set this keyword to indicate that words (short integers) instead of 8-bit bytes are to be transferred to the device. This keyword is valid only when using devices that can transfer 16-bit pixels. The normal transfer uses 8-bit pixels. If this keyword is set, the Image parameter is converted to short integer type, if necessary, and then written to the display. XSIZE The width of the resulting image. On devices with scalable pixel size (such as PostScript), if XSIZE is specified the image will be scaled to fit the specified width. If neither XSIZE nor YSIZE is specified, the image will be scaled to fill the plotting area, while preserving the image's aspect ratio. This keyword is ignored by pixel- based devices that are unable to change the size of their pixels. YSIZE The height of the resulting image. On devices with scalable pixel size (such as PostScript), if YSIZE is specified the image will be scaled to fit the specified height. If neither XSIZE nor YSIZE is specified, the image will be scaled to fill the plotting area, while preserving the image's aspect ratio. This keyword is ignored by pixel- based devices that are unable to change the size of their pixels. Graphics Keywords Accepted See Appendix C, "Graphics Keywords" for the description of graphics and plotting keywords not listed above. CHANNEL, DATA, DEVICE, NORMAL, T3D, Z. Example ; Create and display a simple image: D = BYTSCL(DIST(256)) & TV, D ; Erase the screen: ERASE ; Use the position parameter to display a number of images in the ; same window. ; Display the image in the upper left corner. TV, D, 0 ; Display another copy of the image in the next position: TV, D, 1 See Also ERASE, SLIDE_IMAGE, TVRD, TVSCL, WIDGET_DRAW, WINDOW TVCRS [Previous Routine] [Next Routine] [List of Routines] NAME: TVCRS The TVCRS procedure manipulates the display device cursor. The initial state of the cursor is device dependent. Call TVCRS with one argument to enable or disable the cursor. Call TVCRS with two parameters to enable the cursor and place it on pixel location (X, Y). Note Under Macintosh, the cursor cannot be positioned from an IDL program using the TVCRS procedure. The Macintosh interface does not allow the cursor to be positioned by any device except the mouse. Syntax TVCRS [, ON_OFF] or TVCRS [, X, Y] Keywords: [, /CENTIMETERS | , /INCHES] [, /HIDE_CURSOR] [, /DATA | , /DEVICE | , /NORMAL] [, /T3D | Z=value] Arguments ON_OFF This argument specifies whether the cursor should be on or off. If this argument is present and nonzero, the cursor is enabled. If ON_OFF is zero or no parameters are specified, the cursor is turned off. X The column to which the cursor is set. Y The row to which the cursor is set. Keywords CENTIMETERS Set this keyword to cause X and Y to be interpreted as centimeters, based on the current device resolution. INCHES Set this keyword to cause X and Y to be interpreted as inches, based on the current device resolution. HIDE_CURSOR By default, disabling the cursor works differently for window systems than for other devices. For window systems, the cursor is restored to the standard cursor used for non-IDL windows (and remains visible), while for other devices it is completely blanked out. If the HIDE keyword is set, disabling the cursor causes it to always be blanked out. Graphics Keywords Accepted See Appendix C, "Graphics Keywords" for the description of graphics and plotting keywords not listed above. DATA, DEVICE, NORMAL, T3D, Z. Example To enable the graphics cursor and position it at device coordinate (100, 100), enter: TVCRS, 100, 100 To position the cursor at data coordinate (0.5, 3.2), enter: TVCRS, 0.5, 3.2, /DATA See Also CURSOR, RDPIX TVLCT [Previous Routine] [Next Routine] [List of Routines] NAME: TVLCT The TVLCT procedure loads the display color translation tables from the specified variables. Although IDL uses the RGB color system internally, color tables can be specified to TVLCT using any of the following color systems: RGB (Red, Green, Blue), HLS (Hue, Lightness, Saturation), and HSV (Hue, Saturation, Value). Alpha values may also be used when using the second form of the command. The type and meaning of each argument is dependent upon the color system selected, as described below. Color arguments can be either scalar or vector expressions. If no color-system keywords are present, the RGB color system is used. See Using IDL Chapter 14, "Image Display Routines" for a more complete explanation of color systems. Syntax TVLCT, V1, V2, V3 [, Start] [, /GET] [, /HLS | , /HSV] or TVLCT, V [, Start] [, /GET] [, /HLS | , /HSV] Arguments TVLCT will accept either three n-element vectors (V1, V2, and V3) or a single n-by-3 array (V) as an argument. The vectors (or columns of the array) have different meanings depending on the color system chosen. If an array V is specified, V[*,0] is the same as V1, V[*,1] is the same as V2, V[*,2] is the same as V3. In the description below, we assume that three vectors, V1, V2, and V3 are specified. The V1, V2, and V3 arguments have different meanings depending upon which color system they represent. R, G, B Color System The parameters V1, V2, and V3 contain the Red, Green, and Blue values, respectively. Values are interpreted as integers in the range 0 (lowest intensity) to 255 (highest intensity). The parameters can be scalars or vectors of up to 256 elements. By default, the three arguments are assumed to be R, G, and B values. H, L, S Color System Parameters V1, V2, and V3 contain the Hue, Lightness, and Saturation values respectively. All parameters are floating-point. Hue is expressed in degrees and is reduced modulo 360. V2 (lightness) and V3 (saturation) and can range from 0 to 1.0. Set the HLS keyword to have the arguments interpreted this way. H, S, V Color System Parameters V1, V2, and V3 contain values for Hue, Saturation, and Value (similar to intensity). All parameters are floating-point. Hue is in degrees. The Saturation and Value can range from 0 to 1.0. Set the HSV keyword to have the arguments interpreted this way. Start An integer value that specifies the starting point in the color translation table into which the color intensities are loaded. If this argument is not specified, a value of zero is used, causing the tables to be loaded starting at the first element of the translation tables. Keywords GET Set this keyword to return the RGB values from the internal color tables into the V1, V2, and V3 parameters. For example, the statements: TVLCT, H, S, V, /HSV TVLCT, R, G, B, /GET load a color table based in the HSV system, and then read the equivalent RGB values into the variables R, G, and B. HLS Set this keyword to indicate that the parameters specify color using the HLS color system. HSV Set this keyword to indicate that the parameters specify color using the HSV color system. Example ; Create a set of R, G, and B colormap vectors: R = BYTSCL(SIN(FINDGEN(256))) G = BYTSCL(COS(FINDGEN(256))) B = BINDGEN(256) ; Load these vectors into the color table: TVLCT, R, G, B ; Display an image to see the effect of the new color table: TVSCL, DIST(400) See Also LOADCT, XLOADCT, XPALETTE TVRD [Previous Routine] [Next Routine] [List of Routines] NAME: TVRD The TVRD function returns the contents of the specified rectangular portion of the current graphics window or device. (X0, Y0) is the coordinate of the lower left corner of the area to be read and Nx, Ny is the size of the rectangle in columns and rows. The result is a byte array of dimensions Nx by Ny. All parameters are optional. If no arguments are supplied, the entire display device area is read. Important Note about TVRD and Backing Store On some systems, when backing store is provided by the window system (the RETAIN keyword to DEVICE or WINDOW is set to 1), reading data from a window using TVRD may cause unexpected results. For example, data may be improperly read from the window even when the image displayed on screen is correct. Having IDL provide the backing store (set the RETAIN keyword to 2) ensures that the window contents will be read properly. More detailed notes about TVRD and the X Window system can be found below in "Unexpected Results Using TVRD with X Windows" on page 1465. Syntax Result = TVRD( [X0 [, Y0 [, Nx [, Ny [, Channel]]]]] [, CHANNEL=value] [, /ORDER] [, TRUE={1 | 2 | 3}] [, /WORDS] ) Arguments X0 The starting column of data to read. The default is 0. Y0 The starting row of data to read. The default is 0. Nx The number of columns to read. The default is the width of the display device or window less X0. Ny The number of rows to read. The default is the height of the display device or window less Y0. Channel The memory channel to be read. If not specified, this argument is assumed to be zero. This parameter is ignored on display systems that have only one memory channel. Keywords CHANNEL The memory channel to be read. The CHANNEL keyword is identical to the optional Channel argument. Note: if the display is a 24-bit display, and both the CHANNEL and TRUE parameters are absent, the maximum RGB value in each pixel is returned. ORDER Set this keyword to override the current setting of the !ORDER system variable for the current image only. If set, it causes the image to be read from the top down instead of the normal bottom up. TRUE If this keyword is present, it indicates that a TrueColor image is to be read, if the display is capable. The value assigned to TRUE specifies the index of the dimension over which color is interleaved. The result is an (3, nx, ny) pixel-interleaved array if TRUE is 1; or an (nx, 3, ny) line-interleaved array if TRUE is 2; or an (nx, ny, 3) image-interleaved array if TRUE is 3. WORDS Set this keyword to indicate that words are to be transferred from the device. This keyword is valid only when using devices that can transfer 16-bit pixels. The normal transfer uses 8-bit pixels. If this keyword is set, the function result is an integer array. Unexpected Results Using TVRD with X Windows When using TVRD with the X Windows graphics device, there are two unexpected behaviors that can be confusing to users: * When reading from a window that is obscured by another window (i.e., the target window has another window "on top" or "in front" of it), TVRD may return the contents of the window in front as part of the image contained in the target window. * When reading from an iconified window, the X server may return a stream of "BadMatch" protocol events. IDL uses the Xlib function XGetSubImage() to implement TVRD. The following quote is from the documentation for XGetSubImage() found in The X Window System by Robert W. Scheifler and James Gettys, Second Edition, page 174. It explains the reasons for the behaviors described above: "If the drawable is a window, the window must be viewable, and it must be the case that if there were no... overlapping windows, the specified rectangle of the window would be fully visible on the screen, ... or a BadMatch error results. If the window has backing-store, then the backing-store contents are returned for regions of the window that are obscured... If the window does not have backing-store, the returned contents of such obscured regions are undefined." Hence, the first behavior is caused by attempting to use TVRD on an obscured window that does not have backing store provided by the X server. The result in this case is undefined, meaning that the different servers can produce entirely different results. Many servers simply return the image of the obscuring window. The second behavior is caused by attempting to read from a non-viewable (i.e., unmapped) window. Although IDL could refuse to allow TVRD to work with unmapped windows, some X servers return valid and useful results. Therefore, TVRD is allowed to attempt to read from unmapped windows. Both of these behavior problems can be solved by using one of the following methods: * Always make sure that your target window is mapped and is not obscured before using TVRD on it. The following IDL command can be used: WSHOW, Window_Index, ICONIC=0 * Make IDL provide backing store (rather than the window system) by setting the RETAIN keyword to DEVICE or WINDOW equal to 2. For a full description of backing store, see "Backing Store" on page 2351. Note that under X Windows, backing store is a request that may or may not be honored by the X server. Many servers will honor backing store for 8-bit visuals but ignore them for 24-bit visuals because they require three times as much memory. Example ; Read the entire contents of the current display device into the ; variable T: T = TVRD() See Also RDPIX, TV, WINDOW TVSCL [Previous Routine] [Next Routine] [List of Routines] NAME: TVSCL The TVSCL procedure scales the intensity values of Image into the range of the image display and outputs the data to the image display at the specified location. The array is scaled so the minimum data value becomes 0 and the maximum value becomes the maximum number of available colors (held in the system variable !D.TABLE_SIZE) as follows: Data ­ Data Output = (!D.TABLE_SIZE - 1) min Datamax ­ Datamin where the maximum and minimum are found by scanning the array. The parameters and keywords of the TVSCL procedure are identical to those accepted by the TV procedure. For additional information about each parameter, consult the description of TV. Syntax TVSCL, Image [, Position] or TVSCL, Image [, X, Y [, Channel]] Keywords: [, /CENTIMETERS | , /INCHES] [, CHANNEL=value] [, /NAN] [, /ORDER] [, TOP=value] [, TRUE={1 | 2 | 3}] [, /WORDS] [, XSIZE=value] [, YSIZE=value] [, /DATA | , /DEVICE | , /NORMAL] [, /T3D | Z=value] Arguments Image A two-dimensional array to be displayed as an image. If this argument is not already of byte type, it is converted prior to use. X, Y If X and Y are present, they specify the lower left coordinate of the displayed image. Position Image position. See the discussion of the TV procedure for a full description. Channel The memory channel to be written. This argument is assumed to be zero if not specified. This parameter is ignored on display systems that have only one memory channel. Keywords TVSCL accepts all of the keywords accepted by the TV routine. See "TV" on page 1455. In addition, there are two unique keywords: NAN Set this keyword to cause TVSCL to treat elements of Image that are not numbers (that is, elements that have the special floating-point values Infinity or NaN) as missing data, and display them using color index 0 (zero). Note that color index 0 is also used to display elements that have the minimum value in the Image array. TOP The maximum value of the scaled result. If TOP is not specified, !D.TABLE_SIZE-1 is used. Note that the minimum value of the scaled result is always 0. Example Display a floating-point array as an image using the TV command: TV, DIST(200) Note that the image is not easily visible because the values in the array have not been scaled into the full range of display values. Now display the image with the TVSCL command by entering: TVSCL, DIST(200) Notice how much brighter the image appears. See Also ERASE, SLIDE_IMAGE, TV, WIDGET_DRAW, WINDOW UINDGEN [Previous Routine] [Next Routine] [List of Routines] NAME: UINDGEN The UINDGEN function returns an unsigned integer array with the specified dimensions. Each element of the array is set to the value of its one-dimensional subscript. Syntax Result = UINDGEN(D1, ..., D8) Arguments Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. The dimensions of the result. The dimension parameters can be any scalar expression. Up to eight dimensions can be specified. If the dimension arguments are not integer values, IDL will convert them to integer values before creating the new array. Example To create UI, a 10-element by 10-element 16-bit array where each element is set to the value of its one-dimensional subscript, enter: UI = UINDGEN(10, 10) See Also BINDGEN, CINDGEN, DCINDGEN, DINDGEN, FINDGEN, L64INDGEN, LINDGEN, SINDGEN, UL64INDGEN, ULINDGEN UINT [Previous Routine] [Next Routine] [List of Routines] NAME: UINT The UINT function returns a result equal to Expression converted to unsigned integer type. Syntax Result = UINT( Expression[, Offset [, Dim1, ..., Dim8]] ) Arguments Expression The expression to be converted to unsigned integer. Offset Offset from beginning of the Expression data area. Specifying this argument allows fields of data extracted from Expression to be treated as unsigned integer data. See the description in Chapter 3, "Constants and Variables" of Building IDL Applications for details. Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. 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 arguments are given, the result is taken to be scalar. When converting from a string argument, it is possible that the string does not contain a valid integer and no conversion is possible. The default action in such cases is to print a warning message and return 0. The ON_IOERROR procedure can be used to establish a statement to be jumped to in case of such errors. Example If A contains the floating-point value 32000.0, it can converted to an unsigned integer and stored in the variable B by entering: B = UINT(A) See Also BYTE, COMPLEX, DCOMPLEX, DOUBLE, FIX, FLOAT, LONG, LONG64, STRING, ULONG, ULONG64 UINTARR [Previous Routine] [Next Routine] [List of Routines] NAME: UINTARR The UINTARR function returns an unsigned integer vector or array. Syntax Result = UINTARR( D1, ..., D8 [, /NOZERO] ) Arguments Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. The dimensions of the result. The dimension parameters can be any scalar expression. Up to eight dimensions can be specified. Keywords NOZERO Normally, UINTARR sets every element of the result to zero. If NOZERO is set, this zeroing is not performed and UINTARR executes faster. Example To create L, a 100-element, unsigned integer vector with each element set to 0, enter: L = UINTARR(100) See Also BYTARR, COMPLEXARR, DBLARR, DCOMPLEXARR, FLTARR, INTARR, LON64ARR, LONARR, MAKE_ARRAY, STRARR, ULON64ARR, ULONARR UL64INDGEN [Previous Routine] [Next Routine] [List of Routines] NAME: UL64INDGEN The UL64INDGEN function returns an unsigned 64-bit integer array with the specified dimensions. Each element of the array is set to the value of its one- dimensional subscript. Syntax Result = UL64INDGEN(D1, ..., D8) Arguments Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. The dimensions of the result. The dimension parameters can be any scalar expression. Up to eight dimensions can be specified. If the dimension arguments are not integer values, IDL will convert them to integer values before creating the new array. Example To create L, a 10-element by 10-element 64-bit array where each element is set to the value of its one-dimensional subscript, enter: L = UL64INDGEN(10, 10) See Also BINDGEN, CINDGEN, DCINDGEN, DINDGEN, FINDGEN, L64INDGEN, LINDGEN, SINDGEN, UINDGEN, ULINDGEN ULINDGEN [Previous Routine] [Next Routine] [List of Routines] NAME: ULINDGEN The ULINDGEN function returns an unsigned longword array with the specified dimensions. Each element of the array is set to the value of its one-dimensional subscript. Syntax Result = ULINDGEN(D1, ..., D8) Arguments Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. The dimensions of the result. The dimension parameters can be any scalar expression. Up to eight dimensions can be specified. If the dimension arguments are not integer values, IDL will convert them to integer values before creating the new array. Example To create L, a 10-element by 10-element 32-bit array where each element is set to the value of its one-dimensional subscript, enter: L = ULINDGEN(10, 10) See Also BINDGEN, CINDGEN, DCINDGEN, DINDGEN, FINDGEN, L64INDGEN, LINDGEN, SINDGEN, UINDGEN, UL64INDGEN ULON64ARR [Previous Routine] [Next Routine] [List of Routines] NAME: ULON64ARR The ULON64ARR function returns an unsigned 64-bit integer vector or array. Syntax Result = ULON64ARR( D1, ..., D8 [, /NOZERO] ) Arguments Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. The dimensions of the result. The dimension parameters can be any scalar expression. Up to eight dimensions can be specified. Keywords NOZERO Normally, ULON64ARR sets every element of the result to zero. If NOZERO is set, this zeroing is not performed and ULON64ARR executes faster. Example To create L, a 100-element, unsigned 64-bit vector with each element set to 0, enter: L = ULON64ARR(100) See Also BYTARR, COMPLEXARR, DBLARR, DCOMPLEXARR, FLTARR, INTARR, LON64ARR, LONARR, MAKE_ARRAY, STRARR, UINTARR, ULONARR ULONARR [Previous Routine] [Next Routine] [List of Routines] NAME: ULONARR The ULONARR function returns an unsigned longword integer vector or array. Syntax Result = ULONARR( D1, ..., D8 [, /NOZERO] ) Arguments Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. The dimensions of the result. The dimension parameters can be any scalar expression. Up to eight dimensions can be specified. Keywords NOZERO Normally, ULONARR sets every element of the result to zero. If NOZERO is set, this zeroing is not performed and ULONARR executes more quickly. Example To create L, a 100-element, unsigned longword vector with each element set to 0, enter: L = ULONARR(100) See Also BYTARR, COMPLEXARR, DBLARR, DCOMPLEXARR, FLTARR, INTARR, LON64ARR, LONARR, MAKE_ARRAY, STRARR, UINTARR, ULON64ARR, ULONG [Previous Routine] [Next Routine] [List of Routines] NAME: ULONG The ULONG function returns a result equal to Expression converted to the unsigned longword integer type. Syntax Result = ULONG( Expression[, Offset [, Dim1, ..., Dim8]] ) Arguments Expression The expression to be converted to unsigned longword integer. Offset Offset from beginning of the Expression data area. Specifying this argument allows fields of data extracted from Expression to be treated as unsigned longword integer data. See the description in Chapter 3, "Constants and Variables" of Building IDL Applications 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 arguments are given, the result is taken to be scalar. When converting from a string argument, it is possible that the string does not contain a valid integer and no conversion is possible. The default action in such cases is to print a warning message and return 0. The ON_IOERROR procedure can be used to establish a statement to be jumped to in case of such errors. Example If A contains the floating-point value 32000.0, it can converted to an unsigned longword integer and stored in the variable B by entering: B = ULONG(A) See Also BYTE, COMPLEX, DCOMPLEX, DOUBLE, FIX, FLOAT, LONG, LONG64, STRING, UINT, ULONG64 ULONG64 [Previous Routine] [Next Routine] [List of Routines] NAME: ULONG64 The ULONG64 function returns a result equal to Expression converted to the unsigned 64-bit integer type. Syntax Result = ULONG64( Expression[, Offset [, Dim1, ..., Dim8]] ) Arguments Expression The expression to be converted to unsigned 64-bit integer. Offset Offset from beginning of the Expression data area. Specifying this argument allows fields of data extracted from Expression to be treated as unsigned 64-bit integer data. See the description in Chapter 3, "Constants and Variables" of Building IDL Applications for details. Di This modified argument can now specify dimensions as a single array as well as a sequence of scalar values. 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 arguments are given, the result is taken to be scalar. When converting from a string argument, it is possible that the string does not contain a valid integer and no conversion is possible. The default action in such cases is to print a warning message and return 0. The ON_IOERROR procedure can be used to establish a statement to be jumped to in case of such errors. Example If A contains the floating-point value 32000.0, it can converted to an unsigned 64-bit integer and stored in the variable B by entering: B = ULONG64(A) See Also BYTE, COMPLEX, DCOMPLEX, DOUBLE, FIX, FLOAT, LONG, LONG64, STRING, UINT, ULONG UNIQ [Previous Routine] [Next Routine] [List of Routines] NAME: UNIQ The UNIQ function returns the subscripts of the unique elements in an array. Note that repeated elements must be adjacent in order to be found. This routine is intended to be used with the SORT function: see the examples below. This function was inspired by the UNIX uniq(1) command. UNIQ returns an array of indices into the original array. Note that the index of the last element in each set of non-unique elements is returned. The following expression is a copy of the sorted array with duplicate adjacent elements removed: Array(UNIQ(Array)) UNIQ returns 0 (zero) if the argument supplied is a scalar rather than an array. This routine is written in the IDL language. Its source code can be found in the file uniq.pro in the lib subdirectory of the IDL distribution. Syntax Result = UNIQ( Array [, Index] ) Arguments Array The array to be scanned. For UNIQ to work properly, the array must be sorted into monotonic order unless the optional parameter Idx is supplied. Index This optional parameter is an array of indices into Array that order the elements into monotonic order. That is, the expression: Array(Index) yields an array in which the elements of Array are rearranged into monotonic order. If the array is not already in monotonic order, use the command: UNIQ(Array, SORT(Array)) Examples Find the unique elements of an unsorted array: ; Create an array: array = [1, 2, 1, 2, 3, 4, 5, 6, 6, 5] ; Variable B holds an array containing the sorted, unique values in ; array: b = array[UNIQ(array, SORT(array))] PRINT, b IDL prints 1 2 3 4 5 6 See Also SORT, WHERE USERSYM [Previous Routine] [Next Routine] [List of Routines] NAME: USERSYM The USERSYM procedure is used to define the plotting symbol that marks points when the plotting symbol is set to plus or minus 8. Symbols can be drawn with vectors or can be filled. Symbols can be of any size and can have up to 50 vertices. See "Defining Your Own Plotting Symbols" in Chapter 11 of Using IDL. Syntax USERSYM, X [, Y] [, COLOR=value] [, /FILL] [, THICK=value] Arguments X, Y The X and/or Y parameters define the vertices of the symbol as offsets from the data point in units of approximately the size of a character. In the case of a vector drawn symbol, the symbol is formed by connecting the vertices in order. If only one argument is specified, it must be a (2, N) array of vertices, with element [0, i] containing the X coordinate of the vertex, and element [1, i] containing the Y. If both arguments are provided, X contains only the X coordinates. Keywords COLOR The color used to draw the symbols, or used to fill the polygon. The default color is the same as the line color. FILL Set this keyword to fill the polygon defined by the vertices. If FILL is not set, lines are drawn connecting the vertices. THICK The thickness of the lines used in drawing the symbol. The default thickness is 1.0. Example Make a large, diamond-shaped plotting symbol. Define the vectors of X values by entering: X = [-6, 0, 6, 0, -6] Define the vectors of Y values by entering: Y = [0, 6, 0, -6, 0] Now call USERSYM to create the new plotting symbol 8. Enter: USERSYM, X, Y Generate a simple plot to test the plotting symbol by entering: PLOT, FINDGEN(20), PSYM = 8 See Also PLOT VALUE_LOCATE [Previous Routine] [Next Routine] [List of Routines] NAME: VALUE_LOCATE The VALUE_LOCATE function finds the intervals within a given monotonic vector that brackets a given set of one or more search values. This function is useful for interpolation and table-lookup, and is an adaptation of the locate() routine in Numerical Recipes. VALUE_LOCATE uses the bisection method to locate the interval. Syntax Result = VALUE_LOCATE ( Vector, Value [, /L64 ] ) Return Value Each return value, Result [i], is an index, j, into Vector, corresponding to the interval into which the given Value [i] falls. The returned values are in the range ­1 j N­1, where N is the number of elements in the input vector. If Vector is monotonically increasing, the result j is: if j = ­1 Value [i] < Vector [0] if 0 j < N­1 Vector [j] Value [i] < Vector [j+1] if j = N­1 Vector [N­1] Value [i] If Vector is monotonically decreasing if j = ­1 Vector [0] Value [i] if 0 j < N­1 Vector [j+1] Value [i] < Vector [j] if j = N­1 Value [i] < Vector [N­1] Arguments Vector A vector of monotonically increasing or decreasing values. Vector may be of type string, or any numeric type except complex, and may not contain the value NaN (not- a-number). Value The value for which the location of the intervals is to be computed. Value may be either a scalar or an array. The return value will contain the same number of elements as this parameter. Keywords L64 By default, the result of VALUE_LOCATE is 32-bit integer when possible, and 64- bit integer if the number of elements being processed requires it. Set L64 to force 64- bit integers to be returned in all cases. Note Only 64-bit versions of IDL are capable of creating variables requiring a 64-bit result. Check the value of !VERSION.MEMORY_BITS to see if your IDL is 64-bit or not. Example ; Define a vector of values. vec = [2,5,8,10] ; Compute location of other values within that vector. loc = VALUE_LOCATE(vec, [0,3,5,6,12]) PRINT, loc IDL prints: -1 0 1 1 3 VARIANCE [Previous Routine] [Next Routine] [List of Routines] NAME: VARIANCE The VARIANCE function computes the statistical variance of an n-element vector. Syntax Result = VARIANCE( X [, /DOUBLE] [, /NAN] ) Arguments X An n-element, floating-point or double-precision vector. Keywords DOUBLE If this keyword is set, VARIANCE performs its computations in double precision arithmetic and returns a double precision result. If this keyword is not set, the computations and result depend upon the type of the input data (integer and float data return float results, while double data returns double results). NAN Set this keyword to cause the routine to check for occurrences of the IEEE floating- point value NaN in the input data. Elements with the value NaN are treated as missing data. (See "Special Floating-Point Values" in Chapter 17 of Building IDL Applications for more information on IEEE floating-point values.) Example ; Define the n-element vector of sample data: x = [1, 1, 1, 2, 5] ; Compute the variance: result = VARIANCE(x) PRINT, result IDL prints: 3.00000 See Also KURTOSIS, MEAN, MEANABSDEV, MOMENT, STDDEV, SKEWNESS VAX_FLOAT [Previous Routine] [Next Routine] [List of Routines] NAME: VAX_FLOAT The VAX_FLOAT function performs one of two possible actions: 1. Determine, and optionally change, the default value for the VAX_FLOAT keyword to the OPEN procedures and the CALL_EXTERNAL function. 2. Determine if an open file unit has the VAX_FLOAT attribute set. See the discussion of VAX floating-point conversion in Appendix A, "VMS Floating-Point Arithmetic in IDL" in Building IDL Applications and the VAX_FLOAT keyword to "OPEN" on page 959 for more on the VAX floating-point conversion issue. Syntax Result = VAX_FLOAT( [Default] [, FILE_UNIT=lun] ) Arguments Default Default is used to change the default value of the VAX_FLOAT keyword to the OPEN procedures and the CALL_EXTERNAL function. A value of 0 (zero) makes the default for those keywords False. A non-zero value makes the default True. Specifying Default in conjunction with the FILE_UNIT keyword will cause an error. Note If the FILE_UNIT keyword is not specified, the value returned from VAX_FLOAT is the default value before any change is made. This is the case even if Default is specified. This allows you to get the old setting and change it in a single operation. Keywords FILE_UNIT Set this keyword equal to the logical file unit number (LUN) of an open file. VAX_FLOAT returns True (1) if the file was opened with the VAX_FLOAT attribute, or False (0) otherwise. Setting the FILE_UNIT keyword when the Default argument is specified will cause an error. Example To determine if the default VAX_FLOAT keyword value for OPEN and CALL_EXTERNAL is True or False: default_vax_float = VAX_FLOAT() To determine the current default value of the VAX_FLOAT keyword for OPEN and CALL_EXTERNAL and change it to True (1) in a single operation: old_vax_float = VAX_FLOAT(1) To determine if the file currently open on logical file unit 1 was opened with the VAX_FLOAT keyword set: file_is_vax_float = VAX_FLOAT(FILE_UNIT=1) See Also CALL_EXTERNAL, OPEN VECTOR_FIELD [Previous Routine] [Next Routine] [List of Routines] NAME: VECTOR_FIELD The VECTOR_FIELD procedure is used to place colored, oriented vectors of specified length at each vertex in an input vertex array. The output can be sent directly to an IDLgrPolyline object. The generated display is generally referred to as a hedgehog display and is used to convey various aspects of a vector field. Syntax VECTOR_FIELD, Field, Outverts, Outconn [, ANISOTROPY=array] [, SCALE=value] [, VERTICES=array] Arguments Field Input vector field array. This can be a [3, x, y, z] array or a [2, x, y] array. The leading dimension is the vector quantity to be displayed. Outverts Output vertex array ([3, N] or [2, N] array of floats). Useful if the routine is to be used with Direct Graphics or the user wants to manipulate the data directly. Outconn Output polyline connectivity array to be applied to the output vertices. Keywords ANISOTROPY Set this keyword to a two- or three-element array describing the distance between grid points in each dimension. The default value is [1.0, 1.0, 1.0] for three- dimensional data and [1.0, 1.0] for two-dimensional data. SCALE Set this keyword to a scalar scaling factor. All vector lengths are multiplied by this value. The default is 1.0. VERTICES Set this keyword to a [3, n] or [2, n] array of points. If this keyword is set, the vector field is interpolated at these points. The resulting interpolated vectors are displayed as line segments at these locations. If the keyword is not set, each spatial sample point in the input Field grid is used as the base point for a line segment. VEL [Previous Routine] [Next Routine] [List of Routines] NAME: VEL The VEL procedure draws a velocity (flow) field with arrows following the field proportional in length to the field strength. Arrows are composed of a number of small segments that follow the streamlines. This routine is written in the IDL language. Its source code can be found in the file vel.pro in the lib subdirectory of the IDL distribution. Syntax VEL, U, V [, NVECS=value] [, XMAX= value{xsize/ysize}] [, LENGTH=value{longest/steps}] [, NSTEPS=value] [, TITLE=string] Arguments U The X component at each point of the vector field. U must be a 2D array. V The Y component at each point of the vector field. V must have the same dimensions as U. Keywords LENGTH The length of each arrow line segment expressed as a fraction of the longest vector divided by the number of steps. The default is 0.1. NSTEPS The number of shoots or line segments for each arrow. The default is 10. NVECS The number of vectors (arrows) to draw. If this keyword is omitted, 200 vectors are drawn. TITLE A string containing the title for the plot. XMAX X axis size as a fraction of Y axis size. The default is 1.0. This argument is ignored when !P.MULTI is set. Example ; Create a vector of X values: X = DIST(20) ; Create a vector of Y values: Y = SIN(X)*100 ; Plot the vector field: VEL, X, Y See Also FLOW3, PLOT_FIELD, VELOVECT VELOVECT [Previous Routine] [Next Routine] [List of Routines] NAME: VELOVECT The VELOVECT procedure produces a two-dimensional velocity field plot. A directed arrow is drawn at each point showing the direction and magnitude of the field. This routine is written in the IDL language. Its source code can be found in the file velovect.pro in the lib subdirectory of the IDL distribution. Syntax VELOVECT, U, V [, X, Y] [, COLOR=index] [, MISSING=value [, /DOTS]] [, LENGTH=value] [, /OVERPLOT] [Also accepts all PLOT keywords] Arguments U The X component of the two-dimensional field. U must be a two-dimensional array. V The Y component of the two dimensional field. V must have the same dimensions as U. X Optional abcissae values. X must be a vector with a length equal to the first dimension of U and V. Y Optional ordinate values. Y must be a vector with a length equal to the second dimension of U and V. Keywords Note Keywords not described here are passed directly to the PLOT procedure and may be used to set options such as TITLE, POSITION, NOERASE, etc. COLOR Set this keyword equal to the color index used for the plot. DOTS Set this keyword to 1 to place a dot at each missing point. Set this keyword to 0 or omit it to draw nothing for missing points. Has effect only if MISSING is specified. LENGTH Set this keyword equal to the length factor. The default of 1.0 makes the longest (U,V) vector the length of a cell. MISSING Set this keyword equal to the missing data value. Vectors with a length greater than MISSING are ignored. OVERPLOT Set this keyword to make VELOVECT "overplot". That is, the current graphics screen is not erased, no axes are drawn, and the previously established scaling remains in effect. PLOT Keywords In addition to the keywords described above, all other keywords accepted by the PLOT procedure are accepted by VELOVECT. See PLOT. Example ; Create some random data: U = RANDOMN(S, 20, 20) V = RANDOMN(S, 20, 20) ; Plot the vector field: VELOVECT, U, V ; Plot the field, using dots to represent vectors with values ; greater than 18: VELOVECT, U, V, MISSING=18, /DOTS ; Plot with a title. Note that the XTITLE keyword is passed ; directly to the PLOT procedure: VELOVECT, U, V, MISSING=18, /DOTS, XTITLE='Random Vectors' See Also FLOW3, PLOT, PLOT_FIELD, VEL VERT_T3D [Previous Routine] [Next Routine] [List of Routines] NAME: VERT_T3D The VERT_T3D function transforms a 3D array by a 4x4 transformation matrix and returns the transformed array. The 3D points are typically an array of polygon vertices that were generated by SHADE_VOLUME or MESH_OBJ. This routine is written in the IDL language. Its source code can be found in the file vert_t3d.pro in the lib subdirectory of the IDL distribution. Syntax Result = VERT_T3D( Vertex_List [, MATRIX=4x4_array] [, /NO_COPY] [, /NO_DIVIDE [, SAVE_DIVIDE=variable]] ) Arguments Vertex_List A 3 x n array of 3D coordinates to transform. Keywords DOUBLE Set this keyword to a nonzero value to indicate that the returned coordinates should be double-precision. If this kewyord is not set, the default is to return single-precision coordinates (unless double-precision argumetns are input, in which case the DOUBLE keyword is implied to be non-zero). MATRIX The 4x4 transformation matrix to use. The default is to use the system viewing matrix (!P.T). NO_COPY Normally, a copy of Vertex_list is transformed and the original Vertex_list is preserved. If NO_COPY is set, however, then the original Vertex_List will be undefined after the call to VERT_T3D. Using the NO_COPY requires less memory. NO_DIVIDE Normally, when a [x, y, z, 1] vector is transformed by a 4x4 matrix, the final homogeneous coordinates are obtained by dividing the x, y, and z components of the result vector by the fourth element in the result vector. Setting the NO_DIVIDE keyword will prevent VERT_T3D from performing this division. In some cases (usually when a perspective transformation is involved) the fourth element in the result vector can be very close to (or equal to) zero. SAVE_DIVIDE Set this keyword to a named variable that will hold receive the fourth element of the transformed vector(s). If Vertex_list is a vector then SAVE_DIVIDE is a scalar. If Vertex_list is an array then SAVE_DIVIDE is an array of n elements. This keyword only has effect when the NO_DIVIDE keyword is set. Example Transform four points representing a square in the x-y plane by first translating +2.0 in the positive X direction, and then rotating 60.0 degrees about the Y axis. points = [[0.0, 0.0, 0.0], [1.0, 0.0, 0.0], $ [1.0, 1.0, 0.0], [0.0, 1.0, 0.0]] T3D, /RESET T3D, TRANSLATE=[2.0, 0.0, 0.0] T3D, ROTATE=[0.0, 60.0, 0.0] points = VERT_T3D(points) See Also T3D VOIGT [Previous Routine] [Next Routine] [List of Routines] NAME: VOIGT The VOIGT function returns the intensity of an atomic absorption line profile (also known as a VOIGT profile) based on the Voigt damping parameter a and the frequency offset u, in units of the Doppler width. The result is always floating-point and has the same structure as the arguments. Note that a and u should not both be vectors. The returned line profile (a, u) is defined as: (a, u) H(a, u) ------------------ vD where H is the classical Voigt function: H(a, u) a = --- e y2 ­ y d ------------------------------- a2 (u ­ y)2 + ­ The Doppler width vD (assuming no turbulence), is defined as: v 0 0 D = ----- = ----- c b c 2kT m where 0 is the line center frequency. The dimensionless frequency offset u and the damping parameter a are determined by: ­ u 0 = -------------- D a = ----------------- 4 D Here, is the transition rate: = + 2 col where is the spontaneous decay rate, and col is the atomic collision rate. See Radiative Processes in Astrophysics by G. B. Rybicki and A. P. Lightman (1979) p 291 for more information. The algorithm is from Armstrong, JQSRT 7, 85. (1967). Syntax Result = VOIGT(A, U) Arguments A The Voigt damping parameter. U The dimensionless frequency offset in Doppler widths. See Also LEEFILT, ROBERTS, SOBEL VORONOI [Previous Routine] [Next Routine] [List of Routines] NAME: VORONOI The VORONOI procedure computes the Voronoi polygon of a point within an irregular grid of points, given the Delaunay triangulation. The Voronoi polygon of a point contains the region closer to that point than to any other point. For interior points, the polygon is constructed by connecting the midpoints of the lines connecting the point with its Delaunay neighbors. Polygons are traversed in a counterclockwise direction. For exterior points, the set is described by the midpoints of the connecting lines, plus the circumcenters of the two triangles that connect the point to the two adjacent exterior points. This routine is written in the IDL language. Its source code can be found in the file voronoi.pro in the lib subdirectory of the IDL distribution. Syntax VORONOI, X, Y, I0, C, Xp, Yp, Rect Arguments X An array containing the X locations of the points. Y An array containing the Y locations of the points. I0 An array containing the indices of the points. C A connectivity list from the Delaunay triangulation. This list is produced with the CONNECTIVITY keyword of the TRIANGULATE procedure. Xp, Yp Named variables that will contain the X and Y vertices of Voronoi polygon. Rect The bounding rectangle: [Xmin, Ymin, Xmax, Ymax]. Because the Voronoi polygon (VP) for points on the convex hull extends to infinity, a clipping rectangle must be supplied to close the polygon. This rectangle has no effect on the VP of interior points. If this rectangle does not enclose all the Voronoi vertices, the results will be incorrect. If this parameter, which must be a named variable, is undefined or set to a scalar value, it will be calculated. Example To draw the Voronoi polygons of each point of an irregular grid: N = 20 ; Create a random grid of N points: X = RANDOMU(seed, N) Y = RANDOMU(seed, N) ; Triangulate it: TRIANGULATE, X, Y, tr, CONN=C FOR I=0, N-1 DO BEGIN & $ ; Get the ith polygon: VORONOI, X, Y, I, C, Xp, Yp & $ ; Draw it: POLYFILL, Xp, Yp, COLOR = (I MOD 10) + 2 & $ ENDFOR See Also TRIANGULATE VOXEL_PROJ [Previous Routine] [Next Routine] [List of Routines] NAME: VOXEL_PROJ The VOXEL_PROJ function generates visualizations of volumetric data by computing 2D projections of a colored, semi-transparent volume. Parallel rays from any given direction are cast through the volume, onto the viewing plane. User- selected colors and opacities can be assigned to arbitrary data ranges, simulating the appearance of the materials contained within the volume. The VOXEL_PROJ function can be combined with the Z-buffer to render volume data over objects. Cutting planes can also be specified to view selected portions of the volume. Other options include: selectable resolution to allow quick "preview" renderings, and average and maximum projections. VOXEL_PROJ renders volumes using an algorithm similar to the one described by Drebin, Carpenter, and Hanrahan, in "Volume Rendering", Computer Graphics, Volume 22, Number 4, August 1988, pp. 125-134, but without the surface extraction and enhancement step. Voxel rendering can be quite time consuming. The time required to render a volume is proportional to the viewing areas size, in pixels, times the thickness of the volume cube in the viewing direction, divided by the product of the user-specified X, Y, and Z steps. Syntax Result = VOXEL_PROJ( V [, RGBO] [, BACKGROUND=array] [, CUTTING_PLANE=array] [, /INTERPOLATE] [, /MAXIMUM_INTENSITY] [, STEP=[Sx, Sy, Sz]] [, XSIZE=pixels] [, YSIZE=pixels] [, ZBUFFER=int_array] [, ZPIXELS=byte_array] ) Arguments V A three-dimensional array containing the volume to be rendered. This array is converted to byte type if necessary. RGBO This optional parameter is used to specify the look-up tables that indicate the color and opacity of each voxel value. This argument can be one of the following types: * A (256, 4) byte array for TrueColor rendering. This array represents 256 sets of red, green, blue, and opacity (RGBO) components for each voxel value, scaled into the range of bytes (0 to 255). The R, G, and B components should already be scaled by the opacity. For example, if a voxel value of 100 contains a material that is red, and 35% opaque, the RGBO values should be, respectively: [89, 0, 0, 89] because 255 * 0.35 = 89. If more than one material is present, the RGBO arrays contain the sum of the individual RGBO arrays. The content and shape of the RGBO curves is highly dependent upon the volume data and experimentation is often required to obtain the best display. * A (256, 2) byte array for volumes with only one material or monochrome rendering. This array represents 256 sets of pixel values and their corresponding opacities for each voxel value. * If this argument is omitted, the average projection method, or maximum intensity method (if the MAXIMUM_INTENSITY keyword is set) is used. Keywords BACKGROUND A one- or three-element array containing the background color indices. The default is (0,0,0), yielding a black background with most color tables. CUTTING_PLANE A floating-point array specifying the coefficients of additional cutting planes. The array has dimensions of (4, N), where N is the number of additional cutting planes from 1 to 6. Cutting planes are constraints in the form of: C[0] * X + C[1] * Y + C[2] * Z + D > 0 The X, Y, and Z coordinates are specified in voxel coordinates. For example, to specify a cutting plane that excludes all voxels with an X value greater than 10: CUTTING_PLANE = [-1.0, 0, 0, 10.], for the constraint: -X + 10 > 0. INTERPOLATE Set this keyword to use tri-linear interpolation to determine the data value for each step on a ray. Otherwise, the nearest-neighbor method is used. Setting this keyword improves the quality of images produced, especially when the volume has low resolution in relation to the size of the viewing plane, at the cost of more computing time. MAXIMUM_INTENSITY Set this keyword to make the value of each pixel in the viewing plane the maximum data value along the corresponding ray. The RGBO argument is ignored if present. STEP Set this keyword to a three-element vector, [Sx, Sy, Sz], that controls the resolution of the resulting projection. The first two elements contain the step size in the X and Y view plane, in pixels. The third element is the sampling step size in the Z direction, given in voxels. Sx and Sy must be integers equal to or greater than one, while Sz can contain a fractional part. If Sx or Sy are greater than one, the values of intermediate pixels in the output image are linearly interpolated. Higher step sizes require less time because fewer rays are cast, at the expense of lower resolution in the output image. XSIZE The width, in pixels, of the output image. If this keyword is omitted, the output image is as wide as the currently-selected output device. YSIZE The height, in pixels, of the output image. If this keyword is omitted, the output image is as tall as the currently selected output device. ZBUFFER An integer array, with the same width and height as the output image, that contains the depth portion of the Z-buffer. Include this parameter to combine the previously- read contents of a Z-buffer with a voxel rendering. See the third example, below, for details. ZPIXELS A byte array, with the same width and height as the output image, that contains the image portion of the Z-buffer. Include this parameter to combine the contents of a Z- buffer with a voxel rendering. See the third example, below, for details. Examples Example 1 In the following example, assume that variable V contains a volume of data, with dimensions Vx by Vy by Vz. The volume contains two materials, muscle tissue represented by a voxel range of 50 to 70, that we want to render with red color, and an opacity of 20; and bone tissue represented by a voxel range of 220-255, that we want to render with white color, and an opacity of 50: ; Create the opacity vector: rgbo = BYTARR(256,4) ; Red and opacity for muscle: rgbo[50:70, [0,3]] = 20 ; White and opacity for bone: rgbo[220:255, *] = 50 Example 2 Although it is common to use trapezoidal or Gaussian functions when forming the RGBO arrays, this example uses rectangular functions for simplicity. ; Set up the axis scaling and default rotation: SCALE3, XRANGE=[0, Vx-1], YRANGE=[0, Vy-1], ZRANGE=[0, Vz-1] ; Compute projected image: C = VOXEL_PROJ(V, rgbo) ; Convert from 24-bit to 8-bit image and display: TV, COLOR_QUAN(C, 3, R, G, B) ; Load quantized color tables: TVLCT, R, G, B This example required approximately 27 seconds on a typical workstation to compute the view in a 640- by 512-pixel viewing window. Adding the keyword STEP=[2,2,1] in the call to VOXEL_PROJ decreased the computing time to about 8 seconds, at the expense of slightly poorer resolution. When viewing a volume with only one constituent, the RGBO array should contain only an intensity/opacity value pair. To illustrate, if in the above example, only muscle was of interest we create the RGBO argument as follows: ; Create an empty 256 x 2 array: rgbo = BYTARR(256,2) ; Intensity and opacity for muscle: rgbo[50:70, *] = 20 SCALE3, XRANGE=[0, Vx-1], YRANGE=[0, Vy-1], ZRANGE=[0, Vz-1] ; Compute and display the projected image: TV, VOXEL_PROJ(V, rgbo) ; Create color table array for red: C = (FINDGEN(256)/255.) # [255., 0., 0] ; Load colors: TVLCT, C[*,0], C[*,1], C[*,2] Example 3 This example demonstrates combining a volume with the contents of the Z-buffer: ; Set plotting to Z-buffer: SET_PLOT, 'Z' ; Turn on Z buffering: DEVICE, /Z_BUFFER ; Set scaling: SCALE3, XRANGE=[0, Vx-1], YRANGE=[0, Vy-1], ZRANGE=[0, Vz-1] ; Draw a polygon at z equal to half the depth: POLYFILL, [0, Vx-1, Vx-1, 0], [0, 0, Vy-1, Vy-1], Vz/2., /T3D ; Read pixel values from the Z-buffer: zpix = TVRD() ; Read depth values from the Z-buffer: zbuff = TVRD(/WORDS,/CHAN) ; Back to display window: SET_PLOT, 'X' ; Compute the voxel projection and use the ZPIXELS and ZBUFFER ; keywords to combine the volume with the previously-read contents ; of the Z-buffer: C = VOXEL_PROJ(V, rgbo, ZPIX=zpix, ZBUFF=zbuff) ;Convert from 24-bit to 8-bit image and display. TV, COLOR_QUAN(C, 3, R, G, B) ; Load the quantized color tables: TVLCT, R, G, B See Also POLYSHADE, PROJECT_VOL, RECON3, SHADE_VOLUME WAIT [Previous Routine] [Next Routine] [List of Routines] NAME: WAIT The WAIT procedure suspends execution of an IDL program for a specified period. Note that because of other activity on the system, the duration of program suspension may be longer than requested. Syntax WAIT, Seconds Arguments Seconds The duration of the wait, specified in seconds. This parameter can be a floating-point value to specify a fractional number of seconds. Example To make an IDL program suspend execution for about five and one half seconds, use the command: WAIT, 5.5 See Also EXIT, STOP WARP_TRI [Previous Routine] [Next Routine] [List of Routines] NAME: WARP_TRI The WARP_TRI function returns an image array with a specified geometric correction applied. Images are warped using control (tie) points such that locations (Xi, Yi) are shifted to (Xo, Yo). The irregular grid defined by (Xo, Yo) is triangulated using TRIANGULATE. Then the surfaces defined by (Xo, Yo, Xi) and (Xo, Yo, Yi) are interpolated using TRIGRID to get the locations in the input image of each pixel in the output image. Finally, INTERPOLATE is called to obtain the result. Linear interpolation is used by default. Smooth quintic interpolation is used if the QUINTIC keyword is set. This routine is written in the IDL language. Its source code can be found in the file warp_tri.pro in the lib subdirectory of the IDL distribution. Syntax Result = WARP_TRI( Xo, Yo, Xi, Yi, Image [, TPS] [, OUTPUT_SIZE=vector] [, /QUINTIC] [, /EXTRAPOLATE] ) Arguments Xo, Yo Vectors containing the locations of the control (tie) points in the output image. Xi, Yi Vectors containing the location of the control (tie) points in the input image. Xi and Yi must be the same length as Xo and Yo. Image The image to be warped. May be any type of data. Keywords TPS This new keyword uses Thin Plate Spline interpolation which is ideal for modeling functions with complex local distortions, such as warping functions, which are too complex to be fit with polynomials. OUTPUT_SIZE Set this keyword equal to a 2-element vector containing the size of the output image. If omitted, the output image is the same size as Image. QUINTIC Set this keyword to use smooth quintic interpolation. Quintic interpolation is slower but the derivatives are continuous across triangles, giving a more pleasing result than the default linear interpolation. EXTRAPOLATE Set this keyword to extrapolate outside the convex hull of the tie points. Setting this keyword implies the use of QUINTIC interpolation. See Also INTERPOLATE, TRIANGULATE, TRIGRID WATERSHED [Previous Routine] [Next Routine] [List of Routines] NAME: WATERSHED The WATERSHED function applies the morphological watershed operator to a grayscale image. This operator segments images into watershed regions and their boundaries. Considering the gray scale image as a surface, each local minimum can be thought of as the point to which water falling on the surrounding region drains. The boundaries of the watersheds lie on the tops of the ridges. This operator labels each watershed region with a unique index, and sets the boundaries to zero. Typically, morphological gradients, or images containing extracted edges are used for input to the watershed operator. Noise and small unimportant fluctuations in the original image can produce spurious minima in the gradients, which leads to oversegmentation. Smoothing, or manually marking the seed points are two approaches to overcoming this problem. For further reading, see Dougherty, "An Introduction to Morphological Image Processing", SPIE Optical Engineering Press, 1992 Syntax Result = WATERSHED ( Image [, CONNECTIVITY={4 | 8} ] ) Return Value Returns an image of the same dimensions as the input image. Each pixel of the result will be either zero if the pixel falls along the segmentation between basins, or the identifier of the basin in which that pixel falls. Arguments Image The two-dimensional image to be segmented. Image is converted to byte type if necessary. Keywords CONNECTIVITY Set this keyword to either 4 (to select 4-neighbor connectivity) or 8 (to select 8- neighbor connectivity). Connectivity indicates which pixels in the neighborhood of a given pixel are sampled during the segmentation process. 4-neighbor connectivity samples only the pixels that are immediately adjacent horizontally and vertically. 8- neighbor connectivity samples the diagonally adjacent neighbors in addition to the immediate horizontal and vertical neighbors. The default is 4-neighbor connectivity. Example The following code crudely segments the grains in the data file in the IDL Demo data directory containing an magnified image of grains of pollen. Note that the IDL Demos must be installed in order to read the image used in this example. It inverts the image, because the watershed operator finds holes, and the grains of pollen are bright. Next, the morphological closing operator is applied with a disc of radius 9, contained within a 19 by 19 kernel, to eliminate holes in the image smaller than the disc. The watershed operator is then applied to segment this image. The borders of the watershed images, which have pixel values of zero, are then merged with the original image and displayed as white. ;Radius of disc... r = 9 ;Create a disc of radius r disc = SHIFT(DIST(2*r+1), r, r) LE r ;Read the image READ_JPEG, FILEPATH('pollens.jpg', $ SUBDIR=['examples','demo','demodata']), a ;Invert the image b = MAX(a) - a TVSCL, b, 0 ;Remove holes of radii less than r c = MORPH_CLOSE(b, disc, /GRAY) TVSCL, c, 1 ;Create watershed image d = WATERSHED(c) ;Display it, showing the watershed regions TVSCL, d, 2 ;Merge original image with boundaries of watershed regions e = a > (MAX(a) * (d EQ 0b)) TVSCL, e, 3 WDELETE [Previous Routine] [Next Routine] [List of Routines] NAME: WDELETE The WDELETE procedure deletes IDL windows. Syntax WDELETE [, Window_Index [, ...]] Arguments Window_Index A list of one or more window indices to delete. If this argument is not specified, the current window (as specified by the system variable !D.WINDOW) is deleted. If the window being deleted is not the active window, the value of !D.WINDOW remains unchanged. If the window being deleted is the active window, !D.WINDOW is set to the highest numbered window index or to -1 if no windows remain open. If this window index is the widget ID of a draw widget, that widget is deleted. Example Create IDL graphics window number 5 by entering: WINDOW, 5 Delete window 5 by entering: WDELETE, 5 See Also WINDOW, WSET, WSHOW WEOF [Previous Routine] [Next Routine] [List of Routines] NAME: WEOF The WEOF procedure writes an end of file mark, sometimes called a tape mark, on the designated tape unit at the current position. WEOF is available only under VMS. The tape must be mounted as a foreign volume. See "VMS-Specific Information" in Chapter 8 of Building IDL Applications. Syntax WEOF, Unit Arguments Unit The magnetic tape unit on which the end of file mark is written. This argument must be a number between 0 and 9, and should not be confused with standard file Logical Unit Numbers (LUNs). See Also TAPWRT WF_DRAW [Previous Routine] [Next Routine] [List of Routines] NAME: WF_DRAW The WF_DRAW procedure draws weather fronts of various types using parametric spline interpolation to smooth the lines. WF_DRAW uses the POLYFILL routine to make the annotations on the front lines. This routine is written in the IDL language. Its source code can be found in the file wf_draw.pro in the lib subdirectory of the IDL distribution. Syntax WF_DRAW, X, Y [[, /COLD | , FRONT_TYPE=1] | [, /WARM | , FRONT_TYPE=2] | [, /OCCLUDED | , FRONT_TYPE=3] | [, /STATIONARY | , FRONT_TYPE=4] | [, /CONVERGENCE | , FRONT_TYPE=5]] [, COLOR=value] [, /DATA | , /DEVICE | , /NORMAL] [, INTERVAL=value] [, PSYM=value] [, SYM_HT=value] [, SYM_LEN=value] [, THICK=value] Arguments X, Y Vectors of abcissae and ordinates defining the front to be drawn. Keywords COLD Set this keyword to draw a cold front. The default is a plain line with no annotations. A cold front can also be specified by setting the keyword FRONT_TYPE = 1. COLOR Use this keyword to specify the color to use. The default = !P.COLOR. CONVERGENCE Set this keyword to draw a convergence line. A convergence line can also be specified by setting the keyword FRONT_TYPE = 5. DATA Set this keyword if X and Y are specified in data coordinates. DEVICE Set this keyword if X and Y are specified in device coordinates. FRONT_TYPE Set this keyword equal to the numeric index of type of front to draw. Front type indices are as follows: COLD=1, WARM=2, OCCLUDED=3, STATIONARY=4, CONVERGENCE = 5. Not required if plain line is desired or if an explicit front type keyword is specified. INTERVAL Use this keyword to specify the spline interpolation interval, in normalized units. The default = 0.01. Larger values give coarser approximations to curves, smaller values make more interpolated points. NORMAL Set this keyword if X and Y are specified in normalized coordinates. This is the default. OCCLUDED Set this keyword to draw an occluded front. An occluded front can also be specified by setting the keyword FRONT_TYPE = 3. PSYM Set this keyword a standard PSYM value to draw a marker on each actual (X, Y) data point. See "PSYM" on page 2408 for a list of the symbol types. STATIONARY Set this keyword to draw a stationary front. A stationary front can also be specified by setting the keyword FRONT_TYPE = 4. SYM_HT Use this keyword to specify the height of front symbols, in normalized units. The default = 0.02. SYM_LEN Use this keyword to specify the length and spacing factor for front symbols, in normalized units. The default = 0.15. THICK Use this keyword to specify the line thickness. The default = 1.0. WARM Set this keyword to draw a warm front. A warm front can also be specified by setting the keyword FRONT_TYPE = 2. Example This example draws various fronts on a map of the United States. Note that this example code is in the file wf_draw.pro, and can be run by entering test_wf_draw at the IDL command line. PRO test_wf_draw MAP_SET, LIMIT = [25, -125, 50, -70], /GRID, /USA WF_DRAW, [ -120, -110, -100], [30, 50, 45], /COLD, /DATA, THICK=2 WF_DRAW, [ -80, -80, -75], [ 50, 40, 35], /WARM, /DATA, THICK=2 WF_DRAW, [ -80, -80, -75]-10., [ 50, 40, 35], /OCCLUDED, /DATA,$ THICK=2 WF_DRAW, [ -120, -105], [ 40,35], /STATION, /DATA, THICK=2 WF_DRAW, [ -100, -90, -90], [ 30,35,40], /CONVERG, /DATA, THICK=2 x = [.015, .30] y = 0.04 dy = 0.05 ty = N_ELEMENTS(names) * dy + y POLYFILL, x[[0,1,1,0]],[0, 0, ty, ty],/NORM, COLOR=!P.BACKGROUND FOR i=0, N_ELEMENTS(names)-1 DO BEGIN WF_DRAW, x, y, /NORM, FRONT_TYPE=i, THICK=2 XYOUTS, x[1]+0.015, y[0], names[i], /NORM, CHARS=1.5 y = y + dy ENDFOR END See Also ANNOTATE, XYOUTS WHERE [Previous Routine] [Next Routine] [List of Routines] NAME: WHERE The WHERE function returns a longword vector that contains the one-dimensional subscripts of the nonzero elements of Array_Expression. The length of the resulting vector is equal to the number of nonzero elements in the parameter. Frequently the result of WHERE is used as a vector subscript to select elements of an array using given criteria. If all elements of Array_Expression are zero the result of WHERE is a scalar integer with the value ­1. Syntax Result = WHERE( Array_Expression [, Count] [, COMPLEMENT=variable] [, /L64] [, NCOMPLEMENT=variable] ) Result When WHERE Returns ­1 If all the elements of Array_Expression are zero, WHERE returns a scalar integer with a value of ­1. Attempting to use this result as an index into another array results in a "subscripts out of bounds" error. In situations where this is possible, code similar to the following can be used to avoid errors: ; Use Count to get the number of nonzero elements: index = WHERE(array, count) ; Only subscript the array if it's safe: IF count NE 0 THEN result = array[index] Arguments Array_Expression The array to be searched. Both the real and imaginary parts of a complex number must be zero for the number to be considered zero. Count A named variable that will receive the number of nonzero elements found in Array_Expression. This value is returned as a longword integer. Note The system variable !ERR is set to the number of nonzero elements. This effect is for compatibility with previous versions of IDL and should not be used in new code. Use the COUNT argument to return this value instead. Keywords COMPLEMENT Set this keyword to a named variable that receives the subscripts of the zero elements of Array_Expression. These are the subscripts that are not returned in Result. Together, Result and COMPLEMENT specify every subscript in Array_Expression. If there are no zero elements in Array_Expression, COMPLEMENT returns a scalar integer with the value -1. L64 By default, the result of WHERE is 32-bit integer when possible, and 64-bit integer if the number of elements being processed requires it. Set L64 to force 64-bit integers to be returned in all cases. Note Only 64-bit versions of IDL are capable of creating variables requiring a 64-bit result. Check the value of !VERSION.MEMORY_BITS to see if your IDL is 64-bit or not. NCOMPLEMENT Set this keyword to a named variable that receives the number of zero elements found in Array_Expression. This value is the number of subscripts that will be returned via the COMPLEMENT keyword if it is specified. Examples Example 1 ; Create a 10-element integer array where each element is ; set to the value of its subscript: array = INDGEN(10) PRINT, 'array = ', array ; Find the subscripts of all the elements in the array that have ; a value greater than 5: B = WHERE(array GT 5, count, COMPLEMENT=B_C, NCOMPLEMENT=count_c) ; Print how many and which elements met the search criteria: PRINT, 'Number of elements > 5: ', count PRINT, 'Subscripts of elements > 5: ', B PRINT, 'Number of elements <= 5: ', count_c PRINT, 'Subscripts of elements <= 5: ', B_C IDL prints: array = 0 1 2 3 4 5 6 7 8 9 Number of elements > 5: 4 Subscripts of elements > 5: 6 7 8 9 Number of elements <= 5: 6 Subscripts of elements <= 5: 0 1 2 3 4 5 Example 2 The WHERE function behaves differently with different kinds of array expressions. For instance, if a relational operator is used to compare an array, A, with a scalar, B, then every element of A is searched for B. However, if a relational operator is used to compare two arrays, C and D, then a comparison is made between each corresponding element (i.e. Ci & Di, Ci+1 & Di+1, etc) of the two arrays. If the two arrays have different lengths then a comparison is only made up to the number of elements for the shorter array. The following example illustrates this behavior: ; Compare array, a, and scalar, b: a = [1,2,3,4,5,5,4,3,2,1] b = 5 PRINT, 'a = ', a PRINT, 'b = ', b result=WHERE(a EQ b) PRINT,'Subscripts of a that equal b: ', result ; Now compare two arrays of different lengths: c = [1,2,3,4,5,5,4,3,2,1] d = [0,2,4] PRINT, 'c = ', c PRINT, 'd = ', d result=WHERE(c EQ d) PRINT, 'Subscripts of c that equal d: ', result IDL prints: a = 1 2 3 4 5 5 4 3 2 1 b = 5 Subscripts of a that equal b: 4 5 c = 1 2 3 4 5 5 4 3 2 1 d = 0 2 4 Subscripts of c that equal d: 1 Note that WHERE found only one element in the array d that equals an element in array c. This is because only the first three elements of c were searched, since d has only three elements. See Also UNIQ WHILE...DO [Previous Routine] [Next Routine] [List of Routines] NAME: WHILE...DO The WHILE...DO statement performs its subject statement(s) as long as the expression evaluates to true. The subject is never executed if the condition is initially false. Note For information on using WHILE...DO and other IDL program control statements, see Chapter 11, "Program Control" in Building IDL Applications. Syntax WHILE expression DO statement or WHILE expression DO BEGIN statements ENDWHILE Example i = 0 WHILE (i EQ 1) DO PRINT, i Because the expression (which is false in this case) is evaluated before the subject statement is executed, this code yields no output. WIDGET_BASE [Previous Routine] [Next Routine] [List of Routines] NAME: WIDGET_BASE The WIDGET_BASE function is used to create base widgets. Base widgets serve as containers for other widgets. Note In most cases, you will want let IDL determine the placement of widgets within the base widget. Do this by specifying either the COLUMN keyword or the ROW keyword. See "Positioning Child Widgets Within a Base" on page 1536 for details. The returned value of this function is the widget ID of the newly-created base. Syntax Result = WIDGET_BASE( [Parent] [, CONTEXT_MENU] [, /ALIGN_BOTTOM | , /ALIGN_CENTER | , /ALIGN_LEFT | , /ALIGN_RIGHT | , /ALIGN_TOP] [, APP_MBAR=variable{same as mbar on Windows and Motif} | , /MBAR | , /MODAL] [, /BASE_ALIGN_BOTTOM | , /BASE_ALIGN_CENTER | , /BASE_ALIGN_LEFT | , /BASE_ALIGN_RIGHT | , /BASE_ALIGN_TOP] [, /COLUMN | , /ROW] [, EVENT_FUNC=string] [, EVENT_PRO=string] [, /EXCLUSIVE | , /NONEXCLUSIVE] [, /FLOATING] [, FRAME=width] [, FUNC_GET_VALUE=string] [, /GRID_LAYOUT] [, GROUP_LEADER=widget_id{must specify for modal dialogs}] [, /KBRD_FOCUS_EVENTS] [, KILL_NOTIFY=string] [, /MAP{not for modal bases}] [, /NO_COPY] [, NOTIFY_REALIZE=string] [, PRO_SET_VALUE=string] [, SCR_XSIZE=width] [, SCR_YSIZE=height] [, /SCROLL{not for modal bases}] [, /SENSITIVE] [, SPACE=value{ignored if exclusive or nonexclusive}] [, TITLE=string] [, TLB_FRAME_ATTR=value{top- level bases only}] [, /TLB_KILL_REQUEST_EVENTS{top-level bases only}] [, /TLB_SIZE_EVENTS{top-level bases only}] [, /TRACKING_EVENTS] [, UNAME=string] [, UNITS={0 | 1 | 2}] [, UVALUE=value] [, XOFFSET=value] [, XPAD=value{ignored if exclusive or nonexclusive}] [, XSIZE=value] [, X_SCROLL_SIZE=value] [, YOFFSET=value] [, YPAD=value{ignored if exclusive or nonexclusive}] [, YSIZE=value] [, Y_SCROLL_SIZE=value] ) X Windows Keywords: [, DISPLAY_NAME=string] [, RESOURCE_NAME=string] [, RNAME_MBAR=string] Arguments Parent The widget ID of the parent widget. To create a top-level base, omit the Parent argument. Keywords CONTEXT_MENU (Windows, UNIX only) Set this new keyword to generate context events when the right mouse button is pressed over the widget. To request right mouse button events in a draw widget use the BUTTON_EVENTS keyword to WIDGET_DRAW at creation or the DRAW_BUTTON_EVENTS keyword to WIDGET_CONTROL for an existing draw widget. A right button press generates a WIDGET_DRAW event with the EVENT.TYPE field equal to 0 and the EVENT.RELEASE field equal to 4. ALIGN_BOTTOM Set this keyword to align the new widget with the bottom of its parent base. To take effect, the parent must be a ROW base. ALIGN_CENTER Set this keyword to align the new widget with the center of its parent base. To take effect, the parent must be a ROW or COLUMN base. In ROW bases, the new widget will be vertically centered. In COLUMN bases, the new widget will be horizontally centered. ALIGN_LEFT Set this keyword to align the new widget with the left side of its parent base. To take effect, the parent must be a COLUMN base. ALIGN_RIGHT Set this keyword to align the new widget with the right side of its parent base. To take effect, the parent must be a COLUMN base. ALIGN_TOP Set this keyword to align the new widget with the top of its parent base. To take effect, the parent must be a ROW base. APP_MBAR Set this keyword to a named variable that defines a widget application's menubar. On the Macintosh, the menubar defined by APP_MBAR becomes the system menubar (the menubar at the top of the Macintosh screen). On Motif platforms and under Microsoft Windows, the APP_MBAR is treated in exactly the same fashion as the menubar created with the MBAR keyword. See "MBAR" on page 1524 for details on creating menubars. Warning You cannot specify both an APP_MBAR and an MBAR for the same top-level base widget. Doing so will cause an error. To apply actions triggered by menu items to widgets other than the base that includes the menubar, use the KBRD_FOCUS_EVENTS keyword to keep track of which widget has (or last had) the keyboard focus. BASE_ALIGN_BOTTOM Set this keyword to make all children of the new base align themselves with the bottom of the base by default. To take effect, you must also set the ROW keyword for the new base. The default can be overridden for individual child widgets by setting a different ALIGN_XXX keyword when the child widget is created. BASE_ALIGN_CENTER Set this keyword to make all children of the new base align themselves with the center of the base by default. To take effect, you must also set the COLUMN or ROW keyword for the new base. The default can be overridden for individual child widgets by setting a different ALIGN_XXX keyword when the child widget is created. In ROW bases, child widgets will be vertically centered. In COLUMN bases, child widgets will be horizontally centered. BASE_ALIGN_LEFT Set this keyword to make all children of the new base align themselves with the left side of the base by default. To take effect, you must also set the COLUMN keyword for the new base. The default can be overridden for individual child widgets by setting a different ALIGN_XXX keyword when the child widget is created. BASE_ALIGN_RIGHT Set this keyword to make all children of the new base align themselves with the right side of the base by default. To take effect, you must also set the COLUMN keyword for the new base. The default can be overridden for individual child widgets by setting a different ALIGN_XXX keyword when the child widget is created. BASE_ALIGN_TOP Set this keyword to make all children of the new base align themselves with the top of the base by default. To take effect, you must also set the ROW keyword for the new base. The default can be overridden for individual child widgets by setting a different ALIGN_XXX keyword when the child widget is created. COLUMN If this keyword is included, the base lays out its children in columns. The value of this keyword specifies the number of columns to be used. The number of child widgets in each column is calculated by dividing the number of child widgets created by the number of columns specified. When one column is filled, a new one is started. Specifying both the COLUMN and ROW keywords causes an error. Column Width The width of each column is determined by the width of the widest widget in that column. If the GRID_LAYOUT keyword is set, all columns are as wide as the widest widget in the base. Horizontal Size of Widgets If any of the BASE_ALIGN_* keywords to WIDGET_BASE is set, each widget has its "natural" width, determined either by the value of the widget or by the XSIZE keyword. Similarly, if any of the child widgets specifies one of the ALIGN_* keywords, that widget will have its "natural" width. If none of the BASE_ALIGN_* or (ALIGN_*) keywords are set, all widgets in the base are as wide as their column. Vertical Placement Child widgets are placed vertically one below the other, with no extra space. If the GRID_LAYOUT keyword is set, each row is as high as its tallest member. DISPLAY_NAME Set this keyword equal to a string that specifies the name of the X Windows display on which the base should be displayed. This keyword has no effect on Microsoft Windows and Macintosh platforms. EVENT_FUNC A string containing the name of a function to be called by the WIDGET_EVENT function when an event arrives from a widget in the widget hierarchy rooted at the newly-created widget. EVENT_PRO A string containing the name of a procedure to be called by the WIDGET_EVENT function when an event arrives from a widget in the widget hierarchy rooted at the newly-created widget. Note If the base is a top-level base widget that is managed by the XMANAGER procedure, any value specified via the EVENT_PRO keyword is overridden by the value of the EVENT_HANDLER keyword to XMANAGER. Note also that in this situation, if EVENT_HANDLER is not specified in the call to XMANAGER, an event-handler name will be created by appending the string "_event" to the application name specified to XMANAGER. This means that there is no reason to specify this keyword for a top-level base that will be managed by the XMANAGER procedure. EXCLUSIVE Set this keyword to specify that the base can have only button-widget children and that only one button can be set at a time. These buttons, unlike normal button widgets, have two states-set and unset. When one exclusive button is pressed, any other exclusive buttons (in the same base) that are currently set are automatically released. Hence, only one button can ever be set at one time. This keyword can be used to create exclusive button menus. See the CW_BGROUP and CW_PDMENU functions for high-level menu-creation utilities. Note If this keyword is set, the XOFFSET and YOFFSET keywords are ignored for any widgets in this base. Exclusive bases are always laid out in columns or rows. If neither the COLUMN nor ROW keyword is specified for an exclusive base, the base defaults to COLUMN layout. FLOATING Set this keyword-along with the GROUP_LEADER keyword-to create a "floating" top-level base widget. If the windowing system provides Z-order control, floating base widgets appear above the base specified as their group leader. If the windowing system does not provide Z-order control, the FLOATING keyword has no effect. The iconizing, layering, and destruction behavior of floating bases and their group leaders is discussed in "Iconizing, Layering, and Destroying Groups of Top-Level Bases" on page 1536. FRAME The value of this keyword specifies the width of a frame in units specified by the UNITS keyword (pixels are the default) to be drawn around the borders of the widget. Note that this keyword is only a hint to the toolkit, and may be ignored in some instances. FUNC_GET_VALUE A string containing the name of a function to be called when the GET_VALUE keyword to the WIDGET_CONTROL procedure is called for this widget. Using this technique allows you to change the value that should be returned for a widget. Compound widgets use this ability to define their values transparently to the user. GRID_LAYOUT Set this keyword to force the base to have a grid layout, in which all rows have the same height, and all columns have the same width. The row heights and column widths are taken from the largest child widget. GROUP_LEADER The widget ID of an existing widget that serves as "group leader" for the newly- created widget. Widget application hierarchies are defined by group membership relationships between top-level widget bases. When a group leader is killed, for any reason, all widgets in the group are also destroyed. Iconizing and layering behavior is discussed in "Iconizing, Layering, and Destroying Groups of Top-Level Bases" on page 1536. (This is not available on the Mac.) Note If you specify a floating base (created with the FLOATING keyword) as a group leader, all member bases must also have either the FLOATING or MODAL keywords set. If you specify a modal base (created with the MODAL keyword) as a group leader, all member bases must have the MODAL keyword set as well. A given widget can be in more than one group. The WIDGET_CONTROL procedure can be used to add additional group associations to a widget. It is not possible to remove a widget from an existing group. KBRD_FOCUS_EVENTS Set this keyword to make the base return keyboard focus events whenever the keyboard focus of the base changes. See the "Events" section below for more information. KILL_NOTIFY Set this keyword to a string that contains the name of a procedure to be called automatically when the specified widget dies. Each widget is allowed a single such "callback" procedure. It can be removed by setting the routine to the null string (''). Note that the procedure specified is used only if you are not using the XMANAGER procedure to manage your widgets. The callback routine is called with the widget identifier as its only argument. At that point, the widget identifier can only be used with the WIDGET_CONTROL procedure to get or set the user value. All other requests that require a widget ID are disallowed for the target widget. The callback is not issued until the WIDGET_EVENT function is called. If you use the XMANAGER procedure to manage your widgets, the value of this keyword is overwritten. Use the CLEANUP keyword to XMANAGER to specify a procedure to be called when a managed widget dies. MAP Once a widget hierarchy has been realized, it can be mapped (visible) or unmapped (invisible). This keyword specifies the initial map state for the given base and its descendants. Specifying a non-zero value indicates that the base should be mapped when realized (the default). A zero value indicates that the base should be unmapped initially. After the base is realized, its map state can be altered using the MAP keyword to the WIDGET_CONTROL procedure. Note Modal bases cannot be mapped and unmapped. Warning Under Microsoft Windows, when a hidden base is realized, then mapped, a Windows resize message is sent by the windowing system. This "extra" resize event is generated before any manipulation of the base widget by the user. MBAR Set this keyword to a named variable to cause a menubar to be placed at the top of the base (the base must be a top-level base). The menubar is itself a special kind of base widget that can only have buttons as children. Upon return, the named variable contains the widget ID of the new menubar base. This widget ID can then be used to fill the menubar with pulldown menus. For example, the following widget creation commands first create a base with a menubar, then populate the menubar with a simple pulldown menu (CW_PDMENU could also have been used to construct the pulldown menu): base = WIDGET_BASE(TITLE = 'Example', MBAR=bar) file_menu = WIDGET_BUTTON(bar, VALUE='File', /MENU) file_bttn1=WIDGET_BUTTON(file_menu, VALUE='Item 1',$ UVALUE='FILE1') file_bttn2=WIDGET_BUTTON(file_menu, VALUE='Item 2',$ UVALUE='FILE2') Note that to set X Window System resources for menubars created with this keyword, you must use the RNAME_MBAR keyword rather than the RESOURCE_NAME keyword. If you use CW_PDMENU to create a menu for the menubar, be sure to set the MBAR keyword to that function as well. Note also that the size returned by the GEOMETRY keyword to WIDGET_INFO does not include the size of the menubar. Note To control the system menubar on the Macintosh, use the APP_MBAR keyword. On Windows and Motif platforms the MBAR and APP_MBAR keywords are equivalent. Warning You cannot specify both the MBAR and MODAL keywords for the same widget. Doing so will cause an error. To apply actions triggered by menu items to widgets other than the base that includes the menubar, use the KBRD_FOCUS_EVENTS keyword to keep track of which widget has (or last had) the keyboard focus. MODAL Set this keyword to create a modal dialog. Modal dialogs can have default and cancel buttons associated with them. Default buttons are highlighted by the window system and respond to a press on the "Return" or "Enter" keys as if they had been clicked on. Cancel buttons respond to a press on the "Escape" key as if they had been clicked on. See the DEFAULT_BUTTON and CANCEL_BUTTON keywords to WIDGET_CONTROL for details. Note Modal dialogs must have a group leader. Specify the group leader for a modal top- level base via the GROUP_LEADER keyword. Modal dialogs cannot be scrollable, nor can they support menubars. Setting the SCROLL, MBAR, or APP_MBAR keywords in conjunction with the MODAL keyword will cause an error. Modal dialogs cannot be mapped or unmapped. Setting the MAP keyword on a modal base will cause an error. Note On Windows platforms, the group leader of a modal base must be realized before the modal base itself can be realized. If the group leader has not been realized, it will be realized automatically. The iconizing, layering, and destruction behavior of modal bases and their group leaders is discussed in "Iconizing, Layering, and Destroying Groups of Top-Level Bases" on page 1536. NO_COPY Usually, when setting or getting widget user values, either at widget creation or using the SET_UVALUE and GET_UVALUE keywords to WIDGET_CONTROL, IDL makes a second copy of the data being transferred. Although this technique is fine for small data, it can have a significant memory cost when the data being copied is large. If the NO_COPY keyword is set, IDL handles these operations differently. Rather than copy the source data, it takes the data away from the source and attaches it directly to the destination. This feature can be used by compound widgets to obtain state information from a UVALUE without all the memory copying that would otherwise occur. However, it has the side effect of causing the source variable to become undefined. On a "set" operation (using the UVALUE keyword to WIDGET_BASE or the SET_UVALUE keyword to WIDGET_CONTROL), the variable passed as value becomes undefined. On a "get" operation (GET_UVALUE keyword to WIDGET_CONTROL), the user value of the widget in question becomes undefined. NONEXCLUSIVE Set this keyword to specify that the base can only have button widget children. These buttons, unlike normal button widgets, have two states-set and unset. Non-exclusive bases allow any number of the toggle buttons to be set at one time. Note If this keyword is set, the XOFFSET and YOFFSET keywords are ignored for any widgets in this base. Non-exclusive bases are always laid out in columns or rows. If neither the COLUMN nor ROW keyword is specified for a non-exclusive base, the base defaults to COLUMN layout. NOTIFY_REALIZE Set this keyword to a string that contains the name of a procedure to be called automatically when the specified widget is realized. This callback occurs just once (because widgets are realized only once). Each widget is allowed a single such "callback" procedure. It can be removed by setting the routine to the null string (''). The callback routine is called with the widget ID as its only argument. PRO_SET_VALUE A string containing the name of a procedure to be called when the SET_VALUE keyword to the WIDGET_CONTROL procedure is called for this widget. Using this technique allows you to designate a routine that sets the value for a widget. Compound widgets use this ability to define their values transparently to the user. RESOURCE_NAME A string containing an X Window System resource name to be applied to the widget. Once defined, this name can be used in the user's .Xdefaults file to customize widget resources not directly supported via the IDL widget routines. This keyword is accepted by all widget creation routines. This keyword only works with the "X" device and is ignored on platforms that do not use the X Window System (i.e., IDL for Windows, IDL for Macintosh). RESOURCE_NAME allows unrestricted access to the underlying Motif widgets within the following limitations: * Users must have the appropriate resources defined in their .Xdefaults or application default resource file, or IDL will not see the definitions and they will not take effect. * Motif resources are documented in the OSF/Motif Programmer's Reference Manual. To use them with RESOURCE_NAME, the IDL programmer must determine the type of widget being used by IDL, and then look up the resources that apply to them. Hence, RESOURCE_NAME requires some programmer-level familiarity with Motif. * Only resources that are not set within IDL can be modified using this mechanism. Although it is not an error to set resources also set by IDL, the IDL settings will silently override user settings. Research Systems does not document the resources used by IDL since the actual resources used may differ from release to release as the IDL widgets evolve. Therefore, you should set only those resources that are obviously not being set by IDL. Among the resources that are not being set by IDL are those that control colors, menu mnemonics, and accelerator keys. Example The sample code below produces a pulldown menu named "Menu" with 2 entries named "Item 1" and "Item 2". Using the RESOURCE_NAME keyword in conjunction with X resource definitions, we can alter "Item 1" in several ways not possible through the standard IDL widgets interface. We'll give Item 1 a red background color. We'll also assign "I" as the keyboard mnemonic. Note that Motif automatically underlines the "I" in the title to indicate this. We'll also select Meta-F4 as the keyboard accelerator for selecting "Item 1". If Meta-F4 is pressed while the pointer is anywhere over this application, the effect will be as if the menu was pulled down and "Item 1" was selected with the mouse. ; Simple event handler: PRO test_event, ev HELP, /STRUCTURE, ev END ; Simple widget creation routine: PRO test ; The base gets the resource name "test": a = WIDGET_BASE(RESOURCE_NAME = 'test') b = WIDGET_BUTTON(a, VALUE='Menu', /MENU) ; Assign the Item 1 button the resource name "item1": c = WIDGET_BUTTON(b, VALUE='Item 1', $ RESOURCE_NAME='item1') c = WIDGET_BUTTON(b, VALUE='Item 2') WIDGET_CONTROL, /REALIZE, a XMANAGER, 'test', a END Note that we gave the overall application the resource name "test", and the "Item 1" button the resource name "item1". Now we can use these names in the following .Xdefaults file entries: Idl*test*item1*mnemonic: I Idl*test*item1*accelerator: MetaF4 Idl*test*item1*acceleratorText: Meta-F4 Idl*test*item1*background: red Note on Specifying Color Resources If you wish to specify unique colors for your widgets, it is generally a good idea to use a color name ("red" or "lightblue", for example) rather than specifying an exact color match with a color string (such as "#b1b122222020"). If IDL is not able to allocate an exact color, the entire operation may fail. Specifying a named color implies "closest color match," an operation that rarely fails. If you need an exact color match and IDL fails to allocate the color, try modifying the Idl.colors resource in the $IDL_DIR/resource/X11/lib/app- defaults/Idl file. RNAME_MBAR A string containing an X Window System resource name to be applied to the menubar created by the MBAR keyword. This keyword is identical to the RESOURCE_NAME keyword except that the resource it specifies applies only to the menubar. ROW If this keyword is included, the base lays out its children in rows. The value of this keyword specifies the number of rows to be used. The number of child widgets in each row is calculated by dividing the number of child widgets created by the number of rows specified. When one row is filled, a new one is started. Specifying both the COLUMN and ROW keywords causes an error. Row Height The height of each row is determined by the height of the tallest widget in that row. If the GRID_LAYOUT keyword is set, all rows are as tall as the tallest widget in the base. Vertical Size of Widgets If any of the BASE_ALIGN_* keywords to WIDGET_BASE is set, each widget has its "natural" height, determined either by the value of the widget or by the YSIZE keyword. Similarly, if any of the child widgets specifies one of the ALIGN_* keywords, that widget will have its "natural" height. If none of the BASE_ALIGN_* or (ALIGN_*) keywords are set, all widgets in the base are as tall as their row. Horizontal Placement Child widgets are placed horizontally one next to the other, with no extra space. If the GRID_LAYOUT keyword is set, each column is as wide as its widest member. SCR_XSIZE Set this keyword to the desired "screen" width of the widget, in units specified by the UNITS keyword (pixels are the default). In many cases, setting this keyword is the same as setting the XSIZE keyword. SCR_YSIZE Set this keyword to the desired "screen" height of the widget, in units specified by the UNITS keyword (pixels are the default). In many cases, setting this keyword is the same as setting the YSIZE keyword. SCROLL Set this keyword to give the widget scroll bars that allow viewing portions of the widget contents that are not currently on the screen. Note For the Macintosh, if you set XSIZE or YSIZE to a value less than 48, the base created with the SCROLL keyword will be a minimum of 48x48. If you have not specified values for XSIZE or YSIZE, the base will be set to a minimum of 66x66. If the base is resized, it will jump to the minimum size of 128x64. Warning You cannot specify both the SCROLL and MODAL keywords for the same widget. Doing so will cause an error. SENSITIVE Set this keyword to control the initial sensitivity state of the widget. If SENSITIVE is zero, the widget becomes insensitive. If nonzero, it becomes sensitive. When a widget is sensitive, it has normal appearance and can receive user input. For example, a sensitive button widget can be activated by moving the mouse cursor over it and pressing a mouse button. When a widget is insensitive, it indicates the fact by changing its appearance, looking disabled, and it ignores any input. Sensitivity can be used to control when a user is allowed to manipulate the widget. Note that some widgets do not change their appearance when they are made insensitive, but they cease generating events. After creating the widget hierarchy, you can change the sensitivity state using the SENSITIVE keyword with the WIDGET_CONTROL procedure. SPACE The space, in units specified by the UNITS keyword (pixels are the default), between children of a row or column major base. This keyword is ignored if either the EXCLUSIVE or NONEXCLUSIVE keyword is present. TITLE A string containing the title to be used for the widget. Base widgets use the title only if they are top-level widgets. Note that if the widget base is not wide enough to contain the specified title, the title may appear truncated. If you must be able to see the full title, you have several alternatives: * Rearrange the widgets in the base so that the base becomes naturally wide enough. This is the best solution. * Don't worry about this issue. If the user needs to see the entire label, they can resize the window using the mouse. * Create the base without using the COLUMN or ROW keywords. Instead, use the XSIZE keyword to explicitly set a usable width. This is an undesirable solution that can lead to strange-looking widget layouts. TLB_FRAME_ATTR Set this keyword to one of the values shown in the table below to suppress certain aspects of a top-level base's window frame. This keyword applies only to top-level bases. The settings are merely hints to the window system and may be ignored by some window managers. Valid settings are: Value Meaning 1 Base cannot be resized, minimized, or maximized. 2 Suppress display of system menu. Table 91: Valid Values for TLB_FRAME_ATTR Keyword Value Meaning 4 Suppress title bar. 8 Base cannot be closed. 16 Base cannot be moved. Table 91: Valid Values for TLB_FRAME_ATTR Keyword This keyword is set bitwise, so multiple effects can be set by adding values together. For example, to make a base that has no title bar (setting 4) and cannot be moved (setting 16), set the TLB_FRAME_ATTR keyword to 4+16, or 20. Note For the Macintosh, you can not suppress the title bar; only modal dialogs use a window without a title bar. Any other use of a suppressed title bar would be contrary to Macintosh Human Interface Guidelines and would create an immovable window. TLB_KILL_REQUEST_EVENTS Set this keyword, usable only with top-level bases, to send the top-level base a WIDGET_KILL_REQUEST event if a user tries to destroy the widget using the window manager (by default, widgets are simply destroyed). See the "Events" section below for more information. Use this keyword to perform complex actions before allowing a widget application to exit. Note that widgets that have this keyword set are responsible for killing themselves after receiving a WIDGET_KILL_REQUEST event-they cannot be destroyed using the usual window system controls. Use a call to TAG_NAMES with the STRUCTURE_NAME keyword set to differentiate a WIDGET_KILL_REQUEST event from other types of widget events. For example: IF TAG_NAMES(event, /STRUCTURE_NAME) EQ $ 'WIDGET_KILL_REQUEST' THEN ... TLB_SIZE_EVENTS Set this keyword, when creating a top-level base, to make that base return an event when the base is resized by the user. See the "Events" section below for more information. TRACKING_EVENTS Set this keyword to cause widget tracking events to be issued for the widget whenever the mouse pointer enters or leaves the region covered by that widget. Widget tracking events are returned as structures with the following definition: { WIDGET_TRACKING, ID:0L, TOP:0L, HANDLER:0L, ENTER:0 } ID, TOP, and HANDLER are the standard fields found in every widget event. ENTER is 1 if the tracking event is an entry event, and 0 if it is an exit event. UNAME Set this keyword to a string that can be used to identify the widget in your code. You can associate a name with each widget in a specific hierarchy, and then use that name to query the widget hierarchy and get the correct widget ID. To query the widget hierarchy, use the WIDGET_INFO function with the FIND_BY_UNAME keyword. The UNAME should be unique to the widget hierarchy because the FIND_BY_UNAME keyword returns the ID of the first widget with the specified name. UNITS Set UNITS equal to 0 (zero) to specify that all measurements are in pixels (this is the default), to 1 (one) to specify that all measurements are in inches, or to 2 (two) to specify that all measurements are in centimeters. UVALUE The "user value" to be assigned to the widget. Each widget can contain a user-specified value of any data type and organization. This value is not used by the widget in any way, but exists entirely for the convenience of the IDL programmer. This keyword allows you to set this value when the widget is first created. If UVALUE is not present, the widget's initial user value is undefined. The user value for a widget can be accessed and modified at any time by using the GET_UVALUE and SET_UVALUE keywords to the WIDGET_CONTROL procedure. XOFFSET The horizontal offset of the widget in units specified by the UNITS keyword (pixels are the default) relative to its parent. Specifying an offset relative to a row or column major base widget does not work because those widgets enforce their own layout policies. This keyword is primarily of use relative to a plain base widget. Note that it is best to avoid using this style of widget layout. XPAD The horizontal space, in units specified by the UNITS keyword (pixels are the default), between child widgets and the edges of a row or column major base. The default value of XPAD is platform dependent. This keyword is ignored if either the EXCLUSIVE or NONEXCLUSIVE keyword is present. XSIZE The width of the widget in units specified by the UNITS keyword (pixels are the default). Most widgets attempt to size themselves to fit the situation. However, if the desired effect is not produced, use this keyword to override it. This keyword is only a "hint" to the toolkit and may be ignored in some situations. X_SCROLL_SIZE The XSIZE keyword always specifies the width of a widget. When the SCROLL keyword is specified, this size is not necessarily the same as the width of the visible area. The X_SCROLL_SIZE keyword allows you to set the width of the scrolling viewport independently of the actual width of the widget. Use of the X_SCROLL_SIZE keyword implies SCROLL. This means that scroll bars will be added in both the horizontal and vertical directions when X_SCROLL_SIZE is specified. Because the default size of the scrolling viewport may differ between platforms, it is best to specify Y_SCROLL_SIZE when specifying X_SCROLL_SIZE. YOFFSET The vertical offset of the widget in units specified by the UNITS keyword (pixels are the default) relative to its parent. This offset is specified relative to the upper left corner of the parent widget. Specifying an offset relative to a row or column major base widget does not work because those widgets enforce their own layout policies. This keyword is primarily of use relative to a plain base widget. Note that it is best to avoid using this style of widget layout. YPAD The vertical space, in units specified by the UNITS keyword (pixels are the default), between child widgets and the edges of a row or column major base. The default value of YPAD is platform-dependent. This keyword is ignored if either the EXCLUSIVE or NONEXCLUSIVE keyword is present. YSIZE The height of the widget in units specified by the UNITS keyword (pixels are the default). Most widgets attempt to size themselves to fit the situation. However, if the desired effect is not produced, use this keyword to override it. This keyword is only a "hint" to the toolkit and may be ignored in some situations. Y_SCROLL_SIZE The YSIZE keyword always specifies the height of a widget. When the SCROLL keyword is specified, this size is not necessarily the same as the height of the visible area. The Y_SCROLL_SIZE keyword allows you to set the height of the scrolling viewport independently of the actual height of the widget. Use of the Y_SCROLL_SIZE keyword implies SCROLL. This means that scroll bars will be added in both the horizontal and vertical directions when Y_SCROLL_SIZE is specified. Because the default size of the scrolling viewport may differ between platforms, it is best to specify X_SCROLL_SIZE when specifying Y_SCROLL_SIZE. Keywords to WIDGET_CONTROL A number of keywords to the WIDGET_CONTROL procedure affect the behavior of base widgets. In addition to those keywords that affect all widgets, the following are particularly useful: CANCEL_BUTTON, DEFAULT_BUTTON, KBRD_FOCUS_EVENTS. Keywords to WIDGET_INFO A number of keywords to the WIDGET_INFO function return information that applies specifically to base widgets. In addition to those keywords that apply to all widgets, the following are particularly useful: KBRD_FOCUS_EVENTS, MODAL, TLB_KILL_REQUEST_EVENTS. Exclusive And Non-Exclusive Bases If the EXCLUSIVE or NONEXCLUSIVE keywords are specified, the base only allows button widget children. Positioning Child Widgets Within a Base The standard base widget does not impose any placement constraints on its child widgets. Children of a "bulletin board" base (a base that was created without setting the COLUMN or ROW keywords) have an offset of (0,0) unless an offset is explicitly specified via the XOFFSET or YOFFSET keywords. This means that if you do not specify any of COLUMN, ROW, XOFFSET, or YOFFSET keywords, child widgets will be placed one on top of the other in the upper left corner of the base. However, laying out widgets using the XSIZE, YSIZE, XOFFSET, and YOFFSET keywords can be both tedious and error-prone. Also, if you want your widget application to display properly on different platforms, you should use the COLUMN and ROW keywords to influence child widget layouts instead of explicitly formatting your interfaces. When the ROW or COLUMN keywords are specified, the base decides how to lay out its children, and any XOFFSET and YOFFSET keywords specified for such children are ignored. Positioning Top-Level Bases When locating a new top level window, some window managers ignore the program's positioning requests and either choose a position or allow the user to choose. In such cases, the XOFFSET and YOFFSET keywords to WIDGET_BASE will not have an effect. The window manager may provide a way to disable this positioning style. The Motif window manager (mwm) can be told to honor positioning requests by placing the following lines in your .Xdefaults file: Mwm*clientAutoPlace: False Mwm*interactivePlacement: False Iconizing, Layering, and Destroying Groups of Top-Level Bases Group membership (defined via the GROUP_LEADER keyword) controls the way top-level base widgets are iconized, layered, and destroyed. Note A group can contain sub-groups. Group behavior affects all members of a group and its sub-groups. For example, suppose we create three top-level base widgets with the following group hierarchy: base1 = WIDGET_BASE() base2 = WIDGET_BASE(GROUP_LEADER=base1) base3 = WIDGET_BASE(GROUP_LEADER=base2) Effectively, two groups are created. One group has base2 as its leader and base3 as its member. The other group has base1 as its leader and both base2 and base3 as members. If base1 is iconized, both base2 and base3 are iconized as well. If base2 is iconized, base3 is iconized but base1 is not. Widgets behave slightly differently when displayed on different platforms, and depending on whether they are floating or modal bases. The following rules apply to groups of widgets within a group leader/member hierarchy. Widgets that do not belong to the same group hierarchy cannot influence each other. Iconization and Mapping On Motif and Windows platforms, bases and groups of bases can be iconized (or minimized) by clicking the system minimize control. Minimization has no meaning on the Macintosh. On all platforms, bases and groups of bases can be mapped (made visible) and unmapped (made invisible). Motif When a group leader is iconized or unmapped, all members of the group are iconized or unmapped as well. Similarly, when a group leader is restored, all members of the group are restored. Floating and modal bases cannot be iconized or unmapped independently. When the group leader of a floating or modal base is iconized, a single icon is created for both the group leader and the floating or modal base. When the group leader of a floating or modal base is unmapped, both the group leader and floating or modal base are made invisible. Windows When a group leader is iconized or unmapped, all members of the group are iconized or unmapped as well. Similarly, when a group leader is restored, all members of the group are restored. When a floating base is iconized, its group leader is iconized as well and a single icon is created. When a floating base is unmapped, its group leader is unmapped as well. Modal bases cannot be iconized or unmapped. Other bases cannot be iconized or unmapped until the modal base is dismissed. Macintosh On the Macintosh, iconization has no meaning. When a floating base is unmapped, its group leader is unmapped as well. Modal bases cannot be unmapped. Other bases cannot be unmapped until the modal base is dismissed. Layering Layering is the process by which groups of widgets seem to share the same plane on the display screen. Within a layer on the screen, widgets have a Z-order, or front-to- back order, that defines which widgets appear to be on top of other widgets. Motif All elements on the screen-widgets, the IDLDE, other Motif applications-share a single layer and have an arbitrary Z-order. There is no special layering of IDL widgets. Windows and Macintosh All non-floating and non-modal widgets within a group hierarchy share the same layer-that is, when one group member has the input focus, all members of the group hierarchy are displayed in a layer that appears in front of all other groups or applications. Within the layer, the widgets can have an arbitrary Z-order. Widgets that are floating or modal always float above their group leaders. Destruction When a group leader widget is destroyed, either programmatically or by clicking on the system "close" button, all members of the group and all sub-groups are destroyed as well. If a modal base is on the display, it must be dismissed before any widget can be destroyed. Events Resize Events Top-level widget bases return the following event structure only when they are resized by the user and the base was created with the TLB_SIZE_EVENTS keyword set: { WIDGET_BASE, ID:0L, TOP:0L, HANDLER:0L, X:0L, Y:0L } ID is the widget ID of the base generating the event. TOP is the widget ID of the top level widget containing ID. HANDLER contains the widget ID of the widget associated with the handler routine. The X and Y fields return the new width of the base, not including any frame provided by the window manager. Keyboard Focus Events Widget bases return the following event structure when the keyboard focus changes and the base was created with the KBRD_FOCUS_EVENTS keyword set: { WIDGET_KBRD_FOCUS, ID:0L, TOP:0L, HANDLER:0L, ENTER:0 } ID is the widget ID of the base generating the event. TOP is the widget ID of the top level widget containing ID. HANDLER contains the widget ID of the widget associated with the handler routine. The ENTER field returns 1 (one) if the base is gaining the keyboard focus, or 0 (zero) if the base is losing the keyboard focus. Kill Request Events Top-level widget bases return the following event structure only when a user tries to destroy the widget using the window manager and the base was created with the TLB_KILL_REQUEST_EVENTS keyword set: { WIDGET_KILL_REQUEST, ID:0L, TOP:0L, HANDLER:0L } ID is the widget ID of the base generating the event. TOP is the widget ID of the top level widget containing ID. HANDLER contains the widget ID of the widget associated with the handler routine. WIDGET_BUTTON [Previous Routine] [Next Routine] [List of Routines] NAME: WIDGET_BUTTON The WIDGET_BUTTON function creates button widgets. The returned value of this function is the widget ID of the newly-created button. Syntax Result = WIDGET_BUTTON( Parent [, /ALIGN_CENTER | , /ALIGN_LEFT | , /ALIGN_RIGHT] [, /BITMAP] [, /DYNAMIC_RESIZE] [, EVENT_FUNC=string] [, EVENT_PRO=string] [, FONT=string] [, FRAME=width] [, FUNC_GET_VALUE=string] [, GROUP_LEADER=widget_id] [, /HELP] [, KILL_NOTIFY=string] [, /MENU] [, /NO_COPY] [, /NO_RELEASE] [, NOTIFY_REALIZE=string] [, PRO_SET_VALUE=string] [, SCR_XSIZE=width] [, SCR_YSIZE=height] [, /SENSITIVE] [, /SEPARATOR] [, /TRACKING_EVENTS] [, UNAME=string] [, UNITS={0 | 1 | 2}] [, UVALUE=value] [, VALUE=value] [, X_BITMAP_EXTRA=bits] [, XOFFSET=value] [, XSIZE=value] [, YOFFSET=value] [, YSIZE=value] ) X Windows Keywords: [, RESOURCE_NAME=string] Arguments Parent The widget ID of the parent for the new button widget. Keywords ALIGN_CENTER Set this keyword to center justify the button's text label. ALIGN_LEFT Set this keyword to left justify the button's text label. ALIGN_RIGHT Set this keyword to right justify the button's text label. BITMAP Set this keyword to specify that the bitmap specified with the VALUE keyword is a color bitmap. The value of a widget button can be a bitmap as described below under "Bitmap Button Labels". If you specify a color bitmap with the VALUE keyword, you must also set the /BITMAP keyword. DYNAMIC_RESIZE Set this keyword to create a widget that resizes itself to fit its new value whenever its value is changed. Note that this keyword does not take effect when used with the SCR_XSIZE, SCR_YSIZE, XSIZE, or YSIZE keywords. If one of these keywords is also set, the widget will be sized as specified by the sizing keyword and will never resize itself dynamically. EVENT_FUNC A string containing the name of a function to be called by the WIDGET_EVENT function when an event arrives from a widget in the widget hierarchy rooted at the newly-created widget. EVENT_PRO A string containing the name of a procedure to be called by the WIDGET_EVENT function when an event arrives from a widget in the widget hierarchy rooted at the newly-created widget. FONT The name of the font to be used by the widget. The font specified is a "device font" (an X Windows font on Motif systems; a TrueType or PostScript font on Windows or Macintosh systems). See "About Device Fonts" on page 2482 for details on specifying names for device fonts. If this keyword is omitted, the default font is used. Note On Microsoft Windows platforms, if FONT is not specified, IDL uses the system default font. Different versions of Windows use different system default fonts; in general, the system default font is the font appropriate for the version of Windows in question. FRAME The value of this keyword specifies the width of a frame in units specified by the UNITS keyword (pixels are the default) to be drawn around the borders of the widget. Note that this keyword is only a "hint" to the toolkit, and may be ignored in some instances. FUNC_GET_VALUE A string containing the name of a function to be called when the GET_VALUE keyword to the WIDGET_CONTROL procedure is called for this widget. Using this technique allows you to change the value that should be returned for a widget. Compound widgets use this ability to define their values transparently to the user. GROUP_LEADER The widget ID of an existing widget that serves as "group leader" for the newly- created widget. When a group leader is killed, for any reason, all widgets in the group are also destroyed. A given widget can be in more than one group. The WIDGET_CONTROL procedure can be used to add additional group associations to a widget. It is not possible to remove a widget from an existing group. HELP Set this keyword to tell the widget toolkit that this button is a "help" button for a menubar and should be given that appearance. For example, Motif specifies that the help menubar item is displayed on the far right of the menubar. This keyword is ignored in all other contexts and may be ignored by window managers (including that for the Macintosh) that have no such special appearance defined. KILL_NOTIFY Set this keyword to a string that contains the name of a procedure to be called automatically when the specified widget dies. Each widget is allowed a single such "callback" procedure. It can be removed by setting the routine to the null string (''). Note that the procedure specified is used only if you are not using the XMANAGER procedure to manage your widgets. The callback routine is called with the widget identifier as its only argument. At that point, the widget identifier can only be used with the WIDGET_CONTROL procedure to get or set the user value. All other requests that require a widget ID are disallowed for the target widget. The callback is not issued until the WIDGET_EVENT function is called. If you use the XMANAGER procedure to manage your widgets, the value of this keyword is overwritten. Use the CLEANUP keyword to XMANAGER to specify a procedure to be called when a managed widget dies. MENU The presence of this keyword indicates that the button will be used to activate a pull- down menu. Such buttons can have button children that are then placed into a pull- down menu. Under Motif, if the value specified for MENU is greater than 1, the button label is enclosed in a box to indicate that this button is a pull-down menu. See the CW_PDMENU function for a high-level pull-down menu creation utility. NO_COPY Usually, when setting or getting widget user values, either at widget creation or using the SET_UVALUE and GET_UVALUE keywords to WIDGET_CONTROL, IDL makes a second copy of the data being transferred. Although this technique is fine for small data, it can have a significant memory cost when the data being copied is large. If the NO_COPY keyword is set, IDL handles these operations differently. Rather than copy the source data, it takes the data away from the source and attaches it directly to the destination. This feature can be used by compound widgets to obtain state information from a UVALUE without all the memory copying that would otherwise occur. However, it has the side effect of causing the source variable to become undefined. On a "set" operation (using the UVALUE keyword to WIDGET_BUTTON or the SET_UVALUE keyword to WIDGET_CONTROL), the variable passed as value becomes undefined. On a "get" operation (GET_UVALUE keyword to WIDGET_CONTROL), the user value of the widget in question becomes undefined. NO_RELEASE Set this keyword to make exclusive and non-exclusive buttons generate only select events. This keyword has no effect on regular buttons. NOTIFY_REALIZE Set this keyword to a string that contains the name of a procedure to be called automatically when the specified widget is realized. This callback occurs just once (because widgets are realized only once). Each widget is allowed a single such "callback" procedure. It can be removed by setting the routine to the null string (''). The callback routine is called with the widget ID as its only argument. PRO_SET_VALUE A string containing the name of a procedure to be called when the SET_VALUE keyword to the WIDGET_CONTROL procedure is called for this widget. Using this technique allows you to designate a routine that sets the value for a widget. Compound widgets use this ability to define their values transparently to the user. RESOURCE_NAME A string containing an X Window System resource name to be applied to the widget. See "RESOURCE_NAME" on page 1527 for a complete discussion of this keyword. SCR_XSIZE Set this keyword to the desired "screen" width of the widget, in units specified by the UNITS keyword (pixels are the default). In many cases, setting this keyword is the same as setting the XSIZE keyword. SCR_YSIZE Set this keyword to the desired "screen" height of the widget, in units specified by the UNITS keyword (pixels are the default). In many cases, setting this keyword is the same as setting the YSIZE keyword. SENSITIVE Set this keyword to control the initial sensitivity state of the widget. If SENSITIVE is zero, the widget becomes insensitive. If nonzero, it becomes sensitive. When a widget is sensitive, it has normal appearance and can receive user input. For example, a sensitive button widget can be activated by moving the mouse cursor over it and pressing a mouse button. When a widget is insensitive, it indicates the fact by changing its appearance, looking disabled, and it ignores any input. Sensitivity can be used to control when a user is allowed to manipulate the widget. Note that some widgets do not change their appearance when they are made insensitive, but they cease generating events. After creating the widget hierarchy, you can change the sensitivity state using the SENSITIVE keyword with the WIDGET_CONTROL procedure. SEPARATOR Set this keyword to tell the widget toolkit that this button is part of a pulldown menu pane and that a separator line should be added directly above this entry. This keyword is ignored in all other contexts. TRACKING_EVENTS Set this keyword to cause widget tracking events to be issued for the widget whenever the mouse pointer enters or leaves the region covered by that widget. For the structure of tracking events, see "TRACKING_EVENTS" on page 1533 in the documentation for WIDGET_BASE. UNAME Set this keyword to a string that can be used to identify the widget in your code. You can associate a name with each widget in a specific hierarchy, and then use that name to query the widget hierarchy and get the correct widget ID. To query the widget hierarchy, use the WIDGET_INFO function with the FIND_BY_UNAME keyword. The UNAME should be unique to the widget hierarchy because the FIND_BY_UNAME keyword returns the ID of the first widget with the specified name. UNITS Set UNITS equal to 0 (zero) to specify that all measurements are in pixels (this is the default), to 1 (one) to specify that all measurements are in inches, or to 2 (two) to specify that all measurements are in centimeters. UVALUE The "user value" to be assigned to the widget. Each widget can contain a user-specified value of any data type and organization. This value is not used by the widget in any way, but exists entirely for the convenience of the IDL programmer. This keyword allows you to set this value when the widget is first created. If UVALUE is not present, the widget's initial user value is undefined. VALUE The initial value setting of the widget. The value of a widget button is the label for that button. This label can be a string or a bitmap as described below under "Bitmap Button Labels". If you specify the filename for a color bitmap, you must also set the /BITMAP keyword. Note Under Microsoft Windows, including the ampersand character (&) in the value of a button widget causes the window manager to place an underline under the character following the ampersand. (This is a feature of Microsoft Windows, and is generally used to indicate which character is used as a keyboard accelerator for the button.) If you are designing an application that will run on different platforms, you should avoid the use of the ampersand in button value strings. X_BITMAP_EXTRA When creating a bitmap button that is not of a "byte-aligned" size (i.e., a dimension is not a multiple of 8), this keyword specifies how many bits of the supplied bitmap must be ignored (within the end byte). For example, to create a 10 by 8 bitmap, you need to supply a 2 by 8 array of bytes and ignore the bottom 6 bits. Therefore, you would specify X_BITMAP_EXTRA = 6. XOFFSET The horizontal offset of the widget in units specified by the UNITS keyword (pixels are the default) relative to its parent. Specifying an offset relative to a row or column major base widget does not work because those widgets enforce their own layout policies. This keyword is primarily of use relative to a plain base widget. Note that it is best to avoid using this style of widget programming. XSIZE The width of the widget in units specified by the UNITS keyword (pixels are the default). Most widgets attempt to size themselves to fit the situation. However, if the desired effect is not produced, use this keyword to override it. This keyword is only a "hint" to the toolkit and may be ignored in some situations. YOFFSET The vertical offset of the widget in units specified by the UNITS keyword (pixels are the default) relative to its parent. This offset is specified relative to the upper left corner of the parent widget. Specifying an offset relative to a row or column major base widget does not work because those widgets enforce their own layout policies. This keyword is primarily of use relative to a plain base widget. Note that it is best to avoid using this style of widget programming. YSIZE The height of the widget in units specified by the UNITS keyword (pixels are the default). Most widgets attempt to size themselves to fit the situation. However, if the desired effect is not produced, use this keyword to override it. This keyword is only a "hint" to the toolkit and may be ignored in some situations. Keywords to WIDGET_CONTROL A number of keywords to the WIDGET_CONTROL procedure affect the behavior of button widgets. In addition to those keywords that affect all widgets, the following are particularly useful: DYNAMIC_RESIZE, GET_VALUE, INPUT_FOCUS, SET_BUTTON, SET_VALUE, X_BITMAP_EXTRA. Keywords to WIDGET_INFO Some keywords to the WIDGET_INFO function return information that applies specifically to button widgets. In addition to those keywords that apply to all widgets, the following are particularly useful: DYNAMIC_RESIZE. Exclusive And Non-Exclusive Bases Buttons placed into exclusive or non-exclusive bases (created via the EXCLUSIVE or NONEXCLUSIVE keywords to WIDGET_BASE procedure) are created as two- state "toggle" buttons, which are controlled by such bases. Events Returned by Button Widgets Pressing the mouse button while the mouse cursor is over a button widget causes the widget to generate an event. The event structure returned by the WIDGET_EVENT function is defined by the following statement: {WIDGET_BUTTON, ID:0L, TOP:0L, HANDLER:0L, SELECT:0} ID is the widget id of the button generating the event. TOP is the widget ID of the top level widget containing ID. HANDLER contains the widget ID of the widget associated with the handler routine. SELECT is set to 1 if the button was set, and 0 if released. Normal buttons do not generate events when released, so SELECT will always be 1. However, toggle buttons (created by parenting a button to an exclusive or non-exclusive base) return separate events for the set and release actions. Bitmap Button Labels In addition to using a text string as the label of a button (set via the VALUE keyword), a button can have a bitmap label. This allows buttons to contain a graphic symbol. The bitmap is specified via the VALUE keyword. If you specify a color bitmap, you must also specify the /BITMAP keyword, like this: button=WIDGET_BUTTON ( base, VALUE='mybitmap.bmp', /BITMAP ) To modify the color bitmap after creation, use the /BITMAP keyword with WIDGET_CONTROL, like this: WIDGET_CONTROL, button. SET_VALUE='mybitmap2.bmp', /BITMAP You can produce appropriate bitmaps in the following ways: * On Windows, create a color bitmap using the IDL GUIBuilder Bitmap Editor, which creates 16 color bitmaps for buttons. The Bitmap Editor can read and write bitmap files (*.bmp). Using the editor, you can create your own bitmaps, or you can open existing bitmap files and modify them. Open the Bitmap Editor from the Properties dialog for a created button. For more information, see "Using the Bitmap Editor" in Chapter 21 of Building IDL Applications. * Use any color bitmap editor available on your operating system. * Create a black and white bitmap using an external bitmap editor, and read it into an IDL byte array using the appropriate procedure (READ_BMP, READ_PICT, etc.) and convert the byte array to a bitmap byte array using the CVTTOBM function. * On an X-Window system, use the X11 bitmap utility to create a black and white bitmap byte array and read it in to IDL using the READ_X11_BITMAP routine. * Create a black and white bitmap using the XBM_EDIT procedure. This procedure offers several alternatives for the form of the final bitmap. Although IDL places no restriction on the size of bitmap allowed, the various toolkits may prefer certain sizes. Transparent Bitmaps For 16- and 256-color bitmaps, IDL uses the color of the pixel in the lower left corner as the transparent color. All pixels of this color become transparent, allowing the button color to show through. This allows you to use bitmaps that are not rectangular. If you have a rectangular bitmap that you want to use as a button label, you must either draw a border of a different color around the bitmap or save the bitmap as 24- bit (TrueColor). If your bitmap also contains text, make sure the border you draw is a different color than the text, otherwise the text color will become transparent. See Also CW_BGROUP, CW_PDMENU WIDGET_CONTROL [Previous Routine] [Next Routine] [List of Routines] NAME: WIDGET_CONTROL The WIDGET_CONTROL procedure is used to realize, manage, and destroy widget hierarchies. It is often used to change the default behavior or appearance of previously-realized widgets. Syntax WIDGET_CONTROL [, Widget_ID] Keywords that apply to all widgets: [, CONTEXT_MENU] [, BAD_ID=variable] [, /CLEAR_EVENTS] [, DEFAULT_FONT=string{do not specify Widget_ID}] [, /DELAY_DESTROY{do not specify Widget_ID}] [, /DESTROY] [, EVENT_FUNC=string] [, EVENT_PRO=string] [, FUNC_GET_VALUE=string] [, GET_UVALUE=variable] [, GROUP_LEADER=widget_id] [, /HOURGLASS{do not specify Widget_ID}] [, KILL_NOTIFY=string] [, /MAP] [, /NO_COPY] [, NOTIFY_REALIZE=string] [, PRO_SET_VALUE=string] [, /REALIZE] [, /RESET{do not specify Widget_ID}] [, SCR_XSIZE=width] [, SCR_YSIZE=height] [, SEND_EVENT=structure] [, /SENSITIVE] [, SET_UNAME=string] [, SET_UVALUE=value] [, /SHOW] [, TIMER=value] [, TLB_GET_OFFSET=variable] [, TLB_GET_SIZE=variable] [, /TLB_KILL_REQUEST_EVENTS] [, TLB_SET_TITLE=string] [, TLB_SET_XOFFSET=value] [, TLB_SET_YOFFSET=value] [, /TRACKING_EVENTS] [, UNITS={0 | 1 | 2}] [, /UPDATE] [, XOFFSET=value] [, XSIZE=value] [, YOFFSET=value] [, YSIZE=value] Keywords that apply to widgets created with widget_base: [, CANCEL_BUTTON=widget_id{for modal bases}] [, DEFAULT_BUTTON=widget_id{for modal bases}] [, /ICONIFY] [, /KBRD_FOCUS_EVENTS] [, /TLB_KILL_REQUEST_EVENTS] Keywords that apply to widgets created with widget_button: [, /BITMAP] [, /DYNAMIC_RESIZE] [, GET_VALUE=value] [, /INPUT_FOCUS] [, /SET_BUTTON] [, SET_VALUE=value] [, X_BITMAP_EXTRA=bits] Keywords that apply to widgets created with widget_draw: [, /DRAW_BUTTON_EVENTS] [, /DRAW_EXPOSE_EVENTS] [, /DRAW_MOTION_EVENTS] [, /DRAW_VIEWPORT_EVENTS] [, DRAW_XSIZE=integer] [, DRAW_YSIZE=integer] [, GET_DRAW_VIEW=variable] [, GET_UVALUE=variable] [, GET_VALUE=variable] [, /INPUT_FOCUS] [, SET_DRAW_VIEW=[x, y]] Keywords that apply to widgets created with widget_droplist: [, /DYNAMIC_RESIZE] [, SET_DROPLIST_SELECT=integer] [, SET_VALUE=value] Keywords that apply to widgets created with widget_label: [, /DYNAMIC_RESIZE] [, GET_VALUE=value] [, SET_VALUE=value] Keywords that apply to widgets created with widget_list: [, SET_LIST_SELECT=value] [, SET_LIST_TOP=integer] [, SET_VALUE=value] Keywords that apply to widgets created with widget_slider: [, GET_VALUE=value] [, SET_SLIDER_MAX=value] [, SET_SLIDER_MIN=value] [, SET_VALUE=value] Keywords that apply to widgets created with widget_table: [, ALIGNMENT={0 | 1 | 2}] [, /ALL_TABLE_EVENTS] [, AM_PM=[string, string]] [, COLUMN_LABELS=string_array] [, COLUMN_WIDTHS=array] [, DAYS_OF_WEEK=string_array{7 names}] [, /DELETE_COLUMNS{not for row_major mode}] [, /DELETE_ROWS{not for column_major mode}] [, /EDITABLE] [, EDIT_CELL=[integer, integer]] [, FORMAT=value] [, GET_VALUE=variable] [, INSERT_COLUMNS=value] [, INSERT_ROWS=value] [, /KBRD_FOCUS_EVENTS] [, MONTHS=string_array{12 names}] [, ROW_LABELS=string_array] [, ROW_HEIGHTS=array] [, SET_TABLE_SELECT=[left, top, right, bottom]] [, SET_TABLE_VIEW=[integer, integer]] [, SET_TEXT_SELECT=[integer, integer]] [, SET_VALUE=value] [, TABLE_XSIZE=columns] [, TABLE_YSIZE=rows] [, /USE_TABLE_SELECT | , USE_TABLE_SELECT=[left, top, right, bottom]] [, /USE_TEXT_SELECT] Keywords that apply to widgets created with widget_text: [, /ALL_TEXT_EVENTS] [, /APPEND] [, /EDITABLE] [, GET_VALUE=variable] [, /INPUT_FOCUS] [, /KBRD_FOCUS_EVENTS] [, /NO_NEWLINE] [, SET_TEXT_SELECT=[integer, integer]] [, SET_TEXT_TOP_LINE=line_number] [, SET_VALUE=value] [, /USE_TEXT_SELECT] Arguments Widget_ID The widget ID of the widget to be manipulated. This argument is required by all operations, unless the description of the specific keyword states otherwise. Note that if Widget_ID is not provided for a keyword that needs it, that keyword is quietly ignored. Keywords CONTEXT_MENU (Windows, UNIX only) Set this new keyword to enable context menu events generated by right mouse button clicks. Setting a zero value disables such events. This keyword applies to widgets created with WIDGET_BASE, WIDGET_TEXT, or WIDGET_LIST. Not all keywords to WIDGET_CONTROL apply to all combinations of widgets. In the following list, descriptions of keywords that affect only certain types of widgets include a list of the widgets for which the keyword is useful. ALIGNMENT This keyword applies to widgets created with the WIDGET_TABLE function. Set this keyword equal to a scalar or 2-D array specifying the alignment of the text within each cell. An alignment of 0 (the default) aligns the left edge of the text with the left edge of the cell. An alignment of 2 right-justifies the text, while 1 results in text centered within the cell. If ALIGNMENT is set equal to a scalar, all table cells are aligned as specified. If ALIGNMENT is set equal to a 2-D array, the alignment of each table cell is governed by the corresponding element of the array. If the USE_TABLE_SELECT keyword is set, then the alignment is changed only for the selected cells. ALL_TABLE_EVENTS This keyword applies to widgets created with the WIDGET_TABLE function. Along with the EDITABLE keyword, ALL_TABLE_EVENTS controls the type of events generated by the table widget. Set the ALL_TABLE_EVENTS keyword to cause the full set of events to be generated. If ALL_TABLE_EVENTS is not set, setting EDITABLE causes only end-of-line events to be generated (which could be used by the programmer as an indication to check the cell value or to set the currently selected cell to the next cell). If EDITABLE is not set, all events are suppressed. See the table below for additional details. Note that the equivalent keyword in the WIDGET_TABLE creation routine is called ALL_EVENTS. Keywords Effects ALL_TABLE_EVENTS EDITABLE Input changes Type of events widget contents? generated Not set Not set No None Not set Set Yes End-of-line insertion Set Not set No All events Set Set Yes All events Table 92: Effects of using the ALL_TABLE_EVENTS and EDITABLE keywords ALL_TEXT_EVENTS This keyword applies to widgets created with the WIDGET_TEXT function. Along with the EDITABLE keyword, ALL_TEXT_EVENTS controls the type of events generated by the text widget. Set the ALL_TEXT_EVENTS keyword to cause the full set of events to be generated. If ALL_TEXT_EVENTS is not set, setting EDITABLE causes only end-of-line events to be generated. If EDITABLE is not set, all events are suppressed. See the table below for additional details. Note that the equivalent keyword in the WIDGET_TEXT creation routine is called ALL_EVENTS. Keywords Effects ALL_TEXT_EVENTS EDITABLE Input changes Type of events widget contents? generated Not set Not set No None Not set Set Yes End-of-line insertion Set Not set No All events Set Set Yes All events Table 93: Effects of using the ALL_TEXT_EVENTS and EDITABLE keywords AM_PM This keyword applies to widgets created with the WIDGET_TABLE function. Supplies a string array of 2 names to be used for the names of the AM and PM string when processing explicitly formatted dates (CAPA, CApA, and CapA format codes) with the FORMAT keyword. APPEND This keyword applies to widgets created with the WIDGET_TEXT function. When using the SET_VALUE keyword to set the contents of a text widget (as created with the WIDGET_TEXT procedure), setting this keyword indicates that the supplied text should be appended to the existing contents of the text widget rather than replace it. BAD_ID This keyword applies to all widgets. If Widget_ID is not a valid widget identifier, this WIDGET_CONTROL normally issues an error and causes program execution to stop. However, if BAD_ID is present and specifies a named variable, the invalid ID is stored into the variable, and this routine quietly returns. If no error occurs, a zero is stored. CANCEL_BUTTON This keyword applies to widgets created with the WIDGET_BASE function using the MODAL keyword. Set this keyword equal to the widget ID of a button widget that will be the cancel button on a modal base widget. Pressing the Esc key on the keyboard when a modal widget is on the screen is the same as clicking the button. On Motif and Windows platforms, selecting Close from the system menu (generally located at the upper left of the base widget) generates a button event for the Cancel button. CLEAR_EVENTS This keyword applies to all widgets. If set, any events generated by the widget hierarchy rooted at Widget_ID which have arrived but have not been processed (via the WIDGET_EVENT procedure) are discarded. COLUMN_LABELS This keyword applies to widgets created with the WIDGET_TABLE function. Set this keyword equal to an array of strings to be used as labels for the columns of the table. If no label is specified for a column, it receives the default label "n" where n is the column number. If this keyword is set to the empty string (''), all column labels are set to be empty. COLUMN_WIDTHS This keyword applies to widgets created with the WIDGET_TABLE function. Set this keyword equal to an array of widths for the columns of the table widget. The widths are given in the units specified with the UNITS keyword. If no width is specified for a column, that column is set to the default size, which varies by platform. If COLUMN_WIDTHS is set to a scalar value, all of the column widths are set to that value. DAYS_OF_WEEK This keyword applies to widgets created with the WIDGET_TABLE function. Supplies a string array of 7 names to be used for the names of the days of the week when processing explicitly formatted dates (CDWA, CDwA, and CdwA format codes) with the FORMAT keyword. DEFAULT_BUTTON This keyword applies to widgets created with the WIDGET_BASE function using the MODAL keyword. Set this keyword equal to the widget ID of a button widget that will be the default button on a modal base widget. The default button is highlighted by the window system. Pressing the Enter or Return key on the keyboard when a modal widget is on the screen is the same as clicking the button. DEFAULT_FONT This keyword applies to all widgets. Do not specify a Widget ID when using this keyword. A string containing the name of the default font to be used. If the font to be used for a given widget is not explicitly specified (via the FONT keyword to the widget creation function), a default supplied by the window system or server is used. Use this keyword to change the default. See "About Device Fonts" on page 2482 for details on specifying names for device fonts. If this keyword is omitted, the default font is used. Note On Microsoft Windows platforms, IDL uses the system default font. Different versions of Windows use different system default fonts; in general, the system default font is the font appropriate for the version of Windows in question. DELAY_DESTROY This keyword applies to all widgets. Do not specify a Widget ID when using this keyword. Normally, when the user destroys a widget hierarchy using the window manager, it is immediately removed. This can cause problems for applications that use the background task facility provided by the XMANAGER procedure if the hierarchy is destroyed while a background task is using it. If DELAY_DESTROY is set, attempts to destroy the hierarchy are delayed until the next attempt to obtain an event for it. Setting DELAY_DESTROY to zero restores the default behavior. XMANAGER uses this keyword automatically when managing background tasks. It is not expected that applications will need to use it directly. DELETE_COLUMNS This keyword applies to widgets created with the WIDGET_TABLE function. Set this keyword to delete the currently-selected columns. If the USE_TABLE_SELECT keyword is given as a four element array, the columns specified are deleted. Warning You cannot delete columns from a table which displays structure data in /ROW_MAJOR (default) mode because it would change the structure. DELETE_ROWS This keyword applies to widgets created with the WIDGET_TABLE function. Set this keyword to delete the currently-selected rows. If the USE_TABLE_SELECT keyword is given as a four element array, the rows specified are deleted. Warning You cannot delete rows from a table which displays structure data in /COLUMN_MAJOR mode because it would change the structure. DESTROY This keyword applies to all widgets. Set this keyword to destroy the widget and any child widgets in its hierarchy. Any further attempts to use the IDs for these widgets will cause an error. DRAW_BUTTON_EVENTS This keyword applies to widgets created with the WIDGET_DRAW function. Set this keyword to enable button press events for draw widgets. Setting a zero value disables such events. DRAW_EXPOSE_EVENTS This keyword applies to widgets created with the WIDGET_DRAW function. Set this keyword to enable viewport expose events for draw widgets. Setting a zero value disables such events. Note You must explicitly disable backing store (by setting the RETAIN keyword to WIDGET_DRAW equal to zero) in order to generate expose events. DRAW_MOTION_EVENTS This keyword applies to widgets created with the WIDGET_DRAW function. Set this keyword to enable motion events for draw widgets. Setting a zero value disables such events. DRAW_VIEWPORT_EVENTS This keyword applies to widgets created with the WIDGET_DRAW function. Set this keyword to enable viewport motion events for draw widgets. Setting a zero value disables such events. DRAW_XSIZE This keyword applies to widgets created with the WIDGET_DRAW function. Set this keyword to an integer that specifies the new horizontal size for the graphics region (the virtual size) of a draw widget in units specified by the UNITS keyword (pixels are the default). For non-scrollable draw widgets, setting this keyword is the same as setting SCR_XSIZE or XSIZE. However, for scrolling draw widgets DRAW_XSIZE is the only way to change the width of the drawable area (XSIZE sets the viewport size). DRAW_YSIZE This keyword applies to widgets created with the WIDGET_DRAW function. Set this keyword to an integer that specifies the new vertical size for the graphics region (the virtual size) of a draw widget in units specified by the UNITS keyword (pixels are the default). For non-scrollable draw widgets, setting this keyword is the same as setting SCR_YSIZE or YSIZE. However, for scrolling draw widgets DRAW_YSIZE is the only way to change the height of the drawable area (YSIZE sets the viewport size). DYNAMIC_RESIZE This keyword applies to widgets created with the WIDGET_BUTTON, WIDGET_DROPLIST, and WIDGET_LABEL functions. Set this keyword to activate (if set to 1) or deactivate (if set to 0) dynamic resizing of the specified WIDGET_BUTTON, WIDGET_LABEL, or WIDGET_DROPLIST widget (see the documentation for the DYNAMIC_RESIZE keyword to those procedures for more information about dynamic widget resizing). EDITABLE This keyword applies to widgets created with the WIDGET_TABLE and WIDGET_TEXT functions. Set this keyword to allow direct user editing of the contents of a text or table widget. Normally, the text in text and table widgets is read-only. See the descriptions of the ALL_TABLE_EVENTS and ALL_TEXT_EVENTS keywords for additional details. EDIT_CELL This keyword applies to widgets created with the WIDGET_TABLE function. Set this keyword equal to a two-element integer array containing the x (row) and y (column) coordinates of a table cell to put that cell into edit mode. For example, to put the top left cell of a table widget into edit mode, use the following command: WIDGET_CONTROL, table, EDIT_CELL=[0, 0] where table is the Widget ID of the table widget. EVENT_FUNC This keyword applies to all widgets. A string containing the name of a function to be called by the WIDGET_EVENT function when an event arrives from a widget in the widget hierarchy given by Widget_ID. This keyword overwrites any event routine supplied by previous uses of the EVENT_FUNC or EVENT_PRO keywords. To specify no event routine, set this keyword to a null string (''). EVENT_PRO This keyword applies to all widgets. A string containing the name of a procedure to be called by the WIDGET_EVENT function when an event arrives from a widget in the widget hierarchy given by Widget_ID. This keyword overwrites any event routine supplied by previous uses of the EVENT_FUNC or EVENT_PRO keywords. To specify no event routine, set this keyword to a null string (''). FORMAT This keyword applies to widgets created with the WIDGET_TABLE function. Set this keyword equal to a single string or an array of strings that specify the format of data displayed within table cells. The string(s) are of the same form as used by the FORMAT keyword to the PRINT procedure, and the default format is the same as that used by the PRINT/PRINTF procedure. If the USE_TABLE_SELECT keyword is set, then the format is changed only for the selected cells. FUNC_GET_VALUE This keyword applies to all widgets. A string containing the name of a function to be called when the GET_VALUE keyword to the WIDGET_CONTROL procedure is called for this widget. The function specified by FUNC_GET_VALUE is called with the widget ID as an argument. The function specified by FUNC_GET_VALUE should return a value for a widget. Using this technique allows you to change the value that should be returned for a widget. Compound widgets use this ability to define their values transparently to the user. GET_DRAW_VIEW This keyword applies to widgets created with the WIDGET_DRAW function. Specifies a named variable which will be assigned the current position of a draw widget viewport. The position is returned as a 2-element integer array giving the X and Y position relative to the lower left corner of the graphics area. GET_UVALUE This keyword applies to all widgets. Set this keyword to a named variable to contain the current user value of the widget. Each widget can contain a user set value of any data type and organization. This value is not used by the widget in any way, and exists entirely for the convenience of the IDL programmer. This keyword allows you to obtain the current user value. The user value of a widget can be set with the SET_UVALUE keyword to this routine, or with the UVALUE keyword to the routine that created it. To improve the efficiency of the data transfer, consider using the NO_COPY keyword (described below) with GET_UVALUE. GET_VALUE This keyword applies to widgets created with the WIDGET_BUTTON, WIDGET_DRAW, WIDGET_LABEL, WIDGET_SLIDER, WIDGET_TABLE, and WIDGET_TEXT functions. Note If you would like information about the values returned for a specific compound widget-beginning with the prefix "CW_"-please refer to the description of the compound widget, which may also include a section titled, "Keywords to WIDGET_CONTROL and WIDGET_INFO". Compound widgets are described in the Reference Guide. Set this keyword to a named variable to contain the current value of the widget. The type of value returned depends on the widget type: * Button: If the button label is text, it is returned as a string. Attempts to obtain the value of a button with a bitmap label is an error. * Draw: The value of a draw widget depends on whether the draw widget uses IDL Direct Graphics or IDL Object Graphics. (The type of graphics used is specified by the GRAPHICS_LEVEL keyword to WIDGET_DRAW.) The two possibilities are: A. By default, draw widgets use IDL Direct Graphics. In this case, the value of a draw widget is the IDL window ID for the drawing area. This ID is used with procedures such as WSET, WSHOW, etc., to direct graphics to the widget. The window ID is assigned to drawing area widgets at the time they are realized. If the widget has not yet been realized, a value of -1 is returned. B. If the draw widget uses IDL Object Graphics (that is, if the GRAPHICS_LEVEL keyword to WIDGET_DRAW is set equal to 2), the value of the draw widget is the object reference of the window object used in the draw widget. * Label: The label text is returned as a string. * Slider: The current value of the slider is returned as an integer. * Table: Normally, the data for the whole table are returned as a two dimensional array or a vector of structures. However, if the USE_TABLE_SELECT keyword is present, the value returned is a subset of the whole data. This may either be a two dimensional array or a vector of (possibly anonymous) structures. If the USE_TEXT_SELECT keyword is set, the value returned is a string corresponding to the currently-selected text in the currently-selected cell. * Text: The current contents of the text widget are returned as a string array. If the USE_TEXT_SELECT keyword is also specified, only the contents of the current selection are returned. * Widget types not listed above do not return a value. Attempting to retrieve the value of such a widget causes an error. The value of a widget can be set with the SET_VALUE keyword to this routine, or with the VALUE keyword to the routine that created it. GROUP_LEADER This keyword applies to all widgets. The widget ID of an existing widget that serves as "group leader" for the newly- created widget. When a group leader is killed, for any reason, all widgets in the group are also destroyed. A given widget can be in more than one group. The WIDGET_CONTROL procedure can be used to add additional group associations to a widget. It is not possible to remove a widget from an existing group. HOURGLASS This keyword applies to all widgets. Do not specify a Widget ID when using this keyword. Set this keyword to turn on an "hourglass-shaped" cursor for all IDL widgets and graphics windows. The hourglass remains in place until the WIDGET_EVENT function attempts to process the next event. Then the previous cursor is reinstated. If an application starts a time-intensive calculation inside an event-handling routine, the hourglass cursor should be used to indicate that the system is not currently responding to events. ICONIFY This keyword applies to all widgets. Set this keyword to a non-zero value to cause the specified widget to become iconified. Set this keyword to zero to open an iconified widget. INPUT_FOCUS This keyword applies to widgets created with the WIDGET_BUTTON, WIDGET_DRAW, and WIDGET_TEXT functions. If Widget_ID is a text widget, you can set this keyword to cause the widget to receive the keyboard focus. If Widget_ID is a button widget, set this keyword to position the mouse pointer over the button (on Motif), or set the focus to the button so that it can be "pushed" with the spacebar (on Windows). You cannot set the input focus to a button in IDL for Macintosh. If Widget_ID is a draw widget, set this keyword to give it the focus in IDL for Macintosh; this allows you to print from the draw widget. This keyword has no effect for other widget types. Note You cannot assign the input focus to an unrealized widget. INSERT_COLUMNS This keyword applies to widgets created with the WIDGET_TABLE function. Set this keyword to the number of columns to be added to the right of the rightmost column of the table. If the USE_TABLE_SELECT keyword is set, the columns are inserted to the left of the current selection. Warning You cannot insert columns into a table which displays structure data in /ROW_MAJOR (default) mode because it would change the structure. INSERT_ROWS This keyword applies to widgets created with the WIDGET_TABLE function. Set this keyword to the number of rows to be added below the bottommost row of the table. If the USE_TABLE_SELECT keyword is set, the rows are inserted above the current selection. Warning You cannot insert rows into a table which displays structure data in /COLUMN_MAJOR mode because it would change the structure. KBRD_FOCUS_EVENTS This keyword applies to widgets created with the WIDGET_BASE, WIDGET_TABLE, and WIDGET_TEXT functions. Set this keyword to cause widget keyboard focus events to be issued for the widget whenever the keyboard focus of that widget changes. See the KBRD_FOCUS_EVENTS keywords to WIDGET_BASE, WIDGET_TABLE, and WIDGET_TEXT for details. KILL_NOTIFY This keyword applies to all widgets. Set this keyword to a string that contains the name of a procedure to be called automatically when the specified widget dies. Each widget is allowed a single such "callback" procedure. It can be removed by setting the routine to the null string (''). Use this keyword to change or remove a previously-specified callback procedure for Widget_ID. A previously-defined callback can be removed by setting this keyword to the null string (''). The callback routine is called with the widget identifier as its only argument. At that point, the widget identifier can only be used with the WIDGET_CONTROL procedure to get or set the user value. All other requests that require a widget ID are disallowed for the target widget. The callback is not issued until the WIDGET_EVENT function is called. The CLEANUP keyword to XMANAGER can also be used to specify a procedure to be called when a managed widget dies. The last call to either XMANAGER, CLEANUP or WIDGET_CONTROL, KILL_NOTIFY determines the procedure that is executed when the specified widget dies. Calling XMANAGER with the CLEANUP keyword overrides any previous setting of KILL_NOTIFY. Similarly, calling WIDGET_CONTROL with KILL_NOTIFY overrides any previous setting of CLEANUP. MANAGED This keyword applies to all widgets. This keyword is used by the XMANAGER procedure to mark those widgets that it is currently managing. User applications should not use this keyword directly. MAP This keyword applies to all widgets. Set this keyword to zero to unmap the widget hierarchy rooted at the widget specified by Widget_ID. The hierarchy disappears from the screen, but still exists. The mapping operation applies only to base widgets. If the specified widget is not a base, IDL searches upward in the widget hierarchy until it finds the closest base widget. The map operation is applied to that base. Set MAP to a nonzero value to re-map the widget hierarchy and make it visible. Normally, the widget is automatically mapped when it is realized, so use of the MAP keyword is not required. MONTHS This keyword applies to widgets created with the WIDGET_TABLE function. Supplies a string array of 12 names to be used for the names of the months when processing explicitly formatted dates (CMOA, CMoA, and CmoA format codes) with the FORMAT keyword. NO_COPY This keyword applies to all widgets. Usually, when setting or getting widget user values, either at widget creation or using the SET_UVALUE and GET_UVALUE keywords to WIDGET_CONTROL, IDL makes a second copy of the data being transferred. Although this technique is fine for small data, it can have a significant memory cost when the data being copied is large. If the NO_COPY keyword is set, IDL handles these operations differently. Rather than copy the source data, it takes the data away from the source and attaches it directly to the destination. This feature can be used by compound widgets to obtain state information from a UVALUE without all the memory copying that would otherwise occur. However, it has the side effect of causing the source variable to become undefined. On a "set" operation (using the SET_UVALUE keyword to WIDGET_CONTROL), the variable passed as value becomes undefined. On a "get" operation (GET_UVALUE keyword to WIDGET_CONTROL), the user value of the widget in question becomes undefined. Note The NO_COPY keyword increases efficiency when sending event structures using the SEND_EVENT keyword to WIDGET_CONTROL. NO_NEWLINE This keyword applies to widgets created with the WIDGET_TEXT function. When setting the value of a multi-line text widget, newline characters are automatically appended to the end of each line of text. The NO_NEWLINE keyword suppresses this action. NOTIFY_REALIZE This keyword applies to all widgets. Set this keyword to a string that contains the name of a procedure to be called automatically when the specified widget is realized. This callback occurs just once (because widgets are realized only once). Each widget is allowed a single such "callback" procedure. A previously-set callback routine can be removed by setting this keyword to the null string (''). The callback routine is called with the widget ID as its only argument. PRO_SET_VALUE This keyword applies to all widgets. A string containing the name of a procedure to be called when the SET_VALUE keyword to the WIDGET_CONTROL procedure is called for this widget. The procedure specified by PRO_SET_VALUE is called with 2 arguments- a widget ID and a value. Using this technique allows you to designate a routine that sets the value for a widget. Compound widgets use this ability to define their values transparently to the user. REALIZE This keyword applies to all widgets. If set, the widget hierarchy is realized. Until the realization step, the widget hierarchy exists only within IDL. Realization is the step of actually creating the widgets on the screen (and mapping them if necessary). When a previously-realized widget gets a new child widget, the new child is automatically realized. Tip Under Microsoft Windows, when a hidden base is realized, then mapped, a Windows resize message is sent by the windowing system. This "extra" resize event is generated before any manipulation of the base widget by the user. RESET This keyword applies to all widgets. Do not specify a Widget ID when using this keyword. Set the RESET keyword to destroy every currently active widget. This keyword should be used with caution. ROW_LABELS This keyword applies to widgets created with the WIDGET_TABLE function. Set this keyword equal to an array of strings to be used as labels for the rows of the table. If no label is specified for a row, it receives the default label "n" where n is the row number. If this keyword is set to the empty string (''), all row labels are set to be empty. ROW_HEIGHTS This keyword applies to widgets created with the WIDGET_TABLE function. Note This keyword is not supported under Microsoft Windows. Set this keyword equal to an array of heights for the rows of the table widget. The heights are given in any of the units as specified with the UNITS keyword. If no height is specified for a row, that row is set to the default size, which varies by platform. If ROW_HEIGHTS is set to a scalar value, all of the row heights are set to that value. SCR_XSIZE This keyword applies to all widgets. Set this keyword to an integer value that represents the widget's new horizontal size, in units specified by the UNITS keyword (pixels are the default). Attempting to change the size of a widget that is part of a menubar or pulldown menu causes an error. Note that, in many cases, setting this keyword is equivalent to setting the XSIZE keyword. However, this keyword is useful for resizing table, text, list, and scrolling widgets. SCR_YSIZE This keyword applies to all widgets. Set this keyword to an integer value that represents the widget's new vertical size, in units specified by the UNITS keyword (pixels are the default). Attempting to change the size of a widget that is part of a menubar or pulldown menu causes an error. Note that, in many cases, setting this keyword is equivalent to setting the YSIZE keyword. However, this keyword is useful for resizing table, text, list, and scrolling widgets. SEND_EVENT This keyword applies to all widgets. Set this keyword to a structure containing a valid widget event to be sent to the specified widget. The value of SEND_EVENT must be a structure and the first three fields must be ID, TOP, and HANDLER (all of LONG type). Additional fields can be of any type. To improve the efficiency of the data transfer, consider using the NO_COPY keyword with SEND_EVENT. SENSITIVE Set this keyword to control the sensitivity state of a widget after creation. This keyword applies to all widgets. Use the SENSITIVE keyword with the widget creation function to control the initial sensitivity state. When a widget is sensitive, it has normal appearance and can receive user input. For instance, a sensitive button widget can be activated by moving the mouse cursor over it and pressing a mouse button. When a widget is insensitive, it indicates the fact by changing its appearance, and ignores any input directed at it. If SENSITIVE is zero, the widget hierarchy becomes insensitive. If nonzero, it becomes sensitive. Sensitivity can be used to control when a user is allowed to manipulate a widget. It should be noted that some widgets do not change their appearance when they are made insensitive, and simply cease generating events. SET_BUTTON This keyword applies to widgets created with the WIDGET_BUTTON function. This keyword allows changing the current state of toggle buttons. If zero, every toggle button in the hierarchy specified by Widget_ID is set to the unselected state. If nonzero, the action depends on the type of base holding the buttons. Normally, all buttons are selected. However, exclusive bases may or may not allow more than a single button to be selected in this manner, depending on the toolkit implementation. SET_DRAW_VIEW This keyword applies to widgets created with the WIDGET_DRAW function. A scrollable draw widget provides a large graphics area which is viewed through a smaller viewport. This keyword allows changing the current position of the viewport. The desired position is specified as a 2-element integer array giving the X and Y position in units specified by the UNITS keyword (pixels are the default) relative to the lower left corner of the graphics area. For example, to position the viewport to the lower left corner of the image: WIDGET_CONTROL, widget, SET_DRAW_VIEW=[0, 0] SET_DROPLIST_SELECT This keyword applies to widgets created with the WIDGET_DROPLIST function. Set this keyword to an integer that specifies the droplist element to be current (i.e., the element that is displayed on the droplist button). Positions start at zero. If the specified element is outside the possible range, no new selection is set. SET_LIST_SELECT This keyword applies to widgets created with the WIDGET_LIST function. Set this keyword to an integer scalar or vector that specifies the list element or elements to be highlighted. The previous selection (if there is a selection) is cleared. Positions start at zero. If the specified element is outside the possible range, no new selection in set. Note that the MULTIPLE keyword to WIDGET_LIST must have been set in more than a single list element is specified. If the selected position is not currently on the screen, the list widget automatically move the current scrolling viewport to make it visible. The resulting topmost visible element is toolkit specific. If you wish to ensure a certain element is at the top of the list, use the SET_LIST_TOP keyword (described below) to explicitly set the viewport. SET_LIST_TOP This keyword applies to widgets created with the WIDGET_LIST function. Set this keyword to an integer that specifies the element of the list widget to the positioned at the top of the scrolling list. If the specified element is outside the range of list elements, nothing happens. SET_SLIDER_MAX This keyword applies to widgets created with the WIDGET_SLIDER function. Set this keyword to a new maximum value for the specified slider widget. Note This keyword does not apply to floating-point sliders created with the CW_FSLIDER function. SET_SLIDER_MIN This keyword applies to widgets created with the WIDGET_SLIDER function. Set this keyword to a new minimum value for the specified slider widget. Note This keyword does not apply to floating-point sliders created with the CW_FSLIDER function. SET_TABLE_SELECT This keyword applies to widgets created with the WIDGET_TABLE function. Set this keyword to an array of zero-based cell indices, of the form [ left, top, right, bottom ] giving the range of cells to select. If the selected position is not currently on the screen, the table widget automatically moves the current scrolling viewport to make a portion of it visible. The resulting top-left visible cell is toolkit specific. If you wish to ensure a certain element is at the top of the list, use the SET_TABLE_VIEW keyword to explicitly set the viewport. SET_TABLE_VIEW This keyword applies to widgets created with the WIDGET_TABLE function. Set this keyword to a two-element array of zero-based cell indices that specifies the cell of the table widget to the positioned at the top-left of the widget. If the specified cell is outside the range of valid cells, nothing happens. SET_TEXT_SELECT This keyword applies to widgets created with the WIDGET_TABLE and WIDGET_TEXT functions. Use this keyword to clear any current selection in the specified table cell or text widget, and either set a new selection, or simply set the text insertion point. To set a selection, specify a two-element integer array containing the starting position and the length of the selection. For example, to set a selection covering characters 3 though 23: WIDGET_CONTROL, widgetID, SET_TEXT_SELECT=[3, 20] To move the text insertion point without setting a selection, omit the second element, or set it to zero. SET_TEXT_TOP_LINE This keyword applies to widgets created with the WIDGET_TEXT function. Set this keyword to the zero-based line number of the line to be positioned on the topmost visible line in the text widget's viewport. No horizontal scrolling is performed. Note that this is a line number, not a character offset. SET_UNAME This keyword applies to all widgets. Set this keyword to a string that can be used to identify the widget. You can associate a name with each widget in a specific hierarchy, and then use that name to query the widget hierarchy and get the correct widget ID. You can set the name at creation time, using the UNAME keyword with the creation function. To query the widget hierarchy, use the WIDGET_INFO function with the FIND_BY_UNAME keyword. The UNAME should be unique to the widget hierarchy because the FIND_BY_UNAME keyword returns the ID of the first widget with the specified name. SET_UVALUE This keyword applies to all widgets. Each widget can contain a user-set value. This value is not used by IDL in any way, and exists entirely for the convenience of the IDL programmer. This keyword allows you to set this value. To improve the efficiency of the data transfer, consider using the NO_COPY keyword with SET_UVALUE. SET_VALUE This keyword applies to widgets created with the WIDGET_BUTTON, WIDGET_DROPLIST, WIDGET_LABEL, WIDGET_LIST, WIDGET_SLIDER, WIDGET_TABLE, and WIDGET_TEXT functions. Sets the value of the specified widget. The meaning of the value differs between widget types: * Button: The label to be used for the button. This value can be either a scalar string, or a 2D byte array containing a bitmap. * Droplist: The contents of the droplist widget (string or string array). * Label: The text to be displayed by the label widget. * List: The contents of the list widget (string or string array). * Slider: The current position of the slider (integer). * Table: Normally, the data for the whole table is changed to the given data which must be of the form of a two dimensional array or a vector of structures. In this form, the table is resized to fit the given data (unless the TABLE_XSIZE or TABLE_YSIZE keywords are given). If the USE_TABLE_SELECT keyword is present, the value given is treated as a subset of the whole data, and only the given range of cells are updated. Used in this form, the type of data stored in the table cannot be changed. The data passed in is converted, as appropriate, to the type of the selected cells. If less data is passed in than fits in the current selection, the cells outside the range of data (but inside the selection) are left unchanged. If more data is passed in than fits in the current selection, the extra data is ignored. If the USE_TEXT_SELECT keyword is present, the value must be a string which replaces the currently-selected text in the currently-selected cell. * Text: The text to be displayed. If the APPEND keyword is also specified, the text is appended to the current contents instead of instead of completely replacing it (string or string array). If the USE_TEXT_SELECT keyword is specified, the new string replaces only the currently-selected text in the text widget. * Widget types not listed above do not allow the setting of a value. Attempting to set the value of such a widget causes an error. The value of a widget can also be set with the VALUE keyword to the routine that created it. SHOW This keyword applies to all widgets. Controls the visibility of a widget hierarchy. If set to zero, the hierarchy containing Widget_ID is pushed behind any other windows on the screen. If nonzero, the hierarchy is pulled in front. TABLE_XSIZE This keyword applies to widgets created with the WIDGET_TABLE function. Set this keyword equal to the number of data columns in the table widget. Note that if the table widget was created with row titles enabled (that is, if the NO_HEADERS keyword to WIDGET_TABLE was not set), the table will contain one column more than the number specified by TABLE_XSIZE. If the table is made smaller as a result of the application of the TABLE_XSIZE keyword, the data outside the new range persists, but the number of columns and/or rows changes as expected. If the table is made larger, the data type of the cells in the new columns is set according to the following rules: 1. If the table was not created with either the ROW_MAJOR or COLUMN_MAJOR keywords set (if the table is an array rather than a vector of structures), the new cells have the same type as all the original cells. 2. If the SET_VALUE keyword is given, the types of all columns are set according to the new structure. 3. If the table was created with the ROW_MAJOR keyword set, and the SET_VALUE keyword is not specified, the cells in the new columns inherit their type from the cells to their left. 4. If the table was created with the COLUMN_MAJOR keyword set, and the SET_VALUE keyword is not specified, any new columns default to type INT. TABLE_YSIZE This keyword applies to widgets created with the WIDGET_TABLE function. Set this keyword equal to the number of data rows in the table widget. Note that if the table widget was created with column titles enabled (that is, if the NO_HEADERS keyword to WIDGET_TABLE was not set), the table will contain one row more than the number specified by TABLE_YSIZE. If the table is made smaller as a result of the application of the TABLE_YSIZE keyword, the data outside the new range persists, but the number of columns and/or rows changes as expected. If the table is made larger, the data type of the cells in the new rows is set according to the following rules: 1. If the table was not created with either the ROW_MAJOR or COLUMN_MAJOR keywords set (if the table is an array rather than a vector of structures), the new cells have the same type as all the original cells. 2. If the SET_VALUE keyword is given, the types of all rows are set according to the new structure. 3. If the table was created with the COLUMN_MAJOR keyword set, and the SET_VALUE keyword is not specified, the cells in the new rows inherit their type from the cells above. 4. If the table was created with the ROW_MAJOR keyword set, and the SET_VALUE keyword is not specified, any new rows default to type INT. TIMER This keyword applies to all widgets. If this keyword is present, a WIDGET_TIMER event is generated. Set this keyword to a floating-point value that represents the number of seconds before the timer event arrives. Note that this event is identical to any other widget event except that it contains only the 3 standard event tags. These event structures are defined as: { WIDGET_TIMER, ID:0L, TOP:0L, HANDLER:0L } It is left to the caller to tell the difference between standard widget events and timer events. The standard way to do this is to use a widget that doesn't normally generate events (e.g., a base or label). Alternately, the TAG_NAMES function can be called with the STRUCTURE_NAME keyword to differentiate a WIDGET_TIMER event from other types of events. For example: IF TAG_NAMES(event, /STRUCTURE_NAME) EQ $ 'WIDGET_TIMER' THEN ... Using the TIMER keyword is more efficient than the background task functionality found in the XMANAGER procedure because it doesn't "poll" like the original background task code. Research Systems will eventually eliminate the background task functionality from XMANAGER. We encourage all users to modify their code to use the TIMER keyword instead. TLB_GET_OFFSET This keyword applies to all widgets. Set this keyword to a named variable in which the offset of the top-level base of the specified widget is returned, in units specified by the UNITS keyword (pixels are the default). The offset is measured in device coordinates relative to the upper-left corner of the screen. TLB_GET_SIZE This keyword applies to all widgets. Set this keyword to a named variable in which the size of the top-level base of the specified widget is returned, in units specified by the UNITS keyword (pixels are the default). The size is returned as a two-element vector that contains the horizontal and vertical size of the base in device coordinates. TLB_KILL_REQUEST_EVENTS This keyword applies to widgets created with the WIDGET_BASE function. Use this keyword to set or clear kill request events for the specified top-level base. For more information on these events see "TLB_KILL_REQUEST_EVENTS" on page 1532. TLB_SET_TITLE This keyword applies to all widgets. Set this keyword to a scalar string to change the title of the specified top-level base after it has been created. TLB_SET_XOFFSET This keyword applies to all widgets. Use this keyword to set the horizontal position of the top level base of the specified widget. The offset is measured from the upper-left corner of the screen to the upper- left corner of the base, in units specified by the UNITS keyword (pixels are the default). TLB_SET_YOFFSET This keyword applies to all widgets. Use this keyword to set the vertical position of the top level base of the specified widget. The offset is measured from the upper-left corner of the screen to the upper- left corner of the base, in units specified by the UNITS keyword (pixels are the default). TRACKING_EVENTS This keyword applies to all widgets. Set this keyword to a non-zero value to enable tracking events for the widget specified by Widget_ID. Set the keyword to 0 to disable tracking events for the specified widget. For a description of tracking events, see "TRACKING_EVENTS" on page 1533. UNITS This keyword applies to all widgets. Use this keyword to specify the unit of measurement used for most widget sizing operations. Set UNITS equal to 0 to specify that all measurements are in pixels (this is the default), to 1 to specify that all measurements are in inches, or to 2 to specify that all measurements are in centimeters. Note This keyword does not affect all sizing operations. Specifically, the value of UNITS is ignored when setting the XSIZE or YSIZE keywords to WIDGET_LIST, WIDGET_TABLE, or WIDGET_TEXT. UPDATE This keyword applies to all widgets. Use this keyword to enable (if set to 1) or disable (if set to 0) screen updates for the widget hierarchy to which the specified widget belongs. This keyword is useful for preventing unwanted intermediate screen updates when changing the values of many widgets at once or when adding several widgets to a previously-realized widget hierarchy. When first realized, widget hierarchies are set to update. Note Do not attempt to resize a widget on the Windows platform while UPDATE is turned off. Doing so may prevent IDL from updating the screen properly when UPDATE is turned back on. USE_TABLE_SELECT This keyword applies to widgets created with the WIDGET_TABLE function. Set this keyword to modify the behavior of the ALIGNMENT,COLUMN_WIDTH, FORMAT, GET_VALUE, ROW_HEIGHT, and SET_VALUE keywords. If USE_TABLE_SELECT is set, these other keywords only apply to the currently- selected cells. Normally, these keywords apply to the entire contents of a table widget. Note In order to set the format of the currently-selected cells, the value of the FORMAT keyword must be an array of the same dimensions as the selected area. This keyword can also be specified as a four-element array, of the form [ left, top, right, bottom ] giving the group of cells to act on. In this usage, the value -1 is used to refer to the row or column titles. If row or column titles are selected, this keyword only modifies the behavior of the COLUMN_WIDTH and ROW_HEIGHTS keywords. Warning You should set values to -1 only when you can change the labels. For example, on the Macintosh, only COLUMN_WIDTH and ROW_HEIGHT should be set to -1. USE_TEXT_SELECT This keyword applies to widgets created with the WIDGET_TABLE and WIDGET_TEXT functions. Set this keyword to modify the behavior of the GET_VALUE and SET_VALUE keywords. If USE_TEXT_SELECT is set, GET_VALUE and SET_VALUE apply only to the current text selection. Normally, these keywords apply to the entire contents of a text widget. X_BITMAP_EXTRA This keyword applies to widgets created with the WIDGET_BUTTON function. When the value of a button widget is a bitmap, the usual width is taken to be 8 times the number of columns in the source byte array. This keyword can be used to indicate the number of bits in the last byte of each row that should be ignored. The value can range between 0 and 7. XOFFSET This keyword applies to all widgets. Set this keyword to an integer value that specifies the widget's new horizontal offset, in units specified by the UNITS keyword (pixels are the default). Attempting to change the offset of a widget that is the child of a ROW or COLUMN base or a widget that is part of a menubar or pulldown menu causes an error. XSIZE This keyword applies to all widgets. Set this keyword to an integer or floating-point value that represents the widget's new horizontal size. * Text and List widgets: Size is specified in characters. The UNITS keyword is ignored. * Table widgets: Size is specified in columns. The width of the row labels is automatically added to this value. The UNITS keyword is ignored. * All other widgets: If the UNITS keyword is present, size is in the units specified. If the UNITS keyword is not present, the size is specified in pixels. For most non-scrollable widgets, this size is the same as the "screen size" that can be set using the SCR_XSIZE keyword. For scrollable widgets (e.g., scrolling bases and scrolling draw widgets), this keyword adjusts the viewport size. Use the DRAW_XSIZE keyword to change the width of the drawing area in scrolling draw widgets. Attempting to resize a widget that is part of a menubar or pulldown menu causes an error. YOFFSET This keyword applies to all widgets. Set this keyword to an integer value that specifies the widget's new vertical offset, in units specified by the UNITS keyword (pixels are the default). Attempting to change the offset of a widget that is the child of a ROW or COLUMN base or a widget that is part of a menubar or pulldown menu causes an error. YSIZE This keyword applies to all widgets. Set this keyword to an integer or floating-point value that represents the widget's new vertical size * Text and List widgets: Size is specified in lines. The UNITS keyword is ignored. * Table widgets: Size is specified in rows. The height of the column labels is automatically added to this value. The UNITS keyword is ignored. * All other widgets: If the UNITS keyword is present, size is in the units specified. If the UNITS keyword is not present, the size is specified in pixels. For most non-scrollable widgets, this size is the same as the "screen size" that can be set using the SCR_YSIZE keyword. For scrollable widgets (e.g., scrolling bases and scrolling draw and table widgets), this keyword adjusts the viewport size. Use the DRAW_YSIZE keyword to change the height of the drawing area in scrolling draw widgets. Attempting to resize a widget that is part of a menubar or pulldown menu causes an error. WIDGET_DRAW [Previous Routine] [Next Routine] [List of Routines] NAME: WIDGET_DRAW The WIDGET_DRAW function is used to create draw widgets. Draw widgets are rectangular areas that IDL treats as standard graphics windows. Draw widgets can use either IDL Direct graphics or IDL Object graphics, depending on the value of the GRAPHICS_LEVEL keyword. Any graphical output that can be produced by IDL can be directed to a draw widget. Draw widgets can have optional scroll bars to allow viewing a larger graphics area than could otherwise be displayed in the widget's visible area. The returned value of this function is the widget ID of the newly-created draw widget. Note On some systems, when backing store is provided by the window system (RETAIN=1), reading data from a window using TVRD( ) may cause unexpected results. For example, data may be improperly read from the window even when the image displayed on screen is correct. Having IDL provide the backing store (RETAIN=2) ensures that the window contents will be read properly. Syntax Result = WIDGET_DRAW(Parent [, /APP_SCROLL] [, /BUTTON_EVENTS] [, /COLOR_MODEL] [, COLORS=integer] [, EVENT_FUNC=string] [, EVENT_PRO=string] [, /EXPOSE_EVENTS] [, FRAME=width] [, FUNC_GET_VALUE=string] [, GRAPHICS_LEVEL=2] [, GROUP_LEADER=widget_id] [, KILL_NOTIFY=string] [, /MOTION_EVENTS] [, /NO_COPY] [, NOTIFY_REALIZE=string] [, PRO_SET_VALUE=string] [, RENDERER={0 | 1}] [, RESOURCE_NAME=string] [, RETAIN={0 | 1 | 2}] [, SCR_XSIZE=width] [, SCR_YSIZE=height] [, /SCROLL] [, /SENSITIVE] [, /TRACKING_EVENTS] [, UNAME=string] [, UNITS={0 | 1 | 2}] [, UVALUE=value] [, VALUE=value] [, /VIEWPORT_EVENTS] [, XOFFSET=value] [, XSIZE=value] [, X_SCROLL_SIZE=width] [, YOFFSET=value] [, YSIZE=value] [, Y_SCROLL_SIZE=height] ) Arguments Parent The widget ID of the parent widget of the new draw widget. Keywords APP_SCROLL Set this keyword to create a scrollable draw widget with horizontal and vertical scrollbars and a draw area canvas with the same size as the viewport. You can specify the size of the viewport using the X_SCROLL_SIZE and Y_SCROLL_SIZE keywords, and the virtual size of the canvas using the XSIZE and YSIZE keywords. If APP_SCROLL is set, the application generates expose and viewport events such as would occur with EXPOSE=1, RETAIN=0, and VIEWPORT_EVENTS=1. This allows you to redraw the appropriate part of the virtual canvas when your application receives expose or viewport events. Use the APP_SCROLL keyword when displaying images, or anything drawn in device units or pixels. This keyword is good when you are displaying large images because the entire images does not have to be redrawn when change viewport events are generated. Use the SCROLL keyword when a draw widget is going to display graphics drawn in data units (e.g., PLOT, CONTOUR, SURFACE). BUTTON_EVENTS Set this keyword to make the draw widget generate events when the mouse buttons are pressed or released (and the mouse pointer is in the draw widget). Normally, draw widgets do not generate events. COLOR_MODEL Set this keyword equal to 1 (one) to cause the draw widget's associated IDLgrWindow object to use indexed color. If the COLOR_MODEL keyword is not set, or is set to a value other than one, the draw widget will use RGB color. This keyword is only valid when the draw widget uses IDL Object Graphics. (The graphics type used by a draw widget is determined by setting the GRAPHICS_LEVEL keyword to WIDGET_DRAW.) For information on using indexed color in Object Graphics window objects, see Chapter 20, "Working with Color" in Using IDL. COLORS The maximum number of color table indices to be used. This parameter has effect only if it is supplied when the first IDL graphics window is created. If COLORS is not specified when the first window is created, all or most of the available color indices are allocated, depending upon the window system in use. To use monochrome windows on a color display, set COLORS equal to 2 when creating the first window. One color table is maintained for all IDL windows. A negative value for COLORS specifies that all but the given number of colors from the shared color table should be used. EVENT_FUNC A string containing the name of a function to be called by the WIDGET_EVENT function when an event arrives from a widget in the widget hierarchy rooted at the newly-created widget. EVENT_PRO A string containing the name of a procedure to be called by the WIDGET_EVENT function when an event arrives from a widget in the widget hierarchy rooted at the newly-created widget. EXPOSE_EVENTS Set this keyword to make the draw widget generate event when the visibility of the draw widget changes. This may occur when the widget is hidden behind something else on the screen, brought to the foreground, or when the scroll bars are moved. Normally, draw widgets do not generate events. If this keyword is set, expose events will be generated only when IDL is unable to restore the contents of the window itself. After the initial draw, expose events are not issued when GRAPHICS_LEVEL=2 and the software renderer is being used (RENDERER=1). In such cases, expose events are not issued because IDL can internally refresh the window itself. On platforms for which OpenGL support is not offered, the software renderer is always being used, and therefore, expose events are not issued after the initial draw. Note You must explicitly disable backing store (by setting RETAIN=0) in order to generate expose events. Additional expose events may be generated if both EXPOSE_EVENTS and RETAIN=1 are turned on. Warning Large numbers of events may be generated when EXPOSE_EVENTS is specified. You may wish to compress the events (perhaps using a timer) and only act on a subset. FRAME The value of this keyword specifies the width of a frame in units specified by the UNITS keyword (pixels are the default) to be drawn around the borders of the widget. Note that this keyword is only a hint to the toolkit, and may be ignored in some instances. FUNC_GET_VALUE A string containing the name of a function to be called when the GET_VALUE keyword to the WIDGET_CONTROL procedure is called for this widget. Using this technique allows you to change the value that should be returned for a widget. Compound widgets use this ability to define their values transparently to the user. GRAPHICS_LEVEL Set this keyword equal to 2 (two) to use IDL Object Graphics in the draw widget. If the GRAPHICS_LEVEL keyword is not set, or is set to a value other than two, the draw widget will use IDL Direct Graphics. GROUP_LEADER The widget ID of an existing widget that serves as "group leader" for the newly- created widget. When a group leader is killed, for any reason, all widgets in the group are also destroyed. A given widget can be in more than one group. The WIDGET_CONTROL procedure can be used to add additional group associations to a widget. It is not possible to remove a widget from an existing group. KILL_NOTIFY Set this keyword to a string that contains the name of a procedure to be called automatically when the specified widget dies. Each widget is allowed a single such "callback" procedure. It can be removed by setting the routine to the null string (''). Note that the procedure specified is used only if you are not using the XMANAGER procedure to manage your widgets. The callback routine is called with the widget identifier as its only argument. At that point, the widget identifier can only be used with the WIDGET_CONTROL procedure to get or set the user value. All other requests that require a widget ID are disallowed for the target widget. The callback is not issued until the WIDGET_EVENT function is called. If you use the XMANAGER procedure to manage your widgets, the value of this keyword is overwritten. Use the CLEANUP keyword to XMANAGER to specify a procedure to be called when a managed widget dies. MOTION_EVENTS Set this keyword to make the draw widget generate events when the mouse cursor moves across the widget. Normally, draw widgets do not generate events. Draw widgets that return motion events can generate a large number of events that can result in poor performance on slower machines. Note that it is possible to generate motion events with coordinates outside the draw widget. If you position the mouse cursor inside the draw widget, press the mouse button, and drag the cursor out of the draw widget, the X and Y fields of the widget event will specify coordinates outside the draw widget. NO_COPY Usually, when setting or getting widget user values, either at widget creation or using the SET_UVALUE and GET_UVALUE keywords to WIDGET_CONTROL, IDL makes a second copy of the data being transferred. Although this technique is fine for small data, it can have a significant memory cost when the data being copied is large. If the NO_COPY keyword is set, IDL handles these operations differently. Rather than copy the source data, it takes the data away from the source and attaches it directly to the destination. This feature can be used by compound widgets to obtain state information from a UVALUE without all the memory copying that would otherwise occur. However, it has the side effect of causing the source variable to become undefined. On a "set" operation (using the UVALUE keyword to WIDGET_DRAW or the SET_UVALUE keyword to WIDGET_CONTROL), the variable passed as value becomes undefined. On a "get" operation (GET_UVALUE keyword to WIDGET_CONTROL), the user value of the widget in question becomes undefined. NOTIFY_REALIZE Set this keyword to a string that contains the name of a procedure to be called automatically when the specified widget is realized. This callback occurs just once (because widgets are realized only once). Each widget is allowed a single such "callback" procedure. It can be removed by setting the routine to the null string (''). The callback routine is called with the widget ID as its only argument. PRO_SET_VALUE A string containing the name of a procedure to be called when the SET_VALUE keyword to the WIDGET_CONTROL procedure is called for this widget. Using this technique allows you to designate a routine that sets the value for a widget. Compound widgets use this ability to define their values transparently to the user. RENDERER Set this keyword to an integer value indicating which graphics renderer to use when drawing objects within the window. Valid values are: * 0 = Platform native OpenGL * 1 = IDL's software implementation By default, your platform's native OpenGL implementation is used. If your platform does not have a native OpenGL implementation, IDL's software implementation is used regardless of the value of this property. See "Hardware vs. Software Rendering" in Chapter 28 of Using IDL for details. Your choice of renderer may also affect the maximum size of a draw widget. See "IDLgrWindow" on page 2276 for details. RESOURCE_NAME A string containing an X Window System resource name to be applied to the widget. See "RESOURCE_NAME" on page 1527 for a complete discussion of this keyword. RETAIN Set this keyword to 0, 1, or 2 to specify how backing store should be handled for the draw widget. RETAIN=0 specifies no backing store. RETAIN=1 requests that the server or window system provide backing store. RETAIN=2 specifies that IDL provide backing store directly. See "Backing Store" on page 1589 for details on the use of RETAIN with Direct Graphics. For more information on the use of RETAIN with Object Graphics, see "IDLgrWindow::Init" on page 2289. SCR_XSIZE Set this keyword to the desired "screen" width of the widget, in units specified by the UNITS keyword (pixels are the default). In many cases, setting this keyword is the same as setting the XSIZE keyword. SCR_YSIZE Set this keyword to the desired "screen" height of the widget, in units specified by the UNITS keyword (pixels are the default). In many cases, setting this keyword is the same as setting the YSIZE keyword. SCROLL Set this keyword to give the draw widget scroll bars that allow viewing portions of the widget contents that are not currently on the screen. Use the SCROLL keyword when a draw widget is going to display graphics drawn in data units (e.g., PLOT, CONTOUR, SURFACE). Use the APP_SCROLL keyword when displaying images, or anything drawn in device units or pixels. SENSITIVE Set this keyword to control the initial sensitivity state of the widget. If SENSITIVE is zero, the widget becomes insensitive. If nonzero, it becomes sensitive. When a widget is sensitive, it has normal appearance and can receive user input. For example, a sensitive button widget can be activated by moving the mouse cursor over it and pressing a mouse button. When a widget is insensitive, it indicates the fact by changing its appearance, looking disabled, and it ignores any input. Sensitivity can be used to control when a user is allowed to manipulate the widget. Note that some widgets do not change their appearance when they are made insensitive, but they cease generating events. After creating the widget hierarchy, you can change the sensitivity state using the SENSITIVE keyword with the WIDGET_CONTROL procedure. TRACKING_EVENTS Set this keyword to cause widget tracking events to be issued for the widget whenever the mouse pointer enters or leaves the region covered by that widget. For the structure of tracking events, see "TRACKING_EVENTS" on page 1533 in the documentation for WIDGET_BASE. UNAME Set this keyword to a string that can be used to identify the widget in your code. You can associate a name with each widget in a specific hierarchy, and then use that name to query the widget hierarchy and get the correct widget ID. To query the widget hierarchy, use the WIDGET_INFO function with the FIND_BY_UNAME keyword. The UNAME should be unique to the widget hierarchy because the FIND_BY_UNAME keyword returns the ID of the first widget with the specified name. UNITS Set UNITS equal to 0 (zero) to specify that all measurements are in pixels (this is the default), to 1 (one) to specify that all measurements are in inches, or to 2 (two) to specify that all measurements are in centimeters. UVALUE The "user value" to be assigned to the widget. Each widget can contain a user-specified value of any data type and organization. This value is not used by the widget in any way, but exists entirely for the convenience of the IDL programmer. This keyword allows you to set this value when the widget is first created. If UVALUE is not present, the widget's initial user value is undefined. VALUE The initial value setting of the widget. The value of a draw widget is the IDL window number for use with Direct Graphics routines, such as WSET. For Object Graphics routines, it is the draw window object reference. This value cannot be set or modified by the user. To obtain the window number for a newly-created draw widget, use the GET_VALUE keyword to WIDGET_CONTROL after the draw widget has been realized. Draw widgets do not have a window number assigned to them until they are realized. For example, to return the window number of a draw widget in the variable win_num, use the command: WIDGET_CONTROL, my_drawwidget, GET_VALUE = win_num where my_drawwidget is the widget ID of the desired draw widget. When using Object Graphics for the widget draw, the following command returns an object reference to the draw window: WIDGET_CONTROL, my_drawwidget, GET_VALUE = oWindow where oWindow is a window object. VIEWPORT_EVENTS Set this keyword to enable viewport motion events for draw widgets. XOFFSET The horizontal offset of the widget in units specified by the UNITS keyword (pixels are the default) relative to its parent. Specifying an offset relative to a row or column major base widget does not work because those widgets enforce their own layout policies. This keyword is primarily of use relative to a plain base widget. Note that it is best to avoid using this style of widget layout. XSIZE The width of the widget in units specified by the UNITS keyword (pixels are the default). Most widgets attempt to size themselves to fit the situation. However, if the desired effect is not produced, use this keyword to override it. This keyword is only a "hint" to the toolkit and may be ignored in some situations. By default, draw widgets are 100 pixels wide by 100 pixels high. X_SCROLL_SIZE The XSIZE keyword always specifies the width of a widget. When the SCROLL keyword is specified, this size is not necessarily the same as the width of the visible area. The X_SCROLL_SIZE keyword allows you to set the width of the scrolling viewport independently of the actual width of the widget. Use of the X_SCROLL_SIZE keyword implies SCROLL. YOFFSET The vertical offset of the widget in units specified by the UNITS keyword (pixels are the default) relative to its parent. This offset is specified relative to the upper left corner of the parent widget. Specifying an offset relative to a row or column major base widget does not work because those widgets enforce their own layout policies. This keyword is primarily of use relative to a plain base widget. Note that it is best to avoid using this style of widget layout. YSIZE The height of the widget in units specified by the UNITS keyword (pixels are the default). Most widgets attempt to size themselves to fit the situation. However, if the desired effect is not produced, use this keyword to override it. This keyword is only a hint to the toolkit and may be ignored in some situations. By default, draw widgets are 100 pixels wide by 100 pixels high. Y_SCROLL_SIZE The YSIZE keyword always specifies the height of a widget. When the SCROLL keyword is specified, this size is not necessarily the same as the height of the visible area. The Y_SCROLL_SIZE keyword allows you to set the height of the scrolling viewport independently of the actual height of the widget. Use of the Y_SCROLL_SIZE keyword implies SCROLL. Keywords to WIDGET_CONTROL A number of keywords to the WIDGET_CONTROL procedure affect the behavior of draw widgets. In addition to those keywords that affect all widgets, the following are particularly useful: DRAW_BUTTON_EVENTS, DRAW_EXPOSE_EVENTS, DRAW_MOTION_EVENTS, DRAW_VIEWPORT_EVENTS, DRAW_XSIZE, DRAW_YSIZE, GET_DRAW_VIEW, GET_VALUE, INPUT_FOCUS, SET_DRAW_VIEW. Keywords to WIDGET_INFO A number of keywords to the WIDGET_INFO function return information that applies specifically to draw widgets. In addition to those keywords that apply to all widgets, the following are particularly useful: DRAW_BUTTON_EVENTS, DRAW_EXPOSE_EVENTS, DRAW_MOTION_EVENTS, DRAW_VIEWPORT_EVENTS. Widget Events Returned by Draw Widgets By default, draw widgets do not generate events. If the BUTTON_EVENTS keyword is set when the widget is created, pressing or releasing any mouse button while the mouse cursor is over the draw widget causes events to be generated. Specifying the MOTION_EVENTS keyword causes events to be generated continuously as the mouse cursor moves across the draw widget. Specifying the EXPOSE_EVENTS keyword causes events to be generated whenever the visibility of any portion of the draw window (or viewport) changes. The event structure returned by the WIDGET_EVENT function is defined by the following statement: {WIDGET_DRAW, ID:0L, TOP:0L, HANDLER:0L, TYPE: 0, X:0L, Y:0L, PRESS:0B, RELEASE:0B, CLICKS:0, MODIFIERS:0L} Note If you defined your own {WIDGET_DRAW} structures prior to the IDL 5.3 release before the structure was defined by an internal call, the MODIFIERS field will break the existing user code. ID, TOP, and HANDLER are the three standard fields found in every widget event. TYPE returns a value that describes the type of draw widget interaction that generated an event. The values for TYPE are shown in the table below. Value Meaning 0 Button Press 1 Button Release 2 Motion 3 Viewport Moved (Scrollbars) 4 Visibility Changed (Exposed) Table 94: Values for the TYPE field The X and Y fields give the device coordinates at which the event occurred, measured from the lower left corner of the drawing area. PRESS and RELEASE are bitmasks in which the least significant bit represents the leftmost mouse button. The corresponding bit of PRESS is set when a mouse button is pressed, and in RELEASE when the button is released. If the event is a motion event, both PRESS and RELEASE are zero. The CLICKS field returns either 1 or 2. If the time interval between two button-press events is less than the time interval for a double-click event for the platform, the CLICKS field returns 2. If the time interval between button-press events is greater than the time interval for a double-click event for the platform, the CLICKS field returns 1. This means that if you are writing a widget application that requires the user to double-click on a draw widget, you will need to handle two events. The CLICKS field will return a 1 on the first click and a 2 on the second click. The MODIFIERS field is valid for button press, button release and motion events. It is a bitmask which returns the current state of several keyboard modifier keys at the time the event was generated. If a bit is zero, the key is up. If the bit is set, the key is depressed. The value is generated by OR-ing the following values together if a key is depressed. Bitmask Modifier Key 1 Shift 2 Control 4 Caps Lock 8 Alt (See Note following this table.) Table 31: Bitmask for the MODIFIERS Field Note Under UNIX, the Alt key is the currently mapped MOD1 key. There is no Alt key on the Macintosh. Note that the CURSOR procedure is only for use with IDL graphics windows. It should not be used with draw widgets. To obtain the cursor position and button state information from a draw widget, examine the X, Y, PRESS, and RELEASE fields in the structures returned by the draw widget in response to cursor events. Backing Store Draw widgets with scroll bars rely on backing store to repaint the visible area of the window as it is moved. Their performance is best on systems that provide backing store. However, if your system does not automatically provide backing store, you can make IDL supply it with the statement: DEVICE, RETAIN=2 or by using the RETAIN keyword to WIDGET_DRAW. Note If you are using graphics acceleration, you may wish to turn off backing store entirely and enable expose events (via the EXPOSE_EVENTS keyword) and redraw the draw widget's contents manually. However, because the number of events generated may be quite high, you may wish to enable a timer as well and only redraw the draw widget periodically. See Also SLIDE_IMAGE, WINDOW WIDGET_DROPLIST [Previous Routine] [Next Routine] [List of Routines] NAME: WIDGET_DROPLIST The WIDGET_DROPLIST function creates "droplist" widgets. A droplist widget is a button with a label that, when selected, reveals a list of options from which to choose. When the user selects a new option from the list, the list disappears and the button title displays the currently-selected option. This action generates an event containing the index of the selected item, which ranges from 0 to the number of elements in the list minus one, and updates the label on the push-button. The returned value of this function is the widget ID of the newly-created droplist widget. Syntax Result = WIDGET_DROPLIST( Parent [, /DYNAMIC_RESIZE] [, EVENT_FUNC=string] [, EVENT_PRO=string] [, FONT=string] [, FRAME=value] [, FUNC_GET_VALUE=string] [, GROUP_LEADER=widget_id] [, KILL_NOTIFY=string] [, /NO_COPY] [, NOTIFY_REALIZE=string] [, PRO_SET_VALUE=string] [, RESOURCE_NAME=string] [, SCR_XSIZE=width] [, SCR_YSIZE=height] [, /SENSITIVE] [, TITLE=string] [, /TRACKING_EVENTS] [, UNAME=string] [, UNITS={0 | 1 | 2}] [, UVALUE=value] [, VALUE=value] [, XOFFSET=value] [, XSIZE=value] [, YOFFSET=value] [, YSIZE=value] ) Arguments Parent The widget ID of the parent widget for the new droplist widget. Keywords DYNAMIC_RESIZE Set this keyword to create a widget that resizes itself to fit its new value whenever its value is changed. Note that this keyword does not take effect when used with the SCR_XSIZE, SCR_YSIZE, XSIZE, or YSIZE keywords. If one of these keywords is also set, the widget will be sized as specified by the sizing keyword and will never resize itself dynamically. EVENT_FUNC A string containing the name of a function to be called by the WIDGET_EVENT function when an event arrives from a widget in the widget hierarchy rooted at the newly-created widget. EVENT_PRO A string containing the name of a procedure to be called by the WIDGET_EVENT function when an event arrives from a widget in the widget hierarchy rooted at the newly-created widget. FONT The name of the font to be used by the widget. The font specified is a "device font" (an X Windows font on Motif systems; a TrueType or PostScript font on Windows or Macintosh systems). See "About Device Fonts" on page 2482 for details on specifying names for device fonts. If this keyword is omitted, the default font is used. Note On Microsoft Windows platforms, if FONT is not specified, IDL uses the system default font. Different versions of Windows use different system default fonts; in general, the system default font is the font appropriate for the version of Windows in question. FRAME The value of this keyword specifies the width of a frame in units specified by the UNITS keyword (pixels are the default) to be drawn around the borders of the widget. Note that this keyword is only a hint to the toolkit, and may be ignored in some instances. FUNC_GET_VALUE A string containing the name of a function to be called when the GET_VALUE keyword to the WIDGET_CONTROL procedure is called for this widget. Using this technique allows you to change the value that should be returned for a widget. Compound widgets use this ability to define their values transparently to the user. GROUP_LEADER The widget ID of an existing widget that serves as "group leader" for the newly- created widget. When a group leader is killed, for any reason, all widgets in the group are also destroyed. A given widget can be in more than one group. The WIDGET_CONTROL procedure can be used to add additional group associations to a widget. It is not possible to remove a widget from an existing group. KILL_NOTIFY Set this keyword to a string that contains the name of a procedure to be called automatically when the specified widget dies. Each widget is allowed a single such "callback" procedure. It can be removed by setting the routine to the null string (''). Note that the procedure specified is used only if you are not using the XMANAGER procedure to manage your widgets. The callback routine is called with the widget identifier as its only argument. At that point, the widget identifier can only be used with the WIDGET_CONTROL procedure to get or set the user value. All other requests that require a widget ID are disallowed for the target widget. The callback is not issued until the WIDGET_EVENT function is called. If you use the XMANAGER procedure to manage your widgets, the value of this keyword is overwritten. Use the CLEANUP keyword to XMANAGER to specify a procedure to be called when a managed widget dies. NO_COPY Usually, when setting or getting widget user values, either at widget creation or using the SET_UVALUE and GET_UVALUE keywords to WIDGET_CONTROL, IDL makes a second copy of the data being transferred. Although this technique is fine for small data, it can have a significant memory cost when the data being copied is large. If the NO_COPY keyword is set, IDL handles these operations differently. Rather than copy the source data, it takes the data away from the source and attaches it directly to the destination. This feature can be used by compound widgets to obtain state information from a UVALUE without all the memory copying that would otherwise occur. However, it has the side effect of causing the source variable to become undefined. On a "set" operation (using the UVALUE keyword to WIDGET_DROPLIST or the SET_UVALUE keyword to WIDGET_CONTROL), the variable passed as value becomes undefined. On a "get" operation (GET_UVALUE keyword to WIDGET_CONTROL), the user value of the widget in question becomes undefined. NOTIFY_REALIZE Set this keyword to a string that contains the name of a procedure to be called automatically when the specified widget is realized. This callback occurs just once (because widgets are realized only once). Each widget is allowed a single such "callback" procedure. It can be removed by setting the routine to the null string (''). The callback routine is called with the widget ID as its only argument. PRO_SET_VALUE A string containing the name of a procedure to be called when the SET_VALUE keyword to the WIDGET_CONTROL procedure is called for this widget. Using this technique allows you to designate a routine that sets the value for a widget. Compound widgets use this ability to define their values transparently to the user. RESOURCE_NAME A string containing an X Window System resource name to be applied to the widget. See "RESOURCE_NAME" on page 1527 for a complete discussion of this keyword. SCR_XSIZE Set this keyword to the desired "screen" width of the widget, in units specified by the UNITS keyword (pixels are the default). In many cases, setting this keyword is the same as setting the XSIZE keyword. SCR_YSIZE Set this keyword to the desired "screen" height of the widget, in units specified by the UNITS keyword (pixels are the default). In many cases, setting this keyword is the same as setting the YSIZE keyword. SENSITIVE Set this keyword to control the initial sensitivity state of the widget. If SENSITIVE is zero, the widget becomes insensitive. If nonzero, it becomes sensitive. When a widget is sensitive, it has normal appearance and can receive user input. For example, a sensitive button widget can be activated by moving the mouse cursor over it and pressing a mouse button. When a widget is insensitive, it indicates the fact by changing its appearance, looking disabled, and it ignores any input. Sensitivity can be used to control when a user is allowed to manipulate the widget. Note that some widgets do not change their appearance when they are made insensitive, but they cease generating events. After creating the widget hierarchy, you can change the sensitivity state using the SENSITIVE keyword with the WIDGET_CONTROL procedure. TITLE Set this keyword to a string to be used as the title for the droplist widget. TRACKING_EVENTS Set this keyword to cause widget tracking events to be issued for the widget whenever the mouse pointer enters or leaves the region covered by that widget. For the structure of tracking events, see "TRACKING_EVENTS" on page 1533 in the documentation for WIDGET_BASE. UNAME Set this keyword to a string that can be used to identify the widget in your code. You can associate a name with each widget in a specific hierarchy, and then use that name to query the widget hierarchy and get the correct widget ID. To query the widget hierarchy, use the WIDGET_INFO function with the FIND_BY_UNAME keyword. The UNAME should be unique to the widget hierarchy because the FIND_BY_UNAME keyword returns the ID of the first widget with the specified name. UNITS Set UNITS equal to 0 (zero) to specify that all measurements are in pixels (this is the default), to 1 (one) to specify that all measurements are in inches, or to 2 (two) to specify that all measurements are in centimeters. UVALUE The "user value" to be assigned to the widget. Each widget can contain a user-specified value of any data type and organization. This value is not used by the widget in any way, but exists entirely for the convenience of the IDL programmer. This keyword allows you to set this value when the widget is first created. If UVALUE is not present, the widget's initial user value is undefined. VALUE The initial value setting of the widget. The value of a droplist widget is a scalar string or array of strings that contains the text of the list items-one list item per array element. List widgets are sized based on the length (in characters) of the longest item specified in the array of values for the VALUE keyword. XOFFSET The horizontal offset of the widget in units specified by the UNITS keyword (pixels are the default) relative to its parent. Specifying an offset relative to a row or column major base widget does not work because those widgets enforce their own layout policies. This keyword is primarily of use relative to a plain base widget. Note that it is best to avoid using this style of widget programming. XSIZE The desired width of the droplist widget area, in units specified by the UNITS keyword (pixels are the default). Most widgets attempt to size themselves to fit the situation. However, if the desired effect is not produced, use this keyword to override it. This keyword does not control the size of the droplist button or of the dropped list. Instead, it controls the size "around" the droplist button and, as such, is not particularly useful. YOFFSET The vertical offset of the widget in units specified by the UNITS keyword (pixels are the default) relative to its parent. This offset is specified relative to the upper left corner of the parent widget. Specifying an offset relative to a row or column major base widget does not work because those widgets enforce their own layout policies. This keyword is primarily of use relative to a plain base widget. Note that it is best to avoid using this style of widget programming. YSIZE The desired height of the widget, in units specified by the UNITS keyword (pixels are the default). Most widgets attempt to size themselves to fit the situation. However, if the desired effect is not produced, use this keyword to override it. This keyword does not control the size of the droplist button or of the dropped list. Instead, it controls the size "around" the droplist button and, as such, is not particularly useful. Keywords to WIDGET_CONTROL A number of keywords to the WIDGET_CONTROL procedure affect the behavior of droplist widgets. In addition to those keywords that affect all widgets, the following are particularly useful: DYNAMIC_RESIZE, SET_DROPLIST_SELECT, SET_VALUE. Keywords to WIDGET_INFO A number of keywords to the WIDGET_INFO function return information that applies specifically to droplist widgets. In addition to those keywords that apply to all widgets, the following are particularly useful: DROPLIST_NUMBER, DROPLIST_SELECT, DYNAMIC_RESIZE. Widget Events Returned by Droplist Widgets Pressing the mouse button while the mouse cursor is over an element of a droplist widget causes the widget to change the label on the droplist button and to generate an event. The appearance of any previously selected element is restored to normal at the same time. The event structure returned by the WIDGET_EVENT function is defined by the following statement: { WIDGET_DROPLIST, ID:0L, TOP:0L, HANDLER:0L, INDEX:0L } The first three fields are the standard fields found in every widget event. INDEX returns the index of the selected item. This can be used to index the array of names originally used to set the widget's value. Note Platform-specific UI toolkits behave differently if a droplist widget has only a single element. On some platforms, selecting that element again does not generate an event. Events are always generated if the list contains multiple items. See Also CW_PDMENU, WIDGET_BUTTON, WIDGET_LIST WIDGET_EVENT [Previous Routine] [Next Routine] [List of Routines] NAME: WIDGET_EVENT The WIDGET_EVENT function returns events for the widget hierarchy rooted at Widget_ID. Widgets communicate information by generating events. Events are generated when a button is pressed, a slider position is changed, and so forth. Note Widget applications should use the XMANAGER procedure in preference to calling WIDGET_EVENT directly. See "Widget Events" in Chapter 22 of Building IDL Applications. Syntax Result = WIDGET_EVENT([Widget_ID]) [, BAD_ID=variable] [, /NOWAIT] [, /SAVE_HOURGLASS] UNIX Keywords: [, /YIELD_TO_TTY] Arguments Widget_ID Widget_ID specifies the widget hierarchy for which events are desired. The first available event for the specified widget or any of its children is returned. If this argument is not specified, WIDGET_EVENT processes events for all existing widgets. Widget_ID can also be an array of widget identifiers, in which case all of the specified widget hierarchies are searched. Note Attempting to obtain events for a widget hierarchy which is not producing events will hang IDL, unless the NOWAIT keyword is used. Keywords BAD_ID If one of the values supplied via Widget_ID is not a valid widget identifier, this function normally issues an error and causes program execution to stop. However, if BAD_ID is present and specifies a named variable, the invalid ID is stored into the variable, and this routine quietly returns. If no error occurs, a zero is stored. This keyword can be used to handle the situation in which IDL is waiting within WIDGET_EVENT when the user kills the widget hierarchy. This keyword has meaning only if Widget_ID is explicitly specified. NOWAIT When no events are currently available for the specified widget hierarchy, WIDGET_EVENT normally waits until one is available and then returns it. However, if NOWAIT is set and no events are present, it immediately returns. In this case, the ID field of the returned structure will be zero. SAVE_HOURGLASS Set this keyword to prevent the hourglass cursor from being cleared by WIDGET_EVENT. This keyword can be of use if a program has to poll a widget periodically during a long computation. YIELD_TO_TTY Unless the NOWAIT keyword is specified, WIDGET_EVENT does not return until the asked for event is available. If the user should enter a line of input from the keyboard, it cannot be processed until WIDGET_EVENT returns. If the YIELD_TO_TTY keyword is specified and the user enters a line of input, WIDGET_EVENT returns immediately. In this case, the ID field of the returned structure will be zero. Note This keyword is supported under UNIX only, and there are no plans to extend it to other operating systems. Do not use it if you intend to use non-UNIX systems. Event Processing All events for a given widget are processed in the order that they are generated. The event processing performed by WIDGET_EVENT consists of the following steps: 1. Wait for an event from one of the specified widgets to arrive. 2. Starting with the widget that the event belongs to, move up the widget hierarchy looking for a widget that has an event handling procedure or function associated with it. Such routines are associated with a widget via the EVENT_PRO and EVENT_FUNC keywords to the widget creation functions or the WIDGET_CONTROL procedure. 3. If an event handling procedure is found, it is called with the widget ID as its argument. When the procedure returns, WIDGET_EVENT returns to the first step. Hence, event procedures are said to "swallow" events. 4. If an event handling function is found, it is called with the widget ID as its argument. When the function returns, its value is examined. If the value is a non-structure, it is discarded and WIDGET_EVENT returns to the first step. This behavior allows event functions to selectively act like event procedures and swallow events. If the returned value is a structure, it is checked to ensure that it has the standard first 3 fields: ID, TOP, and HANDLER. If not an error is issued. Otherwise the value replaces the event found in the first step and WIDGET_EVENT returns to the second step. Hence, event functions are said to "rewrite" events. This ability to rewrite events is the basis of the "compound widget" in which several widgets are combined to give the appearance of a single, more complicated widget. 5. If an event reaches the top of a widget hierarchy without being swallowed by an event handler, it is returned as the value of WIDGET_EVENT. Events A widget event is returned in a structure. The exact contents of this structure vary depending upon the type of widget involved. The first three elements of this structure, however, are always the same. Any other elements vary from widget type to type. The three fixed elements are: ID The widget ID of the widget that generated the event. TOP The widget ID of the top level base for the widget hierarchy containing ID. HANDLER When an event is passed as the argument to an event handling procedure or function, as discussed in the previous section, this field contains the identifier of the widget associated with the handler routine. When an event is returned from WIDGET_EVENT, this value is always zero to indicate that no handler routine was found. See Also XMANAGER WIDGET_INFO [Previous Routine] [Next Routine] [List of Routines] NAME: WIDGET_INFO The WIDGET_INFO function is used to obtain information about the widget subsystem and individual widgets. The specific area for which information is desired is selected by setting the appropriate keyword. Syntax Result = WIDGET_INFO( [Widget_ID] ) Keywords that apply to all widgets: [, CONTEXT_EVENTS] [, SYSTEM_COLORS] [, /ACTIVE] [, /CHILD] [, /EVENT_FUNC] [, /EVENT_PRO] [, FIND_BY_UNAME=string] [, /GEOMETRY] [, /KBRD_FOCUS_EVENTS] [, /MANAGED] [, /NAME] [, /PARENT] [, /REALIZED] [, /SIBLING] [, /TRACKING_EVENTS] [, /TYPE] [, UNITS={0 | 1 | 2}] [, /UNAME] [, /UPDATE] [, /VALID_ID] [, /VERSION] Keywords that apply to widgets created with widget_base: [, /MODAL] [, /TLB_KILL_REQUEST_EVENTS] Keywords that apply to widgets created with widget_button: [, /DYNAMIC_RESIZE] Keywords that apply to widgets created with widget_draw: [, /DRAW_BUTTON_EVENTS] [, /DRAW_EXPOSE_EVENTS] [, /DRAW_MOTION_EVENTS] [, /DRAW_VIEWPORT_EVENTS] Keywords that apply to widgets created with widget_droplist: [, /DROPLIST_NUMBER] [, /DROPLIST_SELECT] [, /DYNAMIC_RESIZE] Keywords that apply to widgets created with widget_label: [, /DYNAMIC_RESIZE] Keywords that apply to widgets created with widget_list: [, /LIST_MULTIPLE] [, /LIST_NUMBER] [, /LIST_NUM_VISIBLE] [, /LIST_SELECT] [, /LIST_TOP] Keywords that apply to widgets created with widget_slider: [, /SLIDER_MIN_MAX] Keywords that apply to widgets created with widget_table: [, /COLUMN_WIDTHS] [, /ROW_HEIGHTS{not supported in Windows}] [, /TABLE_ALL_EVENTS] [, /TABLE_EDITABLE] [, /TABLE_EDIT_CELL] [, /TABLE_SELECT] [, /TABLE_VIEW] [, /USE_TABLE_SELECT] Keywords that apply to widgets created with widget_text: [, /TEXT_ALL_EVENTS] [, /TEXT_EDITABLE] [, /TEXT_NUMBER] [, TEXT_OFFSET_TO_XY=integer] [, /TEXT_SELECT] [, /TEXT_TOP_LINE] [, TEXT_XY_TO_OFFSET=[column, line]] Arguments Widget_ID Usually this argument should be the widget ID of the widget for which information is desired. If the ACTIVE or VERSION keywords are specified, this argument is not required. Widget_ID can also be an array of widget identifiers, in which case the result is an array with the same structure in which information on all the specified widgets is returned. Keywords SYSTEM_COLORS (Windows, UNIX only) This new keyword requires a valid IDL widget identifier and returns an IDL structure named WIDGET_SYSTEM_COLORS. The structure contains RGB values for 25 display elements. Each RGB value is a three-dimensional array of integers representing the red, green, blue values in the range 0 to 255 or a value of ­1 if unavailable. For more detailed information on the WIDGET_SYSTEM_COLORS structure fields and their meaning see the "Emulating System Colors in Application Widgets" on page 41. CONTEXT_EVENTS (Windows, UNIX only) Set this new keyword to return 1 if Widget_ID is a widget with the CONTEXT_EVENTS attribute set. Otherwise, 0 is returned. This keyword applies to widgets created with WIDGET_BASE, WIDGET_TEXT, or WIDGET_LIST. Not all keywords to WIDGET_INFO apply to all combinations of widgets. In the following list, descriptions of keywords that affect only certain types of widgets include a list of the widgets for which the keyword is useful. ACTIVE This keyword applies to all widgets. Set this keyword to return 1 if there is at least one realized, managed, top-level widget on the screen. Otherwise, 0 is returned. CHILD This keyword applies to all widgets. Set this keyword to return the widget ID of the first child of the widget specified by Widget_ID. If the widget has no children, 0 is returned. COLUMN_WIDTHS This keyword applies to widgets created with the WIDGET_TABLE function. Set this keyword to return an array of long integers giving the width of each column in the table. If USE_TABLE_SELECT is set, only the column widths for the currently-selected cells are returned. DRAW_BUTTON_EVENTS This keyword applies to widgets created with the WIDGET_DRAW function. Set this keyword to return 1 if Widget_ID is a draw widget with the BUTTON_EVENTS attribute set. Otherwise, 0 is returned. DRAW_EXPOSE_EVENTS This keyword applies to widgets created with the WIDGET_DRAW function. Set this keyword to return 1 if Widget_ID is a draw widget with the EXPOSE_EVENTS attribute set. Otherwise, 0 is returned. DRAW_MOTION_EVENTS This keyword applies to widgets created with the WIDGET_DRAW function. Set this keyword to return 1 if Widget_ID is a draw widget with the MOTION_EVENTS attribute set. Otherwise, 0 is returned. DRAW_VIEWPORT_EVENTS This keyword applies to widgets created with the WIDGET_DRAW function. Set this keyword to return 1 if Widget_ID is a draw widget with the VIEWPORT_EVENTS attribute set. Otherwise, 0 is returned. DROPLIST_NUMBER This keyword applies to widgets created with the WIDGET_DROPLIST function. Set this keyword to return the number of elements currently contained in the specified droplist widget. DROPLIST_SELECT This keyword applies to widgets created with the WIDGET_DROPLIST function. Set this keyword to return the zero-based number of the currently-selected element (i.e., the currently-displayed element) in the specified droplist widget. DYNAMIC_RESIZE This keyword applies to widgets created with the WIDGET_BUTTON, WIDGET_DROPLIST, and WIDGET_LABEL functions. Set this keyword to return a True value (1) if the widget specified by Widget_ID is a button, droplist, or label widget that has had its DYNAMIC_RESIZE attribute set. Otherwise, False (0) is returned. EVENT_FUNC This keyword applies to all widgets. Set this keyword to return a string containing the name of the event handler function associated with Widget_ID. A null string is returned if no event handler function exists. EVENT_PRO This keyword applies to all widgets. Set this keyword to return a string containing the name of the event handler procedure associated with Widget_ID. A null string is returned if no event handler procedure exists. FIND_BY_UNAME This keyword applies to all widgets. Set this keyword to a UNAME value that will be searched for in the widget hierarchy, and if a widget with the given UNAME is in the hierarchy, its ID is returned. The search starts in the hierarchy with the given widget ID and travels down, and this keyword returns the widget ID of the first widget that has the specified UNAME value. If a widget is not found, 0 is returned. GEOMETRY This keyword applies to all widgets. Set this keyword to return a WIDGET_GEOMETRY structure that describes the offset and size information for the widget specified by Widget_ID. This structure has the following definition: { WIDGET_GEOMETRY, XOFFSET:0.0, YOFFSET:0.0, XSIZE:0.0, YSIZE:0.0, SCR_XSIZE:0.0, SCR_YSIZE:0.0, DRAW_XSIZE:0.0, DRAW_YSIZE:0.0, MARGIN:0.0, XPAD:0.0, YPAD:0.0, SPACE:0.0 } With the exception of MARGIN, all of the structure's fields correspond to the keywords of the same name to the various widget routines. MARGIN is the width of any frame added to the widget, in units specified by the UNITS keyword (pixels are the default). Therefore, the actual width of any widget is: SCR_XSIZE + (2* MARGIN) The actual height of any widget is: SCR_YSIZE + (2 * MARGIN) Note also that if the top-level base includes a menubar, it is not possible to determine the actual height of the base widget. Calling WIDGET_INFO with the GEOMETRY keyword on a top level base that includes a menubar will return a geometry structure that contains zeroes rather than the actual sizes of the widget. Note Menubars are not included in the size of a top-level base, so the actual height of a widget that includes a menubar is: SCR_YSIZE + (2 * MARGIN) + menubar height It is not possible to either determine or change the height of a menubar within IDL. Retrieving the WIDGET_GEOMETRY structure of a menubar yields a structure with all the fields set equal to zero. KBRD_FOCUS_EVENTS This keyword applies to all widgets. Set this keyword to return the keyboard focus events status of the widget specified by Widget ID. WIDGET_INFO returns 1 (one) if keyboard focus events are currently enabled for the widget, or 0 (zero) if they are not. Only base, table, and text widgets can generate keyboard focus events. LIST_MULTIPLE This keyword applies to widgets created with the WIDGET_LIST function. Set this keyword equal to a named variable that will contain a non-zero value if the list widget supports multiple item selections. See the MULTIPLE keyword to WIDGET_LIST for more on multiple item selections. LIST_NUMBER This keyword applies to widgets created with the WIDGET_LIST function. Set this keyword to return the number of elements currently contained in the specified list widget. LIST_NUM_VISIBLE This keyword applies to widgets created with the WIDGET_LIST function. Set this keyword to return the number of elements that can be visible in the scrolling viewport of the specified list widget. Note that this value can be larger than the total number of elements actually in the list. LIST_SELECT This keyword applies to widgets created with the WIDGET_LIST function. Set this keyword to return the index or indices of the currently-selected (highlighted) element or elements in the specified list widget. Note that this offset is zero-based. If no element is currently selected, -1 is returned. LIST_TOP This keyword applies to widgets created with the WIDGET_LIST function. Set this keyword to return the zero-based offset of the topmost element currently visible in the specified list widget. MANAGED This keyword applies to all widgets. Set this keyword to return 1 if the specified widget is managed, or 0 otherwise. If no widget ID is specified in the call to WIDGET_INFO, the return value will be an array containing the widget IDs of all currently-managed widgets. MODAL This keyword applies to widgets created with the WIDGET_BASE function and the MODAL keyword. If this keyword is set, WIDGET_INFO will return True (1) if the base widget specified by Widget_ID is a modal base widget, or False (0) otherwise. NAME This keyword applies to all widgets. Set this keyword to return the widget type name of the widget specified by Widget_ID. The returned value will be one of the following strings: "BASE", "BUTTON", "DRAW", "DROPLIST", "LABEL", "LIST", "SLIDER", "TABLE", or "TEXT". Set the TYPE keyword to return the widget's type code. PARENT This keyword applies to all widgets. Set this keyword to return the widget ID of the parent of the widget specified by Widget_ID. If the widget is a top-level base (i.e., it has no parent), 0 is returned. REALIZED This keyword applies to all widgets. Set this keyword to return 1 if the widget specified by Widget_ID has been realized. If the widget has not been realized, 0 is returned. ROW_HEIGHTS This keyword applies to widgets created with the WIDGET_TABLE function. Note This keyword is not supported under Microsoft Windows. Set this keyword to return an array of long integers giving the height of each row in the table. If USE_TABLE_SELECT is set, only the row heights for the currently- selected cells are returned. SIBLING This keyword applies to all widgets. Set this keyword to return the widget ID of the first sibling of the widget specified by Widget_ID. If the widget is the last sibling in the chain, 0 is returned. SLIDER_MIN_MAX This keyword applies to widgets created with the WIDGET_SLIDER function. Set this keyword to return the current minimum and maximum values of the specified slider as a two-element integer array. Element 0 is the minimum value and element 1 is the maximum value. TABLE_ALL_EVENTS This keyword applies to widgets created with the WIDGET_TABLE function. Set this keyword to return 1 (one) if Widget_ID is a table widget with the ALL_EVENTS attribute set. Otherwise, 0 (zero) is returned. TABLE_EDITABLE This keyword applies to widgets created with the WIDGET_TABLE function. Set this keyword to return 1 (one) if Widget_ID is a table widget that allows user editing of its contents. Otherwise, 0 (zero) is returned. TABLE_EDIT_CELL This keyword applies to widgets created with the WIDGET_TABLE function. Set this keyword to return a two-element integer array containing the X and Y coordinates of the currently editable cell. If none of the cells in the table widget is currently editable, the array [-1, -1] is returned. TABLE_SELECT This keyword applies to widgets created with the WIDGET_TABLE function. Set this keyword to return an array of the form [ left, top, right, bottom ] containing the zero-based indices of the currently-selected (highlighted) cells in the specified table widget. TABLE_VIEW This keyword applies to widgets created with the WIDGET_TABLE function. Set this keyword to return a two-element array of the form [left, top] containing the zero-based offsets of the top-left cell currently visible in the specified table widget. TEXT_ALL_EVENTS This keyword applies to widgets created with the WIDGET_TEXT function. Set this keyword to return 1 if Widget_ID is a text widget with the ALL_EVENTS attribute set. Otherwise, 0 is returned. TEXT_EDITABLE This keyword applies to widgets created with the WIDGET_TEXT function. Set this keyword to return 1 if Widget_ID is a text widget that allows user editing of its contents. Otherwise, 0 is returned. TEXT_NUMBER This keyword applies to widgets created with the WIDGET_TEXT function. Set this keyword to return the number of characters currently contained in the specified text widget. TEXT_OFFSET_TO_XY This keyword applies to widgets created with the WIDGET_TEXT function. Use this keyword to translate a text widget character offset into column and line form. The value of this keyword should be set to the character offset (an integer) to be translated. WIDGET_INFO returns a two-element integer array giving the column (element 0) and line (element 1) corresponding to the offset. If the offset specified is out of range, the array [-1,-1] is returned. TEXT_SELECT This keyword applies to widgets created with the WIDGET_TEXT function. Set this keyword to return the starting character offset and length (in characters) of the selected (highlighted) text in the specified text widget. WIDGET_INFO returns a two-element integer array containing the starting position of the highlighted text as an offset from character zero of the text in the widget (element 0), and length of the current selection (element 1). TEXT_TOP_LINE This keyword applies to widgets created with the WIDGET_TEXT function. Set this keyword to return the zero-based line number of the line currently at the top of a text widget's display viewport. Note that this value is different from the zero- based character offset of the characters in the line. The character offset can be calculated from the line offset via the TEXT_XY_TO_OFFSET keyword. TEXT_XY_TO_OFFSET This keyword applies to widgets created with the WIDGET_TEXT function. Use this keyword to translate a text widget position given in line and column form into a character offset. The value of this keyword should be set to a two-element integer array specifying the column (element 0) and line (element 1) position. WIDGET_INFO returns the character offset (as a longword integer) corresponding to the position. If the position specified is out of range, -1 is returned. TLB_KILL_REQUEST_EVENTS This keyword applies to widgets created with the WIDGET_BASE function. Set this keyword to return 1 if the top-level base of the widget specified by Widget_ID is set to return kill request events. Otherwise, 0 is returned. TRACKING_EVENTS This keyword applies to all widgets. Set this keyword to return the tracking events status for the widget specified by Widget_ID. WIDGET_INFO returns 1 if tracking events are currently enabled for the widget. Otherwise, 0 is returned. TYPE This keyword applies to all widgets. Set this keyword to return the type code of the specified Widget_ID. Possible values are given the following table. Note that you can set the NAME keyword to return string names instead. Value Type 0 Base 1 Button 2 Slider 3 Text 4 Draw 5 Label 6 List 8 Droplist 9 Table Table 95: Widget Type Codes UNAME This keyword applies to all widgets. Set this keyword to have the WIDGET_INFO function return the user name of the widget. UNITS This keyword applies to all widgets. Use this keyword to specify the unit of measurement used when returning dimensions for most widget types. Set UNITS equal to 0 (zero) to specify that all measurements are in pixels (this is the default), to 1 (one) to specify that all measurements are in inches, or to 2 (two) to specify that all measurements are in centimeters. Note This keyword does not affect all sizing operations. Specifically, the value of UNITS is ignored when retrieving the XSIZE or YSIZE of a WIDGET_LIST, WIDGET_TABLE, or WIDGET_TEXT. UPDATE This keyword applies to all widgets. Set this keyword to return 1 if the widget hierarchy that contains Widget_ID is set to display updates. Otherwise, 0 is returned. See "UPDATE" on page 1574. USE_TABLE_SELECT This keyword applies to widgets created with the WIDGET_TABLE function. Set this keyword to modify the behavior of the COLUMN_WIDTHS and ROW_HEIGHTS keywords. If USE_TABLE_SELECT is set, the COLUMN_WIDTHS and ROW_HEIGHTS keywords only apply to the currently- selected cells. Normally, these keywords apply to the entire contents of a table widget. The USE_TABLE_SELECT keyword can also be specified as a four-element array, of the form [left, top, right, bottom], giving the group of cells to act on. In this usage, the value -1 is used to refer to the row or column titles. VALID_ID This keyword applies to all widgets. Set this keyword to return 1 if Widget_ID represents a currently-valid widget. Otherwise, 0 is returned. VERSION This keyword applies to all widgets. Set this keyword to return a structure that gives information about the widget implementation. This structure has the following definition: { WIDGET_VERSION, STYLE:'', TOOLKIT:'', RELEASE:'' } STYLE is the style of widget toolkit used. TOOLKIT is the implementation of the toolkit. RELEASE is the version level of the toolkit. This field can be used to distinguish between different releases of a given toolkit, such as Motif 1.0 and Motif 1.1. WIDGET_LABEL [Previous Routine] [Next Routine] [List of Routines] NAME: WIDGET_LABEL The WIDGET_LABEL function is used to create label widgets. The returned value of this function is the widget ID of the newly-created label widget. Syntax Result = WIDGET_LABEL( Parent [, /ALIGN_CENTER | , /ALIGN_LEFT | , /ALIGN_RIGHT] [, /DYNAMIC_RESIZE] [, FONT=string] [, FRAME=width] [, FUNC_GET_VALUE=string] [, GROUP_LEADER=widget_id] [, KILL_NOTIFY=string] [, /NO_COPY] [, NOTIFY_REALIZE=string] [, PRO_SET_VALUE=string] [, RESOURCE_NAME=string] [, SCR_XSIZE=width] [, SCR_YSIZE=height] [, /SENSITIVE] [, /TRACKING_EVENTS] [, UNAME=string] [, UNITS={0 | 1 | 2}] [, UVALUE=value] [, VALUE=value] [, XOFFSET=value] [, XSIZE=value] [, YOFFSET=value] [, YSIZE=value] ) Arguments Parent The widget ID of the parent widget for the new label widget. Keywords ALIGN_CENTER Set this keyword to center justify the label text. ALIGN_LEFT Set this keyword to left justify the label text. ALIGN_RIGHT Set this keyword to right justify the label text. DYNAMIC_RESIZE Set this keyword to create a widget that resizes itself to fit its new value whenever its value is changed. Note that this keyword cannot be used with the SCR_XSIZE, SCR_YSIZE, XSIZE, or YSIZE keywords. If one of these keywords is also set, the widget will be sized as specified by the sizing keyword and will never resize itself dynamically. FONT The name of the font to be used by the widget. The font specified is a "device font" (an X Windows font on Motif systems; a TrueType or PostScript font on Windows systems). See "About Device Fonts" on page 2482 for details on specifying names for device fonts. If this keyword is omitted, the default font is used. Note On Microsoft Windows platforms, if FONT is not specified, IDL uses the system default font. Different versions of Windows use different system default fonts; in general, the system default font is the font appropriate for the version of Windows in question. This keyword is not supported on the Macintosh. FRAME The value of this keyword specifies the width of a frame in units specified by the UNITS keyword (pixels are the default) to be drawn around the borders of the widget. Note that this keyword is only a "hint" to the toolkit, and may be ignored in some instances. FUNC_GET_VALUE A string containing the name of a function to be called when the GET_VALUE keyword to the WIDGET_CONTROL procedure is called for this widget. Using this technique allows you to change the value that should be returned for a widget. Compound widgets use this ability to define their values transparently to the user. GROUP_LEADER The widget ID of an existing widget that serves as "group leader" for the newly- created widget. When a group leader is killed, for any reason, all widgets in the group are also destroyed. A given widget can be in more than one group. The WIDGET_CONTROL procedure can be used to add additional group associations to a widget. It is not possible to remove a widget from an existing group. KILL_NOTIFY Set this keyword to a string that contains the name of a procedure to be called automatically when the specified widget dies. Each widget is allowed a single such "callback" procedure. It can be removed by setting the routine to the null string (''). Note that the procedure specified is used only if you are not using the XMANAGER procedure to manage your widgets. The callback routine is called with the widget identifier as its only argument. At that point, the widget identifier can only be used with the WIDGET_CONTROL procedure to get or set the user value. All other requests that require a widget ID are disallowed for the target widget. The callback is not issued until the WIDGET_EVENT function is called. If you use the XMANAGER procedure to manage your widgets, the value of this keyword is overwritten. Use the CLEANUP keyword to XMANAGER to specify a procedure to be called when a managed widget dies. NO_COPY Usually, when setting or getting widget user values, either at widget creation or using the SET_UVALUE and GET_UVALUE keywords to WIDGET_CONTROL, IDL makes a second copy of the data being transferred. Although this technique is fine for small data, it can have a significant memory cost when the data being copied is large. If the NO_COPY keyword is set, IDL handles these operations differently. Rather than copy the source data, it takes the data away from the source and attaches it directly to the destination. This feature can be used by compound widgets to obtain state information from a UVALUE without all the memory copying that would otherwise occur. However, it has the side effect of causing the source variable to become undefined. On a "set" operation (using the UVALUE keyword to WIDGET_LABEL or the SET_UVALUE keyword to WIDGET_CONTROL), the variable passed as value becomes undefined. On a "get" operation (GET_UVALUE keyword to WIDGET_CONTROL), the user value of the widget in question becomes undefined. NOTIFY_REALIZE Set this keyword to a string that contains the name of a procedure to be called automatically when the specified widget is realized. This callback occurs just once (because widgets are realized only once). Each widget is allowed a single such "callback" procedure. It can be removed by setting the routine to the null string (''). The callback routine is called with the widget ID as its only argument. PRO_SET_VALUE A string containing the name of a procedure to be called when the SET_VALUE keyword to the WIDGET_CONTROL procedure is called for this widget. Using this technique allows you to designate a routine that sets the value for a widget. Compound widgets use this ability to define their values transparently to the user. RESOURCE_NAME A string containing an X Window System resource name to be applied to the widget. See "RESOURCE_NAME" on page 1527 for a complete discussion of this keyword. SCR_XSIZE Set this keyword to the desired "screen" width of the widget, in units specified by the UNITS keyword (pixels are the default). In many cases, setting this keyword is the same as setting the XSIZE keyword. SCR_YSIZE Set this keyword to the desired "screen" height of the widget, in units specified by the UNITS keyword (pixels are the default). In many cases, setting this keyword is the same as setting the YSIZE keyword. SENSITIVE Set this keyword to control the initial sensitivity state of the widget. If SENSITIVE is zero, the widget becomes insensitive. If nonzero, it becomes sensitive. When a widget is sensitive, it has normal appearance and can receive user input. For example, a sensitive button widget can be activated by moving the mouse cursor over it and pressing a mouse button. When a widget is insensitive, it indicates the fact by changing its appearance, looking disabled, and it ignores any input. Sensitivity can be used to control when a user is allowed to manipulate the widget. Note that some widgets do not change their appearance when they are made insensitive, but they cease generating events. After creating the widget hierarchy, you can change the sensitivity state using the SENSITIVE keyword with the WIDGET_CONTROL procedure. TRACKING_EVENTS Set this keyword to cause widget tracking events to be issued for the widget whenever the mouse pointer enters or leaves the region covered by that widget. For the structure of tracking events, see "TRACKING_EVENTS" on page 1533 in the documentation for WIDGET_BASE. UNAME Set this keyword to a string that can be used to identify the widget in your code. You can associate a name with each widget in a specific hierarchy, and then use that name to query the widget hierarchy and get the correct widget ID. To query the widget hierarchy, use the WIDGET_INFO function with the FIND_BY_UNAME keyword. The UNAME should be unique to the widget hierarchy because the FIND_BY_UNAME keyword returns the ID of the first widget with the specified name. UNITS Set UNITS equal to 0 (zero) to specify that all measurements are in pixels (this is the default), to 1 (one) to specify that all measurements are in inches, or to 2 (two) to specify that all measurements are in centimeters. UVALUE The "user value" to be assigned to the widget. Each widget can contain a user-specified value of any data type and organization. This value is not used by the widget in any way, but exists entirely for the convenience of the IDL programmer. This keyword allows you to set this value when the widget is first created. If UVALUE is not present, the widget's initial user value is undefined. VALUE The initial value setting of the widget. The value of a widget label is a string containing the text for the label. XOFFSET The horizontal offset of the widget in units specified by the UNITS keyword (pixels are the default) relative to its parent. Specifying an offset relative to a row or column major base widget does not work because those widgets enforce their own layout policies. This keyword is primarily of use relative to a plain base widget. Note that it is best to avoid using this style of widget programming. XSIZE The width of the widget in units specified by the UNITS keyword (pixels are the default). Most widgets attempt to size themselves to fit the situation. However, if the desired effect is not produced, use this keyword to override it. This keyword is only a "hint" to the toolkit and may be ignored in some situations. YOFFSET The vertical offset of the widget in units specified by the UNITS keyword (pixels are the default) relative to its parent. This offset is specified relative to the upper left corner of the parent widget. Specifying an offset relative to a row or column major base widget does not work because those widgets enforce their own layout policies. This keyword is primarily of use relative to a plain base widget. Note that it is best to avoid using this style of widget programming. YSIZE The height of the widget in units specified by the UNITS keyword (pixels are the default). Most widgets attempt to size themselves to fit the situation. However, if the desired effect is not produced, use this keyword to override it. This keyword is only a "hint" to the toolkit and may be ignored in some situations. Keywords to WIDGET_CONTROL A number of keywords to the WIDGET_CONTROL procedure affect the behavior of label widgets. In addition to those keywords that affect all widgets, the following are particularly useful: DYNAMIC_RESIZE, GET_VALUE, SET_VALUE. Keywords to WIDGET_INFO Some keywords to the WIDGET_INFO function return information that applies specifically to label widgets. In addition to those keywords that apply to all widgets, the following are particularly useful: DYNAMIC_RESIZE. Widget Events Returned by Label Widgets Label widgets do not return an event structure. See Also CW_FIELD, WIDGET_TEXT WIDGET_LIST [Previous Routine] [Next Routine] [List of Routines] NAME: WIDGET_LIST The WIDGET_LIST function is used to create list widgets. A list widget offers the user a list of text elements from which to choose. The user can select an item by pointing at it with the mouse cursor and pressing a button. This action generates an event containing the index of the selected item, which ranges from 0 to the number of elements in the list minus one. The returned value of this function is the widget ID of the newly-created list widget. Syntax Result = WIDGET_LIST( Parent [, CONTEXT_EVENTS] [, EVENT_FUNC=string] [, EVENT_PRO=string] [, FONT=string] [, FRAME=width] [, FUNC_GET_VALUE=string] [, GROUP_LEADER=widget_id] [, KILL_NOTIFY=string] [, /MULTIPLE] [, /NO_COPY] [, NOTIFY_REALIZE=string] [, PRO_SET_VALUE=string] [, RESOURCE_NAME=string] [, SCR_XSIZE=width] [, SCR_YSIZE=height] [, /SENSITIVE] [, /TRACKING_EVENTS] [, UNAME=string] [, UNITS={0 | 1 | 2}] [, UVALUE=value] [, VALUE=value] [, XOFFSET=value] [, XSIZE=value] [, YOFFSET=value] [, YSIZE=value] ) Arguments Parent The widget ID of the parent widget for the new list widget. Keywords CONTEXT_EVENTS (Windows, UNIX only) Set this new keyword to generate context events when the right mouse button is pressed over the widget. To request right mouse button events in a draw widget use the BUTTON_EVENTS keyword to WIDGET_DRAW at creation or the DRAW_BUTTON_EVENTS keyword to WIDGET_CONTROL for an existing draw widget. A right button press generates a WIDGET_DRAW event with the EVENT.TYPE field equal to 0 and the EVENT.RELEASE field equal to 4. EVENT_FUNC A string containing the name of a function to be called by the WIDGET_EVENT function when an event arrives from a widget in the widget hierarchy rooted at the newly-created widget. EVENT_PRO A string containing the name of a procedure to be called by the WIDGET_EVENT function when an event arrives from a widget in the widget hierarchy rooted at the newly-created widget. FONT The name of the font to be used by the widget. The font specified is a "device font" (an X Windows font on Motif systems; a TrueType or PostScript font on Windows or Macintosh systems). See "About Device Fonts" on page 2482 for details on specifying names for device fonts. If this keyword is omitted, the default font is used. Note On Microsoft Windows platforms, if FONT is not specified, IDL uses the system default font. Different versions of Windows use different system default fonts; in general, the system default font is the font appropriate for the version of Windows in question. FRAME The value of this keyword specifies the width of a frame in units specified by the UNITS keyword (pixels are the default) to be drawn around the borders of the widget. Note that this keyword is only a "hint" to the toolkit, and may be ignored in some instances. FUNC_GET_VALUE A string containing the name of a function to be called when the GET_VALUE keyword to the WIDGET_CONTROL procedure is called for this widget. Using this technique allows you to change the value that should be returned for a widget. Compound widgets use this ability to define their values transparently to the user. GROUP_LEADER The widget ID of an existing widget that serves as "group leader" for the newly- created widget. When a group leader is killed, for any reason, all widgets in the group are also destroyed. A given widget can be in more than one group. The WIDGET_CONTROL procedure can be used to add additional group associations to a widget. It is not possible to remove a widget from an existing group. KILL_NOTIFY Set this keyword to a string that contains the name of a procedure to be called automatically when the specified widget dies. Each widget is allowed a single such "callback" procedure. It can be removed by setting the routine to the null string (''). Note that the procedure specified is used only if you are not using the XMANAGER procedure to manage your widgets. The callback routine is called with the widget identifier as its only argument. At that point, the widget identifier can only be used with the WIDGET_CONTROL procedure to get or set the user value. All other requests that require a widget ID are disallowed for the target widget. The callback is not issued until the WIDGET_EVENT function is called. If you use the XMANAGER procedure to manage your widgets, the value of this keyword is overwritten. Use the CLEANUP keyword to XMANAGER to specify a procedure to be called when a managed widget dies. MULTIPLE Set this keyword to allow the user to select more than one item from the list in a single operation. Multiple selections are handled using the platform's native mechanism: Motif Holding down the Shift key and clicking an item selects the range from the previously selected item to the new item. Holding down the mouse button when selecting items also selects a range. Holding down the Control key and clicking an item toggles that item between the selected and unselected state. Windows Holding down the Shift key and clicking an item selects the range from the previously selected item to the new item. Holding down the Control key and clicking an item toggles that item between the selected and unselected state. Macintosh Holding down the Shift key and clicking an item selects the range from the previously selected item to the new item. Holding down the Command key and clicking an item toggles that item between the selected and unselected state. NO_COPY Usually, when setting or getting widget user values, either at widget creation or using the SET_UVALUE and GET_UVALUE keywords to WIDGET_CONTROL, IDL makes a second copy of the data being transferred. Although this technique is fine for small data, it can have a significant memory cost when the data being copied is large. If the NO_COPY keyword is set, IDL handles these operations differently. Rather than copy the source data, it takes the data away from the source and attaches it directly to the destination. This feature can be used by compound widgets to obtain state information from a UVALUE without all the memory copying that would otherwise occur. However, it has the side effect of causing the source variable to become undefined. On a "set" operation (using the UVALUE keyword to WIDGET_LIST or the SET_UVALUE keyword to WIDGET_CONTROL), the variable passed as value becomes undefined. On a "get" operation (GET_UVALUE keyword to WIDGET_CONTROL), the user value of the widget in question becomes undefined. NOTIFY_REALIZE Set this keyword to a string that contains the name of a procedure to be called automatically when the specified widget is realized. This callback occurs just once (because widgets are realized only once). Each widget is allowed a single such "callback" procedure. It can be removed by setting the routine to the null string (''). The callback routine is called with the widget ID as its only argument. PRO_SET_VALUE A string containing the name of a procedure to be called when the SET_VALUE keyword to the WIDGET_CONTROL procedure is called for this widget. Using this technique allows you to designate a routine that sets the value for a widget. Compound widgets use this ability to define their values transparently to the user. RESOURCE_NAME A string containing an X Window System resource name to be applied to the widget. See "RESOURCE_NAME" on page 1527 for a complete discussion of this keyword. SCR_XSIZE Set this keyword to the desired "screen" width of the widget, in units specified by the UNITS keyword (pixels are the default). In many cases, setting this keyword is the same as setting the XSIZE keyword. SCR_YSIZE Set this keyword to the desired "screen" height of the widget, in units specified by the UNITS keyword (pixels are the default). In many cases, setting this keyword is the same as setting the YSIZE keyword. SENSITIVE Set this keyword to control the initial sensitivity state of the widget. If SENSITIVE is zero, the widget becomes insensitive. If nonzero, it becomes sensitive. When a widget is sensitive, it has normal appearance and can receive user input. For example, a sensitive button widget can be activated by moving the mouse cursor over it and pressing a mouse button. When a widget is insensitive, it indicates the fact by changing its appearance, looking disabled, and it ignores any input. Sensitivity can be used to control when a user is allowed to manipulate the widget. Note that some widgets do not change their appearance when they are made insensitive, but they cease generating events. After creating the widget hierarchy, you can change the sensitivity state using the SENSITIVE keyword with the WIDGET_CONTROL procedure. TRACKING_EVENTS Set this keyword to cause widget tracking events to be issued for the widget whenever the mouse pointer enters or leaves the region covered by that widget. For the structure of tracking events, see "TRACKING_EVENTS" on page 1533 in the documentation for WIDGET_BASE. UNAME Set this keyword to a string that can be used to identify the widget in your code. You can associate a name with each widget in a specific hierarchy, and then use that name to query the widget hierarchy and get the correct widget ID. To query the widget hierarchy, use the WIDGET_INFO function with the FIND_BY_UNAME keyword. The UNAME should be unique to the widget hierarchy because the FIND_BY_UNAME keyword returns the ID of the first widget with the specified name. UNITS Set UNITS equal to 0 (zero) to specify that all measurements are in pixels (this is the default), to 1 (one) to specify that all measurements are in inches, or to 2 (two) to specify that all measurements are in centimeters. Note This keyword does not affect all sizing operations. Specifically, the value of UNITS is ignored when setting the XSIZE or YSIZE keywords to WIDGET_LIST. UVALUE The "user value" to be assigned to the widget. Each widget can contain a user-specified value of any data type and organization. This value is not used by the widget in any way, but exists entirely for the convenience of the IDL programmer. This keyword allows you to set this value when the widget is first created. If UVALUE is not present, the widget's initial user value is undefined. VALUE The initial value setting of the widget. The value of a list widget is a scalar string or array of strings that contains the text of the list items-one list item per array element. List widgets are sized based on the length (in characters) of the longest item specified in the array of values for the VALUE keyword. Note that the value of a list widget can only be set. It cannot be retrieved using WIDGET_CONTROL. XOFFSET The horizontal offset of the widget in units specified by the UNITS keyword (pixels are the default) relative to its parent. Specifying an offset relative to a row or column major base widget does not work because those widgets enforce their own layout policies. This keyword is primarily of use relative to a plain base widget. Note that it is best to avoid using this style of widget programming. XSIZE The desired width of the widget, in characters. Most widgets attempt to size themselves to fit the situation. However, if the desired effect is not produced, use this keyword to override it. Note that the final size of the widget may be adjusted to include space for scrollbars (which are not always visible), so your widget may be slightly larger than specified. YOFFSET The vertical offset of the widget in units specified by the UNITS keyword (pixels are the default) relative to its parent. This offset is specified relative to the upper left corner of the parent widget. Specifying an offset relative to a row or column major base widget does not work because those widgets enforce their own layout policies. This keyword is primarily of use relative to a plain base widget. Note that it is best to avoid using this style of widget programming. YSIZE The desired height of the widget, in number of list items visible. Most widgets attempt to size themselves to fit the situation. However, if the desired effect is not produced, use this keyword to override it. Note that the final size of the widget may be adjusted to include space for scrollbars (which are not always visible), so your widget may be slightly larger than specified. Keywords to WIDGET_CONTROL A number of keywords to the WIDGET_CONTROL procedure affect the behavior of list widgets. In addition to those keywords that affect all widgets, the following are particularly useful: SET_LIST_SELECT, SET_LIST_TOP, SET_VALUE. Keywords to WIDGET_INFO A number of keywords to the WIDGET_INFO function return information that applies specifically to list widgets. In addition to those keywords that apply to all widgets, the following are particularly useful: LIST_MULTIPLE, LIST_NUMBER, LIST_NUM_VISIBLE, LIST_SELECT, LIST_TOP. Widget Events Returned by List Widgets Pressing the mouse button while the mouse cursor is over an element of a list widget causes the widget to highlight the appearance of that element and to generate an event. The appearance of any previously selected element is restored to normal at the same time. The event structure returned by the WIDGET_EVENT function is defined by the following statement: {WIDGET_LIST, ID:0L, TOP:0L, HANDLER:0L, INDEX:0L, CLICKS:0L} The first three fields are the standard fields found in every widget event. INDEX returns the index of the selected item. This index can be used to subscript the array of names originally used to set the widget's value. The CLICKS field returns either 1 or 2, depending upon how the list item was selected. If the list item is double-clicked, CLICKS is set to 2. Note If you are writing a widget application that requires the user to double-click on a list widget, you will need to handle two events. The CLICKS field will return a 1 on the first click and a 2 on the second click. See Also CW_BGROUP, WIDGET_DROPLIST WIDGET_SLIDER [Previous Routine] [Next Routine] [List of Routines] NAME: WIDGET_SLIDER The WIDGET_SLIDER function is used to create slider widgets. Slider widgets are used to indicate an integer value from a range of possible values. They consist of a rectangular region which represents the possible range of values. Inside this region is a sliding pointer that displays the current value. This pointer can be manipulated by the user via the mouse, or from within IDL via the WIDGET_CONTROL procedure. To indicated floating-point values, see CW_FSLIDER. The returned value of this function is the widget ID of the newly-created slider widget. Syntax Result = WIDGET_SLIDER( Parent [, SCROLL] [, /DRAG] [, EVENT_FUNC=string] [, EVENT_PRO=string] [, FONT=string] [, FRAME=width] [, FUNC_GET_VALUE=string] [, GROUP_LEADER=widget_id] [, KILL_NOTIFY=string] [, MAXIMUM=value] [, MINIMUM=value] [, /NO_COPY] [, NOTIFY_REALIZE=string] [, PRO_SET_VALUE=string] [, RESOURCE_NAME=string] [, SCR_XSIZE=width] [, SCR_YSIZE=height] [, SCROLL=units] [, /SENSITIVE] [, /SUPPRESS_VALUE] [, /TRACKING_EVENTS] [, TITLE=string] [, UNAME=string] [, UNITS={0 | 1 | 2}] [, UVALUE=value] [, VALUE=value] [, /VERTICAL] [, XOFFSET=value] [, XSIZE=value] [, YOFFSET=value] [, YSIZE=value] ) Arguments Parent The widget ID of the parent for the new slider widget. Keywords DRAG Set this keyword to cause events to be generated continuously while the slider is being dragged by the user. Normally, slider widgets generate position events only when the slider comes to rest at its final position and the mouse button is released. When a slider widget is set to return drag events, a large number of events can be generated. On slower machines, poor performance can result. Therefore, this option should only be used when detailed or truly interactive control is required. Warning Under Microsoft Windows and Macintosh, sliders do not generate DRAG events. Sliders created with the DRAG keyword behave just like regular sliders. EVENT_FUNC A string containing the name of a function to be called by the WIDGET_EVENT function when an event arrives from a widget in the widget hierarchy rooted at the newly-created widget. EVENT_PRO A string containing the name of a procedure to be called by the WIDGET_EVENT function when an event arrives from a widget in the widget hierarchy rooted at the newly-created widget. FONT The name of the font to be used by the widget. The font specified is a "device font" (an X Windows font on Motif systems; a TrueType or PostScript font on Windows or Macintosh systems). See "About Device Fonts" on page 2482 for details on specifying names for device fonts. If this keyword is omitted, the default font is used. Note On Microsoft Windows platforms, if FONT is not specified, IDL uses the system default font. Different versions of Windows use different system default fonts. FRAME The value of this keyword specifies the width of a frame in units specified by the UNITS keyword (pixels are the default) to be drawn around the borders of the widget. Note that this keyword is only a "hint" to the toolkit, and may be ignored in some instances. FUNC_GET_VALUE A string containing the name of a function to be called when the GET_VALUE keyword to the WIDGET_CONTROL procedure is called for this widget. Using this technique allows you to change the value that should be returned for a widget. Compound widgets use this ability to define their values transparently to the user. GROUP_LEADER The widget ID of an existing widget that serves as "group leader" for the newly- created widget. When a group leader is killed, for any reason, all widgets in the group are also destroyed. A given widget can be in more than one group. The WIDGET_CONTROL procedure can be used to add additional group associations to a widget. It is not possible to remove a widget from an existing group. KILL_NOTIFY Set this keyword to a string that contains the name of a procedure to be called automatically when the specified widget dies. Each widget is allowed a single such "callback" procedure. It can be removed by setting the routine to the null string (''). Note that the procedure specified is used only if you are not using the XMANAGER procedure to manage your widgets. The callback routine is called with the widget identifier as its only argument. At that point, the widget identifier can only be used with the WIDGET_CONTROL procedure to get or set the user value. All other requests that require a widget ID are disallowed for the target widget. The callback is not issued until the WIDGET_EVENT function is called. If you use the XMANAGER procedure to manage your widgets, the value of this keyword is overwritten. Use the CLEANUP keyword to XMANAGER to specify a procedure to be called when a managed widget dies. MAXIMUM The maximum value of the range encompassed by the slider. If this keyword is not supplied, a default of 100 is used. MINIMUM The minimum value of the range encompassed by the slider. If this keyword is not supplied, a default of 0 is used. NO_COPY Usually, when setting or getting widget user values, either at widget creation or using the SET_UVALUE and GET_UVALUE keywords to WIDGET_CONTROL, IDL makes a second copy of the data being transferred. Although this technique is fine for small data, it can have a significant memory cost when the data being copied is large. If the NO_COPY keyword is set, IDL handles these operations differently. Rather than copy the source data, it takes the data away from the source and attaches it directly to the destination. This feature can be used by compound widgets to obtain state information from a UVALUE without all the memory copying that would otherwise occur. However, it has the side effect of causing the source variable to become undefined. On a "set" operation (using the UVALUE keyword to WIDGET_SLIDER or the SET_UVALUE keyword to WIDGET_CONTROL), the variable passed as value becomes undefined. On a "get" operation (GET_UVALUE keyword to WIDGET_CONTROL), the user value of the widget in question becomes undefined. NOTIFY_REALIZE Set this keyword to a string that contains the name of a procedure to be called automatically when the specified widget is realized. This callback occurs just once (because widgets are realized only once). Each widget is allowed a single such "callback" procedure. It can be removed by setting the routine to the null string (''). The callback routine is called with the widget ID as its only argument. PRO_SET_VALUE A string containing the name of a procedure to be called when the SET_VALUE keyword to the WIDGET_CONTROL procedure is called for this widget. Using this technique allows you to designate a routine that sets the value for a widget. Compound widgets use this ability to define their values transparently to the user. RESOURCE_NAME A string containing an X Window System resource name to be applied to the widget. See "RESOURCE_NAME" on page 1527 for a complete discussion of this keyword. SCR_XSIZE Set this keyword to the desired "screen" width of the widget, in units specified by the UNITS keyword (pixels are the default). In many cases, setting this keyword is the same as setting the XSIZE keyword. SCR_YSIZE Set this keyword to the desired "screen" height of the widget, in units specified by the UNITS keyword (pixels are the default). In many cases, setting this keyword is the same as setting the YSIZE keyword. SCROLL Under the Motif window manager, the SCROLL value specifies how many units the scroll bar should move when the user clicks the left mouse button inside the slider area, but not on the slider itself. The default on Motif is 10% of the slider width. On Macintosh and Microsoft Windows, the SCROLL value specifies how many units the scroll bar should move when the user clicks the left mouse button on the slider arrows, but not within the slider area or on the slider itself. The default on Macintosh and Microsoft Windows is 1 unit. Under the Motif window manager, the value provided for SCROLL specifies how many units the scroll bar should move when the user clicks the left mouse button inside the slider area, but not on the slider itself. This keyword has no effect under other window systems. SENSITIVE Set this keyword to control the initial sensitivity state of the widget. If SENSITIVE is zero, the widget becomes insensitive. If nonzero, it becomes sensitive. When a widget is sensitive, it has normal appearance and can receive user input. For example, a sensitive button widget can be activated by moving the mouse cursor over it and pressing a mouse button. When a widget is insensitive, it indicates the fact by changing its appearance, looking disabled, and it ignores any input. Sensitivity can be used to control when a user is allowed to manipulate the widget. Note that some widgets do not change their appearance when they are made insensitive, but they cease generating events. After creating the widget hierarchy, you can change the sensitivity state using the SENSITIVE keyword with the WIDGET_CONTROL procedure. SUPPRESS_VALUE Set this keyword to inhibit the display of the current slider value. Sliders work only with integer units. This keyword can be used to suppress the actual value of a slider so that a program can present the user with a slider that seems to work in other units (such as floating-point) or with a non-linear scale. TRACKING_EVENTS Set this keyword to cause widget tracking events to be issued for the widget whenever the mouse pointer enters or leaves the region covered by that widget. For the structure of tracking events, see "TRACKING_EVENTS" on page 1533 in the documentation for WIDGET_BASE. TITLE A string containing the title to be used for the slider widget. UNAME Set this keyword to a string that can be used to identify the widget in your code. You can associate a name with each widget in a specific hierarchy, and then use that name to query the widget hierarchy and get the correct widget ID. To query the widget hierarchy, use the WIDGET_INFO function with the FIND_BY_UNAME keyword. The UNAME should be unique to the widget hierarchy because the FIND_BY_UNAME keyword returns the ID of the first widget with the specified name. UNITS Set UNITS equal to 0 (zero) to specify that all measurements are in pixels (this is the default), to 1 (one) to specify that all measurements are in inches, or to 2 (two) to specify that all measurements are in centimeters. UVALUE The "user value" to be assigned to the widget. Each widget can contain a user-specified value of any data type and organization. This value is not used by the widget in any way, but exists entirely for the convenience of the IDL programmer. This keyword allows you to set this value when the widget is first created. If UVALUE is not present, the widget's initial user value is undefined. VALUE The initial value setting of the widget. The value of a widget slider is the current position of the slider. VERTICAL Set this keyword to create a vertical slider. If this keyword is omitted, the slider is horizontal. XOFFSET The horizontal offset of the widget in units specified by the UNITS keyword (pixels are the default) relative to its parent. This offset is specified relative to the upper left corner of the parent widget. Specifying an offset relative to a row or column major base widget does not work because those widgets enforce their own layout policies. This keyword is primarily of use relative to a plain base widget. Note that it is best to avoid using this style of widget programming. XSIZE The width of the widget in units specified by the UNITS keyword (pixels are the default). Most widgets attempt to size themselves to fit the situation. However, if the desired effect is not produced, use this keyword to override it. This keyword is only a "hint" to the toolkit and may be ignored in some situations. YOFFSET The vertical offset of the widget in units specified by the UNITS keyword (pixels are the default) relative to its parent. This offset is specified relative to the upper left corner of the parent widget. Specifying an offset relative to a row or column major base widget does not work because those widgets enforce their own layout policies. This keyword is primarily of use relative to a plain base widget. Note that it is best to avoid using this style of widget programming. YSIZE The height of the widget in units specified by the UNITS keyword (pixels are the default). Most widgets attempt to size themselves to fit the situation. However, if the desired effect is not produced, use this keyword to override it. This keyword is only a "hint" to the toolkit and may be ignored in some situations. Keywords to WIDGET_CONTROL A number of keywords to the WIDGET_CONTROL procedure affect the behavior of slider widgets. In addition to those keywords that affect all widgets, the following are particularly useful: GET_VALUE, SET_SLIDER_MAX, SET_SLIDER_MIN, SET_VALUE. Keywords to WIDGET_INFO Some keywords to the WIDGET_INFO function return information that applies specifically to slider widgets. In addition to those keywords that apply to all widgets, the following are particularly useful: SLIDER_MIN_MAX. Slider Widget Events Slider widgets generate events when the mouse is used to change their value. The event structure returned by the WIDGET_EVENT function is defined by the following statement: {WIDGET_SLIDER, ID:0L, TOP:0L, HANDLER:0L, VALUE:0L, DRAG:0} ID is the widget ID of the button generating the event. TOP is the widget ID of the top level widget containing ID. HANDLER contains the widget ID of the widget associated with the handler routine. VALUE returns the new value of the slider. DRAG returns integer 1 if the slider event was generated as part of a drag operation, or zero if the event was generated when the user had finished positioning the slider. Note that the slider widget only generates events during the drag operation if the DRAG keyword is set, and if the application is running under Motif. When the DRAG keyword is set, the DRAG field can be used to avoid computationally expensive operations until the user releases the slider. Known Implementation Problems Under Motif 1.0, vertical sliders with a title organized in row bases get horizontally truncated and the slider doesn't show (the title does). Use the XSIZE keyword to work around this. See Also CW_FSLIDER WIDGET_TABLE [Previous Routine] [Next Routine] [List of Routines] NAME: WIDGET_TABLE The WIDGET_TABLE function creates table widgets. Table widgets display two- dimensional data and allow in-place data editing. They can have one or more rows and columns, and automatically create scroll bars when viewing more data than can otherwise be displayed on the screen. Note on Table Sizing Table widgets are sized according to the value of the following pairs of keywords to WIDGET_TABLE, in order of precedence: SCR_XSIZE/SCR_YSIZE, XSIZE/YSIZE, X_SCROLL_SIZE/Y_SCROLL_SIZE, VALUE. If either dimension remains unspecified by one of the above keywords, the default value of six (columns or rows) is used when the table is created. If the width or height specified is less than the size of the table, scroll bars are added automatically. The returned value of this function is the widget ID of the newly-created table widget. Syntax Result = WIDGET_TABLE( Parent [, ALIGNMENT={0 | 1 | 2}] [, /ALL_EVENTS] [, AM_PM=[string, string]] [, COLUMN_LABELS=string_array] [, /COLUMN_MAJOR | , /ROW_MAJOR] [, COLUMN_WIDTHS=array] [, DAYS_OF_WEEK=string_array{7 names}] [, /EDITABLE] [, EVENT_FUNC=string] [, EVENT_PRO=string] [, FONT=string] [, FORMAT=value] [, FRAME=width] [, FUNC_GET_VALUE=string] [, GROUP_LEADER=widget_id] [, /KBRD_FOCUS_EVENTS] [, KILL_NOTIFY=string] [, MONTHS=string_array{12 names}] [, /NO_COPY] [, /NO_HEADERS] [, NOTIFY_REALIZE=string] [, PRO_SET_VALUE=string] [, /RESIZEABLE_COLUMNS] [, /RESIZEABLE_ROWS{not supported in Windows}] [, RESOURCE_NAME=string] [, ROW_HEIGHTS=array{not supported in Windows}] [, ROW_LABELS=string_array] [, SCR_XSIZE=width] [, SCR_YSIZE=height] [, /SCROLL] [, /SENSITIVE] [, /TRACKING_EVENTS] [, UNAME=string] [, UNITS={0 | 1 | 2}] [, UVALUE=value] [, VALUE=value] [, XOFFSET=value] [, XSIZE=value] [, X_SCROLL_SIZE=width] [, YOFFSET=value] [, YSIZE=value] [, Y_SCROLL_SIZE=height] ) Arguments Parent The widget ID of the parent widget for the new table widget. Keywords ALIGNMENT Set this keyword equal to a scalar or 2-D array specifying the alignment of the text within each cell. An alignment of 0 (the default) aligns the left edge of the text with the left edge of the cell. An alignment of 2 right-justifies the text, while 1 results in text centered within the cell. If ALIGNMENT is set equal to a scalar, all table cells are aligned as specified. If ALIGNMENT is set equal to a 2-D array, the alignment of each table cell is governed by the corresponding element of the array. ALL_EVENTS Along with the EDITABLE keyword, ALL_EVENTS controls the type of events generated by the table widget. Set the ALL_EVENTS keyword to cause the full set of events to be generated. If ALL_EVENTS is not set, setting EDITABLE causes only end-of-line events to be generated. If EDITABLE is not set, all events are suppressed. See the table below for additional details. Keywords Effects ALL_EVENTS EDITABLE Input changes Type of events widget contents? generated. Not set Not set No None Not set Set Yes End-of-line insertion Set Not set No All events Set Set Yes All events Table 96: Effects of using the ALL_EVENTS and EDITABLE keywords AM_PM Supplies a string array of 2 names to be used for the names of the AM and PM string when processing explicitly formatted dates (CAPA, CApA, and CapA format codes) with the FORMAT keyword. COLUMN_LABELS Set this keyword equal to an array of strings used as labels for the columns of the table widget. The default labels are of the form "Column n", where n is the column number. If this keyword is set to the empty string (''), all column labels are set to be empty. COLUMN_MAJOR This keyword is only valid if the table data is organized as a vector of structures rather than a two-dimensional array. See the VALUE keyword for details. Set this keyword to specify that the data should be read into the table as if each element of the vector is a structure containing one column's data. Note that the structures must all be of the same type, and must have one field for each row in the table. If this keyword is not set, the table widget behaves as if the ROW_MAJOR keyword were set. COLUMN_WIDTHS Set this keyword equal to an array of widths for the columns of the table widget. The widths are given in any of the units as specified with the UNITS keyword. If no width is specified for a column, that column is set to the default size, which varies by platform. If COLUMN_WIDTHS is set to a scalar value, all columns are set to that width. DAYS_OF_WEEK Supplies a string array of 7 names to be used for the names of the days of the week when processing explicitly formatted dates (CDWA, CDwA, and CdwA format codes) with the FORMAT keyword. EDITABLE Set this keyword to allow direct user editing of the text widget contents. Normally, the text in text widgets is read-only. See "ALL_EVENTS" on page 1637 for a description of how EDITABLE interacts with the ALL_EVENTS keyword. Note The method by which text widgets are placed into edit mode is dependent upon the windowing system. On Microsoft Windows, for instance, a cell must be double- clicked to be placed into edit mode. EVENT_FUNC A string containing the name of a function to be called by the WIDGET_EVENT function when an event arrives from a widget in the widget hierarchy rooted at the newly-created widget. EVENT_PRO A string containing the name of a procedure to be called by the WIDGET_EVENT function when an event arrives from a widget in the widget hierarchy rooted at the newly-created widget. FONT The name of the font to be used by the widget. The font specified is a "device font" (an X Windows font on Motif systems; a TrueType or PostScript font on Windows or Macintosh systems). See "About Device Fonts" on page 2482 for details on specifying names for device fonts. If this keyword is omitted, the default font is used. A single font is shared by the row and column labels and by all of the cells in the widget. Note On Microsoft Windows platforms, if FONT is not specified, IDL uses the system default font. Different versions of Windows use different system default fonts; in general, the system default font is the font appropriate for the version of Windows in question. FORMAT Set this keyword equal to a single string or array of strings that specify the format of data displayed within table cells. The string(s) are of the same form as used by the FORMAT keyword to the PRINT procedure, and the default format is the same as that used by the PRINT procedure. Warning If the format specified is incompatible with the data displayed in a table cell, an error message is generated. Since the error is generated for each cell displayed, the number of messages printed is potentially large, and can slow execution significantly. Note also that each time a new cell is displayed (when scroll bars are repositioned, for example), a new error is generated for each cell displayed. FRAME The value of this keyword specifies the width of a frame in units specified by the UNITS keyword (pixels are the default) to be drawn around the borders of the widget. Note that this keyword is only a "hint" to the toolkit, and may be ignored in some instances. FUNC_GET_VALUE A string containing the name of a function to be called when the GET_VALUE keyword to the WIDGET_CONTROL procedure is called for this widget. Using this technique allows you to change the value that should be returned for a widget. Compound widgets use this ability to define their values transparently to the user. GROUP_LEADER The widget ID of an existing widget that serves as "group leader" for the newly- created widget. When a group leader is killed, for any reason, all widgets in the group are also destroyed. A given widget can be in more than one group. The WIDGET_CONTROL procedure can be used to add additional group associations to a widget. It is not possible to remove a widget from an existing group. KBRD_FOCUS_EVENTS Set this keyword to make the base return keyboard focus events whenever the keyboard focus of the base changes. See "Widget Events Returned by Table Widgets" on page 1647 for more information. KILL_NOTIFY Set this keyword to a string that contains the name of a procedure to be called automatically when the specified widget dies. Each widget is allowed a single such "callback" procedure. It can be removed by setting the routine to the null string (''). Note that the procedure specified is used only if you are not using the XMANAGER procedure to manage your widgets. The callback routine is called with the widget identifier as its only argument. At that point, the widget identifier can only be used with the WIDGET_CONTROL procedure to get or set the user value. All other requests that require a widget ID are disallowed for the target widget. The callback is not issued until the WIDGET_EVENT function is called. If you use the XMANAGER procedure to manage your widgets, the value of this keyword is overwritten. Use the CLEANUP keyword to XMANAGER to specify a procedure to be called when a managed widget dies. MONTHS Supplies a string array of 12 names to be used for the names of the months when processing explicitly formatted dates (CMOA, CMoA, and CmoA format codes) with the FORMAT keyword. NO_COPY Usually, when setting or getting widget user values, either at widget creation or using the SET_UVALUE and GET_UVALUE keywords to WIDGET_CONTROL, IDL makes a second copy of the data being transferred. Although this technique is fine for small data, it can have a significant memory cost when the data being copied is large. If the NO_COPY keyword is set, IDL handles these operations differently. Rather than copy the source data, it takes the data away from the source and attaches it directly to the destination. This feature can be used by compound widgets to obtain state information from a UVALUE without all the memory copying that would otherwise occur. However, it has the side effect of causing the source variable to become undefined. On a "set" operation (using the UVALUE keyword to WIDGET_TABLE or the SET_UVALUE keyword to WIDGET_CONTROL), the variable passed as value becomes undefined. On a "get" operation (GET_UVALUE keyword to WIDGET_CONTROL), the user value of the widget in question becomes undefined. NO_HEADERS Set this keyword to disable the display of the table widget's header area (where row and column labels are normally displayed). NOTIFY_REALIZE Set this keyword to a string that contains the name of a procedure to be called automatically when the specified widget is realized. This callback occurs just once (because widgets are realized only once). Each widget is allowed a single such "callback" procedure. It can be removed by setting the routine to the null string (''). The callback routine is called with the widget ID as its only argument. PRO_SET_VALUE A string containing the name of a procedure to be called when the SET_VALUE keyword to the WIDGET_CONTROL procedure is called for this widget. Using this technique allows you to designate a routine that sets the value for a widget. Compound widgets use this ability to define their values transparently to the user. RESIZEABLE_COLUMNS Set this keyword to allow the user to change the size of columns using the mouse. Note that if the NO_HEADERS keyword was set, the columns cannot be resized interactively. RESIZEABLE_ROWS Set this keyword to allow the user to change the size of rows using the mouse. Note that if the NO_HEADERS keyword was set, the rows cannot be resized interactively. Under Microsoft Windows, the row size cannot be changed. RESOURCE_NAME A string containing an X Window System resource name to be applied to the widget. See "RESOURCE_NAME" on page 1527 for a complete discussion of this keyword. ROW_HEIGHTS Set this keyword equal to an array of heights for the rows of the table widget. The heights are given in any of the units as specified with the UNITS keyword. If no height is specified for a row, that row is set to the default size, which varies by platform. If ROW_HEIGHTS is set to a scalar value, all of the row heights are set to that value. Note This keyword is not supported under Microsoft Windows. ROW_LABELS Set this keyword equal to an array of strings to be used as labels for the rows of the table. If no label is specified for a row, it receives the default label "Row n", where n is the row number. If this keyword is set to the empty string (''), all row labels are set to be empty. ROW_MAJOR This keyword is only valid if the table data is organized as a vector of structures rather than a two-dimensional array. See the VALUE keyword for details. Set this keyword to specify that the data should be read into the table as if each element of the vector is a structure containing one row's data. Note that the structures must all be of the same type, and must have one field for each column in the table. This is the default behavior if neither the COLUMN_MAJOR or ROW_MAJOR keyword is set. SCR_XSIZE Set this keyword to the desired "screen" width of the widget, in units specified by the UNITS keyword (pixels are the default). Note that the screen width of the widget includes the width of scroll bars, if any are present. Setting SCR_XSIZE overrides values set for the XSIZE or X_SCROLL_SIZE keywords. See "Note on Table Sizing" on page 1636. SCR_YSIZE Set this keyword to the desired "screen" height of the widget, in units specified by the UNITS keyword (pixels are the default). Note that the screen height of the widget includes the height of scroll bars, if any are present. Setting SCR_YSIZE overrides values set for the YSIZE or Y_SCROLL_SIZE keywords. See "Note on Table Sizing" on page 1636. SCROLL Set this keyword to give the widget scroll bars that allow viewing portions of the widget contents that are not currently on the screen. See "Note on Table Sizing" on page 1636 SENSITIVE Set this keyword to control the initial sensitivity state of the widget. If SENSITIVE is zero, the widget becomes insensitive. If nonzero, it becomes sensitive. When a widget is sensitive, it has normal appearance and can receive user input. For example, a sensitive button widget can be activated by moving the mouse cursor over it and pressing a mouse button. When a widget is insensitive, it indicates the fact by changing its appearance, looking disabled, and it ignores any input. Sensitivity can be used to control when a user is allowed to manipulate the widget. Note that some widgets do not change their appearance when they are made insensitive, but they cease generating events. After creating the widget hierarchy, you can change the sensitivity state using the SENSITIVE keyword with the WIDGET_CONTROL procedure. TRACKING_EVENTS Set this keyword to cause widget tracking events to be issued for the widget whenever the mouse pointer enters or leaves the region covered by that widget. For the structure of tracking events, see "TRACKING_EVENTS" on page 1533 in the documentation for WIDGET_BASE. UNAME Set this keyword to a string that can be used to identify the widget in your code. You can associate a name with each widget in a specific hierarchy, and then use that name to query the widget hierarchy and get the correct widget ID. To query the widget hierarchy, use the WIDGET_INFO function with the FIND_BY_UNAME keyword. The UNAME should be unique to the widget hierarchy because the FIND_BY_UNAME keyword returns the ID of the first widget with the specified name. UNITS Set UNITS equal to 0 (zero) to specify that all measurements are in pixels (this is the default), to 1 (one) to specify that all measurements are in inches, or to 2 (two) to specify that all measurements are in centimeters. Note This keyword does not affect all sizing operations. Specifically, the value of UNITS is ignored when setting the XSIZE or YSIZE keywords. UVALUE The "user value" to be assigned to the widget. Each widget can contain a user-specified value of any data type and organization. This value is not used by the widget in any way, but exists entirely for the convenience of the IDL programmer. This keyword allows you to set this value when the widget is first created. If UVALUE is not present, the widget's initial user value is undefined. VALUE The initial value setting of the widget. The value of a table widget is either a two- dimensional array or a vector of structures. If the value is specified as a two-dimensional array, all data must be of the same data type. If the value is specified as a vector of structures, it can be displayed either in column- major or row-major format by setting either the COLUMN_MAJOR keyword or the ROW_MAJOR keyword. All of the structures must be of the same type, and must contain one field for each column (if COLUMN_MAJOR is set) or row (if ROW_MAJOR is set) in the table. If neither keyword is set, the data is displayed in row major format. If none of [XY]SIZE, SCR_[XY]SIZE, or [XY]_SCROLL_SIZE is present, the size of the table is determined by the size of the array or vector of structures specified by VALUE. See "Note on Table Sizing" on page 1636. XOFFSET The horizontal offset of the widget in units specified by the UNITS keyword (pixels are the default) relative to its parent. This offset is specified relative to the upper left corner of the parent widget. Specifying an offset relative to a row or column major base widget does not work because those widgets enforce their own layout policies. This keyword is primarily of use relative to a plain base widget. Note that it is best to avoid using this style of widget programming. XSIZE The width of the widget in columns. If row labels are present, one column is automatically added to this value. See "Note on Table Sizing" on page 1636. X_SCROLL_SIZE The XSIZE keyword always specifies the width of a widget, in columns. When the SCROLL keyword is specified, this size is not necessarily the same as the width of the visible area. The X_SCROLL_SIZE keyword allows you to set the width of the scrolling viewport independently of the actual width of the widget. See "Note on Table Sizing" on page 1636. Use of the X_SCROLL_SIZE keyword implies SCROLL. This means that scroll bars will be added in both the horizontal and vertical directions when X_SCROLL_SIZE is specified. Because the default size of the scrolling viewport may differ between platforms, it is best to specify Y_SCROLL_SIZE when specifying X_SCROLL_SIZE. YOFFSET The vertical offset of the widget in units specified by the UNITS keyword (pixels are the default) relative to its parent. This offset is specified relative to the upper left corner of the parent widget. Specifying an offset relative to a row or column major base widget does not work because those widgets enforce their own layout policies. This keyword is primarily of use relative to a plain base widget. Note that it is best to avoid using this style of widget programming. YSIZE The height of the widget in rows. If column labels are present, one row is automatically added to this value. See "Note on Table Sizing" on page 1636. Y_SCROLL_SIZE The YSIZE keyword always specifies the height of a widget. in rows. When the SCROLL keyword is specified, this size is not necessarily the same as the height of the visible area. The Y_SCROLL_SIZE keyword allows you to set the height of the scrolling viewport independently of the actual width of the widget. See "Note on Table Sizing" on page 1636. Use of the Y_SCROLL_SIZE keyword implies SCROLL. This means that scroll bars will be added in both the horizontal and vertical directions when Y_SCROLL_SIZE is specified. Because the default size of the scrolling viewport may differ between platforms, it is best to specify X_SCROLL_SIZE when specifying Y_SCROLL_SIZE. Keywords to WIDGET_CONTROL A number of keywords to the WIDGET_CONTROL procedure affect the behavior of table widgets. In addition to those keywords that affect all widgets, the following are particularly useful: ALIGNMENT, ALL_TABLE_EVENTS, COLUMN_LABELS, COLUMN_WIDTHS, DELETE_COLUMNS, DELETE_ROWS, EDITABLE, EDIT_CELL, FORMAT, GET_VALUE, INSERT_COLUMNS, INSERT_ROWS, KBRD_FOCUS_EVENTS, ROW_LABELS, ROW_HEIGHTS, SET_TABLE_SELECT, SET_TABLE_VIEW, SET_TEXT_SELECT, SET_VALUE, TABLE_XSIZE, TABLE_YSIZE, USE_TABLE_SELECT, USE_TEXT_SELECT. Keywords to WIDGET_INFO A number of keywords to the WIDGET_INFO function return information that applies specifically to table widgets. In addition to those keywords that apply to all widgets, the following are particularly useful: COLUMN_WIDTHS, KBRD_FOCUS_EVENTS, ROW_HEIGHTS, TABLE_ALL_EVENTS, TABLE_EDITABLE, TABLE_EDIT_CELL, TABLE_SELECT, TABLE_VIEW, USE_TABLE_SELECT. Widget Events Returned by Table Widgets There are several variations of the table widget event structure depending on the specific event being reported. All of these structures contain the standard three fields (ID, TOP, and HANDLER) as well as an integer TYPE field that indicates which type of structure has been returned. Programs should always check the field type before referencing fields that are not present in all table event structures. The different table widget event structures are described below. Insert Single Character (TYPE = 0) This is the type of structure returned when a single character is typed into a cell of a table widget by a user. {WIDGET_TABLE_CH, ID:0L, TOP:0L, HANDLER:0L, TYPE:0, OFFSET:0L, CH:0B, X:0L, Y:0L } OFFSET is the (zero-based) insertion position that will result after the character is inserted. CH is the ASCII value of the character. X and Y give the zero-based address of the cell within the table. Insert Multiple Characters (TYPE = 1) This is the type of structure returned when multiple characters are pasted into a cell by the window system. {WIDGET_TABLE_STR, ID:0L, TOP:0L, HANDLER:0L, TYPE:1, OFFSET:0L, STR:'', X:0L, Y:0L} OFFSET is the (zero-based) insertion position that will result after the text is inserted. STR is the string to be inserted. X and Y give the zero-based address of the cell within the table. Delete Text (TYPE = 2) This is the type of structure returned when any amount of text is deleted from a cell of a table widget. {WIDGET_TABLE_DEL, ID:0L, TOP:0L, HANDLER:0L, TYPE:2, OFFSET:0L, LENGTH:0L, X:0L, Y:0L} OFFSET is the (zero-based) character position of the first character deleted. It is also the insertion position that will result when the next character is inserted. LENGTH gives the number of characters involved. X and Y give the zero-based address of the cell within the table. Text Selection (TYPE = 3) This is the type of structure returned when an area of text is selected (highlighted) by the user. {WIDGET_TABLE_TEXT_SEL, ID:0L, TOP:0L, HANDLER:0L, TYPE:3, OFFSET:0L, LENGTH:0L, X:0L, Y:0L} The event announces a change in the insertion point. OFFSET is the (zero-based) character position of the first character to be selected. LENGTH gives the number of characters involved. A LENGTH of zero indicates that the widget has no selection, and that the insertion position is given by OFFSET. X and Y give the zero-based address of the cell within the table. Note Text insertion, text deletion, or any change in the current insertion point causes any current selection to be lost. In such cases, the loss of selection is implied by the text event reporting the insert/delete/movement and a separate zero length selection event is not sent. Cell Selection (TYPE = 4) This is the type of structure returned when range of cells is selected (highlighted) or deselected by the user. {WIDGET_TABLE_CELL_SEL, ID:0L, TOP:0L, HANDLER:0L, TYPE:4, SEL_LEFT:0L, SEL_TOP:0L, SEL_RIGHT:0L, SEL_BOTTOM:0L} The event announces a change in the currently selected cells. The range of cells selected is given by the zero-based indices into the table specified by the SEL_LEFT, SEL_TOP, SEL_RIGHT, and SEL_BOTTOM fields. When cells are deselected (either by changing the selection or by clicking in the upper left corner of the table) an event is generated in which the SEL_LEFT, SEL_TOP, SEL_RIGHT, and SEL_BOTTOM fields contain the value -1. Note This means that two WIDGET_TABLE_CELL_SEL events are generated when an existing selection is changed to a new selection. If your code pays attention to WIDGET_TABLE_CELL_SEL events, be sure to differentiate between select and deselect events. Row Height Changed (TYPE = 6) This is the type of structure returned when a row height is changed by the user. {WIDGET_TABLE_ROW_HEIGHT, ID:0L, TOP:0L, HANDLER:0L, TYPE:6, ROW:0L, HEIGHT:0L} The event announces that the height of the given row has been changed by the user. The ROW field contains the zero-based row number, and the HEIGHT field contains the new height. Column Width Changed (TYPE = 7) This is the type of structure returned when a column width is changed by the user. {WIDGET_TABLE_COLUMN_WIDTH, ID:0L, TOP:0L, HANDLER:0L, TYPE:7, COLUMN:0L, WIDTH:0L} The event announces that the width of the given column has been changed by the user. The COLUMN field contains the zero-based column number, and the WIDTH field contains the new width. Invalid Data (TYPE = 8) This is the type of structure returned when the text entered by the user does not pass validation, and the user has finished editing the field (by hitting TAB or ENTER). {WIDGET_TABLE_INVALID_ENTRY, ID:0L, TOP:0L, HANDLER:0L, TYPE:8, STR:'', X:0L, Y:0L} When this event is generated, the cell's data is left unchanged. The invalid contents entered by the user is given as a text string in the STR field. The cell location is given by the X and Y fields. Keyboard Focus Events Table widgets return the following event structure when the keyboard focus changes and the base was created with the KBRD_FOCUS_EVENTS keyword set: { WIDGET_KBRD_FOCUS, ID:0L, TOP:0L, HANDLER:0L, ENTER:0 } ID is the widget ID of the table widget generating the event. TOP is the widget ID of the top level widget containing ID. HANDLER contains the widget ID of the widget associated with the handler routine. The ENTER field returns 1 (one) if the table widget is gaining the keyboard focus, or 0 (zero) if the table widget is losing the keyboard focus. See Also WIDGET_CONTROL WIDGET_TEXT [Previous Routine] [Next Routine] [List of Routines] NAME: WIDGET_TEXT The WIDGET_TEXT function creates text widgets. Text widgets display text and optionally get textual input from the user. They can have 1 or more lines, and can optionally contain scroll bars to allow viewing more text than can otherwise be displayed on the screen. The returned value of this function is the widget ID of the newly-created text widget. Syntax Result = WIDGET_TEXT( Parent [, CONTEXT_EVENTS] [, /ALL_EVENTS] [, /EDITABLE] [, EVENT_FUNC=string] [, EVENT_PRO=string] [, FONT=string] [, FRAME=width] [, FUNC_GET_VALUE=string] [, GROUP_LEADER=widget_id] [, /KBRD_FOCUS_EVENTS] [, KILL_NOTIFY=string] [, /NO_COPY] [, /NO_NEWLINE] [, NOTIFY_REALIZE=string] [, PRO_SET_VALUE=string] [, RESOURCE_NAME=string] [, SCR_XSIZE=width] [, SCR_YSIZE=height] [, /SCROLL] [, /SENSITIVE] [, /TRACKING_EVENTS] [, UNAME=string] [, UNITS={0 | 1 | 2}] [, UVALUE=value] [, VALUE=value] [, /WRAP] [, XOFFSET=value] [, XSIZE=value] [, YOFFSET=value] [, YSIZE=value] ) Arguments Parent The widget ID of the parent widget for the new text widget. Keywords CONTEXT_EVENTS (Windows, UNIX only) Set this new keyword to generate context events when the right mouse button is pressed over the widget. To request right mouse button events in a draw widget use the BUTTON_EVENTS keyword to WIDGET_DRAW at creation or the DRAW_BUTTON_EVENTS keyword to WIDGET_CONTROL for an existing draw widget. A right button press generates a WIDGET_DRAW event with the EVENT.TYPE field equal to 0 and the EVENT.RELEASE field equal to 4. ALL_EVENTS Along with the EDITABLE keyword, ALL_EVENTS controls the type of events generated by the text widget. Set the ALL_EVENTS keyword to cause the full set of events to be generated. If ALL_EVENTS is not set, setting EDITABLE causes only end-of-line events to be generated. If EDITABLE is not set, all events are suppressed. See the following table for additional details. Keywords Effects ALL_EVENT Type of events S EDITABLE Input changes widget contents? generated. Not set Not set No None Not set Set Yes End-of-line insertion Set Not set No All events Set Set Yes All events Table 97: Effects of using the ALL_EVENTS and EDITABLE keywords EDITABLE Set this keyword to allow direct user editing of the text widget contents. Normally, the text in text widgets is read-only. See "ALL_TEXT_EVENTS" on page 1552 for a description of how EDITABLE interacts with the ALL_TEXT_EVENTS keyword. EVENT_FUNC A string containing the name of a function to be called by the WIDGET_EVENT function when an event arrives from a widget in the widget hierarchy rooted at the newly-created widget. EVENT_PRO A string containing the name of a procedure to be called by the WIDGET_EVENT function when an event arrives from a widget in the widget hierarchy rooted at the newly-created widget. FONT The name of the font to be used by the widget. The font specified is a "device font" (an X Windows font on Motif systems; a TrueType or PostScript font on Windows or Macintosh systems). See "About Device Fonts" on page 2482 for details on specifying names for device fonts. If this keyword is omitted, the default font is used. Note On Microsoft Windows platforms, if FONT is not specified, IDL uses the system default font. Different versions of Windows use different system default fonts. FRAME The value of this keyword specifies the width of a frame in units specified by the UNITS keyword (pixels are the default) to be drawn around the borders of the widget. Note This keyword is only a "hint" to the toolkit, and may be ignored in some instances. Under Microsoft Windows, text widgets always have frames. FUNC_GET_VALUE A string containing the name of a function to be called when the GET_VALUE keyword to the WIDGET_CONTROL procedure is called for this widget. Using this technique allows you to change the value that should be returned for a widget. Compound widgets use this ability to define their values transparently to the user. GROUP_LEADER The widget ID of an existing widget that serves as "group leader" for the newly- created widget. When a group leader is killed, for any reason, all widgets in the group are also destroyed. A given widget can be in more than one group. The WIDGET_CONTROL procedure can be used to add additional group associations to a widget. It is not possible to remove a widget from an existing group. KBRD_FOCUS_EVENTS Set this keyword to make the base return keyboard focus events whenever the keyboard focus of the base changes. See "Text Widget Events" on page 1658 for more information. KILL_NOTIFY Set this keyword to a string that contains the name of a procedure to be called automatically when the specified widget dies. Each widget is allowed a single such "callback" procedure. It can be removed by setting the routine to the null string (''). Note that the procedure specified is used only if you are not using the XMANAGER procedure to manage your widgets. The callback routine is called with the widget identifier as its only argument. At that point, the widget identifier can only be used with the WIDGET_CONTROL procedure to get or set the user value. All other requests that require a widget ID are disallowed for the target widget. The callback is not issued until the WIDGET_EVENT function is called. If you use the XMANAGER procedure to manage your widgets, the value of this keyword is overwritten. Use the CLEANUP keyword to XMANAGER to specify a procedure to be called when a managed widget dies. NO_COPY Usually, when setting or getting widget user values, either at widget creation or using the SET_UVALUE and GET_UVALUE keywords to WIDGET_CONTROL, IDL makes a second copy of the data being transferred. Although this technique is fine for small data, it can have a significant memory cost when the data being copied is large. If the NO_COPY keyword is set, IDL handles these operations differently. Rather than copy the source data, it takes the data away from the source and attaches it directly to the destination. This feature can be used by compound widgets to obtain state information from a UVALUE without all the memory copying that would otherwise occur. However, it has the side effect of causing the source variable to become undefined. On a "set" operation (using the UVALUE keyword to WIDGET_TEXT or the SET_UVALUE keyword to WIDGET_CONTROL), the variable passed as value becomes undefined. On a "get" operation (GET_UVALUE keyword to WIDGET_CONTROL), the user value of the widget in question becomes undefined. NO_NEWLINE Normally, when setting the value of a multi-line text widget, newline characters are automatically appended to the end of each line of text. Set this keyword to suppress this action. NOTIFY_REALIZE Set this keyword to a string that contains the name of a procedure to be called automatically when the specified widget is realized. This callback occurs just once (because widgets are realized only once). Each widget is allowed a single such "callback" procedure. It can be removed by setting the routine to the null string (''). The callback routine is called with the widget ID as its only argument. PRO_SET_VALUE A string containing the name of a procedure to be called when the SET_VALUE keyword to the WIDGET_CONTROL procedure is called for this widget. Using this technique allows you to designate a routine that sets the value for a widget. Compound widgets use this ability to define their values transparently to the user. RESOURCE_NAME A string containing an X Window System resource name to be applied to the widget. See "RESOURCE_NAME" on page 1527 for a complete discussion of this keyword. SCR_XSIZE Set this keyword to the desired "screen" width of the widget, in units specified by the UNITS keyword (pixels are the default). In many cases, setting this keyword is the same as setting the XSIZE keyword. SCR_YSIZE Set this keyword to the desired "screen" height of the widget, in units specified by the UNITS keyword (pixels are the default). In many cases, setting this keyword is the same as setting the YSIZE keyword. SCROLL Set this keyword to give the widget scroll bars that allow viewing portions of the widget contents that are not currently on the screen. SENSITIVE Set this keyword to control the initial sensitivity state of the widget. If SENSITIVE is zero, the widget becomes insensitive. If nonzero, it becomes sensitive. When a widget is sensitive, it has normal appearance and can receive user input. For example, a sensitive button widget can be activated by moving the mouse cursor over it and pressing a mouse button. When a widget is insensitive, it indicates the fact by changing its appearance, looking disabled, and it ignores any input. Sensitivity can be used to control when a user is allowed to manipulate the widget. Note that some widgets do not change their appearance when they are made insensitive, but they cease generating events. After creating the widget hierarchy, you can change the sensitivity state using the SENSITIVE keyword with the WIDGET_CONTROL procedure. TRACKING_EVENTS Set this keyword to cause widget tracking events to be issued for the widget whenever the mouse pointer enters or leaves the region covered by that widget. For the structure of tracking events, see "TRACKING_EVENTS" on page 1533 in the documentation for WIDGET_BASE. UNAME Set this keyword to a string that can be used to identify the widget in your code. You can associate a name with each widget in a specific hierarchy, and then use that name to query the widget hierarchy and get the correct widget ID. To query the widget hierarchy, use the WIDGET_INFO function with the FIND_BY_UNAME keyword. The UNAME should be unique to the widget hierarchy because the FIND_BY_UNAME keyword returns the ID of the first widget with the specified name. UNITS Set UNITS equal to 0 (zero) to specify that all measurements are in pixels (this is the default), to 1 (one) to specify that all measurements are in inches, or to 2 (two) to specify that all measurements are in centimeters. Note This keyword does not affect all sizing operations. Specifically, the value of UNITS is ignored when setting the XSIZE or YSIZE keywords to WIDGET_TEXT. UVALUE The "user value" to be assigned to the widget. Each widget can contain a user-specified value of any data type and organization. This value is not used by the widget in any way, but exists entirely for the convenience of the IDL programmer. This keyword allows you to set this value when the widget is first created. If UVALUE is not present, the widget's initial user value is undefined. VALUE The initial value setting of the widget. The value of a text widget is the current text displayed by the widget. VALUE can be either a string or an array of strings. Note that variables returned by the GET_VALUE keyword to WIDGET_CONTROL are always string arrays, even if a scalar string is specified in the call to WIDGET_TEXT. WRAP Set this keyword to indicate that scrolling or multi-line text widgets should automatically break lines between words to keep the text from extending past the right edge of the text display area. Note that carriage returns are not automatically entered when lines wrap; the value of the text widget will remain a single-element array unless you explicitly enter a carriage return. XOFFSET The horizontal offset of the widget in units specified by the UNITS keyword (pixels are the default) relative to its parent. This offset is specified relative to the upper left corner of the parent widget. Specifying an offset relative to a row or column major base widget does not work because those widgets enforce their own layout policies. This keyword is primarily of use relative to a plain base widget. Note that it is best to avoid using this style of widget programming. XSIZE The width of the widget in characters. Note that the physical width of the text widget depends on both the value of XSIZE and on the size of the font used. The default value of XSIZE varies according to your windowing system. On Windows and Mac, the default size is roughly 20 characters. On Motif, the default size depends on the width of the text widget. YOFFSET The vertical offset of the widget in units specified by the UNITS keyword (pixels are the default) relative to its parent. This offset is specified relative to the upper left corner of the parent widget. Specifying an offset relative to a row or column major base widget does not work because those widgets enforce their own layout policies. This keyword is primarily of use relative to a plain base widget. Note that it is best to avoid using this style of widget programming. YSIZE The height of the widget in text lines. Note that the physical height of the text widget depends on both the value of YSIZE and on the size of the font used. The default value of YSIZE is one line. Keywords to WIDGET_CONTROL A number of keywords to the WIDGET_CONTROL procedure affect the behavior of text widgets. In addition to those keywords that affect all widgets, the following are particularly useful: ALL_TEXT_EVENTS, APPEND, EDITABLE, GET_VALUE, KBRD_FOCUS_EVENTS, INPUT_FOCUS, NO_NEWLINE, SET_TEXT_SELECT, SET_TEXT_TOP_LINE, SET_VALUE, USE_TEXT_SELECT. Keywords to WIDGET_INFO A number of keywords to the WIDGET_INFO function return information that applies specifically to text widgets. In addition to those keywords that apply to all widgets, the following are particularly useful: KBRD_FOCUS_EVENTS, TEXT_ALL_EVENTS, TEXT_EDITABLE, TEXT_NUMBER, TEXT_OFFSET_TO_XY, TEXT_SELECT, TEXT_TOP_LINE, TEXT_XY_TO_OFFSET. Text Widget Events There are several variations of t1he text widget event structure depending on the specific event being reported. All of these structures contain the standard three fields (ID, TOP, and HANDLER) as well as an integer TYPE field that indicates which type of structure has been returned. Programs should always check the type field before referencing fields that are not present in all text event structures. The different text widget event structures are described below. Insert Single Character (TYPE = 0) This is the type of structure returned when a single character is typed or pasted into a text widget by a user. { WIDGET_TEXT_CH, ID:0L, TOP:0L, HANDLER:0L, TYPE:0, OFFSET:0L, CH:0B } OFFSET is the (zero-based) insertion position that will result after the character is inserted. CH is the ASCII value of the character. Insert Multiple Characters (TYPE = 1) This is the type of structure returned when multiple characters are pasted into a text widget by the window system. { WIDGET_TEXT_STR, ID:0L, TOP:0L, HANDLER:0L, TYPE:1, OFFSET:0L, STR:'' } OFFSET is the (zero-based) insertion position that will result after the text is inserted. STR is the string to be inserted. Delete Text (TYPE = 2) This is the type of structure returned when any amount of text is deleted from a text widget. { WIDGET_TEXT_DEL, ID:0L, TOP:0L, HANDLER:0L, TYPE:2, OFFSET:0L, LENGTH:0L } OFFSET is the (zero-based) character position of the first character to be deleted. It is also the insertion position that will result when the characters have been deleted. LENGTH gives the number of characters involved. A LENGTH of zero indicates that no characters were deleted. Selection (TYPE = 3) This is the type of structure returned when an area of text is selected (highlighted) by the user. { WIDGET_TEXT_SEL, ID:0L, TOP:0L, HANDLER:0L, TYPE:3, OFFSET:0L, LENGTH:0L } The event announces a change in the insertion point. OFFSET is the (zero-based) character position of the first character to be selected. LENGTH gives the number of characters involved. A LENGTH of zero indicates that no characters are selected, and the new insertion position is given by OFFSET. Note that text insertion, text deletion, or any change in the current insertion point causes any current selection to be lost. In such cases, the loss of selection is implied by the text event reporting the insert/delete/movement and a separate zero length selection event is not sent. Keyboard Focus Events Text widgets return the following event structure when the keyboard focus changes and the base was created with the KBRD_FOCUS_EVENTS keyword set: { WIDGET_KBRD_FOCUS, ID:0L, TOP:0L, HANDLER:0L, ENTER:0 } ID is the widget ID of the text widget generating the event. TOP is the widget ID of the top level widget containing ID. HANDLER contains the widget ID of the widget associated with the handler routine. The ENTER field returns 1 (one) if the text widget is gaining the keyboard focus, or 0 (zero) if the text widget is losing the keyboard focus. See Also CW_FIELD, XDISPLAYFILE WINDOW [Previous Routine] [Next Routine] [List of Routines] NAME: WINDOW The WINDOW procedure creates a window for the display of graphics or text. It is only necessary to use WINDOW if more than one simultaneous window or a special size window is desired because a window is created automatically the first time any display procedure attempts to access the window system. The newly-created window becomes the current window, and the system variable !D.WINDOW is set to that window's window index. (See the description of the WSET procedure for a discussion of the current IDL window.) The behavior of WINDOW varies slightly depending on the window system in effect. See the discussion of IDL graphics devices in Appendix B, "IDL Graphics Devices" for additional details. Syntax WINDOW [, Window_Index] [, COLORS=value] [, /FREE] [, /PIXMAP] [, RETAIN={0 | 1 | 2}] [, TITLE=string] [, XPOS=value] [, YPOS=value] [, XSIZE=pixels] [, YSIZE=pixels] Arguments Window_Index The window index for the newly-created window. A window index is an integer value between 0 and 31 that is used to refer to the window. If this parameter is omitted, window index 0 is used. If the value of Window_Index specifies an existing window, the existing window is deleted and a new one is created. If you need to create more than 32 windows, use the FREE keyword described below. Keywords COLORS Note This keyword is ignored on Windows and Macintosh. The maximum number of color table indices to be used when drawing. This keyword has an effect only if supplied when the first window is created. If COLORS is not present when the first window is created, all or most of the available color indices are allocated depending upon the window system in use. To use monochrome windows on a color display in X Windows, use COLORS = 2 when creating the first window. One color table is maintained for all windows. A negative value for COLORS specifies that all but the given number of colors from the shared color table should be allocated. Although this keyword is ignored on Windows and Macintosh, we could use the following code to use a monochrome window on all platforms: WINDOW, COLORS=2 ; ignored on Windows and Mac white=!D.N_COLORS-1 PLOT, FINDGEN(20), COLOR=white FREE Set this keyword to create a window using the smallest unused window index above 32. If this keyword is present, the Window_Index argument can be omitted. The default position of the new window is opposite that of the current window. Using the FREE keyword allows the creation of a large number of windows. The system variable !D.WINDOW is set to the index of the newly-created window. PIXMAP Set the PIXMAP keyword to specify that the window being created is actually an invisible portion of the display memory called a pixmap. RETAIN Set this keyword to 0, 1, or 2 to specify how backing store should be handled for the window: * 0 = no backing store * 1 = requests that the server or window system provide backing store * 2 = specifies that IDL provide backing store directly See "Backing Store" on page 2351 for details. TITLE A scalar string that contains the window's label. If not specified, the window is given a label of the form "IDL n", where n is the index number of the window. For example, to create a window with the label "IDL Graphics", enter: WINDOW, TITLE='IDL Graphics' XPOS The X position of the window, specified in device coordinates. On Motif platforms, XPOS specifies the X position of the lower left corner and is measured from the lower left corner of the screen. On Windows and Macintosh platforms, XPOS specifies the X position of the upper left corner and is measured from the upper left corner of the screen. That is, specifying WINDOW, XPOS = 0, YPOS = 0 will create a window in the lower left corner on Motif machines and in the upper left corner on Windows and Macintosh machines. If no position is specified, the position of the window is determined from the value of Window Index using the following rules: * Window 0 is placed in the upper right hand corner. * Even numbered windows are placed on the top half of the screen and odd numbered windows are placed on the bottom half. * Windows 0,1,4,5,8, and 9 are placed on the right side of the screen and windows 2,3,6, and 7 are placed on the left. Note The order of precedence (highest to lowest) for positioning windows is: XPOS/YPOS keywords to WINDOW, Tile/Cascade IDE graphics (user system) preferences, optional index argument to WINDOW. Also realize that setting LOCATION is only a request to the Window manager and may not always be honored due to system peculiarities. YPOS The Y position of the window, specified in device coordinates. See the description of XPOS for details. XSIZE The width of the window in pixels. YSIZE The height of the window in pixels. Example Create graphics window number 0 with a size of 400 by 400 pixels and a title that reads "Square Window" by entering: WINDOW, 0, XSIZE=400, YSIZE=400, TITLE='Square Window' See Also WDELETE, WSET, WSHOW WRITE_BMP [Previous Routine] [Next Routine] [List of Routines] NAME: WRITE_BMP The WRITE_BMP procedure writes an image and its color table vectors to a Microsoft Windows Version 3 device independent bitmap file (.BMP). WRITE_BMP does not handle 1-bit-deep images or compressed images, and is not fast for 4-bit images. The algorithm works best on images where the number of bytes in each scan-line is evenly divisible by 4. This routine is written in the IDL language. Its source code can be found in the file write_bmp.pro in the lib subdirectory of the IDL distribution. Syntax WRITE_BMP, Filename, Image[, R, G, B] [, /FOUR_BIT] [, IHDR=structure] [, HEADER_DEFINE=h{define h before call}] [, /RGB] Arguments Filename A scalar string containing the full pathname of the bitmap file to write. Image The array to write into the new bitmap file. The array should be scaled into a range of bytes for 8- and 24-bit deep images. Scale to 0-15 for 4-bit deep images. If the image has 3 dimensions and the first dimension is 3, a 24-bit deep bitmap file is created. Note For 24-bit images, color interleaving is blue, green, red: Image[0, i, j] = blue, Image[1, i, j] = green, Image[2, i, j] = red. R, G, B Color tables. If omitted, the colors loaded in the COLORS common block are used. Keywords FOUR_BIT Set this keyword to write as a 4-bit device independent bitmap. If omitted or zero, an 8-bit deep bitmap is written. IHDR Set this keyword to a BITMAPINFOHEADER structure containing the file header fields that are not obtained from the image itself. The fields in this structure that can be set are: bi{XY}PelsPerMeter, biClrUsed, and biClrImportant. HEADER_DEFINE If this keyword is set, WRITE_BMP returns an empty BITMAPINFOHEADER structure, containing zeros. No other actions are performed. This structure may be then modified with the pertinent fields and passed in via the IHDR keyword parameter. See the Microsoft Windows Programmers Reference Guide for a description of each field in the structure. Note: this parameter must be defined before the call. For example: H = 0 WRITE_BMP, HEADER_DEFINE = H RGB Set this keyword to reverse the color interleaving for 24-bit images to red, green, blue: Image[0, i, j] = red, Image[1, i, j] = green, Image[2, i, j] = blue. By default, 24- bit images are written with color interleaving of blue, green, red. Examples The following command captures the contents of the current IDL graphics window and saves it to a Microsoft Windows Bitmap file with the name test.bmp. Note that this works only on a PseudoColor (8-bit) display: WRITE_BMP, 'test.bmp', TVRD() The following commands scale an image to 0-15, and then write a 4-bit BMP file, using a grayscale color table: ; Create a ramp from 0 to 255: r = BYTSCL(INDGEN(16)) WRITE_BMP, 'test.bmp', BYTSCL(Image, MAX=15), r, r, r, /FOUR See Also READ_BMP, QUERY_* Routines WRITE_IMAGE [Previous Routine] [Next Routine] [List of Routines] NAME: WRITE_IMAGE The WRITE_IMAGE procedure writes an image and its color table vectors, if any, to a file of a specified type. WRITE_IMAGE can write most types of image files supported by IDL. Syntax WRITE_IMAGE, Filename, Format, Data [, Red, Green, Blue] [, /APPEND] Arguments Filename A scalar string containing the name of the file to write. Format A scalar string containing the name of the file format to write. The following are the supported formats: * BMP * JPEG * PNG * PPM * SRF * TIFF * DICOM Data An IDL variable containing the image data to write to the file. Red An optional vector containing the red channel of the color table if a colortable exists. Green An optional vector containing the green channel of the color table if a colortable exists. Blue An optional vector containing the blue channel of the color table if a colortable exists. Keywords APPEND Set this keyword to force the image to be appended to the file instead of overwriting the file. APPEND may be used with image formats that supports multiple images per file and is ignored for formats that support only a single image per file. WRITE_JPEG [Previous Routine] [Next Routine] [List of Routines] NAME: WRITE_JPEG The WRITE_JPEG procedure writes compressed images to files. JPEG (Joint Photographic Experts Group) is a standardized compression method for full-color and gray-scale images. This procedure is based in part on the work of the Independent JPEG Group. As the Independent JPEG Group states, JPEG is intended for real-world scenes (such as digitized photographs). Line art, such as drawings or IDL plots, and other unrealistic images are not its strong suit. Note also that JPEG is a lossy compression scheme. That is, the output image is not identical to the input image. Hence you cannot use JPEG if you must have identical output bits. On typical images of real- world scenes, however, very good compression levels can be obtained with no visible change, and amazingly high compression levels are possible if you can tolerate a low- quality image. You can trade off output image quality against compressed file size by adjusting a compression parameter. Files are encoded in JFIF, the JPEG File Interchange Format; however, such files are usually simply called JPEG files. If you need to store images in a format that uses lossless compression, consider using the WRITE_PNG procedure. This procedure writes a Portable Network Graphics (PNG) file using lossless compression with either 8 or 16 data bits per channel. To store 8-bit or 24-bit images without compression, consider using WRITE_BMP (for Microsoft Bitmap format files) or WRITE_TIFF (to write Tagged Image Format Files). For a short technical introduction to the JPEG compression algorithm, see: Wallace, Gregory K. "The JPEG Still Picture Compression Standard", Communications of the ACM, April 1991 (vol. 34, no. 4), pp. 30-44. Note All JPEG files consist of byte data. Input data is converted to bytes before being written to a JPEG file. Syntax WRITE_JPEG [, Filename | , UNIT=lun] , Image [, /ORDER] [, /PROGRESSIVE] [, QUALITY=value{0 to 100}] [, TRUE={1 | 2 | 3}] Arguments Filename A string containing the name of file to be written in JFIF (JPEG) format. If this parameter is not present, the UNIT keyword must be specified. Image A byte array of either two or three dimensions, containing the image to be written. Grayscale images must have two dimensions. TrueColor images must have three dimensions with the index of the dimension that contains the color specified with the TRUE keyword. Keywords ORDER JPEG/JFIF images are normally written in top-to-bottom order. If the image array is in the standard IDL order (i.e., from bottom-to-top) set ORDER to 0, its default value. If the image array is in top-to-bottom order, ORDER must be set to 1. PROGRESSIVE Set this keyword to write the image as a series of scans of increasing quality. When used with a slow communications link, a decoder can generate a low-quality image very quickly, and then improve its quality as more scans are received. Warning Not all JPEG applications can handle progressive JPEG files, and it is up the JPEG reader to progressively display the JPEG image. For example, IDL's READ_JPEG routine ignores the progressive readout request and reads the entire image in at the first reading. QUALITY This keyword specifies the quality index, in the range of 0 (terrible) to 100 (excellent) for the JPEG file. The default value is 75, which corresponds to very good quality. Lower values of QUALITY produce higher compression ratios and smaller files. TRUE This keyword specifies the index, starting at 1, of the dimension over which the color is interleaved. For example, for an image that is pixel interleaved and has dimensions of (3, m, n), set TRUE to 1. Specify 2 for row-interleaved images (m, 3, n); and 3 for band-interleaved images (m, n, 3). If TRUE is not set, the image is assumed to have no interleaving (it is not a TrueColor image). UNIT This keyword designates the logical unit number of an already open file to receive the output, allowing multiple JFIF images per file or the embedding of JFIF images in other data files. If this keyword is used, Filename should not be specified. Note When using VMS, open the file with the /STREAM keyword. Note When opening a file intended for use with the UNIT keyword, if the filename does not end in .jpg, or .jpeg, you must specify the STDIO keyword to OPEN in order for the file to be compatible with WRITE_JPEG. Examples Write the image contained in the array A, using JPEG compression with a quality index of 25. The image is stored in bottom-to-top order: image = DIST(100) WRITE_JPEG, 'test1.jpg', image, QUALITY=25 Write a TrueColor image to a JPEG file. The image is contained in the band- interleaved array A with dimensions (m, n, 3). Assume it is stored in top-to-bottom order: WRITE_JPEG, 'test2.jpg', image, TRUE=3, /ORDER See Also READ_JPEG, QUERY_* Routines WRITE_NRIF [Previous Routine] [Next Routine] [List of Routines] NAME: WRITE_NRIF The WRITE_NRIF procedure writes an image and its color table vectors to an NCAR Raster Interchange Format (NRIF) rasterfile. WRITE_NRIF only writes 8- or 24-bit deep rasterfiles of types "Indexed Color" (8- bit) and "Direct Color integrated" (24-bit). The color map is included only for 8-bit files. See the document "NCAR Raster Interchange Format and TAGS Raster Reference Manual," available from the Scientific Computing Division, National Center for Atmospheric Research, Boulder, CO, 80307-3000, for information on the structure of NRIF files. This routine is written in the IDL language. Its source code can be found in the file write_nrif.pro in the lib subdirectory of the IDL distribution. Syntax WRITE_NRIF, File, Image [, R, G, B] Arguments File A scalar string containing the full path name of the NRIF file to write. Image The byte array to be written to the NRIF file. If Image has the dimensions (n,m), an 8- bit NRIF file with color tables is created. If Image has the dimensions (3,n,m), a 24- bit NRIF file is created, where each byte triple represents the red, green, and blue intensities at (n,m) on a scale from 0 to 255. The NRIF image will be rendered from bottom to top, in accordance with IDL standards. R, G, B The Red, Green, and Blue color vectors to be used as a color table with 8-bit images. If color vectors are supplied, they are included in the output (8-bit images only). If R, G, B values are not provided, the last color table established using LOADCT is included. If no color table has been established, WRITE_NRIF calls LOADCT to load the grayscale entry (table 0). Note WRITE_NRIF does not recognize color vectors loaded directly using TVLCT, so if a custom color table is desired and it is not convenient to use XPALETTE, include the R, G, and B vectors that were used to create the color table. WRITE_PICT [Previous Routine] [Next Routine] [List of Routines] NAME: WRITE_PICT The WRITE_PICT procedure writes an image and its color table vectors to a PICT (version 2) format image file. The PICT format is used by Apple Macintosh computers. Note: WRITE_PICT only works with 8-bit displays This routine is written in the IDL language. Its source code can be found in the file write_pict.pro in the lib subdirectory of the IDL distribution. Syntax WRITE_PICT, Filename [, Image, R, G, B] Arguments Filename A scalar string containing the full pathname of the PICT file to write. Image The byte array to be written to the PICT file. If Image is omitted, the entire current graphics window is read into an array and written to the PICT file. R, G, B The Red, Green, and Blue color vectors to be written to the PICT file. If R, G, B values are not provided, the last color table established using LOADCT is included. If no color table has been established, WRITE_PICT calls LOADCT to load the grayscale entry (table 0). Example Create a pseudo screen dump from the current window. Note that this works only on a PseudoColor (8-bit) display: WRITE_PICT, 'test.pict', TVRD() See Also READ_PICT, QUERY_* Routines WRITE_PNG [Previous Routine] [Next Routine] [List of Routines] NAME: WRITE_PNG The WRITE_PNG procedure writes a 2D or 3D IDL variable into a Portable Network Graphics (PNG) file. The data in the file is stored using lossless compression with either 8 or 16 data bits per channel, based on the input IDL variable type. 3D IDL variables must have the number of channels as their leading dimension (pixel interleaved). For BYTE format 2D IDL variables, an optional palette may be stored in the image file along with a list of pixel values which are to be considered transparent by a reading program. Note IDL supports version 1.0.5 of the PNG Library. Syntax WRITE_PNG, Filename, Image[, R, G, B] [, /ORDER] [, /VERBOSE] [, TRANSPARENT=array] Arguments Filename A scalar string containing the full pathname of the PNG file to write. Image The array to write into the new PNG file. If Image is one of the integer data types, it is converted to type unsigned integer (UINT) and written out at 16 data bits per channel. All other data types are converted to bytes and written out at 8-bits per channel. Note If Image is two-dimensional (single-channel) and R, G, and B are provided, all input data types (including integer) are converted to bytes and written out as 8-bit data. R, G, B For single-channel images, R, G, and B should contain the red, green, and blue color vectors, respectively. For multi-channel images, these arguments are ignored. Keywords ORDER Set this keyword to indicate that the rows of the image should be written from bottom to top. The rows are written from top to bottom by default. ORDER provides compatibility with PNG files written using versions of IDL prior to IDL 5.4, which wrote PNG files from bottom to top. VERBOSE Produces additional diagnostic output during the write. TRANSPARENT Set this keyword to an array of pixel index values which are to be treated as "transparent" for the purposes of image display. This keyword is valid only if Image is a single-channel (color indexed) image and the R, G, B palette is provided. Example Create an RGBA (16-bits/channel) and a Color Indexed (8-bits/channel) image with a palette. rgbdata = UINDGEN(4,320,240) cidata = BYTSCL(DIST(256)) red = INDGEN(256) green = INDGEN(256) blue = INDGEN(256) WRITE_PNG,'rgb_image.png',rgbdata WRITE_PNG,'ci_image.png',cidata,red,green,blue ; Query and Read the data: names = ['rgb_image.png','ci_image.png','unknown.png'] FOR i=0,N_ELEMENTS(names)-1 DO BEGIN ok = QUERY_PNG(names[i],s) IF (ok) THEN BEGIN HELP,s,/STRUCTURE IF (s.HAS_PALETTE) THEN BEGIN img = READ_PNG(names[i],rpal,gpal,bpal) HELP,img,rpal,gpal,bpal ENDIF ELSE BEGIN img = READ_PNG(names[i]) HELP,img ENDELSE ENDIF ELSE BEGIN PRINT,names[i],' is not a PNG file' ENDELSE ENDFOR See Also READ_PNG, QUERY_* Routines WRITE_PPM [Previous Routine] [Next Routine] [List of Routines] NAME: WRITE_PPM The WRITE_PPM procedure writes an image to a PPM (TrueColor) or PGM (gray scale) file. This routine is written in the IDL language. Its source code can be found in the file write_ppm.pro in the lib subdirectory of the IDL distribution. Note WRITE_PPM only writes 8-bit deep PGM/PPM files of the standard type. Images should be ordered so that the first row is the top row. PPM/PGM format is supported by the PBMPLUS toolkit for converting various image formats to and from portable formats, and by the Netpbm package. Syntax WRITE_PPM, Filename, Image [, /ASCII] Arguments Filename A scalar string specifying the full pathname of the PPM or PGM file to write. Image The 2D (gray scale) or 3D (TrueColor) array to be written to a file. Keywords ASCII Set this keyword to force WRITE_PPM to use formatted ASCII input/output to write the image data. The default is to use the far more efficient binary input/output (RAWBITS) format. Example image = DIST(100) WRITE_PPM, 'file.ppm', image See Also READ_PPM, QUERY_* Routines WRITE_SPR [Previous Routine] [Next Routine] [List of Routines] NAME: WRITE_SPR The WRITE_SPR procedure writes a row-indexed sparse array structure to a specified file. Row-indexed sparse arrays are created using the SPRSIN function. Syntax WRITE_SPR, AS, Filename Arguments AS A row-indexed sparse array created by SPRSIN. Filename The name of the file that will contain AS. Example ; Create an array: A = [[3.,0., 1., 0., 0.],$ [0.,4., 0., 0., 0.],$ [0.,7., 5., 9., 0.],$ [0.,0., 0., 0., 2.],$ [0.,0., 0., 6., 5.]] ; Convert it to sparse storage format: A = SPRSIN(A) ; Store it in the file sprs.as: WRITE_SPR, A, 'sprs.as' See Also FULSTR, LINBCG, SPRSAB, SPRSAX, SPRSIN, READ_SPR WRITE_SRF [Previous Routine] [Next Routine] [List of Routines] NAME: WRITE_SRF The WRITE_SRF procedure writes an image and its color table vectors to a Sun Raster File (SRF). WRITE_SRF only writes 32-, 24-, and 8-bit-deep rasterfiles of type RT_STANDARD. Use the UNIX command rasfilter8to1 to convert these files to 1-bit deep files. See the file /usr/include/rasterfile.h for the structure of Sun rasterfiles. This routine is written in the IDL language. Its source code can be found in the file write_srf.pro in the lib subdirectory of the IDL distribution. Syntax WRITE_SRF, Filename [, Image, R, G, B] [, /ORDER] [, /WRITE_32] Arguments Filename A scalar string containing the full pathname of the SRF to write. Image The array to be written to the SRF. If Image has dimensions (3,n,m), a 24-bit SRF is written. If Image is omitted, the entire current graphics window is read into an array and written to the SRF file. Image should be of byte type, and in top to bottom scan line order. R, G, B The Red, Green, and Blue color vectors to be written to the file. If R, G, B values are not provided, the last color table established using LOADCT is included. If no color table has been established, WRITE_SRF calls LOADCT to load the grayscale entry (table 0). Keywords ORDER Set this keyword to write the image from the top down instead of from the bottom up. This setting is only necessary when writing a file from the current IDL graphics window; it is ignored when writing a file from a data array passed as a parameter. WRITE_32 Set this keyword to write a 32-bit file. If the input image is a TrueColor image, dimensioned (3, n, m), it is normally written as a 24-bit raster file. Example Create a pseudo screen dump from the current window: WRITE_SRF, 'test.srf', TVRD() See Also READ_SRF, QUERY_* Routines WRITE_SYLK [Previous Routine] [Next Routine] [List of Routines] NAME: WRITE_SYLK The WRITE_SYLK function writes the contents of an IDL variable to a SYLK (Symbolic Link) format spreadsheet data file. The function returns TRUE if the write operation was successful. Note This routine writes only numeric and string SYLK data. It cannot handle spreadsheet and cell formatting information (cell width, text justification, font type, date, time, monetary notations, etc.). A given SYLK data file cannot be appended with data blocks through subsequent calls. This routine is written in the IDL language. Its source code can be found in the file write_sylk.pro in the lib subdirectory of the IDL distribution. Syntax Result = WRITE_SYLK( File, Data [, STARTCOL=column] [, STARTROW=row] ) Arguments File A scalar string specifying the full path name of the SYLK file to write. Data A scalar, vector, or 2D array to be written to File. Keywords STARTCOL Set this keyword to the first column of spreadsheet cells to write. If not specified, the write operation begins with the first column found in the file (column 0). STARTROW Set this keyword to the first row of spreadsheet cells to write. If not specified, the write operation begins with the first row of cells found in the file (row 0). Example Suppose you wish to write the contents of a 2 by 2 floating-point array, data, to a SYLK data file called "bar.slk" such that the matrix would appear with it's upper left data at the cell in the 10th row and the 20th column. Use the following command: status = WRITE_SYLK('bar.slk', data, STARTROW = 9, STARTCOL = 19) The IDL variable status will contain the value 1 if the operation was successful. See Also READ_SYLK WRITE_TIFF [Previous Routine] [Next Routine] [List of Routines] NAME: WRITE_TIFF The WRITE_TIFF procedure can write TIFF files with one or more channels, where each channel can contain 8, 16, 32, or floating point pixels. Syntax WRITE_TIFF, Filename [, Image, Order] [, BITS_PER_SAMPLE] [, UNITS] [, ORIENTATION] [, XRESOL] [, YRESOL] [, /APPEND] [, RED=value] [, GREEN=value] [, BLUE=value] [, COMPRESSION={0 | 1 | 2}] [, GEOTIFF=structure] [, /LONG | , /SHORT | ,/FLOAT] [, PLANARCONFIG={1 | 2}] [, /VERBOSE] [, XRESOL=pixels/inch] [, YRESOL=pixels/inch] Arguments Filename A scalar string containing the full pathname of the TIFF to write. Image The array to be written to the TIFF. If Image has dimensions (k,n,m), a k-channel TIFF is written. Image should be in top to bottom scan line order. By default, this array is converted to byte format before being written (see the LONG, SHORT and FLOAT keywords below). Note that many TIFF readers can read only one- or three- channel images. Note The Image argument is optional if PLANARCONFIG is set to 2 and the RED, GREEN, and BLUE keywords have been set to 2D arrays. Order This argument should be 0 if the image is stored from bottom to top (the default). For images stored from top to bottom, this argument should be 1. Warning Not all TIFF readers honor the value of the Order argument. IDL writes the value into the file, but many known readers ignore this value. In such cases, we recommend that you convert the image to top to bottom order with the REVERSE function and then set Order to 1. Keywords UNITS Set this new keyword to indicate the units of the XRESOL and YRESOL keywords. Possible values are: * 1 = No units * 2 = Inches (the default) * 3 = Centimeters ORIENTATION Set this new keyword to indicate the orientation of the image with respect to the columns and rows of Image. Possible values are: * 1 = Column 0 represents the left-hand side, and row 0 represents the top. * 2 = Column 0 represents the right-hand side, and row 0 represents the top. * 3 = Column 0 represents the right-hand side, and row 0 represents the bottom. * 0 or 4 = Column 0 represents the left-hand side, and row 0 represents the bottom. * 5 = Column 0 represents the top, and row 0 represents the left-hand side. * 6 = Column 0 represents the top, and row 0 represents the right-hand side. * 7 = Column 0 represents the bottom, and row 0 represents the right-hand side. * 8 = Column 0 represents the bottom, and row 0 represents the left-hand side. The default is ORIENTATION=1. Warning - Not all TIFF readers honor the value of the ORIENTATION field. IDL writes the value into the file, but many known readers ignore this value. In such cases, it is recommended that the image be converted to top to bottom order with the REVERSE function and then ORIENTATION be set to 1. BITS_PER_SAMPLE This new keyword can be used for a grayscale image, by being set to either 1, 4, or 8 to indicate the bits per sample to write. For 1-bit (bi-level) images, an output bit is assigned the value 1 if the corresponding input pixel is nonzero. For 4-bit grayscale images, the input pixel values should be in the range 0 through 15. The default is BITS_PER_SAMPLE = 8. This keyword is ignored if an RGB image or color palette is present, or if one of the FLOAT, LONG, or SHORT keywords is set. Item APPEND Set this keyword to specify that the image should be added to the existing file, creating a multi-image TIFF file. COMPRESSION Set this keyword to select the type of compression to be used: * 0 = none (default) * 2 = PackBits. FLOAT Set this keyword to write the pixel components as floating-point entities (the default is 8-bit). GEOTIFF Set this keyword to an anonymous structure containing one field for each of the GeoTIFF tags and keys to be written into the file. The GeoTIFF structure is formed using fields named from the following table. Anonymous Structure Field Name IDLDatatype TAGS: "MODELPIXELSCALETAG" DOUBLE[3] "MODELTRANSFORMATIONTAG" DOUBLE[4,4] "MODELTIEPOINTTAG" DOUBLE[6,*] KEYS: "GTMODELTYPEGEOKEY" INT "GTRASTERTYPEGEOKEY" INT "GTCITATIONGEOKEY" STRING "GEOGRAPHICTYPEGEOKEY" INT "GEOGCITATIONGEOKEY" STRING Table 98: GEOTIFF Structures Anonymous Structure Field Name IDLDatatype "GEOGGEODETICDATUMGEOKEY" INT "GEOGPRIMEMERIDIANGEOKEY" INT "GEOGLINEARUNITSGEOKEY" INT "GEOGLINEARUNITSIZEGEOKEY" DOUBLE "GEOGANGULARUNITSGEOKEY" INT "GEOGANGULARUNITSIZEGEOKEY" DOUBLE "GEOGELLIPSOIDGEOKEY" INT "GEOGSEMIMAJORAXISGEOKEY" DOUBLE "GEOGSEMIMINORAXISGEOKEY" DOUBLE "GEOGINVFLATTENINGGEOKEY" DOUBLE "GEOGAZIMUTHUNITSGEOKEY" INT "GEOGPRIMEMERIDIANLONGGEOKEY" DOUBLE "PROJECTEDCSTYPEGEOKEY" INT "PCSCITATIONGEOKEY" STRING "PROJECTIONGEOKEY" INT "PROJCOORDTRANSGEOKEY" INT "PROJLINEARUNITSGEOKEY" INT "PROJLINEARUNITSIZEGEOKEY" DOUBLE "PROJSTDPARALLEL1GEOKEY" DOUBLE "PROJSTDPARALLEL2GEOKEY" DOUBLE "PROJNATORIGINLONGGEOKEY" DOUBLE "PROJNATORIGINLATGEOKEY" DOUBLE "PROJFALSEEASTINGGEOKEY" DOUBLE "PROJFALSENORTHINGGEOKEY" DOUBLE "PROJFALSEORIGINLONGGEOKEY" DOUBLE Table 98: GEOTIFF Structures Anonymous Structure Field Name IDLDatatype "PROJFALSEORIGINLATGEOKEY" DOUBLE "PROJFALSEORIGINEASTINGGEOKEY" DOUBLE "PROJFALSEORIGINNORTHINGGEOKEY" DOUBLE "PROJCENTERLONGGEOKEY" DOUBLE "PROJCENTERLATGEOKEY" DOUBLE "PROJCENTEREASTINGGEOKEY" DOUBLE "PROJCENTERNORTHINGGEOKEY" DOUBLE "PROJSCALEATNATORIGINGEOKEY" DOUBLE "PROJSCALEATCENTERGEOKEY" DOUBLE "PROJAZIMUTHANGLEGEOKEY" DOUBLE "PROJSTRAIGHTVERTPOLELONGGEOKEY" DOUBLE "VERTICALCSTYPEGEOKEY" INT "VERTICALCITATIONGEOKEY" STRING "VERTICALDATUMGEOKEY" INT "VERTICALUNITSGEOKEY" INT Table 98: GEOTIFF Structures Note If a GeoTIFF key appears multiple times in a file, only the value for the first instance of the key is returned. LONG Set this keyword to write the pixel components as unsigned 32-bit entities (the default is 8-bit). PLANARCONFIG This keyword determines the order in which a multi-channel image is stored and written. It has no effect with a single-channel image. Set this keyword to 2 to if the Image parameter is interleaved by "plane", or band, and its dimensions are (Columns, Rows, Channels). The default value is 1, indicating that multi-channel images are interleaved by color, also called channel, and its dimensions are (Channels, Columns, Rows). As a special case, this keyword may be set to 2 to write an RGB image that is contained in three separate arrays (color planes), stored in the variables specified by the RED, GREEN, and BLUE keywords. Otherwise, omit this parameter (or set it to 1). Note Many TIFF readers can read only one- or three-channel images. RED, GREEN, BLUE If you are writing a Palette color image, set these keywords equal to the color table vectors, scaled from 0 to 255. If you are writing an RGB interleaved image (i.e., if the PLANARCONFIG keyword is set to 2), set these keywords to the names of the variables containing the three image components. SHORT Set this keyword to write the pixel components as unsigned 16-bit entities (the default is 8-bit). VERBOSE Set this keyword to produce additional diagnostic output during the write. XRESOL This existing keyword sets the horizontal resolution. Units may now be set for XRESOL using the UNITS keyword. Set this keyword to the horizontal resolution, in pixels per inch. The default is 100. YRESOL This existing keyword sets vertical resolution. Units may now be specified for YRESOL using the UNITS keyword. Set this keyword to the vertical resolution, in pixels per inch. The default is 100. Example Example 1 Create a pseudo screen dump from the current window. Note that this works only on a PseudoColor (8-bit) display: WRITE_TIFF, 'test.tiff', TVRD() Example 2 Write a three-channel image from three one-channel (two-dimensional) arrays, contained in the variables Red, Green, and Blue: WRITE_TIFF, 'test.tif', Red, Green, Blue, PLANARCONFIG=2 Example 3 Write and read a multi-image TIFF file. The first image is a 16-bit single channel image stored using compression. The second image is an RGB image stored using 32- bits/channel uncompressed. ; Write the image data: data = FIX(DIST(256)) rgbdata = LONARR(3,320,240) WRITE_TIFF,'multi.tif',data,COMPRESSION=1,/SHORT WRITE_TIFF,'multi.tif',rgbdata,/LONG,/APPEND ; Read the image data back ok = QUERY_TIFF('multi.tif',s) IF (ok) THEN BEGIN FOR i=0,s.NUM_IMAGES-1 DO BEGIN imp = QUERY_TIFF('multi.tif',t,IMAGE_INDEX=i) img = READ_TIFF('multi.tif',IMAGE_INDEX=i) HELP,t,/STRUCTURE HELP,img ENDFOR ENDIF See Also READ_TIFF, QUERY_* Routines WRITE_WAV [Previous Routine] [Next Routine] [List of Routines] NAME: WRITE_WAV The WRITE_WAV procedure writes the audio stream to the named .WAV file. Syntax WRITE_WAV, Filename, Data, Rate Arguments Filename A scalar string containing the full pathname of the .WAV file to write. Data The array to write into the new .WAV file. The array can be a one- or two- dimensional array. A two-dimensional array is written as a multi-channel audio stream where the leading dimension of the IDL array is the number of channels. If the input array is in BYTE format, the data is written as 8-bit samples, otherwise, the data is written as signed 16-bit samples. Rate The sampling rate for the data array in samples per second. Keywords None. WRITE_WAVE [Previous Routine] [Next Routine] [List of Routines] NAME: WRITE_WAVE The WRITE_WAVE procedure writes a three dimensional IDL array to a .wave or .bwave file for use with the Wavefront Advanced Data Visualizer. Note that this routine only writes one scalar field for each Wavefront file that it creates. This routine is written in the IDL language. Its source code can be found in the file write_wave.pro in the lib subdirectory of the IDL distribution. Syntax WRITE_WAVE, File, Array [, /BIN] [, DATANAME=string] [, MESHNAME=string] [, /NOMESHDEF] [, /VECTOR] Arguments File A scalar string containing the full path name of the Wavefront file to write. Array A 3D array to be written to the file. Keywords BIN Set this keyword to create a binary file. By default, text files are created. DATANAME Set this keyword to the name of the data inside of the Wavefront file. If not specified, the name used is "idldata". MESHNAME Set this keyword to the name of the mesh used in the Wavefront file. If not specified, the name used is "idlmesh". NOMESHDEF Set this keyword to omit the mesh definition from the Wavefront file. VECTOR Set this keyword to write the variable as a vector. The data is written as an array of 3- space vectors. The array may contain any number of dimensions but must have a leading dimension of 3. If the leading array dimension is not 3, this keyword is ignored. See Also READ_WAVE WRITEU [Previous Routine] [Next Routine] [List of Routines] NAME: WRITEU The WRITEU procedure writes unformatted binary data from an expression into a file. This procedure performs a direct transfer with no processing of any kind being done to the data. Syntax WRITEU, Unit, Expr1 ..., Exprn [, TRANSFER_COUNT=variable] VMS-Only Keywords: [, /REWRITE] Arguments Unit The IDL file unit to which the output is sent. Expri The expressions to be output. For non-string variables, the number of bytes implied by the data type is output. When WRITEU is used with a variable of type string, IDL outputs exactly the number of bytes contained in the existing string. Keywords TRANSFER_COUNT Set this keyword to a named variable in which to return the number of elements transferred by the output operation. Note that the number of elements is not the same as the number of bytes (except in the case where the data type being transferred is bytes). For example, transferring 256 floating-point numbers yields a transfer count of 256, not 1024 (the number of bytes transferred). This keyword is useful with files opened with the RAWIO keyword to the OPEN routines. Normally, writing more data than an output device will accept causes an error. Files opened with the RAWIO keyword will not generate such an error. Instead, the programmer must keep track of the transfer count to judge the success or failure of a WRITEU operation. VMS-Only Keywords Note The obsolete FORWRT routine has been replaced by WRITEU. REWRITE When writing data to a file with indexed organization, setting the REWRITE keyword specifies that the data should update the contents of the most recently input record instead of creating a new record. Example ; Create some data to store in a file: D = BYTSCL(DIST(200)) ; Open a new file for writing as IDL file unit number 1: OPENW, 1, 'newfile' ; Write the data in D to the file: WRITEU, 1, D ; Close file unit 1: CLOSE, 1 See Also OPEN, READU WSET [Previous Routine] [Next Routine] [List of Routines] NAME: WSET The WSET procedure selects the current window. Most IDL graphics routines do not explicitly require the IDL window to be specified. Instead, they use the window known as the current window. The window index number of the current window is contained in the read-only system variable !D.WINDOW. WSET only works with devices that have windowing systems. Syntax WSET [, Window_Index] Arguments Window_Index This argument specifies the window index of the window to be made current. If this argument is not specified, a default of 0 is used. If you set Window_Index equal to -1, IDL will try to locate an existing window to make current, ignoring any managed draw widgets that may exist. If there is no window to make current, WSET changes the value of the WINDOW field of the !D system variable to -1, indicating that there are no current windows. If there are no existing IDL windows, and you call WSET without the Window_Index argument or with a Window_Index of 0, a new window with the index 0 is opened. Calling WSET with a Window_Index for a window that does not exist, except for window 0, results in a "Window is closed and unavailable" error message. Examples Create IDL windows 1 and 2 by entering: WINDOW, 1 & WINDOW, 2 Set the current window to window 1 and display an image by entering: WSET, 1 & TVSCL, DIST(100) Set the current window to window 2 and display an image by entering: WSET, 2 & TVSCL, DIST(100) See Also WDELETE, WINDOW, WSHOW WSHOW [Previous Routine] [Next Routine] [List of Routines] NAME: WSHOW The WSHOW procedure exposes or hides the designated window. Syntax WSHOW [, Window_Index [, Show]] [, /ICONIC] Arguments Window_Index The window index of the window to be hidden or exposed. If this argument is not specified, the current window is assumed. If this index is the window ID of a draw widget, the widget base associated with that drawable is brought to the front of the screen. Show Set Show to 0 to hide the window. Omit this argument or set it to 1 to expose the window. Keywords ICONIC Set this keyword to iconify the window. Set ICONIC to 0 to de-iconify the window. Under windowing systems, iconification is the task of the window manager, and client applications such as IDL have no direct control over it. The ICONIC keyword serves as a hint to the window manager, which is free to iconify the window or ignore the request as it sees fit. Example To bring IDL window number 0 to the front, enter: WSHOW, 0 See Also WDELETE, WINDOW, WSET WTN [Previous Routine] [Next Routine] [List of Routines] NAME: WTN The WTN function returns a multi-dimensional discrete wavelet transform of the input array A. The transform is based on a Daubechies wavelet filter. WTN is based on the routine wtn described in section 13.10 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press, and is used by permission. Syntax Result = WTN( A, Coef [, /COLUMN] [, /DOUBLE] [, /INVERSE] [, /OVERWRITE] ) Arguments A The input vector or array. The dimensions of A must all be powers of 2. Coef An integer that specifies the number of wavelet filter coefficients. The allowed values are 4, 12, or 20. When Coef is 4, the daub4() function (see Numerical Recipes, section 13.10) is used. When Coef is 12 or 20, pwt() is called, preceded by pwtset() (see Numerical Recipes, section 13.10). Keywords COLUMN Set this keyword if the input array A is in column-major format (composed of column vectors) rather than in row-major format (composed of row vectors). DOUBLE Set this keyword to force the computation to be done in double-precision arithmetic. INVERSE If the INVERSE keyword is set, the inverse transform is computed. By default, WTN performs the forward wavelet transform. OVERWRITE Set the OVERWRITE keyword to perform the transform "in place." The result overwrites the original contents of the array. Example This example demonstrates the use of IDL's discrete wavelet transform and sparse array storage format to compress and store an 8-bit gray-scale digital image. First, an image selected from the people.dat data file is transformed into its wavelet representation and written to a separate data file using the WRITEU procedure. Next, the transformed image is converted, using the SPRSIN function, to row- indexed sparse storage format retaining only elements with an absolute magnitude greater than or equal to a specified threshold. The sparse image is written to a data file using the WRITE_SPR procedure. Finally, the transformed image is reconstructed from the storage file and displayed alongside the original. ; Begin by choosing the number of wavelet coefficients to use and a ; threshold value: coeffs = 12 & thres = 10.0 ; Open the people.dat data file, read an image using associated ; variables, and close the file: OPENR, 1, FILEPATH('people.dat', SUBDIR = ['examples','data']) images = assoc(1, bytarr(192, 192)) image_1 = images[0] close, 1 ; Expand the image to the nearest power of two using cubic ; convolution, and transform the image into its wavelet ; representation using the WTN function: pwr = 256 image_1 = CONGRID(image_1, pwr, pwr, /CUBIC) wtn_image = WTN(image_1, coeffs) ; Write the image to a file using the WRITEU procedure and check ; the size of the file (in bytes) using the FSTAT function: OPENW, 1, 'original.dat' WRITEU, 1, wtn_image status = FSTAT(1) CLOSE, 1 PRINT, 'Size of the file is ', status.size, ' bytes.' ; Now, we convert the wavelet representation of the image to a ; row-indexed sparse storage format using the SPRSIN function, ; write the data to a file using the WRITE_SPR procedure, and check ; the size of the "compressed" file: sprs_image = SPRSIN(wtn_image, THRES = thres) WRITE_SPR, sprs_image, 'sparse.dat' OPENR, 1, 'sparse.dat' status = FSTAT(1) CLOSE, 1 PRINT, 'Size of the compressed file is ', status.size, ' bytes.' ; Determine the number of elements (as a percentage of total ; elements) whose absolute magnitude is less than the specified ; threshold. These elements are not retained in the row-indexed ; sparse storage format: PRINT, 'Percentage of elements under threshold: ',$ 100.*N_ELEMENTS(WHERE(ABS(wtn_image) LT thres, $ count)) / N_ELEMENTS(image_1) ; Next, read the row-indexed sparse data back from the file ; sparse.dat using the READ_SPR function and reconstruct the ; image from the non-zero data using the FULSTR function: sprs_image = READ_SPR('sparse.dat') wtn_image = FULSTR(sprs_image) ; Apply the inverse wavelet transform to the image: image_2 = WTN(wtn_image, COEFFS, /INVERSE) ; Calculate and print the amount of data used in reconstruction of ; the image: PRINT, 'The image on the right is reconstructed from:', $ 100.0 - (100.* count/N_ELEMENTS(image_1)),$ '% of original image data.' ; Finally, display the original and reconstructed images side by ; side: WINDOW, 1, XSIZE = pwr*2, YSIZE = pwr, $ TITLE = 'Wavelet Image Compression and File I/O' TV, image_1, 0, 0 TV, image_2, pwr - 1, 0 IDL Output Size of the file is 262144 bytes. Size of the compressed file is 69600 bytes. Percentage of elements under threshold: 87.0331 The image on the right is reconstructed from: 12.9669% of original image data. The sparse array contains only 13% of the elements contained in the original array. The following figure is created from this example. The image on the left is the original 256 by 256 image. The image on the right was compressed by the above process and was reconstructed from 13% of the original data. The size of the compressed image's data file is 26.6% of the size of the original image's data file. Note that due to limitations in the printing process, differences between the images may not be as evident as they would be on a high-resolution printer or monitor. Figure 32: Original image (left) and image reconstructed from 13% of the data (right). See Also FFT XBM_EDIT [Previous Routine] [Next Routine] [List of Routines] NAME: XBM_EDIT The XBM_EDIT procedure is a utility for creating and editing icons for use with IDL widgets as bitmap labels for widget buttons. The icons created with XBM_EDIT can be saved in two different file formats. IDL "array definition files" are text files that can be inserted into IDL programs. "Bitmap array files" are data files that can be read into IDL programs. Bitmap array files should be used temporarily until the final icon design is determined and then they can be saved as IDL array definitions for inclusion in the final widget code. This routine does not check the file types of the files being read and assumes that they are of the correct size and type for reading. XBM_EDIT maintains its state in a common block so it is restricted to one working copy at a time. This routine is written in the IDL language. Its source code can be found in the file xbm_edit.pro in the lib/utilities subdirectory of the IDL distribution. Syntax XBM_EDIT [, /BLOCK] [, FILENAME=string] [, GROUP=widget_id] [, XSIZE=pixels] [, YSIZE=pixels] Keywords BLOCK Set this keyword to have XMANAGER block when this application is registered. By default, BLOCK is set equal to zero, providing access to the command line if active command line processing is available. Note that setting BLOCK=1 will cause all widget applications to block, not just this application. For more information, see the documentation for the NO_BLOCK keyword to XMANAGER. Note Only the outermost call to XMANAGER can block. Therefore, to have XBM_EDIT block, any earlier calls to XMANAGER must have been called with the NO_BLOCK keyword. See the documentation for the NO_BLOCK keyword to XMANAGER for an example. FILENAME Set this keyword to a scalar string that contains the filename to be used for the new icon. If this argument is not specified, the name "idl.bm" is used. The filename can be changed in XBM_EDIT by editing the "Filename" field before selecting a file option. GROUP The widget ID of the widget that calls XBM_EDIT. When this ID is specified, the death of the caller results in the death of XBM_EDIT. XSIZE The number of pixels across the bitmap is in the horizontal direction. The default value is 16 pixels. YSIZE The number of pixels across the bitmap is in the vertical direction. The default value is 16 pixels. See Also WIDGET_BUTTON XDISPLAYFILE [Previous Routine] [Next Routine] [List of Routines] NAME: XDISPLAYFILE The XDISPLAYFILE procedure is a utility for displaying ASCII text files using a widget interface. This routine is written in the IDL language. Its source code can be found in the file xdisplayfile.pro in the lib/utilities subdirectory of the IDL distribution. Syntax XDISPLAYFILE, Filename [, /BLOCK] [, DONE_BUTTON=string] [, /EDITABLE] [, FONT=string] [, GROUP=widget_id] [, HEIGHT=lines] [, /MODAL] [, TEXT=string or string array] [, TITLE=string] [, WIDTH=characters] [, WTEXT=variable] Arguments Filename A scalar string that contains the filename of the file to display. Filename can include a path to that file. Keywords BLOCK Set this keyword to have XMANAGER block when this application is registered. By default, BLOCK is set equal to zero, providing access to the command line if active command line processing is available. Note that setting BLOCK=1 will cause all widget applications to block, not just this application. For more information, see the documentation for the NO_BLOCK keyword to XMANAGER. Note Only the outermost call to XMANAGER can block. Therefore, to have XDISPLAYFILE block, any earlier calls to XMANAGER must have been called with the NO_BLOCK keyword. See the documentation for the NO_BLOCK keyword to XMANAGER for an example. DONE_BUTTON Set this keyword to a string containing the text to use for the Done button label. If omitted, the text "Done with " is used. EDITABLE Set this keyword to allow modifications to the text displayed in XDISPLAYFILE. Setting this keyword also adds a "Save" button in addition to the Done button. FONT A string containing the name of the font to use. The font specified is a device font (an X Windows font on Motif systems; a TrueType or PostScript font on Windows or Macintosh systems). See "About Device Fonts" on page 2482 for details on specifying names for device fonts. If this keyword is omitted, the default font is used. GROUP The widget ID of the widget that calls XDISPLAYFILE. If this keyword is specified, the death of the group leader results in the death of XDISPLAYFILE. HEIGHT The number of text lines that the widget should display at one time. If this keyword is not specified, 24 lines is the default. MODAL Set this keyword to create the XDISPLAYFILE dialog as a modal dialog. Setting the MODAL keyword allows you to call XDISPLAYFILE from another modal dialog. TEXT A string or string array to be displayed in the widget instead of the contents of a file. If this keyword is present, the Filename input argument is ignored (but is still required). String arrays are displayed one element per line. TITLE A string to use as the widget title rather than the file name or "XDisplayFile". WIDTH The width of the widget display in characters. If this keyword is not specified, 80 characters is the default. WTEXT Set this keyword to a named variable that will contain the widget ID of the text widget. This allows setting text selections and cursor positions programmatically. For example, the following code opens the XDISPLAYFILE widget and selects the first 10 characters of the file displayed in the text widget: XDISPLAYFILE, 'myfile.txt', /EDITABLE, WTEXT=w WIDGET_CONTROL, w, SET_TEXT_SELECT=[0, 10] See Also PRINT/PRINTF, XYOUTS XDXF [Previous Routine] [Next Routine] [List of Routines] NAME: XDXF The XDXF procedure is a utility for displaying and interactively manipulating DXF objects. Syntax XDXF [, Filename] [, /BLOCK] [, GROUP=widget_id] [, /MODAL] [, SCALE=value] [, /TEST] [keywords to XOBJVIEW] Arguments Filename A string specifying the name of the DXF file to display. If this argument is not specified, a file selection dialog is opened. Keywords XDXF accepts the keywords to XOBJVIEW. In addition, XDXF supports the following keywords: BLOCK Set this keyword to have XMANAGER block when this application is registered. By default, BLOCK is set equal to zero, providing access to the command line if active command line processing is available. Note that setting the BLOCK keyword causes all widget applications to block, not just this application. For more information, see the documentation for the NO_BLOCK keyword to XMANAGER. Note Only the outermost call to XMANAGER can block. Therefore, to have XDXF block, any earlier calls to XMANAGER must have been called with the NO_BLOCK keyword. See the documentation for the NO_BLOCK keyword to XMANAGER for an example. GROUP The widget ID of the widget that calls XDXF. When this ID is specified, the death of the caller results in the death of XDXF. MODAL Set this keyword to block processing of events from other widgets until the user quits XDXF. A group leader must be specified (via the GROUP keyword) for the MODAL keyword to have any effect. By default, XDXF does not block event processing. SCALE Set this keyword to the zoom factor for the initial view. The default is 1/SQRT(3). This default value provides the largest possible view of the object, while ensuring that no portion of the object will be clipped by the XDXF window, regardless of the object's orientation. TEST If this keyword is set, the file heart.dxf in the IDL distribution is automatically opened in XDXF. Using XDXF XDXF displays a resizeable top-level base with a menu and draw widget used to display and manipulate the orientation of a DXF object. Figure 33: The XDXF Utility XDXF also displays a dialog that contains block and layer information and allows the user to turn on and off the display of individual layers. Figure 34: The XDXF Information Dialog The XDXF Toolbar The XDXF toolbar contains the following buttons: Reset: Resets rotation, scaling, and panning. Rotate: Click the left mouse button on the object and drag to rotate. Pan: Click the left mouse button on the object and drag to pan. Zoom: Click the left mouse button on the object and drag to zoom in or out. Select: Click on the object. The name of the selected object is displayed, if the object has a name, otherwise its class is displayed. The XDXF Information Dialog The XDXF Information dialog displays information about the blocks and layers contained in the currently displayed object, and allows you to turn on and off the display of each layer. To show or hide layers in the DXF object, select the layer from the list of layers on the left of the dialog, and click the Show or Hide button. Alternatively, you can click in the "Vis" field for the desired layer. To show or hide all layers, click the Show All or Hide All buttons. Example Display the file heart.dxf, contained in the IDL distribution: XDXF, FILEPATH('heart.dxf', $ SUBDIR=['examples', 'data']) See Also IDLffDXF XFONT [Previous Routine] [Next Routine] [List of Routines] NAME: XFONT The XFONT function is a utility that creates a modal widget for selecting and viewing an X Windows font. The function returns a string containing the name of the last selected font. If no font is selected, or the "Cancel" button is clicked, a null string is returned. Calling XFONT resets the current X Windows font. This routine is written in the IDL language. Its source code can be found in the file xfont.pro in the lib/utilities subdirectory of the IDL distribution. Syntax Result = XFONT( [, GROUP=widget_id] [, /PRESERVE_FONT_INFO] ) Keywords GROUP The widget ID of the widget that calls XFONT. When this ID is specified, the death of the caller results in the death of XFONT. PRESERVE_FONT_INFO Set this keyword to make XFONT save the server font directory in common blocks so that subsequent calls to XFONT start-up much faster. If this keyword is not set, the common block is cleaned. See Also EFONT, SHOWFONT XINTERANIMATE [Previous Routine] [Next Routine] [List of Routines] NAME: XINTERANIMATE The XINTERANIMATE procedure is a utility for displaying an animated sequence of images using off-screen pixmaps or memory buffers. The speed and direction of the display can be adjusted using the widget interface. MPEG animation files can be created either programmatically using keywords to open and save a file, or interactively using the widget interface. Note that the MPEG standard does not allow movies with odd numbers of pixels to be created. Note MPEG support in IDL requires a special license. For more information, contact your Research Systems sales representative or technical support. Note Only a single copy of XINTERANIMATE can run at a time. If you need to run multiple instances of the animation widget concurrently, use the CW_ANIMATE compound widget. This routine is written in the IDL language. Its source code can be found in the file xinteranimate.pro in the lib/utilities subdirectory of the IDL distribution. Using XINTERANIMATE Displaying an animated series of images using XINTERANIMATE requires at least three calls to the routine: one to initialize the animation widget, one to load images, and one to display the images. When initialized using the SET keyword, XINTERANIMATE creates an approximately square pixmap or memory buffer, large enough to contain the requested number of frames of the requested size. Images are loaded using the IMAGE and FRAME keywords. Finally, images are displayed by copying them from the pixmap or memory buffer to the visible draw widget. See CW_ANIMATE for a description of the widget interface controls used by XINTERANIMATE. Syntax XINTERANIMATE [, Rate] Keywords for initialization: [, SET=[sizex, sizey, nframes]] [, /BLOCK] [, /CYCLE] [, GROUP=widget_id] [, /MODAL] [, MPEG_BITRATE=value] [, MPEG_IFRAME_GAP=integer value] [, MPEG_MOTION_VEC_LENGTH={1 | 2 | 3}] [, /MPEG_OPEN, MPEG_FILENAME=string] [ MPEG_QUALITY=value{0 to 100}] [, /SHOWLOAD] [, /TRACK] [, TITLE=string] Keywords for loading images: [, FRAME=value{0 to (nframes- 1)}[, IMAGE=value]] [, /ORDER] [, WINDOW=[window_num [, x0, y0, sx, sy]]] Keywords for running animations: [, /CLOSE] [, /KEEP_PIXMAPS] [, /MPEG_CLOSE] [, XOFFSET=pixels] [, YOFFSET=pixels] Arguments Rate A value between 0 and 100 that represents the speed of the animation as a percentage of the maximum display rate. The fastest animation is with a value of 100 and the slowest is with a value of 0. The default animation rate is 100. The animation must be initialized using the SET keyword before calling XINTERANIMATE with a rate value. Keywords: Initialization The following keywords are used to initialize the animation display. The SET keyword must be provided. Other keywords described in this section are optional; note that they work only when SET is specified. SET Set this keyword to a three-element vector [Sizex, Sizey, Nframes] to initialize XINTERANIMATE. Sizex and Sizey represent the width and height of the images to be displayed, in pixels. Nframes is the number of frames in the animation sequence. Note that Nframes must be at least 2 frames. BLOCK Set this keyword to have XMANAGER block when this application is registered. By default, BLOCK is set equal to zero, providing access to the command line if active command line processing is available. Note that setting BLOCK=1 will cause all widget applications to block, not just this application. For more information, see the documentation for the NO_BLOCK keyword to XMANAGER. Note Only the outermost call to XMANAGER can block. Therefore, to have XINTERANIMATE block, any earlier calls to XMANAGER must have been called with the NO_BLOCK keyword. See the documentation for the NO_BLOCK keyword to XMANAGER for an example. CYCLE Normally, frames are displayed going either forward or backwards. If the CYCLE keyword is set, the animation reverses direction after the last frame in either direction is displayed. GROUP Set this keyword to the widget ID of the widget that calls XINTERANIMATE. When GROUP is specified, the death of the calling widget results in the death of XINTERANIMATE. MODAL Set this keyword to block processing of events from other widgets until the user quits XINTERANIMATE. A group leader must be specified (via the GROUP keyword) for the MODAL keyword to have any effect. By default, XINTERANIMATE does not block event processing. MPEG_BITRATE Set this keyword to a double-precision value to specify the MPEG movie bit rate. Higher bit rates will create higher quality MPEGs but will increase file size. The following table describes the valid values: MPEG Version Range MPEG 1 0.1 to 104857200.0 MPEG 2 0.1 to 429496729200.0 Table 99: BITRATE Value Range If you do not set this keyword, IDL computes the MPEG_BITRATE value based upon the value you have specified for the MPEG_QUALITY keyword. Note Only use the MPEG_BITRATE keyword if changing the MPEG_QUALITY keyword value does not produce the desired results. It is highly recommended to set the MPEG_BITRATE to at least several times the frame rate to avoid unusable MPEG files or file generation errors. MPEG_FILENAME Set this keyword equal to a string specifying the name of the MPEG file. If no file name is specified, the default value (idl.mpg) is used. MPEG_IFRAME_GAP Set this keyword to a positive integer value that specifies the number of frames between I frames to be created in the MPEG file. I frames are full-quality image frames that may have a number of predicted or interpolated frames between them. If you do not specify this keyword, IDL computes the MPEG_IFRAME_GAP value based upon the value you have specified for the MPEG_QUALITY keyword. Note Only use the MPEG_IFRAME_GAP keyword if changing the MPEG_QUALITY keyword value does not produce the desired results. MPEG_MOTION_VEC_LENGTH Set this keyword to an integer value specifying the length of the motion vectors to be used to generate predictive frames. Valid values include: * 1 = Small motion vectors. * 2 = Medium motion vectors. * 3 = Large motion vectors. If you do not set this keyword, IDL computes the MPEG_MOTION_VEC_LENGTH value based upon the value you have specified for the MPEG_QUALITY keyword. Note Only use the MPEG_MOTION_VEC_LENGTH keyword if changing the MPEG_QUALITY value does not produce the desired results. MPEG_OPEN Set this keyword to open an MPEG file. MPEG_QUALITY Set this keyword to an integer value between 0 (low quality) and 100 (high quality) inclusive to specify the quality at which the MPEG stream is to be stored. Higher quality values result in lower rates of time compression and less motion prediction which provide higher quality MPEGs but with substantially larger file size. Lower quality factors may result in longer MPEG generation times. The default is 50. Note Since MPEG uses JPEG (lossy) compression, the original picture quality can't be reproduced even when setting QUALITY to its highest setting. SHOWLOAD Set this keyword to display each frame and update the frame slider as frames are loaded. TRACK Set this keyword to cause the frame slider to track the current frame when the animation is in progress. The default is not to track. TITLE Use this keyword to specify a string to be used as the title of the animation widget. If TITLE is not specified, the title is set to "XInterAnimate." Keywords: Loading Images The following keywords are used to load images into the animation display. They have no effect when initializing or running animations. FRAME Use this keyword to specify the frame number when loading frames. FRAME must be set to a number in the range 0 to Nframes-1. IMAGE Use this keyword to specify a single image to be loaded at the animation position specified by the FRAME keyword. (FRAME must also be specified.) ORDER Set this keyword to display images from the top down instead of the default bottom up. WINDOW When this keyword is specified, an image is copied from an existing window to the animation pixmap or memory buffer. (When using some windowing systems, using this keyword is much faster than reading from the display and then calling XINTERANIMATE with a 2D array.) The value of this parameter is either an IDL window number (in which case the entire window is copied), or a vector containing the window index and the rectangular bounds of the area to be copied. For example: WINDOW = [Window_Number, X0, Y0, Sx, Sy] Keywords: Running Animations The following keywords are used when running the animation. They have no effect when initializing the animation or loading images. CLOSE Set this keyword to delete the offscreen pixmaps or buffers and the animation widget itself. This also takes place automatically when the user presses the "Done With Animation" button or closes the window with the window manager. KEEP_PIXMAPS If this keyword is set, XINTERANIMATE will not destroy the animation pixmaps or buffers when it is killed. Calling XINTERANIMATE again without going through the SET and LOAD steps will play the same animation without the overhead of creating the pixmaps. MPEG_CLOSE Set this keyword to close and save the MPEG file. This keyword has no effect if MPEG_OPEN was not used during initialization. XOFFSET Use this keyword to specify the horizontal offset, in pixels from the left of the frame, of the image in the destination window. YOFFSET Use this keyword to specify the vertical offset, in pixels from the bottom of the frame, of the image in the destination window. Example Enter the following commands to open the file ABNORM.DAT (a series of images of a human heart) and animate the images it contains using XINTERANIMATE. For a more detailed example of using XINTERANIMATE, see "Animation with XINTERANIMATE" in Chapter 11 of Getting Started with IDL. OPENR, unit, FILEPATH('abnorm.dat', SUBDIR=['examples','data']), $ /GET_LUN H = BYTARR(64, 64, 16) READU, unit, H CLOSE, unit ; Read the images into variable H: H = REBIN(H, 128, 128, 16) ; Initialize XINTERANIMATE: XINTERANIMATE, SET=[128, 128, 16], /SHOWLOAD ; Load the images into XINTERANIMATE: FOR I=0,15 DO XINTERANIMATE, FRAME = I, IMAGE = H[*,*,I] ; Play the animation: XINTERANIMATE, /KEEP_PIXMAPS Note Since the KEEP_PIXMAPS keyword was supplied, the same animation can be replayed (after the animation widget has been destroyed) with the single command XINTERANIMATE. See Also CW_ANIMATE XLOADCT [Previous Routine] [Next Routine] [List of Routines] NAME: XLOADCT The XLOADCT procedure is a utility that provides a graphical widget interface to the LOADCT procedure. XLOADCT displays the current colortable and shows a list of available predefined color tables. Clicking on the name of a color table causes that color table to be loaded in true color decomposed visual. Many other options, such as Gamma correction, stretching, and transfer functions can also be applied to the colortable. This routine is written in the IDL language. Its source code can be found in the file xloadct.pro in the lib/utilities subdirectory of the IDL distribution. Syntax XLOADCT [, /BLOCK] [, BOTTOM=value] [, FILE=string] [, GROUP=widget_id] [, /MODAL] [, NCOLORS=value] [, /SILENT] [, UPDATECALLBACK=`procedure_name' [, UPDATECBDATA=value]] [, /USE_CURENT] Keywords BLOCK Set this keyword to have XMANAGER block when this application is registered. By default, BLOCK is set equal to zero, providing access to the command line if active command line processing is available. Note that setting BLOCK=1 will cause all widget applications to block, not just this application. For more information, see the documentation for the NO_BLOCK keyword to XMANAGER. Note Only the outermost call to XMANAGER can block. Therefore, to have XLOADCT block, any earlier calls to XMANAGER must have been called with the NO_BLOCK keyword. See the documentation for the NO_BLOCK keyword to XMANAGER for an example. BOTTOM The first color index to use. XLOADCT will use color indices from BOTTOM to BOTTOM+NCOLORS-1. The default is BOTTOM=0. FILE Set this keyword to a string representing the name of the file to be used instead of the file colors1.tbl in the IDL directory. GROUP The widget ID of the widget that calls XLOADCT. When this ID is specified, a death of the caller results in a death of XLOADCT. MODAL Set this keyword to block processing of events from other widgets until the user quits XLOADCT. A group leader must be specified (via the GROUP keyword) for the MODAL keyword to have any effect. By default, XLOADCT does not block event processing. NCOLORS The number of colors to use. Use color indices from 0 to the smaller of !D.TABLE_SIZE-1 and NCOLORS-1. The default is all available colors (!D.TABLE_SIZE). SILENT Normally, no informational message is printed when a color map is loaded. If this keyword is set to zero, the message is printed. UPDATECALLBACK Set this keyword to a string containing the name of a user-supplied procedure that will be called when the color table is updated by XLOADCT. The procedure may optionally accept a keyword called DATA, which will be automatically set to the value specified by the optional UPDATECBDATA keyword. UPDATECBDATA Set this keyword to a value of any type. It will be passed via the DATA keyword to the user-supplied procedure specified via the UPDATECALLBACK keyword, if any. If the UPDATECBDATA keyword is not set the value accepted by the DATA keyword to the procedure specified by UPDATECALLBACK will be undefined. USE_CURRENT Set this keyword to use the current color tables, regardless of the contents of the COLORS common block. See Also LOADCT, XPALETTE, TVLCT XMANAGER [Previous Routine] [Next Routine] [List of Routines] NAME: XMANAGER The XMANAGER procedure provides the main event loop and management for widgets created using IDL. Calling XMANAGER "registers" a widget program with the XMANAGER event handler. XMANAGER takes control of event processing until all widgets have been destroyed. Beginning with IDL version 5.0, IDL supports an active command line that allows the IDL command input line to continue accepting input while properly configured widget applications are running. See "A Note About Blocking in XMANAGER" on page 1725 for a more detailed explanation of the active command line. This routine is written in the IDL language. Its source code can be found in the file xmanager.pro in the lib subdirectory of the IDL distribution. Syntax XMANAGER [, Name, ID] [, /CATCH] [, CLEANUP=string] [, EVENT_HANDLER=`procedure_name'] [, GROUP_LEADER=widget_id] [, /JUST_REG] [, /NO_BLOCK] Arguments Name A string that contains the name of the routine that creates the widget (i.e., the name of the widget creation routine that is calling XMANAGER). Note The Name argument is stored in a COMMON block for use by the XREGISTERED routine. The stored name is case-sensitive. ID The widget ID of the new widget's top-level base. Keywords BACKGROUND This keyword is obsolete and is included in XMANAGER for compatibility with existing code only. Its functionality has been replaced by the TIMER keyword to the WIDGET_CONTROL procedure. CATCH Set this keyword to cause XMANAGER to catch any errors, using the CATCH procedure, when dispatching widget events. If the CATCH keyword is set equal to zero, execution halts and IDL provides traceback information when an error is detected. This keyword is set by default (errors are caught and processing continues). Do not specify either the Name or ID argument to XMANAGER when specifying the CATCH keyword (they are ignored). CATCH acts as a switch to turn error catching on and off for all applications managed by XMANAGER. When CATCH is specified, XMANAGER changes its error-catching behavior and returns immediately, without taking any other action. Note Beginning with IDL version 5.0, the default behavior of XMANAGER is to catch errors and continue processing events. In versions of IDL prior to version 5.0, XMANAGER halted when an error was detected. This change in default behavior was necessary in order to allow multiple widget applications (all being managed by XMANAGER) to coexist peacefully. When CATCH is set equal to zero, (the old behavior), any error halts XMANAGER, and thus halts event processing for all running widget applications. Note also that CATCH is only effective if XMANAGER is blocking to dispatch errors. If event dispatching for an active IDL command line is in use, the CATCH keyword has no effect. The CATCH=0 setting (errors are not caught and processing halts in XMANAGER when an error is detected) is intended as a debugging aid. Finished programs should not set CATCH=0. CLEANUP Set this keyword to a string that contains the name of the routine to be called when the widget dies. If not specified, no routine is called. The cleanup routine must accept one parameter which is the widget ID of the dying widget. The routine specified by CLEANUP becomes the KILL_NOTIFY routine for the application, overriding any cleanup routines that may have been set previously via the KILL_NOTIFY keyword to WIDGET_CONTROL. EVENT_HANDLER Set this keyword to a string that contains the name of a routine to be called when a widget event occurs in the widget program being registered. If this keyword is not supplied, XMANAGER will construct a default name by adding the "_event" suffix to the Name argument. See the example below for a more detailed explanation. GROUP_LEADER The widget ID of the group leader for the widget being processed. When the leader dies either by the users actions or some other routine, all widgets that have that leader will also die. For example, a widget that views a help file for a demo widget would have that demo widget as its leader. When the help widget is registered, it sets the keyword GROUP_LEADER to the widget ID of the demo widget. If the demo widget were destroyed, the help widget led by it would be killed by the XMANAGER. JUST_REG Set this keyword to indicate that XMANAGER should just register the widget and return immediately. This keyword is useful if you want to register a group of related top-level widgets before beginning event processing and either: * your command-processing front-end does not support an active command line, or * one or more of the registered widgets requests that XMANAGER block event processing. (Note that in this case a later call to XMANAGER without the JUST_REG keyword is necessary to begin blocking.) (See "A Note About Blocking in XMANAGER" on page 1725 for further discussion of the active command line.) Warning JUST_REG is not the same as NO_BLOCK. See "JUST_REG vs. NO_BLOCK" on page 1725 for additional details. NO_BLOCK Set this keyword to tell XMANAGER that the registering client does not require XMANAGER to block if active command line event processing is available. If active command line event processing is available and every current XMANAGER client specifies NO_BLOCK, then XMANAGER will not block and the user will have access to the command line while widget applications are running. Note NO_BLOCK is ignored by IDL Runtime. If a main procedure uses XMANAGER with the NO_BLOCK keyword set, IDL Runtime defers subsequent processing of the commands following the XMANAGER call until the widget associated with the call to XMANAGER is destroyed. It is important to understand the result of making nested calls to XMANAGER. XMANAGER can only block event processing for one client at a time. In applications involving multiple calls to XMANAGER (either directly or via calls to other routines that call XMANAGER, such as XLOADCT), blocking occurs only for the outermost call to XMANAGER, unless XMANAGER is told not to block in that call. If an application contains two calls to XMANAGER, the second call cannot block unless the first call sets the NO_BLOCK keyword. If an application contains a call to XMANAGER, followed by a call to XLOADCT, XLOADCT will not block unless the NO_BLOCK keyword was set in the call to XMANAGER (and the BLOCK keyword to XLOADCT is set). Consider the following example: PRO blocking_example_event, event ; The following call blocks only if the NO_BLOCK keyword to ; XMANAGER is set: XLOADCT, /BLOCK END PRO blocking_example base=WIDGET_BASE(/COLUMN) button1=WIDGET_BUTTON(base,VALUE='Run XLOADCT') WIDGET_CONTROL,base, /REALIZE XMANAGER,'blocking_example', base, /NO_BLOCK END If the NO_BLOCK keyword to XMANAGER was not set in the above example, XLOADCT would not block, even though the BLOCK keyword was set. Setting the NO_BLOCK keyword to XMANAGER prevents XMANAGER from blocking, thereby allowing the subsequent call to XMANAGER (via XLOADCT) to block. Warning NO_BLOCK is not the same as JUST_REG. See "JUST_REG vs. NO_BLOCK" on page 1725 for additional details. Warning Although this routine is written in the IDL language, it may change in the future in its internal implementation. For future upgradability, it is best not to modify or even worry about what this routine does internally. A Note About Blocking in XMANAGER Beginning with IDL version 5.0, most versions of IDL's command-processing front- end are able to support an active command line while running properly constructed widget applications. What this means is that-provided the widget application is properly configured-the IDL command input line is available for input while a widget application is running and widget events are being processed. There are currently 5 separate IDL command-processing front-end implementations: * Apple Macintosh Integrated Development Environment (IDLDE) * Microsoft Windows IDLDE * Motif IDLDE (UNIX and VMS) * UNIX plain tty * VMS plain tty All of these front-ends are able to process widget events except for the VMS plain tty. VMS users can still enjoy an active command line by using the IDLDE interface. If the command-processing front-end can process widget events (that is, if the front- end is not the VMS plain tty), it is still necessary for widget applications to be well- behaved with respect to blocking widget event processing. Since in most cases XMANAGER is used to handle widget event processing, this means that in order for the command line to remain active, all widget applications must be run with the NO_BLOCK keyword to XMANAGER set. (Note that since NO_BLOCK is not the default, it is quite likely that some application will block.) If a single application runs in blocking mode, the command line will be inaccessible until the blocking application exits. When a blocking application exits, the IDL command line will once again become active. JUST_REG vs. NO_BLOCK Although their names imply a similar function, the JUST_REG and NO_BLOCK keywords perform very different services. It is important to understand what they do and how they differ. The JUST_REG keyword tells XMANAGER that it should simply register a client and then return immediately. The result is that the client becomes known to XMANAGER, and that future calls to XMANAGER will take this client into account. Therefore, JUST_REG only controls how the registering call to XMANAGER should behave. The client can still be registered as requiring XMANAGER to block by setting NO_BLOCK=0. In this case, future calls to XMANAGER will block. Note JUST_REG is useful in situations where you suspect blocking might occur-if the active command line is not supported and you wish to keep it active before beginning event processing, or if blocking will be requested at a later time. If no blocking will occur or if the blocking behavior is useful, it is not necessary to use JUST_REG. The NO_BLOCK keyword tells XMANAGER that the registered client does not require XMANAGER to block if the command-processing front-end is able to support active command line event processing. XMANAGER remembers this attribute of the client until the client exits, even after the call to XMANAGER that registered the client returns. NO_BLOCK is just a "vote" on how XMANAGER should behave-the final decision is made by XMANAGER by considering the NO_BLOCK attributes of all of its current clients as well as the ability of the command-processing front-end in use to support the active command line. Blocking vs. Non-blocking Applications The issue of blocking in XMANAGER requires some explanation. IDL widget events are not processed until the WIDGET_EVENT function is called to handle them. Otherwise, they are queued by IDL indefinitely. Knowing how and when to call WIDGET_EVENT is the primary service provided by XMANAGER. There are two ways blocking is typically handled: 1. The first call to XMANAGER processes events by calling WIDGET_EVENT as necessary until no managed widgets remain on the screen. This is referred to as "blocking" because XMANAGER does not return to the caller until it is done, and the IDL command line is not available. 2. XMANAGER does not block, and instead, the part of IDL that reads command input also watches for widget events and calls WIDGET_EVENT as necessary while also reading command input. This is referred to as "non-blocking" or "active command line" mode. XMANAGER will block unless all of the following conditions are met: * The command-processing front-end is able to process widget events (that is, the front-end is not the VMS plain tty). * All registered widget applications have the NO_BLOCK keyword to XMANAGER set. * No modal dialogs are displayed. (Modal dialogs always block until dismissed.) In general, we suggest that new widget applications be written with XMANAGER blocking disabled (that is, with the NO_BLOCK keyword set), unless the widget application will be run on IDL Runtime. Note NO_BLOCK is ignored by IDL Runtime. If a main procedure uses XMANAGER with the NO_BLOCK keyword set, IDL Runtime defers subsequent processing of the commands following the XMANAGER call until the widget associated with the call to XMANAGER is destroyed. Since a widget application that does block event processing for itself will block event processing for all other widget applications (and the IDL command line) as well, we suggest that older widget applications be upgraded to take advantage of the new, non- blocking behavior by adding the NO_BLOCK keyword to most calls to XMANAGER. Example The following code creates a widget named EXAMPLE that is just a base widget with a "Done" button and registers it with the XMANAGER. Widgets being registered with the XMANAGER must provide at least two routines. The first routine creates the widget and registers it with the manager and the second routine processes the events that occur within that widget. An example widget is supplied below that uses only two routines. A number of other "Simple Widget Examples", can be viewed by entering WEXMASTER at the IDL prompt. These simple programs demonstrate many aspects of widget programming. The following lines of code would be saved in a single file, named example.pro: ; Begin the event handler routine for the EXAMPLE widget: PRO example_event, ev ; The uservalue is retrieved from a widget when an event occurs: WIDGET_CONTROL, ev.id, GET_UVALUE = uv ; If the event occurred in the Done button, kill the widget ; example: if (uv eq 'DONE') THEN WIDGET_CONTROL, ev.top, /DESTROY ; End of the event handler part: END ; This is the routine that creates the widget and registers it with ; the XMANAGER: PRO example ; Create the top-level base for the widget: base = WIDGET_BASE(TITLE='Example') ; Create the Done button and set its uservalue to "DONE": done = WIDGET_BUTTON(base, VALUE = 'Done', UVALUE = 'DONE') ; Realize the widget (i.e., display it on screen): WIDGET_CONTROL, base, /REALIZE ; Register the widget with the XMANAGER, leaving the IDL command ; line active: XMANAGER, 'example', base, /NO_BLOCK ; End of the widget creation part: END First the event handler routine is listed. The handler routine has the same name as the main routine with the characters "_event" added. If you would like to use another event handler name, you would need to pass its name to XMANAGER using the EVENT_HANDLER keyword. Notice that the event routine is listed before the main routine. This is because the compiler will not compile the event routine if it was below the main routine. This is only needed if both routines reside in the same file and the file name is the same as the main routine name with the .pro extension added. Notice also the NO_BLOCK keyword to XMANAGER has been included. This allows IDL to continue processing events and accepting input at the command prompt while the example widget application is running. See Also XMTOOL, XREGISTERED XMNG_TMPL [Previous Routine] [Next Routine] [List of Routines] NAME: XMNG_TMPL The XMNG_TMPL procedure is a template for widgets that use the XMANAGER. Use this template instead of writing your widget applications from "scratch". This template can be found in the file xmng_tmpl.pro in the lib subdirectory of the IDL distribution. The documentation header should be altered to reflect the actual implementation of the XMNG_TMPL widget. Use a global search and replace to replace the word XMNG_TMPL with the name of the routine you would like to use. All the comments with a "***" in front of them should be read, decided upon and removed from the final copy of your new widget routine. Syntax XMNG_TMPL [, /BLOCK] [, GROUP=widget_id] Keywords BLOCK Set this keyword to have XMANAGER block when this application is registered. By default, BLOCK is set equal to zero, providing access to the command line if active command line processing is available. Note that setting BLOCK=1 will cause all widget applications to block, not just this application. For more information, see the documentation for the NO_BLOCK keyword to XMANAGER. Note Only the outermost call to XMANAGER can block. Therefore, to have XMNG_TMPL block, any earlier calls to XMANAGER must have been called with the NO_BLOCK keyword. See the documentation for the NO_BLOCK keyword to XMANAGER for an example. GROUP The widget ID of the widget that calls XMNG_TMPL. When this ID is specified, the death of the caller results in the death of XMNG_TMPL. See Also CW_TMPL XMTOOL [Previous Routine] [Next Routine] [List of Routines] NAME: XMTOOL The XMTOOL procedure displays a tool for viewing widgets currently being managed by the XMANAGER. Only one instance of the XMTOOL can run at one time. This routine is written in the IDL language. Its source code can be found in the file xmtool.pro in the lib/utilities subdirectory of the IDL distribution. Syntax XMTOOL [, /BLOCK] [, GROUP=widget_id] Keywords BLOCK Set this keyword to have XMANAGER block when this application is registered. By default, BLOCK is set equal to zero, providing access to the command line if active command line processing is available. Note that setting BLOCK=1 will cause all widget applications to block, not just this application. For more information, see the documentation for the NO_BLOCK keyword to XMANAGER. Note Only the outermost call to XMANAGER can block. Therefore, to have XMTOOL block, any earlier calls to XMANAGER must have been called with the NO_BLOCK keyword. See the documentation for the NO_BLOCK keyword to XMANAGER for an example. GROUP The widget ID of the widget that calls XMTOOL. If the calling widget is destroyed, the XMTOOL is also destroyed. See Also XLOADCT XOBJVIEW [Previous Routine] [Next Routine] [List of Routines] NAME: XOBJVIEW The XOBJVIEW procedure is a utility used to quickly and easily view and manipulate IDL Object Graphics on screen. It displays given objects in an IDL widget with toolbar buttons and menus providing functionality for manipulating, printing, and exporting the resulting graphic. The mouse can be used to rotate, scale, or translate the overall model shown in a view, or to select graphic objects in a view. This routine is written in the IDL language. Its source code can be found in the file xobjview.pro in the lib/utilities subdirectory of the IDL distribution. Syntax XOBJVIEW, Obj [, YOFFSET] [, JUST_REG] [, RENDERER] [, XOFFSET] [, BACKGROUND=[r, g, b]] [, /BLOCK] [, /DOUBLE_VIEW ] [, GROUP=widget_id] [, /MODAL] [, REFRESH=widget_id] [, SCALE=value] [, STATIONARY=objref(s)] [, /TEST] [, TITLE=string] [, TLB=variable] [, XSIZE=pixels] [, YSIZE=pixels] Arguments Obj A reference to an atomic graphics object, an IDLgrModel, or an array of such references. If Obj is an array, the array can contain a mixture of such references. Also, if Obj is an array, all object references in the array must be unique (i.e. no two references in the array can refer to the same object). Obj is not destroyed when XOBJVIEW is quit or killed. Keywords YOFFSET The vertical offset of the widget in units specified by the UNITS keyword (pixels are the default) relative to its parent. This offset is specified relative to the upper left corner of the parent widget. Specifying an offset relative to a row-major or column-major base widget does not work because those widgets enforce their own layout policies. This keyword is primarily of use relative to a plain base widget. Note that it is best to avoid using this style of widget layout. XOFFSET The horizontal offset of the widget in units specified by the UNITS keyword (pixels are the default) relative to its parent. Specifying an offset relative to a row-major or column-major base widget does not work because those widgets enforce their own layout policies. This keyword is primarily of use relative to a plain base widget. Note that it is best to avoid using this style of widget layout. RENDERER Set this keyword to an integer value indicating which graphics renderer to use when drawing objects in the XOBJVIEW draw window. Valid values are: * 0 = Platform native OpenGL * 1 = IDL's software implementation By default, your platform's native OpenGL implementation is used. If your platform does not have a native OpenGL implementation, IDL's software implementation is used regardless of the value of this property. JUST_REG Set this keyword to indicate that the XOBJVIEW utility should just be registered and return immediately. BACKGROUND Set this keyword to a three-element [r, g, b] color vector specifying the background color of the XOBJVIEW window. BLOCK Set this keyword to have XMANAGER block when this application is registered. By default, BLOCK is set equal to zero, providing access to the command line if active command line processing is available. Note that setting the BLOCK keyword causes all widget applications to block, not just this application. For more information, see the documentation for the NO_BLOCK keyword to XMANAGER. Note Only the outermost call to XMANAGER can block. Therefore, to have XOBJVIEW block, any earlier calls to XMANAGER must have been called with the NO_BLOCK keyword. See the documentation for the NO_BLOCK keyword to XMANAGER for an example. DOUBLE_VIEW Set this keyword to cause XOBJVIEW to set the DOUBLE property on the IDLgrView that it uses to display graphical data. GROUP The widget ID of the widget that calls XOBJVIEW. When this ID is specified, the death of the caller results in the death of XOBJVIEW. MODAL Set this keyword to block processing of events from other widgets until the user quits XOBJVIEW. The MODAL keyword does not require a group leader to be specified. If no group leader is specified, and the MODAL keyword is set, XOBJVIEW fabricates an invisible group leader for you. Note To be modal, XOBJVIEW does not require that its caller specify a group leader. This is unlike other IDL widget procedures such as XLOADCT, which, to be modal, do require that their caller specify a group leader. These other procedures were implemented this way to encourage the caller to create a modal widget that will be well-behaved with respect to layering and iconizing. (See "Iconizing, Layering, and Destroying Groups of Top-Level Bases" on page 1536 for more information.) To provide a simple means of invoking XOBJVIEW as a modal widget in applications that contain no other widgets, XOBJVIEW can be invoked as MODAL without specifying a group leader, in which case XOBJVIEW fabricates an invisible group leader for you. For applications that contain multiple widgets, however, it is good programming practice to supply an appropriate group leader when invoking XOBJVIEW, /MODAL. As with other IDL widget procedures with names prefixed with "X", specify the group leader via the GROUP keyword. REFRESH Set this keyword to the widget ID of the XOBJVIEW instance to be refreshed. To retrieve the widget ID of an instance of XOBJVIEW, first call XOBJVIEW with the TLB keyword. To refresh that instance of XOBJVIEW, call XOBVIEW again and set REFRESH to the value retrieved by the TLB keyword in the earlier call to XOBJVIEW. For example, in the initial call to XOBJVIEW, use the TLB keyword as follows: XOBJVIEW, myobj, TLB=tlb If the properties of myobj are changed in your application or at the IDL command line, refresh the view in XOBJVIEW by calling XOBJVIEW again with the REFRESH keyword: XOBJVIEW, myobj, REFRESH=tlb For an example application demonstrating the use of the REFRESH keyword, see "Example 3" on page 1737. Note Currently, the REFRESH keyword can only be used to refresh the object itself. All other keywords to XOBJVIEW are ignored when REFRESH is specified, therefore, properties such as the background color and scale are not affected. SCALE Set this keyword to the zoom factor for the initial view. The default is 1/SQRT(3). This default value provides the largest possible view of the object, while ensuring that no portion of the object will be clipped by the XOBJVIEW window, regardless of the object's orientation. STATIONARY Set this keyword to a reference to an atomic graphics object, an IDLgrModel, or an array of such references. If this keyword is an array, the array can contain a mixture of such references. Also, if this keyword is an array, all object references in the array must be unique (i.e., no two references in the array can refer to the same object). Objects passed to XOBJVIEW via this keyword will not scale, rotate, or translate in response to mouse events. Default stationary objects are two lights. These two lights are replaced if one or more lights are supplied via this keyword. Objects specified via this keyword are not destroyed by XOBJVIEW when XOBJVIEW is quit or killed. For example, to change the default lights used by XOBJVIEW, you could specify your own lights using the STATIONARY keyword as follows: mylight1 = OBJ_NEW('IDLgrLight', TYPE=0, $ COLOR=[255,0,0]) ; Ambient red mylight2 = OBJ_NEW('IDLgrLight', TYPE=2, $ COLOR=[255,0,0], LOCATION=[2,2,5]) ; Directional red mymodel = OBJ_NEW('IDLgrModel') mymodel -> Add, mylight1 mymodel -> Add, mylight2 XOBJVIEW, /TEST, STATIONARY=mymodel TLB Set this keyword to a named variable that upon return will contain the widget ID of the top level base. TEST If set, the Obj argument is not required (and is ignored if provided). A blue sinusoidal surface is displayed. This allows you to test code that uses XOBJVIEW without having to create an object to display. TITLE Set this keyword to the string that appears in the XOBJVIEW title bar. XSIZE Set this keyword to the width of the drawable area in pixels. The default is 400. YSIZE Set this keyword to the height of the drawable area in pixels. The default is 400. Using XOBJVIEW XOBJVIEW displays a resizeable top-level base with a menu, toolbar and draw widget, as shown in the following figure: Figure 35: The XOBJVIEW widget The XOBJVIEW Toolbar The XOBJVIEW toolbar contains the following buttons: Reset: Resets rotation, scaling, and panning. Rotate: Click the left mouse button on the object and drag to rotate. Pan: Click the left mouse button on the object and drag to pan. Zoom: Click the left mouse button on the object and drag to zoom in or out. Select: Click on the object. The name of the selected object is displayed, if the object has a name, otherwise its class is displayed. Examples Example 1 This example displays a simple IDLgrSurface object using XOBJVIEW: oSurf = OBJ_NEW('IDLgrSURFACE', DIST(20)) XOBJVIEW, oSurf Example 2 This example displays an IDLgrModel object consisting of two separate objects: ; Create contour object: oCont = OBJ_NEW('IDLgrContour', DIST(20), N_LEVELS=10) ; Create surface object: oSurf = OBJ_NEW('IDLgrSurface', $ DIST(20),INDGEN(20)+20, INDGEN(20)+20) ; Create model object: oModel = OBJ_NEW('IDLgrModel') ; Add contour and surface objects to model: oModel->Add, oCont oModel->Add, oSurf ; View model: XOBJVIEW, oModel This code results in the following view in the XOBJVIEW widget: Figure 36: Using XOBJVIEW to view a model consisting of two objects Note that when you click the Select button, and then click on an object, the class of that object appears next to the Select button. If the selected object has a non-null NAME property associated with it, that string value will be displayed, otherwise the name of the selected object's class will be displayed. If you want the class of the model to appear when you click over any object in the model, you can set the SELECT_TARGET property of the model as follows: oModel->SetProperty, /SELECT_TARGET Also note that it is not necessary to create a model to view more than one object using XOBJVIEW. We could view the oCont and oSurf objects created in the above example by placing them in an array as follows: XOBJVIEW, [oCont, oSurf] Example 3 This example demonstrates how the REFRESH keyword can be used to refresh the object displayed in an instance of XOBJVIEW. PRO xobjview_refresh_event, event WIDGET_CONTROL, event.id, GET_UVALUE=uval WIDGET_CONTROL, event.top, GET_UVALUE=state CASE uval OF 'red': BEGIN WIDGET_CONTROL, event.id, GET_VALUE=val state.myobj -> GetProperty, COLOR=c state.myobj -> SetProperty, COLOR=[val,c[1],c[2]] XOBJVIEW, state.myobj, GROUP=event.top, $ REFRESH=state.tlb END 'green': BEGIN WIDGET_CONTROL, event.id, GET_VALUE=val state.myobj -> GetProperty, COLOR=c state.myobj -> SetProperty, COLOR=[c[0],val,c[2]] XOBJVIEW, state.myobj, GROUP=event.top, $ REFRESH=state.tlb END 'blue': BEGIN WIDGET_CONTROL, event.id, GET_VALUE=val state.myobj -> GetProperty, COLOR=c state.myobj -> SetProperty, COLOR=[c[0],c[1],val] XOBJVIEW, state.myobj, GROUP=event.top, $ REFRESH=state.tlb END ENDCASE END PRO xobjview_cleanup, wID WIDGET_CONTROL, wID, GET_UVALUE=uval OBJ_DESTROY, uval.myobj END PRO xobjview_refresh base = WIDGET_BASE(/COLUMN, TITLE='Adjust Object Color', $ XOFFSET=420, XSIZE=200) myobj = OBJ_NEW('IDLgrSurface', $ BESELJ(SHIFT(DIST(40), 20, 20) / 2,0) * 20, $ COLOR=[255, 60, 60], STYLE=2, SHADING=1) XOBJVIEW, myobj, TLB=tlb, GROUP=base, BACKGROUND=[0,0,0] red = WIDGET_SLIDER(base, /DRAG, MIN=0, MAX=255, TITLE='Red', $ UVALUE='red', VALUE=255) green = WIDGET_SLIDER(base, /DRAG, MIN=0, MAX=255, $ TITLE='Green', UVALUE='green', VALUE=60) blue = WIDGET_SLIDER(base, /DRAG, MIN=0, MAX=255, $ TITLE='Blue', UVALUE='blue', VALUE=60) WIDGET_CONTROL, base, /REALIZE state = {myobj:myobj, tlb:tlb} WIDGET_CONTROL, base, SET_UVALUE=state XMANAGER, 'xobjview_refresh', base, /NO_BLOCK, $ CLEANUP='xobjview_cleanup' END XPALETTE [Previous Routine] [Next Routine] [List of Routines] NAME: XPALETTE The XPALETTE procedure is a utility that displays a widget interface that allows interactive creation and modification of colortables using the RGB, CMY, HSV, or HLS color systems. Single colors can be defined or multiple color indices between two endpoints can be interpolated. This routine is written in the IDL language. Its source code can be found in the file xpalette.pro in the lib/utilities subdirectory of the IDL distribution. Syntax XPALETTE [, /BLOCK] [, GROUP=widget_id] [, UPDATECALLBACK=`procedure_name' [, UPDATECBDATA=value]] Keywords BLOCK Set this keyword to have XMANAGER block when this application is registered. By default, BLOCK is set equal to zero, providing access to the command line if active command line processing is available. Note that setting BLOCK=1 will cause all widget applications to block, not just this application. For more information, see the documentation for the NO_BLOCK keyword to XMANAGER. Note Only the outermost call to XMANAGER can block. Therefore, to have XPALETTE block, any earlier calls to XMANAGER must have been called with the NO_BLOCK keyword. See the documentation for the NO_BLOCK keyword to XMANAGER for an example. GROUP The widget ID of the widget that calls XPALETTE. When this ID is specified, a death of the caller results in a death of XPALETTE. UPDATECALLBACK Set this keyword to a string containing the name of a user-supplied procedure that will be called when the color table is updated by XLOADCT. The procedure may optionally accept a keyword called DATA, which will be automatically set to the value specified by the optional UPDATECBDATA keyword. UPDATECBDATA Set this keyword to a value of any type. It will be passed via the DATA keyword to the user-supplied procedure specified via the UPDATECALLBACK keyword, if any. If the UPDATECBDATA keyword is not set the value accepted by the DATA keyword to the procedure specified by UPDATECALLBACK will be undefined. Using the XPALETTE Interface Calling XPALETTE causes a graphical interface to appear. The elements of this interface are described below. Plots on Left Side of Interface Three plots show the current red, green, and blue vectors. Status Region The center of the XPALETTE widget is a status region containing: * The total number of colors. * The current color index. XPALETTE allows changing one color at a time. This color is known as the "current color" and is indicated in the color spectrum display with a special marker. * The current mark index. The mark is used to remember a color index. Click the "Set Mark Button" to make the current color index the mark index. * A sample of the current color. The special marker used in the color spectrum display prevents the user from seeing the color of the current index, but it is visible here. Control Panel A panel of 8 buttons control common XPALETTE functions: * Done: Click this button to exit XPALETTE. The new color tables are saved in the COLORS common block and loaded to the display. * Predefined: Click this button to start XLOADCT, allowing selection of one of the predefined color tables. Note that when you change the color map via XLOADCT, XPALETTE is not always able to keep its display accurate. This problem can be overcome by pressing the XPALETTE "Redraw" button after changing the colortable via XLOADCT. * Help: Click this button to display help information. * Redraw: Click this button to redraws the display using the current state of the color map. * Set Mark: Click this button to set the value of the mark index to the current color index. * Switch Mark: Click this button to exchange the mark and the current index. * Copy Current: Click this button to make every color lying between the current index and the mark index (inclusive) the same color as the current color. * Interpolate: Click this button to smoothly interpolate colors between the current index and the mark index. Color System Control This section of the interface allows you to select the color system used to modify individual colors. The "Select Color System" pulldown menu lets you select from four different systems-RGB, CMY, HSV, and HLS. Depending upon the current system, 3 sliders below the pulldown menu allow you to alter the current color. Right Side Color Spectrum Display A display on the right side of the XPALETTE interface shows the current color map as a series of squares. Color index 0 is at the upper left. The color index increases monotonically by rows going left to right and top to bottom. The current color index is indicated by a special marker symbol. There are 4 ways to change the current color: * Click on any square in the color map display. * Use the "By Index" slider to move to the desired color index. * Use the "Row" Slider to move the marker vertically. * Use the "Column" Slider to move the marker horizontally. A Note about the Colors Used in the Interface XPALETTE uses two colors from the current color table as drawing foreground and background colors. These are used for the RGB plots on the left, and the current index marker on the right. This means that if the user set these two colors to the same value, the XPALETTE display could become unreadable (like writing on black paper with black ink). XPALETTE minimizes this possibility by noting changes to the color map and always using the brightest available color for the foreground color and the darkest for the background. Thus, the only way to make XPALETTE's display unreadable is to set the entire color map to a single color, which is highly unlikely. The only side effect of this policy is that you may notice XPALETTE redrawing the entire display after you've modified the current color. This simply means that the change has made XPALETTE pick new drawing colors. See Also LOADCT, MODIFYCT, XLOADCT, TVLCT XPCOLOR [Previous Routine] [Next Routine] [List of Routines] NAME: XPCOLOR The XPCOLOR procedure is a utility that allows you to adjust the value of the current plotting color (foreground) using sliders, and store the desired color in the global system variable, !P.COLOR. When XPCOLOR is called from the IDL input command line, the Set Plot Color dialog box appears. The dialog has two buttons (Done and Help) a single color swatch window, three sliders, and a pulldown menu with the four color systems: red, green, blue (RGB); cyan, magenta, yellow (CMY); hue, saturation, value (HSV); and hue, lightness, and saturation (HLS). When you have chosen the color system and adjusted the sliders to your liking, click Done to store the color selected in the !P.COLOR system variable. Any plots generated in IDL afterwards use the color selected as the plotting (foreground) color until !P.COLOR is changed again. Note For a more flexible color editor, use the XPALETTE User Library routine. This routine is written in the IDL language. Its source code can be found in the file xpcolor.pro in the lib/utilities subdirectory of the IDL distribution. Syntax XPCOLOR [, GROUP=widget_id ] Arguments None. Keywords GROUP Set this keyword to the group leader widget ID as passed to XMANAGER. XPLOT3D [Previous Routine] [Next Routine] [List of Routines] NAME: XPLOT3D The XPLOT3D procedure is a utility for creating and interactively manipulating 3D plots. This routine is written in the IDL language. Its source code can be found in the file xplot3d.pro in the lib/utilities subdirectory of the IDL distribution. Syntax XPLOT3D, X, Y, Z [, /BLOCK] [, COLOR=[r,g,b]] [, /DOUBLE_VIEW] [, GROUP=widget_id] [, LINESTYLE={0 | 1 | 2 | 3 | 4 | 5 | 6}]] [, /MODAL] [, NAME=string] [, /OVERPLOT] [, SYMBOL=objref(s)] [, /TEST] [, THICK=points{1.0 to 10.0}] [, TITLE=string] [, XRANGE=[min, max]] [, YRANGE=[min, max]] [, ZRANGE=[min, max]] [, XTITLE=string] [, YTITLE=string] [, ZTITLE=string] Arguments X A vector of X data values. Y A vector of Y data values. Z A vector of Z data values. Keywords BLOCK Set this keyword to have XMANAGER block when this application is registered. By default, BLOCK is set equal to zero, providing access to the command line if active command line processing is available. Note that setting the BLOCK keyword causes all widget applications to block, not just this application. For more information, see the documentation for the NO_BLOCK keyword to XMANAGER. Note Only the outermost call to XMANAGER can block. Therefore, to have XPLOT3D block, any earlier calls to XMANAGER must have been called with the NO_BLOCK keyword. See the documentation for the NO_BLOCK keyword to XMANAGER for an example. COLOR Set this keyword to an [r, g, b] triplet specifying the color of the curve. DOUBLE_VIEW Set this keyword to cause XPLOT3D to set the DOUBLE property on the IDLgrView that it uses to display the plot. GROUP Set this keyword to the widget ID of the widget that calls XPLOT3D. When this keyword is specified, the death of the caller results in the death of XPLOT3D. LINESTYLE Set this keyword to a value indicating the line style that should be used to draw the curve. The value can be either an integer value specifying a pre-defined line style, or a 2-element vector specifying a stippling pattern. To use a pre-defined line style, set the LINESTYLE keyword to one of the following integer values: * 0 = Solid line (the default) * 1 = dotted * 2 = dashed * 3 = dash dot * 4 = dash dot dot dot * 5 = long dash * 6 = no line drawn To define your own stippling pattern, specify a two-element vector [repeat, bitmask], where repeat indicates the number of times consecutive runs of 1s or 0s in the bitmask should be repeated. (That is, if three consecutive 0s appear in the bitmask and the value of repeat is 2, then the line that is drawn will have six consecutive bits turned off.) The value of repeat must be in the range 1 repeat 255. The bitmask indicates which pixels are drawn and which are not along the length of the line. The bitmask is most conveniently specified as a 16-bit hexadecimal value. For example, LINESTYLE = [2, 'F0F0'X] describes a dashed line (8 bits on, 8 bits off, 8 bits on, 8 bits off). MODAL Set this keyword to block processing of events from other widgets until the user quits XPLOT3D. The MODAL keyword does not require a group leader to be specified. If no group leader is specified, and the MODAL keyword is set, XPLOT3D fabricates an invisible group leader for you. Note To be modal, XPLOT3D does not require that its caller specify a group leader. This is unlike other IDL widget procedures such as XLOADCT, which, to be modal, do require that their caller specify a group leader. These other procedures were implemented this way to encourage the caller to create a modal widget that will be well-behaved with respect to layering and iconizing. (See "Iconizing, Layering, and Destroying Groups of Top-Level Bases" on page 1536 for more information.) To provide a simple means of invoking XPLOT3D as a modal widget in applications that contain no other widgets, XPLOT3D can be invoked as MODAL without specifying a group leader, in which case XPLOT3D fabricates an invisible group leader for you. For applications that contain multiple widgets, however, it is good programming practice to supply an appropriate group leader when invoking XPLOT3D, /MODAL. As with other IDL widget procedures with names prefixed with "X", specify the group leader via the GROUP keyword. NAME Set this keyword to a string specifying the name for the data curve being plotted. The name is displayed on the XPLOT3D toolbar when the curve is selected with the mouse. (To select the curve with the mouse, XPLOT3D must be in select mode. You can put XPLOT3D in select mode by clicking on the rightmost button on the XPLOT3D toolbar.) OVERPLOT Set this keyword to draw the curve in the most recently created view. The TITLE, [XYZ]TITLE, [XYZ]RANGE, and MODAL keywords are ignored if this keyword is set. SYMBOL Set this keyword to a vector containing one or more instances of the IDLgrSymbol object class to indicate the plotting symbols to be used at each vertex of the polyline. If there are more vertices than elements in SYMBOL, the elements of the SYMBOL vector are cyclically repeated. By default, no symbols are drawn. To remove symbols from a polyline, set SYMBOL to a scalar. TEST If set, the X, Y, and Z arguments are not required (and are ignored if provided). A sinusoidal curve is displayed instead. This allows you to test code that uses XPLOT3D without having to specify plot data. THICK Set this keyword to a value between 1.0 and 10.0, specifying the line thickness to be used to draw the polyline, in points. The default is 1.0 points. TITLE Set this keyword to a string to appear in the XPLOT3D title bar. XRANGE Set this keyword to a 2-element array of the form [min, max] specifying the X-axis range. YRANGE Set this keyword to a 2-element array of the form [min, max] specifying the Y-axis range. ZRANGE Set this keyword to a 2-element array of the form [min, max] specifying the Z-axis range. XTITLE Set this keyword to a string specifying the title for the X axis of the plot. YTITLE Set this keyword to a string specifying the title for the Y axis of the plot. ZTITLE Set this keyword to a string specifying the title for the Z axis of the plot. Using XPLOT3D XPLOT3D displays a resizeable top-level base with a menu, toolbar and draw widget, as shown in the following figure: Figure 37: The XPLOT3D Utility The XPLOT3D Toolbar The XPLOT3D toolbar contains the following buttons: Reset: Resets rotation, scaling, and panning. Rotate: Click the left mouse button on the plot and drag to rotate. Zoom: Click the left mouse button on the plot and drag to zoom in or out. Pan: Click the left mouse button on the plot and drag to pan. Click on a curve to display the curve name (if defined with the Select: NAME keyword) on the XPLOT3D toolbar. If no name was defined for the curve, "IDLGRPOLYLINE" is displayed. Projecting Data onto Plot "Walls" To turn on or off the projection of data onto the walls of the box enclosing the 3D plot, select All On, All Off, XY, YZ, or XZ from the View 2D Projection menu. Changing the Axis Type The View Axes menu allows you to select one of the following types of axes: * Simple Axes - displays the X, Y, and Z axes as lines. * Box Axes - displays the X, Y, and Z axes as planes. * No Axes - turns off the display of axes. Example The following example displays two curves in XPLOT3D, using a custom plotting symbol for one of the curves: ;Define plot data: X = INDGEN(20) Y1 = SIN(X/3.) Y2 = COS(X/3.) Z = X ;Display curve 1 in XPLOT3D: XPLOT3D, X, Y1, Z, NAME='Curve1', THICK=2 ;Define custom plotting symbols: oOrb = OBJ_NEW('orb', COLOR=[0, 0, 255]) oOrb->Scale, .75, .1, .5 oSymbol = OBJ_NEW('IDLgrSymbol', oOrb) ;Overplot curve 2 in XPLOT3D: XPLOT3D, X, Y2, Z, COLOR=[0,255,0], NAME='Curve2', $ SYMBOL=oSymbol, THICK=2, /OVERPLOT This code results in the following: Figure 38: Two curves displayed in XPLOT3D XREGISTERED [Previous Routine] [Next Routine] [List of Routines] NAME: XREGISTERED The XREGISTERED function returns True if the widget named as its argument is currently registered with the XMANAGER as an exclusive widget. Otherwise the routine returns false. If the named widget is registered, XREGISTERED returns the number of instances of that name in the list maintained by XMANAGER. The registered widget is brought to the front of the desktop unless the NOSHOW keyword is set. This routine is written in the IDL language. Its source code can be found in the file xregistered.pro in the lib subdirectory of the IDL distribution. Syntax Result = XREGISTERED(Name [, /NO_SHOW] ) Arguments Name A string containing the name of the widget in question. Note XREGISTERED checks for Name in a COMMON block created by XMANAGER. The stored name is case-sensitive. Keywords NOSHOW If the widget in question is registered, it is brought to the front of all the other windows by default. Set this keyword to keep the widget from being brought to the front. Example Suppose that you have a widget program that registers itself with the XMANAGER with the command: XMANAGER, 'mywidget', base You could limit this widget to one instantiation by adding the following line as the first line (after the procedure definition statement) of the widget creation routine: IF XREGISTERED('mywidget') THEN RETURN See Also XMANAGER XROI[1] [Previous Routine] [Next Routine] [List of Routines] NAME: XROI[1] The XROI procedure is a utility for interactively defining regions of interest (ROIs), and obtaining geometry and statistical data about these ROIs. This routine is written in the IDL language. Its source code can be found in the file xroi.pro in the lib/utilities subdirectory of the IDL distribution. Syntax XROI [, ImageData] [, R] [, G] [, B] [, TOOLS] [, /BLOCK] [[, /FLOATING] , GROUP=widget_ID] [, /MODAL] [, REGIONS_IN=value] [, REGIONS_OUT=value] [, REJECTED=variable] [, RENDERER={0 | 1}] [, ROI_COLOR=[r, g, b] or variable] [, ROI_GEOMETRY=variable] [, ROI_SELECT_COLOR=[r, g, b] or variable] [, STATISTICS=variable] [, TITLE=string] [, TOOLS=string/string array {valid values are 'Freehand Draw', 'Polygon Draw', and 'Selection'}] Arguments ImageData ImageData is both an input and output argument. It is an array representing an 8-bit or 24-bit image to be displayed. ImageData can be any of the following: * [m, n] - 8-bit image * [3, m, n] - 24-bit image * [m, 3, n] - 24-bit image * [m, n, 3] - 24-bit image If ImageData is not supplied, the user will be prompted for a file via DIALOG_PICKFILE. On output, ImageData will be set to the current image data. (The current image data can be different than the input image data if the user imported an image via the File Import Image menu item.) R, G, B R, G, and B are arrays of bytes representing red, green, or blue color table values, respectively. R, G, and B are both input and output arguments. On input, these values are applied to the image if the image is 8-bit. To get the red, green, or blue color table values for the image on output from XROI, specify a named variable for the appropriate argument. (If the image is 24-bit, this argument will output a 256-element byte array containing the values given at input, or BINDGEN(256) if the argument was undefined on input.) Keywords BLOCK Set this keyword to have XMANAGER block when this application is registered. By default, BLOCK is set equal to zero, providing access to the command line if active command line processing is available. Note that setting the BLOCK keyword causes all widget applications to block, not just this application. For more information, see the documentation for the NO_BLOCK keyword to XMANAGER. Note Only the outermost call to XMANAGER can block. Therefore, to have XROI block, any earlier calls to XMANAGER must have been called with the NO_BLOCK keyword. See the documentation for the NO_BLOCK keyword to XMANAGER for an example. FLOATING Set this keyword, along with the GROUP keyword, to create a floating top-level base widget. If the windowing system provides Z-order control, floating base widgets appear above the base specified as their group leader. If the windowing system does not provide Z-order control, the FLOATING keyword has no effect. Note Floating widgets must have a group leader. Setting this keyword without also setting the GROUP keyword causes an error. GROUP Set this keyword to the widget ID of the widget that calls XROI. When this keyword is specified, the death of the caller results in the death of XROI. MODAL Set this keyword to block other IDL widgets from receiving events while XROI is active. REGIONS_IN Set this keyword to an array of IDLgrROI references. This allows you to open XROI with ROIs already defined. This is also useful when using a loop to open multiple images in XROI. By using the same named variable for both the REGIONS_IN and REGIONS_OUT keywords, you can reuse the same ROIs in multiple images (see Example 2). This keyword also accepts ­1, or OBJ_NEW() (Null object) to indicate that there are no ROIs to read in. This allows you to assign the result of a previous REGIONS_OUT to REGIONS_IN without worrying about the case where the previous REGIONS_OUT is undefined. REGIONS_OUT Set this keyword to a named variable that will contain an array of IDLgrROI references. This keyword is assigned the null object reference if there are no ROIs defined. By using the same named variable for both the REGIONS_IN and REGIONS_OUT keywords, you can reuse the same ROIs in multiple images (see Example 2). REJECTED Set this keyword to a named variable that will contain those REGIONS_IN that are not in REGIONS_OUT. The objects defined in the variable specified for REJECTED can be destroyed with a call to OBJ_DESTROY, allowing you to perform cleanup on objects that are not required (see Example 2). This keyword is assigned the null object reference if no REGIONS_IN are rejected by the user. RENDERER Set this keyword to an integer value to indicate which graphics renderer to use when drawing objects within the window. Valid values are: * 0 = Platform native OpenGL * 1 = IDL's software implementation (the default) ROI_COLOR This keyword is both an input and an output parameter. Set this keyword to a 3-element byte array, [r, g, b], indicating the color of ROI outlines when they are not selected. This color will be used by XROI unless and until the color is changed by the user via the "Unselected Outline Color" portion of the "ROI Outline Colors" dialog (which is accessed by selecting Edit Outline Colors). If this keyword is assigned a named variable, that variable will be set to the current [r, g, b] value at the time that XROI returns. ROI_GEOMETRY Set this keyword to a named variable that will contain an array of anonymous structures, one for each ROI that is valid when this routine returns. The structures will contain the following fields: Field Description area The area of the region of interest, in square pixels. centroid The coordinates (x, y, z) of the centroid of the region of interest, in pixels. perimeter The perimeter of the region of interest, in pixels. Table 100: Fields of the structure returned by ROI_GEOMETRY If there are no valid regions of interest when this routine returns, ROI_GEOMETRY will be undefined. Note If there are no REGIONS_IN, XROI must either be modal or must block control flow in order for ROI_GEOMETRY to be defined upon exit from XROI. Otherwise, XROI will return before an ROI can be defined, and ROI_GEOMETRY will therefore be undefined. ROI_SELECT_COLOR This keyword is both an input and an output parameter. Set this keyword to a 3-element byte array, [r, g, b], indicating the color of ROI outlines when they are selected. This color will be used by XROI unless and until the color is changed by the user via the "Selected Outline Color" portion of the "ROI Outline Colors" dialog (which is accessed by selecting Edit Outline Colors). If this keyword is assigned a named variable, that variable will be set to the current [r, g, b] value at the time that XROI returns. STATISTICS Set this keyword to a named variable to receive an array of anonymous structures, one for each ROI that is valid when this routine returns. The structures will contain the following fields: Field Description count Number of pixels in region. minimum Minimum pixel value. maximum Maximum pixel value. mean Mean pixel value. stddev Standard deviation of pixel values. Table 101: Fields of the structure returned by STATISTICS If ImageData is 24-bit, or if there are no valid regions of interest when the routine exits, STATISTICS will be undefined. Note If there are no REGIONS_IN, XROI must either be modal or must block control flow in order for STATISTICS to be defined upon exit from XROI. Otherwise, XROI will return before an ROI can be defined, and STATISTICS will therefore be undefined. TITLE Set this keyword to a string to appear in the XROI title bar. TOOLS The values for the TOOLS keyword indicate the buttons to be included on an XROI toolbar. New values to the TOOLS keyword are: * 'Translate Scale' - Enables translation and scaling of ROIs. Mouse down on the bounding box selects a region, mouse motion translates (repositions) the region. Mouse down on a scale handle of the bounding box enables scaling (stretching, enlarging and shrinking) of the region according to mouse motion. Mouse up finishes the translation or scaling. * 'Rectangle' - Enables rectangular ROI drawing. Mouse down positions one corner of the rectangle, mouse motions creates the rectangle, positioning the rectangle's opposite corner, mouse up finishes the rectangular region. * 'Ellipse' - Enables elliptical ROI drawing. Mouse down positions the center of the ellipse, mouse motion positions the corner of the ellipse's imaginary bounding box, mouse up finishes the elliptical region. Set this keyword a string or vector of strings from the following list to indicate which ROI manipulation tools should be supported when XROI is run: * 'Freehand Draw' - Freehand ROI drawing. Mouse down begins a region, mouse motion adds vertices to the region (following the path of the mouse), mouse up finishes the region. * 'Polygon Draw' - Polygon ROI drawing. Mouse down begins a region, subsequent mouse clicks add vertices, double-click finishes the region. * 'Selection' - ROI selection. Mouse down/up selects the nearest region. The nearest vertex in that region is identified with a crosshair symbol. If more than one string is specified, a series of bitmap buttons will appear at the top of the XROI widget in the order specified (to the right of the fixed set of bitmap buttons used for saving regions, displaying region information, copying to clipboard, and flipping the image). If only one string is specified, no additional bitmap buttons will appear, and the manipulation mode is implied by the given string. If this keyword is not specified, bitmap buttons for all three manipulation tools are included on the XROI toolbar. Using XROI XROI displays a top-level base with a menu, toolbar and draw widget. After defining an ROI, the ROI Information window appears, as shown in the following figure: Figure 39: The XROI Utility As you move the mouse over an image, the x and y pixel locations are shown in the status line on the bottom of the XROI window. For 8-bit images, the data value (z) is also shown. If an ROI is defined, the status line also indicates the mouse position relative to the ROI using the text "Inside", "Outside", "On Edge," or "On Vertex." The XROI Toolbar The XROI toolbar contains the following buttons: Save: Opens a file selection dialog for saving the currently defined ROIs to a save file. Info: Opens the ROI Information window. Copy: Copies the contents of the display area to the clipboard. Flip: Flips image vertically. Note that only the image is flipped; any ROIs that have been defined do not move. Depending on the value of the TOOLS keyword, the XROI toolbar may also contain the following buttons: Click this button to draw freehand ROIs. Mouse down Draw begins a region, mouse motion adds vertices to the region Freehand: (following the path of the mouse), mouse up finishes the region. Draw Click this button to draw polygon ROIs. Mouse down Polygon: begins a region, subsequent mouse clicks add vertices, double-click finishes the region. Click this button to select an ROI region. Clicking the image Select: causes a cross hairs symbol to be drawn at the nearest vertex of the selected ROI. Importing an Image into XROI To import an image into XROI, select File Import Image. This opens a DIALOG_READ_IMAGE dialog, which can be used to preview and select an image. Changing the Image Color Table To change the color table properties for the current image, select Edit Image Color Table. This opens the CW_PALETTE_EDITOR dialog, which is a compound widget used to edit color palettes. See CW_PALETTE_EDITOR for more information. This menu item is grayed out if the image does not have a color palette. Changing the ROI Outline Colors To change the outline colors for selected and unselected ROIs, select Edit Outline Colors. This opens the ROI Outline Colors dialog, which consists of two CW_RGBSLIDER widgets for interactively adjusting the ROI outline colors. The left widget is used to define the color for the selected ROI, and the right widget is used to define the color of unselected ROIs. You can select the RGB, CMY, HSV, or HLS color system from the Color System drop-down list. Viewing ROI Information To view geometry and statistical data about the currently selected ROI, click the Info button or select Edit ROI Information. This opens the ROI Information dialog, which displays area, perimeter, number of pixels, minimum and maximum pixel values, and standard deviation. Values for statistical information (minimum, maximum, mean, and standard deviation) appear as "N/A" for 24-bit images. To view a histogram for the currently selected ROI, click the Histogram button. This opens a LIVE_PLOT dialog, which can be used to interactively control the plot properties. Note The Histogram button is enabled only for 8-bit images. Deleting an ROI To delete an ROI, do the following: 1. Click the Info button or select Edit ROI Information. This opens the ROI Information dialog. 2. In the ROI Information dialog, select the ROI you wish to delete from the list of ROIs. You can also select an ROI by clicking the Select button on the XROI toolbar, then clicking on an ROI on the image. 3. Click the Delete ROI button. Examples Example 1 This example opens a single image in XROI: image = READ_PNG(FILEPATH('mineral.png', $ SUBDIR=['examples','data'])) XROI, image Example 2 This example reads 3 images from the file mr_abdomen.dcm, and calls XROI for each image. A single list of regions is maintained, saving the user from having to redefine regions on each image: ;Read 3 images from mr_abdomen.dcm and open each one in XROI: FOR i=0,2 DO BEGIN image = READ_DICOM(FILEPATH('mr_abdomen.dcm',$ SUBDIR=['examples','data']), IMAGE_INDEX=i) XROI, image, r, g, b, REGIONS_IN=regions,$ REGIONS_OUT=regions, ROI_SEL ROI_COLOR=roi_color, REJECTED=rejected, /BLOCK OBJ_DESTROY, rejected ENDFOR OBJ_DESTROY, regions Perform the following steps: 1. Draw an ROI on the first image, then close that XROI window. Note that the next image contains the ROI defined in the first image. This is accomplished by setting REGIONS_IN and REGIONS_OUT to the same named variable in the FOR loop of the above code. 2. Draw another ROI on the second image. 3. Click the Select button and select the first ROI. Then click the Info button to open the ROI Information window, and click the Delete ROI button. 4. Close the second XROI window. Note that the third image contains the ROI defined in the second image, but not the ROI deleted on the second image. This example sets the REJECTED keyword to a named variable, and calls OBJ_DESTROY on that variable. Use of the REJECTED keyword is not necessary to prevent deleted ROIs from appearing on subsequent images, but allows you perform cleanup on objects that are no longer required. XSQ_TEST [Previous Routine] [Next Routine] [List of Routines] NAME: XSQ_TEST The XSQ_TEST function computes the Chi-square goodness-of-fit test between observed frequencies and the expected frequencies of a theoretical distribution. The result is a two-element vector containing the Chi-square test statistic X2 and the one- tailed probability of obtaining a value of X2 or greater. Expected frequencies of magnitude less than 5 are combined with adjacent elements resulting in a reduction of cells used to formulate the chi-squared test statistic. If the observed frequencies differ significantly from the expected frequencies, the Chi- square test statistic will be large and the fit is poor. This situation requires the rejection of the hypothesis that the given observed frequencies are an accurate approximation to the expected frequency distribution. This routine is written in the IDL language. Its source code can be found in the file xsq_test.pro in the lib subdirectory of the IDL distribution. Syntax Result = XSQ_TEST( Obfreq, Exfreq [, EXCELL=variable] [, OBCELL=variable] [, RESIDUAL=variable] ) Arguments Obfreq An n-element integer, single-, or double-precision floating-point vector containing observed frequencies. Exfreq An n-element integer, single-, or double-precision floating-point vector containing expected frequencies. Keywords EXCELL Set this keyword to a named variable that will contain a vector of expected frequencies used to formulate the Chi-square test statistic. If each of the expected frequencies contained in Exfreq, has a magnitude of 5 or greater, then this vector is identical to Exfreq. If Exfreq contains elements of magnitude less than 5, adjacent expected frequencies are combined. The identical combinations are performed on the corresponding elements of Obfreq. OBCELL Set this keyword to a named variable that will contain a vector of observed frequencies used to formulate the Chi-square test statistic. The elements of this vector are often referred to as the "cells" of the observed frequencies. The length of this vector is determined by the length of EXCELL described below. RESIDUAL Set this keyword to a named variable that will contain a vector of signed differences between corresponding cells of observed frequencies and expected frequencies. RESIDUAL[i] = OBCELL[i] - EXCELL[i]. The length of this vector is determined by the length of EXCELL described above. Example ; Define the vectors of observed and expected frequencies: obfreq = [2, 1, 4, 15, 10, 5, 3] exfreq = [0.5, 2.1, 5.9, 10.3, 10.7, 7.0, 3.5] ; Test the hypothesis that the given observed frequencies are an ; accurate approximation to the expected frequency distribution: result = XSQ_TEST(obfreq, exfreq) PRINT, result IDL Output 3.05040 0.383920 Since the vector of expected frequencies contains elements of magnitude less than 5, adjacent expected frequencies are combined resulting in fewer cells. The identical combinations are performed on the corresponding elements of observed frequencies. The computed value of 0.383920 indicates that there is no reason to reject the proposed hypothesis at the 0.05 significance level. See Also CTI_TEST XSURFACE [Previous Routine] [Next Routine] [List of Routines] NAME: XSURFACE The XSURFACE procedure is a utility that provides a graphical interface to the SURFACE and SHADE_SURF commands. Different controls are provided to change the viewing angle and other plot parameters. The command used to generate the resulting surface plot is shown in a text window. Note that this procedure does not accept SURFACE or SHADE_SURF keywords. This routine is written in the IDL language. Its source code can be found in the file xsurface.pro in the lib/utilities subdirectory of the IDL distribution. Syntax XSURFACE, Data [, /BLOCK] [, GROUP=widget_id] Arguments Data The two-dimensional array to display as a wire-mesh or shaded surface. Keywords BLOCK Set this keyword to have XMANAGER block when this application is registered. By default, BLOCK is set equal to zero, providing access to the command line if active command line processing is available. Note that setting BLOCK=1 will cause all widget applications to block, not just this application. For more information, see the documentation for the NO_BLOCK keyword to XMANAGER. Note Only the outermost call to XMANAGER can block. Therefore, to have XSURFACE block, any earlier calls to XMANAGER must have been called with the NO_BLOCK keyword. See the documentation for the NO_BLOCK keyword to XMANAGER for an example. GROUP Set this keyword to the widget ID of the widget that calls XSURFACE. When GROUP is specified, the death of the calling widget results in the death of XSURFACE. Example ; Make a 2D array: z = DIST(30) ; Call XSURFACE. The XSURFACE widget appears: XSURFACE, z See Also SHADE_SURF, SURFACE XVAREDIT [Previous Routine] [Next Routine] [List of Routines] NAME: XVAREDIT The XVAREDIT procedure is a utility that provides a widget-based editor for any IDL variable. Use the input fields to change desired values of the variable or array. Click "Accept" to write the new values into the variable. Click "Cancel" to exit XVAREDIT without saving changes. This routine is written in the IDL language. Its source code can be found in the file xvaredit.pro in the lib/utilities subdirectory of the IDL distribution. Syntax XVAREDIT, Var [, NAME='variable_name'{ignored if variable is a structure}] [, GROUP=widget_id] [, X_SCROLL_SIZE=columns] [, Y_SCROLL_SIZE=rows] Arguments Var The variable to be edited. On output, this variable contains the edited value if the user selects the "Accept" button, or the original value if the user selects the "Cancel" button. Keywords NAME The NAME of the variable. This keyword is overwritten with the structure name if the variable is a structure. GROUP The widget ID of the widget that calls XVAREDIT. When this ID is specified, a death of the caller results in a death of XVAREDIT. X_SCROLL_SIZE Set this keyword to the column width of the scrolling viewport. The default is 4. Y_SCROLL_SIZE Set this keyword to the row width of the scrolling viewport. The default is 4. XVOLUME [Previous Routine] [Next Routine] [List of Routines] NAME: XVOLUME The XVOLUME procedure is a utility for viewing and interactively manipulating volumes and isosurfaces. This routine is written in the IDL language. Its source code can be found in the file xvolume.pro in the lib/utilities subdirectory of the IDL distribution. Tip The XVOLUME_ROTATE and XVOLUME_WRITE_IMAGE procedures, which can be called only after a call to XVOLUME, can be used to easily create animations of volumes and isosurfaces displayed in XVOLUME. See XVOLUME_ROTATE for an example. Syntax XVOLUME, Vol, [, /BLOCK] [, GROUP=widget_id] [, /INTERPOLATE] [, /MODAL] [, RENDERER={0 | 1}] [, /REPLACE] [, SCALE=value] [, /TEST] [, XSIZE=pixels] [, YSIZE=pixels] Arguments Vol A 3-element array of the form [x, y, z] that specifies a data volume. Keywords BLOCK Set this keyword to have XMANAGER block when this application is registered. By default, BLOCK is set equal to zero, providing access to the command line if active command line processing is available. Note that setting the BLOCK keyword causes all widget applications to block, not just this application. For more information, see the documentation for the NO_BLOCK keyword to XMANAGER. Note Only the outermost call to XMANAGER can block. Therefore, to have XVOLUME block, any earlier calls to XMANAGER must have been called with the NO_BLOCK keyword. See the documentation for the NO_BLOCK keyword to XMANAGER for an example. GROUP Set this keyword to the widget ID of the widget that calls XVOLUME. When this keyword is specified, the death of the caller results in the death of XVOLUME. INTERPOLATE Set this keyword to indicate that trilinear interpolation is to be used when rendering the volume and the image planes. Setting this keyword improves the quality of images produced, at the cost of more computing time, especially when the volume has low resolution with respect to the size of the viewing plane. Nearest neighbor sampling is used by default. MODAL Set this keyword to block processing of events from other widgets until the user quits XVOLUME. The MODAL keyword does not require a group leader to be specified. If no group leader is specified, and the MODAL keyword is set, XVOLUME fabricates an invisible group leader for you. Note To be modal, XVOLUME does not require that its caller specify a group leader. This is unlike other IDL widget procedures such as XLOADCT, which, to be modal, do require that their caller specify a group leader. These other procedures were implemented this way to encourage the caller to create a modal widget that will be well-behaved with respect to layering and iconizing. (See "Iconizing, Layering, and Destroying Groups of Top-Level Bases" on page 1536 for more information.) To provide a simple means of invoking XVOLUME as a modal widget in applications that contain no other widgets, XVOLUME can be invoked as MODAL without specifying a group leader, in which case XVOLUME fabricates an invisible group leader for you. For applications that contain multiple widgets, however, it is good programming practice to supply an appropriate group leader when invoking XVOLUME, /MODAL. As with other IDL widget procedures with names prefixed with "X", specify the group leader via the GROUP keyword. RENDERER Set this keyword to an integer value indicating which graphics renderer to use when drawing objects within the window. Valid values are: * 0 = Platform native OpenGL (the default) * 1 = IDL's software implementation REPLACE If this keyword is set, and there is a current instance of XVOLUME running, the volume displayed in XVOLUME is replaced with the volume specified by Vol. For example, display volume1 using the command XVOLUME, volume1 To replace volume1 with volume2, you would use the command XVOLUME, volume2, /REPLACE SCALE Set this keyword to the zoom factor for the initial view. The default is 1/SQRT(3). This default value provides the largest possible view of the volume, while ensuring that no portion of the volume will be clipped by the XVOLUME window, regardless of the volume's orientation. TEST If set, the Vol argument is not required (and is ignored if provided). A volume of random numbers is displayed instead. This allows you to test code that uses XVOLUME without having to specify volume data. XSIZE The width of the drawable area in pixels. YSIZE The height of the drawable area in pixels. Using XVOLUME XVOLUME displays a resizeable top-level base with a toolbar, a menu, a graphical interface for controlling volume and isosurface properties, and a draw widget for displaying and manipulating the volume, as shown in the following figure: Figure 40: The XVOLUME Utility The XVOLUME Toolbar The XVOLUME toolbar contains the following buttons. Note If you have the Auto-Render option selected, the Rotate, Zoom, and Pan features may be more difficult to use. For the best performance while manipulating the orientation of a volume using these features, uncheck the Auto-Render option. Reset: Resets rotation, scaling, and panning. Rotate: Click the left mouse button on the volume and drag to rotate. Zoom: Click the left mouse button on the volume and drag to zoom in or out. Pan: Click the left mouse button on the volume and drag to pan. Select: Click in the draw widget to identify the selected item. A name identifying the selected item is displayed next to the Select button. The XVOLUME Interface The XVOLUME interface provides the following elements for controlling the display of image planes and contours, volumes, and isosurfaces: Image Planes and Contours Image planes and contours allow you to visualize the values associated with the volume or isosurface at a specified X, Y, or Z plane. * Image Planes: Select one of the following options from the dropdown list for each dimension to control the display of image planes: * Off: Turns off the image plane display. * Opaque: Displays an opaque image plane at the location specified by the corresponding plane slider. * Transparent: Displays a transparent image plane at the location specified by the corresponding plane slider. The transparency value of the plane is taken from the volume at the current location of the image plane. * Contours: Check this option to display contours on the specified plane at the location specified by corresponding the plane slider. * Plane Sliders: Move these sliders to change the position of the plane in each dimension. Volume * Color and Opacity: Click this button to change the color and/or opacity of the current volume. This opens a CW_PALETTE_EDITOR dialog, which is a compound widget used to edit color palettes. See CW_PALETTE_EDITOR for more information. * Auto-Render: Select this option to have rendering executed automatically after each change you make to the volume. If Auto-Render is unchecked, you must manually click the Render button to see changes you have made to the volume. If Auto-Render is checked, the Render button will be grayed out. * Render: Click on this button to execute rendering computations and display the current volume. If Auto-Render is checked, this button will be grayed out. Isosurface An isosurface is a 3D surface on which the data values are constant along the entire surface. Use the following elements to control the appearance of the isosurface: * Color: Click this button to change the color system and/or values for the current isosurface. This opens a CW_RGBSLIDER dialog, which is a compound widget that provides a drop-down list for selecting the RGB, CMY, HSV, or HLS color system, and three sliders for adjusting the values associated with each color system. * Isosurface Off: Select this option to turn off the isosurface display. * Opaque Isosurface: Select this option to display an opaque isosurface. * Semi-transparent Isosurface: Select this option to display a semi-transparent isosurface. * Level: Use this slider to adjust the threshold value of the isosurface. Example Create a volume and display using XVOLUME: ; Create a volume: vol = BYTSCL(RANDOMU((SEED=0),5,5,5)) vol = CONGRID(vol, 30,30,30) ; Display volume: XVOLUME, vol See Also XVOLUME_ROTATE, XVOLUME_WRITE_IMAGE, IDLgrVolume, ISOSURFACE, SHADE_VOLUME, SLICER3 XVOLUME_ROTATE [Previous Routine] [Next Routine] [List of Routines] NAME: XVOLUME_ROTATE The XVOLUME_ROTATE procedure is used to programmatically rotate the volume currently displayed in XVOLUME. XVOLUME must be called prior to calling XVOLUME_ROTATE. This procedure can be used to create animations of volumes and isosurfaces. This routine is written in the IDL language. Its source code can be found in the file xvolume_rotate.pro in the lib/utilities subdirectory of the IDL distribution. Syntax XVOLUME_ROTATE, Axis, Angle [, /PREMULTIPLY] Arguments Axis A 3-element vector of the form [x, y, z] describing the axis about which the model is to be rotated. Angle The amount of rotation, measured in degrees. Keywords PREMULTIPLY Set this keyword to cause the rotation matrix specified by Axis and Angle to be pre- multiplied to the model's transformation matrix. By default, the rotation matrix is post-multiplied. Example The following example creates an animation of the volume currently displayed in XVOLUME. It does this by rotating the volume through 360 degrees in increments of 10 degrees using XVOLUME_ROTATE, and writing the volume to a BMP file for each increment using XVOLUME_WRITE_IMAGE. It then loops through the images and uses TV to display each image. First, display a volume as follows: ; Create a volume: vol = BYTSCL(RANDOMU((SEED=0),5,5,5)) vol = CONGRID(vol, 30,30,30) ; Display volume: XVOLUME, vol Now, use the XVOLUME interface to modify the orientation and appearance of the volume or isosurface as desired. Once you have the volume or isosurface displayed the way you want it, run the following program: PRO spin_volume inc = 10. ; degrees. ; Create images FOR i=0,(360./inc)-2 DO BEGIN XVOLUME_WRITE_IMAGE, $ 'spin' + STRCOMPRESS(i, /REMOVE_ALL) + '.bmp', 'bmp' XVOLUME_ROTATE, [0,0,1], inc, /PREMULTIPLY ENDFOR XVOLUME_ROTATE, [0,0,1], inc, /PREMULTIPLY ; Read images img = READ_BMP('spin0.bmp') siz = SIZE(img, /DIM) arr = BYTARR(3, siz[1], siz[2], 360./inc-1) FOR i=0,360./inc-2 DO BEGIN img = READ_BMP( $ 'spin' + STRCOMPRESS(i, /REMOVE_ALL) + '.bmp', /RGB) arr[0,0,0, i] = img PRINT, i ENDFOR ; Display animation FOR i=0,2 DO BEGIN ; num rotations FOR j=0,(360./inc)-2 DO BEGIN TV, arr[*,*,*,j], /TRUE ENDFOR ENDFOR TV, arr[*,*,*,0], /TRUE END See Also XVOLUME, XVOLUME_WRITE_IMAGE XVOLUME_WRITE_IMAGE [Previous Routine] [Next Routine] [List of Routines] NAME: XVOLUME_WRITE_IMAGE The XVOLUME_WRITE_IMAGE procedure is used to write the volume currently displayed in XVOLUME to an image file with the specified name and file format. XVOLUME must be called prior to calling XVOLUME_WRITE_IMAGE. This routine is written in the IDL language. Its source code can be found in the file xvolume_write_image.pro in the lib/utilities subdirectory of the IDL distribution. Syntax XVOLUME_WRITE_IMAGE, Filename, Format [, DIMENSIONS=[x, y] ] Arguments Filename A scalar string containing the name of the file to write. Format A scalar string containing the name of the file format to write. See QUERY_IMAGE for a list of supported formats. Keywords DIMENSIONS Set this keyword to a 2-element vector of the form [x, y] specifying the size of the output image, in pixels. If this keyword is not specified, the image will be written using the dimensions of the current XVOLUME draw widget. Example See XVOLUME_ROTATE. See Also XVOLUME, XVOLUME_ROTATE XYOUTS [Previous Routine] [Next Routine] [List of Routines] NAME: XYOUTS The XYOUTS procedure draws text on the currently-selected graphics device starting at the designated coordinate. Arguments X, Y, and String can be any combination of scalars or arrays. If the arguments are arrays, multiple strings are output. If the optional X and Y arguments are omitted, the text is positioned at the end of the most recently output text string. Important keywords that control the appearance and positioning of the text include: ALIGNMENT, the justification of the text; CHARSIZE, the size of the text; FONT, chooses between vector drawn and hardware fonts; COLOR, the color of the text; and ORIENTATION, the angle between the baseline of the text and the horizontal. With hardware fonts, most of the text attributes, (e.g., size and orientation), are predetermined and not changeable. Note Specify the Z coordinate with the Z keyword when positioning text in three dimensions. Syntax XYOUTS, [X, Y,] String [, ALIGNMENT=value{0.0 to 1.0}] [, CHARSIZE=value] [, CHARTHICK=value] [, TEXT_AXES={0 | 1 | 2 | 3 | 4 | 5}] [, WIDTH=variable] Graphics Keywords:[, CLIP=[X0, Y0, X1, Y1]] [, COLOR=value][, /DATA | , /DEVICE | , /NORMAL] [, FONT=integer] [, ORIENTATION=ccw_degrees_from_horiz] [, /NOCLIP] [, /T3D] [, Z=value] Arguments X, Y The horizontal and vertical coordinates used to position the string(s). X and Y are normally interpreted in data coordinates. The DEVICE and NORMAL keywords can be used to specify the coordinate units. X and Y can be arrays of positions if String is an array. String The string(s) to be output. This argument can be a scalar string or an array of strings. If this argument is not a string, it is converted prior to use using the default formatting rules. If String is an array, X, Y, and the COLOR keyword can also be arrays so that each string can have a separate location and color. Keywords ALIGNMENT Specifies the alignment of the text baseline. An alignment of 0.0 (the default) aligns the left edge of the text baseline with the given (x, y) coordinate. An alignment of 1.0 right-justifies the text, while 0.5 results in text centered over the point (x, y). CHARSIZE The overall character size for the annotation. A CHARSIZE of 1.0 is normal. Setting CHARSIZE = -1 suppresses output of the text string. This keyword has no effect when used with the hardware drawn fonts; for exceptions, see "Scaled Hardware Fonts" on page 1778. CHARTHICK The line thickness of the vector drawn font characters. This keyword has no effect when used with the hardware drawn fonts; for exceptions, see "Scaled Hardware Fonts" on page 1778. The default value is 1.0. TEXT_AXES This keyword specifies the plane of vector drawn text when three-dimensional plotting is enabled. By default, text is drawn in the plane of the XY axes. The horizontal text direction is in the X plane, and the vertical text direction is in the Y plane. Values for this keyword can range from 0 to 5, with the following effects: 0 for XY, 1 for XZ, 2 for YZ, 3 for YX, 4 for ZX, and 5 for ZY. The notation ZY means that the horizontal direction of the text lies in the Z plane, and the vertical direction of the text is drawn in the Y plane. WIDTH Set this keyword to a named variable in which to return the width of the text string, in normalized coordinate units. Graphics Keywords Accepted See Appendix C, "Graphics Keywords" for the description of graphics and plotting keywords not listed above. CLIP, COLOR, DATA, DEVICE, FONT, NOCLIP, NORMAL, ORIENTATION, T3D, Z. Examples Print the string "This is text" at device coordinate position (100,100): XYOUTS, 100, 100, 'This is text', /DEVICE Print an array of strings with each element of the array printed at a different location. Use larger text than in the previous example: XYOUTS, [0, 200, 250], [200, 50, 100], $ ['This', 'is', 'text'], CHARSIZE = 3, /DEVICE Determine the text size for a window device before opening an on-screen window: WINDOW, /FREE, /PIXMAP, XSIZE=myWinXSize, YSIZE=myWinYSize XYOUTS, 'Check this out', WIDTH=w WDELETE myWinXSize and myWinYSize are chosen to match your onscreen window. Since we can not know the characteristics of a given device (such as character size) until a window has been opened, the PIXMAP keyword to WINDOW allows you to compute appropriate dimensions for text with an invisible window before displaying a window on your screen. Scaled Hardware Fonts One example of hardware fonts which can be scaled are PostScript fonts. If you are using PostScript fonts, the keywords CHARTHICK and CHARSIZE will have an effect on a call to XYOUTS. Of the devices we provide that support hardware fonts, only the PostScript device uses scalable PostScript fonts for its "hardware" font system. All other devices use a bitmapped font technology. Scaling is related to whether or not a device supports Hershey formatting commands when hardware fonts are used. Formatting requires the ability to scale the text on a per-character basis (i.e. for subscripting). To see if a given device supports Hershey formatting when hardware fonts are used, look at bit 12 of !D.FLAGS. You can also use this indicator to determine whether or not the hardware fonts will be scaled. See Also ANNOTATE, PRINT/PRINTF ZOOM [Previous Routine] [Next Routine] [List of Routines] NAME: ZOOM The ZOOM procedure displays part of an image from the current window enlarged in a new ("zoom") window. The cursor is used to mark the center of the zoom area, and different zoom factors can be specified interactively. Note ZOOM only works with color systems. This routine is written in the IDL language. Its source code can be found in the file zoom.pro in the lib subdirectory of the IDL distribution. Using ZOOM After calling ZOOM, place the mouse cursor over an image in an IDL graphics window. Click the left mouse button to display a magnified version of the image in a new window. The zoomed image is centered around the pixel selected in the original window. Click the middle mouse button to display a menu of zoom factors. Click the right mouse button to exit the procedure. Using ZOOM with Draw Widgets Note that the ZOOM procedure is only for use with IDL graphics windows. It should not be used with draw widgets. To obtain a zooming effect in a draw widget, use the CW_ZOOM function. Syntax ZOOM [, /CONTINUOUS] [, FACT=integer] [, /INTERP] [, /KEEP] [, /NEW_WINDOW] [, XSIZE=value] [, YSIZE=value] [, ZOOM_WINDOW=variable] Keywords CONTINUOUS Set this keyword to make the zoom window track the mouse without requiring the user to press the left mouse button. This feature only works well on fast computers. FACT Use this keyword to specify the zoom factor, which must be an integer. The default zoom factor is 4. INTERP Set this keyword to use bilinear interpolation. The default is to use pixel replication. KEEP Set this keyword to keep the zoom window after exiting the procedure. NEW_WINDOW Normally, if ZOOM is called with KEEP and then called again, it will use the same window to display the new zoomed image. Set the NEW_WINDOW keyword to force ZOOM to create a new window for this purpose. XSIZE Use this keyword to specify the X size of the zoom window. The default is 512. YSIZE Use this keyword to specify the Y size of the zoom window. The default is 512. ZOOM_WINDOW Set this keyword to a named variable that will contain the index of the zoom window. KEEP must also be set. If KEEP is not set, ZOOM_WINDOW will contain the integer -1. See Also CW_ZOOM, ZOOM_24 ZOOM_24 [Previous Routine] [Next Routine] [List of Routines] NAME: ZOOM_24 The ZOOM_24 procedure displays part of a 24-bit color image from the current window expanded in a new ("zoom") window, and provides information about cursor location and color values in an auxiliary ("data") window. The cursor is used to mark the center of the zoom area, and different zoom factors can be specified interactively. Note ZOOM only works on 24-bit color systems. This routine is written in the IDL language. Its source code can be found in the file zoom_24.pro in the lib subdirectory of the IDL distribution. Using ZOOM_24 After calling ZOOM_24, windows titled "Zoomed Image" (the zoom window) and "Pixel Values" (the data window) appear on the screen. Place the mouse cursor over a 24-bit color image in an IDL graphics window and click the left mouse button to display a magnified version of the image in the zoom window. The zoomed image is centered around the pixel selected in the original window. Move the mouse cursor in the zoom window to determine the coordinates (in the original image) and color values of individual pixels. With the cursor located in the zoom window, click the right mouse button to return to selection mode, which allows you to either choose a new zoom center, change the zoom factor, or exit the procedure. Move the cursor to the original image and click the middle mouse button to display a menu of zoom factors, or click the right mouse button to exit the procedure. Using ZOOM_24 with Draw Widgets Note that the ZOOM_24 procedure is only for use with IDL graphics windows. It should not be used with draw widgets. To obtain a zooming effect in a draw widget, use the CW_ZOOM function. Syntax ZOOM_24 [, FACT=integer] [, /RIGHT] [, XSIZE=value] [, YSIZE=value] Keywords FACT Use this keyword to specify the zoom factor, which must be an integer. The default zoom factor is 4. RIGHT Set this keyword to position the zoom and data windows to the right of the original window. XSIZE Use this keyword to specify the X size of the zoom window. The default is 512. YSIZE Use this keyword to specify the Y size of the zoom window. The default is 512. See Also CW_ZOOM, ZOOM THIS APPENDIX: [Previous Routine] [Next Routine] [List of Routines] IDL_CONTAINER [Previous Routine] [Next Routine] [List of Routines] NAME: IDL_Container An IDL_Container object holds other objects. Destroying an IDL_Container object destroys any objects that have been added to the container via the Add method. Superclasses This class has no superclasses. Subclasses The following classes are subclassed from this class: * IDLgrModel * IDLgrScene * IDLgrView * IDLgrViewgroup Creation See "IDL_Container::Init" on page 1792. Methods Intrinsic Methods This class has the following methods: * IDL_Container::Add * IDL_Container::Cleanup * IDL_Container::Count * IDL_Container::Get * IDL_Container::Init * IDL_Container::IsContained * IDL_Container::Move * IDL_Container::Remove IDL_CONTAINER::ADD [Previous Routine] [Next Routine] [List of Routines] NAME: IDL_Container::Add The IDL_Container::Add procedure method adds a child object to the container. Syntax Obj -> [IDL_Container::]Add, Object [POSITION=index] Arguments Object An instance of an object to be added to the container object. Keywords POSITION Set this keyword equal to the zero-based index of the position within the container at which the new object should be placed. The default is to add the new object at the end of the list of contained items. Example If the container has three objects, the new object will be placed at the fourth position. Since positions begin at zero, this would be equivalent to setting POSITION=3. IDL_CONTAINER::CLEANUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDL_Container::Cleanup The IDL_Container::Cleanup procedure method performs all cleanup on the object. Note Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass. Syntax OBJ_DESTROY, Obj or Obj-> [IDL_Container::]Cleanup(Only in subclass' Cleanup method.) Arguments None Keywords None IDL_CONTAINER::COUNT [Previous Routine] [Next Routine] [List of Routines] NAME: IDL_Container::Count The IDL_Container::Count function method returns the number of objects contained by the container object. Syntax Result = Obj -> [IDL_Container::]Count() Arguments None Keywords None IDL_CONTAINER::GET [Previous Routine] [Next Routine] [List of Routines] NAME: IDL_Container::Get The IDL_Container::Get function method returns an array of object references to objects in a container. Unless the ALL or POSITION keywords are specified, the first object in the container is returned. If no objects are found in the container, the Get function returns -1. Syntax Result = Obj -> [IDL_Container::]Get ([, /ALL [, ISA=class_name(s)] | , POSITION=index] [COUNT=variable] ) Arguments None Keywords ALL Set this keyword to return an array of object references to all of the objects in the container. COUNT Set this keyword equal to a named variable that will contain the number of objects selected by the function. If the ALL keyword is also specified, specifying this keyword is the same as calling the IDL_Container::Count method. ISA Set this keyword equal to a class name or vector of class names. This keyword is used in conjunction with the ALL keyword. The ISA keyword filters the array returned by the ALL keyword, returning only the objects that inherit from the class or classes specified by the ISA keyword. Note This keyword is ignored if the ALL keyword is not provided. POSITION Set this keyword equal to a scalar or array containing the zero-based indices of the positions of the objects to return. IDL_CONTAINER::INIT [Previous Routine] [Next Routine] [List of Routines] NAME: IDL_Container::Init The IDL_Container::Init function method initializes the container object. Note Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass. Syntax Obj = OBJ_NEW('IDL_Container') or Result = Obj -> [IDL_Container::]Init( ) (Only in a subclass' Init method.) Arguments None Keywords None IDL_CONTAINER::ISCONTAINED [Previous Routine] [Next Routine] [List of Routines] NAME: IDL_Container::IsContained The IDL_Container::IsContained function method returns true (1) if the specified object is in the container, or false (0) otherwise. Syntax Result = Obj -> [IDL_Container::]IsContained( Object [, POSITION=variable] ) Arguments Object The object reference or vector of object references of the object(s) to search for in the container. Keywords POSITION Set this keyword to a named variable that upon return will contain the position(s) at which (each of) the argument(s) is located within the container, or -1 if it is not contained. IDL_CONTAINER::MOVE [Previous Routine] [Next Routine] [List of Routines] NAME: IDL_Container::Move The IDL_Container::Move procedure method moves an object from one position in a container to a new position. The order of the other objects in the container remains unchanged. Positioning within a container controls the rendering order of the contained objects. The object whose location has the lowest index value is rendered first. If several objects are located at the same point in three-dimensional space, the object rendered first will occlude objects rendered later. Objects located "behind" other objects in three-dimensional space must be rendered before objects in front of them, even if the "front" objects are translucent. Syntax Obj -> [IDL_Container::]Move, Source, Destination Arguments Source The zero-based index of the current location of the object to be moved. Destination The zero-based index of the location in the container where the object will reside after being moved. Keywords None IDL_CONTAINER::REMOVE [Previous Routine] [Next Routine] [List of Routines] NAME: IDL_Container::Remove The IDL_Container::Remove procedure method removes an object from the container. Syntax Obj -> [IDL_Container::]Remove [, Child_object | , POSITION=index | , /ALL] Arguments Child_object The object reference of the object to be removed from the container. If Child_object is not provided (and neither the ALL nor POSITION keyword are set), the first object in the container will be removed. Keywords ALL Set this keyword to remove all objects from the container. If this keyword is set, the Child_object argument is not required. POSITION Set this keyword equal to the zero-based index of the object to be removed. If the Child_object argument is supplied, this keyword is ignored. IDLANROI [Previous Routine] [Next Routine] [List of Routines] NAME: IDLanROI The IDLanROI object class represents a region of interest. Note The IDLan* naming convention is used for objects in the analysis domain. Regions of interest are described as a set of vertices that may be connected to generate a path or a polygon, or may be treated as separate points. This object may be used as a source for analytical computations on regions. (For additional information about display of ROIs in Object Graphics, refer to the IDLgrROI object class.) Superclasses None. Subclasses This class is a superclass of IDLgrROI. Creation See IDLanROI::Init. Methods Intrinsic Methods The IDLanROI class has the following methods. * IDLanROI::AppendData * IDLanROI::Cleanup * IDLanROI::ComputeGeometry * IDLanROI::ComputeMask * IDLanROI::ContainsPoints * IDLanROI::GetProperty * IDLanROI::Init * IDLanROI::RemoveData * IDLanROI::ReplaceData * IDLanROI::Rotate * IDLanROI::Scale * IDLanROI::SetProperty * IDLanROI::Translate IDLANROI::APPENDDATA [Previous Routine] [Next Routine] [List of Routines] NAME: IDLanROI::AppendData The IDLanROI::AppendData procedure method appends vertices to the region. Syntax Obj­>[IDLanROI::]AppendData, X [, Y] [, Z] [, XRANGE=variable] [, YRANGE=variable] [, ZRANGE=variable] Arguments X A vector providing the X components of the vertices to be appended. If the Y and Z arguments are not specified, X must be a two-dimensional array with the leading dimensions either 2 or 3 ([2,*] or [3,*]), in which case, X[0,*] represents the X values, X[1,*] represents the Y values, and X[2,*] represents the Z values. If the DOUBLE property is non-zero, the data is converted to double precision and is appended to the existing double precision data. Otherwise it is converted to single precision floating point and appended to the existing single precision data. Y A vector providing the Y components of the vertices to be appended. If the DOUBLE property is non-zero, the data is converted to double precision and is appended to the existing double precision data. Otherwise it is converted to single precision floating point and appended to the existing single precision data. Z A vector providing the Z components of the vertices to be appended. If the DOUBLE property is non-zero, the data is converted to double precision and is appended to the existing double precision data. Otherwise it is converted to single precision floating point and appended to the existing single precision data. Keywords XRANGE Set this keyword to a named variable that upon return contains a two-element vector, [xmin, xmax], representing the X range of the modification to the region. The reported range accounts for the last vertex in the region before the append occurred, as well as all vertices appended. This data is returned in double-precision floating-point. YRANGE Set this keyword to a named variable that upon return contains a two-element vector, [ymin, ymax], representing the Y range of the modification to the region. The reported range accounts for the last vertex in the region before the append occurred, as well as all vertices appended. This data is returned in double-precision floating-point. ZRANGE Set this keyword to a named variable that upon return contains a two-element vector, [zmin, zmax], representing the Z range of the modification to the region. The reported range accounts for the last vertex in the region before the append occurred, as well as all vertices appended. This data is returned in double-precision floating-point. IDLANROI::CLEANUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDLanROI::Cleanup The IDLanROI::Cleanup procedure method performs all cleanup for a region of interest object. Note Cleanup methods are special life cycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass. Syntax OBJ_DESTROY, Obj or Obj­>[IDLanROI::]Cleanup (In a subclass' Cleanup method only) Arguments None. Keywords None. IDLANROI::COMPUTEGEOMETRY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLanROI::ComputeGeometry The IDLanROI::ComputeGeometry function method computes the geometrical values for area, perimeter, and/or centroid of the region. Syntax Result = Obj­>[IDLanROI::]ComputeGeometry( [, AREA=variable] [, CENTROID=variable] [, PERIMETER=variable] [, SPATIAL_OFFSET=vector] [, SPATIAL_SCALE=vector] ) Return Value Result This function method returns a 1 for success, or a 0 for failure. Each computed value is returned in the variable name assigned to each keyword. Arguments None. Keywords AREA Set this keyword to a named variable that upon return contains a double-precision floating-point value representing the area of the region. Interior regions (holes) return a negative area. CENTROID Set this keyword to a named variable that upon return contains a double-precision floating-point value representing the centroid for the region. If the TYPE of the region is 0 (points), the centroid is computed as the average of each of the vertices in the region. If the TYPE of the region is 1 (path), the centroid is computed as the weighted average of each of the midpoints of the lines in the region. Weights are proportional to the length of the lines. If the TYPE of the region is 2 (polygon), the centroid is computed as a weighted average of the centroids of the polygons making up the ROI (interior centroids use negative weights). Weights are proportional to the polygon area. PERIMETER Set this keyword to a named variable that upon return contains a double-precision floating-point value representing the perimeter of the region. SPATIAL_OFFSET Set this keyword to a two or three-element vector, [tx, ty] or [tx, ty, tz], representing the spatial calibration offset factors to be applied for the geometry calculations. The value of SPATIAL_SCALE is applied before the spatial offset values are applied. The default is [0.0, 0.0, 0.0]. IDL converts and maintains this value in double- precision floating-point. SPATIAL_SCALE Set this keyword to a two or three-element vector, [sx, sy] or [sx, sy, sz], representing the spatial calibration scaling factors to be applied for the geometry calculations. The spatial calibration scale is applied first, then the value of SPATIAL_OFFSET is applied. The default is [1.0, 1.0, 1.0]. IDL converts and maintains this value in double-precision floating-point. IDLANROI::COMPUTEMASK [Previous Routine] [Next Routine] [List of Routines] NAME: IDLanROI::ComputeMask The IDLanROI::ComputeMask function method prepares a two-dimensional mask for the region. Syntax Result = Obj­>[IDLanROI::]ComputeMask( [, INITIALIZE={ ­1 | 0 | 1 }] [, DIMENSIONS=[xdim, ydim]] | [, MASK_IN=array] [, LOCATION=[x, y [, z]]] [, MASK_RULE={ 0 | 1 | 2 }] [, PLANE_NORMAL=[x, y, z]] [, PLANE_XAXIS=[x,y,z]] ) Return Value Result The return value is a two-dimensional array of bytes whose values range from 0 to 255. The mask is computed by applying the following formula to the current mask for each mask point contained within the ROI: Mout = MAX(MIN( 0, (Mroi*Ext) + Min), 255) where Mroi is 255 and Ext is 1 for points within an exterior region and ­1 for points within an interior region. If the TYPE of the region is 0 (points), a single mask pixel is set for each region vertex that falls within the bounds of the mask. If the TYPE of the region is 1 (path), one-pixel-wide line segments are set within the mask. If the TYPE of the region is 2 (closed polygon), a mask pixel is set if that pixel is on the plane of a region, and the pixel falls within the region (according to the MASK_RULE). Arguments None. Keywords DIMENSIONS Set this keyword to a two-element vector, [xdim, ydim], specifying the requested dimensions of the returned mask. If MASK_IN is provided, the value of this keyword is ignored and the dimensions of that mask are used. Otherwise, the default dimensions are [100, 100]. INITIALIZE Set this keyword to indicate how the mask should be initialized. Valid values include: * ­1 = The mask is not initialized. This option is useful when updating an already existing mask. This is the default if the MASK_IN keyword is set. * 0 = The mask is initialized so that each pixel is set to 0. This is the default if the MASK_IN keyword is not set. * 1 = The mask is initialized so that each pixel is set to 255. LOCATION Set this keyword to a vector of the form [X, Y[, Z]] specifying the location of the origin of the mask. The default is [0, 0, 0]. IDL converts and maintains this value in double-precision floating-point. MASK_IN Set this keyword to a two-dimensional array representing a mask that is already allocated and to be updated for this region. If this keyword is provided, the data portion of this variable is grabbed and used in the returned value (an implicit NO_COPY). If this keyword is not provided, a mask is allocated by default to match the dimensions specified via the DIMENSIONS keyword. MASK_RULE Set this keyword to an integer specifying the rule used to determine whether a given pixel should be set within the mask. Valid values include: * 0 = Boundary only. All pixels falling on a region's boundary are set. * 1 = Interior only. All pixels falling within the region's boundary, but not on the boundary, are set. * 2 = Boundary + Interior. All pixels falling on or within a region's boundary are set. PLANE_NORMAL Set this keyword to a three-element vector, [x, y, z], specifying the normal vector for the plane on which the mask is to be computed. The default is [0, 0, 1]. PLANE_XAXIS Set this keyword to a three-element vector, [x, y, z], specifying the direction vector along which each row of mask pixels is to be computed (starting at LOCATION). The default is [1, 0, 0]. IDLANROI::CONTAINSPOINTS [Previous Routine] [Next Routine] [List of Routines] NAME: IDLanROI::ContainsPoints The IDLanROI::ContainsPoints function method determines whether the given data coordinates are contained within the closed polygon region. Syntax Result = Obj­>[IDLanROI::]ContainsPoints( X [, Y [, Z]] ) Return Value The return value is a vector of values, one per provided point, indicating whether that point is contained. Valid values within this return vector include: * 0 = Exterior. The point lies strictly out of bounds of the ROI. * 1 = Interior. The point lies strictly inside the bounds of the ROI. * 2 = On edge. The point lies on an edge of the ROI boundary. * 3 = On vertex. The point matches a vertex of the ROI. A point is considered to be exterior if: * the point falls within the boundary of an interior region (hole). * the point does not lie in the plane of the region. * the region TYPE property is set to 0 (points) or 1 (path). Arguments X A vector providing the X components of the points to be tested. If the Y and Z arguments are not specified, X must be a two-dimensional array with the leading dimension either 2 or 3 ([2,*] or [3,*]), in which case, X[0,*] represents the X values, X[1,*] represents the Y values, and X[2,*] represents the Z values. Y A vector providing the Y components of the points to be tested. Z A scalar or vector providing the Z component(s) of the points to be tested. If not provided, the Z components default to 0.0. Keywords None. IDLANROI::GETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLanROI::GetProperty The IDLanROI::GetProperty procedure method retrieves the value of a property or group of properties for the region. Syntax Obj­>[IDLanROI::]GetProperty [, ALL=variable] [, N_VERTS=variable] [, ROI_XRANGE=variable] [, ROI_YRANGE=variable] [, ROI_ZRANGE=variable] Arguments None. Keywords Any keyword to IDLanROI::Init followed by the word (Get) can be retrieved using IDLanROI::GetProperty. In addition, the following keywords are available: ALL Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the properties associated with the state of this object. State information about the object includes things like block size, type, etc., but not vertex data. Note The fields in this structure may change in subsequent releases of IDL. N_VERTS Set this keyword to a named variable that will contain the number of vertices currently being used by the region. ROI_XRANGE Set this keyword to a named variable. Upon return, ROI_XRANGE contains a two- element double-precision floating-point vector of the form [xmin, xmax] that specifies the range of X data coordinates covered by the region. ROI_YRANGE Set this keyword to a named variable. Upon return, ROI_YRANGE contains a two- element double-precision floating-point vector of the form [ymin, ymax] that specifies the range of Y data coordinates covered by the region. ROI_ZRANGE Set this keyword to a named variable. Upon return, ROI_ZRANGE contains a two- element double-precision floating-point vector of the form [zmin, zmax] that specifies the range of Z data coordinates covered by the region. IDLANROI::INIT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLanROI::Init The IDLanROI::Init function method initializes a region of interest object. Note Init methods are special life cycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass. Syntax Obj = OBJ_NEW( 'IDLanROI' [, X [, Y [, Z ]]] [, BLOCKSIZE{Get, Set}=vertices] [, DATA{Get, Set}=array] [, /DOUBLE{Get, Set}] [, /INTERIOR{Get, Set}] [, TYPE{Get}={ 0 | 1 | 2 }] ) or Result = Obj -> [IDLanROI::]Init( [X [, Y [, Z ]]] ) (Only in a subclass' Init method.) Note Keywords can be used in either form. They are omitted in the second form for brevity. Arguments X A vector providing the X components of the vertices for the region. If the Y and Z arguments are not specified, X must be a two-dimensional array with the leading dimension either 2 or 3 ([2,*] or [3,*]), in which case, X[0,*] represents the X values, X[1,*] represents the Y values, and X[2,*] represents the Z values. The value for this argument is double-precision floating-point if the DOUBLE keyword is set or the inputted value is of type DOUBLE. Otherwise, it is converted to single-precision floating-point. Y A vector providing the Y components of the vertices. The value for this argument is double-precision floating-point if the DOUBLE keyword is set or the inputted value is of type DOUBLE. Otherwise, it is converted to single-precision floating-point. Z A scalar or vector providing the Z component(s) of the vertices. If not provided, Z values default to 0.0. The value for this argument is double-precision floating-point if the DOUBLE keyword is set or the inputted value is of type DOUBLE. Otherwise, it is converted to single-precision floating-point. Keywords BLOCK_SIZE (Get, Set) Set this keyword to the number of vertices to allocate per block as needed for the region. When additional vertices are required, an additional block is allocated. The default is 100. DATA (Get, Set) Set this keyword to a 2 x n or a 3 x n array which defines, respectively, the 2D or 3D vertex data. DATA is equivalent to the optional arguments, X, Y, and Z. This property is stored as double precision floating point values if the argument variable is of type DOUBLE or if the DOUBLE property is non-zero. Otherwise it is stored as single precision floating point. DOUBLE (Get, Set) Set this keyword to a non-zero value to indicate that data should be stored in this object in double precision floating point. Set this keyword to zero to indicate that the data should be stored in single precision floating point, which is the default. The DOUBLE property controls the precision used for storing the data in the AppendData, Init, and ReplaceData methods via the X, Y, and Z arguments and in SetProperty method via the DATA keyword. IDL converts any data already stored in the object to the requested precision, if necessary. Note that this keyword does not need to be set if any of the X, Y, or Z arguments or the DATA parameters are of type DOUBLE. However, setting this keyword may be desirable if the data consists of large integers that cannot be accurately represented in single precision floating point. This property is also automatically set to one if any of the X, Y or Z arguments or the DATA parameter is stored using a variable of type DOUBLE. INTERIOR (Get, Set) Set this keyword to mark this region as an interior region (i.e., a region treated as a hole). By default, the region is treated as an exterior region. TYPE (Get) Set this keyword to indicate the type of the region. The TYPE keyword determines how computational operations, such as mask generation, are performed. Valid values include: * 0 = points * 1 = path * 2 = closed polygon (the default) IDLANROI::REMOVEDATA [Previous Routine] [Next Routine] [List of Routines] NAME: IDLanROI::RemoveData The IDLanROI::RemoveData procedure method removes vertices from the region. Syntax Obj­>[IDLanROI::]RemoveData[, COUNT=vertices] [, START=index] [, XRANGE=variable] [, YRANGE=variable] [, ZRANGE=variable] Arguments None. Keywords COUNT Set this keyword to the number of vertices to remove. The default is one vertex. START Set this keyword to an index (into the region's current vertex list) where the removal is to begin. By default, the final vertex is removed. XRANGE Set this keyword to a named variable that upon return contains a two-element vector, [xmin, xmax], that represents the X range of the modification to the region. The reported range accounts for the vertex just before the removal (if any), the vertex just after the removal (if any), and the removed vertices. This data is returned in double- precision floating-point. YRANGE Set this keyword to a named variable that upon return contains a two-element vector, [ymin, ymax], that represents the Y range of the modification to the region. The reported range accounts for the vertex just before the removal (if any), the vertex just after the removal (if any), and the removed vertices. This data is returned in double- precision floating-point. ZRANGE Set this keyword to a named variable that upon return contains a two-element vector, [zmin, zmax], that represents the Z range of the modification to the region. The reported range accounts for the vertex just before the removal (if any), the vertex just after the removal (if any), and the removed vertices. This data is returned in double- precision floating-point. IDLANROI::REPLACEDATA [Previous Routine] [Next Routine] [List of Routines] NAME: IDLanROI::ReplaceData The IDLanROI::ReplaceData procedure method replaces vertices in the region with alternate values. The number of replacement values need not match the number of values being replaced. Syntax Obj­>[IDLanROI::]ReplaceData, X[, Y[, Z]] [, START=index] [, FINISH=index] [, XRANGE=variable] [, YRANGE=variable] [, ZRANGE=variable] Arguments X A vector providing the X components of the new replacement vertices. If the Y and Z arguments are not specified, X must be a two-dimensional array with the leading dimensions either 2 or 3 ([2, *] or [3, *]), in which case, X[0, *] represents the X values, X[1, *] represents the Y values, and X[2, *] represents the Z values. If the DOUBLE property is non-zero, the data is converted to double precision and is appended to the existing double precision data. Otherwise it is converted to single precision floating point and appended to the existing single precision data. Y A vector providing the Y components of the new replacement vertices. If the DOUBLE property is non-zero, the data is converted to double precision and is appended to the existing double precision data. Otherwise it is converted to single precision floating point and appended to the existing single precision data. Z A vector providing the Z components of the new replacement vertices. If the DOUBLE property is non-zero, the data is converted to double precision and is appended to the existing double precision data. Otherwise it is converted to single precision floating point and appended to the existing single precision data. Keywords FINISH Set this keyword to the index of the region's current subregion vertex list where the replacement ends. If the START keyword value is 0, the default FINISH is given by FINISH = ((START + N_NEW ­ 1) MOD N_OLD) where N_NEW is the number of replacement vertices provided via the [X, Y, Z] arguments and N_OLD is the number of vertices (prior to replacement) in the current subregion. If the START keyword is not set or is negative, the default FINISH is given by FINISH = N_OLD ­ 1 FINISH may be less than START in which case the vertices, including and following START and the vertices preceding and including FINISH, are replaced with the new values. START Set this keyword to an index of the region's current subregion vertex list where the replacement begins. If the FINISH keyword value is 0, the default START is given by START = ((FINISH ­ N_NEW + 1) MOD N_OLD) where N_NEW is the number of replacement vertices provided via the [X, Y, Z] arguments and N_OLD is the number of vertices (prior to replacement) in the current subregion. If the FINISH keyword is not set (or negative), the default START is clamped to 0 and is given by N_OLD ­ N_NEW XRANGE Set this keyword to a named variable that upon return contains a two-element vector, [xmin, xmax], representing the X range of the modification to the region. The reported range accounts for the replaced vertices, the vertex just before the replacement (if any), the vertex just after the replacement (if any), and the new replacement vertices. This data is returned in double-precision floating-point. YRANGE Set this keyword to a named variable that upon return contains a two-element vector, [ymin, ymax], representing the Y range of the modification to the region. The reported range accounts for the replaced vertices, the vertex just before the replacement (if any), the vertex just after the replacement (if any), and the new replacement vertices. This data is returned in double-precision floating-point. ZRANGE Set this keyword to a named variable that upon return contains a two-element vector, [zmin, zmax], representing the Z range of the modification to the region. The reported range accounts for the replaced vertices, the vertex just before the replacement (if any), the vertex just after the replacement (if any), and the new replacement vertices. This data is returned in double-precision floating-point. IDLANROI::ROTATE [Previous Routine] [Next Routine] [List of Routines] NAME: IDLanROI::Rotate The IDLanROI::Rotate procedure method modifies the vertices for the region by applying a rotation. Syntax Obj­>[IDLanROI::]Rotate, Axis, Angle [, CENTER=[x, y[, z]]] Arguments Axis A three-element vector of the form [x, y, z] describing the axis about which the region is to be rotated. Angle The angle, measured in degrees, by which the rotation is to occur. Keywords CENTER Set this keyword to a two or three-element vector of the form [x, y], or [x, y, z] specifying the center of rotation. The default is [0, 0, 0]. IDL converts and applies this data in double-precision floating-point. IDLANROI::SCALE [Previous Routine] [Next Routine] [List of Routines] NAME: IDLanROI::Scale The IDLanROI::Scale procedure method modifies the vertices for the region by applying a scale. Syntax Obj­>[IDLanROI::]Scale, Sx[, Sy[, Sz]] Arguments Sx The X scale factor. If the Sy and Sz arguments are not specified, Sx must be a two or three-element vector, in which case Sx[0] represents the scale in X, Sx[1] represents the scale in Y, Sx[2] represents the scale in Z. IDL converts and applies this data in double-precision floating-point. Sy The Y scale factor. IDL converts and applies this data in double-precision floating- point. Sz The Z scale factor. IDL converts and applies this data in double-precision floating- point. Keywords None. IDLANROI::SETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLanROI::SetProperty The IDLanROI::SetProperty procedure method sets the value of a property or group of properties for the region. Syntax Obj­>[IDLanROI::]SetProperty Arguments None. Keywords Any keywords to IDLanROI::Init followed by the word (Set) can be set using IDLanROI::SetProperty. IDLANROI::TRANSLATE [Previous Routine] [Next Routine] [List of Routines] NAME: IDLanROI::Translate The IDLanROI::Translate procedure method modifies the vertices for the region by applying a translation. Syntax Obj­>[IDLanROI::]Translate, Tx[, Ty[, Tz]] Arguments Tx The X translation factor. If the Ty and Tz arguments are not specified, Tx must be a two or three-element vector, in which case Tx[0] represents translation in X, Tx[1] represents translation in Y, Tx[2] represents translation in Z. IDL converts and applies this data in double-precision floating-point. Ty The Y translation factor. IDL converts and applies this data in double-precision floating-point. Tz The Z translation factor. IDL converts and applies this data in double-precision floating-point. Keywords None. IDLANROIGROUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDLanROIGroup The IDLanROIGroup object class is an analytical representation of a group of regions of interest. Superclasses This class is a subclass of IDL_Container. Subclasses This class is a superclass of IDLgrROIGroup. Creation See IDLanROIGroup::Init. Methods Intrinsic Methods The IDLanROIGroup class has the following methods: * IDLanROIGroup::Add * IDLanROIGroup::Cleanup * IDLanROIGroup::ComputeMask * IDLanROIGroup::ComputeMesh * IDLanROIGroup::ContainsPoints * IDLanROIGroup::GetProperty * IDLanROIGroup::Init * IDLanROIGroup::Rotate * IDLanROIGroup::Scale * IDLanROIGroup::Translate Inherited Methods This class inherits the following methods: * IDL_Container::Count * IDL_Container::Get * IDL_Container::IsContained * IDL_Container::Move * IDL_Container::Remove IDLANROIGROUP::ADD [Previous Routine] [Next Routine] [List of Routines] NAME: IDLanROIGroup::Add The IDLanROIGroup::Add procedure method adds a region to the region group. Only objects of the IDLanROI class may be added to the group. The regions in the group must all be of the same type: all points, all paths, or all polygons. Syntax Obj­>[IDLanROIGroup::]Add, ROI Arguments ROI A reference to an instance of the IDLanROI object class representing the region of interest to be added to the group. Keywords Accepts all keywords accepted by the IDL_Container::Add method. IDLANROIGROUP::CLEANUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDLanROIGroup::Cleanup The IDLanROIGroup::Cleanup procedure method performs all cleanup for a region of interest group object. Note Cleanup methods are special life cycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass. Syntax OBJ_DESTROY, Obj or Obj­>[IDLanROIGroup::]Cleanup (In a subclass' Cleanup method only.) Arguments None. Keywords None. IDLANROIGROUP::COMPUTEMASK [Previous Routine] [Next Routine] [List of Routines] NAME: IDLanROIGroup::ComputeMask The IDLanROIGroup::ComputeMask function method prepares a two-dimensional mask for this group of regions. Syntax Result = Obj­>[IDLanROIGroup::]ComputeMask( [, INITIALIZE={ ­1 | 0 | 1 }] [, DIMENSIONS=[xdim, ydim]] | [, MASK_IN=array] [, LOCATION=[x, y [, z]]] [, MASK_RULE={ 0 | 1 | 2 }] ) Return Value Result The return value is a two-dimensional array of bytes whose values range from 0 to 255. The mask is computed by applying the following formula to the current mask for each mask point contained within the ROI: Mout = MAX(MIN(0, (Mroi*Ext) + Min), 255) where Mroi is 255 and Ext is 1 for points within an exterior region and ­1 for points within an interior region. If the TYPE of the contained regions is 0 (points), a single mask pixel is set for each region vertex that falls within the bounds of the mask. If the TYPE of the contained regions is 1 (path), each pixel along the paths of the regions is set if it falls within the mask. If the TYPE of the region is 2 (closed polygon), a mask pixel is set if that pixel is on the plane of a contained region, and the pixel falls within that region (according to the MASK_RULE). Arguments None. Keywords DIMENSIONS Set this keyword to a two-element vector, [xdim, ydim], specifying the requested dimensions of the returned mask. If MASK_IN is provided, the value of this keyword is ignored, and the dimensions of that mask are used. Otherwise, the default dimensions are [100, 100]. INITIALIZE Set this keyword to indicate how the mask should be initialized. Valid values include: * ­1 = The mask is not initialized; the default if the MASK_IN keyword is set. This option is useful when updating an already existing mask. * 0 = The mask is initialized with each pixel set to 0; the default if the MASK_IN keyword is not set. * 1 = The mask is initialized with each pixel set to 255. LOCATION Set this keyword to a vector of the form [X, Y[, Z]] specifying the location of the origin of the mask. The default is [0, 0, 0]. MASK_IN Set this keyword to a two-dimensional array representing a mask that is already allocated and to be updated for this region. If this keyword is provided, the data portion of this variable is grabbed and used in the returned value (an implicit NO_COPY). If this keyword is not provided, a mask is allocated by default to match the dimensions specified via the DIMENSIONS keyword. MASK_RULE Set this keyword to an integer specifying the rule used to determine whether a given pixel should be set within the mask. Valid values include: * 0 = Boundary Only. All pixels falling on a region's boundary are set. * 1 = Interior Only. All pixels falling within the region's boundary, but not on the boundary, are set. * 2 = Boundary + Interior. All pixels falling on or within a region's boundary are set. PLANE_NORMAL Set this keyword to a three-element vector, [x, y, z], specifying the normal vector for the plane on which the mask is to be computed. The default is [0, 0, 1]. PLANE_XAXIS Set this keyword to a three-element vector, [x, y, z], specifying the direction vector along which each row of mask pixels is to be computed (starting at LOCATION). The default is [1, 0, 0]. IDLANROIGROUP::COMPUTEMESH [Previous Routine] [Next Routine] [List of Routines] NAME: IDLanROIGroup::ComputeMesh The IDLanROIGroup::ComputeMesh function method triangulates a surface mesh with optional capping from the stack of regions contained within this group. Note The contained regions may be concave. However, this method will fail under the following conditions: * The region group contains fewer than two regions. * The TYPE property of the contained regions is 0 (points) or 1 (path). * Any of the contained regions are not simple (i.e., a region is self-intersecting). * The region group contains interior regions (holes). * More than one region lies on the same plane (i.e., the region group contains branches). Each region pair is normalized by perimeter and the triangulation is computed by walking the contours in parallel, keeping the normalized progress along each contour in sync. The returned triangulation minimizes the mesh surface area. Each vertex may appear only once in the output, and the resulting polygon mesh is solid with outward facing normals computed via the right-hand rule. If capping is requested, it is computed using the IDLgrTessellator on the top and bottom regions, and/or the regions on either side of an inter-slice gap. Syntax Result = Obj->[IDLanROIGroup::]ComputeMesh( Vertices, Conn [, CAPPED={ 0 | 1 | 2}] [, SURFACE_AREA=variable] ) Return Value Result The return value of this function method is the number of triangles generated if the surface mesh triangulation is successful, or zero if unsuccessful. Arguments Vertices An output [3, n] array of vertices. If all regions in the group are defined with single precision vertices (DOUBLE property is zero), then IDL returns a single precision floating point array. Otherwise, if any of the regions in the group are defined with double precision vertices (DOUBLE property is non-zero), then IDL returns a double precision floating point array. Conn An output polygon mesh connectivity array. Keywords CAPPED Set this keyword to a value to indicate whether flat caps are to be computed at the top-most or bottom-most regions (as selected by a counter-clockwise rule), or at the regions on either side of an inter-slice gap. The value of this keyword is a bit-wise OR of the values shown below. For example, to cap the top-most and bottom-most regions only, set the CAPPED keyword to 3. The default is 0 (no caps). * 0 = no caps * 1 = cap the top-most region * 2 = cap the bottom-most region SURFACE_AREA Set this keyword to a named variable that upon return contains the overall surface area of the computed triangulation. This value was minimized in the computation of the triangulation. IDL returns this value in a double-precision floating-point variable. IDLANROIGROUP::CONTAINSPOINTS [Previous Routine] [Next Routine] [List of Routines] NAME: IDLanROIGroup::ContainsPoints The IDLanROIGroup::ContainsPoints function method determines whether the given points (in data coordinates) are contained within this region group. The regions within this group must have a TYPE of 2 (closed polygon) and must fall on parallel planes for successful containment testing to occur. For each point to be tested: * If the point lies directly on one of the region planes, it is tested for containment within each of the regions that fall on that plane. * If the point lies between two of the region planes, it is projected onto the nearest region plane, and tested for containment within each of the regions on that plane. * If the point lies above or below the stack of parallel region planes, the point will be considered to be exterior to the region group. On a given plane, a point will be considered to be exterior if either of the following conditions are true: * The point does not fall within any of the regions on that plane. * The point falls within as many or more holes than non-hole regions on that plane. Syntax Result = Obj­>[IDLanROIGroup::]ContainsPoints( X[, Y[, Z]] ) Return Value The return value is a vector of values, one per provided point, indicating whether that point is contained. Valid values within this return vector include: * 0 = Exterior. The point lies strictly outside the bounds of the ROI. * 1 = Interior. The point lies strictly inside the bounds of the ROI. * 2 = On Edge. The point lies on an edge of the ROI boundary. * 3 = On Vertex. The point matches a vertex of the ROI. Arguments X A vector providing the X components of the points to be tested. If the Y and Z arguments are not specified, X must be a two-dimensional array with the leading dimension either 2 or 3 ([2,*] or [3,*]), in which case, X[0,*] represents the X values, X[1,*] represents the Y values, and X[2,*] represents the Z values. Y A vector providing the Y components of the points to be tested. Z A scalar or vector providing the Z components of the points to be tested. If not provided, the Z components default to 0.0. Keywords None. IDLANROIGROUP::GETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLanROIGroup::GetProperty The IDLanROIGroup::Get Property procedure method retrieves the value of a property or group of properties for the region group. Syntax Obj­>[IDLanROIGroup::]GetProperty[, ALL=variable] [, ROIGROUP_XRANGE=variable] [, ROIGROUP_YRANGE=variable] [, ROIGROUP_ZRANGE=variable] Arguments None. Keywords Any keyword to IDLanROIGroup::Init followed by the word (Get) can be retrieved using IDLanROIGroup::GetProperty. In addition, the following keywords are available: ALL Set this keyword to a named variable. Upon return, ALL contains an anonymous structure with the values of all of the properties associated with the state of this object. Note The fields in this structure may change in subsequent releases of IDL. ROIGROUP_XRANGE Set this keyword to a named variable. Upon return, ROIGROUP_XRANGE contains a two-element double-precision floating-point vector of the form [xmin, xmax] that specifies the range of X data coordinates covered by the region. ROIGROUP_YRANGE Set this keyword to a named variable. Upon return, ROIGROUP_YRANGE contains a two-element double-precision floating-point vector of the form [ymin, ymax] that specifies the range of Y data coordinates covered by the region. ROIGROUP_ZRANGE Set this keyword to a named variable. Upon return, ROIGROUP_ZRANGE contains a two-element double-precision floating-point vector of the form [zmin, zmax] that specifies the range of Z data coordinates covered by the region. IDLANROIGROUP::INIT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLanROIGroup::Init The IDLanROIGroup::Init function method initializes a region of interest group object. Note Init methods are special life cycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass. Syntax Obj = OBJ_NEW('IDLanROIGroup') or Result = Obj­>[IDLanROIGroup::]Init( ) (Only in a subclass' Init method.) Arguments None. Keywords None. IDLANROIGROUP::ROTATE [Previous Routine] [Next Routine] [List of Routines] NAME: IDLanROIGroup::Rotate The IDLanROIGroup::Rotate procedure method modifies the vertices for all regions within the group by applying a rotation. Syntax Obj­>[IDLanROIGroup::]Rotate, Axis, Angle[, CENTER=[ x, y[, z ]] ] Arguments Axis A three-element vector of the form [x, y, z] describing the axis about which the region group is to be rotated. Angle The angle, measured in degrees, by which to rotate the ROI group. Keywords CENTER Set this keyword to a two or three-element vector of the form [x, y], or [x, y, z] specifying the center of rotation. The default is [0, 0, 0]. IDL converts and applies this data in double-precision floating-point. IDLANROIGROUP::SCALE [Previous Routine] [Next Routine] [List of Routines] NAME: IDLanROIGroup::Scale The IDLanROIGroup::Scale procedure method modifies the vertices for the region by applying a scale. Syntax Obj­>[IDLanROIGroup::]Scale, Sx[, Sy[, Sz]] Arguments Sx The X scale factor. If the Sy and Sz arguments are not specified, Sx must be a two or three-element vector, in which case Sx[0] represents the scale in X, Sx[1] represents the scale in Y, Sx[2] represents the scale in Z. IDL converts and applies this data in double-precision floating-point. Sy The Y scale factor. IDL converts and applies this data in double-precision floating- point. Sz The Z scale factor. IDL converts and applies this data in double-precision floating- point. Keywords None. IDLANROIGROUP::TRANSLATE [Previous Routine] [Next Routine] [List of Routines] NAME: IDLanROIGroup::Translate The IDLanROIGroup::Translate procedure method modifies the vertices of all regions within the group by applying a translation. Syntax Obj­>[IDLanROIGroup::]Translate, Tx[, Ty[, Tz]] Arguments Tx The X translation factor. If the Ty and Tz arguments are not specified, Tx must be a two or three-element vector, in which case Tx[0] represents translation in X, Tx[1] represents translation in Y, Tx[2] represents translation in Z. IDL converts and applies this data in double-precision floating-point. Ty The Y translation factor. IDL converts and applies this data in double-precision floating-point. Tz The Z translation factor. IDL converts and applies this data in double-precision floating-point. Keywords None. IDLFFDICOM [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffDICOM An IDLffDICOM object contains the data for one or more images embedded in a DICOM Part 10 file. The API to the IDLffDICOM object provides accessor methods to the basic data elements of a DICOM file, namely the group/element tag, value representation, length, and data values. Additional methods deal with the file header preamble, data dictionary description for individual elements, and embedded sequences of elements. Most methods take a DICOM group/element tag as a parameter. An alternative parameter to the DICOM tag in some methods is the reference. A reference value is a LONG integer that is unique to each element in the DICOM object. This value can be used to directly access a specific element and to differentiate between elements in the DICOM file that have the same group/element tag. Valid reference values are always positive. Superclasses This class has no superclasses. Subclasses This class has no subclasses. Creation See IDLffDICOM::Init. Methods * IDLffDICOM::Cleanup * IDLffDICOM::DumpElements * IDLffDICOM::GetChildren * IDLffDICOM::GetDescription * IDLffDICOM::GetElement * IDLffDICOM::GetGroup * IDLffDICOM::GetLength * IDLffDICOM::GetParent * IDLffDICOM::GetPreamble * IDLffDICOM::GetReference * IDLffDICOM::GetValue * IDLffDICOM::GetVR * IDLffDICOM::Init * IDLffDICOM::Read * IDLffDICOM::Reset IDL DICOM v3.0 Conformance Summary Introduction This section is an abbreviated DICOM conformance statement for IDL, and specifies the compliance of Research Systems IDL DICOM file reading support to the DICOM v3.0 standard. As described in the DICOM Standard PS 3.2 (Conformance), the purpose of this document is to outline the level of conformance to the DICOM standard and to enumerate the supported DICOM Service Classes, Information Objects, and Communications Protocols supported by this implementation. IDL does not contain or support any of the DICOM services such as Storage, Query/Retrieve, Print, Verification, etc., so there will be no conformance claims relating to these services and no mention of any Application Entities for these services. Communications Protocol profiles will also be absent from this document for the same reasons. The remainder of this document will describe how IDL handles the various Information Objects it is capable of reading. Reading of DICOM Part 10 files IDL supports reading files that conform to the DICOM Standard PS 3.10 DICOM File Format. This format provides a means to encapsulate in a file the Data Set representing a SOP (Service Object Pair) Instance related to a DICOM IOD (Information Object Definition). Files written to disk in this DICOM File Format will be referred to as DICOM Part 10 files for the remainder of this document. Note that IDL does NOT support the writing of files in this DICOM File Format, only reading. Encapsulated Transfer Syntaxes Supported IDL supports reading DICOM Part 10 files whose contents have been written using the following Transfer Syntaxes. The Transfer Syntax UID is in the file's DICOM Tag field (0002,0010). UID Value UID Name 1.2.840.10008.1.2 Implicit VR Little Endian: Default Transfer Syntax for DICOM 1.2.840.10008.1.2.1 Explicit VR Little Endian 1.2.840.10008.1.2.2 Explicit VR Big Endian Table A-1: Encapsulated Transfer Syntaxes Supported Encapsulated Transfer Syntaxes NOT Supported IDL does NOT support reading DICOM Part 10 files whose contents have compressed data that has been written using the following Transfer Syntaxes. IDL will NOT be able to access the data element (DICOM Tag field (7FE0,0010)) of files with these types of compressed data. The Transfer Syntax UID is in the file's DICOM Tag field (0002,0010). UID Value UID Name 1.2.840.10008.1.2.4.50 JPEG Baseline (Process 1): Default Transfer Syntax for Lossy JPEG 8 Bit Image Compression 1.2.840.10008.1.2.4.51 JPEG Extended (Process 2 & 4): Default Transfer Syntax for Lossy JPEG 12 Bit Image Compression (Process 4 only) 1.2.840.10008.1.2.4.52 JPEG Extended (Process 3 & 5) 1.2.840.10008.1.2.4.53 JPEG Spectral Selection, Non-Hierarchical (Process 6 & 8) 1.2.840.10008.1.2.4.54 JPEG Spectral Selection, Non-Hierarchical (Process 7 & 9) 1.2.840.10008.1.2.4.55 JPEG Full Progression, Non-Hierarchical (Process 10 & 12) 1.2.840.10008.1.2.4.56 JPEG Full Progression, Non-Hierarchical (Process 11 & 13) 1.2.840.10008.1.2.4.57 JPEG Lossless, Non-Hierarchical (Process 14) 1.2.840.10008.1.2.4.58 JPEG Lossless, Non-Hierarchical (Process 15) 1.2.840.10008.1.2.4.59 JPEG Extended, Hierarchical (Process 16 & 18) 1.2.840.10008.1.2.4.60 JPEG Extended, Hierarchical (Process 17 & 19) 1.2.840.10008.1.2.4.61 JPEG Spectral Selection, Hierarchical (Process 20 & 22) 1.2.840.10008.1.2.4.62 JPEG Spectral Selection, Hierarchical (Process 21 & 23) 1.2.840.10008.1.2.4.63 JPEG Full Progression, Hierarchical (Process 24 & 26) 1.2.840.10008.1.2.4.64 JPEG Full Progression, Hierarchical (Process 25 & 27) 1.2.840.10008.1.2.4.65 JPEG Lossless, Hierarchical (Process 28) Table A-2: Encapsulated Transfer Syntaxes NOT Supported UID Value UID Name 1.2.840.10008.1.2.4.66 JPEG Lossless, Hierarchical (Process 29) 1.2.840.10008.1.2.4.70 JPEG Lossless, Non-Hierarchical, First-Order Prediction (Process 14 [Selection Value 1]): Default Transfer Syntax for Lossless JPEG Image Compression 1.2.840.10008.1.2.5 RLE Lossless Table A-2: Encapsulated Transfer Syntaxes NOT Supported Encapsulated SOP Classes Supported IDL supports reading DICOM Part 10 files whose contents encapsulate the data of the following SOP Classes. The SOP Class UID is in the file's DICOM Tag field (0008,0016). UID Value UID Name 1.2.840.10008.5.1.4.1.1.1 CR Image Storage 1.2.840.10008.5.1.4.1.1.2 CT Image Storage 1.2.840.10008.5.1.4.1.1.4 MR Image Storage 1.2.840.10008.5.1.4.1.1.6.1 Ultrasound Image Storage 1.2.840.10008.5.1.4.1.1.7 Secondary Capture Image Storage 1.2.840.10008.5.1.4.1.1.12.1 X-Ray Angiographic Image Storage 1.2.840.10008.5.1.4.1.1.12.2 X-Ray Radiofluoroscopic Image Storage 1.2.840.10008.5.1.4.1.1.20 Nuclear Medicine Image Storage 1.2.840.10008.5.1.4.1.1.128 Positron Emission Tomography Image Storage Table A-3: Encapsulated SOP Classes Supported Handling of odd length data elements The DICOM Standard PS 3.5 (Data Structures and Encoding) specifies that the data element values which make up a DICOM data stream must be padded to an even length. The toolkit upon which IDL's DICOM reading functionality is built strictly enforces this specification. If IDL encounters an incorrectly formed odd length data field while reading a DICOM Part 10 file it will report an error and stop the reading process. Handling of undefined VRs The VR (Value Representation) of a data element describes the data type and format of that data element's values. If IDL encounters an undefined VR while reading a DICOM Part 10 file, it will set that data element's VR to be UN (unknown). Handling of retired and private data elements Certain data elements are no longer supported under the v3.0 of the DICOM standard and are denoted as retired. Also, some DICOM implementations may require the communication of information that cannot be contained in standard data elements, and thus create private data elements to contain such information. Retired and private data elements should pose no problem to IDL's DICOM Part 10 file reading capability. When IDL encounters a retired or private data element tag during reading a DICOM Part 10 file, it will treat it just like any standard data element: read the data value and allow it to be accessed via the IDLffDICOM::GetValue method. IDLFFDICOM::CLEANUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffDICOM::Cleanup This method destroys the IDLffDICOM object. Note Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: if you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass. Syntax OBJ_DESTROY, Obj or OBJ -> [IDLffDICOM::]Cleanup(Only in subclass' Cleanup method.) Arguments None Keywords None Examples ; create a DICOM object, read a DICOM file and dump its contents: obj = OBJ_NEW( 'IDLffDICOM' ) var = obj->Read(DIALOG_PICKFILE(FILTER="*")) obj->DumpElements OBJ_DESTROY, obj ; executing this statement should produce an invalid object ; reference error since obj no longer exists: obj->DumpElements IDLFFDICOM::DUMPELEMENTS [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffDICOM::DumpElements This method dumps a description of the DICOM data elements of the IDLffDICOM object to the screen or to a file. Syntax Obj -> [IDLffDICOM::]DumpElements [, Filename] Arguments Filename A scalar string that contains the full path and filename of the file to which to dump the elements. The file is written as ASCII text. Keywords None Examples The columns output by DumpElements are the element reference, the (group, element) tuple, the value representation, the description, the value length, and some of the data values. ; create a DICOM object, read a DICOM file and dump its contents: obj = OBJ_NEW( 'IDLffDICOM' ) var = obj->Read(DIALOG_PICKFILE(FILTER='*')) obj->DumpElements ; dump the contents of the current DICOM object to a file under ; Windows: obj->DumpElements, 'c:\rsi\elements.dmp' ; dump the contents of the current DICOM object to a file under ; UNIX: obj->DumpElements, '/rsi/elements.dmp' OBJ_DESTROY, obj IDLFFDICOM::GETCHILDREN [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffDICOM::GetChildren This method is used to find the member element references of a DICOM sequence. It takes as an argument a scalar reference to a DICOM element representing the parent of the sequence, and returns an array of references to the elements of the object that are members of that sequence. The scalar parent reference is possibly obtained by a previous call to GetReference or any method that generates a reference list. Any member of a sequence may also itself be the parent of another sequence. If the scalar reference argument is not the parent of a sequence, the method returns -1. Syntax array = Obj -> [IDLffDICOM::]GetChildren( Reference ) Arguments Reference This argument is a scalar reference to a DICOM element that is known to be the parent of a DICOM sequence. Keywords None Examples obj = OBJ_NEW('IDLffDICOM') read = obj->Read(DIALOG_PICKFILE(FILTER='*')) ; Get a list of references to all elements that are sequences: refs = obj->GetReference(VR='SQ') ; Cycle through the returned list and print out the immediate ; children references and descriptions of each sequence: FOR i = 0, N_ELEMENTS(refs)-1 DO BEGIN IF (refs[i] NE -1) THEN $ BEGIN children = obj->GetChildren(refs[i]) FOR j = 0, N_ELEMENTS(children)-1 DO $ BEGIN PRINT,children[j] ENDFOR ENDIF ENDFOR OBJ_DESTROY,obj IDLFFDICOM::GETDESCRIPTION [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffDICOM::GetDescription This accessor method takes optional DICOM group and element arguments and returns an array of STRING descriptions. The description is a string describing the field's contents as per the data dictionary in the DICOM specification PS 3.6. If no arguments or keywords are specified, the returned array contains the descriptions for all elements in the object. The effect of multiple keywords and parameters is to AND their results. If no DICOM elements can be found matching the search criteria, -1 will be returned. Syntax array = Obj -> [IDLffDICOM::]GetDescription( [Group [, Element]] [, REFERENCE=list of element references] ) Arguments Group Set this optional argument to the value for the DICOM group to search for, i.e. `0018'x. If this argument is omitted, then all of the DICOM array elements are returned. Element This optional argument can be specified only if the Group argument has also been specified. Set this argument to the value for the DICOM element for which to search, such as `0010'x. If this argument is omitted and the Group argument was specified, then all elements of the specified Group are returned. Keywords REFERENCE Set this keyword to a list of element reference values from which to return description values. Examples obj = OBJ_NEW('IDLffDICOM') read = obj->Read(DIALOG_PICKFILE(FILTER='*')) ; Get the description of the patient name element: arr = obj->GetDescription('0010'x,'0010'x) PRINT, arr ; Get array of all of the descriptions from the patient info group: arr = obj->GetDescription('0010'x) FOR i = 0, N_ELEMENTS(arr)-1 DO BEGIN PRINT, arr[i] ENDFOR OBJ_DESTROY, obj IDLFFDICOM::GETELEMENT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffDICOM::GetElement This accessor method takes optional DICOM group and/or element arguments and returns an array of DICOM Element numbers for those parameters. If no arguments or keywords are specified, the returned array contains Element numbers for all elements in the object. The effect of multiple keywords and parameters is to AND their results. If no matching elements can be found, the function returns -1. Syntax array = Obj -> [IDLffDICOM::]GetElement( [Group [, Element]] [, REFERENCE=list of element references] ) Arguments Group Set this optional argument to the value for the DICOM group to search for, i.e. `0018'x. If this argument is omitted, then all of the DICOM array elements are returned. Element This optional argument can be specified only if the Group argument has also been specified. Set this argument to the value for the DICOM element to search for, such as `0010'x. If this argument is omitted and the Group argument was specified, then all elements of the specified Group are returned. Keywords REFERENCE Set this keyword to a list of element reference values from which to return element number values. Examples obj = OBJ_NEW('IDLffDICOM') read = obj->Read(DIALOG_PICKFILE(FILTER='*')) ; Get references to all elements with "patient" in the description: refs = obj->GetReference(DESCRIPTION='patient') ; Get the element numbers of the elements containing "patient": FOR i = 0, N_ELEMENTS(refs)-1 DO BEGIN num = obj->GetElement(REFERENCE=refs[i]) PRINT,num ENDFOR ; Get the element numbers from the Patient Info group, 0010: elements = obj->GetElement('0010'x) PRINT, elements OBJ_DESTROY,obj IDLFFDICOM::GETGROUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffDICOM::GetGroup This accessor method takes optional DICOM group and/or element arguments and returns an array of DICOM Group numbers for those parameters. If no arguments or keywords are specified, the returned array contains Group numbers for all groups in the object. The effect of multiple keywords and parameters is to AND their results. If no matching elements can be found, the function returns -1. Syntax array = Obj -> [IDLffDICOM::]GetGroup( [Group[, Element]] [, REFERENCE=list of element references] ) Arguments Group Set this optional argument to the value for the DICOM group for which to search, such as `0018'x. If this argument is omitted, then all of the DICOM array elements are returned. Element This optional argument can be specified only if the Group argument has also been specified. Set this to the value for the DICOM element for which to search, such as `0010'x. If this argument is omitted and the Group argument was specified, then all elements of the specified Group are returned. Keywords REFERENCE Set this keyword to a list of element references from which to return group number values. Examples obj = OBJ_NEW('IDLffDICOM') read = obj->Read(DIALOG_PICKFILE(FILTER='*')) ; Get references to all elements with "patient" in the description: refs = obj->GetReference(DESCRIPTION='patient') ; Get the group numbers of the elements containing "patient": FOR i = 0, N_ELEMENTS(refs)-1 DO BEGIN num = obj->GetGroup(REFERENCE=refs[i]) PRINT, num ENDFOR ; Get the group numbers from the Patient Info group, 0010: grp = obj->GetGroup('0010'x) PRINT, grp OBJ_DESTROY,obj IDLFFDICOM::GETLENGTH [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffDICOM::GetLength This accessor method takes optional DICOM group and/or element arguments and returns an array of LONGs. The length is the field length that explicitly exists in the DICOM file, and represents the length of the element value in bytes. If no arguments or keywords are specified, the returned array contains the lengths for all elements in the object. The effect of multiple keywords and parameters is to AND their results. If no matching elements can be found, the function returns -1. Syntax array = Obj -> [IDLffDICOM::]GetLength( [Group [, Element]] [, REFERENCE=list of element references] ) Arguments Group Set this optional argument to the value for the DICOM group for which to search, such as `0018'x. If this argument is omitted, all DICOM array elements are returned. Element This optional argument can be specified only if the Group argument has also been specified. Set this to the value for the DICOM element for which to search, such as `0010'x. If this argument is omitted and the Group argument was specified, then all elements of the specified Group are returned. Keywords REFERENCE Set this keyword to a list of element references from which to return length values. Examples obj = OBJ_NEW('IDLffDICOM') read = obj->Read(DIALOG_PICKFILE(FILTER='*')) ; Get the length of the patient name element: arr = obj->GetLength('0010'x,'0010'x) PRINT, arr ; Get an array of all of the lengths from the patient info group: arr = obj->GetLength('0010'x) PRINT, arr OBJ_DESTROY, obj IDLFFDICOM::GETPARENT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffDICOM::GetParent This method is used to find the parent references of a set of elements in a DICOM sequence. It takes as an argument an array of references that represent DICOM elements. If no members of the ReferenceList are members of a sequence, a -1 is returned, and for each member of the ReferenceList which is not a member of a sequence, a -1 is returned. Syntax array = Obj ->[IDLffDICOM::]GetParent( ReferenceList ) Arguments ReferenceList An array of references to DICOM elements that are known to be members of a DICOM sequence. Keywords None Examples obj = OBJ_NEW('IDLffDICOM') read = obj->Read(DIALOG_PICKFILE(FILTER='*')) ; Get the reference to the Referenced Study Sequence ; element, if it exists: ref = obj->GetReference('0008'x,'1110'x) PRINT, ref PRINT, obj->GetDescription(REFERENCE=ref) ; Get and print the parent sequence, if it exists. ; This should result in a -1 since this element is not ; a member of a sequence: parent = obj->GetParent(ref) PRINT, parent PRINT, obj->GetDescription(REFERENCE=parent) ; Get the children of the Referenced Study Sequence ; element, if it exists: refs = obj->GetChildren(ref[0]) PRINT, refs PRINT, obj->GetDescription(REFERENCE=refs) OBJ_DESTROY,obj IDLFFDICOM::GETPREAMBLE [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffDICOM::GetPreamble This method returns the preamble of a DICOM v3.0 Part 10 file. The preamble is a fixed 128 byte field available for implementation specified usage. If it is not used by the implementor of the file, it will be set to all zeroes. The return value is a 128- element BYTE array. Syntax array = Obj -> [IDLffDICOM::]GetPreamble( ) Arguments None Keywords None Examples ; Create a DICOM object, read a DICOM file: obj = OBJ_NEW( 'IDLffDICOM' ) var = obj->Read(DIALOG_PICKFILE(FILTER='*')) ; Get an array of the byte contents of the DICOM file preamble: arr = obj->GetPreamble( ) PRINT, arr OBJ_DESTROY, obj IDLFFDICOM::GETREFERENCE [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffDICOM::GetReference This method takes optional DICOM group and/or element arguments and returns an array of references to matching elements in the object. References are opaque, meaning that they have no specific significance other than a correspondence to the element they refer to. If no arguments or keywords are specified, the returned array contains references to all elements in the object. The effect of multiple keywords and parameters is to AND their results. If no matching elements can be found, the function returns -1. Syntax array = Obj -> [IDLffDICOM::]GetReference( [Group [, Element]] [, DESCRIPTION=string] [, VR=DICOM VR string] ) Arguments Group Set this optional argument to the value for the DICOM group for which to search, such as `0018'x. If this argument is omitted, then all of the DICOM array elements are returned. Element This optional argument can be specified only if the Group argument has also been specified. Set this to the value for the DICOM element to search for, such as `0010'x. If this argument is omitted and the Group argument was specified, then all elements of the specified Group are returned. Keywords DESCRIPTION Set this keyword to a string containing text to be searched for in each element's DICOM description. An element will be returned only if the text in this string can be found in the description. The text comparison is case-insensitive. VR Set this keyword to a DICOM VR string. An element will be returned only if its value representation matches this string. Examples obj = OBJ_NEW('IDLffDICOM') read = obj->Read(DIALOG_PICKFILE(FILTER='*')) ; Get the reference to the patient name element: ref = obj->GetReference('0010'x,'0010'x) PRINT, ref ; get references to all elements with "patient" in the description: refs = obj->GetReference(DESCRIPTION='patient') FOR i = 0, N_ELEMENTS(refs)-1 DO BEGIN PRINT, refs[i] PRINT, obj->GetDescription(REFERENCE=refs[i]) ENDFOR ; Get references to all elements with a VR of DA (date): refs = obj->GetReference(vr='DA') FOR i = 0, N_ELEMENTS(refs)-1 DO BEGIN PRINT, refs[i] PRINT, obj->GetDescription(REFERENCE=refs[i]) ENDFOR OBJ_DESTROY, obj IDLFFDICOM::GETVALUE [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffDICOM::GetValue This method takes optional DICOM group and/or element arguments and returns an array of POINTERs to the values of the elements matching those parameters. If no arguments or keywords are specified, the returned array contains pointers to all elements in the object. The effect of multiple keywords and parameters is to AND their results. If no matching elements can be found, the function returns -1. Syntax ptrArray = Obj -> [IDLffDICOM::]GetValue( [Group [, Element]] [, REFERENCE=list of element references] [, /NO_COPY] ) Arguments Group Set this optional argument to the value for the DICOM group for which to search, such as `0018'x. If this argument is omitted, then all of the DICOM array elements are returned. Element This optional argument can be specified only if the Group argument has also been specified. Set this to the value for the DICOM element for which to search, such as `0010'x. If this argument is omitted and the Group argument was specified, then all elements of the specified Group are returned. Keywords REFERENCE Set this keyword to a list of element references from which to return pointer values. NO_COPY If this keyword is set, the pointers returned point to the actual data in the object for the specified DICOM fields. If not set (the default), the pointers point to copies of the data instead, and need to be freed by using PTR_FREE. Examples Example 1 obj = OBJ_NEW('IDLffDICOM') read = obj->Read(DIALOG_PICKFILE(FILTER='*')) ; Get the image data array = obj->GetValue('7fe0'x, '0010'x) OBJ_DESTROY, obj TVScl, *array[0] PTR_FREE, array Example 2 obj = OBJ_NEW('IDLffDICOM') read = obj->Read(DIALOG_PICKFILE(FILTER='*')) ; Get all of the image data element(s), 7fe0,0010, from the file: array = obj->GetValue('7fe0'x,'0010'x,/NO_COPY) ; Get the row & column size of the image(s): rows = obj->GetValue('0028'x,'0010'x,/NO_COPY) cols = obj->GetValue('0028'x,'0011'x,/NO_COPY) ; If the image has a samples per pixel value greater than 1 ; it is most likely a color image, get the samples per pixel: isColor = 0 samples = obj->GetValue('0028'x,'0002'x,/NO_COPY) IF (SIZE(samples,/N_DIMENSIONS) NE 0) THEN BEGIN IF (*samples[0] GT 1) THEN isColor = 1 ENDIF ; Next, we need to differentiate between files with color data ; that is either color-by-plane or color-by-pixel, get the planar ; configuration: IF (isColor EQ 1) THEN BEGIN isPlanar = 0 planar = obj->GetValue('0028'x,'0006'x, /NO_COPY) IF (SIZE(planar, /N_DIMENSIONS) NE 0) THEN BEGIN IF (*planar[0] EQ 1) THEN isPlanar = 1 ENDIF ENDIF ; Display the first NumWin images from the file: IF N_ELEMENTS(array) GT 10 THEN NumWin = 10 $ ELSE NumWin = N_ELEMENTS(array) offset = 0 FOR index = 0, NumWin-1 DO BEGIN ; Create window for each image that is the size of the image: WSET,index ; Display the image data IF (isColor EQ 1) THEN $ IF (isPlanar EQ 1) THEN $ ; color-by-plane TVScl,TRANSPOSE(*array[index],[2,0,1]),/TRUE $ ELSE $ ; color-by-pixel TVScl,*array[index],/TRUE $ ELSE $ ; monochrome TVScl,*array[index] offset = offset+10 ENDFOR ; Clean up OBJ_DESTROY,obj IDLFFDICOM::GETVR [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffDICOM::GetVR This accessor method takes optional DICOM group and/or element arguments and returns an array of VR (Value Representation) STRINGs for those parameters. A VR is a string that represents a DICOM value representation as described in the DICOM specification PS 3.5. If no arguments or keywords are specified, the returned array contains VRs for all elements in the object. The effect of multiple keywords and parameters is to AND their results. If no matching elements can be found, the function returns -1. Syntax array = Obj -> [IDLffDICOM::]GetVR( [Group [, Element]] [, REFERENCE=list of references] ) Arguments Group Set this optional argument to the value for the DICOM group for which to search, such as `0018'x. If this argument is omitted, then all of the DICOM array elements are returned. Element This optional argument can be specified only if the Group argument has also been specified. Set this to the value for the DICOM element for which to search, such as `0010'x. If this argument is omitted and the Group argument was specified, then all elements of the specified Group are returned. Keywords REFERENCE Use the specified list of references from which to return VR STRING values. Examples obj = OBJ_NEW('IDLffDICOM') read = obj->Read(DIALOG_PICKFILE(FILTER='*')) ; Get the VR of the patient name element: arr = obj->GetVR('0010'x,'0010'x) PRINT, arr ; Get an array of all of the VRs from the patient info group: arr = obj->GetVR('0010'x) PRINT, arr OBJ_DESTROY,obj IDLFFDICOM::INIT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffDICOM::Init This method creates a new IDLffDICOM object and optionally reads the specified file as defined in the IDLffDICOM::Read method. Syntax Result = OBJ_NEW( 'IDLffDICOM' [, Filename] [, /VERBOSE] ) or Result = Obj -> [IDLffDICOM::]Init( [Filename] [, /VERBOSE] ) (Only in a subclass' Init method.) Arguments Filename This optional argument is a scalar string that contains the full path and filename of a DICOM v3.0 Part 10 file to open, read into memory, then close, when the object is created. It is the same as calling: result->Read(Filename). Keywords VERBOSE Set this keyword to print informational messages to the Output Log during the operational life of the object. Examples ; Create a DICOM object: obj = OBJ_NEW( 'IDLffDICOM' ) ; Create a DICOM object and read in a DICOM file named ct_head.dcm ; under Microsoft Windows: obj = OBJ_NEW( 'IDLffDICOM', $ 'c:\rsi\idl52\examples\data\mr_brain.dcm' ) ; Create a DICOM object and allow the user to choose a DICOM file ; to be read: obj = OBJ_NEW( 'IDLffDICOM', DIALOG_PICKFILE(FILTER='*')) IDLFFDICOM::READ [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffDICOM::Read This method opens and reads from the specified disk file, places the information into the DICOM object, then closes the file. The return value is 1 on success and 0 on failure. Syntax result = Obj -> [IDLffDICOM::]Read( Filename [, ENDIAN={1 | 2 | 3 | 4}] ) Arguments Filename This argument is a scalar string that contains the full path and filename of a DICOM Part 10 file to open and read into memory. Keywords ENDIAN Set this keyword to configure the endian format when reading a DICOM file. * 1 = Implicit VR Little Endian * 2 = Explicit VR Little Endian * 3 = Implicit VR Big Endian * 4 = Explicit VR Big Endian Examples ; Create a DICOM object and read a DICOM file: obj = OBJ_NEW( 'IDLffDICOM' ) var = obj->Read(DIALOG_PICKFILE(FILTER='*')) OBJ_DESTROY, obj IDLFFDICOM::RESET [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffDICOM::Reset This method removes all of the elements from the IDLffDICOM object, leaving the object otherwise intact. Syntax Obj -> [IDLffDICOM::]Reset Arguments None Keywords None Examples ; Create a DICOM object, read a DICOM file and dump its contents: obj = OBJ_NEW( 'IDLffDICOM' ) var = obj->Read(DIALOG_PICKFILE(FILTER='*')) obj->DumpElements obj->Reset ; DumpElements should produce no output here: obj->DumpElements OBJ_DESTROY, obj IDLFFDXF [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffDXF An IDLffDXF object contains geometry, connectivity and attributes for graphics primitives. Note IDL supports version 2.003 of the DXF Library. Superclasses This class has no superclass. Subclasses This class has no subclasses. Creation See "IDLffDXF::Init" on page 1884 Methods Intrinsic Methods This class has the following methods: * IDLffDXF::Cleanup * IDLffDXF::GetContents * IDLffDXF::GetEntity * IDLffDXF::GetPalette * IDLffDXF::Init * IDLffDXF::PutEntity * IDLffDXF::Read * IDLffDXF::RemoveEntity * IDLffDXF::Reset * IDLffDXF::SetPalette * IDLffDXF::Write This object treats a DXF file as a list of entities. Note, these are not directly mapped to DXF entity types, rather they are an abstraction of the DXF types. The Read method is used to read the contents of a DXF file into the current entity list. The user may then query this list using the GetContents method to determine the types and number of entities in the file. The user may retrieve arrays of entities from the list using the GetEntity method and add additional entities using the PutEntity method. Entities can also be removed from the list (RemoveEntity) or the entire list destroyed (Reset). The current list of entities can also be written to disk as a DXF file. Note, this object converts DXF entities to IDL entities and back. This conversion is not reversible; thus, if a DXF file is read and then written, the data in the file is not changed, but the internal DXF entity types may be changed by IDL. As an example, DXF face3d entities may be written as DXF polyline entities. The object has one attribute which can be modified using the Get/SetPalette methods. This palette is used to convert color index values. The palette is not actually written to the DXF file. So, if the user wanted to specify entity colors from a 256 entry table, that table would be set using SetPalette, but the actual colors written to the file are the closest colors matched to the fixed AutoCAD color palette. There are two special color values: (0) = color by block color, (256) = color by layer color. In this object, blocks and layers are treated as named entities with attributes, but are special in that all other entities have a block and layer entity reference in them. This allows the user to use these entity names as filters for many operations. There is a default block and a default layer. The default block has the name "" (the null string), and the default layer is '0'. The user may change the (non-name) attributes for these implicit blocks using PutEntity. IDLFFDXF::CLEANUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffDXF::Cleanup The IDLffDXF::Cleanup procedure method performs all cleanup on the object. Note Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass. Syntax OBJ_DESTROY, Obj or Obj -> [IDLffDXF::]Cleanup(Only in subclass' Cleanup method.) Arguments None Keywords None IDLFFDXF::GETCONTENTS [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffDXF::GetContents The IDLffDXF::GetContents method returns the DXF entity types contained in the object. The returned value is a one-dimensional string array of the type names found in the file. The Read or PutEntity methods must have been called previously for the results of this method to be valid. Valid DXF ENTITY DXF_TYPE Types ( 0=default) ARC 1 CIRCLE 2 ELLIPSE 3 LINE 4 LINE3D 5 TRACE 6 POLYLINE 7 LWPOLYLINE 8 POLYGON 9 FACE3D 10 SOLID 11 RAY 12 XLINE 13 TEXT 14 MTEXT 15 POINT 16 SPLINE 17 BLOCK 18 INSERT 19 LAYER 20 Table A-4: DXF Entity Types This object uses a small number of IDL named structures to return the data associated which each entity. This means that several of these DXF types are returned in the same structures, using different values of the DXF_TYPE field. The mapping of DXF entities to IDL named structures is as follows (each of these structures is documented in the GetEntity method): IDL Structure DXF Entity IDL_DXF_ELLIPSE arc, circle, ellipse IDL_DXF_POLYLINE line, line3d, trace, polyline, lwpolyline IDL_DXF_POLYGON face3d, solid, polyline (3d mesh) IDL_DXF_POINT point IDL_DXF_XLINE ray, xline IDL_DXF_SPLINE spline IDL_DXF_TEXT text, multitext IDL_DXF_BLOCK block IDL_DXF_INSERT insert IDL_DXF_LAYER layer Table A-5: DXF mapping to IDL structures Syntax Result = Obj-> [IDLffDXF::]GetContents( [Filter] [BLOCK=string] [, COUNT=variable] [LAYER=string] ) Arguments Filter An integer array of the DXF entity types to which the return types are restricted. If set, Result can contain only types given in this argument and count will also reflect that restriction. Keywords BLOCK Set this keyword to a string value containing the block name to obtain the entities from. The default is all blocks. COUNT A long array containing the number of each entity type contained within the DXF object. If the Filter argument was provided, the numbers reflect the reduced set of entities caused by the Filter argument. LAYER Set this keyword to a string value containing the layer name to obtain the entities from. The default is all layers. IDLFFDXF::GETENTITY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffDXF::GetEntity The IDLffDXF::GetEntity method returns an array of vertex data for the requested entity type. Syntax Result = Obj-> [IDLffDXF::]GetEntity( Type [, BLOCK=string] [, INDEX=value] [, LAYER=string] ) Note Result has one of the named structure formats described in "Structure Formats" on page 1874. Arguments Type The integer DXF entity type from which to obtain the geometry information. Keywords BLOCK Set this keyword to a block name specifying the graphic block from which to obtain the entity geometry information. The default is all blocks. Setting this keyword to the null string '' '' will cause this method to only return entities from the default DXF entity block. INDEX Set this keyword to a scalar long or a long array of indices to return from the entity type. If not set, this method returns all entities for the given type. LAYER Set this keyword to a string value containing the layer name to obtain the entities from. The default is all layers. Fields Common to all Structures BLOCK The name of the block this entity is in (these may be in the default block ""). COLOR A color index value into the current object palette with 0=use block color and 256=use layer color. EXTRUSION The DXF extrusion vector (if any). LAYER The name of the layer this entity is in (the default layer is '0'). LINESTYLE Defined the same as the user linestyle for IDLgrPolyline::Init. Note IDL will always return a solid line regardless of the linestyle in DXF THICKNESS In AutoCAD units. DXF_TYPE Set to one of the values listed in IDLffDXF::GetContents. Note It is the user's responsibility to free all the pointers returned in these structures when the entity is no longer needed. Structure Formats Structure IDL_DXF_ELLIPSE Field Data Type PT0 Double [3] PT1_OFFSET Double [3] MIN_TO_MAJ_RATIO Double START_ANGLE Double END_ANGLE Double EXTRUSION Double [3] LINESTYLE Integer [2] THICKNESS Double COLOR Integer DXF_TYPE Integer BLOCK String LAYER String Table A-6: Fields of the IDL_DXF_ELLIPSE structure This object is centered at PT0 and has a radius defined by the vector PT1_OFFSET. This vector determines the length and orientation of the major axis of an ellipse as well. The MIN_TO_MAJ_RATIO value specifies the length of the minor axis as a fraction of the major axis length. For a circle, this value is 1.0. The START_ANGLE and END_ANGLE values select the portion of the curve to be drawn. If they are equal, the entire circle or ellipse is drawn. Structure IDL_DXF_POLYGON Field Data Type VERTICES Pointer (to an array of 3D points) CONNECTIVITY Pointer (to an array on integers) VERTEX_COLORS Pointer (to an array of integers) MESH_DIMS Integer [2] CLOSED Integer [2] COLOR Integer EXTRUSION Double [3] FIT_TYPE Integer CURVE_FIT Integer SPLINE_FIT Integer DXF_TYPE Integer BLOCK String LAYER String Table A-7: Fields of the IDL_DXF_POLYGON structure VERTICES is a pointer to an array of dimension [3, n] containing the points for this entity. CONNECTIVITY is the array used to connect these points into polygons (see the POLYGONS keyword for IDLgrPolygon::Init). If this array is not present, the connectivity is implicit in (U, V) space defined by the values in MESH_DIMS; the vertices represent a quad mesh of dimensions (MESH_DIMS[0], MESH_DIMS[1]). VERTEX_COLORS points to an array of color index values for each of the vertices. If a quad mesh is being returned, it can be closed in either dimension according to the CLOSED array. FIT_TYPE, CURVE_FIT, and SPLINE_FIT return the type of curve fit (if any) this polygon assumes. Structure IDL_DXF_POLYLINE Field Data Type VERTICES Pointer (to an array of 3D points) CONNECTIVITY Pointer (to an array on integers) VERTEX_COLORS Pointer (to an array of integers) COLOR Integer MESH_DIMS Integer [2] CLOSED Integer [2] THICKNESS Double LINESTYLE Integer [2] EXTRUSION Double [3] FIT_TYPE String CURVE_FIT Integer SPLINE_FIT Integer DXF_TYPE Integer BLOCK String LAYER String Table A-8: Fields of the IDL_DXF_POLYLINE structure VERTICES is a pointer to an array of dimension [3, n] containing the points for this entity. CONNECTIVITY is the array used to connect these points into polylines (see the POLYLINES keyword for IDLgrPolyline::Init). If this array is not present, the connectivity is implicit in (U, V) space defined by the values in MESH_DIMS; the vertices represent a quad mesh of dimensions (MESH_DIMS[0], MESH_DIMS[1]). VERTEX_COLORS points to an array of color index values for each of the vertices. If a quad mesh is being returned, it can be closed in either dimension according to the CLOSED array. FIT_TYPE, CURVE_FIT, and SPLINE_FIT return the type of curve fit (if any) this polyline assumes. Structure IDL_DXF_POINT Field Data Type PT0 Double [3] UCSX_ANGLE Double THICKNESS Double COLOR Integer DXF_TYPE Integer BLOCK String LAYER String Table A-9: Fields of the IDL_DXF_POINT structure PT0 is the location of the point in space. UCSX_ANGLE is an internal DXF orientation parameter used for symbol plotting. Structure IDL_DXF_SPLINE Field Data Type CTR_PTS Pointer FIT_PTS Pointer KNOTS Pointer WEIGHTS Pointer COLOR Integer DEGREE Integer PERIODIC Integer RATIONAL Integer PLANAR Integer LINEAR Integer KNOT_TOLERANCE Double CTL_TOLERANCE Double FIT_TOLERANCE Double START_TANGENT Double [3] END_TANGENT Double [3] THICKNESS Double LINESTYLE Integer [2] EXTRUSION Double [3] DXF_TYPE Integer BLOCK String LAYER String Table A-10: Fields of the IDL_DXF_SPLINE structure This structure is returned verbatim from the DXF spline structure without interpretation. It is up to the user to interpret these values. Structure IDL_DXF_TXT Field Data Type PT0 Double [3] TEXT_STR String COLOR Integer HEIGHT Double WIDTH_FACTOR Double BOX_WIDTH Double DIRECTION Double [3] ROT_ANGLE Double JUSTIFICATION Integer (0=left, 1=center, 2=right, 3=aligned, 4=middle, 5=fit) VERTICAL_ALIGN Integer (0=baseline, 1=bottom, 2=middle, 3=top) SHAPE_FILE String THICKNESS Double EXTRUSION Double [3] DXF_TYPE Integer BLOCK String LAYER String Table A-11: Fields of the IDL_DXF_TXT structure PT0 is the location of the text string. TEXT_STR is the actual string. HEIGHT specifies the overall scaling of the glyphs while WIDTH_FACTOR is a correction in the baseline direction (anisotropic scaling). For multi-line text, BOX_WIDTH determines where the line breaks should be placed (0.0 for single line text). The text baseline is specified by DIRECTION and its rotation about the Z axis is specified by ROT_ANGLE. Justification is specified by JUSTIFICATION and VERTICAL_ALIGN. SHAPE_FILE is the name of the glyph file used to image this string. The shape file is NOT read by IDL. Structure IDL_DXF_XLINE Field Data Type PT0 Double [3] UNIT_VEC Double [3] COLOR Integer THICKNESS Double LINESTYLE Integer [2] EXTRUSION Double [3] DXF_TYPE Integer BLOCK String LAYER String Table A-12: Fields of the IDL_DXF_XLINE structure PT0 is the start of a ray or a point on a infinite line in space in the case of an XLINE entity. UNIT_VEC determines the direction of the line in space. Structure IDL_DXF_INSERT Field Data Type SCALE Double [3] PT0 Double [3] ROTATION Double INSTANCE_BLOCK String NUM_ROW_COL Integer [2] DISTANCE_BETWEEN Double [2] DXF_TYPE Integer BLOCK String COLOR Integer LAYER String Table A-13: Fields of the IDL_DXF_INSERT structure The insert entity allows for the "instancing" of a block in a grid fashion. INSTANCE_BLOCK is the name of a block to repeat. The block is scaled by SCALE and rotated about the Z axis by ROTATION. The grid begins at PT0 and contains the number of rows and columns specified by NUM_ROW_COL (Note: 0 rows or columns will always give a single instance of the block). The spacing of the grid is specified by DISTANCE_BETWEEN. Structure IDL_DXF_BLOCK Field Data Type PT0 Double [3] COLOR Integer NAME String DXF_TYPE Integer Table A-14: Fields of the IDL_DXF_BLOCK structure This entity specifies a BLOCK. Blocks have a location in space (PT0) [objects in the block are interpreted relative to this point], a name, and a COLOR. They are not contained in layers or other blocks, so these fields are not present. Structure IDL_DXF_LAYER Field Data Type COLOR Integer NAME String DXF_TYPE Integer Table A-15: Fields of the IDL_DXF_LAYER structure This entity specifies a LAYER. Layer is a NAME and a COLOR. They are not contained in layers or other blocks, so these fields are not present. IDLFFDXF::GETPALETTE [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffDXF::GetPalette The IDLffDXF::GetPalette method returns the current color table in the object. Syntax Obj-> [IDLffDXF::]GetPalette, Red, Green, Blue Arguments Red Returns an array of the red components to the current color table. Green Returns an array of the green components to the current color table. Blue Returns an array of the blue components to the current color table. IDLFFDXF::INIT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffDXF::Init The IDL_Container::Init function method initializes the DXF object. Note Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass. Syntax Result = OBJ_NEW('IDLffDXF' [, Filename] ) or Result = Obj -> [IDLffDXF::]Init( [Filename] ) (Only in a subclass' Init method.) Arguments Filename Set this optional argument to a scalar string containing the full path and filename of a DXF file to be read as the object is created. Keywords None IDLFFDXF::PUTENTITY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffDXF::PutEntity The IDLffDXF::PutEntity procedure method inserts an entity into the DXF object. The type of the entity is determined from the DXF_TYPE field of the entity structure. If DXF_TYPE is set to 0, the type is implied by the entity structure. Note Line3D entity types will be written as Line entities due to the obsolete status of Line3D. Polyline entities will be automatically converted to Lightweight Polylines where applicable. Syntax Obj -> [IDLffDXF::]PutEntity, Data Arguments Data An array of Entity structures as defined by the GetEntity method. Note If the entity references a non-existent block or layer, one will automatically be created. Blocks and layers can also be created by passing IDL_DXF_BLOCK or IDL_DXF_LAYER structures to this routine. IDLFFDXF::READ [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffDXF::Read The IDLffDXF::Read method reads a file, parsing the DXF object information contained in the file, and inserts it into itself. This method returns an indication of success in reading the file. Syntax Result = Obj-> [IDLffDXF::]Read( Filename ) Arguments Filename A scalar string containing the full path and filename of the DXF file to be read. Example ; Read all the lines from the electrical layer: oDXF = OBJ_NEW('IDLffDXF') IF (oDXF->Read('myDXF.dxf')) THEN BEGIN contents = oDXF->GetContents(4,COUNT=numLines, $ LAYER='Electrical') IF (numLines ne 0) THEN BEGIN lines = oDXF->GetEntity(4,LAYER='Electrical') ENDIF ENDIF IDLFFDXF::REMOVEENTITY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffDXF::RemoveEntity The IDLffDXF::RemoveEntity method removes the specified entity or entities from the DXF object. Syntax Obj -> [IDLffDXF::]RemoveEntity[, Type] [, INDEX=value] Arguments Type An optional scalar string containing the DXF type to be removed from the DXF object. Note Specifying a block or layer entity will cause all the entities in that layer or block to be removed. Keywords INDEX Set this keyword to a scalar long or a long array of indices to remove from the DXF object. If not set, or set negative, all entities of the given type are removed. IDLFFDXF::RESET [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffDXF::Reset The IDLffDXF::Reset method removes all the entities from the DXF object. Syntax Obj-> [IDLffDXF::]Reset Arguments None Keywords None IDLFFDXF::SETPALETTE [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffDXF::SetPalette The IDLffDXF::SetPalette method sets the current color table in the object. Syntax Obj-> [IDLffDXF::]SetPalette, Red, Green, Blue Arguments Red Sets the red components of the current color table to this array. Green Sets the green components of the current color table to this array. Blue Sets the blue components of the current color table to this array. Keywords None IDLFFDXF::WRITE [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffDXF::Write The IDLffDXF::Write method writes a file for the DXF entity information this object contains. This method returns an indication of success in writing the file. Syntax Result = Obj-> [IDLffDXF::]Write( Filename ) Arguments Filename A scalar string containing the full path and filename of the DXF file to be written. Example ; Write a square to a new DXF file using lines: oDXF = OBJ_NEW('IDLffDXF') lines = {IDL_DXF_POLYLINE} lines.dxf_type = 4 lines.layer='myLayer' lines.thickness = 1.0 ; Create clockwise square: lines = REPLICATE(lines, 4) lines[0].vertices = PTR_NEW([[0.0,0.0,0.0], $ [0.0,1.0,0.0]]) lines[0].connectivity = PTR_NEW([0,1]) lines[1].vertices = PTR_NEW([[0.0,1.0,0.0], $ [1.0,1.0,0.0]]) lines[1].connectivity = PTR_NEW([0,1]) lines[2].vertices = PTR_NEW([[1.0,1.0,0.0], $ [1.0,0.0,0.0]]) lines[2].connectivity = PTR_NEW([0,1]) lines[3].vertices = PTR_NEW([[1.0,0.0,0.0], $ [0.0,0.0,0.0]]) lines[3].connectivity = PTR_NEW([0,1]) oDXF->PutEntity, lines IF (not oDXF->Write('mySquare.dxf')) THEN $ PRINT, 'Write Failed.' ; Clean up the memory in the structs: OBJ_DESTROY, oDXF FOR i=0,3 DO BEGIN PTR_FREE, lines[i].vertices, lines[i].connectivity ENDFOR IDLFFLANGUAGECAT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffLanguageCat The IDLffLanguageCat object provides an interface to IDL language catalog files. Note This object is not savable. Restored IDLffLanguageCat objects may contain invalid data. Note This object is not intended to be created with OBJ_NEW. The MSG_CAT_OPEN function is used to return the correct object reference. Superclasses This class has no superclasses. Subclasses This class has no subclasses. Creation See MSG_CAT_OPEN. Methods * IDLffLanguageCat::IsValid * IDLffLanguageCat::Query * IDLffLanguageCat::SetCatalog See Also MSG_CAT_CLOSE, MSG_CAT_COMPILE, MSG_CAT_OPEN IDLFFLANGUAGECAT::ISVALID [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffLanguageCat::IsValid The IDLffLanguageCat::IsValid function method is used to determine whether the object has a valid catalog. Syntax Result = Obj ->[IDLffLanguageCat::]IsValid( ) Arguments None Keywords None IDLFFLANGUAGECAT::QUERY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffLanguageCat::Query The IDLffLanguageCat::Query function method is used to return the language string associated with the given key. If the key is not found in the given catalog, the default string is returned. Syntax Result = Obj ->[IDLffLanguageCat::]Query( key [, DEFAULT_STRING=string] ) Arguments key The scalar, or array of (string) keys associated with the desired language string. If key is an array, Result will be a string array of the associated language strings. Keywords DEFAULT_STRING Set this keyword to the desired value of the return string if the key cannot be found in the catalog file. The default value is the empty string. IDLFFLANGUAGECAT::SETCATALOG [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffLanguageCat::SetCatalog The IDLffLanguageCat::SetCatalog function method is used to set the appropriate catalog file. This function returns 1 upon success, and 0 on failure. Syntax Result = Obj ->[IDLffLanguageCat::]SetCatalog( application [, FILENAME=string] [, LOCALE=string] [, PATH=string] ) Arguments application A scalar string representing the name of the desired application's catalog file. Keywords FILENAME Set this keyword to a scalar string containing the full path and filename of the catalog file to open. If this keyword is set, application, PATH, and LOCALE are ignored. LOCALE Set this keyword to the desired locale for the catalog file. If not set, the current locale is used. PATH Set this keyword to a scalar string containing the path to search for language catalog files. The default is the current directory. IDLFFSHAPE [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffShape An IDLffShape object contains geometry, connectivity and attributes for graphics primitives accessed from ESRI Shapefiles. Superclasses This class has no superclass. Subclasses This class has no subclasses. Creation See IDLffShape::Init Methods Intrinsic Methods This class has the following methods: * IDLffShape::AddAttribute * IDLffShape::Cleanup * IDLffShape::Close * IDLffShape::DestroyEntity * IDLffShape::GetAttributes * IDLffShape::GetEntity * IDLffShape::GetProperty * IDLffShape::Init * IDLffShape::Open * IDLffShape::PutEntity * IDLffShape::SetAttributes Overview An ESRI Shapefile stores nontopological geometry and attribute information for the spatial features in a data set. A Shapefile consists of a main file (.shp), an index file (.shx), and a dBASE table (.dbf). For example, the Shapefile "states" would have the following files: * states.shp * states.shx * states.dbf Naming Conventions for a Shapefile All the files that comprise an ESRI Shapefile must adhere to the 8.3 filename convention and must be lower case. The main file, index file, and dBASE file must all have the same prefix. The prefix must start with an alphanumeric character and can contain any alphanumeric, underscore (_), or hyphen (-). The main file suffix must use the .shp extension, the index file the .shx extension, and the dBASE table the .dbf extension. Major Elements of a Shapefile A Shapefile consists of the following elements that you can access through the IDLffShape class: * Entities * Attributes Entities The geometry for a feature is stored as a shape comprising a set of vector coordinates (referred to as `entities'). The entities in a Shapefile must all be of the same type. The following are the possible types for entities in a Shapefile: Shape Type Type Code Point 1 PolyLine 3 Polygon 5 Table A-16: Entity Types Shape Type Type Code MultiPoint 8 PointZ 11 PolyLineZ 13 PolygonZ 15 MultiPointZ 18 PointM 21 PolyLineM 23 PolygonM 25 MultiPointM 28 MultiPatch 31 Table A-16: Entity Types (Continued) When retrieving entities using the IDLffShape::GetEntity method, an IDL structure is returned. This structure has the following fields: Field Data Type SHAPE_TYPE IDL_LONG ISHAPE IDL_LONG BOUNDS Double[8] N_VERTICES IDL_LONG VERTICES Pointer (to Vertices array) MEASURE Pointer (to Measure array) N_PARTS IDL_LONG PARTS Pointer (to Parts array). PART_TYPES Pointer (to part types) ATTRIBUTES Pointer to attribute array. Table A-17: Entity Structure Field Data Types The following table describes each field in the structure: Field Description SHAPE_TYPE The entity type. ISHAPE The identifier of the specific entity in the shape object. BOUNDS A bounding box that specifies the range limits of the entity. This eight element array contains the following information: * Index 0 - X minimum value * Index 1 - Y minimum value * Index 2 - Z minimum value (if Z is supported by type) * Index 3 - Measure minimum value (if measure is supported by entity type). * Index4 - X maximum value. * Index5 - Y maximum value. * Index6 - Z maximum value (if Z is supported by the entity type). * Index7 - Measure maximum value (if measure is supported by entity type). Note - If the entity is a point type, the values contained in the bounds array are also the values of the entity. N_VERTICES The number of vertices in the entity. If this value is one and the entity is a POINT type (POINT, POINTM, POINTZ), the vertices pointer will be set to NULL and the entity value will be maintained in the BOUNDS field. Table A-18: Entity Structure Field Descriptions Field Description VERTICES An IDL pointer that contains the vertices of the entity. This pointer contains a double array that has one of the following formats: * [2, N] - If Z data is not present * [3, N] - If Z data is present. where N is the number of vertices. These array formats can be passed to the polygon and polyline objects of IDL Object Graphics. Note - This pointer will be null if the entity is a point type, with the values maintained in the BOUNDS array. MEASURE If the entity has a measure value (this is dependent on the entity type), this IDL pointer will contain a vector array of measure values. The length of this vector is N_VERTICES. Note - This pointer will be null if the entity is of type POINTM, with the values contained in the BOUNDS array. N_PARTS If the values of the entity are separated into parts, the break points are enumerated in the parts array. This field lists the number of parts in this entity. If this value is 0, the entity is one part and the PARTS pointer will be NULL. PARTS An IDL pointer that contains an array of indices into the vertex/measure arrays. These values represent the start of each part of the entity. The index range of each entity part is defined by the following: * Start = Parts[I] * End = Parts[I+1]-1 or the end of the array PART_TYPES This IDL pointer is only valid for entities of type MultiPatch and defines the type of the particular part. If the entity type is not MultiPatch, part types are assumed to be type RING (SHPP_RING). Note - This pointer is NULL if the entity is not type MultiPatch. Table A-18: Entity Structure Field Descriptions (Continued) Field Description ATTRIBUTES If the attributes for an entity were requested, this field contains an IDL pointer that contains a structure of attributes for the entity. For more information on this structure, see "Attributes" on page 1900. Table A-18: Entity Structure Field Descriptions (Continued) Attributes A Shapefile provides the ability to associate information describing each entity (a geometric element) contained in the file. This descriptive information, called attributes, consists of a set of named data elements for each geometric entity contained in the file. The set of available attributes is the same for every entity contained in a Shapefile, with each entity having it's own set of attribute values. An attribute consist of two components: * A name * A data value The name consists of an 11 character string that is used to identify the data value. The data value is not limited to any specific format. The two components that form an attribute are accessed differently using the shape object. To get the name of attributes for the specific file, the ATTRIBUTE_NAMES keyword to the IDLffShape::GetProperty method is used. This returns a string array that contains the names for the attributes defined for the file. To get the attribute values for an entity, the IDLffShape::GetAttributes method is called or the ATTRIBUTES keyword of the IDLffShape::GetEntity method is set. In each case, the attribute values for the specified entity is returned as an anonymous IDL structure. The numeric order of the fields in the returned structure map to the numeric order of the attributes defined for the file. The actual format of the returned structure is: ATTRIBUTE_0 : VALUE, ATTRIBUTE_1 : VALUE, ATTRIBUTE_2 : VALUE, ... ATTRIBUTE_ : VALUE To access the values in the returned structure, you can either hardcode the structure field names or use the structure indexing feature of IDL. Accessing Shapefiles The following example shows how to access data in a Shapefile. This example sets up a map to display parts of a Shapefile, opens a Shapefile, reads the entities from the Shapefile, and then plots only the state of Colorado: PRO ex_shapefile DEVICE, RETAIN=2, DECOMPOSED=0 !P.BACKGROUND=255 ;Define a color table r=BYTARR(256) & g=BYTARR(256) & b=BYTARR(256) r[0]=0 & g[0]=0 & b[0]=0 ;Definition of black r[1]=100 & g[1]=100 & b[1]=255 ;Definition of blue r[2]=0 & g[2]=255 & b[2]=0 ;Definition of green r[3]=255 & g[3]=255 & b[3]=0 ;Definition of yellow r[255]=255 & g[255]=255 & b[255]=255 ;Definition of white TVLCT, r, g, b black=0 & blue=1 & green=2 & yellow=3 & white=255 ; Set up map to plot Shapefile on MAP_SET, /ORTHO,45, -120, /ISOTROPIC, $ /HORIZON, E_HORIZON={FILL:1, COLOR:blue}, $ /GRID, COLOR=black, /NOBORDER ; Fill the continent boundaries: MAP_CONTINENTS, /FILL_CONTINENTS, COLOR=green ; Overplot coastline data: MAP_CONTINENTS, /COASTS, COLOR=black ; Show national borders: MAP_CONTINENTS, /COUNTRIES, COLOR=black ;Open the states Shapefile in the examples directory myshape=OBJ_NEW('IDLffShape', FILEPATH('states.shp', $ SUBDIR=['examples', 'data'])) ;Get the number of entities so we can parse through them myshape -> IDLffShape::GetProperty, N_ENTITIES=num_ent ;Parsing through the entities and only plotting the state of ;Colorado FOR x=1, (num_ent-1) DO BEGIN ;Get the Attributes for entity x attr = myshape -> IDLffShape::GetAttributes(x) ;See if 'Colorado' is in ATTRIBUTE_1 of the attributes for ;entity x IF attr.ATTRIBUTE_1 EQ 'Colorado' THEN BEGIN ;Get entity ent = myshape -> IDLffShape::GetEntity(x) ;Plot entity POLYFILL, (*ent.vertices)[0,*], (*ent.vertices)[1,*], COLOR=yellow ;Clean-up of pointers myshape -> IDLffShape::DestroyEntity, ent ENDIF ENDFOR ;Close the Shapefile OBJ_DESTROY, myshape END This results in the following: Figure A-1: Example Use of Shapefiles Creating New Shapefiles To create a Shapefile, you need to create a new Shapefile object, define the entity and attributes definitions, and then add your data to the file. For example, the following program creates a new Shapefile (cities.shp), defines the entity type to be "Point", defines 2 attributes (CITY_NAME and STATE_NAME), and then adds an entity to the new file: PRO ex_shapefile_newfile ;Create the new shapefile and define the entity type to Point mynewshape=OBJ_NEW('IDLffShape', FILEPATH('cities.shp', $ SUBDIR=['examples', 'data']), /UPDATE, ENTITY_TYPE=1) ;Set the attribute definitions for the new Shapefile tribute, 'CITY_NAME', 7, 25, $ PRECISION=0 tribute, 'STAT_NAME', 7, 25, $ PRECISION=0 ;Create structure for new entity entNew = {IDL_SHAPE_ENTITY} ; Define the values for the new entity entNew.SHAPE_TYPE = 1 entNew.ISHAPE = 1458 entNew.BOUNDS[0] = -104.87270 entNew.BOUNDS[1] = 39.768040 entNew.BOUNDS[2] = 0.00000000 entNew.BOUNDS[3] = 0.00000000 entNew.BOUNDS[4] = -104.87270 entNew.BOUNDS[5] = 39.768040 entNew.BOUNDS[6] = 0.00000000 entNew.BOUNDS[7] = 0.00000000 ;Create structure for new attributes attrNew = mynewshape ->IDLffShape::GetAttributes( $ /ATTRIBUTE_STRUCTURE) ;Define the values for the new attributes attrNew.ATTRIBUTE_0 = 'Denver' attrNew.ATTRIBUTE_1 = 'Colorado' ;Add the new entity to new shapefile mynewshape -> IDLffShape::PutEntity, entNew ;Add the Colorado attributes to new shapefile mynewshape -> IDLffShape::SetAttributes, 0, attrNew ;Close the shapefile OBJ_DESTROY, mynewshape END Updating Existing Shapefiles You can modify existing Shapefiles with the following: * Adding new entities * Adding new attributes (only to Shapefiles without any existing values in any attributes) * Modifying existing attributes Note You cannot modify existing entities. For example, the following program adds an entity and attributes for the city of Boulder to the cities.shp file we created in the previous example: PRO ex_shapefile_modify ;Open the cities Shapefile myshape=OBJ_NEW('IDLffShape', FILEPATH('cities.shp', $ SUBDIR=['examples', 'data']), /UPDATE) ;Create structure for new entity entNew = {IDL_SHAPE_ENTITY} ; Define the values for the new entity entNew.SHAPE_TYPE = 1 entNew.ISHAPE = 1380 entNew.BOUNDS[0] = -105.25100 entNew.BOUNDS[1] = 40.026878 entNew.BOUNDS[2] = 0.00000000 entNew.BOUNDS[3] = 0.00000000 entNew.BOUNDS[4] = -105.25100 entNew.BOUNDS[5] = 40.026878 entNew.BOUNDS[6] = 0.00000000 entNew.BOUNDS[7] = 0.00000000 ;Create structure for new attributes attrNew = myshape ->IDLffShape::GetAttributes( $ /ATTRIBUTE_STRUCTURE) ;Define the values for the new attributes attrNew.ATTRIBUTE_0 = 'Boulder' attrNew.ATTRIBUTE_1 = 'Colorado' ;Add the new entity to new shapefile myshape -> IDLffShape::PutEntity, entNew ;Add the Colorado attributes to new shapefile myshape -> IDLffShape::SetAttributes, 0, attrNew ;Close the shapefile OBJ_DESTROY, myshape END IDLFFSHAPE::ADDATTRIBUTE [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffShape::AddAttribute The IDLffShape::AddAttribute method adds an attribute definition to a Shapefile. Adding a the attribute definition is required before adding the actual attribute data to a file. For more information on attributes, see "Attributes" on page 1900. Note You can only define new attributes to Shapefiles that do not have any existing values in any attributes. Syntax Obj->[IDLffShape::]AddAttribute, Name, Type, Width [, PRECISION=integer] Arguments Name Set to a string that contains the attribute name. Name values are limited to 11 characters. Arguments longer than 11 characters will be truncated. Type Set to the IDL type code that corresponds to the data type that will be stored in the attribute. The valid types are: Code Description 3 Longword Integer 5 Double-precision floating-point 7 String Table A-19: Type Code Descriptions Width Set to the width of the field for the data value of the attribute. The following table describes the possible values depending on the defined Type: Field Type Valid Values Longword Integer Maximum size of the field. Double-precision floating-point Maximum size of the field. String Maximum length of the string. Table A-20: Width Values Keywords PRECISION Set this keyword to the number of positions to be included after the decimal point. The default is 8. This keyword is only valid for fields defined as double-precision floating-point. Example In the following example, we add the attribute "ELEVATION" to an existing Shapefile. Note that if the file already contains data in an attribute for any of the entities defined in the file, this operation will fail. PRO ex_addattr_shapefile ;Open a shapefile myshape=OBJ_NEW('IDLffShape', FILEPATH('cities.shp', $ SUBDIR=['examples', 'data']), /UPDATE) ;Define a new attribute for the Shapefile myshape->IDLffShape::AddAttribute, 'ELEVATION', 3, 4, $ PRECISION=0 ;Close the shapefile OBJ_DESTROY, myshape END IDLFFSHAPE::CLEANUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffShape::Cleanup The IDLffShape::Cleanup method performs all cleanup on a Shapefile object. If the Shapefile being accessed by the object is open and the file has been modified, the new information is written to the file if one of the following conditions is met: * The file was opened with write permissions using the UPDATE keyword to the IDLffShape::Open method * It is a newly created file that has not been written previously. Note Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass. Syntax OBJ_DESTROY, Obj or Obj -> [IDLffShape::]Cleanup (Only in subclass' Cleanup method.) Arguments None Keywords None IDLFFSHAPE::CLOSE [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffShape::Close The IDLffShape::Close method closes a Shapefile. If the file has been modified, it is also written to the disk if neither of the following conditions is met: * The file was opened with write permissions using the UPDATE keyword to the IDLffShape::Open method * It is a newly created file that has not been written previously. If the file has been modified and one of the previous conditions is not met, the file is closed and the changes are not written to disk. Syntax Obj->[IDLffShape::]Close Arguments None. Keywords None. IDLFFSHAPE::DESTROYENTITY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffShape::DestroyEntity The IDLffShape::DestroyEntity method frees memory associated with the entity structure. For more information on the entity structure, see "Entities" on page 1896. Syntax Obj->[IDLffShape::]DestroyEntity, Entity Arguments Entity This argument specifies a scalar or array of entities to destroy. Keywords None. Example In the following example, all of the entities from the states.shp Shapefile are read and then the DestroyEntity method is called to clean up all pointers: PRO ex_shapefile ;Open the states Shapefile in the examples directory myshape=OBJ_NEW('IDLffShape', FILEPATH('states.shp', $ SUBDIR=['examples', 'data'])) ;Get the number of entities so we can parse through them myshape -> IDLffShape::GetProperty, N_ENTITIES=num_ent ;Read all the entities FOR x=1, (num_ent-1) DO BEGIN ;Read the entity x ent = myshape -> IDLffShape::GetEntity(x) ;Clean-up of pointers myshape -> IDLffShape::DestroyEntity, ent ENDFOR ;Close the Shapefile OBJ_DESTROY, myshape END IDLFFSHAPE::GETATTRIBUTES [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffShape::GetAttributes The IDLffShape::GetAttributes method retrieves the attributes for the entities you specify from a Shapefile. Syntax Result = Obj->[IDLffShape::]GetAttributes([Index] [, /ALL] [, /ATTRIBUTE_STRUCTURE] ) Return Value This method returns an anonymous structure array. For more information on the structure, see "Attributes" on page 1900. Arguments Index A scalar or array of longs specifying the entities for which you want to retrieve the attributes, with 0 being the first entity in the Shapefile. Note If you do not specify Index and the ALL keyword is not set, the attributes for the first entity (0) are returned. Keywords ALL Set this keyword to retrieve the attributes for all entities in a Shapefile. If you set this keyword, the Index argument is not required. ATTRIBUTE_STUCTURE Set this keyword to return an empty attribute structure that can then be used with the IDLffShape::SetAttributes method to add attributes to a Shapefile. Examples In the first example, we retrieve the attributes associated with entity at location 0 (the first entity in the file): attr = myShape->getAttributes( 0) In the next example, we retrieve the attributes associated with entities 10 through 20: attr = myShape->getAttributes( 10+indgen(11) ) In the next example, we retrieve the attributes for entities 1,4, 9 and 70: attr = myShape->getAttributes( [1, 4, 9, 70] ) In the next example, we retrieve all the attributes for a Shapefile: attr = myShape->getAttributes( /ALL ) IDLFFSHAPE::GETENTITY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffShape::GetEntity The IDLffShape::GetEntity method returns the entities you specify from a Shapefile. Syntax Result = Obj->[IDLffShape::]GetEntity( [Index] [, /ALL] [, /ATTRIBUTES] ) Return Value This method returns a type {IDL_SHAPE_ENTITY} structure array. For more information on the structure, see "Entities" on page 1896. Note Since an entity structure contains IDL pointers, you must free all the pointers returned in these structures when the entity is no longer needed using the IDLffShape::DestroyEntity method. Note Since entities cannot be modified in a Shapefile, an entity is read directly from the Shapefile each time you use the IDLffShape::GetEntity method even if you have already read that entity. If you modify the structure array returned by this method for a given entity and then use IDLffShape::GetEntity on that same entity, the modified data will NOT be returned, the data that is actually written in the file is returned. Arguments Index A scalar or array of longs specifying the entities for which you want to retrieve with 0 being the first entity in the Shapefile. If the ALL keyword is set, this argument is not required. If you do not specify any entities and the ALL keyword is not set, the first entity (0) is returned. Keywords ALL Set this keyword to retrieve all entities from the Shapefile. If this keyword is set, the Index argument is not required. ATTRIBUTES Set this keyword to return the attributes in the entity structure. If not set, the ATTRIBUTES tag in the entity structure will be a null IDL pointer. Example In the following example, all of the entities from the states.shp Shapefile are read: PRO ex_shapefile ;Open the states Shapefile in the examples directory myshape=OBJ_NEW('IDLffShape', FILEPATH('states.shp', $ SUBDIR=['examples', 'data'])) ;Get the number of entities so we can parse through them myshape -> IDLffShape::GetProperty, N_ENTITIES=num_ent ;Read all the entities FOR x=1, (num_ent-1) DO BEGIN ;Read the entity x ent = myshape -> IDLffShape::GetEntity(x) ;Clean-up of pointers myshape -> IDLffShape::DestroyEntity, ent ENDFOR ;Close the Shapefile OBJ_DESTROY, myshape END IDLFFSHAPE::GETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffShape::GetProperty The IDLffShape::GetProperty method returns the values of properties associated with a Shapefile object. These properties are: * Number of entities * The type of the entities * The number of attributes associated with each entity * The names of the attributes * The name, type, width, and precision of the attributes * The status of a Shapefile * The filename of the Shapefile object Syntax Obj->[IDLffShape::]GetProperty [, N_ENTITIES=variable] [, ENTITY_TYPE=variable] [, N_ATTRIBUTES=variable] [, ATTRIBUTE_NAMES=variable] [, ATTRIBUTE_INFO=variable] [, IS_OPEN=variable] [, FILENAME=variable] Arguments None. Keywords N_ENTITIES Set this keyword to a named variable to return the number of entities contained in Shapefile object. If the value is unknown, this method returns 0. ENTITY_TYPE Set this keyword to a named variable to return the integer type code for the entities contained in the Shapefile object. If the value is unknown, this method returns -1. For more information on entity type codes, see "Entities" on page 1896. N_ATTRIBUTES Set this keyword to a named variable to return the number of attributes associated with a Shapefile object. If the value is unknown, this method returns 0. ATTRIBUTE_NAMES Set this keyword to a named variable to return the names of each attribute in the Shapefile object. These names are returned as a string array. ATTRIBUTE_INFO Set this keyword to a named variable to return the attribute information for each attribute. This consists of an array of attribute information structures that have the following fields: Field Description NAME A string that contains the name of the attribute. TYPE The IDL type code of the attribute. WIDTH The width of the attribute. PRECISION The precision of the attribute. Table A-21: ATTRIBUTE_INFO Fields The file must be open to obtain this information. IS_OPEN Set this keyword to a named variable to return information about the status of a Shapefile. The following values can be returned: Value Description 0 File is not open 1 File is open in read-only mode. 3 File is open in update mode. Table A-22: IS_OPEN Values FILENAME Set this keyword to a named variable to return the fully qualified path name of the Shapefile in the current Shapefile object. Examples In the following example, the number of entities and the entity type is returned: PRO entity_info ;Open the states Shapefile in the examples directory myshape=OBJ_NEW('IDLffShape', FILEPATH('states.shp', $ SUBDIR=['examples', 'data'])) ;Get the number of entities and the entity type myshape -> IDLffShape::GetProperty, N_ENTITIES=num_ent, $ ENTITY_TYPE=ent_type ;Print the number of entities and the type PRINT, 'Number of Entities: ', num_ent PRINT, 'Entity Type: ', ent_type ;Close the Shapefile OBJ_DESTROY, myshape END This results in the following: Number of Entities: 51 Entity Type: 5 In the next example, the definitions for attribute 1 are returned: PRO attribute_info ;Open the states Shapefile in the examples directory myshape=OBJ_NEW('IDLffShape', FILEPATH('states.shp', $ SUBDIR=['examples', 'data'])) ;Get the info for all attribute myshape -> IDLffShape::GetProperty, ATTRIBUTE_INFO=attr_info ;Print Attribute Info PRINT, 'Attribute Number: ', '1' PRINT, 'Attribute Name: ', attr_info[1].name PRINT, 'Attribute Type: ', attr_info[1].type PRINT, 'Attribute Width: ', attr_info[1].width PRINT, 'Attribute Precision: ', attr_info[1].precision ;Close the Shapefile OBJ_DESTROY, myshape END This results in the following: Attribute Number: 1 Attribute Name: STATE_NAME Attribute Type: 7 Attribute Width: 25 Attribute Precision: 0 IDLFFSHAPE::INIT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffShape::Init The IDLffShape::Init function method initializes or constructs a Shapefile object. Note Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass. Syntax Result = OBJ_NEW(`IDLffShape' [, Filename] [, /UPDATE] [, ENTITY_TYPE='Value') Return Value This method returns a Shapefile object. Arguments Filename Set this argument to a scalar string containing the full path and filename of a Shapefile (.shp) to open. If this file exists, it is opened. If the file does not exist, a new Shapefile object is constructed. You do not need to use IDLffShape::Open to open an existing file when specifying this keyword. Note The .shp, .shx, and .dbx files must exist in the same directory for you to be able to open and access the file unless the UPDATE keyword is set. Keywords UPDATE Set this keyword to have the file opened for writing. The default is read-only. ENTITY_TYPE Set this keyword to the entity type of a new Shapefile. Use this keyword only when creating a new Shapefile. For more information on entity types, see "Entities" on page 1896. Example In the following example, we create a new Shapefile object and open the examples/data/states.shp file: myshape=OBJ_NEW('IDLffShape', FILEPATH('states.shp', $ SUBDIR=['examples', 'data'])) IDLFFSHAPE::OPEN [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffShape::Open The IDLffShape::Open method opens a specified Shapefile. Syntax Result = Obj->[IDLffShape::]Open( `Filename' [, /UPDATE] [, ENTITY_TYPE='value'] ) Return Value This method returns 1 if the file can be read successfully. If not able to open the file, it returns 0. Arguments Filename Set this argument to a scalar string containing the full path and filename of a Shapefile (.shp) to open. Note that the .shp, .shx, and .dbx files must exist in the same directory for you to be able to open and access the file unless the UPDATE keyword is set. Keywords UPDATE Set this keyword to have the file opened for writing. The default is read-only. ENTITY_TYPE Set this keyword to the entity type of a new Shapefile. Use this keyword only when creating a new Shapefile. For more information on entity types, see "Entities" on page 1896 Example In the following example, the file examples/data/states.shp is opened for reading and writing: status = myShape->Open(FILEPATH('states.shp', $ SUBDIR=['examples', 'data']), /UPDATE) IDLFFSHAPE::PUTENTITY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffShape::PutEntity The IDLffShape::PutEntity method inserts an entity into the Shapefile object. The entity must be in the proper structure. For more information on the structure, see "Entities" on page 1896. Note The shape type of the new entity must be the same as the shape type defined for the Shapefile. If the shape type has not been defined for the Shapefile using the ENTITY_TYPE keyword for the IDLffShape::Open or IDLffShape::Init methods, the first entity that is inserted into the Shapefile defines the type. Note Only new entities can be inserted into a Shapefile. Existing entities cannot be updated. Syntax Obj->[IDLffShape::]PutEntity, Data Arguments Data Set this argument to a scalar or an array of entity structures. Keywords None. Example In the following example, we create a new shapefile, define a new entity, and then use the PutEntity method to insert it into the new file: PRO ex_shapefile_newfile ;Create the new shapefile and define the entity type to Point pe', FILEPATH('cities.shp', $ SUBDIR=['examples', 'data']), /UPDATE, ENTITY_TYPE=1) ;Create structure for new entity entNew = {IDL_SHAPE_ENTITY} ; Define the values for the new entity entNew.SHAPE_TYPE = 1 entNew.ISHAPE = 1458 entNew.BOUNDS[0] = -104.87270 entNew.BOUNDS[1] = 39.768040 entNew.BOUNDS[2] = 0.00000000 entNew.BOUNDS[3] = 0.00000000 entNew.BOUNDS[4] = -104.87270 entNew.BOUNDS[5] = 39.768040 entNew.BOUNDS[6] = 0.00000000 entNew.BOUNDS[7] = 0.00000000 ;Add the new entity to new shapefile mynewshape -> IDLffShape::PutEntity, entNew ;Close the shapefile OBJ_DESTROY, mynewshape END IDLFFSHAPE::SETATTRIBUTES [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffShape::SetAttributes The IDLffShape::SetAttributes method sets the attributes for a specified entity in a Shapefile object. Syntax es, Index, Attribute_Num, Value or Obj->[IDLffShape::]SetAttributes, Index, Attributes Arguments Index A scalar specifying the entity in which you want to set the attributes. The first entity in the Shapefile object is 0. Attribute_Num The field number for the attribute whose value is being set. This value is 0-based. Value The value that the attribute is being set to. If the value is not of the correct type, type conversion is attempted. If Value is an array and Index is a scalar, the value of record is treated as a starting point. Using this feature, all the attribute values of a specific field can be set for a Shapefile. Attributes An Attribute structure whose fields match the fields in the attribute table. If Attributes is an array, the entities specified in Index, up to the size of the Attributes array, are set. Using this feature, all the attribute values of a set of entities can be set for a Shapefile. The type of this Attribute structure must match the type that is generated internally for Attribute table. To get a copy of this structure, either get the attribute set for an entity or get the definition using the ATTRIBUTE_STRUCTURE keyword of the IDLffShape::GetProperty method. Keywords None. Example In the following example, we create a new shapefile, define the attributes for the new file, define a new entity, define some attributes, insert the new entity, and then use the SetAttributes method to insert the attributes into the new file: PRO ex_shapefile_newfile ;Create the new shapefile and define the entity type to Point mynewshape=OBJ_NEW('IDLffShape', FILEPATH('cities.shp', $ SUBDIR=['examples', 'data']), /UPDATE, ENTITY_TYPE=1) ;Set the attribute definitions for the new Shapefile tribute, 'CITY_NAME', 7, 25, $ PRECISION=0 tribute, 'STAT_NAME', 7, 25, $ PRECISION=0 ;Create structure for new entity entNew = {IDL_SHAPE_ENTITY} ; Define the values for the new entity entNew.SHAPE_TYPE = 1 entNew.ISHAPE = 1458 entNew.BOUNDS[0] = -104.87270 entNew.BOUNDS[1] = 39.768040 entNew.BOUNDS[2] = 0.00000000 entNew.BOUNDS[3] = 0.00000000 entNew.BOUNDS[4] = -104.87270 entNew.BOUNDS[5] = 39.768040 entNew.BOUNDS[6] = 0.00000000 entNew.BOUNDS[7] = 0.00000000 ;Create structure for new attributes attrNew = mynewshape ->IDLffShape::GetAttributes( $ /ATTRIBUTE_STRUCTURE) ;Define the values for the new attributes attrNew.ATTRIBUTE_0 = 'Denver' attrNew.ATTRIBUTE_1 = 'Colorado' ;Add the new entity to new shapefile mynewshape -> IDLffShape::PutEntity, entNew ;Add the Colorado attributes to new shapefile mynewshape -> IDLffShape::SetAttributes, 0, attrNew ;Close the shapefile OBJ_DESTROY, mynewshape END IDLGRAXIS [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrAxis An axis object represents a single vector that may include a set of tick marks, tick labels, and a title. An IDLgrAxis object is an atomic graphic object; it is one of the basic drawable elements of the IDL Object Graphics system, and it is not a container for other objects. Superclasses This class has no superclasses. Subclasses This class has no subclasses. Creation See "IDLgrAxis::Init" on page 1933. Methods Intrinsic Methods This class has the following methods: * IDLgrAxis::Cleanup * IDLgrAxis::GetCTM * IDLgrAxis::GetProperty * IDLgrAxis::Init * IDLgrAxis::SetProperty IDLGRAXIS::CLEANUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrAxis::Cleanup The IDLgrAxis::Cleanup procedure method performs all cleanup on the object. Note Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass. Syntax OBJ_DESTROY, Obj or Obj -> [IDLgrAxis::]Cleanup(Only in subclass' Cleanup method.) Arguments None Keywords None IDLGRAXIS::GETCTM [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrAxis::GetCTM The IDLgrAxis::GetCTM function method returns the 4 x 4 double-precision floating-point graphics transform matrix from the current object upward through the graphics tree. Syntax Result = Obj -> [IDLgrAxis::]GetCTM( [, DESTINATION=objref] [, PATH=objref(s)] [, TOP=objref] ) Arguments None Keywords DESTINATION Set this keyword to the object reference of a destination object to specify that the projection matrix for the View object in the current tree be included in the returned transformation matrix. The resulting matrix will transform a point in the data space of the object on which the GetCTM method is called into a normalized coordinate system (-1 to +1 in X, Y, and Z), relative to the View object that contains the axis object. PATH Set this keyword to a single object reference or a vector of object references. This keyword specifies the path in the graphics hierarchy to compute the transformation matrix. Each path object reference specified with this keyword must contain an alias. The transformation matrix is computed for the version of the object falling within that path. If this keyword is not set, the PARENT properties determine the path from the current object to the top of the graphics hierarchy and no alias paths are pursued. If IDLgrAxis::GetCTM is called from within a Draw method, with the DESTINATION keyword set and the PATH keyword not set, the alias path used to find the object during the draw is used, rather than the PARENT path. Note For more information on aliases, refer to the ALIAS keyword in IDLgrModel::Add. TOP Set this keyword equal to the object reference to an IDLgrModel object to specify that the returned matrix accumulate from the object on which the GetCTM method is called up to but not including the specified model object. IDLGRAXIS::GETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrAxis::GetProperty The IDLgrAxis::GetProperty procedure method retrieves the value of a property or group of properties for the axis. Syntax Obj -> [IDLgrAxis::]GetProperty [, ALL=variable] [, CRANGE=variable] [, PARENT=variable] [, XRANGE=variable] [, YRANGE=variable] [, ZRANGE=variable] Arguments None Keywords Any keyword to IDLgrAxis::Init followed by "Get" can be retrieved using IDLgrAxis::GetProperty. In addition, the following keywords are available: ALL Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the properties associated with the state of this object. State information about the object includes things like color, range, tick direction, etc., but not image, vertex, or connectivity data, or user values. Note The fields of this structure may change in subsequent releases of IDL. CRANGE Set this keyword to a named variable that will contain the actual full range of the axis as a double-precision floating-point vector of the form [minval, maxval]. This range may not exactly match the requested range provided via the RANGE keyword in the Init and SetProperty methods. Adjustments may have been made to round to the nearest even tick interval or to accommodate the EXTEND keyword. PARENT Set this keyword equal to a named variable that will contain an object reference to the object that contains this object. XRANGE Set this keyword equal to a named variable that will contain a two-element double- precision floating-point vector of the form [xmin, xmax] that specifies the range of x data coordinates covered by the graphic object. YRANGE Set this keyword equal to a named variable that will contain a two-element double- precision floating-point vector of the form [ymin, ymax] that specifies the range of y data coordinates covered by the graphic object. ZRANGE Set this keyword equal to a named variable that will contain a two-element double- precision floating-point vector of the form [zmin, zmax] that specifies the range of z data coordinates covered by the graphic object. IDLGRAXIS::INIT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrAxis::Init The IDLgrAxis::Init function method initializes an axis object. Note Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass. Syntax Obj = OBJ_NEW('IDLgrAxis' [, Direction] [, AM_PM{Get, Set}=array] [, COLOR{Get, Set}=index or RGB_vector] [, DAYS_OF_WEEK{Get, Set}=array] [, DIRECTION{Get, Set}=integer] [, /EXACT{Get, Set}] [, /EXTEND{Get, Set}] [, GRIDSTYLE{Get, Set}=integer{0 to 6}or [repeat{1 to 255}, bitmask]] [, /HIDE{Get, Set}] [, LOCATION{Get, Set}=[x, y] or [x, y, z]] [, /LOG{Get, Set}] [, MAJOR{Get, Set}=integer] [, MINOR{Get, Set}=integer] [, MONTHS{Get, Set}=array] [, NAME{Get, Set}=string] [, /NOTEXT{Get, Set}] [, PALETTE{Get, Set}=objref] [, RANGE{Get, Set}=[min, max]] [, SUBTICKLEN{Get, Set}=value] [, TEXTALIGNMENTS{Get, Set}=[horiz{0.0 to 1.0}, vert{0.0 to 1.0}]] [, TEXTBASELINE{Get, Set}=vector] [, TEXTPOS{Get, Set}={0 | 1}] [, TEXTUPDIR{Get, Set}=vector] [, THICK{Get, Set}=points{1.0 to 10.0}] [, TICKDIR{Get, Set}={0 | 1}] [, TICKFORMAT{Get, Set}=string or array of strings] [, TICKFRMTDATA{Get, Set}=value] [, TICKINTERVAL{Get, Set}=value] [, TICKLAYOUT{Get, Set}=scalar] [, TICKLEN{Get, Set}=value] [, TICKTEXT{Get, Set}=objref or vector] [, TICKUNITS{Get, Set}=string] [, TICKVALUES{Get, Set}=vector] [, TITLE{Get, Set}=objref] [, /USE_TEXT_COLOR{Get, Set}] [, UVALUE{Get, Set}=value] [, XCOORD_CONV{Get, Set}=vector] [, YCOORD_CONV{Get, Set}=vector] [, ZCOORD_CONV{Get, Set}=vector] ) or Result = Obj -> [IDLgrAxis::]Init( [Direction] ) (Only in a subclass' Init method.) Note Keywords can be used in either form. They are omitted in the second form for brevity. Arguments Direction An integer value specifying which axis is being created. Specify 0 (zero) to create an X axis, 1 (one) to create a Y axis, or 2 to create a Z axis. Keywords Properties retrievable via IDLgrAxis::GetProperty are indicated by the word "Get" following the keyword. Properties settable via IDLgrAxis::SetProperty are indicated by the word "Set" following the keyword. AM_PM (Get, Set) Supplies a string array of 2 names to be used for the names of the AM and PM string when processing explicitly formatted dates (CAPA, CApA, and CapA format codes) with the TICKFORMAT keyword. COLOR (Get, Set) Set this keyword to the color to be used as the foreground color for this axis. The color may be specified as a color lookup table index or as an RGB vector. The default is [0, 0, 0]. DAYS_OF_WEEK (Get, Set) Supplies a string array of 7 names to be used for the names of the days of the week when processing explicitly formatted dates (CDWA, CDwA, and CdwA format codes) with the TICKFORMAT keyword. DIRECTION (Get, Set) Set this keyword to an integer value specifying which axis is being created. Specify 0 (zero) to create an X axis, 1 (one) to create a Y axis, or 2 to create a Z axis. Specifying this keyword is the same as specifying the optional Direction argument. EXACT (Get, Set) Set this keyword to force the axis range to be exactly as specified. If this keyword is not set, the range may be lengthened or shortened slightly to allow for evenly spaced tick marks. EXTEND (Get, Set) Set this keyword to a nonzero value to extend the axis slightly beyond the specified range. This can be useful when you specify the axis range based on the minimum and maximum data values, but do not want the graphic to extend all the way to the end of the axis. GRIDSTYLE (Get, Set) Set this keyword to indicate the line style that should be used to draw the axis' tick marks. The value can be either an integer value specifying a pre-defined line style, or a two-element vector specifying a stippling pattern. To use a pre-defined line style, set the GRIDSTYLE property equal to one of the following integer values: * 0 = Solid line (the default) * 1 = dotted * 2 = dashed * 3 = dash dot * 4 = dash dot dot * 5 = long dash * 6 = no line drawn To define your own stippling pattern, specify a two-element vector [repeat, bitmask], where repeat indicates the number of times consecutive runs of 1's or 0's in the bitmask should be repeated. (That is, if three consecutive 0's appear in the bitmask and the value of repeat is 2, then the line that is drawn will have six consecutive bits turned off.) The value of repeat must be in the range 1 repeat 255. The bitmask indicates which pixels are drawn and which are not along the length of the line. Bitmask is most conveniently specified as a 16-bit hexadecimal value. For example, GRIDSTYLE = [2, 'F0F0'X] describes a dashed line (8 bits on, 8 bits off, 8 bits on, 8 bits off). HIDE (Get, Set) Set this keyword to a boolean value indicating whether this object should be drawn: * 0 = Draw graphic (the default) * 1 = Do not draw graphic LOCATION (Get, Set) Set this keyword to a two- or three-element vector of the form [x, y] or [x, y, z] to specify the coordinate through which the axis should pass. The default is [0, 0, 0]. IDL converts, maintains, and returns this data as double-precision floating-point. LOG (Get, Set) Set this keyword to indicate that the axis is logarithmic. MAJOR (Get, Set) Set this keyword to an integer representing the number of major tick marks. The default is -1, specifying that IDL will compute the number of tickmarks. Setting MAJOR equal to zero suppresses major tickmarks entirely. MINOR (Get, Set) Set this keyword to an integer representing the number of minor tick marks. The default is -1, specifying that IDL will compute the number of tickmarks. Setting MINOR equal to zero suppresses minor tickmarks entirely. MONTHS (Get, Set) Supplies a string array of 12 names to be used for the names of the months when processing explicitly formatted dates (CMOA, CMoA, and CmoA format codes) with the TICKFORMAT keyword. NAME (Get, Set) Set this keyword equal to a string containing the name associated with this object. The default is the null string, ' '. NOTEXT (Get, Set) Set this keyword to prevent the tick labels and the axis title from being drawn. PALETTE Set this keyword equal to the object reference of a palette object (an instance of the IDLgrPalette object class). This keyword is only used if the destination device is using the RGB color model. If so, and a color value for the object is specified as a color index value, the palette set by this keyword is used to translate the color to RGB space. If the PALETTE property on this object is not set, the destination object PALETTE property is used (which defaults to a grayscale ramp). RANGE (Get, Set) Set this keyword to a two-element vector containing the minimum and maximum data values covered by the axis. The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double-precision floating-point. SUBTICKLEN (Get, Set) Set this keyword to a scale ratio specifying the length of minor tick marks relative to the length of major tick marks. The default is 0.5, specifying that the minor tick mark is one-half the length of the major tick mark. TEXTALIGNMENTS (Get, Set) Set this keyword to a two-element floating-point vector, [horizontal, vertical], specifying the horizontal and vertical alignments for the tick text. Each alignment value should be a value between 0.0 and 1.0. For horizontal alignment, 0.0 left- justifies the text; 1.0 right-justifies the text. For vertical alignment, 0.0 bottom- justifies the text, 1.0 top-justifies the text. The defaults are as follows: * X-Axis: [0.5, 1.0] (centered horizontally, top-justified vertically) * Y-Axis: [1.0, 0.5] (right-justified horizontally, centered vertically) * Z-Axis: [1.0, 0.5] (right-justified horizontally, centered vertically) TEXTBASELINE (Get, Set) Set this keyword to a two- or three-element vector describing the direction in which the baseline of the tick text is to be oriented. Use this keyword in conjunction with the TEXTUPDIR keyword to specify the plane on which the tick text lies. The default is [1,0,0]. TEXTPOS (Get, Set) Set this keyword to either a zero or one to indicate on which side of the axis the tick text labels are to be drawn. The table below describes the placement of the tick text with each setting. Axis TEXTPOS=0 TEXTPOS=1 Tick text will be drawn below Tick text will be drawn above the X axis, where below is the X axis, where above is X defined as being toward the described as being toward the direction of the negative Y axis direction of the positive Y axis. (this is the default). Tick text will be drawn to the Tick text will be drawn to the left of the Y Axis, where left is right of the Y axis, where right Y defined as being toward the is defined as being toward the direction of the negative X axis direction of the positive X axis. (this is the default). Tick text will be drawn to the Tick text will be drawn to the left of the Z axis, where left is right of the Z axis, where right Z defined as being toward the is defined as being toward the direction of the negative X axis direction of the positive X axis. (this is the default). Table A-23: Values for the TEXTPOS keyword TEXTUPDIR (Get,Set) Set this keyword to a two- or three-element vector describing the direction in which the up-vector of the tick text is to be oriented. Use this keyword in conjunction with the TEXTBASELINE keyword to specify the plane on which the tick text lies. TEXTUPDIR should be orthogonal to TEXTBASELINE. The default is as follows: * X-Axis: [0, 1, 0] * Y-Axis: [0, 1, 0] * Z-Axis: [0, 0, 1] THICK (Get, Set) Set this keyword to a value between 1.0 and 10.0, specifying the line thickness used to draw the axis, in points. The default is 1.0 points. TICKDIR (Get, Set) Set this keyword to either zero or one to indicate the tick mark direction. For an X axis, setting TICKDIR=0 means the tick marks will be drawn above the X axis, in the direction of the positive Y axis (this is the default); setting TICKDIR=1 means the tick marks will be drawn below the X axis. For a Y axis, setting TICKDIR=0 means the tick marks will be drawn to the right of the Y axis, in the direction of the positive X axis (this is the default); setting TICKDIR=1 means the tick marks will be drawn to the left of the Y axis. For a Z axis, setting TICKDIR=0 means the tick marks will be drawn to the right the Z axis, in the direction of the positive X axis (this is the default); setting TICKDIR=1 means the tick marks will be drawn to the left of the Z axis. TICKFORMAT (Get, Set) Set this keyword to a string (or an array of strings), where each string represents a format string or the name of a function to be used to format the tick mark labels. If an array is provided, each string corresponds to a level of the axis. (The TICKUNITS keyword determines the number of levels for an axis.) If the string begins with an open parenthesis, it is treated as a standard format string. (Refer to the Format Codes in the IDL Reference Guide.) If the string does not begin with an open parenthesis, it is interpreted as the name of a callback function to be used to generate tick mark labels. If TICKUNITS are not specified: * The callback function is called with three parameters: Axis, Index, and Value, where: * Axis is the axis number: 0 for X axis, 1 for Y axis, 2 for Z axis * Index is the tick mark index (indices start at 0) * Value is the data value at the tick mark (a double-precision floating point value) If TICKUNITS are specified: The callback function is called with four parameters: Axis, Index, Value, and Level, where: * Axis, Index, and Value are the same as described above. * Level is the index of the axis level for the current tick value to be labeled. (Level indices start at 0.) Used with the LABEL_DATE function, this keyword can easily create axes with date/time labels. TICKFRMTDATA (Get, Set) Set this keyword to a value of any type. It will be passed via the DATA keyword to the user-supplied formatting function specified via the TICKFORMAT keyword, if any. By default, this value is 0, indicating that the DATA keyword will not be set (and furthermore, need not be supported by the user-supplied function.) Note TICKFRMTDATA will not be included in the structure returned via the ALL keyword to the IDLgrColorbar::GetProperty method. TICKINTERVAL (Get, Set) Set this keyword to a scalar indicating the interval between major tick marks for the first axis level. The default value is computed according to the axis RANGE and the number of major tick marks (MAJOR). This keyword takes precedence over MAJOR. For example, if TICKUNITS=['S','H','D'], and TICKINTERVAL=30, then the interval between major ticks for the first axis level will be 30 seconds. TICKLAYOUT (Get, Set) Set this keyword to a scalar that indicates the tick layout style to be used to draw each level of the axis. Valid values include: 0 = The axis line, major tick marks and tick labels are all included. Minor tick marks only appear on the first level of the axis. This is the default tick layout style. 1 = Only the labels for the major tick marks are drawn. The axis line, major tick marks, and minor tick marks are omitted. 2 = Each major tick interval is outlined by a box. The tick labels are positioned within that box (left-aligned). For the first axis level only, the major and minor tick marks will also be drawn. Note For all tick layout styles, at least one tick label will appear on each level of the axis (even if no major tick marks fall along the axis line). If there are no major tick marks, the single tick label will be centered along the axis. TICKLEN (Get, Set) Set this keyword to the length of each major tick mark, measured in data units. The recommended, and default, tick mark length is 0.2. IDL converts, maintains, and returns this data as double-precision floating-point. TICKTEXT (Get, Set) Set this keyword to either a single instance of the IDLgrText object class (with multiple strings) or to a vector of instances of the IDLgrText object class (one per major tick) to specify the annotations to be assigned to the tickmarks. By default, with TICKTEXT set equal to a null object, IDL computes the tick labels based on major tick values. The positions of the provided text objects may be overwritten; position is determined according to tick mark location. The tickmark text will have the same color as the IDLgrAxis object, regardless of the color specified by the COLOR property of the IDLgrText object or objects, unless the USE_TEXT_COLOR keyword is specified. Note If IDL computes the tick labels, the text object it creates will be destroyed automatically when the axis object is destroyed, even if you have altered the properties of the text object. If you create your own text object containing tickmark text, however, it will not be destroyed automatically. TICKUNITS (Get, Set) Set this keyword to a string (or a vector of strings) indicating the units to be used for axis tick labeling. If more than one unit is provided, the axis will be drawn in multiple levels, one level per unit. The order in which the strings appear in the vector determines the order in which the corresponding unit levels will be drawn. The first string corresponds to the first level (the level nearest to the primary axis line). Valid unit strings include: * "Numeric" * "Years" * "Months" * "Days" * "Hours" * "Minutes" * "Seconds" * "Time" - Use this value to indicate that the tick values are time values; IDL will determine the appropriate time intervals and tick label formats based upon the range of values covered by the axis. * ""- Use the empty string to indicate that no tick units are being explicitly set. This implies that a single axis level will be drawn using the "Numeric" unit. This is the default setting. If any of the time units are utilized, then the tick values are interpreted as Julian date/time values. Note that the singular form of each of the time value strings is also acceptable (e.g, TICKUNITS='Day' is equivalent to TICKUNITS='Days'). Note Julian values must be in the range -1095 to 1827933925, which corresponds to calendar dates 1 Jan 4716 B.C.E. and 31 Dec 5000000, respectively. TICKVALUES (Get, Set) Set this keyword to a vector of data values representing the values at each tick mark. If TICKVALUES is set to 0, the default, IDL computes the tick values based on the axis range and the number of major ticks. IDL converts, maintains, and returns this data as double-precision floating-point. TITLE (Get, Set) Set this keyword to an instance of the IDLgrText object class to specify the title for the axis. The default is the null object, specifying that no title is drawn. The title will be centered along the axis, even if the text object itself has an associated location. The title will have the same color as the IDLgrAxis object, regardless of the color specified by the COLOR property of the IDLgrText object, unless the USE_TEXT_COLOR keyword is specified. USE_TEXT_COLOR (Get, Set) Set this keyword to indicate that, for the tick text and/or title of the axis, the color property values set for the given IDLgrText objects are to be used to draw those text items. By default, this value is zero, indicating that the color properties of the IDLgrText objects will be ignored, and that the COLOR property for the axis object will be used for these text items instead. UVALUE (Get, Set) Set this keyword to a value of any type. You can use this "user value" to contain any information you wish. Remember that if you set the user value equal to a pointer or object reference, you should destroy the pointer or object reference explicitly when destroying the object it is a user value of. XCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert X coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedX = s0 + s1 * DataX Recommended values are: [(-Xmin)/(Xmax-Xmin), 1/(Xmax-Xmin)] The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double- precision floating-point. YCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert Y coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedY = s0 + s1 * DataY Recommended values are: [(-Ymin)/(Ymax-Ymin), 1/(Ymax-Ymin)] The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double- precision floating-point. ZCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert Z coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedZ = s0 + s1 * DataZ Recommended values are: [(-Zmin)/(Zmax-Zmin), 1/(Zmax-Zmin)] The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double- precision floating-point. IDLGRAXIS::SETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrAxis::SetProperty The IDLgrAxis::SetProperty procedure method sets the value of a property or group of properties for the axis. Syntax Obj -> [IDLgrAxis::]SetProperty Arguments None Keywords Any keyword to IDLgrAxis::Init followed by the word "Set" can be set using IDLgrAxis::SetProperty. IDLGRBUFFER [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrBuffer An IDLgrBuffer object is an in-memory, off-screen destination object. Object trees can be drawn to instances of the IDLgrBuffer object and the resulting image can be retrieved from the buffer using the Read() method. The off-screen representation avoids dithering artifacts by providing a full-resolution buffer for objects using either the RGB or Color Index color models. Note Objects or subclasses of this type can not be saved or restored. Superclasses This class has no superclasses. Subclasses This class has no subclasses. Creation See "IDLgrBuffer::Init" on page 1957. Methods Intrinsic Methods This class has the following methods: * IDLgrBuffer::Cleanup * IDLgrBuffer::Draw * IDLgrBuffer::Erase * IDLgrBuffer::GetContiguousPixels * IDLgrBuffer::GetDeviceInfo * IDLgrBuffer::GetFontnames * IDLgrBuffer::GetProperty * IDLgrBuffer::GetTextDimensions * IDLgrBuffer::Init * IDLgrBuffer::PickData * IDLgrBuffer::Read * IDLgrBuffer::Select * IDLgrBuffer::SetProperty IDLGRBUFFER::CLEANUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrBuffer::Cleanup The IDLgrBuffer::Cleanup procedure method performs all cleanup on the object. Note Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass. Syntax OBJ_DESTROY, Obj or Obj -> [IDLgrBuffer::]Cleanup(Only in subclass' Cleanup method.) Arguments None Keywords None IDLGRBUFFER::DRAW [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrBuffer::Draw The IDLgrBuffer::Draw procedure method draws the given picture to this graphics destination. Note Objects are drawn to the destination device in the order that they are added to the model, view, viewgroup, or scene object that contains them. Syntax Obj -> [IDLgrBuffer::]Draw [, Picture] [, CREATE_INSTANCE={1 | 2}] [, /DRAW_INSTANCE] Arguments Picture The view (an instance of an IDLgrView object), viewgroup (an instance of an IDLgrViewgroup object) or scene (an instance of an IDLgrScene object) to be drawn. Keywords CREATE_INSTANCE Set this keyword equal to one to specify that this scene or view is the unchanging part of a drawing. Some destinations can make an instance from the current window contents without having to perform a complete redraw. If the view or scene to be drawn is identical to the previously drawn view or scene, this keyword can be set equal to 2 to hint the destination to create the instance from the current window contents if it can. DRAW_INSTANCE Set this keyword to specify that this scene, viewgroup, or view is the changing part of the drawing. It is overlaid on the result of the most recent CREATE_INSTANCE draw. IDLGRBUFFER::ERASE [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrBuffer::Erase The IDLgrBuffer::Erase procedure method erases this graphics destination. Syntax Obj -> [IDLgrBuffer::]Erase [, COLOR=index or RGB vector] Arguments None Keywords COLOR Set this keyword to the color to be used for the erase. The color may be specified as a color lookup table index or as an RGB vector. IDLGRBUFFER::GETCONTIGUOUSPIXELS [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrBuffer::GetContiguousPixels The IDLgrBuffer::GetContiguousPixels function method returns an array of long integers whose length is equal to the number of colors available in the index color mode (that is, the value of the N_COLORS property). The returned array marks contiguous pixels with the ranking of the range's size. This means that within the array, the elements in the largest available range are set to zero, the elements in the second-largest range are set to one, etc. Use this range to set an appropriate colormap for use with the SHADE_RANGE property of the IDLgrSurface and IDLgrPolygon object classes. To get the largest contiguous range, you could use the following IDL command: result = obj -> GetContiguousPixels() Range0 = WHERE(result EQ 0) A contiguous region in the colormap can be increasing or decreasing in values. The following would be considered contiguous: [0,1,2,3,4] [4,3,2,1,0] Syntax Return = Obj -> [IDLgrBuffer::]GetContiguousPixels() Arguments None Keywords None IDLGRBUFFER::GETDEVICEINFO [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrBuffer::GetDeviceInfo The IDLgrBuffer::GetDeviceInfo procedure method returns information which allows IDL applications to intelligently make decisions for optimal performance. For example, it allows an application to determine if RENDERER=1 is actually implemented in hardware. It also allows applications to make optimal quality decisions when dynamically building texture maps. Syntax Obj­>[IDLgrBuffer::]GetDeviceInfo [, ALL=variable] [, MAX_TEXTURE_DIMENSIONS=variable] [, MAX_VIEWPORT_DIMENSIONS=variable] [, NAME=variable] [, NUM_CPUS=variable] [, VENDOR=variable] [, VERSION=variable] Arguments None. Keywords ALL Set this keyword to a named variable which, upon return, contains a structure with the values of all the device information keywords as fields. MAX_TEXTURE_DIMENSIONS Set this keyword equal to a named variable. Upon return, MAX_TEXTURE_DIMENSIONS contains a two-element integer array that specifies the maximum texture size supported by the device. MAX_VIEWPORT_DIMENSIONS Set this keyword equal to a named variable. Upon return, MAX_VIEWPORT_DIMENSIONS contains a two-element integer array that specifies the maximum size of a graphics display supported by the device. NAME Set this keyword equal to a named variable. Upon return, NAME contains the name of the rendering device as a string. NUM_CPUS Set this keyword equal to a named variable. Upon return, NUM_CPUS contains an integer that specifies the number of CPUs that are known to, and available to IDL. Note The NUM_CPUS keyword accurately returns the number of CPUs for the SGI Irix, SUN, and Microsoft Windows platforms. For platforms other than these, the number returned may not reflect the actual number of CPUs available to IDL in the current system. VENDOR Set this keyword equal to a named variable. Upon return, VENDOR contains the name of the rendering device creator as a string. VERSION Set this keyword equal to a named variable. Upon return, VERSION contains the version of the rendering device driver as a string. IDLGRBUFFER::GETFONTNAMES [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrBuffer::GetFontnames The IDLgrBuffer::GetFontnames function method returns the list of available fonts that can be used in IDLgrFont objects. This method will only return the names of the available TrueType fonts. Hershey fonts will not be returned. See Appendix H, "Fonts" for more information. Syntax Return = Obj -> [IDLgrBuffer::]GetFontnames( FamilyName[, IDL_FONTS={0 | 1 | 2 }] [, STYLES=string] ) Arguments FamilyName A string representing the name of the font family to which all of the returned fonts must belong. The string may be a fully specified family name-such as "Helvetica". You can use both "*" and "?" as wildcard characters, matching any number of characters or one character respectively. To return all available family names, use "*". Keywords IDL_FONTS Set this keyword to specify where to search for fonts that IDL may use. Set IDL_FONT to 1 to select only fonts installed by IDL and to 2 to select only fonts detected in the host operating system. The default value is 0, specifying that both IDL and operating system fonts should be returned. STYLES Set this keyword to a string specifying the styles that are to be matched by the returned font names. You can set STYLES to a fully specified style string, such as "Bold Italic". If you set STYLES to the null string, ' ', only fontnames without style modifiers will be returned. You can use both "*" and "?" as wildcard characters, matching any number of characters or one character respectively. The default value is the string, "*", which returns all fontnames containing the FamilyName argument, with or without style modifiers. IDLGRBUFFER::GETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrBuffer::GetProperty The IDLgrBuffer::GetProperty procedure method retrieves the value of a property or group of properties for the buffer. Syntax Obj -> [IDLgrBuffer::]GetProperty [, ALL=variable] [, IMAGE_DATA=variable] [, SCREEN_DIMENSIONS=variable] [, ZBUFFER_DATA=variable] Keywords Any keyword to IDLgrBuffer::Init followed by the word "Get" can be retrieved using IDLgrBuffer::GetProperty. In addition, the following keywords are available: ALL Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the retrievable properties associated with this object (except IMAGE_DATA and ZBUFFER_DATA). IMAGE_DATA Set this keyword to a named variable that will contain a byte array representing the image that is currently rendered within the buffer. If the buffer uses an RGB color model, the returned array will have dimensions (3, xdim, ydim). If the window object uses an indexed color model, the returned array will have dimensions (xdim, ydim). SCREEN_DIMENSIONS Set this keyword to a named variable that will contain a two-element vector of the form [width, height] specifying the maximum allowed dimensions (measured in device units) for the buffer object. ZBUFFER_DATA Set this keyword to a named variable that will contain a float array representing the zbuffer that is currently within the buffer. The returned array will have dimensions (xdim, ydim). IDLGRBUFFER::GETTEXTDIMENSIONS [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrBuffer::GetTextDimensions The IDLgrBuffer::GetTextDimensions function method retrieves the dimensions of a text object that will be rendered in a window. The result is a 3-element double- precision floating-point vector [xDim, yDim, zDim] representing the dimensions of the text object, measured in data units. Syntax Result = Obj ->[IDLgrBuffer::]GetTextDimensions( TextObj [, DESCENT=variable] [, PATH=objref(s)] ) Arguments TextObj The object reference to a text or axis object for which text dimensions are requested. Keywords DESCENT Set this keyword equal to a named variable that will contain an array of double- precision floating-point values (one for each string in the IDLgrText object). The values represent the distance to travel (parallel to the UPDIR vector) from the text baseline to reach the bottom of the lowest descender in the string. All values will be negative numbers, or zero. This keyword is valid only if TextObj is an IDLgrText object. PATH Set this keyword to a single object reference or a vector of object references. This keyword specifies the path in the graphics hierarchy to compute the text dimensions. Each path object reference specified with this keyword must contain an alias. The text dimensions are computed for the version of the object falling within that path. If this keyword is not set, the PARENT properties determine the path from the current object to the top of the graphics hierarchy and no alias paths are pursued. If IDLgrBuffer::GetTextDimensions is called from within a Draw method and the PATH keyword is not set, the alias path used to find the object during the draw is used, rather than the PARENT path. Note For more information on aliases, refer to the ALIAS keyword in IDLgrModel::Add IDLGRBUFFER::INIT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrBuffer::Init The IDLgrBuffer::Init function method initializes the buffer object. Note Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass. Syntax Obj = OBJ_NEW('IDLgrBuffer' [, COLOR_MODEL{Get}={0 | 1}] [, DIMENSIONS{Get, Set}=[width, height]] [, GRAPHICS_TREE{Get, Set}=objref] [, N_COLORS{Get}=integer{2 to 256}] [, PALETTE{Get, Set}=objref] [, QUALITY{Get, Set}={0 | 1 | 2}] [, RESOLUTION{Get, Set}=[xres, yres]] [, UNITS{Get, Set}={0 | 1 | 2 | 3}] [, UVALUE{Get, Set}=value] ) or Result = Obj -> [IDLgrBuffer::]Init( ) (Only in a subclass' Init method.) Note Keywords can be used in either form. They are omitted in the second form for brevity. Arguments None Keywords Properties retrievable via IDLgrBuffer::GetProperty are indicated by the word "Get" following the keyword. Properties settable via IDLgrBuffer::SetProperty are indicated by the word "Set" following the keyword. COLOR_MODEL (Get) Set this keyword to the color model to be used for the buffer: * 0 = RGB (default) * 1 = Color Index DIMENSIONS (Get, Set) Set this keyword to a two-element vector of the form [width, height] to specify the dimensions of the buffer in units specified by the UNITS property. The default is [640,480]. GRAPHICS_TREE (Get, Set) Set this keyword to an object reference of type IDLgrScene, IDLgrViewgroup, or IDLgrView. If this property is set to a valid object reference, calling the Draw method on the destination object with no arguments will cause the object reference associated with this property to be drawn. If this object is valid and the destination object is destroyed, this object reference will be destroyed as well. By default the GRAPHICS_TREE property is set equal to the null-object. N_COLORS (Get) Set this keyword to the number of colors (between 2 and 256) to be used if COLOR_MODEL is set to Color Index. PALETTE (Get, Set) Set this keyword to the object reference of a palette object (an instance of the IDLgrPalette object class) to specify the red, green, and blue values that are to be loaded into the buffer's color lookup table. QUALITY (Get, Set) Set this keyword to an integer indicating the rendering quality at which graphics are to be drawn to the buffer. Valid values are: * 0 = Low * 1 = Medium * 2 = High (default) RESOLUTION (Get, Set) Set this keyword to a two-element vector of the form [xres, yres] specifying the device resolution in centimeters per pixel. This value is stored in double precision. The default value is: [0.035277778, 0.035277778] (72 DPI). UNITS (Get, Set) Set this keyword to indicate the units of measure for the DIMENSIONS property. Valid values are: * 0 = Device (default) * 1 = Inches * 2 = Centimeters * 3 = Normalized: relative to 1600 x 1200 UVALUE (Get, Set) Set this keyword to a value of any type. You can use this "user value" to contain any information you wish. Remember that if you set the user value equal to a pointer or object reference, you should destroy the pointer or object reference explicitly when destroying the object it is a user value of. IDLGRBUFFER::PICKDATA[1] [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrBuffer::PickData The IDLgrBuffer::Pickdata function method maps a point in the two-dimensional device space of the buffer to a point in the three-dimensional data space of an object tree. The resulting 3D data space coordinates are returned in a user-specified variable. The Pickdata function returns one if the specified location in the buffer's device space "hits" a graphic object, or zero otherwise. Syntax Result = Obj -> [IDLgrBuffer::]PickData( View, Object, Location, XYZLocation [, DIMENSIONS] [, PATH=objref(s)] ) Arguments View The object reference of an IDLgrView object that contains the object being picked. Object The object reference of a model or atomic graphic object from which the data space coordinates are being requested. Location A two-element vector [x, y] specifying the location in the buffer's device space of the point to pick data from. XYZLocation A named variable that will contain the three-dimensional double-precision floating- point data space coordinates of the picked point. Note that the value returned in this variable is a location, not a data value. Note If the atomic graphic object specified as the target has been transformed using either the LOCATION or DIMENSIONS properties (this is only possible with IDLgrAxis, IDLgrImage, and IDLgrText objects), these transformations will not be included in the data coordinates returned by the Pickdata function. This means that you may need to re-apply the transformation accomplished by specifying LOCATION or DIMENSIONS once you have retrieved the data coordinates with Pickdata. This situation does not occur if you transform the axis, text, or image object using the [XYZ]COORD_CONV properties. Keywords DIMENSIONS Set this keyword to a two-element array [w, h] to specify data picking should occur for all device locations that fall within a pick box of these dimensions. The pick box will be centered about the coordinates [x, y] specified in the Location argument, and will occupy the rectangle defined by: (x-(w/2), y-(h/2)) - (x+(w/2), y+(h/2)) By default, the pick box covers a single pixel. The return value of the Pickdata method will match the dimensions of the pick box. Likewise, the array returned via the XYZLocation argument will have dimensions [3, w, h]. PATH Set this keyword to a single object reference or a vector of object references. This keyword specifies the path in the graphics hierarchy to map the device position to a data space coordinate. Each path object reference specified with this keyword must contain an alias. The data space coordinate is computed for the version of the object falling within that path. If this keyword is not set, the PARENT properties determine the path from the current object to the top of the graphics hierarchy and no alias paths are pursued. Note For more information on aliases, refer to the ALIAS keyword in IDLgrModel::Add. IDLGRBUFFER::READ [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrBuffer::Read The IDLgrWindow::Read function method reads an image from a buffer. The returned value is an instance of the IDLgrImage object class. Syntax Result = Obj -> [IDLgrBuffer::]Read() Arguments None Keywords None IDLGRBUFFER::SELECT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrBuffer::Select The IDLgrBuffer::Select function method returns a list of objects selected at a specified location. If no objects are selected, the Select function returns -1. Note IDL returns a maximum of 512 objects. This maximum may be smaller if any of the objects are contained in deep model hierarchies. Because of this limit, it is possible that not all objects eligible for selection will appear in the list. Syntax Result = Obj -> [IDLgrBuffer::]Select(Picture, XY [, DIMENSIONS=[width, height]] [, UNITS={0 | 1 | 2 | 3}]) Arguments Picture The view, viewgroup, or scene (an instance of the IDLgrView, IDLgrViewgroup, or IDLgrScene class) whose children are among the candidates for selection. If the first argument is a scene or viewgroup, then the returned object list will contain one or more views. If the first argument is a view, the list will contain atomic graphic objects (or model objects which have their SELECT_TARGET property set). Objects are returned in order, according to their distance from the viewer. The closer an object is to the viewer, the lower its index in the returned object list. If multiple objects are at the same distance from the viewer (views in a scene or 2D geometry), the last object drawn will appear at a lower index in the list. XY A two-element array defining the center of the selection box in device space. By default, the selection box is 3 pixels by 3 pixels. Keywords DIMENSIONS Set this keyword to a two-element array [w, h] to specify that the selection box will have a width w and a height h, and will be centered about the coordinates [x, y] specified in the XY argument. The box occupies the rectangle defined by: (x-(w/2), y-(h/2)) - (x+(w/1), y+(h/2)) Any object which intersects this box is considered to be selected. By default, the selection box is 3 pixels by 3 pixels. UNITS Set this keyword to indicate the units of measure. Valid values are: * 0 = Device (default) * 1 = Inches * 2 = Centimeters * 3 = Normalized: relative to the dimensions of the graphics destination. IDLGRBUFFER::SETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrBuffer::SetProperty The IDLgrBuffer::SetProperty procedure method sets the value of a property or group of properties for the buffer. Syntax Obj -> [IDLgrBuffer::]SetProperty Arguments None Keywords Any keyword to IDLgrBuffer::Init followed by the word "Set" can be retrieved using IDLgrBuffer::SetProperty. IDLGRCLIPBOARD [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrClipboard An IDLgrClipboard object will send Object Graphics output to the operating system native clipboard in bitmap format. The format of bitmaps sent to the clipboard is operating system dependent: output is stored as a PICT image on the Macintosh, as a device-independent bitmap under Windows, and as an Encapsulated PostScript (EPS) image under UNIX and VMS. Note Objects or subclasses of this type can not be saved or restored. Superclasses This class has no superclasses. Subclasses This class has no subclasses. Creation See "IDLgrClipboard::Init" on page 1976. Methods Intrinsic Methods This class has the following methods: * IDLgrClipboard::Cleanup * IDLgrClipboard::Draw * IDLgrClipboard::GetContiguousPixels * IDLgrClipboard::GetDeviceInfo * IDLgrClipboard::GetFontnames * IDLgrClipboard::GetProperty * IDLgrClipboard::GetTextDimensions * IDLgrClipboard::Init * IDLgrClipboard::SetProperty IDLGRCLIPBOARD::CLEANUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrClipboard::Cleanup The IDLgrClipboard::Cleanup procedure method performs all cleanup on the object. Note Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass. Syntax OBJ_DESTROY, Obj or Obj-> [IDLgrClipboard::]Cleanup(Only in subclass' Cleanup method.) Arguments None Keywords None IDLGRCLIPBOARD::DRAW [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrClipboard::Draw The IDLgrClipboard::Draw procedure method draws the given picture to this graphics destination. Note Objects are drawn to the destination device in the order that they are added to the model, view, viewgroup, or scene object that contains them. Syntax Obj -> [IDLgrClipboard::]Draw [, Picture] [, FILENAME=string] [, POSTSCRIPT=value] [, VECTOR={ 0 | 1 } ] Arguments Picture The view (an instance of an IDLgrView object), viewgroup (an instance of an IDLgrViewgroup object) or scene (an instance of an IDLgrScene object) to be drawn. Keywords FILENAME Set this keyword to a string representing the name of a file to which the output should be written. By default, this keyword is the null string, indicating that the output is written to the clipboard. POSTSCRIPT Set this keyword to a nonzero value to indicate that the generated output should be in PostScript format. By default, the generated output is in Windows Enhanced Metafile Format on Windows platforms, PICT format on Macintosh platforms, and PostScript on Unix/VMS platforms. VECTOR Set this keyword to indicate the type of graphics primitives generated. Valid values include: 0 = Bitmap (default) 1 = Vector If VECTOR = 0 (Bitmap), the Draw method renders the scene to a buffer and then copies the buffer to the printer in bitmap format. The bitmap retains the quality of the original image, but the user cannot scale the bitmap effectively on all devices. If VECTOR = 1 (Vector), the Draw method renders the scene using simple vector operations that result in a representation of the Scene that is scalable to the printer. The vector representation does not retain all the attributes of the original image, however, a user can effectively scale it on other devices. On Windows, the representation is the Windows Enhanced Metafile (EMF). On UNIX platforms, the representation is PostScript. On Macintosh, it is PICT. IDLGRCLIPBOARD::GETCONTIGUOUSPIXELS [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrClipboard::GetContiguousPixels The IDLgrClipboard::GetContiguousPixels function method returns an array of long integers whose length is equal to the number of colors available in the index color mode (that is, the value of the N_COLORS property). The returned array marks contiguous pixels with the ranking of the range's size. This means that within the array, the elements in the largest available range are set to zero, the elements in the second-largest range are set to one, etc. Use this range to set an appropriate colormap for use with the SHADE_RANGE property of the IDLgrSurface and IDLgrPolygon object classes. To get the largest contiguous range, you could use the following IDL command: result = obj -> GetContiguousPixels() Range0 = WHERE(result EQ 0) A contiguous region in the colormap can be increasing or decreasing in values. The following would be considered contiguous: [0,1,2,3,4] [4,3,2,1,0] Syntax Return = Obj ->[IDLgrClipboard::]GetContiguousPixels() Arguments None Keywords None IDLGRCLIPBOARD::GETDEVICEINFO [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrClipboard::GetDeviceInfo The IDLgrClipboard::GetDeviceInfo procedure method returns information which allows IDL applications to intelligently make decisions for optimal performance. For example, it allows an application to determine if RENDERER=1 is actually implemented in hardware. It also allows applications to make optimal quality decisions when dynamically building texture maps. Syntax Obj­>[IDLgrClipboard::]GetDeviceInfo [, ALL=variable] [, MAX_TEXTURE_DIMENSIONS=variable] [, MAX_VIEWPORT_DIMENSIONS=variable] [, NAME=variable] [, NUM_CPUS=variable] [, VENDOR=variable] [, VERSION=variable] Arguments None. Keywords ALL Set this keyword to a named variable which, upon return, contains a structure with the values of all the device information keywords as fields. MAX_TEXTURE_DIMENSIONS Set this keyword equal to a named variable. Upon return, MAX_TEXTURE_DIMENSIONS contains a two element integer array that specifies the maximum texture size supported by the device. MAX_VIEWPORT_DIMENSIONS Set this keyword equal to a named variable. Upon return, MAX_VIEWPORT_DIMENSIONS contains a two element integer array that specifies the maximum size of a graphics display supported by the device. NAME Set this keyword equal to a named variable. Upon return, NAME contains the name of the rendering device as a string. NUM_CPUS Set this keyword equal to a named variable. Upon return, NUM_CPUS contains an integer that specifies the number of CPUs that are known to, and available to IDL. Note The NUM_CPUS keyword accurately returns the number of CPUs for the SGI Irix, SUN, and Microsoft Windows platforms. For platforms other than these, the number returned may not reflect the actual number of CPUs available to IDL in the current system. VENDOR Set this keyword equal to a named variable. Upon return, VENDOR contains the name of the rendering device creator as a string. VERSION Set this keyword equal to a named variable. Upon return, VERSION contains the version of the rendering device driver as a string. IDLGRCLIPBOARD::GETFONTNAMES [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrClipboard::GetFontnames The IDLgrClipboard::GetFontnames function method returns the list of available fonts that can be used in IDLgrFont objects. This method will only return the names of the available TrueType fonts. Hershey fonts will not be returned; see Appendix H, "Fonts" for more information. Syntax Return = Obj -> [IDLgrClipboard::]GetFontnames( FamilyName [, IDL_FONTS={0 | 1 | 2}] [, STYLES=string] ) Arguments FamilyName A string representing the name of the font family to which all of the returned fonts must belong. The string may be a fully specified family name-such as "Helvetica". You can use both "*" and "?" as wildcard characters, matching any number of characters or one character respectively. To return all available family names, use "*". Keywords IDL_FONTS Set this keyword to specify where to search for fonts that IDL may use. Set IDL_FONT to 1 to select only fonts installed by IDL and to 2 to select only fonts detected in the host operating system. The default value is 0, specifying that both IDL and operating system fonts should be returned. STYLES Set this keyword to a string specifying the styles that are to be matched by the returned font names. You can set STYLES to a fully specified style string, such as "Bold Italic". If you set STYLES to the null string, ' ', only fontnames without style modifiers will be returned. You can use both "*" and "?" as wildcard characters, matching any number of characters or one character respectively. The default value is the string, "*", which returns all fontnames containing the FamilyName argument, with or without style modifiers. IDLGRCLIPBOARD::GETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrClipboard::GetProperty The IDLgrClipboard::GetProperty procedure method retrieves the value of a property or group of properties for the clipboard buffer. Syntax Obj -> [IDLgrClipboard::]GetProperty [, ALL=variable] [, SCREEN_DIMENSIONS=variable] Arguments None Keywords Any keyword to IDLgrClipboard::Init followed by the word "Get" can be retrieved using IDLgrClipboard::GetProperty. In addition, the following keywords are available: ALL Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the retrievable properties associated with this object. SCREEN_DIMENSIONS Set this keyword to a named variable that will contain a two-element vector of the form [width, height] specifying the maximum allowed dimensions (measured in device units) for the clipboard object. IDLGRCLIPBOARD::GETTEXTDIMENSIONS [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrClipboard::GetTextDimensions The IDLgrClipboard::GetTextDimensions function method retrieves the dimensions of a text object that will be rendered in the clipboard buffer. The result is a 3-element double-precision floating-point vector [xDim, yDim, zDim] representing the dimensions of the text object, measured in data units. Syntax Result = Obj ->[IDLgrClipboard::]GetTextDimensions( TextObj [, DESCENT=variable] [, PATH=objref(s)] ) Arguments TextObj The object reference to a text or axis object for which the text dimensions are requested. Keywords DESCENT Set this keyword equal to a named variable that will contain an array of double- precision floating-point values (one for each string in the IDLgrText object). The values represent the distance to travel (parallel to the UPDIR vector) from the text baseline to reach the bottom of the lowest descender in the string. All values will be negative numbers, or zero. This keyword is valid only if TextObj is an IDLgrText object. PATH Set this keyword to a single object reference or a vector of object references. This keyword specifies the path in the graphics hierarchy to compute the text dimensions. Each path object reference specified with this keyword must contain an alias. The text dimensions are computed for the version of the object falling within that path. If this keyword is not set, the PARENT properties determine the path from the current object to the top of the graphics hierarchy and no alias paths are pursued. If IDLgrClipboard::GetTextDimensions is called from within a Draw method and the PATH keyword is not set, the alias path used to find the object during the draw is used, rather than the PARENT path. Note For more information on aliases, refer to the ALIAS keyword in IDLgrModel::Add. IDLGRCLIPBOARD::INIT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrClipboard::Init The IDLgrClipboard::Init function method initializes the clipboard object. Note Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass. Syntax Obj = OBJ_NEW('IDLgrClipboard' [, COLOR_MODEL{Get}={0 | 1}] [, DIMENSIONS{Get, Set}=[width, height]] [, GRAPHICS_TREE{Get, Set}=objref] [, N_COLORS{Get}=integer{2 to 256}] [, PALETTE{Get, Set}=objref] [, QUALITY{Get, Set}={0 | 1 | 2}] [, RESOLUTION{Get, Set}=[xres, yres]] [, UNITS{Get, Set}={0 | 1 | 2 | 3}] [, UVALUE{Get, Set}=value] ) or Result = Obj -> [IDLgrClipboard::]Init( ) (Only in a subclass' Init method.) Note Keywords can be used in either form. They are omitted in the second form for brevity. Arguments None Keywords Properties retrievable via IDLgrClipboard::GetProperty are indicated by the word "Get" following the keyword. Properties settable via IDLgrClipboard::SetProperty are indicated by the word "Set" following the keyword. COLOR_MODEL (Get) Set this keyword to the color model to be used for the clipboard buffer: * 0 = RGB (default) * 1 = Color Index DIMENSIONS (Get, Set) Set this keyword to a two-element vector of the form [width, height] to specify the dimensions of the clipboard buffer in units specified by the UNITS property. The default is [640,480]. GRAPHICS_TREE (Get, Set) Set this keyword to an object reference of type IDLgrScene, IDLgrViewgroup, or IDLgrView. If this property is set to a valid object reference, calling the Draw method on the destination object with no arguments will cause the object reference associated with this property to be drawn. If this object is valid and the destination object is destroyed, this object reference will be destroyed as well. By default the GRAPHICS_TREE property is set equal to the null-object. N_COLORS (Get) Set this keyword to the number of colors (between 2 and 256) to be used if COLOR_MODEL is set to Color Index. PALETTE (Get, Set) Set this keyword to the object reference of a palette object (an instance of the IDLgrPalette object class) to specify the red, green, and blue values that are to be loaded into the clipboard buffer's color lookup table. QUALITY (Get, Set) Set this keyword to an integer indicating the rendering quality at which graphics are to be drawn to the clipboard buffer. Valid values are: * 0 = Low * 1 = Medium * 2 = High (default) RESOLUTION (Get, Set) Set this keyword to a two-element vector of the form [xres, yres] specifying the device resolution in centimeters per pixel. This value is stored in double precision. The default value is: [0.035277778, 0.035277778] (72 DPI). Note To match screen rendering on an IDLgrClipboard object, the following properties should be matched between the devices: DIMENSIONS, UNITS, RESOLUTION, COLOR_MODEL and N_COLORS. UNITS (Get, Set) Set this keyword to indicate the units of measure for the DIMENSIONS property. Valid values are: * 0 = Device (default) * 1 = Inches * 2 = Centimeters * 3 = Normalized (relative to 1600 x 1200) UVALUE (Get, Set) Set this keyword to a value of any type. You can use this "user value" to contain any information you wish. Remember that if you set the user value equal to a pointer or object reference, you should destroy the pointer or object reference explicitly when destroying the object it is a user value of. IDLGRCLIPBOARD::SETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrClipboard::SetProperty The IDLgrClipboard::SetProperty procedure method sets the value of a property or group of properties for the clipboard buffer. Syntax Obj -> [IDLgrClipboard::]SetProperty Arguments None Keywords Any keyword to IDLgrClipboard::Init followed by the word "Set" can be retrieved using IDLgrClipboard::SetProperty. IDLGRCOLORBAR [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrColorbar The IDLgrColorbar object consists of a color-ramp with an optional framing box and annotation axis. The object can be horizontal or vertical. An IDLgrColorbar object is a composite object; it is one of the basic drawable elements of the IDL Object Graphics system, and it is not a container for other objects. This object class is implemented in the IDL language. Its source code can be found in the file idlgrcolorbar_ _define.pro in the lib subdirectory of the IDL distribution. Superclasses This class is a subclass of IDLgrModel. Subclasses This class has no subclasses. Creation See "IDLgrColorbar::Init" on page 1985. Methods Intrinsic Methods This class has the following methods: * IDLgrColorbar::Cleanup * IDLgrColorbar::ComputeDimensions * IDLgrColorbar::GetProperty * IDLgrColorbar::Init * IDLgrColorbar::SetProperty Inherited Methods This class inherits the following methods: * IDLgrModel::GetCTM IDLGRCOLORBAR::CLEANUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrColorbar::Cleanup The IDLgrColorbar::Cleanup procedure method performs all cleanup on the object. Note Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass. Syntax OBJ_DESTROY,Obj or Obj -> [IDLgrColorbar::]Cleanup(Only in subclass' Cleanup method.) Arguments None Keywords None IDLGRCOLORBAR::COMPUTEDIMENSIONS [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrColorbar::ComputeDimensions The IDLgrColorbar::ComputeDimensions function method retrieves the dimensions of a colorbar object for the given destination object. The result is a three-element double-precision floating-point vector [xDim, yDim, zDim] representing the dimensions of the colorbar object measured in data units. Syntax Result = Obj ->[IDLgrColorbar::]ComputeDimensions( DestinationObj [, PATH=objref(s)] ) Arguments DestinationObject The object reference to a destination object (IDLgrBuffer, IDLgrClipboard, IDLgrPrinter, or IDLgrWindow) for which the dimensions of the colorbar are being requested. Keywords PATH Set this keyword to a single object reference or a vector of object references. This keyword specifies the path in the graphics hierarchy to compute the dimensions. Each path object reference specified with this keyword must contain an alias. The text dimensions are computed for the version of the object falling within that path. If this keyword is not set, the PARENT properties determine the path from the current object to the top of the graphics hierarchy and no alias paths are pursued. If IDLgrColorbar::ComputeDimensions is called from within a Draw method and the PATH keyword is not set, the alias path used to find the object during the draw is used, rather than the PARENT path. Note For more information on aliases, refer to the ALIAS keyword in IDLgrModel::Add. IDLGRCOLORBAR::GETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrColorbar::GetProperty The IDLgrColorbar::GetProperty procedure method retrieves the value of a property or group of properties for the colorbar. Syntax Obj -> [IDLgrColorbar::]GetProperty [, ALL=variable] [, PARENT=variable] [, XRANGE=variable] [, YRANGE=variable] [, ZRANGE=variable] Arguments None Keywords Any keyword to IDLgrColorbar::Init followed by the word "Get" can be retrieved using IDLgrColorbar::GetProperty. In addition, the following keywords are available: ALL Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the retrievable properties associated with this object. PARENT Set this keyword to a named variable that will contain an object reference to the object that contains this colorbar. XRANGE Set this keyword to a named variable that will contain a two-element double- precision floating-point vector of the form [xmin, xmax] specifying the range of the x data coordinates covered by the colorbar. YRANGE Set this keyword to a named variable that will contain a two-element double- precision floating-point vector of the form [ymin, ymax] specifying the range of the Y data coordinates covered by the colorbar. ZRANGE Set this keyword to a named variable that will contain a two-element double- precision floating-point vector of the form [zmin, zmax] specifying the range of the Z data coordinates covered by the colorbar. Note Until the colorbar is drawn to the destination object, the [XYZ]RANGE properties will be zero. Use the ComputeDimensions method on the colorbar object to get the data dimensions of the colorbar prior to a draw operation. IDLGRCOLORBAR::INIT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrColorbar::Init The IDLgrColorbar::Init function method initializes the colorbar object. Note Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass. Syntax Obj = OBJ_NEW( 'IDLgrColorbar' [, aRed, aGreen, aBlue] [, BLUE_VALUES{Get, Set}=vector] [, COLOR{Get, Set}=index or RGB vector] [, DIMENSIONS{Get, Set}=[dx, dy]] [, GREEN_VALUES{Get, Set}=vector] [, /HIDE{Get, Set}] [, MAJOR{Get, Set}=integer] [, MINOR{Get, Set}=integer] [NAME{Get, Set}=string] [, PALETTE{Get, Set}=objref] [, RED_VALUES{Get, Set}=vector] [, SHOW_AXIS{Get, Set}={0 | 1 | 2}] [, /SHOW_OUTLINE{Get, Set}] [, SUBTICKLEN{Get, Set}=min [, THICK{Get, Set}=points{1.0 to 10.0}] [, /THREED{Get}] [, TICKFORMAT{Get, Set}=string] [, TICKFRMTDATA{Get, Set}=value] [, TICKLEN{Get, Set}=value] [, TICKTEXT{Get, Set}=objref(s)] [, TICKVALUES{Get, Set}=vector] [, TITLE{Get, Set}=objref] [, UVALUE{Get, Set}=value] [, XCOORD_CONV{Get, Set}=vector] [, YCOORD_CONV{Get, Set}=vector] [, ZCOORD_CONV{Get, Set}=vector] ) or Result = Obj -> [IDLgrColorbar::]Init( [aRed, aGreen, aBlue] ) (Only in a subclass' Init method.) Note Keywords can be used in either form. They are omitted in the second form for brevity. Arguments aRed A vector containing the red values for the color palette. These values should be within the range of 0 < Value < 255. The number of elements comprising the aRed vector must not exceed 256. aGreen A vector containing the green values for the color palette. These values should be within the range of 0 < Value < 255. The number of elements comprising the aGreen vector must not exceed 256. aBlue A vector containing the blue values for the color palette. These values should be within the range of 0 < Value < 255. The number of elements comprising the aBlue vector must not exceed 256. If aRed, aGreen, and aBlue are not provided, the color palette will default to a 256 entry greyscale ramp. Keywords Properties retrievable via IDLgrColorbar::GetProperty are indicated by the word "Get" following the keyword. Properties settable via IDLgrColorbar::SetProperty are indicated by the word "Set" following the keyword. BLUE_VALUES (Get, Set) A vector containing the blue values for the color palette. Setting this value is the same as specifying the aBlue argument to the IDLgrColorbar::Init method. COLOR (Get, Set) Set this keyword to the color to be used as the foreground color for the axis and outline box. The color may be specified as a color lookup table index or as an RGB vector. The default is [0, 0, 0]. DIMENSIONS (Get, Set) Set this keyword to a two element vector [dx, dy] that specifies the size of the ramp display (not the axis) in pixels. If dx > dy, the colorbar is drawn horizontally with the axis placed below or above the ramp box depending on the value of the SHOW_AXIS property. If dx < dy, the colorbar is drawn vertically with the axis placed to the right or left of the ramp box depending on the value of the SHOW_AXIS property. The default value is [16,256]. GREEN_VALUES (Get, Set) A vector containing the green values for the color palette. Setting this value is the same as specifying the aGreen argument to the IDLgrColorbar::Init method. HIDE (Get, Set) Set this keyword to a boolean value to indicate whether this object should be drawn: * 0 = Draw graphic (the default) * 1 = Do not draw graphic MAJOR (Get, Set) Set this keyword to an integer representing the number of major tick marks. The default is -1, specifying that IDL will compute the number of tickmarks. Setting MAJOR equal to zero suppresses major tickmarks entirely. MINOR (Get, Set) Set this keyword to an integer representing the number of minor tick marks. The default is -1, specifying that IDL will compute the number of tickmarks. Setting MINOR equal to zero suppresses minor tickmarks entirely. NAME (Get, Set) Set this keyword to a string representing the name to be associated with this object. The default is the null string, ''. PALETTE (Get, Set) Set this keyword to an instance of the IDLgrPalette object class. If this keyword is a valid object reference, the colors within the IDLgrPalette are used to specify the colors for the colorbar. RED_VALUES (Get, Set) A vector containing the red values for the color palette. Setting this value is the same as specifying the aRed argument to the IDLgrColorbar::Init method. SHOW_AXIS (Get, Set) Set this keyword to an integer value indicating whether the axis should be drawn: * 0 = Do not display axis (the default) * 1 = Display axis on left side or below the color ramp * 2 = Display axis on right side or above the color ramp SHOW_OUTLINE (Get, Set) Set this keyword to a boolean value indicating whether the colorbar bounds should be outlined: * 0 = Do not display outline (the default) * 1 = Display outline SUBTICKLEN (Get, Set) Set this keyword to a scale ratio specifying the length of minor tick marks relative to the length of major tick marks. The default is 0.5, specifying that the minor tick mark is one-half the length of the major tick mark. THICK (Get, Set) Set this keyword to a value between 1.0 and 10.0, specifying the line thickness used to draw the axis and box outline, in points. The default is 1.0 points. THREED (Get) Set this keyword on initialization to create the colorbar as a graphic object that can be fully transformed in three dimensions. By default, the colorbar always faces the viewer and is drawn at z=0. TICKFORMAT (Get, Set) Set this keyword to either a standard IDL format string (see "Files and Input/Output" in Chapter 8 of Building IDL Applications for details on format codes) or a string containing the name of a user-supplied function that returns a string to be used to format the axis tick mark labels. The function should accept integer arguments for the direction of the axis, the index of the tick mark, and the value of the tick mark, and should return a string to be used as the tick mark's label. The function may optionally accept a keyword called DATA, which will be automatically set to the TICKFRMTDATA value. The default TICKFORMAT is '', the null string, which indicates that IDL will determine the appropriate format for each value. TICKFRMTDATA (Get, Set) Set this keyword to a value of any type. It will be passed via the DATA keyword to the user-supplied formatting function specified via the TICKFORMAT keyword, if any. By default, this value is 0, indicating that the DATA keyword will not be set (and furthermore, need not be supported by the user-supplied function). Note that TICKFRMTDATA will not be included in the structure returned via the ALL keyword to the IDLgrColorbar::GetProperty method. TICKLEN (Get, Set) Set this keyword to the length of each major tick mark, measured in data units. The recommended, and default, tick mark length is 0.2. IDL converts, maintains, and returns this data as double-precision floating-point. TICKTEXT (Get, Set) Set this keyword to either a single instance of the IDLgrText object class (with multiple strings) or to a vector of instances of the IDLgrText object class (each with a single string) to specify the annotations to be assigned to the tick marks. By default, TICKTEXT is set to the NULL object, which indicates that IDL will compute tick annotations based upon the major tick values. The positions and orientation of the provided text object(s) may be overwritten by the colorbar. TICKVALUES (Get, Set) Set this keyword to a vector of data values representing the values at each tick mark. If TICKVALUES is set to 0, the default, IDL computes the tick values based on the axis range and the number of major ticks. IDL converts, maintains, and returns this data as double-precision floating-point. TITLE (Get, Set) Set this keyword to an instance of the IDLgrText object class to specify the title for the axis. The default is the null object, specifying that no title is drawn. The title will be centered along the axis, even if the text object itself has an associated location. UVALUE (Get, Set) Set this keyword to a value of any type. You may use this value to contain any information you wish. XCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert X coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedX = s0 + s1 * DataX Recommended values are: [(-Xmin)/(Xmax-Xmin), 1/(Xmax-Xmin)] The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double- precision floating-point. YCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert Y coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedY = s0 + s1 * DataY Recommended values are: [(-Ymin)/(Ymax-Ymin), 1/(Ymax-Ymin)] The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double- precision floating-point. ZCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert Z coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedZ = s0 + s1 * DataZ Recommended values are: [(-Zmin)/(Zmax-Zmin), 1/(Zmax-Zmin)] The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double- precision floating-point. IDLGRCOLORBAR::SETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrColorbar::SetProperty The IDLgrColorbar::SetProperty procedure method sets the value of a property or group of properties for the colorbar. Syntax Obj -> [IDLgrColorbar::]SetProperty Arguments None Keywords Any keyword to IDLgrColorbar::Init followed by the word "Set" can be retrieved using IDLgrColorbar::SetProperty. IDLGRCONTOUR [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrContour The IDLgrContour object draws a contour plot from data stored in a rectangular array or from a set of unstructured points. Both line contours and filled contour plots can be created. An IDLgrContour object is an atomic graphic object; it is one of the basic drawable elements of the IDL Object Graphics system, and it is not a container for other objects. The object stores the following argument or property in double-precision if the DOUBLE_DATA keyword parameter is specified, and in single-precision otherwise. Superclasses This class has no superclasses. Subclasses This class has no subclasses. Creation See "IDLgrContour::Init" on page 1998. Methods Intrinsic Methods This class has the following methods: * IDLgrContour::Cleanup * IDLgrContour::GetCTM * IDLgrContour::GetProperty * IDLgrContour::Init * IDLgrContour::SetProperty IDLGRCONTOUR::CLEANUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrContour::Cleanup The IDLgrContour::Cleanup procedure method performs all cleanup on the object. Note Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass. Syntax OBJ_DESTROY, Obj or Obj -> [IDLgrContour::]Cleanup(Only in subclass' Cleanup method.) Arguments None Keywords None IDLGRCONTOUR::GETCTM [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrContour::GetCTM The IDLgrContour::GetCTM method returns the 4 x 4 double-precision floating- point graphics transform matrix from the current object upward through the graphics tree. Syntax Result = Obj -> [IDLgrContour::]GetCTM( [, DESTINATION=objref] [, PATH=objref(s)] [, TOP=objref] ) Arguments None Keywords DESTINATION Set this keyword to the object reference of a destination object to specify that the projection matrix for the View object in the current tree be included in the returned transformation matrix. The resulting matrix will transform a point in the data space of the object on which the GetCTM method is called into a normalized coordinate system (-1 to +1 in X, Y, and Z), relative to the View object that contains the surface object. PATH Set this keyword to a single object reference or a vector of object references. This keyword specifies the path in the graphics hierarchy to compute the transformation matrix. Each path object reference specified with this keyword must contain an alias. The transformation matrix is computed for the version of the object falling within that path. If this keyword is not set, the PARENT properties determine the path from the current object to the top of the graphics hierarchy and no alias paths are pursued. If IDLgrContour::GetCTM is called from within a Draw method, with the DESTINATION keyword set and the PATH keyword not set, the alias path used to find the object during the draw is used, rather than the PARENT path. Note For more information on aliases, refer to the ALIAS keyword in IDLgrModel::Add. TOP Set this keyword equal to the object reference to an IDLgrModel object to specify that the returned matrix accumulate from the object on which the GetCTM method is called up to but not including the specified model object. IDLGRCONTOUR::GETPROPERTY[1] [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrContour::GetProperty The IDLgrContour::GetProperty procedure method retrieves the value of a property or group of properties for the contour. Syntax Obj -> [IDLgrContour::]GetProperty [, DEPTH_OFFSET] [, ALL=variable] [, GEOM=variable] [, PARENT=variable] [, XRANGE=variable] [, YRANGE=variable] [, ZRANGE=variable] Arguments None Keywords DEPTH_OFFSET An integer value that specifies an offset in depth to be used when rendering filled primitives. This offset is applied along the viewing axis, with positive values moving the primitive away from the viewer. The units are "Z-Buffer units", where a value of 1 is used to specify a distance that corresponds to a single step in the device's Z-Buffer. Use DEPTH_OFFSET to always cause a filled primitive to be rendered slightly deeper than other primitives, independent of model transforms. This is useful for avoiding stitching artifacts caused by rendering lines or polygons on top of other polygons at the same depth. Note - RSI suggests using this feature to remove stitching artifacts and not as a means for "layering" complex scenes with multiple DEPTH_OFFSET values. It is safest to use only a DEPTH_OFFSET value of 0, the default, and one other non-zero value such as 1. Many system-level graphics drivers are not consistent in their handling of DEPTH_OFFSET values, particularly when multiple non-zero values are used. This can lead to portability problems because one set of DEPTH_OFFSET values may produce better results on one machine as compared to another. Using IDL's software renderer will help improve the cross-platform consistency of scenes that use DEPTH_OFFSET. Note - DEPTH_OFFSET has no effect unless the FILL keyword is set. Any keyword to IDLgrContour::Init followed by the word "Get" can be retrieved using IDLgrContour::GetProperty. In addition, the following keywords are available: ALL Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the retrievable properties associated with this object. GEOM Set this keyword to a named variable that will contain the geometry associated with the contour. IDL returns this data in single-precision floating-point by default or in double-precision floating-point if the DOUBLE_GEOM keyword is set in the IDLgrContour::Init method. PARENT Set this keyword to a named variable that will contain an object reference to the object that contains this contour. XRANGE Set this keyword to a named variable that will contain a two-element double- precision floating-point vector of the form [xmin, xmax] specifying the range of the X data coordinates covered by the contour. YRANGE Set this keyword to a named variable that will contain a two-element double- precision floating-point vector of the form [ymin, ymax] specifying the range of the Y data coordinates covered by the contour. ZRANGE Set this keyword to a named variable that will contain a two-element double- precision floating-point vector of the form [zmin, zmax] specifying the range of the Z data coordinates covered by the contour. IDLGRCONTOUR::INIT[1] [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrContour::Init The IDLgrContour::Init function method initializes the contour object. Note Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass. Syntax Obj = OBJ_NEW('IDLgrContour' [, Values] [, DEPTH_OFFSET] [, ANISOTROPY{Get, Set}=[x, y, z]] [, C_COLOR{Get, Set}=vector] [, C_FILL_PATTERN{Get, Set}=array of IDLgrPattern objects] [, C_LINESTYLE{Get, Set}=array of linestyles] [, C_THICK{Get, Set}=float array{each element 1.0 to 10.0}] [, C_VALUE{Get, Set}=scalar or vector] [, COLOR{Get, Set}=index or RGB vector] [, DATA_VALUES{Get, Set}=vector or 2D array] [, /DOUBLE_DATA] [, /DOUBLE_GEOM] [, /DOWNHILL{Get, Set}] [, /FILL{Get, Set}] [, GEOMX{Set}=vector or 2D array] [, GEOMY{Set}=vector or 2D array] [, GEOMZ{Set}=scalar, vector, or 2D array] [, /HIDE{Get, Set}] [, MAX_VALUE{Get, Set}=value] [, MIN_VALUE{Get, Set}=value] [, NAME{Get, Set}=string] [, N_LEVELS{Get, Set}=value] [, PALETTE{Get, Set}=objref ] [, /PLANAR{Get, Set}] [, POLYGONS{Get, Set}=array of polygon descriptions] [, SHADE_RANGE{Get, Set}=[min, max] ] [, SHADING{Get, Set}={0 |1}] [, TICKINTERVAL{Get, Set}=value] [, TICKLEN{Get, Set}=value] [, UVALUE{Get, Set}=value] [, XCOORD_CONV{Get, Set}=vector] [, YCOORD_CONV{Get, Set}=vector] [, ZCOORD_CONV{Get, Set}=vector] ) or Result = Obj -> [IDLgrContour::]Init( [Values] ) (Only in a subclass' Init method.) Note Keywords can be used in either form. They are omitted in the second form for brevity. Arguments Values A vector or two-dimensional array of values to be contoured. If no values are provided, the values will be derived from the GEOMZ keyword value (if set and the PLANAR keyword is not set). In this case, the values to be contoured will match the Z coordinates of the provided geometry. IDL converts and maintains this data as double-precision floating-point if the argument is of type DOUBLE or if the DOUBLE_DATA keyword is set. Otherwise, the data is stored in single-precision. IDL returns the data as double-precision if it was stored in double-precision. Keywords DEPTH_OFFSET An integer value that specifies an offset in depth to be used when rendering filled primitives. This offset is applied along the viewing axis, with positive values moving the primitive away from the viewer. The units are "Z-Buffer units", where a value of 1 is used to specify a distance that corresponds to a single step in the device's Z-Buffer. Use DEPTH_OFFSET to always cause a filled primitive to be rendered slightly deeper than other primitives, independent of model transforms. This is useful for avoiding stitching artifacts caused by rendering lines or polygons on top of other polygons at the same depth. Note - RSI suggests using this feature to remove stitching artifacts and not as a means for "layering" complex scenes with multiple DEPTH_OFFSET values. It is safest to use only a DEPTH_OFFSET value of 0, the default, and one other non-zero value such as 1. Many system-level graphics drivers are not consistent in their handling of DEPTH_OFFSET values, particularly when multiple non-zero values are used. This can lead to portability problems because one set of DEPTH_OFFSET values may produce better results on one machine as compared to another. Using IDL's software renderer will help improve the cross-platform consistency of scenes that use DEPTH_OFFSET. Note - DEPTH_OFFSET has no effect unless the FILL keyword is set. Properties retrievable via IDLgrContour::GetProperty are indicated by the word "Get" following the keyword. Properties settable via IDLgrContour::SetProperty are indicated by the word "Set" following the keyword. ANISOTROPY (Get, Set) Set this keyword equal to a three-element vector [x, y, z] that represents the multipliers to be applied to the internally computed correction factors along each axis that account for anisotropic geometry. Correcting for anisotropy is particularly important for the appropriate representations of downhill tickmarks. By default, IDL will automatically compute correction factors for anisotropy based on the [XYZ] range of the contour geometry. If the geometry (as provided via the GEOMX, GEOMY, and GEOMZ keywords) falls within the range [xmin, ymin, zmin] to [xmax, ymax, zmax], then the default correction factors are computed as follows: dx = xmax - xmin dy = ymax - ymin dz = zmax - zmin ; Get the maximum of the ranges: maxRange = (dx > dy) > dz IF (dx EQ 0) THEN xcorrection = 1.0 ELSE $ xcorrection = maxRange / dx IF (dy EQ 0) THEN ycorrection = 1.0 ELSE $ ycorrection = maxRange / dy IF (dz EQ 0) THEN zcorrection = 1.0 ELSE $ zcorrection = maxRange / dz This internally computed correction is then multiplied by the corresponding [x, y, z] values of the ANISOTROPY keyword. The default value for this keyword is [1,1,1]. IDL converts, maintains, and returns this data as double-precision floating-point. C_COLOR (Get, Set) Set this keyword to a vector of colors representing the colors to be applied at each contour level. If there are more contour levels than elements in this vector, the colors will be cyclically repeated. If C_COLORS is set to 0, all contour levels will be drawn in the color specified by the COLOR keyword (this is the default). C_FILL_PATTERN (Get, Set) Set this keyword to an array of IDLgrPattern objects representing the patterns to be applied at each contour level if the FILL keyword is non-zero. If there are more contour levels than fill patterns, the patterns will be cyclically repeated. If this keyword is set to 0, all contour levels are filled with a solid color (this is the default). C_LINESTYLE (Get, Set) Set this keyword to an array of linestyles representing the linestyles to be applied at each contour level. The array may be either a vector of integers representing pre- defined linestyles, or an array of 2-element vectors representing a stippling pattern specification. If there are more contour levels than linestyles, the linestyles will be cyclically repeated. If this keyword is set to 0, all levels are drawn as solid lines (this is the default). C_THICK (Get, Set) Set this keyword to an array of line thicknesses representing the thickness to be applied at each contour level, where each element is a value between 1.0 and 10.0. If there are more contour levels than line thicknesses, the thicknesses will be cyclically repeated. If this keyword is set to 0, all contour levels are drawn with a line thickness of 1.0 points (this is the default). C_VALUE (Get, Set) Set this keyword to a scalar value or a vector of values for which contour values are to be drawn. If this keyword is set to 0, contour levels will be evenly sampled across the range of the DATA_VALUES, using the value of the N_LEVELS keyword to determine the number of samples. IDL converts, maintains, and returns this data as double-precision floating-point. COLOR (Get, Set) Set this keyword to the color to be used to draw the contours. The color may be specified as a color lookup table index or as an RGB vector. The default is [0,0,0]. This value will be ignored if the C_COLORS keyword is set to a vector. DATA_VALUES (Get, Set) Set this keyword to a vector or two-dimensional array specifying the values to be contoured. The keyword is the same as the Values argument described in the Arguments section above. IDL converts and stores this data as double-precision floating-point if the argument is of type DOUBLE or if the DOUBLE_DATA keyword is set. Otherwise, the data is stored in single-precision. IDL returns the data as double-precision if it was stored in double-precision. DOUBLE_DATA (Get, Set) Set this keyword to indicate that the object is to store data provided by either the Values argument or the DATA_VALUES keyword parameter in double-precision floating-point. Otherwise, the data is stored in single-precision floating-point. IDL converts any value data already stored in the object to the requested precision, if necessary. DOUBLE_GEOM (Get, Set) Set this keyword to indicate that the object is to store data provided by any of the GEOMX, GEOMY, or GEOMZ keyword parameters in double-precision floating- point. Otherwise, the data is stored in single-precision floating-point. IDL converts any geometry data already stored in the object to the requested precision, if necessary. DOWNHILL (Get, Set) Set this keyword to indicate that downhill tick marks should be rendered as part of each contour level to indicate the downhill direction relative to the contour line. FILL (Get, Set) Set this keyword to indicate that the contours should be filled. The default is to draw the contour levels as lines without filling. Filling contour may produce less than satisfactory results if your data contains NaNs, or if the contours are not closed. GEOMX (Set) Set this keyword to a vector or two-dimensional array specifying the X coordinates of the geometry with which the contour values correspond. If X is a vector, it must match the number of elements in the Values argument or DATA_VALUES keyword value, or it must match the first of the two dimensions of the Values argument or DATA_VALUES keyword value (in which case, the X coordinates will be repeated for each row of data values). IDL converts and maintains this data as double- precision floating-point if the parameter is of type DOUBLE or if the DOUBLE_GEOM property is non-zero. Otherwise, the data is stored in single- precision. IDL returns the data as double-precision if it was stored in double- precision. GEOMY (Set) Set this keyword to a vector or two-dimensional array specifying the Y coordinates of the geometry with which the contour values correspond. If Y is a vector, it must match the number of elements in the Values argument or DATA_VALUES keyword value, or it must match the second of the two dimensions of the Values argument or DATA_VALUES keyword value (in which case, the Y coordinates will be repeated for each column of data values). IDL converts and maintains this data as double precision floating point if the parameter is of type DOUBLE or if the DOUBLE_GEOM property is non-zero. Otherwise, the data is stored in single precision. IDL returns the data as double precision if it was stored in double precision. GEOMZ (Set) Set this keyword to a scalar, a vector, or a two-dimensional array specifying the Z coordinates of the geometry with which the contour values correspond. * If GEOMZ is a scalar, and the PLANAR keyword is set, the resulting contour geometry will be projected onto the plane Z=GEOMZ. If GEOMZ is a scalar, and the PLANAR keyword is not set, any geometry associated with the contour will be freed. * If GEOMZ is a vector or an array, it must match the number of elements in the Values argument or the DATA_VALUES keyword value. * If GEOMZ is not set, the geometry will be derived from the DATA_VALUES property (if it is set to a two-dimensional array). In this case, the connectivity is implied. The X and Y coordinates match the row and column indices of the array, and the Z coordinates match the data values. IDL converts and maintains this data as double precision floating point if the parameter is of type DOUBLE or if the DOUBLE_GEOM property is non-zero. Otherwise, the data is stored in single precision. IDL returns the data as double precision if it was stored in double precision. HIDE (Get, Set) Set this keyword to a boolean value to indicate whether this object should be drawn: * 0 = Draw graphic (the default) * 1 = Do not draw graphic MAX_VALUE (Get, Set) Set this keyword to the maximum value to be plotted. Data values greater than this value are treated as missing data. The default is the maximum value of the input Z data. IDL converts, maintains, and returns this data as double-precision floating- point. MIN_VALUE (Get, Set) Set this keyword to the minimum value to be plotted. Data values less than this value are treated as missing data. The default is the minimum value of the input Z data. IDL converts, maintains, and returns this data as double-precision floating-point. NAME (Get, Set) Set this keyword to a string representing the name to be associated with this object. The default is the null string, ''. N_LEVELS (Get, Set) Set this keyword to the number of contour levels to generate. This keyword is ignored if the C_VALUE keyword is set to a vector, in which case, the number of levels is derived from the number of elements in that vector. Set this keyword to zero to indicate that IDL should compute a default number of levels based on the range of data values. This is the default. PALETTE Set this keyword equal to the object reference of a palette object (an instance of the IDLgrPalette object class). This keyword is only used if the destination device is using the RGB color model. If so, and a color value for the object is specified as a color index value, the palette set by this keyword is used to translate the color to RGB space. If the PALETTE property on this object is not set, the destination object PALETTE property is used (which defaults to a grayscale ramp). PLANAR (Get, Set) Set this keyword to indicate that the contoured data is to be projected onto a plane. This keyword is ignored if GEOMZ is not a scalar. The default is non-planar (i.e., to display the contoured data at the Z locations provided by the GEOMZ keyword. POLYGONS (Get, Set) Set this keyword to an array of polygon descriptions that represents the connectivity information for the data to be contoured (as specified in the Values argument or the DATA_VALUES keyword). A polygon description is an integer or longword array of the form: [n, i0, i1, ..., in-1], where n is the number of vertices that define the polygon, and i0..in-1 are indices into the X, Y, and Z arguments that represent the polygon vertices. To ignore an entry in the POLYGONS array, set the vertex count, n, to 0. To end the drawing list, even if additional array space is available, set n to -1. If this keyword is not specified, a single polygon will be generated. Note The connectivity array described by POLYGONS allows an individual object to contain more than one polygon. Vertex, normal, and color information can be shared by the multiple polygons. Consequently, the polygon object can represent an entire mesh and compute reasonable normal estimates in most cases. SHADE_RANGE (Get, Set) Set this keyword to a two-element array that specifies the range of pixel values (color indices) to use for shading. The first element is the color index for the darkest pixel. The second element is the color index for the brightest pixel. This value is ignored when the contour is drawn to a graphics destination that uses the RGB color model. SHADING (Get, Set) Set this keyword to an integer representing the type of shading to use: * 0 = Flat (default): The color has a constant intensity for each face of the contour, based on the normal vector. * 1 = Gouraud: The colors are interpolated between vertices, and then along scanlines from each of the edge intensities. Gouraud shading may be slower than flat shading, but results in a smoother appearance. TICKINTERVAL (Get, Set) Set this keyword equal to a number indicating the distance between downhill tickmarks, in data units. If TICKINTERVAL is not set, or if you explicitly set it to zero, IDL will compute the distance based on the geometry of the contour. IDL converts, maintains, and returns this data as double-precision floating-point. TICKLEN (Get, Set) Set this keyword equal to a number indicating the length of the downhill tickmarks, in data units. If TICKLEN is not set, or if you explicitly set it to zero, IDL will compute the length based on the geometry of the contour. IDL converts, maintains, and returns this data as double-precision floating-point UVALUE (Get, Set) Set this keyword to a value of any type. Use this value to contain any information you wish. XCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert X coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedX = s0 + s1 * DataX Recommended values are: [(-Xmin)/(Xmax-Xmin), 1/(Xmax-Xmin)] The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double- precision floating-point. YCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert Y coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedY = s0 + s1 * DataY Recommended values are: [(-Ymin)/(Ymax-Ymin), 1/(Ymax-Ymin)] The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double- precision floating-point. ZCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert Z coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedZ = s0 + s1 * DataZ Recommended values are: [(-Zmin)/(Zmax-Zmin), 1/(Zmax-Zmin)] The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double- precision floating-point. IDLGRCONTOUR::SETPROPERTY[1] [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrContour::SetProperty The IDLgrContour::SetProperty procedure method sets the value of a property or group of properties for the contour. Syntax Obj -> [IDLgrContour::]SetProperty Arguments None Keywords DEPTH_OFFSET An integer value that specifies an offset in depth to be used when rendering filled primitives. This offset is applied along the viewing axis, with positive values moving the primitive away from the viewer. The units are "Z-Buffer units", where a value of 1 is used to specify a distance that corresponds to a single step in the device's Z-Buffer. Use DEPTH_OFFSET to always cause a filled primitive to be rendered slightly deeper than other primitives, independent of model transforms. This is useful for avoiding stitching artifacts caused by rendering lines or polygons on top of other polygons at the same depth. Note - RSI suggests using this feature to remove stitching artifacts and not as a means for "layering" complex scenes with multiple DEPTH_OFFSET values. It is safest to use only a DEPTH_OFFSET value of 0, the default, and one other non-zero value such as 1. Many system-level graphics drivers are not consistent in their handling of DEPTH_OFFSET values, particularly when multiple non-zero values are used. This can lead to portability problems because one set of DEPTH_OFFSET values may produce better results on one machine as compared to another. Using IDL's software renderer will help improve the cross-platform consistency of scenes that use DEPTH_OFFSET. Note - DEPTH_OFFSET has no effect unless the FILL keyword is set. Any keyword to IDLgrContour::Init followed by the word "Set" can be retrieved using IDLgrContour::SetProperty. IDLGRFONT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrFont A font object represents a typeface, style, weight, and point size that may be associated with text objects. Superclasses This class has no superclass. Subclasses This class has no subclasses. Creation See "IDLgrFont::Init" on page 2010. Methods Intrinsic Methods This class has the following methods: * IDLgrFont::Cleanup * IDLgrFont::GetProperty * IDLgrFont::Init * IDLgrFont::SetProperty IDLGRFONT::CLEANUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrFont::Cleanup The IDLgrFont::Cleanup procedure method performs all cleanup on the object. Note Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass. Syntax OBJ_DESTROY, Obj or Obj -> [IDLgrFont::]Cleanup(Only in subclass' Cleanup method.) Arguments None Keywords None IDLGRFONT::GETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrFont::GetProperty The IDLgrFont::GetProperty procedure method retrieves the value of a property or group of properties for the font. Syntax Obj -> [IDLgrFont:]GetProperty [, ALL=variable] Arguments None Keywords Any keyword to IDLgrFont::Init followed by the word "Get" can be retrieved using IDLgrFont::GetProperty. In addition, the following keywords are available: ALL Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the properties associated with the state of this object. State information about the object includes things like color, range, tick direction, etc., but not image, vertex, or connectivity data, or user values. Note The fields of this structure may change in subsequent releases of IDL. IDLGRFONT::INIT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrFont::Init The IDLgrFont::Init function method initializes the font object. Note Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass. Syntax Obj = OBJ_NEW('IDLgrFont' [, Fontname] [, NAME{Get, Set}=string] [, SIZE{Get, Set}=points] [, SUBSTITUTE{Get, Set}={ 'Helvetica' | 'Courier' | 'Times' | 'Symbol' | 'Hershey'}] [, THICK{Get, Set}=points{1.0 to 10.0}] [, UVALUE{Get, Set}=value] ) or Result = Obj -> [IDLgrFont::]Init( [Fontname] ) (Only in a subclass' Init method.) Note Keywords can be used in either form. They are omitted in the second form for brevity. Arguments Fontname A string representing the name of the font to be used. This string should take the form erN'. All destination objects support the following fontnames: Helvetica, Courier, Times, Symbol, and Monospace Symbol. (These fonts are included with IDL; you may have other fonts installed on your system as well.) Valid modifiers for each of these fonts (except Symbol and Monospace Symbol) are: * Font weight: Bold * Font angle: Italic For example, 'Helvetica*Bold*Italic'. To select a Hershey font, use a fontname of the form: 'Hershey*fontnum'. See Appendix H, "Fonts" for further information and a list of fonts supported by IDL. Note Beginning with IDL version 5.1, only TrueType and Hershey fonts are supported in the Object Graphics system. Keywords Properties retrievable via IDLgrFont::GetProperty are indicated by the word "Get" following the keyword. Properties settable via IDLgrFont::SetProperty are indicated by the word "Set" following the keyword. NAME (Get, Set) Set this keyword equal to a string containing the name of the font to use. Setting the NAME keyword is the same as supplying the Fontname argument described above. SIZE (Get, Set) Set this keyword equal to a floating-point integer representing the point size of the font. The default is 12.0 points. SUBSTITUTE (Get, Set) Set this keyword to a string that indicates the font to use as a substitute if the specified Fontname is not available on the graphics destination. Valid values are only those fonts that are available on all destination objects (the fonts included with IDL). These are: 'Helvetica' (the default), 'Courier', 'Times', 'Symbol', or 'Hershey'. THICK (Get, Set) Set this keyword to a value between 1.0 and 10.0, indicating the line thickness (measured in points) to use for the Hershey vector fonts. The default is 1.0 points. UVALUE (Get, Set) Set this keyword to a value of any type. You can use this "user value" to contain any information you wish. Remember that if you set the user value equal to a pointer or object reference, you should destroy the pointer or object reference explicitly when destroying the object it is a user value of. IDLGRFONT::SETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrFont::SetProperty The IDLgrFont::SetProperty procedure method sets the value of a property or group of properties for the font. Syntax Obj -> [IDLgrFont:]SetProperty Arguments None Keywords Any keyword to IDLgrFont::Init followed by the word "Set" can be set using IDLgrFont::SetProperty. IDLGRIMAGE [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrImage An image object represents a mapping from a two-dimensional array of data values to a two dimensional array of pixel colors, resulting in a flat 2D-scaled version of the image, drawn at Z = 0. The image object is drawn at Z =0 and is positioned and sized with respect to two points: p1 = [LOCATION(0), LOCATION(1), 0] p2 = [LOCATION(0) + DIMENSION(0), LOCATION(1) + DIMENSION(1), 0]. where LOCATION and DIMENSION are properties of the image object. These points are transformed in three dimensions, resulting in screen space points designated as p1' and p2'. The image data is drawn on the display as a 2D image within the 2D rectangle defined by (p1'[0], p1'[1] - p2'[0], p2'[1]). The 2D image data is scaled in 2D (not rotated) to fit into this projected rectangle and then drawn with Z buffering disabled Note Image objects do not take into account the Z locations of other objects that may be included in the view object. This means that objects that are drawn to the destination object (window or printer) after the image is drawn will appear to be in front of the image, even if they are located at a negative Z value (behind the image object). Objects are drawn to a destination device in the order that they are added (via the Add method) to the model, view, or scene that contains them. To rotate or position image objects in three-dimensional space, use the IDLgrPolygon object with texture mapping enabled. An IDLgrImage object is an atomic graphic object; it is one of the basic drawable elements of the IDL Object Graphics system, and it is not a container for other objects. Superclasses This class has no superclasses. Subclasses This class has no subclasses. Creation See "IDLgrImage::Init" on page 2020. Methods Intrinsic Methods This class has the following methods: * IDLgrImage::Cleanup * IDLgrImage::GetCTM * IDLgrImage::GetProperty * IDLgrImage::Init * IDLgrImage::SetProperty IDLGRIMAGE::CLEANUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrImage::Cleanup The IDLgrImage::Cleanup procedure method performs all cleanup on the object. Note Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass. Syntax OBJ_DESTROY, Obj or Obj -> [IDLgrImage::]Cleanup(Only in subclass' Cleanup method.) Arguments None Keywords None IDLGRIMAGE::GETCTM [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrImage::GetCTM The IDLgrImage::GetCTM function method returns the 4 x 4 double-precision floating-point graphics transform matrix from the current object upward through the graphics tree. Syntax Result = Obj -> [IDLgrImage::]GetCTM( [, DESTINATION=objref] [, PATH=objref(s)] [, TOP=objref to IDLgrModel object] ) Arguments None Keywords DESTINATION Set this keyword to the object reference of a destination object to specify that the projection matrix for the View object in the current tree be included in the returned transformation matrix. The resulting matrix will transform a point in the data space of the object on which the GetCTM method is called into a normalized coordinate system (-1 to +1 in X, Y, and Z), relative to the View object that contains the image object. PATH Set this keyword to a single object reference or a vector of object references. This keyword specifies the path in the graphics hierarchy to compute the transformation matrix. Each path object reference specified with this keyword must contain an alias. The transformation matrix is computed for the version of the object falling within that path. If this keyword is not set, the PARENT properties determine the path from the current object to the top of the graphics hierarchy and no alias paths are pursued. If IDLgrImage::GetCTM is called from within a Draw method, with the DESTINATION keyword set and the PATH keyword not set, the alias path used to find the object during the draw is used, rather than the PARENT path. Note For more information on aliases, refer to the ALIAS keyword in IDLgrModel::Add. TOP Set this keyword equal to the object reference to an IDLgrModel object to specify that the returned matrix accumulate from the object on which the GetCTM method is called up to but not including the specified model object. IDLGRIMAGE::GETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrImage::GetProperty The IDLgrImage::GetProperty procedure method retrieves the value of the property or group of properties for the image. Syntax Obj -> [IDLgrImage::]GetProperty [, ALL=variable] [, PARENT=variable] [, XRANGE=variable] [, YRANGE=variable] [, ZRANGE=variable] Arguments None Keywords Any keyword to IDLgrImage::Init followed by the word "Get" can be retrieved using IDLgrImage::GetProperty. In addition, the following keywords are available: ALL Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the properties associated with the state of this object. State information about the object includes things like color, range, tick direction, etc., but not image, vertex, or connectivity data, or user values. Note The fields of this structure may change in subsequent releases of IDL. PARENT Set this keyword equal to a named variable that will contain an object reference to the object that contains this object. XRANGE Set this keyword equal to a named variable that will contain a two-element double- precision floating-point vector of the form [xmin, xmax] that specifies the range of x data coordinates covered by the graphic object. YRANGE Set this keyword equal to a named variable that will contain a two-element double- precision floating-point vector of the form [ymin, ymax] that specifies the range of y data coordinates covered by the graphic object. ZRANGE Set this keyword equal to a named variable that will contain a two-element double- precision floating-point vector of the form [zmin, zmax] that specifies the range of z data coordinates covered by the graphic object. IDLGRIMAGE::INIT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrImage::Init The IDLgrImage::Init function method initializes the image object. Note Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass. Syntax Obj = OBJ_NEW('IDLgrImage' [, ImageData] [, BLEND_FUNCTION{Get, Set}=vector] [, CHANNEL{Get, Set}=hexadecimal bitmask] [, DATA{Get, Set}=nxm, 2xnxm, 3xnxm, or 4xnxm array of image data] [, DIMENSIONS{Get, Set}=[width, height]] [, /GREYSCALE{Get, Set}] [, /HIDE{Get, Set}] [, INTERLEAVE{Get, Set}={0 | 1 | 2}] [, /INTERPOLATE{Get, Set}] [LOCATION{Get, Set}=[x, y] or [x, y, z]] [, NAME{Get, Set}=string] [, /NO_COPY{Get, Set}] [, /ORDER{Get, Set}] [, PALETTE{Get, Set}=objref] [, /RESET_DATA{Set}] [, SHARE_DATA{Set}=objref] [, SUB_RECT{Get, Set}=[x, y, xdim, ydim]] [, UVALUE{Get, Set}=value] [, XCOORD_CONV{Get, Set}=vector] [YCOORD_CONV{Get, Set}=vector] [, ZCOORD_CONV{Get, Set}=vector] ) or Result = Obj -> [IDLgrImage::]Init( [ImageData] ) (Only in a subclass' Init method.) Note Keywords can be used in either form. They are omitted in the second form for brevity. Arguments ImageData An array of data values to be displayed as an image. If this argument is not already of byte type, it is converted to byte type when the image object is created. Since IDL maintains the image data using the byte type, the input data values should range from 0 through 255. The input data values can be either color lookup table indices when using a palette or channel intensities for greyscale or RGB images with an optional Alpha channel. When used as channel intensities, the data value of 0 specifies minimum intensity and the data value of 255 specifies maximum intensity. The Alpha channel values are also specified in the image data in the range 0 through 255, with an image data value of 0 corresponding to an Alpha blend factor of 0 and an image data value of 255 corresponding to an Alpha blend factor of 1.0. ImageData can be any of the following, where n is the width of the image, and m is the height: * An n x m array of color lookup table indices. * An n x m greyscale image, or a 2 x n x m, n x 2 x m, or n x m x 2 greyscale image with an alpha channel. (The alpha channel is ignored if the destination device uses Indexed color mode.) * A 3 x n x m, n x 3 x m, or n x m x 3 RGB image, or a 4 x n x m, n x 4 x m, or n x m x 4 RGB image with an alpha channel. If the array has more than one channel, the interleave is specified by the INTERLEAVE property. Keywords Properties retrievable via IDLgrImage::GetProperty are indicated by the word "Get" following the keyword. Properties settable via IDLgrImage::SetProperty are indicated by the word "Set" following the keyword. BLEND_FUNCTION (Get, Set) Set this keyword equal to a two-element vector [src, dst] specifying one of the functions listed below for each of the source and destination objects. These are only valid for RGB model destinations. If no Alpha data are specified in an image, the image's Alpha blend factor is assumed to be 1.0. The values of the blending function (Vsrc and Vdst) are used in the following equation Cd' = (Vsrc Ci) + (Vdst Cd) where Cd is the initial color of a pixel on the destination device (the background color), Ci is the color of the pixel in the image, and Cd' is the resulting color of the pixel. Setting src and dst in the BLEND_FUNCTION vector to the following values determine how each term in the equation is calculated: src or dst Vsrc or Vdst What the function does 0 n/a Alpha blending is disabled. Cd' = Ci. 1 0 The value of Vsrc or Vdst in the equation is zero, thus the value of the term is zero. 2 1 The value of Vsrc or Vdst in the equation is one, thus the value of the term is the same as the color value. 3 Image The value of Vsrc or Vdst in the equation is the blend factor of the image's Alpha channel. 4 1-Image The value of Vsrc or Vdst in the equation is one minus the blend factor of the image's Alpha channel. Table A-24: Values for src and dst in BLEND_FUNCTION Since the Alpha blending operation is dependent on the values of pixels already drawn to the destination for some blending functions, the final result may depend more on the order of drawing the images, and not necessarily on their relative location along the Z axis. IDL draws images in the order that they are stored in the IDLgrModel object that contains them. CHANNEL (Get, Set) Set this keyword to a hexadecimal bitmask that defines which color channel(s) to draw. Each bit that is a 1 is drawn; each bit that is a 0 is not drawn. For example, 'ff0000'X represents a Red channel write. The default is to draw all channels, and is represented by the hexadecimal value 'ffffff'X. Note This keyword is ignored for CI destination objects. DATA (Get, Set) Set this keyword to a n x m, 2 x n x m, 3 x n x m, or 4 x n x m array of image data for the object. The n and m values may be in any position as specified by the INTERLEAVE keyword. This keyword is equivalent to the optional argument, ImageData. DIMENSIONS (Get, Set) Set this keyword equal to a two-element vector of the form [width, height] specifying the dimensions of the rectangle in which the image is to be drawn on the device. The image will be resampled as necessary to fit within this rectangle. The default is derived from the dimensions of the given image data and is measured in pixels. IDL converts, maintains, and returns this data as double-precision floating-point. GREYSCALE (Get, Set) Set this keyword to specify that the image not be drawn through a palette. If this keyword is not set, for an RGB colormodel destination, if a palette is present in the image object, it is used. If there is no current destination palette, a greyscale palette is used. For a Color Index colormodel destination, the current destination palette is used. Note Only single band images (i.e. 1 x n x m) are affected by this keyword. By default, GREYSCALE is disabled. HIDE (Get, Set) Set this keyword to a boolean value indicating whether this object should be drawn: * 0 = Draw graphic (the default) * 1 = Do not draw graphic INTERLEAVE (Get, Set) Set this keyword to indicate the dimension over which color is interleaved for images with more than one channel: * 0 = Pixel interleaved: Images with dimensions (3, m, n) * 1 = Scanline interleaved (row interleaved): Images with dimensions (m, 3, n) * 2 = Planar interleaved: Images with dimensions (m, n, 3). Note If an alpha channel is present, the 3s should be replaced by 4s. In a greyscale image with an alpha channel, the 3s should be replaced by 2s. INTERPOLATE (Get, Set) Set this keyword to one to display the IDLgrImage object using bilinear interpolation. The default is to use nearest neighbor interpolation. LOCATION (Get, Set) A two- or three-element vector [x, y] or [x, y, z] specifying the position of the lower lefthand corner of the image, measured in data units. If the vector is of the form [x, y], then the z value is set equal to zero. The default is [0, 0, 0]. IDL converts, maintains, and returns this data as double-precision floating-point. NAME (Get, Set) Set this keyword equal to a string containing the name associated with this object. The default is the null string, ' '. NO_COPY (Get, Set) Set this keyword to relocate the image data from the input variable to the image object, leaving the input variable ImageData undefined. Only the ImageData argument is affected. If this keyword is omitted, the input image data will be duplicated and a copy will be stored in the object. ORDER (Get, Set) Set this keyword to force the rows of the image data to be drawn from top to bottom. By default, image data is drawn from the bottom row up to the top row. PALETTE (Get, Set) Set this keyword equal to the object reference of a palette object (an instance of the IDLgrPalette object class) to specify the red, green, and blue values of the color lookup table to be associated with the image if it is an indexed color image. This property is ignored if the image is a greyscale or RGB image. Note This table is only used when the destination is an RGB model device. The Indexed color model writes the indices directly to the device. In order to ensure that these colors are used when the image is displayed, this palette must be copied to the graphics destination's palette for any graphics destination that uses the Indexed color model. RESET_DATA (Set) Set this keyword to treat the data provided via the DATA property as a new data set unique to this object, rather than overwriting data that is shared by other objects. There is no reason to use this keyword if the object on which the property is being set does not currently share data with another object (that is, if the SHARE_DATA property is not in use). This keyword has no effect if no new data is provided via the DATA property. SHARE_DATA (Set) Set this keyword equal to the object reference of an object with which data is to be shared by this image. An image may only share data with another image. The SHARE_DATA property is intended for use when data values are not set via an argument to the object's Init method or by setting the object's DATA property. SUB_RECT (Get, Set) Set this keyword to a four-element vector, [x, y, xdim, ydim], specifying the position of the lower left-hand corner and the dimensions of the sub-rectangle to display. UVALUE (Get, Set) Set this keyword to a value of any type. You can use this "user value" to contain any information you wish. Remember that if you set the user value equal to a pointer or object reference, you should destroy the pointer or object reference explicitly when destroying the object it is a user value of. XCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert X coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedX = s0 + s1 * DataX Recommended values are: [(-Xmin)/(Xmax-Xmin), 1/(Xmax-Xmin)] The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double- precision floating-point. YCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert Y coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedY = s0 + s1 * DataY Recommended values are: [(-Ymin)/(Ymax-Ymin), 1/(Ymax-Ymin)] The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double- precision floating-point. ZCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert Z coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedZ = s0 + s1 * DataZ Recommended values are: [(-Zmin)/(Zmax-Zmin), 1/(Zmax-Zmin)] The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double- precision floating-point. IDLGRIMAGE::SETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrImage::SetProperty The IDLgrImage::SetProperty procedure method sets the value of the property or group of properties for the image. Syntax Obj -> [IDLgrImage::]SetProperty Arguments None Keywords Any keyword to IDLgrImage::Init followed by the word "Set" can be set using IDLgrImage::SetProperty. IDLGRLEGEND [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrLegend The IDLgrLegend object provides a simple interface for displaying a legend. The legend itself consists of a (filled and/or framed) box around one or more legend items (arranged in a single column) and an optional title string. Each legend item consists of a glyph patch positioned to the left of a text string. The glyph patch is drawn in a square which is a fraction of the legend label font height. The glyph itself can be in one of two types (see the TYPE keyword). In line type, the glyph is a line segment with linestyle, thickness and color attributes and an optional symbol object drawn over it. In fill type, the glyph is a square patch drawn with color and optional pattern object attributes. An IDLgrLegend object is a composite object; it is one of the basic drawable elements of the IDL Object Graphics system, and it is not a container for other objects. This object class is implemented in the IDL language. Its source code can be found in the file idlgrlegend_ _define.pro in the lib subdirectory of the IDL distribution. Superclasses This class is a subclass of IDLgrModel. Subclasses This class has no subclasses. Creation See "IDLgrLegend::Init" on page 2034. Methods Intrinsic Methods This class has the following methods: * IDLgrLegend::Cleanup * IDLgrLegend::ComputeDimensions * IDLgrLegend::GetProperty * IDLgrLegend::Init * IDLgrLegend::SetProperty Inherited Methods This class inherits the following methods: * IDLgrModel::GetCTM IDLGRLEGEND::CLEANUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrLegend::Cleanup The IDLgrLegend::Cleanup procedure method performs all cleanup on the object. Note Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass. Syntax OBJ_DESTROY, Obj or Obj -> [IDLgrLegend::]Cleanup(Only in subclass' Cleanup method.) Arguments None Keywords None IDLGRLEGEND::COMPUTEDIMENSIONS [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrLegend::ComputeDimensions The IDLgrLegend::ComputeDimensions function method retrieves the dimensions of a legend object for the given destination object. The result is a three-element double- precision floating-point vector [xDim, yDim, zDim] representing the dimensions of the legend object measured in data units. Syntax Result = Obj ->[IDLgrLegend::]ComputeDimensions( DestinationObject [, PATH=objref(s)] ) Arguments DestinationObject The object reference to a destination object (IDLgrBuffer, IDLgrClipboard, IDLgrPrinter, or IDLgrWindow) for which the dimensions of the legend are being requested. Keywords PATH Set this keyword to a single object reference or a vector of object references. This keyword specifies the path in the graphics hierarchy to compute the dimensions. Each path object reference specified with this keyword must contain an alias. The text dimensions are computed for the version of the object falling within that path. If this keyword is not set, the PARENT properties determine the path from the current object to the top of the graphics hierarchy and no alias paths are pursued. If IDLgrLegend::ComputeDimensions is called from within a Draw method and the PATH keyword is not set, the alias path used to find the object during the draw is used, rather than the PARENT path. Note For more information on aliases, refer to the ALIAS keyword in IDLgrModel::Add. IDLGRLEGEND::GETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrLegend::GetProperty The IDLgrLegend::GetProperty procedure method retrieves the value of a property or group of properties for the legend. Syntax Obj -> [IDLgrLegend::]GetProperty [, ALL=variable] [, PARENT=variable] [, XRANGE=variable] [, YRANGE=variable] [, ZRANGE=variable] Arguments None Keywords Any keyword to IDLgrLegend::Init followed by the word "Get" can be retrieved using IDLgrLegend::GetProperty. In addition, the following keywords are available: ALL Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the retrievable properties associated with this object. PARENT Set this keyword to a named variable that will contain an object reference to the object that contains this legend. XRANGE Set this keyword to a named variable that will contain a two-element double- precision floating-point vector of the form [xmin, xmax] specifying the range of the X data coordinates covered by the legend. YRANGE Set this keyword to a named variable that will contain a two-element double- precision floating-point vector of the form [ymin, ymax] specifying the range of the Y data coordinates covered by the legend. ZRANGE Set this keyword to a named variable that will contain a two-element double- precision floating-point vector of the form [zmin, zmax] specifying the range of the Z data coordinates covered by the legend. Note Until the legend is drawn to the destination object, the [XYZ]RANGE properties will be zero. Use the ComputeDimensions method on the legend object to get the data dimensions of the legend prior to a draw operation. IDLGRLEGEND::INIT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrLegend::Init The IDLgrLegend::Init function method initializes the legend object. Note Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass. Syntax Obj = OBJ_NEW('IDLgrLegend' [, aItemNames] [, BORDER_GAP{Get, Set}=value] [, COLUMNS{Get, Set}=integer] [, FILL_COLOR{Get, Set}=index or RGB vector] [, FONT{Get, Set}=objref] [, GAP{Get, Set}=value] [, GLYPH_WIDTH{Get, Set}=value] [, /HIDE{Get, Set}] [, ITEM_COLOR{Get, Set}=array of colors] [, ITEM_LINESTYLE{Get, Set}=int array] [, ITEM_NAME{Get, Set}=string array] [, ITEM_OBJECT{Get, Set}=array of objrefs of type IDLgrSymbol or IDLgrPattern] [, ITEM_THICK{Get, Set}=float array{each element 1.0 to 10.0}] [, ITEM_TYPE{Get, Set}=int array{each element 0 or 1}] [, NAME{Get, Set}=string] [, OUTLINE_COLOR{Get, Set}=index or RGB vector] [, OUTLINE_THICK{Get, Set}=points{1.0 to 10.0}] [, /SHOW_FILL{Get, Set}] [, /SHOW_OUTLINE{Get, Set}] [, TEXT_COLOR{Get, Set}=index or RGB vector] [, TITLE{Get, Set}=objref] [, UVALUE{Get, Set}=value] [, XCOORD_CONV{Get, Set}=vector] [, YCOORD_CONV{Get, Set}=vector] [, ZCOORD_CONV{Get, Set}=vector] ) or Result = Obj -> [IDLgrLegend::]Init( [aItemNames] ) (Only in a subclass' Init method.) Note Keywords can be used in either form. They are omitted in the second form for brevity. Arguments aItemNames An array of strings to be used as the displayed item label. The length of this array is used to determine the number of items to be displayed. Each item is defined by taking one element from the ITEM_NAME, ITEM_TYPE, ITEM_LINESTYLE, ITEM_THICK, ITEM_COLOR, and ITEM_OBJECT vectors. If the number of items (as defined by the ITEM_NAME array) exceeds any of the attribute vectors, the attribute defaults will be used for any additional items. Keywords Properties retrievable via IDLgrLegend::GetProperty are indicated by the word "Get" following the keyword. Properties settable via IDLgrLegend::SetProperty are indicated by the word "Set" following the keyword. BORDER_GAP (Get, Set) Set this keyword to a floating-point value to indicate the amount of blank space to be placed around the outside of the glyphs and text items. The units for this property are fractions of the legend label font height. The default is 0.1 (10% of the label font height). COLUMNS (Get, Set) Set this keyword to an integer value to indicate the number of columns the legend items should be displayed in. The default is one column. FILL_COLOR (Get, Set) Set this keyword to the color to be used to fill the legend background box. The color may be specified as a color lookup table index or as an RGB vector. The default is [255,255,255]. FONT (Get, Set) Set this keyword to an instance of an IDLgrFont object class to describe the font to use to draw the legend labels. The default is 12 point Helvetica. Note If the default font is in use, retrieving the value of the FONT property (using the GetProperty method) will return a font object that will be destroyed when this legend object is destroyed, leaving a dangling object reference. GAP (Get, Set) Set this keyword to a floating-point value to indicate the amount of blank space to be placed vertically between each legend item. The units for this keyword are fractions of the legend label font height. The default is 0.1 (10% of the label font height). The same gap is placed horizontally between the legend glyph and the legend text string. GLYPH_WIDTH (Get, Set) Set this keyword to a floating-point value to indicate the width of the glyphs, measured as a fraction of the font height. The default is 0.8 (80% of the font height). HIDE (Get, Set) Set this keyword to a boolean value to indicate whether this object should be drawn: * 0 = Draw graphic (the default) * 1 = Do not draw graphic ITEM_COLOR (Get, Set) Set this keyword to an array of colors defining the color of each item. The array defines M different colors, and should be either of the form [3,M] or [M]. In the first case, the three values are used as an RGB triplet, in the second case, the single value is used as a color index value. The default color is [0,0,0]. ITEM_LINESTYLE (Get, Set) Set this keyword to an array of integers defining the style of the line to be drawn if the TYPE property is set to zero. The array can be of the form [M] or [2,M]. The first form selects the linestyle for each legend item from the predefined defaults: * 0 = Solid line (the default) * 1 = dotted * 2 = dashed * 3 = dash dot * 4 = dash dot dot * 5 = long dash * 6 = no line drawn The second form specifies the stippling pattern explicitly for each legend item (see the LINESTYLE keyword to IDLgrPolyline::Init for details). ITEM_NAME (Get, Set) Set this keyword to an array of strings. Specifying this keyword is the same as providing the aName argument for the IDLgrLegend::Init method. ITEM_OBJECT (Get, Set) Set this keyword to an array of object references of type IDLgrSymbol or IDLgrPattern. A symbol object is drawn only if the TYPE property is set to zero. A pattern object is used when drawing the color patch if the TYPE property is set to one. The default object is the NULL object. Note If one or more IDlgrSymbol object references are provided, the SIZE property of those objects may be modified by this legend to suit its layout needs. ITEM_THICK (Get, Set) Set this keyword to an array of floats that define the thickness of each item line, in points, where each element is a value between 1.0 and 10.0. This property is only used if the TYPE property is set to zero. The default is 1.0 points. ITEM_TYPE (Get, Set) Set this keyword to an array of integers which define the type of glyph to be displayed for each item: * 0 = line type (the default) * 1 = filled box type NAME (Get, Set) Set this keyword to a string representing the name to be associated with this object. The default is the null string, ''. OUTLINE_COLOR (Get, Set) Set this keyword to the color to be used to draw the legend outline box. The color may be specified as a color lookup table index or as an RGB vector. The default is [0,0,0]. OUTLINE_THICK (Get, Set) Set this keyword to a value between 1.0 and 10.0 that defines the thickness of the outline frame, in points. The default is 1.0 points. SHOW_FILL (Get, Set) Set this keyword to a boolean value indicating whether the background should be filled with a color: * 0 = Do not fill background (the default) * 1 = Fill background SHOW_OUTLINE (Get, Set) Set this keyword to a boolean value indicating whether the outline box should be displayed: * 0 = Do not display outline (the default) * 1 = Display outline TEXT_COLOR (Get, Set) Set this keyword to the color to be used to draw the legend item text. The color may be specified as a color lookup table index or as an RGB vector. The default is [0,0,0]. TITLE (Get, Set) Set this keyword to an instance of the IDLgrText object class to specify the title for the legend. The default is the null object, specifying that no title is drawn. The title will be centered at the top of the legend, even if the text object itself has an associated location. UVALUE (Get, Set) Set this keyword to a value of any type. Use this value to contain any information you wish. XCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert X coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedX = s0 + s1 * DataX Recommended values are: [(-Xmin)/(Xmax-Xmin), 1/(Xmax-Xmin)] The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double- precision floating-point. YCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert Y coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedY = s0 + s1 * DataY Recommended values are: [(-Ymin)/(Ymax-Ymin), 1/(Ymax-Ymin)] The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double- precision floating-point. ZCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert Z coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedZ = s0 + s1 * DataZ Recommended values are: [(-Zmin)/(Zmax-Zmin), 1/(Zmax-Zmin)] The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double- precision floating-point. IDLGRLEGEND::SETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrLegend::SetProperty The IDLgrLegend::SetProperty procedure method sets the value of a property or group of properties for the legend. Syntax Obj-> [IDLgrLegend::]SetProperty [, RECOMPUTE={0 | 1}{0 prevents recompute, 1 is the default}] Arguments None Keywords Any keyword to IDLgrLegend::Init followed by the word "Set" can be retrieved using IDLgrLegend::SetProperty. In addition, the following keywords are available: RECOMPUTE Set this keyword to 1 to force IDL to recompute the legend dimensions when the legend is redrawn. Set this keyword to 0 to prevent IDL from recomputing legend dimensions. IDLGRLIGHT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrLight A light object represents a source of illumination for three-dimensional graphic objects. Lights may be either ambient, positional, directional, or spotlights. A maximum of 8 lights per view are allowed. Lights are not required for objects displayed in two dimensions. An IDLgrLight object is an atomic graphic object; it is one of the basic drawable elements of the IDL Object Graphics system, and it is not a container for other objects. Superclasses This class has no superclasses. Subclasses This class has no subclasses. Creation See "IDLgrLight::Init" on page 2046. Methods Intrinsic Methods This class has the following methods: * IDLgrLight::Cleanup * IDLgrLight::GetCTM * IDLgrLight::GetProperty * IDLgrLight::Init * IDLgrLight::SetProperty IDLGRLIGHT::CLEANUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrLight::Cleanup The IDLgrLight::Cleanup procedure method performs all cleanup on the object. Note Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass. Syntax OBJ_DESTROY, Obj or Obj -> [IDLgrLight::]Cleanup(Only in subclass' Cleanup method.) Arguments None Keywords None IDLGRLIGHT::GETCTM [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrLight::GetCTM The IDLgrLight::GetCTM function method returns the 4 x 4 double-precision floating-point graphics transform matrix from the current object upward through the graphics tree. Syntax Result = Obj -> [IDLgrLight::]GetCTM( [, DESTINATION=objref] [, PATH=objref(s)] [, TOP=objref to IDLgrModel object] ) Arguments None Keywords DESTINATION Set this keyword to the object reference of a destination object to specify that the projection matrix for the View object in the current tree be included in the returned transformation matrix. The resulting matrix will transform a point in the data space of the object on which the GetCTM method is called into a normalized coordinate system (-1 to +1 in X, Y, and Z), relative to the View object that contains the light object. PATH Set this keyword to a single object reference or a vector of object references. This keyword specifies the path in the graphics hierarchy to compute the transformation matrix. Each path object reference specified with this keyword must contain an alias. The transformation matrix is computed for the version of the object falling within that path. If this keyword is not set, the PARENT properties determine the path from the current object to the top of the graphics hierarchy and no alias paths are pursued. If IDLgrLight::GetCTM is called from within a Draw method, with the DESTINATION keyword set and the PATH keyword not set, the alias path used to find the object during the draw is used, rather than the PARENT path. Note For more information on aliases, refer to the ALIAS keyword in IDLgrModel::Add. TOP Set this keyword equal to the object reference to an IDLgrModel object to specify that the returned matrix accumulate from the object on which the GetCTM method is called up to but not including the specified model object. IDLGRLIGHT::GETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrLight::GetProperty The IDLgrLight::GetProperty procedure method retrieves the value of a property or group of properties for the light. Syntax Obj -> [IDLgrLight::]GetProperty [, ALL=variable] [, PARENT=variable] Arguments None Keywords Any keyword to IDLgrLight::Init followed by the word "Get" can be retrieved using IDLgrLight::GetProperty. In addition, the following keywords are available: ALL Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the properties associated with the state of this object. State information about the object includes things like color, range, tick direction, etc., but not image, vertex, or connectivity data, or user values. Note The fields of this structure may change in subsequent releases of IDL. PARENT Set this keyword equal to a named variable that will contain an object reference to the object that contains this object. IDLGRLIGHT::INIT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrLight::Init The IDLgrLight::Init function method initializes the light object. Note Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass. Syntax Obj = OBJ_NEW('IDLgrLight' [, ATTENUATION{Get, Set}=[constant, linear, quadratic]] [, COLOR{Get, Set}=[R, G, B]] [, CONEANGLE{Get, Set}=degrees] [, DIRECTION{Get, Set}=3-element vector] [, FOCUS{Get, Set}=value] [, /HIDE{Get, Set}] [, INTENSITY{Get, Set}=value{0.0 to 1.0}] [, LOCATION{Get, Set}=[x, y, z]] [, NAME{Get, Set}=string] [, TYPE{Get, Set}={0 | 1 | 2 | 3}] [, UVALUE{Get, Set}=value] [, XCOORD_CONV{Get, Set}=vector] [, YCOORD_CONV{Get, Set}=vector] [, ZCOORD_CONV{Get, Set}=vector] ) or Result = Obj -> [IDLgrLight::]Init( ) (Only in a subclass' Init method.) Note Keywords can be used in either form. They are omitted in the second form for brevity. Arguments None Keywords Properties retrievable via IDLgrLight::GetProperty are indicated by the word "Get" following the keyword. Properties settable via IDLgrLight::SetProperty are indicated by the word "Set" following the keyword. ATTENUATION (Get, Set) Set this keyword to a 3-element floating-point vector of the form [constant, linear, quadratic] that describes the factor by which light intensity is to fall with respect to distance from the light source. ATTENTUATION applies only to Positional and Spot lights, as specified by the TYPE keyword. The overall attenuation factor is computed as follows: attenuation = 1/(constant + linear*distance + quadratic*distance^2) By default, the values are [1, 0, 0]. COLOR (Get, Set) Set this keyword to a three-element vector specifying the RGB color of the light. The default is [255, 255, 255], which is a white light. The color of a light is ignored when graphics are sent to graphics destinations using the Indexed color model, in which case light intensities are scaled into the range of colors available on the graphics destination. CONEANGLE (Get, Set) Set this keyword to the angle (measured in degrees) of coverage for a spotlight. The default is 60. DIRECTION (Get, Set) Set this keyword to the three-element vector representing the direction in which a spotlight is to be pointed. The default is [0,0,-1]. Note For directional lights, the light's parallel rays follow a vector beginning at the position specified by LOCATION and ending at [0, 0, 0]. FOCUS (Get, Set) Set this keyword to a floating-point value that describes the attenuation of intensity for spotlights as the distance from the center of the cone of coverage increases. This factor is used as an exponent to the cosine of the angle between the direction of the spotlight and the direction from the light to the vertex being lighted. The default is 0.0. HIDE (Get, Set) Set this keyword to a boolean value indicating whether this light should be enabled: * 0 = Enable light (the default) * 1 = Disable light Note If no lights are present in the view (or if all lights in the view are hidden), an ambient light will be provided by default. INTENSITY (Get, Set) Set this keyword to a floating-point value between 0.0 (darkest) and 1.0 (brightest) indicating the intensity of the light. The default is 1.0. LOCATION (Get, Set) Set this keyword to a vector of the form [x, y, z] describing the position of the light. By default, the position is [0, 0, 0]. IDL converts, maintains, and returns this data as double-precision floating-point. NAME (Get, Set) Set this keyword equal to a string containing the name associated with this object. The default is the null string, ' '. TYPE (Get, Set) Set this keyword to one of the following values, indicating the type of light. Valid values are: * 0 = Ambient light. An ambient light is a universal light source, which has no direction or position. An ambient light illuminates every surface in the scene equally, which means that no edges are made visible by contrast. Ambient lights control the overall brightness and color of the entire scene. If no value is specified for the TYPE property, an ambient light is created. * 1 = Positional light. A positional light supplies divergent light rays, and will make the edges of surfaces visible by contrast if properly positioned. A positional light source can be located anywhere in the scene. * 2 = Directional light. A directional light supplies parallel light rays. The effect is that of a positional light source located at an infinite distance from scene. * 3 = Spot light. A spot light illuminates only a specific area defined by the light's position, direction, and the cone angle, or angle which the spotlight covers. UVALUE (Get, Set) Set this keyword to a value of any type. You can use this "user value" to contain any information you wish. Remember that if you set the user value equal to a pointer or object reference, you should destroy the pointer or object reference explicitly when destroying the object it is a user value of. XCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert X coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedX = s0 + s1 * DataX Recommended values are: [(-Xmin)/(Xmax-Xmin), 1/(Xmax-Xmin)] The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double- precision floating-point. YCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert Y coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedY = s0 + s1 * DataY Recommended values are: [(-Ymin)/(Ymax-Ymin), 1/(Ymax-Ymin)] The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double- precision floating-point. ZCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert Z coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedZ = s0 + s1 * DataZ Recommended values are: [(-Zmin)/(Zmax-Zmin), 1/(Zmax-Zmin)] The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double- precision floating-point. IDLGRLIGHT::SETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrLight::SetProperty The IDLgrLight::SetProperty procedure method sets the value of a property or group of properties for the light. Syntax Obj -> [IDLgrLight::]SetProperty Arguments None Keywords Any keyword to IDLgrLight::Init followed by the word "Set" can be set using IDLgrLight::SetProperty. IDLGRMODEL [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrModel A model object represents a graphical item or group of items that can be transformed (rotated, scaled, and/or translated). It serves as a container of other IDLgrModel objects or atomic graphic objects. IDLgrModel applies a transform to the current view tree. Superclasses This class is a subclass of IDL_Container. Subclasses The following classes are subclassed from this class: * IDLgrColorbar * IDLgrLegend Creation See "IDLgrModel::Init" on page 2060. Methods Intrinsic Methods This class has this following methods: * IDLgrModel::Add * IDLgrModel::Cleanup * IDLgrModel::Draw * IDLgrModel::GetByName * IDLgrModel::GetCTM * IDLgrModel::GetProperty * IDLgrModel::Init * IDLgrModel::Reset * IDLgrModel::Rotate * IDLgrModel::Scale * IDLgrModel::SetProperty * IDLgrModel::Translate Inherited Methods This class inherits the following methods: * IDL_Container::Count * IDL_Container::Get * IDL_Container::IsContained * IDL_Container::Move IDLGRMODEL::ADD [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrModel::Add The IDLgrModel::Add procedure method adds a child to this Model. Syntax Obj -> [IDLgrModel::]Add, Object [, /ALIAS] [, POSITION=index] Arguments Object An instance of an atomic graphic object or another model object to be added to the model object. Keywords ALIAS Set this keyword to a nonzero value to indicate that an alias-rather than the object itself-is to be added to the model. With this keyword you can add the same object to multiple models without duplicating that object and its children. If this keyword is set, the PARENT keyword on the object being added will not change. Furthermore, if this keyword is set, the object being added will not be destroyed when the model is destroyed. POSITION Set this keyword equal to the zero-based index of the position within the container at which the new object should be placed. IDLGRMODEL::CLEANUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrModel::Cleanup The IDLgrModel::Cleanup procedure method performs all cleanup on the object. Note Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass. Syntax OBJ_DESTROY, Obj or Obj -> [IDLgrModel::]Cleanup(Only in subclass' Cleanup method.) Arguments None Keywords None IDLGRMODEL::DRAW [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrModel::Draw The IDLgrModel::Draw procedure method draws the specified picture to the specified graphics destination. This method is provided for purposes of sub-classing only, and is intended to be called only from the Draw method of a subclass of IDLgrModel. Note Objects are drawn to the destination device in the order that they are added to the model, view, viewgroup, or scene object that contains them. Syntax Obj -> [IDLgrModel::]Draw, Destination, Picture Arguments Destination The destination object (IDLgrBuffer, IDLgrClipboard, IDLgrPrinter, or IDLgrWindow) to which the specified view object will be drawn. Picture The view (an instance of an IDLgrView object), viewgroup (an instance of an IDLgrViewgroup object), or scene (an instance of an IDLgrScene object) to be drawn. Keywords None IDLGRMODEL::GETBYNAME [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrModel::GetByName The IDLgrModel::GetByName function method finds contained objects by name and returns the object reference to the named object. If the named object is not found, the GetByName function returns a null object reference. Note The GetByName function does not perform a recursive search through the object hierarchy. If a fully qualified object name is not specified, only the contents of the current container object are inspected for the named object. Syntax Result = Obj -> [IDLgrModel::]GetByName(Name) Arguments Name A string containing the name of the object to be returned. Object naming syntax is very much like the syntax of a UNIX file system. Objects contained by other objects can include the name of their parent object; this allows you to create a fully qualified name specification. For example, if object1 contains object2, which in turn contains object3, the string specifying the fully qualified object name of object3 would be 'object1/object2/object3'. Object names are specified relative to the object on which the GetByName method is called. If used at the beginning of the name string, the / character represents the top of an object hierarchy. The string '..' represents the object one level "up" in the hierarchy. Keywords None IDLGRMODEL::GETCTM [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrModel::GetCTM The IDLgrModel::GetCTM function method returns the 4 x 4 double-precision floating-point graphics transform matrix from the current object upward through the graphics tree. Syntax Result = Obj -> [IDLgrModel::]GetCTM( [, DESTINATION=objref] [, PATH=objref(s)] [, TOP=objref to IDLgrModel object] ) Arguments None Keywords DESTINATION Set this keyword to the object reference of a destination object to specify that the projection matrix for the View object in the current tree be included in the returned transformation matrix. The resulting matrix will transform a point in the data space of the object on which the GetCTM method is called into a normalized coordinate system (-1 to +1 in X, Y, and Z), relative to the View object that contains the model object. PATH Set this keyword to a single object reference or a vector of object references. This keyword specifies the path in the graphics hierarchy to compute the transformation matrix. Each path object reference specified with this keyword must contain an alias. The transformation matrix is computed for the version of the object falling within that path. If this keyword is not set, the PARENT properties determine the path from the current object to the top of the graphics hierarchy and no alias paths are pursued. If IDLgrModel::GetCTM is called from within a Draw method, with the DESTINATION keyword set and the PATH keyword not set, the alias path used to find the object during the draw is used, rather than the PARENT path. Note For more information on aliases, refer to the ALIAS keyword in IDLgrModel::Add. TOP Set this keyword equal to the object reference to an IDLgrModel object to specify that the returned matrix accumulate from the object on which the GetCTM method is called up to but not including the specified model object. IDLGRMODEL::GETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrModel::GetProperty The IDLgrModel::GetProperty procedure method retrieves the value of a property or group of properties for the model. Syntax Obj -> [IDLgrModel::]GetProperty [, ALL=variable] [, PARENT=variable] Arguments None Keywords Any keyword to IDLgrModel::Init followed by the word "Get" can be retrieved using IDLgrModel::GetProperty. In addition, the following keywords are available: ALL Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the properties associated with this object. Note The fields of this structure may change in subsequent releases of IDL. PARENT Set this keyword equal to a named variable that will contain an object reference to the object that contains this object. IDLGRMODEL::INIT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrModel::Init The IDLgrModel::Init procedure method initializes the model object. Note Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass. Syntax Obj = OBJ_NEW('IDLgrModel' [, /HIDE{Get, Set}] [, LIGHTING{Get, Set}={0 | 1 | 2}] [, NAME{Get, Set}=string] [, /SELECT_TARGET{Get, Set}] [, TRANSFORM{Get, Set}=4x4 transformation matrix] [, UVALUE{Get, Set}=value] ) or Result = Obj -> [IDLgrModel::]Init( ) (Only in a subclass' Init method.) Note Keywords can be used in either form. They are omitted in the second form for brevity. Arguments None Keywords Properties retrievable via IDLgrModel::GetProperty are indicated by the word "Get" following the keyword. Properties settable via IDLgrModel::SetProperty are indicated by the word "Set" following the keyword. HIDE (Get, Set) Set this keyword to a boolean value indicating whether this object should be drawn: * 0 = Draw model and children (the default) * 1 = Do not draw model or children Note HIDE only controls the display attributes of IDLgrModel children since the IDLgrModel object itself lacks geometry. LIGHTING (Get, Set) Set this keyword to one of the following values to indicate whether lighting is to be enabled or disabled for all atomic graphic objects that have this model as a parent. IDLgrModel objects that have this model as a parent will not be effected, as they have their own value for this property. If this value is set to 0, any lights added as children of this model will be used to illuminate any other models in the view hierarchy that have lighting enabled. * 0 = Disable lighting * 1 = Enable single-sided lighting * 2 = Enable double-sided lighting (the default) NAME (Get, Set) Set this keyword equal to a string containing the name associated with this object. The default is the null string, ' '. SELECT_TARGET (Get, Set) Set this keyword to tag the model object as the target object to be returned when any object contained by the model is selected via the IDLgrWindow::Select method. By default, an IDLgrModel object cannot be returned as the target of a SELECT operation since it contains no geometry. TRANSFORM (Get, Set) Set this keyword to a 4x4 transformation matrix to be applied to the object. This matrix will be multiplied by its parent's transformation matrix (if the parent has one). The default is the identity matrix. IDL converts, maintains, and returns this data as double-precision floating-point. UVALUE (Get, Set) Set this keyword to a value of any type. You can use this "user value" to contain any information you wish. Remember that if you set the user value equal to a pointer or object reference, you should destroy the pointer or object reference explicitly when destroying the object it is a user value of. IDLGRMODEL::RESET [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrModel::Reset The IDLgrModel::Reset procedure method sets the current transform matrix for the model object to the identity matrix. Note Using this method is functionally identical to the following statement: Obj ->[IDLgrModel::]SetProperty, TRANSFORM=IDENTITY(4) Syntax Obj -> [IDLgrModel::]Reset Arguments None Keywords None IDLGRMODEL::ROTATE [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrModel::Rotate The IDLgrModel::Rotate procedure method rotates the model about the specified axis by the specified angle. IDL computes and maintains the resulting transform matrix in double-precision floating-point. Syntax Obj -> [IDLgrModel::]Rotate, Axis, Angle [, /PREMULTIPLY] Arguments Axis A three-element vector of the form [x, y, z] describing the axis about which the model is to be rotated. Angle The angle (measured in degrees) by which the rotation is to occur. Keywords PREMULTIPLY Set this keyword to cause the rotation matrix specified by Axis and Angle to be pre- multiplied to the model's transformation matrix. By default, the rotation matrix is post-multiplied. IDLGRMODEL::SCALE [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrModel::Scale The IDLgrModel::Scale procedure method scales the model by the specified scaling factors. IDL computes and maintains the resulting transform matrix in double- precision floating-point. Syntax Obj -> [IDLgrModel::]Scale, Sx, Sy, Sz [, /PREMULTIPLY] Arguments Sx, Sy, Sz The scaling factors in the x, y, and z dimensions by which the model is to be scaled. Keywords PREMULTIPLY Set this keyword to cause the scaling matrix specified by Sx, Sy, Sz to be pre- multiplied to the model's transformation matrix. By default, the scaling matrix is post-multiplied. IDLGRMODEL::SETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrModel::SetProperty The IDLgrModel::SetProperty procedure method sets the value of a property or group of properties for the model. Syntax Obj -> [IDLgrModel::]SetProperty Arguments None Keywords Any keyword to IDLgrModel::Init followed by the word "Set" can be set using IDLgrModel::SetProperty. IDLGRMODEL::TRANSLATE [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrModel::Translate The IDLgrModel::Translate procedure method translates the model about the specified axis by the specified translation offsets. IDL computes and maintains the resulting transform matrix in double-precision floating-point. Syntax Obj -> [IDLgrModel::]Translate, Tx, Ty, Tz [, /PREMULTIPLY] Arguments Tx, Ty, Tz The offsets in X, Y, and Z, respectively, by which the model is to be translated. Keywords PREMULTIPLY Set this keyword to cause the translation matrix specified by Tx, Ty, Tz to be pre- multiplied to the model's transformation matrix. By default, the translation matrix is post-multiplied. IDLGRMPEG [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrMPEG An IDLgrMPEG object creates an MPEG movie file from an array of image frames. Note The MPEG standard does not allow movies with odd numbers of pixels to be created. Note MPEG support in IDL requires a special license. For more information, contact your Research Systems sales representative or technical support. Superclasses This class has no superclasses. Subclasses This class has no subclasses. Creation See "IDLgrMPEG::Init" on page 2070. Methods Intrinsic Methods This class has the following methods: * IDLgrMPEG::Cleanup * IDLgrMPEG::GetProperty * IDLgrMPEG::Init * IDLgrMPEG::Put * IDLgrMPEG::Save * IDLgrMPEG::SetProperty IDLGRMPEG::CLEANUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrMPEG::Cleanup The IDLgrMPEG::Cleanup procedure method performs all cleanup on the object. Note Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass. Syntax OBJ_DESTROY, Obj or Obj -> [IDLgrMPEG::]Cleanup(Only in subclass' Cleanup method.) Arguments None Keywords None IDLGRMPEG::GETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrMPEG::GetProperty The IDLgrMPEG::GetProperty procedure method retrieves the value of a property or group of properties for the MPEG object. Syntax Obj -> [IDLgrMPEG::]GetProperty [, ALL=variable] Arguments None Keywords Any keyword to IDLgrMPEG::Init followed by the word "Get" can be retrieved using IDLgrMPEG::GetProperty. In addition, the following keywords are available: ALL Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the retrievable properties associated with this object. IDLGRMPEG::INIT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrMPEG::Init The IDLgrMPEG::Init function method initializes the MPEG object. Note Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass. Note MPEG support in IDL requires a special license. For more information, contact your Research Systems sales representative or technical support. Syntax Obj = OBJ_NEW('IDLgrMPEG' [, BITRATE{Get, Set}=value] [, DIMENSIONS{Get, Set}=2-element array] [, FILENAME{Get, Set}=string] [, FORMAT{Get, Set}={0 | 1}] [, FRAME_RATE{Get, Set} ={1 | 2 | 3 | 4 | 5 | 6 | 7 | 8}] [, IFRAME_GAP{Get, Set}=integer value] [, /INTERLACED{Get, Set}] [, MOTION_VEC_LENGTH{Get, Set}={1 | 2 | 3}] [ QUALITY{Get, Set}=value{0 to 100}] [, SCALE{Get, Set}=[xscale, yscale]] [, /STATISTICS{Get, Set}] [, TEMP_DIRECTORY=string] ) or Result = Obj -> [IDLgrMPEG::]Init( ) (Only in a subclass' Init method.) Note Keywords can be used in either form. They are omitted in the second form for brevity. Arguments None Keywords Properties retrievable via IDLgrMPEG::GetProperty are indicated by the word "Get" following the keyword. Properties settable via IDLgrMPEG::SetProperty are indicated by the word "Set" following the keyword. BITRATE (Get, Set) Set this keyword to a double-precision value to specify the MPEG movie bit rate. Higher bit rates will create higher quality MPEGs but will increase file size. The following table describes the valid values: MPEG Version Range MPEG 1 0.1 to 104857200.0 MPEG 2 0.1 to 429496729200.0 Table A-25: BITRATE Value Range Set this keyword to 0.0 (the default setting) to indicate that IDL should compute the BITRATE value based upon the value you have specified for the QUALITY keyword. The value of BITRATE returned by IDLgrMPEG::GetProperty is either the value computed by IDL from the QUALITY value or the last non-zero valid value stored in this property. Note Only use the BITRATE keyword if changing the QUALITY keyword value does not produce the desired results. It is highly recommended to set the BITRATE to at least several times the frame rate to avoid unusable MPEG files or file generation errors. DIMENSIONS (Get, Set) Set this keyword to a 2-element array specifying the dimensions (in pixels) of each of the images to be used as frames for the movie. If this property is not specified, the dimensions of the first image loaded will be used. Once IDLgrMPEG::Put has been called, this keyword can no longer be set. Note When creating MPEG files, you must be aware of the capabilities of the MPEG decoder you will be using to view it. Some decoders only support a limited set of sampling and bitrate parameters to normalize computational complexity, buffer size, and memory bandwidth. For example, the Windows Media Player supports a limited set of sampling and bitrate parameters. In this case, it is best to use 352 x 240 x 30 fps or 352 x 288 x 25 fps when determining the dimensions and frame rate for your MPEG file. When opening a file in Windows Media Player that does not use these dimensions, you will receive a "Bad Movie File" error message. The file is not "bad", this decoder just doesn't support the dimensions of the MPEG. FILENAME (Get, Set) Set this keyword to a string representing the name of the file in which the encoded MPEG sequence is to be stored. The default is 'idl.mpg'. FORMAT (Get, Set) Set this keyword to one of the following values to specify the type of MPEG encoding to use: * 0 = MPEG1 (the default) * 1 = MPEG2 FRAME_RATE (Get, Set) Set this keyword to one of the following integer values to specify the frame rate used in creating the MPEG file: Value Descriptions 1 23.976 frames/sec: NTSC encapsulated film rate 2 24 frames/sec: Standard international film rate 3 25 frames/sec: PAL video frame rate 4 29.97 frames/sec: NTSC video frame rate 5 30 frames/sec: NTSC drop frame video frame rate (the default) 6 50 frames/sec: Double frame rate/progressive PAL 7 59.94 frames/sec: Double frame rate NTSC 8 60 frames/sec: Double frame rate NTSC drop frame video Table A-26: FRAME_RATE Values IFRAME_GAP (Get, Set) Set this keyword to a positive integer value that specifies the number of frames between I frames to be created in the MPEG file. I frames are full-quality image frames that may have a number of predicted or interpolated frames between them. Set this keyword to 0 (the default setting) to indicate that IDL should compute the IFRAME_GAP value based upon the value you have specified for the QUALITY keyword. The value of IFRAME_GAP returned by IDLgrMPEG::GetProperty is either the value computed by IDL from the QUALITY value or the last non-zero valid value stored in this property. Note Only use the IFRAME_GAP keyword if changing the QUALITY keyword value does not produce the desired results. INTERLACED (Get, Set) Set this keyword to indicate that frames in the encoded MPEG file should be interlaced. The default is non-interlaced. MOTION_VEC_LENGTH (Get, Set) Set this keyword to an integer value specifying the length of the motion vectors to be used to generate predictive frames. The following table describes the valid values: Value Description 1 Small motion vectors. 2 Medium motion vectors. 3 Large motion vectors. Table A-27: MOTION_VEC_LENGTH Values Set this keyword to 0 (the default setting) to indicate that IDL should compute the MOTION_VEC_LENGTH value based upon the value you have specified for the QUALITY keyword. The value of MOTION_VEC_LENGTH returned by IDLgrMPEG::GetProperty is either the value computed by IDL from the QUALITY value or the last non-zero value stored in this property. Note Only use the MOTION_VEC_LENGTH keyword if changing the QUALITY value does not produce the desired results. QUALITY (Get, Set) Set this keyword to an integer value between 0 (low quality)and 100 (high quality) inclusive to specify the quality at which the MPEG stream is to be stored. Higher quality values result in lower rates of time compression and less motion prediction which provide higher quality MPEGs but with substantially larger file size. Lower quality factors may result in longer MPEG generation times. The default is 50. Note Since MPEG uses JPEG (lossy) compression, the original picture quality can't be reproduced even when setting QUALITY to its' highest setting. SCALE (Get, Set) Set this keyword to a two-element vector, [xscale, yscale], indicating the scale factors to be stored with the MPEG file as hints for playback. The default is [1.0, 1.0], indicating that the movie should be played back at the dimensions of the stored image frames. STATISTICS (Get, Set) Set this keyword to save statistical information about MPEG encoding for the supplied image frames in a file when the IDLgrMPEG::Save method is called. The information will be saved in a file with a name that matches that specified by the FILENAME keyword, with the extension ".stat". By default, statistics are not saved. TEMP_DIRECTORY Set the keyword to a string value which specifies a directory in which to place temporary files while creating the MPEG movie file. The default value is platform specific. IDLGRMPEG::PUT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrMPEG::Put The IDLgrMPEG::Put procedure method puts a given image into the MPEG sequence at the specified frame. Note that all images in a given MPEG movie must have matching dimensions. If no dimensions were explicitly specified when the MPEG object was initialized, the dimensions will be set according to the dimensions of the first image. Syntax Obj -> [IDLgrMPEG::]Put, Image[, Frame] Arguments Image An instance of an IDLgrImage object or a m x n or 3 x m x n array representing the image to be loaded at the given frame. Frame An integer specifying the index of the frame at which the image is to be added. Frame indices start at zero. If Frame is not supplied, the frame number used will be one more than the last frame that was put. Frame number need not be consecutive; in case of a gap in frame numbers, the frame before the gap is repeated to fill the space. Keywords None IDLGRMPEG::SAVE [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrMPEG::Save The IDLgrMPEG::Save procedure method encodes and saves the MPEG sequence to the specified filename. Note The MPEG standard does not allow movies with odd numbers of pixels to be created. Syntax Obj -> [IDLgrMPEG::]Save [, FILENAME=string] Macintosh Keywords: [, CREATOR_TYPE=string] Arguments None Keywords CREATOR_TYPE Set this keyword to a four character string representing the creator string to be used when writing this file on a Macintosh. This property is ignored if the current platform is not a Macintosh. The default is TVOD (Apple Movie Player application). FILENAME Set this keyword to a string representing the name of the file in which the encoded MPEG sequence is to be stored. The default is idl.mpg. IDLGRMPEG::SETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrMPEG::SetProperty The IDLgrMPEG::SetProperty procedure method sets the value of a property or group of properties for the MPEG object. Syntax Obj -> [IDLgrMPEG::]SetProperty Arguments None Keywords Any keyword to IDLgrMPEG::Init followed by the word "Set" can be retrieved using IDLgrMPEG::SetProperty. IDLGRPALETTE [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPalette A palette object represents a color lookup table that maps indices to red, green, and blue values. Superclasses This class has no superclass. Subclasses This class has no subclasses. Creation See "IDLgrPalette::Init" on page 2082. Methods Intrinsic Methods This class has this following methods: * IDLgrPalette::Cleanup * IDLgrPalette::GetRGB * IDLgrPalette::GetProperty * IDLgrPalette::Init * IDLgrPalette::LoadCT * IDLgrPalette::NearestColor * IDLgrPalette::SetRGB * IDLgrPalette::SetProperty IDLGRPALETTE::CLEANUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPalette::Cleanup The IDLgrPalette::Cleanup procedure method performs all cleanup on the object. Note Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass. Syntax OBJ_DESTROY, Obj or Obj -> [IDLgrPalette::]Cleanup(Only in subclass' Cleanup method.) Arguments None Keywords None IDLGRPALETTE::GETRGB [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPalette::GetRGB The IDLgrPalette::GetRGB function method returns the RGB values contained in the palette at the given index. The returned value is a three-element vector of the form [red, green, blue]. Syntax Result = Obj -> [IDLgrPalette::]GetRGB(Index) Arguments Index The index whose RGB values are desired. This value should be in the range of 0 Index < N_COLORS, where N_COLORS is the number of elements in the color palette, as returned by the N_COLORS keyword to the IDLgrPalette:GetProperty method. Keywords None IDLGRPALETTE::GETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPalette::GetProperty The IDLgrPalette::GetProperty procedure method retrieves the value of a property or group of properties for the palette. Syntax Obj -> [IDLgrPalette::]GetProperty [, ALL=variable] [, N_COLORS=variable] Arguments None Keywords Any keyword to IDLgrPalette::Init followed by the word "Get" can be retrieved using IDLgrPalette::GetProperty. In addition, the following keywords are available: ALL Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the properties associated with the state of this object. State information about the object includes things like color, range, tick direction, etc., but not image, vertex, or connectivity data, or user values. Note The fields of this structure may change in subsequent releases of IDL. N_COLORS Set this keyword to a named variable that upon return will contain the number of elements in the color palette. IDLGRPALETTE::INIT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPalette::Init The IDLgrPalette::Init function method initializes a palette object. Note Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass. Syntax Obj=OBJ_NEW('IDLgrPalette', aRed, aGreen, aBlue [, BLUE_VALUES{Get, Set}=vector] [, BOTTOM_STRETCH{Get, Set}=value{0 to 100}] [, GAMMA{Get, Set}=value{0.1 to 10.0}] [, GREEN_VALUES{Get, Set}=vector] [, NAME{Get, Set}=string] [, RED_VALUES{Get, Set}=vector] [, TOP_STRETCH{Get, Set}=value{0 to 100}] [, UVALUE{Get, Set}=value] ) or Result=Obj-> [IDLgrPalette::]Init( [aRed, aGreen, aBlue] ) (Only in a subclass' Init method.) Note Keywords can be used in either form. They are omitted in the second form for brevity. Arguments aRed A vector containing the red values for the color palette. These values should be within the range of 0 Value 255. The number of elements comprising the aRed vector must not exceed 256. aGreen A vector containing the green values for the color palette. These values should be within the range of 0 Value 255. The number of elements comprising the aGreen vector must not exceed 256. aBlue A vector containing the blue values for the color palette. These values should be within the range of 0 Value 255. The number of elements comprising the aBlue vector must not exceed 256. Keywords Properties retrievable via IDLgrPalette::GetProperty are indicated by the word "Get" following the keyword. Properties settable via IDLgrPalette::SetProperty are indicated by the word "Set" following the keyword. BLUE_VALUES (Get, Set) A vector containing the blue values for the color palette. Setting this value is the same as specifying the aBlue argument to the IDLgrPalette::Init method. BOTTOM_STRETCH (Get, Set) Set this keyword equal to the bottom parameter for stretching the colors in the palette. This value must be in the range of 0 Value 100. The default value is 0. GAMMA (Get, Set) Set this keyword to the gamma value to be applied to the color palette. This value should be in the range of 0.1 Gamma 10.0. The default is 1.0. GREEN_VALUES (Get, Set) A vector containing the green values for the color palette. Setting this value is the same as specifying the aGreen argument to the IDLgrPalette::Init method. NAME (Get, Set) Set this keyword equal to a string containing the name associated with this object. The default is the null string, ' '. RED_VALUES (Get, Set) A vector containing the red values for the color palette. Setting this value is the same as specifying the aRed argument to the IDLgrPalette::Init method. TOP_STRETCH (Get, Set) Set this keyword equal to the top parameter for stretching the colors in the palette. This value must be in the range of 0 Value 100. The default value is 100. UVALUE (Get, Set) Set this keyword to a value of any type. You can use this "user value" to contain any information you wish. Remember that if you set the user value equal to a pointer or object reference, you should destroy the pointer or object reference explicitly when destroying the object to which the user value applies. IDLGRPALETTE::LOADCT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPalette::LoadCT The IDLgrPalette::LoadCT procedure method loads one of the IDL predefined color tables into an IDLgrPalette object. Syntax Obj -> [IDLgrPalette::]LoadCT, TableNum [, FILENAME=colortable filename] Arguments TableNum The number of the pre-defined IDL color table to load, from 0 to 40. Keywords FILE Set this keyword to the name of a colortable file to be used instead of the file colors1.tbl in the IDL distribution. The MODIFYCT procedure can be used to create and modify colortable files. IDLGRPALETTE::NEARESTCOLOR [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPalette::NearestColor The IDLgrPalette::NearestColor function method returns the index of the color in the palette that best matches the given RGB values. Syntax Result = Obj-> [IDLgrPalette::]NearestColor(Red, Green, Blue) Arguments Red The red value of the color that should be matched. This value should be within the range of 0 Value 255. Green The green value of the color that should be matched. This value should be within the range of 0 Value 255. Blue The blue value of the color that should be matched. This value should be within the range of 0 Value 255. Keywords None IDLGRPALETTE::SETRGB [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPalette::SetRGB The IDLgrPalette::SetRGB procedure method sets the color values at a specified index in the palette to the specified Red, Green and Blue values. Syntax Obj -> [IDLgrPalette::]SetRGB, Index, Red, Green, Blue Arguments Index The index within the Palette object to be set. This value should be in the range of 0 Value < N_COLORS. Red The red value to set in the color palette. Green The green value to set in the color palette. Blue The blue value to set in the color palette. Keywords None IDLGRPALETTE::SETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPalette::SetProperty The IDLgrPalette::SetProperty procedure method sets the value of a property or group of properties for the palette. Syntax Obj -> [IDLgrPalette::]SetProperty Arguments None Keywords Any keyword to IDLgrPalette::Init followed by the word "Set" can be set using IDLgrPalette::SetProperty. IDLGRPATTERN [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPattern A pattern object describes which pixels are filled and which are left blank when an area is filled. Pattern objects are used by setting the FILL_PATTERN property of a polygon object equal to the object reference of the pattern object. Superclasses This class has no superclass. Subclasses This class has no subclasses. Creation See IDLgrPattern::Init. Methods Intrinsic Methods This class has this following methods: * IDLgrPattern::Cleanup * IDLgrPattern::GetProperty * IDLgrPattern::Init * IDLgrPattern:SetProperty IDLGRPATTERN::CLEANUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPattern::Cleanup The IDLgrPattern::Cleanup procedure method performs all cleanup on the object. Note Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass. Syntax OBJ_DESTROY, Obj or Obj -> [IDLgrPattern::]Cleanup(Only in subclass' Cleanup method.) Arguments None Keywords None IDLGRPATTERN::GETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPattern::GetProperty The IDLgrPattern::GetProperty procedure method retrieves the value of a property or group of properties for the pattern. Syntax Obj -> [IDLgrPattern::]GetProperty [, ALL=variable] Arguments None Keywords Any keyword to IDLgrPattern::Init followed by the word "Get" can be retrieved using IDLgrPattern::GetProperty. In addition, the following keywords are available: ALL Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the properties associated with the state of this object. State information about the object includes things like color, range, tick direction, etc., but not image, vertex, or connectivity data, or user values. Note The fields of this structure may change in subsequent releases of IDL. IDLGRPATTERN::INIT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPattern::Init The IDLgrPattern::Init function method initializes the pattern object. Note Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass. Syntax Obj = OBJ_NEW('IDLgrPattern' [, Style] [, ORIENTATION{Get, Set}=ccw degrees from horiz] [, NAME{Get, Set}=string] [, PATTERN{Get, Set}=32 x 32 bit array] [, SPACING{Get, Set}=pixels] [, STYLE{Get, Set}={0 | 1 | 2}] [, THICK=pixels{1.0 to 10.0}] [, UVALUE{Get, Set}=value] ) or Result = Obj -> [IDLgrPattern::]Init( [Style] ) (Only in a subclass' Init method.) Note Keywords can be used in either form. They are omitted in the second form for brevity. Arguments Style A integer value representing the type of pattern. Valid values are: * 0 = Solid color (default) * 1 = Line Fill * 2 = Pattern Keywords Properties retrievable via IDLgrPattern::GetProperty are indicated by the word "Get" following the keyword. Properties settable via IDLgrPattern:SetProperty are indicated by the word "Set" following the keyword. ORIENTATION (Get, Set) Set this keyword to a scalar representing the angle (measured in degrees counterclockwise from the horizontal) of the lines used in a Line Fill. This keyword is ignored unless the Style argument (or STYLE property) is set to one. NAME (Get, Set) Set this keyword equal to a string containing the name associated with this object. The default is the null string, ' '. PATTERN (Get, Set) Set this keyword to a 32 x 32 bit array (bitmap) describing the pattern that will be tiled over a polygon when a pattern fill is used. The bitmap must be configured as a 4 x 32 "bitmap byte array" as created by the CVTTOBM function. Each bit that is a 1 is drawn, each bit that is 0 is not drawn. Each bit in this array represents a 1 point by 1 point square area of pixels on the destination device. This keyword is ignored unless the Style argument (or STYLE keyword) is set to 2. SPACING (Get, Set) Set this keyword equal to a floating-point value representing the distance (measured in points) between the lines used for a Line Fill. This keyword is ignored unless the Style argument (or STYLE property) is set to 1. The default is 2.0 points. STYLE (Get, Set) Set this keyword to one of the following values specifying the type of pattern: * 0 = Solid (default) * 1 = Line Fill * 2 = Pattern This keyword is the same as the Style argument described above. THICK Set this keyword to a value between 1.0 and 10.0, specifying the line thickness to be used to draw the pattern lines for a Line Fill, in points. The default is 1.0 points. This keyword is ignored unless the Style argument or STYLE keyword is set to 1. UVALUE (Get, Set) Set this keyword to a value of any type. You can use this "user value" to contain any information you wish. Remember that if you set the user value equal to a pointer or object reference, you should destroy the pointer or object reference explicitly when destroying the object to which the user value applies. IDLgrPattern:SetProperty The IDLgrPattern::SetProperty procedure method sets the value of a property or group of properties for the pattern. Syntax Obj -> [IDLgrPattern::]SetProperty Arguments None Keywords Any keyword to IDLgrPattern::Init followed by the word "Set" can be set using IDLgrPattern::SetProperty. IDLGRPLOT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPlot A plot object creates a set of polylines connecting data points in two-dimensional space. An IDLgrPlot object is an atomic graphic object; it is one of the basic drawable elements of the IDL Object Graphics system, and it is not a container for other objects. Superclasses This class has no superclasses. Subclasses This class has no subclasses. Creation See "IDLgrPlot::Init" on page 2101. Methods Intrinsic Methods This class has the following methods: * IDLgrPlot::Cleanup * IDLgrPlot::GetCTM * IDLgrPlot::GetProperty * IDLgrPlot::Init * IDLgrPlot::SetProperty IDLGRPLOT::CLEANUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPlot::Cleanup The IDLgrPlot::Cleanup procedure method performs all cleanup on the object. Note Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass. Syntax OBJ_DESTROY, Obj or Obj -> [IDLgrPlot::]Cleanup (Only in subclass' Cleanup method.) Arguments None Keywords None IDLGRPLOT::GETCTM [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPlot::GetCTM The IDLgrPlot::GetCTM function method returns the 4 x 4 double-precision floating-point graphics transform matrix from the current object upward through the graphics tree. Syntax Result = Obj -> [IDLgrPlot::]GetCTM( [, DESTINATION=objref] [, PATH=objref(s)] [, TOP=objref to IDLgrModel object] ) Arguments None Keywords DESTINATION Set this keyword to the object reference of a destination object to specify that the projection matrix for the View object in the current tree be included in the returned transformation matrix. The resulting matrix will transform a point in the data space of the object on which the GetCTM method is called into a normalized coordinate system (-1 to +1 in X, Y, and Z), relative to the View object that contains the plot object. PATH Set this keyword to a single object reference or a vector of object references. This keyword specifies the path in the graphics hierarchy to compute the transformation matrix. Each path object reference specified with this keyword must contain an alias. The transformation matrix is computed for the version of the object falling within that path. If this keyword is not set, the PARENT properties determine the path from the current object to the top of the graphics hierarchy and no alias paths are pursued. If IDLgrPlot::GetCTM is called from within a Draw method, with the DESTINATION keyword set and the PATH keyword not set, the alias path used to find the object during the draw is used, rather than the PARENT path. Note For more information on aliases, refer to the ALIAS keyword in IDLgrModel::Add. TOP Set this keyword equal to the object reference to an IDLgrModel object to specify that the returned matrix accumulate from the object on which the GetCTM method is called up to but not including the specified model object. IDLGRPLOT::GETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPlot::GetProperty The IDLgrPlot::GetProperty procedure method retrieves the value of the property or group of properties for the plot. Syntax Obj -> [IDLgrPlot::]GetProperty [, ALL=variable] [, DATA=variable] [, PARENT=variable] [, ZRANGE=variable] Arguments None Keywords Any keyword to IDLgrPlot::Init followed by the word "Get" can be retrieved using IDLgrPlot::GetProperty. In addition, the following keywords are available: ALL Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the properties associated with the state of this object. State information about the object includes things like color, range, tick direction, etc., but not image, vertex, or connectivity data, or user values. Note The fields of this structure may change in subsequent releases of IDL. DATA Set this keyword to a named variable that will contain the plot data in a 3 x n array, [DataX, DataY, DataZ]. PARENT Set this keyword equal to a named variable that will contain an object reference to the object that contains this object. ZRANGE Set this keyword to a named variable that will contain a two-element vector of the form [zmin, zmax] specifying the range of z data values covered by the graphic object. IDL maintains and returns this property in double-precision floating-point. Note The XRANGE and YRANGE properties can also be retrieved via the GetProperty method; ZRANGE, however, can only be retrieved, not initialized (Init method) or set (SetProperty method). IDLGRPLOT::INIT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPlot::Init The IDLgrPlot::Init function method initializes the plot object. Note Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass. Syntax Obj = OBJ_NEW('IDLgrPlot' [, [X,] Y] [, COLOR{Get, Set}=index or RGB vector | , VERT_COLORS{Get, Set}=vector] [, DATAX {Set}=vector] [, DATAY{Set}=vector] [, /DOUBLE{Get, Set}] [, /HIDE{Get, Set}] [, /HISTOGRAM{Get, Set}] [, LINESTYLE{Get, Set}=integer or two-element vector] [, MAX_VALUE{Get, Set}=value] [, MIN_VALUE{Get, Set}=value] [, NAME{Get, Set}=string] [, NSUM{Get, Set}=value] [, PALETTE{Get, Set}=objref] [, /POLAR{Get, Set}] [, /RESET_DATA{Set}] [, SHARE_DATA{Set}=objref] [, SYMBOL{Get, Set}=objref(s)] [, THICK{Get, Set}=points{1.0 to 10.0}] [, /USE_ZVALUE] [, UVALUE{Get, Set}=value] [, XCOORD_CONV{Get, Set}=vector] [, XRANGE{Get, Set}=[xmin, xmax]] [, YCOORD_CONV{Get, Set}=vector] [, YRANGE{Get, Set}=[ymin, ymax]] [, ZCOORD_CONV{Get, Set}=vector] [, ZVALUE{Get, Set}=value] ) or Result = Obj -> [IDLgrPlot::]Init( [[X,] Y] ) (Only in a subclass' Init method.) Note Keywords can be used in either form. They are omitted in the second form for brevity. Arguments X A vector representing the abscissa values to be plotted. If X is provided, Y is plotted as a function of X. The value for this argument is double-precision floating-point if the DOUBLE keyword is set or the inputted value is of type DOUBLE. Otherwise it is converted to single-precision floating-point. Y Either a vector of two-element arrays [x, y] representing the points to be plotted, or a vector representing the ordinate values to be plotted. If Y is a vector of ordinate values and X is not specified, Y is plotted as a function of the vector index of Y. The value for this argument is double-precision floating-point if the DOUBLE keyword is set or the inputted value is of type DOUBLE. Otherwise it is converted to single- precision floating-point. Keywords Properties retrievable via IDLgrPlot::GetProperty are indicated by the word "Get" following the keyword. Properties settable via IDLgrPlot::SetProperty are indicated by the word "Set" following the keyword. COLOR (Get, Set) Set this keyword to the color to be used as the foreground color for this plot. The color may be specified as a color lookup table index or as an RGB vector. The default is [0, 0, 0]. DATAX (Set) Set this keyword to a vector specifying the X values to be plotted. This keyword is the same as the X argument. DATAY (Set) Set this keyword to a vector specifying the Y values to be plotted. This keyword is the same as the Y argument. DOUBLE (Get, Set) Set this keyword to indicate that data provided by any of the X or Y arguments or DATAX or DATAY keywords will be stored in this object as double-precision floating-point. If you set this keyword equal to 0, the data provided will be stored in this object as single-precision floating-point. If you do not specify this keyword, the data is stored as double-precision floating-point if the original data was of type DOUBLE or as single-precision floating-point if the original data was not of type DOUBLE. HIDE (Get, Set) Set this keyword to a boolean value indicating whether this object should be drawn: * 0 = Draw graphic (the default) * 1 = Do not draw graphic HISTOGRAM (Get, Set) Set this keyword to force only horizontal and vertical lines to be used to connect the plotted points. By default, the points are connected using a single straight line. LINESTYLE (Get, Set) Set this keyword to indicate the line style that should be used to draw the plot lines. The value can be either an integer value specifying a pre-defined line style, or a two- element vector specifying a stippling pattern. To use a pre-defined line style, set the LINESTYLE property equal to one of the following integer values: * 0 = Solid line (the default) * 1 = dotted * 2 = dashed * 3 = dash dot * 4 = dash dot dot dot * 5 = long dash * 6 = no line drawn To define your own stippling pattern, specify a two-element vector [repeat, bitmask], where repeat indicates the number of times consecutive runs of 1's or 0's in the bitmask should be repeated. (That is, if three consecutive 0's appear in the bitmask and the value of repeat is 2, then the line that is drawn will have six consecutive bits turned off.) The value of repeat must be in the range 1 repeat 255. The bitmask indicates which pixels are drawn and which are not along the length of the line. Bitmask is most conveniently specified as a 16-bit hexadecimal value. For example, LINESTYLE = [2, 'F0F0'X] describes a dashed line (8 bits on, 8 bits off, 8 bits on, 8 bits off). MAX_VALUE (Get, Set) The maximum value to be plotted. If this keyword is present, data values greater than the value of MAX_VALUE are treated as missing data and are not plotted. Note that the IEEE floating-point value NaN is also treated as missing data. IDL converts, maintains, and returns this data as double-precision floating-point. MIN_VALUE (Get, Set) The minimum value to be plotted. If this keyword is present, data values less than the value of MIN_VALUE are treated as missing data and are not plotted. Note that the IEEE floating-point value NaN is also treated as missing data. IDL converts, maintains, and returns this data as double-precision floating-point. NAME (Get, Set) Set this keyword equal to a string containing the name associated with this object. The default is the null string, ' '. NSUM (Get, Set) Set this keyword to the number of data points to average when plotting. If NSUM is larger than 1, every group of NSUM points is averaged to produce one plotted point. If there are M data points, then M/NSUM points are plotted. PALETTE (Get, Set) Set this keyword equal to the object reference of a palette object (an instance of the IDLgrPalette object class). This keyword is only used if the destination device is using the RGB color model. If so, and a color value for the object is specified as a color index value, the palette set by this keyword is used to translate the color to RGB space. If the PALETTE property on this object is not set, the destination object PALETTE property is used (which defaults to a grayscale ramp). POLAR (Get, Set) Set this keyword to create a polar plot. The X and Y arguments must both be present. The X argument represents the radius, and the Y argument represents the angle expressed in radians. RESET_DATA (Set) Set this keyword to treat the data provided via one of the DATA[XY] properties as a new data set unique to this object, rather than overwriting data that is shared by other objects. There is no reason to use this keyword if the object on which the property is being set does not currently share data with another object (that is, if the SHARE_DATA property is not in use). This keyword has no effect if no new data is provided via a DATA property. SHARE_DATA (Set) Set this keyword to an object with which data is to be shared by this plot. A plot may only share data with another plot. The SHARE_DATA property is intended for use when data values are not set via an argument to the object's Init method or by setting the object's DATA property. SYMBOL (Get, Set) Set this keyword to a vector containing instances of the IDLgrSymbol object class. Each symbol in the vector will be drawn at the corresponding plotted point. If there are more points than elements in SYMBOL, the elements of the SYMBOL vector are cyclically repeated. By default, no symbols are drawn. To remove symbols from a plot, set the SYMBOL property equal to a null object reference. THICK (Get, Set) Set this keyword to a value between 1.0 and 10.0, specifying the line thickness to be used to draw the plotted lines, in points. The default is 1.0 points. USE_ZVALUE Set this keyword to use the current ZVALUE. The plot is considered three- dimensional if this keyword is set. UVALUE (Get, Set) Set this keyword to a value of any type. You can use this "user value" to contain any information you wish. Remember that if you set the user value equal to a pointer or object reference, you should destroy the pointer or object reference explicitly when destroying the object it is a user value of. VERT_COLORS (Get, Set) Set this keyword to a vector of colors to be used to draw at each vertex. Color is interpolated between vertices. If there are more plot points than elements in VERT_COLORS, the elements of VERT_COLORS are cyclically repeated. By default, the plot is all drawn in the single color provided by the COLOR keyword. If the VERT_COLORS is provided, the COLOR keyword is ignored. XCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert X coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedX = s0 + s1 * DataX Recommended values are: [(-Xmin)/(Xmax-Xmin), 1/(Xmax-Xmin)] The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double- precision floating-point. XRANGE (Get, Set) Set this keyword equal to a two-element vector of the form [xmin, xmax] specifying the range of x data coordinates covered by the graphic object. If this property is not specified, the minimum and maximum data values are used. IDL converts, maintains, and returns this data as double-precision floating-point. YCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert Y coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedY = s0 + s1 * DataY Recommended values are: [(-Ymin)/(Ymax-Ymin), 1/(Ymax-Ymin)] The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double- precision floating-point. YRANGE (Get, Set) Set this keyword equal to a two-element vector of the form [ymin, ymax] specifying the range of y data values covered by the graphic object. If this property is not specified, the minimum and maximum data values are used. IDL converts, maintains, and returns this data as double-precision floating-point. ZCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert Z coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedZ = s0 + s1 * DataZ The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double- precision floating-point. ZVALUE (Get, Set) Set this keyword equal to a two-element vector of the form [[xy]min, [xy]max] specifying the range of [xy] data coordinates covered by the graphic object. If this property is not specified, the minimum and maximum data values are used. IDL converts, maintains, and returns this data as double-precision floating-point. Note The USE_ZVALUE keyword needs to be set in order for ZVALUEs to take affect. IDLGRPLOT::SETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPlot::SetProperty The IDLgrPlot::SetProperty procedure method sets the value of the property or group of properties for the plot. Syntax Obj -> [IDLgrPlot::]SetProperty Arguments None Keywords Any keyword to IDLgrPlot::Init followed by the word "Set" can be set using IDLgrPlot::SetProperty. IDLGRPOLYGON [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPolygon A polygon object represents one or more polygons that share a given set of vertices and rendering attributes. All polygons must be convex-that is, a line connecting any pair of vertices on the polygon cannot fall outside the polygon. Concave polygons can be converted to a set of convex polygons using the IDLgrTessellator object. An IDLgrPolygon object is an atomic graphic object; it is one of the basic drawable elements of the IDL Object Graphics system, and it is not a container for other objects. Superclasses This class has no superclasses. Subclasses This class has no subclasses. Creation See "IDLgrPolygon::Init" on page 2114. Methods Intrinsic Methods This class has the following methods: * IDLgrPolygon::Cleanup * IDLgrPolygon::GetCTM * IDLgrPolygon::GetProperty * IDLgrPolygon::Init * IDLgrPolygon::SetProperty IDLGRPOLYGON::CLEANUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPolygon::Cleanup The IDLgrPolygon::Cleanup procedure method performs all cleanup on the object. Note Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass. Syntax OBJ_DESTROY, Obj or Obj -> [IDLgrPolygon::]Cleanup(Only in subclass' Cleanup method.) Arguments None Keywords None IDLGRPOLYGON::GETCTM [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPolygon::GetCTM The IDLgrPolygon::GetCTM The IDLgrPolygon::GetCTM function method returns the 4 x 4 double-precision floating-point graphics transform matrix from the current object upward through the graphics tree. Syntax Result = Obj -> [IDLgrPolygon::]GetCTM( [, DESTINATION=objref] [, PATH=objref(s)] [, TOP=objref to IDLgrModel object] ) Arguments None Keywords DESTINATION Set this keyword to the object reference of a destination object to specify that the projection matrix for the View object in the current tree be included in the returned transformation matrix. The resulting matrix will transform a point in the data space of the object on which the GetCTM method is called into a normalized coordinate system (-1 to +1 in X, Y, and Z), relative to the View object that contains the polygon object. PATH Set this keyword to a single object reference or a vector of object references. This keyword specifies the path in the graphics hierarchy to compute the transformation matrix. Each path object reference specified with this keyword must contain an alias. The transformation matrix is computed for the version of the object falling within that path. If this keyword is not set, the PARENT properties determine the path from the current object to the top of the graphics hierarchy and no alias paths are pursued. If IDLgrPolygonl::GetCTM is called from within a Draw method, with the DESTINATION keyword set and the PATH keyword not set, the alias path used to find the object during the draw is used, rather than the PARENT path. Note For more information on aliases, refer to the ALIAS keyword in IDLgrModel::Add. TOP Set this keyword equal to the object reference to an IDLgrModel object to specify that the returned matrix accumulate from the object on which the GetCTM method is called up to but not including the specified model object. IDLGRPOLYGON::GETPROPERTY[1] [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPolygon::GetProperty The IDLgrPolygon::GetProperty procedure method retrieves the value of the property or group of properties for the polygons. Syntax Obj -> [IDLgrPolygon::]GetProperty [, ALL=variable] [, PARENT=variable] [, XRANGE=variable] [, YRANGE=variable] [, ZRANGE=variable] Arguments There are no arguments for this methods. Keywords Any keyword to IDLgrPolygon::Init followed by the word "Get" can be retrieved using IDLgrPolygon::GetProperty. In addition, the following keywords are available: ALL Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the properties associated with the state of this object. State information about the object includes things like color, range, tick direction, etc., but not image, vertex, or connectivity data, or user values. Note The fields of this structure may change in subsequent releases of IDL. PARENT Set this keyword equal to a named variable that will contain an object reference to the object that contains this object. XRANGE Set this keyword equal to a named variable that will contain a two-element vector of the form [xmin, xmax] that specifies the range of x data coordinates covered by the graphic object. IDL maintains and returns this property in double-precision floating- point. YRANGE Set this keyword equal to a named variable that will contain a two-element vector of the form [ymin, ymax] that specifies the range of y data coordinates covered by the graphic object. IDL maintains and returns this property in double-precision floating- point. ZRANGE Set this keyword equal to a named variable that will contain a two-element vector of the form [zmin, zmax] that specifies the range of z data coordinates covered by the graphic object. IDL maintains and returns this property in double-precision floating- point. IDLGRPOLYGON::INIT[1] [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPolygon::Init The IDLgrPolygon::Init function method initializes the polygons object. Note Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass. Syntax Obj = OBJ_NEW('IDLgrPolygon' [, X [, Y[, Z]]] [, BOTTOM{Get, Set}=index or RGB vector] [, COLOR{Get, Set}=index or RGB vector | , VERT_COLORS{Get, Set}=vector] [, DATA{Get, Set}=array] [, /DOUBLE{Get, Set}] [, FILL_PATTERN{Get, Set}=objref to IDLgrPattern object] [, /HIDDEN_LINES] [, /HIDE{Get, Set}] [, LINESTYLE{Get, Set}=value] [, NAME{Get, Set}=string] [, NORMALS{Get, Set}=array] [, PALETTE=objref] [, POLYGONS{Get, Set}=array of polygon descriptions] [, REJECT{Get, Set}={0 | 1 | 2}] [, /RESET_DATA{Set}] [, SHADE_RANGE{Get, Set}=array] [, SHADING{Get, Set}={0 | 1}] [, SHARE_DATA{Set}=objref] [, STYLE{Get, Set}={0 | 1 | 2}] [, TEXTURE_COORD{Get, Set}=array] [, /TEXTURE_INTERP{Get, Set}] [, TEXTURE_MAP{Get, Set}=objref to IDLgrImage object] [, THICK{Get, Set}=points{1.0 to 10.0}] [, XCOORD_CONV{Get, Set}=vector] [, YCOORD_CONV{Get, Set}=vector] [, ZCOORD_CONV{Get, Set}=vector] [, ZERO_OPACITY_SKIP{Get, Set}={0 | 1}] ) or Result = Obj -> [IDLgrPolygon::]Init( [X, [Y, [Z]]] ) (Only in a subclass' Init method.) Note Keywords can be used in either form. They are omitted in the second form for brevity. Arguments X A vector argument providing the X coordinates of the vertices. The vector must contain at least three elements. If the Y and Z arguments are not provided, X must be an array of either two or three vectors (i.e., [2,*] or [3,*]), in which case, X[0,*] specifies the X values, X[1,*] specifies the Y values, and X[2,*] specifies the Z values. This argument is stored as double precision floating point values if the argument variable is of type DOUBLE or if the DOUBLE property is non-zero, otherwise it is converted to single precision floating point. Y A vector argument providing the Y coordinates of the vertices. The vector must contain at least three elements. This argument is stored as double precision floating point values if the argument variable is of type DOUBLE or if the DOUBLE property is non-zero, otherwise it is converted to single precision floating point. Z A vector argument providing the Z coordinates of the vertices. The vector must contain at least three elements. This argument is stored as double precision floating point values if the argument variable is of type DOUBLE or if the DOUBLE property is non-zero, otherwise it is converted to single precision floating point. Keywords Properties retrievable via IDLgrPolygon::GetProperty are indicated by the word "Get" following the keyword. Properties settable via IDLgrPolygon::SetProperty are indicated by the word "Set" following the keyword. BOTTOM (Get, Set) Set this keyword to an RGB or Indexed color for drawing the backs of the polygons. (The back of a polygon is the side opposite the normal direction). Setting a bottom color is only supported when the destination device uses RGB color mode. COLOR (Get, Set) Set this keyword to an RGB or Indexed color for drawing polygons. The default color is [0, 0, 0] (black). If the TEXTURE_MAP property is used, the final color is modulated by the texture map pixel values. This keyword is ignored if the VERT_COLORS keyword is provided. DATA (Get, Set) Set this keyword to a 2 x n or a 3 x n array which defines, respectively, the 2D or 3D vertex data. DATA is equivalent to the optional arguments, X, Y, and Z. This property is stored as double precision floating point values if the property variable is of type DOUBLE or if the DOUBLE keyword parameter is also specified, otherwise it is converted to single precision floating point. DOUBLE (Get, Set) Set this keyword to a non-zero value to indicate that data provided by any of the X, Y, or Z arguments or DATA keyword should be stored in this object in double precision floating point. Set this keyword to zero to indicate that the data should be stored in single precision floating point. IDL converts any value data already stored in the object to the requested precision, if necessary. Note that this keyword does not need to be set if any of the X, Y, or Z arguments or the DATA parameters are of type DOUBLE. However, setting this keyword may be desirable if the data consists of large integers that cannot be accurately represented in single precision floating point. This property is also automatically set to one if any of the X, Y or Z arguments or the DATA parameter is stored using a variable of type DOUBLE. FILL_PATTERN (Get, Set) Set this keyword equal to an object reference to an IDLgrPattern object (or an array of IDLgrPattern objects) to specify the fill pattern to use for filling the polygons. By default, FILL_PATTERN is set to a null object reference, specifying a solid fill. HIDDEN_LINES Set this keyword to draw point and wireframe surfaces using hidden line (point) removal. By default, hidden line removal is disabled. HIDE (Get, Set) Set this keyword to a boolean value indicating whether this object should be drawn: * 0 = Draw graphic (the default) * 1 = Do not draw graphic LINESTYLE (Get, Set) Set this keyword to indicate the line style that should be used to draw the polygon. The value can be either an integer value specifying a pre-defined line style, or a two- element vector specifying a stippling pattern. To use a pre-defined line style, set the LINESTYLE property equal to one of the following integer values: * 0 = Solid line (the default) * 1 = dotted * 2 = dashed * 3 = dash dot * 4 = dash dot dot dot * 5 = long dash * 6 = no line drawn To define your own stippling pattern, specify a two-element vector [repeat, bitmask], where repeat indicates the number of times consecutive runs of 1's or 0's in the bitmask should be repeated. (That is, if three consecutive 0's appear in the bitmask and the value of repeat is 2, then the line that is drawn will have six consecutive bits turned off.) The value of repeat must be in the range 1 repeat 255. The bitmask indicates which pixels are drawn and which are not along the length of the line. Bitmask is most conveniently specified as a 16-bit hexadecimal value. For example, LINESTYLE = [2, 'F0F0'X] describes a dashed line (8 bits on, 8 bits off, 8 bits on, 8 bits off). NAME (Get, Set) Set this keyword equal to a string containing the name associated with this object. The default is the null string, ' '. NORMALS (Get, Set) Set this keyword to a 3 x n array of unit polygon normals at each vertex. If this keyword is not set, vertex normals are computed by averaging shared polygon normals at each vertex. Normals are computed using the Right Hand Rule; that is, if the polygon is facing the viewer, vertices are taken in counterclockwise order. To remove previously specified normals, set NORMALS to a scalar. Note Computing normals is a computationally expensive operation. Rendering speed increases significantly if you supply the surface normals explicitly. You can compute the array of polygon normals used by this keyword automatically. See "COMPUTE_MESH_NORMALS" on page 211 for details. Once you use the NORMALS keyword in a call to IDLgrPolygon::Init or IDLgrPolygon::SetProperty, you are responsible for that IDLgrPolygon's normals from then on. IDL will not calculate that IDLgrPolygon's normals for you automatically, even if you draw the IDLgrPolygon after vertices or connectivity have been changed. If you do not use the NORMALS keyword, IDL calculates normals the first time it draws the IDLgrPolygon. IDL reuses those normals for subsequent draws unless it determines that a fresh recalculation of normals is required, such as if the vertices of the IDLgrPolygon are changed, or you supply new normals via the NORMALS keyword. PALETTE Set this keyword equal to the object reference of a palette object (an instance of the IDLgrPalette object class). This keyword is only used if the destination device is using the RGB color model. If so, and a color value for the object is specified as a color index value, the palette set by this keyword is used to translate the color to RGB space. If the PALETTE property on this object is not set, the destination object PALETTE property is used (which defaults to a grayscale ramp). POLYGONS (Get, Set) Set this keyword to an array of polygon descriptions. A polygon description is an integer or longword array of the form: [n, i0, i1, ..., in-1], where n is the number of vertices that define the polygon, and i0..in-1 are indices into the X, Y, and Z arguments that represent the polygon vertices. To ignore an entry in the POLYGONS array, set the vertex count, n, to 0. To end the drawing list, even if additional array space is available, set n to -1. If this keyword is not specified, a single polygon will be generated. Note The connectivity array described by POLYGONS allows an individual object to contain more than one polygon. Vertex, normal, and color information can be shared by the multiple polygons. Consequently, the polygon object can represent an entire mesh and compute reasonable normal estimates in most cases. REJECT (Get, Set) Set this keyword to an integer value to reject polygons as being hidden depending on the orientation of their normals. Select from one of the following values: * 0 = No polygons are hidden * 1 = Polygons whose normals point away from the viewer are hidden * 2 = Polygons whose normals point toward the viewer are hidden Set this keyword to zero to draw all polygons regardless of the direction of their normals. RESET_DATA (Set) Set this keyword to treat the data provided via the DATA property as a new data set unique to this object, rather than overwriting data that is shared by other objects. There is no reason to use this keyword if the object on which the property is being set does not currently share data with another object (that is, if the SHARE_DATA property is not in use). This keyword has no effect if no new data is provided via the DATA property. SHADE_RANGE (Get, Set) Set this keyword to a two-element array that specifies the range of pixel values (color indices) to use for shading. The first element is the color index for the darkest pixel. The second element is the color index for the brightest pixel. The default is [0, 255]. This keyword is ignored when the polygons are drawn to a graphics destination that uses the RGB color model. SHADING (Get, Set) Set this keyword to an integer representing the type of shading to use: * 0 = Flat (default): The color of the first vertex in each polygon is used to define the color for the entire polygon. The color has a constant intensity based upon the normal vector. * 1 = Gouraud: The colors along each line are interpolated between vertex colors, and then along scanlines from each of the edge intensities. Gouraud shading may be slower than flat shading, but results in a smoother appearance. SHARE_DATA (Set) Set this keyword to an object with which data is to be shared by this polygon(s). Polygons may only share data with another polygons object or a polyline. The SHARE_DATA property is intended for use when data values are not set via an argument to the object's Init method or by setting the object's DATA property. STYLE (Get, Set) Set this keyword to specify how the polygon should be drawn: * 0 = Points: Only vertices are drawn, using either COLOR or VERT_COLORS. * 1 = Lines: Each polygon is outlined by connecting vertices. * 2 = Filled (default): The polygon faces are shaded. Note Texturing is in effect only when STYLE = 2 (Filled). TEXTURE_COORD (Get, Set) A 2 x n array containing the texture map coordinates for each of the n polygon vertices. Use this keyword in conjunction with the TEXTURE_MAP keyword to wrap images over 2D and 3D polygons. Default coordinates are not provided. Texture coordinates are normalized. This means that the m x n image object specified via the TEXTURE_MAP property is mapped into the range [0.0, 0.0] to [1.0, 1.0]. If texture coordinates outside the range [0.0, 0.0] to [1.0, 1.0] are specified, the image object is tiled into the larger range. For example, suppose the image object specified via TEXTURE_MAP is a 256 x 256 array, and we want to map the image into a square two units on each side. To completely fill the square with a single copy of the image: TEXTURE_COORD = [[0,0], [1,0], [1,1], [0,1]] To fill the square with four tiled copies of the image: TEXTURE_COORD = [[0,0], [2,0], [2,2], [0,2]] TEXTURE_INTERP (Get, Set) Set this keyword to indicate that bilinear sampling is to be used for texture mapping an image onto the polygon(s). The default is nearest neighbor sampling. TEXTURE_MAP (Get, Set) Set this keyword to the object reference of an IDLgrImage object to be texture mapped onto the polygons. The tiling or mapping of the texture is defined expressly by TEXTURE_COORD. If this keyword is omitted, polygons are filled with the color specified by the COLOR or VERT_COLORS property. If both TEXTURE_MAP and COLORS or VERT_COLORS properties exist, the color of the texture is modulated by the base color of the object. (This means that for the clearest display of the texture image, the COLOR property should be set equal to [255,255,255].) To remove a texture map, set TEXTURE_MAP equal to a null object reference. Setting TEXTURE_MAP to the object reference of an IDLgrImage that contains an Alpha channel allows you to create a transparent IDLgrPolygon object. For more on the Alpha channel, see "Image Objects" in Chapter 25 of Using IDL. If an Alpha channel is present in the IDLgrImage object, IDL blends the texture using the blend function src=Alpha and dst=1 ­ Alpha, which corresponds to a BLEND_FUNCTION of (3,4) as described for the IDLgrImage object. If the width and/or height of the provided image is not an exact power of two, then the texture map will consist of the given image pixel values resampled to the nearest larger dimensions that are exact powers of two. Note Texture mapping is disabled when rendering to a destination object that uses Indexed color mode. THICK (Get, Set) Set this keyword to a value between 1.0 and 10.0, specifying the size of the points or the thickness of the lines to be drawn when STYLE is set to either 0 (Points) or 1 (Lines), in points. The default is 1.0 points. VERT_COLORS (Get, Set) Set this keyword to a vector of colors to be used to draw at each vertex. Color is interpolated between vertices if SHADING is set to 1 (Gouraud). If there are more vertices than elements in VERT_COLORS, the elements of VERT_COLORS are cyclically repeated. By default, the polygons are all drawn in the single color provided by the COLOR keyword. To remove vertex colors, set VERT_COLORS to a scalar. Note If the polygon object is being rendered on a destination device that uses the Indexed color model, and the view that contains the polygon also contains one or more light objects, the VERT_COLORS property is ignored and the SHADE_RANGE property is used instead. XCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert X coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedX = s0 + s1 * DataX Recommended values are: [(-Xmin)/(Xmax-Xmin), 1/(Xmax-Xmin)] The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double- precision floating-point. YCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert Y coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedY = s0 + s1 * DataY Recommended values are: [(-Ymin)/(Ymax-Ymin), 1/(Ymax-Ymin)] The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double- precision floating-point. ZCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert Z coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedZ = s0 + s1 * DataZ Recommended values are: [(-Zmin)/(Zmax-Zmin), 1/(Zmax-Zmin)] The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double- precision floating-point. ZERO_OPACITY_SKIP (Get, Set) Set this keyword to gain finer control over the rendering of textured polygon pixels (texels) with an opacity of 0 in the texture map. Texels with zero opacity do not affect the color of a screen pixel since they have no opacity. If this keyword is set to 1, any texels are "skipped" and not rendered at all. If this keyword is set to zero, the Z- buffer is updated for these pixels and the display image is not affected as noted above. By updating the Z-buffer without updating the display image, the polygon can be used as a clipping surface for other graphics primitives drawn after the current graphics object. The default value for this keyword is 1. Note This keyword has no effect if no texture map is used or if the texture map in use does not contain an opacity channel. IDLGRPOLYGON::SETPROPERTY[1] [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPolygon::SetProperty The IDLgrPolygon::SetProperty procedure method sets the value of the property or group of properties for the polygons. Syntax Obj -> [IDLgrPolygon::]SetProperty Arguments None Keywords Any keyword to IDLgrPolygon::Init followed by the word "Set" can be set using IDLgrPolygon::SetProperty. IDLGRPOLYLINE [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPolyline A polyline object represents one or more polylines that share a set of vertices and rendering attributes. An IDLgrPolyline object is an atomic graphic object; it is one of the basic drawable elements of the IDL Object Graphics system, and it is not a container for other objects. Superclasses This class has no superclasses. Subclasses This class has no subclasses. Creation See "IDLgrPolyline::Init" on page 2130. Methods Intrinsic Methods This class has the following methods: * IDLgrPolyline::Cleanup * IDLgrPolyline::GetCTM * IDLgrPolyline::GetProperty * IDLgrPolyline::Init * IDLgrPolyline::SetProperty IDLGRPOLYLINE::CLEANUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPolyline::Cleanup The IDLgrPolyline::Cleanup procedure method performs all cleanup on the object. Note Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass. Syntax OBJ_DESTROY, Obj or Obj -> [IDLgrPolyline::]Cleanup(Only in subclass' Cleanup method.) Arguments None Keywords None IDLGRPOLYLINE::GETCTM [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPolyline::GetCTM The IDLgrPolyline::GetCTM function method returns the 4 x 4 double-precision floating-point graphics transform matrix from the current object upward through the graphics tree. Syntax Result = Obj -> [IDLgrPolyline::]GetCTM( [, DESTINATION=objref] [, PATH=objref(s)] [, TOP=objref to IDLgrModel object] ) Arguments None Keywords DESTINATION Set this keyword to the object reference of a destination object to specify that the projection matrix for the View object in the current tree be included in the returned transformation matrix. The resulting matrix will transform a point in the data space of the object on which the GetCTM method is called into a normalized coordinate system (-1 to +1 in X, Y, and Z), relative to the View object that contains the polyline object. PATH Set this keyword to a single object reference or a vector of object references. This keyword specifies the path in the graphics hierarchy to compute the transformation matrix. Each path object reference specified with this keyword must contain an alias. The transformation matrix is computed for the version of the object falling within that path. If this keyword is not set, the PARENT properties determine the path from the current object to the top of the graphics hierarchy and no alias paths are pursued. If IDLgrPolyline::GetCTM is called from within a Draw method, with the DESTINATION keyword set and the PATH keyword not set, the alias path used to find the object during the draw is used, rather than the PARENT path. Note For more information on aliases, refer to the ALIAS keyword in IDLgrModel::Add. TOP Set this keyword equal to the object reference to an IDLgrModel object to specify that the returned matrix accumulate from the object on which the GetCTM method is called up to but not including the specified model object. IDLGRPOLYLINE::GETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPolyline::GetProperty The IDLgrPolyline::GetProperty procedure method retrieves the value of a property or group of properties for the polylines. Syntax Obj -> [IDLgrPolyline::]GetProperty [, ALL=variable] [, PARENT=variable] [, XRANGE=variable] [, YRANGE=variable] [, ZRANGE=variable] Arguments None Keywords Any keyword to IDLgrPolyline::Init followed by the word "Get" can be retrieved using IDLgrPolyline::GetProperty. In addition, the following keywords are available: ALL Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the properties associated with the state of this object. State information about the object includes things like color, range, tick direction, etc., but not image, vertex, or connectivity data, or user values. Note The fields of this structure may change in subsequent releases of IDL. PARENT Set this keyword equal to a named variable that will contain an object reference to the object that contains this object. XRANGE Set this keyword equal to a named variable that will contain a two-element vector of the form [xmin, xmax] that specifies the range of x data coordinates covered by the graphic object. IDL maintains and returns this property in double-precision floating- point. YRANGE Set this keyword equal to a named variable that will contain a two-element vector of the form [ymin, ymax] that specifies the range of y data coordinates covered by the graphic object. IDL maintains and returns this property in double-precision floating- point. ZRANGE Set this keyword equal to a named variable that will contain a two-element vector of the form [zmin, zmax] that specifies the range of z data coordinates covered by the graphic object. IDL maintains and returns this property in double-precision floating- point. IDLGRPOLYLINE::INIT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPolyline::Init The IDLgrPolyline::Init function method initializes the polylines object. Note Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass. Syntax Obj = OBJ_NEW('IDLgrPolyline' [, X [, Y[, Z]]] [, COLOR{Get, Set}=index or RGB vector | , VERT_COLORS{Get, Set}=vector] [, DATA{Get, Set}=array] [, /DOUBLE{Get, Set}] [, /HIDE{Get, Set}] [, LINESTYLE{Get, Set}=value] [, NAME{Get, Set}=string] [, PALETTE{Get, Set}=objref] [, POLYLINES{Get, Set}=array of polyline descriptions] [, /RESET_DATA{Set}] [, SHADING{Get, Set}={0 | 1}] [, SHARE_DATA{Set}=objref] [, SYMBOL{Get, Set}=objref(s)] [, THICK{Get, Set}=points{1.0 to 10.0}] [, UVALUE{Get, Set}=value] [, XCOORD_CONV{Get, Set}=vector] [, YCOORD_CONV{Get, Set}=vector] [, ZCOORD_CONV{Get, Set}=vector] ) or Result = Obj -> [IDLgrPolyline::]Init( [X, [Y, [Z]]] ) (Only in a subclass' Init method.) Note Keywords can be used in either form. They are omitted in the second form for brevity. Arguments X A vector providing the X components of the points to be connected. If the Y and Z arguments are not provided, X must be an array of either two or three vectors (i.e., [2,*] or [3,*]), in which case, X[0,*] specifies the X values, X[1,*] specifies the Y values, and X[2,*] specifies the Z values. This argument is stored as double precision floating point values if the argument variable is of type DOUBLE or if the DOUBLE property is non-zero, otherwise it is stored as single precision floating point. Y A vector providing the Y coordinates of the points to be connected. This argument is stored as double precision floating point values if the argument variable is of type DOUBLE or if the DOUBLE property is non-zero, otherwise it is stored as single precision floating point. Z A vector providing the Z coordinates of the points to be connected. This argument is stored as double precision floating point values if the argument variable is of type DOUBLE or if the DOUBLE property is non-zero, otherwise it is stored as single precision floating point. Keywords Properties retrievable via IDLgrPolyline::GetProperty are indicated by the word "Get" following the keyword. Properties settable via IDLgrPolyline::SetProperty are indicated by the word "Set" following the keyword. COLOR (Get, Set) Set this keyword to an RGB or Indexed color for drawing polylines. The default color is [0, 0, 0] (black). This keyword is ignored if the VERT_COLORS keyword is provided. DATA (Get, Set) Set this keyword to a 2 x n or a 3 x n array which defines, respectively, the 2D or 3D vertex data. DATA is equivalent to the optional arguments, X, Y, and Z. This property is converted to double-precision floating-point values if the DOUBLE keyword is set. Otherwise, it is converted to single-precision floating-point. DOUBLE (Get, Set) Set this keyword to indicate that data provided by any of the X, Y, or Z arguments or the DATA keyword will be stored in this object as double-precision floating-point. If you set this keyword equal to 0, the data provided will be stored in this object as single-precision floating-point. If you do not specify this keyword, the data is stored as double-precision floating-point if the original data was of type DOUBLE or as single-precision floating-point if the original data was not of type DOUBLE. HIDE (Get, Set) Set this keyword to a boolean value indicating whether this object should be drawn: * 0 = Draw graphic (the default) * 1 = Do not draw graphic LINESTYLE (Get, Set) Set this keyword to indicate the line style that should be used to draw the polyline. The value can be either an integer value specifying a pre-defined line style, or a two- element vector specifying a stippling pattern. To use a pre-defined line style, set the LINESTYLE property equal to one of the following integer values: * 0 = Solid line (the default) * 1 = dotted * 2 = dashed * 3 = dash dot * 4 = dash dot dot dot * 5 = long dash * 6 = no line drawn To define your own stippling pattern, specify a two-element vector [repeat, bitmask], where repeat indicates the number of times consecutive runs of 1's or 0's in the bitmask should be repeated. (That is, if three consecutive 0's appear in the bitmask and the value of repeat is 2, then the line that is drawn will have six consecutive bits turned off.) The value of repeat must be in the range 1 repeat 255. The bitmask indicates which pixels are drawn and which are not along the length of the line. Bitmask is most conveniently specified as a 16-bit hexadecimal value. For example, LINESTYLE = [2, 'F0F0'X] describes a dashed line (8 bits on, 8 bits off, 8 bits on, 8 bits off). NAME (Get, Set) Set this keyword equal to a string containing the name associated with this object. The default is the null string, ' '. PALETTE (Get, Set) Set this keyword equal to the object reference of a palette object (an instance of the IDLgrPalette object class). This keyword is only used if the destination device is using the RGB color model. If so, and a color value for the object is specified as a color index value, the palette set by this keyword is used to translate the color to RGB space. If the PALETTE property on this object is not set, the destination object PALETTE property is used (which defaults to a grayscale ramp). POLYLINES (Get, Set) Set this keyword to an array of polyline descriptions. A polyline description is an integer or longword array of the form: [n, i0, i1, ..., in-1], where n is the number of vertices that define the polyline, and i0..in-1 are indices into the X, Y, and Z arguments that represent the vertices of the polyline(s). To ignore an entry in the POLYLINES array, set the vertex count, n, to 0. To end the drawing list, even if additional array space is available, set n to -1. If this keyword is not specified, a single connected polyline will be generated from the X, Y, and Z arguments. Note The connectivity array described by POLYLINES allows an individual object to contain more than one polyline. Vertex, normal and color information can be shared by the multiple polylines. Consequently, the polyline object can represent an entire mesh and compute reasonable normal estimates in most cases. RESET_DATA (Set) Set this keyword to treat the data provided via one of the DATA property as a new data set unique to this object, rather than overwriting data that is shared by other objects. There is no reason to use this keyword if the object on which the property is being set does not currently share data with another object (that is, if the SHARE_DATA property is not in use). This keyword has no effect if no new data is provided via the DATA property. SHADING (Get, Set) Set this keyword to an integer representing the type of shading to use: * 0 = Flat (default): The color of the first vertex in a line segment is used to define the color for the entire line segment. The color has a constant intensity based upon the normal vector. * 1 = Gouraud: The colors along each line are interpolated between vertex colors. Gouraud shading may be slower than flat shading, but results in a smoother appearance. SHARE_DATA (Set) Set this keyword to an object whose data is to be shared by this polyline. A polyline may only share data with a polygon object or another polyline. The SHARE_DATA property is intended for use when data values are not set via an argument to the object's Init method or by setting the object's DATA property. SYMBOL (Get, Set) Set this keyword to a vector containing one or more instances of the IDLgrSymbol object class to indicate the plotting symbols to be used at each vertex of the polyline. If there are more vertices than elements in SYMBOL, the elements of the SYMBOL vector are cyclically repeated. By default, no symbols are drawn. To remove symbols from a polyline, set SYMBOL to a scalar. THICK (Get, Set) Set this keyword to a value between 1.0 and 10.0, specifying the line thickness to be used to draw the polyline, in points. The default is 1.0 points. UVALUE (Get, Set) Set this keyword to a value of any type. You can use this "user value" to contain any information you wish. Remember that if you set the user value equal to a pointer or object reference, you should destroy the pointer or object reference explicitly when destroying the object it is a user value of. VERT_COLORS (Get, Set) Set this keyword to a vector of colors to be used to draw at each vertex. Color is interpolated between vertices if SHADING is set to 1 (Gouraud). If there are more vertices than elements in VERT_COLORS, the elements of VERT_COLORS are cyclically repeated. By default, the polyline is drawn in the single color provided by the COLOR keyword. To remove vertex colors, set VERT_COLORS to a scalar. XCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert X coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedX = s0 + s1 * DataX Recommended values are: [(-Xmin)/(Xmax-Xmin), 1/(Xmax-Xmin)] The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double- precision floating-point. YCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert Y coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedY = s0 + s1 * DataY Recommended values are: [(-Ymin)/(Ymax-Ymin), 1/(Ymax-Ymin)] The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double- precision floating-point. ZCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert Z coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedZ = s0 + s1 * DataZ Recommended values are: [(-Zmin)/(Zmax-Zmin), 1/(Zmax-Zmin)] The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double- precision floating-point. IDLGRPOLYLINE::SETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPolyline::SetProperty The IDLgrPolylines::SetProperty procedure method sets the value of a property or group of properties for the polylines. Syntax Obj -> [IDLgrPolyline::]SetProperty Arguments None Keywords Any keyword to IDLgrPolyline::Init followed by the word "Set" can be set using IDLgrPolyline::SetProperty. IDLGRPRINTER [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPrinter A printer object represents a hardcopy graphics destination. When a printer object is created, the printer device to which it refers is the default system printer. To change the printer, utilize the printer dialogs (see "DIALOG_PRINTJOB" on page 400 and "DIALOG_PRINTERSETUP" on page 398.) Note Objects or subclasses of this type can not be saved or restored. Superclasses This class has no superclass. Subclasses This class has no subclasses. Creation See "IDLgrPrinter::Init" on page 2145. Methods Intrinsic Methods This class has the following methods: * IDLgrPrinter::Cleanup * IDLgrPrinter::Draw * IDLgrPrinter::GetContiguousPixels * IDLgrPrinter::GetFontnames * IDLgrPrinter::GetProperty * IDLgrPrinter::GetTextDimensions * IDLgrPrinter::Init * IDLgrPrinter::NewDocument * IDLgrPrinter::NewPage * IDLgrPrinter::SetProperty IDLGRPRINTER::CLEANUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPrinter::Cleanup The IDLgrPrinter::Cleanup procedure method performs all cleanup on the object. If a document is open (that is, if graphics have been draw to the printer), the document is closed and the pending graphics are sent to the current printer. Note Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass. Syntax OBJ_DESTROY, Obj or Obj -> [IDLgrPrinter::]Cleanup(Only in subclass' Cleanup method.) Arguments None Keywords None IDLGRPRINTER::DRAW [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPrinter::Draw The IDLgrPrinter::Draw procedure method draws the given picture to this graphics destination. Note Objects are drawn to the destination device in the order that they are added to the model, view, viewgroup, or scene object that contains them. Syntax Obj -> [IDLgrPrinter::]Draw [, Picture] [, VECTOR={ 0 | 1 } ] Arguments Picture The view (an instance of an IDLgrView object), viewgroup (an instance of an IDLgrViewgroup object), or scene (an instance of an IDLgrScene object) to be drawn. Keywords VECTOR Set this keyword to indicate the type of graphics primitives generated. Valid values include: 0 = Bitmap (default) 1 = Vector If VECTOR = 0 (Bitmap), the Draw method renders the scene to a buffer and then copies the buffer to the printer in bitmap format. The bitmap retains the quality of the original image. If VECTOR = 1 (Vector), the Draw method renders the scene using simple vector operations that result in a representation of the Scene that is scalable to the printer. The vector representation does not retain all the attributes of the original image. The vector representation is sent to the printer. IDLGRPRINTER::GETCONTIGUOUSPIXELS [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPrinter::GetContiguousPixels The IDLgrPrinter::GetContiguousPixels function method returns an array of long integers whose length is equal to the number of colors available in the index color mode (that is, the value of the N_COLORS property). The returned array marks contiguous pixels with the ranking of the range's size. This means that within the array, the elements in the largest available range are set to zero, the elements in the second-largest range are set to one, etc. Use this range to set an appropriate colormap for use with the SHADE_RANGE property of the IDLgrSurface and IDLgrPolygon object classes. To get the largest contiguous range, you could use the following IDL command: result = obj -> GetContiguousPixels() Range0 = WHERE(result EQ 0) A contiguous region in the colormap can be increasing or decreasing in values. The following would be considered contiguous: [0,1,2,3,4] [4,3,2,1,0] Syntax Return = Obj -> [IDLgrPrinter::]GetContiguousPixels() Arguments None Keywords None IDLGRPRINTER::GETFONTNAMES [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPrinter::GetFontnames The IDLgrPrinter::GetFontnames function method returns the list of available fonts that can be used in IDLgrFont objects. This method will only return the names of the available TrueType fonts. Hershey fonts will not be returned; see Appendix H, "Fonts" for more information. Syntax Return = Obj -> [IDLgrPrinter::]GetFontnames( FamilyName [, IDL_FONTS={0 | 1 | 2}] [, STYLES=string] ) Arguments FamilyName A string representing the name of the font family to which all of the returned fonts must belong. The string may be a fully specified family name-such as "Helvetica". You can use both "*" and "?" as wildcard characters, matching any number of characters or one character respectively. To return all available family names, use "*". Keywords IDL_FONTS Set this keyword to specify where to search for fonts that IDL may use. Set IDL_FONT to 1 to select only fonts installed by IDL and to 2 to select only fonts detected in the host operating system. The default value is 0, specifying that both IDL and operating system fonts should be returned. STYLES Set this keyword to a string specifying the styles that are to be matched by the returned font names. You can set STYLES to a fully specified style string, such as "Bold Italic". If you set STYLES to the null string, ' ', only fontnames without style modifiers will be returned. You can use both "*" and "?" as wildcard characters, matching any number of characters or one character respectively. The default value is the string, "*", which returns all fontnames containing the FamilyName argument, with or without style modifiers. IDLGRPRINTER::GETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPrinter::GetProperty The IDLgrPrinter::GetProperty procedure method retrieves the value of a property or group of properties for the printer. Syntax Obj -> [IDLgrPrinter::]GetProperty [, ALL=variable] [, DIMENSIONS=variable] [, NAME=string] [, RESOLUTION=variable] Arguments None Keywords Any keyword to IDLgrPrinter::Init followed by the word "Get" can be retrieved using IDLgrPrinter::GetProperty. In addition, the following keywords are available: ALL Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the properties associated with the state of this object. State information about the object includes things like color, range, tick direction, etc., but not image, vertex, or connectivity data, or user values. Note The fields of this structure may change in subsequent releases of IDL. DIMENSIONS Set this keyword to a named variable that will contain a two-element vector of the form [width, height] specifying the overall `drawable' area that may be printed on a page. By default, the dimensions are measured in device units (refer to the UNITS (Get, Set) keyword). NAME A string containing the operating system-specific name of the print stream. e.g. '\\BORG\HpJet'. RESOLUTION Set this keyword to a named variable that will contain a vector of the form [xres, yres] defining the pixel resolution, measured in centimeters per pixel. This value is stored in double precision. IDLGRPRINTER::GETTEXTDIMENSIONS [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPrinter::GetTextDimensions The IDLgrPrinter::GetTextDimensions function method retrieves the dimensions of a text object that will be rendered in a window. The result is a 3-element double- precision floating-point vector [xDim, yDim, zDim] representing the dimensions of the text object, measured in data units. Syntax Result = Obj ->[IDLgrPrinter::]GetTextDimensions( TextObj [, DESCENT=variable] [, PATH=objref(s)] ) Arguments TextObj The object reference to a text or axis object for which the text dimensions are requested. Keywords DESCENT Set this keyword equal to a named variable that will contain an array of double- precision floating-point values (one for each string in the IDLgrText object). The values represent the distance to travel (parallel to the UPDIR vector) from the text baseline to reach the bottom of the lowest descender in the string. All values will be negative numbers, or zero. This keyword is valid only if TextObj is an IDLgrText object. PATH Set this keyword to a single object reference or a vector of object references. This keyword specifies the path in the graphics hierarchy to compute the text dimensions. Each path object reference specified with this keyword must contain an alias. The text dimensions are computed for the version of the object falling within that path. If this keyword is not set, the PARENT properties determine the path from the current object to the top of the graphics hierarchy and no alias paths are pursued. If IDLgrPrinter::GetTextDimensions is called from within a Draw method and the PATH keyword is not set, the alias path used to find the object during the draw is used, rather than the PARENT path. Note For more information on aliases, refer to the ALIAS keyword in IDLgrModel::Add. IDLGRPRINTER::INIT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPrinter::Init The IDLgrPrinter::Init function method initializes the printer object. Note Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass. Syntax Obj = OBJ_NEW('IDLgrPrinter' [, COLOR_MODEL{Get}={0 | 1}] [, GRAPHICS_TREE{Get, Set}=objref of type IDLgrScene, IDLgrViewgroup, or IDLgrView] [, /LANDSCAPE{Get, Set}] [, N_COLORS{Get}=integer{2 to 256}] [, N_COPIES{Get, Set}=integer] [, PALETTE{Get, Set}=objref] [, PRINT_QUALITY{Get, Set}={0 | 1 | 2}] [, QUALITY{Get, Set}={0 | 1 | 2}] [, UNITS{Get, Set}={0 | 1 | 2 | 3}] [, UVALUE{Get, Set}=value] ) or Result = Obj -> [IDLgrPrinter::]Init( ) (Only in a subclass' Init method.) Note Keywords can be used in either form. They are omitted in the second form for brevity. Arguments None Keywords Properties retrievable via IDLgrPrinter::GetProperty are indicated by the word "Get" following the keyword. Properties settable via IDLgrPrinter::SetProperty are indicated by the word "Set" following the keyword. COLOR_MODEL (Get) Set this keyword to the color model to be used for the buffer: * 0 = RGB (default) * 1 = Color Index GRAPHICS_TREE (Get, Set) Set this keyword to an object reference of type IDLgrScene, IDLgrViewgroup, or IDLgrView. If this property is set to a valid object reference, calling the Draw method on the destination object with no arguments will cause the object reference associated with this property to be drawn. If this object is valid and the destination object is destroyed, this object reference will be destroyed as well. By default the GRAPHICS_TREE property is set equal to the null-object. LANDSCAPE (Get, Set) Set this keyword to produce hardcopy output in landscape mode. The default value of zero indicates Portrait mode. Note The printer driver may not support the LANDSCAPE option; in general, it is best to use the printer dialogs to set orientation. N_COLORS (Get) Set this keyword to the number of colors (between 2 and 256) to be used if the COLOR_MODEL is set to Indexed (1). This keyword is ignored if the COLOR_MODEL is set to RGB (0). N_COPIES (Get, Set) Set this keyword equal to an integer that determines the number of copies of print data to be generated. The default is 1 copy. Note Your specific printer driver may not support the N_COPIES option. You can also use the printer dialogs to set the number of copies. PALETTE (Get, Set) Set this keyword equal to the object reference of a palette object (an instance of the IDLgrPalette object class) to specify the red, green, and blue values that are to be loaded into the graphics destination's color lookup table if the Indexed color model is used. PRINT_QUALITY (Get, Set) Set this keyword to an integer value indicating the print quality at which graphics are to be drawn to the printer. Note that the print quality is independent of the rendering quality (as set by the QUALITY keyword). Valid values are: * 0 = Low * 1 = Normal (this is the default) * 2 = High Generally, setting the print quality to a lower value will increase the speed of the printing job, but decrease the resolution; setting it to a higher value will cause the printing job to take more time, but will increase the resolution. Note Some printer drivers may not be able to support different printing qualities. In these cases, the setting of the PRINT_QUALITY property will be quietly ignored. QUALITY (Get, Set) Set this keyword to an integer value indicating the rendering quality at which graphics are to be drawn to this destination. Note that the rendering quality is independent of the print quality (as set by the PRINT_QUALITY keyword). Valid values are: * 0 = Low * 1 = Medium * 2 = High (default) UNITS (Get, Set) Set this keyword to indicate the units of measure for the DIMENSIONS property. Valid values are: * 0 = Device (default) * 1 = Inches * 2 = Centimeters * 3 = Normalized: relative to the drawable area on a page. Note If you change the value of the UNITS property (using the SetProperty method), IDL will convert the current value of the DIMENSIONS property to the new units. UVALUE (Get, Set) Set this keyword to a value of any type. You can use this "user value" to contain any information you wish. Remember that if you set the user value equal to a pointer or object reference, you should destroy the pointer or object reference explicitly when destroying the object it is a user value of. IDLGRPRINTER::NEWDOCUMENT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPrinter::NewDocument The IDLgrPrinter::NewDocument procedure method closes the current document (a page or group of pages), which causes any pending output to be sent to the printer, finishing the printer job. Syntax Obj -> [IDLgrPrinter::]NewDocument Arguments None Keywords None IDLGRPRINTER::NEWPAGE [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPrinter::NewPage The IDLgrPrinter::NewPage procedure method issues a new page command to the printer. Syntax Obj -> [IDLgrPrinter::]NewPage Arguments None Keywords None IDLGRPRINTER::SETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrPrinter::SetProperty The IDLgrPrinter::SetProperty procedure method sets the value of a property or group of properties for the printer. Syntax Obj -> [IDLgrPrinter::]SetProperty Arguments None Keywords Any keyword to IDLgrPrinter::Init followed by the word "Set" can be set using IDLgrPrinter::SetProperty. IDLGRROI [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrROI The IDLgrROI object class is an object graphics representation of a region of interest. Superclasses This class is a subclass of IDLanROI. Subclasses None. Creation See IDLgrROI::Init. Methods Intrinsic Methods The IDLgrROI object class has the following methods: * IDLgrROI::Cleanup * IDLgrROI::GetProperty * IDLgrROI::Init * IDLgrROI::PickVertex * IDLgrROI::SetProperty Inherited Methods This class inherits the following methods: * IDLanROI::AppendData * IDLanROI::ComputeGeometry * IDLanROI::ComputeMask * IDLanROI::ContainsPoints * IDLanROI::RemoveData * IDLanROI::ReplaceData * IDLanROI::Rotate * IDLanROI::Scale * IDLanROI::Translate IDLGRROI::CLEANUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrROI::Cleanup The IDLgrROI::Cleanup procedure method performs all cleanup for a region of interest object. Note Cleanup methods are special life cycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass. Syntax OBJ_DESTROY, Obj or Obj­>[IDLgrROI::]Cleanup (In a subclass' Cleanup method only.) Arguments None. Keywords None. IDLGRROI::GETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrROI::GetProperty The IDLgrROI::GetProperty procedure method retrieves the value of a property or group of properties for the Object Graphics region. Syntax Obj­>[IDLgrROI::]GetProperty [, ALL=variable] [, XRANGE=variable] [, YRANGE=variable] [, ZRANGE=variable] Arguments None. Keywords Note All keywords accepted by IDLanROI::GetProperty are also accepted by this method. Furthermore, any keyword to IDLgrROI::Init followed by the word (Get) can be retrieved using IDLgrROI::GetProperty. The following keywords are also accepted: ALL Set this keyword to a named variable to contain an anonymous structure with the values of all of the properties associated with the state of this object. State information about the object may include things like color, line style, etc., but not vertex data or user values. Note The fields in this structure may change in subsequent releases of IDL. XRANGE Set this keyword equal to a named variable that will contain a two-element vector of the form [xmin, xmax] that specifies the range of x data coordinates covered by the graphic object. IDL maintains and returns this property in double-precision floating- point. YRANGE Set this keyword equal to a named variable that will contain a two-element vector of the form [ymin, ymax] that specifies the range of y data coordinates covered by the graphic object. IDL maintains and returns this property in double-precision floating- point. ZRANGE Set this keyword equal to a named variable that will contain a two-element vector of the form [zmin, zmax] that specifies the range of z data coordinates covered by the graphic object. IDL maintains and returns this property in double-precision floating- point. IDLGRROI::INIT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrROI::Init The IDLgrROI::Init function method initializes an Object Graphics region of interest. Note Init methods are special life cycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass. Syntax Obj = OBJ_NEW( 'IDLgrROI' [, X[, Y[, Z]]] [, COLOR{Get, Set}=vector] [, /DOUBLE{Get, Set}] [, /HIDE{Get, Set}] [, LINESTYLE{Get, Set}=value] [, NAME{Get, Set}=string] [, PALETTE{Get, Set}=objref] [, STYLE{Get, Set}={ 0 | 1 | 2 } ] [, SYMBOL{Get, Set}=objref] [, THICK{Get, Set}=points{1.0 to 10.0}] [, UVALUE{Get, Set}=uvalue] [, XCOORD_CONV{Get, Set}=[s0, s1] ] [, YCOORD_CONV{Get, Set}=[s0, s1] ] [, ZCOORD_CONV{Get, Set}=[s0, s1] ] ) or Result = Obj­>[IDLgrROI::]Init([X[, Y[, Z]]] ) (Only in a subclass' Init method.) Note Keywords can be used in either form. They are omitted in the second form for brevity. Arguments X A vector providing the X components of the vertices for the region. If the Y and Z arguments are not specified, X must be a two-dimensional array with the leading dimension either 2 or 3 ([2, *] or [3, *]), in which case, X[0, *] represents the X values, X[1, *] represents the Y values, and X[2, *] represents the Z values. This argument is stored as double precision floating point values if the argument variable is of type DOUBLE or if the DOUBLE property is non-zero. Otherwise it is converted and stored as single precision floating point. Y A vector providing the Y components of the vertices. This argument is stored as double precision floating point values if the argument variable is of type DOUBLE or if the DOUBLE property is non-zero. Otherwise it is converted and stored as single precision floating point. Z A scalar or vector providing the Z components of the vertices. If not provided, Z values default to 0.0. This argument is stored as double precision floating point values if the argument variable is of type DOUBLE or if the DOUBLE property is non-zero. Otherwise it is converted and stored as single precision floating point. Keywords Note All keywords accepted by IDLanROI::Init are accepted by this method as well. In addition, the following keywords are accepted: COLOR (Get, Set) Set this keyword to an RGB or indexed color for drawing the region. The default color is [0, 0, 0]. DOUBLE (Get, Set) Set this keyword to a non-zero value to indicate that data should be stored in this object in double precision floating point. Set this keyword to zero to indicate that the data should be stored in single precision floating point, which is the default. The DOUBLE property controls the precision used for storing the data in the (inherited)AppendData, Init, and (inherited)ReplaceData methods via the X, Y, and Z arguments and in SetProperty method via the (inherited)DATA keyword. IDL converts any data already stored in the object to the requested precision, if necessary. Note that this keyword does not need to be set if any of the X, Y, or Z arguments or the (inherited)DATA parameters are of type DOUBLE. However, setting this keyword may be desirable if the data consists of large integers that cannot be accurately represented in single precision floating point. This property is also automatically set to one if any of the X, Y or Z arguments or the DATA parameter is stored using a variable of type DOUBLE. HIDE (Get, Set) Set this keyword to a Boolean value indicating whether this region should be drawn: * 0 = draw the region (the default) * 1 = do not draw the region LINESTYLE (Get, Set) Set this keyword to the line style to be used to draw the region. The value can be either an integer value specifying a pre-defined line style, or a two-element vector specifying a stippling pattern. The valid values for the pre-defined line styles are: * 0 = solid (the default) * 1 = dotted * 2 = dashed * 3 = dash dot * 4 = dash dot dot dot * 5 = long dash * 6 = no line drawn NAME (Get, Set) Set this keyword to a string to use as the name for this region. PALETTE (Get, Set) Set this keyword to the object reference of a palette object (an instance of the IDLgrPalette object class). This keyword is only used for Object Graphics destinations using the RGB color model. In this case, if the color value for the region is specified as a color index value, this palette is used to look up the color for the region. If the PALETTE keyword is not set, the destination object PALETTE property is used, which defaults to a gray scale ramp. STYLE (Get, Set) Set this keyword to indicate the geometrical primitive to use to represent the region when displayed. Valid values include: * 0 = points * 1 = open polyline * 2 = closed polyline (the default) SYMBOL (Get, Set) Set this keyword to reference an IDLgrSymbol object for the symbol used for display when STYLE = 0 (points). By default, a dot is used. THICK (Get, Set) Set this keyword to a value between 1.0 and 10.0, specifying the size of the points, or the thickness of the lines, measured in points. The default is 1.0 points. UVALUE (Get, Set) Set this keyword to a user value of any type to contain any information you wish. Remember if you set this user value equal to a pointer or object reference, you must destroy the pointer or object reference explicitly when destroying this region. XCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert X coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedX = s0 + s1*DataX Recommended values are: [ (­Xmin)/(Xmax ­ Xmin), 1.0/(Xmax ­ Xmin) ] IDL converts, maintains, and returns this data as double-precision floating-point. YCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert Y coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedY = s0 + s1*DataY Recommended values are: [ (­Ymin)/(Ymax ­ Ymin), 1.0/(Ymax ­ Ymin) ] IDL converts, maintains, and returns this data as double-precision floating-point. ZCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert Z coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedZ = s0 + s1*DataZ Recommended values are: [ (­Zmin)/(Zmax ­ Zmin), 1.0/(Zmax ­ Zmin) ] IDL converts, maintains, and returns this data as double-precision floating-point. IDLGRROI::PICKVERTEX [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrROI::PickVertex The IDLgrROI::PickVertex function method picks a vertex of the region which, when projected onto the given destination device, is nearest to the given 2D device coordinate. Syntax Result = Obj­>[IDLgrROI::]PickVertex( Dest, View, Point [, PATH=objref] ) Return Value Result The return value is the index of the nearest region vertex. If two or more vertices are equally nearest to the point, the smallest index of those vertices is returned. Arguments Dest An object reference to an IDLgrWindow or IDLgrBuffer for which the pick is to occur. View An object reference to the IDLgrView containing this region. Point A two-element vector, [x, y], representing the device location used for picking a nearest vertex. Keywords PATH Set this keyword to a single object reference or a vector of object references. This keyword specifies the path in the graphics hierarchy to map the device position to a location in the data space of the region. Each path object reference specified with this keyword must contain an alias. The selected vertex is computed for the version of the object falling within the specified path. If this keyword is not set, the parent properties determine the path from the current object to the top of the graphics hierarchy and no alias paths are pursued. IDLGRROI::SETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrROI::SetProperty The IDLgrROI::SetProperty procedure method sets the value of a property or group of properties for the Object Graphics region. Syntax Obj­>[IDLgrROI::]SetProperty Arguments None. Keywords Note Any keywords accepted by IDLanROI::SetProperty are also accepted by this method. Furthermore, any keywords to IDLgrROI::Init followed by the word (Set) can be set using IDLgrROI::SetProperty as well. IDLGRROIGROUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrROIGroup The IDLgrROIGroup object class is an Object Graphics representation of a group of regions of interest. Superclasses This class is a subclass of IDLanROIGroup. Subclasses None. Creation See IDLgrROIGroup::Init. Methods Intrinsic Methods The IDLgrROIGroup class has the following methods: * IDLgrROIGroup::Add * IDLgrROIGroup::Cleanup * IDLgrROIGroup::GetProperty * IDLgrROIGroup::Init * IDLgrROIGroup::PickRegion * IDLgrROIGroup::SetProperty Inherited Methods This class inherits the following methods: * IDLanROIGroup::ContainsPoints * IDLanROIGroup::ComputeMask * IDLanROIGroup::GetProperty * IDLanROIGroup::Rotate * IDLanROIGroup::Scale * IDLanROIGroup::Translate IDLGRROIGROUP::ADD [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrROIGroup::Add The IDLgrROIGroup::Add procedure method adds a region to the region group. Only objects of the IDLgrROI class may be added to the group. The regions in the group must all be of the same type: all points, all paths, or all polygons. Syntax Obj­>[IDLgrROIGroup::]Add, ROI Arguments ROI A reference to an instance of the IDLgrROI object class representing the region of interest to add to the group. Keywords Accepts all keywords accepted by the IDLanROIGroup::Add method. IDLGRROIGROUP::CLEANUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrROIGroup::Cleanup The IDLgrROIGroup::Cleanup procedure method performs all cleanup for an Object Graphics region of interest group object. Note Cleanup methods are special life cycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass. Syntax OBJ_DESTROY, Obj or Obj­>[IDLgrROIGroup::]Cleanup (In a subclass' Cleanup method only.) Arguments None. Keywords None. IDLGRROIGROUP::GETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrROIGroup::GetProperty The IDLgrROIGroup::Get Property procedure method retrieves the value of a property or group of properties for the region group. Syntax Obj­>[IDLgrROIGroup::]GetProperty [, ALL=variable] [, PARENT=variable] [, XRANGE=variable] [, YRANGE=variable] [, ZRANGE=variable] Arguments None. Keywords Note All keywords accepted by IDLanROIGroup::GetProperty are also accepted by this method. Furthermore, any keyword to IDLgrROIGroup::Init followed by the word (Get) can be retrieved using IDLgrROIGroup::GetProperty. ALL Set this keyword to a named variable. Upon return, ALL contains an anonymous structure with the values of all of the properties associated with the state of this object. Note The fields in this structure may change in subsequent releases of IDL. PARENT Set this keyword equal to a named variable that will contain an object reference to the object that contains this object. XRANGE Set this keyword equal to a named variable that will contain a two-element vector of the form [xmin, xmax] that specifies the range of x data coordinates covered by the graphic object. IDL maintains and returns this property in double-precision floating- point. YRANGE Set this keyword equal to a named variable that will contain a two-element vector of the form [ymin, ymax] that specifies the range of y data coordinates covered by the graphic object. IDL maintains and returns this property in double-precision floating- point. ZRANGE Set this keyword equal to a named variable that will contain a two-element vector of the form [zmin, zmax] that specifies the range of z data coordinates covered by the graphic object. IDL maintains and returns this property in double-precision floating- point. IDLGRROIGROUP::INIT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrROIGroup::Init The IDLgrROIGroup::Init function method initializes an Object Graphics region of interest group object. Note Init methods are special life cycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass. Syntax Obj = OBJ_NEW('IDLgrROIGroup' [, COLOR{Get, Set}=vector] [, /HIDE{Get, Set}] [, NAME{Get, Set}=string] [, XCOORD_CONV{Get, Set}=[s0, s1] ] [, YCOORD_CONV{Get, Set}=[s0, s1] ] [, ZCOORD_CONV{Get, Set}=[s0, s1] ] ) or Result = Obj­>[IDLgrROIGroup::]Init( ) (Only in a subclass' Init method.) Note Keywords can be used in either form. They are omitted in the second form for brevity. Arguments None. Keywords COLOR (Get, Set) Set this keyword to an RGB or indexed color for drawing the region group. The default color is [0,0,0]. HIDE (Get, Set) Set this keyword to a Boolean value indicating whether this region group should be drawn: * 0 = draw the region group (the default) * 1 = do not draw the region group NAME (Get, Set) Set this keyword to a string to use as the name for this region group. XCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert X coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedX = s0 + s1*DataX Recommended values are: [ (­Xmin)/(Xmax ­ Xmin), 1.0/(Xmax ­ Xmin) ] IDL converts, maintains, and returns this data as double-precision floating-point. YCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert Y coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedY = s0 + s1*DataY Recommended values are: [ (­Ymin)/(Ymax ­ Ymin), 1.0/(Ymax ­ Ymin) ] IDL converts, maintains, and returns this data as double-precision floating-point. ZCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert Z coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedZ = s0 + s1*DataZ Recommended values are: [ (­Zmin)/(Zmax ­ Zmin), 1.0/(Zmax ­ Zmin) ] IDL converts, maintains, and returns this data as double-precision floating-point. IDLGRROIGROUP::PICKREGION [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrROIGroup::PickRegion The IDLgrROIGroup::PickRegion function method picks a region within the group which, when projected onto the given destination device, is nearest to the given 2D device coordinate. Syntax Result = Obj­>[IDLgrROIGroup::]PickRegion( Dest, View, Point [, PATH=objref] ) Return Value Result The return value is the object reference of the nearest region. If two or more regions are equally nearest to the point, the one that was added to the region group first is returned. Arguments Dest An object reference to an IDLgrWindow or IDLgrBuffer for which the pick is to occur. View An object reference to the IDLgrView containing this region. Point A two-element vector, [x, y], representing the device location to use for picking a nearest region. Keywords PATH Set this keyword to a single object reference or a vector of object references. This keyword specifies the path in the graphics hierarchy to map the device position to a location in the data space of the region. Each path object reference specified with this keyword must contain an alias. The selected region is computed for the version of the object falling within the specified path. If this keyword is not set, the parent properties determine the path from the current object to the top of the graphics hierarchy and no alias paths are pursued. IDLGRROIGROUP::SETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrROIGroup::SetProperty The IDLgrROIGroup::Set Property procedure method sets the value of a property or group of properties for the region group. Syntax Obj­>[IDLgrROIGroup::]SetProperty Arguments None. Keywords Note Any keywords to IDLgrROIGroup::Init followed by the word (Set) can be set using IDLgrROIGroup::SetProperty. IDLGRSCENE [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrScene A scene object represents the entire scene to be drawn and serves as a container of IDLgrView or IDLgrViewgroup objects. Superclasses This class is a subclass of IDL_Container. Subclasses This class has no subclasses. Creation See "IDLgrScene::Init" on page 2179. Methods Intrinsic Methods This class has the following methods: * IDLgrScene::Add * IDLgrScene::Cleanup * IDLgrScene::GetByName * IDLgrScene::GetProperty * IDLgrScene::Init * IDLgrScene::SetProperty Inherited Methods This class inherits the following methods: * IDL_Container::Count * IDL_Container::Get * IDL_Container::IsContained * IDL_Container::Move IDLGRSCENE::ADD [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrScene::Add The IDLgrScene::Add function method verifies that the added item is an instance of an IDLgrView or IDLgrViewgroup object. If it is, IDLgrScene:Add adds the view or viewgroup to the specified scene. Syntax Obj -> [IDLgrScene::]Add, View [, POSITION=index] Arguments View An instance of the IDLgrView or IDLgrViewgroup object class. Keywords POSITION Set this keyword equal to the zero-based index of the position within the container at which the new object should be placed. IDLGRSCENE::CLEANUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrScene::Cleanup The IDLgrScene::Cleanup procedure method performs all cleanup on the object. Note Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass. Syntax OBJ_DESTROY, Obj or Obj -> [IDLgrScene::]Cleanup(Only in subclass' Cleanup method.) Arguments None Keywords None IDLGRSCENE::GETBYNAME [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrScene::GetByName The IDLgrScene::GetByName function method finds contained objects by name and returns the object reference to the named object. If the named object is not found, the GetByName function returns a null object reference. Note The GetByName function does not perform a recursive search through the object hierarchy. If a fully qualified object name is not specified, only the contents of the current container object are inspected for the named object. Syntax Result = Obj -> [IDLgrScene::]GetByName(Name) Arguments Name A string containing the name of the object to be returned. Object naming syntax is very much like the syntax of a UNIX filesystem. Objects contained by other objects can include the name of their parent object; this allows you to create a fully qualified name specification. For example, if object1 contains object2, which in turn contains object3, the string specifying the fully qualified object name of object3 would be 'object1/object2/object3'. Object names are specified relative to the object on which the GetByName method is called. If used at the beginning of the name string, the / character represents the top of an object hierarchy. The string '..' represents the object one level "up" in the hierarchy. Keywords None IDLGRSCENE::GETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrScene::GetProperty The IDLgrScene::GetProperty procedure method retrieves the value of a property or group of properties for the contour. Syntax Obj -> [IDLgrScene::]GetProperty [, ALL=variable] Keywords Any keyword to IDLgrScene::Init followed by the word "Get" can be retrieved using IDLgrScene::GetProperty. In addition, the following keywords are available: ALL Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the properties associated with the state of this object. State information about the object includes things like color, range, tick direction, etc., but not image, vertex, or connectivity data, or user values. Note The fields of this structure may change in subsequent releases of IDL. IDLGRSCENE::INIT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrScene::Init The IDLgrScene::Init function method initializes the scene object. Note Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass. Syntax Obj = OBJ_NEW('IDLgrScene' [, COLOR{Get, Set}=index or RGB vector] [, /HIDE{Get, Set}] [, NAME{Get, Set}=string] [, /TRANSPARENT{Get, Set}] [, UVALUE{Get, Set}=value] ) or Result = Obj -> [IDLgrScene::]Init( ) (Only in a subclass' Init method.) Note Keywords can be used in either form. They are omitted in the second form for brevity. Arguments None Keywords Properties retrievable via IDLgrScene::GetProperty are indicated by the word "Get" following the keyword. Properties settable via IDLgrScene::SetProperty are indicated by the word "Set" following the keyword. HIDE Set this keyword to a boolean value indicating whether this object should be drawn: * 0 = Draw graphic (the default) * 1 = Do not draw graphic COLOR (Get, Set) Set this keyword to the color to which the scene should be erased before drawing. The color may be specified as a color lookup table index or an RGB vector. NAME Set this keyword equal to a string containing the name associated with this object. The default is the null string, ' '. TRANSPARENT (Get, Set) Set this keyword to disable window clearing. If this keyword is not set, the destination object in use by the scene is automatically erased when the scene is initialized. UVALUE (Get, Set) Set this keyword to a value of any type. You can use this "user value" to contain any information you wish. Remember that if you set the user value equal to a pointer or object reference, you should destroy the pointer or object reference explicitly when destroying the object it is a user value of. IDLGRSCENE::SETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrScene::SetProperty The IDLgrScene::SetProperty procedure method sets the value of a property or group of properties for the buffer. Syntax Obj -> [IDLgrScene::]SetProperty Arguments None Keywords Any keyword to IDLgrScene::Init followed by the word "Set" can be set using IDLgrScene::SetProperty. IDLGRSURFACE [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrSurface A surface object represents a shaded or vector representation of a mesh grid. An IDLgrSurface object is an atomic graphic object; it is one of the basic drawable elements of the IDL Object Graphics system, and it is not a container for other objects. Superclasses This class has no superclasses. Subclasses This class has no subclasses. Creation See "IDLgrSurface::Init" on page 2188. Methods Intrinsic Methods This class has the following methods: * IDLgrSurface::Cleanup * IDLgrSurface::GetCTM * IDLgrSurface::GetProperty * IDLgrSurface::Init * IDLgrSurface::SetProperty IDLGRSURFACE::CLEANUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrSurface::Cleanup The IDLgrSurface::Cleanup procedure method performs all cleanup on the object. Note Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass. Syntax OBJ_DESTROY, Obj or Obj -> [IDLgrSurface::]Cleanup(Only in subclass' Cleanup method.) Arguments None Keywords None IDLGRSURFACE::GETCTM [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrSurface::GetCTM The IDLgrSurface::GetCTM function method returns the 4 x 4 double-precision floating-point graphics transform matrix from the current object upward through the graphics tree. Syntax Result = Obj -> [IDLgrSurface::]GetCTM( [, DESTINATION=objref] [, PATH=objref(s)] [, TOP=objref to IDLgrModel object] ) Arguments None Keywords DESTINATION Set this keyword to the object reference of a destination object to specify that the projection matrix for the View object in the current tree be included in the returned transformation matrix. The resulting matrix will transform a point in the data space of the object on which the GetCTM method is called into a normalized coordinate system (-1 to +1 in X, Y, and Z), relative to the View object that contains the surface object. PATH Set this keyword to a single object reference or a vector of object references. This keyword specifies the path in the graphics hierarchy to compute the transformation matrix. Each path object reference specified with this keyword must contain an alias. The transformation matrix is computed for the version of the object falling within that path. If this keyword is not set, the PARENT properties determine the path from the current object to the top of the graphics hierarchy and no alias paths are pursued. If IDLgrSurface::GetCTM is called from within a Draw method, with the DESTINATION keyword set and the PATH keyword not set, the alias path used to find the object during the draw is used, rather than the PARENT path. Note For more information on aliases, refer to the ALIAS keyword in IDLgrModel::Add. TOP Set this keyword equal to the object reference to an IDLgrModel object to specify that the returned matrix accumulate from the object on which the GetCTM method is called up to but not including the specified model object. IDLGRSURFACE::GETPROPERTY[1] [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrSurface::GetProperty The IDLgrSurface::GetProperty procedure method retrieves the value of a property or group of properties for the surface. Syntax Obj -> [IDLgrSurface::]GetProperty [, ALL=variable] [, DATA=variable] [, PARENT=variable] [, XRANGE=variable] [, YRANGE=variable] [, ZRANGE=variable] Arguments None Keywords Any keyword to IDLgrSurface::Init followed by the word "Get" can be retrieved using IDLgrSurface::GetProperty. In addition, the following keywords are available: ALL Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the properties associated with the state of this object. State information about the object includes things like color, range, tick direction, etc., but not image, vertex, or connectivity data, or user values. Note The fields of this structure may change in subsequent releases of IDL. DATA Set this keyword to a named variable that upon return will contain the surface data. PARENT Set this keyword equal to a named variable that will contain an object reference to the object that contains this object. XRANGE Set this keyword equal to a named variable that will contain a two-element vector of the form [xmin, xmax] that specifies the range of x data coordinates covered by the graphic object. IDL maintains and returns this property in double-precision floating- point. YRANGE Set this keyword equal to a named variable that will contain a two-element vector of the form [ymin, ymax] that specifies the range of y data coordinates covered by the graphic object. IDL maintains and returns this property in double-precision floating- point. ZRANGE Set this keyword equal to a named variable that will contain a two-element vector of the form [zmin, zmax] that specifies the range of z data coordinates covered by the graphic object. IDL maintains and returns this property in double-precision floating- point. IDLGRSURFACE::INIT[1] [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrSurface::Init The IDLgrSurface::Init function method initializes the surface object. Note Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass. Syntax Obj = OBJ_NEW('IDLgrSurface' [, Z [, X, Y]] [, BOTTOM{Get, Set}=index or RGB vector] [, COLOR{Get, Set}=index or RGB vector] [, DATAX{Set}=vector or 2D array] [, DATAY{Set}=vector or 2D array] [, DATAZ{Set}=2D array] [, /DOUBLE{Get, Set}] [, /EXTENDED_LEGO{Get, Set}] [, /HIDDEN_LINES{Get, Set}] [, /HIDE{Get, Set}] [, LINESTYLE{Get, Set}=value] [, MAX_VALUE{Get, Set}=value] [, MIN_VALUE{Get, Set}=value] [, NAME{Get, Set}=string] [, PALETTE{Get, Set}=objref] [, /RESET_DATA{Set}] [, SHADE_RANGE{Get, Set}=[index of darkest pixel, index of brightest pixel]] [, SHADING{Get, Set}={0 | 1}] [, SHARE_DATA{Set}=objref] [, /SHOW_SKIRT{Get, Set}] [, SKIRT{Get, Set}=Z value] [, STYLE{Get, Set}={0 | 1 | 2 | 3 | 4 | 5 | 6}] [, TEXTURE_COORD{Get, Set}=array] [, /TEXTURE_INTERP{Get, Set}] [, TEXTURE_MAP{Get, Set}=objref to IDLgrImage] [, THICK{Get, Set}=points{1.0 to 10.0}] [, UVALUE{Get, Set}=value] [, /USE_TRIANGLES{Get, Set}] [, VERT_COLORS{Get, Set}=vector] [, XCOORD_CONV{Get, Set}=vector] [, YCOORD_CONV{Get, Set}=vector] [, ZCOORD_CONV{Get, Set}=vector] [, ZERO_OPACITY_SKIP{Get, Set}={0 | 1}] ) or Result = Obj -> [IDLgrSurface::]Init( [Z [, X, Y]] ) (Only in a subclass' Init method.) Note Keywords can be used in either form. They are omitted in the second form for brevity. Arguments X A vector or two-dimensional array specifying the X coordinates of the grid. If this argument is a vector, each element of X specifies the X coordinates for a column of Z (e.g., X[0] specifies the X coordinate for Z[0, *]). If X is a two-dimensional array, each element of X specifies the X coordinate of the corresponding point in Z (Xij specifies the X coordinate of Zij). This argument is stored as double precision floating point values if the argument variable is of type DOUBLE or if the DOUBLE property is non-zero, otherwise it is stored as single precision floating point. Y A vector or two-dimensional array specifying the Y coordinates of the grid. If this argument is a vector, each element of Y specifies the Y coordinates for a column of Z (e.g., Y[0] specifies the Y coordinate 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 coordinate of Zij). This argument is stored as double precision floating point values if the argument variable is of type DOUBLE or if the DOUBLE property is non-zero, otherwise it is stored as single precision floating point. Z The two-dimensional array to be displayed. If X and Y are provided, the surface is defined as a function of the (X, Y) locations specified by their contents. Otherwise, the surface is generated as a function of the array indices of each element of Z. This argument is stored as double precision floating point values if the argument variable is of type DOUBLE or if the DOUBLE property is non-zero, otherwise it is stored as single precision floating point. Keywords Properties retrievable via IDLgrSurface::GetProperty are indicated by the word "Get" following the keyword. Properties settable via IDLgrSurface::SetProperty are indicated by the word "Set" following the keyword. BOTTOM (Get, Set) The color value used to draw the bottom surface. If not specified, or set to a negative scalar value, the bottom is drawn with the same color as the top. Setting a bottom color is only supported when the destination device uses RGB color mode. COLOR (Get, Set) Set this keyword to the color to be used as the foreground color for this model. The color may be specified as a color lookup table index or as an RGB vector. The default is [0, 0, 0]. DATAX (Set) Set this keyword to a vector or a two-dimensional array specifying the X coordinates of the surface grid. This keyword is the same as the X argument described above. This property is stored as double precision floating point values if the property is of type DOUBLE or if the DOUBLE property is non-zero, otherwise it is stored as single precision floating point. DATAY (Set) Set this keyword to a vector or a two-dimensional array specifying the Y coordinates of the surface grid. This keyword is the same as the Y argument described above. This property is stored as double precision floating point values if the property is of type DOUBLE or if the DOUBLE property is non-zero, otherwise it is stored as single precision floating point. DATAZ (Set) Set this keyword to the two-dimensional array to display as a surface. This keyword is the same as the Z argument described above. This property is stored as double precision floating point values if the property is of type DOUBLE or if the DOUBLE property is non-zero, otherwise it is stored as single precision floating point. DOUBLE (Get, Set) Set this keyword to a non-zero value to indicate that data provided by any of the X, Y, or Z arguments or DATAX, DATAY, or DATAZ keywords should be stored in this object in double precision floating point. Set this keyword to zero to indicate that the data should be stored in single precision floating point, which is the default. IDL converts any value data already stored in the object to the requested precision, if necessary. Note that this keyword does not need to be set if any of the X, Y, or Z arguments or the DATAX, DATAY, or DATAZ parameters are of type DOUBLE. However, setting this keyword may be desirable if the data consists of large integers that cannot be accurately represented in single precision floating point. This property is also automatically set to one if any of the X, Y or Z arguments or the DATAX, DATAY, or DATAZ parameters is stored using a variable of type DOUBLE. EXTENDED_LEGO (Get, Set) Set this keyword to force the IDLgrSurface object to display the last row and column of data when lego display styles are selected. HIDDEN_LINES (Get, Set) Set this keyword to draw point and wireframe surfaces using hidden line (point) removal. By default, hidden line removal is disabled. HIDE (Get, Set) Set this keyword to a boolean value indicating whether this object should be drawn: * 0 = Draw graphic (the default) * 1 = Do not draw graphic LINESTYLE (Get, Set) Set this keyword to indicate the line style that should be used to draw the surface lines. The value can be either an integer value specifying a pre-defined line style, or a two-element vector specifying a stippling pattern. To use a pre-defined line style, set the LINESTYLE property equal to one of the following integer values: * 0 = Solid line (the default) * 1 = dotted * 2 = dashed * 3 = dash dot * 4 = dash dot dot dot * 5 = long dash * 6 = no line drawn To define your own stippling pattern, specify a two-element vector [repeat, bitmask], where repeat indicates the number of times consecutive runs of 1's or 0's in the bitmask should be repeated. (That is, if three consecutive 0's appear in the bitmask and the value of repeat is 2, then the line that is drawn will have six consecutive bits turned off.) The value of repeat must be in the range 1 repeat 255. The bitmask indicates which pixels are drawn and which are not along the length of the line. Bitmask is most conveniently specified as a 16-bit hexadecimal value. For example, LINESTYLE = [2, 'F0F0'X] describes a dashed line (8 bits on, 8 bits off, 8 bits on, 8 bits off). MAX_VALUE (Get, Set) The maximum value to be plotted. If this keyword is present, data values greater than the value of MAX_VALUE are treated as missing data and are not plotted. Note that the IEEE floating-point value NaN is also treated as missing data. IDL converts, maintains, and returns this data as double-precision floating-point. MIN_VALUE (Get, Set) The minimum value to be plotted. If this keyword is present, data values less than the value of MIN_VALUE are treated as missing data and are not plotted. Note that the IEEE floating-point value NaN is also treated as missing data. IDL converts, maintains, and returns this data as double-precision floating-point. NAME (Get, Set) Set this keyword equal to a string containing the name associated with this object. The default is the null string, ' '. PALETTE (Get, Set) Set this keyword equal to the object reference of a palette object (an instance of the IDLgrPalette object class). This keyword is only used if the destination device is using the RGB color model. If so, and a color value for the object is specified as a color index value, the palette set by this keyword is used to translate the color to RGB space. If the PALETTE property on this object is not set, the destination object PALETTE property is used (which defaults to a grayscale ramp). RESET_DATA (Set) Set this keyword to treat the data provided via one of the DATA[XYZ] properties as a new data set unique to this object, rather than overwriting data that is shared by other objects. There is no reason to use this keyword if the object on which the property is being set does not currently share data with another object (that is, if the SHARE_DATA property is not in use). This keyword has no effect if no new data is provided via a DATA property. SHADE_RANGE (Get, Set) Set this keyword to a two-element array that specifies the range of pixel values (color indices) to use for shading. The first element is the color index for the darkest pixel. The second element is the color element for the brightest pixel. This value is ignored when the polygons are drawn to a graphics destination that uses the RGB color model. SHADING (Get, Set) Set this keyword to an integer representing the type of shading to use if STYLE is set to 2 (Filled) or 6 (LegoFilled). * 0 = Flat (default): The color has a constant intensity for each face of the surface, based on the normal vector. * 1 = Gouraud: The colors are interpolated between vertices, and then along scanlines from each of the edge intensities. Gouraud shading may be slower than flat shading, but results in a smoother appearance. SHARE_DATA (Set) Set this keyword to an object whose data is to be shared by this surface. A surface may only share data with another surface. The SHARE_DATA property is intended for use when data values are not set via an argument to the object's Init method or by setting the object's DATA property. SHOW_SKIRT (Get, Set) Set this keyword to enable skirt drawing. The default is to disable skirt drawing. SKIRT (Get, Set) Set this keyword to the Z value at which a skirt is to be defined around the array. The Z value is expressed in data units; the default is 0.0. If a skirt is defined, each point on the four edges of the surface is connected to a point on the skirt which has the given Z value, and the same X and Y values as the edge point. In addition, each point on the skirt is connected to its neighbor. The skirt value is ignored if skirt drawing is disabled (see SHOW_SKIRT above). IDL converts, maintains, and returns this data as double-precision floating-point. STYLE (Get, Set) Set this keyword to and integer value that indicates the style to be used to draw the surface. Valid values are: * 0 = Points * 1 = Wire mesh (the default) * 2 = Filled * 3 = RuledXZ * 4 = RuledYZ * 5 = Lego * 6 = LegoFilled: for outline or shaded and stacked histogram-style plots. TEXTURE_COORD (Get, Set) A 2 x n array of surface coordinate-texturemap coordinate pairs [s, t] at each vertex., containing the fill pattern array subscripts of each of the n polygon vertices. Use this keyword in conjunction with the TEXTURE_MAP keyword to warp images over the surface. To stretch (or shrink) the texture map to cover the surface mesh completely, set TEXTURE_COORD to a scalar. By default, TEXTURE_COORD is set equal to [0.0, 0.0] to [1.0, 1.0] over the surface bounds. Texture coordinates are normalized. This means that the m x n image object specified via the TEXTURE_MAP property is mapped into the range [0.0, 0.0] to [1.0, 1.0]. If texture coordinates outside the range [0.0, 0.0] to [1.0, 1.0] are specified, the image object is tiled into the larger range. For example, suppose the image object specified via TEXTURE_MAP is a 256 x 256 array, and we want to map the image into a square two units on each side. To completely fill the square with a single copy of the image: TEXTURE_COORD = [[0,0], [1,0], [1,1], [0,1]] To fill the square with four tiled copies of the image: TEXTURE_COORD = [[0,0], [2,0], [2,2], [0,2]] TEXTURE_INTERP (Get, Set) Set this keyword to a nonzero value to indicate that bilinear sampling is to be used with texture mapping. The default method is nearest-neighbor sampling. TEXTURE_MAP (Get, Set) Set this keyword to an instance of the IDLgrImage object class to be texture mapped onto the surface. If this keyword is omitted or set to a null object reference, no texture map is applied and the surface is filled with the color specified by the COLOR or VERT_COLORS property. If both TEXTURE_MAP and COLORS or VERT_COLORS properties exist, the color of the texture is modulated by the base color of the object. (This means that for the clearest display of the texture image, the COLOR property should be set equal to [255,255,255].) By default, the texture map will be stretched (or shrunk) to cover the surface mesh completely. Setting TEXTURE_MAP to the object reference of an IDLgrImage that contains an Alpha channel allows you to create a transparent IDLgrSurface object. For more on the Alpha channel, see "Image Objects" in Chapter 25 of Using IDL. If the width and/or height of the provided image is not an exact power of two, then the texture map will consist of the given image pixel values resampled to the nearest larger dimensions that are exact powers of two. Note Texture mapping is disabled when rendering to a destination object that uses Indexed color mode. THICK (Get, Set) Set this keyword to a value between 1.0 and 10.0, specifying the line thickness to use to draw surface lines, in points. The default is 1.0 points. UVALUE (Get, Set) Set this keyword to a value of any type. You can use this "user value" to contain any information you wish. Remember that if you set the user value equal to a pointer or object reference, you should destroy the pointer or object reference explicitly when destroying the object of which it is a user value. USE_TRIANGLES (Get, Set) Set this keyword to force the IDLgrSurface object to use triangles instead of quads to draw the surface and skirt. VERT_COLORS (Get, Set) Set this keyword to a vector of colors to be used to draw at each vertex. Color is interpolated between vertices if SHADING is set to 1 (Gouraud). If there are more vertices than elements in VERT_COLORS, the elements of VERT_COLORS are cyclically repeated. By default, the polygons are all drawn in the single color provided by the COLOR keyword. If this keyword is omitted or set to a scalar, vertex colors are removed and the surface is drawn in the color specified by the COLOR keyword. Note If the surface object is being rendered on a destination device that uses the Indexed color model, and the view that contains the surface also contains one or more light objects, the VERT_COLORS property is ignored and the SHADE_RANGE property is used instead. XCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert X coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedX = s0 + s1 * DataX Recommended values are: [(-Xmin)/(Xmax-Xmin), 1/(Xmax-Xmin)] The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double- precision floating-point. YCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert Y coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedY = s0 + s1 * DataY Recommended values are: [(-Ymin)/(Ymax-Ymin), 1/(Ymax-Ymin)] The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double- precision floating-point. ZCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert Z coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedZ = s0 + s1 * DataZ Recommended values are: [(-Zmin)/(Zmax-Zmin), 1/(Zmax-Zmin)] The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double- precision floating-point. ZERO_OPACITY_SKIP (Get, Set) Set this keyword to gain finer control over the rendering of textured surface pixels (texels) with an opacity of 0 in the texture map. Texels with zero opacity do not affect the color of a screen pixel since they have no opacity. If this keyword is set to 1, any texels are "skipped" and not rendered at all. If this keyword is set to zero, the Z- buffer is updated for these pixels and the display image is not affected as noted above. By updating the Z-buffer without updating the display image, the surface can be used as a clipping surface for other graphics primitives drawn after the current graphics object. The default value for this keyword is 1. Note This keyword has no effect if no texture map is used or if the texture map in use does not contain an opacity channel. IDLGRSURFACE::SETPROPERTY[1] [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrSurface::SetProperty The IDLgrSurface::SetProperty procedure method sets the value of a property or group of properties for the surface. Syntax Obj -> [IDLgrSurface::]SetProperty Arguments None Keywords Any keyword to IDLgrSurface::Init followed by the word "Set" can be set using IDLgrSurface::SetProperty. IDLGRSYMBOL [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrSymbol A symbol object represents a graphical element that is plotted relative to a particular position. Note Seven predefined symbols are provided by IDL. Superclasses This class has no superclass. Subclasses This class has no subclasses. Creation See "IDLgrSymbol::Init" on page 2202. Methods Intrinsic Methods This class has the following methods: * IDLgrSymbol::Cleanup * IDLgrSymbol::GetProperty * IDLgrSymbol::Init * IDLgrSymbol::SetProperty IDLGRSYMBOL::CLEANUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrSymbol::Cleanup The IDLgrSymbol::Cleanup procedure method performs all cleanup on the object. Note Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass. Syntax OBJ_DESTROY, Obj or Obj -> [IDLgrSymbol::]Cleanup(Only in subclass' Cleanup method.) Arguments None Keywords None IDLGRSYMBOL::GETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrSymbol::GetProperty The IDLgrSymbol::GetProperty procedure method retrieves the value of a property or group of properties for the symbol. Syntax Obj -> [IDLgrSymbol::]GetProperty [, ALL=variable] Arguments None Keywords Any keyword to IDLgrSymbol::Init followed by the word "Get" can be retrieved using IDLgrSymbol::GetProperty. In addition, the following keywords are available: ALL Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the properties associated with the state of this object. State information about the object includes things like color, range, tick direction, etc., but not image, vertex, or connectivity data, or user values. Note The fields of this structure may change in subsequent releases of IDL. IDLGRSYMBOL::INIT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrSymbol::Init The IDLgrSymbol::Init function method initializes the plot symbol. Note Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass. Syntax Obj = OBJ_NEW('IDLgrSymbol' [, Data] [, COLOR{Get, Set}=index or RGB vector] [, DATA{Get, Set}=integer or objref] [, NAME{Get, Set}=string] [, SIZE{Get, Set}=vector] [, THICK{Get, Set}=points{1.0 to 10.0}] [, UVALUE{Get, Set}=value] ) or Result = Obj -> [IDLgrSymbol::]Init( [Data] ) (Only in a subclass' Init method.) Note Keywords can be used in either form. They are omitted in the second form for brevity. Arguments Data Either an integer value from the list shown below, or an object reference to either an IDLgrModel object or atomic graphic object. Use one of the following scalar-represented internal default symbols: * 0 = No symbol * 1 = Plus sign, `+' (default) * 2 = Asterisk * 3 = Period (Dot) * 4 = Diamond * 5 = Triangle * 6 = Square * 7 = X If an instance of the IDLgrModel object class or an atomic graphic object is used, the object tree is used as the symbol. For best results, the object should fill the domain from -1 to +1 in all dimensions. The pre-defined symbols listed above are all defined in the domain -1 to +1. Keywords Properties retrievable via IDLgrSymbol::GetProperty are indicated by the word "Get" following the keyword. Properties settable via IDLgrSymbol::SetProperty are indicated by the word "Set" following the keyword. COLOR (Get, Set) Set this keyword to the color used to draw the symbol. The color may be specified as a color lookup table index or as an RGB vector. The default color is the color of the object for which this symbol is being used. DATA (Get, Set) Set this keyword to specify a symbol. This keyword is equivalent to the Data argument. NAME (Get, Set) Set this keyword equal to a string containing the name associated with this object. The default is the null string, ' '. SIZE (Get, Set) Set this keyword to a one-, two-, or three-element vector describing the X, Y, and Z scaling factors to be applied to the symbol. The default is [1.0, 1.0, 1.0]. * If SIZE is specified as a scalar, then the X, Y, and Z scale factors are all equal to the scalar value. * If SIZE is specified as a 2-element vector, then the X and Y scale factors are as specified by the vector, and the Z scale factor is 1.0. * If SIZE is specified as a 3-element vector, then the X, Y, and Z scale factors are as specified by the vector. IDL converts, maintains, and returns this data as double-precision floating-point. THICK (Get, Set) Set this keyword to a value between 1.0 and 10.0, specifying the line thickness to used to draw any lines that make up the symbol, in points. The default is 1.0 points. UVALUE (Get, Set) Set this keyword to a value of any type. You can use this "user value" to contain any information you wish. Remember that if you set the user value equal to a pointer or object reference, you should destroy the pointer or object reference explicitly when destroying the object it is a user value of. IDLGRSYMBOL::SETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrSymbol::SetProperty The IDLgrSymbol::SetProperty procedure method sets the value of a property or group of properties for the symbol. Syntax Obj -> [IDLgrSymbol::]SetProperty Arguments None Keywords Any keyword to IDLgrSymbol::Init followed by the word "Set" can be set using IDLgrSymbol::SetProperty. IDLGRTESSELLATOR [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrTessellator A tessellator object converts a simple concave polygon (or a simple polygon with "holes") into a number of simple convex polygons (general triangles). A polygon is simple if it includes no duplicate vertices, if the edges intersect only at vertices, and exactly two edges meet at any vertex. Each polygon can be marked as being either an interior or an exterior (default) polygon. Interior polygons are treated as holes in the exterior polygons. Multiple non-overlapping exterior polygons are allowed as well. All polygons should be specified in the same orientation (either clockwise or counter-clockwise). Once all the polygons have been passed into the tessellator object, the final triangulation is accomplished by the IDLgrTessellator::Tessellate method. A list of vertices and a connectivity array are returned. You may process these by hand, or pass them to an IDLgrPolygon object. The tessellator object will not create any vertices in the process, rather the output vertex list will include only those vertices passed into the object originally. Superclasses This class has no superclasses. Subclasses This class has no subclasses. Creation See "IDLgrTessellator::Init" on page 2210. Methods Intrinsic Methods This class has the following methods: * IDLgrTessellator::AddPolygon * IDLgrTessellator::Cleanup * IDLgrTessellator::Init * IDLgrTessellator::Reset * IDLgrTessellator::Tessellate IDLGRTESSELLATOR::ADDPOLYGON [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrTessellator::AddPolygon The IDLgrTessellator::AddPolygon procedure method adds a polygon to the tessellator object. Syntax Obj -> [IDLgrTessellator::]AddPolygon, X [, Y[, Z]] [, POLYGON{Get, Set}=array of polygon descriptions] [, /INTERIOR] Arguments X A 1 x n, 2 x n, or 3 x n array of polygon vertices. Y A vector of Y values. If X and Y are both specified, they must be one-dimensional vectors of the same length. Z A vector of Z values. If X, Y, and Z are all specified, they must all three be one- dimensional vectors of the same length. If no Z values are specified, the Z value for the polygon is set to 0. Keywords POLYGON (Get, Set) Set this keyword to an array of polygon descriptions. A polygon description is an integer or longword array of the form: [n, i0, i1, ..., in-1], where n is the number of vertices that define the polygon, and i0..in-1 are indices into the X, Y, and Z arguments that represent the polygon vertices. To ignore an entry in the POLYGON array, set the vertex count, n, to 0. To end the drawing list, even if additional array space is available, set n to -1. If this keyword is not specified, a single polygon will be generated. Note The connectivity array described by POLYGONS allows you to add multiple polygons to the tessellator object with a single AddPolygon operation. INTERIOR Set this keyword to set a polygon to be an interior polygon, which is treated as a hole in the exterior polygons. IDLGRTESSELLATOR::CLEANUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrTessellator::Cleanup The IDLgrTessellator::Cleanup procedure method performs all cleanup on the object. Note Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass. Syntax OBJ_DESTROY,Obj or Obj -> [IDLgrTessellator::]Cleanup(Only in subclass' Cleanup method.) Arguments None Keywords None IDLGRTESSELLATOR::INIT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrTessellator::Init The IDLgrTessellator::Init function method initializes the tessellator object. Note Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass. Syntax Obj = OBJ_NEW('IDLgrTesselator') or Result = Obj -> [IDLgrTessellator::]Init( ) (Only in a subclass' Init method.) Arguments None Keywords None IDLGRTESSELLATOR::RESET [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrTessellator::Reset The IDLgrTessellator::Reset procedure method resets the object's internal state. All previously added polygons are removed from memory and the object is prepared for a new tessellation task. Syntax Obj -> [IDLgrTessellator::]Reset Arguments None Keywords None IDLGRTESSELLATOR::TESSELLATE [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrTessellator::Tessellate The IDLgrTessellator::Tessellate function method performs the actual tessellation. Syntax Result = Obj -> [IDLgrTessellator::]Tessellate( Vertices, Poly [, /QUIET] ) Arguments If the tessellation succeeds, IDLgrTessellator::Tessellate returns 1 and the contents of Vertices and Poly are set to the results of the tessellation. If the tessellation fails, the function returns 0. Vertices A 2 x n array if all the input polygons were 2D. A 3 x n array if all the input polygons were 3D. Poly An array of polygon descriptions. A polygon description is an integer or longword array of the form: [n, i0, i1, ..., in-1], where n is the number of vertices that define the polygon, and i0..in-1 are indices into the X, Y, and Z arguments that represent the polygon vertices. Note On output, the Vertices array can be used as the value of the DATA property, and the Poly array can be used as the value of the POLYGON property, of a polygon object. Keywords QUIET Set this keyword to suppress warning and error message generation due to tessellation errors. !ERROR_STATE is not updated in the case of the return value being `0' when the QUIET keyword is specified. IDLGRTEXT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrText A text object represents one or more text strings that share common rendering attributes. An IDLgrText object is an atomic graphic object; it is one of the basic drawable elements of the IDL Object Graphics system, and it is not a container for other objects. Superclasses This class has no superclasses. Subclasses This class has no subclasses. Creation See "IDLgrText::Init" on page 2219. Methods Intrinsic Methods This class has the following methods: * IDLgrText::Cleanup * IDLgrText::GetCTM * IDLgrText::GetProperty * IDLgrText::Init * IDLgrText::SetProperty Keywords PALETTE Set this keyword equal to the object reference of a palette object (an instance of the IDLgrPalette object class). This keyword is only used if the destination device is using the RGB color model. If so, and a color value for the object is specified as a color index value, the palette set by this keyword is used to translate the color to RGB space. If the PALETTE property on this object is not set, the destination object PALETTE property is used (which defaults to a grayscale ramp). IDLGRTEXT::CLEANUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrText::Cleanup The IDLgrText::Cleanup procedure method performs all cleanup on the object. Note Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass. Syntax OBJ_DESTROY, Obj or Obj -> [IDLgrText::]Cleanup(Only in subclass' Cleanup method.) Arguments None Keywords None IDLGRTEXT::GETCTM [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrText::GetCTM The IDLgrText::GetCTM function method returns the 4 x 4 double-precision floating-point graphics transform matrix from the current object upward through the graphics tree. Syntax Result = Obj -> [IDLgrText::]GetCTM( [, DESTINATION=objref] [, PATH=objref(s)] [, TOP=objref to IDLgrModel object] ) Arguments None Keywords DESTINATION Set this keyword to the object reference of a destination object to specify that the projection matrix for the View object in the current tree be included in the returned transformation matrix. The resulting matrix will transform a point in the data space of the object on which the GetCTM method is called into a normalized coordinate system (-1 to +1 in X, Y, and Z), relative to the View object that contains the text object. PATH Set this keyword to a single object reference or a vector of object references. This keyword specifies the path in the graphics hierarchy to compute the transformation matrix. Each path object reference specified with this keyword must contain an alias. The transformation matrix is computed for the version of the object falling within that path. If this keyword is not set, the PARENT properties determine the path from the current object to the top of the graphics hierarchy and no alias paths are pursued. If IDLgrText::GetCTM is called from within a Draw method, with the DESTINATION keyword set and the PATH keyword not set, the alias path used to find the object during the draw is used, rather than the PARENT path. Note For more information on aliases, refer to the ALIAS keyword in IDLgrModel::Add. TOP Set this keyword equal to the object reference to an IDLgrModel object to specify that the returned matrix accumulate from the object on which the GetCTM method is called up to but not including the specified model object. IDLGRTEXT::GETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrText::GetProperty The IDLgrText::GetProperty procedure method retrieves the value of a property or group of properties for the text. Syntax Obj -> [IDLgrText::]GetProperty [, ALL=variable] [, PARENT=variable] [, XRANGE=variable] [, YRANGE=variable] [, ZRANGE=variable] Arguments None Keywords Any keyword to IDLgrText::Init followed by the word "Get" can be retrieved using IDLgrText::GetProperty. In addition, the following keywords are available: ALL Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the properties associated with the state of this object. State information about the object includes things like color, range, tick direction, etc., but not image, vertex, or connectivity data, or user values. Note The fields of this structure may change in subsequent releases of IDL. PARENT Set this keyword equal to a named variable that will contain an object reference to the object that contains this object. XRANGE Set this keyword equal to a named variable that will contain a two-element vector of the form [xmin, xmax] that specifies the range of x data coordinates covered by the graphic object. IDL maintains and returns this property in double-precision floating- point. YRANGE Set this keyword equal to a named variable that will contain a two-element vector of the form [ymin, ymax] that specifies the range of y data coordinates covered by the graphic object. IDL maintains and returns this property in double-precision floating- point. ZRANGE Set this keyword equal to a named variable that will contain a two-element vector of the form [zmin, zmax] that specifies the range of z data coordinates covered by the graphic object. IDL maintains and returns this property in double-precision floating- point. Note Until the text is drawn to the destination object, the [XYZ]RANGE properties will only report the locations of the text. Use the GetTextDimensions method of the destination object to get the data dimensions of the text prior to a draw operation. IDLGRTEXT::INIT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrText::Init The IDLgrText::Init function method initializes the text object. Note Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass. Syntax Obj = OBJ_NEW('IDLgrText' [, String or vector of strings] [, ALIGNMENT{Get, Set}=value{0.0 to 1.0}] [, BASELINE{Get, Set}=vector] [, CHAR_DIMENSIONS{Get, Set}=[width, height]] [, COLOR{Get, Set}=index or RGB vector] [, /ENABLE_FORMATTING{Get, Set}] [, FONT{Get, Set}=objref] [, /HIDE{Get, Set}] [, LOCATIONS{Get, Set}=array] [, NAME{Get, Set}=string] [, /ONGLASS{Get, Set}] [, PALETTE{Get, Set}=objref] [, RECOMPUTE_DIMENSIONS{Get, Set}={0 | 1 | 2}] [, STRINGS{Get, Set}=string or vector of strings] [, UPDIR{Get, Set}=vector] [, UVALUE{Get, Set}=value] [, VERTICAL_ALIGNMENT{Get, Set}=value{0.0 to 1.0}] [, XCOORD_CONV{Get, Set}=vector] [, YCOORD_CONV{Get, Set}=vector] [, ZCOORD_CONV{Get, Set}=vector] ) or Result = Obj -> [IDLgrText::]Init( [String or vector of strings] ) (Only in a subclass' Init method.) Note Keywords can be used in either form. They are omitted in the second form for brevity. Arguments String The string (or vector of strings) to be created. If this argument is not a string, it is converted prior to using the default formatting rules. Keywords Properties retrievable via IDLgrText::GetProperty are indicated by the word "Get" following the keyword. Properties settable via IDLgrText::SetProperty are indicated by the word "Set" following the keyword. ALIGNMENT (Get, Set) Set this keyword to a floating-point value between 0.0 and 1.0 to indicate the requested horizontal alignment of the text baseline. An alignment of 0.0 (the default) aligns the left-justifies the text at the given position; an alignment of 1.0 right- justifies the text, and an alignment of 0.5 centers the text over the given position. BASELINE (Get, Set) Set this keyword to a two (or three) element vector describing the direction in which the baseline is to be oriented. Use this keyword in conjunction with the UPDIR keyword to specify the plane on which the text lies. The default BASELINE is [1.0,0,0] (i.e., parallel to the x-axis). CHAR_DIMENSIONS (Get, Set) Set this keyword equal to a two-element vector [width, height] indicating the dimensions (measured in data units) of a bounding box for each character, to be used when scaling text projected in three dimensions. If either width or height is zero, the text will be scaled such that if it were positioned halfway between the near and far clipping planes, it will appear at the point size associated with this text object's font. The default value is [0, 0]. IDL converts, maintains, and returns this data as double- precision floating-point. Note If you set the CHAR_DIMENSIONS property to [0,0] (using the SetProperty method), indicating that IDL should calculate the text size, the value (returned by the GetProperty method) will not be updated to reflect the calculated size until you call either the Draw method or the GetTextDimensions method. For example, if the VIEWPLANE_RECT of the view the text object is being rendered in is set equal to [0,0,10,10] (that is, it spans ten data units in each of the X and Y directions), setting the CHAR_DIMENSIONS property equal to [2, 3] will scale the text such that each character fills 20% of the X range and 30% of the Y range. This property has no effect if the ONGLASS property is set equal to one. COLOR (Get, Set) Set this keyword to the color to be used as the foreground color for the text. The color may be specified as a color lookup table index or as an RGB vector. The default is [0, 0, 0]. ENABLE_FORMATTING (Get, Set) Set this keyword to indicate that the text object should honor embedded Hershey- style formatting codes within the strings. (Formatting codes are described in Appendix H, "Fonts".) The default is not to honor the formatting codes. FONT (Get, Set) Set this keyword to an instance of an IDLgrFont object class to describe the font to use to draw this string. The default is 12 point Helvetica. See IDLgrFont for details. Note If the default font is in use, retrieving the value of the FONT property (using the GetProperty method) will return a null object. HIDE (Get, Set) Set this keyword to a boolean value indicating whether this object should be drawn: * 0 = Draw graphic (the default) * 1 = Do not draw graphic LOCATIONS (Get, Set) Set this keyword to an array of one or more two- or three-element vectors specifying the coordinates (measured in data units) used to position the string(s). Each vector is of the form [x, y] or [x, y, z]; if z is not provided, it is assumed to be zero. Each location corresponds to the corresponding string in the String argument. If only one location is provided, and the String argument is a vector of more than one strings, the initial string is positioned at the given location, and each subsequent string is positioned by cyclically reusing the location values. IDL converts, maintains, and returns this data as double-precision floating-point. NAME (Get, Set) Set this keyword equal to a string containing the name associated with this object. The default is the null string, ' '. ONGLASS (Get, Set) Set this keyword to indicate that the text should be displayed "on the glass". The default is projected 3D text. PALETTE (Get, Set) Set this keyword equal to the object reference of a palette object (an instance of the IDLgrPalette object class). This keyword is only used if the destination device is using the RGB color model. If so, and a color value for the object is specified as a color index value, the palette set by this keyword is used to translate the color to RGB space. If the PALETTE property on this object is not set, the destination object PALETTE property is used (which defaults to a grayscale ramp). RECOMPUTE_DIMENSIONS (Get, Set) Set this keyword to one of the following values to indicate when this text object's character dimensions (refer to the CHAR_DIMENSIONS property) are to be recomputed automatically: * 0 = Never recompute. Always use the character dimensions provided via the CHAR_DIMENSIONS property. If CHAR_DIMENSIONS is set to [0,0], compute once and re-use the resulting dimensions until the CHARACTER_DIMENSIONS are modified. * 1 = Recompute, but reuse the current transformation matrix from the previous draw of this text object. If this is the first time the text object is drawn, compute the current transformation matrix. (This option is useful if the parent model of this text object is scaled for zooming, and the text is supposed to increase in size, rather having its data dimensions recomputed to ensure the font size is matched.) * 2 = Recompute always, including the current transformation matrix. STRINGS (Get, Set) Set this keyword to the string (or vector of strings) associated with the text object. This keyword is the same as the String argument described above. UPDIR (Get, Set) Set this keyword to a two (or three) element vector describing the vertical direction for the string. The upward direction is the direction defined by a vector pointing from the origin to the point specified. Use this keyword in conjunction with the BASELINE keyword to specify the plane on which the text lies; the direction specified by UPDIR should be orthogonal to the direction specified by BASELINE. The default UPDIR is [0.0, 1.0, 0.0] (i.e., parallel to the Y axis). UVALUE (Get, Set) Set this keyword to a value of any type. You can use this "user value" to contain any information you wish. Remember that if you set the user value equal to a pointer or object reference, you should destroy the pointer or object reference explicitly when destroying the object it is a user value of. VERTICAL_ALIGNMENT (Get, Set) Set this keyword to a floating-point value between 0.0 and 1.0 to indicate the requested vertical alignment of the text. An alignment of 0.0 (the default) bottom- justifies the text at the given location; an alignment of 1.0 top-justifies the text at the given location. XCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert X coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedX = s0 + s1 * DataX Recommended values are: [(-Xmin)/(Xmax-Xmin), 1/(Xmax-Xmin)] The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double- precision floating-point. YCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert Y coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedY = s0 + s1 * DataY Recommended values are: [(-Ymin)/(Ymax-Ymin), 1/(Ymax-Ymin)] The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double- precision floating-point. ZCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert Z coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedZ = s0 + s1 * DataZ Recommended values are: [(-Zmin)/(Zmax-Zmin), 1/(Zmax-Zmin)] The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double- precision floating-point. IDLGRTEXT::SETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrText::SetProperty The IDLgrText::SetProperty procedure method sets the value of a property or group of properties for the text. Syntax Obj -> [IDLgrText::]SetProperty Arguments None Keywords Any keyword to IDLgrText::Init followed by the word "Set" can be set using IDLgrText::SetProperty. IDLGRVIEW [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrView A view object represents a rectangular area in which graphics objects are drawn. It is a container for objects of the IDLgrModel class. Superclasses This class is a subclass of IDL_Container. Subclasses This class has no subclasses. Creation See "IDLgrView::Init" on page 2231. Methods Intrinsic Methods This class has the following methods: * IDLgrView::Add * IDLgrView::Cleanup * IDLgrView::GetByName * IDLgrView::GetProperty * IDLgrView::Init * IDLgrView::SetProperty Inherited Methods This class inherits the following methods: * IDL_Container::Count * IDL_Container::Get * IDL_Container::IsContained * IDL_Container::Move IDLGRVIEW::ADD [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrView::Add The IDLgrView::Add procedure method adds a child to this view. Syntax Obj -> [IDLgrView::]Add, Model [, POSITION=index] Arguments Model An instance of the IDLgrModel object class. Keywords POSITION Set this keyword equal to the zero-based index of the position within the container at which the new object should be placed. IDLGRVIEW::CLEANUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrView::Cleanup The IDLgrView::Cleanup procedure method performs all cleanup on the object. Note Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass. Syntax OBJ_DESTROY, Obj or Obj -> [IDLgrView::]Cleanup(Only in subclass' Cleanup method.) Arguments None Keywords None IDLGRVIEW::GETBYNAME [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrView::GetByName The IDLgrView::GetByName function method finds contained objects by name. If the named object is not found, the GetByName function returns a null object reference. Note The GetByName function does not perform a recursive search through the object hierarchy. If a fully qualified object name is not specified, only the contents of the current container object are inspected for the named object. Syntax Result = Obj -> [IDLgrView::]GetByName(Name) Arguments Name A string containing the name of the object to be returned. Object naming syntax is very much like the syntax of a UNIX filesystem. Objects contained by other objects can include the name of their parent object; this allows you to create a fully qualified name specification. For example, if object1 contains object2, which in turn contains object3, the string specifying the fully qualified object name of object3 would be 'object1/object2/object3'. Object names are specified relative to the object on which the GetByName method is called. If used at the beginning of the name string, the / character represents the top of an object hierarchy. The string '..' represents the object one level "up" in the hierarchy. Keywords None IDLGRVIEW::GETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrView::GetProperty The IDLgrView::GetProperty procedure method retrieves the value of the property or group of properties for the view. Syntax Obj -> [IDLgrView::]GetProperty [, ALL=variable] [, PARENT=variable] Arguments None Keywords Any keyword to IDLgrView::Init followed by the word "Get" can be retrieved using IDLgrView::GetProperty. In addition, the following keywords are available: ALL Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the properties associated with the state of this object. State information about the object includes things like color, range, tick direction, etc., but not image, vertex, or connectivity data, or user values. Note The fields of this structure may change in subsequent releases of IDL. PARENT Set this keyword equal to a named variable that will contain an object reference to the object that contains this object. IDLGRVIEW::INIT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrView::Init The IDLgrView::Init function method initializes the view object. Note Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass. Syntax Obj = OBJ_NEW('IDLgrView' [, COLOR{Get, Set}=index or RGB vector] [, DEPTH_CUE{Get, Set}=[zbright, zdim]] [, DIMENSIONS{Get, Set}=[width, height]] [, /DOUBLE {Get, Set}] [, EYE{Get, Set}=distance] [, LOCATION{Get, Set}=[x, y]] [, PROJECTION{Get, Set}={1 | 2}] [, /TRANSPARENT{Get, Set}] [, UNITS{Get, Set}={0 | 1 | 2 | 3}] [, UVALUE{Get, Set}=value] [, VIEWPLANE_RECT{Get, Set}=[x, y, width, height]] [, ZCLIP{Get, Set}=[near, far]] ) or Result = Obj -> [IDLgrView::]Init( ) (Only in a subclass' Init method.) Note Keywords can be used in either form. They are omitted in the second form for brevity. Arguments None Keywords Properties retrievable via IDLgrView::GetProperty are indicated by the word "Get" following the keyword. Properties settable via IDLgrView::SetProperty are indicated by the word "Set" following the keyword. COLOR (Get, Set) Set this keyword to the color for the view. This is the color to which the view area will be erased before its contents are drawn. The color may be specified as a color lookup table index or as an RGB vector. The default is [255, 255, 255] (white). DEPTH_CUE (Get, Set) Set this keyword to a two-element floating-point array [zbright, zdim] specifying the near and far Z planes between which depth cueing is in effect. Depth cueing is only honored when drawing to a destination object that uses the RGB color model. Depth cueing causes an object to appear to fade into the background color of the view object with changes in depth. If the depth of an object is further than zdim (that is, if the object's location in the Z direction is farther from the origin than the value specified by zdim), the object will be painted in the background color. Similarly, if the object is closer than the value of zbright, the object will appear in its "normal" color. Anywhere in-between, the object will be a blend of the background color and the object color. For example, if the DEPTH_CUE property is set to [-1,1], an object at the depth of 0.0 will appear as a 50% blend of the object color and the view color. The relationship between Zbright and Zdim determines the result of the rendering: * Zbright < Zdim: Rendering darkens with depth. * Zbright > Zdim: Rendering brightens with depth. * Zbright = Zdim: Disables depth cueing. You can disable depth cueing by setting zbright = zdim. The default is [0.0, 0.0]. DIMENSIONS (Get, Set) Set this keyword to a two-element vector of the form [width, height] specifying the dimensions of the viewport (the rectangle in which models are displayed on a graphics destination). By default, the viewport dimensions are set to [0, 0], which indicates that it will match the dimensions of the graphics destination to which it is drawn. The dimensions are measured in the units specified by the UNITS keyword. DOUBLE (Get, Set) The DOUBLE keyword parameter controls the precision used for rendering the entire contents of the view. If set, IDL calculates the transformations used for the modeling and view transforms using double-precision floating-point arithmetic. This allows the values specified for the VIEWPLANE_RECT, modeling transforms in IDLgrModel objects, and coordinate data in atomic graphic objects to be used as double-precision before mapping to device coordinates. Note If this keyword is not specified, IDL uses single-precision floating-point arithmetic for these values which can cause loss of significance and incorrect rendering of data. Using this keyword may impact graphics performance and should only be used when handling data requiring double-precision. EYE (Get, Set) Set this keyword to specify the distance from the eyepoint to the viewplane (Z=0). The default is 4.0. The eyepoint is always centered within the viewplane rectangle. (That is, if the VIEWPLANE_RECT property is set equal to [0,0,1,1], the eyepoint will be at X=0.5, Y=0.5.) IDL converts, maintains, and returns this data as double- precision floating-point. LOCATION (Get, Set) Set this keyword to a two-element vector of the form [x, y] specifying the position of the lower left corner of the view. The default is [0, 0], measured in device units. PROJECTION (Get, Set) Set this keyword to and integer value indicating the type of projection to use within this view. All models displayed within this view will be projected using this type of projection. Valid values are described below. * 1 = Orthogonal projection (default). * 2 = Perspective: Indicates that all models are projected toward the eye (located at the origin), which is the apex of the viewing frustum. With a perspective projection, models that are farther away from the eye will appear smaller in the view than models that are nearer to the eye. TRANSPARENT (Get, Set) Set this keyword to disable the viewport erase, making the viewport transparent. UNITS (Get, Set) Set this keyword to specify the units of measure for this view. Valid values are: * 0 = Device (default) * 1 = Inches * 2 = Centimeters * 3 = Normalized: relative to the graphics destination's rect. Note If you set the UNITS property (using the SetProperty method) of a view without also setting the LOCATION and DIMENSIONS properties, IDL will use the existing size and location values in the new units, without conversion. This means that if your view's location and dimensions were previously measured in centimeters, and you change the value of UNITS to 1 (measurement in inches), the actual size of the view object will change. UVALUE (Get, Set) Set this keyword to a value of any type. You can use this "user value" to contain any information you wish. Remember that if you set the user value equal to a pointer or object reference, you should destroy the pointer or object reference explicitly when destroying the object to which the user value applies. VIEWPLANE_RECT (Get, Set) Set this keyword to a four-element vector of the form [x, y, width, height] to describe the bounds in x and y of the view volume. Objects within the view volume are projected into the viewport. These values are measured in normalized space. The default is [-1.0, -1.0, 2.0, 2.0] IDL converts, maintains, and returns this data as double-precision floating-point. Note The z bounds of the view volume are set via the ZCLIP keyword. The viewplane rectangle is always located at Z=0. ZCLIP (Get, Set) Set this keyword to a two element vector representing the near and far clipping planes to be applied to the objects in this view. The vector should take the form [near, far]. By default, these values are [1, -1]. IDL converts, maintains, and returns this data as double-precision floating-point. IDLGRVIEW::SETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrView::SetProperty The IDLgrView::SetProperty procedure method sets the value of the property or group of properties for the view. Syntax Obj -> [IDLgrView::]SetProperty Arguments None Keywords Any keyword to IDLgrView::Init followed by the word "Set" can be set using IDLgrView::SetProperty. IDLGRVIEWGROUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrViewgroup The IDLgrViewgroup object is a simple container object, very similar to the IDLgrScene object. It contains one or more IDLgrView objects and an IDLgrScene can contain one or more of these objects. This object is special in that it can also contain objects which do not have a Draw method (e.g. IDLgrPattern and IDLgrFont). An IDLgrViewgroup object cannot be returned by a call to the IDLgrWindow::Select method. Superclasses This class is a subclass of IDL_Container. Subclasses This class has no subclasses. Creation See IDLgrViewgroup::Init. Methods Intrinsic Methods This class has the following methods: * IDLgrViewgroup::Add * IDLgrViewgroup::Cleanup * IDLgrViewgroup::GetByName * IDLgrViewgroup::GetProperty * IDLgrViewgroup::Init * IDLgrViewgroup::SetProperty Inherited Methods This class inherits the following methods: * IDL_Container::Count * IDL_Container::Get * IDL_Container::IsContained * IDL_Container::Move IDLGRVIEWGROUP::ADD [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrViewgroup::Add The IDLgrViewgroup::Add function method verifies that the added item is not an instance of the IDLgrScene or IDLgrViewgroup object. If it is not, IDLgrViewgroup:Add adds the object to the specified viewgroup. Syntax Obj -> [IDLgrViewgroup::]Add, Object [, POSITION=index] Arguments Object An instance of an object or a list of objects. Objects which subclass IDLgrScene or IDLgrViewGroup can not be added (avoiding circularity constraints). All other objects are allowed. Keywords POSITION Set this keyword equal to the zero-based index of the position within the container at which the new object should be placed. IDLGRVIEWGROUP::CLEANUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrViewgroup::Cleanup The IDLgrViewgroup::Cleanup procedure method performs all cleanup on the object. Note Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass. Syntax OBJ_DESTROY,Obj or Obj -> [IDLgrViewgroup::]Cleanup(Only in subclass' Cleanup method.) Arguments None Keywords None IDLGRVIEWGROUP::GETBYNAME [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrViewgroup::GetByName The IDLgrViewgroup::GetByName function method finds contained objects by name. If the named object is not found, the GetByName function returns a null object reference. Note The GetByName function does not perform a recursive search through the object hierarchy. If a fully qualified object name is not specified, only the contents of the current container object are inspected for the named object. Syntax Result = Obj -> [IDLgrViewgroup::]GetByName(Name) Arguments Name A string containing the name of the object to be returned. Object naming syntax is very much like the syntax of a UNIX filesystem. Objects contained by other objects can include the name of their parent object; this allows you to create a fully qualified name specification. For example, if object1 contains object2, which in turn contains object3, the string specifying the fully qualified object name of object3 would be 'object1/object2/object3'. Object names are specified relative to the object on which the GetByName method is called. If used at the beginning of the name string, the / character represents the top of an object hierarchy. The string '..' represents the object one level "up" in the hierarchy. Keywords None IDLGRVIEWGROUP::GETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrViewgroup::GetProperty The IDLgrViewgroup::GetProperty procedure method retrieves the value of a property or group of properties for the viewgroup object. Syntax Obj -> [IDLgrViewgroup::]GetProperty [, ALL=variable] [, PARENT=variable] Arguments None Keywords Any keyword to IDLgrViewgroup::Init followed by the word "Get" can be retrieved using IDLgrViewgroup::GetProperty. In addition, the following keywords are available: ALL Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the retrievable properties associated with this object. PARENT Set this keyword to a named variable that will contain an object reference to the object that contains this viewgroup. IDLGRVIEWGROUP::INIT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrViewgroup::Init The IDLgrViewgroup::Init function method initializes the viewgroup object. Note Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass. Syntax Obj = OBJ_NEW('IDLgrViewgroup' [, /HIDE{Get, Set}] [, NAME{Get, Set}=string] [, UVALUE{Get, Set}=value] ) or Result = Obj -> [IDLgrViewgroup::]Init( ) (Only in a subclass' Init method.) Note Keywords can be used in either form. They are omitted in the second form for brevity. Arguments None Keywords Properties retrievable via IDLgrViewgroup::GetProperty are indicated by the word "Get" following the keyword. Properties settable via IDLgrViewgroup::SetProperty are indicated by the word "Set" following the keyword. HIDE (Get, Set) Set this keyword to a boolean value to indicate whether this object should be drawn: * 0 = Draw graphic (the default) * 1 = Do not draw graphic NAME (Get, Set) Set this keyword to a string representing the name to be associated with this object. The default is the null string, ''. UVALUE (Get, Set) Set this keyword to a value of any type. You may use this value to contain any information you wish. IDLGRVIEWGROUP::SETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrViewgroup::SetProperty The IDLgrViewgroup::SetProperty procedure method sets the value of a property or group of properties for the viewgroup. Syntax Obj -> [IDLgrViewgroup::]SetProperty Arguments None Keywords Any keyword to IDLgrViewgroup::Init followed by the word "Set" can be retrieved using IDLgrViewgroup::SetProperty. IDLGRVOLUME [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrVolume A volume object represents a mapping from a three-dimensional array of data to a three-dimensional array of voxel colors, which, when drawn, are projected to two dimensions. An IDLgrVolume object is an atomic graphic object; it is one of the basic drawable elements of the IDL Object Graphics system, and it is not a container for other objects. Superclasses This class has no superclasses. Subclasses This class has no subclasses. Creation See "IDLgrVolume::Init" on page 2252. Methods Intrinsic Methods This class has the following methods: * IDLgrVolume::Cleanup * IDLgrVolume::ComputeBounds * IDLgrVolume::GetCTM * IDLgrVolume::GetProperty * IDLgrVolume::Init * IDLgrVolume::PickVoxel * IDLgrVolume::SetProperty IDLGRVOLUME::CLEANUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrVolume::Cleanup The IDLgrVolume::Cleanup procedure method performs all cleanup on the object. Note Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass. Syntax OBJ_DESTROY, Obj or Obj -> [IDLgrVolume::]Cleanup(Only in subclass' Cleanup method.) Arguments None Keywords None IDLGRVOLUME::COMPUTEBOUNDS [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrVolume::ComputeBounds The IDLgrVolume::ComputeBounds procedure method computes the smallest bounding box that contains all voxels whose opacity lookup is greater than a given opacity value. The BOUNDS property is updated to the computed bounding box. Syntax Obj -> [IDLgrVolume::]ComputeBounds [, OPACITY=value] [, /RESET] [, VOLUMES=int array] Arguments None Keywords OPACITY Set this keyword to the opacity value to be used to determine which voxels are included within the bounding box. All voxels whose opacity lookup is greater than this value will be included. The default value is zero. RESET Set this keyword to cause the BOUNDS keyword of IDLgrVolume::Init to be reset to contain the entire volume. VOLUMES Set this keyword to an array of integers which select which volumes to consider when computing the bounding box. A non-zero value selects a volume to be searched. The default is to search all loaded volumes. For example: VOLUMES=[0,1] will cause ComputeBounds to search only the volume loaded in DATA1. IDLGRVOLUME::GETCTM [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrVolume::GetCTM The IDLgrVolume::GetCTM function method returns the 4 x 4 double-precision floating-point graphics transform matrix from the current object upward through the graphics tree. Syntax Result = Obj -> [IDLgrVolume::]GetCTM( [, DESTINATION=objref] [, PATH=objref(s)] [, TOP=objref to IDLgrModel object] ) Arguments None Keywords DESTINATION Set this keyword to the object reference of a destination object to specify that the projection matrix for the View object in the current tree be included in the returned transformation matrix. The resulting matrix will transform a point in the data space of the object on which the GetCTM method is called into a normalized coordinate system (-1 to +1 in X, Y, and Z), relative to the View object that contains the volume object. PATH Set this keyword to a single object reference or a vector of object references. This keyword specifies the path in the graphics hierarchy to compute the transformation matrix. Each path object reference specified with this keyword must contain an alias. The transformation matrix is computed for the version of the object falling within that path. If this keyword is not set, the PARENT properties determine the path from the current object to the top of the graphics hierarchy and no alias paths are pursued. If IDLgrVolume::GetCTM is called from within a Draw method, with the DESTINATION keyword set and the PATH keyword not set, the alias path used to find the object during the draw is used, rather than the PARENT path. Note For more information on aliases, refer to the ALIAS keyword in IDLgrModel::Add. TOP Set this keyword equal to the object reference to an IDLgrModel object to specify that the returned matrix accumulate from the object on which the GetCTM method is called up to but not including the specified model object. IDLGRVOLUME::GETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrVolume::GetProperty The IDLgrVolume::GetProperty procedure method retrieves the value of a property or group of properties for the volume. Syntax Obj -> [IDLgrVolume::]GetProperty [, ALL=variable] [, PARENT=variable] [, VALID_DATA=variable] [, XRANGE=variable] [, YRANGE=variable] [, ZRANGE=variable] Arguments None Keywords Any keyword to IDLgrVolume::Init followed by the word "Get" can be retrieved using IDLgrVolume::GetProperty. In addition, the following keywords are available: ALL Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the properties associated with the state of this object. State information about the object includes things like color, range, tick direction, etc., but not image, vertex, or connectivity data, or user values. Note The fields of this structure may change in subsequent releases of IDL. PARENT Set this keyword equal to a named variable that will contain an object reference to the object that contains this object. VALID_DATA Set his keyword equal to a named variable that will contain an array of integers (one per volume, DATA0, DATA1, etc.) which have the value 1 if volume data has been loaded for that volume and 0 if that volume data is currently undefined. XRANGE Set this keyword equal to a named variable that will contain a two-element double- precision floating-point vector of the form [xmin, xmax] that specifies the range of x data coordinates covered by the graphic object. YRANGE Set this keyword equal to a named variable that will contain a two-element double- precision floating-point vector of the form [ymin, ymax] that specifies the range of y data coordinates covered by the graphic object. ZRANGE Set this keyword equal to a named variable that will contain a two-element double- precision floating-point vector of the form [zmin, zmax] that specifies the range of z data coordinates covered by the graphic object. IDLGRVOLUME::INIT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrVolume::Init The IDLgrVolume::Init function method initializes the volume object. At least one volume method must be specified, via arguments or keywords. Note Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass. Syntax Obj = OBJ_NEW('IDLgrVolume' [, vol0 [, vol1 [, vol2 [, vol3]]]] [, AMBIENT{Get, Set}=RGB vector] [, BOUNDS{Get, Set}=[xmin, ymin, zmin, xmax, ymax, zmax]] [, COMPOSITE_FUNCTION{Get, Set}={0 | 1 | 2 | 3}] [, CUTTING_PLANES{Get, Set}=array] [, DATA0{Get, Set}=[dx, dy, dz]] [, DATA1{Get, Set}=[dx, dy, dz]] [, DATA2{Get, Set}=[dx, dy, dz]] [, DATA3{Get, Set}=[dx, dy, dz]] [, DEPTH_CUE{Get, Set}=[zbright, zdim]] [, /HIDE{Get, Set}] [, HINTS{Get, Set}={0 | 1 | 2 | 3}] [, /INTERPOLATE{Get, Set}] [, /LIGHTING_MODEL{Get, Set}] [, NAME{Get, Set}=string] [, /NO_COPY{Get, Set}] [, OPACITY_TABLE0{Get, Set}=256-element byte array] [, OPACITY_TABLE1{Get, Set}=256-element byte array] [, RENDER_STEP{Get, Set}=[x, y, z]] [, RGB_TABLE0{Get, Set}=256 x 3-element byte array] [, RGB_TABLE1{Get, Set}=256 x 3-element byte array] [, /TWO_SIDED{Get, Set}] [, UVALUE{Get, Set}=value] [, VOLUME_SELECT{Get, Set}={0 | 1 | 2}] [, XCOORD_CONV{Get, Set}=vector] [, YCOORD_CONV{Get, Set}=vector] [, /ZBUFFER{Get, Set}] [, ZCOORD_CONV{Get, Set}=vector] [, ZERO_OPACITY_SKIP{Get, Set}={0 | 1}] ) or Result = Obj -> [IDLgrVolume::]Init( [vol0 [, vol1 [, vol2 [, vol3]]]] ) (Only in a subclass' Init method.) Note Keywords can be used in either form. They are omitted in the second form for brevity. Arguments vol0 A three-element array (dx, dy, dz) which specifies a data volume. vol1 A three-element array (dx, dy, dz) which specifies a data volume. vol2 A three-element array (dx, dy, dz) which specifies a data volume. vol3 A three-element array (dx, dy, dz) which specifies a data volume. Note If two or more of the above arguments are specified, they must have matching dimensions. Keywords Properties retrievable via IDLgrVolume::GetProperty are indicated by the word "Get" following the keyword. Properties settable via IDLgrVolume::SetProperty are indicated by the word "Set" following the keyword. AMBIENT (Get, Set) Use this keyword to set the color and intensity of the volume's base ambient lighting. Color is specified as an RGB vector. The default is [255, 255, 255]. AMBIENT is applicable only when LIGHTING_MODEL is set. BOUNDS (Get, Set) Set this keyword to a six-element vector of the form [xmin, ymin, zmin, xmax, ymax, zmax], which represents the sub-volume to be rendered. COMPOSITE_FUNCTION (Get, Set) The composite function determines the value of a pixel on the viewing plane by analyzing the voxels falling along the corresponding ray, according to one of the following compositing functions: * 0 = Alpha (default): Alpha-blending. The recursive equation dest' = src * srcalpha + dest * (1 - srcalpha) is used to compute the final pixel color. * 1 = MIP: Maximum intensity projection. The value of each pixel on the viewing plane is set to the brightest voxel, as determined by its opacity. The most opaque voxel's color appropriation is then reflected by the pixel on the viewing plane. * 2 = Alpha sum: Alpha-blending. The recursive equation dest' = src + dest * ( 1 - srcalpha) is used to compute the final pixel color. This equation assumes that the color tables have been pre-multiplied by the opacity tables. The accumulated values can be no greater than 255. * 3 = Average: Average-intensity projection. The resulting image is the average of all voxels along the corresponding ray. CUTTING_PLANES (Get, Set) Set this keyword to a floating-point array with dimensions (4, n) specifying the coefficients of n cutting planes. The cutting plane coefficients are in the form {{nx, ny, nz, D}, ...} where (nx)X+(ny)Y+(nz)Z+ D > 0, and (X, Y, Z) are the voxel coordinates. To clear the cutting planes, set this property to any scalar value (e.g. CUTTING_PLANES = 0). By default, no cutting planes are defined. DATA0 (Get, Set) Set this keyword to a three-element array of the format (dx, dy, dz), which specifies a data volume. Setting this property is the same as including the vol0 argument at creation time. If the data volume dimensions do not match those of any pre-existing data in DATA1, DATA2, or DATA3, all existing data is removed from the object. DATA1 (Get, Set) Set this keyword to a three-element array of the format (dx, dy, dz), which specifies a data volume. Setting this property is the same as including the vol1 argument at creation time. If the data volume dimensions do not match those of any pre-existing data in DATA0, DATA2, or DATA3, all existing data is removed from the object. DATA2 (Get, Set) Set this keyword to a three-element array of the format (dx, dy, dz), which specifies a data volume. Setting this property is the same as including the vol2 argument at creation time. If the data volume dimensions do not match those of any pre-existing data in DATA0, DATA1, or DATA3, all existing data is removed from the object. DATA3 (Get, Set) Set this keyword to a three-element array of the format (dx, dy, dz), which specifies a data volume. Setting this property is the same as including the vol3 argument at creation time. If the data volume dimensions do not match those of any pre-existing data in DATA0, DATA1, or DATA2, all existing data is removed from the object. Note DATA0, DATA1, DATA2, and DATA3 sizes are dynamic. DEPTH_CUE (Get, Set) Set this keyword to a two-element floating-point array [zbright, zdim] specifying the near and far Z planes between which depth cueing is in effect. Depth cueing is only honored when drawing to a destination object that uses the RGB color model. Depth cueing causes an object to appear to fade into the background color of the view object with changes in depth. If the depth of an object is further than zdim (that is, if the object's location in the Z direction is farther from the origin than the value specified by zdim), the object will be painted in the background color. Similarly, if the object is closer than the value of zbright, the object will appear in its "normal" color. Anywhere in-between, the object will be a blend of the background color and the object color. For example, if the DEPTH_CUE property is set to [-1,1], an object at the depth of 0.0 will appear as a 50% blend of the object color and the view color. The relationship between Zbright and Zdim determines the result of the rendering: * Zbright < Zdim: Rendering darkens with depth. * Zbright > Zdim: Rendering brightens with depth. * Zbright = Zdim: Disables depth cueing. You can disable depth cueing by setting zbright = zdim. The default is [0.0, 0.0]. HIDE (Get, Set) Set this keyword to a boolean value indicating whether this object should be drawn: * 0 = Draw graphic (the default) * 1 = Do not draw graphic HINTS (Get, Set) Set this keyword to specify one of the following acceleration hints: * 0 = Disables all acceleration hints (default). * 1 = Enables Euclidean distance map (EDM) acceleration. This option generates a volume map containing the distance from any voxel to the nearest non-zero opacity voxel. The map is used to speed ray casting by allowing the ray to jump over open spaces. It is most useful with sparse volumes. After setting the EDM hint, the draw operation generates the volume map; this process can take some time. Subsequent draw operations will reuse the generated map and may be much faster, depending on the volume's sparseness. A new map is not automatically generated to match changes in opacity tables or volume data (for performance reasons). The user may force recomputation of the EDM map by setting the HINTS property to 1 again. * 2 = Enables the use of multiple CPUs for volume rendering if the platforms used support such use. If HINTS is set to 2, IDL will use all the available (up to 8) CPUs to render portions of the volume in parallel. * 3 = Selects the two acceleration options described above. INTERPOLATE (Get, Set) Set this keyword to indicate that Trilinear interpolation is to be used to determine the data value for each step on a ray. Setting this keyword improves the quality of images produced, at the cost of more computing time. especially when the volume has low resolution with respect to the size of the viewing plane. Nearest neighbor sampling is used by default. LIGHTING_MODEL (Get, Set) Set this keyword to use the current lighting model during rendering in conjunction with a local gradient evaluation. Note Only DIRECTIONAL light sources are honored by the volume object. Because normals must be computed for all voxels in a lighted view, enabling light sources increases the rendering time. NAME (Get, Set) Set this keyword equal to a string containing the name associated with this object. The default is the null string, ' '. NO_COPY (Get, Set) Set this keyword to relocate volume data from the input variables to the volume object, leaving the input variables undefined. Only the DATA0 keyword and the vol0 argument are affected. If this keyword is omitted, the input volume data will be duplicated and a copy will be stored in the object. OPACITY_TABLE0 (Get, Set) Set this keyword to a 256-element byte array to specify an opacity table for DATA0. The default table is the linear ramp. OPACITY_TABLE1 (Get, Set) Set this keyword to a 256-element byte array to specify an opacity table for DATA1. The default table is the linear ramp. This table is used only when VOLUME_SELECT is set equal to 1. RENDER_STEP (Get, Set) Set this keyword to a three element vector of the form [x, y, z] to specify the stepping factor through the voxel matrix. RGB_TABLE0 (Get, Set) Set this keyword to a 256 x 3-element byte array to specify an RGB color table for DATA0. The default table is the linear ramp. RGB_TABLE1 (Get, Set) Set this keyword to a 256 x 3-element byte array to specify an RGB color table for DATA1. The default table is the linear ramp. This table is used only when VOLUME_SELECT is set equal to 1. TWO_SIDED (Get, Set) Set this keyword to force the lighting model to use a two-sided voxel gradient. The two-sided gradient is different from the one-sided gradient (default) in that the absolute value of the inner product of the light direction and the surface gradient is used instead of clamping to 0.0 for negative values. UVALUE (Get, Set) Set this keyword to a value of any type. You can use this "user value" to contain any information you wish. Remember that if you set the user value equal to a pointer or object reference, you should destroy the pointer or object reference explicitly when destroying the object it is a user value of. VOLUME_SELECT (Get, Set) Set this keyword to an integer value to select the form of the volume to be rendered. The VOLUME_SELECT keyword is used to modify the src and srcalpha parameters for the COMPOSITE_FUNCTION keyword. * 0 = render voxels from the 8bit DATA0 volume (the default) src = RGB_TABLE0[DATA0] srcalpha = OPACITY_TABLE0[DATA0] * 1 = render voxels formed by modulating the RGBA components from DATA0 and DATA1 (after RGB and OPACITY table lookups). src = (RGB_TABLE0[DATA0]*RGB_TABLE1[DATA1])/256 * 2 = render voxels formed using a byte from DATA0 (red), DATA1 (green), DATA2(blue) and DATA3(alpha). The keywords OPACITY_TABLE0 and RGB_TABLE0, described above, are used to indirect the data from each volume before forming the RGBA pixel. srcalpha = (OPACITY_TABLE0[DATA3])/256 XCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert X coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedX = s0 + s1 * DataX Recommended values are: [(-Xmin)/(Xmax-Xmin), 1/(Xmax-Xmin)] The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double- precision floating-point. YCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert Y coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedY = s0 + s1 * DataY Recommended values are: [(-Ymin)/(Ymax-Ymin), 1/(Ymax-Ymin)] The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double- precision floating-point. ZBUFFER (Get, Set) Set this keyword to clip the rendering to the current Z-buffer and then update the buffer. The default is to not modify the current Z-buffer. ZCOORD_CONV (Get, Set) Set this keyword to a vector, [s0, s1], of scaling factors used to convert Z coordinates from data units to normalized units. The formula for the conversion is as follows: NormalizedZ = s0 + s1 * DataZ Recommended values are: [(-Zmin)/(Zmax-Zmin), 1/(Zmax-Zmin)] The default is [0.0, 1.0]IDL converts, maintains, and returns this data as double- precision floating-point. ZERO_OPACITY_SKIP (Get, Set) Set this keyword to skip voxels with an opacity of 0. This keyword can increase the output contrast of MIP (MAXIMUM_INTENSITY) projections by allowing the background to show through. If this keyword is set, voxels with an opacity of zero will not modify the Z-buffer. The default (not setting the keyword) continues to render voxels with an opacity of zero. IDLGRVOLUME::PICKVOXEL [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrVolume::PickVoxel The IDLgrVolume::PickVoxel function method computes the coordinates of the voxel projected to a location specified by the 2D device coordinates point, [xi, yi], and the current Z-buffer. The function returns the volume indices as a a vector of three long integers. If the selected point is not within the volume, this function returns [-1,- 1,-1]. Syntax Result = Obj -> [IDLgrVolume::]PickVoxel ( Win, View, Point [, PATH=objref(s)] ) Arguments Win The IDLgrWindow object from which the Z-buffer is to be used. View The IDLgrView object that contains the volume. Point The [x, y] viewport coordinates of the point chosen. Keywords PATH Set this keyword to a single object reference or a vector of object references. This keyword specifies the path in the graphics hierarchy to map the device position to a voxel coordinate. Each path object reference specified with this keyword must contain an alias. The voxel coordinate is computed for the version of the object falling within the specified path. If this keyword is not set, the PARENT properties determine the path from the current object to the top of the graphics hierarchy and no alias paths are pursued. Note For more information on aliases, refer to the ALIAS keyword in IDLgrModel::Add. IDLGRVOLUME::SETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrVolume::SetProperty The IDLgrVolume::SetProperty procedure method sets the value of a property or group of properties for the volume. Syntax Obj -> [IDLgrVolume::]SetProperty Arguments None Keywords Any keyword to IDLgrVolume::Init followed by the word "Set" can be set using IDLgrVolume::SetProperty. IDLGRVRML [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrVRML The IDLgrVRML object allows you to save the contents of an Object Graphics hierarchy into a VRML 2.0 format file. The graphics tree can only contain a single view due to limitations in the VRML specification. The resulting VRML file is interactive and allows you to explore the geometry interactively using a VRML browser. Note Objects or subclasses of this type can not be saved or restored. Aspect ratios are difficult to duplicate as they can be browser dependent. The object is limited to the primitives supported by VRML. Texture maps (and images) will be inlined into the output file. While this will generate large VRML files, the files are fully self-contained. Several entities cannot be translated perfectly. These include: IDLgrImage objects Rotation and Z buffer behavior are not completely supported. Image objects will be converted into texture mapped polygons. BLEND_FUNCTION is not completely supported (only binary srcAlpha,1-srcAlpha) This function is applied automatically if an Alpha channel is present. It is also very browser dependent. Channel masks are not supported. IDLgrPolygon and IDLgrSurface objects Hidden line/hidden point display, color and vertex color blending with texture colors, and bottom color are not supported. Shading may be browser dependent. Front face culling is not supported and back face culling is only supported at the browser's discretion. IDLgrLight objects Lighting scope and intensity may be browser dependent. IDLgrText objects Text using the ONGLASS property is only supported for the initial view. IDLgrViewgroup, IDLgrScene, IDLgrVolume objects These objects are not supported. IDLgrPalette objects Palette objects are simulated using an RGB color model. IDLgrPattern objects Only solid or clear patterns are supported. IDLgrFont, IDLgrSymbol objects The THICK property is not supported. IDLgrPolyline, IDLgrSymbol, IDLgrSurface, IDLgrPolygon and IDLgrPlot objects Line attributes (thickness, linestyle) are not supported. IDLgrView objects Z-clipping control, aspect ratio preservation, the LOCATION property, and orthographic projections are not supported. Destination objects The COLOR_MODEL property is not fully supported in Indexed Color mode, when using a SHADER_RANGE (an RGB model will be substituted instead). The QUALITY property is not supported. Superclasses This class has no superclasses. Subclasses This class has no subclasses. Creation See "IDLgrVRML::Init" on page 2272. Methods Intrinsic Methods This class has the following methods: * IDLgrVRML::Cleanup * IDLgrVRML::Draw * IDLgrVRML::GetDeviceInfo * IDLgrVRML::GetFontnames * IDLgrVRML::GetProperty * IDLgrVRML::GetTextDimensions * IDLgrVRML::Init * IDLgrVRML::SetProperty IDLGRVRML::CLEANUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrVRML::Cleanup The IDLgrVRML::Cleanup procedure method performs all cleanup on the object. Note Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass. Syntax OBJ_DESTROY, Obj or Obj -> [IDLgrVRML::]Cleanup(Only in subclass' Cleanup method.) Arguments None Keywords None IDLGRVRML::DRAW [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrVRML::Draw The IDLgrVRML::Draw procedure method draws the given picture to this graphics destination. Syntax Obj -> [IDLgrVRML::]Draw [, Picture] Arguments Picture The view (an instance of an IDLgrView object) to be drawn. If the view has a LOCATION property, it is ignored. Keywords None IDLGRVRML::GETDEVICEINFO [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrVRML::GetDeviceInfo The IDLgrVRML::GetDeviceInfo procedure method returns information which allows IDL applications to intelligently make decisions for optimal performance. For example, it allows an application to determine if RENDERER=1 is actually implemented in hardware. It also allows applications to make optimal quality decisions when dynamically building texture maps. Syntax Obj­>[IDLgrVRML::]GetDeviceInfo [, ALL=variable] [, MAX_TEXTURE_DIMENSIONS=variable] [, MAX_VIEWPORT_DIMENSIONS=variable] [, NAME=variable] [, NUM_CPUS=variable] [, VENDOR=variable] [, VERSION=variable] Arguments None. Keywords ALL Set this keyword to a named variable which, upon return, contains a structure with the values of all the device information keywords as fields. MAX_TEXTURE_DIMENSIONS Set this keyword equal to a named variable. Upon return, MAX_TEXTURE_DIMENSIONS contains a two element integer array that specifies the maximum texture size supported by the device. MAX_VIEWPORT_DIMENSIONS Set this keyword equal to a named variable. Upon return, MAX_VIEWPORT_DIMENSIONS contains a two element integer array that specifies the maximum size of a graphics display supported by the device. NAME Set this keyword equal to a named variable. Upon return, NAME contains the name of the rendering device as a string. NUM_CPUS Set this keyword equal to a named variable. Upon return, NUM_CPUS contains an integer that specifies the number of CPUs that are known to, and available to IDL. Note The NUM_CPUS keyword accurately returns the number of CPUs for the SGI Irix, SUN, and Microsoft Windows platforms. For platforms other than these, the number returned may not reflect the actual number of CPUs available to IDL in the current system. VENDOR Set this keyword equal to a named variable. Upon return, VENDOR contains the name of the rendering device creator as a string. VERSION Set this keyword equal to a named variable. Upon return, VERSION contains the version of the rendering device driver as a string. IDLGRVRML::GETFONTNAMES [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrVRML::GetFontnames The IDLgrVRML::GetFontnames function method returns the list of available fonts that can be used in IDLgrFont objects. This method will only return the names of the available TrueType fonts. Hershey fonts will not be returned; see Appendix H, "Fonts" for more information. Syntax Return = Obj ->[IDLgrVRML::]GetFontnames( FamilyName [, IDL_FONTS={0 | 1 | 2}] [, STYLES=string] ) Arguments FamilyName A string representing the name of the font family to which all of the returned fonts must belong. The string may be a fully specified family name, such as "Helvetica". You can use both "*" and "?" as wildcard characters, matching any number of characters or one character respectively. To return all available family names, use "*". Keywords IDL_FONTS Set this keyword to specify where to search for fonts that IDL may use. Set IDL_FONT to 1 to select only fonts installed by IDL and to 2 to select only fonts detected in the host operating system. The default value is 0, specifying that both IDL and operating system fonts should be returned. STYLES Set this keyword to a string specifying the styles that are to be matched by the returned font names. You can set STYLES to a fully specified style string, such as "Bold Italic". If you set STYLES to the null string, ' ', only fontnames without style modifiers will be returned. You can use both "*" and "?" as wildcard characters, matching any number of characters or one character respectively. The default value is the string, "*", which returns all fontnames containing the FamilyName argument, with or without style modifiers. IDLGRVRML::GETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrVRML::GetProperty The IDLgrVRML::GetProperty procedure method retrieves the value of a property or group of properties for the VRML object. Syntax Obj -> [IDLgrVRML::]GetProperty [, ALL=variable] [, SCREEN_DIMENSIONS=variable] Arguments None Keywords Any keyword to IDLgrVRML::Init followed by the word "Get" can be retrieved using IDLgrVRML::GetProperty. In addition, the following keywords are available: ALL Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the retrievable properties associated with this object. SCREEN_DIMENSIONS Set this keyword to a named variable that will contain a two-element vector of the form [width, height] specifying the dimensions of the overall screen dimensions for the screen with which this object associated. The screen dimensions are measured in device units. IDLGRVRML::GETTEXTDIMENSIONS [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrVRML::GetTextDimensions The IDLgrVRML::GetTextDimensions function method retrieves the dimensions of a text object that will be rendered in a window. The result is a 3-element double- precision floating-point vector [xDim, yDim, zDim] representing the dimensions of the text object, measured in data units. Syntax Result = Obj ->[IDLgrVRML::]GetTextDimensions( TextObj [, DESCENT=variable] [, PATH=objref(s)] ) Arguments TextObj The object reference to a text or axis object for which the text dimensions are requested. Keywords DESCENT Set this keyword equal to a named variable that will contain an array of double- precision floating-point values (one for each string in the IDLgrText object). The values represent the distance to travel (parallel to the UPDIR vector) from the text baseline to reach the bottom of the lowest descender in the string. All values will be negative numbers, or zero. This keyword is valid only if TextObj is an IDLgrText object. PATH Set this keyword to a single object reference or a vector of object references. This keyword specifies the path in the graphics hierarchy to compute the text dimensions. Each path object reference specified with this keyword must contain an alias. The text dimensions are computed for the version of the object falling within that path. If this keyword is not set, the PARENT properties determine the path from the current object to the top of the graphics hierarchy and no alias paths are pursued. If IDLgrVRML::GetTextDimensions is called from within a Draw method and the PATH keyword is not set, the alias path used to find the object during the draw is used, rather than the PARENT path. Note For more information on aliases, refer to the ALIAS keyword in IDLgrModel::Add. IDLGRVRML::INIT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrVRML::Init The IDLgrVRML::Init function method initializes the VRML object. Note Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass. Syntax Obj = OBJ_NEW('IDLgrVRML' [, COLOR_MODEL{Get}={0 | 1}] [, DIMENSIONS{Get, Set}=[width, height]] [, FILENAME{Get, Set}=string] [, GRAPHICS_TREE{Get, Set}=objref] [, N_COLORS{Get}=integer{2 to 256}] [, PALETTE{Get, Set}=objref] [, QUALITY{Get, Set}={0 | 1 | 2}] [, RESOLUTION{Get, Set}=[xres, yres]] [, UNITS{Get, Set}={0 | 1 | 2 | 3}] [, UVALUE{Get, Set}=value] [, WORLDINFO=string array] [, WOLRDTITLE=string] ) or Result = Obj -> [IDLgrVRML::]Init( ) (Only in a subclass' Init method.) Note Keywords can be used in either form. They are omitted in the second form for brevity. Arguments None Keywords Properties retrievable via IDLgrVRML::GetProperty are indicated by the word "Get" following the keyword. Properties settable via IDLgrVRML::SetProperty are indicated by the word "Set" following the keyword. COLOR_MODEL (Get) Set this keyword to the color model to be used for the buffer: * 0=RGB (the default) * 1=Color indexed. DIMENSIONS (Get, Set) Set this keyword to a two-element vector of the form [width, height] to specify the dimensions of the window in units specified by the UNITS property. The default is [640,480]. Note The only use of this property is to support the use of normalized coordinates for the dimensions of the IDLgrView object passed to the IDLgrVRML::Draw method. FILENAME (Get, Set) Set this keyword to the name of a file into which the vector data will be saved. The default is idl.wrl. GRAPHICS_TREE (Get, Set) Set this keyword to an object reference of type IDLgrView. If this property is set to a valid object reference, calling the Draw method on the destination object with no arguments will cause the object reference associated with this property to be drawn. If this object is valid and the destination object is destroyed, this object reference will be destroyed as well. By default the GRAPHICS_TREE property is set equal to the null-object. N_COLORS (Get) Set this keyword to the number of colors (between 2 and 256) to be used if COLOR_MODEL is set to indexed. PALETTE (Get, Set) Set this keyword to the object reference of a palette object (an instance of the IDLgrPalette object class) to specify the red, green, and blue values that are to be loaded into the buffer's color lookup table. QUALITY (Get, Set) Set this keyword to an integer indicating the rendering quality at which graphics are to be drawn to the buffer. Valid values are: * 0=Low * 1=Medium * 2=High (the default) RESOLUTION (Get, Set) Set this keyword to a two-element vector of the form [xres, yres] specifying the device resolution in centimeters per pixel. Note This keyword is used for text scaling and partial aspect ratio preservation only. The default value is [0.0352778, 0.0352778] (72 DPI). UNITS (Get, Set) Set this keyword to indicate the units of measure for the DIMENSIONS property. Valid values are: * 0=Device (the default) * 1=Inches * 2=Centimeters * 3=Normalized (relative to 1600 x 1200). UVALUE (Get, Set) Set this keyword to a value of any type. You can use this user value to contain any information you wish. WORLDINFO Set this keyword to a list of strings for the info field of the VRML WorldInfo node. The default is the null string, ''. WOLRDTITLE Set this keyword to a string containing the title for the VRML WorldInfo node, TITLE field. The default is 'IDL VRML file'. IDLGRVRML::SETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrVRML::SetProperty The IDLgrVRML::SetProperty procedure method sets the value of a property or group of properties for the VRML world. Syntax Obj -> [IDLgrVRML::]SetProperty Arguments None Keywords Any keyword to IDLgrVRML::Init followed by the word "Set" can be retrieved using IDLgrVRML::SetProperty. IDLGRWINDOW [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrWindow A window object is a representation of an on-screen area on a display device that serves as a graphics destination. Note Objects or subclasses of this type can not be saved or restored. Note on Window Size Limits The OpenGL libraries IDL uses impose limits on the maximum size of a drawable area. The limits are device-dependent - they depend both on your graphics hardware and the setting of the RENDERER property. Currently, the smallest maximum drawable area on any IDL platform is 1280 x 1024 pixels; the limit on your system may be larger. Superclasses This class has no superclass. Subclasses This class has no subclasses. Creation See "IDLgrWindow::Init" on page 2289. Methods Intrinsic Methods This class has the following methods: * IDLgrWindow::Cleanup * IDLgrWindow::Draw * IDLgrWindow::Erase * IDLgrWindow::GetContiguousPixels * IDLgrWindow::GetDeviceInfo * IDLgrWindow::GetFontnames * IDLgrWindow::GetProperty * IDLgrWindow::GetTextDimensions * IDLgrWindow::Iconify * IDLgrWindow::Init * IDLgrWindow::Pickdata * IDLgrWindow::Read * IDLgrWindow::Select * IDLgrWindow::SetCurrentCursor * IDLgrWindow::SetProperty * IDLgrWindow::Show IDLGRWINDOW::CLEANUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrWindow::Cleanup The IDLgrWindow::Cleanup procedure method performs all cleanup on the object. Note Cleanup methods are special lifecycle methods, and as such cannot be called outside the context of object destruction. This means that in most cases, you cannot call the Cleanup method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Cleanup method from within the Cleanup method of the subclass. Syntax OBJ_DESTROY, Obj or Obj -> [IDLgrWindow::]Cleanup(Only in subclass' Cleanup method.) Arguments None Keywords None IDLGRWINDOW::DRAW [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrWindow::Draw The IDLgrWindow::Draw procedure method draws the specified scene or view object to this graphics destination. Note Objects are drawn to the destination device in the order that they are added to the model, view, viewgroup, or scene object that contains them. Syntax Obj -> [IDLgrWindow::]Draw [, Picture] [, CREATE_INSTANCE={1 | 2}] [, /DRAW_INSTANCE] Arguments Picture The view (an instance of an IDLgrView object), viewgroup (an instance of an IDLgrViewgroup object), or scene (an instance of an IDLgrScene object) to be drawn. Keywords CREATE_INSTANCE Set this keyword equal to one specify that this scene or view is the unchanging part of a drawing. Some destinations can make an instance from the current window contents without having to perform a complete redraw. If the view or scene to be drawn is identical to the previously drawn view or scene, this keyword can be set equal to 2 to hint the destination to create the instance from the current window contents if it can. DRAW_INSTANCE Set this keyword to specify that this scene or view is the changing part of a drawing. It is overlaid on the result of the most recent CREATE_INSTANCE draw. IDLGRWINDOW::ERASE [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrWindow::Erase The IDLgrWindow::Erase procedure method erases the entire contents of the window. Syntax Obj -> [IDLgrWindow::]Erase [, COLOR=index or RGB vector] Arguments None Keywords COLOR Set this keyword to the color to be used for the erase. The color may be specified as a color lookup table index or as an RGB vector. The default erase color is white. IDLGRWINDOW::GETCONTIGUOUSPIXELS [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrWindow::GetContiguousPixels The IDLgrWindow::GetContiguousPixels function method returns an array of long integers whose length is equal to the number of colors available in the index color mode (that is, the value of the N_COLORS property). The returned array marks contiguous pixels with the ranking of the range's size. This means that within the array, the elements in the largest available range are set to zero, the elements in the second-largest range are set to one, etc. Use this range to set an appropriate colormap for use with the SHADE_RANGE property of the IDLgrSurface and IDLgrPolygon object classes. To get the largest contiguous range, you could use the following IDL command: result = obj -> GetContiguousPixels() Range0 = WHERE(result EQ 0) A contiguous region in the colormap can be increasing or decreasing in values. The following would be considered contiguous: [0,1,2,3,4] [4,3,2,1,0] Syntax Return = Obj -> [IDLgrWindow::]GetContiguousPixels() Arguments None Keywords None IDLGRWINDOW::GETDEVICEINFO [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrWindow::GetDeviceInfo The IDLgrWindow::GetDeviceInfo procedure method returns information which allows IDL applications to intelligently make decisions for optimal performance. For example, it allows an application to determine if RENDERER=0 is actually implemented in hardware. It also allows applications to make optimal quality decisions when dynamically building texture maps. Syntax Obj­>[IDLgrWindow::]GetDeviceInfo [, ALL=variable] [, MAX_TEXTURE_DIMENSIONS=variable] [, MAX_VIEWPORT_DIMENSIONS=variable] [, NAME=variable] [, NUM_CPUS=variable] [, VENDOR=variable] [, VERSION=variable] Arguments None. Keywords ALL Set this keyword to a named variable which, upon return, contains a structure with the values of all the device information keywords as fields. MAX_TEXTURE_DIMENSIONS Set this keyword equal to a named variable. Upon return, MAX_TEXTURE_DIMENSIONS contains a two element integer array that specifies the maximum texture size supported by the device. MAX_VIEWPORT_DIMENSIONS Set this keyword equal to a named variable. Upon return, MAX_VIEWPORT_DIMENSIONS contains a two element integer array that specifies the maximum size of a graphics display supported by the device. NAME Set this keyword equal to a named variable. Upon return, NAME contains the name of the rendering device as a string. NUM_CPUS Set this keyword equal to a named variable. Upon return, NUM_CPUS contains an integer that specifies the number of CPUs that are known to, and available to IDL. Note The NUM_CPUS keyword accurately returns the number of CPUs for the SGI Irix, SUN, and Microsoft Windows platforms. For platforms other than these, the number returned may not reflect the actual number of CPUs available to IDL in the current system. VENDOR Set this keyword equal to a named variable. Upon return, VENDOR contains the name of the rendering device creator as a string. VERSION Set this keyword equal to a named variable. Upon return, VERSION contains the version of the rendering device driver as a string. IDLGRWINDOW::GETFONTNAMES [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrWindow::GetFontnames The IDLgrWindow::GetFontnames function method returns the list of available fonts that can be used in IDLgrFont objects. This method will only return the names of the available TrueType fonts. Hershey fonts will not be returned; see Appendix H, "Fonts" for more information. Syntax Return = Obj -> [IDLgrWindow::]GetFontnames(FamilyName [, IDL_FONTS={0 | 1 | 2}] [, STYLES=string] ) Arguments FamilyName A string representing the name of the font family to which all of the returned fonts must belong. The string may be a fully specified family name-such as "Helvetica". You can use both "*" and "?" as wildcard characters, matching any number of characters or one character respectively. To return all available family names, use "*". Keywords IDL_FONTS Set this keyword to specify where to search for fonts that IDL may use. Set IDL_FONT to 1 to select only fonts installed by IDL and to 2 to select only fonts detected in the host operating system. The default value is 0, specifying that both IDL and operating system fonts should be returned. STYLES Set this keyword to a string specifying the styles that are to be matched by the returned font names. You can set STYLES to a fully specified style string, such as "Bold Italic". If you set STYLES to the null string, ' ', only fontnames without style modifiers will be returned. You can use both "*" and "?" as wildcard characters, matching any number of characters or one character respectively. The default value is the string, "*", which returns all fontnames containing the FamilyName argument, with or without style modifiers. IDLGRWINDOW::GETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrWindow::GetProperty The IDLgrWindow::GetProperty procedure method retrieves the value of a property or group of properties for the window. Syntax Obj -> [IDLgrWindow::]GetProperty [, ALL=variable] [, IMAGE_DATA=variable] [, RESOLUTION=variable] [, SCREEN_DIMENSIONS=variable] [, ZBUFFER_DATA=variable] Arguments None Keywords Any keyword to IDLgrWindow::Init followed by the word "Get" can be retrieved using IDLgrWindow::GetProperty. In addition, the following keywords are available: ALL Set this keyword to a named variable that will contain an anonymous structure containing the values of all of the properties associated with the state of this object. State information about the object includes things like color, range, tick direction, etc., but not image, vertex, or connectivity data, or user values. Note The fields of this structure may change in subsequent releases of IDL. IMAGE_DATA Set this keyword to a named variable that will contain a byte array representing the image that is currently displayed in the window. If the window object uses an RGB color model, the returned array will have dimensions (3, winXSize, winYSize), or (4, winXSize, winYSize) if an alpha channel is included. If the window object uses an Indexed color model, the returned array will have dimensions (winXSize, winYSize). See "IDLgrWindow::Read" on page 2296 for more information. RESOLUTION Set this keyword to a named variable that will contain a vector of the form [xres, yres] reporting the pixel resolution, measured in centimeters per pixel. This value is stored in double precision. SCREEN_DIMENSIONS Set this keyword to a named variable that will contain a two-element vector of the form [width, height] specifying the dimensions of the overall screen dimensions for the screen with which this window is associated. The screen dimensions are measured in device units. ZBUFFER_DATA Set this keyword to a named variable that will contain a float array representing the zbuffer that is currently within the buffer. The returned array will have dimensions (xdim, ydim). IDLGRWINDOW::GETTEXTDIMENSIONS [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrWindow::GetTextDimensions The IDLgrWindow::GetTextDimensions function method retrieves the dimensions of a text object that will be rendered in a window. The result is a 3-element double- precision floating-point vector [xDim, yDim, zDim] representing the dimensions of the text object, measured in data units. Syntax Result = Obj ->[IDLgrWindow::]GetTextDimensions( TextObj [, DESCENT=variable] [, PATH=objref(s)] ) Arguments TextObj The object reference to a text or axis object for which the text dimensions are requested. Keywords DESCENT Set this keyword equal to a named variable that will contain an array of double- precision floating-point values (one for each string in the IDLgrText object). The values are the distance to travel (parallel to the UPDIR direction) from the baseline to reach the bottom of all the descenders for the string; the values will be negative or 0. This keyword is only valid if TextObj is of the class IDLgrText. PATH Set this keyword to a single object reference or a vector of object references. This keyword specifies the path in the graphics hierarchy to compute the text dimensions. Each path object reference specified with this keyword must contain an alias. The text dimensions are computed for the version of the object falling within that path. If this keyword is not set, the PARENT properties determine the path from the current object to the top of the graphics hierarchy and no alias paths are pursued. If IDLgrWindow::GetTextDimensions is called from within a Draw method and the PATH keyword is not set, the alias path used to find the object during the draw is used, rather than the PARENT path. Note For more information on aliases, refer to the ALIAS keyword in IDLgrModel::Add. IDLGRWINDOW::ICONIFY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrWindow::Iconify The IDLgrWindow::Iconify procedure method iconifies or de-iconifies the window. Note Iconification under window systems is solely handled by the window manager; client applications, such as IDL, do not have the capability to manage icons. The Iconify method provides a hint to the window manager, which applies the information as it sees fit. (On the Macintosh, for example, iconfication is not a standard option; the Iconify method is ignored on the Mac.) Syntax Obj -> [IDLgrWindow::]Iconify, IconFlag Arguments IconFlag Set IconFlag to 1 (one) to iconify the window or to 0 (zero) to restore the window. If the window is already restored, it is brought to the front of the window stack. Keywords None IDLGRWINDOW::INIT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrWindow::Init The IDLgrWindow::Init function method initializes the window object. Note Init methods are special lifecycle methods, and as such cannot be called outside the context of object creation. This means that in most cases, you cannot call the Init method directly. There is one exception to this rule: If you write your own subclass of this class, you can call the Init method from within the Init method of the subclass. Syntax Obj = OBJ_NEW('IDLgrWindow' [, COLOR_MODEL{Get}={0 | 1}] [, DIMENSIONS{Get, Set} =[width, height]] [, GRAPHICS_TREE{Get, Set}=objref of type IDLgrScene, IDLgrViewgroup, or IDLgrView] [, LOCATION{Get, Set}=[x, y]] [, N_COLORS{Get}=integer{2 to 256}] [, PALETTE{Get, Set}=objref] [, QUALITY{Get, Set}={0 | 1 | 2}] [, RENDERER{Get}={0 | 1}] [, RETAIN{Get}={0 | 1 | 2}] [, TITLE{Get, Set}=string] [, UNITS{Get, Set}={0 | 1 | 2 | 3}] [, UVALUE{Get, Set}=value] ) or Result = Obj -> [IDLgrWindow::]Init( ) (Only in a subclass' Init method.) X Windows Keywords: [, DISPLAY_NAME{Get}=string] Note Keywords can be used in either form. They are omitted in the second form for brevity. Arguments None Keywords Properties retrievable via IDLgrWindow::GetProperty are indicated by the word "Get" following the keyword. Properties settable via IDLgrWindow::SetProperty are indicated by the word "Set" following the keyword. COLOR_MODEL (Get) Set this keyword to the color model to be used for the window: * 0 = RGB (default) * 1 = Color Index Note For some X11 display situations, IDL may not be able to support a color index model destination object in object graphics. We do, however, guarantee that an RGB color model destination will be available for all display situations. DIMENSIONS (Get, Set) Set this keyword to a two-element vector of the form [width, height] to specify the dimensions of the window in units specified by the UNITS property. By default, if no value is specified for DIMENSIONS, IDL uses the value of the "Default Window Width" and "Default Window Height" preferences set in the IDL Development Environment's (IDLDE) Preferences dialog. If there is no preference file for the IDLDE, the DIMENSIONS property is set equal to one quarter of the screen size. There are limits on the maximum size of an IDLgrWindow object; see "Note on Window Size Limits" on page 2276 for details. Note Changing DIMENSIONS properties is merely a request and may be ignored for various reasons. DISPLAY_NAME (Get) (X Only) Set this keyword to the name of the X Windows display on which the window is to appear. GRAPHICS_TREE (Get, Set) Set this keyword to an object reference of type IDLgrScene, IDLgrViewgroup, or IDLgrView. If this property is set to a valid object reference, calling the Draw method on the destination object with no arguments will cause the object reference associated with this property to be drawn. If this object is valid and the destination object is destroyed, this object reference will be destroyed as well. By default the GRAPHICS_TREE property is set equal to the null-object. LOCATION (Get, Set) Set this keyword to a two-element vector of the form [x, y] to specify the location of the upper lefthand corner of the window relative to the display screen, in units specified by the UNITS property. By default, the window is positioned at one of four quadrants on the display screen, and the location is measured in device units. Note Changing LOCATION properties is merely a request and may be ignored for various reasons. LOCATION may be adjusted to take into account window decorations. N_COLORS (Get) Set this keyword to the number of colors (between 2 and 256) to be used if COLOR_MODEL is set to Indexed (1). This keyword is ignored if COLOR_MODEL is set to RGB (0). Note If COLOR_MODEL is set to Color Index (1), setting N_COLORS is treated as a request to your operating system. You should always check the actual number of available colors for any Color Indexed destination with the IDLgrWindow::GetProperty method. The actual number of available colors depends on your system and also on how you have used IDL. PALETTE (Get, Set) Set this keyword to the object reference of a palette object (an instance of the IDLgrPalette object class) to specify the red, green, and blue values that are to be loaded into the graphics destination's color lookup table, applicable if the Indexed color model is used. QUALITY (Get, Set) Set this keyword to an integer indicating the rendering quality at which graphics are to be drawn to this destination. Valid values are: * 0 = Low * 1 = Medium * 2 = High (default). RENDERER (Get) Set this keyword to an integer value indicating which graphics renderer to use when drawing objects within the window. Valid values are: * 0 = Platform native OpenGL * 1 = IDL's software implementation By default, your platform's native OpenGL implementation is used. If your platform does not have a native OpenGL implementation, IDL's software implementation is used regardless of the value of this property. See "Hardware vs. Software Rendering" in Chapter 28 of Using IDL for details. Your choice of renderer may also affect the maximum size of an IDLgrWindow object; see "Note on Window Size Limits" on page 2276 for details. RETAIN (Get) Set this keyword to 0, 1, or 2 to specify how backing store should be handled for the window. By default, if no value is specified for RETAIN, IDL uses the value of the "Backing Store" preference set in the IDL Development Environment's (IDLDE) Preferences dialog. If there is no preference file for the IDLDE (that is, if you always use IDL in plain tty mode), the RETAIN property is set equal to 0 by default. * 0 = No backing store. * 1 = The server or window system is requested to provide the backing store. Note that requesting backing store from the server is only a request; backing store may not be provided in all situations. * 2 = Requests that IDL provide the backing store directly. In some situations, IDL can not provide this backing store in Object Graphics. To see if IDL provided backing store, query the RETAIN keyword of IDLgrWindow::GetProperty. IDL may also alter the RENDERER keyword while attempting to provide backing store. In IDL Object Graphics, it is almost always best to disable backing store (that is, set the RETAIN property equal to zero). This is because drawing to an off-screen pixmap (which is what happens when backing store is enabled) almost always bypasses any hardware graphics acceleration that may be available, causing all rendering to be done in software. To ensure that windows are redrawn properly, enable the generation of expose events on the WIDGET_DRAW window and redraw the window explicitly when an expose event is received. TITLE (Get, Set) Set this keyword equal to a string that represents the title of the window. UNITS (Get, Set) Set this keyword to indicate the units of measure for the LOCATION and DIMENSIONS properties. Valid values are: * 0 = Device (default) * 1 = Inches * 2 = Centimeters * 3 = Normalized: relative to the dimensions of the screen. Note If you set the value of the UNITS property (using the SetProperty method) without also setting the value of the LOCATION and DIMENSIONS properties, IDL will convert the current size and location values into the new units. UVALUE (Get, Set) Set this keyword to a value of any type. You can use this "user value" to contain any information you wish. Remember that if you set the user value equal to a pointer or object reference, you should destroy the pointer or object reference explicitly when destroying the object it is a user value of. IDLGRWINDOW::PICKDATA[1] [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrWindow::Pickdata The IDLgrWindow::Pickdata function method maps a point in the two-dimensional device space of the window to a point in the three-dimensional data space of an object tree. The resulting 3D data space coordinates are returned in a user-specified variable. The Pickdata function returns one if the specified location in the window's device space "hits" a graphic object, or zero if no object was "hit". Pickdata returns - 1 if the point selected falls outside of the specified view or window. Syntax Result = Obj -> [IDLgrWindow::]Pickdata( View, Object, Location, XYZLocation [, PATH=objref(s)] ) Arguments View The object reference of an IDLgrView object that contains the object being picked. Object The object reference of a model or atomic graphic object from which the data space coordinates are being requested. Location A two-element vector [x, y] specifying the location in the window's device space of the point to pick data from. XYZLocation A named variable that will contain the three-dimensional double-precision floating- point data space coordinates of the picked point. Note that the value returned in this variable is a location, not a data value. Note If the atomic graphic object specified as the target has been transformed using either the LOCATION or DIMENSIONS properties (this is only possible with IDLgrAxis, IDLgrImage, and IDLgrText objects), these transformations will not be included in the data coordinates returned by the Pickdata function. This means that you may need to re-apply the transformation accomplished by specifying LOCATION or DIMENSIONS once you have retrieved the data coordinates with Pickdata. This situation does not occur if you transform the axis, text, or image object using the [XYZ]COORD_CONV properties. Keywords PATH Set this keyword to a single object reference or a vector of object references. This keyword specifies the path in the graphics hierarchy to map the device position to a data space coordinate. Each path object reference specified with this keyword must contain an alias. The data space coordinate is computed for the version of the object falling within that path. If this keyword is not set, the PARENT properties determine the path from the current object to the top of the graphics hierarchy and no alias paths are pursued. Note For more information on aliases, refer to the ALIAS keyword in IDLgrModel::Add. IDLGRWINDOW::READ [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrWindow::Read The IDLgrWindow::Read function method reads an image from a window. The returned value is an instance of the IDLgrImage object class. Syntax Result = Obj -> [IDLgrWindow::]Read() Arguments None Keywords None IDLGRWINDOW::SELECT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrWindow::Select The IDLgrWindow::Select function method returns a list of objects selected at a specified location. If no objects are selected, the Select function returns -1. Note IDL returns a maximum of 512 objects. This maximum may be smaller if any of the objects are contained in deep model hierarchies. Because of this limit, it is possible that not all objects eligible for selection will appear in the list. Syntax Result = Obj -> [IDLgrWindow::]Select( Picture, XY [, DIMENSIONS=[width, height]] [, UNITS={0 | 1 | 2 | 3}] ) Arguments Picture The view or scene (an instance of the IDLgrView, IDLgrViewgroup, or IDLgrScene class) whose children are among the candidates for selection. If the first argument is a scene, then the returned object list will contain one or more views. If the first argument is a view, the list will contain atomic graphic objects (or model objects which have their SELECT_TARGET property set). Objects are returned in order, according to their distance from the viewer. The closer an object is to the viewer, the lower its index in the returned object list. If multiple objects are at the same distance from the viewer (views in a scene or 2D geometry), the last object drawn will appear at a lower index in the list. XY A two-element array defining the center of the selection box in device space. By default, the selection box is 3 pixels by 3 pixels. Keywords DIMENSIONS Set this keyword to a two-element array [w, h] to specify that the selection box will have a width w and a height h, and will be centered about the coordinates [x, y] specified in the XY argument. The box occupies the rectangle defined by: (x-(w/2), y-(h/2)) - (x+(w/1), y+(h/2)) Any object that intersects this box is considered to be selected. By default, the selection box is 3 pixels by 3 pixels. UNITS Set this keyword to indicate the units of measure. Valid values are: * 0 = Device (default) * 1 = Inches * 2 = Centimeters * 3 = Normalized: relative to the dimensions of the graphics destination. IDLGRWINDOW::SETCURRENTCURSOR [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrWindow::SetCurrentCursor The IDLgrWindow::SetCurrentCursor procedure method sets the current cursor image to be used while positioned over a drawing area. Syntax Obj-> [IDLgrWindow::]SetCurrentCursor [, CursorName] [, IMAGE=16 x 16 bitmap] [, MASK=16 x 16 bitmap] [, HOTSPOT=[x, y]] X Windows Keywords: [, STANDARD=index] Arguments CursorName A string that specifies which built-in cursor to use. This argument is ignored if one of the keywords to this routine is set. This string can be one of the following: * ARROW * CROSSHAIR * ICON * IBEAM * MOVE * ORIGINAL * SIZE_NE * SIZE_NW * SIZE_SE * SIZE_SW * SIZE_NS * SIZE_EW * UP_ARROW Keywords IMAGE Set this keyword to a 16x16 column bitmap, contained in a 16-element short integer vector, specifying the cursor pattern. The offset from the upper-left pixel to the point that is considered the "hot spot" can be provided via the HOTSPOT keyword. MASK When the IMAGE keyword is set, the MASK keyword can be used to simultaneously specify the mask that should be used. In the mask, bits that are set indicate bits in the IMAGE that should be seen and bits that are not are "masked out". HOTSPOT Set this keyword to a two-element vector specifying the [x, y] pixel offset of the cursor "hot spot", the point which is considered to be the mouse position, from the upper left corner of the cursor image. This parameter is only applicable if IMAGE is provided. The cursor image is displayed top-down (the first row is displayed at the top). STANDARD (X Only) Set this keyword to an X11 cursor font index to change the appearance of the cursor in the IDL graphics window to a glyph in this font. On non-X platforms, setting this keyword displays the crosshair cursor. IDLGRWINDOW::SETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrWindow::SetProperty The IDLgrWindow::SetProperty procedure method sets the value of a property or group of properties for the window. Syntax Obj -> [IDLgrWindow::]SetProperty Arguments None Keywords Any keyword to IDLgrWindow::Init followed by the word "Set" can be set using IDLgrWindow::SetProperty. IDLGRWINDOW::SHOW [Previous Routine] [Next Routine] [List of Routines] NAME: IDLgrWindow::Show The IDLgrWindow::Show procedure method exposes or hides a window. Syntax Obj -> [IDLgrWindow::]Show, Position Arguments Position Set this argument equal to a non-zero value to expose the window, or to 0 to hide the window. Keywords None TRACKBALL [Previous Routine] [Next Routine] [List of Routines] NAME: TRACKBALL A TrackBall object translates widget events from a draw widget (created with the WIDGET_DRAW function) into transformations that emulate a virtual trackball (for transforming object graphics in three dimensions). This object class is implemented in the IDL language. Its source code can be found in the file trackball_ _define.pro in the lib subdirectory of the IDL distribution. Superclasses This class has no superclasses. Subclasses This class has no subclasses. Creation See "TrackBall::Init" on page 2304. Methods Intrinsic Methods This class has the following methods: * TrackBall::Init * Trackball::Reset * TrackBall::Update TRACKBALL::INIT [Previous Routine] [Next Routine] [List of Routines] NAME: TRACKBALL::INIT The TrackBall::Init function method initializes the TrackBall object. Syntax Obj = OBJ_NEW('TrackBall', Center, Radius [, AXIS={0 | 1 | 2}] [, /CONSTRAIN] [, MOUSE=bitmask] ) or Result = Obj -> [TrackBall::]Init( Center, Radius ) (Only in a subclass' Init method.) Note Keywords can be used in either form. They are omitted in the second form for brevity. Arguments Center A two-dimensional vector, [X, Y], specifying the center coordinates of the trackball. X and Y should be specified in device units. Radius The radius of the trackball, specified in device units. Keywords AXIS Set this keyword to an integer value to indicate the axis about which rotations are to be constrained if the CONSTRAIN keyword is set. Valid values include: * 0 = Rotate only around the X axis. * 1 = Rotate only around the Y axis. * 2 = Rotate only around the Z axis (this is the default). CONSTRAIN Set this keyword to indicate that the trackball transformations are to be constrained about the axis specified by the AXIS keyword. The default is not to constrain the transformations. MOUSE Set this keyword to a bitmask to indicate which mouse button to honor for trackball events. The least significant bit represents the leftmost button, the next highest bit represents the middle button, and the next highest bit represents the right button. The default is 1b, for the left mouse button. TRACKBALL::RESET [Previous Routine] [Next Routine] [List of Routines] NAME: TRACKBALL::RESET The TrackBall::Reset procedure method resets the state of the TrackBall object. Syntax Obj -> [TrackBall::]Reset, Center, Radius [, AXIS={0 | 1 | 2}] [, /CONSTRAIN] [, MOUSE=bitmask] Arguments Center A two-dimensional vector, [X, Y], specifying the center coordinates of the trackball. X and Y should be specified in device units. Radius The radius of the trackball, specified in device units. Keywords AXIS Set this keyword to an integer value to indicate the axis about which rotations are to be constrained if the CONSTRAIN keyword is set. Valid values include: * 0 = Rotate only around the X axis. * 1 = Rotate only around the Y axis.s * 2 = Rotate only around the Z axis (this is the default). CONSTRAIN Set this keyword to indicate that the trackball transformations are to be constrained about the axis specified by the AXIS keyword. The default is not to constrain the transformations. MOUSE Set this keyword to a bitmask to indicate which mouse button to honor for trackball events. The least significant bit represents the leftmost button, the next highest bit represents the middle button, and the next highest bit represents the right button. The default is 1b, for the left mouse button. TRACKBALL::UPDATE [Previous Routine] [Next Routine] [List of Routines] NAME: TRACKBALL::UPDATE The TrackBall::Update function method updates the state of the TrackBall object based on the information contained in the input widget event structure. The return value is nonzero if a transformation matrix is calculated as a result of the event, or zero otherwise. Syntax Result = Obj -> [TrackBall::]Update( sEvent [, MOUSE=bitmask] [, TRANSFORM=variable] [, /TRANSLATE] ) Arguments sEvent The widget event structure. Keywords MOUSE Set this keyword to a bitmask to indicate which mouse button to honor for trackball events. The least significant bit represents the leftmost button, the next highest bit represents the middle button, and the next highest bit represents the right button. The default is 1b, for the left mouse button. TRANSFORM Set this keyword to a named variable that will contain a 4 x 4 element floating-point array if a new transformations matrix is calculated as a result of the widget event. TRANSLATE Set this keyword to indicate that the trackball movement should be constrained to translation in the X-Y plane rather than rotation about an axis. Example The example code below provides a skeleton for a widget-based application that uses the TrackBall object to interactively change the orientation of graphics. Create a trackball centered on a 512x512 pixel drawable area, and a view containing the model to be manipulated: xdim = 512 ydim = 512 wBase = WIDGET_BASE() wDraw = WIDGET_DRAW(wBase, XSIZE=xdim, YSIZE=ydim, $ GRAPHICS_LEVEL=2, /BUTTON_EVENTS, $ /MOTION_EVENTS, /EXPOSE_EVENTS, RETAIN=0 ) WIDGET_CONTROL, wBase, /REALIZE WIDGET_CONTROL, wDraw, GET_VALUE=oWindow oTrackball = OBJ_NEW('Trackball', [xdim/2.,ydim/2.], xdim/2.) oView = OBJ_NEW('IDLgrView') oModel = OBJ_NEW('IDLgrModel') oView->Add, oModel XMANAGER, 'TrackEx', wBase You must handle the trackball updates in the widget event-handling code. As the trackball transformation changes, update the transformation for the model object, and redraw the view: PRO TrackEx_Event, sEvent ... bHaveXform = oTrackball->Update( sEvent, TRANSFORM=TrackXform ) IF (bHaveXform) THEN BEGIN oModel->GetProperty, TRANSFORM=ModelXform oModel->SetProperty, TRANSFORM=ModelXform # TrackXform oWindow->Draw, oView ENDIF ... END For a complete example, see the file surf_track.pro, located in the examples/visual subdirectory of the IDL distribution. The SURF_TRACK procedure uses IDL widgets to create a graphical user interface to an object tree, creates a surface object from user-specified data (or from default data, if none is specified), and places the surface object in an IDL draw widget. The SURF_TRACK interface allows the user to specify several attributes of the object hierarchy via pulldown menus. NAME: !CPU Supplies information about the state of the system processor, and of IDL's use of it. !CPU is read-only, and cannot be modified directly. NAME: !DPI A read-only variable containing the double-precision value of pi ( ). NAME: !DTOR A read-only variable containing the floating-point value used to convert degrees to radians ( /180 0.01745). NAME: !MAP An array variable containing the information needed to effect coordinate conversions between points of latitude and longitude and map coordinates. The values in this array are established by the MAP_SET procedure; the user should not change them directly. NAME: !PI A read-only variable containing the single-precision value of pi ( ). NAME: !RADEG A read-only variable containing the floating-point value used to convert radians to degrees (180/ 57.2958). NAME: !VALUES A read-only variable containing the IEEE single- and double-precision floating-point values Infinity and NaN (Not A Number). !VALUES is a structure variable with the following fields: ** Structure !VALUES, 4 tags, length=24: F_INFINITY FLOAT Infinity F_NAN FLOAT NaN D_INFINITY DOUBLE Infinity D_NAN DOUBLE NaN where Infinity is the value Infinity and NaN is the value Not A Number. (For more information on these special floating-point values, see "Special Floating-Point Values" in Chapter 17 of Building IDL Applications.) NAME: !ERR This system variable is now obsolete and has been replaced by the !ERROR_STATE system variable. Code that uses the !ERR system variable will continue to function as before, but all new code should use !ERROR_STATE.CODE. NAME: !ERROR_STATE A new field has been added to the returned structure called SYS_CODE_TYPE. The new field follows the SYS_CODE field and comes before the MSG field. The SYS_CODE_TYPE field is a string describing the type of system code contained in the SYS_CODE field. Possible values are: * errno - Unix/Posix system error. * win32 - Microsoft Windows Win32 system error. * winsock - Microsoft Windows sockets library error. * macos - Macintosh system error. A null string in this field indicates that there is no system code corresponding to the current error. A structure variable which contains the status of the last error message. !ERROR_STATE includes the following fields: ** Structure !ERROR_STATE, 7tags, length=52: NAME STRING 'M_SUCCESS' BLOCK STRING 'IDL_MBLK_CORE' CODE LONG 0 SYS_CODE LONG Array[2] MSG STRING '' SYS_MSG STRING '' MSG_PREFIX STRING '%' * NAME: A read-only string variable containing the error name of the IDL- generated component of the last error message. * BLOCK: A read-only string variable containing the name of the message block for the last error message's IDL-generated component. * See the External Development Guide for more information about blocks. * CODE: A long-integer variable containing the error code of the last error's IDL-generated component. * SYS_CODE: A long-integer variable containing the error code of the last error's operating system-generated component, if it exists. * MSG: A read-only string variable containing the text of the last IDL-generated error message. * SYS_MSG: A read-only string variable containing the text of the last error's operating system-generated component, if it exists. * MSG_PREFIX: A string variable containing the prefix string used for error messages. This system variable replaces !ERROR, !ERR_STRING, !MSG_PREFIX, !SYSERR_STRING, and !SYSERROR, and includes two new fields: error name and block name. For a more detailed explanation of !ERROR_STATE, see "Error Handling" in Chapter 17 of Building IDL Applications. NAME: !ERROR This system variable is now obsolete and has been replaced by the !ERROR_STATE system variable. Code that uses the !ERROR system variable will continue to function as before, but we suggest that all new code use !ERROR_STATE.CODE. NAME: !ERR_STRING This system variable is now obsolete and has been replaced by the !ERROR_STATE system variable. Code that uses the !ERR_STRING system variable will continue to function as before, but we suggest that all new code use !ERROR_STATE.MSG. NAME: !EXCEPT An integer variable that controls when IDL checks for invalid mathematical computations (exceptions), such as division by zero. The three allowed values are: Value Description 0 Never report exceptions. 1 Report exceptions when the interpreter is returning to an interactive prompt (the default). 2 Report exceptions at the end of each IDL statement. Note that this slows IDL by roughly 5% compared to setting !EXCEPT=1. Table D-1: EXCEPT Values For more information on invalid mathematical computations and error reporting, see "Math Errors" in Chapter 17 of Building IDL Applications. The value of !EXCEPT is used by the CHECK_MATH function to determine when to return errors. See "CHECK_MATH" on page 172 for details. Note In versions of IDL up to and including IDL 4.0.1, the default exception handling was functionally identical to setting !EXCEPT=2. NAME: !MOUSE A structure variable that contains the status from the last cursor read operation. !MOUSE has the following fields: ** Structure !MOUSE, 4 tags, length=16: X LONG 511 Y LONG 252 BUTTON LONG 4 TIME LONG 1428829775 * X and Y: Contain the location (in device coordinates) of the cursor when the mouse button was pressed. * BUTTON: Contains * - 1 (one) if the left mouse button was pressed, * - 2 (two) if the middle mouse button was pressed * - 4 (four) if the right mouse button was pressed. * TIME: Contains the number of milliseconds since a base time. See "CURSOR" on page 265 for details on reading the cursor position. NAME: !MSG_PREFIX This keyword is now obsolete and has been replaced by the !ERROR_STATE system variable. Code that uses the !MSG_PREFIX system variable will continue to function as before, but we suggest that all new code use !ERROR_STATE.MSG_PREFIX. NAME: !SYSERROR This keyword is now obsolete and has been replaced by the !ERROR_STATE system variable. Code that uses the !SYSERROR system variable will continue to function as before, but we suggest that all new code use !ERROR_STATE.SYS_CODE. NAME: !SYSERR_STRING This keyword is now obsolete and has been replaced by the !ERROR_STATE system variable. Code that uses the !SYSERR_STRING system variable will continue to function as before, but we suggest that all new code use !ERROR_STATE.SYS_MSG. NAME: !WARN The !WARN system variable no longer contains the TRUNCATED_FILENAME field. A structure variable that causes IDL to print warnings to the console or command log when obsolete IDL features are found at compile time. !WARN has the following fields: ** Structure !WARN, 3 tags, length=3: OBS_ROUTINES BYTE 0 OBS_SYSVARS BYTE 0 PARENS BYTE 0 TRUNCATED_FILENAME BYTE 0 Setting each of the four fields to 1 (one) generates a warning for a different type of obsolete code. If the OBS_ROUTINES field is set equal to one, IDL generates warnings when it encounters references to obsolete internal or library routines. If the OBS_SYSVARS field is set equal to one, IDL generates warnings when it encounters references to obsolete system variables. If the PARENS field is set equal to one, IDL generates warnings when it encounters a use of parentheses to specify an index into an array. If the TRUNCATED_FILENAME field is set equal to one, IDL generates warnings whenever a file can only be found by truncating its full name. Warning IDL version 5.1 is the last version of IDL that will support DOS 8.3 filename limitations. All future IDL releases will not truncate filenames. You can use !WARN.TRUNCATE_FILENAME to locate and rename truncated filenames. Please rename the file upon being warned that a filename has been truncated to avoid future problems. No warnings are generated when the fields of the !WARN structure are set equal to zero (the default). IDL ENVIRONMENT SYSTEM VARIABLES [Previous Routine] [Next Routine] [List of Routines] NAME: !DIR A string variable containing the path to the main IDL directory. NAME: !DLM_PATH Significant portions of IDL's built in functionality are packaged in the form of Dynamically Loadable Modules (DLMs). DLMs correspond to Macintosh code fragments, UNIX sharable libraries, VMS sharable executables, or Windows DLLs, depending on the operating system in use. At startup, IDL searches for DLM definition files (which end in the .dlm suffix) and makes note of the routines supplied by each DLM. If such are routine is called, IDL loads the DLM that supplies it into memory. To see a list of the DLMs that IDL knows about, use HELP, /DLM_PATH (see "HELP" on page 571 for more information). !DLM_PATH is initialized from the environment variable IDL_DLM_PATH at startup. If the IDL_DLM_PATH environment variable is not defined, IDL supplies a default that contains the directory in the IDL distribution where the RSI supplied DLMs reside. This initialization is similar to that performed for IDL_PATH, (see "!PATH" on page 2433), including recursive path expansion denoted with a leading "+". Once !DLM_PATH is expanded, IDL uses it as the list of places to look for DLM definition files. Since all DLM searching happens once at startup time, it would be meaningless to change the value of !DLM_PATH afterwards. For this reason, it is a read-only system variable and cannot be assigned to. The value of !DLM_PATH is useful because it shows you where IDL looked for DLMs when it started. NAME: !EDIT_INPUT An integer variable indicating whether keyboard line editing is enabled (when set to a non-zero value) or disabled (when set to zero). By default, !EDIT_INPUT is set equal to one, and line editing is enabled. By default, IDL saves the last 20 command lines. You can change the number of command lines saved in the recall buffer by setting !EDIT_INPUT equal to the number of lines you would like to save. In order for the change to take effect, IDL must be able to process the assignment statement before providing a command prompt. This means that you must put the assignment statement in the IDL startup file. (See "Startup File" in Chapter 2 of Using IDL for more information on startup files.) NAME: !HELP_PATH A string variable listing the directories IDL will search for online help files. The default is the help subdirectory of the main IDL directory. The default can be changed by setting the IDL_HELP_PATH environment variable or logical name under UNIX or VMS, or by specifying the desired help path using the DEFSYSV command under Microsoft Windows or the Macintosh OS. NAME: !JOURNAL A read-only long-integer variable containing the logical unit number of the file used for journal output. NAME: !MAKE_DLL The MAKE_DLL procedure and CALL_EXTERNAL function's AUTO_GLUE keyword use the standard system C compiler and linker to generate sharable libraries that can be used by IDL in various contexts (CALL_EXTERNAL, DLMs, LINKIMAGE). There is a great deal of variation possible in the use of these tools between different platforms, operating system versions, and compiler releases. The !MAKE_DLL system variable is used to configure how IDL uses them for the current platform. The !MAKE_DLL structure is defined as follows: { !MAKE_DLL, COMPILE_DIRECTORY:'', COMPILER_NAME:'', CC:'', LD:''} The meaning of the fields of !MAKE_DLL are given in Table D-2. When expanding !MAKE_DLL.CC and !MAKE_DLL.LD, IDL substitutes text in place of the PRINTF style codes described in the following table. These codes are case- insensitive, and can be either upper or lower case. Note It is possible to use C compilers other than the one assumed by RSI in !MAKE_DLL to build sharable libraries. To do so, you can alter the contents of !MAKE_DLL or use the CC and/or LD keyword to MAKE_DLL and CALL_EXTERNAL. Please understand that RSI cannot and does not maintain a list of all possible compilers and the necessary compiler options. This information is available in your compiler and system documentation. It is the programmers responsibility to understand the rules for their chosen compiler. Field Meaning COMPILE_DIRECTORY IDL requires a place to create the intermediate files necessary to build a sharable library, and possibly the final library itself. Unless told to use an explicit directory, it uses the directory given by the COMPILE_DIRECTORY field of !MAKE_DLL. If the IDL_MAKE_DLL_COMPILE_DIRECTORY environment variable is set, IDL uses its value to initialize the COMPILE_DIRECTORY field. Otherwise, IDL supplies a standard location. Note - Note that if the directory given by !MAKE_DLL.COMPILE_DIRECTORY does not exist when IDL needs it, IDL automatically creates it for you. COMPILER_NAME A string containing the name of the C compiler used by RSI to build the currently running IDL. This field is not used by IDL, and exists solely for informational purposes and to help the end user decide which C compiler to install on their system. CC A string used by IDL as a template to construct the command for using the C compiler. This template uses PRINTF style substitution codes, as described in the following table. LD A string used by IDL as a template to construct the command for using the linker. This template uses PRINTF style substitution codes, as described in the following table. Table D-2: Meaning of !MAKE_DLL fields The following table describes the substitution codes for the CC and LD fields: Code Meaning %B %b The base name of a C file to compile. For example, if the C file is moose.c, then %B substitutes moose. %C %c The name of the C file. %E %e The name of the linker options file. This file, which is automatically generated by IDL as needed, is used to control the linker. Under UNIX, the system documentation refers to this as an export file, or a linker map file. VMS calls it a linker options file (.OPT). Microsoft Windows calls it a .DEF file. %F %f A floating point switch to C compiler. This is only meaningful under VMS, and corresponds to the VAX_FLOAT keyword to MAKE_DLL and CALL_EXTERNAL. %L %l The name of the resulting sharable library. IDL constructs this name by using the base name (%B) and adding the appropriate suffix for the current platform (.dll, .so, .sl, .exe, ...). %O %o An object file name. IDL constructs this name by using the base name (%B) and adding the appropriate suffix for the current platform (.o, .obj). %X %x When expanding !MAKE_DLL.CC, any text supplied via the EXTRA_CFLAGS keyword to MAKE_DLL or CALL_EXTERNAL is inserted in place of %X. IDL does not interpret this text. It is the users responsibility to ensure that it is meaningful in the command. When expanding !MAKE_DLL.LD, the text from the EXTRA_LFLAGS keyword is substituted. The primary use for this code is to include necessary header include directories and link libraries. %% Replaced with a single % character. Table D-3: Description of CC and LD Field Codes NAME: !MORE An integer variable indicating whether IDL should paginate help output sent to a tty device. Setting !MORE to zero (0) prevents IDL from paginating the output text. A non-zero value (the default) causes IDL to display output text one screen at a time. NAME: !PATH A string variable listing the directories IDL will search for libraries, include files, and executive commands. UNIX !PATH is a colon-separated list of directories, similar in concept to the PATH environment variable which UNIX uses to locate commands. !PATH is initialized from the environment variable IDL_PATH when IDL starts. Note that directories that do not contain at least one .pro or .sav file will not be included in !PATH, even if they are specified by the IDL_PATH environment variable. This initial value can be changed, as desired, once in IDL. For example, the following statement adds the directory /usr2/project/idl_files to the beginning of the search path: !path = '/usr2/project/idl_files:' + !path To specify a directory tree that includes all of that directory's subdirectories, use the EXPAND_PATH function. Each user can assign IDL_PATH to a series of directories that are searched for IDL programs, procedures, functions, and "include" files. It is convenient to set up this variable in your ~/.cshrc: setenv IDL_PATH ~/idl_lib:/usr/local/rsi/idl/lib or ~/.profile: /rsi/idl/lib ; export IDL_PATH This causes IDL to search for programs first in the current directory, then in your idl/lib directory, and then in the system-wide directory /usr/local/rsi/ idl/lib. If IDL_PATH is not defined, IDL initializes !PATH to the default value +/usr/ local/rsi/idl. Note that the current directory is always searched before consulting !PATH. VMS !PATH is a comma-separated list of directories and text libraries. Text libraries are distinguished by prepending a "@" character to their name. !PATH is initialized from the logical name IDL_PATH when IDL starts. Note that directories that do not contain at least one .pro or .sav file will not be included in !PATH, even if they are specified by the IDL_PATH logical. This initial value can be changed once in IDL as desired. For example, the following statement adds the directory DISKA:[PROJECTLIB] to the beginning of the search path: path = 'diska:[projectlib],' + !path To specify a directory tree that includes all of that directory's subdirectories, use the EXPAND_PATH function. Each user can assign IDL_PATH to a series of directories and text libraries that are searched in order for IDL programs, procedures, functions, and "include" files. It is convenient to set up this variable in your LOGIN.COM file. For example, DEFINE IDL_PATH "DISKA:[USER.ID causes IDL to search for programs first in the current directory, then in the directory DISKA:[USER.IDLLIB], and finally in the library of routines written in IDL and included in the standard IDL distribution, which is supplied as a VMS text library. Note that the current directory is always searched before consulting !PATH. The logical IDL_PATH also can be defined as a multi-valued logical name (e.g., a search list logical). Therefore, the above example also can be written as follows: DEFINE IDL_PATH DISKA:[USER.IDL IDL simply takes the various translations and concatenates them together into a comma-separated list. Note that the quotes around the second translation in this example are necessary to keep DCL from seeing the "@" character as an invitation to execute a command file. Windows !PATH is a semicolon-separated list of directories, similar in concept to the PATH environment variable DOS uses to locate commands. !PATH is initialized from the saved IDL for Windows preferences data, or from a DOS environment variable IDL_PATH, when IDL starts. Note that directories that do not contain at least one .pro or .sav file will not be included in !PATH, even if they are specified by the preferences data or the IDL_PATH environment variable. Change the path settings by adding to or altering the list of directories in the "Path" dialog, found under the "Preferences" selection of the IDL for Windows File menu, or by changing the value of !PATH from the IDL command prompt. To specify a directory tree that includes all of that directory's subdirectories, use the EXPAND_PATH function. Macintosh !PATH is a comma-separated list of folders. !PATH is initialized from the saved IDL for Macintosh preferences data when IDL starts. Note that folders that do not contain at least one .pro or .sav file will not be included in !PATH, even if they are specified by the preferences data. Change the path settings by adding to or altering the list of directories in the "Search Path" dialog, found in the IDL for Macintosh File menu, or by changing the value of !PATH from the IDL command prompt. Use the following syntax is used to specify Macintosh path locations: * Filenames are specified as a colon-separated list of drive names and folders. * Folder and file names can contain spaces and/or commas. Thus, the file myprogram.pro, located in the folder named Programs which resides on the drive named Macintosh HD would be specified: 'Macintosh HD:Programs:myprogram.pro' To specify a directory tree that includes all of that directory's subdirectories, use the EXPAND_PATH function. A Note on Order within !PATH IDL ensures only that all directories containing IDL files are placed in !PATH. The order in which they appear is completely unspecified, and does not necessarily correspond to any specific order (such as top-down alphabetized). This allows IDL to construct the path in the fastest possible way and speeds startup. This is only a problem if two subdirectories in such a hierarchy contain a file with the same name. Such hierarchies usually are a collection of cooperative routines designed to work together, so such duplication is rare. If the order in which "+" expands directories is a problem for your application, you should add the directories to the path explicitly and not use "+". Only the order of the files within a given "+" entry are determined by IDL. It never reorders !PATH in any other way. You can therefore obtain any search order you desire by writing the path explicitly. NAME: !PROMPT A string variable containing the text string used by IDL to prompt the user for input. The default is IDL>. NAME: !QUIET A long-integer variable indicating whether informational messages should be printed (0) or suppressed (nonzero). By default, !QUIET is set to zero. NAME: !VERSION This variable has been changed by the addition of an OS_NAME field. A structure variable containing information about the version of IDL in use. The structure is defined as follows: {!VERSION, ARCH:'', OS:'', OS_FAMILY:'', RELEASE:'', $ BUILD_DATE:'', MEMORY_BITS:0, FILE_OFFSET_BITS:0 }} The meaning of the fields of !VERSION are given in the following table. Field Meaning ARCH CPU hardware architecture of the system. OS The vendor name of the operating system (for example: AIX, HP-UX, IRIX, linux, MacOS, OSF, sunos, VMS, Win32). RSI recommends that you first consider using the OS_FAMILY field before using the OS field, as most programs are mainly concerned with high level platform differences. OS_FAMILY The generic name of the operating system (MacOS, UNIX, VMS, Windows). RELEASE IDL version number. BUILD_DATE The date the IDL executable was compiled, in the format dictated by ANSI C for the __DATE__ macro. MEMORY_BITS The number of bits used to address memory. Possible values are 32 or 64. The number of bits used to address memory places a theoretical upper limit on the amount of memory available to IDL. FILE_OFFSET_BITS The number of bits used to position file offsets. Possible values are 32 or 64. The number of bits used to position files places a theoretical upper limit on the largest file IDL can access. Table D-4: Meaning of the !VERSION Fields If you need to differentiate between different IDL versions in your code, use !VERSION.OS_FAMILY. At present, four operating system families are supported: MacOS, UNIX, VMS, Windows. For even more detail, you can use !VERSION.OS. CDF_ATTEXISTS [Previous Routine] [Next Routine] [List of Routines] NAME: CDF_ATTEXISTS The CDF_ATTEXISTS function returns TRUE (1) if the specified attribute exists in the specified CDF file, or FALSE (0) if it does not exist. Attributes may be specified by name or number. Syntax Result = CDF_ATTEXISTS( Id, Attribute [, EntryNum] [, /ZVARIABLE] ) Arguments Id The CDF ID of the file containing the Attribute to be checked, returned from a previous call to CDF_OPEN or CDF_CREATE. Attribute A string containing the name or zero-based attribute number of the attribute to be checked. EntryNum The entry number to confirm. If EntryNum is not specified, the entire file is searched for the specified attribute. If the attribute is variable in scope, this is either the name or number of the variable the attribute is to be associated with. If the attribute is global in scope, this is the actual gEntry. It is the user's responsibility to keep track of valid gEntry numbers. Normally gEntry numbers will begin with 0 or 1 and will increase up to MAXGENTRY (as reported in the GET_ATTR_INFO structure returned by CDF_CONTROL), but this is not required. Keywords ZVARIABLE If EntryNum is a variable ID (as opposed to a variable name) and the variable is a zVariable, set this flag to indicate that the variable ID is a zVariable ID. The default is to assume that EntryNum is an rVariable ID. Note: the attribute must have a scope of VARIABLE_SCOPE. Example Create a function to test an attribute's existence and return a string: FUNCTION exists, cdfid, attname_or_number IF CDF_ATTEXISTS(cdfid, attname_or_number) THEN $ RETURN,' Attribute Exists' ELSE $ RETURN,' Attribute Does Not Exist' END ; Create a CDF with 2 attributes: cdfid = CDF_CREATE('DEMOattexists') attr1_id = CDF_ATTCREATE(cdfid, 'GLOBAL_ATT' , /GLOBAL_SCOPE) attr2_id = CDF_ATTCREATE(cdfid, 'VARIABLE_ATT', /VARIABLE_SCOPE) ; Check the existence of the two attributes, plus a third that ; does not exist: PRINT, EXISTS(cdfid, attr1_id) PRINT, EXISTS(cdfid, 1) PRINT, EXISTS(cdfid, 'BAD ATTR') CDF_DELETE, cdfid IDL Output Attribute Exists Attribute Exists Attribute Does Not Exist See Also CDF_ATTCREATE, CDF_ATTGET, CDF_ATTDELETE, CDF_ATTINQ, CDF_ATTPUT, CDF_ATTRENAME CDF_ATTGET [Previous Routine] [Next Routine] [List of Routines] NAME: CDF_ATTGET The CDF_ATTGET procedure reads an attribute entry from a Common Data Format file. Syntax CDF_ATTGET, Id, Attribute, EntryNum, Value [, CDF_TYPE= variable] [, /ZVARIABLE] Arguments Id The CDF ID, returned from a previous call to CDF_OPEN or CDF_CREATE. Attribute A string containing the name of the attribute or the attribute number to be written. EntryNum The entry number. If the attribute is variable in scope, this is either the name or number of the variable the attribute is to be associated with. If the attribute is global in scope, this is the actual gEntry. It is the user's responsibility to keep track of valid gEntry numbers. Normally, gEntry numbers will begin with 0 or 1 and will increase up to MAXGENTRY (as reported in the GET_ATTR_INFO structure returned by CDF_CONTROL), but this is not required. Value A named variable in which the value of the attribute is returned. Keywords CDF_TYPE Set this keyword equal to a named variable that will contain the CDF type of the attribute entry, returned as a scalar string. Possible returned values are: CDF_CHAR, CDF_UCHAR, CDF_INT1, CDF_BYTE, CDF_UINT1, CDF_UINT2, CDF_INT2, CDF_UINT4, CDF_INT4, CDF_REAL4, CDF_FLOAT, CDF_REAL8, CDF_DOUBLE, or CDF_EPOCH. If the type cannot be determined, "UNKNOWN" is returned. Note that, as is true with variable data, attribute entries of type CDF_INT1, CDF_BYTE, CDF_UINT2, and CDF_UINT4 are converted into IDL supported datatypes (for example, data of type CDF_UINT2, data of the C-type unsigned short, is converted into IDL's INT, a signed integer. So, an attribute that is 65535 as a CDF_UINT2 will appear as INT = -1 in IDL). In these cases, pay special attention to the return values. ZVARIABLE If EntryNum is a variable ID (as opposed to a variable name) and the variable is a zVariable, set this flag to indicate that the variable ID is a zVariable ID. The default is to assume that EntryNum is an rVariable ID. Note: the attribute must have a scope of VARIABLE_SCOPE. Example ; Open the CDF file created in the CDF_ATTPUT example: id = CDF_OPEN('foo') CDF_ATTGET, id, 'Att2', 'Var2', x PRINT, X, FORMAT='("[",9(X,F3.1,","),X,F3.1,"]")' CDF_CLOSE, id ; Close the CDF file. IDL Output [ 0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0] This is the expected output, since this attribute was created with a call to FINDGEN. CDF_ATTINQ [Previous Routine] [Next Routine] [List of Routines] NAME: CDF_ATTINQ The CDF_ATTINQ procedure obtains information about a specified attribute in a Common Data Format file. Syntax CDF_ATTINQ, Id, Attribute, Name, Scope, MaxEntry [, MaxZEntry] Arguments Id The CDF ID of the file containing the desired attribute, returned from a previous call to CDF_OPEN or CDF_CREATE. Attribute A string containing either the name or number of the attribute to be inquired. Name A named variable in which the name of the attribute is returned. Scope A named variable in which a string, describing the scope of the attribute, is returned. This string will have one of the following values: "GLOBAL_SCOPE", "VARIABLE_SCOPE", "GLOBAL_SCOPE_ASSUMED", or "VARIABLE_SCOPE_ASSUMED". MaxEntry A named variable in which the maximum rVariable entry number for this attribute is returned. MaxZEntry A named variable in which the maximum zVariable entry number for this attribute is returned. Example cdfid= CDF_OPEN('/cdrom/ozone.8.20.92') CDF_ATTINQ, cdfid, 0, name, scope, maxentry, maxzentry PRINT, name, scope, maxentry, maxzentry CDF_ATTNUM [Previous Routine] [Next Routine] [List of Routines] NAME: CDF_ATTNUM The CDF_ATTNUM function returns the attribute number associated with a particular attribute in a Common Data Format file. Syntax Result = CDF_ATTNUM(Id, Attribute_Name) Arguments Id The CDF ID for the file that contains the desired attribute, returned from a previous call to CDF_OPEN or CDF_CREATE. Attribute_Name A string containing the name of the attribute. Example See the example for "CDF_ATTPUT" on page 35. CDF_ATTPUT [Previous Routine] [Next Routine] [List of Routines] NAME: CDF_ATTPUT The CDF_ATTPUT procedure writes an attribute entry to a Common Data Format file, or attaches an attribute to a CDF variable. If the specified entry already exists, it is overwritten. Syntax CDF_ATTPUT, Id, Attribute, EntryNum, Value [, /ZVARIABLE] Arguments Id The CDF ID, returned from a previous call to CDF_OPEN or CDF_CREATE. Attribute A string containing either the name or number of the attribute to be written. EntryNum The entry number. If the attribute is variable in scope, this is either the name or number of the variable the attribute is to be associated with. If the attribute is global in scope, this is the actual gEntry. It is the user's responsibility to keep track of valid gEntry numbers. Normally gEntry numbers will begin with 0 or 1 and will increase up to MAXGENTRY (as reported in the GET_ATTR_INFO structure returned by CDF_CONTROL), but this is not required. Value The value(s) to be written. Keywords ZVARIABLE If EntryNum is a variable ID (as opposed to a variable name) and the variable is a zVariable, set this flag to indicate that the variable ID is a zVariable ID. The default is to assume that EntryNum is an rVariable ID. Note: the attribute must have a scope of VARIABLE_SCOPE. Examples Example 1 Id= CDF_CREATE('foo', /SUN_ENCODING, /HOST_DECODING, $ /ROW_MAJOR); no dimensions. dummy= CDF_VARCREATE(id, 'Var1', /CDF_INT4, /REC_VARY) v2= CDF_VARCREATE(id, 'Var2', /CDF_FLOAT, /REC_NOVARY) dummy= CDF_ATTCREATE(id, 'Title', /VARIABLE) global_dummy = CDF_ATTCREATE(id,'Date',/GLOBAL) dummy= CDF_ATTCREATE(id, 'Att2', /VARIABLE) CDF_ATTPUT, id, 'Title', 'Var1', 'Temperature at surface' CDF_ATTPUT, id, 'Title', v2, 'Time of recording' CDF_ATTPUT, id, 'Date',1,'July 4, 1996' CDF_ATTPUT, id, 'Att2', 'Var2', FINDGEN(10) ; Rename the "Att2" attribute to "Attribute2": CDF_ATTRENAME, Id, 'Att2', 'Attribute2' ; Verify the attribute number (zero-based) of Attribute2 PRINT, CDF_ATTNUM(id, 'Attribute2') ; Close the CDF file. This file is used in the CDF_ATTGET example. CDF_CLOSE, id IDL Output 1 Example 2 The following example uses the Global attribute "MODS" to keep track of the modification history of a CDF file named mods.cdf. id = CDF_CREATE('mods.cdf', /CLOBBER) cid = CDF_ATTCREATE(id, 'MODS', /GLOBAL_SCOPE) CDF_ATTPUT, id, cid, 0, 'Original Version' CDF_CLOSE, id ; Next, reopen the CDF file and make modifications: id = CDF_OPEN('mods.cdf') CDF_CONTROL, id, ATTRIBUTE='MODS', GET_ATTR_INFO=ginfo ;Use CDF_CONTROL to get the MAXGENTRY used. CDF_ATTPUT, id, cid, ginfo.maxgentry+1,'Second Version' ;Insert the new gEntry at MAXGENTRY+1. CDF_CLOSE, id ; Reopen the CDF file again and make more modifications: id = CDF_OPEN('mods.cdf') CDF_CONTROL, id, ATTRIBUTE='MODS', GET_ATTR_INFO=ginfo CDF_ATTPUT, id, cid, ginfo.maxgentry+1, 'Third Version' CDF_CLOSE, id ;Reopen the CDF file again and make a modification in the ;MAXGENTRY + 2 spot (skipping an entry number). id = CDF_OPEN('mods.cdf') CDF_CONTROL, id, ATTRIBUTE='MODS', GET_ATTR_INFO=ginfo CDF_ATTPUT, id, cid, ginfo.maxgentry+2, 'Fourth Version' ; Now, examine the CDF file to review its modification history. ; Since the gENTRY numbers have a gap in them, we can check each ; attribute with the CDF_ATTEXISTS function. This is a good idea ; if you do not know for certain that the attribute entries are ; serially numbered. CDF_CONTROL, id, ATTRIBUTE='MODS', GET_ATTR_INFO=ginfo FOR I=0, ginfo.maxgentry DO BEGIN IF CDF_ATTEXISTS(id, cid, I) THEN BEGIN CDF_ATTGET, id, cid, I, gatt PRINT, I, gatt, FORMAT='("Attribute: MODS (gENTRY #",i1,") = ",A)' ENDIF ELSE BEGIN PRINT, I, FORMAT='("Attribute: MODS (gENTRY #",i1,") $ Does not exist")' ENDELSE ENDFOR CDF_CLOSE, id IDL Output Attribute: MODS (gENTRY #0) = Original Version Attribute: MODS (gENTRY #1) = Second Version Attribute: MODS (gENTRY #2) = Third Version Attribute: MODS (gENTRY #3) Does not exist Attribute: MODS (gENTRY #4) = Fourth Version CDF_ATTRENAME [Previous Routine] [Next Routine] [List of Routines] NAME: CDF_ATTRENAME The CDF_ATTRENAME procedure is used to rename an existing attribute in a Common Data Format file. Syntax CDF_ATTRENAME, Id, OldAttr, NewName Arguments Id The CDF ID of the file containing the desired attribute, returned from a previous call to CDF_OPEN or CDF_CREATE. OldAttr A string containing the current name of the attribute or the attribute number to be renamed. NewName A string containing the new name for the attribute. Example See the example for "CDF_ATTPUT" on page 35. CDF_CLOSE [Previous Routine] [Next Routine] [List of Routines] NAME: CDF_CLOSE The CDF_CLOSE procedure closes the specified Common Data Format file. The CDF's data buffers are flushed, all of the CDF's open files are closed, and the CDF identifier is freed. You must use CDF_CLOSE to close a CDF file to guarantee that all modifications you have made are actually written to disk. Syntax CDF_CLOSE, Id Arguments Id The CDF ID of the file to be closed, returned from a previous call to CDF_OPEN or CDF_CREATE. Example ; Open a file: id = CDF_OPEN('open_close.cdf' ; ... Other CDF_ commands go here. ; Close the cdf file. CDF_CLOSE, id CDF_COMPRESSION [Previous Routine] [Next Routine] [List of Routines] NAME: CDF_COMPRESSION The CDF_COMPRESSION procedure sets or returns the compression mode for a CDF file and/or variables. Compression parameters should be set before values are written to the CDF file. Syntax CDF_COMPRESSION, Id [, GET_COMPRESSION=variable] [, GET_GZIP_LEVEL=variable] [, GET_VAR_COMPRESSION=variable] [, GET_VAR_GZIP_LEVEL=variable] [, SET_COMPRESSION={0 | 1 | 2 | 3 | 5}] [, SET_GZIP_LEVEL=integer{1 to 9}] [, SET_VAR_COMPRESSION={0 | 1 | 2 | 3 | 5}] [, SET_VAR_GZIP_LEVEL=integer{1 to 9}] [, VARIABLE=variable name or index] [, /ZVARIABLE] Arguments Id The CDF ID of the file being compressed or queried, as returned from a previous call to CDF_OPEN or CDF_CREATE. Note that CDF compression only works for single-file CDF files (see CDF_CREATE). Keywords GET_COMPRESSION Set this keyword to a named variable to retrieve the compression type used for the single-file CDF file. Note that individual CDF variables may compression types different that the one for the rest of the CDF file. GET_GZIP_LEVEL Set this keyword to a named variable in which the current GZIP effort level (1-9) for the CDF file is returned. If the compression type for the file is not GZIP (5), then a value of zero is returned. GET_VAR_COMPRESSION Set this keyword to a named variable to retrieve the compression type for the variable identified by the VARIABLE keyword. GET_VAR_GZIP_LEVEL Set this keyword to a named variable in which the GZIP effort level (1-9) for variable specified by the VARIABLE keyword is returned. If the compression type for the variable is not GZIP (5), then a value of zero is returned. SET_COMPRESSION Set this keyword to the compression type to be used for the single-file CDF file. Note that individual CDF variables may use compression types different than the one for the rest of the CDF file. Valid compression types are: * 0 = No Compression * 1 = Run-Length Encoding * 2 = Huffman * 3 = Adaptive Huffman * 5 = GZIP (see the optional GZIP_LEVEL keyword) SET_GZIP_LEVEL This keyword is used to indicate the desired effort for the GZIP compression. This effort must be expressed as a scalar in the range (1-9). If GZIP_LEVEL is not specified upon entry then the default effort level is taken to be 5. If the SET_GZIP_LEVEL keyword is set to a valid value, and the keyword SET_COMPRESSION is not specified, the SET_COMPRESSION is set to GZIP (5). SET_VAR_COMPRESSION Set this keyword to the compression type for the variable identified by the VARIABLE keyword. If the variable is a zVariable, and is referred to by index in the VARIABLE keyword, then the keyword ZVARIABLE must be set. The desired variable compression should be set before variable data is added with CDF_VARPUT. Valid compression types are: * 0 = No Compression * 1 = Run-Length Encoding * 2 = Huffman * 3 = Adaptive Huffman * 5 = GZIP (see the optional GZIP_LEVEL keyword) SET_VAR_GZIP_LEVEL Set this keyword to the GZIP effort level (1-9). If the compression type for the variable is not GZIP (5), no action is performed. VARIABLE Set this keyword to the name of a variable or a variable index to set the current variable. This keyword is mandatory when queering/setting the compression parameters of a rVariable or zVariable. Note that if VARIABLE is set to the index of a zVARIABLE, the ZVARIABLE keyword must also be set. If ZVARIABLE is not set, the variable is assumed to be an rVariable. ZVARIABLE Set this keyword if the current variable is a zVARIABLE and is referred to by index in the VARIABLE keyword. For example: CDF_COMPRESSION, id, VARIABLE=0, /ZVARIABLE,$ GET_VAR_COMPRESSION=vComp Special Note About Temporary File Location CDF creates temporary files whenever files/variables are compressed or uncompressed. By default, these files are created in the current directory. UNIX users can set the environment variable CDF_TMP to set the temporary directory explicitly. VMS users can similarly set the logical name CDF$TMP to an alternate scratch file directory. Example ; Create a CDF file and define the compression. ; Compression only works on Single-File CDFs: id=CDF_CREATE('demo.cdf',[10,20],/CLOBBER,/SINGLE_FILE) SION=1 ; (Run-length encoding) att_id=CDF_ATTCREATE(id, 'Date',/GLOBAL) CDF_ATTPUT,id,'Date',att_id,systime() ; Change the compression type for the file to GZIP by using ; SET_GZIP_LEVEL: CDF_COMPRESSION,id,SET_GZIP_LEVEL=7 ; Retrieve compression information: HELP,glevel,gcomp ; Create and compress an rVariable: rid=CDF_VARCREATE(id,'rvar0',[1,1],/CDF_FLOAT) CDF_COMPRESSION,id,SET_VAR_COMPRESSION=2,VARIABLE='rvar0' CDF_VARPUT,id,'rvar0',findgen(10,20,5) _GZIP_LEVEL=v_glevel HELP,v_comp,v_glevel ; Create and compress a zVariable: /CDF_DOUBLE) ; You can set a compression and check it in the same call: GET_VAR_GZIP_LEVEL=v_gzip HELP,v_gzip CDF_VARPUT,id,zid,dindgen(10,20,30),/ZVARIABLE ; File and variable keywords can be combined in the same call ; (Set calls are processed before Get calls) /ZVARIABLE, SET_COMPRESSION=2,GET_COMPRESSION=file_comp HELP,file_comp,v_comp CDF_DELETE,id IDL Output GLEVEL LONG = 7 GCOMP LONG = 5 V_COMP LONG = 2 V_GLEVEL LONG = 0 (Note that V_GLEVEL is 0, since the variable compression is not GZIP.) V_GZIP LONG = 9 FILE_COMP LONG = 2 V_COMP LONG = 5 See Also CDF_CONTROL, CDF_CREATE, CDF_OPEN, CDF_VARNUM CDF_CONTROL [Previous Routine] [Next Routine] [List of Routines] NAME: CDF_CONTROL The CDF_CONTROL procedure allows you to obtain or set information for a Common Data Format file, its variables, and its attributes. Syntax CDF_CONTROL, Id [, ATTRIBUTE=name or number] [, GET_ATTR_INFO=variable] [, GET_CACHESIZE=variable] [, GET_COPYRIGHT=variable] [, GET_FILENAME=variable] [, GET_FORMAT=variable] [, GET_NEGTOPOSFP0_MODE=variable] [, GET_NUMATTRS=variable] [, GET_READONLY_MODE=variable] [, GET_RVAR_CACHESIZE=variable] [, GET_VAR_INFO=variable] [, GET_ZMODE=variable] [, GET_ZVAR_CACHESIZE=variable] [, SET_CACHESIZE=value] [, SET_EXTENDRECS=records] [, SET_INITIALRECS=records] [, /SET_NEGTOPOSFP0_MODE] [, SET_PADVALUE=value] [, /SET_READONLY_MODE] [, SET_RVAR_CACHESIZE=value{See Note}] [, SET_RVARS_CACHESIZE=value{See Note}] [, SET_ZMODE={0 | 1 | 2}] [, SET_ZVAR_CACHESIZE=value{See Note}] [, SET_ZVARS_CACHESIZE=value{See Note}] [, VARIABLE=name or index] [, /ZVARIABLE] Note: Use only with MULTI_FILE CDF files Arguments Id The CDF ID of the file being changed or queried, as retuned from a previous call to CDF_OPEN or CDF_CREATE. Keywords ATTRIBUTE Makes the attribute specified the current attribute. Either an attribute name or an attribute number may be specified. GET_ATTR_INFO Set this keyword to a named variable that will contain information about the current attribute. Information is returned in the form of a structure with the following tags: { NUMGENTRIES:0L, NUMRENTRIES:0L, NUMZENTRIES:0L, MAXGENTRY:0L, MAXRENTRY:0L, MAXZENTRY:0L } The first three tags contain the number of globals, rVariables, and zVariables associated with the attribute. MAXGENTRY contains the highest index used, and the last two tags contain the highest variable ids that were used when setting the attribute's value. Note that an attribute must be set before GET_ATTR_INFO can be used. For example: CDF_CONTROL, id, ATTRIBUTE='ATT1', GET_ATTR_INFO=X GET_CACHESIZE Set this keyword to a named variable that will be set equal to the number of 512-byte cache buffers being used for the current .cdf file. For discussion about using caches with CDF files, see section 2.1.4 ("Caching Scheme") of the version 2.6 CDF User's Guide. GET_COPYRIGHT Set this keyword to a named variable that will contain the copyright notice of the CDF library now being used by IDL (as opposed to the library that was used to write the current CDF). GET_FILENAME Set this keyword to a named variable that will contain the pathname of the current .cdf file. GET_FORMAT Set this keyword to a named variable that will contain a string describing the CDF Format of the current CDF file. Possible formats are SINGLE_FILE and MULTI_FILE, and can only be set with the CDF_CREATE procedure. For example: id = CDF_CREATE('single', /SINGLE_FILE) CDF_CONTROL, id, GET_FORMAT = cdfformat HELP, cdfformat IDL prints: CDFFORMAT STRING = 'SINGLE_FILE' GET_NEGTOPOSFP0_MODE Set this keyword to a named variable that will be set equal to the CDF negative to positive floating point 0.0 (NEGtoPOSfp0) mode. In NEGtoPOSfp0 mode, values equal to -0.0 will be converted to 0.0 whenever encountered. By CDF convention, a returned value of -1 indicates that this feature is enabled, and a returned value of zero indicates that this feature is disabled. GET_NUMATTRS Set this keyword to a named variable that will contain a two-element array of longs. The first value will contain the number of attributes with global scope; the second value will contain the number of attributes with variable scope. NOTE: attributes with GLOBAL_SCOPE_ASSUMED scope will be included in the global scope count and attributes with VARIABLE_SCOPE_ASSUMED will be included in the count of attributes with variable scope. Note that you can obtain the total number of attributes using the CDF_INQUIRE routine. GET_RVAR_CACHESIZE Set this keyword to a named variable that will be set equal to the number of 512-byte cache buffers being used for the current MULTI_FILE format CDF and the rVariable indicated by the VARIABLE keyword. This keyword should only be used for MULTI_FILE CDF files. For discussion about using caches with CDF files, see section 2.1.4 ("Caching Scheme") of the version 2.6 CDF User's Guide. GET_READONLY_MODE Set this keyword to a named variable that will be set equal to the CDF read-only mode. By CDF convention, a returned value of -1 indicates that the file is in read- only mode, and a returned value of zero indicates that the file is not in read-only mode. GET_VAR_INFO Set this keyword to a named variable that will contain information about the current variable. For detailed information about the returned values, consult section 2.3.8 ("RECORDS") of the version 2.6 CDF User's Guide. Information is returned in the form of a structure with the following tags: { EXTENDRECS:0L, MAXALLOCREC:0L, MAXREC:0L, MAXRECS:0L, NINDEXENTRIES:0L, NINDEXRECORDS:0L, PADVALUE: } The EXTENDRECS field will contain the number of records by which the current variable will be extended whenever a new record needs to be added. The MAXALLOCREC field will contain the maximum record number (zero-based) allocated for the current variable. Records can only be allocated for NOVARY zVariables in SINGLE_FILE format CDFs. When these conditions are not met, the value is set to -1. The MAXREC field will contain the maximum record number for the current variable. For variables with a record variance of NOVARY, this will be at most zero. A value of -1 indicates that no records have been written. The MAXRECS field will contain the maximum record number (zero-based) of all variables of this type (rVariable or zVariable) in the current CDF. A value of -1 indicates that no records have been written. The NINDEXENTRIES field will contain the number of index entries for the current variable in the current CDF. This value is -1 unless the current CDF is of SINGLE_FILE format, and the variable is a zVariable. The NINDEXRECORDS field will contain the number of index records for the current variable in the current CDF. This value is -1 unless the current CDF is of SINGLE_FILE format, and the variable is a zVariable. The PADVALUE field will contain the value being used to fill locations that are not explicitly filled by the user. If a PADVALUE is not specified, CDF_CONTROL returns an error. For example: fid = CDF_CREATE('test.cdf') varid = CDF_VARCREATE(fid, 'test') CDF_CONTROL, fid, GET_VAR_INFO=info, VARIABLE='test' IDL Prints: % CDF_CONTROL: Function completed but NO_PADVALUE_SPECIFIED: A pad value has not been specified. GET_ZMODE Set this keyword to a named variable that will be set equal the zMode of the current CDF. In a non-zero zMode, CDF rVariables are temporarily replaced with zVariables. The possible return values are: * 0 = zMode is off. * 1 = zMode is on in zMode/1, indicating that the dimensionality and variances of the variables will stay the same. * 2 = zMode is on in zMode/2, indicating that those dimensions with false variances (NOVARY) will be eliminated. For Information about zModes, consult Section 2.1.2 of the version 2.6 CDF User's Guide. GET_ZVAR_CACHESIZE Set this keyword to a named variable that will be set equal to the number of 512-byte cache buffers being used in the current MULTI_FILE format CDF and the zVariable indicated by the VARIABLE keyword. This keyword should only be used with MULTI_FILE CDF files. For discussion about using caches with CDF files, see section 2.1.4 ("Caching Scheme") of the version 2.6 CDF User's Guide. SET_CACHESIZE Set this keyword equal to the desired number of 512-byte cache buffers to used for the current .cdf file. For discussion about using caches with CDF files, see section 2.1.4 ("Caching Scheme") of the version 2.6 CDF User's Guide. SET_EXTENDRECS Set this keyword equal to the number of additional physical records that should be added to the current variable whenever it needs to be extended. SET_INITIALRECS Set this keyword equal to the number of records that should be initially written to the current variable. Note that this keyword should be set before writing any data to the variable. SET_NEGTOPOSFP0_MODE Set this keyword to a non-zero value to put the current CDF file into negative to positive floating point 0.0 (NEGtoPOSfp0) mode. In this mode, values equal to -0.0 will be converted to 0.0 whenever encountered. Setting this keyword equal to zero takes the current CDF file out of NEGtoPOSfp0 mode. SET_PADVALUE Set this keyword equal to the pad value for the current variable. SET_READONLY_MODE Set this keyword to a non-zero value to put the current CDF file into read-only mode. Set this keyword equal to zero to take the current CDF file out of read-only mode. SET_RVAR_CACHESIZE Set this keyword equal to the desired number of 512-byte cache buffers to used for the rVariable file specified by the VARIABLE keyword. This keyword should only be used with MULTI_FILE CDF files. For discussion about using caches with CDF files, see section 2.1.4 ("Caching Scheme") of the version 2.6 CDF User's Guide. SET_RVARS_CACHESIZE Set this keyword equal to the desired number of 512-byte cache buffers to used for all rVariable files in the current CDF file or files. This keyword should only be used with MULTI_FILE CDF files. For discussion about using caches with CDF files, see section 2.1.4 ("Caching Scheme") of the version 2.6 CDF User's Guide. SET_ZMODE Set this keyword to change the zMode of the current CDF. In a non-zero zMode, CDF rVariables are temporarily replaced with zVariables. Set this keyword to one (1) to change to zMode/1, in which the dimensionality and variances of the variables stay the same. Set this keyword to two (2) to change to zMode/2, in which those dimensions with false variances (NOVARY) are eliminated. For Information about zModes, consult Section 2.1.2 of the version 2.6 CDF User's Guide. SET_ZVAR_CACHESIZE Set this keyword equal to the desired number of 512-byte cache buffers to used for the zVariable's file specified by the VARIABLE keyword. This keyword should only be used with MULTI_FILE CDF files. For discussion about using caches with CDF files, see section 2.1.4 ("Caching Scheme") of the version 2.6 CDF User's Guide. SET_ZVARS_CACHESIZE Set this keyword equal to the desired number of 512-byte cache buffers to used for all zVariable files in the current CDF. This keyword should only be used with MULTI_FILE CDF files. For discussion about using caches with CDF files, see section 2.1.4 ("Caching Scheme" of the version 2.6 CDF User's Guide. VARIABLE Set this keyword to a name or index to set the current variable. The following example specifies that the variable MyData should have 20 records written to it initially: CDF_CONTROL, id, VAR='MyData', SET_INITIALRECS=20 Note that if VARIABLE is set to the index of a zVariable, the ZVARIABLE keyword must also be set. If ZVARIABLE is not set, the variable is assumed to be an rVariable. ZVARIABLE Set this keyword to TRUE if the current variable is a zVariable and is referred to by index. For example: CDF_CONTROL, id, VARIABLE=0, /ZVARIABLE, GET_VAR_INFO=V See Also CDF_CREATE, CDF_INQUIRE CDF_CREATE [Previous Routine] [Next Routine] [List of Routines] NAME: CDF_CREATE The CDF_CREATE function creates a new Common Data Format file with the given filename and dimensions. If successful, this function returns the CDF ID for the new file. Note that when you create a CDF file, you must specify both encoding and decoding methods. Encoding specifies the method used to write data to the CDF file. Decoding specifies the method used to retrieve data from the CDF file and pass it to an application (IDL, for example). Encoding and decoding methods are specified by setting the XXX_ENCODING and XXX_DECODING keywords to CDF_CREATE. If no decoding method is specified, the decoding method is set to be the same as the encoding method. All CDF encodings and decodings can be written or read on all platforms, but matching the encoding with the architecture used provides the best performance. If you work in a single-platform environment most of the time, select HOST_ENCODING for maximum performance. If you know that the CDF file will be transported to a computer using another architecture, specify the encoding for the target architecture or specify NETWORK_ENCODING (the default). Specifying the target architecture provides maximum performance on that architecture; specifying NETWORK_ENCODING provides maximum flexibility. For more discussion on CDF encoding/decoding methods and combinations, see sections 2.2.7 ("Encoding") and 2.2.8 ("Decoding") of the version 2.6 CDF User's Guide. Syntax Result = CDF_CREATE( Filename, [Dimensions] [, /CLOBBER] [, /MULTI_FILE | , /SINGLE_FILE] [, /COL_MAJOR | , /ROW_MAJOR] ) Encoding Keywords (pick one): [, /ALPHAOSF1_ENCODING] [, /ALPHAVMSD_ENCODING] [, /ALPHAVMSG_ENCODING] [, /DECSTATION_ENCODING] [, /HOST_ENCODING] [, /HP_ENCODING] [, /IBMRS_ENCODING] [, /IBMPC_ENCODING] [, /MAC_ENCODING] [, /NETWORK_ENCODING] [, /NEXT_ENCODING] [, /SGI_ENCODING] [, /SUN_ENCODING] Decoding Keywords (pick one): [, /ALPHAOSF1_DECODING] [, /ALPHAVMSD_DECODING] [, /ALPHAVMSG_DECODING] [, /DECSTATION_DECODING] [, /HOST_DECODING] [, /HP_DECODING] [, /IBMRS_DECODING] [, /IBMPC_DECODING] [, /MAC_DECODING] [, /NETWORK_DECODING] [, /NEXT_DECODING] [, /SGI_DECODING] [, /SUN_DECODING] Arguments Filename A scalar string containing the name of the file to be created. Note that if the desired filename has a .cdf ending, you can omit the extension and specify just the first part of the filename. For example, specifying "mydata" would open the file mydata.cdf. Dimensions A vector of values specifying size of each rVariable dimension. If no dimensions are specified, the file will contain a single scalar per record (i.e., a 0-dimensional CDF). Keywords CLOBBER Set this keyword to erase the existing file (if the file already exists) before creating the new version. Note that if the existing file has been corrupted, the CLOBBER operation may fail, causing IDL to display an error message. In this case you must manually delete the existing file from outside IDL. COL_MAJOR Set this keyword to use column major (IDL-like) array ordering for variable storage. MULTI_FILE Set this keyword to cause all CDF control information and attribute entry data to be placed in one .cdf file, with a separate file created for each defined variable. If the variable in an rVariable, then the variable files will have extensions of .v0, .v1, etc.; zVariables will be stored in files with extensions of .z0, .z1, etc. This is the default format, and is usually more efficient than the SINGLE_FILE format. See section 2.2.7 ("Format") in the version 2.6 CDF User's Guide for more information. If both SINGLE_FILE and MULTI_FILE are set the file will be created in the MULTI_FILE format. MULTI_FILE Example: id=CDF_CREATE('multi', /MULTI_FILE) CDF_CONTROL, id, GET_FORMAT=cdf_format HELP, cdf_format IDL prints: CDF_FORMAT STRING = 'MULTI_FILE' ROW_MAJOR Set this keyword to specify row major (C-like) array ordering for variable storage. This is the default. SINGLE_FILE Set this keyword to cause all CDF information (control information, attribute entry data, variable data, etc.) to be written to a single .cdf file. The default is to use the MULTI_FILE format where a separate file is created for each variable. See section 2.2.7 ("Format") of the version 2.6 CDF User's Guide for more information. Encoding Keywords Select one of the following keywords to specify the type of encoding: ALPHAOSF1_ENCODING Set this keyword to indicate DEC ALPHA/OSF1 data encoding. ALPHAVMSD_ENCODING Set this keyword to indicate DEC ALPHA/VMS data encoding using Digital's D_FLOAT representation. ALPHAVMSG_ENCODING Set this keyword to indicate DEC ALPHA/VMS data encoding using Digital's G_FLOAT representation. DECSTATION_ENCODING Set this keyword to select Decstation (MIPSEL) data encoding. HOST_ENCODING Set this keyword to select that the file will use native data encoding. HP_ENCODING Set this keyword to select HP 9000 data encoding. IBMPC_ENCODING Set this keyword to select IBM PC data encoding. IBMRS_ENCODING Set this keyword to select IBM RS/6000 series data encoding. MAC_ENCODING Set this keyword to select Macintosh data encoding. NETWORK_ENCODING Set this keyword to select network-transportable data encoding (XDR). This is the default method. NEXT_ENCODING Set this keyword to select NeXT data encoding. SGI_ENCODING Set this keyword to select SGI (MIPSEB) data encoding (Silicon Graphics Iris and Power series). SUN_ENCODING Set this keyword to select SUN data encoding. Decoding Keywords Select one of the following keywords to specify the type of decoding: ALPHAOSF1_DECODING Set this keyword to indicate DEC ALPHA/OSF1 data decoding. ALPHAVMSD_DECODING Set this keyword to indicate DEC ALPHA/VMS data decoding using Digital's D_FLOAT representation. ALPHAVMSG_DECODING Set this keyword to indicate DEC ALPHA/VMS data decoding using Digital's G_FLOAT representation. DECSTATION_DECODING Set this keyword to select Decstation (MIPSEL) data decoding. HOST_DECODING Set this keyword to select that the file will use native data decoding. HP_DECODING Set this keyword to select HP 9000 data decoding. IBMPC_DECODING Set this keyword to select IBM PC data decoding. IBMRS_DECODING Set this keyword to select IBM RS/6000 series data decoding. MAC_DECODING Set this keyword to select Macintosh data decoding. NETWORK_DECODING Set this keyword to select network-transportable data decoding (XDR). This is the default method. NEXT_DECODING Set this keyword to select NeXT data decoding. SGI_DECODING Set this keyword to select SGI (MIPSEB) data decoding (Silicon Graphics Iris and Power series). SUN_DECODING Set this keyword to select SUN data decoding. Example Use the following command to create a 10-element by 20-element CDF using network encoding and Sun decoding: id = CDF_CREATE('cdf_create.cdf', [10,20], /NETWORK_ENCODING, $ /SUN_DECODING) ; ... other cdf commands ... CDF_CLOSE, id ; close the file. Now suppose that we decide to use HP_DECODING instead. We can use the CLOBBER keyword to delete the existing file when creating the new file: id = CDF_CREATE('cdf_create.cdf', [10,20], /NETWORK_ENCODING, $ /HP_DECODING, /CLOBBER) ; ... other cdf commands ... CDF_CLOSE, id ; close the file. The new file is written over the existing file. Use the following command to delete the file: CDF_DELETE, id CDF_DELETE [Previous Routine] [Next Routine] [List of Routines] NAME: CDF_DELETE The CDF_DELETE procedure deletes the specified Common Data Format file. Files deleted include the original .cdf file and the .v0, .v1, etc. files if they exist. Syntax CDF_DELETE, Id Arguments Id The CDF ID of the file to be deleted, returned from a previous call to CDF_OPEN or CDF_CREATE. Example id = CDF_OPEN('open_close.cdf'); Open a file. ; ... other CDF_ commands ... CDF_DELETE, id ; Close and Delete the cdf file. CDF_DOC [Previous Routine] [Next Routine] [List of Routines] NAME: CDF_DOC The CDF_DOC procedure retrieves general documentation information about a Common Data Format file. Syntax CDF_DOC, Id, Version, Release, Copyright [, INCREMENT=variable] Arguments Id A CDF ID, returned from a previous call to CDF_OPEN or CDF_CREATE. Version A named variable in which the version number of the CDF library that created the CDF is returned. Release A named variable in which the release number of the CDF library that created the CDF is returned. Copyright A named variable in which the copyright notice of the CDF library that created the CDF is returned. Keywords INCREMENT Set this keyword to a named variable that will contain the increment of the CDF library that created the specified CDF file. Example id=CDF_CREATE('VersionCheck'); Create a CDF file. CDF_DOC, id, vers, rel, copy, INCREMENT=incr PRINT,'File Written Using CDF', vers, rel, incr, $ FORMAT='(A,I1,".",I1,"r",I2)' CDF_CLOSE, id ; Close the CDF file. IDL Output File Written Using CDF2.6 CDF_ENCODE_EPOCH [Previous Routine] [Next Routine] [List of Routines] NAME: CDF_ENCODE_EPOCH The CDF_ENCODE_EPOCH function encodes a CDF_EPOCH variable into a string. Four different string formats are available. The default (EPOCH=0) is the standard CDF format, which may be parsed by the CDF_PARSED_EPOCH function or broken down with the CDF_EPOCH procedure. Syntax Result = CDF_ENCODE_EPOCH(Epoch [, EPOCH={0 | 1 | 2 | 3}] ) Arguments Epoch The double-precision CDF_EPOCH value to be encoded. For more information about CDF_EPOCH values, see section 2.2.10 ("Data Types") of the version 2.6 CDF User's Guide. Keywords EPOCH Set this keyword to indicate the type of output desired, Set EPOCH=0 to select output of the standard type, which is described in CDF_PARSE_EPOCH. Set EPOCH=1 to select output of the type yyyymodd.ttttttt where: yyyy is the year, mo is the month (1-12), dd is the day of the month (1-31), and ttttttt is the fraction of the day (e.g. 2500000 at 6 am). Set EPOCH=2 to select output of the type yyyymoddhhmmss where: yyyy is the year, mo is the month (1-12), dd is the day of the month (1-31), hh is the hour (0-23), mm is the minute (0-59), and ss is the second (0-59). Set EPOCH=3 to select output of the type yyyy-mo-ddThh:mm:ss.cccZ where: yyyy is the year, mo is the month (1-12), dd is the day of the month (1-31), hh is the hour (0-23), mm is the minute (0-59), ss is the second (0-59), and ccc is the millisecond (0-999). The characters T and Z are the CDF_EPOCH type 3 place holders. Example epoch_string = '04-Dec-1995 20:19:18.176' epoch = CDF_PARSE_EPOCH(epoch_string) HELP, epoch_string, epoch ; Create encode strings: encode0 = CDF_ENCODE_EPOCH(test_epoch, EPOCH=0) encode1 = CDF_ENCODE_EPOCH(test_epoch, EPOCH=1) encode2 = CDF_ENCODE_EPOCH(test_epoch, EPOCH=2) encode3 = CDF_ENCODE_EPOCH(test_epoch, EPOCH=3) ; Compare encoding formats: HELP, encode0, encode1, encode2, encode3 IDL Output EPOCH_STRING STRING = '04-Dec-1995 20:19:18.176' EPOCH DOUBLE = 6.2985328e+13 ENCODE0 STRING = '04-Dec-1995 20:19:18.176' ENCODE1 STRING = '19951204.8467381' ENCODE2 STRING = '19951204201918' ENCODE3 STRING = '1995-12-04T20:19:18.176Z' See Also CDF_EPOCH, CDF_PARSE_EPOCH CDF_EPOCH [Previous Routine] [Next Routine] [List of Routines] NAME: CDF_EPOCH The CDF_EPOCH procedure computes or breaks down CDF_EPOCH values in a CDF file. When computing an epoch, any missing value is considered to be zero. If you supply a value for the Epoch argument and set the BREAKDOWN_EPOCH keyword, CDF_EPOCH will compute the values of the Year, Month, Day, etc. and insert the values into the named variables you supply. If you specify the Year (and optionally, the Month, Day, etc.) and set the COMPUTE_EPOCH keyword, CDF_EPOCH will compute the epoch and place the value in the named variable supplied as the Epoch parameter. Note You must set either the BREAKDOWN_EPOCH or COMPUTE_EPOCH keyword. Syntax CDF_EPOCH, Epoch, Year [, Month, Day, Hour, Minute, Second, Milli] [, /BREAKDOWN_EPOCH] [, /COMPUTE_EPOCH] Arguments Epoch The Epoch value to be broken down, or a named variable into which the computed epoch will be placed. The Epoch value is the number of milliseconds since 01-Jan- 0000 00:00:00.000 Note "Year zero" is a convention chosen by NSSDC to measure epoch values. This date is more commonly referred to as 1 BC. Remember that 1 BC was a leap year. Year The year (such as 1992) or a named variable. Month The month (1-12) or a named variable. You can also set the Month argument equal to zero, in which case the Day argument can take on any value between 1-366; this number is interpreted as the "Day of the Year" rather than a "Day of the Month". Day The day (1-31) or a named variable. If the Month argument is set equal to zero, Day can be set to any value between 1-366. Hour The hour (0-23) or a named variable. Minute The minute (0-59) or a named variable. Second The second (0-59) or a named variable. Milli The millisecond (0-999) or a named variable. If Hour, Minute, and Second are all set equal to zero, Milli is interpreted as the "Millisecond of the Day" and can be any value between 0 and 86400000. Keywords BREAKDOWN_EPOCH If this keyword is set, Epoch is a value which will broken down and the resulting Year, Month, Day, etc. are returned in the remaining parameters which must be named variables. COMPUTE_EPOCH If this keyword is set, Epoch is a named variable into which the epoch is placed and the other parameters are values which will be used to compute the epoch. Example To compute the epoch value of September 20, 1992 at 3:00 am: CDF_EPOCH, MergeDate, 1992, 9, 20, 3, /COMPUTE_EPOCH To break down the given epoch value into standard date components: CDF_EPOCH, 4.7107656e13, yr, mo, dy, hr, mn, sc, milli, /BREAK CDF_ERROR [Previous Routine] [Next Routine] [List of Routines] NAME: CDF_ERROR The CDF_ERROR function returns a string containing a short explanation of a given status code returned from a Common Data Format file. Syntax Result = CDF_ERROR(Status) Arguments Status The status code to be explained. CDF_EXISTS [Previous Routine] [Next Routine] [List of Routines] NAME: CDF_EXISTS The CDF_EXISTS function returns true if the Common Data Format (CDF) scientific data format library is supported on the current IDL platform. This routine is written in the IDL language. Its source code can be found in the file cdf_exists.pro in the lib subdirectory of the IDL distribution. Syntax Result = CDF_EXISTS( ) Example The following IDL command prints an error message if the CDF library is not available: IF CDF_EXISTS() EQ 0 THEN PRINT, 'CDF not supported.' CDF_INQUIRE [Previous Routine] [Next Routine] [List of Routines] NAME: CDF_INQUIRE The CDF_INQUIRE function returns global information about the Common Data Format file. This information is returned in a structure of the form: { NDIMS:0L, DECODING:"", ENCODING:"", MAJORITY:"", MAXREC:0L, $ NVARS:0L, NZVARS:0L, NATTS:0L, DIM:LONARR(NDIMS) } The tags of this structure are described below. Syntax Result = CDF_INQUIRE(Id) Arguments Id A CDF ID, returned from a previous call to CDF_OPEN or CDF_CREATE. Explanation of the Structure Tags NDIMS The longword integer specifying the number of dimensions in the rVariables in the current CDF. DECODING A string describing the decoding type set in the CDF file, such as 'MAC_DECODING' or 'ALPHAVMSD_ENCODING'. ENCODING A string describing the type of encoding used in the CDF file, such as 'NETWORK_ENCODING' or 'SUN_ENCODING'. MAJORITY A string describing the majority used in the CDF file. The majority will be either row ('ROW_MAJOR') or column ('COL_MAJOR'). MAXREC A longword integer specifying the highest record number written in the rVariables in the current CDF. The MAXREC field will contain the value -1 if no rVariables have yet been written to the CDF. NVARS A longword integer specifying the number of rVariables (regular variables) in the CDF. NZVARS A longword integer specifying the number of zVariables in the CDF. NATTS A longword integer specifying the number of attributes in the CDF. Note that the number returned in this field includes both global and variable attributes. You can use the GET_NUMATTR keyword to the CDF_CONTROL routine to determine the number of each. DIM A vector where each element contains the corresponding dimension size for the rVariables in the current CDF. For 0-dimensional CDF's, this argument contains a single element (a zero). Example cdfid = CDF_CREATE('CDFinquire', /HP_ENCODING, /MAC_DECODING) attr1_id = CDF_ATTCREATE(cdfid, 'GLOBAL_ATT', /GLOBAL_SCOPE) attr2_id = CDF_ATTCREATE(cdfid,'VARIABLE_ATT', /VARIABLE_SCOPE) CDF_CONTROL, cdfid, GET_NUMATTRS = num_attrs PRINT, 'This CDF has ', num_attrs(0), $ 'Global attribute(s) and ', num_attrs(1), $ 'Variable attribute(s).', $ FORMAT='(A,I2,A,I2,A)' inquire = CDF_INQUIRE(cdfid) HELP, inquire, /STRUCT CDF_DELETE, cdfid ; Delete the CDF file. IDL Output This CDF has 1 Global attribute(s) and 1 Variable attribute(s). ** Structure <4003e0c0>, 9 tags, length=48, refs=1: NDIMS LONG 0 DECODING STRING 'MAC_DECODING' ENCODING STRING 'HP_ENCODING' MAJORITY STRING 'ROW_MAJOR' MAXREC LONG -1 NVARS LONG 0 NZVARS LONG 0 NATTS LONG 2 DIM LONG Array(1) See Also CDF_CONTROL, CDF_DOC, CDF_LIB_INFO CDF_LIB_INFO [Previous Routine] [Next Routine] [List of Routines] NAME: CDF_LIB_INFO The CDF_LIB_INFO procedure returns information about the CDF Library being used by this version of IDL. Information about the version of CDF used to create a particular CDF file can be obtained through CDF_DOC. Syntax CDF_LIB_INFO [, COPYRIGHT =variable] [, INCREMENT=variable] [, RELEASE=variable] [, SUBINCREMENT=variable] [, VERSION=variable] Keywords COPYRIGHT A named variable in which the copyright notice of the CDF library that this version of IDL is using will be returned. INCREMENT A named variable in which the incremental number of the CDF library that this version of IDL is using will be returned. RELEASE A named variable in which the release number of the CDF library that this version of IDL is using will be returned. SUBINCREMENT A named variable in which the sub incremental character of the CDF library that this version of IDL is using will be returned. VERSION A named variable in which the version number of the CDF library that this version of IDL is using will be returned. Example CDF_LIB_INFO, VERSION=V, RELEASE=R, COPYRIGHT=C, $ INCREMENT=I PRINT, 'IDL ', !version.release, 'uses CDF Library ', $ V, R, I, FORMAT='(A,A,A,I1,".",I1,".",I2,A)' PRINT, C IDL Output IDL 5.0 uses CDF Library 2.6 NSSDC Common Data Format (CDF) (C) Copyright 1990-1995 NASA/GSFC National Space Science Data Center NASA/Goddard Space Flight Center Greenbelt, Maryland 20771 USA (DECnet -- NCF::CDFSUPPORT) (Internet -- CDFSUPPORT@NSSDCA.GSFC.NASA.GOV) See Also CDF_DOC CDF_OPEN [Previous Routine] [Next Routine] [List of Routines] NAME: CDF_OPEN The CDF_OPEN function opens an existing Common Data Format file. If successful, the CDF ID for the file is returned. Syntax Result = CDF_OPEN(Filename) Arguments Filename A scalar string containing the name of the file to be created. Note that if the desired filename has a .cdf ending, you can omit the extension and specify just the first part of the filename. For example, specifying "mydata" would open the file mydata.cdf. Example id = CDF_OPEN('open_close.cdf'); Open a file. ; ... other CDF_ commands ... CDF_CLOSE, id ; Close the cdf file. CDF_PARSE_EPOCH [Previous Routine] [Next Routine] [List of Routines] NAME: CDF_PARSE_EPOCH The CDF_PARSE_EPOCH function parses a properly-formatted input string into a double-precision value properly formatted for use as a CDF_EPOCH variable. CDF_EPOCH variables may be unparsed into a variety of formats using the CDF_ENCODE_EPOCH function. Syntax Result = CDF_PARSE_EPOCH(Epoch_string) Arguments Epoch_string A formatted string that will be parsed into a double precision value suitable to be used as a CDF_EPOCH value. The format expected by CDF_PARSE_EPOCH (the CDF standard) is dd-mmm-yyyy hh:mm:ss.ccc where: * dd is the day of the month, 1-31. * mmm is the month, Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, or Dec. * yyyy is the year, A.D. * hh is the hour, 0-23. * mm is the minute, 0-59. * ss is the second, 0-59, and * ccc is the millisecond, 0-999. For more information about CDF_EPOCH values, see section 2.2.10 ("Data Types") of the version 2.6 CDF User's Guide. Example test_string = '04-Dec-1995 20:19:18.176' test_epoch = CDF_PARSE_EPOCH(test_string) HELP, test_string, test_epoch PRINT, CDF_ENCODE_EPOCH(test_epoch, EPOCH=0) IDL Output TEST_STRING STRING = '04-Dec-1995 20:19:18.176' TEST_EPOCH DOUBLE = 6.2985328e+13 04-Dec-1995 20:19:18.176 See Also CDF_ENCODE_EPOCH, CDF_EPOCH CDF_VARCREATE [Previous Routine] [Next Routine] [List of Routines] NAME: CDF_VARCREATE The CDF_VARCREATE function creates a new variable in a Common Data Format file. Syntax Result = CDF_VARCREATE( Id, Name [, DimVary] [, /CDF_BYTE | , /CDF_CHAR | , /CDF_DOUBLE | , /CDF_EPOCH | , /CDF_FLOAT | , /CDF_INT1 | , /CDF_INT2 | , /CDF_INT4 | , /CDF_REAL4 | , /CDF_REAL8 | , /CDF_UCHAR | , /CDF_UINT1 | , /CDF_UINT2 | , /CDF_UINT4] [, ALLOCATERECS=records] [, DIMENSIONS=array] [, NUMELEM=characters] [, /REC_NOVARY | , /REC_VARY] [, /ZVARIABLE] ) Arguments Id The CDF ID, returned from a previous call to CDF_OPEN or CDF_CREATE. Name A string containing the name of the variable to be created. DimVary A one-dimensional array containing one element per CDF dimension. If the element is non-zero or the string 'VARY', the variable will have variance in that dimension. If the element is zero or the string 'NOVARY' then the variable will have no variance with that dimension. If the variable is zero-dimensional, this argument may be omitted. Keywords You must specify the type variable being created. This is done by setting one of the following keywords: * CDF_BYTE * CDF_INT4 * CDF_CHAR * CDF_REAL4 * CDF_DOUBLE * CDF_REAL8 * CDF_EPOCH * CDF_UCHAR * CDF_FLOAT * CDF_UINT1 * CDF_INT1 * CDF_UINT2 * CDF_INT2 * CDF_UINT4 If no type is specified, CDF_FLOAT is assumed. Although all CDF variable types are supported within the file, IDL has full support only for the following CDF data types: CDF_DOUBLE, CDF_EPOCH, CDF_FLOAT, CDF_INT2, CDF_INT4, CDF_REAL4, CDF_REAL8, and CDF_UCHAR. ALLOCATERECS Set this keyword equal to the desired number of pre-allocated records for this variable in a SINGLE_FILE CDF file. Pre-allocating records ensure that variable data is stored contiguously in the CDF file. For discussion about allocating records, see section 2.3.8 ("Records") of the version 2.6 CDF User's Guide. DIMENSIONS Set this keyword to create a new zVariable with the specified dimensions. For example: id = CDF_CREATE("cdffile.cdf", [100] ) zid = CDF_VARCREATE(id, "Zvar", [1,1,1], DIM=[10,20,30]) NUMELEM The number of elements of the data type at each variable value. This keyword only has meaning for string data types (CDF_CHAR, CDF_UCHAR). This is the number of characters in the string. The default is 1. REC_NOVARY If this keyword is set, all records will contain the same information. REC_VARY If this keyword is set, all records will contain unique data. This is the default. ZVARIABLE A variable is assumed to be a zVariable if its dimensions are specified by the DIMENSIONS keyword. Set this keyword to create a zero-dimensional zVariable. For example: id = CDF_CREATE("cdffile.cdf", [100] ) zid = CDF_VARCREATE(id, "Zvar", /ZVARIABLE) Examples Example 1 In this example, we create a CDF file to record the data retrieved from an array of temperature and salinity detectors. There is a 3 x 4 array of detectors at two depths, 10.0 meters and 20.2 meters: id = CDF_CREATE("temp_salinity.cdf", [3,4], /NETWORK_ENCODING, $ /SUN_DECODING, /CLOBBER) temp_id =CDF_VARCREATE(id, "Temperature", ['Vary', 'Vary'], $ /REC_VARY,/CDF_FLOAT) depth_id = CDF_VARCREATE(id, "Depth", [0,0], /REC_VARY, /CDF_FLOAT) sal_id = CDF_VARCREATE(id, "Salinity", [1,1], /REC_VARY, $ /CDF_DOUBLE) ; Create and fill the UNITS attribute: units_att = CDF_ATTCREATE(id, 'UNITS', /VARIABLE) CDF_ATTPUT, id, 'UNITS', 'Depth', 'Meters' CDF_ATTPUT, id, 'UNITS', temp_id, 'Kelvin' CDF_ATTPUT, id, units_att, sal_id, 'Percent' ; Create and write some fictitous data: data1 = 20.0 + FINDGEN(3,4) CDF_VARPUT, id, varid, data1 ; IDL will handle the type conversion, CDF will set all values ; of this record to a depth of 10.0. CDF_VARPUT, id, depth_id, '10.0' CDF_VARPUT, id, depth_id, 20.2,rec_start=1 ; Set the second depth. CDF_VARPUT, id, sal_id, DINDGEN(3,4)/10.0 ; Make more fictitous data. ; Demostrate the non-variance of depth by retrieving the ; values. On the first pass, use CDF_VARGET1 to retrieve ; single values: CDF_VARGET1, id, depth_id, pth_0; Get single values. CDF_VARGET1, id, depth_id, depth_1, REC_START=1 ; Get single values. HELP, depth_0, depth_1 ; Now retrieve the full depth records: CDF_VARGET, id, depth_id, depth, REC_COUNT=2 ;Examine the depth variable: HELP, depth PRINT, depth IDL Output DEPTH_0 FLOAT = 10.0000 DEPTH_1 FLOAT = 20.2000 DEPTH FLOAT = Array(3, 4, 2) 10.0000 10.0000 10.0000 10.0000 10.0000 10.0000 10.0000 10.0000 10.0000 10.0000 10.0000 10.0000 20.2000 20.2000 20.2000 20.2000 20.2000 20.2000 20.2000 20.2000 20.2000 20.2000 20.2000 20.2000 Example 2 In this example, we create a variable, setting the data type from a string variable, which could have been returned by the DATATYPE keyword to a CDF_VARINQ call: VARTYPE = 'CDF_FLOAT' ; Use the _EXTRA keyword and the CREATE_STRUCT function to ; make the appropriate keyword. VarId = CDF_VARCREATE(Id, 'Pressure', [1,1], $ NUMELEM=2, _EXTRA=CREATE_STRUCT(VARTYPE,1)) CDF_CLOSE, id ; Close the CDF file. CDF_VARDELETE [Previous Routine] [Next Routine] [List of Routines] NAME: CDF_VARDELETE The CDF_VARDELETE procedure deletes a variable from a SINGLE_FILE CDF file. Note that the variable's entries are also deleted, and that the variables that numerically follow the deleted variable within the CDF file are automatically renumbered. CDF rVariables and zVariables are counted separately within CDF files. Attempting to delete a variable from a MULTI_FILE format CDF file will result in a warning message. Syntax CDF_VARDELETE, Id, Variable [, /ZVARIABLE] Arguments Id The CDF ID of the file containing the Variable to be deleted, returned from a previous call to CDF_OPEN or CDF_CREATE. Variable A string containing the name of the variable to be deleted OR the variable number to be deleted. Variable numbers are 0-based in IDL. zVariables and rVariables are counted separately in CDF files. Keywords ZVARIABLE Set this keyword if the Variable is a zVariable and was passed by number. The default is to assume that Variable is an rVariable. Example cid = CDF_CREATE('DEMOvardelete',/SINGLE_FILE) ; Create 3 zVariables and 1 rVariable: var1_id = CDF_VARCREATE(cid, 'rVAR1', /CDF_FLOAT) var2_id = CDF_VARCREATE(cid, 'zVAR1', /CDF_INT4, /REC_NOVARY, $ /ZVARIABLE) var3_id = CDF_VARCREATE(cid, 'zVAR2', /CDF_CHAR, [2,10], $ NUMELEM=10, DIM=[5,5]) var4_id = CDF_VARCREATE(cid, 'zVAR3' ,/CDF_REAL8, /ZVARIABLE) ; Check the number of variables: info = CDF_INQUIRE(cid) HELP, info.nzvars, info.nvars ; Delete the first and third zvariables: CDF_VARDELETE, cid, 'zVAR1', /ZVARIABLE CDF_VARDELETE, cid, 1, /ZVARIABLE ; CAUTION: Remember the variable numbers are zero-based ; and are automatically renumbered. info = CDF_INQUIRE(cid) HELP, info.nzvars, info.nvars varinfo = CDF_VARINQ(cid, 0, /ZVARIABLE) ; check on zVAR2 HELP, varinfo, /STRUCTURE CDF_DELETE, cid IDL Output LONG = 3 LONG = 1 LONG = 1 LONG = 1 ** Structure <400a3b40>, 8 tags, length=48, refs=1: IS_ZVAR INT 1 NAME STRING 'zVAR2' DATATYPE STRING 'CDF_CHAR' NUMELEM LONG 10 RECVAR STRING 'VARY' DIMVAR BYTE Array(2) ALLOCATERECS LONG Array(2) DIM LONG Array(1) See Also CDF_ATTDELETE, CDF_CONTROL, CDF_VARCREATE, CDF_VARINQ CDF_VARGET [Previous Routine] [Next Routine] [List of Routines] NAME: CDF_VARGET The CDF_VARGET procedure reads multiple values from a Common Data Format file variable. By default, all elements of a record are read. If INTERVAL and/or OFFSET are specified but no COUNT is specified, CDF_VARGET attempts to get as many elements of each record as possible. Syntax CDF_VARGET, Id, Variable, Value [, COUNT=vector] [, INTERVAL=vector] [, OFFSET=vector] [, REC_COUNT=records] [, REC_INTERVAL=value] [, REC_START=record] [, /STRING{data in CDF file must be type CDF_CHAR or CDF_UCHAR}] [, /ZVARIABLE] Arguments Id The CDF ID, returned from a previous call to CDF_OPEN or CDF_CREATE Variable A string containing the name of the variable or the variable number being read. Value A named variable in which the values of the variable are returned. Keywords COUNT An optional vector containing the counts to be used in reading Value. The default is to read all elements in each record, taking into account INTERVAL and OFFSET. INTERVAL A vector specifying the interval between values in each dimension. The default value is 1 for each dimension. OFFSET A vector specifying the array indices within the specified record(s) at which to begin writing. OFFSET is a 1-dimensional array containing one element per CDF dimension. The default value is zero for each dimension. REC_COUNT The number of records to read. The default is 1. REC_INTERVAL The interval between records when reading multiple records. The default value is 1. REC_START The record number at which to start reading. The default is 0. STRING Set this keyword to return CDF_CHAR and CDF_UCHAR data from the CDF file into Value as string data rather than byte data. This keyword is ignored if the data in the CDF file is not of type CDF_CHAR or CDF_UCHAR. ZVARIABLE If Variable is a variable ID (as opposed to a variable name) and the variable is a zVariable, set this flag to indicate that the variable ID is a zVariable ID. The default is to assume that Variable is an rVariable ID. Example ; Create a CDF file, and make a few variables: id = CDF_CREATE('DEMOvargets') vid1 = CDF_VARCREATE(id, 'VAR1', /CDF_CHAR, NUMELEM=15) vid2=CDF_VARCREATE(id, 'VAR2', /CDF_UCHAR, NUMELEM=10) CDF_VARPUT, id, vid1, BINDGEN(15, 2)+55, COUNT=2 CDF_VARPUT, id, vid2, ['IDLandCDF ', 'AreWayCool' ; Retrieve the CDF_CHAR array as byte data: CDF_VARGET, id,'VAR1',var1_byte,REC_COUNT=2 HELP, var1_byte ;Retrieve the CDF_CHAR array as string data: CDF_VARGET, id, 'VAR1', var1_string, REC_COUNT=2, /STRING HELP, var1_string ; For demonstration purposes, use the 'VAR2' variable number to ; access 'VAR2' for the duration of this example: var2num = CDF_VARNUM(id, 'VAR2') HELP, var2num ; Rename 'VAR2' to 'VAR_STRING_2': CDF_VARRENAME, id, var2num, 'VAR_STRING_2' ; Examine VAR_STRING_2 with CDF_VARINQ: VAR2_INQ = CDF_VARINQ(id, var2num) HELP, VAR2_INQ, /STRUCTURE ; Read in and print out VAR_STRING_2: CDF_VARGET, id, var2num, var2_string, /STRING, REC_COUNT=2 PRINT, var2_string CDF_DELETE, id ; Delete the CDF file IDL Output % CDF_VARGET: Warning: converting data to unsigned bytes This warning message indicates that the data was stored in the CDF file with type CDF_CHAR (signed 1-byte characters), but was retrieved by IDL with type BYTE (unsigned byte). To turn this warning message off, set !QUIET=1. VAR1_BYTE BYTE = Array(15, 2) VAR1_STRING STRING = Array(2) VAR2NUM LONG = 1 ** Structure <400b1600>, 6 tags, length=33, refs=1: IS_ZVAR INT 0 NAME STRING 'VAR_STRING_2' DATATYPE STRING 'CDF_UCHAR' NUMELEM LONG 10 RECVAR STRING 'VARY' DIMVAR BYTE 0 IDLandCDF AreWayCool CDF_VARGET1 [Previous Routine] [Next Routine] [List of Routines] NAME: CDF_VARGET1 The CDF_VARGET1 procedure reads one value from a CDF file variable. Syntax CDF_VARGET1, Id, Variable, Value [, OFFSET=vector] [, REC_START=record] [, /STRING{data in CDF file must be type CDF_CHAR or CDF_UCHAR}] [, /ZVARIABLE] Arguments Id The CDF ID, returned from a previous call to CDF_OPEN or CDF_CREATE. Variable A string containing the name or number of the variable to be read. Value A named variable in which the value of the variable is returned. Keywords OFFSET A vector specifying the array indices within the specified record(s) at which to begin reading. OFFSET is a 1-dimensional array containing one element per CDF dimension. The default value is 0 for each dimension. REC_START The record number at which to start reading. The default is 0. STRING Set this keyword to return CDF_CHAR and CDF_UCHAR data from the CDF file into Value as string data rather than byte data. This keyword is ignored if the data in the CDF file is not of type CDF_CHAR or CDF_UCHAR. ZVARIABLE If Variable is a variable ID (as opposed to a variable name) and the variable is a zVariable, set this flag to indicate that the variable ID is a zVariable ID. The default is to assume that Variable is an rVariable ID. Example See the example for "CDF_VARCREATE" on page 74. CDF_VARINQ [Previous Routine] [Next Routine] [List of Routines] NAME: CDF_VARINQ The CDF_VARINQ function returns a structure containing information about the specified variable in a Common Data Format file. This structure has the form: { IS_ZVAR:0, NAME:"", DATATYPE:"", NUMELEM:0L, $ RECVAR:"", DIMVAR:BYTARR(...) [, DIM:LONARR(...)]} Note: the DIM field is included in the structure only if IS_ZVAR is one. This structure's tags are explained below. Syntax Result = CDF_VARINQ( Id, Variable [, /ZVARIABLE] ) Arguments Id The CDF ID, returned from a previous call to CDF_OPEN or CDF_CREATE. Variable A string containing the name or number of the variable being inquired. Keywords ZVARIABLE If Variable is a variable ID (as opposed to a variable name) and the variable is a zVariable, set this flag to indicate that the variable ID is a zVariable ID. The default is to assume that Variable is an rVariable ID. Explanation of the Structure Tags IS_ZVAR This field will contain a 1 if the variable is a zVariable or a 0 if it is an rVariable. NAME The name of the variable. DATATYPE A string describing the data type of the variable. The string has the form 'CDF_XXX' where XXX is FLOAT, DOUBLE, EPOCH, UCHAR, etc. NUMELEM The number of elements of the data type at each variable value. This is always 1 except in the case of string type variables (CDF_CHAR, CDF_UCHAR). RECVAR A string describing the record variance of the variable. This is either the string 'VARY' or 'NOVARY'. DIMVAR An array of bytes. The value of each element is zero if there is no variance with that dimension and one if there is variance. For zero-dimensional CDFs, DIMVAR will have one element whose value is zero. DIM An array of longs. The value of each element corresponds to the dimension of the variable. This field is only included in the structure if the variable is a zVariable. Example See the example for "CDF_VARGET" on page 80. CDF_VARNUM [Previous Routine] [Next Routine] [List of Routines] NAME: CDF_VARNUM The CDF_VARNUM function returns the variable number associated with a given variable name in a Common Data Format file. If the specified variable cannot be found in the CDF file, CDF_VARNUM returns the scalar -1. Syntax Result = CDF_VARNUM( Id, VarName [, IsZVar] ) Arguments Id The CDF ID, returned from a previous call to CDF_OPEN or CDF_CREATE. VarName A string containing the name of the variable. IsZVar A named variable into which CDF_VARNUM will place a 1 to indicate that the referenced variable is a zVariable or a 0 to indicate that it is an rVariable. Example See the example for "CDF_VARGET" on page 80. CDF_VARPUT [Previous Routine] [Next Routine] [List of Routines] NAME: CDF_VARPUT The CDF_VARPUT procedure writes a value to a variable in a Common Data Format file. This function provides equivalent functionality to the C routines CDFvarPut and CDFvarHyperPut. Syntax CDF_VARPUT, Id, Variable, Value [, COUNT=vector] [, INTERVAL=vector] [, OFFSET=vector] [, REC_INTERVAL=value] [, REC_START=record] [, /ZVARIABLE] Arguments Id The CDF ID, returned from a previous call to CDF_OPEN or CDF_CREATE. Variable A string containing the name or number of the variable being written. Value The value to write. If the value has 1 more dimension than the CDF, multiple records will be written. Keywords COUNT An optional vector containing the counts to be used in writing Value. Note that counts do not have to match the dimensions of Value. The default count is to use the dimensions of Value. INTERVAL A vector specifying the interval between values in each dimension. The default value is 1 in each dimension. OFFSET A vector specifying the array indices within the specified record(s) at which to begin writing. OFFSET is a 1-dimensional array containing one element per CDF dimension. The default value is zero in each dimension. REC_INTERVAL The interval between records being written when writing multiple records. The default value is 1. REC_START The record number at which to start writing. The default is 0. ZVARIABLE If Variable is a variable ID (as opposed to a variable name) and the variable is a zVariable, set this flag to indicate that the variable ID is a zVariable ID. The default is to assume that Variable is an rVariable ID. Example id= CDF_CREATE('mycdf', [5,10], /NETWORK_ENCODING, /ROW_MAJOR) varid= CDF_VARCREATE(id, 'V1', [1,1], /CDF_FLOAT, /REC_VARY) To write the value 42.0 into record 12, third row, fourth column: CDF_VARPUT, id, varid, 42, REC_START=12, OFFSET=[2,3] To write 3 records, skipping every other record, starting at record 2, writing every other entry of each record. Note that in this example we write 25 values into each record written: CDF_VARPUT, id, varid, FINDGEN(5,5,3), INTERVAL=[2,1], $ REC_INTERVAL=2, REC_START=2 CDF_DELETE, id CDF_VARRENAME [Previous Routine] [Next Routine] [List of Routines] NAME: CDF_VARRENAME The CDF_VARRENAME procedure renames an existing variable in a Common Data Format file. Syntax CDF_VARRENAME, Id, OldVariable, NewName [, /ZVARIABLE] Arguments Id The CDF ID, returned from a previous call to CDF_OPEN or CDF_CREATE. OldVariable A string containing the current name of the variable or the variable number to be renamed. NewName A string containing the new name for the variable. Keywords ZVARIABLE If OldVariable is a variable ID (as opposed to a variable name) and the variable is a zVariable, set this flag to indicate that the variable ID is a zVariable ID. The default is to assume that OldVariable is an rVariable ID. Example See the example for "CDF_VARGET" on page 80. HDF INTERFACES [Previous Routine] [Next Routine] [List of Routines] NAME: HDF Interfaces There are two basic interfaces to HDF files: the single-file application interface and the multiple-file application interface. These interfaces support eight different types (or "models") of data access. The table below lists the different models and the names of the IDL routines that access those models. Each model is described in more detail after the table. Model IDL Routine Name Prefix 24-bit raster HDF_DF24_ annotation data HDF_DFAN_ palette data HDF_DFP_ 8-bit raster HDF_DFR8_ scientific data HDF_SD_ multi-file scientific data HDF_SD_ VData HDF_VD_ VGroup HDF_VG_ Table 3-1: Data Access Models and Routine Prefixes. Single File Application Interfaces In this mode, access is limited to one file at a time. This interface supports the 8-bit raster, 24-bit raster, palette, scientific data, and annotation models. The interfaces are described in more detail after the table. * 8-bit Raster Model: The HDF_DFR8_ routines access 8-bit images. * Palette Model: The HDF_DFP_ routines are used to work with the HDF_DFR8_ routines to manipulate palettes associated with 8-bit HDF images. * 24-bit Raster Model: The HDF_DFR24_ routines access 24-bit images. * Scientific Data Models (SDs): Used to manipulate arrays of arbitrary dimension and type. Under this model, an array accompanied by a record of its data type, dimensions and descriptors is called a Scientific Dataset (SD). * Annotation Model: The annotation model is used to describe the contents of the file through such items as labels, data descriptors, and dimension scales. * Vdata Model: This interface allows for the creation of customized tables. Each table consists of a series of Vdata records whose values are stored in fixed length fields. As described in more detail in the Vdata example below, a Vdata can contain three kinds of identifying information: a Vdata name, Vdata Class, and multiple Vdata field names. The Vdata model is accessed through the routines that begin with the HDF_VD_ prefix. * Vgroup Model: A collection of one or more data objects, Vdata sets, or Vgroups is known as a Vgroup. Each Vgroup can be given a Vgroup name and Vgroup class. The Vgroup model is accessed through the routines that begin with the HDF_VG_ prefix. Multi-File Application Interface The HDF_SD_ routines allow operations on more than one file at a time. This multi- file interoperability is achieved through HDF's use of a modified version of the NetCDF library. IDL's interface to HDF's multi-file capability is the HDF_SD_SETEXTFILE routine. CREATING HDF FILES [Previous Routine] [Next Routine] [List of Routines] NAME: Creating HDF Files The following IDL commands should be used to create a new HDF file: * HDF_OPEN: Call this procedure first to open an HDF file. The CREATE keyword must be set if you want to create a new file instead of opening an existing one. * HDF_DFAN_ADDFDS: Optionally, add a file description. * HDF_DFAN_ADDFID: Optionally, add a file annotation. Adding Data to an HDF File The routines used to add data to an HDF file vary based on the interface model being used: * To add an 8-bit image (with or without a palette), use HDF_DFR8_ADDIMAGE or DFR8_PUTIMAGE. * To add a palette, use HDF_DFP_ADDPAL or HDF_DFP_PUTPAL. * To add a 24-bit image, use HDF_DF24_ADDIMAGE or HDF_DF24_PUTIMAGE. * To add a Multi-File Scientific Dataset, use the following commands: * HDF_SD_CREATE or HDF_SD_SELECT to create an SDS or select an existing one. * HDF_SD_DIMSET to set dimension information. * HDF_SD_ATTRSET to set attribute information. * HDF_SD_SETINFO to insert optional information about the data. * HDF_SD_ADDDATA to insert the data. * HDF_SD_SETEXTFILE to move the data to an external file (optional). * HDF_SD_ENDACCESS to end access to the SDS. * To add a Vdata, use the following commands: * HDF_VD_ATTACH to get a Vdata identifier. * HDF_VD_SETINFO to write information about the Vdata (optional). * HDF_VD_FDEFINE to prepare non-trivial fields (optional). * HDF_VD_WRITE to write the Vdata. * To add a Vdata to a Vgroup, use the following commands: * HDF_VG_ATTACH to get a Vgroup identifier. * HDF_VG_SETINFO to set the Vgroup name and class (optional). * HDF_VG_INSERT to add the Vdata to a Vgroup. * HDF_VG_DETACH to close the Vgroup. * HDF_CLOSE to close the file. HDF Examples Two example files that demonstrate the use of the HDF routines can be found in the examples/data_access/sdf subdirectory of the IDL distribution. The file hdf_info.pro prints a summary of basic information about an HDF file. The file hdf_rdwr.pro creates a new HDF file and then reads the information back from that file. HDF SCIENTIFIC DATASET ID NUMBERS [Previous Routine] [Next Routine] [List of Routines] NAME: HDF Scientific Dataset ID Numbers IDL's HDF_SD_ routines can accept two different types of ID numbers. Documentation for these routines in the IDL Reference Guide refers to these ID numbers as the SD_ID and SDS_ID arguments. The SD_ID is the Scientific Dataset interface ID. There is only one SD_ID per HDF file. For each actual dataset used, you will also need an SDS_ID, which is the ID for the particular dataset. Some routines, such as HDF_SD_ATTRFIND, accept either an SD_ID or an SDS_ID. In these cases, the documentation refers to the ID as an S_ID, meaning that either type of ID is accepted. IDL and HDF Data Types HDF and IDL support many different data types. Many of the HDF routines allow you to perform a data type conversion "on the fly" by setting keywords such as FLOAT. When the data type desired is not explicitly specified, IDL uses the conversions shown in the following tables. Note that single-precision floating-point is the default data type and that the complex data type is not supported. When writing IDL data to an HDF file, IDL data types are converted to the HDF data types shown in the following table: IDL Data Type HDF Data Type BYTE DFNT_UINT8 (IDL bytes are unsigned) INT DFNT_INT16 UINT DFNT_UINT16 LONG DFNT_INT32 ULONG DFNT_UINT32 FLOAT DFNT_FLOAT32 DOUBLE DFNT_DOUBLE STRING DFNT_CHAR Table 3-2: Type Conversions when Writing IDL Data to an HDF File When reading data from an HDF file, HDF data types are converted to the IDL data types shown in the following table: HDF Data Type IDL Data Type DFNT_CHAR or DFNT_UCHAR STRING DFNT_INT8 or DFNT_UINT8 BYTE DFNT_INT16 INT DFNT_UINT16 UINT DFNT_INT32 LONG DFNT_UINT32 ULONG DFNT_FLOAT32 or FLOAT DFNT_NONE DFNT_DOUBLE DOUBLE Table 3-3: Type Conversions when Reading HDF Data into IDL HDF type codes for the supported HDF data types are shown in the table below: HDF Data Type Type Code DFNT_UCHAR 3 DFNT_CHAR 4 DFNT_FLOAT32 5 DFNT_DOUBLE 6 DFNT_INT8 20 DFNT_UINT8 21 DFNT_INT16 22 DFNT_UINT16 23 DFNT_INT32 24 DFNT_UINT32 25 Table 3-4: HDF Data Type Codes Common HDF Tag Numbers The following table lists common HDF tag numbers and their meanings. Tag Number Meaning 030 Version Identifier 100 File Identifier 101 File Description 102 Tag Identifier 103 Tag Description 104 Data Identifier Label 105 Data Identifier Annotation 106 Number Type 107 Machine Type 200 Obsolete 201 Obsolete 202 Obsolete 203 Obsolete 204 Obsolete 300 RIG Image Dimension 301 Raster Image Look Up Table (LUT) 302 Raster Image 303 Compressed Raster Image 306 Raster Image Group (RIG) 307 RIG LUT Dimension 308 RIG Matte Dimension 309 Raster Image Matte Data 310 Raster Image Color Correction Table 3-5: Common HDF Tag Numbers Tag Number Meaning 311 Raster Image Color Format 312 Raster Image Aspect Ratio 400 Composite Image Descriptor 500 XY Position 602 Vector Image - Tek4014 Stream 603 Vector Image - Tek4105 Stream 701 SD Dimension Record 702 SD Data 703 SD Scales 704 SD Labels 705 SD Units 706 SD Formats 707 SD Max/Min 708 SD Coordinates 710 SD Link 720 SD Descriptor (NDG) 731 SD Calibration Information 732 SD Fill Value 1962 Vdata Description 1963 Vdata 1965 Vgroup Table 3-5: Common HDF Tag Numbers ALPHABETICAL LISTING OF HDF ROUTINES [Previous Routine] [Next Routine] [List of Routines] NAME: Alphabetical Listing of HDF Routines The remainder of this chapter is an alphabetical listing of HDF Routines. Note The routines HDF_BROWSER and HDF_READ, introduced in IDL version 5.1, allow you to read HDF data files and import data into IDL using a graphical user interface. Using these two routines, you can avoid the need to use most of the rest of IDL's HDF interface. HDF_BROWSER and HDF_READ are discussed in the IDL Reference Guide. HDF_AN_ANNLEN [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_AN_ANNLEN This function returns the number of characters contained in the HDF AN annotation specified by the annotation identifier ann_id. Syntax Result = HDF_AN_ANNLEN(ann_id) Return Value Returns SUCCEED (0) if successful or FAIL (-1) otherwise. Arguments ann_id Annotation identifier returned by HDF_AN_CREATE, HDF_AN_CREATEF, or HDF_AN_SELECT. HDF_AN_ANNLIST [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_AN_ANNLIST This function obtains a list of identifiers of the annotations that are of the type specified by the parameter annot_type and are attached to the object identified by its tag, obj_tag, and its reference number, obj_ref. Syntax Result = HDF_AN_ANNLIST(an_id, annot_type, obj_tag, obj_ref, ann_list) Return Value Returns SUCCEED (0) or FAIL (-1) otherwise. Arguments an_id HDF AN interface identifier returned by HDF_AN_START. annot_type Type of the annotation. Since this routine is implemented only to obtain the identifiers of data annotations and not file annotations, the valid values of annot_type are: * 0 = data label * 1 = data description obj_tag HDF tag of the object. obj_ref HDF reference number of the object. ann_list A named variable that will contain the annotation identifiers. HDF_AN_ATYPE2TAG [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_AN_ATYPE2TAG This function returns the HDF tag that corresponds to the annotation type specified by the parameter annot_type. Syntax Result = HDF_AN_ATYPE2TAG(annot_type) Return Value Returns the HDF annotation tag (ann_tag) if successful, or not found (0) otherwise. Arguments annot_type Type of the annotation. The following table lists the valid values of annot_type in the left column and the corresponding values for the returned annotation tag on the right. Annotation Type HDF Annotation Tag 0 = Data Label (AN_DATA_LABEL) 104 (DFTAG_DIL) 1= Data Description (AN_DATA_DESC) 105 (DFTAG_DIA) 2 = File Label (AN_FILE_LABEL) 100 (DFTAG_FID) 3 = File Description (AN_FILE_DESC) 101 (DFTAG_FD) Table 3-6: Valid annot_type and ann_tag values. HDF_AN_CREATE [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_AN_CREATE This function creates an HDF AN data annotation of type annot_type for the object specified by its HDF tag, obj_tag, and its HDF reference number, obj_ref. Use HDF_AN_CREATEF to create a file annotation. Currently, the user must write to a newly-created annotation before creating another annotation of the same type. Creating two consecutive annotations of the same type causes the second call to HDF_AN_CREATE to return FAIL (-1). Syntax Result = HDF_AN_CREATE(an_id, obj_tag, obj_ref, annot_type) Return Value Returns the data annotation identifier (ann_id) if successful or FAIL (-1) otherwise. Arguments an_id HDF_AN_ INTERFACE identifier returned by HDF_AN_START. obj_tag HDF tag of the object to be annotated. obj_ref HDF reference number of the object to be annotated. annot_type Type of the data annotation. The returned data annotation identifier can represent either a data label or a data description. Valid values for annot_type are: * 0 = data label * 1 = data description HDF_AN_CREATEF [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_AN_CREATEF This function creates an HDF AN file annotation of the type specified by the parameter annot_type. Use HDF_AN_CREATE to create a data annotation. Currently, the user must write to a newly-created annotation before creating another annotation of the same type. Creating two consecutive annotations of the same type causes the second call to HDF_AN_CREATE to return FAIL (-1) Syntax Result = HDF_AN_CREATEF(an_id, annot_type) Return Value Returns the file annotation identifier (ann_id) if successful or FAIL (-1) otherwise. Arguments an_id HDF_AN_ INTERFACE identifier returned by HDF_AN_START. annot_type Type of the file annotation. The file annotation identifier returned can either represent a file label or a file description. Valid values for annot_type are: * 2 = file label * 3 = file description HDF_AN_END [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_AN_END This procedure terminates access to the HDF AN interface identified by an_id, which is previously initialized by a call to HDF_AN_START. Note that there must be one call to HDF_AN_END for each call to HDF_AN_START. Syntax HDF_AN_END, an_id Arguments an_id HDF AN interface identifier returned by HDF_AN_START. HDF_AN_ENDACCESS [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_AN_ENDACCESS This procedure terminates access to the annotation identified by the parameter ann_id. Note that there must be one call to HDF_AN_ENDACCESS for every call to HDF_AN_SELECT, HDF_AN_CREATE or HDF_AN_CREATEF. Syntax HDF_AN_ENDACCESS, ann_id Arguments ann_id Annotation identifier returned by HDF_AN_CREATE, HDF_AN_CREATEF or HDF_AN_SELECT. HDF_AN_FILEINFO [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_AN_FILEINFO This function retrieves the total number of the four kinds of annotations and stores them in the appropriate parameters. Note that the numbers of data labels and descriptions refer to the total number of data labels and data descriptions in the file, not for a specific object. Use HDF_AN_NUMANN to determine these numbers for a specific object. This function is generally used to find the range of acceptable indices for HDF_AN_SELECT calls. Syntax Result = HDF_AN_FILEINFO(an_id, n_file_labels, n_file_descs, n_data_labels, n_data_descs) Return Value Returns SUCCEED (0) if successful or FAIL (-1) otherwise. Arguments an_id HDF AN interface identifier returned by HDF_AN_START. n_file_labels A named variable that will contain the number of file labels. n_file_descs A named variable that will contain the number of file descriptions. n_data_labels A named variable that will contain the total number of data labels of all data objects in the file. n_data_descs A named variable that will contain the total number of data descriptions of all data objects in the file. HDF_AN_GET_TAGREF [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_AN_GET_TAGREF This function retrieves the HDF tag and reference number of the annotation identified by its index and by its annotation type. Syntax Result = HDF_AN_GET_TAGREF(an_id, index, annot_type, ann_tag, ann_ref) Return Value Returns SUCCEED (0) if successful or FAIL (-1) otherwise. Arguments an_id HDF AN interface identifier returned by HDF_AN_START. index Index of the annotation. This parameter is a nonnegative integer and is less than the total number of annotations of type annot_type in the file. Use HDF_AN_FILEINFO to obtain the total number of annotations of each type in the file. annot_type Type of the annotation. The following table lists the valid values of the parameter annot_type in the left column, and the corresponding values of the parameter ann_tag in the right column. Annotation Type HDF Annotation Tag 0 = Data Label (AN_DATA_LABEL) 104 (DFTAG_DIL) 1= Data Description (AN_DATA_DESC) 105 (DFTAG_DIA) 2 = File Label (AN_FILE_LABEL) 100 (DFTAG_FID) 3 = File Description (AN_FILE_DESC) 101 (DFTAG_FD) Table 3-7: Valid annot_type and ann_tag values. ann_tag A named variable that will contain the HDF tag of the annotation. ann_ref A named variable that will contain the HDF reference number of the annotation. HDF_AN_ID2TAGREF [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_AN_ID2TAGREF This function retrieves the HDF tag/reference number pair of the HDF AN annotation identified by its annotation identifier. Syntax Result = HDF_AN_ID2TAGREF(ann_id, ann_tag, ann_ref) Return Value Returns SUCCEED (0) if successful or FAIL (-1) otherwise. Arguments ann_id HDF AN annotation identifier returned by HDF_AN_SELECT, HDF_AN_CREATE or HDF_AN_CREATEF. ann_tag A named variable that will contain the HDF tag of the annotation. Possible values returned in ann_tag are: * 104 = data label (DFTAG_DIL) * 105 = data description (DFTAG_DIA) * 100 = file label (DFTAG_FID) * 101 = file description (DFTAG_FD) ann_ref A named variable that will contain the HDF reference number of the annotation. HDF_AN_NUMANN [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_AN_NUMANN This function returns the total number of HDF AN annotations that are of a given type and that are attached to the object identified by its HDF tag and its HDF reference number. Syntax Result = HDF_AN_NUMANN(an_id, annot_type, obj_tag, obj_ref) Return Value Returns the number of annotations or FAIL (-1) otherwise. Arguments an_id HDF AN interface identifier returned by HDF_AN_START. annot_type Type of the annotation. The following table lists the valid values of the parameter annot_type in the left column, and the corresponding values of the parameter ann_tag in the right column. Annotation Type HDF Annotation Tag 0 = Data Label (AN_DATA_LABEL) 104 (DFTAG_DIL) 1 = Data Description (AN_DATA_DESC) 105 (DFTAG_DIA) 2 = File Label (AN_FILE_LABEL) 100 (DFTAG_FID) 3 = File Description (AN_FILE_DESC) 101 (DFTAG_FD) Table 3-8: Valid annot_type and ann_tag values. obj_tag HDF tag of the object. obj_ref HDF reference number of the object. Since this routine is implemented only to obtain the total number of data annotations and not file annotations, the valid values of annot_type are: * 0 = data label * 1 = data description To obtain the total number of file annotations or all data annotations, use HDF_AN_FILEINFO. HDF_AN_READANN [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_AN_READANN This function reads the HDF AN annotation identified by the annotation identifier and stores the annotation into a variable. Syntax Result = HDF_AN_READANN( ann_id, annotation [, LENGTH=characters] ) Return Value Returns SUCCEED (0) if successful or FAIL (-1) otherwise. Arguments ann_id Annotation identifier returned by HDF_AN_CREATE, HDF_AN_CREATEF or HDF_AN_SELECT. annotation A named variable that will contain the annotation. Keywords LENGTH Specifies the number of characters to be read from the annotation argument. If LENGTH is not set, or LENGTH is greater than the number of characters in annotation, then the entire annotation is read. HDF_AN_SELECT [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_AN_SELECT This function obtains the HDF AN identifier of the annotation specified by its index and by its annotation type. Syntax Result = HDF_AN_SELECT(an_id, index, annot_type) Return Value Returns the annotation identifier (ann_id) if successful or FAIL (-1) otherwise. Arguments an_id HDF_AN_ INTERFACE identifier returned by HDF_AN_START. index Location of the annotation in the file. This parameter is a nonnegative integer and is less than the total number of annotations of type annot_type in the file minus 1. Use HDF_AN_FILEINFO to obtain the total number of annotations of each type in the file. annot_type Type of the annotation. Valid values of annot_type are: * 0 = data labels * 1 = data descriptions * 2 = file labels * 3 = file descriptions HDF_AN_START [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_AN_START This function initializes the HDF AN interface for the specified file. A call to HDF_AN_START is required before any HDF AN functions can be invoked. HDF_AN_START is used with the HDF_AN_END function to define the extent of an HDF AN session. A call to HDF_AN_END is required for each call to HDF_AN_START. Syntax Result = HDF_AN_START(file_id) Return Value Returns the HDF AN interface identifier (an_id) if successful or FAIL (-1) otherwise. Arguments file_id File identifier returned by HDF_OPEN. Note that each call to HDF_OPEN must be terminated with a call to HDF_CLOSE. HDF_AN_TAG2ATYPE [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_AN_TAG2ATYPE This function returns the HDF AN annotation type that corresponds to the specified HDF annotation tag. Syntax Result = HDF_AN_TAG2ATYPE(ann_tag) Return Value Returns the annotation type if successful or FAIL (-1) otherwise. Arguments ann_tag HDF tag of the annotation. The following table lists the valid values of ann_tag in the left column and the corresponding values of the returned annotation type in the right column. Annotation Type HDF Annotation Tag 0 = Data Label (AN_DATA_LABEL) 104 (DFTAG_DIL) 1= Data Description (AN_DATA_DESC) 105 (DFTAG_DIA) 2 = File Label (AN_FILE_LABEL) 100 (DFTAG_FID) 3 = File Description (AN_FILE_DESC) 101 (DFTAG_FD) Table 3-9: Valid annot_type and ann_tag values. HDF_AN_TAGREF2ID [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_AN_TAGREF2ID This function returns the HDF AN identifier of the annotation specified by its HDF tag and its HDF reference number. Syntax Result = HDF_AN_TAGREF2ID(an_id, ann_tag, ann_ref) Return Value Returns the annotation identifier (ann_id) if successful or FAIL (-1) otherwise. Arguments an_id HDF_AN_ INTERFACE identifier returned by HDF_AN_START. ann_tag HDF tag of the annotation. Valid values are: * 104 = data label (DFTAG_DIL) * 105 = data description (DFTAG_DIA) * 100 = file label (DFTAG_FID) * 101 = file description (DFTAG_FD) ann_ref HDF reference number of the annotation. HDF_AN_WRITEANN [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_AN_WRITEANN This function writes the annotation text provided in the parameter annotation to the HDF AN annotation specified by the parameter ann_id. Syntax Result = HDF_AN_WRITEANN( ann_id, annotation [, LENGTH=characters] ) Return Value Returns SUCCEED (0) if successful or FAIL (-1) otherwise. Arguments ann_id Annotation identifier returned by HDF_AN_CREATE, HDF_AN_CREATEF, or HDF_AN_SELECT. annotation Text or IDL variable to be written as the annotation. Keywords LENGTH Length of the annotation text to be written. If not specified, the entire annotation will be written. If the keyword LENGTH is set, then only LENGTH characters of the annotation will be written. If the annotation has already been written, HDF_AN_WRITEANN will overwrite the current text. HDF_CLOSE [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_CLOSE The HDF_CLOSE procedure closes the HDF file associated with the given file handle. Syntax HDF_CLOSE, FileHandle Arguments FileHandle The HDF file handle returned from a previous call to HDF_OPEN. See Also HDF_OPEN HDF_DELDD [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_DELDD The HDF_DELDD procedure deletes a tag or reference from the list of data descriptors in an HDF file. Syntax HDF_DELDD, FileHandle, Tag, Ref Arguments FileHandle The HDF file handle returned from a previous call to HDF_OPEN. Tag The data descriptor tag to delete. Ref The data descriptor reference number to delete. HDF_DF24_ADDIMAGE [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_DF24_ADDIMAGE The HDF_DF24_ADDIMAGE procedure writes a 24-bit raster image to an HDF file. The interlace is set automatically based upon the dimensions of the image being written: ARR(3, Width, Height) for pixel interlace, ARR(Width, 3, Height) for scan- line interlace, and ARR(Width, Height, 3) for scan-plane interlace. Note HDF_DF24_ADDIMAGE chooses an interlace based upon the location of the `3'- sized dimension. For 3x3xN, 3xNx3 and Nx3x3 images, if the first `3' encountered is supposed to be a width or height, HDF_DF24_ADDIMAGE will choose the `wrong' interlace. However, as long as one reads in the image using the same interlace, the image will be read correctly anyway. Avoid writing 24-bit-deep raster images with a width or height of 3 pixels. Note Input data is converted to bytes before being written to the file, as images in the DF24 HDF model are necessarily byte images. Syntax HDF_DF24_ADDIMAGE, Filename, Image [, /FORCE_BASELINE{useful only if QUALITY<25}] [, /JPEG | , /RLE] [, QUALITY=value{0 to 100}] Arguments Filename A scalar string containing the name of the file to be written. Image A 3-dimensional array of values representing the 3 planes (Red, Green, and Blue) of the 24-bit image. One of the dimensions must be 3 (e.g., a 3 x 100 x 100 array). Keywords FORCE_BASELINE Set this keyword to force the JPEG quantization tables to be constrained to the range 1 to 255. This provides full baseline compatibility with external JPEG applications, but only makes a difference if the QUALITY keyword is set to a value less than 25. The default is TRUE. JPEG Set this keyword to compress the image being added using the JPEG (Joint Photographic Expert Group) method. Note that JPEG compression is lossy; see WRITE_JPEG in the IDL Reference Guide for more information about when this method is appropriate. (In other words, using JPEG compression to reduce the size of an image changes the values of the pixels and hence may alter the meaning of the corresponding data.) Setting either the QUALITY or the FORCE_BASELINE keyword implies this method. QUALITY Set this keyword equal to the JPEG "quality" desired. This value should be in the range 0 (terrible image quality but excellent compression) to 100 (excellent image quality but minimum compression). The default is 75. Setting this keyword implies that the JPEG keyword is set. Lower values of QUALITY produce higher compression ratios and smaller files. RLE Set this keyword to store the image using run length compression. RLE compression is lossless, and is recommended for images where data retention is critical. See Also WRITE_JPEG HDF_DF24_GETIMAGE [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_DF24_GETIMAGE The HDF_DF24_GETIMAGE procedure reads a 24-bit raster image from an HDF file. The default is to use the same format for reading as that used in writing the image. Note: it is slower to read an image in a different interlace than the one in which the image was originally written. Syntax HDF_DF24_GETIMAGE, Filename, Image [, /LINE | , /PIXEL | , /PLANE] Arguments Filename A scalar string containing the name of the file to be read. Image A named variable in which the image data is returned. Keywords LINE Set this keyword to force the image to be read with scan-line interlace. PIXEL Set this keyword to force the image to be read with pixel interlace. PLANE Set this keyword to force the image to be read with scan-plane interlace. HDF_DF24_GETINFO [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_DF24_GETINFO The HDF_DF24_GETINFO procedure retrieves information about the current 24-bit HDF image. Syntax HDF_DF24_GETINFO, Filename, Width, Height, Interlace Arguments Filename A string containing the name of the file to be read. Width A named variable in which the width of the image is returned. Height A named variable in which the height of the image is returned. Interlace A named variable in which the interface method is returned. The returned value is 0 for pixel interlacing, 1 for scan-line interlacing, and 2 for scan-plane interlacing. Example ; Open the file myhdf.hdf: h = HDF_OPEN('myhdf.hdf') ; Return information about the 24-bit image: HDF_DF24_GETINFO, 'myhdf.hdf', width, height, interlace ; Print information about the returned variables: HELP, width, height, interlace HDF_CLOSE('myhdf.hdf') ; Close the HDF file. IDL Output If the image were 536 by 412 pixels, and scan-line interlaced, IDL would print: WIDTH LONG = 536 HEIGHT LONG = 412 INTERLACE LONG = 1 For a more detailed example, see the file hdf_info.pro, located in the examples/data_access/sdf subdirectory of the IDL distribution. See Also HDF_DF24_GETIMAGE, HDF_DF24_LASTREF, HDF_DF24_NIMAGES, HDF_DF24_READREF, HDF_DF24_RESTART HDF_DF24_LASTREF [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_DF24_LASTREF The HDF_DF24_LASTREF function returns the reference number of the most recently read or written 24-bit image in an HDF file. Syntax Result = HDF_DF24_LASTREF( ) Example ; Open an HDF file. h=HDF_OPEN('myhdf.hdf') PRINT, HDF_DF24_LASTREF() ; IDL prints 0, meaning that the call was successful, ; but no reference number was available. ; Create a 3D array, representing a 24-bit image: a = BINDGEN(3,100,100) ; Write the 24-bit image to the file: HDF_DF24_ADDIMAGE, 'myhdf.hdf', a PRINT, HDF_DF24_LASTREF() ; IDL prints a reference number for the last operation ; (for example, 2). Note the reference number is not ; simply a 1-based "image number"; the reference number ; could easily be "2" or "3", etc. ; Write another image to the file: HDF_DF24_ADDIMAGE, 'myhdf.hdf', a ; Print the last reference number: PRINT, HDF_DF24_LASTREF() PRINT, HDF_DF24_NIMAGES('myhdf.hdf') ; IDL prints "2" because we've written two images to the file. ; Close the file HDF_CLOSE, h See Also HDF_DF24_ADDIMAGE, HDF_DF24_GETIMAGE, HDF_DF24_GETINFO, HDF_DF24_NIMAGES, HDF_DF24_READREF, HDF_DF24_RESTART, HDF_DFR8_LASTREF HDF_DF24_NIMAGES [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_DF24_NIMAGES The HDF_DF24_NIMAGES function returns the number of 24-bit images in an HDF file. The function returns -1 if the specified file is invalid or damaged. Syntax Result = HDF_DF24_NIMAGES(Filename) Arguments Filename A string containing the name of the file to be searched. Example ; Open HDF file: h = HDF_OPEN('myhdf.hdf') ; Return the number of 24-bit images in the file: number = HDF_DF24_NIMAGES('myhdf.hdf') ; Print information about the returned value. If there were five ; images in the file, IDL would print NUMBER LONG = 5 HELP, number ; Close the HDF file: HDF_CLOSE, h See Also HDF_DF24_GETIMAGE, HDF_DF24_GETINFO, HDF_DF24_READREF, HDF_DF24_RESTART, HDF_DFR8_NIMAGES HDF_DF24_READREF [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_DF24_READREF The HDF_DF24_READREF procedure sets the reference number of the image in an HDF file to be read by the next call to HDF_DF24_GETIMAGE. Syntax HDF_DF24_READREF, Filename, Refno Arguments Filename A scalar string containing the name of the file to be read. Refno The reference number for a 24-bit raster image. HDF_DF24_RESTART [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_DF24_RESTART The HDF_DF24_RESTART procedure causes the next call to HDF_DF24_GETIMAGE to read the first 24-bit image in the HDF file. Syntax HDF_DF24_RESTART HDF_DFAN_ADDFDS [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_DFAN_ADDFDS The HDF_DFAN_ADDFDS procedure adds a file description to an HDF file. Syntax HDF_DFAN_ADDFDS, Filename, Description Arguments Filename A scalar string containing the name of the file to be written. Description A string or a array of bytes containing the information to be written. HDF_DFAN_ADDFID [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_DFAN_ADDFID The HDF_DFAN_ADDFID procedure adds a file annotation to an HDF file. A file can have multiple annotations added. Syntax HDF_DFAN_ADDFID, Filename, Label Arguments Filename A scalar string containing the name of the file to be written. Label A string containing the annotation string. Example ; Open the HDF file: filename = 'FID.hdf' hid = HDF_OPEN(filename,/CREATE) ; Write two file annotations: HDF_DFAN_ADDFID, filename, 'File Annotation #1' HDF_DFAN_ADDFID, filename, 'File Annotation #2' ; Read the two annotations back: HDF_DFAN_GETFID, filename, fid1 HDF_DFAN_GETFID, filename, fid2 HELP, fid1, fid2 ; Try to read a non-existent FID: HDF_DFAN_GETFID, filename, fid3 ; Read the FIRST fid again, using the FIRST keyword: HDF_DFAN_GETFID, filename, fid4, /FIRST HELP, fid4 ; Close the HDF file: HDF_CLOSE, hid IDL Output FID1 STRING = 'File Annotation #1' FID2 STRING = 'File Annotation #2' % HDF_DFAN_GETFID: Could not read ID length FID4 STRING = 'File Annotation #1' HDF_DFAN_GETDESC [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_DFAN_GETDESC The HDF_DFAN_GETDESC procedure reads the description for the given tag and reference number in an HDF file. Syntax HDF_DFAN_GETDESC, Filename, Tag, Ref, Description [, /STRING] Arguments Filename A scalar string containing the name of the file to be read. Tag The tag number. Ref The reference number. Description A named variable in which the description is returned as a vector of bytes. If a description does not exist, the Description variable will contain either a 0L (long- integer zero) or a blank string, and a warning message will be printed. Warning messages can be suppressed by setting the !QUIET system variable to a non-zero value. Keywords STRING Set this keyword to return the description as a string rather than a vector of bytes. Example desc1 = 'FILE DESCRIPTION NUMBER 1' tag_image = 302 file = 'DEMOdesc.hdf' fid = HDF_OPEN(file, /CREATE) HDF_DFR8_ADDIMAGE, file, DIST(10) HDF_DFAN_PUTDESC, file, tag_image, HDF_DFR8_LASTREF(), desc1 ; Read the description and return a vector of bytes: HDF_DFAN_GETDESC, file, tag_image, HDF_DFR8_LASTREF(), out_desc1 HELP, out_desc1 PRINT, STRING(out_desc1) ; Read the description and return an IDL string variable: HDF_DFAN_GETDESC, file, tag_image, HDF_DFR8_LASTREF(), $ out_desc2, /STRING HELP, out_desc2 HDF_CLOSE, fid IDL Output OUT_DESC1 BYTE = Array(25) FILE DESCRIPTION NUMBER 1 OUT_DESC2 STRING = 'FILE DESCRIPTION NUMBER 1' See Also HDF_DFAN_PUTDESC HDF_DFAN_GETFDS [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_DFAN_GETFDS The HDF_DFAN_GETFDS procedure reads the next available file description from an HDF file. Syntax HDF_DFAN_GETFDS, Filename, Description [, /FIRST] [, /STRING] Arguments Filename A string containing the name of the file to be read. Description A named variable in which the description is returned. By default, the description is returned as a vector of bytes. Set the STRING keyword to return the description as a string. If a description does not exist, the Description variable will contain either a 0L (long- integer zero) or a blank string, and a warning message will be printed. Warning messages can be suppressed by setting the !QUIET system variable to a non-zero value. Keywords FIRST Set this keyword to read the first file description in the file. If FIRST is not set, the next available file description (which can be the first file description) will be read. STRING Set this keyword to return Description as a string instead of a vector of bytes. Example filename = 'DEMOfds.hdf' fds1 = 'FILE DESCRIPTION NUMBER 1' fds2 = 'SHORT FDS 2' ; Create an HDF file: fid = HDF_OPEN(filename, /CREATE) ; Add first file description: HDF_DFAN_ADDFDS, filename, fds1 ; Add second file description: HDF_DFAN_ADDFDS, filename, fds2 ; Get the first file description: HDF_DFAN_GETFDS, filename, out_fds1, /FIRST HELP, out_fds1 PRINT, STRING(out_fds1) ; Get the second file description: HDF_DFAN_GETFDS, filename, out_fds2, /STRING HELP, out_fds2 ; Close the HDF file: HDF_CLOSE, fid IDL Output OUT_FDS1 BYTE = Array(25) FILE DESCRIPTION NUMBER 1 OUT_FDS2 STRING = 'SHORT FDS 2' See Also HDF_DFAN_ADDFDS, HDF_DFAN_ADDFID, HDF_DFAN_GETDESC, HDF_DFAN_GETFID HDF_DFAN_GETFID [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_DFAN_GETFID The HDF_DFAN_GETFID procedure reads the next available file annotation from an HDF file. Syntax HDF_DFAN_GETFID, Filename, Label [, /FIRST] Arguments Filename A scalar string containing the name of the file to be read. Label A named variable in which the annotation is returned as a string. Keywords FIRST Set this keyword to read the first annotation in the file. Otherwise, the next available annotation is read (which may be the first annotation). Example For an example using this routine, see "HDF_DFAN_ADDFID" on page 133. HDF_DFAN_GETLABEL [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_DFAN_GETLABEL The HDF_DFAN_GETLABEL procedure reads the label for the given tag-reference pair in an HDF file. Syntax HDF_DFAN_GETLABEL, Filename, Tag, Ref, Label Arguments Filename A scalar string that contains the name of the file to be read. Tag The tag number. Ref The reference number. Label A named variable in which the label is returned as a string. Example fid = HDF_OPEN('test.hdf', /ALL) label = 'TEST LABEL' tag = 105 ; The annotation tag. ref = 2 ; Choose a reference number. ; Write the label: HDF_DFAN_PUTLABEL, 'test.hdf', tag, ref, label ; Read back the label: HDF_DFAN_GETLABEL, 'test.hdf', tag, ref, outl HELP, outl ; They look the same... ; OUTL STRING = 'TEST LABEL' ; Close the HDF file: HDF_CLOSE, fid See Also HDF_DFAN_GETDESC, HDF_DFAN_LABLIST, HDF_DFAN_PUTDESC, HDF_DFAN_PUTLABEL HDF_DFAN_LABLIST [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_DFAN_LABLIST The HDF_DFAN_LABLIST function retrieves a list of the reference numbers and the corresponding labels for a given tag in an HDF file. If successful, the number of entries found is returned. Syntax Result = HDF_DFAN_LABLIST( Filename, Tag, Reflist, Labellist [, LISTSIZE=value] [, MAXLABEL=value] [, STARTPOS=value] [, /STRING] ) Arguments Filename A scalar string containing the name of the file to be read. Tag The tag number. Reflist A named variable in which an array of reference numbers associated with the given tag is returned. Labellist A named variable in which an array of labels is returned. Unless the STRING keyword is set, Labellist will contain an N_ELEMENTS(Reflist) by MAXLABEL array of bytes. Note that array elements containing labels that are shorter than MAXLABEL will be padded with zeroes. Keywords LISTSIZE Set the maximum size of the Reflist and Labellist returned. The default is to read all references present, or 20 if the inquiry to obtain the number of references fails. MAXLABEL Use this keyword to override the default label length of 16. STARTPOS Use this keyword to set the default starting position in the Reflist array. STRING Set this keyword to return an array of strings rather than an array of bytes. If STRING is set, the MAXLABEL keyword is ignored and full-length strings are returned. Example tag_image = 302 file = 'DEMOlablist.hdf' n_images = HDF_DFAN_LABLIST(file, tag_image, refs, list, /STRING) help, n_images, refs, list PRINT, list(0) ; Find all the compressed images: tag_image_comp = 303 n_comp_images = HDF_DFAN_LABLIST(file, tag_image_comp, $ refs, list, MAXLABEL=5) HELP, n_comp_images, refs, list IDL Output N_IMAGES LONG = 2 REFS INT = Array(2) LIST STRING = Array(2) SAMPLE IMAGE LABEL N_COMP_IMAGES LONG = 3 REFS INT = Array(3) LIST BYTE = Array(5, 3) See Also HDF_DFAN_GETLABEL, HDF_DFAN_PUTLABEL HDF_DFAN_LASTREF [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_DFAN_LASTREF The HDF_DFAN_LASTREF function returns the reference number of the most recently read or written annotation in an HDF file. Syntax Result = HDF_DFAN_LASTREF( ) HDF_DFAN_PUTDESC [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_DFAN_PUTDESC The HDF_DFAN_PUTDESC procedure writes a description for the given tag and reference number in an HDF file. Syntax HDF_DFAN_PUTDESC, Filename, Tag, Ref, Description Arguments Filename A scalar string containing the name of the file to be written. Tag The tag number. Ref The reference number. Description A string or array of bytes containing the information to be written. If a description does not exist, the Description variable will contain either a 0L (long- integer zero) or a blank string, and a warning message will be printed. Warning messages can be suppressed by setting the !QUIET system variable to a non-zero value. Bugs Attempting to overwrite an existing description with a longer one fails. Overwriting an existing description with a shorter description succeeds, but the description length is unchanged and garbage characters are left at the end of the description. Example See the example for "HDF_DFAN_GETDESC" on page 134. HDF_DFAN_PUTLABEL [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_DFAN_PUTLABEL The HDF_DFAN_PUTLABEL procedure writes a label for the given tag and reference number in an HDF file. Syntax HDF_DFAN_PUTLABEL, Filename, Tag, Ref, Label Arguments Filename A scalar string containing the name of the file to be written. Tag The tag number. Ref The reference number. Label A string containing the description to write. Bugs Due to a problem in the HDF version 4.0 library, attempting to rewrite a label fails. For example: file = 'blah.hdf' ; Specify a file ; Specify tag and reference numbers: tag = 105 & ref = 40 ; Make label "XXXX": HDF_DFAN_PUTLABEL, file, tag, ref, 'XXXX' ; Label now "YY": HDF_DFAN_PUTLABEL, file, tag, ref, 'YY' ; Delete the file: OPENU, unit, file, /DELETE, /GET & CLOSE, unit ; Now try to re-use label "XXXX": HDF_DFAN_PUTLABEL, file, tag, ref, 'XXXX' IDL Output % HDF_DFAN_PUTLABEL: Failed to write label % Execution halted at: $MAIN$ HDF_DFP_ADDPAL [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_DFP_ADDPAL The HDF_DFP_ADDPAL procedure appends a palette to an HDF file. Syntax HDF_DFP_ADDPAL, Filename, Palette Arguments Filename A scalar string containing the name of the file to be written. Palette A vector or array containing palette data. Palettes must be either [3, 256] arrays or 786-element vectors. HDF_DFP_GETPAL [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_DFP_GETPAL The HDF_DFP_GETPAL procedure reads the next available palette from an HDF file. Syntax HDF_DFP_GETPAL, Filename, Palette Arguments Filename A scalar string containing the name of the file to be read. Palette A named variable in which the palette data is returned. HDF_DFP_LASTREF [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_DFP_LASTREF The HDF_DFP_LASTREF function returns the reference number of the most recently read or written palette in an HDF file. Syntax Result = HDF_DFP_LASTREF( ) HDF_DFP_NPALS [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_DFP_NPALS The HDF_DFP_NPALS function returns the number of palettes present in an HDF file. This number includes palettes associated with RIS8 (8-bit raster) images. Syntax Result = HDF_DFP_NPALS(Filename) Arguments Filename A scalar string containing the name of the desired HDF file. HDF_DFP_PUTPAL [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_DFP_PUTPAL The HDF_DFP_PUTPAL procedure appends a palette to an HDF file. Syntax HDF_DFP_PUTPAL, Filename, Palette [, /DELETE] [, /OVERWRITE] Arguments Filename A scalar string containing the name of the file to be written. Palette A vector or array containing palette data. Palettes must be either [3, 256] arrays or 786-element vectors. Keywords DELETE Set this keyword to delete the HDF file (if it exists) and create a new HDF file with the specified palette as its first object. Note The HDF file must be closed before the DELETE keyword is specified. Attempting to delete an open HDF file will result in an error. OVERWRITE Set this keyword to overwrite the previous palette with the one specified by Palette. Example ; Create HDF file: id = HDF_OPEN('test.hdf', /CREATE, /RDWR) ; Add a palette: HDF_DFP_PUTPAL,'test.hdf'', FINDGEN(3,256) ; Print number of palettes: PRINT, HDF_DFP_NPALS('test.hdf') ; Append a palette: HDF_DFP_PUTPAL,'test.hdf',findgen(3,256) ; Print the number of palettes: PRINT, HDF_DFP_NPALS('test.hdf') ; Overwrite the last palette: HDF_DFP_PUTPAL, 'test.hdf', FINDGEN(3,256), /OVERWRITE ; Print the number of palettes: PRINT, HDF_DFP_NPALS('test.hdf') ; An attempt to delete a file and add a new palette ; without first closing the HDF file fails: HDF_DFP_PUTPAL, 'test.hdf', $ FINDGEN(3,256), /DELETE ; Close the HDF file: HDF_CLOSE, id ; Delete file and add a new palette: HDF_DFP_PUTPAL, 'test.hdf', FINDGEN(3,256), /DELETE ; Print the number of palettes: PRINT, HDF_DFP_NPALS('test.hdf') IDL Output 1 2 2 % HDF_DFP_PUTPAL: Could not write palette % Execution halted at: $MAIN$ 1 HDF_DFP_READREF [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_DFP_READREF The HDF_DFP_READREF procedure sets the reference number of the palette in an HDF file to be read by the next call to HDF_DFP_GETPAL. Syntax HDF_DFP_READREF, Filename, Refno Arguments Filename A scalar string containing the name of the file to be read. Refno The reference number of a palette. HDF_DFP_RESTART [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_DFP_RESTART The HDF_DFP_RESTART procedure causes the next call to HDF_DFR8_GETPAL to read from the first palette in an HDF file. Syntax HDF_DFP_RESTART HDF_DFP_WRITEREF [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_DFP_WRITEREF The HDF_DFP_WRITEREF procedure sets the reference number for the next palette to be written to an HDF file. Normally, the HDF library automatically chooses a reference number for the palette. This procedure allows you to override that choice. Syntax HDF_DFP_WRITEREF, Filename, Refno Arguments Filename A scalar string containing the name of the file to be read. Refno The new reference number. HDF_DFR8_ADDIMAGE [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_DFR8_ADDIMAGE The HDF_DFR8_ADDIMAGE procedure appends an 8-bit raster image to the specified HDF file. Note Input data is converted to bytes before being written to the file, as images in the DFR8 HDF model are necessarily byte images. Syntax HDF_DFR8_ADDIMAGE, Filename, Image [, /FORCE_BASELINE{useful only if QUALITY<25}] [, /JPEG | , /RLE] [[, /IMCOMP] , PALETTE=vector or array] [, QUALITY=value] Arguments Filename A scalar string containing the name of the file to be written. Image A two-dimensional array containing the image data. If this array is not byte-type data, it is converted to bytes before writing. Keywords FORCE_BASELINE Set this keyword to force the JPEG quantization tables to be constrained to the range 1...255. This provides full baseline compatibility with external JPEG applications, but only makes a difference if the QUALITY keyword is set to a value less than 25. The default is TRUE. JPEG Set this keyword to compress the image being added using the JPEG (Joint Photographic Expert Group) method. Note that JPEG compression is lossy; see WRITE_JPEG in the IDL Reference Guide for more information about when this method is appropriate. (In other words, using JPEG compression to reduce the size of an images changes the values of the pixels and hence may alter the meaning of the corresponding data.) Setting either the QUALITY or the FORCE_BASELINE keywords implies this method. IMCOMP Set this keyword to store the image using imcomp data compression. Note that you must specify a palette. Note also that the JPEG and RLE compression methods are far superior; imcomp data compression should only be used if the images will be viewed on monitors with a very small number of colors (monochrome or 16-color). PALETTE Set this keyword to a vector or array containing valid palette data. Palettes must be either [3, 256] arrays or 786-element vectors. Set PALETTE equal to zero to specify that no palette be used. If the PALETTE keyword is not specified, the current palette (which may be no palette, if a palette has not been specified elsewhere or if the null palette has been explicitly specified with HDF_DFR8_SETPALETTE) will be used. Note that if a palette is specified, it becomes the current palette, even if a default palette has been specified with HDF_DFR8_SETPALETTE. Note also that if IMCOMP data reduction is used, you must specify a valid palette with the PALETTE keyword. It is not sufficient to set the current palette via other means. QUALITY Set this keyword equal to the JPEG "quality" desired. This value should be in range 0 (terrible image quality but excellent compression) to 100 (excellent image quality but minimum compression). The default is 75. Setting this keyword implies that the JPEG keyword is set. Lower values of QUALITY produce higher compression ratios and smaller files. RLE Set this keyword to store the image using run length compression. RLE compression is lossless, and is recommended for images where data retention is critical. Example Assuming that we start with a file, new.hdf, with no 8-bit raster images, images could be appended and overwritten, with the following commands: ; Write the first image to the file: HDF_DFR8_ADDIMAGE, 'new.hdf', Image1 ; Append 2nd image: HDF_DFR8_ADDIMAGE, 'new.hdf', Image2 ; Append 3rd image: HDF_DFR8_ADDIMAGE, 'new.hdf', Image3 ; Use HDF_DFR8_PUTIMAGE to erase all previous images and ; write a new image at the first position in the file: HDF_DFR8_PUTIMAGE, 'new.hdf', Image4 ; Append 2nd image: HDF_DFR8_ADDIMAGE, 'new.hdf', Image5 See Also HDF_DFR8_GETIMAGE, HDF_DFR8_PUTIMAGE, WRITE_JPEG HDF_DFR8_GETIMAGE [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_DFR8_GETIMAGE The HDF_DFR8_GETIMAGE procedure retrieves an image and optionally, its palette, from an HDF file. Syntax HDF_DFR8_GETIMAGE, Filename, Image [, Palette] Arguments Filename A scalar string containing the name of the file to be read. Image A named variable in which the image is returned. Palette A named variable in which the palette is returned as a 3-element by 256-element byte array. If the image does not have an associated palette, this variable is returned as 0. HDF_DFR8_GETINFO [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_DFR8_GETINFO The HDF_DFR8_GETINFO procedure retrieves information about the current 8-bit HDF image. Syntax HDF_DFR8_GETINFO, Filename, Width, Height, Has_Palette Arguments Filename A string containing the name of the file to be read. Width A named variable in which the width of the image is returned. Height A named variable in which the height of the image is returned. Has_Palette A named variable in which 1 is returned if a palette is present. Otherwise, 0 is returned. Example ; Open the file myhdf.hdf: h = HDF_OPEN('myhdf.hdf') ; Retrieve info about an image: HDF_DFR8_GETINFO, 'myhdf.hdf', width, height, has_palette ; Print info about returned variables: HELP, width, height, has_palette ; Close the HDF file: HDF_CLOSE('myhdf.hdf') IDL Output WIDTH LONG = 536 HEIGHT LONG = 412 HAS_PALETTE LONG = 1 For a more detailed example, see the file hdf_info.pro, located in the examples/data_access/sdf subdirectory of the IDL distribution. See Also HDF_DFR8_GETIMAGE, HDF_DFR8_NIMAGES, HDF_DFR8_READREF, HDF_DFR8_RESTART HDF_DFR8_LASTREF [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_DFR8_LASTREF The HDF_DFR8_LASTREF function returns the reference number of the most recently read or written 8-bit image in an HDF file. Syntax Result = HDF_DFR8_LASTREF( ) Example h = HDF_OPEN('myhdf.hdf') ; Open an hdf file. ;IDL prints "0", meaning that the call was successful, ; but no reference number was available: PRINT, HDF_DFR8_LASTREF() ;Create a 2D array representing an 8-bit image: a = BINDGEN(100,100) ; Write the image to the file: HDF_DFR8_ADDIMAGE, 'myhdf.hdf', a ;IDL prints the reference number for the last 8-bit image ; operation (for example, "2"). Note the reference number ; is not simply a 1-based "image number"; it could easily be ; "2" or "3" for the first operation on the file: PRINT, HDF_DFR8_LASTREF() HDF_DFR8_ADDIMAGE, 'myhdf.hdf', a ; Add another image. ; IDL prints "2", because we've put two 8-bit images in the file: PRINT, HDF_DFR8_NIMAGES('myhdf.hdf') HDF_CLOSE, h ; Close the file. See Also HDF_DFR8_ADDIMAGE, HDF_DFR8_GETIMAGE, HDF_DFR8_GETINFO, HDF_DFR8_LASTREF, HDF_DFR8_NIMAGES, HDF_DFR8_READREF, HDF_DFR8_RESTART HDF_DFR8_NIMAGES [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_DFR8_NIMAGES The HDF_DFR8_NIMAGES function returns the number of 8-bit images in the specified HDF file. The function returns -1 if the specified file is invalid or damaged. Syntax Result = HDF_DFR8_NIMAGES(Filename) Arguments Filename A string containing the name of the file to be read. Example ; Open the file myhdf.hdf: h = HDF_OPEN('myhdf.hdf') ; Retrieve the number of 8-bit images in the file into a variable: number = HDF_DFR8_NIMAGES('myhdf.hdf') HDF_CLOSE, h ; Close the file. See Also HDF_DFR8_GETIMAGE, HDF_DFR8_GETINFO, HDF_DFR8_READREF HDF_DFR8_RESTART HDF_DFR8_PUTIMAGE [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_DFR8_PUTIMAGE The HDF_DFR8_PUTIMAGE procedure writes an 8-bit raster image as the first image in an HDF file. If there are images in the file, this procedure erases all other 8- bit and 24-bit images and writes Image as the first image in the file. Note Input data is converted to bytes before being written to the file, as images in the DFR8 HDF model are necessarily byte images. Syntax HDF_DFR8_PUTIMAGE, Filename, Image [, /FORCE_BASELINE{useful only if QUALITY<25}] [[, /IMCOMP] , PALETTE=vector or array] [, /JPEG | , /RLE] [, QUALITY=value] Arguments Filename A scalar string containing the name of the file to be written. Image A two-dimensional array containing the image data. If this array is not byte-type data, it is converted to bytes before writing. Keywords FORCE_BASELINE Set this keyword to force the JPEG quantization tables to be constrained to the range 1...255. This provides full baseline compatibility with external JPEG applications, but only makes a difference if the QUALITY keyword is set to a value less than 25. The default is TRUE. JPEG Set this keyword to compress the image being added using the JPEG (Joint Photographic Expert Group) method. Note that JPEG compression is lossy; see WRITE_JPEG in the IDL Reference Guide for more information about when this method is appropriate. (In other words, using JPEG compression to reduce the size of an images changes the values of the pixels and hence may alter the meaning of the corresponding data.) Setting either the QUALITY or the FORCE_BASELINE keywords implies this method. IMCOMP Set this keyword to store the image using imcomp data compression. Note that you must specify a palette. Note also that the JPEG and RLE compression methods are far superior; imcomp data compression should only be used if the images will be viewed on monitors with a very small number of colors (monochrome or 16-color). PALETTE Set this keyword to a vector or array containing valid palette data. Palettes must be either [3, 256] arrays or 786-element vectors. Set PALETTE equal to zero to specify that no palette be used. If the PALETTE keyword is not specified, the current palette (which may be no palette, if a palette has not been specified elsewhere or if the null palette has been explicitly specified with HDF_DFR8_SETPALETTE) will be used. Note that if a palette is specified, it becomes the current palette, even if a default palette has been specified with HDF_DFR8_SETPALETTE. Note also that if IMCOMP data reduction is used, you must specify a valid palette with the PALETTE keyword. It is not sufficient to set the current palette via other means. QUALITY Set this keyword equal to the JPEG "quality" desired. This value should be in range 0 (terrible image quality but excellent compression) to 100 (excellent image quality but minimum compression). The default is 75. Setting this keyword implies that the JPEG keyword is set. Lower values of QUALITY produce higher compression ratios and smaller files. RLE Set this keyword to store the image using run length compression. RLE compression is lossless, and is recommended for images where data retention is critical. See Also HDF_DFR8_ADDIMAGE, HDF_DFR8_GETIMAGE, WRITE_JPEG HDF_DFR8_READREF [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_DFR8_READREF The HDF_DFR8_READREF procedure sets the reference number of the image to be read from an HDF file by the next call to HDF_DFR8_GETIMAGE. Syntax HDF_DFR8_READREF, Filename, Refno Arguments Filename A scalar string containing the name of the file to be read. Refno A reference number for an 8-bit raster image. HDF_DFR8_RESTART [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_DFR8_RESTART The HDF_DFR8_RESTART procedure causes the next call to HDF_DFR8_GETIMAGE to read from the first image in the HDF file. Syntax HDF_DFR8_RESTART HDF_DFR8_SETPALETTE [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_DFR8_SETPALETTE The HDF_DFR8_SETPALETTE procedure sets the current palette to be used for subsequent images in an HDF file. The current palette will be used when adding images with the HDF_DFR8_ADDIMAGE routine. Syntax HDF_DFR8_SETPALETTE, Palette Arguments Palette A 768-element byte array of palette data. This array be a vector (e.g., BYTARR(768)) or a two-dimensional array (e.g., BYTARR(3, 256)). Set the Palette array to the integer zero to set the current palette to no palette. HDF_DUPDD [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_DUPDD The HDF_DUPDD procedure generates new references to existing data in an HDF file. Syntax HDF_DUPDD, FileHandle, NewTag, NewRef, OldTag, OldRef Arguments FileHandle The HDF file handle returned from a previous call to HDF_OPEN. NewTag An integer tag for new data descriptor. NewRef An integer reference number for the new data descriptor. OldTag The integer tag of data descriptor to duplicate. OldRef The reference number of data descriptor to duplicate. HDF_EXISTS [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_EXISTS The HDF_EXISTS function returns True if the HDF scientific data format library is supported on the current IDL platform. This routine is written in the IDL language. Its source code can be found in the file hdf_exists.pro in the lib subdirectory of the IDL distribution. Syntax Result = HDF_EXISTS( ) Example The following IDL command prints an error message if the HDF library is not available: IF HDF_EXISTS() EQ 0 THEN PRINT, 'HDF not supported.' HDF_GR_ATTRINFO [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_GR_ATTRINFO This function retrieves the name, data type, and number of values of the attribute for the HDF data object identified by the parameter obj_id. Syntax Result = HDF_GR_ATTRINFO(obj_id, attr_index, name, data_type, count) Return Value Returns SUCCEED (0) if successful or FAIL (-1) otherwise. Arguments obj_id Raster image identifier (ri_id), returned by HDF_GR_CREATE or HDF_GR_SELECT, or HDF GR interface identifier (gr_id), returned by HDF_GR_START. attr_index Index of the attribute. The value of this parameter can be obtained using HDF_GR_FINDATTR, HDF_GR_NAMETOINDEX or HDF_GR_REFTOINDEX, depending on available information. Valid values range from 0 to the total number of attributes attached to the object minus 1. The total number of attributes attached to the file can be obtained using the routine HDF_GR_FILEINFO. The total number of attributes attached to an image can be obtained using the routine HDF_GR_GETIMINFO. name A named variable in which the name of the attribute is returned. data_type A named variable in which the attribute data type is returned. See "IDL and HDF Data Types" on page 96. count A named variable in which the number of attributes is returned. HDF_GR_CREATE [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_GR_CREATE This function creates an HDF GR raster image. Once a raster image has been created, it is not possible to change its name, data type, dimension sizes or number of pixel components. However, it is possible to create a raster image and close the file before writing any data values to it. Later, the values can be added to or modified in the raster image, which then can be obtained using HDF_GR_SELECT. Note On creation, any interlace mode may be set. This mode will be used until the file is closed. If the resulting file is reopened, the interlace mode will revert to pixel- interlace (0). Data can still be read in any interlace mode using the INTERLACE keyword to HDF_GR_READIMAGE. This is a limitation of the current HDF library. Syntax Result = HDF_GR_CREATE(gr_id, name, ncomp, data_type, interlace_mode, dim_sizes) Return value Returns a raster image identifier if successful or FAIL (-1) otherwise. Arguments gr_id GR interface identifier returned by HDF_GR_START. name Name of the raster image. The length of the name should not be longer than 256 characters. ncomp Number of pixel components in the image. This parameter must have a value of at least 1. data_type Type of the image data. This parameter can be any of the data types supported by the HDF library. See "IDL and HDF Data Types" on page 96. interlace_mode Interlace mode of the image data. Valid values are: * 0 = Pixel interlace * 1 = Line interlace * 2 = Component interlace dim_sizes Array of sizes for each dimension of the image. The dimensions must be specified and their values must be greater than 0. HDF_GR_END [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_GR_END This procedure terminates the HDF GR interface session identified by the parameter gr_id. HDF_GR_END, together with HDF_GR_START, define the extent of a HDF GR interface session. HDF_GR_END disposes of the internal structures initialized by the corresponding call to HDF_GR_START. There must be a call to HDF_GR_END for each call to HDF_GR_START; failing to provide one may cause loss of data. HDF_GR_START and HDF_GR_END do not manage file access; use HDF_OPEN and HDF_CLOSE to open and close HDF files. HDF_OPEN must be called before HDF_GR_START and HDF_CLOSE must be called after HDF_GR_END. Failure to properly close the HDF file with HDF_GR_END and HDF_CLOSE may result in lost data or corrupted HDF files. Syntax HDF_GR_END, gr_id Arguments gr_id HDF GR interface identifier returned by HDF_GR_START. HDF_GR_ENDACCESS [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_GR_ENDACCESS This procedure terminates access to the raster image identified by the parameter ri_id and disposes of the raster image identifier. This access is initiated by either HDF_GR_SELECT or HDF_GR_CREATE. There must be a call to HDF_GR_ENDACCESS for each call to HDF_GR_SELECT or HDF_GR_CREATE; failing to provide this will result in loss of data. Syntax HDF_GR_ENDACCESS, ri_id Arguments ri_id Raster image identifier returned by HDF_GR_CREATE or HDF_GR_SELECT. HDF_GR_FILEINFO [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_GR_FILEINFO This function retrieves the number of raster images and the number of global attributes for the HDF GR interface identified by the parameter gr_id, and stores them into the parameters n_images and n_file_attrs, respectively. The term "global attributes" refers to attributes that are assigned to the file instead of individual raster images. These attributes are created by HDF_GR_SETATTR with the object identifier parameter set to a HDF GR interface identifier (gr_id) rather than a raster image identifier (ri_id). HDF_GR_FILEINFO is useful in finding the range of acceptable indices for HDF_GR_SELECT calls. Syntax Result = HDF_GR_FILEINFO(gr_id, n_images, n_file_attrs) Return Value Returns SUCCEED (or 0) if successful or FAIL (-1) otherwise. Arguments gr_id HDF GR interface identifier returned by HDF_GR_START. n_images A named variable that will contain the number of raster images in the file. n_file_attrs A named variable that will contain the number of global attributes in the file. HDF_GR_FINDATTR [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_GR_FINDATTR This function finds the index of an HDF data object's attribute given its attribute name. HDF_GR_FINDATTR returns the index of the attribute whose name is specified by the parameter attr_name for the object identified by the parameter obj_id. Syntax Result = HDF_GR_FINDATTR(obj_id, attr_name) Return Value Returns the index of the attribute if successful or FAIL (-1) otherwise. Arguments obj_id Raster image identifier (ri_id), returned by HDF_GR_CREATE or HDF_GR_SELECT, or HDF GR interface identifier (gr_id), returned by HDF_GR_START. attr_name Name of the attribute. HDF_GR_GETATTR [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_GR_GETATTR This function obtains all values of the HDF GR attribute that is specified by its index, attr_index, and is attached to the object identified by the parameter obj_id. Syntax Result = HDF_GR_GETATTR(obj_id, attr_index, values) Return Value Returns SUCCEED (0) if successful or FAIL (-1) otherwise. Arguments obj_id Raster image identifier (ri_id), returned by HDF_GR_CREATE or HDF_GR_SELECT, or HDF GR interface identifier (gr_id), returned by HDF_GR_START. attr_index Index of the attribute. The value of the parameter attr_index can be obtained by using HDF_GR_FINDATTR, HDF_GR_NAMETOINDEX, or HDF_GR_REFTOINDEX, depending on available information. Valid values of attr_index range from 0 to the total number of attributes of the object - 1. The total number of attributes attached to the file can be obtained using the routine HDF_GR_FILEINFO. The total number of attributes attached to the image can be obtained using the routine HDF_GR_GETIMINFO. HDF_GR_GETATTR only reads all values assigned to the attribute and not a subset. values A named variable that will contain the attribute values. HDF_GR_GETCHUNKINFO [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_GR_GETCHUNKINFO This function retrieves chunking information about the HDF GR raster image identified by the parameter ri_id into the parameters dim_length and flag. Note that only chunk dimensions are retrieved; compression information is not available with this function. Syntax Result = HDF_GR_GETCHUNKINFO(ri_id, dim_length, flag) Return Value Returns SUCCEED (0) if successful or FAIL (-1) otherwise. Arguments ri_id Raster image identifier returned by HDF_GR_CREATE or HDF_GR_SELECT. dim_length A named variable that will contain the array of chunk dimensions. flag A named variable that will contain the compression/chunk flag. The value returned in the parameter flag indicates if the raster image is not chunked, chunked, or chunked and compressed. The following table shows the possible values of the parameter flag and the corresponding characteristics of the raster image. Values of flag = Raster Image Characteristics * -1 = Not chunked * 0 = Chunked and not compressed * 1 = Chunked and compressed with either the run-length encoding (RLE), Skipping Huffman or GZIP compression algorithms HDF_GR_GETIMINFO [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_GR_GETIMINFO This function retrieves general information about an HDF GR raster image. HDF_GR_GETIMINFO retrieves the name, number of components, data type, interlace mode, dimension sizes, and number of attributes of the raster image identified by the parameter ri_id. It also retrieves the number of attributes attached to the image into the parameter num_attrs. Syntax Result = HDF_GR_GETIMINFO(ri_id, gr_name, ncomp, data_type, interlace_mode, dim_sizes, num_attrs) Return Value Returns SUCCEED (0) if successful or FAIL (-1) otherwise. Arguments ri_id Raster image identifier returned by HDF_GR_CREATE or HDF_GR_SELECT. gr_name A named variable that will contain the name of the raster image. ncomp A named variable that will contain the number of components in the raster image. data_type A named variable that will contain the data type of the raster image data. The valid values of the parameter data_type are listed in "IDL and HDF Data Types" on page 96. interlace_mode A named variable that will contain the interlace mode of the stored raster image data. * 0 = Pixel interlace * 1 = Line interlace * 2 = Component interlace dim_sizes A named variable that will contain the sizes of the raster image dimensions. num_attrs A named variable that will contain the number of attributes attached to the raster image. HDF_GR_GETLUTID [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_GR_GETLUTID This function gets the identifier of the HDF GR palette attached to the raster image identified by the parameter ri_id. Syntax Result = HDF_GR_GETLUTID(ri_id, pal_index) Return Value Returns the palette identifier if successful or FAIL (-1) otherwise. Arguments ri_id Raster image identifier returned by HDF_GR_CREATE or HDF_GR_SELECT. pal_index Index of the palette. Currently, only one palette can be assigned to a raster image, which means that pal_index should always be set to 0. HDF_GR_GETLUTINFO [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_GR_GETLUTINFO This function retrieves the number of pixel components, data type, interlace mode, and number of color lookup table entries of the palette identified by the parameter pal_id. Syntax Result = HDF_GR_GETLUTINFO(pal_id, ncomp, data_type, interlace_mode, num_entries) Return value Returns SUCCEED (0) if successful or FAIL (-1) otherwise. Arguments pal_id Palette identifier returned by HDF_GR_GETLUTID. ncomp A named variable in which the number of components in the palette is returned. data_type A named variable in which the HDF data type of the palette is returned. See "IDL and HDF Data Types" on page 96 for a description of the HDF data types. interlace_mode A named variable in which the interlace mode of the stored palette data is returned. * 0 = Pixel interlace * 1 = Line interlace * 2 = Component interlace num_entries A named variable in which the number of color lookup table entries in the palette is returned. HDF_GR_IDTOREF [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_GR_IDTOREF This function returns the HDF reference number of the raster image identified by the parameter ri_id. This routine is commonly used for the purpose of annotating the raster image or including the raster image within an HDF Vgroup. Syntax Result = HDF_GR_IDTOREF(ri_id) Return Value Returns the HDF reference number of the raster image if successful or not found (0) otherwise. Arguments ri_id Raster image identifier returned by HDF_GR_SELECT or HDF_GR_CREATE. HDF_GR_LUTTOREF [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_GR_LUTTOREF This function returns the HDF reference number of the palette identified by the parameter pal_id. This function is commonly used for the purpose of annotating the palette or including the palette within a HDF Vgroup. Syntax Result = HDF_GR_LUTTOREF(pal_id) Return value Returns the reference number of the palette if successful or not found (0) otherwise. Arguments pal_id Palette identifier returned by HDF_GR_GETLUTID. HDF_GR_NAMETOINDEX [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_GR_NAMETOINDEX This function returns the index of the raster image named gr_name for the HDF GR interface identified by the parameter gr_id. The value of index can be passed into HDF_GR_SELECT to obtain the raster image identifier (ri_id). Syntax Result = HDF_GR_NAMETOINDEX(gr_id, gr_name) Return Value Returns the index of the raster image if successful or FAIL (-1) otherwise. Arguments gr_id HDF_GR_ interface identifier returned by HDF_GR_START. gr_name Name of the raster image. HDF_GR_READIMAGE [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_GR_READIMAGE This function reads the subsample of the HDF GR raster image specified by the parameter ri_id into the variable data. Syntax Result = HDF_GR_READIMAGE( ri_id, data [, EDGE=array] [, /INTERLACE] [, START=array] [, STRIDE=array] ) Arguments ri_id Raster image identifier returned by HDF_GR_CREATE or HDF_GR_SELECT data A named variable that will contain the image data. Keywords EDGE Array specifying the number of values to be read along each dimension. The default is to read the entire specified image. INTERLACE Set this keyword to force data to be returned in INTERLACE mode. The default is pixel-interlacing (0) other possible values are 1 (line) and 2 (component). START Array specifying the starting location from where raster image data is read. Valid values of each element in the array are 0 to the size of the corresponding raster image dimension minus 1. The default is to read starting at the first pixel in each dimension (start = [0,0]). STRIDE Array specifying the interval between the values that will be read along each dimension. The default is for contiguous reading along each dimension (stride = [1,1]). Note The correspondence between the elements in the array start and the array data dimensions in the HDF GR interface is different from that in the HDF SD interface. The array stride specifies the reading pattern along each dimension. For example, if one of the elements of the array stride is 1, then every element along the corresponding dimension of the array data will be read. If one of the elements of the array stride is 2, then every other element along the corresponding dimension of the array data will be read, and so on. The correspondence between elements of the array stride and the dimensions of the array data is the same as described above for the array start. Each element of the array edges specifies the number of data elements to be read along the corresponding dimension. The correspondence between the elements of the array edges and the dimensions of the array data is the same as described above for the array start. HDF_GR_READLUT [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_GR_READLUT This function reads the palette specified by the parameter pal_id into the pal_data variable. Syntax Result = HDF_GR_READLUT( pal_id, pal_data [, /INTERLACE] ) Return value Returns SUCCEED (0) if successful or FAIL (-1) otherwise. Arguments pal_id Palette identifier returned by HDF_GR_GETLUTID. pal_data A named variable that will contain the palette data. Keywords INTERLACE Set this keyword to force pal_data to be returned in INTERLACE mode. The default is pixel-interlacing (0) other possible values are 1 (line) and 2 (component). HDF_GR_REFTOINDEX [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_GR_REFTOINDEX This function returns the index of the HDF GR raster image specified by the parameter gr_ref. Syntax Result = HDF_GR_REFTOINDEX(gr_id, gr_ref) Return value Returns the index of the image if successful or FAIL (-1) otherwise. Arguments gr_id HDF GR interface identifier returned by HDF_GR_START. gr_ref Reference number of the raster image. HDF_GR_SELECT [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_GR_SELECT This function obtains the identifier of the HDF GR raster image specified by its index. Syntax Result = HDF_GR_SELECT(gr_id, index) Return value Returns the raster image identifier if successful or FAIL (-1) otherwise. Arguments gr_id HDF GR interface identifier returned by HDF_GR_START. index Index of the raster image in the file. Valid values range from 0 to the total number of raster images in the file minus 1. The total number of the raster images in the file can be obtained by using HDF_GR_FILEINFO. HDF_GR_SETATTR [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_GR_SETATTR this function attaches the attribute to the HDF GR object specified by the parameter obj_id. The attribute is defined by its name, data type, number of attribute values, and the attribute values. HDF_GR_SETATTR provides a generic way for users to define metadata. It implements the label = value data abstraction. If an HDF GR interface identifier (gr_id) is specified as the parameter obj_id, a global attribute is created that applies to all objects in the file. If a raster image identifier (ri_id) is specified as the parameter obj_id, an attribute is attached to the specified raster image. Attribute values are passed in the parameter values. The number of attribute values is defined by the parameter count. If more than one value is stored, all values must have the same data type. If an attribute with the given name, data type and number of values exists, it will be overwritten. Currently, the only predefined attribute is the fill value, identified by the attribute name "FillValue". Syntax Result = HDF_GR_SETATTR(obj_id, attr_name, data_type, count, values) Return Value Returns SUCCEED (0) if successful or FAIL (-1) otherwise. Arguments obj_id Raster image identifier (ri_id), returned by HDF_GR_CREATE or HDF_GR_SELECT or HDF GR interface identifier (gr_id), returned by HDF_GR_START. attr_name Name of the attribute (string). data_type Data type of the attribute (integer). Can be any data type supported by the HDF library. These data types are listed under "IDL and HDF Data Types" on page 96. count Number of values in the attribute. values The attribute value. HDF_GR_SETCHUNK [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_GR_SETCHUNK This function makes the HDF GR raster image specified by the parameter ri_id a chunked raster image according to the chunking and compression information provided in the parameters comp_type and comp_prm. Data can be compressed using run-length encoding (RLE), Skipping Huffman or GZIP compression algorithms. Syntax Result = HDF_GR_SETCHUNK(ri_id, dim_length, comp_type, comp_prm) Return value Returns SUCCEED (or 0) if successful or FAIL (-1) otherwise. Arguments ri_id Raster image identifier returned by HDF_GR_CREATE or HDF_GR_SELECT. dim_length Chunk dimensions array. comp_type Type of compression. Valid types are: * 0 = uncompressed data * 1 = data compressed using the RLE compression algorithm * 3 = data compressed using the Skipping Huffman compression algorithm * 4 = data compressed using the GZIP compression algorithm. comp_prm Compression parameters array. Specifies the compression parameters for the Skipping Huffman and GZIP compression methods. It contains only one element, which is set to the skipping size for Skipping Huffman compression or the deflate level for GZIP compression (1-9). HDF_GR_SETCHUNKCACHE [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_GR_SETCHUNKCACHE This function allows the user to set the maximum number of chunks to be cached (maxcache). If HDF_GR_SETCHUNKCACHE is not called, maxcache is set to the number of chunks along the fastest changing dimension. Syntax Result = HDF_GR_SETCHUNKCACHE(ri_id, maxcache, flags) Return Value Returns the value of maxcache if successful or FAIL (-1) otherwise. Arguments ri_id Raster image identifier returned by HDF_GR_CREATE or HDF_GR_SELECT. maxcache Maximum number of chunks to cache. flags Currently, the only HDF allowed value for flags is zero (cache all). HDF_GR_SETCOMPRESS [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_GR_SETCOMPRESS This function specifies the type of compression for the specified HDF GR raster image. Syntax Result = HDF_GR_SETCOMPRESS(ri_id, comp_type, comp_prm) Return value Returns SUCCEED (0) if successful or FAIL (-1) otherwise. Arguments ri_id Raster image identifier returned by HDF_GR_CREATE or HDF_GR_SELECT. comp_type Compression method for the image data. Valid values are: * 0 = no compression * 1 = RLE run-length encoding * 3 = Skipping Huffman compression * 4 = GZIP compression * 6 = JPEG compression comp_prm Compression parameters. If Skipping Huffman is used, set comp_parm to the skipping size (the size in bytes of the data elements). If GZIP compression is used, set comp_parm to an integer ranging from 1 (fastest) to 9 (most compressed). HDF_GR_SETEXTERNALFILE [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_GR_SETEXTERNALFILE This function causes the specified HDF GR raster image be written to the specified external file, at the specified offset. Data can be moved only once for any given raster image, and it is the user's responsibility to make sure the external data file is kept with the "original" file. If the raster image already exists, its data will be moved to the external file. Space occupied by the data in the primary file will not be released. If the raster image does not exist, its data will be written to the external file during the subsequent calls to HDF_GR_WRITEDATA. Syntax Result = HDF_GR_SETEXTERNALFILE(ri_id, filename, offset) Return Value Returns SUCCEED (0) if successful or FAIL (-1) otherwise. Arguments ri_id Raster image identifier returned by HDF_GR_CREATE or HDF_GR_SELECT. filename Name of the external file. offset Offset in bytes from the beginning of the external file to where the data will be written. HDF_GR_START [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_GR_START This function initializes the HDF GR interface for the specified file. This function is used with the HDF_GR_END procedure to define the extent of the HDF GR interface session. As with the start routines in the other interfaces, HDF_GR_START initializes the internal interface structures needed for the remaining HDF_GR_ routines. Use the general purpose routines HDF_OPEN and HDF_CLOSE to manage file access. The HDF_GR_ routines will not open and close HDF files. Note Failure to use HDF_CLOSE properly may result in lost data or corrupted HDF files. Syntax Result = HDF_GR_START(file_id) Return Value Returns the HDF GR interface identifier if successful or FAIL (-1) otherwise. Arguments file_id File identifier returned by HDF_OPEN. HDF_GR_WRITEIMAGE [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_GR_WRITEIMAGE This function writes the subsample of the raster image data stored in the variable data to the specified raster image. The subsample is defined by the values of the parameters start, stride and edge. The array start specifies the starting location of the subsample to be written. Valid values of each element in the array start are 0 to the size of the corresponding raster image dimension - 1. Note The correspondence between elements in the array start and the raster image dimensions in the HDF GR interface is different from that in the HDF SD interface. The array stride specifies the writing pattern along each dimension. For example, if one of the elements of the array stride is 1, then every element along the corresponding dimension of the array data will be written. If one of the elements of the stride array is 2, then every other element along the corresponding dimension of the array data will be written, and so on. The correspondence between elements of the array stride and the dimensions of the array data is the same as described above for the array start. Each element of the array edges specifies the number of data elements to be written along the corresponding dimension. The correspondence between the elements of the array edges and the dimensions of the array data is the same as described above for the array start. Syntax Result = HDF_GR_WRITEIMAGE( ri_id, data [, EDGE=array] [, INTERLACE={0 | 1 | 2}] [, START=array] [, STRIDE=array] ) Return Value Returns SUCCEED (0) if successful or FAIL (-1) otherwise. Arguments ri_id Raster image identifier returned by HDF_GR_CREATE or HDF_GR_SELECT. data The image data to be written. Keywords EDGE Array containing the number of data elements that will be written along each dimension. If not specified, all data will be written. INTERLACE Set this keyword to a scalar value to select the interlace mode of the input data. Valid values are: * 0 = Pixel interlace * 1 = Line interlace * 2 = Component interlace HDF_GR_WRITEIMAGE will write the data in the correct interlace mode the raster image is in. START Array containing the two-dimensional coordinate of the initial location for the write. If not specified, the write starts at the first pixel in each dimension (start=[0,0]). STRIDE Array containing the number of data locations the current location is to be moved forward before each write. If not specified, data is written contiguously (stride = [1,1]). Note See HDF_GR_READIMAGE for further description of the EDGE, START, and STRIDE keywords. HDF_GR_WRITELUT [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_GR_WRITELUT This function writes a palette with the specified number of pixel components, data type of the palette data, interlace mode, and number of entries in the palette. The palette data itself is stored in the pal_data variable. The data types supported by HDF are listed in "IDL and HDF Data Types" on page 96. Currently, only "old-style" palettes are supported, i.e ncomp = 3, num_entries = 256, data_type = uint8. Syntax Result = HDF_GR_WRITELUT( pal_id, pal_data [, DATA_TYPE=value] [, INTERLACE_MODE={0 | 1 | 2}] [, NENTRIES=value] ) Return Value Returns SUCCEED (0) if successful or FAIL (-1) otherwise. Arguments pal_id Palette identifier returned by HDF_GR_GETLUTID. ncomp Number of components in the palette. Must have a value of at least 1. pal_data Palette data to be written. Keywords data_type Data type of the palette data. Can be any of the data types supported by the HDF library. The default is UINT8. interlace_mode Interlace mode of the stored palette data. Valid values are: * 0 = Pixel Interlaced (the default) * 1 = Line Interlaced * 2 = Component Interlaced num_entries Number of entries in the palette. HDF_HDF2IDLTYPE [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_HDF2IDLTYPE This function converts an HDF data type code into an IDL variable type code. See the IDL SIZE function and tables 3-2 through 3-4 in Scientific Data Formats for actual values. Syntax Result = HDF_HDF2IDLTYPE( hdftypecode ) Return Value Returns the IDL variable type code (See SIZE). A return value of zero means the type could not be mapped. Arguments hdftypecode An HDF data type code (long). Example PRINT, HDF_HDF2IDLTYPE( 6 ) See Also HDF_IDL2HDFTYPE HDF_IDL2HDFTYPE [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_IDL2HDFTYPE This function converts an IDL variable type code into an HDF data type code. See the IDL SIZE function and tables 3-2 through 3-4 in Scientific Data Formats for actual values. Syntax Result = HDF_IDL2HDFTYPE( idltypecode ) Return Value Returns the HDF data type code. A return value of zero means the type could not be mapped. Arguments idltypecode An IDL variable type code (long). Example iType = SIZE(5.0d,/TYPE) PRINT, HDF_IDL2HDFTYPE( iType ) See Also HDF_HDF2IDLTYPE HDF_ISHDF [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_ISHDF The HDF_ISHDF function returns true (1) if the file is an HDF file and false (0) if the file either is not an HDF file or does not exist. Warning This routine bases its judgement as to whether or not a file is an HDF file on the first few bytes of the file. Therefore, it is possible that HDF_ISHDF will identify the file as an HDF file, but HDF_OPEN will not be able to open the file (because it is corrupted). Syntax Result = HDF_ISHDF(Filename) Arguments Filename A scalar string containing the name of the file to be tested. HDF_LIB_INFO [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_LIB_INFO The HDF_LIB_INFO procedure returns information about the HDF Library being used by this version of IDL, or information about the version of HDF used to create a particular HDF file. Syntax HDF_LIB_INFO, [FileHandle] [, MAJOR=variable] [, MINOR=variable] [, RELEASE=variable] [, VERSION=variable] Arguments FileHandle The HDF filehandle returned from a previous call to HDF_OPEN. Keywords MAJOR Set this keyword equal to a named variable that will contain the major version number of the HDF library currently in use by IDL. If the FileHandle argument is supplied, the variable will contain the major version number of the HDF library used by that particular HDF file. MINOR Set this keyword equal to a named variable that will contain the minor version number of the HDF library currently in use by IDL. If the FileHandle argument is supplied, the variable will contain the minor version number of the HDF library used by that particular HDF file. RELEASE Set this keyword equal to a named variable that will contain the release number of the HDF library currently in use by IDL. If the FileHandle argument is supplied, the variable will contain the release number of the HDF library used by that particular HDF file. VERSION Set this keyword equal to a named variable that will contain the version number text string of the HDF library currently in use by IDL. If the FileHandle argument is supplied, the variable will contain the version number text string of the HDF library used by that particular HDF file. Example Example 1 HDF_LIB_INFO, MAJOR=MAJOR, MINOR=MINOR, VERSION=VER, RELEASE=REL PRINT, 'IDL ', !version.release, ' uses HDF Library ', $ MAJOR, MINOR, REL, FORMAT='(A,A,A,I1,".",I1,"r",I1,A)' PRINT, VER IDL Output IDL 5.3 uses HDF Library 4.1r3 NCSA HDF Version 4.1 Release 3, May 1999 Example 2 The following example tests the version of HDF used to create a particular file. Note that the strings returned will depend solely upon the version of the HDF library used to create the file. In this example, it is the same as the library compiled into the current version of IDL since it is the current IDL that is creating the file. file='example.hdf' id=HDF_OPEN(file, /CREATE) HDF_LIB_INFO, id, VERSION=VER PRINT, 'The file ', file,' was created with : ', VER HDF_CLOSE, id IDL Output The file example.hdf was created with : NCSA HDF Version 4.1 Release 3, May 1999 HDF_NEWREF [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_NEWREF The HDF_NEWREF function returns the next available reference number for an HDF file. Syntax Result = HDF_NEWREF(FileHandle) Arguments FileHandle The HDF file handle returned from a previous call to HDF_OPEN. HDF_NUMBER [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_NUMBER The HDF_NUMBER function returns the number of tags in an HDF file or the number of references associated with a given tag. Syntax Result = HDF_NUMBER( FileHandle [, TAG=integer] ) Arguments FileHandle The HDF file handle returned from a previous call to HDF_OPEN. Keywords TAG Set this keyword to an integer tag number or the string '*'. If this keyword is set to a tag number, HDF_NUMBER returns the number of references associated with the given tag. If this keyword is set to the string '*', or is not specified, HDF_NUMBER returns the total number of tags in the HDF file. HDF_OPEN [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_OPEN The HDF_OPEN function opens or creates an HDF file for reading and/or writing. If successful, a non-zero file handle (a longword integer) is returned. Longword -1 is returned on failure. Note that any combination of the READ, WRITE and CREATE keywords is valid. Syntax Result = HDF_OPEN( Filename [, /ALL] [, /CREATE] [, NUM_DD=value] [, /RDWR] [, /READ] [, /WRITE] ) Arguments Filename A scalar string containing the name of the file to be opened. Keywords ALL Set this keyword to create a new HDF file with read and write access. Setting this keyword is equivalent to: HDF_OPEN(filename, /READ, /WRITE, /CREATE) CREATE Set this keyword to create a new HDF file. NUM_DD Use this keyword to override the machine default for the number of data descriptors to be allocated per DD block. For example: H = HDF_OPEN('foo.hdf',/CREATE,/WRITE, NUM_DD=100) RDWR Set this keyword to open file with both read and write access. Setting this keyword is equivalent to: HDF_OPEN(filename, /READ, /WRITE) READ Set this keyword to open the file with read access. WRITE Set this keyword to open the file with write access. HDF_PACKDATA [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_PACKDATA This function packs a set IDL variable into an array of raw byte data. It is useful in constructing the input to multi-field HDF Vdata writing routines, such as those found in HDF-EOS, from a set of IDL variables. The packed data is output as an array of bytes which is organized as a number of records. Each record consists of one or more data fields. A record is defined using the HDF_TYPE and HDF_ORDER keywords. These define the record layout in terms of HDF data types. This function first converts the input arrays into the type defined by the HDF_TYPE keyword using IDL type conversion rules. The function then walks through the input IDL arrays and copies the values into output array. There must be as many entries in the HDF_TYPE and HDF_ORDER keywords as there are data arguments. The function will output as many complete records as can be created from the input data arrays or the value of the NREC keyword, whichever is smaller. Syntax Result = HDF_PACKDATA( data1 [, data2 [, data3 [, data4 [, data5 [, data6 [, data7 [, data8]]]]]]] [, HDF_ORDER=array] [, HDF_TYPE=array] [, NREC=records] ) Return Value Returns a 2D BYTE array of packed data. The trailing dimension corresponds to each record in the input data. Arguments data1...data8 These arguments specify IDL arrays to be packed. The arguments are first converted to the types specified by HDF_TYPE. If the corresponding HDF_ORDER value is greater than one, more than one value will be read from the input array and placed in the packed array for each record. Strings are output as fixed width fields. If an input string is longer than its HDF_ORDER value, it is truncated before being packed. If an input string is shorter than its HDF_ORDER value, the extra space is filled with the value 0. Keywords HDF_ORDER Set this keyword to an array the same length as the number of data fields. The value in the array is equal to the number of elements in the data argument for each record. In the case of strings, this is the length (in characters) of the string to be packed. A value of zero is interpreted as one element. The default for this keyword is an array of ones. HDF_TYPE Set this keyword to an array the same length as the number of data fields. The value in the array is an HDF data type for each argument. The IDL variables are converted to these types before being packed into the output array. The default for this keyword is an array of the value 5 (an HDF 32 bit float). See "IDL and HDF Data Types" on page 96 for valid values. NREC Set this keyword to the number of records to be packed. The default is to pack as many complete records as can be formed by all of the input arrays. Example See HDF_UNPACKDATA. See Also HDF_UNPACKDATA, EOS_PT_WRITELEVEL, HDF_VD_WRITE HDF_SD_ADDDATA [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_SD_ADDDATA The HDF_SD_ADDDATA procedure writes a hyperslab of values to an SD dataset. By default, the output data is transposed. This transposition puts the data in column order, which is more efficient in HDF than row order (which is more efficient in IDL). In the rare cases where it is necessary to write the data without transposing, set the NOREVERSE keyword. The OFFSET, COUNT, and STRIDE keywords are similarly affected by the NOREVERSE keyword. Syntax HDF_SD_ADDDATA, SDS_ID, Data [, COUNT=vector] [, /NOREVERSE] [, START=vector] [, STRIDE=vector] Arguments SDS_ID An SD dataset ID as returned by HDF_SD_SELECT or HDF_SD_CREATE. Data The data to be written. Keywords COUNT Set this keyword to a vector of counts (i.e., the number of items) to be written in each dimension. The default is to write all available data. Use caution when using this keyword. See the second example, below. NOREVERSE Set this keyword to prevent HDF_SD_ADDDATA's transposition of Data and any vectors specified by keywords into column order. START Set this keyword to a vector that contains the starting position for the data. The default position is [0, 0, ..., 0]. STRIDE Set this keyword to a vector that contains the strides, or sampling intervals, between accessed values of the NetCDF variable. The default stride vector is that for a contiguous write: [0, 0, ..., 0]. Example The following example writes a 230-element by 380-element byte image to an SD dataset, then reads it back as a 70 by 100 image starting at (40, 20), sampling every other Y pixel and every third X pixel: start = [40, 20] ; Set the start vector. count = [70, 100] ; Set the count vector. stride = [2, 3] ; Set the stride vector. image = DIST(230, 380) ; Create the image. TV, image ; Display the image. ; Create a new HDF file in SD mode: sd_id = HDF_SD_START('image.hdf', /CREATE) ; Define a new SD dataset: sds_id = HDF_SD_CREATE(sd_id, 'image', [230, 380], /BYTE) HDF_SD_ADDDATA, sds_id, image ; Write the image into the dataset. HDF_SD_GETDATA, sds_id, full ; Retrieve the full image. ; Retrieve the sub-sampled image: HDF_SD_GETDATA, sds_id, small, COUNT=count, $ START=start, STRIDE=stride HDF_SD_ENDACCESS, sds_id HDF_SD_END, sd_id HELP, full, small ; Print information about the images. ERASE ; Erase the window. TV, full; Display the full image. TV, small ; Display the sub-sampled image. IDL prints: FULL BYTE = Array(230, 380) SMALL BYTE = Array(70, 100) Continuing with our example, suppose we want to write the center 50 by 100 pixels of the image to the file. You might be tempted to try: HDF_SD_ADDDATA, sds_id, image, START=[90, 90], COUNT=[50,100] You will find, however, that this captures the lower left-hand corner of the original image, rather than the center. To write the data from the center, subset the original image, choosing the data from the center: HDF_SD_ADDDATA, sds_id, image(90:139, 90:189), START=[90, 90],$ COUNT=[50,100] ; This is the correct way to add the data. HDF_SD_ENDACCESS, sds_id ; End SD access. HDF_SD_END, sd_id ; Close the file. See Also HDF_SD_GETDATA HDF_SD_ATTRFIND [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_SD_ATTRFIND The HDF_SD_ATTRFIND function locates the index of an HDF attribute given its name. The attribute can be global or from a specific dataset. If an attribute is located, its index is returned. Otherwise, -1 is returned. Once an attribute's index is known, the HDF_SD_ATTRINFO function can be used to read that attribute. Syntax Result = HDF_SD_ATTRFIND(S_ID, Name) Arguments S_ID An SD interface ID as returned by HDF_SD_START (i.e., a global attribute's "SD_ID"), or HDF_SD_SELECT/HDF_SD_CREATE (i.e., a dataset's "SDS_ID"). Name A string containing the name of the attribute whose index is to be returned. Example ; Open an HDF file and start the SD interface: sd_id = HDF_SD_START('demo.hdf') ; Find "TITLE", a global attribute: gindex = HDF_SD_ATTRFIND(sd_id, 'TITLE') ; Get the ID for the first dataset: sds_id = HDF_SD_SELECT(sd_id, 1) ; Read attribute info: HDF_SD_ATTRINFO,sd_id,gindex, NAME=name, TYPE=type, COUNT=count ; Print info about the returned variables: HELP, type, count, name ; Find the "LOCATION" dataset attribute: dindex = HDF_SD_ATTRFIND(sds_id, 'LOCATION') ; Read attribute info: IDL Output TYPE STRING = 'STRING' COUNT LONG = 8 NAME STRING = 'TITLE' See Also HDF_SD_ATTRINFO, HDF_SD_ATTRSET, HDF_SD_SELECT HDF_SD_ATTRINFO [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_SD_ATTRINFO The HDF_SD_ATTRINFO procedure reads or retrieves information about an SD attribute. The attribute can be global or from a specific dataset. If an attribute is not present, an error message is printed. Syntax HDF_SD_ATTRINFO, S_ID, Attr_Index [, COUNT=variable] [, DATA=variable] [, HDF_TYPE=variable] [, NAME=variable] [, TYPE=variable] Arguments S_ID An SD interface ID as returned by HDF_SD_START (i.e., a global attribute's "SD_ID"), or HDF_SD_SELECT/HDF_SD_CREATE (i.e., a dataset's "SDS_ID"). Attr_Index The attribute index, can either be obtained by calling HDF_SD_ATTRFIND if a particular attribute name is known or can be obtained with a 0-based index sequentially referencing the attribute. Keywords COUNT Set this keyword to a named variable in which the total number of values in the specified attribute is returned. DATA Set this keyword to a named variable in which the attribute data is returned. HDF_TYPE Set this keyword to a named variable in which the HDF type of the attribute is returned as a scalar string. Possible returned values are DFNT_NONE, DFNT_CHAR, DFNT_FLOAT32, DFNT_FLOAT64, DFNT_INT8, DFNT_INT16, DFNT_INT32, DFNT_UINT8, DFNT_UINT16, and DFNT_UINT32. NAME Set this keyword to a named variable in which the name of the attribute is returned. TYPE Set this keyword to a named variable in which the IDL type of the attribute is returned as a scalar string. Possible returned values are BYTE, INT, LONG, FLOAT, DOUBLE, STRING, or UNKNOWN. Example ; Open an HDF file and start the SD interface: sd_id = HDF_SD_START('demo.hdf') ; Find a global attribute: gindex = HDF_SD_ATTRFIND(sd_id, 'TITLE') ; Retrieve attribute info: HDF_SD_ATTRINFO, sd_id, gindex, NAME=n, TYPE=t, COUNT=c, $ DATA=d, HDF_TYPE=h ; Print information about the returned variables: HELP, n, t, c, h ; Return the SD dataset ID for the first dataset (index 0): sds_id = HDF_SD_SELECT(sd_id, 0) ; Find a dataset attribute: dindex = HDF_SD_ATTRFIND(sds_id, 'LOCATION') ; Retrieve attribute info: HDF_SD_ATTRINFO,SDS_ID, dindex, NAME=n, TYPE=t, COUNT=c, DATA=d ; Print information about the new returned variables: HELP, n, t, c, d IDL Output N STRING = 'TITLE' T STRING = 'STRING' C LONG = 17 D STRING = '5th Ave Surf Shop' H STRING = 'DFNT_CHAR' N STRING = 'LOCATION' T STRING = 'STRING' C LONG = 15 D STRING = 'MELBOURNE BEACH' See Also HDF_SD_ATTRFIND, HDF_SD_ATTRSET, HDF_SD_CREATE, HDF_SD_SELECT, HDF_SD_START HDF_SD_ATTRSET [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_SD_ATTRSET The HDF_SD_ATTRSET procedure writes attributes to an open HDF SD dataset. If no data type is specified, the data type is taken from the Values argument. Syntax HDF_SD_ATTRSET, S_ID, Attr_Name, Values [, Count] [, /BYTE] [, /DFNT_CHAR] [, /DFNT_FLOAT32] [, /DFNT_FLOAT64] [, /DFNT_INT8] [, /DFNT_INT16] [, /DFNT_INT32] [, /DFNT_UINT8] [, /DFNT_UINT16] [, /DFNT_UINT32] [, /DOUBLE] [, /FLOAT] [, /INT] [, /LONG] [, /SHORT] [, /STRING] Arguments S_ID An SD interface ID as returned by HDF_SD_START (i.e., a global attribute's "SD_ID"), or HDF_SD_SELECT/HDF_SD_CREATE (i.e., a dataset's "SDS_ID"). Attr_Name A string containing the name of the attribute to be written. Values The attribute values to be written. Count An optional integer argument specifying how many items are to be written. Count must be less than or equal to the number of elements in the Values argument. Keywords BYTE Set this keyword to indicate that the attribute is composed of bytes. Data will be stored with the HDF DFNT_UINT8 data type. Setting this keyword is the same as setting the DFNT_UINT8 keyword. DFNT_CHAR Set this keyword to create an attribute of HDF type DFNT_CHAR. Setting this keyword is the same as setting the STRING keyword. DFNT_FLOAT32 Set this keyword to create an attribute of HDF type DFNT_FLOAT32. Setting this keyword is the same as setting the FLOAT keyword. DFNT_FLOAT64 Set this keyword to create an attribute of HDF type DFNT_FLOAT64. Setting this keyword is the same as setting the DOUBLE keyword. DFNT_INT8 Set this keyword to create an attribute of HDF type DFNT_INT8. DFNT_INT16 Set this keyword to create an attribute of HDF type DFNT_INT16. Setting this keyword is the same as setting either the INT keyword or the SHORT keyword. DFNT_INT32 Set this keyword to create an attribute of HDF type DFNT_INT32. Setting this keyword is the same as setting the LONG keyword. DFNT_UINT8 Set this keyword to create an attribute of HDF type DFNT_UINT8. Setting this keyword is the same as setting the BYTE keyword. DFNT_UINT16 Set this keyword to create an attribute of HDF type DFNT_UINT16. DFNT_UINT32 Set this keyword to create an attribute of HDF type DFNT_UINT32. DOUBLE Set this keyword to indicate that the attribute is composed of double-precision floating-point values. Data will be stored with the HDF DFNT_FLOAT64 data type. Setting this keyword is the same as setting the DFNT_FLOAT64 keyword. FLOAT Set this keyword to indicate that the attribute is composed of single-precision floating-point values. Data will be stored with the HDF DFNT_FLOAT32 data type. Setting this keyword is the same as setting the DFNT_FLOAT32 keyword. INT Set this keyword to indicate that the attribute is composed of 2-byte integers. Data will be stored with the HDF DFNT_INT16 data type. Setting this keyword is the same as setting either the SHORT keyword or the DFNT_INT16 keyword. LONG Set this keyword to indicate that the attribute is composed of longword integers. Data will be stored with the HDF DFNT_INT32 data type. Setting this keyword is the same as setting the DFNT_INT32 keyword. SHORT Set this keyword to indicate that the attribute is composed of 2-byte integers. Data will be stored with the HDF DFNT_INT16 data type. Setting this keyword is the same as setting either the INT keyword or the DFNT_INT16 keyword. STRING Set this keyword to indicate that the attribute is composed of strings. Data will be stored with the HDF DFNT_CHAR data type. Setting this keyword is the same as setting the DFNT_CHAR keyword. Example fid = HDF_OPEN('demo.hdf', /ALL) ; Create a new HDF file. sd_id = HDF_SD_START('demo.hdf', /RDWR) ; Start the SD interface. ; Create a global attribute: HDF_SD_ATTRSET, sd_id, 'TITLE', 'MY TITLE GLOBAL', 16 ; Create another global attribute: HDF_SD_ATTRSET, sd_id, 'RANGE', [-99.88,55544.2], /DOUBLE ; Create a dataset: SDS_ID = HDF_SD_CREATE(sd_id, 'var1', [10,20], /FLOAT) ; Add a dataset attribute: HDF_SD_ATTRSET, SDS_ID, 'TITLE', 'MY TITLE SD_ID', 15 ; Find the recently-created RANGE attribute: index=HDF_SD_ATTRFIND(sd_id, 'RANGE') ; Retrieve data from RANGE: ; Print information about the returned variables: HELP, atn, atc, att ; Print the data returned in variable d with the given format: PRINT, d, FORMAT='(F8.2,x,F8.2)' HDF_SD_ENDACCESS, sds_id ; End access to the HDF file. HDF_SD_END, sd_id HDF_CLOSE, fid IDL Output ATN STRING = 'RANGE' ATC LONG = 2 ATT STRING = 'DOUBLE' -99.88 55544.20 See Also HDF_SD_ATTRFIND, HDF_SD_ATTRINFO, HDF_SD_CREATE, HDF_SD_SELECT HDF_SD_CREATE [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_SD_CREATE The HDF_SD_CREATE function creates and defines a Scientific Dataset (SD) for an HDF file. Keywords can be set to specify the data type. If no keywords are present a floating-point dataset is created. The returned value of this function is the SDS ID of the newly-created dataset. Syntax Result = HDF_SD_CREATE( SD_ID, Name, Dims [, /BYTE] [, /DFNT_CHAR] [, /DFNT_FLOAT32] [, /DFNT_FLOAT64] [, /DFNT_INT8] [, /DFNT_INT16] [, /DFNT_INT32] [, /DFNT_UINT8] [, /DFNT_UINT16] [, /DFNT_UINT32] [, /DOUBLE] [, /FLOAT] [, HDF_TYPE=type] [, /INT] [, /LONG] [, /SHORT] [, /STRING] ) Arguments SD_ID An SD ID as returned by HDF_SD_START. Name A string containing the name of the variable to be created. Dims A 1-based vector specifying the dimensions of the variable. If an UNLIMITED dimension is desired, set the last vector element to zero or a negative number. Keywords BYTE Set this keyword to indicate that the dataset is composed of bytes. Data will be stored with the HDF DFNT_UINT8 data type. Setting this keyword is the same as setting the DFNT_UINT8 keyword. DFNT_CHAR Set this keyword to create a data set of HDF type DFNT_CHAR. Setting this keyword is the same as setting the STRING keyword. DFNT_FLOAT32 Set this keyword to create a data set of HDF type DFNT_FLOAT32. Setting this keyword is the same as setting the FLOAT keyword. DFNT_FLOAT64 Set this keyword to create a data set of HDF type DFNT_FLOAT64. Setting this keyword is the same as setting the DOUBLE keyword. DFNT_INT8 Set this keyword to create a data set of HDF type DFNT_INT8. DFNT_INT16 Set this keyword to create a data set of HDF type DFNT_INT16. Setting this keyword is the same as setting either the INT keyword or the SHORT keyword. DFNT_INT32 Set this keyword to create a data set of HDF type DFNT_INT32. Setting this keyword is the same as setting the LONG keyword. DFNT_UINT8 Set this keyword to create a data set of HDF type DFNT_UINT8. Setting this keyword is the same as setting the BYTE keyword. DFNT_UINT16 Set this keyword to create a data set of HDF type DFNT_UINT16. DFNT_UINT32 Set this keyword to create a data set of HDF type DFNT_UINT32. DOUBLE Set this keyword to indicate that the dataset is composed of double-precision floating-point values. Data will be stored with the HDF DFNT_FLOAT64 data type. Setting this keyword is the same as setting the DFNT_FLOAT64 keyword. FLOAT Set this keyword to indicate that the dataset is composed of single-precision floating- point values. Data will be stored with the HDF DFNT_FLOAT32 data type. Setting this keyword is the same as setting the DFNT_FLOAT32 keyword. HDF_TYPE Set this keyword to the type of data set to create. Valid values are: DFNT_CHAR, DFNT_FLOAT32, DFNT_FLOAT64, DFNT_INT8, DFNT_INT16, DFNT_INT32, DFNT_UINT8, DFNT_UINT16, DFNT_UINT32. For example: type = HDF_IDL2HDFTYPE(SIZE(myData, /type)) sds_id = HDF_SD_CREATE(f_id, "name", dims, HDF_TYPE=type) INT Set this keyword to indicate that the dataset is composed of 2-byte integers. Data will be stored with the HDF DFNT_INT16 data type. Setting this keyword is the same as setting either the SHORT keyword or the DFNT_INT16 keyword. LONG Set this keyword to indicate that the dataset is composed of longword integers. Data will be stored with the HDF DFNT_INT32 data type. Setting this keyword is the same as setting the DFNT_INT32 keyword. SHORT Set this keyword to indicate that the dataset is composed of 2-byte integers. Data will be stored with the HDF DFNT_INT16 data type. Setting this keyword is the same as setting either the INT keyword or the DFNT_INT16 keyword. STRING Set this keyword to indicate that the dataset is composed of strings. Data will be stored with the HDF DFNT_CHAR data type. Setting this keyword is the same as setting the DFNT_CHAR keyword. Example ; Create a new HDF file: sd_id = HDF_SD_START('test.hdf', /CREATE) ; Create an dataset that includes an unlimited dimension: sds_id = HDF_SD_CREATE(sd_id, 'var1', [9,40,0], /SHORT) The example for HDF_SD_ATTRSET also demonstrates the use of this routine. See Also HDF_OPEN, HDF_SD_ENDACCESS, HDF_SD_SELECT HDF_SD_DIMGET [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_SD_DIMGET The HDF_SD_DIMGET procedure retrieves information about an SD dataset dimension. Syntax HDF_SD_DIMGET, Dim_ID [, /COUNT] [, COMPATIBILITY=variable] [, /FORMAT] [, /LABEL] [, /NAME] [, /NATTR] [, /SCALE] [, /TYPE] [, /UNIT] Arguments Dim_ID A dimension ID as returned by HDF_SD _DIMGETID. Keywords COUNT Set this keyword to return the dimension size. COMPATIBILITY Set this keyword to a named variable that will contain a string indicating the dimensional compatibility of the current dimension. Possible values are "BW_COMP" (backwards compatible), "BW_INCOMP" (backwards incompatible), or "FAIL" (the information is unavailable). For further information about dimensional compatibilities, see the HDF User's Guide, and the BW_INCOMP keyword of HDF_SD_DIMSET. By default, IDL writes HDF files in "BW_COMP" mode. FORMAT Set this keyword to return the dimension format description string. LABEL Set this keyword to return the dimension label description string. NAME Set this keyword to return the dimension name. NATTR Set this keyword to return the number of attributes for the dimension. SCALE Set this keyword to return the scale of the dimension. TYPE Set this keyword to return a string describing the data's type (i.e., `BYTE'). UNIT Set this keyword to return the dimension unit description string. Example For an example using this routine, see the example for HDF_SD_DIMSET. See Also HDF_SD_CREATE, HDF_SD_DIMGETID, HDF_SD_DIMSET, HDF_SD_SELECT HDF_SD_DIMGETID [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_SD_DIMGETID The HDF_SD_DIMGETID function returns a dimension ID given a dataset's "SDS_ID" and a dimension number. Syntax Result = HDF_SD_DIMGETID(SDS_ID, Dimension_Number) Arguments SDS_ID An SD dataset ID as returned by HDF_SD _SELECT or HDF_SD_CREATE. Dimension_Number A zero-based dimension number. The dimension number must be greater than or equal to 0 and less than the maximum dimension number, or rank. Example For an example illustrating this routine, see the documentation for HDF_SD_DIMSET. See Also HDF_SD_CREATE, HDF_SD_DIMGET, HDF_SD_DIMSET, HDF_SD_SELECT HDF_SD_DIMSET [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_SD_DIMSET The HDF_SD_DIMSET function sets the scale and data strings for an SD dimension. Syntax HDF_SD_DIMSET, Dim_ID [, /BW_INCOMP] [, FORMAT=string] [, LABEL=string] [, NAME=string] [, SCALE=vector] [, UNIT=string] Arguments Dim_ID A dimension ID as returned by HDF_SD _DIMGETID. Keywords BW_INCOMP Set this keyword to write SD dimensions in the "new" (HDF4.1 and later) style. Versions of HDF prior to HDF 4.0 beta 2 were inefficient in the use of SD dimensions. HDF now uses a new internal representation of SD dimensions. If the BW_INCOMP keyword is not set, or is explicitly set equal to zero, the current version of HDF writes SD dimensions in both the pre-HDF 4.0 format AND the "new" format. This default behavior is called the BW_COMP dimensional compatibility representation. Setting the BW_INCOMP keyword causes the current dimension to be written in only the "new" (HDF4.1 and later) format. Depending on your HDF file, using this new format can reduce the size of the HDF by up to a factor of 2, but at the expense of incompatibility with pre HDF 4.0 beta 2 applications (IDL version 4, for example). The COMPATIBILITY keyword of HDF_SD_DIMGET can be used to check the dimensional compatibility of an HDF dimension. Note Future versions of HDF will recognize only the "new" (BW_INCOMP) dimensional representation. FORMAT A string for the dimension format. LABEL A string for the dimension label. NAME A string for the dimension name. SCALE A vector containing the dimension scale values. UNIT A string for the dimension unit. Example ; Initialize the SD interface: sd_id = HDF_SD_START('myhdf.hdf', /RDWR) ; Create 3 dimensions: sds_id = HDF_SD_CREATE(sd_id, 'var1', [10,20,0], /LONG) ; Select the first dimension: dim_id=HDF_SD_DIMGETID(sds_id,0) ; Set the data strings and scale for the first dimension: HDF_SD_DIMSET, dim_id, NAME='d1', LABEL='l1', $ FORMAT='f1', UNIT='u1', SCALE=FINDGEN(10) HDF_SD_ENDACCESS, sds_id ; Close the HDF file to ensure everything is written: HDF_SD_END, sd_id ; Reopen the file: sd_id = HDF_SD_START('myhdf.hdf') ; Select the first dimension: dim_id = HDF_SD_DIMGETID(sds_id,0) ; Retrieve the information: HDF_SD_DIMGET, dim_id, NAME=d1, LABEL=l1, FORMAT=f1, $ UNIT=u1, SCALE=sc, COUNT=cnt, NATTR=natt, TYPE=type ; Print information about the returned variables: HELP, d1, l1, f1, u1, sc, cnt, natt, type ; Close the SD interface: HDF_SD_ENDACCESS,sds_id HDF_SD_END, sd_id IDL Output D1 STRING = 'd1' L1 STRING = 'l1' F1 STRING = 'f1' U1 STRING = 'u1' SC FLOAT = Array(10) CNT LONG = 10 NATT LONG = 3 TYPE STRING = 'FLOAT' See Also HDF_SD_CREATE, HDF_SD_DIMGET, HDF_SD_DIMGETID, HDF_SD_SELECT HDF_SD_END [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_SD_END The HDF_SD_END function closes the SD interface to an HDF file. Failure to close the file without a call to HDF_SD_END results in the loss of any changed or added SD data. Therefore, HDF_SD_END calls should always be paired with calls to HDF_SD_START. Before HDF_SD_END is called, all access to SD datasets should be terminated with calls to HDF_SD_ENDACCESS. Syntax HDF_SD_END, SD_ID Arguments SD_ID An SD interface ID as returned by HDF _SD_START. Example ; Open a new HDF file: sd_id = HDF_SD_START('test.hdf', /CREATE) ; Various commands could now be used to access SD data ; in the HDF file. ; When done with datasets, access should be ended with ; calls to HDF_SD_ENDACCESS: HDF_SD_ENDACCESS, sds_id_1 ; When done with an HDF file, it should be closed: HDF_SD_END, sd_id Another example can be seen in the documentation for HDF_SD_ATTRSET. See Also HDF_CLOSE, HDF_OPEN, HDF_SD_ENDACCESS, HDF_SD_START HDF_SD_ENDACCESS [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_SD_ENDACCESS The HDF_SD_ENDACCESS function closes an SD dataset interface. Failure to close the interface can result in the loss of any changed or added SD data. This routine should be called once for each call to HDF_SD_START or HDF_SD_CREATE. After all SD dataset interfaces are closed, the HDF file can safely be closed with HDF_SD_END. Syntax HDF_SD_ENDACCESS, SD_ID Arguments SDS_ID An SD dataset ID as returned by HDF_SD_SELECT, or HDF_SD_CREATE. Example ; Open a new HDF file: sd_id = HDF_SD_START('test.hdf', /CREATE) ; Access the HDF file: sds_id_1 = HDF_SD_SELECT(sd_id,0) ; End access to any SD IDs: HDF_SD_ENDACCESS, sds_id_1 ; Close the HDF file: HDF_SD_END, sd_id Also see the example in HDF_SD_ATTRSET. See Also HDF_CLOSE, HDF_OPEN, HDF_SD_CREATE, HDF_SD_ENDACCESS, HDF_SD_START HDF_SD_FILEINFO [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_SD_FILEINFO The HDF_SD_FILEINFO procedure retrieves the number of datasets and global attributes in an HDF file. Syntax HDF_SD_FILEINFO, SD_ID, Datasets, Attributes Arguments SD_ID An SD interface ID as returned by HDF_SD_START. Datasets A named variable in which the total number of SD-type objects (i.e., the number of datasets + the number of dimensions) in the file is returned. Attributes A named variable in which the number of global attributes in the file is returned. Example ; Start the SD interface: sd_id = HDF_SD_START('demo.hdf', /CREATE) ; Set a global attribute: HDF_SD_ATTRSET,sd_id, 'TITLE', 'MYTITLE' ; Set another one: HDF_SD_ATTRSET,sd_id, 'TITLE2', 'MYTITLE2' ; Create a dataset: sds_id = HDF_SD_CREATE(sd_id, 'var1', [10,3]) ; Retrieve info about the dataset: HDF_SD_FILEINFO, sd_id, datasets, attributes ; Print information about the returned variables: HELP, datasets, attributes ; End SD access: HDF_SD_ENDACCESS, sds_id ; Close the SD interface: HDF_SD_END, sd_id IDL Output DATASETS LONG = 1 ATTRIBUTES LONG = 2 See Also HDF_SD_ATTRFIND, HDF_SD_ATTRINFO, HDF_SD_START HDF_SD_GETDATA [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_SD_GETDATA The HDF_SD_GETDATA procedure retrieves a hyperslab of values from an SD dataset. By default, the retrieved data is transposed from HDF's column order format into IDL's row order which is more efficient in IDL. To retrieve the dataset without this transposition, set the NOREVERSE keyword. Syntax HDF_SD_GETDATA, SDS_ID, Data [, COUNT=vector] [, /NOREVERSE] [, START=vector] [, STRIDE=vector] Arguments SDS_ID An SD dataset ID as returned by HDF_SD _SELECT or HDF_SD_CREATE. Data A named variable in which the values are returned. Keywords COUNT Set this keyword to a vector containing the counts, or number of items, to be read. The default is to read all available data. NOREVERSE Set the keyword to retrieve the data without transposing the data from column to row order. START Set this keyword to a vector containing the starting position for the read. The default start position is [0, 0, ..., 0]. STRIDE Set this keyword to a vector containing the strides, or sampling intervals, between accessed values of the HDF variable. The default stride vector is that for a contiguous read: [0, 0, ..., 0]. Example For an example using this routine, see the documentation for HDF_GR_ATTRINFO See Also HDF_GR_ATTRINFO, HDF_SD_GETINFO HDF_SD_GETINFO [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_SD_GETINFO The HDF_SD_GETINFO procedure retrieves information about an SD dataset. Warning Reading a label, unit, format, or coordinate system string that has more than 256 characters can have unpredictable results. Syntax HDF_SD_GETINFO, SDS_ID [, CALDATA=variable] [, COORDSYS=variable] [, DIMS=variable] [, FILL=variable] [, FORMAT=variable] [, HDF_TYPE=variable] [, LABEL=variable] [, NAME=variable] [, NATTS=variable] [, NDIMS=variable] [, /NOREVERSE] [, RANGE=variable] [, TYPE=variable] [, UNIT=variable] Arguments SDS_ID An SD dataset ID as returned by HDF_SD _SELECT or HDF_SD_CREATE. Keywords CALDATA Set this keyword to a named variable in which the calibration data associated with the SD dataset is returned. The data is returned in a structure of the form: For more information about calibration data, see the documentation for HDF_SD_SETINFO. COORDSYS Set this keyword to a named variable in which the coordinate system description string is returned. DIMS Set this keyword to a named variable in which the dimensions of the SD dataset are returned. For efficiency, these dimensions are returned in reverse order from their HDF format unless the NOREVERSE keyword is also set. FILL Set this keyword to a named variable in which the fill value of the SD dataset is returned. Note that a fill value must be set in the SD dataset. If a fill value is not set, the value of the variable named by this keyword will be undefined, and IDL will issue a warning message. FORMAT Set this keyword to a named variable in which the format description string is returned. If the format description string is not present, this variable will contain an empty string. HDF_TYPE Set this keyword to a named variable in which the HDF type of the SD dataset is returned as a scalar string. Possible returned values are DFNT_NONE, DFNT_CHAR, DFNT_FLOAT32, DFNT_FLOAT64, DFNT_INT8, DFNT_INT16, DFNT_INT32, DFNT_UINT8, DFNT_UINT16, and DFNT_UINT32. LABEL Set this keyword to a named variable in which the label description string is returned. If the label description string is not present, this variable will contain an empty string. NAME Set this keyword to a named variable in which the SD dataset name is returned. If the SD dataset name is not present, this variable will contain an empty string. NATTS Set this keyword to a named variable in which the number of "NetCDF-style" attributes for the SD dataset is returned. NDIMS Set this keyword to a named variable in which the number of dimensions in the dataset is returned. NOREVERSE Set this keyword in conjunction with DIMS to return the variable dimensions in non- reversed form. By default, IDL reverses data and dimensions from the HDF format to improve efficiency. RANGE Set this keyword to a named variable in which the maximum and minimum of the current SD dataset is returned as a two-element vector. Note that a range must be set in the SD dataset. If the range is not set, the value of the variable named by this keyword will be undefined, and IDL will issue a warning message. TYPE Set this keyword to a named variable in which the IDL type of the SD dataset is returned as a scalar string. Possible returned values are BYTE, INT, LONG, FLOAT, DOUBLE, STRING, or UNKNOWN. UNIT Set this keyword to a named variable in which the unit description string is returned. If the unit description string is not present, this variable will contain an empty string. Example For an example using this routine, see the documentation for HDF_SD_SETINFO. See Also HDF_OPEN, HDF_SD_END, HDF_SD_SETINFO, HDF_SD_START HDF_SD_IDTOREF [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_SD_IDTOREF The HDF_SD_IDTOREF function converts a SD data set ID into a SD data set reference number. The reference number can be used to add the SD data set to a Vgroup through the HDF_VG interface. The tag number for an SD is 720. Syntax Result = HDF_SD_IDTOREF(SDS_ID) Arguments SDS_ID A SDS_ID as returned from HDF_SD_CREATE or HDF_SD_SELECT. Example ; Create an SD data set and get the Reference number: file_id = HDF_OPEN('demo.hdf', /ALL) sd_id = HDF_SD_START('demo.hdf', /RDWR) dim=[100] sds_id = HDF_SD_CREATE(sd_id, 'demo_data', dim, /FLOAT) ref = HDF_SD_IDTOREF(sds_id) HDF_SD_ADDDATA, sds_id, FINDGEN(100)/10.45 + 2.98 HDF_SD_ENDACCESS, sds_id HDF_SD_END, sd_id ; Use the Reference number to add the SD to a Vgroup: SD_TAG = 720 vgID = HDF_VG_GETID(file_id,-1) vg_handle = HDF_VG_ATTACH(file_id, vgID, /WRITE) HDF_VG_SETINFO, vg_handle, name='data1', class='demo' HDF_VG_ADDTR, vg_handle, SD_TAG, ref ; Use HDF_VG_INQTR to verify the SD was added correctly: IF HDF_VG_INQTR(vg_handle, SD_TAG, ref) THEN $ PRINT, 'SUCCESS' ELSE PRINT, 'Failure' HDF_VG_DETACH, vg_handle HDF_CLOSE, file_id IDL Output SUCCESS See Also HDF_SD_CREATE, HDF_SD_NAMETOINDEX, HDF_SD_REFTOINDEX, HDF_SD_SELECT, HDF_VG_ADDTR, HDF_VG_ATTACH, HDF_VG_DETACH, HDF_VG_GETID, HDF_VG_INQTR HDF_SD_ISCOORDVAR [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_SD_ISCOORDVAR The HDF_SD_ISCOORDVAR function returns True (1) if the supplied dataset ID represents a NetCDF "coordinate" variable. Otherwise, False (0) is returned. Syntax Result = HDF_SD_ISCOORDVAR(SDS_ID) Arguments SDS_ID An SD dataset ID as returned by HDF_SD _SELECT or HDF_SD_CREATE. HDF_SD_NAMETOINDEX [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_SD_NAMETOINDEX The HDF_SD_NAMETOINDEX function returns an SD dataset index given its name and SD interface ID. An error message is printed if the dataset cannot be located. The returned index can be used by HDF_SD_SELECT to access an SD dataset. Syntax Result = HDF_SD_NAMETOINDEX(SD_ID, SDS_Name) Arguments SD_ID An SD interface ID as returned by HDF_SD_START. SDS_Name A string containing the name of the SD dataset be located. Example ; Start the SD interface: sd_id = HDF_SD_START('demo.hdf') ; Return the index of the 'variable_2' dataset: index = HDF_SD_NAMETOINDEX(sd_id, 'variable_2') ; Access the dataset: sds_id=HDF_SD_SELECT(sd_id,index) ; End access: HDF_SD_ENDACCESS, sds_id HDF_SD_END, sd_id See Also HDF_SD_REFTOINDEX, HDF_SD_SELECT, HDF_SD_START HDF_SD_REFTOINDEX [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_SD_REFTOINDEX The HDF_SD_REFTOINDEX function returns a scientific dataset's index given its reference number and SD interface ID. Syntax Result = HDF_SD_REFTOINDEX(SD_ID, Refno) Arguments SD_ID An SD interface ID as returned by HDF_SD_START. Refno The SD reference number for the desired dataset. Example ; Initialize the SD interface: sd_id = HDF_SDSTART('demo.hdf') ; Define the reference number for which we want to search: refno = 66 ; Return the index number: index = HDF_SD_REFTOINDEX(sd_id, refno) ; Now the dataset can be accessed: sds_id = HDF_SD_SELECT(sd_id, index) ; End access: HDF_SD_ENDACCESS,SDS_ID HDF_SD_END, sd_id See Also HDF_SD_IDTOREF, HDF_SD_NAMETOINDEX HDF_SD_SELECT [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_SD_SELECT The HDF_SD_SELECT function returns an SD dataset ID given the current SD interface ID, and the zero-based SD dataset index. HDF_SD_FILEINFO can be used to determine the number of SD datasets in an HDF file, HDF_SD_REFTOINDEX can be used to find the index from its SD dataset ID, and HDF_SD_NAMETOINDEX can be used to find the index from its name. Syntax Result = HDF_SD_SELECT(SD_ID, Number) Arguments SD_ID A SD interface ID as returned from HDF _SD_START. Number A zero-based SD dataset index. Example ; Open an HDF file: sd_id = HDF_SD_START('test.hdf') ; Access the first SD in the HDF file: sds_id_1=HDF_SD_SELECT(sd_id, 0) ; End access to any SD ids: HDF_SD_ENDACCESS, sds_id_1 ; Close the file: HDF_SD_END, sd_id See Also HDF_SD_CREATE, HDF_SD_END, HDF_SD_ENDACCESS, HDF_SD_NAMETOINDEX, HDF_SD_REFTOINDEX, HDF_SD_SELECT, HDF_SD_START HDF_SD_SETCOMPRESS [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_SD_SETCOMPRESS The HDF_SD_SETCOMPRESS procedure compresses an existing HDF SD dataset or sets the compression method of a newly created HDF SD dataset. Available compression methods are No Compression, run-length encoding (RLE), adaptive (skipping) huffman, and GZIP compression. All of these compression methods are lossless. When using skipping huffman compression, IDL automatically determines the correct skipping size. The EFFORT keyword determines the effort applied when using GZIP compression (i.e., when comptype is 4). In general, the default GZIP compression method is the best combination of speed and file size reduction. Syntax HDF_SD_SETCOMPRESS, SDS_ID, comptype [, EFFORT=integer{1 to 9}] Arguments SDS_ID The HDF SD dataset id as returned by HDF_SD_CREATE or HDF_SD_SELECT. comptype The compression type to be applied to the HDF SD dataset. Allowable values are: * 0 = NONE (no compression) * 1 = RLE (run-length encoding) * 3 = SKIPPING HUFFMAN * 4 = GZIP Note All compression types are lossless. Keywords EFFORT If the comptype is set to 4 (GZIP), then this keyword specifies the effort that GZIP expends in compressing the dataset. The EFFORT keyword is restricted to the range 1 (minimal compression, fastest) to 9 (most compressed, slowest). The default is EFFORT=5. Example ; Create an HDF SD file: sd_id = HDF_SD_START('compress.hdf', /CREATE) ; Create an SDS dataset: sds_id = HDF_SD_CREATE(sd_id, 'dataset1', [9,40], /LONG) ; Maximal GZIP compression: HDF_SD_SETCOMPRESS,sds_id,4,EFFORT=9 ; Write the data to be compressed: HDF_SD_ADDDATA,sds_id,fix(dist(9,40)) ; End access to the SDS: HDF_SD_ENDACCESS, sds_id ; End access to the SD interface: HDF_SD_END, sd_id Note Compression of HDF SD datasets is a new feature as of HDF 4.1r2 / IDL 5.2.1. Attempts to read HDF SD datasets not created with HDF 4.1r2 (IDL 5.1) or greater will give unpredictable results. Attempts to read HDF compressed SD datasets with IDL versions prior to IDL 5.1, or other HDF readers that use an HDF version prior to HDF 4.1r2, will fail. HDF_SD_SETEXTFILE [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_SD_SETEXTFILE The HDF_SD_SETEXTFILE procedure moves data values from a dataset into an external file. Only the data is moved-all other information remains in the original file. This routine can only be used with HDF version 3.3 (and later) files, not on older HDF files or NetCDF files. Data can only be moved once, and the user must keep track of the external file(s). The OFFSET keyword allows writing to an arbitrary location in the external file. As shown in the example, when adding data to an external file SD, you must first use HDF_SD_ENDACCESS to sync the file, then reacquire the SDS ID with HDF_SD_SELECT before using HDF_SD_SETEXTFILE. Syntax HDF_SD_SETEXTFILE, SDS_ID, Filename [, OFFSET=bytes] Arguments sds_id An SD dataset ID as returned by HDF_SD_SELECT. Filename The name of the external file to be written. Keywords OFFSET Set this keyword to a number of bytes from the beginning of the external file at which data writing should begin. Exercise extreme caution when using this keyword with existing files. Example ; Create an HDF file: sd_id = HDF_SD_START('ext_main.hdf', /CREATE) ; Add an SD: sds_id = HDF_SD_CREATE(sd_id, 'float_findgen', [3,5], /FLOAT) ; Put some data into the SD: HDF_SD_ADDDATA, sds_id, FINDGEN(3,5) ; Call HDF_SD_ENDACCESS to sync the file: HDF_SD_ENDACCESS,sds_id ; Reacquire the SDS_ID: sds_id = HDF_SD_SELECT(sd_id, 0) ; Move data to an external file named findgen.hdf: HDF_SD_SETEXTFILE, sds_id, 'findgen.hdf' ; Retrieve data from the external file into the variable fout: HDF_SD_GETDATA, sds_id, fout ; Print the contents of fout: PRINT, fout ; Sync and close the files: HDF_SD_ENDACCESS, sds_id HDF_SD_END, sd_id IDL Output 0.00000 1.00000 2.00000 3.00000 4.00000 5.00000 6.00000 7.00000 8.00000 9.00000 10.0000 11.0000 12.0000 13.0000 14.0000 See Also HDF_SD_END, HDF_SD_ENDACCESS, HDF_SD_SELECT, HDF_SD_START HDF_SD_SETINFO [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_SD_SETINFO The HDF_SD_SETINFO procedure sets information about an SD dataset. Warning Setting a label, unit, format, or coordinate system string that has more than 256 characters can have unpredictable results. Syntax HDF_SD_SETINFO, SDS_ID [, FILL=value] [, FORMAT=string] [, LABEL=string] [, RANGE=[max, min]] [, UNIT=string] [, COORDSYS=string] [, CALDATA=structure] Arguments SDS_ID An SD dataset ID as returned by HDF_SD _SELECT or HDF_SD_CREATE. Keywords FILL Set this keyword to the fill value of the SD dataset. FORMAT Set this keyword to a string to be used as the SD dataset format. LABEL Set this keyword to a string to be used as the SD dataset label. RANGE Set this keyword to a two dimensional array that contains the minimum and maximum values of the SD dataset. UNIT Set this keyword to a string to be used as the SD dataset units. COORDSYS Set this keyword to a string to be used as the SD dataset coordinate system. CALDATA Set this keyword to a structure that contains the calibration data. This structure must contain five tags as shown below. The first four tags are of double-precision floating- point type. The fifth tag should be a long integer that specifies the HDF number type. The structure should have the following form: CALDATA={ Cal: 0.0D $ ;Calibration Factor Cal_Err: 0.0D $ ;Calibration Error Offset: 0.0D $ ;Uncalibrated Offset Offset_Err: 0.0D $ ;Uncalibrated Offset Error Num_Type: 0L } ;Number Type of Uncalibrated Data The relationship between HDF and IDL number types is illustrated by the following table: HDF Number Type IDL Data Type 0L UNDEFINED 3L STRING 21L BYTE 22L INTEGER 24L LONG INTEGER 5L FLOATING-POINT 6L DOUBLE-PRECISION Table 3-10: HDF Number Types vs. IDL Data Types The relationship between the calibrated data (CD) and the uncalibrated data (UD) is given by the equation: CD = Cal * (UD - Offset) Cal and Offset are the values of the Cal and Offset structure fields described above. Example ; Open an HDF file: sd_id = HDF_SD_START('demo.hdf', /RDWR) ; Define a new dataset for the file: sds_id = HDF_SD_CREATE(sd_id, 'variable1', [10, 20], /DOUBLE) ; Create a calibration data structure: CAL={Cal:1.0D, Cal_Err:0.1D, Offset:2.5D, Offset_Err:0.1D, $ Num_Type:6L} ; Set information about the dataset: HDF_SD_SETINFO, sds_id, LABEL='label1', unit='unit1', $ format='format1', coordsys='coord1', FILL=999.991, $ RANGE=[99.99,-78], caldata=CAL ; Retrieve the information: HDF_SD_GETINFO, sds_id, LABEL=l, UNIT=u, FORMAT=f, $ COORDSYS=c, FILL=fill, RANGE=r, CALDATA=cd, $ NDIMS=ndims, DIMS=dims, TYPE=ty ; Print information about the returned variables: HELP, l, u, f, c, fill, r, cd, ndims, dims, ty ; Print the range: PRINT, r ; Print the calibration data: PRINT, cd ; Print the dimensions: PRINT, dims ; Close the SD interface: HDF_SD_ENDACCESS, sds_id HDF_SD_END, sd_id IDL Output L STRING = 'label1' U STRING = 'unit1' F STRING = 'format1' C STRING = 'coord1' FILL DOUBLE = 999.99103 R DOUBLE = Array(2) CD STRUCT = -> < Anonymous > Array(1) NDIMS LONG = 2 DIMS LONG = Array(2) TY STRING = 'DOUBLE' -78.000000 99.989998 { 1.0000000 0.10000000 2.5000000 0.10000000 6} 10 20 See Also HDF_SD_END, HDF_SD_ENDACCESS, HDF_SD_GETINFO, HDF_SD_START HDF_SD_START [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_SD_START The HDF_SD_START function opens or creates an HDF file and initializes the SD interface. The returned value of this function is the SD ID of the HDF file. If no keywords are present, the file is opened in read-only mode. Note that every file opened with HDF_SD_START should eventually be closed with a call to HDF_SD_END. Syntax Result = HDF_SD_START( Filename [, /READ | , /RDWR] [, /CREATE] ) Arguments Filename A scalar string containing the name of the file to be opened or created. HDF_SD_START can open the following file types: XDR-based NetCDF files, "old- style" DFSD files, or "new-style" SD files. New files are created as "new-style" SD files. Keywords READ Set this keyword to open the SD interface in read-only mode. If no keywords are specified, this is the default behavior. RDWR Set this keyword to open the SD interface in read and write mode. CREATE Set this keyword to create a new SD file. Example ; Open a new HDF file. The file is ready to be accessed: sd_id = HDF_SD_START('test.hdf', /CREATE) ; When finished with the file, close it with a call to HDF_SD_END: HDF_SD_END, sd_id For a more complicated example, see the documentation for HDF_SD_ATTRSET. See Also HDF_CLOSE, HDF_OPEN, HDF_SD_ATTRFIND, HDF_SD_ATTRINFO, HDF_SD_ATTRSET, HDF_SD_CREATE, HDF_SD_END, HDF_SD_FILEINFO, HDF_SD_NAMETOINDEX, HDF_SD_REFTOINDEX, HDF_SD_SELECT, HDF_SD_SETEXTFILE HDF_UNPACKDATA [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_UNPACKDATA This procedure unpacks an array of byte data into a number of IDL variables. It is useful in deconstructing the output of multi-field HDF Vdata reading routines, such as those found in HDF-EOS, into a set of IDL variables. The packed data is assumed to be an array of bytes that is organized as a number of records. Each record consists of one or more data fields. A record is defined using the HDF_TYPE and HDF_ORDER keywords. These define the record layout in terms of HDF data types. The procedure walks through the input array and copies the values into output IDL arrays. There must be as many entries in the HDF_TYPE and HDF_ORDER keywords as there are data arguments. Syntax HDF_UNPACKDATA, packeddata, data1 [, data2 [, data3 [, data4 [, data5 [, data6 [, data7 [, data8]]]]]]] [, HDF_ORDER=array] [, HDF_TYPE=array] [, NREC=records] Arguments packeddata A BYTE array of packed data. data1...data8 These arguments return IDL arrays of the types specified by HDF_TYPE with values for each record in the packed data. If HDF_ORDER is greater than one, the returned array will be 2D and the leading dimension will be of length HDF_ORDER. The one exception is string types, which will be returned as a 1D array of IDL strings. The fixed-length string field is returned as an IDL string up to the first zero value (if present). The trailing dimension will be equal to the minimum of the NREC keyword value or the number of complete records that fit in the packeddata array. Keywords HDF_ORDER Set this keyword to an array with the same length as the number of data fields. The values in the array are equal to the number of elements in the return argument for each record. In the case of strings, this is the length (in characters) of the string to be read. A value of zero is interpreted as one element. The default for this keyword is an array of ones. HDF_TYPE Set this keyword to an array with the same length as the number of data fields. The value in the array is an HDF data type for each return argument. The returned IDL variables will have these types. The default for this keyword is an array of the value 5 (an HDF 32-bit float). See "IDL and HDF Data Types" on page 96 for valid values. NREC Set this keyword to the number of records to read from packeddata. The default is to read as many complete records as exist in the packeddata array. Example a = INDGEN(5) b = FINDGEN(5) c = ['This', 'is', 'a', 'string', 'array.'] HELP, a, b, c hdftype = [ 22, 5, 4] ; HDF INT16, FLOAT32 and CHAR order = [ 0, 0, 6] ; 2 + 4 + 6 = 12 bytes/record data = HDF_PACKDATA( a, b, c, HDF_TYPE=hdftype, HDF_ORDER=order) HELP, data ; a [12, 5] array (5 - 12byte records) HDF_UNPACKDATA, data, d, e, f, HDF_TYPE=hdftype, HDF_ORDER=order HELP, d, e, f ; recover the original arrays See Also HDF_PACKDATA, HDF_VD_READ, EOS_PT_READLEVEL HDF_VD_ATTACH [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_VD_ATTACH The HDF_VD_ATTACH function accesses a VData with the given Id in an HDF file. If successful, a handle for that VData is returned, otherwise 0 is returned. Syntax Result = HDF_VD_ATTACH( FileHandle, VDataId [, /READ] [, /WRITE] ) Arguments FileHandle The HDF file handle returned from a previous call to HDF_OPEN. VDataId The VData reference number, usually obtained by HDF_VD_GETID or HDF_VD_LONE. Set this argument to -1 to create a new VData. Keywords READ Set this keyword to open the VData for reading. This is the default. WRITE Set this keyword to open the VData for writing. If VDataID is set equal to -1, the file is opened for writing whether or not this keyword is set. HDF_VD_DETACH [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_VD_DETACH The HDF_VD_DETACH procedure is called when done accessing a VData in an HDF file. This routine must be called for every VData attached for writing before closing the HDF file to insure that VSET information is properly updated. Syntax HDF_VD_DETACH, VData Arguments VData The VData handle returned by a previous call to HDF_VD_ATTACH. HDF_VD_FDEFINE [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_VD_FDEFINE The HDF_VD_FDEFINE procedure adds a new field specification for a VData in an HDF file. HDF_VD_FDEFINE can only be used for a new VData. Syntax HDF_VD_FDEFINE, VData, Fieldname [, /BYTE | , /DLONG, | , /DOUBLE | , /DULONG | , /FLOAT | , /INT | , /LONG | , /UINT, | , /ULONG] [, ORDER=value] Arguments VData The VData handle returned by a previous call to HDF_VD_ATTACH. Fieldname A string containing the new field name. Keywords BYTE Set this keyword to indicate that the field will contain 8-bit unsigned integer data. DOUBLE Set this keyword to indicate that the field will contain 64-bit floating point data. FLOAT Set this keyword to indicate that the field will contain 32-bit floating point data. INT Set this keyword to indicate that the field will contain 16-bit integer data. LONG Set this keyword to indicate that the field will contain 32-bit integer data. ORDER This keyword specifies the number of distinct components in the new field. Compound variables have an order greater than 1. The default order is 1. Example HDF_VD_FDEFINE, vid, 'VEL', /DOUBLE, ORDER=3 HDF_VD_FEXIST [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_VD_FEXIST The HDF_VD_FEXIST function returns true if all the specified fields exist in the given HDF file. Syntax Result = HDF_VD_FEXIST(VData, Fieldnames) Arguments VData The VData handle returned by a previous call to HDF_VD_ATTACH. Fieldnames A string containing a comma-separated list of fields to test. For example, 'VEL' or 'PZ,PY,PX'. HDF_VD_FIND [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_VD_FIND The HDF_VD_FIND function returns the reference number of a VData with the specified name in an HDF file. A 0 is returned if an error occurs or a VData of the given name does not exist. Syntax Result = HDF_VD_FIND(FileHandle, Name) Arguments FileHandle The HDF file handle returned from a previous call to HDF_OPEN. Name A string containing the name of the VData to be found. HDF_VD_GET [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_VD_GET The HDF_VD_GET procedure is a general VData inquiry routine. Set the various keywords to named variables to return information about a VData in an HDF file. Syntax HDF_VD_GET, VData [, CLASS=variable] [, COUNT=variable] [, FIELDS=variable] [, INTERLACE=variable] [, NAME=variable] [, NFIELDS=variable] [, REF=variable] [, SIZE=variable] [, TAG=variable] Arguments VData A VData handle returned by HDF_VD_ATTACH. Keywords CLASS Set this keyword to a named variable in which the class name of the VData is returned as a string. COUNT Set this keyword to a named variable in which a long, containing the number of records in the VData, is returned. FIELDS Set this keyword to a named variable in which a comma-separated string of fields in the VData is returned (e.g., 'PX,PY,PZ') The maximum number of fields is 256 (except on the Macintosh, where it is 64). Each field can be up to 128 characters in length. The returned fields may or may not contain buffering whitespace depending on how the HDF file was created. INTERLACE Set this keyword to a named variable in which a string, containing either 'FULL_INTERLACE' or 'NO_INTERLACE', is returned. NAME Set this keyword to a named variable in which a string, containing the name of the VData, is returned. NFIELDS Set this keyword to a named variable in which a long, containing the number of fields in the VDATA, is returned. For example, the VData containing the fields "PX,PY,PZ", has an NFIELDS of 3. REF Set this keyword to a named variable in which the reference number of the VData is returned. SIZE Set this keyword to a named variable in which a long, containing the local size of a record of VData, is returned. TAG Set this keyword to a named variable in which the tag number of the VData is returned. Example HDF_VD_GET, vdat, CLASS=c, COUNT=co, FIELDS=f, NAME=n, SIZE=s See Also HDF_VD_GETINFO, HDF_VG_GETINFO HDF_VD_GETID [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_VD_GETID The HDF_VD_GETID function returns the VData reference number for the next VData in an HDF file after the specified VDataId. Set VDataId to -1 to return the first VData ID in the file. Syntax Result = HDF_VD_GETID(FileHandle, VDataId) Arguments FileHandle The HDF file handle returned by a previous call to HDF_OPEN. VDataID The VData reference number, generally obtained by HDF_VD_GETID or HDF_VD_LONE. Set this argument to -1 to return the first VData in the file. HDF_VD_GETINFO [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_VD_GETINFO The HDF_VD_GETINFO procedure is a general VData inquiry routine. Set the various keywords to named variables to return information about each field of a VData in a HDF file. Syntax HDF_VD_GETINFO, VData, Index [, NAME=variable] [, ORDER=variable] [, SIZE=variable] [, TYPE=variable] Arguments VData The VData handle returned by a previous call to HDF_VD_ATTACH. Index A zero-based index specifying which field or the name of the field within the VData to inquire about. For example: HDF_VD_GETINFO, Vdat, 'VEL', ORDER=order Keywords NAME Set this keyword to a named variable in which the name of the field is returned as a string. ORDER Set this keyword to a named variable in which the order of the field is returned. SIZE Set this keyword to a named variable in which the size of a data value for the specified field in the VData is returned. TYPE Set this keyword to a named variable in which the type of the field is returned. One of the following strings is returned: 'BYTE', 'INT', 'LONG', 'FLOAT', 'DOUBLE'. Example HDF_VD_GET, Vdat, NFIELDS=n FOR index=0,n-1 DO BEGIN HDF_VD_GETINFO, Vdat, index, NAME=n, TYPE=t, ORDER=o PRINT, index, ':', n, 'TYPE=', t, 'ORDER=', o ENDFOR HDF_VD_GETNEXT [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_VD_GETNEXT The HDF_VD_GETNEXT function returns the reference number of the next object inside a VData in an HDF file. If Id is -1, the first item in the VData is returned, otherwise Id should be set to a reference number previously returned by HDF_VD_GETNEXT. HDF_VD_GETNEXT returns -1 if there was an error or there are no more objects after the one specified by Id. Syntax Result = HDF_VD_GETNEXT(VData, Id) Arguments VData The VData handle returned by a previous call to HDF_VD_ATTACH. Id A VGroup or VData reference number obtained by a previous call to HDF_VG_GETNEXT or HDF_VD_GETNEXT. Alternatively, this value can be set to -1 to return the first item in the VData. HDF_VD_INSERT [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_VD_INSERT The HDF_VD_INSERT procedure adds a VData or VGroup to the contents of a VGroup in an HDF file. Syntax HDF_VD_INSERT, VGroup, VData(or Vgroup)[, POSITION=variable] Arguments VGroup The VGroup handle returned by a previous call to HDF_VG_ATTACH. VData The VData (or VGroup) handle returned by HDF_VD_ATTACH (HDF_VG_ATTACH). HDF_VD_ISVD [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_VD_ISVD The HDF_VD_ISVD function returns True (1) if the object associated with Id is a VData in an HDF file. Syntax Result = HDF_VD_ISVD(VGroup, Id) Arguments VGroup The VGroup handle returned by a previous call to HDF_VG_ATTACH. Id The VGroup or VData reference number obtained by a previous call to HDF_VG_GETNEXT or HDF_VD_GETNEXT. Example Vid = HDF_VD_GETNEXT(Vgrp, -1) PRINT, HDF_VD_ISVD(VGrp, Vid) HDF_VD_ISVG [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_VD_ISVG The HDF_VD_ISVG function returns True (1) if the object associated with Id is a VGroup in an HDF file. Syntax Result = HDF_VG_ISVG(VGroup, Id) Arguments VGroup The VGroup handle returned by a previous call to HDF_VG_ATTACH. Id The VGroup or VData reference number obtained by a previous call to HDF_VG_GETNEXT. Example Vid = HDF_VD_GETNEXT(Vgrp, -1) PRINT, HDF_VD_ISVG(VGrp, Vid) HDF_VD_LONE [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_VD_LONE The HDF_VD_LONE function returns an array containing all VDatas in an HDF file that are not contained in another VData. If there are no lone VDatas, HDF_VD_LONE returns -1. Syntax Result = HDF_VD_LONE( FileHandle [, MAXSIZE=value] ) Arguments FileHandle The HDF file handle returned from a previous call to HDF_OPEN. Keywords MAXSIZE The maximum number of groups to be returned (the default is to return all known lone VDatas). For example, to return only the first 12 groups: X = HDF_VD_LONE(fid, MAX=12) Example X = HDF_VD_LONE(fid) IF N_ELEMENTS(X) EQ 0 THEN $ PRINT, 'No Lone VDatas' ELSE PRINT, 'Lone VDatas:', X HDF_VD_READ [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_VD_READ The HDF_VD_READ function reads data from a VData in an HDF file. This function returns the number of records successfully read from the VData. The default is to use FULL_INTERLACE and to read all fields in all records. The user can override the defaults with keywords. If multiple fields with different data types are read, all of the data is read into a byte array. The data must then be explicitly converted back into the correct type(s) using various IDL type conversion routines. For example: nread = HDF_VD_READ(vdat, x, NREC=1, FIELDS="FLT,LNG") floatvalue = FLOAT(x, 0) longvalue = LONG(x, 4) Syntax Result = HDF_VD_READ( VData, Data [, FIELDS=string] [, /FULL_INTERLACE | , /NO_INTERLACE] [, NRECORDS=records] ) Arguments VData The VData handle returned by a previous call to HDF_VD_ATTACH. Data A named variable in which the data is returned. Keywords FIELDS A string containing a comma-separated list of fields to be read. Normally HDF_VD_READ will read all fields in the VData. FULL_INTERLACE Set this keyword to use full interlace when reading (the default). NO_INTERLACE Set this keyword to use no interlace when reading. NRECORDS The number of records to read. By default, HDF_VD_READ reads all records from a VData. Examples Typical read: NREC = HDF_VD_READ(Vdat, X) Read one field: NREC = HDF_VD_READ(Vdat, X, FIELDS='VEL') Read a record: NREC = HDF_VD_READ(Vdat, X, NRECORDS=1) HDF_VD_SEEK [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_VD_SEEK The HDF_VD_SEEK procedure moves the read pointer within the specified VData in an HDF file to a specific record number. Note that the record number is zero- based. Syntax HDF_VD_SEEK, VData, Record Arguments VData A VData handle returned by HDF_VD_ATTACH. Record The zero-based record number to seek. HDF_VD_SETINFO [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_VD_SETINFO The HDF_VD_SETINFO procedure specifies general information about a VData in an HDF file. Keywords can be used to establish the name, class, and interlace for the specified VData. Syntax HDF_VD_SETINFO, VData [, CLASS=string] [, /FULL_INTERLACE | , /NO_INTERLACE] [, NAME=string] Arguments VData The VData handle returned by a previous call to HDF_VD_ATTACH. Keywords CLASS A string that sets the class name for the VData. FULL_INTERLACE Set this keyword to store data in the file with full interlace (i.e., sequentially by record). NAME A string that sets the name of the VData. NO_INTERLACE Set this keyword to store data in the file with no interlace (i.e., sequentially by field). Example HDF_VD_SETINFO, Vdat, NAME='My Favorite Data', /FULL HDF_VD_WRITE [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_VD_WRITE The HDF_VD_WRITE procedure stores data in a VData in an HDF file. There are many restrictions on writing data to a VData. When writing multiple fields of varying types, only limited error checking is possible. When writing a series of fields all with the same type, data is converted to that type before writing. For example: Vdat = HDF_VD_ATTACH(Fid, -1, /WRITE) ; Create a 10 integer vector: Data = INDGEN(10) ; Data converted to FLOAT before write: HDF_VD_WRITE, Vdat, 'PX', Data It is possible to write less data than exists in the Data argument by using the NRECORDS keyword. For example, the following command writes 5 records, instead of the 10 implied by the size of the data (VEL is assumed to be of type FLOAT, order=3): HDF_VD_WRITE, Vdat, 'VEL', FINDGEN(3,10),NREC=5 VEL now contains [ [ 0.0, 1.0, 2.0 ], ..., [ 12.0, 13.0, 14.0] ] HDF_VD_WRITE will not allow a user to specify more records than exist. For example, the following command fails: HDF_VD_WRITE, Vdat, 'VEL', [1,2,3], NREC=1000 Bugs Data can not be appended. Attempts to append data may make future attempts to read data fail. Data can not be overwritten. Syntax HDF_VD_WRITE, VData, Fields, Data [, /FULL_INTERLACE | , /NO_INTERLACE] [, NRECORDS=records] Arguments VData The VData handle returned by a previous call to HDF_VD_ATTACH. Fields A string containing a comma-separated list of the fields to be written. Data The data to be written to the specified VData. Keywords FULL_INTERLACE Set this keyword to use full interlace when writing (the default). NO_INTERLACE Set this keyword to use no interlace when writing. NRECORDS The number of records to written. By default, HDF_VD_WRITE writes all records from a VData. Restrictions It is not possible to write IDL structures directly to a VData (because of possible internal padding depending upon fields/machine architecture, etc.). The user must put the data into a byte array before using HDF_VD_WRITE. When writing a series of fields all with the same type, the low order dimension of Data must match the sum of the orders of the fields. For example: HDF_VD_WRITE, Vdat, 'PX,PY', FLTARR(3,10) fails. PX and PY are both order 1 (total 2) and the array's low order dimension is 3. HDF_VG_ADDTR [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_VG_ADDTR The HDF_VG_ADDTR procedure adds a tag and reference to the specified VGroup in an HDF file. Syntax HDF_VG_ADDTR, VGroup, Tag, Ref Arguments VGroup The VGroup handle returned by a previous call to HDF_VG_ATTACH. Tag The tag to be written. Ref The reference number to be written. Example See "HDF_SD_IDTOREF" on page 242 for an example using this function. See Also HDF_VG_GETTR, HDF_VG_GETTRS, HDF_VG_INQTR, HDF_VG_INSERT HDF_VG_ATTACH [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_VG_ATTACH The HDF_VG_ATTACH procedure attaches (opens) a VGroup in an HDF file for reading or writing. If successful, a handle for that group is returned. If it fails, 0 is returned. If VGroupId is set to -1, a new VGroup is created. If neither the READ nor WRITE keywords are set, the VGroup is opened for reading. Syntax Result = HDF_VG_ATTACH( FileHandle, VGroupId [, /READ] [, /WRITE] ) Arguments FileHandle The HDF file handle returned from a previous call to HDF_OPEN. VGroupId The VGroup reference number, generally obtained by HDF_VG_GETID or HDF_VG_LONE. Keywords READ Set this keyword to open the VGroup for reading. WRITE Set this keyword to open the VGroup for writing. Example See "HDF_SD_IDTOREF" on page 242 for an example using this function. HDF_VG_DETACH [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_VG_DETACH The HDF_VG_DETACH procedure should be called when you are finished accessing a VGroup in an HDF file. This routine must be called for every VGroup attached for writing before closing the HDF file in order to insure that VSET information is properly updated. Syntax HDF_VG_DETACH, VGroup Arguments VGroup The VGroup handle returned by a previous call to HDF_VG_ATTACH. Example See "HDF_SD_IDTOREF" on page 242 for an example using this function. HDF_VG_GETID [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_VG_GETID The HDF_VG_GETID function returns the VGroup ID for the next VGroup after the specified VGroupId in an HDF file. Use a VGroupId of -1 to get the first VGroup in the file. Syntax Result = HDF_VG_GETID(FileHandle, VGroupId) Arguments FileHandle The HDF file handle returned from a previous call to HDF_OPEN. VGroupID The VGroup reference number, generally obtained by HDF_VG_GETID or HDF_VG_LONE. Example See "HDF_SD_IDTOREF" on page 242 for an example using this function. HDF_VG_GETINFO [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_VG_GETINFO The HDF_VG_GETINFO procedure is a general VGroup inquiry routine. Set the various keywords to named variables to return information about different aspects of a VGroup in an HDF file. Syntax HDF_VG_GETINFO, VGroup [, CLASS=variable] [, NAME=variable] [, NENTRIES=variable] [, REF=variable] [, TAG=variable] Arguments VGroup The VGroup handle returned by a previous call to HDF_VG_ATTACH. Keywords CLASS Set this keyword to a named variable in which the class of the VGroup is returned as a string. NAME Set this keyword to a named variable in which the name of the VGroup is returned as a string. NENTRIES Set this keyword to a named variable in which the number of objects inside the VGroup is returned as a long integer. REF Set this keyword to a named variable in which the reference number of the specified Vgroup is returned. TAG Set this keyword to a named variable in which the tag number of the specified Vgroup is returned. Example HDF_VG_GETINFO, Vgrp, CLASS=c, NAME=nm, NENTRIES=n PRINT, c, nm, n HDF_VG_GETNEXT [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_VG_GETNEXT The HDF_VG_GETNEXT function returns the reference number of the next object inside a VGroup in an HDF file. If Id is -1, the first item in the VGroup is returned, otherwise Id should be set to a reference number previously returned by HDF_VG_GETNEXT. HDF_VG_GETNEXT returns -1 if there was an error or there are no more objects after the one specified by Id. Syntax Result = HDF_VG_GETNEXT(VGroup, Id) Arguments VGroup The VGroup handle returned by a previous call to HDF_VG_ATTACH. Id A VGroup or VData reference number obtained by a previous call to HDF_VG_GETNEXT. Alternatively, this value can be set to -1 to return the first item in the VGroup. HDF_VG_GETTR [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_VG_GETTR The HDF_VG_GETTR procedure returns the tag/reference pair at the specified position within a VGroup in an HDF file. Syntax HDF_VG_GETTR, VGroup, Index, Tags, Refs Arguments VGroup The VGroup handle returned by a previous call to HDF_VG_ATTACH. Index The position within VGroup. Tags A named variable in which the tag numbers are returned. Refs A named variable in which the reference numbers are returned. HDF_VG_GETTRS [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_VG_GETTRS The HDF_VG_GETTRS procedure returns the tag/reference pairs of the HDF file objects belonging to the specified VGroup. Syntax HDF_VG_GETTRS, VGroup, Tags, Refs [, MAXSIZE=value] Arguments VGroup The VGroup handle returned by a previous call to HDF_VG_ATTACH. Tags A named variable in which the tag numbers are returned. Refs A named variable in which the reference numbers are returned. Keywords MAXSIZE The maximum number of tags and references to be returned. The default is to return all tags and references in VGroup. HDF_VG_INQTR [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_VG_INQTR The HDF_VG_INQTR function returns true if the specified tag and reference pair is linked to the specified VGroup in an HDF file. Syntax Result = HDF_VG_INQTR(VGroup, Tag, Ref) Arguments VGroup The VGroup handle returned by a previous call to HDF_VG_ATTACH. Tag The tag number. Ref The reference number. Example See "HDF_SD_IDTOREF" on page 242 for an example using this function. HDF_VG_INSERT [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_VG_INSERT The HDF_VG_INSERT procedure adds a VData or VGroup to the contents of a VGroup in an HDF file. Syntax HDF_VG_INSERT, VGroup, VData(or Vgroup)[, POSITION=variable] Arguments VGroup The VGroup handle returned by a previous call to HDF_VG_ATTACH. VData The VData (or VGroup) handle returned by HDF_VD_ATTACH (HDF_VG_ATTACH). HDF_VG_ISVD [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_VG_ISVD The HDF_VG_ISVD function returns true if the object associated with Id is a VData in an HDF file. Syntax Result = HDF_VG_ISVD(VGroup, Id) Arguments VGroup The VGroup handle returned by a previous call to HDF_VG_ATTACH. Id The VGroup or VData reference number obtained by a previous call to HDF_VG_GETNEXT. Example Vid = HDF_VG_GETNEXT(Vgrp, -1) PRINT, HDF_VG_ISVD(VGrp, Vid) HDF_VG_ISVG [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_VG_ISVG The HDF_VG_ISVG function returns true if the object associated the Id is a VGroup in an HDF file. Syntax Result = HDF_VG_ISVG(VGroup, Id) Arguments VGroup The VGroup handle returned by a previous call to HDF_VG_ATTACH. Id The VGroup or VData reference number obtained by a previous call to HDF_VG_GETNEXT. Example Vid = HDF_VG_GETNEXT(Vgrp, -1) PRINT, HDF_VG_ISVG(VGrp, Vid) HDF_VG_LONE [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_VG_LONE The HDF_VG_LONE function returns an array containing the IDs of all VGroups in an HDF file that are not contained in another VGroup. If there are no lone VGroups, HDF_VG_LONE returns -1. Syntax Result = HDF_VG_LONE( FileHandle [, MAXSIZE=value] ) Arguments FileHandle The HDF file handle returned by a previous call to HDF_OPEN. Keywords MAXSIZE The maximum number of groups to return (the default is to return all lone VGroups). For example, to return no more than 12 VGroups, use the command: X = HDF_VG_LONE(fid, MAX=12) Example X=HDF_VG_LONE(fid) IF X(0) EQ-1 THEN $ PRINT, "No Lone VGroups" ELSE PRINT, "Lone VGroups:", X HDF_VG_NUMBER [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_VG_NUMBER The HDF_VG_NUMBER function returns the number of HDF file objects in the specified VGroup. Syntax Result = HDF_VG_NUMBER(VGroup) Arguments VGroup The VGroup handle returned by a previous call to HDF_VG_ATTACH. HDF_VG_SETINFO [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_VG_SETINFO The HDF_VG_SETINFO procedure sets the name and class of a VGroup. Syntax HDF_VG_SETINFO, VGroup [, CLASS=string] [, NAME=string] Arguments VGroup The VGroup handle as returned by HDF_VG _ATTACH. Keywords CLASSNAME A string containing the class name for the VGroup. NAME A string containing the name for the VGroup. Example fid = HDF_OPEN('demo.hdf',/RDWR) ; Open an HDF file: vgid = HDF_VG_ATTACH(fid, -1, /WRITE) ; Add a new VGroup: ; Set the name and class for the VGroup: HDF_VG_SETINFO, vgid, NAME='My Name', CLASS='My VGroup Class' ; Retrieve the name and class information from the file: HDF_VG_GETINFO, vgid, NAME=outname, CLASS=outclass ; Print information about the returned variables: HELP, outname, outclass ; End VGroup access: HDF_VG_DETACH, vgid ; Close the HDF file: HDF_CLOSE, fid IDL Output OUTNAME STRING = 'My Name' OUTCLASS STRING = 'My VGroup Class' See Also HDF_VG_GETINFO FEATURE ROUTINES [Previous Routine] [Next Routine] [List of Routines] NAME: Feature Routines HDF-EOS is an extension of NCSA (National Center for Supercomputing Applications) HDF and uses HDF calls as an underlying basis. This API contains functionality for creating, accessing and manipulating Grid, Point and Swath structures. The Grid interface is designed to support data that has been stored in a rectilinear array based on a well-defined and explicitly supported projection. Tips on writing a grid: * Setting a compression method affects all subsequently defined fields * Setting a tiling scheme affects all subsequently defined fields The Point interface is designed to support data that has associated geolocation information, but is not organized in any well-defined spatial or temporal way. Tips on writing a point: * Every level in a point data set must be linked into the hierarchy * Before two levels can be linked, a link field must exist The Swath interface is tailored to support time-oriented data such as satellite swaths (which consist of a time-oriented series of scanlines), or profilers (which consist of a time-oriented series of profiles). Tips on writing a swath: * Define dimensions before using them to define fields of maps * Setting a compression method affects all subsequently defined fields * If a dimension map is not defined, a one-to-one mapping is assumed during subsetting. HDF-EOS PROGRAMMING MODEL [Previous Routine] [Next Routine] [List of Routines] NAME: HDF-EOS Programming Model Writing * open file * create object * define structure * detach object * attach object * write data * detach object * close file Reading * open file * attach object * inquire object * read data * detach object * close file Note When writing an HDF-EOS object, be sure to detach the object before attaching it for the first time. This will initialize the library for the new object. The object will not be written correctly if the above model is not followed. EOS_EH_CONVANG [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_EH_CONVANG This function converts angles between three units: decimal degrees, radians, and packed degrees-minutes-seconds. In the degrees-minutes-seconds unit, an angle is expressed as an integral number of degrees and minutes and a float point value of seconds packed as a single double as follows: DDDMMMSSS.SS. Syntax Result = EOS_EH_CONVANG(inAngle, code) Return Value Returns angle in desired units. Arguments inAngle Input angle (float). code Conversion code (long). Allowable values are: * 0 = Radians to Degrees * 1 = Degrees to Radians * 2 = DMS to Degrees * 3 = Degrees to DMS * 4 = Radians to DMS * 5 = DMS to Radians Example To convert 27.5 degrees to packed format: inAng = 27.5 outAng = EOS_EH_CONVANG(inAng, 3) outAng will contain the value 27030000.00. EOS_EH_GETVERSION [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_EH_GETVERSION The EOS_EH_GETVERSION function is used to retrieve the HDF-EOS version string of an HDF-EOS file, which is returned in the version argument. This designates the version of HDF-EOS that was used to create the file. This string is of the form "HDFEOS_Vmaj.min" where maj is the major version and min is the minor version. Syntax Result = EOS_EH_GETVERSION(fid, version) Return Value Returns SUCCEED(0) if successful and FAIL(­1) otherwise. Arguments fid File id (long) returned by EOS_SW_OPEN, EOS_GD_OPEN, or EOS_PT_OPEN. version HDF-EOS version (string). Example To get the HDF-EOS version (assumed to be 2.3) used to create the HDF-EOS file: fid = EOS_SW_OPEN("Swathfile.hdf", /READ) status = EOS_EH_GETVERSION(fid, version) version will contain the string "HDFEOS_V2.3". EOS_EH_IDINFO [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_EH_IDINFO This function returns the HDF file IDs corresponding to the HDF-EOS file ID returned by EOS_SW_OPEN, EOS_GD_OPEN, or EOS_PT_OPEN. These IDs can then be used to create or access native HDF structures such as SDS arrays, Vdatas, or HDF attributes within an HDF-EOS file. Syntax Result = EOS_EH_IDINFO(fid, HDFfid, sdInterfaceID) Return Value Returns SUCCEED(0) if successful and FAIL(­1) otherwise. Arguments fid File ID (long) returned by EOS_SW_OPEN, EOS_GD_OPEN, or EOS_PT_OPEN. HDFfid A named variable that will contain the HDF file ID (long) returned by Hopen. sdInterfaceID A named variable that will contain the SD interface ID (long) returned by SDstart. Example To create a vdata within an existing HDF-EOS file: fid = EOS_SW_OPEN("SwathFile.hdf", /RDWR) status = EOS_EH_IDINFO(fid, hdffid, sdid) EOS_EXISTS [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_EXISTS The EOS_EXISTS function returns success (1) if the HDF-EOS extensions are supported on the current platform, and fail (0) if not. Syntax Result = EOS_EXISTS( ) Arguments None Keywords None Example IF (NOT HDF_EOS_EXISTS) THEN PRINT,'HDF-EOS not available.' EOS_GD_ATTACH [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_ATTACH This function attaches to the grid using the gridname parameter as the identifier. Syntax Result = EOS_GD_ATTACH(fid, gridname) Return Value Returns the grid handle (gridID) if successful and FAIL(­1) otherwise. Arguments fid Grid file id (long) returned by EOS_GD_OPEN. gridname Name of grid (string) to be attached. Keywords None. Example In this example, we attach to the previously created grid, "ExampleGrid", within the HDF file, GridFile.hdf, referred to by the handle, fid: gridID = EOS_GD_ATTACH(fid, "ExampleGrid") The grid can then be referenced by subsequent routines using the handle, gridID. EOS_GD_ATTRINFO [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_ATTRINFO This function returns number type and number of elements (count) of a grid attribute. Syntax Result = EOS_GD_ATTRINFO(gridID, attrname, numbertype, count) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments gridID Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH. attrname Attribute name (string). numbertype A named variable that will contain the number type (long) of an attribute. count A named variable that will contain the number of total bytes in an attribute (long). Keywords None. Example In this example, we return information about the ScalarFloat attribute: status = EOS_GD_ATTRINFO(pointID, "ScalarFloat", nt, count) EOS_GD_BLKSOMOFFSET [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_BLKSOMOFFSET This function writes block SOM offset values. This is a special function for SOM MISR data. Syntax Result = EOS_GD_BLKSOMOFFSET(gridID, offset, code) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments gridID The grid ID (long) as returned from EOS_GD_ATTACH. offset A scalar or array of offset values. code The type of action performed (read (r), write (w)). This value must be set to either the string r or w. If the string value is not recognized, the code defaults to r. Keywords None. EOS_GD_CLOSE [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_CLOSE This function closes the HDF grid file. Syntax Result = EOS_GD_CLOSE(fid) Return Value Returns SUCCEED(0) if successful and FAIL(­1) otherwise. Arguments fid Grid file id (long) returned by EOS_GD_OPEN. Example status = EOS_GD_CLOSE(fid) EOS_GD_COMPINFO [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_COMPINFO This function returns the compression code and compression parameters for a given field. Syntax Result = EOS_GD_COMPINFO(gridID, fieldname, compcode, compparm) Return Value Returns SUCCEED(0) if successful and FAIL(­1) otherwise. Arguments gridID Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH. fieldname Fieldname (string). compcode A named variable that will contain the HDF compression code (long). compparm A named variable that will contain the compression parameters (long array). Example To retrieve the compression information about the Opacity field defined in the EOS_GD_DEFCOMP section: status = EOS_GD_COMPINFO(gridID, "Opacity", compcode, compparm) See Also EOS_GD_DEFCOMP EOS_GD_CREATE [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_CREATE This function creates a grid within the file. The grid is created as a Vgroup within the HDF file with the name gridname and class GRID. This function establishes the resolution of the grid, (i.e., the number of rows and columns), and its location within the complete global projection through the upleftpt and lowrightpt arrays. These arrays should be in meters for all GCTP projections other than the Geographic Projection, which should be in packed degree format (q.v. below). For GCTP projection information, see the HDF-EOS User's Guide, Volume 2: Reference Guide provided by NASA. Syntax Result = EOS_GD_CREATE(fid, gridname, xdimsize, ydimsize, upleftpt, lowrightpt) Return Value Returns the grid handle (gridID) and FAIL(­1) otherwise. Arguments fid Grid file id (long) returned by EOS_GD_OPEN. gridname Name of grid (string) to be created. xdimsize Number of columns (long) in grid. ydimsize Number of rows (long) in grid. upleftpt Location (double, 2 element array) of upper left corner of the upper left pixel. lowrightpt Location (double, 2 element array) of lower right corner of the lower right pixel. Example In this example, we create a UTM grid bounded by 54 E to 60 E longitude and 20 N to 30 N latitude. We divide it into 120 bins along the x-axis and 200 bins along the y- axis. uplft[0]=10584.50041d uplft[1]=3322395.95445d lowrgt[0]=813931.10959d lowrgt[1]=214162.53278d xdim=120 ydim=200 gridID = EOS_GD_CREATE(fid, "UTMGrid", xdim, ydim, uplft, lowrgt) The grid structure is then referenced by subsequent routines using the handle, gridID. The xdim and ydim values are referenced in the field definition routines by the reserved dimensions: XDim and YDim. For the Polar Stereographic, Goode Homolosine and Lambert Azimuthal projections, we have established default values in the case of an entire hemisphere for the first projection, the entire globe for the second and the entire polar or equatorial projection for the third. In the case of the Geographic projection (linear scale in both longitude latitude), the upleftpt and lowrightpt arrays contain the longitude and latitude of these points in packed degree format (DDDMMMSSS.SS). * upleftpt- Array that contains the X-Y coordinates of the upper left corner of the upper left pixel of the grid. First and second elements of the array contain the X and Y coordinates respectively. The upper left X coordinate value should be the lowest X value of the grid. The upper left Y coordinate value should be the highest Y value of the grid. * lowrightpt - Array that contains the X-Y coordinates of the lower right corner of the lower right pixel of the grid. First and second elements of the array contain the X and Y coordinates respectively. The lower right X coordinate value should be the highest X value of the grid. The lower right Y coordinate value should be the lowest Y value of the grid. If the projection is geographic (i.e., projcode=0) then the X-Y coordinates should be specified in degrees/minutes/seconds (DDDMMMSSS.SS) format. The first element of the array holds the longitude and the second element holds the latitude. Latitudes are from ­90 to +90 and longitudes are from ­180 to +180 (west is negative). For all other projection types the X-Y coordinates should be in meters in double precision. These coordinates have to be computed using the GCTP software with the same projection parameters that have been specified in the projparm array. For UTM projections use the same zone code and its sign (positive or negative) while computing both upper left and lower right corner X-Y coordinates irrespective of the hemisphere. EOS_GD_DEFBOXREGION [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_DEFBOXREGION This function defines a longitude-latitude box region for a grid. It returns a grid region ID which is used by the EOS_GD_EXTRACTREGION function to read all the entries of a data field within the region. Syntax Result = EOS_GD_DEFBOXREGION(gridID, cornerlon, cornerlat) Return Value Returns the grid region ID if successful and FAIL (­1) otherwise. Arguments gridID Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH. cornerlon Longitude (double, 2 element array) in decimal degrees of box corners. cornerlat Latitude (double, 2 element array) in decimal degrees of box corners. Example In this example, we define the region to be the first quadrant of the Northern hemisphere: cornerlon[0] = 0.d cornerlat[0] = 90.d cornerlon[1] = 90.d cornerlat[1] = 0.d regionID = EOS_GD_DEFBOXREGION(EOS_GD_id, cornerlon, cornerlat) EOS_GD_DEFCOMP [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_DEFCOMP This function sets the HDF field compression for subsequent grid field definitions. The compression does not apply to one-dimensional fields. The compression schemes currently supported are: run length encoding (1), skipping Huffman (3), deflate (gzip) (4) and no compression (0, the default). Deflate compression requires a single integer compression parameter in the range of one to nine with higher values corresponding to greater compression. Compressed fields are written using the standard EOS_GD_WRITEFIELD function, however, the entire field must be written in a single call. If this is not possible, the user should consider tiling. See EOS_GD_DEFTILE for further information. Any portion of a compressed field can then be accessed with the EOS_GD_READFIELD function. Compression takes precedence over merging so that multi-dimensional fields that are compressed are not merged. The user should refer to the HDF Reference Manual for a fuller explanation of compression schemes and parameters. Syntax Result = EOS_GD_DEFCOMP(gridID, compcode [, compparm] ) Return Value Returns SUCCEED(0) if successful and FAIL(­1) otherwise. Arguments gridID Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH. compcode HDF compression code (long). compparm Compression parameters array. Allowable values are: * 0 = None * 1 = Run Length Encoding (RLE) * 3 = Skipping Huffman * 4 = Deflate (gzip) Example Suppose we wish to compress the Pressure field using run length encoding, the Opacity field using deflate compression, the Spectra field with skipping Huffman compression, and use no compression for the Temperature field: status = EOS_GD_DEFCOMP(gridID, 1) status = EOS_GD_DEFFIELD(gridID, "Pressure", "YDim,XDim", 5) compparm[0] = 5 status = EOS_GD_DEFCOMP(gridID, 4, compparm) status = EOS_GD_DEFFIELD(gridID, "Opacity", "YDim,XDim", 5) status = EOS_GD_DEFCOMP(gridID, 3) status = EOS_GD_DEFFIELD(gridID, "Spectra", "Bands,YDim,XDim", 5) status = EOS_GD_DEFCOMP(gridID, 0) status = EOS_GD_DEFFIELD(gridID, "Temperature", "YDim,XDim", 5,$ /MERGE) Note that the MERGE keyword will be ignored in the Temperature field definition. EOS_GD_DEFDIM [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_DEFDIM This function defines dimensions that are used by the field definition routines (described subsequently) to establish the size of the field. Syntax Result = EOS_GD_DEFDIM(gridID, dimname, dim) Return Value Returns SUCCEED(0) if successful and FAIL(­1) otherwise. Arguments gridID Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH. dimname Name of dimension to be defined (string). dim The size of the dimension (long). Example In this example, we define a dimension, Band, with size 15:. status = EOS_GD_DEFDIM(gridID, "Band", 15) To specify an unlimited dimension that can be used to define an appendable array, the dimension value should be set to zero: status = EOS_GD_DEFDIM(gridID, "Unlim", 0) EOS_GD_DEFFIELD [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_DEFFIELD This function defines data fields to be stored in the grid. The dimensions are entered as a string consisting of geolocation dimensions separated by commas. The API will attempt to merge into a single object those fields that share dimensions and in case of multidimensional fields, numbertype. If the MERGE keyword is not set, the API will not attempt to merge it with other fields. Fields using the unlimited dimension will not be merged. Because merging breaks the one-to-one correspondence between HDF-EOS fields and HDF SDS arrays, it should not be set if the user wishes to access the HDF-EOS fields directly using HDF. Syntax Result = EOS_GD_DEFFIELD(gridID, fieldname, dimlist, numbertype [, /MERGE]) Return Value Returns SUCCEED(0) if successful and FAIL(­1) otherwise. Arguments gridID Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH. fieldname Name of field (string) to be defined. dimlist The list of data dimensions (string) defining the field. numbertype The HDF data type (long) of the data stored in the field Keywords MERGE If set, automerge will occur. Example In this example, we define a grid field, Temperature with dimensions XDim and YDim (as established by the EOS_GD_CREATE routine) containing 4-byte floating point numbers and a field, Spectra, with dimensions XDim, YDim, and Bands: status = EOS_GD_DEFFIELD(gridID, "Temperature", & "YDim,XDim", 5, /MERGE) status = EOS_GD_DEFFIELD(gridID, "Spectra", "Bands,YDim,XDim", 5) EOS_GD_DEFORIGIN [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_DEFORIGIN This function defines the origin of the grid data. This allows the user to select any corner of the grid as the origin. Syntax Result = EOS_GD_DEFORIGIN(gridID, origincode) Return Value Returns SUCCEED(0) if successful and FAIL(­1) otherwise Arguments gridID Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH. origincode Location of the origin (long) of the grid data. The allowable values are: * 0 = Upper left * 1 = Upper right * 2 = Lower left * 3 = Lower right Example In this Example we define the origin of the grid to be the Lower Right corner: status = EOS_GD_DEFORIGIN(gridID, 3) EOS_GD_DEFPIXREG [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_DEFPIXREG This function defines whether the pixel center or pixel corner (as defined by the EOS_GD_DEFORIGIN function) is used when requesting the location (longitude and latitude) of a given pixel. Syntax Result = EOS_GD_DEFPIXREG(gridID, pixreg) Return Value Returns SUCCEED(0) if successful and FAIL(­1) otherwise. Arguments gridID Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH. pixreg Pixel registration (long). The allowable values are: * 0 = Center * 1 = Corner Example In this example, we define the pixel registration to be the corner of the pixel cell: status = EOS_GD_DEFPIXREG(gridID, 1) EOS_GD_DEFPROJ [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_DEFPROJ This function defines the GCTP projection and projection parameters of the grid. For GCTP projection information, see the HDF-EOS User's Guide, Volume 2: Reference Guide provided by NASA. Syntax Result = EOS_GD_DEFPROJ(gridID, projcode, zonecode, spherecode, projparm) Return Value Returns SUCCEED(0) if successful and FAIL(­1) otherwise Arguments gridID Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH. projcode GCTP projection code (long). zonecode GCTP zone code used by UTM projection (long). spherecode GCTP spheroid code (long). projparm GCTP projection parameter array. Example Example 1 In this example, we define a Universal Transverse Mercator (UTM) grid bounded by 54 E - 60 E longitude and 20 N - 30 N latitude - UTM zonecode 40, using default spheroid (Clarke 1866), spherecode = 0: spherecode = 0 zonecode = 40 status = EOS_GD_DEFPROJ(gridID, 1, zonecode, spherecode, 0) Example 2 In this example, we define a Polar Stereographic projection of the Northern Hemisphere (True scale at 90 N, 0 Longitude below pole) using the International 1967 spheroid: spherecode = 3 projparm = lonarr (13) ;Set Long below pole & true scale in DDDMMMSSS.SSS form projparm[5] = 90000000.00 status = EOS_GD_DEFPROJ(gridID, 6, 0, spherecode, projparm) Example 3 Finally, we define a Geographic projection. In this case, neither the zone code, sphere code, or the projection parameters are used: status = EOS_GD_DEFPROJ(gridID, 0, 0, 0, 0) EOS_GD_DEFTILE [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_DEFTILE This function defines the tiling dimensions for fields defined following this function call, analogous to the procedure for setting the field compression scheme using EOS_GD_DEFCOMP. The number of tile dimensions and subsequent field dimensions must be the same and the tile dimensions must be integral divisors of the corresponding field dimensions. A tile dimension set to 0 will be equivalent to 1. Syntax Result = EOS_GD_DEFTILE( gridID, tilecode [, tilerank, tiledims] ) Return Value Returns SUCCEED(0) if successful and FAIL(­1) otherwise Arguments gridID Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH. tilecode Tile code (long): 0 = notile, 1 = tile tilerank The number of tile dimensions (long) (optional). tiledims Tile dimensions (long) (optional). Example We will define four fields in a grid, two 2-D fields of the same size with the same tiling, a three-dimensional field with a different tiling scheme, and a fourth with no tiling. We assume that XDim is 200 and YDim is 300. tiledims[0] = 100 tiledims[1] = 200 status = EOS_GD_DEFTILE(gridID, 1, 2, tiledims) status = EOS_GD_DEFFIELD(gridID, "Pressure", "YDim,XDim", 22) status = EOS_GD_DEFFIELD(gridID, "Temperature", "YDim,XDim", 5) tiledims[0] = 1 tiledims[1] = 150 tiledims[2] = 100 status = EOS_GD_DEFTILE(gridID, 1, 3, tiledims) status = EOS_GD_DEFFIELD(gridID, "Spectra", "Bands,YDim,XDim", 5) status = EOS_GD_DEFTILE(gridID, 0, 0) status = EOS_GD_DEFFIELD(gridID, "Communities", "YDim,XDim", 24, /MERGE) EOS_GD_DEFTIMEPERIOD [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_DEFTIMEPERIOD This function defines a time period for a grid. It returns a grid period ID that is used by the EOS_GD_EXTRACTPERIOD routine to read all the entries of a data field within the time period. The grid structure must have the Time field defined. This routine may be called after EOS_GD_DEFBOXREGION to provide both geographic and time subsetting. In this case, the user provides the id from the previous subset call. (This same id is then returned by the function.) Furthermore, it can be called before or after EOS_GD_DEFVRTREGION to further refine a region. This routine may also be called "stand-alone" by setting the input period id to (­1). Syntax Result = EOS_GD_DEFTIMEPERIOD(gridID, periodID, starttime, stoptime) Return Value Returns the grid period ID if successful and FAIL (­1) otherwise. Arguments gridID Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH. periodID Period or region id (long) from previous subset call or ­1 to define a new region. starttime Start time of period (double). stoptime Stop time of period (double). Example In this example, we define a time period with a start time of 35232487.2 and a stop time of 36609898.1. starttime = 35232487.2d stoptime = 36609898.1d periodID = EOS_GD_DEFTIMEPERIOD(gridID, -1, starttime, stoptime) If we had previously performed a geographic subset with id, regionID, then we could further time subset this region with the call: periodID = EOS_GD_DEFTIMEPERIOD(gridID, regionID, starttime, $ stoptime) Note that periodID will have the same value as regionID. EOS_GD_DEFVRTREGION [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_DEFVRTREGION This function subsets on a monotonic field or contiguous elements of a dimension. Whereas the EOS_GD_DEFBOXREGION function subsets along the XDim and YDim dimensions, this function allows the user to subset along any other dimension. The region is specified by a set of minimum and maximum values and can represent either a dimension index (case 1) or field value range (case 2). In the second case, the field must be one-dimensional and the values must be monotonic (strictly increasing or decreasing) in order that the resulting dimension index range be contiguous. (For the current version of this routine, the second option is restricted to fields with number type: 22, 24, 5, 6) This function may be called after EOS_GD_DEFBOXREGION to provide both geographic and "vertical" subsetting. In this case the user provides the id from the previous subset call. (This same id is then returned by the function.) This routine may also be called "stand-alone" by setting the input id to (­1). This function may be called up to eight times with the same region ID. It this way a region can be subsetted along a number of dimensions. The EOS_GD_REGIONINFO and EOS_GD_EXTRACTREGION functions work as before, however the field to be subsetted, (the field specified in the call to EOS_GD_REGIONINFO and EOS_GD_EXTRACTREGION) must contain the dimension used explicitly in the call to EOS_GD_DEFVRTREGION (case 1) or the dimension of the one-dimensional field (case 2). Syntax Result = EOS_GD_DEFVRTREGION(gridID, regionID, vertObj, range) Return Value Returns the grid region ID if successful and FAIL (­1) otherwise. Arguments gridID Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH. regionID Region or period id (long) from previous subset call or ­1 to start a new region. vertObj Dimension or field to subset (string). range Minimum and maximum range for subset (double) 2 element array. Example Suppose we have a field called Pressure of dimension Height whose values increase from 100 to1000. If we desire all the elements with values between 500 and 800, we make the call: range[0] = 500.d range[1] = 800.d regionID = EOS_GD_DEFVRTREGION(gridID, -1, "Pressure", range) The routine determines the elements in the Height dimension which correspond to the values of the Pressure field between 500 and 800. If we wish to specify the subset as elements 2 through 5 (0 - based) of the Height dimension, the call would be: range[0] = 2.d range[1] = 5.d regionID = EOS_GD_DEFVRTREGION(gridID, -1, "DIM:Height", range) The "DIM:" prefix tells the routine that the range corresponds to elements of a dimension rather than values of a field. If a previous subset region or period was defined with id, subsetID, that we wish to refine further with the vertical subsetting defined above we make the call: regionID = EOS_GD_DEFVRTREGION(gridID, subsetID, "Pressure", $ range) The return value, regionID, is set equal to subsetID. That is, the subset region is modified rather than a new one created. In this example, any field to be subsetted must contain the Height dimension. EOS_GD_DETACH [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_DETACH This function detaches from the grid interface. This routine should be run before exiting from the grid file for every grid opened by EOS_GD_CREATE or EOS_GD_ATTACH. Syntax Result = EOS_GD_DETACH(gridID) Return Value Returns SUCCEED(0) if successful and FAIL(­1) otherwise. Arguments gridID Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH. Example In this example, we detach a grid structure: status = EOS_GD_DETACH(gridID) EOS_GD_DIMINFO [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_DIMINFO This function retrieves the size of the specified dimension. Syntax Result = EOS_GD_DIMINFO(gridID, dimname) Return Value Size of dimension. If FAIL(­1), could signify an improper grid id or dimension name. Arguments gridID Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH. dimname Dimension name (string) Example In this example, we retrieve information about the dimension, "Bands": dimsize = EOS_GD_DIMINFO(gridID, "Bands") EOS_GD_DUPREGION [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_DUPREGION This function copies the information stored in a current region or period to a new region or period and generates a new id. It is useful when the user wishes to further subset a region (period) in multiple ways. Syntax Result = EOS_GD_DUPREGION(regionID) Return Value Returns new region or period ID or FAIL (­1) if the region cannot be duplicated. Arguments regionID Region or period id (long) returned by EOS_GD_DEFBOXREGION, EOS_GD_DEFTIMEPERIOD, or EOS_GD_DEFVRTREGION. Example In this example, we first subset a grid with EOS_GD_DEFBOXREGION, duplicate the region creating a new region ID, regionID2, and then perform two different vertical subsets of these (identical) geographic subset regions: regionID = EOS_GD_DEFBOXREGION(gridID, cornerlon, cornerlat) regionID2 = EOS_GD_DUPREGION(regionID) regionID = EOS_GD_DEFVRTREGION(gridID, regionID, "Pressure",$ rangePres) regionID2 = EOS_GD_DEFVRTREGION(gridID, regionID2, $ "Temperature", rangeTemp) EOS_GD_EXTRACTREGION [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_EXTRACTREGION This function reads data into the data buffer from a subsetted region as defined by EOS_GD_DEFBOXREGION. Syntax Result = EOS_GD_EXTRACTREGION(gridID, regionID, fieldname, buffer) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments gridID Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH. regionID Region or period id (long) returned by EOS_GD_DEFBOXREGION (EOS_GD_DEFTIMEPERIOD). fieldname Field to subset (string). buffer A named variable that will contain the data Buffer. Example In this example, we extract data from the "Temperature" field from the region defined in EOS_GD_DEFBOXREGION. The size of the subsetted region for the field is given by the EOS_GD_REGIONINFO routine. status = EOS_GD_EXTRACTREGION(EOS_GD_id, regionID, $ "Temperature", datbuf32) EOS_GD_FIELDINFO [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_FIELDINFO This function retrieves information on a specific data field. Syntax Result = EOS_GD_FIELDINFO(gridID, fieldname, rank, dims, numbertype, dimlist) Return Value Returns SUCCEED(0) if successful and FAIL(­1) if the specified field does not exist. Arguments gridID Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH. fieldname Fieldname (string). rank A named variable that will contain the pointer to rank (long) of the field. dims A named variable that will contain an array (long) of the dimension sizes of the field. numbertype A named variable that will contain the HDF data type (long) of the field. dimlist A named variable that will contain the dimension list (string). Example In this example, we retrieve information about the Spectra data fields: status = EOS_GD_FIELDINFO(gridID, "Spectra", rank, dims,$ numbertype, dimlist) EOS_GD_GETFILLVALUE [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_GETFILLVALUE This function retrieves the fill value for the specified field. Syntax Result = EOS_GD_GETFILLVALUE(gridID, fieldname, fillvalue) Return Value Returns SUCCEED(0) if successful and FAIL(­1) otherwise. Arguments gridID Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH. fieldname Fieldname (string). fillvalue A named variable that will contain the fill value. Example In this example, we get the fill value for the "Temperature" field: status = EOS_GD_GETFILLVALUE(gridID, "Temperature", tempfill) EOS_GD_GETPIXELS [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_GETPIXELS This function returns the pixel rows and columns for specified longitude/latitude pairs. This function converts longitude/latitude pairs into (0-based) pixel rows and columns. The origin is the upper left-hand corner of the grid. This routine is the pixel subsetting equivalent of EOS_GD_DEFBOXREGION. Syntax Result = EOS_GD_GETPIXELS(gridID, nLonLat, lonVal, latVal, pixRow, pixCol) Return Value Returns SUCCEED(0) if successful and FAIL(­1) otherwise. Arguments gridID Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH. nLonLat Number of longitude/latitude pairs (long). lonVal Longitude values in degrees (double, 1D array). latVal Latitude values in degrees (double, 1D array). pixRow A named variable that will contain the pixel Rows (long array). pixCol A named variable that will contain the pixel Columns (long array). Example This example converts two pairs of longitude/latitude values to rows and columns. The rows and columns of the two pairs will be returned in the rowArr and colArr arrays: lonArr[0] = 134.2d latArr[0] = -20.8d lonArr[1] = 15.8d latArr[1] = 84.6d status = EOS_GD_GETPIXELS(gridID, 2, lonArr, latArr, rowArr, $ colArr) EOS_GD_GETPIXVALUES [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_GETPIXVALUES This function reads data from a data field for the specified pixels. It is the pixel subsetting equivalent of EOS_GD_EXTRACTREGION. All entries along the non- geographic dimensions (i.e., NOT XDim and YDim) are returned. Syntax Result = EOS_GD_GETPIXVALUES(gridID, nPixels, pixRow, pixCol, fieldname, buffer) Return Value Returns size of data buffer if successful and FAIL(­1) otherwise. Arguments gridID Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH nPixels Number of pixels (long). pixRow Pixel Rows (long array). pixCol Pixel Columns (long array). fieldname Field (string) from which to extract data values. buffer A named variable that will contain data values. Example To read values from the Spectra field with dimensions, Bands, YDim, and XDim: bufsiz = EOS_GD_GETPIXVALUES(gridID, 2, rowArr, colArr, $ "Spectra", buffer) EOS_GD_GRIDINFO [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_GRIDINFO This function returns the number of rows, columns and the location, in meters, of the upper left and lower right corners of the grid image. Syntax Result = EOS_GD_GRIDINFO(gridID, xdimsize, ydimsize, upleft, lowright) Return Value Returns SUCCEED(0) if successful and FAIL(­1) otherwise. Arguments gridID Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH. xdimsize A named variable that will contain the number of columns in grid (long). ydimsize A named variable that will contain the number of rows in grid (long). upleft A named variable that will contain the location (double, 2 element array; in meters) of upper left corner. lowright A named variable that will contain the location (double, 2 element array; in meters) of lower right corner. Example In this example, we retrieve information from a previously created grid with a call to EOS_GD_ATTACH: status = EOS_GD_GRIDINFO(gridID, xdimsize, ydimsize, $ upleft, lowrgt) EOS_GD_INQATTRS [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_INQATTRS This function retrieves information about attributes defined in a grid. The attribute list is returned as a string with each attribute name separated by commas. Note See STRSPLIT to separate the attribute list. Syntax Result = EOS_GD_INQATTRS( gridID, attrlist [, LENGTH (OUT)=value] ) Return Value Number of attributes found or (­1) if failure. Arguments gridID Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH. attrlist A named variable that will contain the attribute list (string) with entries separated by commas. Keywords LENGTH String length (long) of attribute list. Example In this example, we retrieve information about the attributes defined in a grid structure: nattr = EOS_GD_INQATTRS(gridID, attrlist) EOS_GD_INQDIMS [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_INQDIMS This function retrieves information about dimensions defined in a grid. The dimension list is returned as a string with each dimension name separated by commas. Note See STRSPLIT to separate the dimension list. Syntax Result = EOS_GD_INQDIMS(gridID, dimname, dims) Return Value Number of dimension entries found. If FAIL(­1), could signify an improper grid id. Arguments gridID Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH. dimname A named variable that will contain the dimension list (string) with entries separated by commas. dims A named variable that will contain an array (long) of the size of each dimension. Example To retrieve information about the dimensions, use the following statement: ndim = EOS_GD_INQDIMS(gridID, dimname, dims) EOS_GD_INQFIELDS [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_INQFIELDS This function retrieves information about the data fields defined in grid. The field list is returned as a string with each data field separated by commas. The rank and numbertype arrays will have an entry for each field. Note See STRSPLIT to separate the field list. Syntax Result = EOS_GD_INQFIELDS(gridID, fieldlist, rank, numbertype) Return Value Number of data fields found. If FAIL(­1), could signify an improper grid id. Arguments gridID Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH. fieldlist A named variable that will contain the listing of data fields (string) with entries separated by commas. rank A named variable that will contain the array (long) containing the rank of each data field. numbertype A named variable that will contain the array (long) containing the numbertype of each data field. Example To retrieve information about the data fields, use the following statement: nfld = EOS_GD_INQFIELDS(gridID, fieldlist, rank, numbertype) EOS_GD_INQGRID [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_INQGRID This function retrieves number and names of grids defined in HDF-EOS file. The grid list is returned as a string with each grid name separated by commas. Note See STRSPLIT to separate the grid list. Syntax Result = EOS_GD_INQGRID( filename, gridlist [, LENGTH (OUT)=value] ) Return Value Number of grids found or (­1) if failure. Arguments filename HDF-EOS filename (string). gridlist A named variable that will contain the grid list (string) with entries separated by commas. Keywords LENGTH String length of grid list (long). Example In this example, we retrieve information about the grids defined in an HDF-EOS file, HDFEOS.hdf: ngrid = EOS_GD_INQGRID("HDFEOS.hdf", gridlist) EOS_GD_INTERPOLATE [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_INTERPOLATE This function performs bilinear interpolation on a grid field. It assumes that the pixel data values are uniformly spaced which is strictly true only for an infinitesimally small region of the globe but is a good approximation for a sufficiently small region. The default position of the pixel value is pixel center, however if the pixel registration has been set to 1 (with the EOS_GD_DEFPIXREG function) then the value is located at one of the four corners specified by the EOS_GD_DEFORIGIN routine. All entries along the non-geographic dimensions (i.e., NOT XDim and YDim) are interpolated and all interpolated values are returned as FLOAT64. The reference for the interpolation algorithm is Numerical Recipes in C (2nd ed). (Note for the current version of this routine, the number type of the field to be interpolated is restricted to 22, 24, 5, 6.) Syntax Result = EOS_GD_INTERPOLATE(gridID, Interp, lonVal, latVal, fieldname, interpVal) Return Value Returns size in bytes of interpolated data values if successful and FAIL(­1) otherwise. Arguments gridID Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH nInterp Number of interpolation points (long). lonVal Longitude of interpolation points (double array). latVal Latitude of interpolation points (double array). fieldname The field (string) from which to interpolate data values. interpVal A named variable that will contain the (double) interpolated data values. Example To interpolate the Spectra field at two geographic data points: lonVal[0] = 134.2d latVal[0] = -20.8d lonVal[1] = 15.8d latVal[1] = 84.6d bufsiz = EOS_GD_INTERPOLATE(gridID, 2, lonVal, latVal, $ "Spectra", interpVal) EOS_GD_NENTRIES [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_NENTRIES This function returns the number of entries and descriptive string buffer size for a specified entity. Syntax Result = EOS_GD_NENTRIES( gridID, entrycode [, LENGTH (OUT)=value] ) Return Value Number of entries or FAIL(­1) which could signify an improper grid id or entry code. Arguments gridID Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH. entrycode Entrycode (long). Allowable values are: * 0 = Dimensions * 4 = Datafields Keywords LENGTH String buffer size (long). This is the length of the string returned by the corresponding inquiry routine. Example In this example, we determine the number of data field entries: ndims = EOS_GD_NENTRIES(gridID, 4) EOS_GD_OPEN [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_OPEN This function creates a new file or opens an existing one. Syntax Result = EOS_GD_OPEN( filename, access [, /CREATE] [, /RDWR | , /READ] ) Return Value Returns the grid file id handle (fid) if successful and FAIL(­1) otherwise. Arguments filename Complete path and filename (string) for the file to be opened. Keywords CREATE If file exists, delete it, then open a new file for read/write. RDWR Open for read/write. If file does not exist, create it. READ Open for read only. If file does not exist, error. This is the default. Example In this example, we create a new grid file named, GridFile.hdf. It returns the file handle, fid. fid = EOS_GD_OPEN("GridFile.hdf", /CREATE) See Also EOS_GD_CLOSE EOS_GD_ORIGININFO [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_ORIGININFO This function retrieves the origin code. Syntax Result = EOS_GD_ORIGININFO(gridID, origincode) Return Value Returns 0 if successful, and ­1 otherwise. A return value of ­1 could signify an improper grid id or entry code. Arguments gridID Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH. origincode A named variable that will contain the origin code (long). See EOS_GD_DEFORIGIN for a list of origin codes and their meanings. EOS_GD_PIXREGINFO [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_PIXREGINFO This function retrieves the pixel registration code. Syntax Result = EOS_GD_PIXREGINFO(gridID, pixregcode) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments gridID Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH. pixregcode A named variable that will contain the pixel registration code (long). EOS_GD_PROJINFO [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_PROJINFO This function retrieves the GCTP projection code, zone code, spheroid code and the projection parameters of the grid. For GCTP projection information, see the HDF- EOS User's Guide, Volume 2: Reference Guide provided by NASA. Syntax Result = EOS_GD_PROJINFO(gridID, projcode, zonecode, spherecode, projparm) Return Value Returns SUCCEED(0) if successful and FAIL(­1) otherwise Arguments gridID Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH. projcode A named variable that will contain the GCTP projection code (long). zonecode A named variable that will contain the GCTP zone code used by UTM projection (long). spherecode A named variable that will contain the GCTP spheroid code (long). projparm A named variable that will contain the GCTP projection parameter array (double). EOS_GD_QUERY [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_QUERY The EOS_GD_QUERY function returns information about a specified grid. Syntax Result = EOS_GD_QUERY( Filename, GridName, [Info]) Return Value This function returns an integer value of 1 if the file is an HDF file with EOS GRID extensions, and 0 otherwise. Arguments Filename A string containing the name of the file to query. GridName A string containing the name of the grid to query. Info Returns an anonymous structure containing information about the specified grid. The returned structure contains the following fields: Field IDL Data Type Description ATTRIBUTES String array Array of attribute names DIMENSION_NAMES String array Names of dimensions DIMENSION_SIZES Long array Sizes of dimensions FIELD_NAMES String array Names of fields FIELD_RANKS Long array Ranks (dimensions) of fields FIELD_TYPES Long array IDL types of fields GCTP_PROJECTION Long GCTP projection code Table 4-1: Fields of the Info Structure Field IDL Data Type Description GCTP_PROJECTION_PAR Double array GCTP projection parameters M GCTP_SPHEROID Long GCTP spheroid code GCTP_ZONE Long GCTP zone code (for UTM projection) IMAGE_LOWRIGHT Double[2] Location of lower right corner (meters) IMAGE_UPLEFT Double[2] Location of upper left corner (meters) IMAGE_X_DIM Long Number of columns in grid image IMAGE_Y_DIM Long Number of rows in grid image NUM_ATTRIBUTES Long Number of attributes NUM_DIMS Long Number of dimensions NUM_IDX_MAPS Long Number of indexed dimension mapping entries NUM_MAPS Long Number of dimension mapping entries NUM_FIELDS Long Number of fields NUM_GEO_FIELDS Long Number of geolocation field entries ORIGIN_CODE Long Origin code PIX_REG_CODE Long Pixel registration code Table 4-1: Fields of the Info Structure EOS_GD_READATTR [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_READATTR This function reads attributes from the grid. Syntax Result = EOS_GD_READATTR(gridID, attrname, datbuf) Return Value Returns SUCCEED(0) if successful and FAIL(­1) otherwise. Arguments gridID Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH. attrname Attribute name (string). datbuf A named variable that will contain the attribute values. Example In this example, we read a single precision (32 bit) floating point attribute with the name "ScalarFloat": status = EOS_GD_READATTR(gridID, "ScalarFloat", f32) EOS_GD_READFIELD [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_READFIELD This function reads data from the grid field. The values within start, stride, and edge arrays refer to the grid field (input) dimensions. The default values for start and stride are 0 and 1 respectively. The default value for edge is (dim - start) / stride where dim refers to the size of the dimension. Syntax Result = EOS_GD_READFIELD( gridID, fieldname, buffer [, EDGE=array] [, START=array] [, STRIDE=array] ) Return Value Returns SUCCEED(0) if successful and FAIL(­1) otherwise. Arguments gridID Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH. fieldname Name of field (string) to read. buffer A named variable that will contain the data read from the field. Keywords EDGE Array (long) specifying the number of values to read along each dimension. START Array (long) specifying the starting location within each dimension. STRIDE Array (long) specifying the number of values to skip along each dimension. Example In this example, we read data from the 10th row (0-based) of the Temperature field: start=[10,1] edge=[1,120] status = EOS_GD_READFIELD(gridID, "Temperature", row, $ START = start, EDGE = edge) EOS_GD_READTILE [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_READTILE This function reads a single tile of data from a field. If the data is to be read tile by tile, this routine is more efficient than EOS_GD_READFIELD. In all other cases, the later routine should be used. EOS_GD_READTILE does not work on non-tiled fields. Note that the coordinates are in terms of tiles, not data elements. Syntax Result = EOS_GD_READTILE(gridID, fieldname, tilecoords, buffer) Return Value Returns SUCCEED(0) if successful and FAIL(­1) otherwise. Arguments gridID Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH. fieldname Fieldname (string). tilecoords Array (long) of tile coordinates. buffer A named variable that will contain the tile. Example In this example. we read one tile from the Temperature field (see EOS_GD_DEFTILE example) located at the second column of the first row of tiles: tilecoords[0] = 0 tilecoords[1] = 1 status = EOS_GD_READTILE(gridid, "Temperature",$ tilecoords,buffer) EOS_GD_REGIONINFO [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_REGIONINFO This function returns information about a subsetted region for a particular field. Because of differences in number type and geolocation mapping, a given region will give different values for the dimensions and size for various fields. The upleftpt and lowrightpt arrays can be used when creating a new grid from the subsetted region. Syntax Result = EOS_GD_REGIONINFO(gridID, regionID, fieldname, ntype, rank, dims, size, upleftpt, lowrightpt) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments gridID Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH. regionID Region or period id (long) returned by EOS_GD_DEFBOXREGION or EOS_GD_DEFTIMEPERIOD. fieldname Field to subset (string). ntype A named variable that will contain the HDF data type of field (long). rank A named variable that will contain the rank of field (long). dims A named variable that will contain the dimensions of subset region (long). size A named variable that will contain the size in bytes of subset region (long). upleftpt A named variable that will contain the upper left point of subset region (double array). lowrightpt A named variable that will contain the lower right point of subset region (double array). Example In this example, we retrieve information about the region defined in EOS_GD_DEFBOXREGION for the "Temperature" field: status = EOS_GD_REGIONINFO(EOS_GD_id, regionID, $ "Temperature", ntype,$ rank, dims, size, upleft,$ lowright) EOS_GD_SETFILLVALUE [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_SETFILLVALUE This function sets the fill value for the specified field. The fill value is placed in all elements of the field which have not been explicitly defined. Syntax Result = EOS_GD_SETFILLVALUE(gridID, fieldname, fillvalue) Return Value Returns SUCCEED(0) if successful and FAIL(­1) otherwise. Arguments gridID Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH. fieldname Fieldname (string). fillvalue The fill value to be used. Example In this example, we set a fill value for the "Temperature" field: tempfill = -999.0 status = EOS_GD_SETFILLVALUE(gridID, "Temperature", tempfill) EOS_GD_SETTILECACHE [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_SETTILECACHE This function sets tile cache parameters. Syntax Result = EOS_GD_SETTILECACHE(gridID, fieldname, maxcache, cachecode) Return Value Returns SUCCEED(0) if successful and FAIL(­1) otherwise Arguments gridID Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH. fieldname Fieldname (string). maxcache Maximum number of tiles (long) to cache in memory. cachecode Currently must be set to 0 (long). Example In this example, we set maxcache to 10 tiles. The particular subsetting envisioned for the Spectra field (defined in the EOS_GD_DEFTILE example) would never cross more than 10 tiles along the field's fastest varying dimension, i.e., XDim. status = EOS_GD_SETTILECACHE(gridID, "Spectra", 10, 0) EOS_GD_TILEINFO [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_TILEINFO This function returns the tiling code, tiling rank, and tiling dimensions for a given field. Syntax Result = EOS_GD_TILEINFO(gridID, fieldname, tilecode, tilerank, tiledims) Return Value Returns SUCCEED(0) if successful and FAIL(­1) otherwise. Arguments gridID Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH. fieldname Fieldname (string). tilecode A named variable that will contain the tile code (long): 0 No Tile, 1 Tile. tilerank A named variable that will contain the number of tile dimensions (long). tiledims A named variable that will contain the tile dimensions (long). Example To retrieve the tiling information about the Pressure field defined in the EOS_GD_DEFTILE section: status = EOS_GD_COMPINFO(gridID, "Pressure", tilecode, $ tilerank, tiledims) EOS_GD_WRITEATTR [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_WRITEATTR This function writes/updates attributes in the grid. If the attribute does not exist, it is created. If it does exist, then the value(s) is (are) updated. Syntax Result = EOS_GD_WRITEATTR( gridID, attrname, datbuf [, COUNT=value] [, HDF_TYPE=value] ) Return Value Returns SUCCEED(0) if successful and FAIL(­1) otherwise. Arguments gridID Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH. attrname Attribute name (string). datbuf Attribute values. If HDF_TYPE is specified, the IDL variable is first converted to the type specified by the keyword before being written. Keywords COUNT Number of values to store in attribute (long). HDF_TYPE HDF data type of attribute (long). Example In this example. we write a single precision (32 bit) floating point number with the name "ScalarFloat" and the value 3.14: f32 = 3.14 status = EOS_GD_WRITEATTR(gridid, "ScalarFloat", f32) We can update this value by simply calling the function again with the new value: f32 = 3.14159 status = EOS_GD_WRITEATTR(gridid, "ScalarFloat", f32) EOS_GD_WRITEFIELD [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_WRITEFIELD This function writes data to the grid field. The values within start, stride, and edge arrays refer to the grid field (output) dimensions. The input data in the data buffer is read from contiguously. The default values for start and stride are 0 and 1 respectively. The default value for edge is (dim - start) / stride where dim refers to the size of the dimension. Note that the data buffer for a compressed field must be the size of the entire field as incremental writes are not supported by the underlying HDF routines. Syntax Result = EOS_GD_WRITEFIELD( gridID, fieldname, data [, EDGE=array] [, START=array] [, STRIDE=array] ) Return Value Returns SUCCEED(0) if successful and FAIL(­1) otherwise Arguments gridID Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH. fieldname Name of field (string) to write. data Values (long) to be written to the field. Keywords EDGE Array (long) specifying the number of values to write along each dimension. START Array (long) specifying the starting location within each dimension (0-based). STRIDE Array (long) specifying the number of values to skip along each dimension. Example In this example, we write data to the Temperature field: ; Define elements of temperature array: temperature = indegen (200, 120) status = EOS_GD_WRITEFIELD(gridID, "Temperature", temperature) ; Update Row 10 (0-based) in this field: start=[0,10], edge=[2000,1] ; Define elements of newrow array: status = EOS_GD_WRITEFIELD(gridID, "Temperature", $ START=start, EDGE=edge, newrow) EOS_GD_WRITEFIELDMETA [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_WRITEFIELDMETA This function writes the field metadata for a grid field not defined by the Grid API. Syntax Result = EOS_GD_WRITEFIELDMETA(gridID, fieldname, dimlist, numbertype) Return Value Returns SUCCEED(0) if successful and FAIL(­1) otherwise Arguments gridID Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH. fieldname Name of field (string) that metadata information is to be written. dimlist Dimension list of field (long). numbertype Number type of data in field (long). Example status = EOS_GD_writefieldmeta(gridID, "ExternField", $ "Ydim,Xdim", 5) EOS_GD_WRITETILE [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_GD_WRITETILE This function writes a single tile of data to a field. If the data to be written to a field can be arranged tile by tile, this routine is more efficient than EOS_GD_WRITEFIELD. In all other cases, the EOS_GD_WRITEFIELD routine should be used. EOS_GD_WRITETILE does not work on non-tiled fields. Note that the are coordinates in terms of tiles, not data elements. Syntax Result = EOS_GD_WRITETILE(gridID, fieldname, tilecoords, data) Return Value Returns SUCCEED(0) if successful and FAIL(­1) otherwise. Arguments gridID Grid id (long) returned by EOS_GD_CREATE or EOS_GD_ATTACH. fieldname Fieldname (string). tilecoords Array of tile coordinates (long). data Data to be written to tile. Example In this example, we write one tile to the Temperature field (see the EOS_GD_DEFTILE example) at the second column of the first row of tiles: tilecoords[0] = 0 tilecoords[1] = 1 status=EOS_GD_WRITETILE(gridID, "Temperature", tilecoords, data) EOS_PT_ATTACH [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_PT_ATTACH This function attaches to the point using the pointname parameter as the identifier. Syntax Result = EOS_PT_ATTACH(fid, pointname) Return Value Returns the point handle (pointID) if successful and FAIL (­1) otherwise.Typical reasons for failure are an improper point file id or point name. Arguments fid Point file id (long) returned by EOS_PT_OPEN. pointname Name of point (string) to be attached. Example In this example, we attach to the previously created point, "ExamplePoint", within the HDF file, PointFile.hdf, referred to by the handle, fid: pointID = EOS_PT_ATTACH(fid, "ExamplePoint") The point can then be referenced by subsequent routines using the handle, pointID. See Also EOS_PT_DETACH EOS_PT_ATTRINFO [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_PT_ATTRINFO This function returns number type and number of elements (count) of a point attribute. Syntax Result = EOS_PT_ATTRINFO( pointID, attrname, numbertype, count) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments pointID Point id (long) returned by EOS_PT_CREATE or EOS_PT_ATTACH. attrname Attribute name (string). numbertype A named variable that will contain the HDF type of the attribute value (long). count A named variable that will contain the number of total bytes in attribute (long). Example In this example, we return information about the ScalarFloat attribute: status = EOS_PT_ATTRINFO(pointID, "ScalarFloat", nt, count) EOS_PT_BCKLINKINFO [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_PT_BCKLINKINFO This function returns the linkfield to the previous level. Syntax Result = EOS_PT_BCKLINKINFO(pointID, level, linkfield) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments pointID Point id (long) returned by EOS_PT_CREATE or EOS_PT_ATTACH. level Point level (0-based long). linkfield A named variable that will contain the link field (string). Example In this example, we return the linkfield connecting the Observations level to the previous Desc-Loc level. (These levels are defined in the EOS_PT_DEFLEVEL routine.) status = EOS_PT_BCKLINKINFO(pointID2, 1, linkfield) EOS_PT_CLOSE [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_PT_CLOSE This function closes the HDF point file. Syntax Result = EOS_PT_CLOSE(fid) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments fid Point file id (long) returned by EOS_PT_OPEN. Example status = EOS_PT_CLOSE(fid) EOS_PT_CREATE [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_PT_CREATE This function creates a new point structure. The point is created as a Vgroup within the HDF file with the name pointname and class POINT. Syntax Result = EOS_PT_CREATE(fid, pointname) Return Value Returns the point handle (pointID) if successful and FAIL (­1) otherwise. Arguments fid Point file id (long) returned by EOS_PT_OPEN. pointname Name of point (string) to be created. Example In this example, we create a new point structure, ExamplePoint, in the previously created file, PointFile.hdf: pointID = EOS_PT_CREATE(fid, "ExamplePoint") The point structure is then referenced by subsequent routines using the handle, pointID. EOS_PT_DEFBOXREGION [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_PT_DEFBOXREGION This function defines an area of interest for a point. It returns a point region ID which is used by the EOS_PT_EXTRACTREGION routine to read the fields from a level for those records within the area of interest.The point structure must have a level with both a Longitude and Latitude (or Colatitude) field defined. Syntax Result = EOS_PT_DEFBOXREGION(pointID, cornerlon, cornerlat) Return Value Returns the point regionID if successful and FAIL (­1) otherwise. Arguments pointID Point id (long) returned by EOS_PT_CREATE or EOS_PT_ATTACH. cornerlon Longitude (double) in decimal degrees of box corners (2 element, 1-D array). cornerlat Latitude (double) in decimal degrees of box corners (2 element, 1-D array). Example In this example, we define an area of interest with (opposite) corners at ­145 degrees longitude, ­15 degrees latitude and ­135 degrees longitude, ­8 degrees latitude: cornerlon = dblarr (2) cornerlat = dblarr (2) cornerlon[0] = -145. cornerlat[0] = -15. cornerlon[1] = -135. cornerlat[1] = -8. regionID = EOS_PT_DEFBOXREGION(pointID, cornerlon, cornerlat) EOS_PT_DEFLEVEL [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_PT_DEFLEVEL This function defines a level within the point. A simple point consists of a single level. A point where there is common data for a number of records can be more efficiently stored with multiple levels. The order in which the levels are defined determines the (0-based) level index. Syntax Result = EOS_PT_DEFLEVEL(pointID, levelname, fieldlist, fieldtype, fieldorder) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments pointID Point id (long) returned by EOS_PT_CREATE or EOS_PT_ATTACH. levelname Name of level (string) to be defined. fieldlist List of fields (string) in level. fieldtype Array (long) containing HDF data type of each field within level. fieldorder Array (long) containing order of each field within level. Note An order of 0 is considered the same as an order of 1. Example Example 1 - Simple Point: In this example, we define a simple single level point, with levelname, Sensor. The levelname should not contain any slashes ("/"). It consists of six fields, ID, Time, Longitude, Latitude, Temperature, and Mode defined in the field list. The fieldtype and fieldorder parameters are arrays consisting of the HDF number type codes and field orders, respectively. The Temperature is an array field of dimension 4 and the Mode field a character string of size 4. All other fields are scalars. Note that the order for numerical scalar variables can be either 0 or 1. fieldtype = [22, 22, 5, 5, 5, 4] fieldorder = [0,0,0,0,4,4] fldlist = "ID,Time,Longitude,Latitude,Temperature,Mode" status = EOS_PT_DEFLEVEL(pointID, "Sensor", fldlist, fieldtype,$ fieldorder) Example 2 - Multi-Level Point: In this example, we define a two-level point that describes data from a network of fixed buoys. The first level contains information about each buoy and includes the name (label) of the buoy, its (fixed) longitude and latitude, its deployment date, and an ID that is used to link it to the following level. (The link field is defined in the EOS_PT_DEFLINKAGE routine described later.) The entries within the ID field must be unique. The second level contains the actual measurements from the buoys (rainfall and temperature values) plus the observation time and the ID which relates a given measurement to a particular buoy entry in the previous level. There can be many records in this level with the same ID since there can be multiple measurements from a single buoy. It is advantageous, although not mandatory, to store all records for a particular buoy (ID) contiguously. Level 0 fieldtype0 = [4, 6, 6, 5, 4] fieldorder0 = [8,0,0,0,1] fldlist0 = "Label,Longitude,Latitude,DeployDate,ID" status = EOS_PT_deflevel(pointID2, "Desc-Loc", $ fldlist0, fieldtype0, fieldorder0) Level 1 fieldtype1 = [6, 5, 5, 4] fieldorder1 = [0,0,0,1] fldlist1 = "Time,Rainfall,Temperature,ID" status = EOS_PT_DEFLEVEL(pointID2, "Observations", $ fldlist1, fieldtype1, fieldorder1) EOS_PT_DEFLINKAGE [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_PT_DEFLINKAGE This function defines the linkfield between two levels. This field must be defined in both levels. Syntax Result = EOS_PT_DEFLINKAGE(pointID, parent, child, linkfield) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments pointID Point id (long) returned by EOS_PT_CREATE or EOS_PT_ATTACH. parent Name (string) of parent level. child Name (string) of child level. linkfield Name (string) of common linkfield. Example In this example, we define the ID field as the link between the two levels defined previously in the EOS_PT_DEFLEVEL function: status = EOS_PT_DEFLINKAGE(pointID2, "Desc-Loc", $ "Observations", "ID") EOS_PT_DEFTIMEPERIOD [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_PT_DEFTIMEPERIOD This function defines a time period for a point. It returns a point period ID which is used by the EOS_PT_EXTRACTPERIOD function to read the fields from a level for those records within the time period. The point structure must have a level with the Time field defined. Syntax Result = EOS_PT_DEFTIMEPERIOD(pointID, starttime, stoptime) Return Value Returns the point periodID if successful and FAIL (­1) otherwise. Arguments pointID Point id (long) returned by EOS_PT_CREATE or EOS_PT_ATTACH. starttime Start time (double) of period. stoptime Stop time (double) of period. Example In this example, we define a time period with a start time of 35208757.6 and a stop time of 35984639.2: starttime = 35208757.6d stoptime = 35984639.2d periodID = EOS_PT_DEFTIMEPERIOD(pointID, starttime, stoptime) EOS_PT_DEFVRTREGION [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_PT_DEFVRTREGION This function allows the user to select those records within a point whose field values are within a given range. (For the current version of this routine, the field must have one of the following HDF data types: 22, 24, 5, 6) This function may be called after EOS_PT_DEFBOXREGION or EOS_PT_DEFTIMEPERIOD to provide both geographic or time and vertical subsetting. In this case the user provides the id from the previous subset call. (This same id is then returned by the function.) This routine may also be called stand-alone by setting the input id to (­1). This function may be called up to eight times with the same region ID. In this way a region can be subsetted along a number of dimensions. The EOS_PT_REGIONINFO and EOS_PT_EXTRACTREGION functions work as before, however, because there is no mapping performed between geolocation dimensions and data dimensions for the field to be subsetted, (the field specified in the call to EOS_PT_REGIONINFO and EOS_PT_EXTRACTREGION) must contain the dimension used explicitly in the call to EOS_PT_DEFVRTREGION (case 1) or the dimension of the one-dimensional field (case 2). Syntax Result = EOS_PT_DEFVRTREGION( pointID, regionID, vertObj, range) Return Value Returns the point region ID if successful and FAIL (­1) otherwise. Arguments pointID Point id (long) returned by EOS_PT_CREATE or EOS_PT_ATTACH. regionID Region or period id (long) returned from a previous subset call. vertObj String name of a dimension or field by which to subset. range Minimum and maximum range for the subset (double, 2 element, 1-D array). Example Suppose we wish to find those records within a point whose Rainfall values fall between 1 and 2. We wish to search all the records within the point, so we set the input region ID to (­1): range = [1.,2.] regionID = EOS_PT_DEFVRTREGION(pointID, -1, "Rainfall", range) ; Now we subset further using the Temperature field: range = [22.,24.] regionID = EOS_PT_DEFVRTREGION(pointID, regionID, $ "Temperature", range) The subsetted region referred to by regionID will now contain those records whose Rainfall field are between 1 and 2 and whose Temperature field are between 22 and 24. EOS_PT_DETACH [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_PT_DETACH This function detaches from a point data set. This function should be run before exiting from the point file for every point opened by EOS_PT_CREATE or EOS_PT_ATTACH. Syntax Result = EOS_PT_DETACH(pointID) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments pointID Point id (long) returned by EOS_PT_CREATE or EOS_PT_ATTACH Example status = EOS_PT_DETACH(pointID) EOS_PT_EXTRACTPERIOD [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_PT_EXTRACTPERIOD This function reads data from the designated level fields into the data buffer from the subsetted time period. Syntax Result = EOS_PT_EXTRACTPERIOD(pointID, periodID, level, fieldlist, buffer) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments pointID Point id (long). periodID Period id (long) returned by EOS_PT_DEFTIMEPERIOD. level Point level (0-based long). fieldlist List of fields (string) to extract. buffer A named variable that will contain the data buffer. This buffer is in packed format. Use HDF_UNPACKDATA to convert it into variables. Example In this example, we read data within the subsetted time period defined by EOS_PT_DEFTIMEPERIOD from the Time field: periodID = EOS_PT_DEFTIMEPERIOD(pointID, 35208757.6d, $ 35984639.2d) IF (periodID NE -1) THEN BEGIN status = EOS_PT_EXTRACTPERIOD(pointID, periodID, 1, $ "Time", buffer) HDF_UNPACKDATA, buffer, dataTime, HDF_TYPE=[6] ENDIF EOS_PT_EXTRACTREGION [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_PT_EXTRACTREGION This function reads data from the designated level fields into the data buffer from the subsetted area of interest. Syntax Result = EOS_PT_EXTRACTREGION( pointID, regionID, level, fieldlist, buffer) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments pointID Point id (long). regionID Period id (long) returned by EOS_PT_DEFBOXREGION. level Point level (0-based long). fieldlist List of fields (string) to extract. buffer A named variable that will contain the data buffer. Example In this example, we read data within the subsetted area of interest defined by EOS_PT_DEFBOXREGION from the Longitude and Latitude fields: regionID = EOS_PT_DEFBOXREGION(pointID, [-145.,-135.], [-15.,-8.]) IF (regionID NE -1) THEN BEGIN status = EOS_PT_EXTRACTREGION(pointID, regionID, 0, $ "Longitude,Latitude", buffer) HDF_UNPACKDATA, buffer, dat ENDIF EOS_PT_FWDLINKINFO [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_PT_FWDLINKINFO This function returns the linkfield to the given level. Syntax Result = EOS_PT_FWDLINKINFO(pointID, level, linkfield) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments pointID Point id (long) returned by EOS_PT_CREATE or EOS_PT_ATTACH. level Point level (0-based long). linkfield A named variable that will contain the link field (string). Example In this example, we return the linkfield connecting the Desc-Loc level to the following Observations level. (These levels are defined in the EOS_PT_DEFLEVEL function.): status = EOS_PT_FWDLINKINFO(pointID2, 1, linkfield) EOS_PT_GETLEVELNAME [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_PT_GETLEVELNAME This function returns the name of a level given the level number (0-based). Syntax Result = EOS_PT_GETLEVELNAME( pointID, level, levelname [, LENGTH (OUT)=variable] ) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments pointID Point id (long) returned by EOS_PT_CREATE or EOS_PT_ATTACH. level Point level (0-based long). levelname A named variable that will contain the level name (string). Keywords LENGTH Set this keyword to a named variable that will contain the string length of the level name. Example In this example, we return the level name of the 0th level of the second point defined in the EOS_PT_DEFLEVEL section: status = EOS_PT_GETLEVELNAME(pointID2, 0, levelname) EOS_PT_GETRECNUMS [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_PT_GETRECNUMS This function returns the record numbers in one level that are connected to a given set of records in a different level. The two levels need not be adjacent. The records in one level are related to those in another through the link field. These in turn are related to the next. In this way, each record in any level is related to others in all the levels of the point structure. Syntax Result = EOS_PT_GETRECNUMS( pointID, inlevel, outlevel, inNrec, inRecs, outNrec, outRecs) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments pointID Point id (long) returned by EOS_PT_CREATE or EOS_PT_ATTACH. inlevel Level number (long) of input records (0-based). outlevel Level number (long) of output records (0-based). inNrec Number of records (long) in the inRecs array. inRecs Array (long) containing the input record numbers. outNrec A named variable that will contain the number of records (long) in the outRecs array. outRecs A named variable that will contain the array (long) of output record numbers. Example In this example, we get the record numbers in the second level that are related to the first record in the first level: nrec = 1 recs[0] = 0 inLevel = 0 outLevel = 1 status = EOS_PT_GETRECNUMS(pointID2, inLevel, outLevel, $ nrec, recs, outNrec, outRecs) EOS_PT_INQATTRS [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_PT_INQATTRS This function retrieves information about the attributes defined in a point structure. The attribute list is returned as a string with each attribute name separated by a comma. Note See STRSPLIT to separate the attribute list. Syntax Result = EOS_PT_INQATTRS( pointID, attrlist [, LENGTH=value] ) Return Value Number of attributes found or (­1) if failure. Arguments pointID Point id (long). attrlist A named variable that will contain the attribute list (string) entries separated by commas. Keywords LENGTH String length (long) of attribute list. Example nattr = EOS_PT_INQATTRS(pointID, attrlist) EOS_PT_INQPOINT [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_PT_INQPOINT This function retrieves the number and names of points defined in an HDF-EOS file. The point list is returned as a string with each point name separated by a comma. Note See STRSPLIT to separate the attribute list. Syntax Result = EOS_PT_INQPOINT( filename, pointlist [, LENGTH (OUT)=value] ) Return Value Returns number of points found or (­1) if failure. Arguments filename HDF-EOS filename (string). pointlist A named variable that will contain the point list (string) entries separated by commas. Keywords LENGTH String length (long) of point list. Example In this example, we retrieve information about the points defined in an HDF-EOS file, HDFEOS.hdf: npoint = EOS_PT_INQPOINT("HDFEOS.hdf", pointlist) EOS_PT_LEVELINDX [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_PT_LEVELINDX This function returns the level index for a given level specified by name. Syntax Result = EOS_PT_LEVELINDX( pointID, levelname) Return Value Returns the level index if successful and FAIL (­1) otherwise. Arguments pointID Point id (long) returned by EOS_PT_CREATE or EOS_PT_ATTACH. levelname Level Name (string). Example In this example, we return the level index of the Observations level in the multilevel point structure defined in EOS_PT_DEFLEVEL: levindx = EOS_PT_LEVELINDEX(pointID2, "Observations") EOS_PT_LEVELINFO [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_PT_LEVELINFO This function returns information about the fields in a given level. Typical reasons for failure are an improper point id or level number. Syntax Result = EOS_PT_LEVELINFO(pointID, level, fieldlist, fldtype, fldorder) Return Value Returns number of fields if successful and FAIL (­1) otherwise. Arguments pointID Point id (long) returned by EOS_PT_CREATE or EOS_PT_ATTACH. level Point level (0-based long). fieldlist A named variable that will contain field names (string) in level. fldtype A named variable that will contain the number HDF data type (long) of each field. fldorder A named variable that will contain the order (long) of each field. Example In this example, we return information about the Desc-Loc (1st) level defined previously: nflds = EOS_PT_LEVELINFO(pointID2, 0, fldlist, fldtype, fldorder) The last variable is useful only when information on an entire point is requested. EOS_PT_NFIELDS [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_PT_NFIELDS This function returns the number of fields in a level. Syntax Result = EOS_PT_NFIELDS( pointID, level [, LENGTH=bytes] ) Return Value Returns number of fields if successful and FAIL (­1) otherwise. Arguments pointID Point id (long) returned by EOS_PT_CREATE or EOS_PT_ATTACH. level Level number (0-based long). Keywords LENGTH Size (long) in bytes of fieldlist for level. Example In this example, we retrieve the number of fields in the 2nd point defined previously: nflds=EOS_PT_NFIELDS(pointID2,0) EOS_PT_NLEVELS [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_PT_NLEVELS This function returns the number of levels in a point. Syntax Result = EOS_PT_NLEVELS(pointID) Return Value Returns number of levels if successful and FAIL (­1) otherwise. Arguments pointID Point id (long) returned by EOS_PT_CREATE or EOS_PT_ATTACH. Example In this example, we retrieve the number of levels in the 2nd point defined previously: nlevels = EOS_PT_NLEVELS(pointID2) EOS_PT_NRECS [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_PT_NRECS This function returns the number of records in a given level. Syntax Result = EOS_PT_NRECS( pointID, level) Return Value Returns number of records in a given level if successful and FAIL (­1) otherwise. Arguments pointID Point id (long) returned by EOS_PT_CREATE or EOS_PT_ATTACH. level Level number (0-based long). Example In this example, we retrieve the number of records in the first level of the 2nd point defined previously: nrecs = EOS_PT_NRECS(pointID2, 0) EOS_PT_OPEN [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_PT_OPEN This function creates a new file or opens an existing one. Syntax Result = EOS_PT_OPEN( fieldname [, /CREATE] [, /RDWR | , /READ] ) Return Value Returns the point file id handle (fid) if successful and FAIL (­1) otherwise. Arguments fieldname Complete path and filename (string) for the file to be opened. Keywords CREATE If file exist, delete it, then open a new file for read/write. RDWR Open for read/write. If file does not exist, create it. READ Open for read only. If file does not exist then error. Example In this example, we create a new point file named, PointFile.hdf. It returns the file handle, fid. fid = EOS_PT_OPEN("PointFile.hdf", /CREATE) See Also EOS_PT_CLOSE EOS_PT_PERIODINFO [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_PT_PERIODINFO This function returns information about a subsetted time period for a particular fieldlist. Syntax Result = EOS_PT_PERIODINFO(pointID, periodID, level, fieldlist, size) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments pointID Point id (long). periodID Period id (long) returned by EOS_PT_DEFTIMEPERIOD. level Point level (0-based long). fieldlist List of fields (string) to extract. size A named variable that will contain the size in bytes (long) of subset period. Example In this example, we get the size of the subsetted time period defined in EOS_PT_DEFTIMEPERIOD for the Time field: status = EOS_PT_PERIODINTO(pointID, periodID, 0, "Time", size) EOS_PT_PERIODRECS [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_PT_PERIODRECS This function returns the record numbers within a subsetted time period for a particular level. Syntax Result = EOS_PT_PERIODRECS(pointID, periodID, level, nrec, recs) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments pointID Point id (long). periodID Period id (long) returned by EOS_PT_DEFTIMEPERIOD. level Point level (0-based long). nrec A named variable that will contain the number of records (long) within time period in level. recs A named variable that will contain the record numbers (long) of subsetted records in level. Example In this example, we get the number of records and record numbers within the subsetted area of interest defined in EOS_PT_DEFTIMEPERIOD for the 0th level: status = EOS_PT_PERIODRECS(pointID, periodID, 0, nrec, recs) EOS_PT_QUERY [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_PT_QUERY The EOS_PT_QUERY function returns information about a specified point. Syntax Result = EOS_PT_QUERY( Filename, PointName, [Info] ) Return Value This function returns an integer value of 1 if the file is an HDF file with EOS POINT extensions, and 0 otherwise. Arguments Filename A string containing the name of the file to query. PointName A string containing the name of the point to query. Info Returns an anonymous structure containing information about the specified point. The returned structure contains the following fields: Field IDL Data Type Description ATTRIBUTES String array Array of attribute names NUM_ATTRIBUTE Long Number of attributes S NUM_LEVELS Long Number of levels Table 4-2: Fields of the Info Structure EOS_PT_READATTR [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_PT_READATTR This function reads attributes. Syntax Result = EOS_PT_READATTR(pointID, attrname, datbuf) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments pointID Point id (long) returned by EOS_PT_CREATE or EOS_PT_ATTACH. attrname Attribute name (string). datbuf A named variable that will contain the buffer allocated to hold attribute values. Example In this example, we read a single precision (32 bit) floating point attribute with the name "ScalarFloat": status = EOS_PT_READATTR(pointID, "ScalarFloat", f32) EOS_PT_READLEVEL [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_PT_READLEVEL This function reads data from the specified fields and records of a single level in a point. Syntax Result = EOS_PT_READLEVEL(pointID, level, fieldlist, nrec, recs, buffer) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments pointID Point id (long) returned by EOS_PT_CREATE or EOS_PT_ATTACH. level Level to read (0-based long). fieldlist List of fields (string) to read. nrec Number of records (long) to read. recs Record number of records to read (0-based long). buffer A named variable that will contain the buffer to store data. This buffer is in packed format. Use HDF_UNPACKDATA to convert it into IDL variables. Example In this example, we read records 0, 2, and 3 from the Temperature and Mode fields in the first level of the point referred to by point ID, pointID. Temperature is a 32-bit float field and Mode is a 4 character field (HDF types 5 and 4 respectively): recs = [ 0, 2, 3 ] status = EOS_PT_READLEVEL( pointID, 0, "Temperature,Mode", $ 3, recs, buffer) IF (status EQ 0) THEN BEGIN HDF_UNPACKDATA, buffer, dataTemperature, dataMode, $ HDF_TYPE=[5,4], HDF_ORDER = [4,4] ENDIF EOS_PT_REGIONINFO [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_PT_REGIONINFO This function returns information about a subsetted area of interest for a particular fieldlist. Syntax Result = EOS_PT_REGIONINFO(pointID, regionID, level, fieldlist, size) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments pointID Point id (long). regionID Region id (long) returned by EOS_PT_DEFBOXREGION. level Point level (0-based long). fieldlist List of fields (sting) to extract. size A named variable that will contain the size in bytes (long) of subset period. Example In this example, we get the size of the subsetted area of interest defined in EOS_PT_DEFBOXREGION from the Longitude and Latitude fields: status = EOS_PT_REGIONINFO(pointID, regionID, 0, "Longitude, $ Latitude",size) EOS_PT_REGIONRECS [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_PT_REGIONRECS This function returns the record numbers within a subsetted geographic region for a particular level. Syntax Result = EOS_PT_REGIONRECS(pointID, regionID, level, nrec, recs) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments pointID Point id (long). regionID Region id (long) returned by EOS_PT_DEFBOXREGION. level Point level (0-based long). nrec A named variable that will contain the number of records (long) within geographic region in level. recs A named variable that will contain the record numbers (long) of subsetted records in level. Example In this example, we get the number of records and record numbers within the subsetted area of interest defined in EOS_PT_DEFBOXREGION for the 0th level: status = EOS_PT_REGIONRECS(pointID, regionID, 0, nrec, recs) EOS_PT_SIZEOF [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_PT_SIZEOF This function returns information about specified fields in a point regardless of level. Syntax Result = EOS_PT_SIZEOF(pointID, fieldlist, fldlevel) Return Value Returns size in bytes of specified fields and FAIL (­1) otherwise. Arguments pointID Point id (long) returned by EOS_PT_CREATE or EOS_PT_ATTACH. fieldlist Field names (string). fldlevel A named variable that will contain the level number (long) of each field. Example In this example, we return the size in bytes of the Label and Rainfall fields in the 2nd point defined in the EOS_PT_DEFLEVEL function: size = EOS_PT_SIZEOF(pointID2, "Label,Rainfall", fldlevel) EOS_PT_UPDATELEVEL [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_PT_UPDATELEVEL This function updates the specified fields and records of a single level. Syntax Result = EOS_PT_UPDATELEVEL(pointID, level, field, list, nrec, recs, data) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments pointID Point id (long) returned by EOS_PT_CREATE or EOS_PT_ATTACH. level Level to update (0-based long). fieldlist List of fields (string) to update. nrec Number of records (long) to update. recs Record number of records to update (0-based long). data Values to be written to the fields. Data values are not converted to the internal HDF type automatically. Use HDF_PACKDATA if conversion is necessary or the data fields specify multiple types. Example In this example, we update records 0, 2, and 3 in the Temperature and Mode fields in the second level in the point referred to by the point ID pointID. Temperature is a 4 value 32-bit float field and Mode is a 4 character field (HDF types 5 and 4 respectively): recs = [ 0, 2, 3] dataTemperature = [ [20, 21, 22, 23], [30, 31, 32, 33], $ [40, 41, 42, 43]]] dataMode = ['P', 'I', 'A'] buffer = HDF_PACKDATA(dataTemperature, dataMode, $ HDF_TYPE = [5, 4], HDF_ORDER = [4, 4]) status = EOS_PT_UPDATELEVEL( pointID, 1, "Temperature,Mode", $ 3, recs, buffer) EOS_PT_WRITEATTR [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_PT_WRITEATTR This function writes/updates an attribute in a point. If the attribute does not exist, it is created. If it does exist, then the value(s) is (are) updated. Syntax Result = EOS_PT_WRITEATTR( pointID, attrname, datbuf [, COUNT=value] [, HDF_TYPE=value] ) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments pointID Point id (long) returned by EOS_PT_CREATE or EOS_PT_ATTACH. attrname Attribute name (string). datbuf Attribute values. Keywords COUNT Number of values (long) to store in attribute. HDF_TYPE Number type (long) of attribute. Example In this example, we write a single precision (32 bit) floating point number with the name "ScalarFloat" and the value 3.14: f32 = 3.14f status = EOS_PT_WRITEATTR(pointid, "ScalarFloat", f32) We can update this value by simply calling the function again with the new value: f32 = 3.14159 status = EOS_PT_WRITEATTR(pointid, "ScalarFloat", f32) EOS_PT_WRITELEVEL [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_PT_WRITELEVEL This function writes (appends) full records to a level. The data in each record must be packed. Refer to the section on Vdatas in the HDF documentation. The input data buffer must be sufficient to fill the number of records designated. Syntax Result = EOS_PT_WRITELEVEL(pointID, level, nrec, data) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments pointID Point id (long) returned by EOS_PT_CREATE or EOS_PT_ATTACH. level Level to write (0-based long). nrec Number of records (long) to write. data Values to be written to the field. Data values are not converted to the internal HDF type automatically. Use HDF_PACKDATA if conversion is necessary or the data fields specify multiple types. Example In this example, we write 5 records to the first level in the point referred to by the point id, pointID1: status = EOS_PT_WRITELEVEL(pointID1, 0, 5, datbuf) EOS_QUERY [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_QUERY The EOS_QUERY function returns information about the makeup of an HDF-EOS file. Syntax Result = EOS_QUERY( Filename, [Info] ) Return Value This function returns integer value of 1 if the file is an HDF file with EOS extensions, and 0 otherwise. Arguments Filename A scalar string containing the name of the file to query. Info Returns an anonymous structure containing information about the contents of the file. The returned structure contains the following fields: Field IDL Data Type Description GRID_NAMES String array Names of grids NUM_GRIDS Long Number of grids in file NUM_POINTS Long Number of points in file NUM_SWATHS Long Number of swaths in file POINT_NAMES String array Names of points SWATH_NAMES String array Names of swaths Table 4-3: Fields of the Info Structure EOS_SW_ATTACH [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_ATTACH This function attaches to the swath using the swathname parameter as the identifier. Syntax Result = EOS_SW_ATTACH(fid, swathname) Return Value Returns the swath handle (swathID) if successful and FAIL (­1) otherwise. Arguments fid Swath file id (long) returned by EOS_SW_OPEN. swathname Name of swath (string) to be attached. Example In this example, we attach to the previously created swath, "ExampleSwath", within the HDF file, SwathFile.hdf, referred to by the handle, fid: swathID = EOS_SW_ATTACH(fid, "ExampleSwath") The swath can then be referenced by subsequent routines using the handle, swathID. See Also EOS_SW_DETACH EOS_SW_ATTRINFO [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_ATTRINFO This function returns the number type and number of elements (count) of a swath attribute. Syntax Result = EOS_SW_ATTRINFO(swathID, attrname, numbertype, count) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments swathID Swath id (long) returned by EOS_SW_CREATE or EOS_SW_ATTACH. attrname Attribute name (string). numbertype A named variable that will contain the HDF data type (long) of attribute. count A named variable that will contain the number of total bytes (long) in attribute. Example In this example, we return information about the ScalarFloat attribute: status = EOS_SW_ATTRINFO(pointID, "ScalarFloat", nt, count) EOS_SW_CLOSE [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_CLOSE This function closes the HDF swath file. Syntax Result = EOS_SW_CLOSE(fid) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments fid Swath file id (long) returned by EOS_SW_OPEN. Example status = EOS_SW_CLOSE(fid) EOS_SW_COMPINFO [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_COMPINFO This function returns the compression code and compression parameters for a given field. Syntax Result = EOS_SW_COMPINFO(swathID, fieldname, compcode, compparm) Return Value Returns SUCCEED(0) if successful and FAIL(­1) otherwise. Arguments swathID Swath id (long) returned by EOS_SW_CREATE or EOS_SW_ATTACH. fieldname Fieldname (string). compcode A named variable that will contain the HDF compression code (long). compparm A named variable that will contain the compression parameters (long). Example To retrieve the compression information about the Opacity field defined in the EOS_SW_DEFCOMP section: status = EOS_SW_COMPINFO(swathID, "Opacity", compcode, compparm) EOS_SW_CREATE [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_CREATE This function creates a swath within the file. The swath is created as a Vgroup within the HDF file with the name swathname and class EOS_SWATH. Syntax Result = EOS_SW_CREATE(fid, swathname) Return Value Returns the swath handle (swathID) if successful and FAIL (­1) otherwise. Arguments fid Swath file id (long) returned by EOS_SW_OPEN. swathname Name of swath (string) to be created. Example In this example, we create a new swath structure, "ExampleSwath", in the previously created file, SwathFile.hdf. swathID = EOS_SW_CREATE(fid, "ExampleSwath") The swath structure is referenced by subsequent routines using the handle, swathID. EOS_SW_DEFBOXREGION [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_DEFBOXREGION This function defines a longitude-latitude box region for a swath. It returns a swath region ID that is used by the EOS_SW_EXTRACTREGION function to read all the entries of a data field within the region. A cross track is within a region if its midpoint is within the longitude-latitude box (0), or either of its endpoints is within the longitude-latitude box (1), or any point of the cross track is within the longitude- latitude box (2), depending on the inclusion mode designated by the user. All elements within an included cross track are considered to be within the region even though a particular element of the cross track might be outside the region. The swath structure must have both Longitude and Latitude (or Colatitude) fields defined. Syntax Result = EOS_SW_DEFBOXREGION(swathID, cornerlon, cornerlat, mode) Return Value Returns the swath region ID if successful and FAIL (­1) otherwise. Arguments swathID Swath id (long) returned by EOS_SW_CREATE or EOS_SW_ATTACH. cornerlon Longitude in decimal degrees (double) of box corners (double, 2 element, 1-D array). cornerlat Latitude in decimal degrees (double) of box corners (double, 2 element, 1-D array). mode Cross Track inclusion mode (long). Allowable values are: * 0 = Midpoint * 1 = Endpoint * 2 = Anypoint Example In this example, we define a region bounded by 3 degrees longitude, 5 degrees latitude and 7 degrees longitude, 12 degrees latitude. We will consider a cross track to be within the region if its midpoint is within the region: cornerlon[0] = 3.d cornerlat[0] = 5.d cornerlon[1] = 7.d cornerlat[1] = 12.d regionID = EOS_SW_DEFBOXREGION(swathID, cornerlon, cornerlat, 0) EOS_SW_DEFCOMP [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_DEFCOMP This function sets the HDF field compression for subsequent swath field definitions. The compression does not apply to one-dimensional fields. The compression schemes currently supported are: run length encoding (1), skipping Huffman (3), deflate (gzip) (4) and no compression (0, the default). Deflate compression requires a single integer compression parameter in the range of one to nine with higher values corresponding to greater compression. Compressed fields are written using the standard EOS_SW_WRITEFIELD function, however, the entire field must be written in a single call. Any portion of a compressed field can then be accessed with the EOS_SW_READFIELD function. Compression takes precedence over merging so that multi-dimensional fields that are compressed are not merged. The user should refer to the HDF Reference Manual for a fuller explanation of the compression schemes and parameters. Syntax Result = EOS_SW_DEFCOMP( swathID, compcode, [, compparm] ) Return Value Returns SUCCEED(0) if successful and FAIL(­1) otherwise. Arguments swathID Swath id (long) returned by EOS_SW_CREATE or EOS_SW_ATTACH. compcode HDF compression code (long). compparm Compression parameters (long array) if applicable. Allowable values are: * 0 = None * 1 = Run Length Encoding (RLE) * 3 = Skipping Huffman * 4 = Deflate (gzip) Example Suppose we wish to compress the Pressure using run length encoding, the Opacity field using deflate compression, the Spectra field with skipping Huffman compression, and use no compression for the Temperature field: status = EOS_SW_DEFCOMP(swathID, 1) status = EOS_SW_DEFDATAFIELD(swathID, "Pressure", $ "Track,Xtrack", 5) compparm[0] = 5 status = EOS_SW_DEFCOMP(swathID, 4, compparm) status = EOS_SW_DEFDATAFIELD(swathID, "Opacity", $ "Track,Xtrack", 5) status = EOS_SW_DEFCOMP(swathID, 3) status = EOS_SW_DEFDATAFIELD(swathID, "Spectra", $ "Bands,Track,Xtrack", 5) status = EOS_SW_DEFCOMP(swathID, 0) status = EOS_SW_DEFDATAFIELD(swathID, $ "Temperature", "Track,Xtrack", 5, /MERGE) Note that the MERGE keyword will be ignored in the Temperature field definition. EOS_SW_DEFDATAFIELD [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_DEFDATAFIELD This function defines data fields to be stored in the swath. The dimensions are entered as a string consisting of data dimensions separated by commas. The API will attempt to merge into a single object those fields that share dimensions and in case of multidimensional fields, numbertype. If the merge keyword is not set, the API will not attempt to merge it with other fields. Because merging breaks the one-to-one correspondence between HDF-EOS fields and HDF SDS arrays, it should not be set if the user wishes to access the HDF-EOS field directly using HDF routines. To assure that the fields defined by EOS_SW_DEFDATAFIELD are properly established in the file, the swath should be detached (and then reattached) before writing to any fields. Syntax Result = EOS_SW_DEFDATAFIELD( swathID, fieldname, dimlist, numbertype [, /MERGE] ) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments swathID Swath id (long) returned by EOS_SW_CREATE or EOS_SW_ATTACH. fieldname Name of field (string) to be defined. dimlist The list of data dimensions (string) defining the field. numbertype The HDF data type (long) of the data stored in the field. Keywords MERGE If set, automatic merging will occur. By default, fields are not merged. Example In this example, we define a three dimensional data field named Spectra with dimensions Bands, DataTrack, and DataXtrack: status = EOS_SW_DEFDATAFIELD(swathID, "Spectra", $ "Bands,DataTrack,DataXtrack", 5, /MERGE) EOS_SW_DEFDIM [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_DEFDIM This function defines dimensions that are used by the field definition functions (described subsequently) to establish the size of the field. Syntax Result = EOS_SW_DEFDIM(swathID, fieldname, dim) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments swathID Swath id (long). fieldname Name of dimension (string) to be defined. dim The size (long) of the dimension. Example In this example, we define a track geolocation dimension, GeoTrack, of size 2000, a cross track dimension, GeoXtrack, of size 1000 and two corresponding data dimensions with twice the resolution of the geolocation dimensions: status = EOS_SW_DEFDIM(swathID, "GeoTrack", 2000) status = EOS_SW_DEFDIM(swathID, "GeoXtrack", 1000) status = EOS_SW_DEFDIM(swathID, "DataTrack", 4000) status = EOS_SW_DEFDIM(swathID, "DataXtrack", 2000) status = EOS_SW_DEFDIM(swathID, "Bands", 5) To specify an unlimited dimension that can be used to define an appendable array, the dimension value should be set to zero: status = EOS_SW_DEFDIM(swathID, "Unlim", 0) EOS_SW_DEFDIMMAP [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_DEFDIMMAP This function defines monotonic mapping between the geolocation and data dimensions. Typically the geolocation and data dimensions are of different size (resolution). This function establishes the relation between the two where the offset gives the index of the data element (0-based) corresponding to the first geolocation element and the increment gives the number of data elements to skip for each geolocation element. If the geolocation dimension begins "before" the data dimension, then the offset is negative. Similarly, if the geolocation dimension has higher resolution than the data dimension, then the increment is negative. A typical reason for failure is an incorrect geolocation or data dimension name. Syntax Result = EOS_SW_DEFDIMMAP(swathID, geodim, datadim, offset, increment) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments swathID Swath id (long) returned by EOS_SW_CREATE or EOS_SW_ATTACH. geodim Geolocation dimension name (string). datadim Data dimension name (string). offset The offset (long) of the geolocation dimension with respect to the data dimension. increment The increment (long) of the geolocation dimension with respect to the data dimension. Example In this example, we establish the following: * The first element of the GeoTrack dimension corresponds to the first element of the DataTrack dimension and the data dimension has twice the resolution of the geolocation dimension. * The first element of the GeoXtrack dimension corresponds to the second element of the DataTrack dimension and the data dimension has twice the resolution of the geolocation dimension. "GeoTrack", "DataTrack", 0, 2) "GeoXtrack", "DataXtrack", 1, 2) EOS_SW_DEFGEOFIELD [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_DEFGEOFIELD This function defines geolocation fields to be stored in the swath. The dimensions are entered as a string consisting of geolocation dimensions separated by commas. The API will attempt to merge into a single object those fields that share dimensions and in case of multidimensional fields, numbertype. If the merge keyword is not set, the API will not attempt to merge it with other fields. Fields using the unlimited dimension will not be merged. Because merging breaks the one-to-one correspondence between HDF-EOS fields and HDF SDS arrays, it should not be set if the user wishes to access the HDF field directly using HDF routines. To assure that the fields defined by EOS_SW_DEFGEOFIELD are properly established in the file, the swath should be detached (and then reattached) before writing to any fields. Syntax Result = EOS_SW_DEFGEOFIELD( swathID, fieldname, dimlist, numbertype [, /MERGE] ) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments swathID Swath id (long) returned by EOS_SW_CREATE or EOS_SW_ATTACH. fieldname Name of field (string) to be defined. dimlist The list of geolocation dimensions (sting) defining the field. numbertype The HDF data type (long) of the data stored in the field. Keywords MERGE If set, automatic merging will occur. By default, fields are not merged. Example In this example, we define the geolocation fields, Longitude and Latitude with dimensions GeoTrack and GeoXtrack and containing 4 byte floating point numbers. We allow these fields to be merged into a single object: status = EOS_SW_DEFGEOFIELD(swathID, "Longitude",$ "GeoTrack,GeoXtrack", 5, /MERGE status = EOS_SW_DEFGEOFIELD(swathID, "Latitude", $ "GeoTrack,GeoXtrack", 5, /MERGE EOS_SW_DEFIDXMAP [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_DEFIDXMAP If there does not exist a regular (linear) mapping between a geolocation and data dimension, then the mapping must be made explicit. Each element of the index array, whose dimension is given by the geolocation size, contains the element number (0- based) of the corresponding data dimension. Syntax Result = EOS_SW_DEFIDXMAP(swathID, geodim, datadim, index) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments swathID Swath id (long) returned by EOS_SW_CREATE or EOS_SW_ATTACH. geodim Geolocation dimension name (string). datadim Data dimension name (string). index The array (long) containing the indices of the data dimension to which each geolocation element corresponds. Example In this example, we consider the (simple) case of a geolocation dimension IdxGeo of size 5 and a data dimension IdxData of size 8. In this case, the 0th element of IdxGeo will correspond to the 0th element of IdxData, the 1st element of IdxGeo to the 2nd element of IdxData, etc.: index = [0,2,3,6,7] status = EOS_SW_DEFIDXMAP(swathID, "IdxGeo", "IdxData", index) EOS_SW_DEFTIMEPERIOD [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_DEFTIMEPERIOD This function defines a time period for a swath. It returns a swath period ID which is used by the EOS_SW_EXTRACTPERIOD function to read all the entries of a data field within the time period. A cross track is within a time period if its midpoint is within the time period box (0), or either of its endpoints is within the time period box (1), or any point of the cross track is within the time period box (2), depending on the inclusion mode designated by the user. All elements within an included cross track are considered to be within the time period even though a particular element of the cross track might be outside the time period. The swath structure must have the Time field defined. Syntax Result = EOS_SW_DEFTIMEPERIOD(swathID, starttime , stoptime, mode) Return Value Returns the swath period ID if successful and FAIL (­1) otherwise. Arguments swathID Swath id (long) returned by EOS_SW_CREATE or EOS_SW_ATTACH. starttime Start time (double) of period. stoptime Stop time (double) of period. mode Cross Track inclusion mode (long). Allowable values are: * 0 = Midpoint * 1 = Endpoint * 2 = Anypoint Example In this example, we define a time period with a start time of 35232487.2 and a stop time of 36609898.1.We will consider a cross track to be within the time period if either one of the time values at the endpoints of a cross track are within the time period: starttime = 35232487.2d stoptime = 36609898.1d periodID = EOS_SW_DEFTIMEPERIOD(swathID, starttime, stoptime, 1) EOS_SW_DEFVRTREGION [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_DEFVRTREGION Whereas the EOS_SW_DEFBOXREGION and EOS_SW_DEFTIMEPERIOD functions perform subsetting along the "Track" dimension, this function allows the user to subset along any dimension. The region is specified by a set of minimum and maximum values and can represent either a dimension index (case 1) or field value range (case 2). In the second case, the field must be one-dimensional and the values must be monotonic (strictly increasing or decreasing) in order that the resulting dimension index range be contiguous. (For the current version of this function, the second option is restricted to fields with one of the following HDF data types: 22, 24, 5, 6.) This function may be called after EOS_SW_DEFBOXREGION or EOS_SW_DEFTIMEPERIOD to provide both geographic or time and "vertical" subsetting. In this case the user provides the id from the previous subset call. (This same id is then returned by the function.) This function may also be called "stand- alone" by setting the input id to (­1). This function may be called up to eight times with the same region ID. It this way a region can be subsetted along a number of dimensions. The EOS_SW_REGIONINFO and EOS_SW_EXTRACTREGION functions work as before, however, because there is no mapping performed between geolocation dimensions and data dimensions the field to be subsetted, (the field specified in the call to EOS_SW_REGIONINFO and EOS_SW_EXTRACTREGION) must contain the dimension used explicitly in the call to EOS_SW_DEFVRTREGION (case 1) or the dimension of the one-dimensional field (case 2). Syntax Result = EOS_SW_DEFVRTREGION(swathID, regionID, vertObj, range) Return Value Returns the swath region ID if successful and FAIL (­1) otherwise. Arguments swathID Swath id (long) returned by EOS_SW_CREATE or EOS_SW_ATTACH. regionID Region or period id (long) from previous subset call, or ­1 to create a new region within the entire dataset. vertObj Dimension or field (string) to subset by. range Minimum and maximum range (double) for subset. Example Suppose we have a field called Pressure of dimension Height whose values increase from 100 to1000, and we desire all the elements with values between 500 and 800: range[0] = 500.d range[1] = 800.d regionID = EOS_SW_DEFVRTREGION(swathID, -1, "Pressure", range) The function determines the elements in the Height dimension that correspond to the values of the Pressure field between 500 and 800. If we wish to specify the subset as elements 2 through 5 (0 - based) of the Height dimension, the call would be: range[0] = 2.d range[1] = 5.d regionID = EOS_SW_DEFVRTREGION(swathID, -1, "DIM:Height", range) The "DIM:" prefix tells the routine that the range corresponds to elements of a dimension rather than values of a field. In this example, any field to be subsetted must contain the Height dimension. If a previous subset region or period was defined with an id of subsetID that we wish to refine further with the vertical subsetting defined above, we make the call: regionID = EOS_SW_DEFVRTREGION(swathID, subsetID, $ "Pressure", range) The return value, regionID, is set equal to subsetID. That is, the subset region is modified rather than a new one created. We can further refine the subset region with another call to the function: freq[0] = 1540.3d freq[1] = 1652.8d regionID = EOS_SW_DEFVRTREGION(swathID, regionID, $ "FreqRange", freq) EOS_SW_DETACH [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_DETACH This function detaches from the swath interface. It should be run before exiting from the swath file for every swath opened by EOS_SW_CREATE or EOS_SW_ATTACH. Syntax Result = EOS_SW_DETACH(swathID) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments swathID Swath id (long) returned by EOS_SW_CREATE or EOS_SW_ATTACH. Example status = EOS_SW_DETACH(swathID) EOS_SW_DIMINFO [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_DIMINFO This function retrieves the size of the specified dimension. Syntax Result = EOS_SW_DIMINFO(swathID, dimname) Return Value Size of dimension or FAIL (­1) if the swath ID or dimension name are invalid. Arguments swathID Swath id (long). dimname Dimension name (string). Example In this example, we retrieve information about the dimension, "GeoTrack": dimsize = EOS_SW_DIMINFO(swathID, "GeoTrack") EOS_SW_DUPREGION [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_DUPREGION This function copies the information stored in a current region or period to a new region or period and generates a new id. It is useful when the user wishes to further subset a region (period) in multiple ways. Syntax Result = EOS_SW_DUPREGION(regionID) Return Value Returns new region or period ID or FAIL (­1) on error. Arguments regionID Region or period id (long) returned by EOS_SW_DEFBOXREGION, EOS_SW_DEFTIMEPERIOD, or EOS_SW_DEFVRTREGION. Example In this example, we first subset a swath with EOS_SW_DEFBOXREGION, duplicate the region creating a new region ID, regionID2, and then perform two different vertical subsets of these (identical) geographic subset regions: regionID = EOS_SW_DEFBOXREGION(swathID, cornerlon, $ cornerlat, 0) regionID2 = EOS_SW_DUPREGION(regionID) regionID = EOS_SW_DEFVRTREGION(swathID, regionID, $ "Pressure", rangePres) regionID2 = EOS_SW_DEFVRTREGION(swathID, regionID2, $ "Temperature", rangeTemp) EOS_SW_EXTRACTPERIOD [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_EXTRACTPERIOD This function reads data into the data buffer from the subsetted time period. Only complete crosstracks are extracted. If the external_mode flag is set to (1) then the geolocation fields and the data field can be in different swaths. If set to (0), then these fields must be in the same swath structure. Syntax Result = EOS_SW_EXTRACTPERIOD(swathID, periodID, fieldname, external_mode, buffer) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments swathID Swath id (long). periodID Period id (long) returned by EOS_SW_DEFTIMEPERIOD. fieldname Field to subset (string). external_mode External geolocation mode (long). buffer A named variable that will contain the period data. Example In this example, we read data within the subsetted time period defined in EOS_SW_DEFTIMEPERIOD from the Spectra field. Both the geolocation fields and the Spectra data field are in the same swath. status = EOS_SW_EXTRACTPERIOD(EOS_SW_id, periodID, 0,"Spectra", $ datbuf) EOS_SW_EXTRACTREGION [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_EXTRACTREGION This function reads data into the data buffer from the subsetted region. Only complete crosstracks are extracted. If the external_mode flag is set to (1) then the geolocation fields and the data field can be in different swaths. If set to (0), then these fields must be in the same swath structure. Syntax Result = EOS_SW_EXTRACTREGION(swathID, regionID, fieldname, external_mode, buffer) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments swathID Swath id (long) returned by EOS_SW_CREATE or EOS_SW_ATTACH. regionID Region id (long) returned by EOS_SW_DEFBOXREGION. fieldname Field to subset (string). external_mode External geolocation mode (long). buffer A named variable that will contain the data buffer. Example In this example, we read data within the subsetted region defined in EOS_SW_DEFBOXREGION from the Spectra field. Both the geolocation fields and the Spectra data field are in the same swath. status = EOS_SW_EXTRACTREGION(EOS_SW_id, regionID, 0, "Spectra",$ datbuf) EOS_SW_FIELDINFO [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_FIELDINFO This function retrieves information on a specific data field. Syntax Result = EOS_SW_FIELDINFO(swathID, fieldname, rank, dims, numbertype, dimlist) Return Value Returns SUCCEED(0) if successful and FAIL(­1) if the specified field does not exist. Arguments swathID Swath id (long). fieldname Fieldname (string). rank A named variable that will contain the rank of field (long). dims A named variable that will contain the array of length "rank" (long) containing the dimension sizes of the field. If one of the dimensions in the field is appendable, then the current value for that dimension will be returned in the dims array. numbertype A named variable that will contain HDF data type of the field. dimlist A named variable that will contain the list of dimensions (string) in field. Example In this example, we retrieve information about the Spectra data fields: status = EOS_SW_FIELDINFO(swathID, "Spectra", rank, dims, $ numbertype, dimlist) EOS_SW_GETFILLVALUE [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_GETFILLVALUE This function retrieves the fill value for the specified field. Syntax Result = EOS_SW_GETFILLVALUE(swathID, fieldname, fillvalue) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments swathID Swath id (long) returned by EOS_SW_CREATE or EOS_SW_ATTACH. fieldname Fieldname (string). fillvalue A named variable that will contain the fill value. Example In this example, we get the fill value for the "Temperature" field: status = EOS_SW_GETFILLVALUE(swathID, "Temperature", tempfill) EOS_SW_IDXMAPINFO [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_IDXMAPINFO This function retrieves the size of the indexed array and the array of indexed elements of the specified geolocation mapping. Syntax Result = EOS_SW_IDXMAPINFO(swathID, geodim, datadim, index) Return Value Returns size of indexed array if successful and FAIL (­1) if the specified mapping does not exist. Arguments swathID Swath id (long) returned by EOS_SW_CREATE or EOS_SW_ATTACH. geodim Geolocation dimension name (string). datadim Data dimension name (string). index A named variable that will contain an array (long) of indices of the data dimension to which each geolocation element corresponds. Example In this example, we retrieve information about the indexed mapping between the "IdxGeo" and "IdxData" dimensions: idxsz = EOS_SW_IDXMAPINFO(swathID, "IdxGeo", "IdxData", index) EOS_SW_INQATTRS [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_INQATTRS This function retrieves information about attributes defined in swath. The attribute list is returned as a string with each attribute name separated by commas. Note See STRSPLIT to separate the attribute list. Syntax Result = EOS_SW_INQATTRS( swathID, attrlist [, LENGTH (OUT)=value] ) Return Value Number of attributes found or (­1) if failure. Arguments swathID Swath id (long) returned by EOS_SW_CREATE or EOS_SW_ATTACH. attrlist A named variable that will contain the attribute list (string) with entries separated by commas. Keywords LENGTH String length (long) of attribute list. Example nattr = EOS_SW_INQATTRS(swathID, attrlist) EOS_SW_INQDATAFIELDS [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_INQDATAFIELDS This function retrieves information about all of the data fields defined in swath. The field list is returned as a string with each data field separated by commas. The rank and numbertype arrays will have an entry for each field. Note See STRSPLIT to separate the field list. Syntax Result = EOS_SW_INQDATAFIELDS(swathID, fieldlist, rank, numbertype) Return Value Returns number of data fields found. If ­1, could signify improper swath id. Arguments swathID Swath id (long) returned by EOS_SW_CREATE or EOS_SW_ATTACH. fieldlist A named variable that will contain the listing of data fields (string) with entries separated by commas. rank A named variable that will contain an array (long) of rank of each data field. numbertype A named variable that will contain an array (long) of numbertype of each data field. Example nflds = EOS_SW_INQDATAFIELDS(swathID, fieldlist, rank, numbertype) EOS_SW_INQDIMS [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_INQDIMS This function retrieves information about all of the dimensions defined in swath. The dimension list is returned as a string with each dimension name separated by commas. Note See STRSPLIT to separate the dimension list. Syntax Result = EOS_SW_INQDIMS(swathID, dimname, dim) Return Value Returns number of dimension entries found. If ­1, could signify an improper swath id. Arguments swathID Swath id (long) returned by EOS_SW_CREATE or EOS_SW_ATTACH. dimname A named variable that will contain the dimension list (string) with entries separated by commas. dims A named variable that will contain an array (long) of size of each dimension. Example ndims = EOS_SW_INQDIMS(swathID, dimname, dims) EOS_SW_INQGEOFIELDS [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_INQGEOFIELDS This function retrieves information about all of the geolocation fields defined in swath. The field list is returned as a string with each geolocation field separated by commas. The rank and numbertype arrays will have an entry for each field. Note See STRSPLIT to separate the field list. Syntax Result = EOS_SW_INQGEOFIELDS(swathID, fieldlist, rank, numbertype) Arguments swathID Swath id (long) returned by EOS_SW_CREATE or EOS_SW_ATTACH. fieldlist A named variable that will contain the listing of geolocation fields (string) with entries separated by commas. rank A named variable that will contain an array (long) of the rank of each geolocation field. numbertype A named variable that will contain an array (long) of the numbertype of each geolocation field. Return Value Returns number of geolocation fields found. If ­1, could signify an improper swath id. Example nflds = EOS_SW_INQGEOFIELDS(swathID, fieldlist, rank, numbertype) EOS_SW_INQIDXMAPS [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_INQIDXMAPS This function retrieves information about all of the indexed geolocation/data mappings defined in swath. The dimension mapping list is returned as a string with each mapping separated by commas. The two dimensions in each mapping are separated by a slash (/). Note See STRSPLIT to separate the mapping list. Syntax Result = EOS_SW_INQIDXMAPS(swathID, idxmap, idxsizes) Return Value Number of indexed mapping relations found. If ­1, could signify an improper swath id. Arguments swathID Swath id (long) returned by EOS_SW_CREATE or EOS_SW_ATTACH. idxmap A named variable that will contain the indexed Dimension mapping list (string) with entries separated by commas. idxsizes A named variable that will contain an array (long) of the sizes of the corresponding index arrays. Example nidxmaps = EOS_SW_INQIDXMAPS(swathID, idxmap, idxsizes) EOS_SW_INQMAPS [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_INQMAPS This function retrieves information about all of the (non-indexed) geolocation relations defined in swath. The dimension mapping list is returned as a string with each mapping separated by commas. The two dimensions in each mapping are separated by a slash (/). Note See STRSPLIT to separate the mapping list. Syntax Result = EOS_SW_INQMAPS(swathID, dimmap, offset, increment) Return Value Number of geolocation relation entries found. If ­1, could signify an improper swath id. Arguments swathID Swath id (long) returned by EOS_SW_CREATE or EOS_SW_ATTACH. dimmap A named variable that will contain the dimension mapping list (string) with entries separated by commas. offset A named variable that will contain an array (long) of the offset of each geolocation relation. increment A named variable that contain an array (long) of the increment of each geolocation relation. Example nmaps = EOS_SW_INQMAPS(swathID, dimmap, offset, increment) EOS_SW_INQSWATH [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_INQSWATH This function retrieves number and names of swaths defined in the HDF-EOS file. The swath list is returned as a string with each swath name separated by commas. Note See STRSPLIT to separate the swath list. Syntax Result = EOS_SW_INQSWATH( filename, swathlist [, LENGTH =value] ) Return Value Number of swaths found or (­1) if failure. Arguments filename HDF-EOS filename (string). swathlist Swath list (string) with entries separated by commas. Keywords LENGTH String length (long) of swath list. Example In this example, we retrieve information about the swaths defined in an HDF-EOS file, HDFEOS.hdf: nswath = EOS_SW_INQSWATH("HDFEOS.hdf", swathlist) EOS_SW_MAPINFO [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_MAPINFO This function retrieves the offset and increment of the specified geolocation mapping. Syntax Result = EOS_SW_MAPINFO(swathID, geodim, datadim, offset, increment) Return Value Returns SUCCEED (0) if successful and FAIL (­1) if the specified mapping does not exist. Arguments swathID Swath id (long) returned by EOS_SW_CREATE or EOS_SW_ATTACH. geodim Geolocation dimension name (string). datadim Data dimension name (string). offset A named variable that will contain the mapping offset (long). increment A named variable that will contain the mapping increment (long). Example In this example, we retrieve information about the mapping between the GeoTrack and DataTrack dimensions: status = EOS_SW_MAPINFO(swathID, "GeoTrack", "DataTrack", $ offset, increment) EOS_SW_NENTRIES [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_NENTRIES This function returns number of entries and descriptive string buffer size for a specified entity. This function can be called before an inquiry routine in order to determine the sizes of the output arrays and descriptive strings. Syntax Result = EOS_SW_NENTRIES( swathID, entrycode [, LENGTH (OUT)=value] ) Return Value Number of entries or FAIL (­1) in the case of an improper swath id or entry code. Arguments swathID Swath id (long) returned by EOS_SW_CREATE or EOS_SW_EOS_SW_ATTACH. entrycode Entrycode (long). Allowable values are: * 0 = Dimensions * 1 = Dimension Mappings * 2 = Indexed Dimension Mappings * 3 = Geolocation Fields * 4 = Data Fields Keywords LENGTH String buffer size (long). This is the length of the string that would be returned by the corresponding inquiry routine. Example In this example, we determine the number of dimension mapping entries. nmaps = EOS_SW_NENTRIES(swathID, 2) EOS_SW_OPEN [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_OPEN This function creates a new file or opens an existing file. Syntax Result = EOS_SW_OPEN( filename [, /CREATE] [, /RDWR | , /READ] ) Return Value Returns the swath file id handle (fid) if successful and FAIL (­1) otherwise. Arguments filename Complete path and filename for the file to be opened (string). Keywords CREATE If file exists, delete it, then open a new file for read/write. RDWR Open for read/write, If file does not exist, create it. READ Open for read only. If file does not exist, error. This is the default. Example In this example, we create a new swath file named, SwathFile.hdf. It returns the file handle, fid: fid = EOS_SW_OPEN("SwathFile.hdf", /CREATE) EOS_SW_PERIODINFO [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_PERIODINFO This function returns information about a subsetted time period for a particular field. Because of differences in number type and geolocation mapping, a given time period will give different values for the dimensions and size for various fields. Syntax Result = EOS_SW_PERIODINFO(swathID, periodID, fieldname, ntype, rank, dims, size) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments swathID Swath id (long) returned by EOS_SW_CREATE or EOS_SW_ATTACH. periodID Period id (long) returned by EOS_SW_DEFTIMEPERIOD. fieldname Field to subset (string). ntype A named variable that will contain the number type of field (long). rank A named variable that will contain the rank of field (long). dims A named variable that will contain the dimensions of subset period (long). size A named variable that will contain the size in bytes of subset period (long). Example In this example, we retrieve information about the time period defined in EOS_SW_DEFTIMEPERIOD for the Spectra field: ; Get size in bytes of time period for "Spectra" field status = EOS_SW_PERIODINFO(EOS_SW_id, periodID, $ "Spectra", ntype, rank, dims, size) EOS_SW_QUERY [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_QUERY The EOS_SW_QUERY function returns information about a specified swath. Syntax Result=EOS_SW_QUERY(Filename, SwathName, [Info]) Return Value This function returns an integer value of 1 if the file is an HDF file with EOS SWATH extensions, and 0 otherwise. Arguments Filename A string containing the name of the file to be queried. SwathName A string containing the name of the swath to be queried. Info Returns an anonymous structure containing information about the specified swath. The returned structure contains the following fields: Field IDL data type Description ATTRIBUTES String array Array of attribute names DIMENSION_NAMES String array Names of dimensions DIMENSION_SIZES Long array Sizes of dimensions FIELD_NAMES String array Names of fields FIELD_RANKS Long array Ranks (dimensions) of fields FIELD_TYPES Long array IDL types of fields GEO_FIELD_NAMES String array Names of geolocation fields Table 4-4: Fields of the Info Structure Field IDL data type Description GEO_FIELD_RANKS Long array Ranks (dimensions) of geolocation fields GEO_FIELD_TYPES Long array IDL types of geolocation fields IDX_MAP_NAMES String array Names of index maps IDX_MAP_SIZES Long array Sizes of index map arrays NUM_ATTRIBUTES Long Number of attributes NUM_DIMS Long Number of dimensions NUM_FIELDS Long Number of fields NUM_GEO_FIELDS Long Number of geolocation fields NUM_IDX_MAPS Long Number of indexed dimension mapping entries NUM_MAPS Long Number of mapping entries MAP_INCREMENTS Long array Increment of each geolocation relation MAP_NAMES String array Names of maps MAP_OFFSETS Long array Offset of each geolocation relation Table 4-4: Fields of the Info Structure EOS_SW_READATTR [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_READATTR This function reads attributes from a swath field. Syntax Result = EOS_SW_READATTR(swathID, attrname, datbuf) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments swathID Swath id (long) returned by EOS_SW_CREATE or EOS_SW_ATTACH. attrname Attribute name (string). datbuf A named variable that will contain the attribute values. Example In this example, we read a single precision (32-bit) floating-point attribute with the name "ScalarFloat": status = EOS_SW_READATTR(swathID, "ScalarFloat", f32) EOS_SW_READFIELD [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_READFIELD This function reads data from a swath field. The values within start, stride, and edge arrays refer to the swath field (input) dimensions. The default values for start and stride are 0 and 1 respectively if these keywords are not set. The default value for edge is (dim ­ start) / stride where dim refers to the IDL variable dimension. Syntax Result = EOS_SW_READFIELD( swathID, fieldname, buffer [, EDGE=array] [, START=array] [, STRIDE=array] ) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments swathID Swath id (long) returned by EOS_SW_CREATE or EOS_SW_ATTACH. fieldname Name of field to read (string). buffer A named variable that will contain the data read from the field. Keywords EDGE Array (long) specifying the number of values to read along each dimension. START Array (long) specifying the starting location within each dimension. STRIDE Array (long) specifying the number of values to skip along each dimension. Example In this example, we read data from the 10th track (0-based) of the Longitude field: start=[10,1] edge=[1,1000] status = EOS_SW_READFIELD(swathID, "Longitude", track, $ START = start, EDGE = edge) EOS_SW_REGIONINFO [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_REGIONINFO This function returns information about a subsetted region for a particular field. Because of differences in number type and geolocation mapping, a given region will give different values for the dimensions and size for various fields. Syntax Result = EOS_SW_REGIONINFO(swathID, regionID, fieldname, ntype, rank, dims, size) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments swathID Swath id (long) returned by EOS_SW_CREATE or EOS_SW_ATTACH. regionID Region id (long) returned by EOS_SW_DEFBOXREGION. fieldname Field to subset (string). ntype A named variable that will contain the number type of field (long). rank A named variable that will contain the rank of field (long). dims A named variable that will contain the dimensions of subset region (long). size A named variable that will contain the size in bytes of subset region (long). Example In this example, we retrieve information about the region defined in EOS_SW_DEFBOXREGION for the Spectra field: status = EOS_SW_REGIONINFO(EOS_SW_id, regionID, "Spectra", $ ntype, rank, dims, size) EOS_SW_SETFILLVALUE [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_SETFILLVALUE This function sets the fill value for the specified field. The fill value is placed in all elements of the field that have not been explicitly defined. Syntax Result = EOS_SW_SETFILLVALUE(swathID, fieldname, fillvalue) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments swathID Swath id (long) returned by EOS_SW_CREATE or EOS_SW__ATTACH. fieldname Fieldname (string). fillvalue The fill value to be used. Example In this example, we set a fill value for the "Temperature" field: tempfill = -999.0 status = EOS_SW_SETFILLVALUE(swathID, "Temperature", tempfill) EOS_SW_WRITEATTR [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_WRITEATTR This function writes/updates attributes in a swath. If the attribute does not exist, it is created. If it does exist, then the value is updated. Syntax Result = EOS_SW_WRITEATTR( swathID, attrname, datbuf [, COUNT=value] [, HDF_TYPE=value] ) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments swathID Swath id (long) returned by EOS_SW_CREATE or EOS_SW_ATTACH. attrname Attribute name (string). datbuf Attribute values (long). If HDF_TYPE is specified, the attribute values are first converted to the type specified by HDF_TYPE before being stored. Keywords COUNT Number of values to store in attribute (long). HDF_TYPE HDF data type of the attribute. Example In this example, we write a single precision (32 bit) floating point number with the name "ScalarFloat" and the value 3.14: f32 = 3.14 status = EOS_SW_WRITEATTR(swathid, "ScalarFloat", f32) We can update this value by simply calling the function again with the new value: f32 = 3.14159 status = EOS_SW_WRITEATTR(swathid, "ScalarFloat", f32) EOS_SW_WRITEDATAMETA [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_WRITEDATAMETA This function writes field metadata for an existing data field. This is useful when the data field was defined without using the swath API. Note that any entries in the dimension list must be defined through the EOS_SW_DEFDIM function before this function is called. Syntax Result = EOS_SW_WRITEDATAMETA(swathID, fieldname, dimlist, numbertype) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments swathID Swath id (long) returned by EOS_SW_CREATE or EOS_SW_ATTACH. fieldname Name of field (string). dimlist The list of data dimensions defining the field (string). numbertype The number type of the data stored in the field (long). Example In this example, we write the metadata for the "Band_1" data field used in the swath: status = EOS_SW_WRITEDATAMETA(swathID, "Band_1", $ "GeoTrack,GeoXtrack",5) EOS_SW_WRITEFIELD [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_WRITEFIELD This function writes data to a swath field. The values within start, stride, and edge arrays refer to the swath field (output) dimensions. The default values for start and stride are 0 and 1 respectively and are used if keywords are not set. The default value for edge is (dim ­ start) / stride where dim refers to the size of the dimension. Note that the data buffer for a compressed field must be the size of the entire field as incremental writes are not supported by the underlying HDF routines. Syntax Result = EOS_SW_WRITEFIELD( swathID, fieldname, cut, data [, EDGE=array] [, START=array] [, STRIDE=array] ) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments swathID Swath id (long) returned by EOS_SW_CREATE or EOS_SW_ATTACH. fieldname Name of field to write (string). data Values to be written to the field. Keywords EDGE Array (long) specifying the number of values to write along each dimension. START Array (long) specifying the starting location within each dimension (0-based). STRIDE Array (long) specifying the number of values to skip along each dimension. Example In this example, we write data to the Longitude field: ; Define elements of longitude array: longitude = indgen(2000, 1000) status = EOS_SW_WRITEFIELD(swathID,"Longitude", longitude) ; We now update Track 10 (0 - based) in this field: newtrack = intarr (1000) start=[10,0] edge =[1,1000] ; Define elements of newtrack array: status = EOS_SW_WRITEFIELD(swathID, "Longitude",newtrack, $ START = start, EDGE = edge) EOS_SW_WRITEGEOMETA [Previous Routine] [Next Routine] [List of Routines] NAME: EOS_SW_WRITEGEOMETA This function writes field metadata for an existing geolocation field. This is useful when the data field was defined without using the swath API. Note that any entries in the dimension list must be defined through the EOS_SW_DEFDIM function before this function is called. Syntax Result = EOS_SW_WRITEGEOMETA(swathID, fieldname, dimlist, numbertype) Return Value Returns SUCCEED (0) if successful and FAIL (­1) otherwise. Arguments swathID Swath id (long) returned by EOS_SW_CREATE or EOS_SW_ATTACH. fieldname Name of field (string). dimlist The list of geolocation dimensions (string) defining the field. numbertype The number type of the data (long) stored in the field. Example In this example, we write the metadata for the "Latitude" geolocation field used in the swath: status = EOS_SW_WRITEGEOMETA(swathID, $ "Latitude", "GeoTrack,GeoXtrack", 5) NCDF_ATTCOPY [Previous Routine] [Next Routine] [List of Routines] NAME: NCDF_ATTCOPY The NCDF_ATTCOPY function copies an attribute from one netCDF file to another. Note that Incdf and Outcdf can be the same netCDF ID. NCDF_ATTCOPY returns the attribute number of the copied attribute in the new file, or -1 if the copy was not successful. Syntax Result = NCDF_ATTCOPY( Incdf [, Invar | , /IN_GLOBAL] , Name, Outcdf [, Outvar] [, /OUT_GLOBAL] ) Arguments Incdf The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE. Invar The netCDF variable ID to be read, returned from a previous call to NCDF_VARDEF or NCDF_VARID, or the name of the variable. If the IN_GLOBAL keyword is set, this argument must be omitted. Name A scalar string containing the name of the attribute to be copied. Outcdf The netCDF ID of a netCDF file opened for writing, returned from a previous call to NCDF_OPEN or NCDF_CREATE. Outvar The netCDF variable ID to be written, returned from a previous call to NCDF_VARDEF or NCDF_VARID, or the name of the variable. If the OUT_GLOBAL keyword is set, this argument must be omitted. Keywords IN_GLOBAL Set this keyword to read a global attribute. OUT_GLOBAL Set this keyword to create a global attribute. Example See example from "NCDF_ATTINQ" on page 478. NCDF_ATTDEL [Previous Routine] [Next Routine] [List of Routines] NAME: NCDF_ATTDEL The NCDF_ATTDEL procedure deletes an attribute from a netCDF file. Syntax NCDF_ATTDEL, Cdfid [, Varid | , /GLOBAL] , Name Arguments Cdfid The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE. Varid The netCDF variable ID, returned from a previous call to NCDF_VARDEF or NCDF_VARID, or the name of the variable. Name A scalar string containing the name of the attribute to be deleted. Keywords GLOBAL Set this keyword to delete a global variable. Example ; Open file test.nc for writing: id = NCDF_OPEN('test.nc', /WRITE) ; Delete global attribute TITLE from the file: NCDF_ATTDEL, id, 'TITLE', /GLOBAL NCDF_CLOSE, id ; Close the file. See Also NCDF_ATTNAME, NCDF_ATTPUT NCDF_ATTGET [Previous Routine] [Next Routine] [List of Routines] NAME: NCDF_ATTGET The NCDF_ATTGET procedure retrieves the value of an attribute from a netCDF file. Syntax NCDF_ATTGET, Cdfid [, Varid | , /GLOBAL] , Name, Value Arguments Cdfid The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE. Varid The netCDF variable ID, returned from a previous call to NCDF_VARDEF or NCDF_VARID, or the name of the variable. If the GLOBAL keyword is used, this argument must be omitted. Name A scalar string containing the attribute name. Value A named variable in which the attribute's value is returned. NCDF_ATTGET sets Value's size and data type appropriately. Keywords GLOBAL Set this keyword to retrieve the value of a global attribute. Example For an example using this routine, see the documentation for NCDF_ATTINQ. See Also NCDF_ATTINQ, NCDF_ATTNAME, NCDF_ATTPUT NCDF_ATTINQ [Previous Routine] [Next Routine] [List of Routines] NAME: NCDF_ATTINQ The NCDF_ATTINQ function returns a structure that contains information about a netCDF attribute. This structure, described below, has the form: { DATATYPE:'', LENGTH:0L } Syntax Result = NCDF_ATTINQ( Cdfid [, Varid | , /GLOBAL] , Name ) Arguments Cdfid The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE. Varid The netCDF variable ID, returned from a previous call to NCDF_VARDEF or NCDF_VARID, or the name of the variable. If the GLOBAL keyword is set, this argument must be omitted. Name A scalar string containing the name of the attribute for which information is to be returned. Keywords GLOBAL Set this keyword to inquire about a global variable. If this keyword is set, the Varid argument must be omitted. Explanation of the Structure Tags DataType A string describing the data type of the variable. The string will be one of the following: BYTE, CHAR, INT, LONG, FLOAT, or DOUBLE. Length The number of values stored in the attribute. If the attribute is a string, the number of values indicates one more character than the string length to include the terminating null character. This is the NetCDF convention, as demonstrated in the example below. Example id = NCDF_CREATE('test.nc', /CLOBBER ; Open a new netCDF file. id2 = NCDF_CREATE('test2.nc', /CLOBBER ; Open a second file. ; Create two global attributes TITLE and DATE: NCDF_ATTPUT, id, /GLOBAL, 'TITLE', 'MY TITLE' NCDF_ATTPUT, id, /GLOBAL, 'DAY', 'July 1,1996' ; Suppose we wanted to use DATE instead of DAY. We could use ; ATTRENAME to rename the attribute: NCDF_ATTRENAME, id, 'DAY', 'DATE', /GLOBAL ; Next, copy both attributes into a duplicate file: result = NCDF_ATTCOPY(id, 'TITLE', id2, /IN_GLOBAL, /OUT_GLOBAL) result2 = NCDF_ATTCOPY(id, 'DATE', id2, /IN_GLOBAL, /OUT_GLOBAL) ; Put the file into data mode: NCDF_CONTROL, id, /ENDEF ; Get the second attribute's name: name = NCDF_ATTNAME(id, /GLOBAL, 1) ; Retrieve the date: NCDF_ATTGET, id, /GLOBAL, name, date ; Get info about the attribute: result = NCDF_ATTINQ(id, /GLOBAL, name) HELP, name, date, result, /STRUCTURE PRINT, date PRINT, STRING(date) NCDF_DELETE, id ; Close the netCDF files. NCDF_DELETE, id2 IDL Output NAME STRING = 'DATE' DATE BYTE = Array(12) ** Structure <400dac30>, 2 tags, length=12, refs=1: DATATYPE STRING 'BYTE' LENGTH LONG 12 Note the length includes the NCDF standard NULL terminator 74 117 108 121 32 49 44 49 57 57 54 0 July 1,1996 See Also NCDF_ATTDEL, NCDF_ATTGET, NCDF_ATTNAME, NCDF_ATTPUT NCDF_ATTNAME [Previous Routine] [Next Routine] [List of Routines] NAME: NCDF_ATTNAME The NCDF_ATTNAME function returns the name of an attribute in a netCDF file given its ID. The NULL string ("") is returned if there is no such attribute. Syntax Result = NCDF_ATTNAME( Cdfid [, Varid | , /GLOBAL] , Attnum ) Arguments Cdfid The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE. Varid The netCDF variable ID, returned from a previous call to NCDF_VARDEF or NCDF_VARID, or the name of the variable. If the GLOBAL keyword is set, this argument must be omitted. Attnum An expression containing the number of the desired attribute. The attributes for each variable are numbered from 0 to the number-of-attributes minus 1. Note that the number of attributes can be found using NCDF_VARINQ or NCDF_INQUIRE (to find the number of global variables). Keywords GLOBAL Set this keyword to return the name of one of the global attributes. See Also NCDF_ATTINQ NCDF_ATTPUT [Previous Routine] [Next Routine] [List of Routines] NAME: NCDF_ATTPUT The NCDF_ATTPUT procedure creates an attribute in a netCDF file. If the attribute is new, or if the space required to store the attribute is greater than before, the netCDF file must be in define mode. Syntax NCDF_ATTPUT, Cdfid [, Varid | , /GLOBAL] , Name , Value [, LENGTH=value] [, /BYTE | , /CHAR | , /DOUBLE | , /FLOAT | , /LONG | , /SHORT] Arguments Cdfid The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE. Varid The netCDF variable ID, returned from a previous call to NCDF_VARDEF or NCDF_VARID, or the name of the variable. If the GLOBAL keyword is set, this argument must be omitted. Name A scalar string containing the attribute name. Value An expression containing the data to be written. Although this procedure checks that there are a sufficient number of bytes of data, the data type is not checked or altered. Keywords GLOBAL Set this keyword to create a global attribute. LENGTH Use this keyword to override the default length (the whole value). Set this keyword to a value less than or equal to the number of elements in Value. For example: ATTR_ID = NCDF_ATTPUT(CDFID, VARID, 'Attr1', $ INDGEN(10), LENGTH=5 writes Attr1 as [0,1,2,3,4]. The following keywords specify a non-default data type for the variable. By default, NCDF_ATTPUT chooses one based upon the type of data. If a data type flag is specified, the data supplied in Value is converted to that data type before being written to the file. Only one of these keywords can be used in a single call to NCDF_ATTPUT. BYTE Set this keyword to indicate that the data is composed of bytes. CHAR Set this keyword to indicate that the data is composed of bytes (assumed to be ASCII). DOUBLE Set this keyword to indicate that the data is composed of 8-byte floating point numbers (doubles). FLOAT Set this keyword to indicate that the data is composed of 4-byte floating point numbers (floats). LONG Set this keyword to indicate that the data is composed of 4-byte integers (longs). SHORT Set this keyword to indicate that the data is composed of 2-byte integers. Example NCDF_ATTPUT, cdfid, /GLOBAL, "Title", "My Favorite Data File" NCDF_ATTPUT, cdfid, "data", "scale_factor", 12.5D" See Also NCDF_ATTINQ NCDF_ATTRENAME [Previous Routine] [Next Routine] [List of Routines] NAME: NCDF_ATTRENAME The NCDF_ATTRENAME procedure renames an attribute in a netCDF file. Syntax NCDF_ATTRENAME, Cdfid [, Varid | , /GLOBAL] Oldname, Newname Arguments Cdfid The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE. Varid The netCDF variable ID, returned from a previous call to NCDF_VARDEF or NCDF_VARID, or the name of the variable. If the GLOBAL keyword is set, this argument must be omitted. OldName A scalar string containing the attribute's current name. NewName A scalar string containing the attribute's new name. Keywords GLOBAL Set this keyword to rename a global attribute. See Also NCDF_ATTINQ NCDF_CLOSE [Previous Routine] [Next Routine] [List of Routines] NAME: NCDF_CLOSE The NCDF_CLOSE procedure closes an open netCDF file. If a writable netCDF file is not closed before exiting IDL, the disk copy of the netCDF file may not reflect recent data changes or new definitions. Syntax NCDF_CLOSE, Cdfid Arguments Cdfid The netCDF ID of the file to be closed, returned from a previous call to NCDF_OPEN or NCDF_CREATE. See Also NCDF_ATTINQ NCDF_CONTROL [Previous Routine] [Next Routine] [List of Routines] NAME: NCDF_CONTROL The NCDF_CONTROL procedure performs miscellaneous netCDF operations. Different options are controlled by keywords. Only one keyword can be specified in any call to NCDF_CONTROL, unless the OLDFILL keyword is specified. Syntax NCDF_CONTROL, Cdfid [, /ABORT] [, /ENDEF] [, /FILL | , /NOFILL] [, /NOVERBOSE | , /VERBOSE] [, OLDFILL=variable] [, /REDEF] [, /SYNC] Arguments Cdfid The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE. Keywords ABORT Set this keyword to close a netCDF file that is not in define mode. If the file is being created and is still in define mode, the file is deleted. If define mode was entered by a call to NCDF_CONTROL with the REDEF keyword, the netCDF file is restored to its state before definition mode was entered, and the file is closed. ENDEF Set this keyword to take an open netCDF file out of define mode (and into data mode). FILL Set this keyword so that data in the netCDF file is pre-filled with default fill values. The default values (which cannot be changed) are: Data Type Fill Value BYTE 0 CHAR 0 Table 5-1: Default Fill Values for netCDF Files Data Type Fill Value SHORT -32767 LONG -2147483647 FLOAT 9.96921E+36 DOUBLE 9.96921E+36 Table 5-1: Default Fill Values for netCDF Files NOFILL Set this keyword so that data in the netCDF file is not pre-filled. This option saves time when it is certain that variable values will be written before a read is attempted. NOVERBOSE Set this keyword to suppress the printing of netCDF error messages. Cdfid is required but not used. OLDFILL This keyword specifies a named variable in which the previous fill value is returned. This keyword can only be used in combination with the FILL or NOFILL keywords. For example: NCDF_CONTROL, id, FILL=1, OLDFILL=previous_fill REDEF Set this keyword to put an open netCDF file into define mode. SYNC Set this keyword to update the disk copy of a netCDF file that is open for writing. The netCDF file must be in data mode. A netCDF file in define mode will be updated only when NCDF_CONTROL is called with the ENDEF keyword. VERBOSE Set this keyword to cause netCDF error messages to be printed. Cdfid is required but not used. For example: NCDF_CONTROL, 0, /VERBOSE is a valid command even if 0 is not a valid NetCDF file ID. Example See the examples under NCDF_ATTINQ and NCDF_VARPUT. See Also NCDF_CLOSE, NCDF_CREATE, NCDF_OPEN NCDF_CREATE [Previous Routine] [Next Routine] [List of Routines] NAME: NCDF_CREATE The NCDF_CREATE function creates a new netCDF file. If successful, the netCDF ID for the file is returned. The newly-created netCDF file is automatically placed into define mode. If you do not have write permission to create the specified Filename, NCDF_CREATE returns an error message instead of a netCDF file ID. Syntax Result = NCDF_CREATE( Filename [, /CLOBBER | , /NOCLOBBER] ) Arguments Filename A scalar string containing the name of the file to be created Keywords CLOBBER Set this keyword to erase the existing file (if the file already exists) before creating the new version. NOCLOBBER Set this keyword to create a new netCDF file only if the specified file does not already exist. This is the default. Example ; Open a new NetCDF File and destroy test.nc if it already exists: id = NCDF_CREATE('test.nc',/CLOBBER) id2 = NCDF_CREATE('test.nc', /NOCLOBBER) This attempt to create a new version of the file test.nc produces the following error because the NOCLOBBER keyword was set: nccreate: filename "test.nc": File exists % NCDF_CREATE: Operation failed % Execution halted at $MAIN$ (NCDF_CREATE). See Also NCDF_CLOSE, NCDF_CONTROL, NCDF_OPEN NCDF_DIMDEF [Previous Routine] [Next Routine] [List of Routines] NAME: NCDF_DIMDEF The NCDF_DIMDEF function defines a dimension in a netCDF file given its name and size. If successful, the dimension ID is returned. Syntax Result = NCDF_DIMDEF( Cdfid, DimName, Size [, /UNLIMITED] ) Arguments Cdfid The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE. DimName A scalar string containing the name of the dimension being defined. Size The size of the dimension. Size can be any scalar expression. If the UNLIMITED keyword is used, the Size parameter should be omitted. Keywords UNLIMITED Set this keyword to create a dimension of unlimited size. Note that only one dimension in a netCDF file can be unlimited. Example See NCDF_VARPUT. NCDF_DIMID [Previous Routine] [Next Routine] [List of Routines] NAME: NCDF_DIMID The NCDF_DIMID function returns the ID of a netCDF dimension, given the name of the dimension. This function returns -1 if the dimension does not exist. Syntax Result = NCDF_DIMID( Cdfid, DimName ) Arguments Cdfid The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE. DimName A scalar string containing the dimension name. Example See NCDF_VARPUT. NCDF_DIMINQ [Previous Routine] [Next Routine] [List of Routines] NAME: NCDF_DIMINQ The NCDF_DIMINQ procedure retrieves the name and size of a dimension in a netCDF file, given its ID. The size for the unlimited dimension, if any, is the maximum value used so far in writing data for that dimension. Syntax NCDF_DIMINQ, Cdfid, Dimid, Name, Size Arguments Cdfid The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE. Dimid The netCDF dimension ID, returned from a previous call to NCDF_DIMID or NCDF_DIMDEF, or an indexed number from 0 to NDIMS-1 that indexes the desired dimension. The first dimension has a DIMID of 0, the second dimension has a DIMID of 1, and so on. Name A named variable in which the dimension name is returned (a scalar string). Size A named variable in which the size of the dimension is returned (a scalar longword integer) Example See NCDF_VARPUT. NCDF_DIMRENAME [Previous Routine] [Next Routine] [List of Routines] NAME: NCDF_DIMRENAME The NCDF_DIMRENAME procedure renames an existing dimension in a netCDF file which has been opened for writing. If the new name is longer than the old name, the netCDF file must be in define mode. You cannot rename one dimension to have the same name as another dimension. Syntax NCDF_DIMRENAME, Cdfid, Dimid, NewName Arguments Cdfid The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE. Dimid The netCDF dimension ID, returned from a previous call to NCDF_DIMID or NCDF_DIMDEF, or the name of the dimension. NewName A scalar string containing the new name for the dimension. Example See NCDF_VARPUT. NCDF_EXISTS [Previous Routine] [Next Routine] [List of Routines] NAME: NCDF_EXISTS The NCDF_EXISTS function returns true if the Network Common Data Format (netCDF) scientific data format library is supported on the current IDL platform. This routine is written in the IDL language. Its source code can be found in the file ncdf_exists.pro in the lib subdirectory of the IDL distribution. Syntax Result = NCDF_EXISTS( ) Example The following IDL command prints an error message if the NetCDF library is not available: IF NCDF_EXISTS() EQ 0 THEN PRINT, 'NCDF not supported.' NCDF_INQUIRE [Previous Routine] [Next Routine] [List of Routines] NAME: NCDF_INQUIRE The NCDF_INQUIRE function returns a structure that contains information about an open netCDF file. This structure of the form: { NDIMS:0L, NVARS:0L, NGATTS:0L, RECDIM:0L } The structure tags are described below. Syntax Result = NCDF_INQUIRE(Cdfid) Arguments Cdfid The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE. Explanation of the Structure Tags Ndims The number of dimensions defined for this netCDF file. Nvars The number of variables defined for this netCDF file. Ngatts The number of global attributes defined for this netCDF file. RecDim The ID of the unlimited dimension, if there is one, for this netCDF file. If there is no unlimited dimension, RecDim is set to -1. Example See NCDF_VARDEF. NCDF_OPEN [Previous Routine] [Next Routine] [List of Routines] NAME: NCDF_OPEN The NCDF_OPEN function opens an existing netCDF file. If successful, the netCDF ID for the file is returned. Syntax Result = NCDF_OPEN( Filename [, /NOWRITE | , /WRITE] ) Arguments Filename A scalar string containing the name of the file to be opened. Keywords NOWRITE Set this keyword to open an existing netCDF file as read only. This is the default. WRITE Set this keyword to open an existing netCDF file for both writing and reading. See Also NCDF_ATTINQ NCDF_VARDEF [Previous Routine] [Next Routine] [List of Routines] NAME: NCDF_VARDEF The NCDF_VARDEF function adds a new variable to an open netCDF file in define mode. If successful, the variable ID is returned. If a new variable cannot be defined, NCDF_VARDEF returns -1. Syntax Result = NCDF_VARDEF( Cdfid, Name [, Dim] [, /BYTE | , /CHAR | , /DOUBLE | , /FLOAT | , /LONG | , /SHORT] ) Arguments Cdfid The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE. Name A scalar string containing the variable name. Dim An optional vector containing the dimension IDs corresponding to the variable dimensions. If the ID of the unlimited dimension is included, it must be the rightmost element in the array. If Dim is omitted, the variable is assumed to be a scalar. Keywords The following keywords specify the data type for the variable. Only one of these keywords can be used. If no data type keyword is specified, FLOAT is used by default. BYTE Set this keyword to indicate that the data is composed of bytes. CHAR Set this keyword to indicate that the data is composed of bytes (assumed to be ASCII). DOUBLE Set this keyword to indicate that the data is composed of double-precision floating- point numbers. FLOAT Set this keyword to indicate that the data is composed of floating-point numbers. LONG Set this keyword to indicate that the data is composed of longword integers. SHORT Set this keyword to indicate that the data is composed of 2-byte integers. Example id = NCDF_CREATE('test.nc', /CLOBBER) ; Create the netCDF file. NCDF_ATTPUT, id, 'TITLE', 'Incredibly Important Data', /GLOBAL NCDF_ATTPUT, id, 'GALAXY', 'Milky Way', /GLOBAL NCDF_ATTPUT, id, 'PLANET', 'Earth', /GLOBAL xid = NCDF_DIMDEF(id, 'x', 100) ; Define the X dimension. yid = NCDF_DIMDEF(id, 'y', 200) ; Define the Y dimension. zid = NCDF_DIMDEF(id, 'z', /UNLIMITED) ; Define the Z dimension. vid0 = NCDF_VARDEF(id, 'image0', [yid, xid], /FLOAT) vid1 = NCDF_VARDEF(id, 'image1', [yid, xid], /FLOAT) ; Rename image0 to dist_image: dist_id = NCDF_VARID(id, 'image0') NCDF_VARRENAME, id, vid0, 'dist_image' NCDF_ATTPUT, id, vid, 'TITLE', 'DIST_IMAGE' NCDF_CONTROL, id, /ENDEF ; Put the file into data mode. image = CONGRID(DIST(200), 200, 100) NCDF_VARPUT, id, vid, image INQ_VID = NCDF_VARINQ(id, 'dist_image') HELP, INQ_VID, /STRUCTURE file_inq = NCDF_INQUIRE(id) HELP, file_inq, /STRUCTURE NCDF_CLOSE, id ; Close the NetCDF file. IDL Output ** Structure <400ec678>, 5 tags, length=32, refs=1: NAME STRING 'dist_image' DATATYPE STRING 'FLOAT' NDIMS LONG 2 NATTS LONG 1 DIM LONG Array(2) ** Structure <400ebdf8>, 4 tags, length=16, refs=1: NDIMS LONG 3 NVARS LONG 2 NGATTS LONG 3 RECDIM LONG 2 NCDF_VARGET [Previous Routine] [Next Routine] [List of Routines] NAME: NCDF_VARGET The NCDF_VARGET procedure retrieves a hyperslab of values from a netCDF variable. The netCDF file must be in data mode to use this procedure. Syntax NCDF_VARGET, Cdfid, Varid, Value [, COUNT=vector] [, OFFSET=vector] [, STRIDE=vector] Arguments Cdfid The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE. Varid The netCDF variable ID, returned from a previous call to NCDF_VARDEF or NCDF_VARID, or the name of the variable. Value A named variable in which the values are returned. NCDF_VARGET sets Value's size and data type as appropriate. Keywords COUNT An optional vector containing the counts to be used in reading Value. COUNT is a 1- based vector with an element for each dimension of the data to be written.The default matches the size of the variable so that all data is written out. OFFSET An optional vector containing the starting position for the read. The default start position is [0, 0, ...]. STRIDE An optional vector containing the strides, or sampling intervals, between accessed values of the netCDF variable. The default stride vector is that for a contiguous read, [1, 1, ...]. Example Suppose that a 230 by 230 image is saved in the netCDF file dave.nc. The following commands extract both the full image and a 70x70 sub-image starting at [80,20] sampling every other X pixel and every third Y pixel: ; A variable that contains the offset for the sub-image: offset = [80, 20] ; The dimensions of the sub-image: count = [70, 70] ; Create a variable to be used as a value for the STRIDE keyword. ; Every other X element and every third Y element will be sampled: stride = [2, 3] ; Open the NetCDF file: id = NCDF_OPEN('dave.nc') ; Get the variable ID for the image: image = NCDF_VARID(id, 'image') ; Get the full image: NCDF_VARGET, id, image, fullimage ; Extract the sub-sampled image: NCDF_VARGET, id, image, subimage, $ COUNT=count, STRIDE=stride, OFFSET=offset ; Close the NetCDF file: NCDF_CLOSE, id See Also NCDF_VARGET1, NCDF_VARID, NCDF_VARINQ, NCDF_VARPUT NCDF_VARGET1 [Previous Routine] [Next Routine] [List of Routines] NAME: NCDF_VARGET1 The NCDF_VARGET1 procedure retrieves one element from a netCDF variable. The netCDF file must be in data mode to use this procedure. Syntax NCDF_VARGET1, Cdfid, Varid, Value [, OFFSET=vector] Arguments Cdfid The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE. Varid The netCDF variable ID, returned from a previous call to NCDF_VARDEF or NCDF_VARID, or the name of the variable. Value A named variable in which the value of the variable is returned. NCDF_VARGET1 sets Value's size and data type as appropriate. Keywords OFFSET A vector containing the starting position of the read. The default starting position is [0, 0, ...]. Example Suppose that the file dave.nc contains an image saved with the netCDF variable name "dave". The following commands extract the value of a single pixel from the image: ; The location of the single element (pixel) whose value we will ; retrieve: offset = [180,190] ; Open the netCDF file: id = NCDF_OPEN('dave.nc') ; Get the variable ID for variable "dave": varid = NCDF_VARID(id, 'dave') ; Extract the element and return the value in the variable ; single_pixel: NCDF_VARGET1, id, varid, single_pixel, OFFSET=offset ; Close the netCDF file: NCDF_CLOSE, id See Also NCDF_VARGET, NCDF_VARID, NCDF_VARINQ, NCDF_VARPUT NCDF_VARID [Previous Routine] [Next Routine] [List of Routines] NAME: NCDF_VARID The NCDF_VARID function returns the ID of a netCDF variable. This function returns -1 if the variable does not exist. Syntax Result = NCDF_VARID(Cdfid, Name) Arguments Cdfid The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE. Name A scalar string containing the variable name. Example See NCDF_VARDEF. NCDF_VARINQ [Previous Routine] [Next Routine] [List of Routines] NAME: NCDF_VARINQ The NCDF_VARINQ function returns a structure that contains information about a netCDF variable, given its ID. This structure has the form: { NAME:"", DATATYPE:"", NDIMS:0L, NATTS:0L, DIM:LONARR(NDIMS) } This structure is described below. Syntax Result = NCDF_VARINQ(Cdfid, Varid) Arguments Cdfid The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE. Varid The netCDF variable ID, returned from a previous call to NCDF_VARDEF or NCDF_VARID, or the name of the variable. Explanation of the Structure Tags Name The name of the variable. DataType A string describing the data type of the variable. The string will be one of the following: 'BYTE', 'CHAR', 'INT', 'LONG', 'FLOAT', or 'DOUBLE'. Ndims The number of dimensions. Natts The number of attributes assigned to this variable. Dim A vector of the dimension IDs for the variable dimensions. Example See NCDF_VARDEF. NCDF_VARPUT [Previous Routine] [Next Routine] [List of Routines] NAME: NCDF_VARPUT The NCDF_VARPUT procedure writes a hyperslab of values to a netCDF variable. The netCDF file must be in data mode to use this procedure. Syntax NCDF_VARPUT, Cdfid, Varid, Value [, COUNT=vector] [, OFFSET=vector] [, STRIDE=vector] Arguments Cdfid The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE. Varid The netCDF variable ID, returned from a previous call to NCDF_VARDEF or NCDF_VARID, or the name of the variable. Value Data values to be written to the netCDF file. If the data type of Value does not match that of the netCDF variable, it is converted to the correct data type before writing. Value must have a dimensionality less than or equal to that of the variable being written. Keywords COUNT An optional vector containing the counts to be used in writing Value. COUNT is a 1- based vector with an element for each dimension of the data to be written. Note that counts do not have to match the dimensions of Value. The default count vector is the dimensionality of Value. OFFSET An optional vector containing the starting position to write. The default start position is [0, 0, ...]. STRIDE An optional vector containing the strides, or writing intervals, between written values of the netCDF variable. The default stride vector is that for a contiguous write, [1, 1, ...]. Example Suppose that you wish to create a 100x100 byte (0 & 1) checker board: ; Create offsets for even and odd rows: offset_even = [0,0] & offset_odd = [1,1] ; Create count and stride values: count = [50,50] & stride = [2,2] ; Make the "black" spaces of the checker board: black = BYTARR(50,50) > 1B ; Create the netCDF file: id = NCDF_CREATE('checker.nc', /CLOBBER) ; Fill the file with BYTE zeros: NCDF_CONTROL, id, /FILL ; Define the X dimension: xid = NCDF_DIMDEF(id, 'x', 100) ; Define the Y dimension: yid = NCDF_DIMDEF(id, 'y', 100) ; Define the Z dimension, UNLIMITED: zid = NCDF_DIMDEF(id, 'yy', /UNLIMITED) ; Define a variable with the name "board": vid = NCDF_VARDEF(id, 'board', [yid, xid], /BYTE) ; Rename 'yy' to 'z' as the zid dimension name: NCDF_DIMRENAME, id, zid, 'z' ; Put the file into data mode: NCDF_CONTROL, id, /ENDEF ; Use NCDF_DIMID and NCDF_DIMINQ to verify the name and size ; of the zid dimension: check_id = NCDF_DIMID(id,'z') NCDF_DIMINQ, id, check_id, dim_name, dim_size HELP, check_id, dim_name, dim_size IDL prints: CHECK_ID LONG = 2 DIM_NAME STRING = 'z' DIM_SIZE LONG = 0 Note that the DIM_SIZE is 0 because no records have been written yet for this dimension. NCDF_VARPUT, id, vid, black, $ COUNT=count, STRIDE=stride, OFFSET=offset_even NCDF_VARPUT, id, vid, black, $ COUNT=count, STRIDE=stride, OFFSET=offset_odd ; Get the full image: NCDF_VARGET, id, vid, output ; Create a window for displaying the image: WINDOW, XSIZE=100, YSIZE=100 ; Display the image: TVSCL, output ; Make stride larger than possible: stride = [2,3] ; As an experiment, attempt to write to an array larger than ; the one we previously allocated with NCDF_VARDEF: NCDF_VARPUT, id, vid, black, $ COUNT=count, STRIDE=stride, OFFSET=offset_odd IDL prints: % NCDF_VARPUT: Requested write is larger than the available data area. You will need to change the OFFSET/COUNT/STRIDE, or redefine the variable dimensions. You attempted to access 150 elements in a 100 array. NCDF_CLOSE, id ; Close the netCDF file. See Also NCDF_VARGET, NCDF_VARGET1, NCDF_VARID, NCDF_VARINQ NCDF_VARRENAME [Previous Routine] [Next Routine] [List of Routines] NAME: NCDF_VARRENAME The NCDF_VARRENAME procedure renames a netCDF variable. Syntax NCDF_VARRENAME, Cdfid, Varid, Name Arguments Cdfid The netCDF ID, returned from a previous call to NCDF_OPEN or NCDF_CREATE. Varid The netCDF variable ID, returned from a previous call to NCDF_VARDEF or NCDF_VARID, or the name of the variable. Name A scalar string containing the new name for the variable. Example See NCDF_VARDEF. IDLCOMIDISPATCH [Previous Routine] [Next Routine] [List of Routines] NAME: IDLcomIDispatch The IDLcomIDispatch object class creates a COM object that implements an IDispatch interface. Using the provided class or program ID, the underlying implementation will utilize the internal IDL COM sub-system to instantiate the desired COM object. Note IDL objects use method names to identify and call object life cycle methods (INIT and CLEANUP). As such, these method names should be considered reserved. If an underlying ActiveX or IDispatch object implements a method using either INIT or CLEANUP those methods will be overridden by the IDL life cycle methods and not accessible from IDL. Subclasses A dynamic sub-class of IDLcomIDispatch is created when the object is instantiated. A dynamic class name is created to provide a unique name for each component type, while providing the same super-class across all IDispatch components. Creation See IDLcomIDispatch::Init Methods * IDLcomIDispatch::Init * IDLcomIDispatch::GetProperty * IDLcomIDispatch::SetProperty IDLCOMIDISPATCH::INIT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLcomIDispatch::Init The IDLcomIDispatch::Init function method is used to initialize a given COM object and establish a link between the resulting IDL object and the IDispatch interface of the underlying COM object. Syntax Obj = OBJ_NEW('IDLcomIDispatch$$ID') Arguments None Class Names To ensure that each particular type of COM object has a unique IDL class type, the identifier for the underlying COM object is utilized to construct the IDL class name. Since two types of class identifiers exist in COM, those must also be indicted during this class construction process. With this in mind the following naming scheme was devised: $$ For IDispatch based objects, the class name takes the following form: Using a COM Class ID IDLcomIDispatch$CLSID$ Using a COM Program ID IDLcomIDispatch$PROGID$ Note All IDispatch based objects created in IDL sub-class from the intrinsic IDL class IDLcomIDispatch. The COM Class ID separator ( - ) or the Program ID separator ( . ) should be indicated using an underscore ( _ ) when constructing the class name for the particular object name. For example: If the CLSID of an object is: A77BC2B2-88EC-4D2A-B2B3-FS56ACB52ES2 then using IDLcomIDispatch to create an instance of the object would appear as: demobj = OBJ_NEW $ Note The curly braces ( {} ) for COM Class IDs should not be included in the name of the object. They are invalid characters for IDL Class names. IDLCOMIDISPATCH::GETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLcomIDispatch::GetProperty The IDLcomIDispatch::GetProperty function method is used to get properties for a particular IDispatch interface. The IDispatch property names are mapped to IDL keywords. The underlying property values are treated as IDL keyword values. This follows conventions set forth by other IDL objects. Note The provided keywords must map directly to a property name or an error will be thrown. Any keyword that is passed into either of the property routines is assumed to be a fully-qualified IDispatch property name. As such, the partial keyword name functionality provided by IDL is not valid with IDL COM based objects. Note Some getable properties require input parameters. As such, the GetProperty method can take parameters. If parameters are provided, only one property can be provided. Syntax IDLcomIDispatch -> GetProperty, = Value, [arg0, arg1, ...] Arguments Note Some IDLcomIDispatch GetProperty calls take arguments. The argument used, if any, is dependent on the individual property. IDLCOMIDISPATCH::SETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLcomIDispatch::SetProperty The IDLcomIDispatch::SetProperty function method is used to set properties for a particular IDispatch interface. The IDispatch property names are mapped to IDL keywords. The underlying property values are treated as IDL keyword values. This follows conventions set forth by other IDL objects. Note The provided keywords must map directly to a property name or an error will be thrown. Any keyword that is passed into either of the property routines is assumed to be a fully-qualified IDispatch property name. As such, the partial keyword name functionality provided by IDL is not valid with IDL COM based objects. Syntax IDLcomIDispatch -> SetProperty, = Value Arguments None IDLFFMRSID [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffMrSID An IDLffMrSID object class is used to query information about and load image data from a MrSID (.sid) image file. Superclasses This class has no superclasses. Subclasses This class has no subclasses. Creation See IDLffMrSID::Init Methods This class has the following methods: * IDLffMrSID::Cleanup * IDLffMrSID::GetDimsAtLevel * IDLffMrSID::GetImageData * IDLffMrSID::GetProperty * IDLffMrSID::Init IDLFFMRSID::CLEANUP [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffMrSID::Cleanup The IDLffMrSID::Cleanup procedure method deletes all MrSID objects, closing the MrSID file in the process. It also deletes the IDL objects used to communicate with the MrSID library. Syntax OBJ_DESTROY, Obj or Obj -> [IDLffMrSID::]Cleanup(Only in subclass' Cleanup method.) Arguments None. Keywords None. IDLFFMRSID::GETDIMSATLEVEL [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffMrSID::GetDimsAtLevel The IDLffMrSID::GetDimsAtLevel function method is used to retrieve the dimensions of the image at a given level. This can be used, for example, to determine what level is required to fit the image into a certain area. Syntax Dims = Obj -> [IDLMrSID::]GetDimsAtLevel ( Level ) Arguments Level Set this argument to a scalar integer that specifies the level at which the dimensions are to be determined. This level must be in the range returned by the LEVELS keyword of IDLffMrSID::GetProperty. Keywords None. Example PRO MrSID_GetDimsAtLevel ; Initialize the MrSID file object. oFile = OBJ_NEW('IDLffMrSID', FILEPATH('test_gs.sid', $ SUBDIRECTORY = ['examples', 'data'])) ; Get the range of levels of resolution contained within the file. oFile -> GetProperty, LEVELS = lvls PRINT, lvls ; IDL prints, -9, 4 ; Print the image dimensions at the lowest image resolution ; where image level = 4. imgLevelA = MAX(lvls) dimsAtA = oFile-> GetDimsAtLevel(imgLevelA) PRINT, 'Dimensions of lowest resolution image is', dimsAtA ;IDL prints, 32, 32 ; Print the image dimensions at full resolution ; where image level = 0 dimsAtFull = oFile -> GetDimsAtLevel(0) PRINT, 'Dimensions of full resolution image is', dimsAtFull ;IDL prints, 512, 512 ;Print the image dimensions at the highest resolution ; where image level = -9 highestLvl = MIN(lvls) dimsAtHighest = oFile -> GetDimsAtLevel(highestLvl) PRINT, 'Dimensions of highest resolution image is', dimsAtHighest ;IDL prints, 262144, 262144 ; Clean up object references. OBJ_DESTROY, [oFile] END IDLFFMRSID::GETIMAGEDATA [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffMrSID::GetImageData The IDLffMrSID::GetImageData function method extracts and returns the image data from the MrSID file at the specified level and location. Syntax ImageData = Obj->[IDLMrSID::]GetImageData ( [, LEVEL = lvl] [, SUB_RECT = rect] ) Return Value ImageData returns an n-by-w-by-h array containing the image data where n is 1 for grayscale or 3 for RGB images, w is the width and h is the height. Note The returned image is ordered bottom-up, the first pixel returned is located at the bottom-left corner of the image. This differs from how data is stored in the MrSID file where the image is top-down, meaning the pixel at the start of the file is located at the top-left corner of the image. Arguments None. Keywords LEVEL Set this keyword to an integer that specifies the level at which to read the image. If this keyword is not set, the maximum level is used which returns the minimum resolution (see the LEVELS keyword to IDLffMrSID::GetProperty). SUB_RECT Set this keyword to a four-element vector [x, y, xdim, ydim] specifying the position of the lower left-hand corner and the dimensions of the sub-rectangle of the MrSID image to return. This is useful for displaying portions of a high-resolution image. If this keyword is not set, the whole image will be returned. This may require significant memory if a high-resolution image level is selected. If the sub-rectangle is greater than the bounds of the image at the selected level the area outside the image bounds will be set to black. Note The elements of SUB_RECT are measured in pixels at the current level. This means the point x = 10, y = 10 at level 1 will be located at x = 20, y = 20 at level 0 and x = 5, y = 5 at level 2. Example PRO MrSID_GetImageData ; Initialize the MrSID file object. oFile = OBJ_NEW('IDLffMrSID', FILEPATH('test_gs.sid', $ SUBDIRECTORY = ['examples', 'data'])) ; Get the range of levels of resolution contained within the file. oFile -> GetProperty, LEVELS = lvls PRINT, lvls ; IDL prints, -9, 4 ; Get the image data at level 0. imgDataA = oFile -> GetImageData(LEVEL = 0) HELP, 'image array data at full resolution', imgDataA ;IDL prints, Array[1, 512, 512] indicating a grayscale 512 x 512 array. ; Display the full resolution image. oImgA = OBJ_NEW('IDLgrImage', imgDataA) oModelA = OBJ_NEW('IDLgrModel') oModelA -> Add, oImgA XOBJVIEW, oModelA, BACKGROUND = [0,0,0], $ TITLE = 'Full Resolution Image', /BLOCK ; Get the image data of a higher resolution image, imgDataB = oFile -> GetImageData(LEVEL = -2) HELP, imgDataB ; IDL returns [1,2048,2048] indicating a grayscale 2048 x 2048 array. ; To save processing time, display only a 1024 x 1024 portion of ; the high resolution, using 512,512 as the origin.. imgDataSelect = oFile -> GetImageData(LEVEL = -2,$ SUB_RECT = [512, 512, 1024, 1024]) oImgSelect = OBJ_NEW('IDLgrImage', imgDataSelect) oModel = OBJ_NEW('IDLgrModel') oModel -> Add, oImgSelect XOBJVIEW, oModel, BACKGROUND = [0,0,0], $ TITLE = 'Detail of High Resolution Image', /BLOCK ; Clean up object references. OBJ_DESTROY, [oFile, oImgA, oModelA, oImgSelect, oModel] END IDLFFMRSID::GETPROPERTY [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffMrSID::GetProperty The IDLffMrSID::GetProperty function method is used to query properties associated with the MrSID image. Syntax Obj->[IDLMrSID::]GetProperty [, CHANNELS=nChannels] [, DIMENSIONS=Dims] [, LEVELS=Levels] [, PIXEL_TYPE=pixelType] [, TYPE=strType] [, GEO_VALID=geoValid] [, GEO_PROJTYPE=geoProjType] [, GEO_ORIGIN=geoOrigin] [, GEO_RESOLUTION=geoRes] Arguments None. Keywords CHANNELS Set this keyword to a named variable that will contain the number of image bands. For RGB images this is 3, for grayscale it is 1. DIMENSIONS Set this keyword equal to a named variable that will contain a two-element long integer array of the form [width, height] that specifies the dimensions of the MrSID image at level 0 (full resolution). LEVELS Set this keyword equal to a named variable that will contain a two-element long integer array of the form [minlvl, maxlvl] that specifies the range of levels within the current image. Higher levels are lower resolution. A level of 0 equals full resolution. Negative values specify higher levels of resolution. PIXEL_TYPE Set this keyword to a named variable that will contain the IDL basic type code for a pixel sample. For a list of the data types indicated by each type code, see "IDL Type Codes" in the IDL Reference Guide. TYPE Set this keyword to a named variable that will contain a string identifying the file format. This should always be MrSID. GEO_VALID Set this keyword to a named variable that will contain a long integer that is set to: * 1 - If the MrSID image contains valid georeferencing data. * 0 - If the MrSID image does not contain georeferencing data or the data is in an unsupported format. Note Always verify that this keyword returns 1 before using the data returned by any other GEO_* keyword. GEO_PROJTYPE Set this keyword to a named variable that will contain an unsigned integer that specifies the geoTIFF projected coordinate system type code. For example, type code 32613 corresponds to PCS_WGS84_UTM_zone_13N. For more information on the geoTIFF file type and available type codes see: http://www.remotesensing.org/geotiff/geotiff.html GEO_ORIGIN Set this keyword to a named variable that will contain a two-element double precision array of the form [x, y] that specifies the location of the center of the upper- left pixel. GEO_RESOLUTION Set this keyword to a named variable that will contain a two-element double precision array of the form [xres, yres] that specifies the pixel resolution. Example PRO MrSID_GetProperty ; Initialize the MrSID object. oFile = OBJ_NEW('IDLffMrSID', FILEPATH('test_gs.sid', $ SUBDIRECTORY = ['examples', 'data'])) ; Get the property information of the MrSID file oFile -> GetProperty, CHANNELS = chan, LEVELS = $ lvls, Pixel_Type = pType, TYPE = fileType, GEO_VALID = geoQuery ; Print MrSID file information. PRINT, 'Number of image channels = ', chan ; IDL returns 1 indicating one image band. PRINT, 'Range of image levels = ', lvls ; IDL returns -9, 4, the minimum and maximum level values. PRINT, 'Type code of image pixels = ', pType ; IDL returns 1 indicating byte data type. PRINT, 'Image file type = ', FileType ; IDL returns "MrSID" PRINT, 'Result of georeferencing data query = ', geoQuery ; IDL returns 0 indicating that the image does not contain ; georeferencing data. ; Destroy object references. OBJ_DESTROY, [oFile] END IDLFFMRSID::INIT [Previous Routine] [Next Routine] [List of Routines] NAME: IDLffMrSID::Init The IDLffMrSID::Init function method initializes an IDLffMrSID object containing the image data from a MrSID image file. Syntax Result = OBJ_NEW(`IDLffMrSID', Filename [, /QUIET] ) Arguments Filename Set this argument to a scalar string containing the full path and filename of a MrSID file to be accessed through this IDLffMrSID object. Note This is a required argument; it is not possible to create an IDLffMrSID object without specifying a valid MrSID file. Keywords QUIET Set this keyword to suppress error messages while constructing the IDLffMrSID object. Example oMrSID = OBJ_NEW('IDLffMrSID', FILEPATH('test_gs.sid', $ SUBDIRECTORY = ['examples', 'data'])) CPU [Previous Routine] [Next Routine] [List of Routines] NAME: CPU The CPU procedure controls the way IDL uses the system processor for calculations. The results of using the CPU procedure are reflected in the state of the !CPU system variable. Syntax CPU [,TPOOL_MAX_ELTS = NumMaxElts] [,TPOOL_MIN_ELTS = NumMinElts] [,TPOOL_NTHREADS = NumThreads] [,/VECTOR_ENABLE] Keywords TPOOL_MAX_ELTS This keyword specifies the maximum number of data elements for computations that use the thread pool. This keyword changes the value returned by !CPU.TPOOL_MAX_ELTS. If the memory required for a given computation fits in physical memory, using the thread pool typically provides an increase in speed compared to the single-threaded case. However, once the computation exceeds the ability of the system's physical memory to contain it, use of the thread pool can be slower than the single-threaded case as the threads end up vying for access to system memory. If the system variable !CPU.TPOOL_MAX_ELTS is non-zero, IDL will not use the thread pool for any computation involving more than that number of elements. The default for this value is 0, meaning no imposed limit. TPOOL_MIN_ELTS This keyword sets the minimum number of data elements for a computation that are necessary before IDL will use the thread pool. For fewer than TPOOL_MIN_ELTS, the main IDL thread will perform the computation without using the thread pool. It is important not to use the thread pool for small tasks since the overhead of using the thread pool will not be offset by the overhead incurred by operation of the thread pool, and the performance of the computation will be slower than if the thread pool was not used. TPOOL_NTHREADS This keyword sets the number of threads that IDL will use in thread pool computations. The default is to use !CPU.HW_NCPU threads, so that each thread will have the potential to run in parallel with the others. If you set TPOOL_NTHREADS to 0, !CPU.HW_NCPU threads will be used. Setting this keyword to 1 disables threading. For numerical computation, there is no benefit to using more threads than your system has CPUs. However, depending on the size of the problem and the number of other programs running on the system, there may be a performance advantage to using fewer CPUs. VECTOR_ENABLE Set this keyword to enable use of the system's vector unit (e.g. Macintosh Altivec/Velocity Engine). Set it to zero to disable such use. This keyword is ignored if the current system does not support a vector unit, which can be determined by the value of the !CPU.HW_VECTOR system variable. Example In the following example, we will: * Save the current thread pool settings from the !CPU system environment variable. * Modify the thread pool settings so that IDL is configured, for our particular system, to efficiently perform a floating point computation. * Perform a floating point computation. * Modify the thread pool settings so that IDL is configured, for our particular system, to efficiently perform a double precision computation. * Perform a double precision computation. * Restore the thread pool settings to their original values. The first computation will use the thread pool since it does not exceed any of the specified parameters. The second computation, since it exceeds the maximum number of data elements, will not use the thread pool: ; Retrieve the current thread pool settings. threadpool = !CPU ; Modify the thread pool settings. CPU, TPOOL_MAX_ELTS = 1000000, TPOOL_MIN_ELTS = 50000, $ TPOOL_NTHREADS = 2 ; Create 65,341 elements of floating point data. theta = FINDGEN(361, 181) ; Perform computation, using 2 threads. sineSquared = 1. - (COS(!DTOR*theta))^2 ; Modify thread pool settings for new data type. CPU, TPOOL_MAX_ELTS = 50000, TPOOL_MIN_ELTS = 10000 ; Create 65,341 elements of double precision data theta = DINDGEN(361, 181) ; Perform computation. sineSquared = 1. - (COS(!DTOR*theta))^2 ;Return thread pool settings to their initial values. CPU, TPOOL_MAX_ELTS = threadpool.TPOOL_MAX_ELTS, $ TPOOL_MIN_ELTS = threadpool.TPOOL_MIN_ELTS, $ TPOOL_NTHREADS = threadpool.HW_NCPU See Also !CPU DEFINE_MSGBLK [Previous Routine] [Next Routine] [List of Routines] NAME: DEFINE_MSGBLK The DEFINE_MSGBLK procedure defines and loads a new message block into the currently running IDL session. Once loaded, the MESSAGE procedure can be used to issue messages from this block. A message block is a collection of messages that are loaded into IDL as a single unit. Each block contains the messages required for a specific application. At startup, IDL contains a single internal message block named IDL_MBLK_CORE, which contains the standard messages required by the IDL system. Dynamically loadable modules (DLMs) usually define additional message blocks for their own needs when they are loaded. At the IDL programming level, the DEFINE_MSGBLK or DEFINE_MSGBLK_FROM_FILE procedures can be used to define message blocks. You can use the HELP, /MESSAGES command to see the currently defined message blocks. Syntax DEFINE_MSGBLK, BlockName, ErrorNames, ErrorFormats [,/IGNORE_DUPLICATE] [,PREFIX = PrefixStr] Arguments BlockName A string giving the name of the message block to be defined. Block names must be unique within the IDL system. We recommend that you follow the advice given in "Advice for Library Authors" in Chapter 12 of the Building IDL Applications manual when selecting this name in order to avoid name conflicts. Use of the PREFIX keyword is also recommended to enforce a consistent naming convention. ErrorNames An array of strings giving the names of the messages to be defined with the message block. ErrorFormats An array of strings giving the formats for the messages to be defined with the message block. Each format is matched with the corresponding name in ErrorNames. For this reason, ErrorFormats should have the same number of elements as ErrorNames. We recommend the use of the PREFIX keyword to enforce a consistent naming scheme for your messages. Error formats are simplified printf-style format strings. For more information on format strings, see "C printf-Style Quoted String Format Code" in Chapter 8 of the Building IDL Applications manual. Keywords IGNORE_DUPLICATE Attempts to define a given BlockName more than once in the same IDL session usually cause DEFINE_MSGBLK to issue an error and stop execution of the IDL program. Specify IGNORE_DUPLICATE to cause DEFINE_MSGBLK to quietly ignore attempts to redefine a message block. In this case, no error is issued and execution continues. The original message block remains installed and available for use. PREFIX It is a common and recommended practice to give each message name defined in ErrorNames a common unique prefix that identifies it as an error from a specific message block. However, specifying this prefix in each entry of ErrorNames is tedious and error prone. The PREFIX keyword can be used to specify a prefix string that will be added to each element of ErrorNames. Example This example defines a message block called ROADRUNNER that contains 2 messages: name = ['BADPLAN', 'RRNOTCAUGHT'] fmt = ['Bad plan detected: %s.', 'Road Runner not captured.'] DEFINE_MSGBLK, prefix = 'ACME_M_', 'ROADRUNNER', name, fmt Once this message block is loaded, the ACME_M_BADPLAN message can be issued using the following statement: MESSAGE, NAME = 'acme_m_badplan', BLOCK = 'roadrunner', $ 'Exploding bridge while standing underneath' This MESSAGE statement produces the output similar to: % Bad plan detected: Exploding bridge while standing underneath. % Execution halted at: $MAIN$ The IDL command: HELP, /STRUCTURES, !ERROR_STATE can be used to examine the effect of this message on IDL's error state. See Also DEFINE_MSGBLK_FROM_FILE, MESSAGE DEFINE_MSGBLK_FROM_FILE [Previous Routine] [Next Routine] [List of Routines] NAME: DEFINE_MSGBLK_FROM_FILE The DEFINE_MSGBLK_FROM_FILE procedure reads the definition of a message block from a file, and uses DEFINE_MSGBLK to load it into the currently running IDL session. Once loaded, the MESSAGE procedure can be used to issue messages from this block. DEFINE_MSGBLK_FROM_FILE can be more convenient than DEFINE_MSGBLK for large message blocks. This routine is written in the IDL language. Its source code can be found in the file define_msgblk_from_file.pro in the lib subdirectory of the IDL distribution. Syntax DEFINE_MSGBLK_FROM_FILE, Filename [,BLOCK = BlockName] [, /IGNORE_DUPLICATE] [,PREFIX = PrefixStr] [,/VERBOSE] Arguments Filename The name of the file containing the message block definition. The contents of this file must be formatted as described in the section "Format of Message Definition Files" which follows. Keywords BLOCK If present, specifies the name of the message block. Normally, this keyword is not specified, and an @IDENT line in the message file specifies the name of the block. We recommend that you follow the advice given in "Advice for Library Authors" in Chapter 12 of the Building IDL Applications manual when selecting this name in order to avoid name clashes. Use of a prefix is also recommended to enforce a consistent naming convention. IGNORE_DUPLICATE Attempts to define a given BlockName more than once in the same IDL session usually cause DEFINE_MSGBLK to issue an error and stop execution of the IDL program. Specify IGNORE_DUPLICATE to cause DEFINE_MSGBLK to quietly ignore attempts to redefine a message block. In this case, no error is issued and execution continues. The original message block remains installed and available for use. PREFIX If present, specifies a prefix string to be applied to the beginning of each message name in the message block. Normally, this keyword is not specified, and an @PREFIX line in the message file specifies the prefix string. We recommend the use of a prefix to enforce a consistent naming scheme for your messages. VERBOSE If set, causes DEFINE_MSGBLK_FROM_FILE to print informational messages describing the message block loaded. Format of Message Definition Files A message definition file has a simple structure designed to ease the specification of message blocks. Any line starting with the character @ specifies information about the message block. Any line not starting with an @ character is ignored, and can be used for comments, documentation, notes, or other human readable information. All such text is ignored by DEFINE_MSGBLK_FROM_FILE. There are three different types of lines starting with @ allowed in a message definition file: @IDENT name Specifies the name of the message block being defined. There should be exactly one such line in every message definition file. If the BLOCK keyword to DEFINE_MSGBLK_FROM_FILE is specified, the @IDENT line is ignored and can be omitted. RSI recommends always specifying an @IDENT line. @PREFIX PrefixStr If present, specifies a prefix string to be applied to the beginning of each message name in the message block. There should be at most one such line in every message definition file. If the PREFIX keyword to DEFINE_MSGBLK_FROM_FILE is specified, the @PREFIX line is ignored and can be omitted. RSI recommends always specifying an @PREFIX line. @ MessageName MessageFormat Specifies a single message name and format string pair. The format string should be delimited with double quotes. A message definition file should contain one such line for every message it defines. Example The following example uses the same message block as in the example given for "DEFINE_MSGBLK" on page 197, but uses a message definition file to create the message block. The first step is to create a message definition file called roadruner.msg containing the following lines: ; Message definition file for ROADRUNNER message block @IDENT roadrunner @PREFIX ACME_M_ @ BADPLAN "Bad plan detected: %s." @ RRNOTCAUGHT "Road Runner not captured." If you are currently in IDL, exit out and restart. Then, within IDL, you can use the following statement to load in the message block: DEFINE_MSGBLK_FROM_FILE, 'roadrunner.msg' Once this message block is loaded, the ACME_M_BADPLAN message can be issued using the following statement: MESSAGE, NAME = 'acme_m_badplan', BLOCK='roadrunner', $ 'Exploding bridge while standing underneath' This MESSAGE statement produces the output similar to: % Bad plan detected: Exploding bridge while standing underneath. % Execution halted at: $MAIN$ The IDL command: HELP, /STRUCTURES, !ERROR_STATE can be used to examine the effect of this message on IDL's error state. See Also DEFINE_MSGBLK, MESSAGE ERF [Previous Routine] [Next Routine] [List of Routines] NAME: ERF The ERF function returns the value of the error function: x erf x ( ) 2 = ------- e t2 ­ t d 0 The result is double-precision if the argument is double-precision, otherwise the result is floating-point. The result always has the same structure as X. The ERF function does not work with complex arguments. Syntax Result = ERF(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, ERF(0.4D) IDL prints: 0.42839236 See Also ERFC, ERFCX, GAMMA, IGAMMA, EXPINT ERFC [Previous Routine] [Next Routine] [List of Routines] NAME: ERFC The ERFC function returns the value of the complimentary error function: erfc(x) = 1 ­ erf(x) 2 = ------- e t22 ­ t d x The result is double-precision if the argument is double-precision, otherwise the result is floating-point. The result always has the same structure as X. The ERFC function does not work with complex arguments. Syntax Result = ERFC(X) Arguments X The expression for which the complimentary error function is to be evaluated. Example To find the complimentary error function of 0.4 and print the result, enter: PRINT, ERFC(0.4D) IDL prints: 0.57160764 See Also ERF, ERFCX ERFCX [Previous Routine] [Next Routine] [List of Routines] NAME: ERFCX The ERFCX function returns the value of the scaled complimentary error function: erfcx x ( ) = ex2erfc(x) The result is double-precision if the argument is double-precision, otherwise the result is floating-point. The result always has the same structure as X. The ERFCX function does not work with complex arguments. Syntax Result = ERFCX(X) Arguments X The expression for which the complimentary error function is to be evaluated. Example To find the scaled complimentary error function of 0.4 and print the result, enter: PRINT, ERFCX(0.4D) IDL prints: 0.67078779 See Also ERF, ERFC FILE_INFO [Previous Routine] [Next Routine] [List of Routines] NAME: FILE_INFO The FILE_INFO function returns status information about a specified file. Syntax Result = FILE_INFO(Path, /NOEXPAND_PATH) Return Value The FILE_INFO function returns a structure expression of type FILE_INFO containing status information about a specified file or files. The result will contain one structure for each input element. Fields of the FILE_INFO Structure The following descriptions are of fields in the structure returned by the FILE_INFO function. They are not keywords to FILE_INFO. * NAME - The name of the file. * EXISTS - True (1) if the file exists. False (0) if it does not exist. * READ - True (1) if the file is exists and is readable by the user. False (0) if it is not readable. * WRITE - True (1) if the file exists and is writable by the user. False (0) if it is not writable. * EXECUTE - True (1) if the file exists and is executable by the user. False (0) if it is not executable. The source of this information differs between operating systems: UNIX and VMS: IDL checks the per-file information (the execute bit) maintained by the operating system. Microsoft Windows: The determination is made on the basis of the file name extension (e.g. .exe). Macintosh: Files of type APPL (proper applications) are reported as executable; this corresponds to Double Clickable applications. * REGULAR - True (1) if the file exists and is a regular disk file and not a directory, pipe, socket, or other special file type. False (0) if it is not a regular disk file (it maybe a directory, pipe, socket, or other special file type). * DIRECTORY - True (1) if the file exists and is a directory. False (0) if it is not a directory. * BLOCK_SPECIAL - True (1) if the file exists and is a UNIX block special device. On non-UNIX operating systems, this field will always be False (0). * CHARACTER_SPECIAL - True (1) if the file exists and is a UNIX character special device. On non-UNIX operating systems, this field will always be False (0). * NAMED_PIPE - True (1) if the file exists and is a UNIX named pipe (fifo) device. On non-UNIX operating systems, this field will always be False (0). * SETGID - True (1) if the file exists and has its Set-Group-ID bit set. On non- UNIX operating systems, this field will always be False (0). * SETUID - True (1) if the file exists and has its Set-User-ID bit set. On non- UNIX operating systems, this field will always be False (0). * SOCKET - True (1) if the file exists and is a UNIX domain socket. On non- UNIX operating systems, this field will always be False (0). * STICKY_BIT - True (1) if the file exists and has its sticky bit set. On non- UNIX operating systems, this field will always be False (0). * SYMLINK - True (1) if the file exists and is a UNIX symbolic link. On non- UNIX operating systems, this field will always be False (0). * DANGLING_SYMLINK - True (1) if the file exists and is a UNIX symbolic link that points at a non-existent file. On non-UNIX operating systems, this field will always be False (0). * ATIME, CTIME, MTIME - The date of last access, date of creation, and date of last modification given in seconds since 1 January 1970 UTC. Use the SYSTIME function to convert these dates into a textual representation. Note Some file systems do not maintain all of these dates (e.g. MS DOS FAT file systems), and may return 0. On some non-UNIX operating systems, access time is not maintained, and ATIME and MTIME will always return the same date. * SIZE - The current length of the file in bytes. If Path is not to a regular file (possibly to a directory, pipe, socket, or other special file type), the value of SIZE will not contain any useful information. Arguments Path The path of the file about which information is required. This parameter can be a scalar or array of type string. Keywords NOEXPAND_PATH If specified, FILE_INFO uses Path exactly as specified, without applying the usual file path expansion. Examples To get information on the file dist.pro within the IDL User Library: HELP,/STRUCTURE, FILE_INFO(FILEPATH('dist.pro', $ SUBDIRECTORY = 'lib')) Executing the above command will produce output similar to: ** Structure FILE_INFO, 21 tags, length=72: NAME STRING '/usr/local/rsi/idl/lib/dist.pro' EXISTS BYTE 1 READ BYTE 1 WRITE BYTE 0 EXECUTE BYTE 0 REGULAR BYTE 1 DIRECTORY BYTE 0 BLOCK_SPECIAL BYTE 0 CHARACTER_SPECIALBYTE 0 NAMED_PIPE BYTE 0 SETGID BYTE 0 SETUID BYTE 0 SOCKET BYTE 0 STICKY_BIT BYTE 0 SYMLINK BYTE 0 DANGLING_SYMLINKBYTE 0 MODE LONG 420 ATIME LONG64 970241431 CTIME LONG64 970241595 MTIME LONG64 969980845 SIZE LONG64 1717 See Also FILE_TEST, FSTAT FILE_SEARCH [Previous Routine] [Next Routine] [List of Routines] NAME: FILE_SEARCH The FILE_SEARCH function returns a string array containing the names of all files matching the input path specification. Input path specifications may contain wildcard characters, enabling them to match multiple files. All matched filenames are returned in a string array, one file name per array element. If no files exist with names matching the input arguments, a null scalar string is returned instead of a string array. FILE_SEARCH has the ability to perform standard, or recursive searching: * Standard: When called with a single Path_Specification argument, FILE_SEARCH returns all files that match that specification. This is the same operation, sometimes referred to as file globbing, performed by most operating system command interpreters when wildcard characters are used in file specifications. * Recursive: When called with two arguments, FILE_SEARCH performs recursive searching of directory hierarchies. In a recursive search, FILE_SEARCH looks recursively for any and all subdirectories in the file hierarchy rooted at the Dir_Specification argument. Within each of these subdirectories, it returns the names of all files that match the pattern in the Recur_Pattern argument. This operation is similar to that performed by the UNIX find(1) command. Note To avoid going into an infinite loop, the FILE_SEARCH routine does not search for files designated by symbolic links. A relative path is a file path that can only be unambiguously interpreted by basing it relative to some other known location. Usually, this location is the current working directory for the process. A fully qualified path is a complete and unambiguous path that can be interpreted directly. For example, bin/idl is a relative path, while /usr/local/rsi/idl/bin/idl is a fully qualified path. By default, FILE_SEARCH follows the format of the input to decide the form of returned paths. If the input is relative, the results will be relative. If the input is fully qualified, the results will also be fully qualified. If you specify the FULLY_QUALIFY_PATH keyword, the results will be fully qualified no matter which form of input is used. The wildcards understood by FILE_SEARCH are based on those used by standard UNIX tools. They are described in the "Supported Wildcards and Expansions" on page 218. Note Research Systems strongly recommends the FILE_SEARCH function be used rather than the FINDFILE function. FILE_SEARCH is ultimately intended as a replacement for FINDFILE. Syntax Result = FILE_SEARCH(Path_Specification) or for recursive searching, Result = FILE_SEARCH(Dir_Specification, Recur_Pattern) Keywords: [, COUNT=variable ] [, /EXPAND_ENVIRONMENT ] [, /EXPAND_TILDE ] [, /FOLD_CASE ] [, /FULLY_QUALIFY_PATH ] [, /ISSUE_ACCESS_ERROR ] [, /MARK_DIRECTORY ] [, /MATCH_INITIAL_DOT | /MATCH_ALL_INITIAL_DOT ] [, /NOSORT ] [, /QUOTE ] [, /TEST_DIRECTORY ] [, /TEST_EXECUTABLE ] [, /TEST_READ ] [, /TEST_REGULAR ] [, /TEST_WRITE ] [, /TEST_ZERO_LENGTH ] UNIX-Only Keywords: [, /TEST_BLOCK_SPECIAL ] [, /TEST_CHARACTER_SPECIAL ] [, /TEST_DANGLING_SYMLINK ] [, /TEST_GROUP ] [, /TEST_NAMED_PIPE ] [, /TEST_SETGID ] [, /TEST_SETUID ] [, /TEST_SOCKET ] [, /TEST_STICKY_BIT ] [, /TEST_SYMLINK ] [, /TEST_USER ] Arguments Any of the arguments described in this section can contain wildcard characters, as described in the Supported Wildcards and Expansions section below. Path_Specification A scalar or array variable of string type, containing file paths to match. If Path_Specification is not supplied, or if it is supplied as a null string, FILE_SEARCH uses a default pattern of * and matches all files in the current directory. Dir_Specification A scalar or array variable of string type, containing directory paths within which FILE_SEARCH will perform recursive searching for files matching the Recur_Pattern argument. FILE_SEARCH examines Dir_Specification, and any directory found below it, and returns the paths of any files in those directories that match Recur_Pattern. If Dir_Specification is supplied as a null string, FILE_SEARCH searches the current directory. Recur_Pattern A scalar string containing a pattern for files to match in any of the directories specified by the Dir_Specification argument. If Recur_Pattern is supplied as a null string, FILE_SEARCH uses a default pattern of * and matches all files in the specified directories. Keywords COUNT A named variable into which the number of files found is placed. If no files are found, a value of 0 is returned. EXPAND_ENVIRONMENT By default, FILE_SEARCH follows the conventions of the underlying operating system to determine if it expands environment variable references in input file specification patterns. The default is to do such expansions under UNIX, and not to do them on the Macintosh or Microsoft Windows. The EXPAND_ENVIRONMENT keyword is used to change this behavior. Set it to a non-zero value to cause FILE_SEARCH to perform environment variable expansion on all platforms. Set it to zero to disable such expansion. Note Macintosh users should note that the Macintosh operating system does not support the concept of an environment, and as such, environment variable expansion is likely to be of little use. One significant exception to this is to use the IDL_TMPDIR environment variable to generate paths to temporary files. See the description of the GETENV function for further details. The syntax for expanding environment variables in an input file pattern is based on that supported by the standard UNIX shell (/bin/sh), as described in the Supported Wildcards and Expansions section below. EXPAND_TILDE Users of the UNIX C-shell (/bin/csh), and other tools influenced by it, are familiar with the use of a tilde (~) character at the beginning of a path to denote a home directory. A tilde by itself at the beginning of the path (e.g. ~/directory/file) is equivalent to the home directory of the user executing the command, while a tilde followed by the name of a user (e.g. ~user/directory/file) is expanded to the home directory of the named user. By default, FILE_SEARCH follows the conventions of the underlying operating system in deciding whether to expand a leading tilde or to treat it as a literal character. Hence, the default is to expand them under UNIX, and not on Macintosh or Microsoft Windows. The EXPAND_TILDE keyword is used to change this behavior. Set it to zero to disable tilde expansion on all platforms. Set it to a non-zero value to enable tilde expansion. Note Microsoft Windows users should note that only the plain form of tilde is recognized by Windows IDL. Attempts to use the ~user form will cause IDL to issue an error. IDL uses the HOME and HOMEPATH environment variables to obtain a home directory for the current Windows user. Note Macintosh users should note that the FILE_SEARCH quietly ignores the EXPAND_TILDE keyword. There is no support for tilde expansion on that platform. FOLD_CASE By default, FILE_SEARCH follows the case sensitivity policy of the underlying operating system. Matches are case sensitive on UNIX platforms, and case insensitive on Macintosh and Microsoft Windows platforms. The FOLD_CASE keyword is used to change this behavior. Set it to a non-zero value to cause FILE_SEARCH to do all file matching case insensitively. Set to zero to cause all file matching to be case sensitive. FULLY_QUALIFY_PATH If set, FILE_SEARCH expands all returned file paths so that they are complete. Under UNIX, this means that all files are specified relative to the root of the file system. On Macintosh and Windows platforms, it means that all files are specified relative to the Drive/Volume on which they are located. By default, FILE_SEARCH returns fully qualified paths when the input specification is fully qualified, and returns relative paths otherwise. For example: CD, '/usr/local/rsi/idl/bin' PRINT, FILE_SEARCH('idl') idl PRINT, FILE_SEARCH('idl',/FULLY_QUALIFY_PATH) /usr/local/rsi/idl/bin/idl Under Microsoft Windows, any use of a drive letter colon (:) character implies full qualification, even if the path following the colon does not start with a slash character. ISSUE_ACCESS_ERROR If the IDL process lacks the necessary permission to access a directory included in the input specification, FILE_SEARCH will normally skip over it quietly and not include it in the generated results. Set ISSUE_ACCESS_ERROR to cause an error to be issued instead. MARK_DIRECTORY If set, all directory paths are returned with a path separator character appended to the end. This allows the caller to concatenate a file name directly to the end without having to supply a separator character first. This is convenient for cross-platform programming, as the separator characters differ between operating systems: PRINT, FILE_SEARCH(!DIR) /usr/local/rsi/idl PRINT, FILE_SEARCH(!DIR, /MARK_DIRECTORY) /usr/local/rsi/idl/ MATCH_ALL_INITIAL_DOT By default, wildcards do not match leading dot (.) characters, and FILE_SEARCH does not return the names of files that start with the dot (.) character unless the leading dot is actually contained within the search string. Set MATCH_ALL_INITIAL_DOT to change this policy so that wildcards will match all files starting with a dot, including the special "." (current directory) and ".." (parent directory) entries. RSI recommends the use of the MATCH_INITIAL_DOT keyword instead of MATCH_ALL_INITIAL_DOT for most purposes. MATCH_INITIAL_DOT MATCH_INITIAL_DOT serves the same function as MATCH_ALL_INITIAL_DOT, except that the special "." (current directory) and ".." (parent directory) directories are not included. NOSORT If set, FILE_SEARCH will not sort the resulting files. On some operating systems, particularly UNIX, this can make FILE_SEARCH execute faster. By default, FILE_SEARCH sorts the results from each element of the input file specification together, and places the results from each input element into the result in the order they are found. Hence, the statement: Result = FILE_SEARCH(['*.c', '*.h']) returns all of the C files in the current directory in lexical order, followed by all of the H files, also sorted lexically among themselves. In contrast, the statement: Result = FILE_SEARCH('*.[ch]') returns all of the C and H files sorted together into lexical order. This version is more efficient that the previous one, because the directory is only searched once. QUOTE FILE_SEARCH usually treats all wildcards found in the input specification as having the special meanings described in "Supported Wildcards and Expansions" on page 218. This means that such characters cannot normally be used as plain literal characters in file names. For example, it is not possible to match a file that contains a literal asterisk character in its name because asterisk is interpreted as the "match zero or more characters" wildcard. If the QUOTE keyword is set, the backslash character can be used to escape any character so that it is treated as a plain character with no special meaning. In this mode, FILE_SEARCH replaces any two character sequence starting with a backslash with the second character of the pair. In the process, any special wildcard meaning that character might have had disappears, and the character is treated as a literal. If QUOTE is set, any literal backslash characters in your path must themselves be escaped with a backslash character. This is especially important for Microsoft Windows users, because the directory separator character for that platform is the backslash. Windows IDL also accepts UNIX-style forward slashes for directory separators, so Windows users have two choices in handling this issue: Result = FILE_SEARCH('C:\\home\\bob\\\*.dat', /QUOTE) Result = FILE_SEARCH('C:/home/bob/\*.dat', /QUOTE) TEST_DIRECTORY Only include a matching file if it is a directory. TEST_EXECUTABLE Only include a matching file if it is executable. The source of this information differs between operating systems: UNIX: IDL checks the per-file information (the execute bit) maintained by the operating system. Microsoft Windows: The determination is made on the basis of the file name extension (e.g. .exe). Macintosh: Files of type APPL (proper applications) are reported as executable; this corresponds to double-clickable applications. TEST_READ Only include a matching file if it is readable by the user. Note This keyword does not support Access Control Listing (ACL) settings for files. TEST_REGULAR Only include a matching file if it is a regular disk file and not a directory, pipe, socket, or other special file type. TEST_WRITE Only include a matching file if it is writable by the user. Note This keyword does not support Access Control Listing (ACL) settings for files. TEST_ZERO_LENGTH Only include a matching file if it has zero length. Note The length of a directory is highly system dependent and does not necessarily correspond to the number of files it contains. In particular, it is possible for an empty directory to report a non-zero length. RSI does not recommend using the TEST_ZERO_LENGTH keyword on directories, as the information returned cannot be used in a meaningful way. UNIX-Only Keywords TEST_BLOCK_SPECIAL Only include a matching file if it is a block special device. TEST_CHARACTER_SPECIAL Only include a matching file if it is a character special device. TEST_DANGLING_SYMLINK Only include a matching file if it is a symbolic link that points at a non-existent file. TEST_GROUP Only include a matching file if it belongs to the same effective group ID (GID) as the IDL process. TEST_NAMED_PIPE Only include a matching file if it is a named pipe (fifo) device. TEST_SETGID Only include a matching file if it has its Set-Group-ID bit set. TEST_SETUID Only include a matching file if it has its Set-User-ID bit set. TEST_SOCKET Only include a matching file if it is a UNIX domain socket. TEST_STICKY_BIT Only include a matching file if it has its sticky bit set. TEST_SYMLINK Only include a matching file if it is a symbolic link that points at an existing file. TEST_USER Only include a matching file if it belongs to the same effective user ID (UID) as the IDL process. Supported Wildcards and Expansions The wildcards understood by FILE_SEARCH are based on those used by the standard UNIX shell /bin/sh (*?[], environment variables) with some enhancements commonly found in the C-shell /bin/csh (~ and {}). These wildcards are processed identically across all IDL supported platforms. The supported wildcards are shown in the following table: Wildcard Description * Matches any string, including the null string. ? Matches any single character. [...] Matches any one of the enclosed characters. A pair of characters separated by "-" matches any character lexically between the pair, inclusive. If the first character following the opening bracket ( [ ) is a ! or ^, any character not enclosed is matched. {str, str, ...} Expand to each string (or filename-matching pattern) in the comma-separated list. ~ If used at start of input file specification, is replaced with the ~user path to the appropriate home directory. See the description of the EXPAND_TILDE keyword for details. $var Replace with value of named environment variable. See the description of the EXPAND_ENVIRONMENT keyword for full details. ${var} Replace ${var} with the value of the var environment variable. If var is not found in the environment, ${var} is replaced with a null string. This format is useful when the environment variable reference sits directly next to unrelated text, as the use of the {} brackets make it possible for IDL to determine where the environment variable ends and the remaining text starts (e.g. ${mydir} other text). ${var:-alttext} If environment variable var is present in the environment and has a non-NULL value, then substitute that value. If var is not present, or has a NULL value, then substitute the alternative text (alttext) provided instead. Table 6-1: Supported Wildcards and Expansions Wildcard Description ${var-alttext} If environment variable var is present in the environment (even if it has a NULL value) then substitute that value. If var is not present, then substitute the alternative text (alttext) provided instead. Table 6-1: Supported Wildcards and Expansions (Continued) These wildcards can appear anywhere in an input file specification, with the following exceptions: Tilde (~) The tilde character is only considered to be a wildcard if it is the first character in the input file specification, and only if allowed by the EXPAND_TILDE keyword. Otherwise, it is treated as a regular character. Microsoft Windows UNC Paths On a local area network, Microsoft Windows offers an alternative to the drive letter syntax for accessing files. The Universal Naming Convention allows specifying paths on other hosts, using the syntax: \\hostname\sharename\dir\dir\Z...\file UNC paths are distinguished from normal paths by the use of two initial slashes in the path. FILE_SEARCH can process such paths, but wildcard characters are not allowed in the hostname or sharename segments. Wildcards are allowed for specifying directories and files. For performance reasons, RSI does not recommend using the recursive form of FILE_SEARCH with UNC paths on very large directory trees. When using FILE_SEARCH, you should be aware of the following issues: Initial Dot Character The default is for wildcards not to match the dot (.) character if it occurs as the first character of a directory or file name. This follows the convention of UNIX shells, which treat such names as hidden files. In order to match such files, you can take any of the following actions: * Explicitly include the dot character at the start of your pattern (e.g. ".*"). * Specify the MATCH_INITIAL_DOT keyword, which changes the dot matching policy so that wildcards will match any names starting with dot (except for the special "." and ".." directories). * Specify the MATCH_ALL_INITIAL_DOT keyword, which changes the dot matching policy so that wildcards will match any names starting with dot (including the special "." and ".." directories). File Path Syntax The syntax allowed for file paths differs between operating systems. FILE_SEARCH always processes file paths using the syntax rules for the platform on which the IDL session is running. As a convenience for Microsoft Windows users, Windows IDL accepts UNIX style forward slashes as well as the usual backslashes as path separators. Differing Defaults Between Platforms The different operating systems supported by IDL have some conventions for processing file paths that are inherently incompatible. If FILE_SEARCH attempted to force an identical default policy for these features across all platforms, the resulting routine would be inconvenient to use on all platforms. FILE_SEARCH resolves this inherent tension between convenience and control in the following way: * These features are controlled by keywords which are listed in the table below. If a keyword is not explicitly specified, FILE_SEARCH will determine an appropriate default for that feature based on the conventions of the underlying operating system. Hence, FILE_SEARCH will by default behave in a way that is reasonable on the platform it is used on. * If one of these keywords is explicitly specified, FILE_SEARCH will use its value to determine support for that feature. Hence, if the keyword is used, FILE_SEARCH will behave identically on all platforms. If maximum cross- platform control is desired, you can achieve it by specifying all the relevant keywords. The keywords that have different defaults on different platforms are listed in the following table: Wildcard Keyword Default Default Default Mac UNIX Win $var ${var} EXPAND_ENVIRONMENT no yes no ${var:-alttext} ${var-alttext} ~ EXPAND_TILDE no yes no FOLD_CASE yes no yes Table 6-2: Differing Defaults on Different Platforms TEST_* Keywords The keywords with names that start with the TEST_ prefix allow you to filter the list of resulting file paths based on various criteria. If you remove the TEST_ prefix from these keywords, they correspond directly to the same keywords to the FILE_TEST function, and are internally implemented by the same test code. One could therefore use FILE_TEST instead of the TEST_ keywords to FILE_SEARCH. For example, the following statement locates all subdirectories of the current directory: Result = FILE_SEARCH(/TEST_DIRECTORY) It is equivalent to the following statements, using FILE_TEST: result = FILE_SEARCH() idx = where(FILE_TEST(result, /DIRECTORY), count) result = (count eq 0) ? '' : result[idx] The TEST_* keywords are more succinct, and can be more efficient in the common case in which FILE_SEARCH generates a long list of results, only to have FILE_TEST discard most of them. Examples Example 1 Find all files in the current working directory: Result = FILE_SEARCH() Example 2 Find all IDL program (*.pro) files in the current working directory: Result = FILE_SEARCH('*.pro') Example 3 Under Microsoft Windows, find all files in the top level directories of all drives other than the floppy drives: Result=FILE_SEARCH('[!ab]:*') This example relies on the following: * FILE_SEARCH allows wildcards within the drive letter part of an input file specification. * Drives A and B are always floppies, and are not used by Windows for any other type of drive. Example 4 Find all files in the user's home directory that start with the letters A-D. Match both upper and lowercase letters: Result = FILE_SEARCH('~/[a-d]*', /EXPAND_TILDE, /FOLD_CASE) Example 5 Find all directories in the user's home directory that start with the letters A-D. Match both upper and lowercase letters: Result = FILE_SEARCH('~/[a-d]*', /EXPAND_TILDE, /FOLD_CASE, $ /TEST_DIRECTORY) Example 6 Recursively find all subdirectories found underneath the user's home directory that do not start with a dot character: Result = FILE_SEARCH('$HOME', '*', /EXPAND_ENVIRONMENT, $ /TEST_DIRECTORY) Example 7 Recursively find all subdirectories found underneath the user's home directory, including those that start with a dot character, but excluding the special "." and ".." directories: Result = FILE_SEARCH('$HOME', '*', /MATCH_INITIAL_DOT, $ /EXPAND_ENVIRONMENT, /TEST_DIRECTORY) Example 8 Find all .pro and .sav files in a UNIX IDL library search path, sorted by directory, in the order IDL searches for them: Result = FILE_SEARCH(STRSPLIT(!PATH, ':', /EXTRACT) + $ '/*.{pro,sav}') Colon (:) is the UNIX path separator character, so the call to STRSPLIT breaks the IDL search path into an array of directories. To each directory name, we concatenate the wildcards necessary to match any .pro or .sav files in that directory. When this array is passed to FILE_SEARCH, it locates all files that match these specifications. FILE_SEARCH sorts all of the files found by each input string. The files for each string are then placed into the output array in the order they were searched for. Example 9 Recursively find all directories in your IDL distribution: Result = FILE_SEARCH(!DIR, '*', /TEST_DIRECTORY) See Also FILE_TEST, FILEPATH, FINDFILE, GETENV GRID_INPUT [Previous Routine] [Next Routine] [List of Routines] NAME: GRID_INPUT The GRID_INPUT procedure preprocesses and sorts two-dimensional scattered data points, and removes duplicate values. This procedure is also used for converting spherical coordinates to Cartesian coordinates. Syntax GRID_INPUT, X, Y, F, X1, Y1, F1 [, DUPLICATES=string ] [, EPSILON=value ] [, EXCLUDE=vector ] or GRID_INPUT, Lon, Lat, F, Xyz, F1, /SPHERE [, /DEGREES] [, DUPLICATES=string ] [, EPSILON=value ] [, EXCLUDE=vector ] or GRID_INPUT, R, Theta, F, X1, Y1, F1, /POLAR [, /DEGREES] [, DUPLICATES=string ] [, EPSILON=value ] [, EXCLUDE=vector ] Arguments X, Y These are input arguments for scattered data points, where X, and Y are location. All of these arguments are N point vectors. F The function value at each location in the form of an N point vector. Lon, Lat These are input arguments representing scattered data points on a sphere, specifying location (longitude and latitude). All are N point vectors. Lon, Lat are in degrees or radians (default). R, Theta These are scattered data point input arguments representing the R and Theta polar coordinate location in degrees or radians (default). All arguments are N point vectors. X1, Y1, F1 These output arguments are processed and sorted single precision floating point data which are passed as the input points to the GRIDDATA function. Xyz Upon return, a named variable that contains a 3-by-n array of Cartesian coordinates representing points on a sphere. Keywords DEGREES By default, all angular inputs and keywords are assumed to be in radian units. Set the DEGREES keyword to change the angular input units to degrees. DUPLICATES Set this keyword to a string indicating how duplicate data points are handled per the following table. The case (upper or lower) is ignored. The default setting for DUPLICATES is "First". String Meaning "First" Retain only the first encounter of the duplicate locations. "Last" Retain only the last encounter of the duplicate locations. "All" Retains all locations, which is invalid for any gridding technique that requires a TRIANGULATION. Some methods, such as Inverse Distance or Polynomial Regression with no search criteria can handle duplicates. "Avg" Retain the average F value of the duplicate locations. "Midrange" Retain the average of the minimum and maximum duplicate locations ((Max(F) + Min (F)) / 2). "Min" Retain the minimum of the duplicate locations (Min(F)). "Max" Retain the maximum of the duplicate locations (Max(F)). EPSILON The tolerance for finding duplicates. Points within EPSILON distance of each other are considered duplicates. For spherical coordinates, EPSILON is in units of angular distance, as set by the DEGREES keyword. EXCLUDE An N-point vector specifying the indices of the points to exclude. POLAR Set to indicate inputs are in polar coordinates. SPHERE Set to indicate inputs are in spherical coordinates. In this case, the output argument Xyz is set to a 3-by-n array containing the spherical coordinates converted to 3- dimensional Cartesian points on a sphere. Example The following example uses the data from the irreg_grid1.txt ASCII file. This file contains scattered elevation data of a model of an inlet. This scattered elevation data contains two duplicate locations. The GRID_INPUT procedure is used to omit the duplicate locations. ; Import the Data: ; Determine the path to the file. file = FILEPATH('irreg_grid1.txt', $ SUBDIRECTORY = ['examples', 'data']) ; Import the data from the file into a structure. dataStructure = READ_ASCII(file) ; Get the imported array from the first field of ; the structure. dataArray = TRANSPOSE(dataStructure.field1) ; Initialize the variables of this example from ; the imported array. x = dataArray[*, 0] y = dataArray[*, 1] data = dataArray[*, 2] ; Display the Data: ; Scale the data to range from 1 to 253 so a color table can be ; applied. The values of 0, 254, and 255 are reserved as outliers. scaled = BYTSCL(data, TOP = !D.TABLE_SIZE - 4) + 1B ; Load the color table. If you are on a TrueColor, set the ; DECOMPOSED keyword to the DEVICE command before running a ; color table related routine. DEVICE, DECOMPOSED = 0 LOADCT, 38 ; Open a display window and plot the data points. WINDOW, 0 PLOT, x, y, /XSTYLE, /YSTYLE, LINESTYLE = 1, $ TITLE = 'Original Data, Scaled (1 to 253)', $ XTITLE = 'x', YTITLE = 'y' ; Now display the data values with respect to the color table. FOR i = 0L, (N_ELEMENTS(x) - 1) DO PLOTS, x[i], y[i], PSYM = -1, $ SYMSIZE = 2., COLOR = scaled[i] ; Preprocess and sort the data. GRID_INPUT will ; remove any duplicate locations. GRID_INPUT, x, y, data, xSorted, ySorted, dataSorted ; Display the results from GRID_INPUT: ; Scale the resulting data. scaled = BYTSCL(dataSorted, TOP = !D.TABLE_SIZE - 4) + 1B ; Open a display window and plot the resulting data points. WINDOW, 1 PLOT, xSorted, ySorted, /XSTYLE, /YSTYLE, LINESTYLE = 1, $ TITLE = 'The Data Preprocessed and Sorted, Scaled (1 to 253)', $ XTITLE = 'x', YTITLE = 'y' ; Now display the resulting data values with respect to the color ; table. FOR i = 0L, (N_ELEMENTS(xSorted) - 1) DO PLOTS, $ xSorted[i], ySorted[i], PSYM = -1, COLOR = scaled[i], $ SYMSIZE = 2. See Also GRIDDATA GRIDDATA [Previous Routine] [Next Routine] [List of Routines] NAME: GRIDDATA The GRIDDATA function interpolates scattered data values and locations sampled on a plane or a sphere to a regular grid. This is accomplished using one of several available methods. The function result is a two-dimensional floating point array. Computations are performed in single precision floating point. Interpolation methods supported by this function are as follows: * Inverse Distance (default) * Natural Neighbor * Kriging * Nearest Neighbor * Linear * Polynomial Regression * Minimum Curvature * Quintic * Modified Shepard's * Radial Basis Function Syntax Interleaved Result = GRIDDATA( X, F ) Planar Result = GRIDDATA( X, Y, F ) Sphere From Cartesian Coordinates Result = GRIDDATA( X, Y, Z, F, /SPHERE ) Sphere From Spherical Coordinates Result = GRIDDATA( Lon, Lat, F, /SPHERE ) Inverse Distance Keywords: [, METHOD='InverseDistance' | /INVERSE_DISTANCE ] [, ANISOTROPY=vector ] [, /DEGREES ] [, DELTA=vector ] [, DIMENSION=vector ] [, TRIANGLES=array [, EMPTY_SECTORS=value ] [, MAX_PER_SECTOR=value ] [, MIN_POINTS=value ] [, SEARCH_ELLIPSE=vector ] ] [, FAULT_POLYGONS=vector ] [, FAULT_XY=array ] [, /GRID, XOUT=vector, YOUT=vector ] [, MISSING=value ] [, POWER=value ] [, SECTORS={1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 } ] [, SMOOTHING=value ] [, /SPHERE] [, START=vector ] Kriging Keywords: METHOD='Kriging' | /KRIGING [, ANISOTROPY=vector ] [, DELTA=vector ] [, DIMENSION=vector ] [, TRIANGLES=array [, EMPTY_SECTORS=value ] [, MAX_PER_SECTOR=value ] [, MIN_POINTS=value ] [, SEARCH_ELLIPSE=vector ] ] [, FAULT_POLYGONS=vector ] [, FAULT_XY=array ] [, /GRID, XOUT=vector, YOUT=vector ] [, MISSING=value ] [, SECTORS={1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 } ] [, /SPHERE] [, START=vector ] [, VARIOGRAM=vector ] Linear Interpolation Keywords: METHOD='Linear' | /LINEAR , TRIANGLES=array [, DELTA=vector ] [, DIMENSION=vector ] [, /GRID, XOUT=vector, YOUT=vector ] [, MISSING=value ] [, START=vector ] Minimum Curvature Keywords: METHOD='MinimumCurvature' | /MIN_CURVATURE [, DELTA=vector ] [, DIMENSION=vector ] [, START=vector ] Modified Shepard's Keywords: METHOD='ModifiedShepards' | /SHEPARDS, TRIANGLES=array [, ANISOTROPY=vector ] [, DELTA=vector ] [, DIMENSION=vector ] [, EMPTY_SECTORS=value ] [, FAULT_POLYGONS=vector ] [, FAULT_XY=array ] [, /GRID, XOUT=vector, YOUT=vector ] [, MAX_PER_SECTOR=value ] [, MIN_POINTS=value ] [, MISSING=value ] [, NEIGHBORHOOD=array ] [, SEARCH_ELLIPSE=vector ] [, SECTORS={1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 } ] [, START=vector ] Natural Neighbor Keywords: METHOD='NaturalNeighbor' | /NATURAL_NEIGHBOR, TRIANGLES=array [, /DEGREES ] [, DELTA=vector ] [, DIMENSION=vector ] [, /GRID, XOUT=vector, YOUT=vector ] [, MISSING=value ] [, /SPHERE] [, START=vector ] Nearest Neighbor Keywords: METHOD='NearestNeighbor' | /NEAREST_NEIGHBOR, TRIANGLES=array [, /DEGREES ] [, DELTA=vector ] [, DIMENSION=vector ] [, FAULT_POLYGONS=vector ] [, FAULT_XY=array ] [, /GRID, XOUT=vector, YOUT=vector ] [, MISSING=value ] [, /SPHERE] [, START=vector ] Polynomial Regression Keywords: METHOD='PolynomialRegression' | /POLYNOMIAL_REGRESSION, [, DELTA=vector ] [, DIMENSION=vector ] [, TRIANGLES=array [, EMPTY_SECTORS=value ] [, MAX_PER_SECTOR=value ] [, MIN_POINTS=value ] [, SEARCH_ELLIPSE=vector ] ] [, FAULT_POLYGONS=vector ] [, FAULT_XY=array ] [, /GRID, XOUT=vector, YOUT=vector ] [, MISSING=value ] [, POWER=value ] [, SECTORS={1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 } ] [, START=vector ] Quintic Keywords: METHOD='Quintic' | /QUINTIC, TRIANGLES=array [, DELTA=vector ] [, DIMENSION=vector ] [, MISSING=value ] [, START=vector ] Radial Basis Function Keywords: METHOD='RadialBasisFunction' | /RADIAL_BASIS_FUNCTION, [, ANISOTROPY=vector ] [, /DEGREES ] [, DELTA=vector ] [, DIMENSION=vector ] [, TRIANGLES=array [, EMPTY_SECTORS=value ] [, MAX_PER_SECTOR=value ] [, MIN_POINTS=value ] [, SEARCH_ELLIPSE=vector ] ] [, FAULT_POLYGONS=vector ] [, FAULT_XY=array ] [, FUNCTION_TYPE={ 0 | 1 | 2 | 3 | 4 } ] [, /GRID, XOUT=vector, YOUT=vector ] [, MISSING=value ] [, SECTORS={1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 } ] [, SMOOTHING=value ] [, /SPHERE] [, START=vector ] Return Value Result is a two-dimensional floating point array. Computations are preformed in single precision floating point. Arguments X [, Y [, Z]] The point locations. If only one input coordinate parameter is supplied, the points are interleaved; for the Cartesian coordinate system the points are 2-by-n dimensions; and 3-by-n for a sphere in Cartesian coordinates. F The function value at each location in the form of an n-point vector. Lon, Lat These arguments contain the locations (on a sphere) of the data points (similar to X, and Y) but are in degrees or radians (default) depending on the use of the keyword DEGREES. Keywords ANISOTROPY This keyword is a vector describing an ellipse (see the description for the SEARCH_ELLIPSE keyword). All points on the circumference of the ellipse have an equal influence on a point at the center of the ellipse. For example, assume that atmospheric data are being interpolated, with one dimension being altitude, and the other dimension representing distance from a point. If the vertical mixing is half that of the horizontal mixing, a point 100 units from an interpolate and at the same level has the same influence as a point 50 units above or below the interpolate at the same horizontal location. This effect requires setting the ANISOTROPY keyword to [2, 1, 0] which forms an ellipse with an X-axis length twice as long as its Y-axis length. DEGREES By default, all angular inputs and keywords are assumed to be in radian units. Set the DEGREES keyword to change the angular input units to degrees. DELTA A two-element array specifying the grid spacing in X, and Y. If this keyword is not specified, then the grid spacing is determined from the values of the DIMENSION and START keywords. These keywords have default values of 25 and [min(x), min(y)], respectively. The spacing derived from these keywords creates a grid of DIMENSION cells, enclosing a rectangle from START, to [max(x), max(y)]. This keyword can also be set to a scalar value to be used for the grid size in both X and Y. This keyword is ignored if the GRID, XOUT and YOUT keywords are specified. DIMENSION A two element array specifying the grid dimensions in X and Y. Default value is 25 for each dimension. This keyword can also be set to a scalar value to be used for the grid spacing in both X and Y. This keyword is ignored if the GRID, XOUT and YOUT keywords are specified. EMPTY_SECTORS This keyword defines the search rules for the maximum number of sectors that may be empty when interpolating at each point. If this number or more sectors contain no data points, considering the search ellipse and/or the fault polygons, the resulting interpolant is the missing data value. Note The TRIANGLES keyword is required when the EMPTY_SECTORS, MAX_PER_SECTOR, MIN_POINTS, or SEARCH_ELLIPSE keywords are used. FAULT_POLYGONS Set this keyword to an array containing one or more polygon descriptions. A polygon description is an integer or longword array of the form: [n, i0, i1, ..., in­1], where n is the number of vertices that define the polygon, and i0...in­1 are indices into the FAULT_XY vertices. The FAULT_POLYGON array may contain multiple polygon descriptions that have been concatenated. To have this keyword ignore an entry in the FAULT_POLYGONS array, set the vertex count, n, and all associated indices to 0. To end the drawing list, even if additional array space is available, set n to ­1. If this keyword is not specified, a single connected polygon is generated from FAULT_XY. Note FAULT_POLYGONS are not supported with spherical gridding. FAULT_XY The a 2-by-n array specifying the coordinates of points on the fault lines/polygons. Note FAULT_XY is not supported with spherical gridding. FUNCTION_TYPE Note This keyword is only used with the Radial Basis Function method of interpolation. Set this keyword to one of the values shown in the following table to indicate which basis function to use. Default is 0, the Inverse Multiquadric function. Value Function Type Used Equation 0 Inverse Multiquadric B(h) = 1 ( h2 R2 + ) 1 Multilog B(h) = log(h2 R2 + ) 2 Multiquadric B(h) = h2 R2 + 3 2 3 Natural Cubic Spline B(h) = (h2 R2 + ) 4 Thin Plate Spline B(h) = (h2 R2 + )log(h2 R2 + ) Note - In the equations, h = the anisotropically scaled distance from the interpolant to the node, and R2 = the value of the SMOOTHING keyword. GRID The GRID keyword controls how the XOUT and YOUT vectors specify where interpolates are desired. If GRID is set, XOUT and YOUT must also be specified. Interpolation is performed on a regular or irregular grid specified by the vectors XOUT with m elements and YOUT with n elements. The Result is an m-by-n grid with point [i, j] resulting from the interpolation at (XOUT[i], YOUT[j]). When XOUT and YOUT are used, the DELTA, DIMENSION and START keywords are ignored. INVERSE_DISTANCE Selects the Inverse Distance method of interpolation. KRIGING Selects the Kriging method of interpolation. The variogram type for the Kriging method is set by default, however the VARIOGRAM keyword can be used to set variogram parameters. LINEAR Selects the Linear method of interpolation. The TRIANGLES keyword is required when the LINEAR keyword is used. MAX_PER_SECTOR This keyword defines the search rules for the maximum number of data points to include in each sector when interpolating. Search rules effectively limit the number of data points used in computing each interpolate. For example, to use the nearest n nodes to compute each interpolant, specify MAX_PER_SECTOR = n and use the TRIANGLES keyword. Note The TRIANGLES keyword is required when the EMPTY_SECTORS, MAX_PER_SECTOR, MIN_POINTS, or SEARCH_ELLIPSE keywords are used. METHOD A string containing one of the method names as shown in the following table. The default for METHOD is "InverseDistance". Note The interpolation method can be chosen using the METHOD keyword set to the specific string, or by setting the corresponding method name keyword. Note There are no spaces between words in the method strings and the strings are case insensitive. Method String Meaning "InverseDistance" Data points closer to the grid points have more effect than those which are further away. Method String Meaning "Kriging" Data points and their spatial variance are used to determine trends which are applied to the grid points. "Linear" Grid points are linearly interpolated from triangles formed by Delaunay triangulation. "MinimumCurvature" A plane of grid points is conformed to the data points while trying to minimize the amount of bending in the plane. "ModifiedShepards" Inverse Distance weighted with the least squares method. "NaturalNeighbor" Each interpolant is a linear combination of the three vertices of its enclosing Delaunay triangle and their adjacent vertices. "NearestNeighbor" The grid points have the same value as the nearest data point. "PolynomialRegression" Each interpolant is a least-squares fit of a polynomial in X and Y of the specified power to the specified data points. "Quintic" Grid points are interpolated with quintic polynomials from triangles formed by Delaunay triangulation. "RadialBasisFunction" The effects of data points are weighted by a function of their radial distance from a grid point. MIN_CURVATURE Selects the Minimum Curvature method of interpolation. MIN_POINTS If fewer than this number of data points are encountered in all sectors, the value of the resulting grid point is set to the value of the MISSING keyword. The MIN_POINTS keyword also indicates the number of closest points used for each local fit, if SEARCH_ELLIPSE isn't specified. Note The TRIANGLES keyword is required when the EMPTY_SECTORS, MAX_PER_SECTOR, MIN_POINTS, or SEARCH_ELLIPSE keywords are used. MISSING Set this keyword to the value to use for missing data values. Default is 0. NATURAL_NEIGHBOR Selects the Natural Neighbor method of interpolation. Note The TRIANGLES keyword is required when the NATURAL_NEIGHBOR keyword is used. NEAREST_NEIGHBOR Selects the Nearest Neighbor method of interpolation. Note The TRIANGLES keyword is required when the NEAREST_NEIGHBOR keyword is used. NEIGHBORHOOD Note The NEIGHBORHOOD keyword is only used for the Modified Shepard's method of interpolation. A two-element array, [Nq, Nw] defining the quadratic fit, Nq, and weighting, Nw, neighborhood sizes for the Modified Shepard's method. The default for Nq is the smaller of 13 and the number of points minus 1, with a minimum of 5. The default for Nw is the smaller of 19 and the number of points. The Modified Shepard's method first computes the coefficients of a quadratic fit for each input point, using its Nq closest neighbors. When interpolating an output point, the quadratic fits from the Nw closest input points are weighted inversely by a function of distance and then combined. The size of the neighborhood used for Shepard's method interpolation may also be specified by the search rules keywords. POLYNOMIAL_REGRESSION Selects the Polynomial Regression method for interpolation. The power of the polynomial regression is set to 2 by default, however the POWER keyword can be used to change the power to 1 or 3. The function fit to each interpolant corresponding to the POWER keyword set equal to 1, 2 (default), and 3 respectively is as follows: F(x,y) = a0 + a1x + a2y F(x,y) = a + + + + + (default) 0 a1x a2y a3x2 a4y2 a5xy F(x,y) = a0 a1x a2y a3x2 a4y2 a5xy a6x3 a7y3 a8x2y a9xy2 + + + + + + + + + By inspection, a minimum of three data points are required to fit the linear polynomial, six data points for the second polynomial equation (where POWER = 2), and ten data points for the third polynomial (POWER = 3). If not enough data points exist for a given interpolant, the missing data values are set to the value of the MISSING keyword. POWER The weighting power of the distance, or the maximum order in the polynomial fitting function. For polynomial regression, this value is either 1, 2 (the default), or 3. Note The POWER keyword is only used for the Inverse Distance and Polynomial Regression methods of interpolation. QUINTIC Selects the triangulation with Quintic interpolation method. Note The TRIANGLES keyword is required when the QUINTIC keyword is used. RADIAL_BASIS_FUNCTION Selects the Radial Basis Function method of interpolation. SEARCH_ELLIPSE This keyword defines the search rules as a scalar or vector of from 1 to 3 elements that specify an ellipse or circle in the form [R1], [R1, R2], or [R1, R2, Theta]. R1 is one radius, R2 the other radius, and Theta describes the angle between the X-axis to the R1-axis, counterclockwise, in degrees or radians as specified by the DEGREES keyword. Only data points within this ellipse, centered on the location of the interpolate, are considered. If not specified, or 0, this distance test is not applied. Search rules effectively limit the number of data points used in computing each interpolate. For example, to only consider data points within a distance of 5 units of each interpolant, specify the keyword as SEARCH_ELLIPSE = 5. Note The TRIANGLES keyword is required when the EMPTY_SECTORS, MAX_PER_SECTOR, MIN_POINTS, or SEARCH_ELLIPSE keywords are used. SECTORS This keyword defines the search rules for the number of sectors used in applying the MAX_SECTOR, EMPTY_SECTORS, and MIN_POINTS tests, an integer from 1 (the default setting) to 8. SHEPARDS Selects the Modified Shepard's method of interpolation. The parameters for the Modified Shepard's method are set by default, however the NEIGHBORHOOD keyword can be used to modify the parameters. Note The TRIANGLES keyword is required when the SHEPARDS keyword is used. SMOOTHING A scalar value defining the smoothing radius. For the Radial Basis Function method, if SMOOTHING is not specified, the default value is equal to the average point spacing, assuming a uniform distribution. For the Inverse Distance method, the default value is 0, implying no smoothing. Note The SMOOTHING keyword is used only for the Inverse Distance and Radial Basis Function methods of interpolation. SPHERE If set, data points lie on the surface of a sphere. START A scalar or a two-element array specifying the start of the grid in X, and Y. Default value is [min(x), min(y)]. This keyword is ignored if the GRID, XOUT and YOUT keywords are specified. TRIANGLES A 3-by-nt longword array describing the connectivity of the input points, as returned by TRIANGULATE, where nt is the number of triangles. If duplicate point locations are input and the TRIANGLES keyword is present, only one of the points is considered. Note The TRIANGLES keyword is required for the Natural Neighbor, Nearest Neighbor, Modified Shepard's, Linear, and Quintic Interpolation methods. Note The TRIANGLES keyword is required when the EMPTY_SECTORS, MAX_PER_SECTOR, MIN_POINTS, or SEARCH_ELLIPSE keywords are used. VARIOGRAM Specifies the variogram type and parameters for the Kriging method. This parameter is a vector of one to four elements in the form of: [ Type, Range, Nugget, Scale]. The Type is encoded as: 1 for linear, 2 for exponential, 3 for gaussian, 4 for spherical. Defaults values are: Type is exponential, Range is 8 times the average point spacing assuming a uniform distribution, Nugget is zero, and Scale is 1. Note The VARIOGRAM keyword is only used with the Kriging method of interpolation. XOUT If the GRID keyword is set, use XOUT to specify irregularly spaced rectangular output grids. If XOUT is specified, YOUT must also be specified. When XOUT and YOUT are used, the DELTA, DIMENSION and START keywords are ignored. If GRID is not set (the default), the location vectors XOUT and YOUT directly contain the X and Y values of the interpolates, and must have the same number of elements. The Result has the same structure and number of elements as XOUT and YOUT, with point [i] resulting from the interpolation at (XOUT[i], YOUT[i]). YOUT If the GRID keyword is set, use YOUT to specify irregularly spaced rectangular output grids. If YOUT is specified, XOUT must also be specified. When XOUT and YOUT are used, the DELTA, DIMENSION and START keywords are ignored. If GRID is not set (the default), the location vectors XOUT and YOUT directly contain the X and Y values of the interpolates, and must have the same number of elements. The Result has the same structure and number of elements as XOUT and YOUT, with point [i] resulting from the interpolation at (XOUT[i], YOUT[i]). Example 1 This example interpolates a data set measured on an irregular grid. Various types of the Inverse Distance interpolation method (the default method) are used in this example. ; Create a dataset of N points. n = 100 ;# of scattered points seed = -121147L ;For consistency x = RANDOMU(seed, n) y = RANDOMU(seed, n) ; Create a dependent variable in the form a function of (x,y) ; with peaks & valleys. f = 3 * EXP(-((9*x-2)^2 + (7-9*y)^2)/4) + $ 3 * EXP(-((9*x+1)^2)/49 - (1-0.9*y)) + $ 2 * EXP(-((9*x-7)^2 + (6-9*y)^2)/4) - $ EXP(-(9*x-4)^2 - (2-9*y)^2) ; Initialize display. WINDOW, 0, XSIZE = 512, YSIZE = 768, TITLE = 'Inverse Distance' !P.MULTI = [0, 1, 3, 0, 0] ; Inverse distance: Simplest default case which produces a 25 x ; 25 grid. grid = GRIDDATA(x, y, f) SURFACE, grid, CHARSIZE = 3, TITLE = 'Simple Example' ; Default case, Inverse distance. grid = GRIDDATA(x, y, f, START = 0, DELTA = 0.02, DIMENSION = 51) SURFACE, grid, CHARSIZE = 3, TITLE = 'Larger Grid' ; Inverse distance + smoothing. grid = GRIDDATA(x, y, f, START = 0, DELTA = 0.02, DIMENSION = 51, $ SMOOTH = 0.05) SURFACE, grid, CHARSIZE = 3, TITLE = 'Smoothing' ; Set system variable back to default value. !P.MULTI = 0 Example 2 This example uses the same data as the previous one, however in this example we use the Radial Basis Function and the Modified Shepard's interpolation methods. ; Create a dataset of N points. n = 100 ;# of scattered points seed = -121147L ;For consistency x = RANDOMU(seed, n) y = RANDOMU(seed, n) ; Create a dependent variable in the form of a function of (x,y) ; with peaks & valleys. f = 3 * EXP(-((9*x-2)^2 + (7-9*y)^2)/4) + $ 3 * EXP(-((9*x+1)^2)/49 - (1-0.9*y)) + $ 2 * EXP(-((9*x-7)^2 + (6-9*y)^2)/4) - $ EXP(-(9*x-4)^2 - (2-9*y)^2) ; Initialize display. WINDOW, 0, XSIZE = 512, YSIZE = 512, $ TITLE = 'Different Methods of Gridding' !P.MULTI = [0, 1, 2, 0, 0] ; Use radial basis function with multilog basis function. grid = GRIDDATA(x, y, f, START = 0, DELTA = 0.02, DIMENSION = 51, $ /RADIAL_BASIS_FUNCTION, FUNCTION_TYPE = 1) SURFACE, grid, CHARSIZE = 3, TITLE = 'Radial Basis Function' ; The following example requires triangulation. TRIANGULATE, x, y, tr ; Use Modified Shepard's method. grid = GRIDDATA(x, y, f, START = 0, DELTA = 0.02, DIMENSION = 51, $ TRIANGLES = tr, /SHEPARDS) SURFACE, grid, CHARSIZE = 3, TITLE = "Modified Shepard's Method" ; Set system variable back to default value. !P.MULTI = 0 Example 3 This example uses the same data as the previous ones, however in this example we use various types of the Polynomial Regression interpolation method. ; Create a dataset of N points. n = 100 ;# of scattered points seed = -121147L ;For consistency x = RANDOMU(seed, n) y = RANDOMU(seed, n) ; Create a dependent variable in the form a function of (x,y) ; with peaks & valleys. f = 3 * EXP(-((9*x-2)^2 + (7-9*y)^2)/4) + $ 3 * EXP(-((9*x+1)^2)/49 - (1-0.9*y)) + $ 2 * EXP(-((9*x-7)^2 + (6-9*y)^2)/4) - $ EXP(-(9*x-4)^2 - (2-9*y)^2) ; Initialize display. WINDOW, 0, XSIZE = 512, YSIZE = 768, $ TITLE = 'Polynomial Regression' !P.MULTI = [0, 1, 3, 0, 0] ; The following examples require the triangulation. TRIANGULATE, x, y, tr ; Fit with a 2nd degree polynomial in x and y. This fit considers ; all points when fitting the surface, obliterating the individual ; peaks. grid = GRIDDATA(x, y, f, START = 0, DELTA = 0.02, DIMENSION = 51, $ TRIANGLES = tr, /POLYNOMIAL_REGRESSION) SURFACE, grid, CHARSIZE = 3, TITLE = 'Global Degree 2 Polynomial' ; Fit with a 2nd degree polynomial in x and y, but this time use ; only the 10 closest nodes to each interpolant. This provides a ; relatively smooth surface, but still shows the individual peaks. grid = GRIDDATA(x, y, f, START = 0, DELTA = 0.02, DIMENSION = 51, $ TRIANGLES = tr, /POLYNOMIAL_REGRESSION, MAX_PER_SECTOR = 10) SURFACE, grid, CHARSIZE = 3, TITLE = 'Local Polynomial, 10 Point' ; As above, but use only the nodes within a distance of 0.4 when ; fitting each interpolant. grid = GRIDDATA(x, y, f, START = 0, DELTA = 0.02, DIMENSION = 51, $ TRIANGLES = tr, /POLYNOMIAL_REGRESSION, SEARCH_ELLIPSE = 0.4) SURFACE, grid, CHARSIZE = 3, $ TITLE = 'Local Polynomial, Radius = 0.4' ; Set system variable back to default value. !P.MULTI = 0 Example 4 This example uses the same data as the previous ones, however in this example we show how to speed up the interpolation by limiting the interpolation to the local area around each interpolate. ; Create a dataset of N points.\. n = 100 ;# of scattered points seed = -121147L ;For consistency x = RANDOMU(seed, n) y = RANDOMU(seed, n) ; Create a dependent variable in the form a function of (x,y) ; with peaks & valleys. f = 3 * EXP(-((9*x-2)^2 + (7-9*y)^2)/4) + $ 3 * EXP(-((9*x+1)^2)/49 - (1-0.9*y)) + $ 2 * EXP(-((9*x-7)^2 + (6-9*y)^2)/4) - $ EXP(-(9*x-4)^2 - (2-9*y)^2) ; Note: the inverse distance, kriging, polynomial regression, and ; radial basis function methods are, by default, global methods in ; which each input node affects each output node. With these ; methods, large datasets can require a prohibitively long time to ; compute unless the scope of the interpolation is limited to a ; local area around each interpolate by specifying search rules. ; In fact, the radial basis function requires time proportional to ; the cube of the number of input points. ; For example, with 2,000 input points, a typical workstation ; required 500 seconds to interpolate a 10,000 point grid using ; radial basis functions. By limiting the size of the fit to the ; 20 closest points to each interpolate, via the MIN_POINTS ; keyword, the time required dropped to less than a second. ; Initialize display. WINDOW, 0, XSIZE = 512, YSIZE = 512, $ TITLE = 'Radial Basis Function' !P.MULTI = [0, 1, 2, 0, 0] ; Slow way: grid = GRIDDATA(x, y, f, START = 0, DELTA = 0.02, DIMENSION = 51, $ /RADIAL_BASIS_FUNCTION) SURFACE, grid, CHARSIZE = 3, TITLE = 'All Points' ; The following example requires triangulation. TRIANGULATE, x, y, tr ; Faster way: grid = GRIDDATA(x, y, f, START = 0, DELTA = 0.02, DIMENSION = 51, $ /RADIAL_BASIS_FUNCTION, MIN_POINTS = 15, TRIANGLES = tr) SURFACE, grid, CHARSIZE = 3, TITLE = 'Nearest 15 Points' ; Set system variable back to default value. !P.MULTI = 0 Example 5 This example interpolates a spherical data set measured on an irregular grid. We use the Kriging and Natural Neighbors interpolation methods in this example. ; Create a 100 scattered points on a sphere and form a function ; of their latitude and longitude. Then grid them to a 2 degree ; grid over the sphere, display a Mollweide projection map, and ; overlay the contours of the result on the map. ; Create a dataset of N points. n = 100 ; A 2 degree grid with grid dimensions. delta = 2 dims = [360, 180]/delta ; Longitude and latitudes lon = RANDOMU(seed, n) * 360 - 180 lat = RANDOMU(seed, n) * 180 - 90 ; The lon/lat grid locations lon_grid = FINDGEN(dims[0]) * delta - 180 lat_grid = FINDGEN(dims[1]) * delta - 90 ; Create a dependent variable in the form of a smoothly varying ; function. f = SIN(2*lon*!DTOR) + COS(lat*!DTOR) ; ; Initialize display. WINDOW, 0, XSIZE = 512, YSIZE = 768, TITLE = 'Spherical Gridding' !P.MULTI = [0, 1, 3, 0, 0] ; Kriging: Simplest default case. z = GRIDDATA(lon, lat, f, /KRIGING, /DEGREES, START = 0, /SPHERE, $ DELTA = delta, DIMENSION = dims) MAP_SET, /MOLLWEIDE, /ISOTROPIC, /HORIZON, /GRID, CHARSIZE = 3, $ TITLE = 'Sphere: Kriging' CONTOUR, z, lon_grid, lat_grid, /OVERPLOT, NLEVELS = 10, /FOLLOW ; This example is the same as above, but with the addition of a ; call to QHULL to triangulate the points on the sphere, and to ; then interpolate using the 10 closest points. The gridding ; portion of this example requires about one-fourth the time as ; above. QHULL, lon, lat, tr, /DELAUNAY, SPHERE = s z = GRIDDATA(lon, lat, f, /DEGREES, START = 0, DELTA = delta, $ DIMENSION = dims, TRIANGLES = tr, MIN_POINTS = 10, /KRIGING, $ /SPHERE) MAP_SET, /MOLLWEIDE, /ISOTROPIC, /HORIZON, /GRID, /ADVANCE, $ CHARSIZE = 3, TITLE = 'Sphere: Kriging, 10 Closest Points' CONTOUR, z, lon_grid, lat_grid, /OVERPLOT, NLEVELS = 10, /FOLLOW ; This example uses the natural neighbor method, which is about ; four times faster than the above example but does not give as ; smooth a surface. z = GRIDDATA(lon, lat, f, /DEGREES, START = 0, DELTA = delta, $ DIMENSION = dims, /SPHERE, /NATURAL_NEIGHBOR, TRIANGLES = tr) MAP_SET, /MOLLWEIDE, /ISOTROPIC, /HORIZON, /GRID, /ADVANCE, $ CHARSIZE = 3, TITLE = 'Sphere: Natural Neighbor' CONTOUR, z, lon_grid, lat_grid, /OVERPLOT, NLEVELS = 10, /FOLLOW ; Set system variable back to default value. !P.MULTI = 0 Example 6 The following example uses the data from the irreg_grid1.txt ASCII file. This file contains scattered elevation data of a model of an inlet. This scattered elevation data contains two duplicate locations. The GRID_INPUT procedure is used to omit the duplicate locations for the GRIDDATA function. The GRIDDATA function is then used to grid the data using the Radial Basis Function method. This method is specified by setting the METHOD keyword the RadialBasisFunction string, although it could easily be done using the RADIAL_BASIS_FUNCTION keyword. ; Import the Data: ; Determine the path to the file. file = FILEPATH('irreg_grid1.txt', $ SUBDIRECTORY = ['examples', 'data']) ; Import the data from the file into a structure. dataStructure = READ_ASCII(file) ; Get the imported array from the first field of ; the structure. dataArray = TRANSPOSE(dataStructure.field1) ; Initialize the variables of this example from ; the imported array. x = dataArray[*, 0] y = dataArray[*, 1] data = dataArray[*, 2] ; Display the Data: ; Scale the data to range from 1 to 253 so a color table can be ; applied. The values of 0, 254, and 255 are reserved as outliers. scaled = BYTSCL(data, TOP = !D.TABLE_SIZE - 4) + 1B ; Load the color table. If you are on a TrueColor, set the ; DECOMPOSED keyword to the DEVICE command before running a ; color table related routine. DEVICE, DECOMPOSED = 0 LOADCT, 38 ; Open a display window and plot the data points. WINDOW, 0 PLOT, x, y, /XSTYLE, /YSTYLE, LINESTYLE = 1, $ TITLE = 'Original Data, Scaled (1 to 253)', $ XTITLE = 'x', YTITLE = 'y' ; Now display the data values with respect to the color table. FOR i = 0L, (N_ELEMENTS(x) - 1) DO PLOTS, x[i], y[i], PSYM = -1, $ SYMSIZE = 2., COLOR = scaled[i] ; Grid the Data and Display the Results: ; Preprocess and sort the data. GRID_INPUT will ; remove any duplicate locations. GRID_INPUT, x, y, data, xSorted, ySorted, dataSorted ; Initialize the grid parameters. gridSize = [51, 51] ; Use the equation of a straight line and the grid parameters to ; determine the x of the resulting grid. slope = (MAX(xSorted) - MIN(xSorted))/(gridSize[0] - 1) intercept = MIN(xSorted) xGrid = (slope*FINDGEN(gridSize[0])) + intercept ; Use the equation of a straight line and the grid parameters to ; determine the y of the resulting grid. slope = (MAX(ySorted) - MIN(ySorted))/(gridSize[1] - 1) intercept = MIN(ySorted) yGrid = (slope*FINDGEN(gridSize[1])) + intercept ; Grid the data with the Radial Basis Function method. grid = GRIDDATA(xSorted, ySorted, dataSorted, $ DIMENSION = gridSize, METHOD = 'RadialBasisFunction') ; Open a display window and contour the Radial Basis Function ; results. WINDOW, 1 scaled = BYTSCL(grid, TOP = !D.TABLE_SIZE - 4) + 1B CONTOUR, scaled, xGrid, YGrid, /XSTYLE, /YSTYLE, /FILL, $ LEVELS = BYTSCL(INDGEN(18), TOP = !D.TABLE_SIZE - 4) + 1B, $ C_COLORS = BYTSCL(INDGEN(18), TOP = !D.TABLE_SIZE - 4) + 1B, $ TITLE = 'The Resulting Grid with Radial Basis Function', $ XTITLE = 'x', YTITLE = 'y' Example 7 The following example uses the data from the irreg_grid1.txt ASCII file. This file contains scattered elevation data of a model of an inlet. This scattered elevation data contains two duplicate locations. The same data is used in the previous example. The GRID_INPUT procedure is used to omit the duplicate locations for the GRIDDATA function. The GRIDDATA function is then used to grid the data using the Radial Basis Function method. This method is specified by setting the METHOD keyword the RadialBasisFunction string, although it could easily be done using the RADIAL_BASIS_FUNCTION keyword. Faulting is also applied in this example. First, a fault area is placed around the right side of the dataset. This fault area contains data points. The data points within this area are gridded separately from the points outside of the fault area. Then, a fault area is defined within an region that does not contain any data points. Since this fault area does not contain any points, the grid within this region simply results to the value defined by the MISSING keyword. The points outside of the fault area are gridded independent of the fault region. ; Import the Data: ; Determine the path to the file. file = FILEPATH('irreg_grid1.txt', $ SUBDIRECTORY = ['examples', 'data']) ; Import the data from the file into a structure. dataStructure = READ_ASCII(file) ; Get the imported array from the first field of ; the structure. dataArray = TRANSPOSE(dataStructure.field1) ; Initialize the variables of this example from ; the imported array. x = dataArray[*, 0] y = dataArray[*, 1] data = dataArray[*, 2] ; Grid the Data and Display the Results: ; Preprocess and sort the data. GRID_INPUT will ; remove any duplicate locations. GRID_INPUT, x, y, data, xSorted, ySorted, dataSorted ; Initialize the grid parameters. gridSize = [51, 51] ; Use the equation of a straight line and the grid parameters to ; determine the x of the resulting grid. slope = (MAX(xSorted) - MIN(xSorted))/(gridSize[0] - 1) intercept = MIN(xSorted) xGrid = (slope*FINDGEN(gridSize[0])) + intercept ; Use the equation of a straight line and the grid parameters to ; determine the y of the resulting grid. slope = (MAX(ySorted) - MIN(ySorted))/(gridSize[1] - 1) intercept = MIN(ySorted) yGrid = (slope*FINDGEN(gridSize[1])) + intercept ; Initialize display. DEVICE, DECOMPOSED = 0 LOADCT, 38 WINDOW, 0, XSIZE = 600, YSIZE = 600, $ TITLE = 'The Resulting Grid from the Radial Basis Function '+ $ 'Method with Faulting' !P.MULTI = [0, 1, 2, 0, 0] ; Define a fault area, which contains data points. faultVertices = [[2200, 4000], [2200, 3000], [2600, 2700], $ [2600, -50], [5050, -50], [5050, 4000], [2200, 4000]] faultConnectivity = [7, 0, 1, 2, 3, 4, 5, 6, -1] ; Grid the data with faulting using the Radial Basis Function ; method. grid = GRIDDATA(xSorted, ySorted, dataSorted, $ DIMENSION = gridSize, METHOD = 'RadialBasisFunction', $ FAULT_XY = faultVertices, FAULT_POLYGONS = faultConnectivity, $ MISSING = MIN(dataSorted)) ; Display grid results. CONTOUR, BYTSCL(grid), xGrid, YGrid, /XSTYLE, /YSTYLE, /FILL, $ LEVELS = BYTSCL(INDGEN(18)), C_COLORS = BYTSCL(INDGEN(18)), $ TITLE = 'Fault Area Contains Data ' + $ '(Fault Area in Dashed Lines)', XTITLE = 'x', YTITLE = 'y' ; Display outline of fault area. PLOTS, faultVertices, /DATA, LINESTYLE = 2, THICK = 2 ; Define a fault area, which does not contain data points. faultVertices = [[2600, -50], [2800, -50], [2800, 2700], $ [2400, 3000], [2400, 4000], [2200, 4000], [2200, 3000], $ [2600, 2700], [2600, -50]] faultConnectivity = [9, 0, 1, 2, 3, 4, 5, 6, 7, 8, -1] ; Grid the data with faulting using the Radial Basis Function ; method. grid = GRIDDATA(xSorted, ySorted, dataSorted, $ DIMENSION = gridSize, METHOD = 'RadialBasisFunction', $ FAULT_XY = faultVertices, FAULT_POLYGONS = faultConnectivity, $ MISSING = MIN(dataSorted)) ; Display grid results. CONTOUR, BYTSCL(grid), xGrid, YGrid, /XSTYLE, /YSTYLE, /FILL, $ LEVELS = BYTSCL(INDGEN(18)), C_COLORS = BYTSCL(INDGEN(18)), $ TITLE = 'Fault Area Does Not Contain Data '+ $ '(Fault Area in Dashed Lines)', XTITLE = 'x', YTITLE = 'y' ; Display outline of fault area. PLOTS, faultVertices, /DATA, LINESTYLE = 2, THICK = 2 ; Set system variable back to default value. !P.MULTI = 0 References Kriging Isaaks, E. H., and Srivastava, R. M., An Introduction to Applied Geostatistics, Oxford University Press, New York, 1989. Minimum Curvature Barrodale, I., et al, "Warping Digital Images Using Thin Plate Splines", Pattern Recognition, Vol 26, No 2, pp. 375-376., 1993. Powell, M.J.D., "Tabulation of thin plate splines on a very fine two-dimensional grid", Report No. DAMTP 1992/NA2, University of Cambridge, Cambridge, U.K. 1992. Modified Shepard's Franke, R., and Nielson, G. , "Smooth Interpolation of Large Sets of Scattered Data", International Journal for Numerical Methods in Engineering, v. 15, 1980, pp. 1691- 1704. Renka, R. J., Algorithm 790 - CSHEP2D: Cubic Shepard Method for Bivariate Interpolation of Scattered Data, Robert J. Renka, ACM Trans. Math Softw. 25, 1 (March 1999), pp. 70-73. Shepard, D., "A Two Dimensional Interpolation Function for Irregularly Spaced Data", Proc. 23rd Nat. Conf. ACM, 1968, pp. 517-523. Natural Neighbor Watson, D. F., Contouring: A Guide to the Analysis and Display of Spatial Data, Pergamon Press, ISBN 0 08 040286 0, 1992. Watson, D. F., Nngridr - An Implementation of Natural Neighbor Interpolation, David Watson, P.O. Box 734, Clarement, WA 6010, Australia, 1994. Quintic Akima, H., Algorithm 761 - Scattered-data Surface Fitting that has the Accuracy of a Cubic Polynomial, Hiroshi Akima, ACM Trans. Math. Softw. 22, 3 (Sep. 1996), pp. 362 - 371. Renka, R.J., "A Triangle-based C1 Interpolation Method", Rocky Mountain Journal of Mathematics, Vol 14, No. 1, 1984. Radial Basis Function Franke, R., A Critical Comparison of Some Methods for Interpolation of Scattered Data, Naval Postgraduate School, Technical Report, NPS 53-79-003, 1979. Hardy, R.L., "Theory and Applications of the Multiquadric-biharmonic Method", Computers Math. With Applic, v 19, no. 8/9, 1990, pp.163-208. See Also GRID_INPUT HDF_VD_ATTRFIND [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_VD_ATTRFIND The HDF_VD_ATTRFIND function returns an attribute's index number given the name of an attribute associated with the specified vdata or vdata/field pair. If the attribute cannot be located, ­1 is returned. Syntax Result = HDF_VD_ATTRFIND(VData, FieldID, Name) Arguments VData The VData handle returned by a previous call to HDF_VD_ATTACH. FieldID A zero-based index specifying the field, or a string containing the name of the field within the VData to which the attribute is attached. Setting FieldID to ­1 specifies that the attribute is attached to the vdata itself. Name A string containing the name of the attribute whose index is to be returned. Example For an example using this routine, see the documentation for HDF_VD_ATTRSET. See Also HDF_VD_ATTRINFO, HDF_VD_ATTRSET, HDF_VD_ISATTR, HDF_VD_NATTRS HDF_VD_ATTRINFO [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_VD_ATTRINFO The HDF_VD_ATTRINFO procedure reads or retrieves information about a vdata attribute or a vdata field attribute from the currently attached HDF vdata structure. If the attribute is not present, an error message is printed. Syntax HDF_VD_ATTRINFO, VData, FieldID, AttrID, Values [, COUNT=variable] [, DATA=variable] [, HDF_TYPE=variable] [, NAME=variable ] [, TYPE=variable] Arguments VData The VData handle returned by a previous call to HDF_VD_ATTACH. FieldID A zero-based index specifying the field, or a string containing the name of the field within the VData whose attribute is to be read. Setting FieldID to -1 specifies that the attribute to be read is attached to the vdata itself. AttrID A zero-based integer index specifying the attribute to be read, or a string containing the name of that attribute. Values The attribute value(s) to be written. Keywords COUNT Set this keyword to a named variable in which the number of data values (order of the attribute) is returned. DATA Set this keyword to a named variable in which the attribute data is returned. HDF_TYPE Set this keyword to a named variable in which the HDF data type of the attribute is returned as a scalar string. NAME Set this keyword to a named variable in which the name of the attribute is returned. TYPE Set this keyword to a named variable in which the IDL type of the attribute is returned as a scalar string. Example For an example using this routine, see the documentation for HDF_VD_ATTRSET. See Also HDF_VD_ATTRFIND, HDF_VD_ATTRSET, HDF_VD_ISATTR, HDF_VD_NATTRS HDF_VD_ATTRSET [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_VD_ATTRSET The HDF_VD_ATTRSET procedure writes a vdata attribute or a vdata field attribute to the currently attached HDF vdata structure. If no data type keyword is specified, the data type of the attribute value is used. Syntax HDF_VD_ATTRSET, VData, FieldID, Attr_Name, Values [, Count] [, /BYTE] [, /DFNT_CHAR8] [, /DFNT_FLOAT32] [, /DFNT_FLOAT64] [, /DFNT_INT8] [, /DFNT_INT16] [, /DFNT_INT32] [, /DFNT_UCHAR8] [, /DFNT_UINT8] [, /DFNT_UINT16] [, /DFNT_UINT32] [, /DOUBLE] [, /FLOAT] [, /INT] [, /LONG] [, /SHORT] [, /STRING] [, /UINT ] [, /ULONG ] Arguments VData The VData handle returned by a previous call to HDF_VD_ATTACH. Note The vdata structure must have been attached in write mode in order for attributes to be correctly associated with a vdata or one of its fields. If the vdata is not write accessible, HDF does not return an error; instead, the attribute information is written to the file but is not associated with the vdata. FieldID A zero-based index specifying the field, or a string containing the name of the field within the VData whose attribute is to be set. If FieldID is set to -1, the attribute will be attached to the vdata itself. Attr_Name A string containing the name of the attribute to be written. Values The attribute value(s) to be written. Note Attributes to be written as characters may not be a multi-dimensional array (e.g. if being converted from byte values) or an array of IDL strings. Count An optional integer argument specifying how many values are to be written. Count must be less than or equal to the number of elements in the Values argument. If not specified, the actual number of values present will be written. Keywords BYTE Set this keyword to indicate that the attribute is composed of bytes. Data will be stored with the HDF DFNT_UINT8 data type. Setting this keyword is the same as setting the DFNT_UINT8 keyword. DFNT_CHAR8 Set this keyword to create an attribute of HDF type DFNT_CHAR8. Setting this keyword is the same as setting the STRING keyword. DFNT_FLOAT32 Set this keyword to create an attribute of HDF type DFNT_FLOAT32. Setting this keyword is the same as setting the FLOAT keyword. DFNT_FLOAT64 Set this keyword to create an attribute of HDF type DFNT_FLOAT64. Setting this keyword is the same as setting the DOUBLE keyword. DFNT_INT8 Set this keyword to create an attribute of HDF type DFNT_INT8. DFNT_INT16 Set this keyword to create an attribute of HDF type DFNT_INT16. Setting this keyword is the same as setting either the INT keyword or the SHORT keyword. DFNT_INT32 Set this keyword to create an attribute of HDF type DFNT_INT32. Setting this keyword is the same as setting the LONG keyword. DFNT_UCHAR8 Set this keyword to create an attribute of HDF type DFNT_UCHAR8. DFNT_UINT8 Set this keyword to create an attribute of HDF type DFNT_UINT8. Setting this keyword is the same as setting the BYTE keyword. DFNT_UINT16 Set this keyword to create an attribute of HDF type DFNT_UINT16. DFNT_UINT32 Set this keyword to create an attribute of HDF type DFNT_UINT32. DOUBLE Set this keyword to indicate that the attribute is composed of double-precision floating-point values. Data will be stored with the HDF type DFNT_FLOAT64. Setting this keyword is the same as setting the DFNT_FLOAT64 keyword. FLOAT Set this keyword to indicate that the attribute is composed of single-precision floating-point values. Data will be stored with the HDF type DFNT_FLOAT32 data type. Setting this keyword is the same as setting the DFNT_FLOAT32 keyword. INT Set this keyword to indicate that the attribute is composed of 16-bit integers. Data will be stored with the HDF type DFNT_INT16 data type. Setting this keyword is the same as setting either the SHORT keyword or the DFNT_INT16 keyword. LONG Set this keyword to indicate that the attribute is composed of longword integers. Data will be stored with the HDF type DFNT_INT32 data type. Setting this keyword is the same as setting the DFNT_INT32 keyword. SHORT Set this keyword to indicate that the attribute is composed of 16-bit integers. Data will be stored with the HDF type DFNT_INT16 data type. Setting this keyword is the same as setting either the INT keyword or the DFNT_INT16 keyword. STRING Set this keyword to indicate that the attribute is composed of strings. Data will be stored with the HDF type DFNT_CHAR8 data type. Setting this keyword is the same as setting the DFNT_CHAR8 keyword. UINT Set this keyword to indicate that the attribute is composed of unsigned 2-byte integers. Data will be stored with the HDF type DFNT_UINT16 data type. Setting this keyword is the same as setting the DFNT_UINT16 keyword. ULONG Set this keyword to indicate that the attribute is composed of unsigned longword integers. Data will be stored with the HDF type DFNT_UINT32 data type. Setting this keyword is the same as setting the DFNT_UINT32 keyword. Example ; Open an HDF file. fid = HDF_OPEN(FILEPATH('vattr_example.hdf',$ SUBDIRECTORY = ['examples', 'data']), /RDWR) ; Locate and attach an existing vdata. vdref = HDF_VD_FIND(fid, 'MetObs') vdid = HDF_VD_ATTACH(fid, vdref, /WRITE) ; Attach two attributes to the vdata. HDF_VD_ATTRSET, vdid, -1, 'vdata_contents', $ 'Ground station meteorological observations.' HDF_VD_ATTRSET, vdid, -1, 'num_stations', 10 ; Attach an attribute to one of the fields in the vdata. HDF_VD_ATTRSET, vdid, 'TempDP', 'field_contents', $ 'Dew point temperature in degrees Celsius.' ; Get the number of attributes associated with the vdata. num_vdattr = HDF_VD_NATTRS(vdid, -1) PRINT, 'Number of attributes attached to vdata MetObs: ', $ num_vdattr ; Get information for one of the vdata attributes by first finding ; the attribute's index number. attr_index = HDF_VD_ATTRFIND(vdid, -1, 'vdata_contents') HDF_VD_ATTRINFO, vdid, 1, attr_index, $ NAME = attr_name,DATA = metobs_contents HELP, attr_name, metobs_contents ; Get information for another vdata attribute using the ; attribute's name. HDF_VD_ATTRINFO, vdid, -1, 'num_stations', DATA = num_stations, $ HDF_TYPE = hdftype, TYPE = idltype HELP, num_stations, hdftype,idltype PRINT, num_stations ; Get the number of attributes attached to the vdata field ; TempDP. num_fdattr = HDF_VD_NATTRS(vdid, 'TempDP') PRINT, 'Number of attributes attached to field TempDP: ', $ num_fdattr ; Get the information for the vdata field attribute. HDF_VD_ATTRINFO, vdid, 'TempDP', 'field_contents', $ COUNT = count, HDF_TYPE = hdftype, TYPE = idltype, $ DATA = dptemp_attr HELP, count, hdftype, idltype, dptemp_attr ; End access to the vdata. HDF_VD_DETACH, vdid ; Attach a vdata which stores one of the attribute values. vdid = HDF_VD_ATTACH(fid, 5) ; Get the vdata's name and check to see that it is indeed storing ; an attribute. HDF_VD_GET, vdid, NAME = vdname isattr = HDF_VD_ISATTR(vdid) HELP, vdname, isattr ; End access to the vdata and the HDF file. HDF_VD_DETACH, vdid HDF_CLOSE, fid IDL Output Number of attributes attached to vdata MetObs: 2 ATTR_NAME STRING = 'vdata_contents' METOBS_CONTENTS STRING = 'Ground station meteorological observations.' NUM_STATIONS INT = Array[1] HDFTYPE STRING = 'DFNT_INT16' IDLTYPE STRING = 'INT' 10 Number of attributes attached to field TempDP: 1 COUNT LONG = 41 HDFTYPE STRING = 'DFNT_CHAR8' IDLTYPE STRING = 'STRING' DPTEMP_ATTR STRING = 'Dew point temperature in degrees Celsius.' VDNAME STRING = 'field_contents' ISATTR LONG = 1 See Also HDF_VD_ATTRFIND, HDF_VD_ATTRINFO, HDF_VD_ISATTR, HDF_VD_NATTRS HDF_VD_ISATTR [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_VD_ISATTR The HDF_VD_ISATTR function returns TRUE (1) if the vdata is storing an attribute, FALSE (0) otherwise. HDF stores attributes as vdatas, so this routine provides a means to test whether or not a particular vdata contains an attribute. Syntax Result = HDF_VD_ISATTR(VData) Arguments VData The VData handle returned by a previous call to HDF_VD_ATTACH. Example For an example using this routine, see the documentation for HDF_VD_ATTRSET. See Also HDF_VD_ATTRFIND, HDF_VD_ATTRINFO, HDF_VD_ATTRSET, HDF_VD_NATTRS HDF_VD_NATTRS [Previous Routine] [Next Routine] [List of Routines] NAME: HDF_VD_NATTRS The HDF_VD_NATTRS function returns the number of attributes associated with the specified vdata or vdata/field pair if successful. Otherwise, ­1 is returned. Syntax Result = HDF_ VD _NATTRS( VData, FieldID ) Arguments VData The VData handle returned by a previous call to HDF_VD_ATTACH. FieldID A zero-based index specifying the field, or a string containing the name of the field, within the VData whose attributes are to be counted. Setting Index to ­1 specifies that attributes attached to the vdata itself are to be counted. Example For an example using this routine, see the documentation for HDF_VD_ATTRSET. See Also HDF_VD_ATTRFIND, HDF_VD_ATTRINFO, HDF_VD_ATTRSET, HDF_VD_ISATTR HEAP_FREE [Previous Routine] [Next Routine] [List of Routines] NAME: HEAP_FREE The HEAP_FREE procedure recursively frees all heap variables (pointers or objects) referenced by its input argument. This routine examines the input variable, including all array elements and structure fields. When a valid pointer or object reference is encountered, that heap variable is marked for removal, and then is recursively examined for additional heap variables to be freed. In this way, all heap variables that are referenced directly or indirectly by the input argument are located. Once all such heap variables are identified, HEAP_FREE releases them in a final pass. Pointers are released as if the PTR_FREE procedure was called. Objects are released as with a call to OBJ_DESTROY. As with the related HEAP_GC procedure, there are some disadvantages to using HEAP_FREE such as: * When freeing object heap variables, HEAP_FREE calls OBJ_DESTROY without supplying any plain or keyword arguments. Depending on the objects being released, this may not be sufficient. In such cases, the caller must call OBJ_DESTROY explicitly with the proper arguments rather than using HEAP_FREE. * HEAP_FREE releases the referenced heap variables in an unspecified order which depends on the current state of the internal data structure used by IDL to hold them. This can be confusing for object destructor methods that expect all of their contained data to be present. If your application requires a specific order for the release of its heap variables, you must explicitly free them in the correct order. HEAP_FREE cannot be used in such cases. * The algorithm used by HEAP_FREE to release variables requires examination of every existing heap variable (that is, it is an O(n) algorithm). This may be slow if an IDL session has thousands of current heap variables. For these reasons, Research Systems recommends that applications keep careful track of their heap variable usage, and explicitly free them at the proper time (for example, using the object destructor method) rather than resorting to simple-looking but potentially expensive expedients such as HEAP_FREE or HEAP_GC. HEAP_FREE is recommended when: * The data structures involved are highly complex, nested, or variable, and writing cleanup code is difficult and error prone. * The data structures are opaque, and the code cleaning up does not have knowledge of the structure. Syntax HEAP_FREE, Var [, /OBJ] [, /PTR] [, /VERBOSE] Arguments Var The variable whose data is used as the starting point for heap variables to be freed. Keywords OBJ Set this keyword to free object heap variables only. PTR Set this keyword to free pointer heap variables only. Note Setting both the PTR and OBJ keywords is the same as setting neither. VERBOSE If this keyword is set, HEAP_FREE writes a one line description of each heap variable, in the format used by the HELP procedure, as the variable is released. This is a debugging aid that can be used by program developers to check for heap variable leaks that need to be located and eliminated. Example ; Create a structure variable. mySubStructure = {pointer:PTR_NEW(INDGEN(100)), $ obj:OBJ_NEW('Idl_Container')} myStructure ={substruct:mySubStructure, $ ptrs:[PTR_NEW(INDGEN(10)), PTR_NEW(INDGEN(11))]} ;Look at the heap. HELP, /HEAP_VARIABLES ; Now free the heap variables contained in myStructure. HEAP_FREE, myStructure, /VERBOSE HELP, /HEAP_VARIABLES See Also HEAP_GC INTERVAL_VOLUME [Previous Routine] [Next Routine] [List of Routines] NAME: INTERVAL_VOLUME The new INTERVAL_VOLUME procedure is used to generate a tetrahedral mesh from volumetric data. The generated mesh spans the portion of the volume where the volume data samples fall between two constant data values. This can also be thought of as a mesh constructed to fill the volume between two isosurfaces which are drawn according to the two supplied constant data values. The algorithm is very similar to the ISOSURFACE algorithm and expands upon the SHADE_VOLUME algorithm. A topologically-consistent tetrahedral mesh is returned by decomposing the volume into oriented tetrahedra. This also allows the algorithm to find the interval volume of any tetrahedral mesh. If an auxiliary array is provided, its data is interpolated onto the output vertices and is returned. This auxiliary data array may have multiple values at each vertex. Any size- leading dimension is allowed as long as the number of values in the subsequent dimensions matches the number of elements in the input data array. For more information on the INTERVAL_VOLUME algorithm, see the paper, "Interval Volume Tetrahedrization", Nielson and Sung, Proceedings: IEEE Visualization, 1997. Syntax INTERVAL_VOLUME, Data, Value0, Value1, Outverts, Outconn [, AUXDATA_IN=array, AUXDATA_OUT=variable] [, GEOM_XYZ=array, TETRAHEDRA=array] Arguments Data Input three-dimensional array of scalars that define the volume data. Value0 Input scalar iso-value. This value specifies one of the limits for the interval volume. The generated interval volume encloses all volume samples between and including Value0 and Value1. Value0 may be greater than or less than Value1, but the two values may not be exactly equal. This value also cannot be a NaN, but can be +/- INF. Value1 Input scalar iso-value. This value specifies the other limit for the interval volume. The generated interval volume encloses all volume samples between and including Value0 and Value1. Value1 may be greater than or less than Value0, but the two values may not be exactly equal. This value also cannot be a NaN, but can be +/- INF. Outverts A named variable to contain an output [3, n] array of floating point vertices making up the tetrahedral mesh. Outconn A named variable to contain an output array of tetrahedral mesh connectivity values. This array is one-dimensional and consists of a series of four vertex indices, where each group of four indices describes a tetrahedron. The connectivity values are indices into the vertex array returned in Outverts. If no tetrahedra are extracted, this argument returns the array [-1]. Keywords AUXDATA_IN This keyword defines the input array of auxiliary data with trailing dimensions being the number of values in Data. Note If you specify the AUXDATA_IN then you must specify AUXDATA_OUT. AUXDATA_OUT Set this keyword to a named variable that will contain an output array of auxiliary data sampled at the locations in Outverts. Note If you specify AUXDATA_OUT then you must specify AUXDATA_IN. GEOM_XYZ This keyword defines a [3, n] input array of vertex coordinates (one for each value in the Data array). This array is used to define the spatial location of each scalar. If this keyword is omitted, Data must be a three-dimensional array and the scalar locations are assumed to be on a uniform grid. Note If you specify GEOM_XYZ then you must specify TETRAHEDRA. TETRAHEDRA This keyword defines an input array of tetrahedral connectivity values. If this array is not specified, the connectivity is assumed to be a rectilinear grid over the input three- dimensional array. If this keyword is specified, the input data array need not be a three-dimensional array. Each tetrahedron is represented by four values in the connectivity array. Every four values in the array correspond to the vertices of a single tetrahedron. Note If you specify TETRAHEDRA then you must specify GEOM_XYZ. Example The following example generates an interval volume and displays the surface of the volume: RESTORE, FILEPATH('clouds3d.dat', $ SUBDIRECTORY=['examples','data']) INTERVAL_VOLUME, rain, 0.1, 0.6, verts, conn conn = TETRA_SURFACE(verts, conn) oRain = OBJ_NEW('IDLgrPolygon', verts, POLYGONS=conn, $ COLOR=[255,255,255], SHADING=1) XOBJVIEW, oRain, BACKGROUND=[150,200,255] See Also ISOSURFACE, SHADE_VOLUME, XVOLUME PATH_SEP [Previous Routine] [Next Routine] [List of Routines] NAME: PATH_SEP The PATH_SEP function returns the proper file path segment separator character for the current operating system. This is the character used by the host operating system for delimiting subdirectory names in a path specification. Use of this function instead of hard wiring separators makes code more portable. This routine is written in the IDL language. Its source code can be found in the file path_sep.pro in the lib subdirectory of the IDL distribution. Syntax Result = PATH_SEP( [ /PARENT_DIRECTORY ] [, /SEARCH_PATH ] ) Arguments None. Keywords PARENT_DIRECTORY If set, PATH_SEP returns the standard directory notation used by the host operating system to indicate the parent of a directory. SEARCH_PATH If set, PATH_SEP returns the character used to separate entries in a search path. See Also FILEPATH, FILE_SEARCH QGRID3 [Previous Routine] [Next Routine] [List of Routines] NAME: QGRID3 The QGRID3 function linearly interpolates the dependent variable values to points in a regularly sampled volume. Its inputs are a triangulation of scattered data points in three dimensions, and the value of a dependent variable for each point. Syntax Result = QGRID3( XYZ, F, Tetrahedra [, DELTA=vector ] [, DIMENSION=vector ] [, MISSING=value ] [, START=vector ] ) or Result = QGRID3( X, Y, Z, F, Tetrahedra [, DELTA=array ] [, DIMENSION=array ] [, MISSING=value ] [, START=array ] ) Return Value Result is a 3-dimensional array of either single or double precision floating type, of the specified dimensions. Arguments XYZ This is a 3-by-n array containing the scattered points. X, Y, Z One-dimensional vectors containing the X, Y, and Z point coordinates. Tetrahedra A longword array containing the point indices of each tetrahedron, as created by QHULL. Keywords Note Any of the keywords may be set to a scalar if all elements are the same. DELTA A scalar or three element array specifying the grid spacing in X, Y, and Z. If this keyword is not specified, it is set to create a grid of DIMENSION cells, enclosing the volume from START to [max(x), max(y), max(z)]. DIMENSION A three element array specifying the grid dimensions in X, Y, and Z. Default value is 25 for each dimension. MISSING The value to be used for grid points that lie outside the convex hull of the scattered points. The default is 0. START A three element array specifying the start of the grid in X, Y, and Z. Default value is [min(x), min(y), min(z)]. Example 1 This example interpolates a data set measured on an irregular grid. ; Create a dataset of N points. n = 200 x = RANDOMU(seed, n) y = RANDOMU(seed, n) z = RANDOMU(seed, n) ; Create dependent variable. f = x^2 - x*y + z^2 + 1 ; Obtain a tetrahedra using the QHULL procedure. QHULL, x, y, z, tet, /DELAUNAY ; Create a volume with dimensions [51, 51, 51] ; over the unit cube. volume = QGRID3(x, y, z, f, tet, START=0, DIMENSION=51, $ DELTA=0.02) ; Display the volume. XVOLUME, BYTSCL(volume) Example 2 This example is similar to the previous one, however in this example we use a [3, n] array of points. ; Create a dataset of N points. n = 200 p = RANDOMU(seed, 3, n) ; Create dependent variable. f = p[0,*]^2 - p[0,*]*p[1,*] + p[2,*]^2 + 1 ; Obtain a tetrahedra. QHULL, p, tet, /DELAUNAY ; Create a volume with dimensions [51, 51, 51] over the unit cube. volume = QGRID3(p, f, tet, START=0, DIMENSION=51, DELTA=0.02) ; Display the volume. XVOLUME, BYTSCL(volume) Example 3 The following example uses the data from the irreg_grid2.txt ASCII file. This file contains scattered three-dimensional data. This file contains bore hole data for a square mile of land. The QHULL procedure is used to triangulate the three- dimensional locations. The QGRID3 function uses the results from QHULL to grid the data into a volume. The scattered data is displayed as symbol polyline objects in the XOBJVIEW utility. The resulting gridded volume is displayed in the XVOLUME utility: ; Import the Data: ; Determine the path to the file. This file contains bore hole ; data for a square mile of land. The bore hole samples were ; roughly taken diagonally from the upper left corner of the ; square to the lower right corner. file = FILEPATH('irreg_grid2.txt', $ SUBDIRECTORY = ['examples', 'data']) ; Import the data from the file into a structure. dataStructure = READ_ASCII(file) ; Get the imported array from the first field of ; the structure. dataArray = TRANSPOSE(dataStructure.field1) ; Initialize the variables of this example from ; the imported array. x = dataArray[*, 0] y = dataArray[*, 1] z = dataArray[*, 2] data = dataArray[*, 3] ; Determine number of data points. nPoints = N_ELEMENTS(data) ; Triangulate the Data with QHULL: ; Construct the convex hulls of the volume. QHULL, x, y, z, tetrahedra, /DELAUNAY ; Grid the Data and Display the Results: ; Initialize volume parameters. cubeSize = [51, 51, 51] ; Grid the data into a volume. volume = QGRID3(x, y, z, data, tetrahedra, START = 0, $ DIMENSION = cubeSize, DELTA = 0.02) ; Scale the volume to be able to view the full data value range ; with the color tables provided in the XVOLUME utility. scaledVolume = BYTSCL(volume) ; Display the results in the XVOLUME utility. XVOLUME, scaledVolume ; Derive the isosurface for mineral deposits with the data value ; of 2.5. ISOSURFACE, volume, 2.5, vertices, connectivity ; Initialize a model to contain the isosurface. oModel = OBJ_NEW('IDLgrModel') ; Initialize the polygon object of the isosurface. oPolygon = OBJ_NEW('IDLgrPolygon', vertices, $ POLYGONS = connectivity, COLOR = [0, 0, 255]) ; Determine the range in each direction. xRange = [0, cubeSize[0]] yRange = [0, cubeSize[1]] zRange = [0, cubeSize[2]] ; Initialize an axis for each direction. oAxes = OBJARR(3) oAxes[0] = OBJ_NEW('IDLgrAxis', 0, RANGE = xRange, $ LOCATION = [xRange[0], yRange[0], zRange[0]], /EXACT, $ TICKLEN = (0.02*(yRange[1] - yRange[0]))) oAxes[1] = OBJ_NEW('IDLgrAxis', 1, RANGE = yRange, $ LOCATION = [xRange[0], yRange[0], zRange[0]], /EXACT, $ TICKLEN = (0.02*(xRange[1] - xRange[0]))) oAxes[2] = OBJ_NEW('IDLgrAxis', 2, RANGE = zRange, $ LOCATION = [xRange[0], yRange[1], zRange[0]], /EXACT, $ TICKLEN = (0.02*(xRange[1] - xRange[0]))) ; Add the polygon and axes object to the model. oModel -> Add, oPolygon oModel -> Add, oAxes ; Rotate the model for a better perspective. oModel -> Rotate, [0, 0, 1], 30. oModel -> Rotate, [1, 0, 0], -45. ; Display the model, which contains the isosurface. XOBJVIEW, oModel, /BLOCK, SCALE = 0.75, $ TITLE = 'Isosurface at the Value of 2.5' ; Cleanup object references. OBJ_DESTROY, [oModel] See Also QHULL QHULL [Previous Routine] [Next Routine] [List of Routines] NAME: QHULL The QHULL procedure constructs convex hulls, Delaunay triangulations, and Voronoi diagrams of a set of points of 2-dimensions or higher. It uses and is based on the program QHULL, which is described in Barber, Dobkin and Huhdanpaa, "The Quickhull Algorithm for Convex Hulls," ACM Transactions on Mathematical Software, Vol. 22, No 4, December 1996, Pages 469-483. For more information about QHULL see h Syntax QHULL, V, Tr or, QHULL, V0 , V1, [, V2 ... [, V6] ] , Tr [, BOUNDS=variable ] [, CONNECTIVITY=variable ] [, /DELAUNAY ] [, SPHERE=variable ] [, VDIAGRAM=array ] [, VNORMALS=array ] [, VVERTICES=array ] Arguments V An input argument providing an nd-by-np array containing the locations of np points, in nd dimensions. The number of dimensions, nd, must be greater than or equal to 2. V0, V1, V2, ..., V(N­1) Input vectors of dimension np-by-1 elements each containing the i-th coordinate of np points in nd dimensions. A maximum of seven input vectors may be specified. Tr An nd1-by-nt array containing the indices of either the convex hull (nd1 is equal to nd), or the Delaunay triangulation (nd1 is equal to nd+1) of the input points. Keywords BOUNDS If set to a variable name, return the indices of the points on the convex hull of the input points. CONNECTIVITY Set this keyword to a named variable in which the adjacency list for each of the np nodes is returned. The list has the following form: Each element i, 0 i < np, contains the starting index of the connectivity list (list) for node i within the list array. To obtain the adjacency list for node i, extract the list elements from list[i] to list[i+1] ­ 1. The adjacency list is not ordered. To obtain the connectivity list, either the DELAUNAY or SPHERE keywords must also be specified. For example, to perform a spherical triangulation, use the following procedure call: QHULL, lon, lat, CONNECTIVITY = list which returns the adjacency list in the variable list. The subscripts of the nodes adjacent to lon[i] and lat[i] are contained in the array: list[list[i] :list[i+1] ­ 1]. DELAUNAY Performs a Delaunay triangulation and returns the vertex indices of the resulting polyhedra; otherwise, the convex hull of the data are returned. SPHERE Computes the Delaunay triangulation of the points which lie on the surface of a sphere. The V0 argument contains the longitude, in degrees, and V1 contains the latitude, in degrees, of each point. VDIAGRAM When specified, this keyword returns the connectivity of the Voronoi diagram in a 4- by-nv integer array. For each Voronoi ridge, i, VDIAGRAM[0:1, i] contains the index of the two input points the ridge bisects. VDIAGRAM[2:3, i] contains the indices of the Voronoi vertices. In the case of an unbounded half-space, VDIAGRAM[2, i] is set a negative index, j, indicating that the corresponding Voronoi ridge is unbounded, and that the equation for the ridge is contained in VNORMAL[*, ­j], and starts at Voronoi vertex [3, i]. VNORMALS When specified, this keyword returns the normals of each Voronoi ridge that is unbounded. See the description of VDIAGRAM. VVERTICES When specified, this keyword returns the Voronoi vertices. Example For some examples using the QHULL procedure, see the QGRID3 function. See Also QGRID3 QUERY_MRSID [Previous Routine] [Next Routine] [List of Routines] NAME: QUERY_MRSID The QUERY_MRSID function allows you to obtain information about a MrSID image file without having to read the file. It is a wrapper around the object interface that presents MrSID image loading in a familiar way to users of the QUERY_* image routines. However this function is not as efficient as the object interface and the object interface should be used whenever possible. See "IDLffMrSID" in Chapter 5 "New Objects" for information about the object interface. Syntax Result = QUERY_MRSID( Filename [, Info] [, LEVEL=lvl] ) Return Value Result is a long integer with the value of: * 1 ­ If the query was successful (and the file type was correct). * 0 ­ If the query fails. Arguments Filename A scalar string containing the full path and filename of the MrSID file to query. Info Returns an anonymous structure containing information about the image in the file. The Info.TYPE field will return the value 'MrSID'. The anonymous structure is detailed in the QUERY_* Routines documentation. However, the info structure filled in by QUERY_MRSID has additional members appended to the end: * info.LEVELS ­ a named variable that will contain a two-element integer vector of the form [minlvl, maxlvl] that specifies the range of levels within the current image. Higher levels are lower resolution. A level of 0 equals full resolution. Negative values specify higher levels of resolution. * Info.GEO_VALID ­ a long integer with a value of 1 if the file contains valid georeferencing data, or 0 if the georeferencing data is nonexistent or unsupported. Note Always verify that this keyword returns 1 before using the data returned by any other GEO_* keyword. * Info.GEO_PROJTYPE ­ unsigned integer. * Info.GEO_ORIGIN ­ 2-element double precision array. * Info.GEO_RESOLUTION ­ 2-element double precision array. See "IDLffMrSID::GetProperty" in Chapter 5 for more information on GEO_* values. Keywords LEVEL Set this keyword to an integer that specifies the level to which the DIMENSIONS field of the info structure corresponds. This can be used, for example, to determine what level is required to fit the image into a certain area. If this keyword is not specified, the dimensions at level 0 are returned. Example ; Select the image file. file = QUERY_MRSID(FILEPATH('test_gs.sid', $ SUBDIRECTORY=['examples', 'data']), info, LEVEL = -2) HELP, file ; IDL returns 1 indicating the correct file type ; and successful query. ; Print the range of levels of resolution available within ; the file. PRINT, 'Range of image levels = ', info.LEVELS ; Print the image dimensions when the image level is set to -2 ; as specified by LEVEL = -2 in the QUERY_MRSID statement. PRINT, 'dimensions of image at LEVEL is -2 =', info.DIMENSIONS ; IDL returns 2048 by 2048 ; Check for valid georeferencing data. PRINT, 'Result of georeferencing query', info.GEO_VALID ; IDL returns 0 indicating that the file does not contain ; georeferencing data. READ_MRSID [Previous Routine] [Next Routine] [List of Routines] NAME: READ_MRSID The new READ_MRSID function extracts and returns image data from a MrSID file at the specified level and location. It is a wrapper around the object interface that presents MrSID image loading in a familiar way to users of the READ_* image routines. However this function is not as efficient as the object interface and the object interface should be used whenever possible. See "IDLffMrSID" in Chapter 5 for information about the object interface. Syntax Result = READ_MRSID ( Filename [, LEVEL=lvl] [, SUB_RECT=rect] ) Return Value ImageData returns an n-by-w-by-h array containing the image data where n is 1 for grayscale or 3 for RGB images, w is the width and h is the height. Note The returned image is ordered bottom-up, the first pixel returned is located at the bottom-left of the image. This differs from how data is stored in the MrSID file where the image is top-down, meaning the pixel at the start of the file is located at the top-left of the image. Arguments Filename A scalar string containing the full path and filename of the MrSID file to read. Keywords LEVEL Set this keyword to an integer that specifies the level at which to read the image. If this keyword is not set, the maximum level (see QUERY_MRSID) is used which returns the minimum resolution. SUB_RECT Set this keyword to a four-element vector [x, y, xdim, ydim] specifying the position of the lower left-hand corner and the dimensions of the sub-rectangle of the MrSID image to return. This is useful for displaying only a portion of the high-resolution image. If this keyword is not set, the entire image will be returned. This may require significant memory if a high-resolution level is selected. If the sub-rectangle is greater than the bounds of the image at the selected level the area outside the image bounds will be set to black. Note The elements of SUB_RECT are measured in pixels at the current level. This means the point x = 10, y = 10 at level 1 will be located at x = 20, y = 20 at level 0 and x = 5, y = 5 at level 2. Example ; Query the file. result = QUERY_MRSID(FILEPATH('test_gs.sid', $ SUBDIRECTORY = ['examples', 'data']), info) ; If result is not zero, read in an image from the file and ; display it. IF (result NE 0) THEN BEGIN PRINT, info imageData = READ_MRSID(FILEPATH('test_gs.sid', $ SUBDIRECTORY = ['examples', 'data']), SUB_RECT = $ [0, 0, 200, 200], LEVEL = 3) oImage = OBJ_NEW('IDLgrImage', imageData, ORDER = 0) XOBJVIEW, oImage, BACKGROUND = [255,255,0] ENDIF ; Use the file access object to query the file. oMrSID = OBJ_NEW('IDLffMrSID', FILEPATH('test_gs.sid', $ SUBDIRECTORY = ['examples', 'data'])) oMrSID -> GetProperty, PIXEL_TYPE=pt, $ CHANNELS = chan, DIMENSIONS = dims, $ TYPE = type, LEVELS = lvls PRINT, pt, chan, dims, type, lvls ; Use the object to read in an image from the file. lvls = -3 dimsatlvl = oMrSID -> GetDimsAtLevel(lvls) PRINT, dimsatlvl imageData = oMrSID -> GetImageData(LEVEL = 3) PRINT, size(imageData) OBJ_DESTROY, oImage REAL_PART [Previous Routine] [Next Routine] [List of Routines] NAME: REAL_PART The REAL_PART function returns the real part of its complex-valued argument. If the complex-valued argument is double-precision, the result will be double-precision, otherwise the result will be single-precision floating-point. If the argument is not complex, then the result will be double-precision if the argument is double-precision, otherwise the result will be single-precision. Syntax Result = REAL_PART(Z) Arguments Z A scalar or array for which the real part is desired. Z may be of any numeric type. Example The following example demonstrates how you can use REAL_PART to obtain the real parts of an array of complex variables. ; Create an array of complex values: cValues = COMPLEX([1, 2, 3],[4, 5, 6]) ; Print just the real parts of each element in cValues: PRINT, REAL_PART(cValues) IDL prints: 1.00000 2.00000 3.00000 See Also COMPLEX, DCOMPLEX, IMAGINARY REGION_GROW [Previous Routine] [Next Routine] [List of Routines] NAME: REGION_GROW The REGION_GROW function performs region growing for a given region within an N-dimensional array by finding all pixels within the array that are connected neighbors to the region pixels and that fall within provided constraints. The constraints are specified either as a threshold range (a minimum and maximum pixel value) or as a multiple of the standard deviation of the region pixel values. If the threshold is used (this is the default), the region is grown to include all connected neighboring pixels that fall within the given threshold range. If the standard deviation multiplier is used, the region is grown to include all connected neighboring pixels that fall within the range of the mean (of the region's pixel values) plus or minus the given multiplier times the sample standard deviation. REGION_GROW returns the vector of array indices that represent pixels within the grown region. The grown region will not include pixels at the edges of the input array. If no pixels fall within the grown region, this function will return the value -1. Syntax Result = REGION_GROW(Array, ROIPixels [, /ALL_NEIGHBORS] [, STDDEV_MULTIPLIER=value | THRESHOLD=[min,max]] ) Arguments Array An N-dimensional array of data values. The region will be grown according to the data values within this array. ROIPixels A vector of indices into Array that represent the initial region that is to be grown. Keywords ALL_NEIGHBORS Set this keyword to indicate that all adjacent neighbors to a given pixel should be considered during region growing (sometimes known as 8-neighbor searching when the array is two-dimensional). The default is to search only the neighbors that are exactly one unit in distance from the current pixel (sometimes known as 4-neighbor searching when the array is two-dimensional). STDDEV_MULTIPLIER Set this keyword to a scalar value that serves as the multiplier of the sample standard deviation of the original region pixel values. The expanded region includes neighboring pixels that fall within the range of the mean of the region's pixel values plus or minus the given multiplier times the sample standard deviation as follows: Mean +/- StdDevMultiplier * StdDev This keyword is mutually exclusive of THRESHOLD. If both keywords are specified, a warning message will be issued and the THRESHOLD value will be used. THRESHOLD Set this keyword to a two-element vector, [min,max], of the inclusive range within which the pixel values of the grown region must fall. The default is the range of pixel values within the initial region. This keyword is mutually exclusive of STDDEV_MULTIPLIER. If both keywords are specified, a warning message will be issued and the THRESHOLD value will be used. Note If neither keyword is specified, THRESHOLD is used by default. The range of threshold values is based upon the pixel values within the original region and therefore does not have to be provided. Example The following example demonstrates how you can grow a pre-defined region within an image of human red blood cells. ; Load an image. fname = FILEPATH('rbcells.jpg', SUBDIR=['examples','data']) READ_JPEG, fname, img imgDims = SIZE(img, /DIMENSIONS) ; Define original region pixels. x = FINDGEN(16*16) MOD 16 + 276. y = LINDGEN(16*16) / 16 + 254. roiPixels = x + y * imgDims[0] ; Grow the region. newROIPixels = REGION_GROW(img, roiPixels) ; Load a grayscale color table. DEVICE, DECOMPOSED = 0 LOADCT, 0 ; Set the topmost color table entry to red. topClr = !D.TABLE_SIZE-1 TVLCT, 255, 0, 0, topClr ; Show the results. tmpImg = BYTSCL(img, TOP=(topClr-1)) tmpImg[roiPixels] = topClr WINDOW, 0, XSIZE=imgDims[0], YSIZE=imgDims[1], $ TITLE='Original Region' TV, tmpImg tmpImg = BYTSCL(img, TOP=(topClr-1)) tmpImg[newROIPixels] = topClr WINDOW, 2, XSIZE=imgDims[0], YSIZE=imgDims[1], $ TITLE='Grown Region' TV, tmpImg SIMPLEX [Previous Routine] [Next Routine] [List of Routines] NAME: SIMPLEX The SIMPLEX function uses the simplex method to solve linear programming problems. Given a set of N independent variables Xi, where i = 1, ..., N, the simplex method seeks to maximize the following function, Z = a1X1 + a2X2 + ...aNXN with the assumption that Xi 0. The Xi are further constrained by the following equations: bj1X1 + bj2X2 + ...bjNXN cj j = 1, 2 ... , ,M1 bj1X1 + bj2X2 + ...bjNXN cj j = M1 + 1, M1 + 2 ... , , M1 + M2 bj1X1 + bj2X2 + ...bjNXN= cj j = M1 + M2 + 1, M1 + M2 + 2 ... , , M where M = M1 + M2 + M3 is the total number of equations, and the constraint values cj must all be positive. To solve the above problem using the SIMPLEX function, the Z equation is rewritten as a vector: Zequation = a1 a2 ...aN The constraint equations are rewritten as a matrix with N+1 columns and M rows, where all of the b coefficients have had their sign reversed: c1 ­b11 ­b12...­b1N c2 ­b21 ­b22...­b2N Constraints = : : : : : : cM ­bM1 ­bM2...­bMN Note The constraint matrix must be organized so that the coefficients for the less-than (<) equations come first, followed by the coefficients of the greater-than (>) equations, and then the coefficients of the equal (=) equations. The Result is a vector of N+1 elements containing the maximum Z value and the values of the N independent X variables (the optimal feasible vector): Result = Zmax X1 X2...XN The SIMPLEX function is based on the routine simplx described in section 10.8 of Numerical Recipes in C: The Art of Scientific Computing (Second Edition), published by Cambridge University Press, and is used by permission. Syntax Result = SIMPLEX( Zequation, Constraints, M1, M2, M3 [, Tableau [, Izrov [, Iposv] ] ] [, /DOUBLE] [, EPS = value] [, STATUS = variable] ) Arguments Zequation A vector containing the N coefficients of the Zequation to be maximized. Constraints An array of N+1 columns by M rows containing the constraint values and coefficients for the constraint equations. M1 An integer giving the number of less-than constraint equations contained in Constraints. M1 may be zero, indicating that there are no less than constraints. M2 An integer giving the number of greater-than constraint equations contained in Constraints. M2 may be zero, indicating that there are no greater than constraints. M3 An integer giving the number of equal-to constraint equations contained in Constraints. M3 may be zero, indicating that there are no equal to constraints. The total of M1 + M2 + M3 should equal M, the number of constraint equations. Tableau Set this optional argument to a named variable in which to return the output array from the simplex algorithm. For more detailed discussion about this argument, see the write-up in section 10.8 of Numerical Recipes in C. Izrov Set this optional argument to a named variable in which to return the output izrov variable from the simplex algorithm. For more detailed discussion about this argument, see the write-up in section 10.8 of Numerical Recipes in C. Iposv Set this optional argument to a named variable in which to return the output iposv variable from the simplex algorithm. For more detailed discussion about this argument, see the write-up in section 10.8 of Numerical Recipes in C. Keywords DOUBLE Set this keyword to use double-precision for computations and to return a double- precision result. Set DOUBLE to 0 to use single-precision for computations and to return a single-precision result. The default is /DOUBLE if any of the inputs are double-precision, otherwise the default is 0. EPS Set this keyword to a number close to machine accuracy, which is used to test for convergence at each iteration. The default is 10­6. STATUS Set this keyword to a named variable to receive the status of the operation. Possible status values are: Value Description 0 Successful completion. 1 The objective function is unbounded. 2 No solution satisfies the given constraints. 3 The routine did not converge. Table 6-3: SIMPLEX Function Status Values Example The following example is taken from Numerical Recipes in C. Find the Z value which maximizes the equation Z = X1 + X2 + 3 X3 - 0.5 X4, with the following constraints: X1 + 2X3 740 2X2 ­ 7X4 0 X2 ­ X3 + 2X4 0.5 X1 + X2 + X3 + X4 = 9 To find the solution, enter the following code at the IDL command line: ; Set up the Zequation with the X coefficients. Zequation = [1,1,3,-0.5] ; Set up the Constraints matrix. Constraints = [ $ [740, -1, 0, -2, 0], $ [ 0, 0, -2, 0, 7], $ [0.5, 0, -1, 1, -2], $ [ 9, -1, -1, -1, -1] ] ; Number of less-than constraint equations. m1 = 2 ; Number of greater-than constraint equations. m2 = 1 ; Number of equal constraint equations. m3 = 1 ;; Call the function. result = SIMPLEX(Zequation, Constraints, m1, m2, m3) ;; Print out the results. PRINT, 'Maximum Z value is: ', result[0] PRINT, 'X coefficients are: ' PRINT, result[1:*] IDL prints: Maximum Z value is: 17.0250 X coefficients are: 0.000000 3.32500 4.72500 0.950000 Therefore, the optimal feasible vector is X1 = 0.0, X2 = 3.325, X3 = 4.725, and X4 = 0.95. See Also AMOEBA, DFPMIN, POWELL WIDGET_ACTIVEX [Previous Routine] [Next Routine] [List of Routines] NAME: WIDGET_ACTIVEX The WIDGET_ACTIVEX function is used to create an ActiveX control in IDL and also to place it into an IDL widget hierarchy. The program or class ID of the underlying IDL object that represents the ActiveX control is retrieved using the GET_VALUE keyword of WIDGET_CONTROL. This is similar to the operations used to get the window object from an IDL draw widget. Note IDL ActiveX functionality is only supported on the Windows NT and Windows 2000 platforms. Note This is the only method to create an IDL object that represents an ActiveX control. Creating an ActiveX control (an object based off the class name prefix IDLcomActiveX$) using OBJ_NEW() is not supported and the results are undefined. Note All ActiveX based objects created in IDL sub-class from the intrinsic IDL class IDLcomActiveX, which is a sub-class from IDLcomIDispatch. Syntax Result = WIDGET_ACTIVEX( Parent, COM_ID, [, /ALIGN_BOTTOM | , /ALIGN_CENTER | , /ALIGN_LEFT | , /ALIGN_RIGHT | , /ALIGN_TOP] [, EVENT_FUNC=string] [, EVENT_PRO=string] [, FUNC_GET_VALUE=string] [ID_TYPE=value] [, KILL_NOTIFY=string] [, /NO_COPY] [, NOTIFY_REALIZE=string] [, PRO_SET_VALUE=string] [, SCR_XSIZE=width] [, SCR_YSIZE=height] [, /SENSITIVE] [, UNAME=string] [, UNITS={0 | 1 | 2}] [, UVALUE=value] [, XOFFSET=value] [, XSIZE=value] [, YOFFSET=value] [, YSIZE=value] ) Arguments Parent The widget ID of the parent widget of the new ActiveX control. COM_ID The class or program ID of the COM object to create. Note The provided Class ID or program ID must follow the standard Microsoft naming convention. So Class IDs will contain '{}' brackets and use '-' as a separator and Program IDs will use a '.' for a separator. The use of '_' is only used with IDispatch objects in the call to OBJ_NEW() because the object name must follow standard IDL object naming syntax. Keywords ALIGN_BOTTOM Set this keyword to align the new widget with the bottom of its parent base. To take effect, the parent must be a ROW base. ALIGN_CENTER Set this keyword to align the new widget with the center of its parent base. To take effect, the parent must be a ROW or COLUMN base. In ROW bases, the new widget will be vertically centered. In COLUMN bases, the new widget will be horizontally centered. ALIGN_LEFT Set this keyword to align the new widget with the left side of its parent base. To take effect, the parent must be a COLUMN base. ALIGN_RIGHT Set this keyword to align the new widget with the right side of its parent base. To take effect, the parent must be a COLUMN base. ALIGN_TOP Set this keyword to align the new widget with the top of its parent base. To take effect, the parent must be a ROW base. EVENT_FUNC A string containing the name of a function to be called by the WIDGET_EVENT function when an event arrives from a widget in the widget hierarchy rooted at the newly-created widget. EVENT_PRO A string containing the name of a procedure to be called by the WIDGET_EVENT function when an event arrives from a widget in the widget hierarchy rooted at the newly-created widget. Note If the base is a top-level base widget that is managed by the XMANAGER procedure, any value specified via the EVENT_PRO keyword is overridden by the value of the EVENT_HANDLER keyword to XMANAGER. Note also that in this situation, if EVENT_HANDLER is not specified in the call to XMANAGER, an event-handler name will be created by appending the string "_event" to the application name specified to XMANAGER. This means that there is no reason to specify this keyword for a top-level base that will be managed by the XMANAGER procedure. FUNC_GET_VALUE A string containing the name of a function to be called when the GET_VALUE keyword to the WIDGET_CONTROL procedure is called for this widget. Using this technique allows you to change the value that should be returned for a widget. Compound widgets use this ability to define their values transparently to the user. ID_TYPE The type of COM control ID passed in (class or program). If set to 0, the ID is a class ID (the default) and if set to 1, the ID is a program ID. The following keywords are accepted by all IDL Widget types and are also accepted by WIDGET_ACTIVEX. The keywords are only enumerated in this specification. For details on how they operate, consult the IDL Reference Guide. KILL_NOTIFY Set this keyword to a string that contains the name of a procedure to be called automatically when the specified widget dies. Each widget is allowed a single such callback procedure. It can be removed by setting the routine to the null string (''). Note that the procedure specified is used only if you are not using the XMANAGER procedure to manage your widgets. The callback routine is called with the widget identifier as its only argument. At that point, the widget identifier can only be used with the WIDGET_CONTROL procedure to get or set the user value. All other requests that require a widget ID are disallowed for the target widget. The callback is not issued until the WIDGET_EVENT function is called. If you use the XMANAGER procedure to manage your widgets, the value of this keyword is overwritten. Use the CLEANUP keyword to XMANAGER to specify a procedure to be called when a managed widget dies. NO_COPY Usually, when setting or getting widget user values, either at widget creation or using the SET_UVALUE and GET_UVALUE keywords to WIDGET_CONTROL, IDL makes a second copy of the data being transferred. Although this technique is fine for small data, it can have a significant memory cost when the data being copied is large. If the NO_COPY keyword is set, IDL handles these operations differently. Rather than copy the source data, it takes the data away from the source and attaches it directly to the destination. This feature can be used by compound widgets to obtain state information from a UVALUE without all the memory copying that would otherwise occur. However, it has the side effect of causing the source variable to become undefined. On a "set" operation (using the UVALUE keyword to WIDGET_BASE or the SET_UVALUE keyword to WIDGET_CONTROL), the variable passed as value becomes undefined. On a "get" operation (GET_UVALUE keyword to WIDGET_CONTROL), the user value of the widget in question becomes undefined. NOTIFY_REALIZE Set this keyword to a string that contains the name of a procedure to be called automatically when the specified widget is realized. This callback occurs just once (because widgets are realized only once). Each widget is allowed a single such callback procedure. It can be removed by setting the routine to the null string (''). The callback routine is called with the widget ID as its only argument. PRO_SET_VALUE A string containing the name of a procedure to be called when the SET_VALUE keyword to the WIDGET_CONTROL procedure is called for this widget. Using this technique allows you to designate a routine that sets the value for a widget. Compound widgets use this ability to define their values transparently to the user. SCR_XSIZE Set this keyword to the desired "screen" width of the widget, in units specified by the UNITS keyword (pixels are the default). In many cases, setting this keyword is the same as setting the XSIZE keyword. SCR_YSIZE Set this keyword to the desired "screen" height of the widget, in units specified by the UNITS keyword (pixels are the default). In many cases, setting this keyword is the same as setting the YSIZE keyword. SENSITIVE Set this keyword to control the initial sensitivity state of the widget. If SENSITIVE is zero, the widget becomes insensitive. If nonzero, it becomes sensitive. When a widget is sensitive, it has normal appearance and can receive user input. For example, a sensitive button widget can be activated by moving the mouse cursor over it and pressing a mouse button. When a widget is insensitive, it indicates the fact by changing its appearance, looking disabled, and it ignores any input. Sensitivity can be used to control when a user is allowed to manipulate the widget. Note that some widgets do not change their appearance when they are made insensitive, but they cease generating events. After creating the widget hierarchy, you can change the sensitivity state using the SENSITIVE keyword with the WIDGET_CONTROL procedure. UNAME Set this keyword to a string that can be used to identify the widget in your code. You can associate a name with each widget in a specific hierarchy, and then use that name to query the widget hierarchy and get the correct widget ID. To query the widget hierarchy, use the WIDGET_INFO function with the FIND_BY_UNAME keyword. The UNAME should be unique to the widget hierarchy because the FIND_BY_UNAME keyword returns the ID of the widget with the specified name. UNITS Set UNITS equal to 0 (zero) to specify that all measurements are in pixels (this is the default), to 1 (one) to specify that all measurements are in inches, or to 2 (two) to specify that all measurements are in centimeters. UVALUE The "user value" to be assigned to the widget. Each widget can contain a user-specified value of any data type and organization. This value is not used by the widget in any way, but exists entirely for the convenience of the IDL programmer. This keyword allows you to set this value when the widget is first created. If UVALUE is not present, the widget's initial user value is undefined. The user value for a widget can be accessed and modified at any time by using the GET_UVALUE and SET_UVALUE keywords to the WIDGET_CONTROL procedure. XOFFSET The horizontal offset of the widget in units specified by the UNITS keyword (pixels are the default) relative to its parent. Specifying an offset relative to a row or column major base widget does not work because those widgets enforce their own layout policies. This keyword is primarily of use relative to a plain base widget. Note that it is best to avoid using this style of widget layout. XSIZE The width of the widget in units specified by the UNITS keyword (pixels are the default). Most widgets attempt to size themselves to fit the situation. However, if the desired effect is not produced, use this keyword to override it. This keyword is only a "hint" to the toolkit and may be ignored in some situations. YOFFSET The vertical offset of the widget in units specified by the UNITS keyword (pixels are the default) relative to its parent. This offset is specified relative to the upper left corner of the parent widget. Specifying an offset relative to a row or column major base widget does not work because those widgets enforce their own layout policies. This keyword is primarily of use relative to a plain base widget. Note that it is best to avoid using this style of widget layout. YSIZE The height of the widget in units specified by the UNITS keyword (pixels are the default). Most widgets attempt to size themselves to fit the situation. However, if the desired effect is not produced, use this keyword to override it. This keyword is only a "hint" to the toolkit and may be ignored in some situations. Examples For examples using WIDGET_ACTIVEX, see Chapter 3, "Using COM Objects in IDL". WIDGET_DISPLAYCONTEXTMENU [Previous Routine] [Next Routine] [List of Routines] NAME: WIDGET_DISPLAYCONTEXTMENU The WIDGET_DISPLAYCONTEXTMENU procedure displays a shortcut menu (otherwise known as a context sensitive or pop-up menu). After buttons for the context menu have been created a context menu can be displayed using WIDGET_DISPLAYCONTEXTMENU. This is normally called in an event handler that has processed a context menu event. This procedure takes the ID of the widget that is the parent of the context menu, the x and y location to display the menu, and the ID of the context menu base. The ID would normally be the event.id value of the context menu event, and the x and y locations also come from the context event. As stated above, there may be multiple context menus for a particular widget. The last parameter of WIDGET_DISPLAYCONTEXTMENU allows the user to specify which menu to display. In the case of a draw widget that is the parent of a context menu, the x and y locations can be obtained from the button event structure. When WIDGET_DISPLAYCONTEXTMENU is called it displays the context menu and handles the native event if the user selects a button. If a button is selected a user button event is generated and the menu is dismissed. If no button is selected (the user clicks elsewhere on the screen) then the menu is dismissed and no user event is generated. Normally no further processing would be done in the context event or draw event handler after calling WIDGET_DISPLAYCONTEXTMENU. The new user event is queued and will be handled in a new call to the event handler. Syntax WIDGET_DISPLAYCONTEXTMENU, Parent, X, Y, ContextBase_ID Arguments Parent The widget ID of the parent of a context menu. X The x location, relative to the parent widget, to display the menu. Y The y location, relative to the parent widget, to display the menu. ContextBase_ID The widget ID of the context menu base that is the head of the menu to display. Use the CONTEXT_MENU keyword to WIDGET_BASE to create a context menu base. This base must be a child of the widget supplied with the Parent argument. Keywords None. Examples For examples using WIDGET_DISPLAYCONTEXTMENU, see Chapter 4, "Using the Shortcut Menu Widget". XOBJVIEW_ROTATE [Previous Routine] [Next Routine] [List of Routines] NAME: XOBJVIEW_ROTATE The XOBJVIEW_ROTATE procedure is used to programmatically rotate the object currently displayed in XOBJVIEW. XOBJVIEW must be called prior to calling XOBJVIEW_ROTATE. This procedure can be used to create animations of object displays. This routine is written in the IDL language. Its source code can be found in the file xobjview_rotate.pro in the lib/utilities subdirectory of the IDL distribution. Syntax XOBJVIEW_ROTATE, Axis, Angle [, /PREMULTIPLY] Arguments Axis A 3-element vector of the form [x, y, z] describing the axis about which the model is to be rotated. Angle The amount of rotation, measured in degrees. Keywords PREMULTIPLY Set this keyword to cause the rotation matrix specified by Axis and Angle to be pre- multiplied to the model's transformation matrix. By default, the rotation matrix is post-multiplied. Example The following example creates an animation of the test object (a surface) currently displayed in XOBJVIEW. It does this by rotating the surface through 360 degrees in increments of 10 degrees using XOBJVIEW_ROTATE, and writing the display image to a BMP file for each increment using XOBJVIEW_WRITE_IMAGE. PRO RotateAndWriteObject XOBJVIEW, /TEST FOR i = 0, 359 DO BEGIN XOBJVIEW_ROTATE, [0, 1, 0], 1, /PREMULTIPLY; XOBJVIEW_WRITE_IMAGE, 'img' + $ STRCOMPRESS(i, /REMOVE_ALL) + '.bmp', 'bmp' ENDFOR END See Also XOBJVIEW, XOBJVIEW_WRITE_IMAGE XOBJVIEW_WRITE_IMAGE [Previous Routine] [Next Routine] [List of Routines] NAME: XOBJVIEW_WRITE_IMAGE The XOBJVIEW_WRITE_IMAGE procedure is used to write the object currently displayed in XOBJVIEW to an image file with the specified name and file format. XOBJVIEW must be called prior to calling XOBJVIEW_WRITE_IMAGE. This routine is written in the IDL language. Its source code can be found in the file xobjview_write_image.pro in the lib/utilities subdirectory of the IDL distribution. Syntax XOBJVIEW_WRITE_IMAGE, Filename, Format [, DIMENSIONS=[x, y] ] Arguments Filename A scalar string containing the name of the file to write. Format A scalar string containing the name of the file format to write. See QUERY_IMAGE for a list of supported formats. Keywords DIMENSIONS Set this keyword to a 2-element vector of the form [x, y] specifying the size of the output image, in pixels. If this keyword is not specified, the image will be written using the dimensions of the current XOBJVIEW draw widget. Example See XOBJVIEW_ROTATE. See Also XOBJVIEW, XOBJVIEW_ROTATE XROI[2] [Previous Routine] [Next Routine] [List of Routines] NAME: XROI[2] The XROI procedure is an existing procedure but has been enhanced substantially in IDL 5.5. This utility is used for interactively defining regions of interest (ROIs), and obtaining geometry and statistical data about these ROIs. This routine is written in the IDL language. Its source code can be found in the file xroi.pro in the lib/utilities subdirectory of the IDL distribution. Syntax XROI [, ImageData] [, R] [, G] [, B] [, TOOLS] [, /BLOCK] [[, /FLOATING] , GROUP=widget_ID] [, /MODAL] [, REGIONS_IN=value] [, REGIONS_OUT=value] [, REJECTED=variable] [, RENDERER={0 | 1}] [, ROI_COLOR=[r, g, b] or variable] [, ROI_GEOMETRY=variable] [, ROI_SELECT_COLOR=[r, g, b] or variable] [, STATISTICS=variable] [, TITLE=string] [, TOOLS=string/string array {valid values are 'Translate-Scale', 'Rectangle', 'Ellipse', 'Freehand Draw', 'Polygon Draw', and 'Selection'}] Arguments ImageData ImageData is both an input and output argument. It is an array representing an 8-bit or 24-bit image to be displayed. ImageData can be any of the following: * [m, n] - 8-bit image * [3, m, n] - 24-bit image * [m, 3, n] - 24-bit image * [m, n, 3] - 24-bit image If ImageData is not supplied, the user will be prompted for a file via DIALOG_PICKFILE. On output, ImageData will be set to the current image data. (The current image data can be different than the input image data if the user imported an image via the File Import Image menu item.) R, G, B R, G, and B are arrays of bytes representing red, green, or blue color table values, respectively. R, G, and B are both input and output arguments. On input, these values are applied to the image if the image is 8-bit. To get the red, green, or blue color table values for the image on output from XROI, specify a named variable for the appropriate argument. (If the image is 24-bit, this argument will output a 256-element byte array containing the values given at input, or BINDGEN(256) if the argument was undefined on input.) Keywords BLOCK Set this keyword to have XMANAGER block when this application is registered. By default, BLOCK is set equal to zero, providing access to the command line if active command line processing is available. Note that setting the BLOCK keyword causes all widget applications to block, not just this application. For more information, see the documentation for the NO_BLOCK keyword to XMANAGER. Note Only the outermost call to XMANAGER can block. Therefore, to have XROI block, any earlier calls to XMANAGER must have been called with the NO_BLOCK keyword. See the documentation for the NO_BLOCK keyword to XMANAGER for an example. FLOATING Set this keyword, along with the GROUP keyword, to create a floating top-level base widget. If the windowing system provides Z-order control, floating base widgets appear above the base specified as their group leader. If the windowing system does not provide Z-order control, the FLOATING keyword has no effect. Note Floating widgets must have a group leader. Setting this keyword without also setting the GROUP keyword causes an error. GROUP Set this keyword to the widget ID of the widget that calls XROI. When this keyword is specified, the death of the caller results in the death of XROI. MODAL Set this keyword to block other IDL widgets from receiving events while XROI is active. REGIONS_IN Set this keyword to an array of IDLgrROI references. This allows you to open XROI with previously defined regions of interest (see Example 3). This is also useful when using a loop to open multiple images in XROI. By using the same named variable for both the REGIONS_IN and REGIONS_OUT keywords, you can reuse the same ROIs in multiple images (see Example 2). This keyword also accepts ­1, or OBJ_NEW() (Null object) to indicate that there are no ROIs to read in. This allows you to assign the result of a previous REGIONS_OUT to REGIONS_IN without worrying about the case where the previous REGIONS_OUT is undefined. REGIONS_OUT Set this keyword to a named variable that will contain an array of IDLgrROI references. This keyword is assigned the null object reference if there are no ROIs defined. By using the same named variable for both the REGIONS_IN and REGIONS_OUT keywords, you can reuse the same ROIs in multiple images (see Example 2). REJECTED Set this keyword to a named variable that will contain those REGIONS_IN that are not in REGIONS_OUT. The objects defined in the variable specified for REJECTED can be destroyed with a call to OBJ_DESTROY, allowing you to perform cleanup on objects that are not required (see Example 2). This keyword is assigned the null object reference if no REGIONS_IN are rejected by the user. RENDERER Set this keyword to an integer value to indicate which graphics renderer to use when drawing objects within the window. Valid values are: * 0 = Platform native OpenGL * 1 = IDL's software implementation (the default) ROI_COLOR This keyword is both an input and an output parameter. Set this keyword to a 3-element byte array, [r, g, b], indicating the color of ROI outlines when they are not selected. This color will be used by XROI unless and until the color is changed by the user via the "Unselected Outline Color" portion of the "ROI Outline Colors" dialog (which is accessed by selecting Edit ROI Outline Colors). If this keyword is assigned a named variable, that variable will be set to the current [r, g, b] value at the time that XROI returns. ROI_GEOMETRY Set this keyword to a named variable that will contain an array of anonymous structures, one for each ROI that is valid when this routine returns. The structures will contain the following fields: Field Description area The area of the region of interest, in square pixels. centroid The coordinates (x, y, z) of the centroid of the region of interest, in pixels. perimeter The perimeter of the region of interest, in pixels. Table 6-4: Fields of the structure returned by ROI_GEOMETRY If there are no valid regions of interest when this routine returns, ROI_GEOMETRY will be undefined. Note If there are no REGIONS_IN, XROI must either be modal or must block control flow in order for ROI_GEOMETRY to be defined upon exit from XROI. Otherwise, XROI will return before an ROI can be defined, and ROI_GEOMETRY will therefore be undefined. ROI_SELECT_COLOR This keyword is both an input and an output parameter. Set this keyword to a 3-element byte array, [r, g, b], indicating the color of ROI outlines when they are selected. This color will be used by XROI unless and until the color is changed by the user via the "Selected Outline Color" portion of the "ROI Outline Colors" dialog (which is accessed by selecting Edit ROI Outline Colors). If this keyword is assigned a named variable, that variable will be set to the current [r, g, b] value at the time that XROI returns. STATISTICS Set this keyword to a named variable to receive an array of anonymous structures, one for each ROI that is valid when this routine returns. The structures will contain the following fields: Field Description count Number of pixels in region. minimum Minimum pixel value. maximum Maximum pixel value. mean Mean pixel value. stddev Standard deviation of pixel values. Table 6-5: Fields of the structure returned by STATISTICS If ImageData is 24-bit, or if there are no valid regions of interest when the routine exits, STATISTICS will be undefined. Note If there are no REGIONS_IN, XROI must either be modal or must block control flow in order for STATISTICS to be defined upon exit from XROI. Otherwise, XROI will return before an ROI can be defined, and STATISTICS will therefore be undefined. TITLE Set this keyword to a string to appear in the XROI title bar. TOOLS The values for the TOOLS keyword indicate the buttons to be included on an XROI toolbar. New values to the TOOLS keyword are: * 'Translate Scale' - Enables translation and scaling of ROIs. Mouse down on the bounding box selects a region, mouse motion translates (repositions) the region. Mouse down on a scale handle of the bounding box enables scaling (stretching, enlarging and shrinking) of the region according to mouse motion. Mouse up finishes the translation or scaling. * 'Rectangle' - Enables rectangular ROI drawing. Mouse down positions one corner of the rectangle, mouse motions creates the rectangle, positioning the rectangle's opposite corner, mouse up finishes the rectangular region. * 'Ellipse' - Enables elliptical ROI drawing. Mouse down positions the center of the ellipse, mouse motion positions the corner of the ellipse's imaginary bounding box, mouse up finishes the elliptical region. Set this keyword a string or vector of strings from the following list to indicate which ROI manipulation tools should be supported when XROI is run: * 'Translate-Scale' - Translation and scaling of ROIs. Mouse down inside the bounding box selects a region, mouse motion translates (repositions) the region. Mouse down on a scale handle of the bounding box enables scaling (stretching, enlarging and shrinking) of the region according to mouse motion. Mouse up finishes the translation or scaling. * 'Rectangle' - Rectangular ROI drawing. Mouse down positions one corner of the rectangle, mouse motions creates the rectangle, positioning the rectangle's opposite corner, mouse up finishes the rectangular region. * 'Ellipse' - Elliptical ROI drawing. Mouse down positions the center of the ellipse, mouse motion positions the corner of the ellipse's imaginary bounding box, mouse up finishes the elliptical region. * 'Freehand Draw' - Freehand ROI drawing. Mouse down begins a region, mouse motion adds vertices to the region (following the path of the mouse), mouse up finishes the region. * 'Polygon Draw' - Polygon ROI drawing. Mouse down begins a region, subsequent mouse clicks add vertices, double-click finishes the region. * 'Selection' - ROI selection. Mouse down/up selects the nearest region. The nearest vertex in that region is identified with a crosshair symbol. If more than one string is specified, a series of bitmap buttons will appear at the top of the XROI widget in the order specified (to the right of the fixed set of bitmap buttons used for saving regions, displaying region information, copying to clipboard, and flipping the image). If only one string is specified, no additional bitmap buttons will appear, and the manipulation mode is implied by the given string. If this keyword is not specified, bitmap buttons for all three manipulation tools are included on the XROI toolbar. Using XROI XROI displays a top-level base with a menu, toolbar and draw widget. After defining an ROI, the ROI Information window appears, as shown in the following figure: Figure 6-1: The XROI Utility As you move the mouse over an image, the x and y pixel locations are shown in the status line on the bottom of the XROI window. For 8-bit images, the data value (z) is also shown. If an ROI is defined, the status line also indicates the mouse position relative to the ROI using the text "Inside", "Outside", "On Edge," or "On Vertex." The XROI Toolbar The XROI toolbar contains the following buttons: Save: Opens a file selection dialog for saving the currently defined ROIs to a save file. Info: Opens the ROI Information window. Copy: Copies the contents of the display area to the clipboard. Flip: Flips image vertically. Note that only the image is flipped; any ROIs that have been defined do not move. Depending on the value of the TOOLS keyword, the XROI toolbar may also contain the following buttons: Click this button to translate or scale ROIs. Mouse down inside the bounding box selects a region, mouse motion Translate/ translates (repositions) the region. Mouse down on a scale Scale: handle of the bounding box enables scaling (stretching, enlarging and shrinking) of the region according to mouse motion. Mouse up finishes the translation or scaling. Click this button to draw rectangular ROIs. Mouse down Draw positions one corner of the rectangle, mouse motions creates Rectangle: the rectangle, positioning the rectangle's opposite corner, mouse up finishes the rectangular region. Click this button to draw elliptical ROIs. Mouse down Draw positions the center of the ellipse, mouse motion positions Ellipse: the corner of the ellipse's imaginary bounding box, mouse up finishes the elliptical region. Click this button to draw freehand ROIs. Mouse down Draw begins a region, mouse motion adds vertices to the region Freehand: (following the path of the mouse), mouse up finishes the region. Draw Click this button to draw polygon ROIs. Mouse down Polygon: begins a region, subsequent mouse clicks add vertices, double-click finishes the region. Click this button to select an ROI region. Clicking the image Select: causes a cross hairs symbol to be drawn at the nearest vertex of the selected ROI. Importing an Image into XROI To import an image into XROI, select File Import Image. This opens a DIALOG_READ_IMAGE dialog, which can be used to preview and select an image. Changing the Image Color Table To change the color table properties for the current image, select Edit Image Color Table. This opens the CW_PALETTE_EDITOR dialog, which is a compound widget used to edit color palettes. See CW_PALETTE_EDITOR for more information. This menu item is grayed out if the image does not have a color palette. Changing the ROI Outline Colors To change the outline colors for selected and unselected ROIs, select Edit ROI Outline Colors. This opens the ROI Outline Colors dialog, which consists of two CW_RGBSLIDER widgets for interactively adjusting the ROI outline colors. The left widget is used to define the color for the selected ROI, and the right widget is used to define the color of unselected ROIs. You can select the RGB, CMY, HSV, or HLS color system from the Color System drop-down list. Viewing ROI Information To view geometry and statistical data about the currently selected ROI, click the Info button or select Edit ROI Information. This opens the ROI Information dialog, which displays area, perimeter, number of pixels, minimum and maximum pixel values, mean, and standard deviation. Values for statistical information (minimum, maximum, mean, and standard deviation) appear as "N/A" for 24-bit images. Viewing a Histogram Plot for an ROI To view a histogram for an ROI, use either the shortcut menu or the ROI Information dialog. To view an ROI's histogram plot using the shortcut menu: 1. Position the cursor on the line defining the boundary of an ROI in the drawing window and click the right mouse button. This selects the region and brings up its shortcut menu. 2. Select the Plot Histogram menu option from the shortcut menu. To view an ROI's histogram plot using the ROI Information dialog: 1. Open the ROI Information dialog by clicking the Info button or selecting Edit ROI Information. 2. Select a region from the list and click the Histogram button on the ROI Information dialog. Either of the previous methods opens a LIVE_PLOT dialog showing the ROI's histogram that can be used to interactively control the plot properties. Note XROI's histogram plot feature now supports RGB images. Growing an ROI Once a region has been created, it may be used as a source ROI for region growing. Region growing is a process of generating one or more new ROIs based upon the image pixel values that fall within the source ROI and the values of the neighboring pixels. New pixels are added to the new grown region if those image pixel values fall within a specified threshold. Note This option is an interactive implementation of the REGION_GROW function. To create a new, grown region, do the following: 1. Within the draw area, click the right mouse button on the ROI that is to be grown. This will select the region and bring up its shortcut menu. 2. Select Grow Region By threshold or select Grow Region By std. dev. multiple from the shortcut menu to control how the region is grown. The By threshold option grows the region to include all neighboring pixels that fall within a specified threshold range. By default, the range is defined by the minimum and maximum pixel values occurring within the original region. To specify a different threshold range, see Using the Region Grow Properties Dialog in the following section. The By std. dev. multiple option grows a region to include all neighboring pixels that fall within the range of: Mean +/- StdDevMultiplier * StdDev where Mean is the mean value of the pixel values within the source ROI, StdDevMultiplier is a multiplier that is set using the Region Grow Properties dialog (described below), and StdDev is the sample standard deviation of the pixel values within the original region. Using the Region Grow Properties Dialog The Region Grow Properties dialog allows you to view and edit the properties associated with a region growing process. To bring up the Region Grow Properties dialog, do one of the following: * Click the right mouse button on an ROI in the drawing window and select Grow Region Properties... shortcut menu option. * Select Edit Region Grow Properties... from the XROI menu bar. This brings up the Region Grow Properties dialog, shown in the following figure. Figure 6-2: XROI's Region Grow Properties Dialog The Region Grow Properties dialog offers the following options: Option Description Pixel search Describes which pixels are searched when growing the method: original ROI. The option are: * 4-neighbor - Searches only the four neighboring pixels that share a common edge with the current pixel. This is the default. * 8-neighbor - Searches all eight neighboring pixels, including those that are located diagonally relative to the original pixel and share a common corner. Table 6-6: Options of the Region Grow Properties Dialog Option Description Threshold range: Represents the minimum and maximum image pixel values that are to be included in the grown region when using the Grow Region By threshold option (described in "Growing an ROI" on page 312). By default, the range of pixel values used are those occurring in the ROI to be grown. To change the threshold values, uncheck Use source ROI threshold and enter the minimum and maximum threshold values in the Min: and Max: fields provided. Standard deviation Represents the factor by which the sample standard multiplier: deviation of the original ROI's pixel values is multiplied. This factor only applies when the Grow Region By std. dev. multiple option (described in "Growing an ROI" on page 312) is used. Change the multiplier value by typing the value into the Standard deviation multiplier field provided. For RGB image, Determines the basis of region growing for an RGB (rather use: than indexed) image. The image data values used when growing a RGB region can be one of the following: * Luminosity - Uses the luminosity values associated with an RGB image. This is the default method. Luminosity is computed as: Luminosity = (0.3 * Red) + (0.59 * Green) + (0.11 * Blue) * Red Channel, Green Channel or Blue Channel - Uses the ROI's red, green or blue channel as a basis for region growing. Click the channel's associated button to specify the channel to be used. Note - For indexed images, the image data itself is always used for region growing. Table 6-6: Options of the Region Grow Properties Dialog (Continued) Option Description Acceptance criteria: Determines which contours of the grown region are accepted as new regions, (which will also be displayed in the draw area and in the ROI Information dialog list of regions). The region growing process can result in a large number of contours, some of which may be considered insignificant. By default, no more than two regions (those with the greatest geometrical area) are accepted. Modify the acceptance criteria by altering the following values: * Maximum number of regions: - Specifies the upper limit of the number of regions to create when growing an ROI. * Minimum area per region: - Specifies that only contours having a geometric area (computed in device coordinates) of at least the value stated are accepted and displayed. * Accept all regions: - Select this option to accept all generated contours, regardless of count or area. Table 6-6: Options of the Region Grow Properties Dialog (Continued) Deleting an ROI An ROI can be deleted using either the shortcut menu or using the ROI Information dialog. To delete an ROI using the shortcut menu: 1. Click the right mouse button on the line defining the boundary of the ROI in the drawing area that you wish to delete. This selects the region and bring up the shortcut menu. 2. Select the Delete menu option from the shortcut menu. To delete an ROI using the ROI Information dialog: 1. Click the Info button or select Edit ROI Information. This opens the ROI Information dialog. 2. In the ROI Information dialog, select the ROI you wish to delete from the list of ROIs. You can also select an ROI by clicking the Select button on the XROI toolbar, then clicking on an ROI on the image. 3. Click the Delete ROI button. Examples Example 1 This example opens a single image in XROI: image = READ_PNG(FILEPATH('mineral.png', $ SUBDIR=['examples', 'data'])) XROI, image Example 2 This example reads 3 images from the file mr_abdomen.dcm, and calls XROI for each image. A single list of regions is maintained, saving the user from having to redefine regions on each image: ;Read 3 images from mr_abdomen.dcm and open each one in XROI: FOR i=0,2 DO BEGIN image = READ_DICOM(FILEPATH('mr_abdomen.dcm',$ SUBDIR=['examples', 'data']), IMAGE_INDEX=i) XROI, image, r, g, b, REGIONS_IN = regions, $ REGIONS_OUT = regions, $ ROI_SELECT_COLOR = roi_select_color, $ ROI_COLOR = roi_color, REJECTED = rejected, /BLOCK OBJ_DESTROY, rejected ENDFOR OBJ_DESTROY, regions Perform the following steps: 1. Draw an ROI on the first image, then close that XROI window. Note that the next image contains the ROI defined in the first image. This is accomplished by setting REGIONS_IN and REGIONS_OUT to the same named variable in the FOR loop of the above code. 2. Draw another ROI on the second image. 3. Click the Select button and select the first ROI. Then click the Info button to open the ROI Information window, and click the Delete ROI button. 4. Close the second XROI window. Note that the third image contains the ROI defined in the second image, but not the ROI deleted on the second image. This example sets the REJECTED keyword to a named variable, and calls OBJ_DESTROY on that variable. Use of the REJECTED keyword is not necessary to prevent deleted ROIs from appearing on subsequent images, but allows you perform cleanup on objects that are no longer required. Example 3 XROI's File Save ROIs option allows you to save selected regions of interest. This example shows how to restore such a save file. Suppose you have a file named mineralRoi.sav that contains regions of interest selected in the mineral.png image file. You would need to complete the following steps to restore the file: 1. First, restore the file, mineralRoi.sav. Provide a value for the RESTORE procedure's RESTORED_OBJECTS keyword. Using the scenario stated above, you could enter the following: RESTORE, 'mineralRoi.sav', RESTORED_OBJECTS = myRoi 2. Pass the restored object data containing your regions of interest into XROI by specifying myRoi as the value for REGIONS_IN as follows: XROI, READ_PNG(FILEPATH('mineral.png', SUBDIRECTORY = $ ['examples', 'data'])), REGIONS_IN = myRoi This opens the previously selected regions of interest in the XROI utility.