LLUs Home                                      Next chapter  

NCAR Graphics

Fundamentals

UNIX Version 4.0

Document Version 1.0

July 1995

Acknowledgments

Authors: Adrianne Middleton-Link, Dave Kennison, Fred Clare, Bob Lackman, Tim Scheitlin, John Clyne, Jeff Kuehn, Pete Morreale, Dave Brown

Technical writer/editors: Juli Rew, Nancy Dawson, Brian Bevirt

Production: Christine Guzy, Valeri Hart, Jacque Marshall, Janie Young

Special thanks to the following technical reviewers: Dave Kennison, Tim Scheitlin, Tom Parker, Ken Hansen, Pete Morreale, Jeff Kuehn, Bob Lackman, Fred Clare, John Clyne, and Mary Haley.

Thanks also to Jeff Kuehn and Sally Haerer for helping to organize this project and Brian Bevirt for his explanation of the design principles used in the tutorial modules of this manual (Chapter 5).

About the cover

Four NCAR Graphics utilities cooperate to produce the cover graphic using data originating from the U.S. National Meteorological Center. Ezmap creates the polar stereographic map projection and overlying map grid. Conpack draws the contour lines representing surface pressure at mean sea level, and Vectors renders the ground-level wind velocity vectors. Surface pressure also determines the color of the vectors, with red representing the highs, yellow the middle values, and green the lows. The program uses the Areas utility in two ways: first to allow Ezmap to solid fill the oceans and land masses, and then to create an area map that permits the map grid, the contour lines, and the vectors to be masked around the contour label boxes.

The data represent a 24-hour forecast extracted from the National Meteorological Center's Global Product Set for March 13, 1993, at 1200 hours. The National Weather Service's Numerical Product Service broadcasts the data over satellite feed; Unidata's Local Data Manager receives the transmissions and converts the raw data to netcdf format. A prototype version of NCAR Graphics Command Language was used to extract one level and timestep from the netcdf files into a single data file readable by the NCAR Graphics program.

The plot shows most of the Northern Hemisphere during one forecast timestep. The extreme low pressure at the right hand edge of the picture (962.74 hectopascals) represents the center of the severe snow storm that pummelled the East Coast of North America in March 1993. It is interesting to note the other storm of similar shape and intensity, occurring simultaneously at about the same latitude off the eastern coast of Asia. With NCAR Graphics installed on a UNIX system, you can compile and run the code that produced this plot by executing the command:

ncargex fcover

For ordering information, please contact NCAR Graphics ordering information at (303) 497-1201 or ncarginf@ncar.ucar.edu or:

University Corporation for Atmospheric Research
SCD/NCAR Graphics Orders
P.O. Box 3000
Boulder, CO 80307-3000 (USA)

Copyright

Copyright © 1987-1999 University Corporation for Atmospheric Research
The use of this Software is governed by a License Agreement.

Trademarks

NCAR Graphics is a registered trademark of the University Corporation for Atmospheric Research.

All brand and product names are trademarks or registered trademarks of their respective holders. Reference to a company or product name does not imply approval or recommendation of that company or product to the exclusion of others.

Published by: National Center for Atmospheric Research, Scientific Computing Division, P.O. Box 3000, Boulder, CO 80307-3000. The National Center for Atmospheric Research is operated by the University Corporation for Atmospheric Research and is sponsored by the National Science Foundation. Any opinions, findings, and conclusions or recommendations expressed in this publication are those of the authors and do not necessarily reflect the views of the National Science Foundation.

Conventions used in this document

UNIX

Fortran

      CALL FLMHDR (35)

General

Contents

Preface
Welcome to NCAR Graphics
History of graphics at NCAR
How to use this documentation set
How to get consulting help
Chapter 1: Overview of functionality
Low level utilities
UNIX command tools
Chapter 2: Five quick steps for creating and viewing your plot
Overview
The steps
Step 1: Ensure that the environment variable NCARG_ROOT is set
Step 2: Write a graphics program
Step 3: Compile and load the program
Step 4: Execute the program
Step 5: View your plot
Viewing an NCGM on a graphics terminal
Viewing an NCGM with the X Window System
Chapter 3: Writing a graphics program
The structure of NCAR Graphics
Structure of a Fortran program
Example graphics program
Opening GKS and activating workstations
GKS settings
Normalization transformations (SET)
Graphics code
Ending the plot or frame
Deactivating workstations and closing GKS
Writing a C program
Chapter 4: Viewing and editing your CGMs and raster images
Introduction
Environment
Search path
Metafile translators
X11 users
Translator fonts
Getting started --- Translating metafiles with ctrans
Viewing your NCGM
Printing your NCGM
Examining the contents of your NCGM
Controlling NCGM translation
Interactive metafile translation
Interactive ctrans (ictrans)
Random access
Saving a metafile
Printing metafiles
Zooming in on your plot
Batch processing
Interactive display tool --- idt
Translating metafiles (idt)
The idt control panel
The display panel
idt segments <start segment> <stop segment>
Continuous playing <loop>
Printing frames <print>
Saving metafiles <save>
Enlarging a plot <zoom>
Desktop animation <animate>
Terminating a plotting session <done>
The idt file browser
Metafile editing
The med program
Listing buffer contents (print)
Writing frames to a file (write)
Appending frames to a file (append)
Reading a file into the buffer (read)
Splitting a large metafile (split)
Copying frames (copy)
Deleting frames (delete)
Moving frames (move)
Compositing frames (merge)
Editing a new file (edit)
Obtaining help (help)
Batch processing
Raster imagery
Raster file formats
Raster utilities
Viewing raster files (rasview)
Raster file format conversion, concatenation, and resizing (rascat)
Listing raster files (rasls)
Color palettes (rasgetpal)
Textual color palette format
Examples of textual color palettes
Splitting multiframe raster files into single-frame raster(rassplit)
Interoperability with other tools
Non-NCAR Computer Graphics Metafiles
Rasterizing NCGMs
Chapter 5: Introducing the tutorial chapters
Understanding the layout of tutorial modules
Details about how tutorial information is presented
Chapter 6: What you need to know about GKS
Table of GKS workstation-related user entry points
Opening GKS, opening and activating workstations
Deactivating and closing workstations, closing GKS
Making sure things are current
Controlling pictures
Using GKS segments, the Gflash utility
Changing an NCGM filename
Putting it all together
Chapter 7: Color tables and color mapping systems
Table of color table and color mapping user entry points
Color tables
Converting between HLS and RGB
Converting between HSV and RGB
Converting between YIQ and RGB
Chapter 8: Coordinate systems in NCAR Graphics
Table of coordinate system user entry points
Definitions
Normalization transformations
Restoring the normalization transformation
Chapter 9: Drawing points, markers, and filled dots
User entry points for drawing markers
Creating markers with GKS routines
Creating dots with SPPS routines
Creating markers connected with lines in SPPS
Creating filled circular dots
Chapter 10: Drawing lines and curves
Table of line and curve-drawing user entry points
Table of line and curve-drawing parameters
Line and curve-drawing parameters: What they do and how to use them
Drawing lines and curves with GKS routines
Drawing lines and curves with SPPS routines
Drawing lines and curves with SPPS routines
Drawing lines and curves with high level routines
Setting the dash pattern of lines and curves
Smoothing curves and removing crowded lines
Changing line color
Changing line width
Chapter 11: Drawing text and symbols
Table of text-drawing user entry points
Table of text-drawing parameters
Text-drawing parameters: What they do and how to use them
Drawing text with GKS routines
Drawing text with the PLCHLQ routine
Drawing text with the PLCHHQ routine
Setting color and other PLCHHQ text characteristics
Drawing weather symbols with the NGWSYM routine
Complex character set
Duplex character set
Fontcap databases 1-20
Fontcap databases 21-137
Chapter 12: Portable raster images (cell arrays)
Table of cell array user entry points
Creating cell arrays
Chapter 13: Area filling with GKS and Softfill
Table of user entry points for area filling
Table of Softfill parameters
Filling areas
Softfill parameters: What they do and how to use them
Pattern-filling areas in NDCs
Pattern-filling areas in world coordinates
Solid fills and pattern-fill substitutes
Choosing how fill is done
Controlling fill lines
Filling with dots or characters
Chapter 14: Drawing label bars
Table of Labelbar user entry points
Table of Labelbar parameters
Drawing the label bar
Advanced filling of label bars
Setting and retrieving Labelbar parameters
Setting Labelbar parameters
Chapter 15: Drawing axes, perimeters, and grids
Table of Gridall user entry points
Table of Gridall parameters
Drawing grids, perimeters, and axes with GRIDAL
Labeling grids, perimeters, and axes
Setting grid, perimeter, and axis color
Chapter 16: Drawing graphs with Autograph
Table of Autograph user entry points
Drawing one curve per plot with EZY
Drawing one curve per plot with ordered pairs using EZXY
Drawing multiple curves per plot with EZMY
Drawing multiple curves with ordered pairs using EZMXY
Changing the axis text labels
Changing the axis minimum and maximum values
Differentiating multiple curves with a dash pattern
Changing the curve colors
Changing the axis colors
Changing the info label colors
Chapter 17: Creating bar charts using the Histogram utility
Table of Histogram user entry points
Table of Histogram parameters
Generating a histogram
Comparing two histograms
Four histograms on a frame
Chapter 18: Field flows
Table of Vectors user entry points
Table of Streamlines user entry points
Table of Vectors parameters
Table of Streamlines parameters
Using parameters in Vectors and Streamlines
Creating simple field flow plots
A simple plot using Vectors
A simple plot using Streamlines
Exploring the field flow utilities
Displaying vectors overlaying an Ezmap projection
Modifying the appearance of a Vector plot
Coloring a Vector plot based on scalar array data
Masked Streamlines over contour lines and Ezmap
Mapping to polar coordinates in Streamlines
A polar plot using Vectors, Conpack, and Ezmap
Chapter 19: Drawing 3-D objects
Table of Threed user entry points
Defining a 3-D to 2-D transformation
Drawing a perimeter
Changing the lengths of tick marks on a perimeter
Drawing points
Drawing straight-line segments and curves with FRST3 and VECT3
Drawing straight-line segments with LINE3
Drawing curves with CURVE3
Drawing curves with fences, using FENCE3
Drawing character strings (labels)
Overlaying output from Surface on a Threed plot
Chapter 20: Drawing surfaces and isosurfaces
Table of isosurface-drawing user entry points
Table of Isosurface-drawing parameters
Table of surface-drawing parameters
Isosurface parameters: What they do and how to use them
Drawing pictures with the EZISOS routine
Drawing pictures with the ISOSRF routine
Drawing text in 3-space when using ISOSRF
Drawing pictures with the EZSRFC routine
Drawing pictures with the SRFACE routine
Drawing text in 3-space when using SRFACE
Chapter 21: Movie titles
Table of Scrolled_title user entry points
Table of Scrolled_title parameters
Table of high-quality fonts available for titling
Generating high-quality titles
Glossary
Appendix A: The use of X/Y coordinates in NCAR Graphics
Introduction
Required abstractions: Plotter frame, world and user coordinates
X/Y coordinates in calls to GKS routines (world coordinates)
X/Y coordinates in calls to most NCAR Graphics (user coordinates)
The routine SET
The routine GETSET
Other coordinate systems used in NCAR Graphics
The SPPS conversion routines
An example illustrating the effects of MI and LS
Appendix B: UNIX environment variables
Appendix C: User entry points and functions
The Areas utility
The Autograph utility
The Bivar utility
The Colconv utility
The Conpack utility
The Conran_family utility
The Dashline utility
The Ezmap utility
The Gflash utility
The GKS-0A Fortran library
The GKS-0A C library
The Gridall utility
The Histogram utility
The Isosurface utility
The Labelbar utility
The Ngmisc utility
The Plotchar utility
The Scrolled_title utility
The Softfill utility
The SPPS library
The Streamlines utility
The Surface utility
The Threed utility
The Vectors utility
Man page entries for NCAR Graphics commands and auxiliary support programs
Appendix D: Pictorial index to ncargex
Index

Preface

Welcome to NCAR Graphics

NCAR Graphics has been distributed to about 1,500 sites around the world. At its heart lie over two dozen high-level Fortran-callable utilities for contouring, mapping, drawing field flows, drawing surfaces, drawing histograms, drawing X/Y plots, labeling, and more. The package includes an ANSI/ISO standard version of GKS, written in FORTRAN 77. Currently two graphics output options are included: a device-independent private encoding of the ANSI/ISO Computer Graphics Metafile (CGM) standard and X11 commands. Recent improvements in NCAR Graphics include more color options and a raster viewing library that allows you to translate between various CGM and raster formats.

History of graphics at NCAR

Since NCAR's inception as a national research center in the early 1960s, graphics has played an important role in supercomputing for the atmospheric sciences. Early on, the Computing Facility of NCAR, now the Scientific Computing Division (SCD), generated a low-level collection of routines to draw lines, curves, and dashed-line patterns called the NCAR System Plot Package. This package was later replaced with some higher level routines now known as SPPS and a GKS package.

By the 1970s, NCAR scientists and SCD staff had developed several higher level graphics utilities, which were integrated into a graphics package that could be distributed throughout the scientific community.

In the early 1980s, graphics and programming language standards had gained wide acceptance, so NCAR Graphics utilities were converted to FORTRAN 77, the metafile was based on a private encoding of the CGM standard, and utilities were moved to depend on the GKS standard.

Since that time, the functionality of NCAR Graphics has been growing: it now contains new utilities, new viewing capabilities, and a variety of translators and filters for the numerous standard file formats. In the next few years, we plan to install an interactive package over the existing FORTRAN 77 interface to allow scientists to modify graphics interactively and study their data as the data are generated.

How to use this documentation set

To provide improved information for users, NCAR Graphics documentation has changed immensely since Version 3.1. This section lists document types, describes what to expect in each type of document, specifies titles of documents in each category, and tells how you can obtain copies of each document.

NCAR Graphics Fundamentals

This user guide, NCAR Graphics Fundamentals, Unix Version 4.0, is designed to get you up and running as fast as possible. It contains information about creating and viewing graphics. It also provides short tutorials on how to use the basic functionality of each NCAR Graphics utility. This document is designed to be used with the NCAR Graphics Contouring and Mapping Tutorial.

NCAR Graphics Fundamentals, Unix Version 4.0 is available as PostScript file. To get the PostScript file, please contact your NCAR Graphics site representative or installer.

NCAR Graphics Contouring and Mapping Tutorial

The NCAR Graphics Contouring and Mapping Tutorial is a step-by-step guide to the important functionality of the contouring and geographic mapping utilities. This guide also covers Areas, an area-processing utility that allows you to fill regions, draw masked lines, and perform other useful functions. The NCAR Graphics Contouring and Mapping Tutorial requires basic Fortran program-writing skills and knowledge of how to generate and view graphics. Information about generating and viewing graphics appears in this guide, NCAR Graphics Fundamentals, Unix Version 4.0.

Programmer documents and other reference documents

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. They are organized by utility or function and assume that readers have a strong background in NCAR Graphics programming.

Online man pages

The man pages have been completely redesigned and rewritten. There is now a short (one to six screens) man page for each utility in NCAR Graphics, each utility's set of parameters (if applicable), each user entry point, and each user-modifiable internal routine. These man pages are the most current documentation available for NCAR Graphics because they will be updated with each software release. You can access a man page at any time by executing:

man routine
where routine is the name, in lowercase letters, of the routine (or utility, or a utility's set of parameters) for which you need information. If you have used NCAR Graphics in the past, you need to note the new spelling of some utility names. To avoid confusion between the utility and the driver routine of the same name, we have changed the spelling of the utility name where both of these were formerly identical.

How to get consulting help

If you have questions about using NCAR Graphics, contact your NCAR Graphics site representative. If you do not know who your site representative is and cannot find out from other users or the package installer at your site, you can call the NCAR Graphics Information Line at (303) 497-1201 to obtain the name of your representative. In its sole discretion, NCAR provides limited consulting support on usage and installation on an "as available" basis only. (Please refer to your Software License Agreement for a complete definition of "support.")

 LLUs Home                            Next chapter