Using The Dmapf Routines (C)
The Dmapf routines are an extension of the Cmapf routines
to a general orientation of projection surface to the Earth's
surface. The Cmapf routines are a library of C-language
subroutines and functions which process geographic and
dynamic data between grids and geographical coordinates
on a family of conformal map projections.
The Cmapf routines deal only with the cases in which the
projection surfaces are either axially aligned with the
Earth's North-South axis, (in the case of the Mercator
Cylindrical or the Lambert Conic Projection) or orthogonal
to the Earth's axis (in the case of the Polar Stereographic
Projection.
The Dmapf routines extend the Cmapf routines by allowing
projection surfaces whose axes lie in the equatorial plane
(transverse Mercator and Transverse Lambert) or in other
directions (Oblique Stereographic, orthogonal to a diameter
through any specified point on the Earth's surface). Oblique
Mercator and Lambert projections are provided for, but
rarely used.
Data characterizing the map projections and the grids
on them is embedded in maparam structures. Note: in all
cases, North latitudes will be given as positive degrees,
South latitudes negative degrees, East longitudes positive
degrees and West longitudes negative degrees.
Initializing (configuring) the maparam structure:
- Stage I - Selecting a Map Projection.
-
To initialize a map parameter (maparam) structure
with a Conformal Polar Projection, use any one of the
following subroutines:
- Normal (aligned with Earth's axis) Projections
- #include cmapf.h
- maparam stcprm;
- double reflat,reflon,tnglat;
- stlmbr(&stcprm, reflat, reflon);
or
equivalently
- stcmap(&stcprm, tnglat, reflon);
for a normal (polar) Lambert projection with reflat
being the latitude at which the projection plane,
cone, or cylinder is tangent to the Earth, while
reflon is the longitude of some point 180 degrees
away from the cut. This operates exactly the same
as in the Cmapf routines.
- Transverse (aligned with an equatorial diameter)
Projections
- #include cmapf.h
- maparam stcprm;
- double r_lat,r_long;
- stvmrc(&stcprm, r_lat, r_long);
will define a transverse Mercator projection onto
a cylinder tangent to the Earth along a meridian.
The meridian passes through the reference point r_lat,r_long,
and has the least distortion near that meridian.
The cylinder is cut half way from the reference
point, and the cut is the projection of a great
semi-circle, 180 degrees away from the r_lat latitude,
extending to equatorial points 90 degrees removed
from the r_long meridian.
- Oblique (aligned with any other diameter) Projections:
- #include cmapf.h
- maparam stcprm;
- double r_lat,r_lon,an_lat,an_lon,a_lat1,a_lng1,a_lat2,a_lng2;
- sobstr(&stcprm, r_lat,r_lon);
- sobmrc(&stcprm, r_lat,r_lon, an_lat,an_lon);
or
- soblmb(&stcprm, r_lat,r_lon, a_lat1,a_lng1,
a_lat2,a_lng2);
will define, respectively, the oblique Stereographic, oblique
Mercator, and oblique Lambert Conformal projections.
In each case, r_lat and r_lon are the latitude
and longitude of the reference point,
which is the point on the Earth at which this
map's distortion is least (because the gradient
of the scale is zero) and which is furthest from
any cut.
an_lat,an_lon, a_lat1,a_lng1, a_lat2,and a_lng2
are latitudes and longitudes of anchor points,
which inform the routines of the location of the
tangent circles for the Mercator and Lambert projections,
respectively. The reference point, together with
one or two anchor points, define the circle at
which the projection surface is tangent to the
Earth.
In the Stereographic case, the one point r_lat,r_long
is the point where the projection plane is tangent
to the Earth.
In the Mercator case, two points define a great
circle, at which the projection cylinder is tangent
to the Earth. The reference and anchor points must
be two different points.
In the Lambert Conic Conformal case, three points
are required to define a small circle at which
the projection cone is tangent to the Earth's surface.
The reference point and the anchor point(s) must
be three distinct points.
The above routines allow for an extensive selection
of projection types, but in practice, most projections
will consist of the normal projections, the transverse
Mercator, and the Oblique Stereographic.
Whichever of the above routines is selected, it will
fill the structure "stcprm" with default data specifying
the selected projection on the appropriate surface
tangent to the globe at the indicated point or circle.
If a cut is needed to lay the cone or cylinder out
flat on the plane, it will be made opposite to (the
maximum distance from) the reference point.
- Stage II - Laying out a grid on a selected map projection.
-
This stage configures the maparam structure with the
information to locate the points of the grid on the
selected map projection selected in Stage I above.
Two alternative means are provided: Either One-Point
specification or Two-Point specification.
- Two-Point Specification:
- maparam stcprm;
- double x1,y1,xlat1,xlon1, x2,y2,xlat2,xlon2;
- stcm2p(&stcprm, x1,y1,xlat1,xlon1, x2,y2,xlat2,xlon2);
causes stcprm to be configured so that the grid
point with grid coordinates x1,y1 will be located
on the map at latitude xlat1, longitude xlon1,
while x2,y2 is located on the map at xlat2, xlon2.
The two points must be different. This specification
locates all other grid points, assumed arranged
on the projection with equal spacing in the x-
and y- directions.
The two points will often be opposite corners
of the intended grid, but many times a different
selection will be preferred. For example, in a
Mercator projection, it will often be better to
select two points of the same latitude or the same
longitude, to ensure exact N-S orientation of the
grid. Alternatively, several subgrids of an overall
grid may be guaranteed compatibility by using the
same two points of the overall grid, even if neither
of the points lie in the subgrid at all.
- One-Point Specification:
- maparam stcprm;
- double x1,y1,xlat1,xlon1, scalat,scalon, gsize,orient;
- stcm1p(&stcprm, x1,y1,xlat1,xlon1, scalat,scalon,
gsize,orient);
causes stcprm to be configured so that the grid
point with grid coordinates x1,y1 will be located
on the map at latitude xlat1, longitude xlon1.
The remaining configuration information is provided
at the scaling point whose latitude and longitude
are scalat, scalon. At that point, and incidentally
every point on the latitude circle scalat, the
size of a grid cell is gsize in both the x- and
y- directions. Finally, at the scaling point, the
y-lines of the grid make an angle of "orient" degrees
clockwise (East) of the scalon meridian.
The x1,y1 coordinates can be thought of as "pinning" that
grid point to the map at xlat1,xlon1, the gsize
value can be thought of as "zooming" the grid in
and out until the desired size is attained, and
the "orient" specification can be thought of as
rotating the grid about the pinned point until
the y-axis through the scaling point has the desired
bearing.
Frequently, a grid will be published as having
an "lov" value of a longitude intended to be vertical;
for such grids, scalon=lov and orient=0.
Using the configured maparams:
- Coordinate transforms:
-
- maparam stcprm;
- double xlat,xlon, x,y;
- cll2xy(&stcprm, xlat,xlon, &x,&y);
will return grid coordinates x,y according to the
grid configured as stcprm, for the point whose latitude
and longitude are xlat,xlon. Longitude values are adjusted
to fit between reflon-180. and reflon+180., so that
nearby points on the globe remain nearby points on
the map, unless they straddle the "cut" at longitude
reflon+180., and find themselves on opposite edges
of an unrolled cylinder.
- maparam stcprm;
- double xlat,xlon, x,y;
- cxy2ll(&stcprm, x,y, &xlat,&xlon);
will return latitude and longitude parameters according
to the grid configured as stcprm, for the point whose
grid coordinates are x,y. Longitude values will be
returned in the range from -180. to +180.
If the point x,y corresponds to the North or South
Pole, where longitude is undefined, the returned longitude
will be 180. for the North Pole, 0. for the South Pole,
conforming to the WMO standard for reporting winds
there. (In an earlier version of CMAPF, the value of
reflon was returned at the poles.)
- Wind Vector transforms:
-
- maparam stcprm;
- double xlat,xlon, ue,vn, ug,vg;
- cc2gll(&stcprm, xlat,xlon, ue,vn, &ug,&vg);
and
- cg2cll(&stcprm, xlat,xlon, ug,vg, &ue,&vn);
will convert the East- and North- components ue,vn
(Cartographic components) of the wind to and from components
ug,vg of the wind in the x- and y- directions of the
grid (Grid components). The first transfers from cartographic
components to grid components, the second does the
reverse. In both cases, the wind is that observed at
the specified cartographic coordinates xlat,xlon.
At the poles (xlat=90. or xlat= -90.), the direction
of "North", which determines the meaning of ue and
vn, is based on the nominal value of longitude. The
direction of North will agree with that perceived by
an observer stationed a short distance away on the
xlon meridian. Thus, if xlat,xlon = 90.,-70., "North" will
be assigned to the direction of the 110E meridian.
- cc2gxy(&stcprm, x,y, ue,vn, &ug,&vg);
and
- cg2cxy(&stcprm, x,y, ug,vg, &ue,&vn);
will convert the East- and North- components ue,vn
(Cartographic components) of the wind to and from components
ug,vg of the wind in the x- and y- directions of the
grid (Grid components). The first transfers from cartographic
components to grid components, the second does the
reverse. In both cases, the wind is that observed at
the specified grid coordinates x,y.
If x,y refers to the North or to the South pole, the
orientation of "North" is defined according to World
Meteorological Organization (WMO) code 878. The direction
of "North" is that of the Greenwich meridian, which
is the equivalent of using xlat=90.,xlon=180. for the
North Pole, and xlat=-90.,xlon=0. for the South Pole.
- cw2gll(&stcprm, xlat,xlon, ue,vn, &ug,&vg);
- cg2wll(&stcprm, xlat,xlon, ug,vg, &ue,&vn);
- cw2gxy(&stcprm, x,y, ue,vn, &ug,&vg);
and
- cg2wxy(&stcprm, x,y, ug,vg, &ue,&vn);
perform the same services as the above transforms,
except that within 1 degree (111km or 60nm) or either
pole, ue and vn are interpreted according to WMO code
878 above. In an earlier version of CMAPF, this was
the definition of the c2g and g2c routines, above.
- Gridsize Evaluation:
-
- maparam stcprm;
- double gsize,xlat,xlon,x,y;
- gsize = cgszll(&stcprm, xlat,xlon);
and
- gsize = cgszxy(&stcprm, x,y);
return the size, in kilometers, of a grid cell at
the indicated point.
- Curvature Vector:
-
- maparam stcprm;
- double x,y,gx,gy,xlat,xlon;
- ccrvxy (&stcprm, x,y, &gx,&gy);
and
- ccrvll (&stcprm, xlat,xlon, &gx,&gy);
return, in gx and gy, the logarithmic gradient of
the scale. This vector represents the curvature on
the Earth of a straight line segment on the map. Units
are in radians per kilometer on the Earth's surface.
See the paper for details on usage in equations.
- North Polar Vector evaluations:
-
- maparam stcprm;
- double x,y, xlat,xlon, enx,eny,enz;
- cpolxy (&stcprm, x,y, &enx,&eny,&enz);
and
- cpolll (&stcprm, xlat,xlon, &enx,&eny,&enz);
return, in enx, eny, and enz the components of the
direction of the Earth's axis. Components enx and eny
provide the local direction of North in grid coordinates,
while enz is proportional to the local Coriolis parameter.
- Other Routines:
-
In addition to the functions defined above for the
end user, there are also a number of functions that
assist the end-user routines, but are not generally
used by the end user. These functions include
- functions returning void:
- mpstrt, basm2g, basg2m, proj_3d, geo_ll, ll_geo,
xy_map, map_xy, map_xe, xe_map, xe_xy, xy_xe, cgrnll
and cgrnxy
- functions returning double:
- x_prod, cml2xy, csabva, snabva, lnabva, xpabva
and atnabv
These function names should not be used in code created
by the end user.
|