 LLUs Home                                      Next chapter

Acknowledgments

Authors: Adrianne Middleton-Link, Dave Kennison, Fred Clare, Bob Lackman, Tim Scheitlin, John Clyne, Jeff Kuehn, Peter 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: Tom Parker, Ken Hansen, Pete Morreale, Jeff Kuehn, Bob Lackman, Fred Clare, John Clyne, and Mary Haley.

Thanks also to 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).

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 netdcf 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 scdinfo@ncar.ucar.edu or

University Corporation for Atmospheric Research

SCD/NCAR Graphics Orders

P.O. Box 3000

Boulder, CO 80307-3000 (USA)

This documentation is subject to the terms and conditions specified in a valid, executed License Agreement between Licensee and Licensor.

Published by: National Center for Atmospheric Research, Scientific Computing Division, P.O. Box 3000, Boulder, CO 803073000. 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.

Trademarks: 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.

Printed on recycled paper (25% post-consumer waste).

Conventions used in this document

UNIX

Command names, options, filenames, pathnames, directories, and other items that must be typed as shown are printed in bold letters. Examples:

man ls

For more information about the ls command, see its man page.
Variables where you provide the substitution are shown in bold italic letters. Examples:

mv filename1 filename2

At the prompt, type your login_id.
The \\ (backslash) followed by pressing RETURN when you are entering a command allows you to continue the command on the next line. In UNIX, a \\ escapes the next character.

Fortran

Fortran programs, shell scripts, and screen displays are shown in Courier ("typewriter") font.

      CALL FLMHDR (35)

General

You must press RETURN after each command, but the RETURN is not shown in the document, except when required for clarity.
Keystrokes that must be pressed simultaneously are linked by a hyphen, with the modifier key indicated by capital letters before the hyphen. Example:

To finish the file, enter CONTROLd at the beginning of a new line.

Preface vii

Welcome to NCAR Graphics vii

History of graphics at NCAR vii

How to use this documentation set viii

How to get consulting help ix

Chapter 1: Overview of functionality

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

Overview 7

The steps 7

Step 1: Ensure that the environment variable NCARG_ROOT is set 7

Step 2: Write a graphics program 8

Step 3: Compile and load the program 8

Step 4: Execute the program 9

Step 5: View your plot 9

Viewing an NCGM on a graphics terminal 9

Viewing an NCGM with the X Window System 10

Chapter 3: Writing a graphics program

The structure of NCAR Graphics 13

Structure of a Fortran program 14

Example graphics program 14

Opening GKS and activating workstations 15

GKS settings 16

Normalization transformations (SET) 16

Graphics code 18

Ending the plot or frame 18

Deactivating workstations and closing GKS 19

Writing a C program 19

Chapter 4: Viewing and editing your CGMs and raster images

Introduction 21

Environment 22

Search path 22

Metafile translators 22

X11 users 23

Translator fonts 23

Getting started --- Translating metafiles with ctrans 24

Viewing your NCGM 24

Printing your NCGM 25

Examining the contents of your NCGM 25

Controlling NCGM translation 26

Interactive metafile translation 27

Interactive ctrans (ictrans) 27

Random access 28

Saving a metafile 28

Printing metafiles 29

Zooming in on your plot 30

Batch processing 30

Interactive display tool --- idt 30

Translating metafiles (idt) 31

The idt control panel 32

The display panel 33

idt segments <start segment> <stop segment> 34

Continuous playing <loop> 34

Printing frames <print> 34

Saving metafiles <save> 35

Enlarging a plot <zoom> 35

Desktop animation <animate> 35

Terminating a plotting session <done> 37

The idt file browser 37

Metafile editing 39

The med program 39

Listing buffer contents (print) 40

Writing frames to a file (write) 40

Appending frames to a file (append) 40

Reading a file into the buffer (read) 40

Splitting a large metafile (split) 41

Copying frames (copy) 41

Deleting frames (delete) 41

Moving frames (move) 42

Compositing frames (merge) 42

Editing a new file (edit) 42

Obtaining help (help) 43

Batch processing 43

Raster imagery 44

Raster file formats 44

Raster utilities 44

Viewing raster files (rasview) 45

Raster file format conversion, concatenation, and resizing (rascat) 46

Listing raster files (rasls) 47

Color palettes (rasgetpal) 47

Textual color palette format 48

Examples of textual color palettes 48

Splitting multiframe raster files into single-frame raster files
(rassplit) 49

Interoperability with other tools 50

Non-NCAR Computer Graphics Metafiles 50

Rasterizing NCGMs 50

Chapter 5: Introducing the tutorial chapters

Understanding the layout of tutorial modules 54

Details about how tutorial information is presented 56

Chapter 6: What you need to know about GKS workstations

Table of GKS workstation-related user entry points 59

Opening GKS, opening and activating workstations 60

Deactivating and closing workstations, closing GKS 62

Making sure things are current 64

Controlling pictures 66

Using GKS segments, the Gflash utility 68

Changing an NCGM filename 70

Putting it all together 72

Chapter 7: Color tables and color mapping systems

Table of color table and color mapping user entry points 81

Color tables 82

Converting between HLS and RGB 84

Converting between HSV and RGB 86

Converting between YIQ and RGB 88

Chapter 8: Coordinate systems in NCAR Graphics

Table of coordinate system user entry points 93

Definitions 94

Normalization transformations 96

Restoring the normalization transformation 98

Chapter 9: Drawing points, markers, and filled dots

User entry points for drawing markers 103

Creating markers with GKS routines 104

Creating dots with SPPS routines 106

Creating markers connected with lines in SPPS 108

Creating filled circular dots 110

Chapter 10: Drawing lines and curves

Table of line and curve-drawing user entry points 115

Table of line and curve-drawing parameters 116

Line and curve-drawing parameters: What they do and how to use them 117

Drawing lines and curves with GKS routines 118

Drawing lines and curves with SPPS routines 120

Drawing lines and curves with SPPS routines 122

Drawing lines and curves with high level routines 124

Setting the dash pattern of lines and curves 126

Smoothing curves and removing crowded lines 128

Changing line color 130

Changing line width 132

Chapter 11: Drawing text and symbols

Table of text-drawing user entry points 136

Table of text-drawing parameters 138

Text-drawing parameters: What they do and how to use them 140

Drawing text with GKS routines 142

Drawing text with the PLCHLQ routine 144

Drawing text with the PLCHHQ routine 146

Setting color and other PLCHHQ text characteristics 150

Drawing weather symbols with the NGWSYM routine 152

Complex character set 154

Duplex character set 155

Fontcap databases 1-20 156

Fontcap databases 21-137 157

Chapter 12: Portable raster images (cell arrays)

Table of cell array user entry points 161

Creating cell arrays 162

Chapter 13: Area filling with GKS and Softfill

Table of user entry points for area filling 166

Table of Softfill parameters 167

Filling areas 168

Softfill parameters: What they do and how to use them 170

Pattern-filling areas in NDCs 172

Pattern-filling areas in world coordinates 174

Solid fills and pattern-fill substitutes 176

Choosing how fill is done 180

Controlling fill lines 182

Filling with dots or characters 184

Chapter 14: Drawing label bars

Table of Labelbar user entry points 188

Table of Labelbar parameters 189

Drawing the label bar 190

Advanced filling of label bars 194

Setting and retrieving Labelbar parameters 196

Setting Labelbar parameters 198

Chapter 15: Drawing axes, perimeters, and grids

Table of Gridall user entry points 202

Table of Gridall parameters 203

Drawing grids, perimeters, and axes with GRIDAL 204

Labeling grids, perimeters, and axes 206

Setting grid, perimeter, and axis color 208

Chapter 16: Drawing graphs with Autograph

Table of Autograph user entry points 212

Drawing one curve per plot with EZY 214

Drawing one curve per plot with ordered pairs using EZXY 216

Drawing multiple curves per plot with EZMY 218

Drawing multiple curves with ordered pairs using EZMXY 220

Changing the axis text labels 222

Changing the axis minimum and maximum values 224

Differentiating multiple curves with a dash pattern 226

Changing the curve colors 228

Changing the axis colors 230

Changing the info label colors 232

Chapter 17: Creating bar charts using the Histogram utility

Table of Histogram user entry points 236

Table of Histogram parameters 237

Generating a histogram 238

Comparing two histograms 242

Four histograms on a frame 244

Chapter 18: Field flows

Table of Vectors user entry points 248

Table of Streamlines user entry points 249

Table of Vectors parameters 250

Table of Streamlines parameters 253

Using parameters in Vectors and Streamlines 255

Creating simple field flow plots 257

A simple plot using Vectors 258

A simple plot using Streamlines 260

Exploring the field flow utilities 263

Displaying vectors overlaying an Ezmap projection 264

Modifying the appearance of a Vector plot 266

Coloring a Vector plot based on scalar array data 268

Masked Streamlines over contour lines and Ezmap 270

Mapping to polar coordinates in Streamlines 272

A polar plot using Vectors, Conpack, and Ezmap 274

Chapter 19: Drawing 3-D objects

Table of Threed user entry points 279

Defining a 3-D to 2-D transformation 280

Drawing a perimeter 282

Changing the lengths of tick marks on a perimeter 284

Drawing points 286

Drawing straight-line segments and curves with FRST3 and VECT3 288

Drawing straight-line segments with LINE3 290

Drawing curves with CURVE3 292

Drawing curves with fences, using FENCE3 294

Drawing character strings (labels) 296

Overlaying output from Surface on a Threed plot 298

Chapter 20: Drawing surfaces and isosurfaces

Table of isosurface-drawing user entry points 302

Table of Isosurface-drawing parameters 303

Table of surface-drawing parameters 304

Isosurface parameters: What they do and how to use them 305

Drawing pictures with the EZISOS routine 306

Drawing pictures with the ISOSRF routine 308

Drawing text in 3-space when using ISOSRF 312

Drawing pictures with the EZSRFC routine 314

Drawing pictures with the SRFACE routine 316

Drawing text in 3-space when using SRFACE 318

Chapter 21: Movie titles

Table of Scrolled_title user entry points 322

Table of Scrolled_title parameters 323

Table of high-quality fonts available for titling 325

Generating high-quality titles 326

Glossary 331

Appendix A: The use of X/Y coordinates in NCAR Graphics 337

Introduction 337

Required abstractions: Plotter frame, world and user coordinates 337

X/Y coordinates in calls to GKS routines (world coordinates) 338

X/Y coordinates in calls to most NCAR Graphics routines
(user coordinates) 340

The routine SET 343

The routine GETSET 344

Other coordinate systems used in NCAR Graphics 345

The SPPS conversion routines 346

An example illustrating the effects of MI and LS 354

Appendix B: UNIX environment variables 361

Appendix C: User entry points and functions 363

The Areas utility 363

The Autograph utility 363

The Bivar utility 366

The Colconv utility 366

The Conpack utility 367

The Conran_family utility 369

The Dashline utility 370

The Ezmap utility 370

The Gflash utility 373

The GKS-0A Fortran library 374

The GKS-0A C library 379

The Gridall utility 384

The Histogram utility 386

The Isosurface utility 386

The Labelbar utility 387

The Ngmisc utility 388

The Plotchar utility 388

The Scrolled_title utility 389

The Softfill utility 390

The SPPS library 391

The Streamlines utility 392

The Surface utility 394

The Threed utility 394

The Vectors utility 395

Man page entries for NCAR Graphics commands and auxiliary support programs 396

Appendix D: Pictorial index to ncargex 399

Index 401

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 both in hardcopy and electronic form. To order hardcopy, please contact NCAR Graphics ordering information at (303) 497-1201 or scdinfo@ncar.ucar.edu or University Corporation for Atmospheric Research, SCD/NCAR Graphics orders, P.O. Box 3000, Boulder, CO 80307-3000 (USA). The online version is available on the distribution
as a PostScript file. Please see your site installer for it.

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

NCAR Graphics

Fundamentals

UNIX Version 4.0