This file lists new subroutines and functions found in

This file lists new subroutines and functions found in ZXPLOT Version 3.0.

Main new features in version 3.0 include improved color support, color filled contours maps, cross-hatching at arbitary angles and plotting in map projection space (supporting Polosteographic, Lambert and Mercator projections). The documentations were taken directly from the source code and certainly need more work. They will be merged into the User Documentation later.

Ming Xue (mxue@ou.edu)

ENTRY xpaprlnth( yside0a )
Define the length of the paper relative to the width. For US letter size paper, width is 1 and the length should be between 1.0 and 1.5.
It should be called before xdevic. Otherwise, xdspac should be called after xpaprlnth. The paper length does not effect on NCAR graphics output, for which is the plotting space is limited to 1x1.

ENTRY xpsfn(psfn, iounit )
Define the Postscript output file name (psfn) and the Fortran I/O unit to use for writing the file. Effective for PS version only.

SUBROUTINE PSopn
Low-level routine called by XDEVIC to open PS output file. Used by PS version only.

SUBROUTINE PSfram
SUBROUTINE PScls
SUBROUTINE PSspac(pl,pr,pb,pt, x1,x2,y1,y2)
SUBROUTINE PStran(x,y)
SUBROUTINE PSpnup(x1,y1)
ENTRY PSpndn(x2,y2)
SUBROUTINE PSwndw(x1,x2,y1,y2)
SUBROUTINE PSgray(gray)
SUBROUTINE PSlnwd(wd)
SUBROUTINE PSfont(n)
ENTRY PSftsz(nsiz)
ENTRY PSftnm(ftname)
Low-level routines used by the PS version.

SUBROUTINE xpscmnt(ch)
To write a comment string (ch) into the PS output file. The comments are often used as identifiers of the blocks of PS code.

SUBROUTINE XFILAREA(X,Y,NP)
Fill a polygon area defined by 1D arrays x(np),y(np), where x and y are the coordinates of the polygon corners, and np the number of corners.

SUBROUTINE xichar

SUBROUTINE xafstyl(nstyle)

SUBROUTINE xafstyl(nstyle)
Call GKS (NCAR graphics) routine gsfais to define the style of area fill.
Effective for the GKS and NCAR graphics version only.
nstyle = 0 hollow fill

= 1 solid fill

= 2 pattern fill

= 3 hatch fill

SUBROUTINE xafpatn(npat)

Calls GKS (NCAR graphics) routine gsfasi to define the hatch pattern when the fill style is set to hatch fill.
npat = 1 horizontal lines
= 2 vertical lines
= 3 lines of positive slope
= 4 lines of negative slope
= 5 horizontal and vertical lines
= 6 lines of postive and negative slope

CALL set(px1,px2,py1,py2, x1,x2,y1,y2, mode)

ENTRY xqset(xp1a,xp2a,yp1a,yp2a,x1a,x2a,y1a,y2a)

ENTRY xzx2ncar( xpos, ypos )
With the NCAR graphics version, return the coordinate of (xpos,ypos)in the NCAR graphics plotting space. In another word, (xpos,ypos) on input corresponds to plotting space defined by XMAP, and on output to the plotting space defined by SET. Does nothing for PS version.

SUBROUTINE STRMLN (U,V,WORK,IMAX,IPTSX,JPTSY,NSET,IER)
NCAR graphics routine for plotting streamlines.

SUBROUTINE strmln

SUBROUTINE XCOLOR(icolor)

ENTRY XQCOLOR(lcolor)
Set and enquire color index, which affect all plotting that follows, include the color for characters, lines and area fills.

SUBROUTINE xbrokn(if1,ib1,if2,ib2)
ENTRY xbrokn0
ENTRY xdash
ENTRY xdot
ENTRY xqbrkn(kf1,kb1,kf2,kb2)
Enquire the parameters used in XBROKN.
ENTRY xfull
ENTRY xqfull(kfull)
Enquire the parameter value used in XFULL.

SUBROUTINE xthick(ithick)
ENTRY xqthik(kthick)
Enquire the current setting of line thickness. Used by PS version only.
ENTRY xlnmag(alnmag)
ENTRY xqlnmag(blnmag)
Set and enquire the current setting of line thickness magnification factor.
Used by PS version only.

SUBROUTINE xchmag(h)

ENTRY xqchmg(hh )

ENTRY xchsiz( hc )

ENTRY xqchsz( cs1 )

SUBROUTINE xcfont( ifont )

ENTRY xqcfnt ( nfont )
ifont =5 for greek symbol font.

SUBROUTINE xarrow(u,v,x0,y0, xleng,uunit)

ENTRY xartyp(ktype)

SUBROUTINE XSETCLRS(col_tab)
Initialize and choose the color tables.

Integer col_tab = -1, color table read in from file coltabfn, which

can be set using entry XSTCTFN.

= 0, Black and white plot. All lines are black.

= 1, Predefined color table No. 1.

= 2, Predefined color table No. 2,

which is No.1 in reversed order.

= 3, Predefined color table No. 3.

= 4, Gray scale color table.

= 5, predefined 200 multi-spectum color table (zj).

ENTRY XQCLRTBL( ncoltable )
Enquire the color table number, as given by parameter col_tab in XSETCLRS.

ENTRY XSTCTFN(col_tab_fn)
character col_tab_fn*(*)
Set the file name containing the color table. Used when col_tab=-1 for XSETCLRS.

SUBROUTINE xwindw(x1,x2,y1,y2)

SUBROUTINE xqwndw(x1,x2,y1,y2)

SUBROUTINE xqwdwon(window_on)
Enquire the corrent status of window clipping.
OUTPUT: Integer window_on, = 0, off, =1 on.

SUBROUTINE xwdwof
Turn window clipping off.

SUBROUTINE XMARKER(X,Y,MARKER)
Draw a predefined marker.
INPUT:

REAL x,y: The center coordinate of the marker
INTEGER MARKER: The marker type/number.
Currently five marker types are defined. They are
1
2
3
4
5

ENTRY XMRKSZ(R)
Set marker size in terms of their radius in normalized plotting space.

ENTRY XMKRFIL( imkfil )
Option to fill the marker. 0 for no and 1 for yes.

ENTRY XQMKRFIL( imkfil0 )
Enquire the current option for marker fill.

SUBROUTINE XAXSCA1(XL,XR,XSTEP,XJUMP,YB,YT,YSTEP,YJUMP)
An alternative to XAXSCA, and allows user to define intervals between major tick marks in terms of the multiples of minor tick marks (XJUMP and YJUMP) between major tick marks. REAL XJUMP, YJUMP: Major tick marks are plotted every xjump and yjump minor ticks along x and y axies, respectively.

SUBROUTINE XCTRHL(Z,X,Y,MD,M,N)
Plot H and L labels at the high and low centers of a data fields

ENTRY XHLLABL(hl_label)
Set the option of plotting H-L labels at the high and low centers of a data field.
hl_label = 0, no H-L labels

= 1, search a radius of one grid interval to determine the local

maximum and minimum.

= 2, search a radius of two grid intervals to determine the local

maximum and minimum.

SUBROUTINE XCOLFIL(a,x,y,iwrk,xw,yw,md,m,n, cl0,ncl, mode)

Generate color filled contour plot of 2-d field A given its
coordinates x and y. The contour levels between which color fill occurs
are supbject to the limits set by XCTRLIM.
INPUT:

REAL a(md,n) 2-dimensional slice of data to contour

REAL x(md,n) coordinate of grid points in plot space (over on page)

REAL y(md,n) y coordinate of grid points in plot space (up on page)

INTEGER md first dimension of a

INTEGER m number of points in the first dimension of a to be plotted

INTEGER n second dimension of a

REAL cl0(ncl) contour levels

INTEGER ncl Number of contour levels

INTEGER mode =1,2,3,4. As in XCONTA.
Integer iwrk(m,n)

REAL xw(8*m),yw(8*m) Work arrays

SUBROUTINE XCTRLIM(ctr_min, ctr_max)

ENTRY XQCTRLIM(ctr_min, ctr_max)

c Set lower and upper limits (the range) of the values beyond which no

c contour is plotted. Used by XCONTA and XCOLFIL.

c IF set to -9999.0, then the min or max in the field is used.

c e.g., CALL XCTRLIM(0.0, -9999.0) will plot all positive contours.
Set up and enquire the lower and upper limits (range) of values beyond which no contour or color filled contours is produced. When a value is set to -9999.0, the extrema (minimum or maximum) in the plotted field will be used as the limit. Effectively no limited is imposed other than the limit of its own.

SUBROUTINE XCTRCLR (clrbgn, clrend)

SUBROUTINE XQCTRCLR(clrbgn, clrend)
INTEGER clrbgn, clrend
Set the range of color indecies in the current color table to be used for value-dependent colored contours and color filled field.
In general, clrbgn matches the lower limit of the contour value to be plotted. The latter is set by XCTRLIM. The colors will be repeated of the number of colors in the specified range are not sufficient to cover all contours.

SUBROUTINE XCONTA(Z,X,Y,IWRK,MD, M,N, CL, NCL, MODE )
mode = 4, contours at levels specified in array CL(NCL) are plotted.

SUBROUTINE XCTRBADV(flagbadv)
INTEGER: flagbadv =0 and 1. Turn bad value flagging on and off for contour
plotting.

ENTRY XVTRBADV(MHOLE)
INTEGER: flagbadv =0 and 1. Turn bad value flagging on and off for vector
field (including arrow and wind barb) plotting.

ENTRY XBADVAL(SPECM)
Set values used to flag bad/missing values in a contoured or wind vector field.

SUBROUTINE XHATCHA(Z,X,Y,xwk,ywk,MD,M,N,CL1,CL2,hatch_angle)
Draw hatch pattern between two contour levels CL1 and CL2, with specified hatch_angle in degrees. xwk and ywk are work arrays of size (md*n). Other arguments have the same definition as in XHATCH.

SUBROUTINE XVECTR(U,V,X,Y,MD,M,ISTEP,N,JSTEP,XLENG,UUNIT)

SUBROUTINE XBARB(U,V,X0,Y0,wunits,XLENG,barbopt)
REAL u,v, x0,y0, wunits,XLENG
INTEGER barbopt
Plot a single wind bard (U,V) at location (X,Y).
integer wunits: Wind vector units. =1: m/s, =2: knots or miles/per hour
real xleng: Length of the wind barb in terms of x-coordinate

integer barbopt: Option for plotting the direction of wind barb

=1, wind barb direction conforms to the streamlines if plotted,

i.e., it depends on the grid aspect ration.

=2, wind bard direction represents the absolute direction,

regardless the grid aspect ratio.

SUBROUTINE XBARBS(U,V,X,Y,MD,M,ISTEP,N,JSTEP,wunits,xleng,barbopt)
REAL u(md,n),v(md,n),x(md,n),y(md,n)
Call XBARB to plot wind barbs for a wind field (U,V) defined at coordinate (X,Y).
Most arguments have the same definition as in XVECTR.

SUBROUTINE XCPALET(mode)
Plot a color palette coresponding to the most recently plotted
contour or color filled contour field.
INPUT:

mode Option for positioning the color palette

= 1, color bar is located below the plotting space

= 2, color bar is located to the right of plotting space

SUBROUTINE XRCH_new( R,CH,LCH)

SUBROUTINE xgetfmt(R,CH)

SUBROUTINE XSTRMIN( string, length )

General Information on setting up Set up map projection grid.
This set of subroutines allows for transformation between
lat-lon coordinates and any one of three map projections: Polar
Stereographic, Lambert Conformal or Mercator.
In order for the transformation subroutines to work, the

map projection must first be set up by calling setmapr. The
user may wish to call setorig immediately after setmapr to
established an origin (given a lat-long or x-y in the default
system) other than the default origin (e.g., the north pole).
All lat-lons are in degrees (positive north, negative south,

positive east and negative west). Note carefully the dimensions
of x,y -- it differs among the subroutines to conform to ARPS usage.
x,y coordinates are meters on earth but may be changed using the scale
parameter in setmapr to change to km (scale=0.001) or to a different
sphere (e.g., scale=mars_radius/earth_radius).

SUBROUTINE XSTPJGRD(mapproj,trulat1,trulat2,trulon,

ctrlat,ctrlon,xl,yl,xorig,yorig)
Call XSTMPRJ and xsetorig to setup a map projection. Afterwards,
coresponding coordinate values in a projection (x,y) space and the longitude-
latitude space can be found by calledin xlltoxy and xxytoll.
INPUT:

mapproj Map projection option.

= 0, no map projection;

= 1, polar projection;

= 2, Lambert projection;

= 3, Mercator projection.

trulat1 1st true latitude of map projection.

trulat2 2nd true latitude of map projection (used only by mapproj = 2).

trulon True longitude of map projection.

ctrlat Latitude of the model physical domain center (deg. N).

ctrlon Longitude of the model physical domain center (deg. E).

Parameters ctrlat and ctrlon do not have to be set when

initopt=3, since the values in the header of the input data

file will be used in this case.

xl Width of the rectangular grid

yl Height of the rectangular grid

xorig x-coordinate of the lower-left corner of the grid

yorig y-coordinate of the lower-left corner of the grid

SUBROUTINE XSTMPRJ(iproj,trulat1,trulat2,trulon)
Set constants for map projections.
INPUT:

INTEGER iproj Map projection number

1=North Polar Stereographic (-1 South Pole)

2=Northern Lambert Conformal (-2 Southern)

3=Mercator

4=Lat,Lon

REAL scale Map scale factor, at latitude=latnot

Distance on map = (Distance on earth) * scale

For ARPS model runs, generally this is 1.0

For ARPS plotting this will depend on window

size and the area to be plotted.

REAL latnot(2) Real "True" latitude(s) of map projection

(degrees, positive north)

Except for iproj=1, only latnot(1) is used

REAL orient Longitude line that runs vertically on the map.

(degrees, negative west, positive east)

SUBROUTINE XGETMAPR(iproj,scale,latnot,orient,x0,y0)
Get the constants for the current map projection.
OUTPUT:

INTEGER iproj Map projection number

1=North Polar Stereographic (-1 South Pole)

2=Northern Lambert Conformal (-2 Southern)

3=Mercator

4=Lat,Lon

REAL scale Map scale factor, at latitude=latnot

Distance on map = (Distance on earth) * scale

For ARPS model runs, generally this is 1.0

For ARPS plotting this will depend on window

size and the area to be plotted.

REAL latnot(2) Real "True" latitude(s) of map projection

(degrees, positive north)

Except for iproj=2, only latnot(1) is used

REAL orient Longitude line that runs vertically on the map.

(degrees, negative west, positive east)

REAL x0 x coordinate of origin

REAL y0 y coordinate of origin

SUBROUTINE XSETORIG(iopt,x0,y0)
Set the origin for the map projection.
This is call after subroutine mapproj if the origin
must be moved from the original position, which is the
pole for the polar stereographic projection and the
Lambert conformal, and the equator for Mercator.
INPUT:
INTEGER iopt origin setting option

1: origin given in corrdinate x,y

2: origin given in lat,lon on earth

REAL x0 first coordinate of origin

REAL y0 second coordinate of origin
SUBROUTINE XXYTOLL(idim,jdim,x,y,rlat,rlon)
Determine latitude and longitude given X,Y coordinates on

map projection. SETMAPR must be called before this routine
to set-up the map projection constants.
INPUT:
INTEGER idim Number of points in x direction.
INTEGER jdim Number of points in y direction.

REAL rlat Array of latitude.

(degrees, negative south, positive north)

REAL rlon Array of longitude.

(degrees, negative west, positive east)
OUTPUT:

REAL x Vector of x in map coordinates

REAL y Vector of y in map coordinates

Units are meters unless the scale parameter is

not equal to 1.0

SUBROUTINE XLLTOXY(idim,jdim,rlat,rlon,xloc,yloc)
Determine x, y coordinates on map projection from the given latitude
and longitude. SETMAPR must be called before this routine to set-up
the map projection constants.
INPUT:
INTEGER idim Array dimension in x direction
INTEGER jdim Array dimension in y direction
REAL rlat Real vector of latitude.

(degrees, negative south, positive north)
REAL rlon Real vector of longitude.

(degrees, negative west, positive east)
OUTPUT:

REAL xloc Real vector of x in map coordinates

REAL yloc Real vector of y in map coordinates
SUBROUTINE XLATTOMF(idim,jdim,rlat,emfact)
Determine the map scale factor, emfact, at a given latitude.
INPUT:

INTEGER idim Array dimension in x direction

INTEGER jdim Array dimension in y direction

REAL rlat Real vector of latitudes.

(degrees, negative south, positive north)
OUTPUT:

REAL emfact Vector of map scale factors corresponding to the

input latitudes (map scale includes the projection

image scale times the overall scale of the map).

SUBROUTINE XXYTOMF(idim,jdim,x,y,emfact)
Determine the map scale factor, emfact, given x,y in the projected space.
INPUT:

INTEGER idim Array dimension in x direction.

INTEGER jdim Array dimension in y direction.

REAL x x coordinate values (meters if scmap=1.0)

REAL y y coordinate values (meters if scmap=1.0)
OUTPUT:

REAL emfact Vector of map scale factors corresponding to the input x,y's.

SUBROUTINE XDDROTUV(nsta,stalon,dd,ff,ddrot,umap,vmap)
Rotate wind from earth direction to map orientation.
INPUT:

INTEGER nsta array dimension

REAL stalon longitude (degrees E)

REAL dd wind direction (degrees from north)

REAL ff wind speed
OUTPUT:

REAL ddrot wind direction rotated to map orientation

REAL umap u wind component on map (same units as ff)

REAL vmap v wind component on map (same units as ff)

SUBROUTINE XUVROTDD(idim,jdim,elon,umap,vmap,dd,ff)
Convert winds u, v in map coordinates to wind direction and speed
in earth coordinates.
INPUT:

INTEGER idim Array dimension in the x direction

INTEGER jdim Array dimension in the y direction

REAL elon Earth longitude (degrees E)

REAL umap u wind component on map

REAL vmap v wind component on map
OUTPUT:

REAL dd wind direction on earth

REAL ff wind speed on earth

SUBROUTINE XUVETOMP(idim,jdim,uear,vear,lon,umap,vmap)
Transform u, v wind from earth coordinates to map coordinates.
INPUT:

INTEGER idim Array dimension in the x direction

INTEGER jdim Array dimension in the y direction

REAL uear u (eastward) wind component on earth

REAL vear v (northwrd) wind component on earth

REAL lon earth longitude
OUTPUT:

REAL umap u wind component on map

REAL vmap v wind component on map

SUBROUTINE XUVMPTOE(idim,jdim,umap,vmap,lon,uear,vear)
Transform u, v wind from map coordinates to earth coordinates.
INPUT:

INTEGER idim Array dimension in x direction

INTEGER jdim Array dimension in y direction

REAL umap u wind component on map

REAL vmap v wind component on map

REAL lon Longitude (degrees E)
OUTPUT:

REAL uear u (eastward) wind component on earth

REAL vear v (northward) wind component on earth

SUBROUTINE XDRAWMAP(nunit, mapfile, latgrid, longrid)
This subroutine draws a map within a rectagular box in
a map projection space. The map projection and plotting space
should have been properly set before calling this subroutine.
INPUT:

INTEGER nunit the channel of the mapfile data

CHARACTER mapfile*(*) character of map file name
REAL latgrid,longrid (degree): the intervals between lat and lon grid lines.

< 0.0, no grid lines in the given direction,

= 0.0, internally determined,

= any real number, typically from 1.0 to 10.0 degrees.