Using Ezmap
Previous Chapter Tutorial Home Next Chapter
- Mp 1. What is Ezmap?
- Mp 1.1 Table of Ezmap user entry points
- Single-call entry point
- Map initialization routines
- Latitude, longitude, and limb line drawing routines
- Labeling routine
- Map drawing and control routines
- Positioning routines
- Point and line routines
- Color function
- Inverse transformation routine
- Parameter routines
- Mp 1.2 Table of Ezmap parameters
- Mp 1.3 Table of Ezmap map projections
- Mp 1.4 Description of projections: Conic
- Mp 1.5 Description of projections: Azimuthal
- Mp 1.6 Description of projections: Cylindrical
- Mp 1.7 Producing a quick and dirty plot
- Mp 1.8 What calls do I need to get my Ezmap plot?
- Mp 1.9 Ezmap parameters: What they do and how to use them
- Mp 2. Getting set up
- Mp 2.1 Positioning the plot in the frame
- Mp 2.2 Choosing your map projection
- Mp 2.3 Choosing your map projection: Satellite view
- Mp 2.4 Choosing map outlines to be drawn
- Mp 2.5 Setting limits for the projection
- Mp 2.6 Setting map line colors
- Mp 2.7 Controlling Ezmap lines
- Mp 2.8 Controlling geographic and political outlines
- Mp 2.9 Rectangular and elliptical perimeters
- Mp 2.10 Saving and retrieving Ezmap parameters
- Mp 3. Simple maps
- Mp 3.1 Initializing Ezmap
- Mp 3.2 Grids: Drawing latitude and longitude lines
- Mp 3.3 Grids: Dash patterns
- Mp 3.4 Labeling
- Mp 3.5 Drawing political and geographic outlines
- Mp 3.6 A shortcut
- Mp 4. Producing maps with masking or filled areas
- Mp 4.1 Color and area identifiers in Ezmap
- Mp 4.2 Ezmap group identifiers
- Mp 4.3 Initialize Ezmap with Areas
- Mp 4.4 Labeling
- Mp 4.5 Grid lines with masking
- Mp 4.6 Grid lines with masking: Writing a masking routine
- Mp 4.7 Filling areas
- Mp 4.8 Filling areas: Writing a fill routine
- Mp 5. Points, lines, and inverse transformations
- Mp 5.1 Projecting a point onto the map
- Mp 5.2 Inverse transformations
- Mp 5.3 Drawing lines on a simple map
- Mp 5.4 Drawing a great circle between two points
- Mp 5.5 Adding lines to an area map
- Mp 5.6 Drawing lines masked by an area map
- Mp 6. Table of Ezmap area identifiers
- Mp 7. Ezmap parameter descriptions
Ezmap is a color mapping toolkit you can use to generate ten different projections of the globe with various continental outlines, political boundaries, and optional latitude and longitude lines. Ezmap was previously two utilities, Ezmap and Ezmapa.
The Ezmap utility uses more than one routine to draw maps. The routines listed here cover all Ezmap tasks you may need to perform. This module organizes the routines according to their functions.
- SUPMAP
- Single-call map-drawing routine. See module Mp 1.7.
- MAPINT
- Initializes Ezmap. See modules Mp 3.1 and Mp 4.3.
- MAPBLA
- Adds the geographical map to an area map. See module Mp 4.3.
- MAPGRD
- Draws latitude/longitude grid. See module Mp 3.2.
- MAPGRM
- Draws latitude/longitude grid with masking. See module Mp 4.5.
- MAPLBL
- Labels map. See modules Mp 3.4 and Mp 4.4.
- MAPLOT
- Draws geographical and political outlines. See module Mp 3.5.
- MAPDRW
- Draws a complete map after user sets basic parameters. See module Mp 3.6.
- MAPUSR
- Changes line attributes for various parts of the map. See module Mp 2.7.
- MAPPOS
- Positions map in frame. See module Mp 2.1.
- MAPROJ
- Sets global map projection. See module Mp 2.2.
- MAPSET
- Specifies rectangular portion of the u/v plane to draw. See module Mp 2.5.
- MAPRS
- Re-executes a call to SET. See module Mp 2.10.
- MAPTRA
- Projects points onto a geographic map, returns a special value for points that are unprojectable and for points outside the perimeter. See module Mp 5.1.
- MAPTRN
- Projects points onto a geographic map, returns a special value for points that are unprojectable, but not for points outside the perimeter.
- MAPEOD
- Examines each outline-dataset segment. See module Mp 2.8.
- MAPIT
- Draws a line on a map, omitting nonvisible portions. See module Mp 5.3 .
- MAPIQ
- Terminates a line drawn by MAPIT. See module Mp 5.3.
- MAPITA
- Used to insert a line in an area map. See module Mp 5.5.
- MAPIQA
- Used to terminate insertion of a line in an area map. See module Mp 5.5.
- MAPITM
- Used to draw a masked line. See module Mp 5.6.
- MAPIQM
- Used to terminate drawing of a masked line. See module Mp 5.6 .
- MAPGCI
- Returns points interpolated on a great circle between two points. See module Mp 5.4.
- MAPACI
- Obtains a color index for a given area such that no two adjacent areas have the same color index. See module Mp 4.1.
- MAPTRI
- Computes the latitude and longitude of a point from its u/v coordinates. See module Mp 5.2.
- MAPSAV
- Saves current state. See modules Mp 1.9 and Mp 2.10.
- MAPRST
- Restores state saved by MAPSAV. See modules Mp 1.9 and Mp 2.10.
- MPSETC
- Sets character parameters. See module Mp 1.9.
- MPSETI
- Sets integer parameters. See module Mp 1.9.
- MPSETR
- Sets real parameters. See module Mp 1.9.
- MPGETC
- Gets character parameters. See module Mp 1.9.
- MPGETI
- Gets integer parameters. See module Mp 1.9.
- MPGETR
- Gets real parameters. See module Mp 1.9.
This table is a quick reference guide to the examples in which Ezmap
parameters are used and the modules in which Ezmap parameters are
described. More complete descriptions appear in section "Mp 7. Ezmap parameter
descriptions."
The behavior of a typical routine in an NCAR Graphics utility is
sometimes determined entirely by the routine's arguments, but
frequently it is also affected by the value of one or more of the
utility's parameters. A "parameter" is a variable that
controls the behavior of a utility; parameters are accessed via
parameter-access routines that can set or retrieve the parameter
value.
Instructions for setting and retrieving Ezmap parameters are provided
in module "Mp 1.9 Ezmap parameters: What they do
and how to use them."
----------------------------------------------------------------------------------------
Parameter Brief description Fortran type Examples Module
----------------------------------------------------------------------------------------
AR ARea Character --- Mp 7.
C1 Color index 1 (for perimeter) Integer cmpclr Mp 2.6
C2 Color index 2 (for grid) Integer cmpclr Mp 2.6
C3 Color index 3 (for labels) Integer cmpclr Mp 2.6
C4 Color index 4 (for limb line) Integer cmpclr Mp 2.6
C5 Color index 5 (for continents) Integer cmpclr Mp 2.6
C6 Color index 6 (for US states) Integer cmpclr Mp 2.6
C7 Color index 7 (for countries) Integer cmpclr Mp 2.6
DA grid DAshline pattern Integer cmpdd Mp 3.3
DD Distance between Dots Real cmplot Mp 3.5
DL Dotted Line flag Integer --- Mp 7.
DO Dotted Outline flag Integer cmplot Mp 3.5
EL ELliptical perimeter flag Integer cmpel Mp 2.9
ER ERror Integer --- Mp 7.
G1 Group 1 (group identifier for geo Integer cmpgrp Mp 4.2
graphic entities and perimeter)
G2 Group 2 (group identifier for vertical Integer cmpgrp Mp 4.2
strips)
GD Grid Drawing resolution Real cmpgrd Mp 3.2
GR GRid spacing Real cmpgrd Mp 3.2
IN INitialization flag Integer --- Mp 7.
LA meridian/pole LAbel flag Integer cmplbl, Mp 3.4,
cmplab Mp 4.4
LS Label Size Integer cmplbl, Mp 3.4,
cmplab Mp 4.4
MV Minimum Vector length Real cmplot Mp 3.5
OU OUtline data flag Character cmpou Mp 2.4
P1 PLM1(1) value Real --- Mp 7.
P2 PLM2(1) value Real --- Mp 7.
P3 PLM3(1) value Real --- Mp 7.
P4 PLM4(1) value Real --- Mp 7.
P5 PLM1(2) value Real --- Mp 7.
P6 PLM2(2) value Real --- Mp 7.
P7 PLM3(2) value Real --- Mp 7.
P8 PLM4(2) value Real --- Mp 7.
PE PErimeter flag Integer cmpel Mp 2.9
PN PLON value Real --- Mp 7.
PR PRojection specifier value Character --- Mp 7.
PT PLAT value Real --- Mp 7.
RE REsolution Integer cmplot Mp 3.5
RO ROtation Real --- Mp 7.
SA SAtellite view distance Real cmpsat Mp 2.3
S1 Satellite viewing angle Real cmpsat Mp 2.3
S2 Satellite view projection Real cmpsat Mp 2.3
SR lat/lon Search Radius Real --- Mp 7.
VS Vertical-Stripping parameter Integer cmpgrp Mp 4.2
XL XLOW value Real --- Mp 7.
XR XROW value Real --- Mp 7.
YB YBOW value Real --- Mp 7.
YT YTOW value Real --- Mp 7.
----------------------------------------------------------------------------------------
--------------------------------------------------
Abbreviation Projection Type
--------------------------------------------------
LC Lambert Conformal Conic
ST STereographic Azimuthal
OR ORthographic Azimuthal
LE Lambert Equal-area Azimuthal
GN GNomonic Azimuthal
AE Azimuthal Equidistant Azimuthal
SV Satellite View Azimuthal
CE Cylindrical Equidistant Cylindrical
ME MErcator Cylindrical
MO MOllweide-type Cylindrical
--------------------------------------------------
This module provides background information; it is not required for using or understanding the Ezmap utility.
Ezmap uses three different kinds of projections to project maps of the Earth onto a two-dimensional surface: conic, azimuthal, and cylindrical. Conic 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 different circles. The cone is then cut from point to mouth, and spread out flat.
The only conic projection offered by Ezmap is the Lambert Conformal projection. In this projection, the cone passes through the earth at two user-specified latitudes, usually both in the same hemisphere. The cone is cut on the opposite side of the globe from a user-specified meridian (longitude). The cone is then laid flat on the plotter plane with either the north pole or the south pole (depending on your specified latitudes) at the origin.
Mathematically, if LAT1 and LAT2 are the latitudes where the cone passes through the globe, and LAT1<>LAT2, then the "cone constant" is given by:
LOG (COS(LAT1)) - LOG (COS(LAT2))
CONE = -------------------------------------------------
LOG (TAN (45-S*LAT1/2)) - LOG (TAN (45-S*LAT2/2))
where S=1 in the northern hemisphere, and S=-1 in the southern hemisphere.
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 following formulas give the coordinates of the projected point in the plotter plane.
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.
If LAT1=LAT2, then the cone is tangent to the globe along the single standard parallel and
CONE = COS (90 - S * LAT1)
The vertex of the cone is at a distance from the plane of the equator given by D=R/SIN(LAT1), where R is the radius of the earth and LAT1 is the latitude of the single standard parallel. Note that as LAT1 approaches zero, D approaches infinity, and, as LAT1 approaches 90 degrees, D approaches R, the radius of the earth.
The entire globe projects onto the u/v plane minus a wedge with its apex at the origin. This projection is best used to depict midlatitude regions of limited extent, where it is relatively free of distortion. The Lambert Conformal projection preserves angles. A portion of the u/v plane determined by the MAPSET call is the user coordinate system for drawing.
This module provides background information; it is not required for using or understanding the Ezmap utility.
The second kind of projection that Ezmap uses to project a map of the earth onto the plotter frame is the azimuthal projection. Azimuthal projections map the globe onto a plane whose origin touches the earth at the user-specified point (PLAT, PLON). The image may be rotated by the user-specified angle ROTA.
Ezmap generates azimuthal projections as follows:
- Touch a plane (called the u/v plane here) to the earth at latitude
0 and longitude 0 (where the Greenwich parallel meets the equator);
the earth is oriented with the North Pole at the top and the South
Pole at the bottom.
- Rotate the earth about its polar axis until the v axis is tangent
to the meridian identified by PLON.
- Rotate the earth, tilting one of the poles towards the plane until
the point (PLAT, PLON) is touching the plane at its origin.
- Rotate the earth clockwise through the angle ROTA about a line
perpendicular to the u/v plane passing through the origin.
- Use lines emanating from a central point within or behind the
earth (depending on the projection) to project the globe onto the u/v
plane.
- Set up scales along the u/v axes.
- Draw a rectangular or elliptical portion of the resulting map.
This portion of the u/v plane is the user coordinate system.
If A is the angular separation, in degrees, of the point P to be projected from the point (PLAT, PLON), and if R is the linear distance of the projected point P' from the u/v origin, then the azimuthal projections can be described as relationships between A and R:
- Stereographic
R = TAN(A/2) = (1-COS(A)) / SIN(A)
- As A approaches 180 degrees, R approaches infinity. The entire globe is projected onto the entire u/v plane. In practice, distortion becomes great when A is approximately 127 degrees or more. The center of the projection is the point on the earth's surface opposite the point of tangency with the projection plane.
- Orthographic
R = SIN(A)
- Points for which A>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.
- Lambert equal-area
R = 2 * SIN(A) / SQRT(2*(1+COS(A))
- As A approaches 180 degrees, R approaches 2. The globe is projected into a circle of radius 2.
- Gnomonic
R = TAN(A)
- Points for which A>90 degrees are invisible. Thus, a hemisphere is projected to the entire u/v plane. In practice, distortion becomes great when A is approximately 65 degrees or more. The center of this projection is the center of the earth.
- Azimuthal equidistant
R = A * ¶ / 180.0
- As A approaches 180 degrees, R approaches ¶. The globe is projected into a circle of radius ¶.
- Basic satellite view
- This formula applies only when S1=0, the basic view.
R = SQRT(SA*SA-1)*SIN(A)/(SA-COS(A))
- where SA is the distance, in earth radii, from the center of the earth to a satellite above the point (PLAT, PLON). Points for which COS(A) < 1 / SA are invisible. The portion of the earth's surface that 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 out, the satellite view projection approaches the orthographic projection. Two parameters, S1 and S2, may be used to modify the basic satellite view projection; they can be used to show the earth as it would look to a simple pinhole camera pointed in a specified direction.
This module provides background information; it is not required for using or understanding the Ezmap utility.
The third kind of projection Ezmap uses to project a map of the earth onto the plotter frame is the cylindrical projection. Cylindrical projections map the earth onto a cylinder that is tangent to the earth along a great circle passing through the user-specified point (PLAT, PLON) and tilted at the user-specified angle ROTA.
The process of creating a cylindrical projection can be described geometrically in ten steps:
- Imagine that the earth is placed behind the u/v (projection) plane
so that the point at latitude 0 and longitude 0 just touches the plane
at latitude 0 and longitude 0. The north pole is at the top, and the
south pole is at the bottom.
- Rotate the earth about its polar axis until the v axis is tangent
to the meridian identified by PLON.
- Rotate the earth by tilting one of the poles directly toward you
and the other pole directly away from you until the point (PLAT, PLON)
is at the origin of the u/v plane.
- Rotate the earth clockwise through the angle ROTA about a line
perpendicular to the u/v plane passing through the point at latitude 0
and longitude 0.
- Wrap the u/v plane around the globe to form a cylinder with the u
axis touching the earth along a great circle.
- Using the technique specific to the projection type, project
geographical outlines, parallels, and meridians outward from the
earth's surface onto the cylinder.
- Cut the cylinder along a line parallel to its axis and opposite
the origin.
- Unwrap the cylinder.
- Set up linear scales along the u and v axes.
- Draw a rectangular or elliptical portion of the resulting map.
This portion of the u/v plane is the user coordinate system.
The technique used in step 6 above is described in the following three paragraphs for each of Ezmap's three types of cylindrical projections in the simple case where PLAT=PLON=ROTA=0. Let RLAT and RLON be the latitude and longitude, in degrees, of a point to be projected. 180<=RLON<=180. (If PLAT, PLON, and/or ROTA are nonzero, you must substitute for RLAT and RLON a pseudo-latitude and a pseudo-longitude computed from the real latitude and longitude.) The cylindrical projections may then be described as follows:
- Cylindrical equidistant
U = RLAT
V = RLON
- where the entire globe is projected into a rectangle in the u/v plane. 180<=U<=180, and 90<=V<=90.
- Mercator
U = RLON * ¶/180.0
V = ALOG (COT (45 - RLAT/2))
- The entire globe is projected onto an infinite rectangle in the u/v plane. -¶<=U<=¶. There are no limits on V. In practice, distortion becomes high for latitudes within 5 degrees of either pole.
- Mollweide type
- (This is not a true Mollweide projection.)
U = RLON/90
V = COS (90-RLAT)
- The entire surface of the globe is projected into an ellipse. -2<=U<=2, -1<=V<=1.
Hershey, A.V, "The plotting of Maps on a CRT Printer," NWL Report 1844, 1963.
Lee, Tso-Hwa, "Students' Summary Reports, Work-Study Program in Scientific Computing," NCAR, 1968.
Parker, R.L., "2UCSD SUPERMAP: World Plotting Package."
Steers, J.A., An Introduction to the Study of Map Projections, University of London Press, 1962.
SUPMAP creates a map of a desired portion of the globe by using your specifications for the projection, outlines, and latitude/longitude line intervals. An appropriate call to the routine SET is performed, and the routine MAPTRN is initialized so that you may map points of known latitude and longitude to points on the u/v plane and use the u/v coordinates to draw objects on the map.
1 REAL PLIM1(2), PLIM2(2), PLIM3(2), PLIM4(2)
2 DATA PLIM1 /0.0, 0.0/
3 DATA PLIM2 /0.0, 0.0/
4 DATA PLIM3 /0.0, 0.0/
5 DATA PLIM4 /0.0, 0.0/
6 CALL SUPMAP (7, 0., 0., 0., PLIM1, PLIM2, PLIM3, PLIM4, 1, 5, 0, 0,IERR)
CALL SUPMAP (JPRJ, PLAT, PLON, ROTA, PLIM1, PLIM2, PLIM3, PLIM4,
+ JLTS, JGRD, IOUT, IDOT, IERR)
- JPRJ
- Integer, Input---Defines the projection type with the following values (values less than 1 are treated as 1, and values greater than 10 are treated as 10):
- 1 Stereographic
- 2 Orthographic
- 3 Lambert conformal conic
- 4 Lambert equal-area
- 5 Gnomonic
- 6 Azimuthal equidistant
- 7 Satellite view
- 8 Cylindrical equidistant
- 9 Mercator
- 10 Mollweide-type
- Using the value 2 causes the Ezmap parameter SA to be zeroed. (If SA is greater than 1., a satellite-view projection is used rather than an orthographic projection; it specifies the distance of the satellite from the center of the earth in units of earth radii.) Using the value 7 causes SA to be examined. If it has a nonzero value, the value is left alone. If it has a zero value, its value is reset to 6.631, which is about right for a satellite in a geosynchronous equatorial orbit.
- The sign of JPRJ, when IOUT is -1, 0, or +1, indicates whether the continental outlines are to be plotted or not. See the description of IOUT below.
- PLAT, PLON, ROTA
- Real, Input---Define the origin of the projection and its rotation angle. These arguments are used in the same way as they would be in a call to the routine MAPROJ. See module "Mp 2.2 Choosing your map projection" for a complete description.
- JLTS
- Integer, Input---Specifies how to choose the rectangular limits of the map to be drawn. JLTS also determines the meaning of PLIM1, PLIM2, PLIM3, and PLIM4, which take real numbers as values. JLTS takes one of the following values:
- 1 The maximum useful area produced by the projection is plotted. PLIM1, PLIM2, PLIM3, and PLIM4 are not used.
- 2 The points (PLIM1, PLIM2) and (PLIM3, PLIM4) represent opposite corners of the map. PLIM1 and PLIM3 are latitudes, in degrees. PLIM2 and PLIM4 are longitudes, in degrees. If a cylindrical projection is being used, the first point is assumed to be on the left edge of the map and the second point is on the right edge. The order makes no difference for other map projections. You cannot use JLTS=2 if any two adjacent corners of the desired map are outside the limb of projection.
- 3 PLIM1, PLIM2, PLIM3, and PLIM4 specify the minimum value of U, the maximum value of U, the minimum value of V, and the maximum value of V, respectively. Knowledge of the projection equations is necessary for using this option correctly.
- Note: PLIM1, PLIM2, PLIM3, and PLIM4 are two-element real arrays. If 1<=JLTS<=4, then only the first element of each array is used.
- 4 PLIM1, PLIM2, PLIM3, and PLIM4 are positive angles, in degrees, representing angular distances from a point on the map to the left, right, bottom, and top edges of the map, respectively. For most projections, these angles are measured with the center of the earth at the vertex and represent angular distances from the point that projects to the origin of the u/v plane. For a satellite view projection, these angles are measured with the satellite at the vertex and represent angular deviations from the line of sight. Angular limits are particularly useful for polar projections and for the satellite view projection; they are not appropriate for the Lambert conformal conic projection and an error results if you attempt to use JLTS=4 with JPRJ=3.
- 5 PLIM1, PLIM2, PLIM3, and PLIM4 are two-element arrays giving the latitudes and longitudes, in degrees, of four points that are to be on the edges of the rectangular map. If a cylindrical projection is being used, the first point is assumed to be on the left edge and the second point is on the right edge. The order makes no difference for other map projections. You cannot use JLTS=5 if an entire side of the desired map is outside the limb of projection.
- Note: PLIM1, PLIM2, PLIM3, and PLIM4 are two-element real arrays. If 1<=JLTS<=4, then only the first element of each array is used.
- MOD (IABS(JGRD), 1000)
- Integer, Input---The value, in degrees, of the interval at which lines of latitude and longitude are to be plotted. If the given interval is zero, grid lines and labels are not plotted. If JGRD is less than zero, the perimeter is not plotted. Set JGRD to -1000 to suppress both grid lines and perimeter; set JGRD to +1000 to suppress the grid lines, but leave the perimeter. The value -0 may have a meaning on some computers, but should be avoided; use -1000 instead.
- IOUT
- Integer, Input---The outline flag determines which geopolitical boundaries are drawn:
- 0 Suppress US state outlines
- -1 Plot US state outlines, but not continental outlines
- +1 Plot US state outlines and continental outlines
- <=-2 Do not plot any outlines
- +2 Plot continental outlines, no US outlines
- 3 Plot US state outlines, no others
- 4 Plot continental outlines, international outlines, and US state outlines
- >4 Plot continental outlines and international outlines, but no US outlines
- In past versions of this software, the sign of IOUT specified whether or not a line of text was to be written on the print output. This usage is no longer valid.
- IDOT
- Integer, Input---The dotted outline flag takes the following values:
- 0 Continuous outlines
- 1 Dotted outlines
- IERR
- Integer, Output---A nonzero value on return indicates that an error has occurred.
- Given that Boulder, Colorado has a latitude of 40.00 and a
longitude of 105.15, draw a satellite projection centered above
Boulder.
There are essentially two ways to use Ezmap. First, you can use Ezmap
to draw a simple black-and-white map, often for use as a background,
or you can use Ezmap with the Areas utility to do color-fill or
pattern-fill areas, masking, or to act as a background for another
color utility like Conpack.
--------------------------------------------------------------
* ** 1. Open GKS
2. Define position on plotter frame
* ** 3. Define map projection
* ** 4. Choose map limits
* ** 5. Choose desired political boundaries
* 6. Initialize Areas
* ** 7. Initialize Ezmap
* 8. Add geographic boundaries (or outlines) to area map
9. Draw geographic labels
10. Draw points and lines on your map
11. Draw desired latitude and longitude lines
* 12. Fill desired areas
** 13. Draw geographic outlines
* ** 14. Call FRAME
* ** 15. Close GKS
--------------------------------------------------------------
* Steps needed for maps that have masking or filling.
** Steps needed for a simple black-and-white map.
Ezmap relies heavily on parameters to produce the map options you specify (such as which projection, the map limits, the perimeter, and so on). The first argument in a call to MPGETx or MPSETx is the parameter name. The second argument is either a variable in which the value of the named parameter is to be returned (via MPGETx) or an expression specifying the desired new value of the parameter (via MPSETx).
CALL MPGETC (PNAM, CVAL)
CALL MPGETI (PNAM, IVAL)
CALL MPGETR (PNAM, RVAL)
CALL MPSETC (PNAM, CVAL)
CALL MPSETI (PNAM, IVAL)
CALL MPSETR (PNAM, RVAL)
CALL MAPSAV (INFO)
CALL MAPRST (INFO)
- MPGETC
- Retrieves character parameter information.
- MPGETI
- Retrieves integer parameter information.
- MPGETR
- Retrieves real parameter information.
- MPSETC
- Sets character parameter information.
- MPSETI
- Sets integer parameter information.
- MPSETR
- Sets real parameter information.
- MAPSAV
- Saves all user-settable Ezmap parameter information to a file.
- MAPRST
- Retrieves all user-settable Ezmap parameter information from a file in which MAPSAV has saved the information.
- PNAM
- Character expression, Input or Output---The name of the parameter that you want to set or retrieve. Two-character parameter names appear in examples and discussions in place of PNAM. The parameter names and their meanings are enclosed in single quotation marks in the Fortran code to ensure that they are treated as character expressions rather than real or integer variables. Only the first two characters within the quotation marks are examined.
- CVAL
- Character expression, Input or Output---A character value to be set or retrieved.
- IVAL
- Integer, Input or Output---An integer value to be set or retrieved.
- RVAL
- Real, Input or Output---A real value to be set or retrieved.
- INFO
- Integer, Input or Output---A unit number for a single unformatted record.
Module "Mp 1.2 Table of Ezmap
parameters" is a quick reference guide to all Ezmap
parameters; it also gives references to modules in which
parameter-setting examples appear. Section "Mp 7. Ezmap parameter
descriptions" provides more thorough descriptions of the
Ezmap parameters.
Before you can draw a map, you need to set Ezmap parameters and call several Ezmap setup routines; these steps define how much of which projection you want to view. Because the Ezmap initialization routine MAPINT uses these parameters to do some of the initialization process, it is best to completely define your map before calling MAPINT.
------------------------------------------------------------
1. Open GKS
* 2. Define position on plotter frame
* 3. Define map projection
* 4. Choose map limits
* 5. Choose desired political boundaries
6. Initialize Areas
* 7. Initialize Ezmap
8. Add geographic boundaries (or outlines) to area map
9. Draw geographic labels
10. Draw points and lines on your map
11. Draw desired latitude and longitude lines
12. Fill desired areas
13. Draw geographic outlines
14. Call FRAME
15. Close GKS
------------------------------------------------------------
* Steps discussed in this section.
In most NCAR Graphics utilities, you can use the SPPS routine SET to position your plot in the plotter frame or viewport. In Ezmap, however, the special routine MAPPOS helps you position your plot.
1 CALL MAPPOS (0.5, 1.0, 0.0, 0.5)
2 CALL MAPDRW
CALL MAPPOS (XVPL, XVPR, YVPB, YVPT)
- XVPL
- Real, Input---The position of the left edge of the area in which the viewport is to be positioned, in Normalized Device Coordinates (NDCs). 0.0<=XVPL<=1.0. The default is .05.
- XVPR
- Real, Input---The position of the right edge of the area in which the viewport is to be positioned, in NDCs. 0.0<=XVPR<=1.0. The default is .95.
- YVPB
- Real, Input---The position of the bottom edge of the area in which the viewport is to be positioned, in NDCs. 0.0<=YVPB<=1.0. The default is .05.
- YVPT
- Real, Input---The position of the top edge of the area in which the viewport is to be positioned, in NDCs. 0.0<=YVPT<=1.0. The default is .95.
By using the MAPPOS routine, you can squeeze more than one Ezmap plot onto the same frame. MAPPOS centers the viewport and makes it as large as possible within the specified area, and if possible, maintains the proper aspect ratio.
Line 1 of the cmppos.f code segment sets the left, right, bottom, and top of the viewport so that it is located in the lower left corner of the plotter frame.
- Using the cmppos example, move the plot to the center
of the plotter frame, but keep it the same size.
There are ten different map projections available with Ezmap.
To specify the projection you want, call the MAPROJ routine.
1 CALL MAPPOS (.5125, .73125, .63125, .85)
2 CALL MAPROJ ('OR', 0., 0., 0.)
3 CALL MAPDRW
CALL MAPROJ (JPRJ, PLAT, PLON, ROTA)
- JPRJ
- Character expression, Input---Specifies the desired projection type, as follows:
- LC
Lambert conformal conic with two standard parallels
- ST
Stereographic
- OR
Orthographic. The Ezmap parameter SA will be zeroed. See the next module.
- LE
Lambert equal-area
- GN
Gnomonic
- AE
Azimuthal equidistant
- SV
Satellite view. If Ezmap parameter SA<=1., it will be reset to 6.631 (the value for a satellite in a geosynchronous orbit).
- CE
Cylindrical equidistant
- ME
Mercator
- MO
Mollweide-type
- PLAT, PLON, and ROTA
- Real, Input---Angular quantities, in degrees; their usage depends on the value of JPRJ:
- JPRJ<>LC
PLAT and PLON define the latitude and longitude of the point on the globe that projects to the origin of the u/v plane. This is the center of the projection, not the center of the map. 90.<=PLAT<=+90., with positive values in the northern hemisphere and negative values in the southern. 180.<=PLON<=+180., with positive values to the east of Greenwich, England, and negative values to the west. ROTA is the angle between the v axis and north at the origin. It is taken to be positive if the angular movement from north to the v axis is counterclockwise, otherwise ROTA is negative. If the origin is at the north pole, "north" is taken to be in the direction of PLON+180. If the origin is at the south pole, "north" is taken to be in the direction of PLON. For cylindrical projections, the axis of the projection is parallel to the v axis.
- JPRJ=LC
PLON defines the central meridian of the projection, and PLAT and ROTA define the two standard parallels. If PLAT=ROTA, the simpler conic projection, with one standard parallel, is used. For more information, refer to the drawing in module "Mp 1.4 Description of projections: Conic."
The MAPROJ routine requires you to choose the projection you want to use as well as the center of the projection and the angle of rotation. To minimize distortion, it is usually best to center your projection over the area of interest, and limit the map projection to the minimally necessary area. If you are using Mercator or cylindrical equidistant projections, use PLAT=0 to avoid curved grid lines.
Line 1 of the mpex05.f code segment sets the viewport so that the map is drawn in the upper center of the screen. Line 2 chooses an orthographic projection and centers it on latitude 0 and longitude 0, which is just off the west coast of North Africa. Line 3 draws the map projection.
- Using the cezmap1 example, draw a cylindrical equidistant
map with straight grid lines.
- Copy cezmap1.f to your own file, and name it
cezmap.f. You will use this file in subsequent exercises to
build a customized simple map-drawing routine.
Two of the projections, the orthographic and satellite view projections, have the same internal identifier. To get a satellite projection, it is necessary to set one or more of the three satellite view parameters, SA, S1, and S2.
1 CALL MAPROJ ('SV', 40., 10., 0.)
2 CALL MPSETR ('SA - SATELLITE VIEW DISTANCE', 2.)
3 CALL MPSETR ('S1 - SATELLITE ANGLE 1', 10.)
4 CALL MPSETR ('S2 - SATELLITE ANGLE 2', 15.)
5 CALL MAPDRW
CALL MPSETR ('SA', sa)
CALL MPSETR ('S1', s1)
CALL MPSETR ('S2', s2)
- SA
- Real---Produces a SAtellite view if SA>1.0, otherwise, you get an orthographic projection. SA is the distance of the satellite from the center of the earth, measured in earth radii. If S1=0 as SA approaches infinity, the satellite view projection approaches the orthographic projection. SA=0.0 by default.
- S1
- Real---Satellite angle 1 measures the angle, in degrees, between the line from the satellite to the center of the earth and the line of sight of the satellite. Used only when SA is greater than 1. S1=0.0 by default.
- S2
- Real---Satellite angle 2. Let the case where S1=S2=0 be called the basic satellite view. If S1<>0.0, then S2 specifies the angle, in degrees, from the positive u axis of the basic satellite view counterclockwise to the line OP, where O is the origin of the basic view, and P is the projection on the basic view, of the desired line of sight from the satellite. When S1 and S2 are not equal to zero, the portion of the earth projected remains the same, but the edge of the part of the u/v plane covered by the projection is an ellipse, a parabola, or a hyperbola with an axis at an angle S2 to the u axis. Used only when SA>1. S2=0.0 by default.
The illustration shows a two-dimensional view of a plane passing through the center of the earth (marked E) and a satellite. The surface of the earth appears as a circle. The radius of the earth is defined to be r, or in this case, one unit. The distance of the satellite from the center of the earth is SA. Two planes of projection for the satellite view are shown: the basic satellite view (S1=0.) and another satellite view (S1<>0.). Note that something less than a full hemisphere is projected. Also, as S1 increases, the visible portion of the earth that is projected becomes elliptical, then parabolic, then hyperbolic.
If the basic satellite view is desired, it is not necessary for the user to set either S1 or S2. However, to get a satellite view instead of an orthographic projection, it is necessary to set SA>1.0.
Line 1 of the cmpsat.f code segment sets up the projection to give us a reasonably undistorted view of the Mediterranean. Line 2 sets the satellite at two earth radii distant (roughly 4000 miles out). Lines 3 and 4 set the viewing angle to be slightly off of straight down, and line 5 draws our map.
- Beijing, China is at roughly latitude 39 and longitude 116.
Draw a satellite view from right over the city, assuming that the
satellite is 2.5, 5, and 20 earth radii away. Also for each of these
distances, set S1=30.0 and 60.0, and S2=40.0.
Ezmap offers you several different options for outlining your map. You can use the OU parameter to select continental outlines, international outlines, and state outlines for the US.
1 DATA PLIM1 /30., 0./
2 DATA PLIM2 /-15., 0./
3 DATA PLIM3 /60., 0./
4 DATA PLIM4 /30., 0./
5 CALL MPSETC ('OU - OUTLINE DATA FLAG', 'PO')
6 CALL MAPROJ ('ME', 0., 0., 0.)
7 CALL MAPSET ('CO', PLIM1, PLIM2, PLIM3, PLIM4)
8 CALL MAPINT
9 CALL MAPLOT
CALL MPSETC ('OU', string)
- OU
- Character expression---the OUtline parameter tells which set of outline data to use:
- NO
No outlines
- CO
Continental outlines (the default)
- US
US state outlines
- PO
Continental and political (by country) outlines
- PS
US state outlines, country outlines, and continental outlines
Line 5 of the cmpou.f code segment sets the outline dataset for political, or country outlines. Line 6 sets up the map projection. Lines 1 through 4 and 7 define and choose the corners of the map. Lines 8 and 9 initialize Ezmap and draw the map.
Although state outlines for the US are available, major geographic features like rivers and mountains, and political features like the provinces in other countries are not available with NCAR Graphics at this time. We hope to incorporate this information into one of the future releases of the software.
- Using the cmpou example, try drawing no political boundaries.
- Using your version of cezmap.f (see Mp 2.2 exercises), add
a parameter to the cezmap subroutine calling sequence so that
you can choose your outline dataset outside cezmap. Compare
your results to cezmap2.f.
The MAPSET routine provides several methods you can use to set limits for the map to be drawn.
Figure 1 Figure 2
Figure 3
1 DATA PLIM1 /30., 0./
2 DATA PLIM2 /-15., 0./
3 DATA PLIM3 /60., 0./
4 DATA PLIM4 /30., 0./
5 CALL MAPROJ ('ME', 0., 0., 0.)
6 CALL MAPSET ('CO', PLIM1, PLIM2, PLIM3, PLIM4)
7 CALL MAPINT
8 CALL MAPLOT
CALL MAPSET (JLIM, PLIM1, PLIM2, PLIM3, PLIM4)
- JLIM
- Character expression, Input---Specifies how to choose the rectangular limits of the map to be drawn. JLIM also determines the meaning of PLIM1, PLIM2, PLIM3, and PLIM4, which are two-element real arrays. JLIM takes one of the following values:
- MA
The maximum useful area produced by the projection is plotted. PLIM1, PLIM2, PLIM3, and PLIM4 are not used.
- CO
The points (PLIM1(1), PLIM2(1)) and (PLIM3(1), PLIM4(1)) represent opposite corners of the map. PLIM1 and PLIM3 are latitudes, in degrees. PLIM2 and PLIM4 are longitudes, in degrees. If a cylindrical projection is being used, the first point is assumed to be on the left edge of the map and the second point is on the right edge. The order makes no difference for other map projections. CO cannot be used if any two adjacent corners of the desired map are outside the limb of projection, hence CO can only be used in cases similar to Figure 1 in the illustration.
- LI
PLIM1(1), PLIM2(1), PLIM3(1), and PLIM4(1) specify the minimum value of u, the maximum value of u, the minimum value of v, and the maximum value of v, respectively. Knowledge of the projection equations (see modules Mp 1.4 through Mp 1.6) is necessary for using this option correctly. LI is the only option that can be used in Figure 3 of the illustration "Setting limits on your map projection."
- AN
PLIM1(1), PLIM2(1), PLIM3(1), and PLIM4(1) are positive angles, in degrees, representing angular distances from a point on the map to the left, right, bottom, and top edges of the map, respectively. For most projections, these angles are measured with the center of the earth at the vertex and represent angular distances from the point that projects to the origin of the u/v plane. For a satellite view projection, these angles are measured with the satellite at the vertex and represent angular deviations from the line of sight. Angular limits are particularly useful for polar projections and for the satellite view projection; they are not appropriate for the Lambert conformal conic projection and an error results if you attempt to use JLIM=AN with JPRJ=LC.
- PO
PLIM1, PLIM2, PLIM3, and PLIM4 are two-element real arrays giving the latitudes and longitudes, in degrees, of four points that are to be on the edges of the rectangular map. If a cylindrical projection is being used, the first point is assumed to be on the left edge and the second point is on the right edge. The order makes no difference for other map projections. PO cannot be used if an entire side of the desired map is outside the limb of projection, as in Figure 3 in the illustration; it can be used in cases like Figure 2.
Lines 1 through 4 of the cmpou.f code segment set the limits of the projection. Line 6 uses these limits as corners of the projection, so only the first elements of the arrays PLIM1, PLIM2, PLIM3, and PLIM4 are used. Line 5 sets the map projection; lines 7 and 8 initialize and draw the map.
In Figure 1 of the cmpou example, JLIM can be set to CO, PO, or LI. However, CO won't work in Figure 2 because one of the necessary corners of specification is outside the projected map area. In Figure 3, only LI works as an option because both a necessary corner and the entire side of the desired map is outside the limb of projection.
Note: Most compilers allow us to treat PLIM1 through PLIM4 as if they were reals, so we can pass in reals in the code when JLIM=MA, CO, LI, or AN.
- Using the cmpou example, set JLIM to draw the complete globe.
- The continental US is approximately bounded by latitudes of 22 and 47 and longitudes of -120 and -65. Draw a map of the continental US.
- Using your version of cezmap.f (from the Mp 2.2 exercises), modify it so that you can pass in the limits of your map projection. Test these limits by producing a maximal area satellite view projection. Compare your results with the cezmap3 example.
There are seven parameters controlling the line color of various portions of the map. These parameters are most frequently used in simple line maps; they cannot be used to color-fill regions in the map.
1 CALL COLOR
2 CALL MPSETC ('OU - OUTLINE DATA FLAG', 'PS')
3 CALL MPSETI ('C1 - COLOR INDEX 1 - PERIMETER', 1)
4 CALL MPSETI ('C2 - COLOR INDEX 2 - GRID', 2)
5 CALL MPSETI ('C3 - COLOR INDEX 3 - LABELS', 3)
6 CALL MPSETI ('C4 - COLOR INDEX 4 - LIMB LINE', 4)
7 CALL MPSETI ('C5 - COLOR INDEX 5 - CONTINENTAL OUTLINES', 5)
8 CALL MPSETI ('C6 - COLOR INDEX 6 - US STATE OUTLINES', 6)
9 CALL MPSETI ('C7 - COLOR INDEX 7 - COUNTRY OUTLINES', 7)
10 CALL MAPROJ ('SV', 40., -50., 0.)
11 CALL MPSETR ('SA - SATELLITE VIEW DISTANCE', 5.)
12 CALL MAPSET ('MA', PLIM1, PLIM2, PLIM3, PLIM4)
13 CALL MAPINT
CALL MPSETI ('C1', ic1)
CALL MPSETI ('C2', ic2)
CALL MPSETI ('C3', ic3)
CALL MPSETI ('C4', ic4)
CALL MPSETI ('C5', ic5)
CALL MPSETI ('C6', ic6)
CALL MPSETI ('C7', ic7)
Each color index parameter specifies the color index of some part of the map, as indicated below. The default values for all color index parameters are negative; this specifies that no color index change is to be made between parts of the map.
--------------------------------
Parameter Type Area of
effect
--------------------------------
C1 Integer Perimeter
C2 Integer Grid (lat/
lon lines)
C3 Integer Labels
C4 Integer Limb line
C5 Integer Continental
outlines
C6 Integer US state
outlines
C7 Integer Country
outlines
--------------------------------
Line 1 of the cmpclr.f code segment sets up the color table by calling the user-supplied routine COLOR, which calls the GKS routine GSCR. Line 2 chooses the "draw everything" option for this map. Lines 3 through 9 set each color index parameter to a color index chosen from the color table. This shows each of the different colors on the map: the perimeter is red, the grid is green, the labels are orange, the limb line is blue, the continents are outlined in magenta, the US states are outlined in aqua, and other countries are outlined in black. Lines 10 and 11 choose a satellite projection from 5 earth radii, and set a maximal viewport to show as much as possible.
If you wanted to make the entire map the same color, you could set the polyline and text colors using the GKS calls GSPLCI and GSTXCI, and not set Ezmap parameters C1 through C7.
- Using the cmpclr example, change the grid lines to aqua and the continent lines to yellow.
- Using your version of cezmap.f (from the Mp 2.2 exercises), change line colors to values you select.
Ezmap supplies a default version of MAPUSR that does nothing. By modifying this default version of MAPUSR, you gain complete control over how each line in Ezmap is drawn. You can use it to change colors of lines, dash patterns of lines, or even to eliminate the drawing of certain lines.
1 CALL MAPROJ ('SV', 40., 10., 0.)
2 CALL MPSETR ('SA - SATELLITE VIEW DISTANCE', 5.)
3 CALL MPSETC ('OU - OUTLINE DATA FLAG', 'PO')
4 CALL MAPDRW
5
6 SUBROUTINE MAPUSR (IPRT)
7 C 1110000011100000
8 IF (IPRT .EQ. 1) CALL DASHDB (57568)
9 C 1111111100000000
10 IF (IPRT .EQ. 2) CALL DASHDB (65280)
11C 0100110001110000
12 IF (IPRT .EQ. 4) CALL DASHDB (19568)
13C 1111000011110000
14 IF (IPRT .EQ. 5) CALL DASHDB (61680)
15C 1110010011100100
16 IF (IPRT .EQ. 6) CALL DASHDB (58596)
17C 010101010101010101
18 IF (IPRT .EQ. 7) CALL DASHDB (21845)
19 RETURN
20 END
SUBROUTINE MAPUSR (IPRT)
- MAPUSR
- Subroutine---This Ezmap subroutine is called just before and just after each portion of the map is drawn. The default version of MAPUSR does nothing, but you can modify it to control how Ezmap draws lines.
- IPRT
- Integer, Input---If positive, this variable specifies which part of the map is about to be drawn with these values:
- 1 Perimeter
- 2 Grid
- 3 Labels
- 4 Limb line
- 5 Continental outlines
- 6 US state outlines
- 7 International outlines
- A negative value for IPRT indicates that part of the map has been drawn.
Lines 1 through 4 of the cmpusr.f code segment define and draw a satellite view map projection as usual. In this case, a custom version of MAPUSR must be written and either added to the end of your program or loaded before the NCAR Graphics libraries are loaded. The MAPUSR shown here checks to see which portion of the map is being drawn, and then sets a binary dash pattern using the DASHDB call. Each line of MAPUSR is preceded by a comment line that shows the binary dash pattern converted to base 10 in the call to DASHDB. In each binary dash pattern, 0 represents a space and 1 represents a dash.
Because characters are drawn using the GKS routine GTX, not the Dashline utility, do not attempt to set a dashed line for them in MAPUSR.
This version of MAPUSR uses the dash pattern option to draw the various parts of the map. However, if you set the dotted outline flag DO nonzero to specify dotted outlines, this version of MAPUSR would have no effect.
- Modify MAPUSR to change the line colors in the cmpusr example.
You can write your own MAPEOD routine to control how Ezmap draws outlines. For example, you may want to use MAPEOD to reduce visual clutter by eliminating lake and island outlines.
1 SUBROUTINE MAPEOD (NOUT, NSEG, IDLS, IDRS, NPTS, PNTS)
2 DIMENSION PNTS (*)
3 IF (IDLS .NE. 2 .AND. IDRS .NE. 2) NPTS=0
4 IF (IDLS .NE. 1 .AND. IDRS .NE. 1 .AND.
+ IDLS .NE. 3 .AND. IDRS .NE. 3 .AND.
+ IDLS .NE. 11 .AND. IDRS .NE. 11 .AND.
+ IDLS .NE. 79 .AND. IDRS .NE. 79 .AND.
+ IDLS .NE. 99 .AND. IDRS .NE. 99 .AND.
+ IDLS .NE. 104 .AND. IDRS .NE. 104 .AND.
+ IDLS .NE. 107 .AND. IDRS .NE. 107 .AND.
+ IDLS .NE. 163 .AND. IDRS .NE. 163) NPTS=0
5 RETURN
6 END
CALL MAPEOD (NOUT, NSEG, IDLS, IDRS, NPTS, PNTS)
- NOUT
- Integer, Input---The number of the outline dataset from which the segment is taken. The following table shows the numbers specifying the NOUT dataset and gives the outline type and outline name:
----------------------------------------
Number Name Contents
----------------------------------------
1 CO Continental outlines only
2 US US state outlines only
3 PS Continental, US state,
and international outlines
4 PO Continental and interna
tional outlines
----------------------------------------
- NSEG
- Integer, Input---The number of the segment within the outline dataset. The maps in the mpex09 example show segment numbers for the outline dataset CO; you may modify this program to produce maps showing segment numbers for any outline dataset.
- IDLS, IDRS
- Integer, Input---Identifiers for the areas to the left and
right, respectively, of the segment. (Left and right are defined from
the standpoint of a viewer standing at point 1 of the segment and
looking toward point 2.) For a complete list of area identifiers, see
section "Mp 6. Table of Ezmap
area identifiers."
- NPTS
- Integer, Input---The number of points defining the outline segment, when entering subroutine MAPEOD. NPTS may be zeroed by MAPEOD to suppress plotting of the segment on the map.
- PNTS(NPTS)
- Real array, Input---PNTS(1) and PNTS(2) are the latitude and longitude of the first point, PNTS(3) and PNTS(4) are the latitude and longitude of the second point, . . . and PNTS(2*NPTS1) and PNTS(2*NPTS) are the latitude and longitude of the last point. All values are in degrees. Longitudes are all between 180 and +180, and no segment crosses the meridian at 180 (+180) degrees.
This version of MAPEOD uses area identifiers for the outline dataset CO to suppress all but the major global land masses and the British Isles. Line 3 of the mpex03.f code segment culls the segment if there is no ocean on either side of it. Line 4 checks to see if this is a continental outline or an outline of British Isles, and if not, then removes the outline.
MAPEOD is called by Ezmap to examine each segment in an outline dataset just before it is plotted. The default version does nothing. The mpex03, mpex05, and mpex09 examples all contain versions of MAPEOD that you might find useful.
The Ezmap perimeter is controlled by two parameters. PE determines if a perimeter is drawn, and EL determines if the perimeter is an ellipse or a rectangle.
1 CALL MAPROJ ('SV', 40., 10., 0.)
2 CALL MPSETR ('SA - SATELLITE VIEW DISTANCE', 5.)
3 CALL MPSETC ('OU - OUTLINE DATA FLAG', 'PO')
4 CALL MPSETI ('PE - PERIMETER FLAG', 0)
5 CALL MPSETI ('EL - ELLIPTICAL PERIMETER FLAG', 1)
CALL MPSETI ('PE', ipe)
CALL MPSETI ('EL', iel)
- PE
- Integer---Draws a PErimeter if nonzero. PE<>0 by default.
- EL
- Integer---If nonzero, draw only that part of the map inside an ELlipse inscribed within the normal rectangular perimeter. This is particularly appropriate for use with azimuthal projections and angular limits specifying a square, in which case the ellipse becomes a circle. This parameter works for any map. EL=0 by default.
In Ezmap, a "perimeter" is the boundary of a map produced by a call to Ezmap routines. The perimeter may either be a rectangle in the projection plane or an ellipse inscribed in that rectangle.
An "ellipse" is a particular kind of closed curve as defined by any plane geometry text.
A "limb line" is that line in the Ezmap projection plane separating points into which some point on the globe projects from points into which no point on the globe projects. For example, when you are using an orthographic projection, the visible side of the globe maps into the interior of a circle of radius 1 and centered at the origin; the "limb" of an orthographic projection is therefore that circle. Depending on the projection being used, the "limb lines" may be straight lines, circles, ellipses, parabolas, or hyperbolas. Limb lines can also be complicated curves (sometimes defined by means of a function and sometimes defined by means of a table of X/Y coordinates defining a polygon) for projections not offered by Ezmap.
Lines 1 through 3 of the cmpel.f code segment set up the satellite map projection. Lines 4 and 5 turn off perimeter drawing. Examine the plot to see the places where Ezmap has not drawn a dividing line between a geographical outline and the background; this occurs because PE has been turned off.
- Using the cmpel example, draw a perimeter around the map.
- Using the cmpitm example, turn on the EL option before the call to cmpmsk, and notice the difference it makes in the plot.
- Using your own version of cezmap.f (from the Mp 2.2 exercises), set the perimeter and ellipse options.
Three Ezmap routines allow you to save and retrieve various aspects of Ezmap's state. MAPRS allows you to redo the SET call that was used in the last call to MAPINT. MAPSAV allows you to save your map transformation and parameter information to a file. MAPRST allows you to retrieve the information saved by MAPSAV so you can use it for another plot.
CALL MAPRS
CALL MAPSAV (IUNIT)
CALL MAPRST (IUNIT)
- MAPRS
- Occasionally, you may want to re-execute the call to SET that was done for you by your last call to MAPINT. MAPRS does this. You might use this when you plot user lines over a map generated in a different overlay (such as when using a Gflash buffer), and when the system plot package does not reside in an outer overlay.
- MAPSAV(IUNIT)
- Saves current state of Ezmap to a file by writing, on the Fortran unit specified by IUNIT, the current values of all the user-settable parameters. IUNIT is the number of a Fortran unit to which a single unformatted record is to be written. You must position this unit; MAPSAV does not rewind it, either before or after writing the record.
- MAPRST(IUNIT)
- Restores a previous state of Ezmap saved by an earlier call to MAPSAV by reading, from the Fortran unit specified by IUNIT, values of all user-settable parameters, and then executing MAPINT. IUNIT is the number of a Fortran unit from which a single unformatted record is to be read. You must position this unit; MAPRST does not rewind it, either before or after reading the record.
For our purposes, we define a "simple map" as a map that is essentially a line drawing. Simple maps do not have color-filled or pattern-filled regions.
You need fewer steps to produce simple black-and-white maps than you do when you use the Areas utility for maps that require masking and filling.
-----------------------------------------------
1. Open GKS
2. Define position on plotter frame
3. Define map projection
4. Choose map limits
5. Choose desired political boundaries
6. Initialize Ezmap
7. Draw geographic labels
8. Draw points and lines on your map
9. Draw desired latitude and longitude lines
10. Draw geographic outlines
11. Call FRAME
12. Close GKS
-----------------------------------------------
Before using the Ezmap utility, you must initialize it with the MAPINT routine. Also, after calling MAPPOS, MAPROJ, or MAPSET, you must call MAPINT again to re-initialize Ezmap.
1 CALL COLOR
2 CALL MPSETC ('OU - OUTLINE DATA FLAG', 'PO')
3 CALL MAPROJ ('SV', 40., -50., 0.)
4 CALL MPSETR ('SA - SATELLITE VIEW DISTANCE', 5.)
5 CALL MAPSET ('MA', PLIM1, PLIM2, PLIM3, PLIM4)
6 CALL MAPINT
CALL MAPINT
Line 1 of the cmpgrd.f code segment sets up the color table. Line 2 turns on drawing of the continental and political outlines. Lines 3 through 5 set the projection for a satellite view over the Atlantic Ocean. Line 6 initializes Ezmap. Notice that the call to MAPINT follows calls to MAPROJ and MAPSET, since both these routines set values that MAPINT needs.
You must call MAPINT to initialize the Ezmap utility after calling MAPPOS, MAPROJ, or MAPSET.
Currently, it is okay to call MAPINT many times. You can check the flag IN (which may be retrieved by a call to MPGETI) to determine whether or not a call to MAPINT is required at a given time. You can change internal parameters such as C1, OU, LA, and so on either before or after a call to MAPINT, but for consistency with Conpack, we set Ezmap parameters before initialization.
MAPGRD is the routine that Ezmap uses to draw the limb line and the latitude/longitude (grid) lines. There are also several Ezmap parameters associated with changing grid dashline patterns and accuracy. The grid-spacing parameter GR controls how many degrees apart the latitude and longitude lines are drawn. The grid-drawing parameter GD changes the accuracy used for drawing the latitude and longitude lines. The latitude and longitude line spacings cannot be set individually.
1 CALL COLOR
2 CALL MPSETC ('OU - OUTLINE DATA FLAG', 'PO')
3 CALL MPSETI ('C2 - COLOR INDEX 2 - GRID', 2)
4 CALL MPSETI ('C4 - COLOR INDEX 4 - LIMB LINE', 2)
5 CALL MAPROJ ('SV', 40., -50., 0.)
6 CALL MPSETR ('SA - SATELLITE VIEW DISTANCE', 5.)
7 CALL MAPSET ('MA', PLIM1, PLIM2, PLIM3, PLIM4)
8 CALL MPSETR ('GR - GRID SPACING', 10.)
9 CALL MPSETR ('GD - GRID DRAWING RESOLUTION', 10.)
10 CALL MAPINT
11 CALL MAPGRD
CALL MPSETR ('GR', gr)
CALL MPSETR ('GD', gd)
CALL MAPGRD
- GR
- Real---The GRid spacing parameter chooses the desired spacing, in degrees, of latitude and longitude lines on the globe. GR=10.0 by default.
- GD
- Real---The Grid Drawing resolution parameter controls how accurately the latitude and longitude lines are mapped onto the globe. GD specifies the distance in degrees between points defining a grid line. 0.001<=GD<=10. By default, GD=1.0.
Line 1 of the cmpgrd.f code segment sets up the color table. Line 2 turns on drawing of the continental and political outlines. Lines 3 and 4 set the color parameters so that everything drawn by MAPGRD is drawn in green (color index 2). Lines 5 through 7 set up the projection for a satellite view over the Atlantic Ocean.
Line 8 sets the grid lines to be drawn at intervals of 10 degrees. Line 9 sets the accuracy parameter to 10 so that the map requires a minimum of CPU and plotting time.
GD sets the distance between points on each latitude and longitude curve. By setting GD=10 degrees, we are setting the grid lines so that they may not be extremely accurate between calculated points. However, the first exercise below shows that the resulting difference in the curves is reasonably small (knowing that CPU time and CGM size both increase rapidly as GD gets smaller). Line 10 initializes Ezmap, and line 11 draws the grid lines and the limb line (the line around the globe).
If you plan to use idt to zoom in on an area one degree across, then you may want to draw the grid lines using points that are closer together on the globe; this increases the accuracy with which those lines are projected on the map.
- Using the UNIX command time, run the cmpgd example with GD=.001, and again with GD=1.0. What is the difference in CPU time on your machine? Plot the two plots on paper and compare their differences.
- Using cmpgd.f, change the grid spacing to 20 degrees.
- Using your own version of cezmap.f (from the Mp 2.2 exercises), add grid spacing to your subroutine call so that you can change it from your main program.
By default, the Ezmap utility draws grid lines using the Dashline utility. The default gridline pattern is a very short dash followed by a space of the same size. This pattern can be changed using the grid Dashline pattern parameter DA.
1 CALL MPSETR ('GR - GRID SPACING', 10.)
2 CALL MPSETR ('GD - GRID DRAWING RESOLUTION', 10.)
3 CALL MPSETI ('DA - GRID DASHLINE PATTERN', 64764)
4 CALL MAPINT
5 CALL MAPGRD
CALL MPSETI ('DA', ida)
- DA
- Integer---The grid DAshline parameter sets a dashed line pattern using the same interface as DASHDB. Construct a 16-bit binary number using 0s to represent blanks and 1s to represent dots or dashes, then convert to base 10. (For example, 0101010101010101 becomes 21845, which produces the dashed line used as the default grid pattern.)
Lines 1 and 2 of the cmpdd.f code segment set the grid spacing and accuracy just as in the previous module. Line 3 uses the DA parameter to change the grid pattern to one with long lines and small gaps. Line 4 initializes Ezmap, and line 5 draws the grid lines.
- Using the cmpdd example, make dash patterns use the following two sequences (parentheses enclose the spaces, they are not part of the dash pattern):
(- - - - - - )
(--- --- )
There are two parameters and a routine that affect labeling in Ezmap. The routine MAPLBL is called to draw the perimeter as well as labels at the north and south poles, the Greenwich meridian, and the international date line. The LA parameter turns labeling on and off, and LS controls label size.
1 CALL COLOR
2 CALL MPSETC ('OU - OUTLINE DATA FLAG', 'PO')
3 CALL MPSETI ('C2 - COLOR INDEX 2 - GRID', 2)
4 CALL MPSETI ('C4 - COLOR INDEX 4 - LIMB LINE', 2)
5 CALL MPSETI ('C1 - COLOR INDEX 1 - PERIMETER', 1)
6 CALL MPSETI ('C3 - COLOR INDEX 3 - LABELS', 1)
7 CALL MAPROJ ('SV', 40., -50., 0.)
8 CALL MPSETR ('SA - SATELLITE VIEW DISTANCE', 5.)
9 CALL MAPSET ('MA', PLIM1, PLIM2, PLIM3, PLIM4)
10 CALL MPSETI ('LA - MERIDIAN/POLE LABEL FLAG', 1)
11 CALL MPSETI ('LS - LABEL SIZE', 40)
12 CALL MAPINT
13 CALL MAPGRD
14 CALL MAPLBL
CALL MPSETI ('LA', ila)
CALL MPSETI ('LS', ils)
CALL MAPLBL
- LA
- Integer---The meridian/pole LAbel flag directs MAPLBL to draw labels at the prime meridian, international dateline, poles, and equator when LA<>0. When LA=0, no labels are drawn. The default is for labels to be drawn.
- LS
- Integer---The Label Size parameter controls label size using the formula NDC=LS/1024, where NDC is the size in NDCs, and LS is the value given to the LS parameter. The special values 0, 1, 2, and 3 produce labels sized at 0.008, 0.012, 0.016, and 0.024 NDCs, respectively. By default, LS=1 (0.012 NDCs).
Line 1 of the cmplbl.f code segment sets up the color table. Line 2 turns on drawing of continental and political outlines. Lines 3 through 6 set the color parameters so that everything drawn by MAPGRD is drawn in green (color index 2), and everything drawn by MAPLBL is drawn in orange (color index 1). Lines 7 through 9 set up the projection for a satellite view over the Atlantic Ocean.
Line 10 ensures that labels are drawn, and line 11 sets labels to be about 0.040 NDCs in size. Line 12 initializes Ezmap, line 13 draws the grid and limb lines, and line 14 draws the label and perimeter.
If LA is turned off, MAPLBL won't draw any labels. MAPLBL is also responsible for drawing the perimeter, if desired (when PE<>0). The cmplbl example uses white to show things drawn by MAPLBL, and green to show things drawn by MAPGRD.
- Using the cmplbl example, turn off drawing of the perimeter.
- Using the cmplbl example, set the size of the labels to the default value, but don't set LS=1.
- Using your own version of cezmap.f (from the Mp 2.2 exercises), set up your favorite label options.
The MAPLOT routine draws political and continental outlines. You can control how MAPLOT draws these outlines by using the parameters DO, DD, MV, and RE.
1 CALL COLOR
2 CALL MPSETC ('OU - OUTLINE DATA FLAG', 'PO')
3 CALL MPSETI ('C5 - COLOR INDEX 5 - CONTINENTAL OUTLINES', 5)
4 CALL MPSETI ('C7 - COLOR INDEX 7 - COUNTRY OUTLINES', 5)
5 CALL MPSETI ('C2 - COLOR INDEX 2 - GRID', 2)
6 CALL MPSETI ('C4 - COLOR INDEX 4 - LIMB LINE', 2)
7 CALL MPSETI ('C1 - COLOR INDEX 1 - PERIMETER', 1)
8 CALL MPSETI ('C3 - COLOR INDEX 3 - LABELS', 1)
9 CALL MAPROJ ('SV', 40., -50., 0.)
10 CALL MPSETR ('SA - SATELLITE VIEW DISTANCE', 5.)
11 CALL MAPSET ('MA', PLIM1, PLIM2, PLIM3, PLIM4)
12 CALL MPSETI ('DO - DOTTED OUTLINE FLAG', 1)
13 CALL MPSETI ('DD - DISTANCE BETWEEN DOTS', 7)
14 CALL MAPINT
15 CALL MAPGRD
16 CALL MAPLBL
17 CALL MAPLOT
CALL MPSETI ('DO', ido)
CALL MPSETI ('DD', idd)
CALL MAPLOT
- DO
- Integer---The Dotted Outline flag determines whether or not political and continental outlines are solid or dotted. By default DO=0, denoting solid outlines. When DO<>0, dotted outlines are drawn.
- DD
- Integer---The Distance between Dots parameter determines the space between dots in the dotted line pattern. By default, DD=12 out of 4096, or .003 NDCs. To calculate DD in NDCs, DD=INT(NDC*RE), where NDC is the distance in Normalized Device Coordinates, and RE is the resolution as set by the RE parameter.
- MV
- Integer---The Minimum Vector length for MAPIT parameter controls the minimum line segment length between two points. Points closer than MV to the previous point are omitted. By default, MV=4, or roughly .001 NDCs.
- RE
- Integer---The REsolution parameter determines the value DD is divided by to get NDCs. RE=4096 by default.
Line 1 of the cmplot.f code segment sets up the color table. Line 2 turns on drawing of the continental and political outlines. Lines 3 through 8 set the color parameters so that everything drawn by MAPGRD is drawn in green (color index 2), everything drawn by MAPLBL is drawn in orange (color index 1), and everything drawn by MAPLOT is drawn in magenta (color index 5). Lines 9 through 11 set up the projection for a satellite view over the Atlantic Ocean.
Line 12 turns on dotted line drawing of political and continental outlines, and line 13 spaces these outline dots closer together than the dots that form the grid lines. Line 14 initializes Ezmap, and line 15 draws the grid and limb lines. Line 16 draws the labels and perimeter, and line 17 draws the magenta outlines.
By default, continental outlines are drawn using solid lines from the Dashline utility. If you set DO nonzero, the continental outlines drawn as dots by Ezmap; Dashline is not used. DD controls the distance between dots.
Note: Most users don't need the RE parameter.
- Using the cmplot example, set the dots to be 0.005 NDCs apart.
- Using the cmplot example, draw solid continental outlines.
If all you are doing is calling MAPINT, MAPGRD, MAPLBL, and MAPLOT without any calls between, there is a shortcut that you can take to draw your map. MAPDRW calls MAPINT, MAPGRD, MAPLBL, and MAPLOT in that order, making it possible to combine four calls into one.
1 CALL COLOR
2 CALL MPSETC ('OU - OUTLINE DATA FLAG', 'PO')
3 CALL MPSETI ('C5 - COLOR INDEX 5 - CONTINENTAL OUTLINES', 5)
4 CALL MPSETI ('C7 - COLOR INDEX 7 - COUNTRY OUTLINES', 5)
5 CALL MPSETI ('C2 - COLOR INDEX 2 - GRID', 2)
6 CALL MPSETI ('C4 - COLOR INDEX 4 - LIMB LINE', 2)
7 CALL MPSETI ('C1 - COLOR INDEX 1 - PERIMETER', 1)
8 CALL MPSETI ('C3 - COLOR INDEX 3 - LABELS', 1)
9 CALL MAPROJ ('SV', 40., -50., 0.)
10 CALL MPSETR ('SA - SATELLITE VIEW DISTANCE', 5.)
11 CALL MAPSET ('MA', PLIM1, PLIM2, PLIM3, PLIM4)
12 CALL MPSETR ('GR - GRID SPACING', 10.)
13 CALL MPSETR ('GD - GRID DRAWING RESOLUTION', 10.)
14 CALL MPSETI ('LA - MERIDIAN/POLE LABEL FLAG', 1)
15 CALL MPSETI ('LS - LABEL SIZE', 40)
16 CALL MPSETI ('DO - DOTTED OUTLINE FLAG', 1)
17 CALL MPSETI ('DD - DISTANCE BETWEEN DOTS', 7)
18 CALL MAPDRW
CALL MAPDRW
Lines 1 through 11 of the cmpdrw.f code segment match lines 1 through 11 of the cmplot.f code segment in the preceding module. Line 1 sets up the color table. Line 2 turns on drawing of the continental and political outlines. Lines 3 through 8 set the color parameters so that everything drawn by MAPGRD is drawn in green (color index 2), everything drawn by MAPLBL is drawn in orange (color index 1), and everything drawn by MAPLOT is drawn in magenta (color index 5). Lines 9 through 11 set up the projection for a satellite view over the Atlantic Ocean.
Lines 12 and 13 of the cmpdrw.f code segment set grid parameters discussed in module "Mp 3.2 Grids: Drawing latitude and longitude lines." Lines 14 and 15 set label parameters discussed in the preceding module. Line 16 turns on dotted line drawing of political and continental outlines, and line 17 sets the dots closer together than gridline dots.
The shortcut occurs as line 18 calls MAPDRW. Notice that since MAPDRW calls MAPINT, calls to MAPROJ, MAPSET, and MAPPOS must be made before calling MAPDRW. Also, since MAPDRW calls MAPINT, MAPGRD, MAPLBL, and MAPLOT, parameters that affect those routines must be set before calling MAPDRW.
You can probably use MAPDRW in almost any simple map drawing. However,
as shown in Ezmap section "Mp
4. Producing maps with masking or filled areas," it is often
desirable to be able to call MAPINT and MAPLOT separately.
- Examine your own version of cezmap.f (from the Mp 2.2 exercises) to see if it can use MAPDRW.
Drawing maps with masking or filled areas is very much like drawing simple maps. However, it takes a few extra steps and uses a slightly different set of routines.
----------------------------------------------------------
1. Open GKS
2. Define position on plotter frame
3. Define map projection
4. Choose map limits
5. Choose desired political boundaries
* 6. Initialize Areas
* 7. Initialize Ezmap
* 8. Add geographic boundaries (or outlines) to area map
* 9. Draw geographic labels
10. Draw points and lines on your map
* 11. Draw desired latitude and longitude lines
* 12. Fill desired areas
13. Draw geographic outlines
14. Call FRAME
15. Close GKS
----------------------------------------------------------
* Steps discussed in this section.
Section "Mp 6. Table of Ezmap
area identifiers" and the MAPACI function can be used as tools
for choosing a particular geographic area or set of areas for filling,
shading, or masking.
1 SUBROUTINE MASK (XC, YC, MCS, AREAID, GRPID, IDSIZE)
2
3 INTEGER AREAID(IDSIZE), GRPID(IDSIZE), ID
4 REAL XC(MCS), YC(MCS)
5 DO 10, I=1, IDSIZE
6 IF (GRPID(I) .EQ. 1) ID = AREAID(I)
7 10 CONTINUE
8 IF ((MAPACI(ID) .EQ. 1) .AND. (MCS .GE. 2)) THEN
9 CALL CURVED (XC, YC, MCS)
10 ENDIF
11 RETURN
12 END
MAPACI (IDAREA)
- MAPACI
- Integer, Function---Obtains, for a given area, a suggested color index appropriate for use in creating a color map having adjacent areas of different colors. Returns an integer between 1 and 7 inclusive.
- IDAREA
- Integer, Input---Area identifier for an area defined by an
area map created by MAPBLA.
The "Sample Ezmap area identifier table" illustration shows
part of the table printed in section "Mp 6. Table of Ezmap area
identifiers." The first column of this table contains the
abbreviated name of the dataset in which the areas are defined. (PO
stands for Political Outlines, US stands for US state outlines, CO is
for Continental Outlines, and PS is for all of the above.)
The second column contains the area identifier for the area so you can uniquely address any area in the map database. The third column shows the suggested color index for the area. These color indices are carefully chosen so that no country or state has the same color as any of its neighbors. Also note that all bodies of water like oceans and lakes have a color index of 1. This makes it easy for your program to pick out the oceans for masking purposes or to choose an appropriate color for the oceans.
In line 8 of the cmpmsk.f code segment, note that MAPACI is called as a function rather than as a subroutine. MAPACI returns an integer value that can be used to detect ocean or land masses, to set color-fill values, and for many other purposes. A complete discussion of this code segment appears in module "Mp 4.6 Grid lines with masking: Writing a masking routine."
The Ezmap routine MAPBLA puts two groups of edges into an area map. Group 1 holds all the outline information for the maps; group 2 holds vertical strip outlines. This module discusses how to change which group identifiers are used, and how to set the number of vertical strips.
1 CALL MPSETI ('VS - VERTICAL STRIPS', 9)
2 CALL MPSETC ('OU - OUTLINE DATA FLAG', OUTLN)
3 CALL MPSETR ('GR - GRID SPACING', GRD)
4 CALL MAPROJ (PROJ, PLAT, PLON, ROTA)
5 IF (PROJ .EQ. 'SV') CALL MPSETR ('SA - SATELLITE VIEW DISTANCE', 5.)
6 CALL MAPSET (JLIM, PLIM1, PLIM2, PLIM3, PLIM4)
7 CALL MAPINT
CALL MPSETI ('VS', ivs)
CALL MPSETI ('G1', ig1)
CALL MPSETI ('G2', ig2)
- VS
- Integer---The Vertical Stripping parameter specifies the number of strips into which a plot is to be divided. Vertical strips can be created to minimize the number of points that define an area to be filled so that the plot can be drawn on limited hardware. By default, VS=1.
- G1
- Integer---The Group 1 parameter is the group identifier for the perimeter and the set of projected boundary lines implied by your map projection and limits.
- G2
- Integer---The Group 2 parameter is the group identifier for the perimeter and the boundary lines for vertical strips.
Currently, there are four groups of edges defined by default in NCAR Graphics:
- 1 Ezmap geographic information
- 2 Ezmap vertical strips
- 3 Conpack contour lines
- 4 Conpack vertical strips
Most people will never need to change any of these group identifiers. However, using Ezmap parameters G1 and G2, you can change the defaults of the first two groups. In most cases, you probably do not want to use the same values for Ezmap edge groups and Conpack edge groups.
The cmpgrp.f code segment creates a plot using nine vertical strips; this has the effect of making the areas created both smaller and simpler. Line 1 sets the number of vertical strips by giving VS the value of 9. Lines 2 through 9 then set up map drawing normally.
- Change the value of VS in cmpgrp.f, and watch how it is plotted to the screen.
Initializing Ezmap with Areas requires three routines. ARINAM initializes the area map, MAPINT initializes Ezmap, and MAPBLA is used to add the geographic outlines to the area map after both ARINAM and MAPINT have been called.
1 EXTERNAL MASK
2 CALL MAPINT
3 CALL ARINAM (MAP, LMAP)
4 CALL MAPBLA (MAP)
5 CALL MAPGRM (MAP, XWRK, YWRK, NWRK, IAREA, IGRP, ISIZ, MASK)
CALL MAPINT
CALL ARINAM (MAP, LMAP)
CALL MAPBLA (MAP)
- MAP(LMAP)
- Integer array, Workspace---An integer array in which an area map of the globe is to be constructed.
- LMAP
- Integer, Input---Length of the MAP array. LMAP is unchanged by the call.
Line 1 of the cmpmsk.f code segment declares the masking routine to be external so that the compiler knows that MASK is a subroutine rather than a variable. Line 2 initializes Ezmap and sets up our projection and map limits. Line 3 initializes the area map using the Areas routine ARINAM, and line 4 adds the projections of the geographic outlines to the area map.
Although MAPINT and ARINAM have been discussed previously, they are included in the synopsis because both routines are critical to using Ezmap with Areas. As shown before, MAPINT sets up the map limits and projection, defining a set of lines that divide up the plane. ARINAM initializes the area map array. MAPBLA takes the lines defined by MAPINT and adds them to the area map, using the default of edge group 1 for geographical map outlines and the default of edge group 2 for creating a set of vertical strips. Please see the previous module for further information on setting and using Ezmap group identifiers and vertical strips.
If you set the area map too small, the error message:
ERROR 5 IN AREDAM - AREA-MAP ARRAY OVERFLOW
occurs when MAPBLA is called. There is no good way to predict exactly how large the area map should be before adding edges to it. Try setting LMAP=50000 and increasing it as necessary. It is not unusual to need LMAP=250000 in maps with lots of tiny regions.
- Copy cmpmsk.f into your own directory and name it cmapa.f. Set it up so that you can change parameters (such as label size, grid options, and so on) at any time. You will use cmapa.f in subsequent exercises.
Just as we used MAPLBL to add labels to our simple map, we use it to write labels on a map with masked or filled areas. As before, the LA parameter turns labeling on and off, and the LS parameter controls label size for labels drawn by MAPLBL.
1 EXTERNAL MASK
2 CALL MPSETI ('LS - LABEL SIZE', 20)
3 CALL MAPINT
4 CALL ARINAM (MAP, LMAP)
5 CALL MAPBLA (MAP)
6 CALL MAPGRM (MAP, XWRK, YWRK, NWRK, IAREA, IGRP, ISIZ, MASK)
7 CALL MPSETI ('EL - ELLIPTICAL PERIMETER FLAG', 1)
8 CALL MAPLBL
9 CALL MAPLOT
CALL MAPLBL
CALL MPSETI ('LA', ila)
CALL MPSETI ('LS', ils)
- LA
- Integer---The meridian/pole LAbel flag directs MAPLBL to draw labels at the prime meridian, international dateline, poles, and equator when LA<>0. When LA=0, no labels are drawn. The default is for labels to be drawn.
- LS
- Integer---The Label Size parameter controls label size using the formula NDC=LS/1024 where NDC is the size in NDCs, and LS is the value given to the LS parameter. The special values 0, 1, 2, and 3 produce labels sized at 0.008, 0.012, 0.016, and 0.023 NDCs, respectively. By default, LS=1 (0.012 NDCs).
Line 1 of the cmplab.f code segment declares the masking routine to be external so that MAPGRM doesn't core dump. Line 2 sets the label size to be a bit larger than normal. Lines 3 and 4 initialize Ezmap and Areas respectively. Line 5 adds geographic and political outlines to the area map. Line 6 draws grid lines over water and uses the area map to mask them over land. Line 7 draws the ellipse that provides the limb line for this plot. Line 8 draws the labels.
If LA is turned off, MAPLBL does not draw any labels. MAPLBL also draws the perimeter if one is specified. The perimeter parameter PE<>0 by default.
- Change the cmplbl example so no perimeter is drawn.
- Using the cmplbl example, set the size of the labels to the default value but don't set LS=1.
- Using your own version of cmapa.f, set up your favorite label options.
The Ezmap routine MAPGRM allows you to draw grid lines and mask them over any geographic area such as oceans, land, or specific countries or continents.
1 EXTERNAL MASK
2 CALL MAPINT
3 CALL ARINAM (MAP, LMAP)
4 CALL MAPBLA (MAP)
5 CALL MAPGRM (MAP, XWRK, YWRK, NWRK, IAREA, IGRP, ISIZ, MASK)
6 CALL MAPLBL
7 CALL MAPLOT
CALL MAPGRM (MAP, XCS, YCS, MCS, IAREA, IGRP, ISIZ, LPR)
- MAP
- Integer array, Workspace---Area map initialized in ARINAM and constructed by MAPBLA.
- XCS(MCS), YCS(MCS)
- Real arrays, Workspace---Workspace used by MAPGRM in calls to the user-supplied routine LPR.
- MCS
- Integer, Input---Dimension of the arrays XCS and YCS. MCS must be greater than or equal to 2; the value 100 is suggested.
- IAREA(ISIZ), IGRP(ISIZ)
- Integer arrays, Workspace---To be used by MAPGRM in calls to the user-supplied routine LPR.
- ISIZ
- Integer, Input---Dimension of the arrays IAREA and IGRP. ISIZ must be greater than or equal to 2. If other groups of boundary lines are added to the area map (by calling MAPITA and MAPIQA or by calling AREDAM), then ISIZ must be increased by the number of such groups.
- LPR
- Subroutine---A user-supplied line-processing subroutine that is called once for each piece of the masked grid. Each such piece is contained in exactly one area defined by the area map. LPR must be declared external in the routine that calls MAPGRM. This subroutine is discussed in detail in the next module.
Line 1 declares MASK as external so that MAPGRM knows that MASK is a subroutine and not an integer variable. Lines 2 through 4 of the cmplab.f code segment initialize Ezmap with Areas, as discussed in module "Mp 4.3 Initialize Ezmap with Areas." Line 5 calls MAPGRM with the area map and the user-supplied masking subroutine MASK. MASK is discussed in the next module.
ISIZ, the size of the group and area identifier arrays (IAREA and IGRP), is determined by how many groups of lines you have added to the area map. Remember that the first group is the geographical outline set. Other groups might include vertical stripping if you are using it, contour lines, or lines that you may want to add to the area map using the Ezmap line-drawing routines.
Lines 6 and 7 label the globe and draw continental outlines.
Just as Areas doesn't really do any filling or masking, MAPGRD doesn't actually draw masked grid lines. MAPGRD calls a routine that you must write to correctly mask the grid lines. This makes it possible for you to precisely control which portions of the lines are masked.
1 SUBROUTINE MASK (XC, YC, MCS, AREAID, GRPID, IDSIZE)
2 INTEGER AREAID(IDSIZE), GRPID(IDSIZE), ID
3 REAL XC(MCS), YC(MCS)
4 DO 10, I=1, IDSIZE
5 IF (GRPID(I) .EQ. 1) ID = AREAID(I)
6 10 CONTINUE
7 IF ((MAPACI(ID) .EQ. 1) .AND. (MCS .GE. 2)) THEN
8 CALL CURVED (XC, YC, MCS)
9 ENDIF
10 RETURN
11 END
SUBROUTINE LPR (XCS, YCS, NCS, IAREA, IGRP, ISIZ)
DIMENSION XCS(*), YCS(*), IAREA(*), IGRP(*)
- LPR
- Subroutine---A user-supplied line-processing subroutine that is called once for each piece of the masked grid. Each such piece is contained in exactly one area defined by the area map. LPR must be declared external in the routine that calls MAPGRM. You must use the following structure when you write subroutine LPR:
SUBROUTINE LPR (XCS, YCS, NCS,
+ IAREA, IGRP, ISIZ)
DIMENSION XCS(*), YCS(*), IAREA(*),
+ IGRP(*)
- (code to process polyline defined by XCS, YCS, IAREA, and IGRP)
RETURN
END
- XCS(NCS), YCS(NCS)
- Real arrays, Input---Hold the X and Y coordinates, in the fractional coordinate system, of NCS points defining a piece of the grid. These are input arrays for the subroutine LPR.
- NCS
- Integer, Input---Number of X and Y coordinates in the arrays XCS and YCS.
- IAREA(ISIZ), IGRP(ISIZ)
- Integer arrays, Input---Hold ISIZ pairs of identifiers for the area within which the piece of the polyline lies. For each value of I from 1 to ISIZ, IAREA(I) is the area identifier for the area with respect to the group of edges specified by the group identifier IGRP(I).
- ISIZ
- Integer, Input---Number of values in IAREA and IGRP. ISIZ is equal to the number of groups of edges that you put in the area map.
- You can assume that MAPGRM has made this call:
CALL SET (VPL, VPR, VPB, VPT, VPL, VPR, VPB, VPT, 1)
- This call ensures correct results if the normalized device coordinates in XCS and YCS are used in calls to such routines as the GKS line-drawing routine GPL or the Dashline routine CURVED. LPR may make its own SET call to achieve some other effect.
In this code segment, the line processing routine (shown as LPR in the synopsis) is named MASK. Lines 4 through 6 set up a do loop to extract the geographic area identifier of the region passed into MASK. Line 7 checks to see if the region is over land or water, and it checks to see if the line has at least two points in it. If both conditions are true, then the line is drawn with the Dashline routine CURVED in line 8. Otherwise, no line is drawn.
By using the color identifier to pick out land values, you could draw
grid lines only over land. Similarly, by looking up the area
identifiers for a given country in section "Mp 6. Table of Ezmap area
identifiers," you could draw grid lines either only over a
given country, or over everything except a given country.
- Using cmpmsk.f, modify MASK so that it draws grid lines only over land masses.
- Modify your own version of cmapa.f (from the Mp 4.3 exercises) so it draws only the grid lines that you want.
In this module, we use the Areas routine ARSCAM to fill areas, just as we did in the Areas chapter of this tutorial. The biggest difference is in the way we choose the areas to be filled.
1 CALL COLOR
2 CALL MAPINT
3 CALL ARINAM (MAP, LMAP)
4 CALL MAPBLA (MAP)
5 CALL GSFAIS (1)
6 CALL ARSCAM (MAP, XWRK, YWRK, NWRK, IAREA, IGRP, ISIZ, FILL)
7 CALL MAPGRM (MAP, XWRK, YWRK, NWRK, IAREA, IGRP, ISIZ, MASK)
8 CALL MAPLOT
CALL ARSCAM (MAP, XWRK, YWRK, NWRK, IAREA, IGRP, ISIZ, FILL)
- MAP
- Integer array, Workspace---The area map that has been initialized by a call to ARINAM and to which edges have been added by calls to AREDAM. If you did not preprocess the area map by calling ARPRAM, ARSCAM calls it before doing anything else.
- XWRK(NWRK), YWRK(NWRK)
- Real arrays, Workspace---The X and Y coordinates defining the edge of a given area, for use by ARSCAM in calls to the area-processing routine APR.
- NWRK
- Integer, Input---Dimension of each of the arrays XWRK and YWRK. A nice size for NWRK is 1000.
- IAREA(ISIZ), IGRP(ISIZ)
- Integer arrays, Workspace---Each dimensioned NGRPS, for use by ARSCAM in calls to the area-processing routine APR.
- ISIZ
- Integer, Input---Dimension of each of the arrays IAREA and IGRP. ISIZ>=n, where n is the number of groups in the area map.
- FILL
- Subroutine---A user-supplied area-processing routine that is called by ARSCAM and that must be declared external in the routine that calls ARSCAM. The FILL subroutine is described in full detail in the next module.
Line 1 of the cmpfil.f code segment sets up the color table. Lines 2, 3, and 4 initialize Ezmap and Areas, then add the geographic map to the area map.
Line 5 sets the GKS interior fill style to "solid" to produce solid fill. Line 6 calls the Areas scan area map routine with user-supplied fill routine so that each country is filled. Line 7 draws the grid lines over water, and line 8 draws the continental and political boundaries. The order of the overlaying done by these calls is critical to produce proper results. You must call detail-drawing routines after filling, since color-fill draws over anything that might have been there previously.
- Using your own version of cmapa.f (from the Mp 4.3 exercises), set it up to fill the regions of your choice. You may also want to choose a different color table for your routine.
The fill routine you write to work with Ezmap is nearly identical to one you would use to fill any type of area. Because there are so many area identifiers in Ezmap, Ezmap provides a tool that allows you to fill water with one color or fill pattern, then fill adjacent countries or states with different colors or fill patterns. This tool is a function named MAPACI.
1 SUBROUTINE FILL (XWRK, YWRK, NWRK, IAREA, IGRP, IDSIZ)
2 DIMENSION XWRK(*), YWRK(*), IAREA(*), IGRP(*)
3 ID=0
4 DO 10, I=1, IDSIZ
5 IF (IGRP(I) .EQ. 1) ID = IAREA(I)
6 10 CONTINUE
7 IF (ID .GE. 1) THEN
8 CALL GSFACI (MAPACI(ID) + 1)
9 CALL GFA (NWRK, XWRK, YWRK)
10 ENDIF
11 RETURN
12 END
SUBROUTINE FILL (XWRK, YWRK, NWRK, IAREA, IGRP, NGRPS)
DIMENSION XWRK(*), YWRK(*), IAREA(*), IGRP(*)
- FILL
- Subroutine---A user-supplied area-processing routine that is called by ARSCAM and that must be declared external in the routine that calls ARSCAM. The FILL subroutine must have the following form:
SUBROUTINE FILL (XWRK, YWRK, NWRK, IAREA, IGRP, NGRPS)
DIMENSION XWRK(*), YWRK(*), IAREA(*), IGRP(*)
- (code to process the area defined by XWRK, YWRK, IAREA, and IGRP)
RETURN
END
- XWRK(NWRK), YWRK(NWRK)
- Real arrays, Input---The X and Y coordinates, in the fractional coordinate system, of NWRK points defining a polygonal area. The last of these points is a duplicate of the first. Holes in an area are traced in such a way as to maximize the probability of hardware fill working properly by using vertical lines to get to and from the holes and tracing them in the proper direction.
- NWRK
- Integer, Input---Number of X and Y coordinates in the arrays XWRK and YWRK. A nice starting value for NWRK is 1000.
- IAREA(NGRPS), IGRP(NGRPS)
- Integer arrays, Input---Hold NGRPS pairs of identifiers for the area defined by XWRK and YWRK. For each value of I from 1 to NGRPS, IAREA(I) is the area identifier for the area with respect to the group of edges specified by the group identifier IGRP(I).
- NGRPS
- Integer, Input---Number of values in IAREA and IGRP. NGRPS is equal to the number of groups of edges that you put in the area map.
As discussed in module "Mp 4.1 Color and area identifiers in
Ezmap," you can either isolate an area by looking up its area
identifiers in section "Mp 6.
Table of Ezmap area identifiers," or you can isolate the
desired area using the color index. In this case, we want to ensure
that oceans having an Ezmap color index of 1 are colored aquamarine,
which has a GKS color index of 2.
Lines 4 through 6 of the cmpfil.f code segment retrieve the area identifier for the geographic region by checking each element of the group array for group identifier 1, and assigning its associated area id to ID. Line 7 checks to see if the area is over the map, and if so, line 8 chooses a color index by retrieving the suggested Ezmap color using MAPACI. Line 9 fills the area.
- Use section "Mp 6.
Table of Ezmap area identifiers" or the ngfile utility
to determine the correct area identifier, then use the cmpfil
example to change the color of Canada to be different than either the
US or Russia.
- Using your own version of cmapa.f (from the Mp 4.3 exercises), modify it to do color fill.
Ezmap has two routines that project points onto a map, two sets of routines for adding lines to a map, and one routine that finds the latitude and longitude of a point whose projection on the u/v plane is known. The first set of routines deals strictly with adding lines to geographic or "simple" maps (drawing the lines), and the second set of routines adds lines to an area map (subdividing areas, but no lines are drawn). This section discusses each of these types of routines in detail.
----------------------------------------------------------
1. Open GKS
2. Define position on plotter frame
3. Define map projection
4. Choose map limits
5. Choose desired political boundaries
6. Initialize Areas
7. Initialize Ezmap
8. Add geographic boundaries (or outlines) to area map
9. Draw geographic labels
* 10. Draw points and lines on your map
11. Draw desired latitude and longitude lines
12. Fill desired areas
13. Draw geographic outlines
14. Call FRAME
15. Close GKS
----------------------------------------------------------
* Steps discussed in this section.
Ezmap offers two routines that project points onto a geographic map: MAPTRA and MAPTRN. Given the latitude and longitude of a point on the globe, both routines return the u/v coordinates of that point's projection. You can then take this information and do nearly anything with it, like draw a label or a polymarker. Conpack uses MAPTRA to project and draw contour lines.
1 CALL MAPDRW
3 CALL MAPTRA (40., -105.15, X, Y)
4 IF (X .NE. 1.E12) CALL POINTS (X, Y, 1, -3, 0)
CALL MAPTRA (RLAT, RLON, UVAL, VVAL)
- RLAT
- Real, Input---The latitude of a point on the globe. RLAT must be between -90.0 and +90.0 inclusive.
- RLON
- Real, Input---The longitude of a point on the the globe. RLON must be between -540.0 and +540.0 inclusive. Positive longitudes are measured eastward from the Greenwich meridian, and negative longitudes are measured westward from the Greenwich meridian.
- UVAL, VVAL
- Real, Output---The point (UVAL, VVAL) is the point on the u/v plane into which the point with latitude RLAT and longitude RLON projects. The units of UVAL and VVAL depend on the projection.
MAPTRA is identical to MAPTRN, with one exception: if the point is outside the boundary of the map, MAPTRA returns UVAL equal to 1.E12 and MAPTRN returns the u/v coordinates for the point. If you use MAPTRN, you may need to check to determine if the point is within limits.
If the point is not projectable on the map, both routines return UVAL equal to 1.E12.
Line 1 of the cmptra.f code segment draws the map as a reminder that the map projection and limits have been set up and that the map has been drawn. Line 3 calls MAPTRA to get the user coordinates of the point. If the coordinates are on the projection, then an asterisk is drawn over Boulder, Colorado, USA. MAPTRN or MAPTRA can be called any time after MAPINT is called.
- Using a full-globe mercator projection, draw a red circle over Lhasa, Tibet (29., 91.)
- Using the preceding exercise, write the city names over Beijing, China (39., 116.) and Machu Picchu, Peru (-13., -72.).
Sometimes it is necessary to find the latitude and longitude values of a point, knowing only the user coordinates set up by the map transformation. MAPTRI allows you to do this for all Ezmap plots.
1 DO 103, I=1, NCLS
2 X = CFUX (.05 + .90 * (REAL (I-1) + .5) / REAL (NCLS))
3 DO 102, J=1, NCLS
4 Y = CFUY (.05 + .90 * (REAL (J-1) + .5) / REAL (NCLS))
5 CALL MAPTRI (X, Y, RLAT, RLON)
6 IF (RLAT .NE. 1.E12) THEN
7 DVAL = .25 * (1. + COS (DTOR * 10. * RLAT)) +
+ .25 * (1. + SIN (DTOR * 10. * RLON)) * COS (DTOR * RLAT)
8 ICRA (I,J) = MAX (2, MIN (NCLR+1, 2+INT (DVAL * REAL (NCLR))))
9 ELSE
10 ICRA (I,J) = 0
11 ENDIF
12 102 CONTINUE
13 103 CONTINUE
14 CALL GCA (CFUX(.05), CFUY(.05), CFUX(.95), CFUY(.95), 1000, 1000,
+ 1, 1, NCLS, NCLS, ICRA)
15 CALL MAPDRW
CALL MAPTRI (X, Y, RLAT, RLON)
- X, Y
- Real, Input---The X and Y user coordinates of the point for which you want latitude and longitude values.
- RLAT, RLON
- Real, Output---The latitude and longitude values for a point specified in user coordinates. If RLAT=1.E12, then the point is outside the map projection.
The mpex10 example uses MAPTRI to create a cell array representing a data field on a projected globe.
Lines 1 through 13 of the mpex10.f code segment pick values to fill a cell array that will be used to color the globe. In line 2, CFUX takes an X coordinate in NDCs and returns an X coordinate in user coordinates. Similarly, CFUY in line 4 takes a Y coordinate of a point in NDCs and returns a Y value in user coordinates.
Line 5 uses MAPTRI to retrieve the coordinates of the point in latitude and longitude. Since MAPTRI returns a value of RLAT=1.E12 if the point is not over a plotted portion of the globe, line 6 checks to see if the point maps onto the portion of the globe that will be plotted. If it does, then a value for the cell array is specified there. Otherwise, line 10 sets the cell array element to black. Line 14 fills the cell array, and line 15 draws the map over it.
- Modify mpex10.f to put a cell array only over the United States.
There are two routines to help you add lines to geographic maps. MAPIT draws line segments and omits nonvisible portions. MAPIQ terminates line segments drawn by MAPIT.
1 CALL MAPDRW
2 CALL MAPIT (37., -109., 0)
3 CALL MAPIT (41., -109., 1)
4 CALL MAPIT (41., -102., 1)
5 CALL MAPIT (37., -102., 1)
6 CALL MAPIT (37., -109., 1)
7 CALL MAPIQ
CALL MAPIT (RLAT, RLON, IFST)
CALL MAPIQ
- RLAT
- Real, Input---The latitude, in degrees, of a point to which the "pen" is to be moved. RLAT must be between -90. and +90., inclusive.
- RLON
- Real, Input---The longitude, in degrees, of a point to which the "pen" is to be moved. RLON must be between -540. and +540., inclusive.
- IFST
- Integer, Input---The first point flag allows you to control whether or not line segments are drawn.
- 0 Do a "pen-up" move. IFST should be zero for the first point in each curve.
- 1 Do a "pen-down" move only if the distance from the last point to the new point is greater than MV/RE. IFST should be positive for any point after the first point in a curve.
- >1 Do a "pen-down" move regardless of the distance from the last point to the new one. IFST should be positive for any point after the first point in a curve.
MAPIT draws lines on the map. It is called by Ezmap and, if desired, it can be called by the user. MAPIT attempts to omit nonvisible portions of lines and to handle "crossover"---the jump from one side 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. Crossover can occur on cylindrical and conical projections; MAPIT handles it gracefully on the former and not so well on the latter.
The Ezmap parameter DL determines whether MAPIT 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 parameters DD and MV also affect the behavior of MAPIT. Fo