Ezmap, A Map-Drawing Package

David J. Kennison
NCAR, P.O. Box 3000, Boulder, Colorado 80307-3000
email: kennison@ucar.edu

Table of Contents

INTRODUCTION

This document describes an NCAR Graphics package named EZMAP. It allows one to plot maps of the earth using any one of many different projections, with parallels, meridians, continental outlines, international boundaries, Canadian provincial boundaries, Mexican state boundaries, and U. S. state and county boundaries. The origin and orientation of the projection may be selected by the user. Points on the earth defined by latitude and longitude are mapped to points in a projection plane, referred to as the u/v plane. A rectangular perimeter whose sides are parallel to the u and v axes is chosen; material within that perimeter (or an inscribed elliptical perimeter) is mapped to the plane of the plotter (referred to as the x/y plane) for plotting. The u and v axes are parallel to the x and y axes, respectively.

The package EZMAP has acquired its current form over a number of years; several times, groups of routines implementing a particular new function have been added and each of these has a sort of subpackage name, as follows:

Principal sections of this document are as follows:

Routines Used to Draw a Simple Map

To draw the simple map defined by the current values of EZMAP's internal parameters (assuming no area fills and no access to the new, improved, map database "Earth..1", which was created in 1998, "Earth..2", which was created in 1999, or "Earth..3", which was created in 2000), one need only execute the single FORTRAN statement "CALL MDPDRW":

Calling MDPDRW results in calls to four lower-level routines. In many situations, the user will wish to call these routines directly; they are as follows (in the order in which they are called by MDPDRW):

Another routine is sometimes of interest:

Routines Used to Change the Values of Internal Parameters

The following routines are called to change the values of internal parameters of EZMAP, and thus change the behavior of other EZMAP routines:

Routines Used to Retrieve the Values of Internal Parameters

The following routines are used to retrieve the current values of EZMAP parameters:

Routines Used to Save and Restore Internal Parameters

To restore all default values of all the internal parameters of EZMAP, use the following:

To save/restore the current values of the internal parameters of EZMAP, use the following:

Routines Used to Do Transformations

The following routines effect transformations from lat/lon coordinates to u/v coordinates:

The following inverse-transformation routine was added to EZMAP early in 1992:

The example named "mpex10" shows one of the ways in which this routine may be used; it draws what is essentially a colored contour plot of a data field defined on the surface of the globe, using an orthographic projection.

Routines Used to Draw Objects on a Map

In drawing objects on a map, the following routines will be useful:

Routines Used to Draw Solid-Filled Maps (EZMAPA)

In late 1986 or early 1987, a package of routines was written allowing a user to draw solid-filled maps of the globe. This package was named EZMAPA and was first advertised in the NCAR Graphics User's Guide (Version 2.00), published in August, 1987. Conceptually, the routines of EZMAPA are just part of EZMAP; they use the same common blocks and many of the same underlying low-level routines and they are affected by the same set of internal parameters as the routines of EZMAP proper. The EZMAPA routines will be described in this document; to use them effectively, it will be necessary to understand also the package AREAS, which is described in a separate document. The EZMAPA routines are as follows:

Routines Used to Access New Datasets (EZMAPB)

In early 1998, a new world map database, called "Earth..1", was created for use with EZMAP; this database has higher-resolution coastlines, it has been updated to reflect many of the political changes that have taken place over the years since EZMAP came into existence, and it is structured differently, allowing for greater flexibility and ease of use and providing for easier changes and extensions in the future. In mid-1999, an updated version of this database, called "Earth..2", was created; it contains everything "Earth..1" does, plus the provinces of Canada, the states of Mexico, the counties of the United States, the country called Eritrea, and the countries resulting from the breakup of the USSR that were not included in "Earth..1". In the summer of 2000, a version of "Earth..2" was created which is just like it, but contains climate divisions of the states instead of counties.

Each area defined by the database has 1) an "area identifier" (an integer uniquely identifying it), 2) an "area type" specifying its level in a hierarchy of areas, 3) a suggested color index, 4) an area identifier specifying its "parent" area (the area of which it is a part), and 5) a name. For example, there is an area named "Madeline Island" which is of type 4 (used for a state or a portion thereof) and has suggested color index 6. Its parent is an area named "Wisconsin", which is also of type 4 and has suggested color index 6. The parent of "Wisconsin" is "Conterminous US", which is of type 3 (used for a country or a portion thereof) and has suggested color index 3. The parent of "Conterminous US" is "United States", which is also of type 3 and has suggested color index 3. The parent of "United States" is "North America", which is of type 2 and has suggested color index 5. The parent of "North America" is "Land", which is of type 1 and has suggested color index 2. The area named "Land" is at the top of the hierarchy and therefore has no parent (when you ask for the area identifier of its parent, you get a zero).

One may use the database at any of five specified hierarchical levels: 1 => land/water, 2 => continents, 3 => countries, 4 => states, and 5 => counties. When the database is used at a particular level, entities that exist only at lower levels (larger level numbers) effectively disappear.

The new database was created from data available on the World Wide Web, using a new interactive editor based on NCAR Graphics. There are plans to make this editor available, so that a knowledgeable user can create a database tailored to his or her own needs: for example (assuming that one can obtain the necessary outline data), it should now be relatively easy to create and use a Pangaea database with EZMAP.

A new package of routines is used to access "Earth..1" and other databases in the same format; this package is called EZMAPB. Conceptually, the EZMAPB routines are just part of EZMAP; they use the same common blocks and many of the same underlying low-level routines and they are affected by the same set of internal parameters as the routines in EZMAP proper.

The principal EZMAPB routines are as follows:

As each of the EZMAPB routines MDLNAM, MDLNDM, and MDLNDR processes boundary lines from a specified database, it calls an EZMAPB routine named MDCHLN (the default version of which does nothing):

Another EZMAPB routine, named MDGLTY, may be called by the user from within the line-processing routine specified by the final argument in a call to MDLNDM:

There is a group of EZMAPB functions providing access to information about the areas defined by a database being used; these may be referenced at any time the appropriate information has been loaded into EZMAPB's common blocks (that is, after calling one of MDLNAM, MDLNDM, MDLNDR, or MDLNRI), but they are normally to be referenced from within the area-processing routine specified as the final argument in a call to the AREAS routine ARSCAM, in which they may be used to obtain information determining the manner in which the areas are to be rendered:

Two additional EZMAPB functions are provided; these have nothing to do with mapping, really, but can be useful in dealing with character strings:

Routines Used to Access the USGS Package (EZMAPC)

In early 1999, EZMAP was modified to provide access to a package of routines obtained from the United States Geological Survey (USGS). The original package was called the General Coordinate Transformation Package (GCTP), but it had to be modified considerably for use with EZMAP.

The GCTP was intended to be run using 64-bit arithmetic on machines having 32-bit reals and therefore used double precision everywhere. On machines having 64-bit reals, this is unnecessary and may be very time-consuming; real arithmetic should be used instead. Therefore, each of the original GCTP routines exists in two different versions in our package - in single precision and in double precision. An EZMAP routine that needs to call a GCTP routine on a particular system calls whichever version of it is appropriate for use on that system.

On a machine having 32-bit reals, 64-bit double precision arithmetic is used in all computations within the GCTP, but the output values are truncated to 32 bits for plotting purposes; in this case, it is possible for a user with special needs to retrieve the 64-bit values directly.

The following user-level routines were added to EZMAP:

Routines Used to Access the RANGS/GSHHS Data

In 2001, EZMAP was modified to provide access to a dataset of very high resolution coastlines, referred to here as the RANGS/GSHHS data. (See the example named "mpex13" for plots comparing the databases previously available with the new one.)

The "Global Self-consistent Hierarchical High-resolution Shoreline" (GSHHS) dataset was originally created by Paul Wessel, of SOEST (School of Ocean and Earth Science and Technology), at the University of Hawaii, Honolulu, Hawaii, and Walter H. F. Smith, of the NOAA Geosciences Lab, National Ocean Service, Silver Spring, Maryland, for use with the package "Generic Mapping Tools" (GMT). The data they used came from the public-domain datasets "World Databank II" (WDBII) and "World Vector Shoreline" (WVS), but they cleaned up the data greatly. The on-line documentation for GMT contains a description of the whole process. The GSHHS dataset may be used at any one of five different levels of resolution, characterized by the keywords "finest", "fine", "medium", "coarse" and "coarsest".

Subsequently, Riener Feistel, at the Baltic Sea Research Institute, in Warnemuende, Germany, added structure to the data, making it easier to use in limited regions, to create what he calls the "Regionally Accessible Nested Global Shorelines" (RANGS) dataset. For a complete description, look here.

The RANGS/GSHHS data may be downloaded from the NCAR Graphics site or from Feistel's site, above. The following files are required:

    rangs(0).cat:      259,200 bytes  }
    rangs(1).cat:      259,200 bytes  }
    rangs(2).cat:      259,200 bytes  }  RANGS "catalog" files.
    rangs(3).cat:      259,200 bytes  }
    rangs(4).cat:      259,200 bytes  }

    rangs(0).cel:    6,518,664 bytes  }
    rangs(1).cel:    5,945,492 bytes  }
    rangs(2).cel:    4,062,215 bytes  }  RANGS "cell" files.
    rangs(3).cel:    3,398,642 bytes  }
    rangs(4).cel:    3,045,848 bytes  }

    gshhs(0).rim:   89,496,428 bytes  }
    gshhs(1).rim:   20,775,224 bytes  }
    gshhs(2).rim:    5,099,196 bytes  }  GSHHS "rim" files.
    gshhs(3).rim:    1,109,192 bytes  }
    gshhs(4).rim:      170,948 bytes  }

    total length:  140,917,849 bytes
Files containing a "(0)" define the finest-resolution dataset, those containing a "(1)" the next finest, and so on.

The following user-level routines were added to EZMAP:

Routines in Double Precision

In 2001, with the introduction of routines allowing access to the RANGS/GSHHS database, it became obvious that single-precision arithmetic could no longer provide sufficient resolution to deal with many large-scale maps of interest, so EZMAP was modified to use nothing but double-precision arithmetic internally (except in the EZMAPC routines, which already existed in both single-precision and double-precision incarnations).

This change involved the addition of many new EZMAP entry points. With four exceptions (MAPGTD, MAPSTD, MPGETD, and MPSETD) that were created solely for the sake of consistency, the names of all the new entry points begin with the two characters "MD" (for "Maps, Double"). In general, the routines with new names, beginning with "MD", are now the principal ones, while the routines with older names, beginning with "MAP" or "MP", are implemented by calling the new ones; thus, there is a small advantage in using the new entry-point names, but all of the older ones will work. (Note, however, that the double-precision routines MDPGCI, MDGCOG, and MDRITD are not used by their single-precision analogues MAPGCI, NGGCOG, and NGRITD.)

The new entry points are detailed below:

First, since all internal parameters of type REAL were changed to be of type DOUBLE PRECISION, it was necessary to create six entirely new routines to set and retrieve parameter values:

      MDGETD = MPGETD = MAPGTD (DP parameter value retrieval)
      MDSETD = MPSETD = MAPSTD (DP parameter value setting)
Three new routines are just like existing routines that set internal parameter values, but allow users to provide double-precision values:

      MDPPOS (like MAPPOS, sets map position parameters, has DP arguments)
      MDPROJ (like MAPROJ, sets projection parameters, has DP arguments)
      MDPSET (like MAPSET, sets map limit parameters, has DP arguments)
Three new routines allow access to double-precision versions of the basic transformation routines (lat/lon to U/V and vice-versa):

      MDPTRA (like MAPTRA, transformation routine, has DP arguments)
      MDPTRI (like MAPTRI, transformation routine, has DP arguments)
      MDPTRN (like MAPTRN, transformation routine, has DP arguments)
Thirteen new routines are used for drawing objects using lat/lon coordinates specified in double precision:

      In EZMAP,

      MDPGCI (like MAPGCI, interpolate points on great circle, has DP arguments)
      MDGCOG (like NGGCOG, create a great circle on globe, has DP arguments)
      MDRITD (like NGRITD, do 3D rotations, has DP arguments)

      MDPFST (like MAPFST, start a line, has DP lat/lon arguments)
      MDPVEC (like MAPVEC, continue a line, has DP lat/lon arguments)

      MDPIT  (like MAPIT, start or continue a line, has DP lat/lon arguments)
      MDPIQ  (like MAPIQ, finish drawing a line)
      MDPITD (like MAPITD, start or continue a line, has DP lat/lon arguments, using DASHPACK)
      MDPIQD (like MAPIQD, finish drawing a line, using DASHPACK)

      In EZMAPA,

      MDPITA (like MAPITA, line segment to area map, DP lat/lon arguments)
      MDPIQA (like MAPIQA, finish adding lines to an area map)
      MDPITM (like MAPITM,  draw line segment masked, DP lat/lon arguments)
      MDPIQM (like MAPIQM, finish drawing lines masked by an area map)
Four new routines are used to place latitude and longitude labels along a specified line on the map (which becomes more important as one uses more detailed large-scale maps): 
      MDLBLN (puts longitude labels along a specified line on the map)
      MDLBLT (puts latitude labels along a specified line on the map)
      MDLACH (converts a double-precision latitude to character form)
      MDLOCH (converts a double-precision longitude to character form)
As of 01/24/2007, another four have been added, which are just like the four immediately above, but express the labels in decimal degrees, rather than in standard nautical form: 
      MDLLND (puts longitude labels along a specified line on the map)
      MDLLTD (puts latitude labels along a specified line on the map)
      MDLACD (converts a double-precision latitude to character form)
      MDLOCD (converts a double-precision longitude to character form)
All the rest of the entry points were created solely for the sake of consistency, so that new programs can be written using nothing but names that begin with the characters "MD". These entry points are essentially just alternate names for existing entry points and are used with the same arguments as the originals:

      In EZMAP,

      MDGETC (like MPGETC = MAPGTC, parameter retrieval)
      MDGETI (like MPGETI = MAPGTI, parameter retrieval)
      MDGETL (like MPGETL = MAPGTL, parameter retrieval)
      MDGETR (like MPGETR = MAPGTR, parameter retrieval)
      MDPDRW (like MAPDRW, draw a complete map)
      MDPEOD (like MAPEOD, user-supplied routine to examine outline dataset)
      MDPGRD (like MAPGRD, draw a lat/lon grid)
      MDPINT (like MAPINT, initialize the package)
      MDPLBL (like MAPLBL, label a map)
      MDPLMB (like MAPLMB, draw a limb line)
      MDPLOT (like MAPLOT, draw geographic outlines)
      MDPRS  (like MAPRS, re-call SET)
      MDPRST (like MAPRST, restore saved parameter values)
      MDPSAV (like MAPSAV, save current parameter values)
      MDRSET (like MPRSET, parameter resetting)
      MDSETC (like MPSETC = MAPSTC, parameter setting)
      MDSETI (like MPSETI = MAPSTI, parameter setting)
      MDSETL (like MPSETL = MAPSTL, parameter setting)
      MDSETR (like MPSETR = MAPSTR, parameter setting)
      MDPUSR (like MAPUSR, user-supplied routine to change line style, color, etc.)

      In EZMAPA,

      MDPACI (like MAPACI, get suggested color index for specified area)
      MDPBLA (like MAPBLA, put boundary lines in an area map)
      MDPBLM (like MAPBLM, draw boundary lines masked by an area map)
      MDPGRM (like MAPGRM, draw a lat/lon grid masked by an area map)
      MDPLMM (like MAPLMB, draw a limb line masked by an area map)

      In EZMAPB,

      MDCHLN (like MPCHLN, change settings affecting lines being drawn)
      MDFNME (like MPFNME, get full name of an area)
      MDGLTY (like MPGLTY, get line type of current line being drawn)
      MDIATY (like MPIATY, get area type of an area)
      MDIFNB (like MPIFNB, get index of first non-blank of a string)
      MDILNB (like MPILNB, get index of last non-blank of a string)
      MDIOLA (like MPIOLA, get id of largest area containing an area)
      MDIOSA (like MPIOSA, get id of smallest area containing an area)
      MDIPAI (like MPIPAI, check whether an area is part of another)
      MDIPAN (like MPIPAN, check whether an area is part of another)
      MDIPAR (like MPIPAR, get id of parent area of an area)
      MDISCI (like MPISCI, get suggested color index for an area)
      MDLNAM (like MPLNAM, put outlines in an area map)
      MDLNDM (like MPLNDM, draw outlines masked by an area map)
      MDLNDR (like MPLNDR, draw outlines)
      MDLNRI (like MPLNRI, read information from an outline dataset)
      MDNAME (like MPNAME, get the name of an area)

      In EZMAPC,

      MDUTIN (like MPUTIN, USGS transform initialization)

      MDUTFD (like MPUTFD, USGS transform, forward, double precision)
      MDUTFS (like MPUTFS, USGS transform, forward, single precision)
      MDUTID (like MPUTID, USGS transform, inverse, double precision)
      MDUTIS (like MPUTIS, USGS transform, inverse, single precision)

Miscellaneous Other Routines

The following EZMAP routines are used for the purposes stated:

All of the routines mentioned above are described in detail in the section "ROUTINES", below.

PROJECTIONS

EZMAP originally offered eleven different projections. As of 1999, the 23 projections of the USGS package GCTP have been added to this number, but as there is some overlap in capability, the exact count now depends on how one defines what constitutes a "different" projection. Map projections naturally fall into three groups: conical, azimuthal, and cylindrical:

Conical Projections

Conical projections map the surface of the earth onto a cone which is either tangent to the earth along a single circle or intersects it along two circles. The cone is cut along some line passing through its vertex and opened up onto a flat surface. The only conical projection offered by EZMAP proper is the Lambert conformal conic (three others are provided in the USGS package). The Lambert conformal conic may be defined with two standard parallels or with one standard parallel.

The cone intersects the earth along two user-specified standard parallels (lines of latitude), which would normally both be in the Northern Hemisphere or in the Southern Hemisphere; the cone is cut along the line opposite a user-specified central meridian (line of longitude) and laid flat on the u/v plane with either the North Pole or the South Pole (as implied by the standard parallels) at the origin.

If LAT1 and LAT2 are the latitudes of the two standard parallels and LAT1 is not equal to LAT2, the so-called "cone constant" is given by the formula

                 LOG(COS(LAT1))-LOG(COS(LAT2))
    CONE = -------------------------------------------
           LOG(TAN(45-S*LAT1/2))-LOG(TAN(45-S*LAT2/2))
where "S" is +1 in the Northern Hemisphere and -1 in the Southern Hemisphere. If LAT1 equals LAT2, then

    CONE = COS(90-S*LAT1)
The value of CONE is between 0 and 1; CONE*360 is the angular separation between the edges of the cut after the cone is opened onto the plane, as measured across the surface of the flattened cone. If (RLAT,RLON) is a point to be projected, then the formulas

    R = (TAN(45-S*RLAT/2))**CONE
    U = R*SIN(CONE*(RLON-CLON))
    V = -S*R*COS(CONE*(RLON-CLON))
where CLON is the longitude of the central meridian, give the coordinates of the projected point in the u/v plane.

The globe is projected onto the entire u/v plane minus a wedge with its apex at the origin. This projection is normally used to depict mid-latitude regions of limited extent, for which it is relatively distortion-free. It has the property of preserving angles.

See the example named "mpex01".

Azimuthal Projections

Azimuthal projections map the earth (or a single hemisphere of it) onto a u/v plane whose origin touches the earth at the user-specified point (PLAT,PLON). The image may be rotated by a user-specified angle ROTA. The azimuthal projections are generated as follows:

If A is the angular separation, in degrees, of a point P, to be projected, from the point (PLAT,PLON), SINA is the sine of A, COSA is the cosine of A, and R is the linear distance of the projected point P' from the u/v origin, the various azimuthal projections may be described in terms of the relationship between A and R, as follows:

      R = TAN(A/2) = (1-COSA)/SINA
As A approaches 180 degrees, R approaches infinity. The entire globe is projected to the entire u/v plane. In practice, distortion becomes great beyond R=2, when A is approximately 127 degrees. The center of the projection is the point on the earth's surface opposite the point of tangency with the projection plane.

See the examples named "mpex02", "mpex04", "mpex05", and "mpex07".

      R = SINA
Points for which A is greater than 90 degrees are treated as invisible. Thus, a hemisphere is projected inside a circle of radius 1. The center of the projection is at infinity; all projection lines are parallel to each other and perpendicular to the u/v plane.

See the example named "mpex05".

      R = 2*SINA/SQRT(2*(1+COSA))
As A approaches 180 degrees, R approaches 2. The entire globe is projected into a circle of radius 2.

See the example named "mpex05".

      R = TAN(A) = SINA/COSA
Points for which A is greater than 90 degrees are invisible. Thus, a hemisphere is projected to the entire u/v plane. In practice, distortion becomes great beyond R=2, when A is approximately 65 degrees. The center of this projection is the center of the earth.

See the example named "mpex05".

      R = A*pi/180
As A approaches 180 degrees, R approaches pi (3.1415926...). Thus, the entire globe is projected within a circle of radius pi.

See the example named "mpex05".

      R = SQRT(SA*SA-1)*SINA/(SA-COSA)
where "SA" is the distance from the center of the earth to a satellite above the point (PLAT,PLON), in multiples of the earth's radius. Points for which COSA is less than "1/SA" are invisible. The portion of the earth's surface which would be visible from the satellite is projected inside a circle of radius 1. The center of the projection is at the satellite's position. As the satellite moves further and further out, the basic satellite-view projection approaches the orthographic projection. See the examples named "mpex05" and "mpexfi".

The basic satellite-view projection gives a view of the earth as seen by a satellite camera that is looking straight down toward the center of the earth. Note that the model for the "camera" we're talking about here is a pin-hole camera, in which each point of an image is formed by a single straight line emanating from some point in the scene. Real cameras are more complicated than that: each point of an image is formed by focusing infinitely many rays emanating from a point in the scene (all the rays from the point that happen to pass through the lens of the camera). An image formed by a real camera is generally distorted in some fashion and cannot be expected to exactly match an image formed by our hypothetical pin-hole camera.

See the examples named "mpex05" and "mpexfi".

      R = (something messy that I don't have in closed form)!
The user-settable parameters 'S1' and 'S2' affect the satellite-view projection as follows: S1 measures the angle between the line to the center of the earth and the line of sight of the satellite (the line to which the projection plane is perpendicular). The default value of S1 is zero, which gives the basic satellite view. When S1 is non-zero, S2 specifies the angle from the positive u axis of the basic satellite view counter-clockwise to the line OP, where O is the origin of the basic view and P is the projection (a single point), on the basic view, of the desired line of sight from the satellite. When S1 and S2 are used, the part of the earth projected is the same as for the basic view, but the part of the u/v plane covered by the projection may become the interior of an ellipse, the area "inside" a parabola, or the area "inside" one branch of a hyperbola; in each of these cases, the major axis of the curve defining the limb of the projection is at an angle S2 to the u axis.

Basically, 'S1' and 'S2' allow you to aim the satellite camera in any desired direction; however, getting exactly the view that you want is not completely trivial. The example "cpex10" demonstrates a technique that may be quite useful: if, in the call to MAPROJ that requests the satellite-view projection (with a first argument = 'SV' and second and third arguments PLAT and PLON specifying the position of the satellite), you use a value of ROTA (the final argument) such that the point you want to aim the satellite camera at is directly above the center of the basic view and you then use 'S1' non-zero and 'S2' = 90., you get a view with "outer space" at the top, the earth at the bottom, and the horizon line more or less horizontal. It is recommended that the satellite-view projection be used with a call to MAPSET in which the first argument JLTS = 'AN'; in that case, the other four arguments specify the field of view of the camera (as angular distances to the left, to the right, to the bottom, and to the top, of the frame). It is further recommended that you not use a first argument JLTS = 'MA' in such a call to MAPSET, since, in that case, you get a view showing the entire part of the globe that is visible from the satellite and distortion is likely to be extreme.

See the examples named "mpex06" and "cpex10". The latter is actually a CONPACK example, but it demonstrates the aiming technique described in the previous paragraph.

Cylindrical Projections

Cylindrical projections map the surface of the earth onto a cylinder which is tangent to the earth along a great circle passing through the user-specified point (PLAT,PLON) and tilted at a user-specified angle ROTA. The cylinder is cut along a line parallel to its axis and unrolled onto the plane. The cylindrical projections are generated as follows:

What happens in step 6 above will be described for each of the three types of cylindrical projections provided by EZMAP in the simple case where PLAT, PLON, and ROTA are all zero. Let RLAT and RLON be the latitude and longitude, in degrees, of a point to be projected; RLON must lie between -180 and +180. (If PLAT, PLON, and/or ROTA are non-zero, one must substitute for RLAT and RLON a pseudo-latitude and a pseudo-longitude computed from the real latitude and longitude; this is left as an exercise for the devotee of spherical trigonometry.) The cylindrical projections may then be described as follows:

      U = RLON
      V = RLAT
The entire globe is projected into a rectangle in the u/v plane. U ranges from -180 to +180, V from -90 to +90.

See the example named "mpex05".

      U = RLON*pi/180 (where pi=3.14159...)
      V = (4/3)*SIN(RLAT)
The entire globe is projected into a rectangle in the u/v plane. U ranges from -pi to +pi, V from -4/3 to +4/3.

See the example named "mpex14" or the example in the demo program "ezmapdemo". 

      U = RLON*pi/180 (where pi=3.14159...)
      V = ALOG(COT(45-RLAT/2))
The entire globe is projected into an infinite rectangle in the u/v plane. U ranges from -pi to +pi, V from -infinity to +infinity. In practice, distortion becomes unacceptable for latitudes within 5 degrees of the North or South Pole.

See the examples named "mpex03", "mpex04", "mpex05", "mpex08", and "mpex09".

Also available is a variation of the Mercator, referred to as the "rotated Mercator", which is generated as described above except that steps 3 and 4 are skipped (leaving the earth upright, with the cylinder wrapped around it, tangent to the equator), and, following step 8, there is a final clockwise rotation by the angle ROTA, so that the infinite rectangle in the u/v plane is tilted with respect to the U and V axes. Meridians are straight lines making an angle of ROTA with the V axis; parallels are straight lines that are perpendicular to the meridians. An example is available from "ezmapdemo".

      U = RLON/90
      V = COS(90-RLAT)
The entire surface of the globe is projected into an ellipse. U ranges from -2 to +2, V from -1 to +1.

See the example named "mpex05".

      RLAT     PLEN      PDFE
      ----    ------    ------
       00N    1.0000    0.0000
       05N    0.9986    0.0620
       10N    0.9954    0.1240
       15N    0.9900    0.1860
       20N    0.9822    0.2480
       25N    0.9730    0.3100
       30N    0.9600    0.3720
       35N    0.9427    0.4340
       40N    0.9216    0.4958
       45N    0.8962    0.5571
       50N    0.8679    0.6176
       55N    0.8350    0.6769
       60N    0.7986    0.7346
       65N    0.7597    0.7903
       70N    0.7186    0.8435
       75N    0.6732    0.8936
       80N    0.6213    0.9394
       85N    0.5722    0.9761
       90N    0.5322    1.0000
This is a pseudo-cylindrical projection. The entire surface of the globe is projected into an area having straight edges at the top and bottom and curved edges on the left and right. U ranges from -1 to +1, V from -.5072 to +.5072. This projection is now the principal one used by the National Geographic Society.

USGS Projections

The United States Geological Survey makes available a package of FORTRAN routines, called the General Coordinate Transformation Package, which implements 23 different map transformations. In late 1998, I acquired a copy of this package and I have now (early 1999) made it possible to use the package from EZMAP.

In order to use the USGS routines, one must first call the routine MDPROJ with a first argument 'UT' (for "USGS Transformations"). Then, one must call the routine MDUTIN to select a particular USGS transformation and initialize it. MDUTIN calls MDPINT, and subsequent calls are just as before.

Some of the USGS transformations are for projections that we did not previously have. Some of them are for projections that we did have, but provide for the use of an ellipsoidal model of the earth instead of or in addition to a spherical model. In all cases, one can specify the dimensions of the earth in meters, so that U and V coordinates have real meaning.

The projections provided by the USGS are as follows:

No. Name Type Earth Model Shape of Projected Earth
01UTM (Universal Transverse Mercator) cylindrical ellipsoid not used for whole-earth maps
02State Plane various ellipsoid (Clarke 1866 or GRS 1980 only) not used for whole-earth maps
03Albers Equal-Area Conic conical ellipsoid interior of a circle minus a smaller circle and a wedge
04Lambert Conformal Conic conical ellipsoid entire plane minus a wedge
05Mercator cylindrical ellipsoid strip between vertical lines
06Polar Stereographic azimuthal ellipsoid entire plane
07Polyconic conical ellipsoid interior of a near-circle
08Equidistant Conic conical ellipsoid interior of a circle minus a smaller circle and a wedge
09Transverse Mercator cylindrical ellipsoid strip between horizontal lines
10Stereographic azimuthal sphere of reference entire plane
11Lambert Azimuthal Equal-Area azimuthal sphere of reference interior of a circle
12Azimuthal Equidistant azimuthal sphere of reference interior of a circle
13Gnomonic azimuthal sphere of reference entire plane
14Orthographic azimuthal sphere of reference interior of a circle
15Perspective azimuthal sphere of reference interior of a circle
16Sinusoidal cylindrical sphere of reference area between two sine curves
17Equirectangular cylindrical sphere of reference interior of a rectangle
18Miller Cylindrical cylindrical sphere of reference interior of a rectangle
19Van der Grinten I cylindrical sphere of reference interior of a circle
20Oblique Mercator (Hotine) cylindrical ellipsoid strip between oblique lines
21Robinson pseudocylindrical sphere of reference interior of a polygon
22Space Oblique Mercator cylindrical ellipsoid really, really weird - useful in limited areas
23Modified Stereographic for Alaska azimuthal ellipsoid (Clarke 1866 only) not used for whole-earth maps

The UTM Coordinate System

The Universal Transverse Mercator coordinate system was adopted by the U.S. Army in 1947 for use on large-scale military maps; it provides map coordinates that are simpler to use than latitude and longitude (as, for example, in computing distances between two points on such a map). The UTM system is currently employed by the armed forces of the United States and NATO. With the advent of inexpensive GPS receivers, other map users are now adopting the UTM system as well.

The UTM system takes advantage of the fact that a transverse Mercator projection of the earth is generated using a cylinder whose axis is perpendicular to the plane of a particular meridian and portrays with minimal distortion a strip of the earth's surface near that meridian, where the surface of the earth and the cylinder are very close together.

The portion of the earth between latitudes 80S and 84N is divided into 60 longitude zones, each of which is 6 degrees of longitude in width. The zones are numbered consecutively from west to east; zone number 1 is centered at 177W and covers longitudes from 180W to 174W and zone number 60 is centered at 177E and covers longitudes from 174E to 180E. Each of the sixty UTM zones is projected to an X/Y plane using a transverse Mercator projection having the central meridian of the zone as its central meridian. Given the latitude and longitude of a point in a UTM zone, the transverse Mercator projection gives us an X value, referred to as an "easting", and a Y value, referred to as a "northing", for the point; these are the numeric UTM coordinates of the point and they are measured in meters. Eastings are biased by the addition of a "false easting", so that a point on the central meridian always has an easting of exactly 500,000. The northing for a point in the Northern Hemisphere is just its distance from the equator, but the northing for a point in the Southern Hemisphere is biased by a "false northing" of 10,000,000 (so that subtracting it from 10,000,000 gives the distance of the point from the equator). The use of the "false easting" and "false northing" ensures that the UTM coordinates will always be positive values.

Thus, given a point at an arbitrary longitude and a latitude between 80S and 84N, one can determine the zone and the hemisphere in which the point lies and then compute its numeric UTM coordinates relative to that zone. Similarly, given a zone number, a hemisphere, and the numeric UTM coordinates of a point, one can determine the latitude and longitude of the point.

Each of the sixty UTM zones is further subdivided into twenty horizontal bands, which are lettered, from south to north, beginning with "C" for a band from 80S to 72S and ending with "X" for a band from 72N to 84N; the letters I and O are skipped to avoid confusion with the numbers 1 and 0. Each of the first nineteen bands spans eight degrees of latitude, while the northernmost band, band "X", spans 12 degrees of latitude.

Note that the information provided by the horizontal-band letters is somewhat redundant: although specifying the letter gives someone who is familiar with the UTM system a rough idea of where on the earth a point lies, it affects the computation of the lat/lon coordinates from the numeric UTM coordinates only in that one can deduce from the letter whether a specified point is in the Southern Hemisphere (bands C-M) or in the Northern Hemisphere (bands N-X).

The USGS routines do not make use of the band letters in UTM coordinates; instead, the convention is that positive zone numbers, from 1 to 60, refer to the Northern Hemisphere and negative zone numbers, from -1 to -60, refer to the Southern Hemisphere. As far as I know, this convention is peculiar to the USGS routines and is not used elsewhere.

The State Plane Coordinate System

The State Plane coordinate system is a collection of transformations, each of which is to be used in mapping a particular limited area (zone) of the U.S. There is at least one such transformation for each of the fifty states (up to ten for some of the larger states), plus a few for some U.S. possessions like American Samoa and Puerto Rico. Each of the transformations provides a relatively distortion-free representation of the particular zone for which it is meant to be used.

There are two different versions of the State Plane system, an older one based on the "North American datum of 1927 (NAD27)", which uses the "Clarke 1866" spheroid, and a newer one based on the "North American datum of 1983 (NAD83)", which uses the "GRS 1980" spheroid. In either version, a four-digit "zone number" specifies the area of interest; for example, zone number "2800" refers to New Hampshire. The sets of zone numbers used in the two versions are similar, but not identical: for example, in both versions, Delaware is zone number "0700", but the older version of Montana is divided into zones "2501", "2502", and "2503" ("North", "Central", and "South"), while the newer version of Montana is just zone number "2500".

The principal projections used by the State Plane system are the Lambert Conformal Conic with two standard parallels and the Transverse Mercator secant to the model of the earth; there is also a single zone for which the Polyconic is used and another for which the Oblique Mercator is used. Distortion in the Lambert Conformal Conic is a function of latitude, but is independent of longitude, so it is used for areas having a greater extent in longitude than in latitude; the scale is true along each of the standard parallels. Similarly, distortion in the Transverse Mercator is a function of longitude, but is independent of latitude, so it is used for areas having a greater extent in latitude than in longitude; the scale is true along each of two lines roughly parallel to the central meridian.

For each of the State Plane coordinate zones, projection parameters are defined so that the point having a given latitude and longitude has coordinates X and Y (referred to as the "easting" and "northing", respectively) in the projection space; X and Y are measured in meters. The coordinates are offset by addition of a "false easting" and a "false northing" which are defined in such a way as to make the coordinates of all points within the area of interest be positive.

When one calls MDUTIN to initialize the USGS package for a particular State Plane zone without specifying the ranges of X and Y coordinates to be displayed, the routine sets those ranges in such a way as to show the approximate intended extent of that zone. The EZMAP demo program can be made to draw plots of the State Plane zones in a specified area.

ROUTINES

This section describes all the user-callable routines of EZMAP. The descriptions are arranged in functional order; for an alphabetical listing, see the index (above).

PRINCIPAL ROUTINES

MAPDRW
MDPDRW

(Note that these routines are equivalent; MAPDRW just calls MDPDRW.)

Draws a complete map, as described by the current values of the internal parameters of EZMAP. Note that this routine uses whichever old outline dataset is selected by the value of the internal parameter 'OU'; to access the new map databases "Earth..1", "Earth..2", and "Earth..3", one must call instead the routines that MDPDRW would have called, but call MDLNDR (which see) instead of MDPLOT.

Usage

Just call it. MDPDRW calls MDPINT (if the value of the internal parameter 'IN' indicates that initialization is required), MDPGRD, MDPLBL, and MDPLOT, in that order.

Users may sometimes wish to call directly the routines that MDPDRW calls. For example, they sometimes want to change the aspect ratio of a map drawn by EZMAP to something other than that implied by the projection selected; in order to do this, it is necessary to put calls to GETSET and SET in between the call to MDPINT and the calls to MDPGRD, MDPLBL, and MDPLOT. This is possible only if the user is calling those routines directly (rather than indirectly, by calling MDPDRW).

See the examples named "mpex01", "mpex02", "mpex04", "mpex05", "mpex06", "mpex07", and "mpex10".

Arguments

None.

MAPINT
MDPINT

(Note that these two routines are equivalent; MAPINT just calls MDPINT.)

An initialization routine. As of early 1999, EZMAP keeps track of its own initialization state and does its own calls to the routine MDPINT. Therefore, it is no longer necessary for a user to call it; however, such a call will do no harm.

Usage

The statement

      CALL MDPINT
initializes the EZMAP package. This is required initially and again after a call to any of the routines MDPPOS, MDPROJ, or MDPSET. The flag 'IN', which may be retrieved by a call to MDGETI or MDGETL, indicates whether or not initialization is required at a given time. As of now (April, 1987), no parameter change by means of a call to MDSETx forces re-initialization; only calls to MDPPOS, MDPROJ, and MDPSET do.

To clarify the use of MDPINT: Once the internal parameters describing a map transformation are completely defined, MDPINT must be called; it computes as many of the transformation parameters as possible, so that, when MDPTRN is called, it can return the u/v coordinates corresponding to a particular lat/lon position as quickly as possible. If the transformation is changed, MDPINT must be re-called before the next call to MDPTRN. Routines which call MDPTRN and therefore depend on MDPINT's having been called are as follows: MDPBLA, MDPFST, MDPGRD, MDPGRM, MDPIQ, MDPIQA, MDPIQM, MDPIT, MDPITA, MDPITM, MDPLBL, MDPLOT, MDPTRA, MDPTRI, MDPVEC, MDLNAM, MDLNDM, MDLNDR, MDRGOL, MDRGSF, and SUPCON. Routines which change the transformation in some way and therefore require MDPINT to be re-called are as follows: MDPPOS, MDPROJ, and MDPSET. If one is just doing a single plot, one does the parameter-setting calls that define the transformation, calls MDPINT to initialize, and then calls the various routines that draw the plot; in this case, a single call to MDPINT is all that is necessary.

One of the things that MDPINT does is call the SPPS routine SET to define the mapping from the u/v (projection) plane to the x/y (plotter) plane, so that u/v coordinates returned by the routines MDPTRA and MDPTRN can be used directly (as "user" coordinates) in calls to other NCAR Graphics routines. The user must be careful not to interfere with this process by doing an inappropriate call to SET in between calling MDPINT and calling other routines that depend on the proper SET call's having been done; if such a call must be done, the routine MDPRS (q.v.) may be used to restore the SET call done by MDPINT.

See the examples named "mpex09", "mpex10", and "eezmpa".

Arguments

None.

MAPGRD
MDPGRD

(Note that these routines are equivalent; MAPGRD just calls MDPGRD.)

Draws a lat/lon grid.

Usage

If the parameter 'GR' has a value greater than zero, the statement

      CALL MDPGRD
draws a grid consisting of lines of latitude (parallels) and lines of longitude (meridians).

In addition to the grid, MDPGRD also draws the limb line (if any) of the current projection. For more information about limb lines, see the description of the routine MDPLMB.

If EZMAP needs initialization or if there is an uncleared NCAR Graphics error or if the parameter 'GR' is less than or equal to zero, MDPGRD does nothing.

The grid is drawn using calls to MDPIT and MDPIQ. By default, MDPGRD forces the value of the internal parameter 'DL' to zero, so that the grid will be drawn using calls to the routines FRSTD and VECTD, in the dash package. MDPGRD also calls the dash-package routine DASHDB to force the current dash pattern to the value specified by the internal parameter 'DA'. Before returning control to the user, MDPGRD restores the original value of 'DL' and the original dash pattern. A user version of one of the routines MAPUSR or MDPUSR may be supplied to change the way in which the grid lines are drawn (as shown in the example "mpex09").

The values of the parameters 'GP', 'GN', and 'GT' also affect the drawing of the grid.

Arguments

None.

MAPLBL
MDPLBL

(Note that these routines are equivalent; MAPLBL just calls MDPLBL.)

Labels the map.

Usage

The statement

      CALL MDPLBL
if the parameter 'LA' is set appropriately, labels the international date line (ID), the equator (EQ), the Greenwich Meridian (GM), and the poles (NP and SP), and, if the parameter 'PE' is set appropriately, draws the perimeter of the map. If EZMAP needs initialization or if there is an uncleared NCAR Graphics error, MDPLBL does nothing.

See the example named "eezmpa".

Arguments

None.

MAPLOT
MDPLOT

(Note that these routines are equivalent; MAPLOT just calls MDPLOT.)

Draws geographical outlines. Note that this routine uses whichever old outline dataset is selected by the value of the internal parameter 'OU'; to access the new map databases "Earth..1", "Earth..2", and "Earth..3", one must call instead the EZMAPB routine MDLNDR.

Usage

The statement

      CALL MDPLOT
draws the continental and/or international and/or U.S. state outlines selected by the EZMAP parameter 'OU'; the parameter 'DO' determines whether solid lines or dotted lines are used.

If the internal parameter 'GR' has been given a negative value, MDPLOT will also draw the limb line (if any) of the current projection. For more information about limb lines, see the description of the routine MDPLMB.

If EZMAP currently needs initialization or if there is an uncleared NCAR Graphics error, MDPLOT does nothing.

The outlines are drawn using calls to MAPIT and MAPIQ, which call MDPIT and MDPIQ, respectively. By default, MDPLOT forces the value of the internal parameter 'DL' equal to the value of the internal parameter 'DO'; it also supplies the dash package with a solid-line dash pattern. When 'DO' is zero, the outlines are drawn using calls to the routines FRSTD and VECTD, in the dash package, and this gives solid lines. When 'DO' is non-zero, the outlines are drawn using calls to the SPPS routine POINTS, which gives dotted lines. Before returning control to the user, MDPLOT restores the original value of 'DL' and the original dash pattern. A user version of the routine MDPUSR may be supplied to change the way in which the outlines are drawn (as shown in the example "mpex09").

See the examples named "mpex09" and "eezmpa".

Arguments

None.

PARAMETER-ACCESS ROUTINES

MAPPOS (XLOW,XROW,YBOW,YTOW)
MDPPOS (XLOW,XROW,YBOW,YTOW)

(Note that MAPPOS has four arguments of type REAL and MDPPOS has four arguments of type DOUBLE PRECISION; MAPPOS is actually implemented by calling MDPPOS.)

Positions the map on the plotter frame.

Usage

The statement

      CALL MDPPOS (XLOW,XROW,YBOW,YTOW)
sets four EZMAP parameters specifying the position of a window in the plotter frame within which maps are to be drawn. Each of the arguments is between 0. and 1., inclusive, and specifies the position of one edge of the window, as a fraction of the distance from left to right, or from bottom to top, across the window. The map is centered within the window and made as large as possible, but maintains its intrinsic shape (aspect ratio).

If it is desired to give a map a different aspect ratio than that implied by the projection being used, it will be necessary to insert, immediately after the call to MDPINT, an appropriate call to SET to override the one done by MDPINT and therefore to specify precisely the mapping of the u/v plane into a desired viewport on the plotter frame. Typically, one might call GETSET to find out what arguments 5-8 should be in one's own call to SET. Note that, if MDPDRW is being called, that call will have to be replaced by calls directly to MDPINT, MDPGRD, MDPLBL, and MDPLOT, in order to allow one's own call to SET to be placed immediately after the call to MDPINT.

See the examples named "mpex04", "mpex05", "mpex06", and "mpex07".

Arguments

XLOW (an input expression, of type REAL or DOUBLE PRECISON, depending on which routine is called ) specifies the position of the left edge of the window. The default is .05.

XROW (an input expression, of type REAL or DOUBLE PRECISON, depending on which routine is called) specifies the position of the right edge of the window. The default is .95.

YBOW (an input expression, of type REAL or DOUBLE PRECISON, depending on which routine is called) specifies the position of the bottom edge of the window. The default is .05.

YTOW (an input expression, of type REAL or DOUBLE PRECISON, depending on which routine is called) specifies the position of the top edge of the window. The default is .95.

MAPROJ (JPRJ,PLAT,PLON,ROTA)
MDPROJ (JPRJ,PLAT,PLON,ROTA)

(Note that the MAPROJ has three arguments of type REAL and MDPROJ has three arguments of type DOUBLE PRECISION; MAPROJ is actually implemented by calling MDPROJ.)

Set the projection to be used.

Usage

The statement

      CALL MDPROJ (JPRJ,PLAT,PLON,ROTA)
sets EZMAP parameters specifying the projection to be used for subsequent maps.

See the examples named "mpex01", "mpex02", "mpex04", "mpex05", "mpex06", "mpex07", "mpex09", "mpex10", and "eezmpa".

Arguments

JPRJ (an input expression, of type CHARACTER) defines the desired projection type. All the possible values are two characters in length; these are the possibilities:

The conic projection:

The azimuthal projections:

The cylindrical projections:

The USGS transformations:

Note: The orthographic and satellite-view projections have the same internal identifier. The EZMAP parameter 'SA' determines which will be used. If a call to MDPROJ selecting one of them is followed by a call to MDSETR or MDSETD resetting 'SA', it may have the effect of causing the other to be used. See the description of the internal parameter 'SA', below.

PLAT, PLON, and ROTA (input expressions, of type REAL or DOUBLE PRECISION, depending on which routine is called) are angular quantities, in degrees. How they are used depends on the value of JPRJ, as follows:

For more detailed descriptions of the projections, see the section named "PROJECTIONS".

MAPSET (JLTS,PLM1,PLM2,PLM3,PLM4)
MDPSET (JLTS,PLM1,PLM2,PLM3,PLM4)

(Note that the MAPSET has four dimensioned arguments of type REAL and MDPSET has four dimensioned arguments of type DOUBLE PRECISION; MAPSET is actually implemented by calling MDPSET.)

To set internal parameters specifying the rectangular portion of the u/v plane to be drawn.

Usage

The statement

      CALL MDPSET (JLTS,PLM1,PLM2,PLM3,PLM4)
specifies what portion of the u/v plane is to be drawn.

See the examples named "mpex01", "mpex02", "mpex04", "mpex07", "mpex09", "mpex10", and "eezmpa".

Arguments

JLTS (an input expression, of type CHARACTER) is a character string specifying how the limits of the map are to be chosen. There are five possibilities, as follows:

PLM1, PLM2, PLM3, and PLM4 (input arrays, dimensioned 2, of type REAL or DOUBLE PRECISION, depending on which routine is called) are as described above, depending on the value of JLTS. Note that each is a two-element array. Strictly speaking, the FORTRAN standard requires that they be declared as such, even when only the first element of each array is used.

MAPSTx (PNAM,xVAL)
MPSETx (PNAM,xVAL)
MDSETx (PNAM,xVAL)

(Note that, although, for a given value of "x", MAPSTx, MPSETx, and MDSETx are equivalent, the first two are implemented by calling the third.)

To set the values of internal parameters of EZMAP.

Usage

Use one of the four statements

      CALL MAPSTC (PNAM,CVAL) or CALL MPSETC (PNAM,CVAL) or CALL MDSETC (PNAM,CVAL)
      CALL MAPSTI (PNAM,IVAL) or CALL MPSETI (PNAM,IVAL) or CALL MDSETI (PNAM,IVAL)
      CALL MAPSTL (PNAM,LVAL) or CALL MPSETL (PNAM,LVAL) or CALL MDSETL (PNAM,LVAL)
      CALL MAPSTR (PNAM,RVAL) or CALL MPSETR (PNAM,RVAL) or CALL MDSETR (PNAM,RVAL)
      CALL MAPSTD (PNAM,DVAL) or CALL MPSETD (PNAM,DVAL) or CALL MDSETD (PNAM,DVAL)
depending on whether the value to be set is of type CHARACTER, INTEGER, LOGICAL, REAL, or DOUBLE PRECISION. Some parameters may be set in more than one way. For example, the parameter 'GR', which specifies the grid spacing, may be given the value 10.0 in either of three ways:

      CALL MDSETI ('GR',10)
      CALL MDSETR ('GR',10.)
      CALL MDSETD ('GR',10.D0)
The flag which controls dotting of outlines may be turned on using either of these calls:

      CALL MDSETI ('DO',1)
      CALL MDSETL ('DO',.TRUE.)
The important point to remember is that the last character of the routine name implies the type of its second argument.

See the examples named "mpex01", "mpex02", "mpex04", "mpex05", "mpex06", "mpex07", "mpex08", "mpex09", "mpex10", "mpexfi", and "eezmpa".

Arguments

PNAM (an input expression, of type CHARACTER*2) specifies the name of an internal parameter whose value is to be set. Only the first two characters of this string are examined.

xVAL (an input expression of type CHARACTER, INTEGER, LOGICAL, REAL, or DOUBLE PRECISION, depending on which routine is called) contains the value to be given to the parameter specified by PNAM.

See the section "INTERNAL PARAMETERS" for descriptions of all the internal parameters.

MAPGTx (PNAM,xVAL)
MPGETx (PNAM,xVAL)
MDGETx (PNAM,xVAL)

(Note that, although, for a given value of "x", MAPGTx, MPGETX, and MDGETx are equivalent, the first two are implemented by calling the third.)

Gets the current value of a specified EZMAP parameter.

Usage

Use one of the statements

      CALL MAPGTC (PNAM,CVAL) or CALL MPGETC (PNAM,CVAL) or CALL MDGETC (PNAM,CVAL)
      CALL MAPGTI (PNAM,IVAL) or CALL MPGETI (PNAM,IVAL) or CALL MDGETI (PNAM,IVAL)
      CALL MAPGTL (PNAM,LVAL) or CALL MPGETL (PNAM,LVAL) or CALL MDGETL (PNAM,LVAL)
      CALL MAPGTR (PNAM,RVAL) or CALL MPGETR (PNAM,RVAL) or CALL MDGETR (PNAM,RVAL)
      CALL MAPGTD (PNAM,DVAL) or CALL MPGETD (PNAM,DVAL) or CALL MDGETD (PNAM,DVAL)
depending on whether the value to be retrieved is of type CHARACTER, INTEGER, LOGICAL, REAL, or DOUBLE PRECISION. The values of some parameters may be retrieved in more than one way. For example, the value of the initialization flag may be retrieved as a logical quantity (.TRUE. or .FALSE.) or as an integer (non-zero or zero).

See the examples named "mpex07" and "mpex08".

Arguments

PNAM (an input expression of type CHARACTER) specifies the name of the parameter to get. Only the first two characters of the string are examined. See the section "INTERNAL PARAMETERS" for a list of all the internal parameters whose values may be retrieved.

xVAL (an output variable of type CHARACTER, INTEGER, LOGICAL, REAL, or DOUBLE PRECISION, depending on which routine is called) receives the value of the parameter specified by PNAM.

MPRSET
MDRSET

(Note that these routines are equivalent; MPRSET just calls MDRSET.)

Resets the internal state of EZMAP to the default.

Usage

The statement 

      CALL MDRSET
may be used to reset the values of all the internal parameters of EZMAP to their defaults and then recall the initialization routine MDPINT.

Arguments

None.

MAPSAV (IFNO)
MDPSAV (IFNO)

(Note that these routines are equivalent; MAPSAV just calls MDPSAV with the specified argument.)

Saves the current state of EZMAP for later restoration by MDPRST.

Usage

The statement

      CALL MDPSAV (IFNO)
saves the current state of EZMAP by writing, on the unit specified by IFNO, the current values of all the user-settable parameters.

No example is available for MDPSAV.

Arguments

IFNO (an input expression, of type INTEGER) is the number of a unit to which a single unformatted record is to be written. It is the user's responsibility to position this unit. MDPSAV does not rewind it, either before or after writing the record.

MAPRST (IFNO)
MDPRST (IFNO)

(Note that these routines are equivalent; MAPRST just calls MDPRST with the specified argument.)

Restores the state of EZMAP saved by an earlier call to MDPSAV.

Usage

The statement

      CALL MDPRST (IFNO)
restores EZMAP to a previously saved state by reading, from the unit specified by IFNO, values of all user-settable parameters, and then executing MDPINT.

No example is available for MDPRST.

Arguments

IFNO (an input expression, of type INTEGER) is the number of a unit from which a single unformatted record is to be read. It is the user's responsibility to position this unit. MDPRST does not rewind it, either before or after reading the record.

BASIC PROJECTION ROUTINES

MAPTRN (RLAT,RLON,UVAL,VVAL)
MDPTRN (RLAT,RLON,UVAL,VVAL)

(Note that MAPTRN has arguments of type REAL and MDPTRN has arguments of type DOUBLE PRECISION; MAPTRN is actually implemented by calling MDPTRN.)

To project points.

Usage

The statement

      CALL MDPTRN (RLAT,RLON,UVAL,VVAL)
may be used to find the projection in the u/v plane of a point whose latitude and longitude are known. MDPTRN may be called at any time after EZMAP has been initialized (by calling MDPINT or otherwise).

See the example named "mpex09".

Arguments

RLAT and RLON (input expressions, of type REAL or DOUBLE PRECISION, depending on which routine is called) are the latitude and longitude, respectively, of a point on the globe. RLAT must be between -90. and +90., inclusive; RLON must be between -540. and +540., inclusive.

UVAL and VVAL (output variables, of type REAL or DOUBLE PRECISION, depending on which routine is called) define the point (UVAL,VVAL) that is the projection in the u/v plane of (RLAT,RLON). The units of UVAL and VVAL depend on the projection.

If the point is not projectable, UVAL is returned equal to 1.E12 or 1.D12, depending on which routine is called. Note that, if the point is projectable, but outside the boundary of the map, as defined by the last call to MDPSET, its u and v coordinates are still returned by MDPTRN. The user must do the test required to determine if the point is within limits, if that is necessary.

MAPTRA (RLAT,RLON,UVAL,VVAL)
MDPTRA (RLAT,RLON,UVAL,VVAL)

(Note that MAPTRA has arguments of type REAL and MDPTRA has arguments of type DOUBLE PRECISION; MAPTRA is actually implemented by calling MDPTRA.)

To project points.

MDPTRA is just like MDPTRN except that, if a point being projected is outside the boundary of the map (as defined by the last call to MDPSET and by the value of the internal parameter 'EL'), a special value is returned to signal this condition; see the sub-section named "Arguments", below. (The default version of the CONPACK routine named CPMPXY now calls MAPTRA, rather than MAPTRN; it was for this purpose that MAPTRA and MDPTRA were created, but users may wish to call them, as well.)

Usage

The statement

      CALL MDPTRA (RLAT,RLON,UVAL,VVAL)
may be used to find the projection in the u/v plane of a point whose latitude and longitude are known. MDPTRA may be called at any time after EZMAP has been initialized (by calling MDPINT or otherwise).

Currently, no example is available for MDPTRA.

Arguments

RLAT and RLON (input expressions, of type REAL or DOUBLE PRECISION, depending on which routine is called) are the latitude and longitude, respectively, of a point on the globe. RLAT must be between -90. and +90., inclusive; RLON must be between -540. and +540., inclusive.

UVAL and VVAL (output variables, of type REAL or DOUBLE PRECISION, depending on which routine is called) define the point (UVAL,VVAL) that is the projection in the u/v plane of (RLAT,RLON). The units of UVAL and VVAL depend on the projection.

If the point is not projectable or if it is outside the boundary of the map, as defined by the last call to MDPSET and by the value of the parameter 'EL', UVAL is returned equal to 1.E12 or 1.D12, depending on which routine is called.

MAPTRI (UVAL,VVAL,RLAT,RLON)
MDPTRI (UVAL,VVAL,RLAT,RLON)

(Note that MAPTRI has arguments of type REAL and MDPTRI has arguments of type DOUBLE PRECISION; MAPTRI is actually implemented by calling MDPTRI.)

To perform inverse transformations.

Usage

The statement

      CALL MDPTRI (UVAL,VVAL,RLAT,RLON)
is used to find the latitude and longitude of a point whose projection in the u/v plane is known. MDPTRI may be called at any time after EZMAP has been initialized (by calling MDPINT or otherwise).

See the example named "mpex10".

Arguments

UVAL and VVAL (input expressions, of type REAL or DOUBLE PRECISION, depending on which routine is called) define the point (UVAL,VVAL) that is the projection in the u/v plane of the point whose latitude and longitude are desired. The units of UVAL and VVAL depend on the projection.

RLAT and RLON (output variables, of type REAL or DOUBLE PRECISION ) are the latitude and longitude, respectively, of the point, in degrees. RLAT will be between -90. and +90., inclusive; RLON will be between -180. and +180., inclusive.

If the point (UVAL,VVAL) is not the projection of some point of the globe or is outside the boundary of the map, RLAT and RLON are returned equal to 1.E12 or 1.D12, depending on which routine is called.

DRAWING ROUTINES

MAPFST (RLAT,RLON)
MDPFST (RLAT,RLON)

(Note that MAPFST has lat/lon arguments of type REAL and MDPFST has lat/lon arguments of type DOUBLE PRECISION. Both are implemented by calling MDPIT.)

Draws lines on a map - used in conjunction with MDPVEC.

Usage

The statement

      CALL MDPFST (RLAT,RLON)
is equivalent to the statement

      CALL MDPIT (RLAT,RLON,0)
See the description of MDPIT.

Arguments

RLAT and RLON (input expressions of type REAL or DOUBLE PRECISION, depending on which routine is called) are defined in the same way as for MDPIT.

MAPVEC (RLAT,RLON)
MDPVEC (RLAT,RLON)

(Note that both of these routines are implemented by calling MDPIT, and that there may be some advantage in calling that routine directly.)

Draws lines on a map - used in conjunction with MDPFST.

Usage

The statement

      CALL MDPVEC (RLAT,RLON)
is equivalent to the statement

      CALL MDPIT (RLAT,RLON,1)
See the description of MDPIT.

Arguments

RLAT and RLON (input expressions, of type REAL or DOUBLE PRECISION, depending on which routine is called) are defined as for MDPIT.

MAPIT (RLAT,RLON,IFST)
MDPIT (RLAT,RLON,IFST)

(Note that MAPIT has lat/lon arguments of type REAL and MDPIT has lat/lon arguments of type DOUBLE PRECISION; MAPIT is actually implemented by calling MDPIT.)

Draws lines on a map.

Usage

MDPIT is used to draw lines on a map; it is called by various EZMAP routines (MDPLOT, MDPGRD, MDPVEC, and MDLNDR) and may also be called directly by the user. MDPIT attempts to omit non-visible portions of lines and to handle "cross-over" - a jump from one end of the map to the other caused by the projection's having slit the globe along some half of a great circle and laid it open with the two sides of the slit at opposite ends of the map. Cross-over can occur on cylindrical and conical projections; MDPIT handles it gracefully on the former and not quite so well on the latter.

The EZMAP parameter 'DL' determines whether MDPIT draws solid lines or dotted lines. Dotted lines are drawn using calls to POINTS. Solid lines are drawn using calls to DASHD, FRSTD, and VECTD. The EZMAP parameters 'DD' and 'MV' also affect MDPIT's behavior. See the description of these parameters in the section "INTERNAL PARAMETERS".

A sequence of calls to MDPIT should be followed by a call to MDPIQ to flush its buffers before a STOP, a CALL FRAME, or a call to change the color index, line width, dash pattern, or the like.

Beware of intermingling calls to MDPIT and calls to MDPITD; the two routines share buffer space and intermingling the calls will have undesirable effects.

Because the entire line segment joining the points in two contiguous pen-down calls to MDPIT is considered visible if both of the points are visible and invisible if both of the points are invisible, such points should not be too far apart on the globe.

See the example named "mpexfi".

Arguments

RLAT and RLON (input expressions, of type REAL or DOUBLE PRECISION, depending on which routine is called) specify the latitude and longitude of a point to which the "pen" is to be moved. Both are given in degrees. RLAT must be between -90. and +90., inclusive; RLON must be between -540. and +540., inclusive.

IFST (an input expression, of type INTEGER) is 0 to do a "pen-up" move, 1 to do a "pen-down" move only if the distance from the last point to the new point is greater than 'MV' plotter units, and 2 or greater to do a "pen-down" move regardless of the distance from the last point to the new one.

MAPIQ
MDPIQ

(Note that these routines are equivalent; MAPIQ just calls MDPIQ.)

Terminate a string of calls to MDPIT.

Usage

The statement

      CALL MDPIQ
flushes MDPIT's buffers. It is particularly important that this be done before a STOP or a CALL FRAME and before changing the color index, dash pattern, etc.

See the description of MDPIT.

See the example named "mpexfi".

Arguments

None.

MAPITD (RLAT,RLON,IFST)
MDPITD (RLAT,RLON,IFST)

(Note that the MAPITD has lat/lon arguments of type REAL and MDPITD has lat/lon arguments of type DOUBLE PRECISION; MAPITD is actually implemented by calling MDPITD.)

Draws lines on a map using the new dash package DASHPACK.

Usage

MDPITD is used to draw lines on a map; it is not called by any of the EZMAP routines, but is intended to be called directly by the user. MDPITD is just like MDPIT except that it uses the new dash package DASHPACK instead of the old DASHCHAR; it attempts to omit non-visible portions of lines and to handle "cross-over" - a jump from one end of the map to the other caused by the projection's having slit the globe along some half of a great circle and laid it open with the two sides of the slit at opposite ends of the map. Cross-over can occur on cylindrical and conical projections; MDPITD handles it gracefully on the former and not quite so well on the latter.

The EZMAP parameter 'DL' determines whether MDPITD draws solid lines or dotted lines. Dotted lines are drawn using calls to POINTS. Solid lines are drawn using calls to DPFRST, DPVECT, and DPLAST. The EZMAP parameters 'DD' and 'MV' also affect MDPITD's behavior. See the descriptions of these parameters in the section "INTERNAL PARAMETERS".

A sequence of calls to MDPITD should be followed by a call to MDPIQD to flush its buffers before a STOP, a CALL FRAME, or a call to change the color index, line width, dash pattern, or the like.

Beware of intermingling calls to MDPIT and calls to MDPITD; the two routines share buffer space and intermingling the calls will have undesirable effects.

Because the entire line segment joining the points in two contiguous pen-down calls to MDPITD is considered visible if both of the points are visible and invisible if both of the points are invisible, such points should not be too far apart on the globe.

Arguments

RLAT and RLON (input expressions, of type REAL or DOUBLE PRECISION, depending on which routine is called) specify the latitude and longitude of a point to which the "pen" is to be moved. Both are given in degrees. RLAT must be between -90. and +90., inclusive; RLON must be between -540. and +540., inclusive.

IFST (an input expression, of type INTEGER) is 0 to do a "pen-up" move, 1 to do a "pen-down" move only if the distance from the last point to the new point is greater than 'MV' plotter units, and 2 or greater to do a "pen-down" move regardless of the distance from the last point to the new one.

MAPIQD
MDPIQD

(Note that these routines are equivalent: MAPIQD just calls MDPIQD.)

Terminate a string of calls to MDPITD.

Usage

The statement

      CALL MDPIQD
flushes MDPITD's buffers. It is particularly important that this be done before a STOP or a CALL FRAME and before changing the color index, dash pattern, etc.

See the description of MDPITD.

Arguments

None.

MAPGCI (ALAT,ALON,BLAT,BLON,NOPI,RLTI,RLNI)
MDPGCI (ALAT,ALON,BLAT,BLON,NOPI,RLTI,RLNI)

(Note that MAPGCI has arguments of type REAL and MDPGCI has arguments of type DOUBLE PRECISION.)

Calculates the latitudes and longitudes of points on the shorter of the great circle routes between two given points on the surface of the globe.

Usage

Each of the statements

      CALL MAPGCI (ALAT,ALON,BLAT,BLON,NOPI,RLTI,RLNI)
      CALL MDPGCI (ALAT,ALON,BLAT,BLON,NOPI,RLTI,RLNI)
defines the positions of two points, A and B, on the globe and the number of equally-spaced points, NOPI, to be interpolated along the shorter of the great circle routes from A to B. The latitudes and longitudes of the interpolated points are returned to the caller in the arrays RLTI and RLNI. If the points A and B are exactly opposite one another on the globe, the code does not fail, but the direction of the great circle route will be somewhat unpredictable.

Arguments

ALAT and ALON (input expressions of type REAL or DOUBLE PRECISION, depending on which routine is called) specify the latitude and longitude of the point A.

BLAT and BLON (input expressions of type REAL or DOUBLE PRECISION, depending on which routine is called) specify the latitude and longitude of the point B.

NOPI (an input expression of type INTEGER) specifies the number of equally-spaced points to be interpolated along the shorter of the great circle route from A to B.

RLTI and RLNI (output arrays of type REAL or DOUBLE PRECISION, depending on which routine is called, each dimensioned at least NOPI) are the latitudes and longitudes of the interpolated points. Each lat/lon pair defines one of the interpolated points; the points are in order of increasing distance from A. The positions of the points A and B themselv