Chapter 2: Five quick steps for creating and viewing your plot

   Previous chapter          LLUs Home          Next chapter         Index

Overview

This chapter briefly discusses the necessary steps for creating and viewing a plot. For detailed information on step 2, please study the "Writing a graphics program" chapter. For more information on step 5, please study the "Viewing and editing your CGMs and raster images" chapter.

The steps

There are five steps required to create and view a plot:

  1. Ensure that the environment variable NCARG_ROOT is set.
  2. Write a graphics program.
  3. Compile and load the program.
  4. Execute the program.
  5. View your plot.

Step 1: Ensure that the environment variable NCARG_ROOT is set

Before you can do anything, you must make sure that you have set either NCARG_ROOT or the three environment variables NCARG_BIN, NCARG_LIB, and NCARG_INCLUDE, depending on how NCAR Graphics was installed on your system. In some cases, the installer may have set either NCARG_ROOT or NCARG_BIN, NCARG_LIB, and NCARG_INCLUDE globally so that you don't have to worry about it. To figure out if any of these variables have been set, execute:
env
A list of all the environment variables that have been set will be shown, along with their values.

If you don't have either NCARG_ROOT, or NCARG_BIN, NCARG_LIB, and NCARG_INCLUDE set, then please contact the person who installed NCAR Graphics at your site for information on how to set them.

Step 2: Write a graphics program

A quick way to write a graphics program is to choose an example that produces output similar to what you need for visualizing your data, run ncargex, and modify the resulting source code to do what you want.

"Appendix D: A pictorial guide to NCAR Graphics examples" provides grayscale prints of the example plots available via ncargex. Choose one that does something like what you want to do, then type:

ncargex example
where example is the name under the plot of your choice.

The ncargex command puts several files in your current working directory. The file example.f is the main program that you will want to modify, and the file example.ncgm is the NCAR Graphics Computer Graphics Metafile (NCGM) that is created when the example is compiled and executed. Other files that are created when you run ncargex include an executable file named example, and occasionally, a file full of support routines for the main program.

Before you modify an example program, please study the "Writing a graphics program" chapter of this guide so that you understand what the different calls do. Also, when modifying an example program, we recommend that you comment out lines of code and run the example to check the result first. You may then decide to remove some of the code that you commented out: this prevents you from removing something critical, then later finding that you have to locate and replace a deleted line.

Step 3: Compile and load the program

To make it easy to compile and load your program and the NCAR Graphics libraries, NCAR Graphics provides a command to compile and load C programs (ncargcc) and a command to compile and load Fortran programs (ncargf77).

For a C program, execute:

ncargcc example.c
Where example.c is the name of the program you want to compile.

For a Fortran program, execute:

ncargf77 example.f
Where example.f is the name of the program you want to compile.

Step 4: Execute the program

Unless you've specified otherwise when compiling and loading your program, you can run your program by executing:
a.out
When you run your program, one of two things will happen depending on the workstation type you have chosen. Either output will be displayed directly on your X Windows workstation, or an NCGM will be created. By default, NCGM files are named gmeta.

Step 5: View your plot

NCAR Graphics now offers two output options for your plots. By setting the GKS workstation type, you can make your program output plots directly to as many as 15 different X Windows on your workstation. You can also create a single NCGM file. For details on how to choose your output option, please see the section "What you need to know about GKS workstations." If you choose the X Windows output option, you will need to set the DISPLAY environment variable as shown in examples 1 and 2 below. Then your program will display directly to your workstation, or send an error message to your workstation.

If you choose to create an NCGM file, the rest of this section gives you an overview of your viewing and editing options.

To view an NCGM file, it must be translated into commands that your terminal, workstation, or printer recognizes. The translator that does this is called ctrans, and it can be accessed directly or through either a command line interface called ictrans or a graphical user interface (GUI) called idt. If you are working on a terminal or workstation that is not running X Windows, you should use ictrans. If you are working on an X terminal or a workstation running X Windows, you will probably want to use idt, although ictrans will also work.

Viewing an NCGM on a graphics terminal

The ictrans command is an interactive user interface to the ctrans translator; ictrans is the preferred tool to view an NCGM on a graphics terminal. ictrans provides random access to the frames contained in your metafile. You need to specify the graphcap to be used, and there are two ways to do this: you can either set the GRAPHCAP environment variable or specify the graphcap with the -d option on the ictrans command line. In the following examples, the C shell is used to set environment variables. Please consult the man page on the shell that you are using for instructions on how to set environment variables on your system.

If you have run ncargex example, which produces an NCGM named example.ncgm, and you are working on a Tektronix 4107 graphics terminal, you can view example.ncgm by typing either:

setenv GRAPHCAP t4107
ictrans example.ncgm
ictrans> 1p
or:
ictrans -d t4107 example.ncgm
ictrans> 1p
Typing "1p" directs the translator to plot frame 1. When the plotting is complete, a "<READY>" prompt appears; you must then press RETURN in your terminal window before a new "ictrans>" prompt will be displayed. If the example program only produces a single frame, then entering "2p" will result in an error message.

Many ictrans commands are available for interactive viewing of your metafiles. You can find out about other ictrans commands by typing the abbreviation for the help command:

ictrans> h
All ictrans commands can be abbreviated to the shortest unique string, just as the "h" above stands for "help."

To exit ictrans, type:

ictrans> q
More information about ictrans appears on the man page for ictrans and in the "Viewing and editing your NCGMs and raster images."

Viewing an NCGM with the X Window System

The image display tool idt is a Graphical User Interface (GUI) to the ctrans translator. You need to set the GRAPHCAP and DISPLAY environment variables, then you can view your NCGM. Because X11 is network-based, idt can run on one system and produce its graphics locally or on a remote system. The following two examples demonstrate each of these cases.

Example 1. Local application
Create an NCGM named example.ncgm on your local workstation (called "localstation" here) by executing ncargex example. To view it on your workstation's display, execute the following three commands:
localstation> setenv GRAPHCAP X11
localstation> setenv DISPLAY 0:0
localstation> idt example.ncgm
Example 2. Distributed application
You have an NCGM named example.ncgm on a computer called "mainframe," and you want to view it on your workstation called localstation. You may need to specify the complete domain name of your workstation on the network (host.domain). Assuming that you are logged on to a window to the remote computer named mainframe, you would execute:

mainframe> setenv GRAPHCAP X11
mainframe> setenv DISPLAY localstation.domain:0
mainframe> idt example.ncgm
Two idt windows will come up. Use the window with the "pushbutton" controls to plot your frames. Complete instructions for using idt appear in the chapter "Viewing and editing your CGMs and raster images."

In both of the preceding examples, we have set the environment variables using the C shell. If you are using a different shell, use the man page for your shell to learn how to set environment variables. If you frequently use the same type of graphics display, you can set these variables in your .login, .cshrc, or .profile file so that they are set automatically every time you log in. In example 2, the computer named localstation must have been configured to allow X11 requests from the computer named mainframe. See the man page on xhost, or consult your system administrator if necessary.

For further details about viewing and editing images, see the chapter "Viewing and editing your CGMs and raster images."

   Previous chapter          LLUs Home          Next chapter         Index