By
Richard Grotjahn
with assistance from:
Erick Lorenz
This primer supersedes a previous document entitled "NCAR Graphics on ATM Computers" written by Grotjahn (1994). The earlier document showed how to use NCAR graphics on the microvax machines. This document indicates some basic steps in using NCAR graphics on the Atmospheric Science UNIX computers. Please note these cautions: 1) the versions and their implementations change over time and this document is based upon working procedures at the time of publication indicated below. 2) This document is not a substitute for reading the manuals, but instead provides an overview of some features in the plotting system. The Appendices are intended only to provide some commonly-needed reference material. It is not intended to be a comprehensive description.
Be sure to notice:
NCAR graphics is a collection of programs and subroutines that can be used to generate, store, view and plot computer graphics. The original NCAR graphics (all versions before version "2") used FORTRAN 77 and created metacode files of plotter instructions (unique to NCAR graphics) and required special translators to be viewed on output devices. Beginning with version 2.0, the routines were implemented with GKS compatible output. GKS stands for Graphics Kernal System; it was one of the first standardized collections of plotting instructions. By creating a GKS version, the user no longer had to create metacode translators, but could create a GKS file which the manufacturer of the plotting device would have a translator for already. The GKS version also makes the NCAR plot package more transportable.
NCAR graphics has been divided into two groupings of FORTRAN subprograms. One group contains "primitive" "system" routines. The other group contains "higher level" subprograms that call the "system" routines; the higher level programs are called graphics "utilities" in NCAR documentation.
System plot package: In the versions before GKS, there was a "NCAR System Plot Package" (NSPP) which contained so-called graphics primitives. The primitives did simple tasks, like: pen-up, pen-down, move pen, scale the plotting screen, advance to the next frame (page), etc. GKS contains many of the same types of commands. NCAR's GKS calls are in a group labelled "SPPS", which stands for "System Plot Package Simulator." Versions of most of the original NSPP routines are still callable as SPPS routines in versions 2 and 3 . Examples include: SET, CURVE, LINE, GETSET, FRSTPT, VECTOR, and FRAME. These still exist, though there may be slight changes in the arguments. Some old NSPP files do not exist (e.g. FLASH) in SPPS, while others have been placed in the second group of "higher level" files (like those that draw borders and grids). Descriptions of the SPPS can be found in the version 2 manual.
Graphics Utilities: The "utilities" include programs that do popular tasks, such as contour plotting, line plotting (f(x) vs x), software characters, two and three dimensional surfaces. Since contour plotting is so important to scientists, the most important improvement between versions 2 and 3 is surely the great improvement in the appearance of contour plots in version 3. In versions 1 and 2, the primary contour plotting was handled by 6 routines. Version 3 allows you to select contour plotting routines that perform similar tasks but from 2 new utilities: CONPACK and BIVAR. The changes to the Utilities between versions 2 and 3 are summarized in the manual for version 3. Tables from that manual are reproduced below. The manual for version 3 only discusses those changes made to version 2, so one needs the manual for version 2 for many of the utilities. As of this writing, we have version 3 implemented on the ATM machines.
This document will assume that you are familiar with the UNIX operating system on the Atmospheric Science computers. This includes using directories, saving, compiling, linking, and running jobs. It is also assumed that you know how to do file editing. You can obtain more information on atm25 by typing by accessing several NCAR graphics man pages. For example:
generates a list of other ncar graphics man pages. Included are examples and other information under separate headings. For example, for information on ictrans, type:
The GKS version can be run in either an interactive or a batch type mode. The interactive mode will likely change when version 4 is installed since that version has a rudimentary graphical user interface (GUI). This document only discusses the batch mode. (In a batch mode, you run your program which creates a plot file as output. When your program is finished, you open the graphics file and view the plots.)
You must place the following FORTRAN statement before your first plot instruction
and after the last graphics statement call, you place
There are example programs in the manuals and on line from the DEC VMS system. Several examples can be found in the directory: DISK10:[NCARG] TEST.DIR
Alternatively, you may wish to use the executable file "contour.for" which is included in a public access directory: /library/ on moe.ucdavis.edu. This program is described next. The example executable shell file that creates a contour plot can be obtained while in your directory by typing:
where the trailing period causes a file named "contour.for" to be placed in your current directory. Information about using this file can be found in the comment cards within the file. You need to look at those comment cards (for UNIX and FORTRAN changes) in order to run this program.
Program contour.for is an executable file meaning that the file contains all the necessary UNIX scripts to run the fortran program contained in the file as well as handle simple I/O. The file will run as is (as long as it is designated executable). The first changes you are likely to make are to specify informative file names for your output. The file is set up to plot a simple array; most plot calls are contained in subroutine PLOTY, while the main program sets up two simple arrays and calls subroutine PLOTY. Novice users may wish to simply modify the main program and not change the subroutine until becoming more familiar with NCAR graphics. When properly designated as an executable file, all one needs to do is type the file's name (including the extension) and hit "return" in order to run the program.
The file is intended to be largely self-explanatory and illustrates the specific application of generating pleasing, but generic contour plots. The script illustrates the special compile option needed for using NCAR graphics as well as how to rename the printed (.out) and plotted (.plt) output files. Most of the FORTRAN calls for plotting are collected in the subroutine PLOTY. Some lines in PLOTY are commented out but included to illustrate some other options.
The file contour.for illustrates creating contour plots; eventually a library of similar files is planned that illustrates other types of plotting tasks such as: line drawing (f(x) vs x), streamline or vector fields, shaded fill, 3-dimensional plots, and political/continental map outlines. The current library includes programs to draw f(x) vs x plots and to contour randomly located data.
3. Viewing a plot
You have two main options for viewing the plot file. When you are using an x-windows environment, you can use a simple and intuitive viewer invoked using the idt command. When you are using a graphics terminal (non-windowed) access, then you can use the ictrans command.
The x-windows environment is automatically created on ATM 24 and 25 when you log in. When using a networked PC to log in you have two options for connecting to a UNIX CPU: X-Win vs the telnet "terminal" button. If you start up the X-Win facility on a networked PC, the monitor will have a display much like that on the graphics workstations: atm24 or atm25. On a graphic workstation or with X-Win your PC can use the graphics display facility: "idt" directly. The UNIX command to view a plot file: test.plt is very simple:
where "nn" is the number of the PC that you are using. That is a "zero" on the end of the command.
The idt command will start two windows, one of which has "buttons" that look something like a video player. The right pointing arrow button advances to and plots the next frame in the plot file. The left pointing arrow backs up and plots the previous plot frame. There is a print button which gives a menu choice that includes: hpm (for the hp4 printer), cps (for the color printer), and ln7 (for the ln7 printer). As of this writing, the hpm option is recommended. Please remember that each color printer plot is quite expensive. As of this writing, memory problems sometimes occur with ln7 that may cause a graphics frame to be lost. When you are done viewing your plots, activate the "done" then "quit" buttons to end an idt session.
The GKS version has a similar facility as PLOT for the old NCAR graphics; it is invoked using ictrans. On some x-windows configurations ictrans may open a plotting window, but the common usage here is for displaying graphics when you are using a terminal emulator. An example terminal emulator is EM4105. (This is a common means of accessing the computers using a modem.) What ictrans does is inform your terminal emulator that the instructions that follow are to be interpreted as plotting commands, until you quit the ictrans facility.
A sample session might begin with the command:
where test.plt is the file of plots you wish to examine. The "t4105" specifies the plotting device type, here it informs ictrans that the GKS commands must be translated into tektronics 4105 metacode language. Hence, you need to specify the correct device type (from the available options in ictrans) to best match your emulator. When started, ictrans will change the prompt and you have simple options by which to plot, print, or skip to various plot frames in your plot file. When you are done you type quit. The printer that the indicated frame is sent to depends upon the printer you specified in your UNIX environment prior to initiating ictrans. Some example ictrans commands are: 2p this indicates plot frame number 2 (note: lower case p)
Note: when the drawing of a plot has been completed, ictrans will pause. (This allows a print screen command, for example.) You must hit "return" before the ictrans prompt will reappear and allow you to use another command. This command, like all UNIX commands, is case sensitive. For example: 3P indicates print frame number 3 (note: upper case P) h displays a list of ictrans commands and how to use them quit terminate ictrans
Finally, you may send an entire plot file directly to a printer by piping the ctrans and lpr commands together. For example, to send the file test.plt to hp4, you type:
The appendices which follow include some frequently needed information that can be found in the various NCAR manuals. Only excerpts are provided here to illustrate some basic features. (That is why the page numbering at the bottom has gaps.) The intent in collecting the appendices is to provide greater access to the information since we could only obtain a couple of copies of the manuals, and because each user could make notes as needed. (It is impossible to write a manual in a way to suit all users needs or understandings because each user has different knowledge and learning style.) These appendices are available for copying at the user's expense.
Appendix A: This material is reproduced from pages 25 and 64-67 from the manual for Version 2. These pages compare the old and new system plot packages, and describe what each of the routines does in the version 2 GKS. Note that version 3 altered several of these routines once again (particularly contour plotting routines), so consult the next Appendix as well.
Appendix B: This material is reproduced from pages 1-6 and 1-7 from the version 3 GKS manual. The two tables list what routines were changed between versions 2 and 3 and where to find documentation about other routines.
Appendix C: This material is reproduced from pages 3-3 through 3-10 in the version 3 GKS manual. The focus of this appendix is an overview of the various parts to the contour routines and related options. Appendix D has several examples of FORTRAN usage.
Appendix D: This material presents examples of computer code to use the version 3 to produce a pleasing contour plot. The material is reproduced from version 3 GKS manual. This manual has many more examples of FORTRAN code. These examples may be found in the DEC VMS directory DISK10:[NCARG]TEST.DIR
Appendix E: This material describes the routine PLCHHQ which replaced PWRITX for generating high quality software characters in version 3.
Appendix F: Software character set from PLCHHQ and PLOTCHAR. See the separate web page: PLCHHQ character set for complete depictions of the characters and symbols.
Appendix G: Documentation for calling the contouring routines CPCNRC and CPEZCT.
former file: \wp7docs\Courses\compute\unixgks.wpd