SCDzine
Spring 1999, Vol. 20, No. 1
H I N T

sun image GSUN: Graphics made easier in NCL

A simpler interface to NCL's graphical display capabilities. . .

Mary Haley
Mary Haley


Contents

SCDzine

Search

Article index

Subscribe

Contact us

SCD

by Mary Haley

This article is geared to current NCAR Graphics users who are using NCL to generate graphics for scientific visualization.

Are you having difficulty creating graphics with NCAR Command Language (NCL) because of unfamiliarity with object-oriented concepts? Do you have a hard time remembering how to create objects in NCL and how they relate to each other? If so, a new set of plotting functions and procedures called "Getting Started Using NCL" (GSUN) may be just the thing to help you produce better graphics, quicker.

This article:

  • Provides a brief review of NCL
  • Shows how GSUN's plotting functions, primitive procedures, and miscellaneous functions make it easier to use NCL's graphical display capabilities
  • Tells briefly how to use GSUN, providing two examples
  • Offers a short description of the GSUN documentation


NCL: A brief review

NCAR Command Language (NCL) is a programming language within NCAR Graphics software designed specifically for the analysis and visualization of data. The power and utility of NCL is evident in its capabilities for file handling, data processing, and graphical display. File handling and data processing commands in NCL are fairly straightforward and can be easily understood with basic knowledge of a programming language such as Fortran or C. (For more information on file handling and data processing commands, see "Built-in NCL functions and procedures" in the NCAR Graphics documentation.)

Graphical display in NCL is powerful and provides many options to get the plots you want -- but it requires knowledge of object-oriented concepts which some users have found difficult to understand and implement.

GSUN makes it easier to use this powerful graphical display capability.


GSUN also rises

Developed in 1998 by SCD's Fred Clare and Mary Haley, GSUN provides a simpler interface to NCL. Dennis Shea, a scientist in CGD and a heavy user of NCL, provided valuable input on the design of GSUN functions and procedures, made suggestions on how to make them useful for the scientific programming community, and provided SCD with data for creating example plots.

GSUN functions and procedures come in three categories:

  • Plotting functions for drawing contour plots, XY plots, vector plots, and streamline plots. (For more information, see "Plotting functions" in the GSUN documentation.)

  • Primitive procedures for drawing polylines, polymarkers, polygons, and text. (For more information, see "Output primitive procedures" in the GSUN documentation.)

  • Miscellaneous functions and procedures for opening a workstation, drawing a map, defining and retrieving a colormap, generating a labelbar, and putting multiple plots on a page. (For more information, see "Miscellaneous functions and procedures" in the GSUN documentation.)

Note that while the GSUN plotting functions may make plotting easier in NCL, they do not encompass the full flexibility of the plotting capabilities available in NCL. To utilize the full power of NCL, we recommend that you consult the NCL reference pages in the NCAR Graphics documentation.


How to use GSUN

You must have version 4.1 of the NCAR Graphics software package installed on your system to have access to the GSUN functions and procedures. For information on getting version 4.1, see order and price information in the NCAR Graphics documentation or send email to ncarginf@ucar.edu.

The basic steps for using GSUN to create a plot in NCL are:

  1. Load the NCL file containing the GSUN functions and procedures. (Its pathname is $NCARG_ROOT/lib/ncarg/nclex/gsun/gsn_code.ncl.)

  2. Read in your data.

  3. Process the data if necessary.

  4. Call the GSUN function gsn_open_wks to open a "workstation" on which to draw your graphics. (A "workstation" can be an NCGM file, a PostScript file, or an X11 window.)

  5. Set up an optional list of resources to customize your plot.

  6. Call the appropriate GSUN plotting function (gsn_contour, gsn_xy, gsn_vector, gsn_contour_map, and others) for generating the type of plot you want. All the GSUN plotting functions have a similar interface where the first argument is the display (workstation) on which to draw the graphics, the next argument (or two) is the data to be plotted, and the last argument is the optional list of resources generated in step 5, above.

Here are two step-by-step examples, including code and graphical output, of how to use GSUN.
  • Example 1: How to create a simple XY plot using GSUN (includes how to change the default value of a resource)

  • Example 2: How to create contour plots using GSUN


GSUN documentation available

The online GSUN documentation shows in greater detail how to use the new functions and procedures and introduces users to the basic concepts of programming in NCL. This documentation is available at http://ngwww.ucar.edu/ngdoc/ng/ug/ncl/gsun/.

The GSUN documentation contains these chapters:

  • The "Introduction" talks briefly about the three parts of NCL: file handling, data processing, and graphical display.

  • "Learning NCL by example" is the heart of the documentation, providing several detailed examples of how to use GSUN functions. Each example module contains a short description of the example, images of the graphical output, numbered NCL code used to generate the output, and a line-by-line description of the code.

  • "Basics" contains information essential to a sound understanding of NCL at a beginning level. It augments and complements the previous chapter.

  • "Going beyond the basics" gives you a more thorough understanding of NCL, including how to incorporate your own Fortran/C code into NCL, how the object-oriented paradigm fits into NCL, and how to make use of resource files.

  • "Hints and tips for using NCL" provides useful tips for using NCL and answers frequently asked questions on data processing, file handling, plotting, and documentation.

  • The "Appendix" has a detailed description of all the GSUN functions and procedures, some examples of advanced NCL scripts, and a list of URLs you may find useful in your work with NCL.


Comments, questions?

Please direct comments or questions about GSUN to Mary Haley (haley@ucar.edu) or Fred Clare (fred@ucar.edu).

NCAR Graphics is a registered trademark of the University Corporation for Atmospheric Research (UCAR). Reference to a company or product name does not imply approval or recommendation of that company or product to the exclusion of others. Copyright: 1987-1999 UCAR. The use of this software is governed by a license agreement.

rule
Contents || SCDzine || Search || Article index || Subscribe || Contact us || SCD