Coyote Library Utility Programs

The utility programs perform a variety of useful tasks for other programs in the Coyote Library. As such, they really belong in almost every category of programs.

• ADJUSTPOSITION Allows interactive adjustment of the plot position in a graphics windows.
• ARCSAMPLE Resamples a closed curve on approximately equally-spaced arc distances.
• BELL Windows-only set of programs for ringing the bell (or playing a sound).
• BINARY Used to print a binary representation of an integer.
• BITGET Returns the value of a specified bit in a number.
• CAPFIRSTLETTER A utility program that capitalizes the first letter of each word in a string.
• cgADDTOPATH Allows the user to add a directory to the IDL !PATH system variable.
• cgAPPENDTOFILENAME Appends a string to the root name of a longer file name.
• cgCENTERTLB Centers a widget program on the display.
• cgDEMODATA Opens data files found in the IDL distribution.
• cgDBLTOSTR Converts a double precision value to a string in a way that preserves significant digits.
• cgFIXPS Fixes IDL PostScript landscape output files so they display with proper orientation.
• cgGREEK Returns a letter from the Greek alphabet as a string for plot annotation.
• cgNUMBER_FORMATTER A utility routine to format numbers used in text widgets.
• cgPICKFILE A wrapper for Dialog_Pickfile that remembers your last selection.
• cgPROGRESSBAR Implements a "show progress" bar.
• cgRANDOMINDICES Create random indices without replacement (unique indices).
• cgRANDOMWALD Create random indices with Inverse Gaussian or Wald distribution.
• cgRESIZEIMAGE A Congrid command without Congrid's weaknesses for resizing images.
• cgREVERSEINDICES A routine read the histogram reverse indices vector in a simple way.
• cgROOTNAME Return the base or root of the filename, the directory name, and the file extension as strings.
• cgSCALEVECTOR Scales vector or array between given MIN and MAX values.
• cgSETDIFFERENCE Finds the difference between two sets of integer values.
• cgcSETINTERSECTION Finds the intersection between two sets of integer values.
• cgSETUNION Finds the union between two sets of integer values.
• CLIPBOARD Copies contents of an IDL graphics window to clipboard for pasting to other applications.
• CONVERT_TO_TYPE A function that converts its input argument to a run-time data type.
• COUNT_ROWS Count the number of rows in an ASCII file.
• DECOMPOSEDCOLOR Determines if graphics device supports decomposed color.
• ERRORLOGGER An object for logging program errors and other comments.
• ERROR_MESSAGE A device-independent error handler with traceback capability.
• FIND_RESOURCE_FILE Returns a fully-qualified path to a resource file.
• FLOATS_EQUAL Compares two floating-point values or arrays for equality.
• FPUFIX Fixes problems in data that can cause floating point underflow errors.
• GEOCOORD Converts a GEOTIFF structure to a MAPCOORD map coordinate object.
• GETDECOMPOSEDSTATE Returns a device/version independent current decomposition state.
• GET_OBJECT_ID Obtain a unique object identifier for an object.
• GRIDPOSITIONS Calculate column and row grid positions anywhere in the window.
• HELP_VAR Performs a "HELP" on variables only.
• IDLWAVE_CATALOG Catalog file of this library for the IDLWAVE Emacs mode.
• IMAGE_DIMENSIONS Utility for determining the size and dimensions of images.
• INSIDE Tests if point is inside a specified polygon.
• JD2TIME Converts a Julian Day Number into a well-formatted time string.
• LEFTJUSTIFY Creates a string that is left justified with respect to a string width.
• LINKEDLIST Implements a doubly linked list.
• LIST_SELECTOR A pop-up dialog widget for selecting items from a string array.
• MAXWINDOWSIZE Returns the maximum size of an unobstructed graphics window.
• MAXMIN Print the maximum and minimum of a variable.
• NAME_SELECTOR A pop-up dialog widget for selecting items from a string array.
• PRINTWINDOW Utility for sending the contents of a graphics window to the printer.
• PROGRAMROOTDIR Utility for specifying relative filepaths in IDL program distributions.
• RANDOMNUMBERGENERATOR An object for creating random numbers.
• RANGEOF A utility program for finding the range of a vector or array.
• REPMAT Replicates or tiles a matrix in a manner similar to MatLab RepMat command.
• RESOLVE_OBJECT Restores an object's methods when a saved object is restored.
• SAVETOMAIN Saves a variable to the main IDL level from within a procedure.
• SCROLLWINDOW A scrollable window when display size is smaller than window size.
• SETDECOMPOSEDSTATE Sets a device/version independent current decomposition state.
• SETDEFAULTVALUE Sets default values for positional and keyword arguments.
• SORT_ND Efficiently perform an N-dimensional sort along any dimension of an array.
• STR_SIZE Calculates character size for direct graphics resizeable graphics windows.
• TEXTLINEFORMAT Formats a long line of text into a string array of specified maximum length.
• TRANSFORM_VOLUME Allows efficient rotation, scaling, and transformation of 3D array or volume data.
• UNDEFINE Deletes program variables at any program level, including at the IDL command line.
• WINDOWAVAILABLE Indicates whether a graphics window is currently open and available.
• XCD Fancy change directory utility. Couldn't live without it. :-)

	ADJUSTPOSITION
	This utility program allows the user to interactively adjust the plot position coordinates by resizing and moving a plot representation in a window. The return value from this function can be used to position almost any IDL graphic in a graphics window via the Position keyword. This program requires FSC_Field and FSC_PlotWindow from the Coyote program library.

   IDL> h = Histogram(cgDemoData(7), REVERSE_INDICES=ri)
   IDL> bin5Indices = cgReverseIndices(ri, 5, COUNT=count)

   IDL> set_a = [1,2,3,4,5]
   IDL> set_b = [4,5,6,7,8,9,10,11]
   IDL> Print, cgSetDifference(set_a, set_b)
          1  2  3

   IDL> set_a = [1,2,3,4,5]
   IDL> set_b = [4,5,6,7,8,9,10,11]
   IDL> Print, cgSetIntersection(set_a, set_b)
          4  5

   IDL> set_a = [1,2,3,4,5]
   IDL> set_b = [4,5,6,7,8,9,10,11]
   IDL> Print, cgSetUnion(set_a, set_b)
          1  2  3  4  5  6  7  8  9  10  11

FIND_BOUNDARY

The purpose of this utility routine is to find the pixel boundary (or contour, if you like) about a region of interest in an image. The region of interest is given as a one-dimensional vector of image indices, such as those that are returned from the Where function. Optional keywords allow you to return the perimeter length and the area enclosed within the boundary as well. The program uses a chain-code algorithm for calculaing the boundary pixels.

LIST_SELECTOR

This utility routine is a pop-up dialog widget that allows the user to select one or more "names" from a string array of names. I use it to give the user a list of scientific data sets inside an HDF file. This program is similar to Name_Selector, but I find it easier to use and make selections when you have a large number of selections. MAXWINDOWSIZE This utility program allows you to obtain the maximum size of an unobstructed graphics window in a device independent way. A graphics window constructed of this size is about as large as the display, but is not obstructed by tool bars, task bars, start bars, etc. MAXMIN This utility program allows the user to to print the maximum and minimum of a variable. NAME_SELECTOR This utility routine is a pop-up dialog widget that allows the user to select one or more "names" from a string array of names. I use it to give the user a list of scientific data sets inside an HDF file. I will read and display the selected scientific data sets from the file. This program is similar to List_Selector. PRINTWINDOW This simple utility just copies the contents of an IDL direct graphics window and sends it directly to the default printer, represented by the PRINTER device. Care is taken to preserve the aspect ratio of the window and to create as large an image as possible on the output page. PROGRAMROOTDIR This is a utility routine that allows you to distribute IDL program libraries and find application sub-directories relative to the directory containing the program that is currently running. In other words, your end-users need only include directories relative to the main program directory. You won't care where on their hard drive they place them! If your directory structure looks like this: .../myapp .../myapp/data/resources You can find your icon resources file, myicon.icn, like this: filename = Filepath(Root_Dir=ProgramRootDir(), Subdirectory=['data','resources'], 'myicon.icn) This program is a must if you distribute IDL program libraries. cgPROGRESSBAR This simple object implements a "progress bar". If you compile the program, you will find an example program, named Progressbar_Example, that will show you how to operate the cgProgressBar object. RandomNumberGenerator Unless you are careful in IDL, your random numbers may not be all that random. (See Random Numbers Are...Uh, Repeating.) This RandomNumberGenerator object will protect your random number seed so that you can continue to generate random number sequences from any of your program modules. Perhaps the best way to make random numbers available to your IDL programs is to make this random number generator object a system variable that can be accessed by any IDL program module. IDL> DefSysV, '!RNG', Obj_New('RandomNumberGenerator') IDL> randomNumbers = !RNG -> GetRandomNumbers(3) IDL> Print, randomNumbers 0.089239137 0.77428782 0.069180504 Any keywords and parameters appropriate for the IDL RandomU function can be used with this object. RANGEOF This utility program returns the range ([minimum, maximum]) of a vector or array. REPMAT This utility program replicates or tiles a 2D matrix or array by an integer number of colums and rows. It is similar to the MatLab RepMat command. RESOLVE_OBJECT When save objects are restored, they are almost always restored without their methods. That is to say, the object code has not yet been compiled when an object is restored, so it is not possible to call a method on a restored object without encountering an error. This Resolve_Object program solves the problem in an efficient way by compiling object and superclass object methods only if they need to be compiled. Simply restore your object, and then pass it to Resolve_Object and you are ready to use your object normally. SAVETOMAIN This utility program allows the user to save or export a variable to the main IDL level (normally where IDL commands are typed) from within a procedure or function. I use it when debugging code and I want to save an image to the main IDL level for further inspection with other interactive programming tools. SCROLLWINDOW This program is more or less a drop-in replacement for the Window command in IDL, with this significant difference: if the requested graphics window size is larger than the display size, the graphics window is returned in a scrollable base widget so the user can scroll around in the larger graphics window. I find this program useful when I need to create large windows on my desktop machine, but still want to be able to see the full-resolution output on my laptop, which has a lower resolution display. SETDECOMPOSEDSTATE This program set the current color decomposition state of a graphics device in a device-independent and version-independent manner. An output keyword, CurrentState, is availabe to return the current color decomposition state of the device at the time it is set. This avoids a problem with UNIX machines obtaining the state in a different way than Windows machines. SETDEFAULTVALUE This utility program sets the default values for positional and keyword arguments to IDL commands. SORT_ND The purpose of this program is to provide an efficient algorithm for sorting an array by individual rows. The program, described by JD Smith, the author, “as a friend to HIST_ND”, was the result of a long discussion on this topic on the IDL newsgroup. This was the most efficient algorithm of several that were offered and discussed. It is offered here with JD's permission. STR_SIZE This function allows you to calculate a character size for a particular string, so that the string width is close to a specified target width in the current graphics window. The function is particularly useful with respect to sizing strings in resizeable graphics windows. The target width is specified in normalized units. TEXTLINEFORMAT This small utility program can take a long line of text and break it into a string array at some arbitrary maximum length. I find it useful for breaking up a long error message produced with MESSAGE into a string array suitable for display in DIALOG_MESSAGE. TRANSFORM_VOLUME There has been extensive discussion lately on the IDL newsgroup about the most efficient method for rotating volumetric data. Several algorithms were tried and discussed. This algorithm, by Martin Downing in the UK, is the current favorite. It processes the volume in "chunks", which could, in theory, make it suitable for parallelization. UNDEFINE This is a simple utility program to delete or undefine a variable from within an IDL program. It is a more powerful version of DelVar, which can only be used at the main IDL level. WINDOWAVAILABLE This small utility program can determine if a specified IDL graphics window is currently open and available to receive graphics commands. XCD This simple utility routine for changing directories is written by Paul Sorenson and included here with his permission. It works on VMS and Windows machines only. This is one of those incredibly useful programs that make you think: "Now how come I didn't think of that!" It is an excellent example of how to write a widget program with an object-oriented design. All the programs you need are available in this zip file. Version of IDL used to prepare this article: IDL 7.0.1.   Web Coyote's Guide to IDL Programming Copyright © 1996–2013 Fanning Software Consulting, Inc. Last Updated: 21 March 2011