Coyote Graphics Programs

These are programs from the Coyote Library that are specifically identified as being associated with the Coyote Graphics System. Documentation for Coyote Graphics routines is now available on-line. These programs are included in the Coyote Library. Please consult this article if you are having any difficulty running a Coyote Graphics program. If you are looking for ideas for your own graphics output, visit the Coyote Plot Gallery for examples and IDL code for over 50 different plots you can create with Coyote Graphics routines.

Major Graphics Commands

cgCOLOR The heart and soul of the Coyote Graphics system!
cgCOLORBAR Creates direct graphics color bar.
cgCONTOUR A device-independent and color-independent wrapper for the CONTOUR command.
cgHISTOPLOT Draws a histogram plot (direct graphics).
cgIMAGE Device independent replacement for TV. Works with !P.Multi and Position keyword.
cgPLOT A device-independent and color-independent wrapper for the PLOT command.
cgPLOTS A device-independent and color-independent wrapper for the PLOTS command.
cgSTRETCH Interactively increase image contrast with various image pixel transformations.
cgSURF A device-independent and color-independent wrapper to the SURFACE and SHADE_SURF commands.
cgSURFACE A full-rotating, object graphics surface command with texture mapping.
cgTAYLORDIAGRAM Creates a Taylor Diagram plot from user data.
cgZPLOT An interactive zoom/pan compound widget or application for line plots.
cgZIMAGE An interactive zoom widget for 2D and true-color images.

Minor Graphics Commands

cgARROW Draws an arrow in a graphics window.
cgAXIS A device/color independent wrapper for the AXIS command.
cgBARPLOT Draws data as a bar plot.
cgBLENDIMAGE Allows the user to blend two images together.
cgBOXPLOT Draws data as a box and whisker plot.
cgDOTPLOT A fancy plot, used more often in business presentations.
cgLAYOUT Returns positions for positioning graphics in a column/row grid.
cgPOLYGON A device-independent and color-independent program for creating filled or unfilled polygons.
cgSCATTER2D Creates a scatter plot between two variables.
cgSNAPSHOT Device independent replacement/upgrade for TVRD. Creates raster files directly.
cgSYMBOL Draws device independent Greek (φ, ξ, λ, etc.) and other symbols (Å, ≠, ≡, etc.) in programs.
cgSYMCAT A symbol catalog with 46 possible symbols to use in IDL graphics plots.
cgTEXT A wrapper for XYOUTS that writes (and places) text in a color independent manner.
cgWINDROSE Creates a wind rose diagram from wind speed and direction arrays.

Color Graphics Commands

cgCOLOR The heart and soul of the Coyote Graphics system!
cgCOLOR24 Converts RGB color value to 24-bit integer.
cgCOLORBAR Creates direct graphics color bar.
cgCOLORFILL A device-independent and color-independent wrapper for the POLYFILL command.
cgDCBAR A discrete color bar with a handful of colors and centered labels.
cgDEFAULTCOLOR This function defines a default color for Coyote Graphics routines.
cgLOADCT A drop-in replacement for LOADCT with additional functionality.
cgPICKCOLORNAME Utility for picking or specifying a color by name.
cgTIMESTAMP A utility program to create a time stamp in 11 different formats.
cgTRANSPARENTIMAGE Creates a semi-transparent image with optional missing color “knocked-out”.

Utility Commands

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.
cgCHECKFORSYMBOLS Parses a text string for embedded cgSymbol characters.
cgCONLEVELS A function for creating contour levels for the cgContour command.
cgCONTAINER A modified IDL_Container object with properties important for Coyote Graphics.
cgCOORD A coordinate object for Coyote Graphics routines.
cgDEFCHARSIZE A routine define the default character size for Coyote Graphics routines.
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.
cgGRAPHICSKEYWORDS Maintains a list and the values of typical "graphics keywords".
cgGREEK Returns a letter from the Greek alphabet as a string for plot annotation.
cgHISTOGRAM A wrapper for HISTOGRAM that prevents silent errors and adds functionality.
cgIMAGEINFO Works with cgIMAGE to display interactive image locations and values.
cgJULIAN2DATE Converts a Julian Number into a well-formatted date string.
cgNUMBER_FORMATTER A utility routine to format numbers used in text widgets.
cgMONTHS Returns a month string in various formats for graphic rendering.
cgNORMALIZE Creates scaling vector that positions graphic elements in graphic views.
cgOBJ_ISA Similar to the built-in OBJ_ISA, but with more features.
cgOTSU_THRESHOLD Finds the threshold between bimodal populations of pixels in an image.
cgPICKFILE A wrapper for Dialog_Pickfile that remembers your last selection.
cgPROGRESSBAR Implements a "show progress" bar.
cgREVERSEINDICES A routine read the histogram reverse indices vector in a simple way.
cgRESIZEIMAGE A Congrid command without Congrid's weaknesses for resizing images.
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.
cgSET_TTFONT Sets the True-Type font for PostScript and raster output.
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.

Window Commands

cgCONTROL A routine for setting and controlling cgWINDOW properties.
cgDELETE A routine to delete an cgWINDOW from the display.
cgDISPLAY A device-independent and color-independent wrapper for the WINDOW command.
cgERASE A wrapper for ERASE that erases window in white color.
cgQUERY A utility routine to gather information about cgWINDOW applications on the display.
cgSET A WSet command for cgWINDOW.
cgSHOW A WShow command for cgWINDOW.
cgWINDOW A "smart" graphics window. Resizeable with automatic file output.
cgWINDOW_GETDEFS Gets default values for cgWINDOW.
cgWINDOW_SETDEFS Sets default values for cgWINDOW.

Output Commands

cgCBAR2KML Creates a color bar for KML files in Google Earth.
cgFIXPS Fixes IDL PostScript landscape output files so they display with proper orientation.
cgIMAGE2KML Creates a KML file to overlay an image in Google Earth.
cgKML_FEATURE Implements an abstract KML Feature object class.
cgKML_FILE Creates a KML file to be displayed in Google Earth.
cgKML_GROUNDOVERLAY Implements an KML GroundOverlay element.
cgKML_LOOKAT Implements an abstract KML LookAt object class.
cgKML_OBJECT Implements an abstract KML Object object class.
cgKML_OVERLAY Implements an abstract KML Overlay object class.
cgKML_SCREENOVERLAY Implements a KML ScreenOverlay object class.
cgKML2KMZ Create KMZ files from KML and image files.
cgPS2PDF A device-independent way to create PDF files from PostScript intermediary files.
cgPS2RASTER Create BMP, GIF, JPEG, PDF, PNG, and TIFF files from PostScript intermediary files.
PS_START Open and configure a PostScript file.
PS_END Close a PostScript file.

Mapping Commands

cgCBAR2KML Creates a color bar for KML files in Google Earth.
cgCHANGEMAPPROJECTION Warps an image in one map projection to another.
cgCLIPTOMAP Clip or subset a georegistered image to a map boundary.
cgDRAWSHAPES A program to draw shapefile polygons on map projections.
cgFINDMAPBOUNDARY Finds the the boundary of the map projected grid for files that allow it.
cgGEOMAP Automatically georegisters a GeoTiff image.
cgGOOGLE_METERSPERPIXEL Calculates meters per pixel value for Google Static Maps.
cgGOOGLEMAPMARKER__DEFINE Defines a marker structure for Google Static Maps.
cgGOOGLEMAPWIDGET A compound object-widget for adding Google Static Maps to an application.
cgGOOGLEMAPWIDGET__DEFINE The cgGoogleMapWidget object.
cgIMAGE2KML Creates a KML file to overlay an image in Google Earth.
cgMAP_CONTINENTS A Coyote Graphics wrapper for Map_Continents.
cgMAP_GRID A Coyote Graphics wrapper for Map_Grid that fixes a number of problems.
cgMAP_GSHHS Draws outlines from the GSHHS shoreline data on maps.
cgMAP_SET A Coyote Graphics wrapper for Map_Set.
cgMAP A more powerful means of creating and using GCTP map projections.
cgMAPCONTINENTS An object wrapper for cgMap_Continents and cgMap_GSHHS.
cgMAPGRID An object wrapper for cgMap_Grid.
cgMAPPLOTS Draws lines and symbols on map projections set up with cgMap.
cgMAPVECTOR Draws vectors (arrows) on map projections set up with cgMap.
cgNCDFMAP Creates a map coordinate object for netCDF files with map projections.
cgSHAPEINFO Allows the user to browse shapefiles containing geographical information.
cgTERMINATOR_MAP Creates a day/night map terminator on a map projection.
cgUTMZONE Returns the UTM zone for a particular longitude and latitude.
cgWARPTOMAP Allows mapping of data with associated latitude and longitude arrays.

	cgADDTOPATH
	This utility program allows the user to add a new directory to the IDL !PATH system variable.

	cgAPPENDTOFILENAME
	The purpose of this utility routine is to allow the user to append some text to the root name of a file. It is often used when a variable is changed for some reason, and you want to save the variable in a file with a different name.

	cgARROW
	This program draws an arrow on a graphics display. It is similar to the old Arrow command in IDL that now conflicts with the Arrow object in IDL 8. Set the WINDOW keyword to add this command to an cgWindow application.

	cgAXIS
	This program is a wrapper for the AXIS command and is meant to work seamlessly with the other other Coyote Graphics programs in this device independent, color independent series. Set the WINDOW keyword to add this command to an cgWindow application.

	cgBARPLOT
	Draws data as a bar plot.

cgBLENDIMAGE

This is an extremely simple program that will "blend" or "fuse" two 24-bit true-color images using alpha blending. You set the alpha value to a number between 0 and 1 to select the percentage of background image pixels to use in the blended image. For example, ALPHA=0.8 will use 80% of the background pixel values and 20% of the foreground pixel values in the blended image. The program is a wrapper to the cgImage command and can use all the features and keywords of that command. The figure below shows two MODIS images on the left (MOD02) and middle (MOD29), and the blended image on the right. An ALPHA value of 0.75 was used to create the blended image.

A blended image.

	cgBOXPLOT
	Draws data as box and whisker plots. Here is example output from plotting the Michaelson-Morely data from their speed of light experiments.

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

	cgCHECKFORSYMBOLS
	This function parses a text string for embedded cgSymbol characters and replaces them with the appropriate display or PostScript values to render the symbol. Symbols are embedded by prepending a "$\" to the start of the symbol name, and finishing with a "$" (e.g., $\Angstrom$).

cgCOLOR

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 nearly 200 colors defined in the program by name. The colors available are the ones defined for the cgPickColorName program:

The cgColor program colors.

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

   IDL> Print, cgColor(/Names), Format='(5(A14, 2x))'
         WHITE            SNOW           IVORY     LIGHTYELLOW        CORNSILK
         BEIGE        SEASHELL           LINEN    ANTIQUEWHITE          PAPAYA
        ALMOND          BISQUE        MOCCASIN           WHEAT       BURLYWOOD
           TAN       LIGHTGRAY        LAVENDER      MEDIUMGRAY            GRAY
     SLATEGRAY        DARKGRAY        CHARCOAL           BLACK        HONEYDEW
     LIGHTCYAN      POWDERBLUE         SKYBLUE  CORNFLOWERBLUE       CADETBLUE
     STEELBLUE      DODGERBLUE       ROYALBLUE            BLUE            NAVY
     PALEGREEN      AQUAMARINE     SPRINGGREEN            CYAN       TURQUOISE
 LIGHTSEAGREEN        SEAGREEN     FORESTGREEN            TEAL     GREENYELLOW
    CHARTREUSE       LAWNGREEN           GREEN       LIMEGREEN       OLIVEDRAB
         OLIVE       DARKGREEN   PALEGOLDENROD           KHAKI       DARKKHAKI
        YELLOW            GOLD       GOLDENROD   DARKGOLDENROD     SADDLEBROWN
          ROSE            PINK       ROSYBROWN      SANDYBROWN            PERU
     INDIANRED       CHOCOLATE          SIENNA      DARKSALMON          SALMON
   LIGHTSALMON          ORANGE           CORAL      LIGHTCORAL       FIREBRICK
       DARKRED           BROWN         HOTPINK        DEEPPINK         MAGENTA
        TOMATO       ORANGERED             RED         CRIMSON       VIOLETRED
        MAROON         THISTLE            PLUM          VIOLET          ORCHID
  MEDIUMORCHID      DARKORCHID      BLUEVIOLET          PURPLE       SLATEBLUE
 DARKSLATEBLUE             WT1             WT2             WT3             WT4
           WT5             WT6             WT7             WT8            TAN1
          TAN2            TAN3            TAN4            TAN5            TAN6
          TAN7            TAN8            BLK1            BLK2            BLK3
          BLK4            BLK5            BLK6            BLK7            BLK8
          GRN1            GRN2            GRN3            GRN4            GRN5
          GRN6            GRN7            GRN8            BLU1            BLU2
          BLU3            BLU4            BLU5            BLU6            BLU7
          BLU8            ORG1            ORG2            ORG3            ORG4
          ORG5            ORG6            ORG7            ORG8            RED1
          RED2            RED3            RED4            RED5            RED6
          RED7            RED8            PUR1            PUR2            PUR3
          PUR4            PUR5            PUR6            PUR7            PUR8
          PBG1            PBG2            PBG3            PBG4            PBG5
          PBG6            PBG7            PBG8            YGB1            YGB2
          YGB3            YGB4            YGB5            YGB6            YGB7
          YGB8            RYB1            RYB2            RYB3            RYB4
          RYB5            RYB6            RYB7            RYB8             TG1
           TG2             TG3             TG4             TG5             TG6
           TG7             TG8        OPPOSITE

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 = cgCOLOR("Green", !D.Table_Size-2)
   backColor = cgCOLOR("Dark Gray", !D.Table_Size-3)
   dataColor = cgCOLOR("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 cgCOLOR program to specify colors.

The value that is returned by cgCOLOR 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, cgColor('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 nearly 200 colors provided.

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

   IDL> color = cgCOLOR(/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 = cgCOLOR(/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:

   x = Findgen(101) * 10/101.
   y = FltArr(3,101)
   FOR j=0,2 DO y[j,*] = cgDemoData(17)
   cgPlot, x, y[0,*], AxisColor='yellow', Background='charcoal', /NoData
   colors = ['dodger blue', 'indian red', 'pale green']
   FOR j=0,2 DO cgPlot, x, y[j,*], Color=colors[j], /Overplot

The plot might look something like this.

An example of using the cgCOLOR program to specify colors.

cgCOLORBAR

This program shows you one way to create a color bar for your programs. This color bar appears exactly the same in a PostScript file as it does on your display. You can easily create continuous or discrete color bars.

Color bars created with the cgColorbar program.

	cgCOLORFILL
	This program is a wrapper for the POLYFILL command. It fills a polygon with a color or "texture." Set the WINDOW keyword to add this command to an cgWindow application.

cgCONLEVELS

The cgContour program specializes in producing equally spaced contour intervals. But, depending on the data, the levels are not always "nicely" spaced or formatted. The role of the cgConLevels function is to address this problem by providing an easy and intuitive way to produce contour levels that look nice on contour plots.

Here is code that produces a "normal" contour plot with 10 equally-spaced contour intervals.

    cgDisplay, WID=0
    data = cgScaleVector(cgDemoData(2), 0.1, 4534.5)
    cgLoadCT, 33, NColors=10, Bottom=1
    cgContour, data, NLevels=10, /Fill, /Outline, $
       Position=[0.1, 0.1, 0.9, 0.75], C_Colors=Indgen(10)+1
    cgColorbar, NColors=9, Bottom=1, /Discrete, /Fit, $
       Range=[Min(data), Max(data)], OOB_High=10, OOB_Low='white'

A normal contour plot with 10 equally spaced contour intervals.

Here is code that use cgConLevels to produce the contour levels.

    cgDisplay, WID=1
    data = cgScaleVector(cgDemoData(2), 0.1, 4534.5)
    cgLoadCT, 33, NColors=10, Bottom=1
    levels = cgConLevels(data, Factor=100, MINVALUE=0)
    cgContour, data, Levels=levels, /Fill, /Outline, $
       Position=[0.1, 0.1, 0.9, 0.75], C_Colors=Indgen(10)+1
    cgColorbar, NColors=9, Bottom=1, /Discrete, /Fit, $
       Range=[Min(levels), Max(levels)], OOB_High=10, OOB_Low='white'

Using cgConLevels to produce equally spaced contour intervals.

A contour plot using cgConLevels to produce the contour intervals.

	cgCONTAINER
	This is a subclassed IDL_Container object that contains properties that are used with other Coyote Graphics routines.

cgCONTOUR

This program does for the CONTOUR command what the cgIMAGE command did for TV command. In other words, it makes the CONTOUR command obsolete, by giving users a useable device-independent, color-independent tool for producing graphics on modern computers. See the article Device Independent Contour Plots for additional information and screen shots. Below are pictures of basic Contour plots (on the left) verses cgContour plots (on the right), in both regular and filled versions. Set the Window keyword to add this command to an cgWindow application.

Regular contour plots.

Filled contour plots.

	cgCONTROL
	This routine allows the user to control various internal properties of a cgWindow application, including the ability to load images with and without immediate execution and the ability to programmatically create PostScript and raster file output from the window. The program is essentially a conduit to the SetProperty method of the underlying cgWindow object.

	cgCOORD
	This is a subclassed cgContainer object that maintains a rectangular data coordinate system for other Coyote Graphics objects and programs.

	cgDBLTOSTR
	This utility routine converts a double-precision number to a string in a way that preserves all 14 significant digits. A more general form of this function is cgNumber_Formatter.

cgDCBAR

This program produces a discrete color bar with a handful, say 3 to 20 colors. Labels are centered (either horizontally or vertically) for each color, and the labels can be rotated, if needed, to keep an uncluttered display. The colorbar can be displayed either horizontally or vertically anywhere in the display window. You can learn more about how this program works by reading the Discrete Color Bar article on my web page.

A discrete color bar..

cgDEFAULTCOLOR

The purpose of this function is to choose a default color for Coyote Graphics routines. The input can be a string, a byte or integer, or a long integer. If the input is a long integer, the function will evaluate the value depending upon the current color state. If using indexed color, and the long integer is in the range 0-255, the long integer is interpreted as a color table index number. The output is generally passed to cgColor to obtain the actual color used in the program.

    color = cgDefaultColor(inputColor, Default='Opposite')
    IF Size(color, /TNAME) EQ 'STRING' THEN color = cgColor(color)

cgDEFCHARSIZE

This program selects the default character size for Coyote Graphics programs. Character size is based on several factors, including operating system, font type, and whether multiple plots are being displayed. In no case is the character size changed by the program if the !P.Charsize system variable is not set to its default value of 0.0. The character sizes returned are meant to emulate the slightly larger default character sizes used in the IDL 8 function graphics system.

	cgDELETE
	This command allows you to delete any or all cgWindow applications on the display. cgWindow applications can be selected by window index number, window title, widget identifier, or object reference. Set the ALL keyword to delete all the cgWindow applications on the display.

cgDEMODATA

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. :-)

cgDISPLAY

This program is a wrapper for the WINDOW command. It erases a graphics window in a device and color independent way. Colors can be specified as color names. The default color is "white." This program automatically “protects ”the WINDOW command from devices that do not support windows. It is used to create IDL graphics windows in programs that are meant to work identically on the display and in other devices, such as the PostScript device, that do not support windows. If issued while in the PostScript device, a "window" with the same aspect ratio as the window that would be created on the display is specified. Using this program to open windows is one way to ensure your PostScript output looks identical to your display output.

	cgDOTPLOT
	A dot chart or dot plot is a statistical chart consisting of data points plotted on a simple scale, typically with open or closed circles. This program trys to imitate the dot plot found on this web page.

	cgERASE
	This program is a wrapper for the ERASE command. It erases a graphics window in a device and color independent way. Colors can be specified as color names. The default color is "white." Set the WINDOW keyword to erase (delete) all the commands from an cgWindow graphics display before the display is erased with the specified color.

	cgGRAPHICSKEYWORDS
	This program is an object that maintains a list of "graphics keywords" and their current values. Normally, Coyote Graphics objects will use this object as a superclass object to deal with the "common" keywords associated with most graphics routines without having to continually define the same keywords in programs.

cgGREEK

This returns a Greek letter in a device-independent way for use in plot titles and other graphics annotation. Programs written using this function will work in your display window or in your PostScript file. The names of the Greek alphabet are shown below.

cgHISTOPLOT

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. The cumulative probability distribution function can be obtained and/or plotted on the histogram plot. Set the WINDOW keyword to add this command to an cgWindow application.

The cgHISTOPLOT program.

cgHISTOGRAM

This program is used as a wrapper to the Histogram command in IDL. It works around a bug in the Histogram command when byte data is binned in versions prior to IDL 8.2, and it takes care to match the data type of the BinSize keyword to the data type of the data being binned. If this matching is not done, Histogram silently returns incorrect results. I have added the ability to smooth the data (with the Smooth keyword) and to return the relative frequency of the histogram, rather than the histogram counts (with the Frequency keyword). The relative frequency is a number between 0 and 1. I have also added the ability to specify "missing" data that should not be binned.

cgIMAGE

This program is a wrapper for the TV and TVScl commands. You don't have to use this command, but you do have to use a TV alternative command. Nothing in IDL will hold you back more from improving your programming skills than the TV command. I haven't used a TV command in 15 years, and you shouldn't use it either. With the exception of cgColor, no program is more important and more powerful in the Coyote Graphics System than cgImage.

Among the many features of the cgImage command are these:

Works identically on the display, in PostScript files, and in the Z-buffer
Is color model independent
Displays 2D, true-color, and alpha-channel images in correct colors
Allows images to be positioned with the POSITION keyword
Honors the !P.MULTI system variable
Images can be created with axes
A image coordinate system can be established with XRANGE and YRANGE keywords
Automatically scales images with values less than 0 or greater than 255
Has 10 different contrast enhancement stretches for image display
Protects image colors
Allows color tables to be selected with the CTIndex and Palette keywords
Allows overplotting of images onto a data or map coordinate system
Can read and display images directly from a file.
Works well with the map coordinate object, cgMap, for georegistered images
Allows semi-transparent images to be overlaid on existing images
Allows output directly to PostScript and raster files (e.g., PNG, JPEG, TIFF, etc.)

	cgIMAGEINFO
	This program works with cgIMAGE 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.

	cgJULIAN2DATE
	This function converts a Julian number into a well-formatted date string of the form 16 Mar 2008 15:45:33. Input can be a scalar or an array of Julian numbers. There are 15 different formats for the date string, selected with the FORMAT keyword.

	cgKML_FEATURE
	This object implements the abstract Feature class in a KML file. A feature extends a KML object.

	cgKML_FILE
	This object implements and writes a KML file for display in Google Earth. See the KML Documentation for additional details. This is a partial implementation of the KML elements that go into a KML file. Initially, enough infrastructure was built to allow images to be added to KML files as GroundOverlay objects. Please check back frequently for updates and extensions to this code.

	cgKML_GROUNDOVERLAY
	This object implements a GroundOverlay element in a KML file. A ground overlay allows an image to be draped over the Google Earth terrain map.

	cgKML_LOOKAT
	This object implements the abstract LookAt class in a KML file. A LookAt tag allows the user to "fly to" a particular location and elevation over the surface of the Earth.

	cgKML_OBJECT
	This object implements the abstract Object class in a KML file. An Object class ia a basic KML class and is normally inherited by almost every other KML class.

	cgKML_OVERLAY
	This object implements the abstract Overlay class in a KML file. An Overlay extends a KML Feature class.

	cgKML_SCREENOVERLAY
	This object implements a ScreenOverlay element in a KML file. A screen overlay allows an image to be located at an permanent location on the Google Earth display. It is useful for creating color bars and legends for ground overlays.

cgKML2KMZ

This program simply collects files created from the cgImage2KML program and moves the files to a zip file with a *.kmz file extention. The method used is an undocumented and unsupported method for creating KMZ files in IDL 8. It should not be relied upon, and it will not work in earlier versions of IDL. The cross-platform zip file functionality is scheduled to be exposed to IDL users in an IDL release sometime in 2013, but it is not known when or if this will occur.

cgLAYOUT

The purpose of this program is to return the normalized position coordinates for a line plot, contour plot, or image plot with a specific "layout" in the current graphics window. A "layout" has a specified grid of columns and rows organized inside a graphics display window. This program is particularly useful for laying out !P.Multi-like plots with additional annotation, such as color bars associated with them. Here, for example, is how I would create a 2 by 2 grid of images, each with an associated color bar.

   cgDisplay, WID=1
   cgLoadCT, 22, /Brewer, /Reverse
   pos = cgLayout([2,2], OXMargin=[5,5], OYMargin=[5,12], XGap=3, YGap=10)
   FOR j=0,3 DO BEGIN
       p = pos[*,j]
       cgImage, cgDemoData(18), NoErase=j NE 0, Position=p
       cgColorBar, position=[p[0], p[3]+0.05, p[2], p[3]+0.1]
   ENDFOR
   cgText, 0.5, 0.925, /Normal, 'Example Image Layout', Alignment=0.5, $
       Charsize=cgDefCharsize()*1.25

You see the result in the figure below.

cgLOADCT

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: "cgLOADCT, 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> cgLoadCT, 5, NCOLORS=8, CLIP=[16,240]

Colorbars with colors loaded with LOADCT and cgLOADCT

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.

	cgMONTHS
	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.

	cgNUMBER_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.

	cgOBJ_ISA
	This program is similar to the built-in Obj_Isa program, except that it can handle undefined arguments and arrays.

	cgOTSU_THRESHOLD
	The purpose of this function is to find an optimal threshold for separating a bimodal distribution of pixels in an image histogram. The Otsu Threshold method is used to find the threshold.

cgNORMALIZE

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.

	cgPICKFILE
	This utility program is a wrapper for Dialog_Pickfile, except that it remembers the directory location of your last selection and, optionally, the last file name selected. Keywords allow me to find files in my IDL directories easily.

	cgPLOT
	This program does for the PLOT command what the cgIMAGE command did for TV command. In other words, it makes the PLOT command obsolete, by giving users a useable device-independent, color-independent tool for producing graphics on modern computers. Set the WINDOW keyword to add this command to an cgWindow application.

cgPLOTS

This program is a device-independent, color-independent wrapper for the PLOTS command. Data colors (Color keyword), symbol colors (SymColor keyword), and symbol size (SymSize keyword) can all be vectors, unlike the PLOTS command. This allows you to draw plots with multicolored lines, multicolored symbols, and/or multisized symbols. Set the WINDOW keyword to add this command to an cgWindow application.

   IDL> data = cgDemoData(1)
   IDL> time = cgScaleVector(Findgen(101), 0, 6)
   IDL> LoadCT, 33, /Silent
   IDL> cgPlot, time, data, /NODATA, XTITLE='Time', YTITLE='Signal'
   IDL> cgPlotS, time, data, PSYM=-16, COLOR=BytScl(data), $
           SYMCOLOR=BytScl(data), SYMSIZE=cgScaleVector(data, 1.0, 2.5)

cgPlots functionality

	cgPOLYGON
	This command allows you draw a filled or unfilled polygon on the display. Polygons can be created in two or three dimensions, and the fill color can be different from the polygon outline color.

cgPS2PDF

This program takes advantage of third-party free software (Ghostscript, pstopdf, epstopdf, etc.) to create a machine independent way to create PDF files from PostScript intermediate files. It is not my intention to reinvent the wheel, but I did need a way to create PDF files automatically from within a cgWindow program, and this program does the job. On-line documentation for this program is available .

	cgPS2RASTER
	This program takes advantage of the ImageMagick convert command to convert PostScript intermediate files to BMP, GIF, JPEG, PNG, or TIFF raster files in a machine independent way. On-line documentation for this program is available .

cgQUERY

This command allows you obtain information about all the cgWindow applications currently on the display. You can obtain their window index numbers, the identifiers of their top-level base widgets, their window titles, and their object references. If the CURRENT keyword is set, the same information can be obtained for just the current cgWindow application.

   IDL> windowIDs = cgQuery(WIDGETID=tlbIDs, OBJECTREF=objRefs, TITLE=winTitles, COUNT=count)
   IDL> FOR j=0,count-1 DO Print, windowIDs[j], '  ', winTitles[j]

cgRANDOMINDICES

This command allows the user to select a certain number of random indices out of a selection vector. The indices are selected without replacement, which means you get a list of unique indices. (None are repeated.) For example, to select 10 random indices out of a vector of 100 random indices, you would type this.

   IDL> indices = cgRandomIndices(100, 10, SEED=seed)
   IDL> Print, indices
        7  13  20  21  32  44  50  66  80  93

	cgRANDOMWALD
	This command returns random numbers based on an Inverse Gaussian Distribution of numbers. This is also known as a Wald Distribution. IDL> numbers = cgRandomWald(seed, 5) IDL> Print, numbers 0.35932975 0.47249304 1.8922137 0.33552555 0.74778911

cgRESIZEIMAGE

This program is a substitute program for Congrid, specifically for sizing 2D and true-color images, without the weaknesses of the Congrid command. Interpolation always occurs at pixel centers, so that resized pixels do not change their image "location." True-color (or 3D) images can be resized with nearest neighbor sampling, unlike with the Congrid command. See Resizing Images for additional detailed information.

	cgROOTNAME
	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.

	cgSCATTER2D
	This program allows you to create a scatter plot between two variables. It is similar to a plot command, but in addition it optionally calculates the Pearson correlation coefficient and plots a best-fit straight line though the data. The fitting parameters can be retrieved from the program and/or displayed on the data plot. On-line documentation for the program is available.

	cgSNAPSHOT
	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.

	cgSURF
	This program does for the SURFACE and SHADE_SURF commands what the cgIMAGE command did for TV command. In other words, it makes the SURFACE and SHADE_SURF commands obsolete, by giving users a useable device-independent, color-independent tool for producing graphics on modern computers. Set the WINDOW keyword to add this command to an cgWindow application.

cgSURFACE

This program has been completely re-written in Nov 2010 to be a fully-capable surface command along the lines of the traditional surface command, cgSurf. It uses most of the the same keywords and acts in a similar fashion, but adds a great deal more functionality, including interactivity. Users can rotate and zoom into and out of the surface with the mouse, change colors and other surface properties at will, and save the surface to a number of output file types, including PostScript. Four lights illuminate the surface, and users have complete control over the color and intensity of these lights. The lights can be turned on or off to change surface features. Any 2D or true-color image can be added to the surface as a texture map.

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


cgSurface is a non-traditional traditional graphics command for interacting with surfaces.

cgTAYLORDIAGRAM

This program implements a Taylor Diagram from user data. A Taylor diagram can represent three different statistics (centered root-mean-squared (RMS) distance, correlation, and standard deviation) simultaneously in one two-dimensional plot. According to the IPCC:

"Taylor diagrams provide a way of graphically summarizing how closely a pattern (or a set of patterns) matches observations. The similarity between two patterns is quantified in terms of their correlation, their centered root-mean-square difference and the amplitude of their variations (represented by their standard deviations). These diagrams are especially useful in evaluating multiple aspects of complex models or in gauging the relative skill of many different models."


A Taylor Diagram plot.

	cgSET
	This command is the equivalent of the WSet command for normal IDL graphics windows. It allows you to select a cgWindow application on the display and make it the "current" cgWindow application. Graphics commands are normally added to the current graphics display window. cgWindow applications can be selected by window index number, window title, widget identifier, or object reference.

	cgSET_TTFONT
	This command allows the user to set the name of the True-Type font that should be used for PostScript and raster file output.

	cgSHOW
	This command is the equivalent of the WShow command for normal IDL graphics windows. It allows you to move a cgWindow application forwand on the display without making it the "current" cgWindow application. Graphics commands are normally added to the current graphics display window. cgWindow applications can be selected by window index number, window title, widget identifier, or object reference.

	cgSYMBOL
	This command allows you to create device independent Greek (φ, ξ, λ, etc.) and other symbols (Å, ≠, ≡, etc.) in your IDL programs. The symbols produced will work correctly on the display and in a PostScript file. See the article Using Greek Symbols for additional information. Symbols can be embedded into text strings in Coyote Graphics routines.

cgSYMCAT

This function provides a way of specifying 46 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 star symbols (symbol number 45), you would type this:

   Plot, cgDemoData(1), SymSize=2, PSym=cgSYMCAT(45)

Symbols can also be asked for by name (e.g., "star" or "-star"). Coyote Graphics plotting routines can take advantage of this capability automatically.

   cgPlot, cgDemoData(1), SymSize=2, PSym="-star"

cgTEXT

This program is a wrapper for XYOUTS and is meant to work seamlessly with the other cg*** programs in this device independent, color independent series. It can choose its color based on the background color of the graphics window. If the PLACE keyword is set, the user can click inside the current graphics window to set text at the cursor location. Set the WINDOW keyword to add this command to an cgWindow application.

   IDL> cgText, 0.5, 0.5, 'Centered Text', /ALIGNMENT=0.5, COLOR='dodger blue'
   IDL> cgText, /PLACE, 'Use CURSOR to Locate this Text', COLOR='red8'

cgTIMESTAMP

This utility routine creates a time stamp in one of 11 different formats. Optionally, a sequence of any number of random digits can be appended to the time stamp. Local or UTM time can be specified. And the time stamp can be formatted in a way that is appropriate for use in an IDL variable name.

   IDL> FOR j=0,10 DO Print, cgTimeStamp(j)
      _sun_feb_07_21:24:54_2010
      _Sun_Feb_07_21:24:54_2010
      _07_02_2010_21:24:54
      _07022010_21:24:54
      _07022010
       _07Feb2010_21:24:54
      _07feb2010_21:24:54
      _07FEB2010_21:24:54
      _02_07_2010_21:24:54
      _02072010_21:24:54
      _02072010

cgTRANSPARENTIMAGE

Creates a transparent image either from a supplied image or from an IDL graphics window. The missing "color" can be specified as the name of a color, as a color index (for 2D images) or as a color triple. Optionally, the transparent image can be saved as a transparent PNG file.

Here is an example of some commands to display a transparent image.

   cgDisplay, WID=0
   cgImage, cgDemoData(5), CTIndex=0, /Interp
   timage = cgTransparentImage(COLOR='black', TRANSPARENT=50)
   cgDisplay, WID=1
   cgImage, cgDemoData(7), CTIndex=22
   cgImage, timage

	cgWINDOW_GETDEFS
	This routine allows the user to get global default values for configuring cgWindow.

	cgWINDOW_SETDEFS
	This routine allows the user to set global default values for configuring cgWindow.

cgWINDOW

This command is a resizeable graphics window for displaying IDL graphics commands. In addition to resizing the graphics window, this command can create BMP, GIF, JPEG, PNG, TIFF raster files, as well as true PostScript output. This command is invoked automatically by setting the Window keyword on Coyote Graphics routines. If ImageMagick is available on your machine, you will have the additional option of making raster image files of the window contents directly from PostScript files. This completely eliminates any concern for poor quality fonts in raster file output.

The cgWindow program can accept multiple graphics commands. Commands can be added, deleted, replaced, and listed. Multiple cgWindow programs can be opened at once, and you have easy access to the commands in any graphics window. Here is an example of how to display a filled contour plot with a color bar.

   IDL> cgLoadCT, 4, /Brewer, /Reverse, NColors=12, Bottom=1
   IDL> cgWindow, 'cgContour', cgDemoData(2), NLevels=12, /Fill, C_Colors=Indgen(12)+1, $
           Position=[0.1,0.1,0.9,0.75]
   IDL> cgWindow, 'cgContour', cgDemoData(2), Color='Charcoal', NLevels=12, /Overplot, /AddCmd
   IDL> cgWindow, 'cgColorbar', Divisions=12, Range=[Min(data), Max(data)], NColors=12, $
            Bottom=1, XMinor=0, XTicklen=1.0, /AddCmd

cgWindow allows multiple commands that can be moved and edited.

If used with Coyote Graphics routines (by setting the WINDOW keyword), cgWindow can be used in exactly the same way normal IDL graphics windows are used. That is to say, resizeable, smart graphics windows are available for all IDL users.

cgWINDROSE

This command creates a wind rose diagram from wind speed and direction data. There is an example using the program in the Coyote Plot Gallery.

The results of running the cgWindRose program.

cgZIMAGE

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. The image location and the image value at that location is output in a status bar widget in newer versions of this program. This makes your programs more modular and easier to maintain. Right clicking in the image window pulls up hidden zoom controls. (For the equivalent program written with object graphics, see ZOOMBOX.)

cgZPLOT

This routine allows the user to interact with a line plot created with cgPlot. Users can zoom and pan into the line plot display. There is a multiple undo and redo capability, and users can "tweak" the zoom by clicking the LEFT mouse button outside of the plot boundaries. Clicking inside the plot boundaries with the LEFT mouse button will allow a rubberband-box zoom in both the X and Y directions. A button is available that can "adjust" the Y range of the zoomed-in plot to completely show the values indicated by the X range of the zoomed-in plot. Combined with Undo and Redo (all implemented at key combination shortcuts), this allows the user to "pull-in and back-out" of zoomed plots. The RIGHT mouse button allows fast panning of the plot in the display window. The program is written as a stand-alone application, but it is also a compound widget object, which means you can have a zoom/pan window in your own IDL application.

Version of IDL used to prepare this article: IDL 7.0.1.

Last Updated: 24 May 2012