DISSPLA to NCAR Transition Guide

Introduction

Both DISSPLA and NCAR are rich and complicated subroutine call libraries. This transition guide assumes you have familiarity with DISSPLA but that you have not used NCAR extensively. If you are new to using NCAR, check out the NCAR documentation Due to the size and richness of DISSPLA and NCAR this transition guide does not attempt to be complete on a detailed level. Instead, a rough overview of each package is given in the context of comparisons and contrasts on a functional level followed by specific low level equivalencies (where they exist) for a core set of procedures/routines. This core set of routines include routines for initialization and termination, coordinate systems, miscellaneous control, grids and labels, text pl! otting, lines and markers, and contouring. Included in these sections are tables with specific routine equivalencies and code fragments demonstrating the concepts using NCAR.

Overview & Comparison of DISSPLA & NCAR

These two packages are examples of two things, which are "the same only different". In most cases, they can do equivalent things but it different (sometimes very different) ways. There are two major, minor differences. DISSPLA ultimately defines its coordinates in terms of physical units (e.g. inches) while NCAR defines everything in terms of a unit box and the conversion to physical units is done implicitly or by postprocessing tools (e.g. ctrans). This also manifests itself in many of the arguments passed to DISSPLA routines (i.e. they're in inches). The other difference is that DISSPLA tends to do have separate functions for many things with NCAR has one function with input variables you use to select the action or a number of internal variables you can set via separate "set" calls.

Basically, both DISSPLA and NCAR are used as follows:

1. Get an output device open and initialized.
2. Set up the plotting area and axes (e.g. where to plot, the coordinate system).
3. Draw lines, curves, plots, text, etc. in the plotting area.
4. Close the output device.

Step 1 is complex because of the number of output devices that each package supports and the variety of options possible in each case. Step 2 and 3 are complex because of all the ways users would like to view their data. Should the axes be linear or logarithmic? What is being plotted (e.g. functions, relations, contours)? Will where need to be additional text? The list goes on and on. Step 4 is straightforward.

Both DISSPLA and NCAR provide routines for:

• Opening and initializing output devices
• Setting up plotting areas and axes
• Drawing lines and curves
• Drawing text and symbols
• Graphing data (line graphs, histograms, etc.) and producing contours
• Shading/Area filling
• 3D function/object drawing
• Drawing world maps

In addition to this, DISSPLA has the capability to do "3D object rendering". NCAR does not have this capability. On the other hand, NCAR can produce field flows, isosurfaces (3D contours), and movies. Refer to the NCAR tutorials and documentation for more details about these additional capabilities.

The remainder of this guide will discuss in detail the more elementary parts of DISSPLA and NCAR. This will cover opening and initializing the output device, setting up the plotting area and axes, drawing various things in plotting area (e.g. lines, curves, plots, text), and closing the output device. To convert codes, which use a more complex set of DISSPLA routines, please refer to the DISSPLA and NCAR documentation.

Detailed Documentation of Basic Functionality

Opening, Initializing, and Closing Output Devices/Workstations

The way DISSPLA and NCAR are initialized and how you define the plotting device are similar. DISSPLA calls the devices you plot to output devices while NCAR calls them workstations. DISSPLA used a separate subroutine call for specifying and initializing each device, whereas NCAR specifies the device by a number within the "open" workstation routine. Refer to the DISSPLA and NCAR documentation for the specific output device/workstation designations and initialization options. 

The order of the subroutine calls to open, initialize, and close NCAR are important. The minimum calls necessary are:

	call gopks (ier, idum)
	call gopwk (iwkid, iconid, iwktype)
	call gacwk (iwkid)

		< graphics calls >

	call gdawk (iwkid)
	call gclwk (iwkid)
	call gclks

Here are two ways to change the name of the file that NCAR will be creating. The first is the easiest to do and change. When the environment variable NCARG_GKS_OUTPUT is defined, NCAR will use this filename when creating the CGM. For example,

	% setenv NCARG_GKS_OUTPUT mycgm.1 

The other way is within your Fortran code, before you open GKS (gopks) and the workstation (gopwk):

	character*80 fname, cdum
	fname = "mycgm.1"
	call gesc (-1391, 1, fname, 1, 1, cdum)
        call gopks (…)
        call gopwk (…) 

Plotting Areas and Axes

These routines set up the coordinate system for all the plotting discussed in the next section. In both DISSPLA and NCAR provide a rich set of options. Here some of the basic possibilities are listed.  The result of using the NCAR routines will be similar to using the DISSPLA routines. To get closer or equivalent output, refer to the detailed DISSPLA and NCAR documentation.

Grid, Label, and Text Routines

NCAR has at least two ways to produce a grid, ticks, labels, etc. The first method used the features of NCAR called "Autograph". This method is recommended because it best matches the capabilities of DISSPLA, and is the easiest to use. Autograph also has the capability to draw complete line graphs. We are not recommended using "Autograph" for drawing lines to DISSPLA users because the DASHPACK routines better support curve smoothing. "Better" here means that you do not need to change the libraries you load, and smoothing is turned off and on using a flag.

The second method would be to use the grid routines in NCAR, e.g., GRIDAL. These routines have a lot of flexibility, but you need to provide more information. If you are interested in using these routines, see "man gridal" and "man gridall_params".

In the case of drawing text both DISSPLA and NCAR again off a rich set of options, fonts, etc. In the table below a very basic set of text drawing options are given. See the documentation for DISSPLA and NCAR for more information.

To create a grid with axis, ticks, and tick labels without drawing lines and axis titles, do:

c	specifies no frame advance after the call to ezxmy so you can add your curves,
c	contours, etc.
	call agseti ('frame.', 2)
c	don't have ezxmy draw the curves nor change the limits of the data defined by
c	the call to set.
	call agseti ('SET.', -4)
c	I don't think the next calls are needed because of the previous call, but I do
c	it for completeness.
	data_x(1) = xmin	! set the values of data_x and data_y to the limits of 
	data_x(2) = xmax	! your data, defined in the call to set.
	data_y(1) = ymin
	data_y(2) = ymax
c	suppress x and y axis titles, NOTE that the call order is critical.
	call agsetc ('LABEL/NAME.', 'B')	! x axis
	call agseti ('LABEL/SUPPRESSION FLAG.', 1)
	call agsetc ('LABEL/NAME.', 'L')	! y axis
	call agseti ('LABEL/SUPPRESSION FLAG.', 1)
c	draw grid, also suppressing the graph title
	call ezmxy (data_x, data_y, 1, 1, 1, '')

To have the titles plotted (x and y axis titles, and graph titles) do:

	call agseti ('frame.', 2)
	call agseti ('SET.', -4)
c	I don't think the next calls are needed because of the previous call, but I do
c	it for completeness.
	data_x(1) = xmin	! set the values of data_x and data_y to the limits 
	data_x(2) = xmax	! of your data, defined in the call to set.
	data_y(1) = ymin
	data_y(2) = ymax
c	specify the x and y axis titles, NOTE that the call order is critical.
	call agsetc ('LABEL/NAME.', 'B')	! x axis
	call agseti ('LINE/NUMBER.', -100)
	call agsetr ('LIN/CH.', .03)		! increase the size of the characters
	call agseti ('LINE/TEXT.', xlabel)	! xlabel is a character string
	call agsetc ('LABEL/NAME.', 'L')	! y axis
	call agseti ('LINE/NUMBER.', 100)
	call agsetr ('LIN/CH.', .03)		! increase the size of the characters
	call agseti ('LINE/TEXT.', ylabel)	! ylabel is a character string 
c	draw grid with the graph title
	call ezmxy (data_x, data_y, 1, 1, 1, 'My Title')

Line and Marker Routines

By changing parameters, DISSPLA could plot lines, markers, and disjoint lines with or without smoothing. NCAR has a more than one way to draw lines and markers. The examples below show how to use the DASHPACK routines in NCAR. These routines are recommended over curve and curved because smoothing can be done without loading anything special, and because parameters can be set through subroutine calls. Both DISSPLA and NCAR can do smoothing in a variety of ways and there are very few exact equivalencies. Below are some possibilities. These can be used as a starting point. Note: line style changes affect all lines drawn in DISSPLA and NCAR. The only exception might be in some of the higher level routines in NCAR.

Defining line styles in NCAR via the dashpack parameters:

	subroutine dashpat(num)

c	routine that produces 10 dash line patterns
c	it is a simple routine, because previous states are not
c	saved and restored. '$' represents a solid line, '_'
c	represents a blank. The line patterns are stored in dashpt
c	and their length in dashsz.

	integer dashsz(10)
	character*10 dashpt(10)
	data dashpt /	'$', '$_', '$$__', '$$$$___', 
     x			'$$$$$$____', '$$_$_$$_$_', '$$$$_$_',
     x			'$$$$$__$__', '$$_$_$_', '$$$$$_$_$_'/
	data dashsz/1, 2, 4, 7, 10, 10, 7, 10, 7, 10/

c
c	If num is greater than 10, make it 10
	num_dash = num
	if (num_dash .gt. 10) num_dash = 10

	call dpseti ('DPS', 0)
	call dpsetc ('DPT', dashpt(num_dash))
	call dpseti ('DPL', dashsz(num_dash))
c
	return
	end

Contouring Routines

It is difficult to give a one-to-one correspondence between contouring for DISSPLA and NCAR. They both have a rich set of routines and options. The best way to convert is to look at the examples shown here, or use the examples of contouring in ncargex (see 'man ncargex'). You might want to use the higher level routines in NCAR (see how to run these examples by doing 'man ng4ex'), but I have neither looked them over nor tried them out.

There is, by and large, less functionality in DISSPLA than there is in NCAR. DISSPLA provides the ability to do contouring as an "Engineering Option" where it is an integrated capability of NCAR. Basically, DISSPLA allow the user to read contours generated elsewhere to make up for this (a capability NCAR doesn't have, as far as I know). DISSPLA provides only a few ways to convert data not on a grid to a grid and one way to generate contours. It then provides various options for drawing contours regardless of how they were generated. NCAR does not separate the generation and drawing of contours and it provides many, many ways of dealing with data that does not lie on a grid.

A PostScript version of NCAR's contouring package (CONPACK) is available from the web at: http://ngwww.ucar.edu/ngdoc/ng4.0.1/conmaptutor/conpack/conpacka.html. This document is important to read. It has a lot of useful information in it that this simple guide does not duplicate. You may also want to refer to this section of the GRAFLIB to NCAR transition guide, http://www-vis.lbl.gov/software/graf_trans.html, as it contains addition information on some of the NCAR contouring routines that go beyond what is available in DISSPLA.

Some things to note:

• Unlike the previous example, the arguments for the various routines are not listed in detail with their corresponding meaning. Only the set routines are listed. Please check the respective manuals for the arguments and meanings.
• At the end of this section are two important example routines. The first is a code fragment which shows how you to set your own contour levels. The NCAR default is to choose the contour levels. The code fragment below shows how to override this behavior. The second routine, cpmpxy, is an example if you need to change the mapping function.
• NCAR can fill between the contours, either with a color or a pattern. Check out the CONPACK examples by either doing 'ncargex -conpack' to create CGM files or 'ncargex -W x11 -conpack' to plot to a X11 window.
• While DISSPLA has numerous ways of doing contours, NCAR has even more. For example, in NCAR there are at least three different ways of plotting contour lines that effect how contours lines will overlap labels (from a fast method that allows lines to cross labels to a slower way that insures that no contour lines will cross a label).
• You might want to turn off clipping before you call the contouring routines. This is important if you are having them plot titles. If clipping is not turned off, you won't see the titles.

Below is a code fragment demonstrating how you can choose your own contour levels:

	data clevels/-1.,0.,5.,10./
	
	INCL = 4
	call cpseti('CLS - Contour Level Selector', 0)
	call cpseti('NCL - No. of contour levels', INCL)
	DO I = 1,INCL
	   call cpseti('PAI - Parameter Array Index', I)
	   call cpsetr('CLV - Contour level value', clevel(I))
	enddo

If you change the mapping function (e.g. call cpseti ('MAP -- Mapping Function', cpmpxy)) you need to add a routine like cpmpxy below to:

	SUBROUTINE CPMPXY(IMAP,XINP,YINP,XOTP,YOTP)
C
C 	This version of CPMPXY implements four different mappings:
C
C   	IMAP = 1 implies an EZMAP mapping. XINP and YINP are assumed to be
C   	the longitude and latitude, in degrees, of a point on the globe.
C
C   	IMAP = 2 implies a polar coordinate mapping. XINP and YINP are
C   	assumed to be values of rho and theta (in degrees).
C
C   	IMAP = 3 implies an orthogonal, but unequally spaced mapping. XINP
C   	is assumed to lie in the range from 1 to M, YINP in the range from
C   	1 to N, where M and N are the dimensions of the grid. The common
C   	block CPMPC1 contains arrays XFOI and YFOJ giving the X coordinates
C   	associated with I = 1 to M and the Y coordinates associated with
C   	J = 1 to N.
C
C   	IMAP = 4 implies a generalized distortion. XINP is assumed to lie
C   	in the range from 1 to M, YINP in the range from 1 to N, where M
C   	and N are the dimensions of the grid. The common block CPMPC2
C   	contains arrays XFIJ and YFIJ, giving the X and Y coordinates
C   	associated with index pairs (I,J).
C
C 	Declare common blocks.
C
	   Parameter (M=<data column dimension >, N=<data row dimension>)
        COMMON /CPMPC1/ XFOI(M),YFOJ(N)
        COMMON /CPMPC2/ XFIJ(M,N),YFIJ(M,N)
C
C 	Do the mapping.
C
        IF (IMAP.EQ.1) THEN
          CALL MAPTRN (YINP,XINP,XOTP,YOTP)
        ELSE IF (IMAP.EQ.2) THEN
          XOTP=XINP*COS(.017453292519943*YINP)
          YOTP=XINP*SIN(.017453292519943*YINP)
        ELSE IF (IMAP.EQ.3) THEN
          I=MAX(1,MIN(32,INT(XINP)))
          J=MAX(1,MIN(32,INT(YINP)))
          XOTP=(REAL(I+1)-XINP)*XFOI(I)+(XINP-REAL(I))*XFOI(I+1)
          YOTP=(REAL(J+1)-YINP)*YFOJ(J)+(YINP-REAL(J))*YFOJ(J+1)
        ELSE IF (IMAP.EQ.4) THEN
          I=MAX(1,MIN(32,INT(XINP)))
          J=MAX(1,MIN(32,INT(YINP)))
          XOTP=(REAL(J+1)-YINP)*
     +    ((REAL(I+1)-XINP)*XFIJ(I,J  )+(XINP-REAL(I))*XFIJ(I+1,J  ))
     +    +(YINP-REAL(J))*
     +    ((REAL(I+1)-XINP)*XFIJ(I,J+1)+(XINP-REAL(I))*XFIJ(I+1,J+1))
          YOTP=(REAL(J+1)-YINP)*
     +    ((REAL(I+1)-XINP)*YFIJ(I,J  )+(XINP-REAL(I))*YFIJ(I+1,J  ))
     +    +(YINP-REAL(J))*
     +    ((REAL(I+1)-XINP)*YFIJ(I,J+1)+(XINP-REAL(I))*YFIJ(I+1,J+1))
        ELSE
          XOTP=XINP
          YOTP=YINP
        END IF
C
C Done.
C
        RETURN
C
      END