NCAR Graphics Contouring and Mapping Tutorial

Previous Chapter          Tutorial Home          Next Chapter

This tutorial manual is a learning tool for beginning and intermediate users who need to prepare NCAR Graphics programs that fill areas, draw maps, and contour data fields. It answers most questions typically raised by people who are beginning to use the Conpack, Ezmap, and Areas utilities.

Note: This tutorial assumes that you already know how to write Fortran programs, that you are working on a UNIX system so you can view NCAR Graphics man pages and access the tutorial examples via the ncargex command, and that you are acquainted with some NCAR Graphics terminology.

We highly recommend that you study chapters 1 through 4 of the NCAR Graphics Fundamentals guide before attempting to use this manual.

Design of this tutorial

This tutorial manual is a step-by-step guide to performing specific programming tasks. This tutorial is designed to lead you through specific tasks to be accomplished by your NCAR Graphics program and to explain important aspects of the software.

Each module describes a single concept or task. Most modules appear on two facing pages, so the two-page spreads you see in this manual provide all the essential information you need to understand a single concept or accomplish a single task.

The structure of the modules is consistent; this helps you focus on the material being presented. The sequence of modules leads you from learning basic information about NCAR Graphics programs to performing increasingly more complex tasks.

On a larger scale, the chapters are organized by utility: Areas, then Ezmap, then Conpack. Each chapter leads you from basic information about one utility to more complex tasks you can perform with that utility. To help you understand how the utilities work together, the Ezmap chapter incorporates some material from the Areas chapter, then the Conpack chapter integrates material from both Ezmap and Areas.

Other resources to use with this manual

Other documentation is also available to help you use NCAR Graphics: the introductory user guide NCAR Graphics Fundamentals, a full set of man pages, and programmer documents from the package developers. Examples are also provided to show you NCAR Graphics capabilities and to help you understand and use the code that produces the examples. The online version of Fundamentals and the programmer documents are provided as PostScript files on the distribution medium. Please see your site installer for them.

NCAR Graphics Fundamentals contains important information for all users: a glossary of NCAR Graphics terms, the structure of NCAR Graphics programs, strategies for learning NCAR Graphics, instructions for compiling, linking, and running programs, instructions for producing and editing output from NCAR Graphics programs, and guidelines for using the utilities.

The online man pages provide concise reference information for all user entry points, user-modifiable internal routines, parameters used in all utilities, and NCAR Graphics commands (such as ncargex). The overview man page ncargintro introduces all utilities in the package, and overview man pages for each utility introduce all routines in that utility.

Programmer documents are the software developers' reference notes; they are provided for users who want to explore the information that developers use to maintain a utility's source code.

The ncargex command allows you to access more than 250 examples, and all of them are internally documented with comments. A brief introduction to ncargex is provided under the "Code segment" heading below, and procedures for using ncargex appear in Chapter 2 "Five quick steps for creating and viewing your plot" of NCAR Graphics Fundamentals. A pictorial index to all NCAR Graphics examples is provided as Appendix D of Fundamentals.

Intro 1.1 Understanding the layout of tutorial module

Intro 1.2 Details about how information is presented in this manual

This tutorial is divided into chapters for each of the three utilities. Each chapter is divided into sections, and each section contains modules. The modules are organized as shown on the preceding two pages; most are laid out as two-page spreads so that all relevant information is available to you at a glance. Some modules fit on one page, and a few require four pages.

Reference guides throughout

Each chapter starts with a series of quick reference tables that show all user entry points and parameters for the utility. More detailed parameter descriptions appear as the final section of each chapter.

A functional outline for the utility is presented at the end of each chapter's first section and on the first page of each subsequent section. This outline shows the basic steps needed to run the utility. The steps to be discussed in that section are marked with asterisks to help you see how the concepts described in that section fit into any Fortran program using the utility.

Basic concepts explained first

If you must first understand any underlying concepts for a utility before you use it, the first section of the chapter discusses these concepts. (This includes definitions of terms and overviews of routines that control parameters.) If the utility provides a routine that allows you to quickly view a simple plot of your data, the first section also presents this.

The second section of a chapter may provide additional preliminary information. All subsequent sections then contain task-oriented modules that lead you through all steps necessary to use the utility.

Instructions for performing tasks

Each module explains a specific task, has a descriptive title, and is structured in a consistent way. The following describes the guidelines used in creating each part of a task-oriented module: this will be useful if you have a question about the way information is presented in any of these modules.

Module header, title, and introduction

The title of the module defines the concept or task that is discussed in it. The header above the title helps you see how this concept or task fits into a program that uses the utility. The text below the title briefly introduces the concept or task.

Module numbering indicates the chapter (with the two-letter utility code), the section (first number), and the module (second number, after the period). For example, module Cp 9.4 is the fourth module in the ninth section of the Conpack chapter. In some cases, multiple modules are needed to cover a group of related concepts; all such modules are grouped together with an additional number (for example, Cp 6.9.1 through Cp 6.9.4).

Graphic example

The graphic illustrates the task discussed in the module. In most modules, the graphic is produced by the example program named in the code segment.

All black-and-white graphics appear on your screen as white lines on a black background; in this manual, these examples are printed with black lines on a white background. This reversal is done so the graphics are easier to see in the manual. Most color graphics in this manual appear exactly as they do on your screen; in rare cases, a black background is changed to white for improved readability on the printed page.

The first instance of a color graphic is always printed in color. If a color graphic occurs twice in a four-page module, however, the second instance of the graphic appears in black and white.

Code segment

The code segment is an excerpt from the Fortran code that generates the graphic example; it shows how the task being explained by the module is accomplished. The line numbers before each line are only for references from the text; these numbers have nothing to do with the line numbers in the example code.

The heading "Code segment from example_name.f" gives you the name of the example file. To run the example and create the NCAR CGM (NCGM), type:

ncargex example_name

Do not type the ".f" extension; "example_name.f" denotes the file that contains the Fortran code. The ncargex command generates local copies of the example source code, compiles and links the source file(s), runs the executable, and produces an NCGM that you can examine with a translator such as idt or ictrans. More information is available from the man pages and the NCAR Graphics Fundamentals guide.

All Fortran code is printed in this manual with the Courier (typewriter) font. This monospaced type font preserves the correct relationships of Fortran columns. Any Fortran code that continues onto the next line is printed with a plus sign (+) in column 6 of the continued line.

Synopsis

This line of code demonstrates the calling sequence of the routines or parameters discussed in the module. The synopsis may contain more than one line of code.

Arguments

This part of the module is a detailed description of every element in the synopsis. This section typically describes each argument to or parameter for the Fortran routine(s) in the synopsis.

Two important pieces of information follow the argument name: its Fortran type and its function in the program. When parameters are listed under the Arguments heading, only their Fortran type is given.

Fortran types include INTEGER, REAL, and CHARACTER, plus arrays of these types (the dimension of any array is always indicated). The argument's function in the program may be as input (the user supplies a value for the argument), output (the routine returns information to the user or the program in the argument), workspace (a scratch array for the routines to use in manipulating information, but that the user must declare), or as a subroutine (a special-purpose routine that the user typically writes or modifies to produce a desired result).

In parameter descriptions, uppercase letters show how the characters that comprise the parameter name are derived. Uppercase letters are also used in this way in the tables of parameters at the beginning and end of each chapter. This is not done for argument names, although the argument names are often derived in a similar way.

Wherever it is appropriate, specific values and ranges of values are explained in text that is indented from the text describing arguments and parameters.

Characters used as variables to represent a number (n or m for example) are printed in italics.

Discussion

This part of a module provides a line-by-line analysis of how the code segment functions in the program. The Discussion may also include other useful information such as common mistakes and how to avoid them, frequently seen error messages and the situations in which they occur, and general cautions.

All references to example names, filenames, and commands are printed with bold characters.

Exercises

These are directions that encourage users to apply and explore the concepts and tasks presented in this module. If you have trouble getting the desired results, please contact your site representative.

Previous Chapter          Tutorial Home          Next Chapter