Coyote Graphics System (CGS) Commands

QUESTION: What in the world is the Coyote Graphics System (CGS) I am hearing so much about!?

ANSWER: The Coyote Graphics System (CGS) is a collection of Coyote Library programs that turn the traditional IDL graphics commands (e.g., Plot, Contour, Surface, TV, etc.) into modern programs that duplicate the device independence, color model independence, and functionality (including resizeable graphics windows) of the latest “new” graphics system in IDL. Best of all, this functionality is available in any version of IDL. Documentation for the Coyote Graphics System routines is now available on-line. Also, there are number of IDL programming tips that apply specifically to Coyote Graphics routines.

CGS commands work the same on your display, in a PostScript file, and in the Z-graphics buffer. They allow traditional graphics commands to be displayed in resizeable graphics windows that are as easy to work with as the non-resizeable graphics windows IDL programmers have traditionally used. The resizeable graphics window allows your graphics display to automatically (and programmatically, if you choose) create PostScript and PDF file output, and any of five different types of raster file output. If ImageMagick is installed on your computer, raster file output can use PostScript intermediate files to give your raster output, and especially your output fonts, a presentation quality look. Ghostscript is required to produce PDF file output.

CGS graphics visualizations can be saved and recalled later, or e-mailed to colleagues so they can view the same graphics output you see on your display.

CGS routines use colors in a natural way (e.g., Color='red') and work correctly in either an indexed or decomposed color environment.

CGS routines are faster (sometimes orders of magnitude faster!) than the equivalent IDL function graphics commands.

Best of all, CGS routines fix most of the bugs (e.g., contour holes and levels) in the traditional IDL commands and work in the intuitive way you expect them to work.

The programming techniques for creating programs that work in the CGS system are now completely explained in my latest book, Coyote's Guide to Traditional IDL Graphics: Using Familiar Tools Creatively.

Coyote Graphics System Programs

The Coyote Graphics System really makes use of all the programs in the Coyote Library, but here are short descriptions of the programs that belong specifically to the CGS system.

cgColor -- The granddaddy of device independent graphics programs, cgColor allows you to ask for colors by name, a fundamental property of all the graphics programs described below. If you want to learn the names of the 200 colors you can use, type this command.
```
   color = PickColorName()
```
cgPlot -- This is a wrapper for both the Plot and OPlot commands. It differs from both in that you can set both the color of the data (with the Color keyword) and the color of the axes, titles, and other plot annotation (with the AxisColor keyword), as well as the color of the symbols (with the SymColor keyword). To overplot on a set of axes established by another command, set the OverPlot keyword. Another new feature of this command is that you can use the Aspect keyword to select a particular aspect ratio (height/width) of the plot. And, like most Coyote Graphics commands, you can send the command directly to a PostScript, PDF, JPEG, PNG, etc. file with the Output keyword. Here is an example of the command in action. Users can use all 46 symbols allowed by SymCat, rather than just the eight allowed by the Plot command.
```
   data = cgDemoData(1)
   cgPlot, data, COLOR='red', Aspect=2./3, XTitle='Time', $
       YTitle='Signal', PSym=-46, SymColor='grn6', SymSize=2
   cgPlot, !X.CRange, [15,15], LineStyle=2, Color='blue', /Overplot
```
cgPlot is a wrapper for both the Plot and OPlot commands.

To display this or any other CGS command in a resizable graphics window, simply set the Window and/or AddCmd keywords.
```
   data = cgDemoData(1)
   cgPlot, data, Color='red', Aspect=2./3, XTitle='Time', $
       YTitle='Signal', PSym=-46, SymColor='grn6', SymSize=2, /Window
   cgPlot, !X.CRange, [15,15], LineStyle=2, Color='blue', /Overplot, /AddCmd
```
Plot and OPlot command can be displayed in resizeable graphics windows.
cgContour -- This is a wrapper for the Contour command. It fixes a number of problems with the traditional Contour command, including producing the correct number of contours when the NLevels keyword is used, and properly filling the contour hole in contour plots. A new Label keyword makes it easy to label contour levels. It will easily overlay contours on images, if the images are displayed with cgImage. To display this command in a resizable graphics window, set the Window keyword. To send the output of the command directly to a PostScript, PDF, JPEG, PNG, or TIFF file, use the Output keyword.
```
   data = cgDemoData(2)
   LoadCT, 33, NColorS=12, Bottom=1
   cgContour, data, /Fill, NLevels=12, Position=[0.125,0.125,0.9,0.75], C_Colors=Indgen(12)+1
   cgContour, data, /Overplot, Color='black'
   cgColorbar, Range=[Min(data), Max(data)], Divisions=12, NColors=12, Bottom=1, $
       Position=[0.125, 0.87, 0.9, 0.94], /Discrete
```
cgContour is a wrapper for the Contour command.
cgSurf -- This is a wrapper for both the Surface and Shade_Surf commands. (Although, for convenience, you can use the cgShadeSurf command to create shaded surfaces.) The title is put onto the surface flat-to-the-screen, rather than rotated in the traditional Surface fashion. To display this command in a resizable graphics window, set the Window keyword. To send the output of the command directly to a PostScript, PDF, JPEG, PNG, or TIFF file, use the OUTPUT keyword.
```
   data = cgDemoData(2)
   cgLoadCT, 0
   cgSurf, data, /Shaded, Shades=BytScl(data)
   cgLoadCT, 25, /Brewer, /Reverse
   cgSurf, data, Shades=BytScl(data), /NoErase, Title='Surface Title'
```
cgSurf is a wrapper for both the Surface and Shade_Surf commands.
cgSurface -- As nice as cgSurf is, it still suffers from limitations imposed on the Surface command. In particular, the Surface command is not a true 3D command, since the surface cannot be rotated around all three axes. You need to move to the object graphics system, which is a true 3D system, to obtain this functionality. But the object graphics surface commands offered by Excelis (iSurface or the new Surface function in IDL 8) seem clunky and unintuitive to me. For one thing, the Z-axis is always in the wrong place when the commands start up. cgSurface is a non-traditional traditional graphics command that is meant to complement these other traditional commands. I use it when I truly want to see what my surface looks like. It comes in a resizeable graphics window and the surface can be rotated with the mouse around all three surface axes. The Middle and Right buttons zoom into and out of the surface. Clicking on the surface axes will allow the user to move or translate the surface, and clicking on the plot title will allow the user to move the title. You can save the surface as JPEG, PNG, TIFF, or PostScript files. You have complete control over the four lights that illuminate the surface, and you can drape any 2D or true-color image on top of the surface.
```
   data = cgDemoData(2)
   cgLoadCT, 33
   cgSurface, data, /Elevation_Shading, /Shaded, Title='Elevation Shading'
   cgSurface, data, Title='Texture Mapping Example', Texture_Image=cgDemoData(16), ZScale=0.5
```
cgSurface is a non-traditional traditional command for interacting with surfaces.
cgImage -- This command 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. I haven't used a TV command in 15 years, and you shouldn't be using it either. It is absolutely impossible to work with images in any meaningful way with the TV command. Liam Gumley's ImDisp is another good TV alternative command. One way cgImage differs from ImDisp is that cgImage is able to display images with alpha channels properly. cgImage can display, for example, transparent images. To send the output of the command directly to a PostScript, PDF, JPEG, PNG, or TIFF file, use the Output keyword.
```
   image = cgDemoData(18)
   cgLoadCT, 4, /Brewer, /Reverse
   cgImage, image, Margin=0.025, /Save, /Axes
   cgContour, image, Color='black', /OnImage
```
cgImage is a wrapper for the TV command.

cgImage allows an image to be positioned on the display with the same Position keyword used by other graphics commands, and it recognizes the setting of !P.Multi so you can use it to produces multiple plots, like other graphics commands.
```
   head = Reverse(cgDemoData(8), 2)
   s = Size(head, /Dimensions)
   cgLoadCT, 0
   cgDisplay, 9*s[0], 6*s[1]
   !P.Multi = [0, 9, 6]
   !X.OMargin = [0, 25]
   !Y.OMargin = [0, 8]
   FOR j=0,53 DO cgImage, head[*,*,j], Background='white', MultiMargin = 0.25
   !P.Multi = 0
   cgColorbar, /Vertical, Range=[0,10], Format='(F0.2)', $
       Position=[0.94, 0.15, 0.97, 0.80], $
   cgText, 0.45, 0.95, 'MRI Study of the Head', /Normal, Alignment=0.5
   !X.OMargin=0 & !Y.OMargin=0 
```
cgImage can be positioned with the Position keyword and with !P.Multi.
cgPlotS -- This command is a wrapper for the PlotS command. Data colors (Color keyword), symbol colors (SymColor keyword), and symbol sizes (SymSize keyword) can all be vectors. This allows you to draw plots with multicolored lines, multicolored symbols, and/or multisized symbols.
```
   data = cgDemoData(1)
   time = Scale_Vector(Findgen(101), 0, 6)
   LoadCT, 33, /Silent
   cgPlot, time, data, /NoData, XTitle='Time', YTitle='Signal'
   cgPlotS, time, data, PSym=-16, Color=BytScl(data), $
           SymColor=BytScl(data), SymSize=Scale_Vector(data, 1.0, 2.5)
```
cgPlotS is a more powerful alternative to PlotS.
cgColorbar and cgDCbar-- These commands produce continuous and discrete color bars, respectively. See Adding a Colorbar for additional information about color bars.
cgBarPlot -- This command displays a bar plot. See Creating a Bar Plot for additional information.

Four data sets displayed side-by-side in a bar plot.
cgBoxPlot -- This command displays a box plot. See Drawing a Box and Whisker Plot for additional information.

A box and whisker plot in IDL.
cgAxis -- This command draws an axis in the display window and is a wrapper for the Axis command.
cgText -- This command is a wrapper for the XYOutS command. Colors can be expressed by name and the text can be placed in a graphics window interactively, using the cursor, if the Placekeyword is set. If the color is undefined the text is automatically written in a color "opposite" to the background color for maximum contrast.
cgDisplay -- This command is a wrapper for the Window command. Colors can be expressed by name. The default erase color is "white" to accommodate these graphics commands. This command can be used in programs that are meant to work on the display and in devices that do not support windows by "protecting" the Window command from the latter devices. In other words, before in such programs you had to write code like this.
```
   IF (!D.Flags AND 256) NE 0 THEN Window, 1, XSIZE=400, YSIZE=500
```
Now, you can just write code like this.
```
  cgDisplay, 1, 400, 500
  cgDisplay, XSIZE=600, YSIZE=600, /FREE, Color='gray'
```
The Window command is protected automatically. In a PostScript file, the command acts to create a "window" with the same aspect ratio as the current graphics window. This makes is extremely easy to produce PostScript output that looks virtually identical to your display output. In the Z-graphics buffer, the command sets the resolution of the Z device to match the size of the current graphics windows.
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 and PDF output. Any Coyote Graphics routine that sets a Window keyword will be displayed in an cgWindow application. This makes it possible to use this resizeable, smart graphics window in a fashion that is identical to how normal IDL graphics windows are used. Use cgSet, cgShow and cgDelete to manipulate cgWindow applications.
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.
```
   cgLoadCT, 4, /Brewer, /Reverse, NColors=12, Bottom=1
   data = cgDemoData(2)
   cgContour, data, NLevels=12, /Fill, C_Colors=Indgen(12)+1, $
              Position=[0.1,0.1,0.9,0.75], /Outline, /Window
   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.

To change colors in an cgWindow display, use cgLoadCT or XColors with the Window keyword set. The WinID keyword can select which cgWindow, based on window index number, to apply the colors to. Otherwise, the current cgWindow colors are changed.
```
   cgLoadCT, 33, /Window
   XColors, /Window
```
The current commands in a cgWindow (the visualization) can be saved to a file, e-mailed to a colleague so he or she can be looking at the same visualization you are, and restored whenever you like. Simply use the Save Visualization and Restore Visualization buttons under the File menu on the interface.
cgSymbol -- This command allows you to use 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.
cgSnapshot -- This command allows you to take a snapshot of a graphics window. It is the equivalent to the TVRD command in IDL. It can be used to automatically create color raster file output in any of five different raster file formats.
cgQuery -- This command allows you to gather information about all the cgWindow applications currently on the display. Information includes window index numbers, the widget identifiers of the top-level base widgets, the window titles, or the window's object references. Set the Currentkeyword to get similar informaton for just the current cgWindow.
cgControl -- This command allows you to set various global and local properties of the graphics window. For example, you can turn window updating on or off, change the parameters for how PostScript files are created, and even create PostScript, PDF, and raster files programmatically..
cgSet -- This command allows you to make an cgWindow application the "current" display window. It is the equivalent to the WSet command in IDL.
cgShow -- This command allows you to bring an cgWindow application forward on the display. It is the equivalent to the WShow command in IDL.
cgDelete -- This command allows you to delete any or all cgWindow applications on the display. It is the equivalent to the WDelete command in IDL.
cgErase -- This command is a wrapper for the Erase command. Colors can be expressed by name. The default erase color is "white" to accommodate these graphics commands. Set the Window keyword to erase an cgWindow and delete all of its display commands.
```
   cgErase, 'gray'
```
cgLoadCT -- A beefed-up LoadCT. Brewer color tables as well as IDL color tables can be loaded, reversed, clipped, etc. Set the Window keyword to change the cgWindow color tables.
XColors -- A functional XLoadCT. Brewer color tables as well as IDL color tables can be loaded, reversed, clipped, etc. Set the Window keyword to change the cgWindow color tables.
cgDefCharSize -- This utility routine calculates default character sizes for Coyote Graphics routines. The character size depends on the operating system you are using, the current font value, and the state of the !P.Multi system variable. It's purpose is to make character sizes large enough to be read easily and to make Coyote Graphics routines look more like the IDL 8 function graphics routines. Default character sizes are only used if !P.Charsize is set to its default value of 0.
cgWindow_SetDefs -- This utility routine sets the default "values" for the window. Configure your PostScript and ImageMagick output, turn resizeable text sizing on or off, set the background color for the window, and set many other options.
cgWindow_GetDefs -- This utility routine returns the default "values" for the window.
cgPS2PDF -- A program that converts PostScript files to PDF files in a machine independent way, using Ghostscript or its equivalent for the conversion process.
PS_Start and PS_End -- I use these commands to create PostScript files, which I turn into high-quality graphics files (PNG, JPEG, TIFF, etc.) with ImageMagick for display on web pages and in presentations. I used to gripe about fonts in traditional graphics. But not since I learned to use ImageMagick. Now I produce a PostScript file and create a high quality PNG, JPEG, or TIFF file at the same time. I don't even think about fonts anymore.
For example, to create the contour plot example above, I typed these commands at the IDL command line. The resulting output is right-side-up, too, because PS_End automatically calls FixPS to put those upside-down IDL landscape files in the proper orientation for display in other programs.)
```
   PS_Start, Filename='coyote_graphics.ps'
   data = cgDemoData(2)
   cgLoadCT, 33, NColors=12, Bottom=1
   cgContour, data, /Fill, NLevels=12, Position=[0.125,0.125,0.9,0.75], $
      C_Colors=Indgen(12)+1,  /Outline
   cgColorbar, Range=[Min(data), Max(data)], Divisions=12, NColors=12, Bottom=1, $
      Position=[0.125, 0.87, 0.9, 0.94], XTicklen=1, XMINOR=0
   PS_End, /PNG, Resize=12.5
```

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


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