ncl_ezmap - Man Page

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.

The man page ncl_ezmapa(3) is an alias of ncl_ezmap(3).