Coyote and Catalyst Program Libraries

Overview of Libraries

My original goal for writing the programs in the Coyote Library was to have a library of well-written and well-documented example programs for the students attending my IDL programming courses. But, of course, over time the library evolved into programs that became indispensible in my own IDL programming work. There are still a number of example programs in the library, but for the most part these programs are the bread and butter of my own daily IDL programming practice. Indispensible to me, if not to you.

In addition to the Coyote Library, as of October 2008, I have also made the Catalyst Library available. This is an IDL object library that David Burridge and I originally wrote in 2003 for a large satellite image application. It has evolved over time into something that I use in nearly all of my IDL consulting projects. The name “Catalyst ”comes from the notion that we have been able to build fairly sophisiticated applications with the library in a fraction of the time it used to take us. The Catalyst Library is a framework for building IDL applications. This is similar to the iTools framework, with the very important difference that the Catalyst Library can be programmed by mere mortals. In other words, if you can write an IDL widget program, you know everything you need to write a Catalyst Library application. For the most part, Catalyst Library applications use direct graphics methods, even though everything in the library is an object. You do not need to know any object graphics, or any iTools functionality to use and build programs with the library.

I hope you find these programs useful to you and instructive as well. If you ever have a problem with one of the programs, please contact me. Your satisfaction, while not strictly guaranteed, is always carefully considered. And if one of these programs is just what you have been looking for, consider making a small PalPay donation by clicking the button below. Any amount is appreciated. If you donate enough for me to buy the beer at the weekly book club, you will gain (at the very least) a gaggle of admirers!

Downloading and Installing the Libraries

Coyote Library

Many of the Coyote Library programs require others in the library to work properly. It is best to download all the Coyote Library programs at once as a 900K zip file. Make a directory named coyote somewhere on your machine, and extract the Coyote files into it. Add the coyote directory to your IDL path. There are many ways to add the coyote directory to your path, but something like this, typed at the IDL command line, or executed in an IDL start-up file, always works:

Windows -- Assuming the files were extracted to the "C:\idlfiles\coyote\" directory:
   IDL> !PATH = Expand_Path('+C:\idlfiles\coyote\') + ';' + !PATH
UNIX -- Assuming the files were extracted to the "~/idlfiles/coyote/" directory:
   IDL> !PATH = Expand_Path('+~/idlfiles/coyote/') + ':' + !PATH

Catalyst Library

The Catalyst Library is only available as a zip file, and is also about 900K. Create a catalyst directory somewhere on your machine (inside the coyote directory you created above is a good choice) and extract the files to this directory. Be sure both the coyote and catalyst directories are on your IDL path. There are many ways to add these directories to your path, but something like this, typed at the IDL command line, or executed in an IDL start-up file, always works:

Windows -- Assuming the files were extracted to the "C:\idlfiles\coyote\" and "C:\idlfiles\catalyst\" directories:
   IDL> !PATH = Expand_Path('+C:\idlfiles\coyote\;+C:\idlfiles\catalyst\') + ';' + !PATH
UNIX -- Assuming the files were extracted to the "~/idlfiles/coyote/" and "~/idlfiles/catalyst/" directories:
   IDL> !PATH = Expand_Path('+~/idlfiles/coyote/:+~/idlfiles/catalyst/) + ':' + !PATH

Motley Library

Note that I am also proud to host Mark Hadfield's Motley Library of IDL programs, too. Mark is an excellent IDL programmer and you will find excellent object graphics programs, elegant object classes, and means for acessing netCDF files, among lots of other programs in this excellent collection. (If you are after the earlier, IDL 5.6 version, of the Motley Library, click here.)

Program Documentation

You may find it useful to look over the Coyote Library documentation before plunging into the programs themselves. The Catalyst Library comes with its own set of documentation, which will be found in the docs sub-directory in the main catalyst directory.

Programs for the IDL Programming Techniques Book

A number of IDL program files are required to work with my IDL Programming Techniques book. Be sure you select the programs for the correct edition of the book. Note that these programs have the same names as the programs in the Coyote Library, but are not the same. Because books freeze time, the programs associated with them also have to freeze. In general, Coyote Library routines are to be preferred to book programs. They are more recent and have been debugged more thoroughly, simply by the passage of time. But if you have a problem, or the book appears to be describing a different program, this may be the reason. Please contact me if you have problems you can't resolve on your own. If you are working with versions of IDL older than IDL 6.0, you should start with the book programs, as these will be more compatable with older versions of IDL.

Programs by Type

Programs for Working with Colors
Programs for Working with PostScript Output
Programs for Reading and Writing Data
Utility Programs
Image Processing Programs
Graphics Display Programs
General Widget Programs
Object Graphics Programs
Catalyst Library Programs

Download ALL Programs

Programs by Name

ACTIVECONTOUR Active contour (or snake) example program. Uses GVF Active Contouring algorithm..
ADJUSTPOSITION Allows interactive adjustment of the plot position in a graphics windows.
ANNOTATEWINDOW A Catalyst Library application for annotating IDL graphics windows.
ARCSAMPLE Resamples a closed curve on approximately equally-spaced arc distances.
ASINHSCL Similar to BYTSCL, except that an inverse hyperbolic sine function is used for scaling.
ASPECT Calculates plot position coordinates for plot of specified aspect ratio.
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.
CATALYST A sample application demonstating Catalyst Library features.
CENTERTLB Centers a widget program on the display.
CHECKERBOARD Creates a 2D checkerboard image.
CINDEX Allows you to see the color index number associated with each color.
CLIPBOARD Copies contents of an IDL graphics window to clipboard for pasting to other applications.
CLIPSCL Performs a linear byte scaling of data, with clipping on each end of the histogram.
COLOR24 Converts RGB color value to 24-bit integer.
COLORBAR Creates direct graphics color bar.
COLORBAR__DEFINE Creates direct graphics color bar as an object.
COLORBUTTONBITMAP Creates a true-color bit map for created colored widget buttons.
CONTRASTZOOM Allows "in place" zoomimg and interactive contrast/brightness adjustment using object graphics.
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.
CTLOAD A drop-in replacement for LOADCT with additional functionality.
ERROR_MESSAGE A device-independent error handler with traceback capability.
DRAWCOUNTIES An example program demonstating how to read a county boundary shapefile for display on a map.
DRAWSTATES An example program demonstating how to read a state boundary shapefile for display on a map.
ERROR_MESSAGE A device-independent error handler with traceback capability.
FIND_BOUNDARY Finds the boundary pixels around a region of interest.
FIND_RESOURCE_FILE Returns a fully-qualified path to a resource file.
FIT_ELLIPSE Fits an ellipse to a region of interest (known as a "blob").
FLOATS_EQUAL Compares two floating-point values or arrays for equality.
FPUFIX Fixes problems in data that can cause floating point underflow errors.
FSC_BASE_FILENAME A function for returning the base filename, the directory name, and the file extension as separate strings.
FSC_COLOR A device-independent color-selection tool.
FSC_DROPLIST A replacement for WIDGET_DROPLIST with easy Get/Set Value capability.
FSC_FIELD A replacement compound widget for CW_FIELD. Similar to FSC_INPUTFIELD.
FSC_FILESELECT A file selection compound widget.
FSC_INPUTFIELD A replacement compound widget for CW_FIELD. Written as an object.
FSC_NORMALIZE Positions object graphic elements in object graphic views.
FSC_PLOTWINDOW A good-for-nothing object compound widget program, written with object graphics.
FSC_PSCONFIG A full-featured program for configuring the PostScript device.
FSC_SURFACE A full-rotating, object graphics surface example.
FSC_WINDOW A "smart" graphics window. Resizeable with automatic file output.
GAUSSSCL Performs a Gaussian scaling on image arrays.
GET_OBJECT_ID Obtain a unique object identifier for an object.
GETIMAGE Reads unformatted 2D and 3D arrays.
GMASCL BYTSCL on steroids! Gamma as well as linear scaling.
HCOLORBAR Create object graphics horizontal color bar.
HELP_VAR Performs a "HELP" on variables only.
HDFREAD Reads an HDF data file created with HDFWRITE.
HDFWRITE Writes an HDF data file.
HIST_ND Calculates an N-dimensional histogram.
HISTOMATCH Performs histogram matching on an image.
HISTOPLOT Draws a histogram plot (direct graphics).
IDLWAVE_CATALOG Catalog file of this library for the IDLWAVE Emacs mode.
IMAGE_BLEND Image with transparent image overlay.
IMAGE_DIMENSIONS Utility for determining the size and dimensions of images.
IMGWIN An image window for interactively exploring image values and positions.
INSIDE Tests if point is inside a specified polygon.
IXYOUTS A program, analogous to XYOUTS, for adding text to iTools.
LINKEDLIST Implements a doubly linked list.
LOADDATA Opens data files found in the IDL distribution.
LOGSCL Like BYTSCL, only with a logrithmic scaling instead of linear scaling.
MAP_GSHHS_SHORELINE Draws shorelines using the GSHHS data base in manner of MAP_CONTINENTS.
MPI_PLOT A wrapper for PLOT and OPLOT commands that allows interactive configuration of keywords.
NAME_SELECTOR A pop-up dialog widget for selecting items from a string array.
NCDF_BROWSER A simplified front end for the NCDF_DATA object.
NCDF_DATA__DEFINE An object for browsing and reading data and metadata in netCDF files.
NUMBER_FORMATTER A utility routine to format numbers used in text widgets.
OBJECT_SHADE_SURF Elevation-shaded surface in object graphics.
PICKCOLOR Utility for picking or specifying a drawing color.
PICKCOLORNAME Utility for picking or specifying a color by name.
PRECIPMAP Demonstrates how to fit a map coordinate system to a map-projected image.
PRINTWINDOW Utility for sending the contents of a graphics window to the printer.
PROGRAMROOTDIR Utility for specifying relative filepaths in IDL program distributions.
PROGRESSBAR Implements a "show progress" bar.
PS_START/PS_END Wrapper programs for opening and closing PostScript files.
PSWINDOW Creates PostScript window with same aspect ratio as display window.
PSCONFIG A function wrapper for graphically configuring the PostScript device.
READ_NCDF A program for reading netCDF files by Paul van Delst.
READ_TOMS_AEROSOL Demonstrates how to overlay satellite imagery on a map projection.
REVERSE_AXES Demonstrates how to reverse object graphics axes.
SCALE_VECTOR Scales vector between given MIN and MAX values.
SELECT_OBJECTS Select and move objects interactively.
SELECTIMAGE A selection/browser tool for known format images.
SETDEFAULTVALUE Sets default values for positional and keyword arguments.
SHAPEINFO Allows the user to browse shapefiles containing geographical information.
SHARPEN Sharpens an image with a Laplacian kernel.
SIMPLE_SURFACE A much simplified FSC_SURFACE object program.
SORT_ND Efficiently perform an N-dimensional sort along any dimension of an array.
STATIONPLOT Plots meteorological "station" data. Used with WINDBARB
STR_SIZE Calculates character size for direct graphics resizeable graphics windows.
SYMCAT A symbol catalog with 44 possible symbols to use in IDL graphics plots.
TERMINATOR_MAP Draws map with day/night terminator displayed.
TEXTBOX A simple pop-up (or modal) dialog widget that returns a text string.
TEXTLINEFORMAT Formats a long line of text into a string array of specified maximum length.
TEXTURE_SURFACE A program that demonstrates the proper way to overlay an image on a surface object.
THEMONTHS A utility program to return the months of the year in various formats.
TRANSFORM_VOLUME Allows efficient rotation, scaling, and transformation of 3D array or volume data.
TVIMAGE Device independent replacement for TV. Works with !P.Multi and Position keyword.
TVINFO Works together with TVIMAGE and TVSCALE to display interactive image locations and values.
TVREAD Device independent replacement/upgrade for TVRD. Use it to create JPEG, TIFF, BMP, etc. files directly.
TVSCALE Device independent replacement for TVSCL. Works with !P.Multi and Position keyword.
UNDEFINE Deletes program variables at any program level, including at the IDL command line.
VCOLORBAR Creates object graphics vertical color bar.
WINDBARB Plots meteorological wind barbs.
WINDOWAVAILABLE Indicates whether a graphics window is currently open and available.
WINDOWIMAGE Interactively change the contrast and brightness of an image using direct graphics.
XCD Fancy change directory utility. Couldn't live without it. :-)
XCOLORS Changes color tables interactively. Absolutely required for 24-bit displays.
XCONTOUR An object graphics contouring example.
XIMAGE An object graphics image example.
XMOVIE Correct implementation of a widget annimation loop.
XPLOT An object graphics plot example.
XSTRETCH Interactively increase image contrast with various image pixel transformations.
ZIMAGE Zooms into image with rubberband selection technique. (Uses direct graphics.)
ZOOMBOX Zooms into image with rubberband selection technique. (Uses object graphics.)
ZPLOT Zooms into line plot with rubberband selection technique.

Download ALL Programs

Programs for Working with Colors

	CINDEX
	A utility routine that allows you to see the color index number assoicated with each color in the current color table. On 24-bit displays, you may need to click the cursor in the color table window to force the colors to update themselves to the current color table. To load colors from this program, you need the XColors program. And for best results, download the TVImage program, as well.

COLOR24

A utility routine for converting a color triple, written as a three-element column or row vector of the form [red, green, blue], into a 24-bit long integer. For example, if you were running IDL on a 24-bit display and you wanted to create a plot in a yellow color, you could type:

    "Plot, data, Color=Color24([255,255,0])"

This program is a utility routine in the GetColor program.

	COLORBAR
	This program shows you one way to create a colorbar for your programs. This colorbar appears exactly the same in a PostScript file as it does on your display.

COLORBAR__DEFINE

This program shows you how to create a colorbar for your programs, but written as an object. Direct graphics programs written as objects have a number of advantages. This colorbar, for example, has an Erase method that can be used to erase the colorbar from the display. Plus, colorbar properties can be changed and displayed immediately. The colorbar appears exactly the same in a PostScript file as it does on your display.

CTLOAD

A utility routine that is a drop-in replacement for LOADCT, with additional functionality and a correction to one of my favorite pet peeves. A REVERSE keyword allows the user to reverse the color table vectors prior to loading. A CLIP keyword allows the user to clip the normal color table vector to just a portion of the original color table vectors. I find this useful, for example, when I want a reduced number of colors in the color table, and I want to exclude the color table end-colors (for most IDL color tables these are black and white).

For example, suppose I wish to use the Standard Gamma color table (color table 5), but I wish to exclude, the black color at the bottom, and the white color at the top. I might type: "CTLOAD, 5, CLIP=[16,240]". The color bar at top in the figure below was created by loading colors with this command:

   IDL> LoadCT, 5, NCOLORS=8

The color bar below was created by loading colors with this command:

   IDL> CTLoad, 5, NCOLORS=8, CLIP=[16,240]

Colorbars with colors loaded with LOADCT and CTLOAD

In addition, one of my favorite pet peeves is corrected by having all color table loading done silently. Updated on 14 May 2008 to support Brewer Colors. You will need to download the fsc_brewer.tbl file from Coyote Library to use this functionality. Install it either in the $IDL_DIR/resource/colors directory or in any directory in the IDL path.

FSC_COLOR

This program is a completely device-independent program for specifying colors by name. You can ask for and load any one (or all) of the 88 colors defined in the program by name. This program replaces the older GetColor program. The colors available are the ones defined for the PickColorName program:

To see a list of all the colors available by name, type this:

   IDL> Print, FSC_Color(/Names), Format='(5(A14, 2x))'
        White            Snow           Ivory    Light Yellow        Cornsilk
         Beige        Seashell           Linen   Antique White          Papaya
        Almond          Bisque        Moccasin           Wheat       Burlywood
           Tan      Light Gray        Lavender     Medium Gray            Gray
    Slate Gray       Dark Gray        Charcoal           Black      Light Cyan
   Powder Blue        Sky Blue      Steel Blue     Dodger Blue      Royal Blue
          Blue            Navy        Honeydew      Pale Green      Aquamarine
  Spring Green            Cyan       Turquoise       Sea Green    Forest Green
  Green Yellow      Chartreuse      Lawn Green           Green      Lime Green
    Olive Drab           Olive      Dark Green  Pale Goldenrod           Khaki
    Dark Khaki          Yellow            Gold       Goldenrod  Dark Goldenrod
  Saddle Brown            Rose            Pink      Rosy Brown     Sandy Brown
          Peru      Indian Red       Chocolate          Sienna     Dark Salmon
        Salmon    Light Salmon          Orange           Coral     Light Coral
     Firebrick           Brown        Hot Pink       Deep Pink         Magenta
        Tomato      Orange Red             Red      Violet Red          Maroon
       Thistle            Plum          Violet          Orchid   Medium Orchid
   Dark Orchid     Blue Violet          Purple

The normal calling sequence for producing device-independent drawing colors, will look similar to this. The first parameter is the name of the color you want, the second parameter is the color table index where you would like to load the specified color.

   axisColor = FSC_COLOR("Green", !D.Table_Size-2)
   backColor = FSC_COLOR("Dark Gray", !D.Table_Size-3)
   dataColor = FSC_COLOR("Yellow", !D.Table_Size-4)
   Plot, Findgen(11), Color=axisColor, Background=backColor, /NoData
   OPlot, Findgen(11), Color=dataColor

If color decomposition is turned off, then the color is loaded at the specified index. If color decomposition is turned on, then no color is loaded into the color table.

If a color index is not specified and color decomposition is turned off, then the specified color is loaded into the !P.Color index.

The output of these commands looks like this:

An example of using the FSC_COLOR program to specify colors.

The value that is returned by FSC_COLOR depends upon the keywords used to call it and on the version of IDL you are using. In general, the return value will be either a color index number where the specified color is loaded by the program, or a 24-bit color value that can be decomposed into the specified color on true-color systems.

If you are running IDL 5.2 or higher, the program will determine which return value to use, based on the color decomposition state at the time the program is called. If you are running a version of IDL before IDL 5.2, then the program will return the color index number. This behavior can be overruled in all versions of IDL by setting the DECOMPOSED keyword. If this keyword is 0, the program always returns a color index number. If the keyword is 1, the program always returns a 24-bit color value.

If the TRIPLE keyword is set, the program always returns the color triple, no matter what the current decomposition state or the value of the DECOMPOSED keyword. This is useful, for example, if you want to load a color in the color table yourself.

   IDL> TVLCT, FSC_Color('dodger blue', /Triple), 10

If the ALLCOLORS keyword is used, then instead of a single value, modified as described above, then all the color values are returned in an array. In other words, the return value will be either an NCOLORS-element vector of color table index numbers, an NCOLORS-element vector of 24-bit color values, or an NCOLORS-by-3 array of color triples.

This program can also read an ASCII file of color names and values, so you don't have to use the 88 colors provided.

And if you prefer to have the user select a color name, you can use the SELECTCOLOR keyword. (This requires PickColorName.) For example, suppose you want the RGB color triple of a user-supplied color. You would type this:

   IDL> color = FSC_COLOR(/SelectColor, /Triple)
   IDL> Print, color

The output keyword COLORSTRUCTURE is useful if you want to get all of the colors in a structure variable with the color names as fields in the structure.

   IDL> d = FSC_COLOR(/AllColors, ColorStructure=c)
   IDL> Plot, Findgen(11), Color=c.green, Background=c.charcoal, /NoData
   IDL> OPlot, Findgen(11), Color=c.dodgerblue

It is also possible to specify a vector of color names. For example, if you are overploting several lines in a plot, and you wish to each to have a different color, you might do this:

   IDL> d = FSC_Color(/AllColors, ColorStructure=c)
   IDL> Plot, x, y[0,*], Color=c.yellow, Background=c.charcoal, /NoData
   IDL> colors = FSC_Color( ['dodger blue', 'indian red', 'pale green'] )
   IDL> FOR j=0,2 DO OPlot, x, y[j,*], Color=colors[j]

The plot might look something like this.

Updated 15 May 2008 to use Brewer Colors in addition to the normal colors.

PICKCOLOR

A modal dialog widget for selecting a specific color. One of 88 pre-defined color selections can be made, or the user can manipulate slider widgets to create any RGB color triple. The return value of this function is the new color triple. The color table on entry is the same as the color table on exit. You must specifically load the new color for it to take effect. This program requires the FSC_Color program. Updated 15 May 2008 to use Brewer Colors, too. There are now 200 different colors available.

	PICKCOLORNAME
	A blocking or modal dialog widget for selecting a specific color name. Eighty-eight colors are available. The return value of this function is the new color name. Keywords allow the loading of this color directly in the color table. This program requires the FSC_Color program. Updated 15 May 2008 to use Brewer Colors.

XCOLORS

A widget program for changing color tables, it is similar to XLOADCT. This program has been extensively modified. In particular, it now works on 24-bit color displays exactly the way it works on 8-bit displays. NotifyID, NotifyObj, and NotifyPro keywords allow you to identify other widgets, objects, or programs that should be notified when the user changes the color tables. Such notification is essential for updating colors on 24-bit displays. (See the Color_Example program code for an example of how this works.) This program is essential for writing "color aware" widget programs. No common blocks are used, so each graphics window on your display can have its own color table loading tool if you like. A Cancel button restores the original color table if you change your mind about the colors you load. This program is essential if you are loading color tables from widget programs. Updated on 14 May 2008 to support Brewer Colors. You will need to download the fsc_brewer.tbl file from Coyote Library to use this functionality. Install it either in the $IDL_DIR/resource/colors directory or in any directory in the IDL path.

[Return to Table of Contents]

Programs for Working with PostScript Output

ASPECT

This function calculates and returns the normalized position coordinates necessary to put a plot with a specified aspect ratio into the currently active graphics window. This makes it easy to produce PostScript output in the correct dimensions for measuring. For example, here is how I create a plot that is 2 units tall and 3 units wide:

   Plot, data, Position=Aspect(2.0/3.0)

The program has been updated to also work with a page of PostScript or Printer output. For example, I use it to keep the correct aspect ratio of a graphics plot when I send the plot directly to the printer (via the Printer device). For example, here is code I use in an object graphics program to make the graphics output appear on the printed page with the same aspect ratio as in the display window:

   info.thisWindow->GetProperty, Dimensions=wdims
   plotAspect = Float(wdims[1]) / wdims[0]
   windowAspect = 11.0 / 8.5 ; Letter page. Modify for A4 page.

	; Calculate the proper position on the PostScript page.

   position = Aspect(plotAspect, WindowAspect=windowAspect)

	; Change the dimension and location of the view to page mapping.

   info.thisView->SetProperty, Dimensions=[position[2]-position[0], position[3]-position[1]], $
      Location=[position[0], position[1]], Units=3

      ; Print the document.

   info.thisPrinter->Draw, info.thisView, Vector=info.vector
   info.thisPrinter->NewDocument

FSC_PSCONFIG

This program is my long-awaited replacement for PS_Form. Everything I did wrong in PS_Form, I tried to do right here. This program is written as an object, which makes it trivially easy to extend and maintain. I made it easy to add your own system defaults, help screens, custom set-ups, paper sizes, etc. This is a program that should never grow out of date.

This program is the most sophisticated I have ever offered for free, and one of the most sophisticated I have ever written. I was trying to push and extend a number of ideas I am writing about in an upcoming IDL object programming book. Pushing the envelope in terms of what is possible is the only way I know to see how far I can really go. To that end, I am not recommending this program to anyone using versions of IDL older than IDL 5.2. Moreover, you really should use it on a 24-bit display, although it will work on an 8-bit display. (It just won't look as nice, and it will probably cause color flashing if you have other graphics on this display, as it uses the IDL object graphics class library.) The program works wonderfully well on my Windows NT 4 machine running IDL 5.3. Your mileage may vary.

I've tested the program on as many machines as I can get my hands on, but I'm pretty sure it is not bug free. And I am pushing the notion of "cross-platform compatibility" as hard as I can. Please let me know if you discover problems.

Because this program is as sophisticated as it is, I've written a complete on-line help page to show you how to use it. (If you like, you can download the on-line help page as an Adobe Acrobat PDF file.) Plus, for people who really don't want to know anything about it, there is a wrapper function, PSConfig, that provides a simplified function interface to the object's graphical user interface and configuration keyword methods. PSConfig works very much like my older program, PS_Form.

One of the feature's of this program is that it relies on a number of compound widget objects, which you will have to download to use with the program. These are: FSC_Droplist, FSC_FileSelect, FSC_Field, and FSC_PlotWindow. You can download a complete zip file containing all of these programs, as well as PSConfig and PS_Plotter, an example program showing one way to use the object. For additional information, please see the on-line help page.

The program is now updated (9 November 2007) to allow CMYK output.

PS_START/PS_END

These two programs (in the same file) are wrappers that allow easy configuration of PostScript output. In addition to making PostScript set-up effortless, if ImageMagick is installed on your machine, then you can immediately convert your PostScript output to JPEG, PNG, or TIFF image output. The advantage of this is that your Web output takes advantage of nice PostScript fonts.

Here is an example of creating a line plot in a PostScript file named lineplot.ps and at the same time creating a PNG file named lineplot.png for display in a browser:

   PS_Start, FILENAME='lineplot.ps'
   Plot, Findgen(11), COLOR=FSC_Color('navy'), /NODATA, XTITLE='Time', YTITLE='Signal'
   OPlot, Findgen(11), COLOR=FSC_Color('indian red')
   OPlot, Findgen(11), COLOR=FSC_Color('olive'), PSYM=2
   PS_End, /PNG

The programs interface with PSConfig to configure the PostScript device, so any keywords appropriate to PSConfig (and there are a lot of them) can be used with PS_Start. Numerous programs from the Coyote Library are required with these programs, but be sure you get a new version of FSC_PSConfig if you are just downloading this file.

PSCONFIG

This program is a simplified wrapper function for FSC_PSConfig, my new program for configuring the PostScript device. It is essentially a drop-in replacement for PS_Form, an older program with similar functionality. It provides access to FSC_PSConfig's graphical user interface for allowing the user to configure the PostScript device, and it returns the necessary keywords for configuring the PostScript device in exactly the same way PS_Form does. Most of the PS_Form keywords can also be used to set the initial properties of the graphical user interface. Be sure to read the FSC_PSConfig on-line help for instructions. (If you like, you can download the on-line help page as an Adobe Acrobat PDF file.)

You can download all of the programs you need, including an example program and the on-line help in PDF format, in one complete zip file.

The program is used like this:

   keywords = PSConfig(Cancel=cancelled)
   IF cancelled THEN RETURN
   thisDevice = !D.Name
   Set_Plot, 'PS'
   Device, _Extra=keywords
   Plot, findgen(11) ; Or whatever graphics commands you use.
   Device, /Close_File
   Set_Plot, thisDevice

The program is now updated (9 November 2007) to allow CMYK output.

PSWINDOW

This function is used to calculate the size of a PostScript window that has the same aspect ratio (ratio of height to width) as the current display graphics window. It creates the largest possible PostScript output window with the desired aspect ratio. This assures that graphics output looks similar to, if not identical to, PostScript output. This program has been updated with a PRINTER keyword that makes it useful for calculating an output window on the PRINTER device page as well.

[Return to Table of Contents]

Programs for Reading and Writing Data

	DRAWCOUNTIES
	This is an example program that shows you how to read a political boundary shapefile containing state counties. You will have to supply the shapefile to use the program. I used co1990p020.shp, which I obtained for free on the Internet.

	DRAWSTATES
	This is an example program that shows you how to read a political boundary shapefile containing state boundaries. You can supply your own shapefile, or I will read the states.shp file that comes in the IDL distribution.

	GETIMAGE
	A pop-up form widget for selecting and reading binary data. The data files can be either two- or three-dimensional data sets, with or without headers, in XDR or simple binary format. This program is especially useful with the training files used in IDL training courses.

	HDFREAD
	This is an example program that shows you how to read an HDF file that is created with HDFWrite. You will learn how to get file and data set attributes out of the HDF file in a general way, how to access a particular SDS, and how to access and use the color palette that is stored in the HDF file.

	HDFWRITE
	This is an example program that shows you how to write an HDF file that can be read with HDFRead. You will learn how to set file and data set attributes in the HDF file, how to store different types of SDS data, and how to store a color palette in the HDF file.

LOADDATA

This program is a utility routine for reading data files that are found in the IDL distribution, primairly in the $IDL_DIR/examples/data subdirectory. I use it when I teach IDL courses to get data of various types so I don't have to keep opening and closing files all the time. It is not particularly well written, but many of my code examples work better when you have a tool for loading data quickly. :-)

NCDF_BROWSER

The purpose of this program is to allow the user to browse and read the data and metadata in netCDF files. This IDL procedure is an easy-to-use front end for the NCDF_DATA object, described below. This gives you access to a great deal of NCDF_DATA object functionality, without having to be familiar with, or use, object programming. Data and metadata can be read from the file directly into IDL variables at the main IDL level through this graphical user interface. The user has a choice of reading single variables or the entire file. New netCDF files can be loaded with the click of a button..

	NCDF_DATA__DEFINE
	This is the object that underlies the NCDF_BROWSER program described above. The object itself provides the flexibility to browse and read the data and metadata of netCDF files either interactively (as with the NCDF_BROWSER) or non-interactively via object methods. The interactive part of the object, via the BROWSE method, looks identical to the Browser Window described above..

READ_NCDF

This program, written by Paul van Delst, is used to read variable and attribute data from netCDF files. Specific variables and attributes to read can be specified. This is one of the best documented of the netCDF readers, which is why it is included here. An excellent example of how to write your own code. This program does not use pointers, but rather builds the output structure incrementally. This can be slow for large files, but it works nicely for most of the netCDF files I deal with.

SELECTIMAGE

This program is a selection/browser widget for reading known format (e.g. TIFF, JPEG, etc.) images. File formats supported are listed in the table below. A thumbnail image is displayed, along with information about the image, before selection is determined. The image is returned as the result of the function. The program has been updated on 26 February 2006 to read FITS images, if the NASA Astronomy Library is on your IDL path. File type is determined by file extensions. The following file types and extensions are supported.

File Type	File Extensions
BMP	*.bmp
DICOM	*.dcm
FITS	.fits, .fts
GIF	*.gif
JPEG	.jpg, .jpeg, *.jpe
JPEG2000	.jpf, .jpx, .jp2, .j2c, *.j2k
PICT	*.pict
PNG	*.png
TIFF	.tif, tiff

	TVINFO
	This program works together with TVIMAGE and TVSCALE to allow the user to interactively determine image location and values for the displayed image. Further information is contained in this article on my web page.

	TVREAD
	This program is a device independent replacement for the IDL TVRD program. It returns an 8-bit image when called on 8-bit displays and a 24-bit pixel interleaved image when called on 24-bit displays. Optional keywords can produce BMP, GIF, JPEG, PICT, PNG, and TIFF file output automatically.

[Return to Table of Contents]

Utility Programs

	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.

	ARCSAMPLE
	This small utility program re-samples a closed curve with a specified number of points at approximately equally-spaced arc intervals. I've had occasion to use it in a number of different (and strange) applications, so I've become convinced it is generally useful. :-)

	BELL
	This is a Windows-only set of programs for ringing the bell (or--more generally--for playing a sound on Windows machines. Standard sounds (ding, bells, chimes, etc.) are available in your Windows installation. More interesting (and fun) sounds are provided with the Bell program.

	BINARY
	This small utility program is used to print a binary representation of an integer. See Converting Between 8-Bit and 24-Bit Numbers for more information on how it can be used.

	BITGET
	This utility routine returns the bit value (0 or 1) of a specified bit in a number.

	CAPFIRSTLETTER
	This utility routine simply capitalizes the first letter in each word of a given string. All other letters are set to lowercase.

	CENTERTLB
	This utility routine simply calculates the offsets necessary to center a widget program on the display. Call the program after all the widgets have been created, but before the widgets are realized.

	CLIPBOARD
	This utility routine copies the contents of an IDL graphics window to the clipboard for subsequent pasting into other applications. I've successfully pasted IDL graphics windows into Framemaker, Powerpoint, Photoshop, Excel, and Word documents.

	CONVERT_TO_TYPE
	This utility program allows the user to convert input to a particular data type at run-time. It is particularly useful in preserving the data type of input data that needs to be scaled or otherwise manipulated in a data type other than its native type.

	COUNT_ROWS
	Counts the number of rows in an ASCII file. Replaced by FILE_LINES in IDL 5.6.

	FIND_RESOURCE_FILE
	This utility program will find and return a fully-qualified path to a resource file. It will look in likely places to find the file first, then search the entire IDL path for such a file. I find it a big help in distributing applications that require resource files such as bitmaps for buttons, special color table files, or data files for vector overlays, etc.

	FLOATS_EQUAL
	This utility program compares to floating-point or double-precision values or arrays for equality. Arrays are equal if they contain the same number of elements, and each element is equal to the matching element in the other array.

	FPUFIX
	This utility program fixes problems with numerical data that might cause floating point underflow warning messages. Basically, values that are very close to zero (within the MACHAR XMIN limit) are set to zero.

ERROR_MESSAGE

The purpose of this utility routine is to have a device-independent way to create error messages. I like to write programs that use Dialog_Message to report errors to the user. But, of course, these error message don't work if I'm in the PostScript device rather than the X device. This program gives me the ability to write one error message and have it work appropriately for the device it is running on. Moreover, a Traceback keyword will give me accurate traceback information if this is used in conjunction with a Catch error handler.

	FSC_BASE_FILENAME
	The purpose of this utility routine is to allow the user to obtain the base file name, the directory name, and the file extension in a single call. It is similar to the built-in routines FILE_DIRNAME and FILE_BASENAME, but more convenient to use in most situations.

	GET_OBJECT_ID
	This is a simple utility program that returns a unique string identifier for a heap variable (object or pointer).

	HELP_VAR
	The purpose of this utility routine is to allow the user to display help for variables only, without the additional compiled procedures and functions given by the normal HELP command. It uses the undocumented and unsupported IDL routine Routine_Names, so it may not work for you. :-)

	IDLWAVE_CATALOG
	This is an IDLWAVE catalog file that describes the Coyote Library. It is used with the IDL Emacs Mode.

	IMAGE_DIMENSIONS
	The purpose of this utility routine is to have a simple way of obtaining the size and dimensions of both 8-bit and 24-bit images without a lot of fooling around. It is especially useful if you are writing device-independent image display routines.

	INSIDE
	This is a simple utility program that returns a 1 if a specified 2D point is inside a specified 2D polygon. The algorithm used is discussed in this article.

	LINKEDLIST
	This program creates a doubly linked list object. The items stored in the list can be any type of IDL variable. Methods are available to add, delete, count, inquire about, and move list items from one location in the list to another. I like to use the linked list to implement a multiple UNDO or "history" feature in my programs.

	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.

	NUMBER_FORMATTER
	This utility routine converts a number to a string. I use it primarily to convert numbers I wish to display in a text widget. It allows you to specify how many decimal places you would like to have in the output. This is much more flexible than IDL's normal string formatting functions, and it works with all types of numerical values.

	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.

	PROGRESSBAR
	This simple object implements a "progress bar". If you compile the program manually, you will find an example program at the bottom of the file that will show you how to operate the ProgressBar object. This program requires several programs from the Coyote Library, which you can download as a zip file if you like.

	SCALE_VECTOR
	This simple utility routine allows you to scale all the points in a vector between a minimum and maximun value. The minimum value of the vector (or array) is set equal to the minimun data range. And the maximun value of the vector (or array) is set equal to the maximun data range. The program is useful for scaling latitude and longitude vectors for contour plots on map projections, for example.

	SETDEFAULTVALUE
	This utility program sets the default values for positional and keyword arguments to IDL commands.

SHAPEINFO

The purpose of this program is to allow the user to browse a very narrow selection of shapefiles. Namely, those containing geographical shapes in latitude and longitude coordinates. In other words, shapefiles containing maps. File attributes are listed in the left-hand list widget. Clicking on a file attribute, will list all the entity attributes for that file attribute in the right-hand list. Clicking an entity attribute with list the type of entity, and the X and Y bounds of that entity (shown as LON and LAT, respectively), in the statusbar at the bottom of the display.

Knowing the attribute and entity names of a shapefile will give you insight into how to read and display the information in the file. For examples, see the Coyote Library programs DrawCounties and DrawStates.

	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.

	SYMCAT
	This function provides a way of specifying 44 different plotting symbols for use with graphics commands such as PLOT and OPLOT. The return value of the function is used as input to the PSYM keyword. For example, to display a plot with hourglass symbols (symbol number 19), you would type this: Plot, findgen(11), SymSize=2, PSym=SYMCAT(19)

	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.

	THEMONTHS
	This utility routine simply returns the names of the months in various formats. It is useful for labeling graphics displays and so forth. The user can ask for a specific month by giving a month index. Formats, in addition to the normal months, include all capital letters, three-letter abbreviations, and single letters.

	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.

	TVINFO
	This program works together with TVIMAGE and TVSCALE to allow the user to interactively determine image location and values for the displayed image. Further information is contained in this article on my web page.

	TVREAD
	This program is a device independent replacement for the IDL TVRD program. It returns an 8-bit image when called on 8-bit displays and a 24-bit pixel interleaved image when called on 24-bit displays. Optional keywords can produce BMP, GIF, JPEG, PICT, PNG, and TIFF file output automatically.

	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.

[Return to Table of Contents]

Image Processing Programs

	ACTIVECONTOUR
	This is a demonstration program for experimenting with active contours or snakes. It uses the Gradient Vector Flow (GVF) method of active contouring by Chenyang Xu and Jerry Prince. For details of the method and pointers to articles and other information, see Active Contouring (Snakes) in IDL.

ASINHSCL

This is an image processing utility routine similar to GMASCL in that it scales input data into the range of 0 to 255. But it uses an inverse hyperbolic sine scaling algorithm, rather than a power-law (gamma) scaling algorithm. This is extremely useful when you have an image with a low signal to noise ratio. It can compress the noise, which simulataneously expanding the signal. You can specify both the minimum and maximun scaling output values, and you can obtain a negative image by simply setting the Negative keyword. The shape of the hyperbolic sine curve can be modified with a “softening” parameter, named beta. The input is scaled with the following equation before the final output is scaled into the range 0 to 255:

scaled = ASINH(beta*image)

Here is a picture of what the output looks like when the input is INDGEN(256). Although the output resembles a gamma function with the default beta parameter, the function can be “tuned” to work with even those very difficult FITS images. The XSTRETCH program can be used as an interactive front end to this program.

Data scaled with an inverse hyperbolic sine scale factor.

CHECKERBOARD

This function returns a checkerboard image containing a user-specified number of alternating colored boxes (default of 8 as in a real checkerboard). The default image output size is 400 by 400, but can be specified by the user.

CLIPSCL

This is an image processing utility routine similar to BYTSCL in that it scales input data into the range of 0 to 255. But it differs in that a user-specified percentage of pixels can be clipped from either end of the image histogram. The default it to use a two percent clip. (What ENVI calls a linear 2% stretch.) Clipping is approximate, and depends entirely on the image histogram. To clip 5 percent of the pixels from both ends of the image histogram before stretching, type this command. The XSTRETCH program can be used as an interactive front end to this program.

   IDL> TVImage, ClipScl(image, 5)

GAUSSSCL

This is an image processing utility routine similar to GMASCL in that it scales input data into the range of 0 to 255. But it uses an Gaussian (normal) scaling algorithm, rather than a power-law (gamma) scaling algorithm. Interactive Gaussian stretching can be accomplished with XSTRETCH.

Here is a picture of what the output looks like with various Gaussian values when the input is INDGEN(256).

GMASCL

I think of this program as “BYTSCL on steroids!” It scales image data in the manner of BYTSCL, but it also allows gamma log scaling in addition to the standard linear scaling. Moreover, you can specify both the minimum and maximun scaling output values, and you can obtain a negative image by simply setting the Negative keyword. I wrote the program primarily to deal with gnarly FITS images with their often complex image contrast requirements. For exploring image contrast, see XSTRETCH, which is an interactive graphical front end for this program.

Here is a picture of what the output looks like with various gamma values when the input is INDGEN(256).

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.

FIT_ELLIPSE

The purpose of this utility routine is to fit an ellipse to a region of interest (or blob), which is defined by a one-dimensional array of pixel indices (such as is returned by the Where function. The method uses a "mass density" algorithm to calculate center of mass, orientation, major and minor axes, and semi-major and semi-minor axes of an ellise. The points that describe the ellipse are returned as a result of the function.

The result of fitting an ellipse about the ROI.

HIST_ND

The purpose of this program is to calculate an N-dimensional histogram. Please don't ask me any questions about it. I didn't write it, and I'm not even totally sure I understand it. It was written by J.D. Smith and made available to the IDL community via the IDL newsgroup. I do know this: anything JD does is impressive. And the amount of code in this program (well, to be more exact, the lack of code in this program) is tremendously impressive. There is no one in the entire IDL community who understands histograms or vectorization better than JD.

	HISTOMATCH
	The purpose of this program is to perform "histogram matching" on an image. Histogram matching is a process whereby the image pixel distribution is manipulated to conform to the pixel distribution or histogram of another image. The final pixel distribution of the image will approximate that of the input histogram. For a more complete explanation of this process, see Histogram Matching.

LOGSCL

This is an image processing utility routine similar to GMASCL in that it scales input data into the range of 0 to 255. But it uses a log scaling algorithm, rather than a linear or gamma (power-law) scaling algorithm. This is extremely useful when you want to compress information in the upper and lower data values, while stretching the area around a mean value. You can specify both the minimum and maximun scaling output values, and you can obtain a negative image by simply setting the Negative keyword. The center of the scaling curve can be set with a Mean keyword, and the slope of the curve can be set by selecting higher values of Exponent. The input is scaled with this equation before the final output is scaled into the range 0 to 255:

scaled = 1 / ( 1 + (mean/input)^exponent)

Here is a picture of what the output looks like when the input is INDGEN(256). The XSTRETCH program can be used as an interactive front end to this program.

Data scaled with a logrithmic scale factor.

	SHARPEN
	The purpose of this program is to sharpen an image with a Laplacian filter. Laplacian filters identify edges in images. In sharpening, these edges are added back to the image to produce a "sharpening" effect. For a more complete description of the method use, see the article Image Sharpening with a Laplacian Kernel.

XSTRETCH

This widget program has been completely revised as a general purpose contrast enhancer for 2D images. It allows the user to interactively apply linear, gamma, log, or inverse hyperbolic sine stretches to an image. The user moves two threshold bars over the histogram plot of an image and the specified stretch is applied to the image data between the two threshold lines. For the log stretches, a third line shows the general shape of the scaling function. The program has been updated to allow both windows to be interactively resized, printed, as saved in a variety of file output types. The stretched image can be saved to the main IDL level. This program requires a number of programs from the Coyote Library, which you can download as a single zip file. The program was updated on 6 September 2007 to include four new stretches: (1) a linear 2 percent stretch, (2) a square root (log) stretch, (3) a histogram equalization stretch, and (4) a Gaussian normal stretch.

[Return to Table of Contents]

Graphics Display Programs

FSC_WINDOW

A "smart", resizeable graphics window. If you want resizeable graphics windows for direct graphics programs in IDL 5.2 and higher, then this is the program for you. Each graphics window can use and load its own color tables and send its content to PostScript, BMP, GIF, JPEG, PICT, PNG, and TIFF files. These windows "protect" their colors from corruption from other programs and they work on 24-bit displays almost exactly the way they work on 8-bit displays. The program can reproduce virtually any IDL graphics procedure command you wish to write if you follow just three simple rules, outlined in the program documentation. FSC_Window requires a number of programs from the Coyote program library. See the program documentation for details.

This program replaces an older program named XWindow. Note that the names of some keywords have changed from that older program.

This program requires several programs from the Coyote Library, which you can download as a zip file if you like.

	HISTOPLOT
	A program for drawing a histogram plot that actually looks like a histogram plot. The histogram bars can be filled with lines (for black and white printing) or with colors. By setting an OPLOT keyword, you can overplot histograms on already exisiting axes. This program requires FSC_COLOR and ERROR_MESSAGE from the Coyote Library, which you can download as a zip file if you like.

MAP_GSHHS_SHORELINE

Some people prefer the higher precision of the Global Self-consistent, Hierarchical, High-resolution, Shoreline (GSHHS) database for drawing continental outlines and other shorelines to the built-in CIA database that comes with IDL. This program works in way analogous to MAP_CONTINENTS, in that it allows the user to draw shoreline boundaries into a map projection space set up with either MAP_SET or MAP_PROJ_INIT. You see example output below from running the program with the highest resolution GSHHS file. Detailed instructions for using this program are described in an accompanying article.

MPI_PLOT

This program is a wrapper program for the Plot and OPlot commands. Its purpose is to make it easy for the user to modify Plot keywords and parameters through interactive dialogs. Changes are implemented immediately, allowing the user to quickly make a plot ready for publication-quality applications, web output, etc. Users can save the plot in PostScript format, as well as JPEG, TIFF, PNG, BMP, etc. outputs. Users can make changes to program colors, fonts, character sizes, line styles, and plot symbols, among many other parameters. The program window is completely resizable.

Using the program is as simple as using the Plot and OPlot commands.

   IDL> MPI_Plot, data, Color='Saddle Brown', DataColor='Navy', Background='Ivory'
   IDL> MPI_Plot, moredata, Color='Red', LineStyle=2, /Overplot

Below, you can see the MPI_Plot program and the dialog (at reduced size) that gives you access to plot and axis keywords and parameters.

Interactively modify the MPI_Plot parameters.

	PRECIPMAP
	This program is strictly a demonstration program to illustrate how to create a map coordinate system on top of an image that is already gridded into a map projection. It uses a precipitation image that is gridded into a polar stereographic map projection.

READ_TOMS_AEROSOL

This program is strictly a demonstration program to illustrate how to overlay satellite data onto an IDL map projection in a device-independent way. That is to say, the output of the program should look identical (as much as is reasonably possible) on the display and in PostScript output. The program is discussed in detail in this tutorial article. Output of the program looks similar to the image below.

	STATIONPLOT
	This program allows you to plot meteorological "stations" on a map project or other plot. See the WINDBARB program below for a picture of what station plots look like. This was written primarily to be used by the WINDBARB program.

	TERMINATOR_MAP
	This program demonstrates how to calculate and draw a day/night terminator on a map projection. It requires programs from both the Coyote Library and the Johns Hopkins University Applied Physics Lab (JHUAPL) IDL Library. Users can specify seven different map projections, as well as the date and time of a particular view.

TVIMAGE

This program allows you to display and position an image in a output display window with the Position keyword, just like other IDL graphics output. The advantage of this is that output looks the same in PostScript windows as well as display windows and it is trivial to use images along with other IDL graphics commands in the same window. The aspect ratio of the image can be preserved in the output window if desired. The program has been updated to honor the !P.Multi setting, so you can position images in windows exactly the way you do plots. This is a replacement program for the TV command. The program automatically determines if an 8-bit or 24-bit image is being displayed and sets the Decomposition and True keywords appropriately. This is a true device-, image-, and display-independent program. This is far and away the most useful program in my library!

The program has been updated on 18 March 2008 to accept a SCALE keyword that will allow the image argument to be byte scaled before display. An AXES keyword has also been added, which will add a set of axes to the image.

TVSCALE

This program allows you to display and position an image in a output display window with the Position keyword, just like other IDL graphics output. The advantage of this is that output looks the same in PostScript windows as well as display windows and it is trivial to use images along with other IDL graphics commands in the same window. The aspect ratio of the image can be preserved in the output window if desired. The program has been updated to honor the !P.Multi setting. This means you can display multiple images in a window just like you can display multiple plots. This is a replacement program for the TVSCL command, although unlike that command, TVScale allows you to use both a Top and Bottom keyword to specify the range of the scaled data. The data is scaled between the values of the Bottom and Top keywords. The program automatically determines if an 8-bit or 24-bit image is being displayed and sets the Decomposition and True keywords appropriately. This is a true device-, image-, and display-independent program.

	WINDBARB
	This program allows you to plot meteorological wind barbs on a map or other graphical display. Wind barbs show the direction and speed of the wind at a particular location. The figure below shows wind barbs plotted along with station plots on a map projection. To plot stations, you will require the StationPlot program, too.

WINDOWIMAGE

This program demonstrates how to write a program to interactively change the contrast and brightness of an image. This is sometimes called the window level and window width. This kind of interaction is often required when working with 16-bit medical images. Details of the algorithm used in this program can be found in this article. This program requires TVImage and Colorbar__Define from the Coyote program library.

[Return to Table of Contents]

General Widget Programs

COLORBUTTONBITMAP

This simple function creates a true-color bitmap that can be used to create a colored widget button. I used the following code to create the figure below.

   tlb = Widget_Base(/Row, /Exclusive)
   button1 = Widget_Button(tlb, Value=ColorButtonBitmap('Button 1')) 
   button2 = Widget_Button(tlb, Value=ColorButtonBitmap('Button 2', $
      FGCOLOR='YELLOW', BGCOLOR='NAVY'))
   button3 = Widget_Button(tlb, Value=ColorButtonBitmap('Button 3', $
       BGCOLOR='YELLOW', FGCOLOR='INDIAN RED'))
   Widget_Control, tlb, /Realize

	FSC_DROPLIST
	The purpose of this compound widget object is to provide an alternative to the droplist widget (Widget_Droplist) offered in the IDL distribution. What has always annoyed me about a droplist is that you can’t get the current “value” of a droplist easily. This compound widget makes this and other tasks much easier.

FSC_FIELD

This compound widget is designed as a more-or-less drop-in replacement for the RSI-supplied CW_Field program. It is an ill-conceived precursor (which I have tried desperately not to support) to FSC_INPUTFIELD. If you aren't really sure about objects, use this program instead of FSC_INPUTFIELD. If you are ready to go for it, use FSC_INPUTFIELD, the officially supported version of these two similar programs.

	FSC_FILESELECT
	This compound widget is a file selection tool I find I use over and over in my own programming. I wanted a way for the user to be able to select either a directory name or a file name. Writing the program as an object gave me a great deal of power over how I handle absolute or relative file names. Here is what the program looks like in a top-level base by itself:

FSC_INPUTFIELD

This compound widget is designed as a more-or-less drop-in replacement for the RSI-supplied CW_Field program. There are several things I have never liked about CW_Field, but the the foremost thing is that on Windows machines the text widget input box is grayed out and does not look as if it is editable. Without this visual clue, users are confused about how CW_Field works. This program is more flexible and powerful than CW_Field. One of the ways it is more powerful is that it is possible to set the fields up so that users can tab from one field to the next and have the text in the fields automatically selected for editing. An example program at the end of the code shows you how this is done. Compile the program file first to run the example.

TEXTBOX

A simple example of the proper way to write a pop-up dialog widget program that returns information to the caller. The program can be used to return a single piece of information from the user. For example, to ask the user for the name of a variable to store a processed image at the main IDL level, you might type something like this:

   varname = TextBox(Title='Provide Main-Level Variable Name...', Group_Leader=event.top, $
      Label='Variable Name: ', Cancel=cancelled, XSize=200, Value='stretched_image')
   IF NOT cancelled THEN BEGIN
      displayImage = BytScl(*info.image, Top=info.top,  $
         Max=info.maxThresh, Min=info.minThresh)
      dummy = Routine_Names(varname, displayImage, Store=1)
   ENDIF

See Writing Pop-Up Dialog Widgets for a discussion of this program.

	XMOVIE
	A simplified XInterAnimate program that shows you the correct way to implement an animation loop in a widget program with a Widget_Timer event.

ZIMAGE

This program allows you to "zoom" into a portion of an image. It illustrates how to use pixmaps and the "device copy" technique to create a rubberband box on top of an image. It also illustrates a very powerful technique of having several event handlers for an individual widget and switching between them. This makes your programs more modular and easier to maintain. (For the equivalent program written with object graphics, see ZOOMBOX.)

	ZPLOT
	This program shows you how to "zoom" into a line plot. Similar to ZImage, the program allows you to designate a zoom area with a rubberband box. The program also demonstrates a device independent way to work with drawing colors. The program requires GetColor from the Coyote Library.

[Return to Table of Contents]

Object Graphics Programs

CONTRASTZOOM

This is an object graphics program that I set as a programming exercise for myself. I had several ideas I wanted to work out in object graphics. First, I wanted to know how to work with several graphical representations of data in the same graphics window. I wanted each view to work independently of the others, and I wanted to know how to gather user interaction from each view. Second, I wanted to know how to do an "in place" zoom into an image, and do it in such a way that I could preserve the aspect ratio of the portion of the image I was zooming into. Third, I wanted to show how to "window" and "level" an image. This is also known as setting the "contrast" and "brightness" of the image. I wanted to do this in conjunction with a color bar that reflected the window and level in a way that was intuitive and gave me a sense that I knew what I was doing. :-)

I spent nearly 10 days working on this. Not exclusively, but steadily. I was surprised at how difficult it was to get what I wanted. The IDL documentation does not offer much in the way of how to do things easily. For example, I tried several different ways of drawing the rubberband box in the zoom image until I found a method that reliably gave me the proper image coordinates. It took me a long time to figure out how to maintain the proper aspect ratio of the image in a resizeable graphics window. At the end, I got fairly good at knowing what to do. But I spent hours staring at my computer screen, too.

You can see a picture of the program in the figure below. The left image is a zoomable image. Click and drag a rubberband box around the portion of the image you wish to "zoom" into. The image is not necessarily zoomed. Rather, this portion of the image is shown in the graphics view in a way that preserves its aspect ratio. The effect is to have it appear that you are zooming into the data. To "zoom out" to the entire image, just click and release anywhere in the left window.

The center window is the contrast/brightness image. Click and drag the cursor horizontally in this window to adjust the "brightness" or "level" of the image data. Click and drag the cursor vertically in this window to adjust the "contrast" or "window" into the image data. Click and release the cursor in this window to return to the starting values of 25% contrast and 75% brightness.

FSC_NORMALIZE

I find the scaling factors that have to be passed to the [XYZ]Coord_Convert keyword to get graphics primitives arranged properly in my graphic views impossible to understand. Here is a program that allows me to specify the primitive's data range (obtained from the primitive itself) and a position in my arbitrary coordinate system and it calculates the proper scaling factor automatically. I could not write object graphics programs without it. This is a program that is used in all of my object graphics programs.

	FSC_PLOTWINDOW
	This is an object compound widget, written using object graphics, that is -- quite frankly -- probably not good for much of anything, except curiosity. I use it to good effect in my FSC_PSConfig program. It consists of a resizeable "plot" window inside a draw widget. If I come up with any more uses for it, I'll let you know. :-)

FSC_SURFACE

An example program of how to create a fully-rotatable surface with axes and a title with the IDL object graphics system. The display window is resizeable. Menu bar options give you the ability to change plot colors, send output directly to your printer, create numereous types of file output containing the window's contents, and manipulate other surface plot properties. This program is heavily documented to give you a good start on writing object graphics programs of your own. New functionality added in 2002 includes the ability to zoom into and out of the plot using the right and middle keywords, the ability to set the aspect ratio of the plot (including Z scaling), and the ability to create encapsulated PostScript (EPS) files. Elevation shading and light controls are also demonstrated. This program requires several programs from the Coyote Library. You can download all the programs you need in this zip file.

This program won the IDL Code Contest, sponsored by Research Systems, Inc. to inaugurate their User Contribution Library in November 2002.

	HCOLORBAR
	This is a program that creates a horizontal colorbar using IDL object graphics. This program defines the methods and structure for a horizontal colorbar object. The program should be named "hcolorbar__define.pro". This program shows you the correct way to create your own object graphics primitive from a collection of objects from the IDL object graphics class library.

IMAGE_BLEND

People have asked for the best way to combine two images so that you could see through one image into the other. This is one way to do it, using the alpha blending channel available with object graphics images. In the default mode, you can overlay a color image on a gray-scale image. But this program is written so that you can change both the foreground and background image colors and set the "amount" of transparency with a slider.

	iXYOUTS
	This is a program for adding text to an iTool program interactively. It is analogous to XYOUTS in direct graphics. It can accept any keywords that are appropriate for an IDLgrTEXT object.

	OBJECT_SHADE_SURF
	Someone on the IDL newsgroup wanted to know how to make an elevation- shaded surface in object graphics. Oddly enough, you do this by turning all shading off! Here is an example of how to do it.

	REVERSE_AXES
	I was asked a simple question: "How do you reverse an object graphics axis without the textual annotation going completely bonkers." Four days later, I came up with the answer. It wasn't what I expected. You can read the details in this article. But here is the code that shows you how to do it.

SELECT_OBJECTS

This is an example program that shows you the easiest way to select, move, and size graphics objects interactively. The program displays an image, colorbar, and title object which can be selected and moved within the graphics object window. In addition, the right mouse button causes the selected object to get smaller, while the middle mouse button causes the selected object to get larger. This program requires several programs from the Coyote Library, which you can download as a zip file if you like.

	SIMPLE_SURFACE
	This is a greatly simplified version of FSC_Surface without all the bells and whistles of the latter program. If you are just getting started with object graphics, this is a good program to start learning from.

TEXTURE_SURFACE

If you follow the suggestions of the IDL on-line documentation for adding an image as a texture map to an object graphics surface, you will be led astray. Here is the proper way to add an image as a texture map. Details about the process can be found in this article. The program also demonstrates how to add a texture to just a portion of the surface, and how to specify a color for the remaining portion of the surface. These details are not covered at all in the IDL documentation.

	VCOLORBAR
	This is a program that creates a vertical colorbar using IDL object graphics. This program defines the methods and structure for a vertical colorbar object. The program should be named "vcolorbar__define.pro". This program shows you the correct way to create your own object graphics primitive from a collection of objects from the IDL object graphics class library.

XCONTOUR

This is a simple contour plot program written with the new IDL object graphics capability. It comes in a resizeable graphics window. You can send the window contents directly to the printer. You can also save the window contents in GIF or JPEG files and manipulate some contour plot properties. Filled and line contours are shown. You will probably have to do some work to get a really robust contour plot program, but this well-documented program gives you a place to start. The program has been updated to work with the new contour and colorbar objects introduced in IDL 5.1.

XIMAGE

This is a simple image plot program that displays an image with axes around it. It is written with IDL object graphics. The image is displayed in a resizeable graphics window. You can send the window contents directly to the printer, or you can save the window contents as TIFF, JPEG, etc. files. Image colors can be changed and some simple image processing operations are demonstrated. Moving the cursor in the image returns the cursor location and the value of the image at that location. (Image value is available only for 8-bit images.) The image can b