EZMAP - Allows one to plot maps of the earth according to any of
ten different projections, with parallels, meridians, and continental,
international, and/or U.S. state outlines.
EZMAPA is the name of a supplement to the EZMAP utility that
allows users to produce solid-filled maps of the earth. The EZMAPA routines
are discussed as part of the EZMAP utility.
EZMAPB is the name of a supplement to the EZMAP utility that
provides access to improved map databases (principally one called
"Earth..1", which contains a unified higher-resolution version of
everything that was in the old outline datasets). The EZMAPB routines are
discussed as part of the EZMAP utility.
- 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), one need only execute the single FORTRAN statement "CALL
MAPDRW":
- •
- MAPDRW - Draws a complete simple map.
-
- All that MAPDRW does is call four lower-level routines. In some
situations, the user may wish to call these routines directly; they are as
follows (in the order in which they are called by MAPDRW):
- MAPINT - Initializes. MAPINT must be called at least once before calling
any routine that depends on mapping lat/lon coordinates into u/v
coordinates. After one or more of MAPPOS, MAPROJ, and MAPSET has been
called, MAPINT must be called again. MAPINT does the call to the SPPS
routine SET that defines the mapping from the u/v (projection) plane to
the x/y (plotter) plane.
- MAPGRD - Draws selected parallels and meridians.
- MAPLBL - Labels the international date line, the equator, the Greenwich
meridian, and the poles, and draws the perimeter.
- MAPLOT - Draws selected geographic 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 database "Earth..1", which
was created in 1998, one must call instead the EZMAPB routine MPLNDR.
- 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:
- MAPPOS - Determines what portion of the plotter frame is to be used.
- MAPROJ - Determines the projection to be used.
- MAPSET - Determines what portion of the u/v plane is to be viewed.
- MAPSTC - Sets a parameter value of type CHARACTER.
- MAPSTI - Sets a parameter value of type INTEGER.
- MAPSTL - Sets a parameter value of type LOGICAL.
- MAPSTR - Sets a parameter value of type REAL.
- Routines Used to
Retrieve the Values of Internal Parameters
-
The following routines are used to retrieve the current values
of EZMAP parameters:
- MAPGTC - Gets a parameter value of type CHARACTER.
- MAPGTI - Gets a parameter value of type INTEGER.
- MAPGTL - Gets a parameter value of type LOGICAL.
- MAPGTR - Gets a parameter value of type REAL.
- Routines Used to
Save and Restore Internal Parameters
-
To save/restore the current values of the internal parameters
of EZMAP, use the following:
- MAPSAV - Saves the values (by writing a record on a user-specified
unit).
- MAPRST - Restores saved values (by reading a record from a user-specified
unit).
- Routines Used to
Draw Objects on a Map
-
To draw objects on the map, use the following routines:
- MAPTRA - Computes the u/v coordinates of a point from its latitude and
longitude. If the point is unprojectable or its projection lies outside
the current perimeter, a special value is returned to signal this.
- MAPTRN - Computes the u/v coordinates of a point from its latitude and
longitude. If the point is unprojectable, a special value is returned to
signal this, but no check is made for the projected value being outside
the perimeter.
- MAPFST - Does a "pen-up" move defining the start of a line to be
projected and drawn. The line is defined by a series of lat/lon
coordinates.
- MAPVEC - Does a "pen-down" move defining the continuation of a
line to be projected and drawn. The line is defined by a series of lat/lon
coordinates.
- MAPIT - Does "pen-up" or "pen-down" moves. This
routine is called by MAPFST and MAPVEC.
- MAPIQ - Signals the end of a string of calls to MAPIT and causes its
buffers to be flushed.
- MAPGCI - Given the latitudes and longitudes of two points on the surface
of the globe, this routine returns the latitudes and longitudes of a
specified number of points along the great circle route joining them.
- Routines Used to
Do Inverse Transformations
-
The following routine was added to EZMAP early in 1992:
- •
- MAPTRI - Computes the latitude and longitude of a point from its u/v
coordinates. If the point is outside the boundary of the map, a special
value is returned.
-
- 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 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 in
this package are really 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 routines of EZMAPA 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:
- MAPBLA - Adds boundary lines to an existing area map. Routines in the
package AREAS may then be used to process that area map in various ways.
(Example: drawing a map of Europe with each country in a different color.)
Note that this routine uses whichever old outline dataset is selected by
the value of the internal parameter 'OU'; to access the new map database
"Earth..1", which was created in 1998, one must call instead the
EZMAPB routine MPLNAM.
- MAPBLM - Draws boundary lines "masked" by an existing area map.
(Example: drawing these lines only where they do not overlay CONPACK
labels.) Note that this routine uses whichever old outline dataset is
selected by the value of the internal parameter 'OU'; to access the new
map database "Earth..1", which was created in 1998, one must
call instead the EZMAPB routine MPLNDM.
- MAPGRM - Draws lines of latitude and longitude "masked" by an
existing area map. (Example: drawing these lines over water, but not over
land.)
- MAPITA and MAPIQA - Adds to an area map the projections of arbitrary lines
defined by lat/lon coordinates of points on the surface of the globe.
MAPBLA uses these routines to add boundary lines to an area map; they may
be called directly by the user to add his/her own set of boundary lines to
the area map.
- MAPITM and MAPIQM - Draws, masked by an area map, the projections of
arbitrary lines defined by lat/lon coordinates of points on the surface of
the globe. MAPGRM uses these routines to draw masked lines of latitude and
longitude; they may be called directly by the user to draw other masked
lines.
- MAPACI - A function which, given the "area identifier" for a
particular area defined by the boundaries in one of the old EZMAP outline
datasets, returns a suggested color index for that area; it is guaranteed
that, if the suggested color indices are used, no two areas having a
boundary in common will have the same color. Note that this function
should not be used to select color indices for areas defined by the new
map database "Earth..1", which was created in 1998; for that
purpose, use EZMAPB functions instead (in particular, MPISCI).
- 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.
Each area defined by the database has 1) a "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 (so far, no counties are included).
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:
- MPLNAM (MaP LiNes, to Area Map) - A routine to extract boundary lines from
a specified database and send them to an area map.
- MPLNDM (MaP LiNes, Draw Masked) - A routine to extract boundary lines from
a specified database and draw them, masked by the contents of an area
map.
- MPLNDR (MaP LiNes, Draw) - A routine to extract boundary lines from a
specified database and draw them.
- MPLNRI - A routine to force the reading of certain information from a
database into labelled COMMON blocks inside EZMAP, so that subsequent
references to some of the functions described below will have that
information to work with. (Each of the routines MPLNAM, MPLNDM, and MPLNDR
reads this data as a side effect; MPLNRI is provided for use in cases in
which none of the other three routines has yet been called.)
-
- As each of the EZMAPB routines MPLNAM, MPLNDM, and MPLNDR processes
boundary lines from a specified database, it calls an EZMAPB routine named
MPCHLN (the default version of which does nothing):
- •
- MPCHLN - A user-replaceable routine that can be made to change line style,
color, line width, and so on as the boundary lines from a database are
being drawn; it can also be made to delete particular lines or to change
the area identifiers associated with them. The arguments of MPCHLN tell it
which of the EZMAPB routines is calling it and whether it's being called
before or after the line is processed; they also supply the "line
type" of the line being drawn, the area identifiers of the areas on
either side of it, and the actual coordinates defining the line. Line
types are similar to area types (1 => land/water, 2 => continents, 3
=> countries, 4 => states, and 5 => counties).
-
- Another EZMAPB routine, named MPGLTY, may be called by the user from
within the line-processing routine specified by the final argument in a
call to MPLNDM:
- •
- MPGLTY - Retrieves the line type of the line being drawn.
-
- 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 MPLNAM, MPLNDM, MPLNDR, or MPLNRI),
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:
- MPIPAI - A function whose value is non-zero if and only if the area with a
specified area identifier is part of the area having a second specified
area identifier.
- MPIPAN - A function whose value is non-zero if and only if the area with a
specified area identifier is part of the area having a specified
name.
- MPIOAR - A function whose value is the area identifier of the smallest
area that is defined at or above a specified level in the area hierarchy
and of which the area having a specified area identifier is a part.
- MPIATY - A function whose value is the type of the area having a specified
area identifier.
- MPIPAR - A function whose value is the area identifier of the parent of
the area having a specified area identifier.
- MPISCI - A function whose value is the suggested color index for an area
having a specified area identifier.
- MPNAME - A function whose value is the name of the area having a
particular area identifier.
- MPFNME - A function whose value is the full name of the area having a
specified area identifier, up to a specified level in the hierarchy of
areas; the full name of an area consists of its own name, preceded by the
name of its parent, preceded by the name of its parent's parent, and so
on; the various components of the name are separated by the 3-character
string ' - ' (a blank, a dash, and another blank).
-
- Two additional EZMAPB functions are provided; these have nothing to do
with mapping, really, but can be useful in dealing with character
strings:
- MPIFNB - A function whose value is the index of the first non-blank
character in a character string.
- MPILNB - A function whose value is the index of the last non-blank
character in a character string.
- Miscellaneous
Other Routines
-
The following EZMAP routines are used for the purposes
stated:
- MAPRS - Re-executes the "CALL SET" done during the last call to
MAPINT. This is useful when there has been an intervening call to a
utility that calls SET. It is quite common for a background drawn by EZMAP
to be placed in a flash buffer (as created by the package
"GFLASH"). When the contents of the flash buffer are copied to
the metafile being created, if it is desired to draw something on the
EZMAP background, MAPRS may first have to be called to ensure that the
correct SET call is in effect.
- MPRST - Resets the internal state of EZMAP/EZMAPA to the default.
- SUPMAP - Draws a map with a single call. An implementation of the routine
from which EZMAP grew.
#include <ncarg/ncargC.h>
c_mapaci
c_mapbla
c_mapdrw
c_mapfst
c_mapgrd
c_mapgrm
c_mapgtc
c_mapgtc
c_mapgti
c_mapgtl
c_mapgtr
c_mapint
c_mapiq
c_mapiqa
c_mapiqm
c_mapit
c_mapita
c_mapitm
c_maplbl
c_maplot
c_mappos
c_maproj
c_maprs
c_maprst
c_mapsav
c_mapset
c_mapstc
c_mapsti
c_mapstl
c_mapstr
c_maptra
c_maptri
c_maptrn
c_mapvec
c_mpfnme
c_mpglty
c_mpiaty
c_mpifnb
c_mpilnb
c_mpiola
c_mpiosa
c_mpipai
c_mpipan
c_mpipar
c_mpisci
c_mplnam
c_mplndm
c_mplndr
c_mplnri
c_mpname
c_mprset
c_supmap
The following EZMAP routines are used for the purposes stated:
- MAPUSR - This routine is called by various EZMAP routines just before and
just after drawing parts of the map. By default, grid lines are drawn
using software dashed lines and geographical outlines are drawn using
either solid lines or dotted lines. The dash pattern used for the grid
lines, the flag which says whether outlines are solid or dotted, and the
color indices of various parts of the map are all user-settable
parameters, but more complete control of color indices, spot size, dash
pattern, etc., may be achieved by supplying one's own version of MAPUSR; a
user version may be as complicated as is required to achieve a desired
effect. Note that this routine is not called by any of the EZMAPB
routines; they call MPCHLN instead.
- MAPEOD - This routine is called by the EZMAP routine MAPLOT and by the
EZMAPA routines MAPBLA and MAPBLM; in each case, it is called once for
each segment in the outline dataset. The user may supply a version which
examines the segment to see if it ought to be plotted and, if not, to
delete it. This can be used (for example) to reduce the clutter in
northern Canada. Note that this routine is not called by any of the EZMAPB
routines; they call MPCHLN instead.
- MPCHLN - This routine is called by the EZMAPB routines MPLNAM, MPLNDM, and
MPLNDR; in each case, it is called just before and just after the
processing of each segment in the map database. The default version does
nothing; a user-supplied version can do for the new databases what MAPUSR
and MAPEOD did for the old ones.
To use EZMAP Fortran or C routines, load the NCAR Graphics
libraries ncarg, ncarg_gks, and ncarg_c, preferably in that order.
When error conditions are detected, the support routine SETER is
called. By default, SETER writes a message to the standard error file (as
defined by I1MACH(4)) and then terminates execution. It is possible to put
SETER into recovery mode and regain control after a recoverable error (which
includes all of the possible errors).
The possible error messages are listed below. All errors are
recoverable in the sense that a user program which has called ENTSR to set
recovery mode will get control back after one of these errors occurs.
MAPBLA - UNCLEARED PRIOR ERROR
MAPCHI - ERROR EXIT FROM GQPLCI
MAPCHI - ERROR EXIT FROM GQPMCI
MAPCHI - ERROR EXIT FROM GQTXCI
MAPDRW - UNCLEARED PRIOR ERROR
MAPFST - UNCLEARED PRIOR ERROR
MAPGCI - UNCLEARED PRIOR ERROR
MAPGRD - UNCLEARED PRIOR ERROR
MAPGRM - UNCLEARED PRIOR ERROR
MAPGTC - UNCLEARED PRIOR ERROR
MAPGTC - UNKNOWN PARAMETER NAME
MAPGTI - UNCLEARED PRIOR ERROR
MAPGTI - UNKNOWN PARAMETER NAME
MAPGTL - UNCLEARED PRIOR ERROR
MAPGTL - UNKNOWN PARAMETER NAME
MAPGTR - UNCLEARED PRIOR ERROR
MAPGTR - UNKNOWN PARAMETER NAME
MAPINT - ANGULAR LIMITS TOO GREAT
MAPINT - ATTEMPT TO USE NON-EXISTENT PROJECTION
MAPINT - MAP HAS ZERO AREA
MAPINT - MAP LIMITS INAPPROPRIATE
MAPINT - UNCLEARED PRIOR ERROR
MAPIO - EOF ENCOUNTERED IN OUTLINE DATASET
MAPIO - ERROR ON READ OF OUTLINE DATASET
MAPIQ - UNCLEARED PRIOR ERROR
MAPIQA - UNCLEARED PRIOR ERROR
MAPIQM - UNCLEARED PRIOR ERROR
MAPIT - UNCLEARED PRIOR ERROR
MAPITA - UNCLEARED PRIOR ERROR
MAPITM - UNCLEARED PRIOR ERROR
MAPLBL - UNCLEARED PRIOR ERROR
MAPLMB - UNCLEARED PRIOR ERROR
MAPLOT - UNCLEARED PRIOR ERROR
MAPPOS - ARGUMENTS ARE INCORRECT
MAPPOS - UNCLEARED PRIOR ERROR
MAPROJ - UNCLEARED PRIOR ERROR
MAPROJ - UNKNOWN PROJECTION NAME
MAPRS - UNCLEARED PRIOR ERROR
MAPRST - EOF ON READ
MAPRST - ERROR ON READ
MAPRST - UNCLEARED PRIOR ERROR
MAPSAV - ERROR ON WRITE
MAPSAV - UNCLEARED PRIOR ERROR
MAPSET - UNCLEARED PRIOR ERROR
MAPSET - UNKNOWN MAP AREA SPECIFIER
MAPSTC - UNCLEARED PRIOR ERROR
MAPSTC - UNKNOWN OUTLINE NAME
MAPSTC - UNKNOWN PARAMETER NAME
MAPSTI - UNCLEARED PRIOR ERROR
MAPSTI - UNKNOWN PARAMETER NAME
MAPSTL - UNCLEARED PRIOR ERROR
MAPSTL - UNKNOWN PARAMETER NAME
MAPSTR - UNCLEARED PRIOR ERROR
MAPSTR - UNKNOWN PARAMETER NAME
MAPTRA - UNCLEARED PRIOR ERROR
MAPTRI - UNCLEARED PRIOR ERROR
MAPTRN - ATTEMPT TO USE NON-EXISTENT PROJECTION
MAPTRN - UNCLEARED PRIOR ERROR
MAPVEC - UNCLEARED PRIOR ERROR
MPGETC - UNCLEARED PRIOR ERROR
MPGETI - UNCLEARED PRIOR ERROR
MPGETL - UNCLEARED PRIOR ERROR
MPGETR - UNCLEARED PRIOR ERROR
MPLNAM - Can't form name of ".names" file
MPLNAM - Can't open the ".lines" file
MPLNAM - Can't open the ".names" file
MPLNAM - Read bad index from ".names" file
MPLNAM - Read error on ".lines" file
MPLNAM - Read error on ".names" file
MPLNAM - UNCLEARED PRIOR ERROR
MPLNDM - Can't form name of ".names" file
MPLNDM - Can't open the ".lines" file
MPLNDM - Can't open the ".names" file
MPLNDM - Read bad index from ".names" file
MPLNDM - Read error on ".lines" file
MPLNDM - Read error on ".names" file
MPLNDM - UNCLEARED PRIOR ERROR
MPLNDR - Can't form name of ".names" file
MPLNDR - Can't open the ".lines" file
MPLNDR - Can't open the ".names" file
MPLNDR - Read bad index from ".names" file
MPLNDR - Read error on ".lines" file
MPLNDR - Read error on ".names" file
MPLNDR - UNCLEARED PRIOR ERROR
MPLNRI - Can't form name of ".names" file
MPLNRI - Can't open the ".names" file
MPLNRI - Read bad index from ".names" file
MPLNRI - Read error on ".names" file
MPLNRI - UNCLEARED PRIOR ERROR
MPRSET - UNCLEARED PRIOR ERROR
MPSETC - UNCLEARED PRIOR ERROR
MPSETI - UNCLEARED PRIOR ERROR
MPSETL - UNCLEARED PRIOR ERROR
MPSETR - UNCLEARED PRIOR ERROR
SUPCON - UNCLEARED PRIOR ERROR
SUPMAP - UNCLEARED PRIOR ERROR
Online: ezmap_params, mapaci, mapbla, mapblm, mapdrw, mapeod,
mapfst, mapgci, mapgrd, mapgrm, mapgtc, mapgti, mapgtl, mapgtr, mapint,
mapiq, mapiqa, mapiqd, mapiqm, mapit, mapita, mapitd, mapitm, maplbl,
maplmb, maplot, mappos, maproj, maprs, maprst, mapsav, mapset, mapstc,
mapsti, mapstl, mapstr, maptra, maptri, maptrn, mapusr, mapvec, mpchln,
mpfnme, mpgetc, mpgeti, mpgetl, mpgetr, mpglty, mpiaty, mpifnb, mpilnb,
mpiola, mpiosa, mpipai, mpipan, mpipar, mpisci, mplnam, mplndm, mplndr,
mplnri, mpname, mprset, mpsetc, mpseti, mpsetl, mpsetr, supmap, supcon,
ncarg_cbind
Hardcopy: NCAR Graphics Contouring and Mapping Tutorial; NCAR
Graphics Fundamentals, UNIX Version
Copyright (C) 1987-2009
University Corporation for Atmospheric Research
The use of this Software is governed by a License Agreement.