NCL Website header
NCL Home > Documentation > HLUs > Classes

MapTransformation class

The MapTransformation manages forward and reverse transformations in the coordinate space defined by various map projections.

Synopsis

Header file:		ncarg/hlu/MapTransformation.h
Class name:		mapTransformationClass
Class pointer:		<Not referenceable>
Fortran class function:	<Not referenceable>
Supeclass:		Transformation
Composite classes:	<None>

Class-defined types

Type name:		NhlTMapLimitMode
Definition:
typedef enum _NhlMapLimitMode {
	NhlMAXIMALAREA	= 0,	/* "MaximalArea" */ 
	NhlLATLON	= 1,	/* "LatLon"	 */ 
	NhlANGLES	= 2,	/* "Angles"	 */ 
	NhlNPC		= 3,	/* "NPC"	 */
	NhlNDC		= 4,	/* "NDC"	 */
	NhlCORNERS	= 5,	/* "Corners"	 */ 
	NhlPOINTS	= 6,	/* "Points"	 */
	NhlWINDOW	= 7	/* "Window"	 */ 
} NhlMapLimitMode;

Type name:		NhlTProjection
Definition:
typedef enum _NhlProjection {
	NhlORTHOGRAPHIC		  = 0, /* "Orthographic"	   */
	NhlSTEREOGRAPHIC	  = 1, /* "Stereographic"	   */
	NhlLAMBERTEQUALAREA	  = 2, /* "LambertEqualArea"	   */
	NhlGNOMONIC		  = 3, /* "Gnomonic"		   */
	NhlAZIMUTHALEQUIDISTANT	  = 4, /* "AzimuthalEquidistant"   */
	NhlSATELLITE		  = 5, /* "Satellite"		   */
	NhlPSEUDOMOLLWEIDE	  = 6, /* "PseudoMollweide"	   */
	NhlMERCATOR		  = 7, /* "Mercator"		   */
	NhlCYLINDRICALEQUIDISTANT = 8, /* "CylindricalEquidistant" */
	NhlLAMBERTCONFORMAL	  = 9, /* "LambertConformal"	   */
	NhlROBINSON		  = 10 /* "Robinson"		   */
        NhlCYLINDRICALEQUALAREA   = 11 /* "CylindricalEqualArea"   */
	NhlROTATEDMERCATOR        = 12 /* "RotatedMercator"        */
        NhlAITOFF                 = 13 /* "Aitoff"                 */
        NhlHAMMER                 = 14 /* "Hammer"                 */
        NhlMOLLWEIDE              = 15 /* "Molleweide"             */
        NhlWINKELTRIPEL           = 16 /* "WinkelTripel"           */
} NhlProjection;

Resources

Local resources

You may access MapTransformation resources only through objects that instantiate a MapTransformation child object. These include:

+---------------------------------------------------------------+
|			MapTransformation Resource Set		|
|---------------------------------------------------------------|
| NAME				TYPE			ACCESS	|
|	CLASS				DEFAULT			|
|===============================================================|
| mpProjection                  NhlTProjection          RCSG    |
|       MpProjection                  "CylindricalEquidistant"  |
|---------------------------------------------------------------|
| mpLeftMapPosF                 NhlTFloat               G       |
|       MpLeftMapPosF                   <dynamic>               |
|---------------------------------------------------------------|
| mpRightMapPosF                NhlTFloat               G       |
|       MpRightMapPosF                  <dynamic>               |
|---------------------------------------------------------------|
| mpBottomMapPosF               NhlTFloat               G       |
|       MpBottomMapPosF                 <dynamic>               |
|---------------------------------------------------------------|
| mpTopMapPosF                  NhlTFloat               G       |
|       MpTopMapPosF                    <dynamic>               |
|---------------------------------------------------------------|
| mpCenterLatF                  NhlTFloat               RCSG    |
|       MpCenterLatF                    0.0                     |
|---------------------------------------------------------------|
| mpCenterLonF                  NhlTFloat               RCSG    |
|       MpCenterLonF                    0.0                     |
|---------------------------------------------------------------|
| mpCenterRotF                  NhlTFloat               RCSG    |
|       MpCenterRotF                    0.0                     |
|---------------------------------------------------------------|
| mpLimitMode                   NhlTMapLimitMode        RCSG    |
|       MpLimitMode                     "MaximalArea"           |
|---------------------------------------------------------------|
| mpMinLatF                     NhlTFloat               RCSG    |
|       MpMinLatF                       -90.0                   |
|---------------------------------------------------------------|
| mpMaxLatF                     NhlTFloat               RCSG    |
|       MpMaxLatF                       90.0                    |
|---------------------------------------------------------------|
| mpMinLonF                     NhlTFloat               RCSG    |
|       MpMinLonF                       -180.0                  |
|---------------------------------------------------------------|
| mpMaxLonF                     NhlTFloat               RCSG    |
|       MpMaxLonF                       180.0                   |
|---------------------------------------------------------------|
| mpRelativeCenterLat           NhlTBoolean             RCSG    |
|       MpRelativeCenterLat             False                   |
|---------------------------------------------------------------|
| mpRelativeCenterLon           NhlTBoolean             RCSG    |
|       MpRelativeCenterLon             False                   |
|---------------------------------------------------------------|
| mpLeftAngleF                  NhlTFloat               RCSG    |
|       MpLeftAngleF                    80.0                    |
|---------------------------------------------------------------|
| mpRightAngleF                 NhlTFloat               RCSG    |
|       MpRightAngleF                   80.0                    |
|---------------------------------------------------------------|
| mpBottomAngleF                NhlTFloat               RCSG    |
|       MpBottomAngleF                  80.0                    |
|---------------------------------------------------------------|
| mpTopAngleF                   NhlTFloat               RCSG    |
|       MpTopAngleF                     80.0                    |
|---------------------------------------------------------------|
| mpLeftNPCF                    NhlTFloat               RCSG    |
|       MpLeftNPCF                      0.0                     |
|---------------------------------------------------------------|
| mpRightNPCF                   NhlTFloat               RCSG    |
|       MpRightNPCF                     1.0                     |
|---------------------------------------------------------------|
| mpBottomNPCF                  NhlTFloat               RCSG    |
|       MpBottomNPCF                    0.0                     |
|---------------------------------------------------------------|
| mpTopNPCF                     NhlTFloat               RCSG    |
|       MpTopNPCF                       1.0                     |
|---------------------------------------------------------------|
| mpLeftNDCF                    NhlTFloat               RCSG    |
|       MpLeftNDCF                      <dynamic>               |
|---------------------------------------------------------------|
| mpRightNDCF                   NhlTFloat               RCSG    |
|       MpRightNDCF                     <dynamic>               |
|---------------------------------------------------------------|
| mpBottomNDCF                  NhlTFloat               RCSG    |
|       MpBottomNDCF                    <dynamic>               |
|---------------------------------------------------------------|
| mpTopNDCF                     NhlTFloat               RCSG    |
|       MpTopNDCF                       <dynamic>               |
|---------------------------------------------------------------|
| mpLeftCornerLatF              NhlTFloat               RCSG    |
|       MpLeftCornerLatF                0.0                     |
|---------------------------------------------------------------|
| mpLeftCornerLonF              NhlTFloat               RCSG    |
|       MpLeftCornerLonF                0.0                     |
|---------------------------------------------------------------|
| mpRightCornerLatF             NhlTFloat               RCSG    |
|       MpRightCornerLatF               0.0                     |
|---------------------------------------------------------------|
| mpRightCornerLonF             NhlTFloat               RCSG    |
|       MpRightCornerLonF               0.0                     |
|---------------------------------------------------------------|
| mpLeftPointLatF               NhlTFloat               RCSG    |
|       MpLeftPointLatF                 0.0                     |
|---------------------------------------------------------------|
| mpLeftPointLonF               NhlTFloat               RCSG    |
|       MpLeftPointLonF                 0.0                     |
|---------------------------------------------------------------|
| mpRightPointLatF              NhlTFloat               RCSG    |
|       MpRightPointLatF                0.0                     |
|---------------------------------------------------------------|
| mpRightPointLonF              NhlTFloat               RCSG    |
|       MpRightPointLonF                0.0                     |
|---------------------------------------------------------------|
| mpBottomPointLatF             NhlTFloat               RCSG    |
|       MpBottomPointLatF               0.0                     |
|---------------------------------------------------------------|
| mpBottomPointLonF             NhlTFloat               RCSG    |
|       MpBottomPointLonF               0.0                     |
|---------------------------------------------------------------|
| mpTopPointLatF                NhlTFloat               RCSG    |
|       MpTopPointLatF                  0.0                     |
|---------------------------------------------------------------|
| mpTopPointLonF                NhlTFloat               RCSG    |
|       MpTopPointLonF                  0.0                     |
|---------------------------------------------------------------|
| mpLeftWindowF                 NhlTFloat               RCSG    |
|       MpLeftWindowF                   0.0                     |
|---------------------------------------------------------------|
| mpRightWindowF                NhlTFloat               RCSG    |
|       MpRightWindowF                  0.0                     |
|---------------------------------------------------------------|
| mpBottomWindowF               NhlTFloat               RCSG    |
|       MpBottomWindowF                 0.0                     |
|---------------------------------------------------------------|
| mpTopWindowF                  NhlTFloat               RCSG    |
|       MpTopWindowF                    0.0                     |
|---------------------------------------------------------------|
| mpLambertParallel1F           NhlTFloat               RCSG    |
|       MpLambertParallel1F             .001                    |
|---------------------------------------------------------------|
| mpLambertParallel2F           NhlTFloat               RCSG    |
|       MpLambertParallel2F             89.999                  |
|---------------------------------------------------------------|
| mpLambertMeridianF            NhlTFloat               RCSG    |
|       MpLambertMeridianF              0.0                     |
|---------------------------------------------------------------|
| mpSatelliteDistF              NhlTFloat               RCSG    |
|       MpSatelliteDistF                1.0                     |
|---------------------------------------------------------------|
| mpSatelliteAngle1F            NhlTFloat               RCSG    |
|       MpSatelliteAngle1F              0.0                     |
|---------------------------------------------------------------|
| mpSatelliteAngle2F            NhlTFloat               RCSG    |
|       MpSatelliteAngle2F              0.0                     |
|---------------------------------------------------------------|
| mpEllipticalBoundary          NhlTBoolean             RCSG    |
|       MpEllipticalBoundary            False                   |
|---------------------------------------------------------------|
| mpGreatCircleLinesOn          NhlTBoolean             RCSG    |
|       MpGreatCircleLinesOn            False                   |
+---------------------------------------------------------------+

Composite resources

The MapTransformation class has no composite class objects.

Superclass resources

MapTransformation disables access to all the resources of its Transformation superclass.


Description

The MapTransformation object manages forward and reverse transformations between a two-dimensional rectangular data coordinate space representing latitude along the vertical axis and longitude along the horizontal axis and any of its 10 supported map projections. The data space extent may coincide with, encompass, or arbitrarily intersect the projected extent.

Creation and access to resources

You do not create objects of the MapTransformation class directly. You may, however, set its resources via objects that instantiate a MapTransformation child. Currently, the MapPlot object is the only HLU library object with a MapTransformation child; it allows access to all resources of the MapTransformation class, depending on it to provide transformations of data representing geophysical and political regions of the earth. Using the MapPlot as a base plot, you can provide map transformations for data associated with other plot object types. In addition, you can transform graphics primitives defined in lat-lon data space into any of the map projections.

Setting the projection and map boundaries

You define a map transformation by setting the mpProjection resource, and then in most cases, choosing a center of projection and a rotation angle using the resources, mpCenterLatF, mpCenterLonF, and mpCenterRotF. Then you choose a method for defining the visible extent of the global surface using the mpLimitMode resource. This resource has eight possible settings:

  • MaximalArea mode shows the maximum possible visible area depending on the projection. The MapTransformation ignores all other extent limiting resources when this mode is set.
  • LatLon mode defines a rectangular area bounded by minimum and maximum latitudes and longitudes, and shows as much of this area as possible given the projection and the current projection center. Set the latitude boundaries using mpMinLatF and mpMaxLatF and the longitude boundaries using mpMinLonF and mpMaxLonF. Two other resources apply only when using LatLon limit mode. These are the boolean resources mpRelativeCenterLon and mpRelativeCenterLat. When mpRelativeCenterLon is set True the value of the mpCenterLonF resource is interpreted as an offset in degrees from the longitude halfway between mpMinLonF and mpMaxLonF. Setting mpRelativeCenterLat True similarly modifies the interpretation of the mpCenterLatF resource.
  • Angles mode limits the area based on positive angular distance in degrees away from the projection center in the four directions parallel to a side of the viewport (not necessarily parallel to lines of latitude and longitude). Use the resources mpLeftAngleF, mpRightAngleF, mpBottomAngleF, and mpTopAngleF to set angular limits. You cannot use this mode for the LambertConformal or RotatedMercator projections. Also, if mpProjection has the value Satellite, the MapTransformation interprets the angles as deviations from the line of sight of the viewing satellite.
  • NPC mode limits the area based on Normalized Projection Coordinates", which map the maximal area of the projection into a rectangle bounded by 0.0 and 1.0 horizontally and vertically. Use the resources mpLeftNPCF, mpRightNPCF, mpBottomNPCF, and mpTopNPCF to set normalized projection coordinate limits. Note that the MapTransformation keeps the NPC resources updated to their current value no matter which map limit mode is currently in effect.
  • NDC mode limits the area based on the current location of the projected map in Normalized Device Coordinates. Use the resources mpLeftNDCF, mpRightNDCF, mpBottomNDCF, and mpTopNDCF to set normalized device coordinate limits. Note that each time these resources are applied using a SetValues call the mapping between NDC and the projected area changes. At the completion of a SetValues call, the MapTransformation internally sets the value of each of these resources to the new location of the original projected coordinate: that is, to one of the boundaries of the projected area.
  • Corners mode limits the area to a rectangle with corners defined by the values of the resources mpLeftCornerLatF, mpLeftCornerLonF, mpRightCornerLatF, and mpLeftCornerLonF.
  • Points mode limits the area to a rectangle containing the four points defined by the values of the resources mpLeftPointLatF, mpLeftPointLonF, mpRightPointLatF, mpRightPointLonF, mpBottomPointLatF, mpBottomPointLonF, mpTopPointLatF, and mpTopPointLonF
  • Window mode limits the area based on the intermediate "window" coordinate system used by the low level utilities. You set window coordinate limits using the resources mpLeftWindowF, mpRightWindowF, mpBottomWindowF, and mpTopWindowF. The MapTransformation keeps the window coordinate system resources updated to their current values no matter which map limit mode is currently in effect.

LambertConformal projection resources

When the conic projection LambertConformal is set, the MapTransformation ignores the projection center and rotation resources. Instead, use mpLambertParallel1F and mpLambertParallel2F to set the two latitudinal edges of the cone, and use mpLambertMeridianF to set its longitudinal center.

Satellite projection resources

If the projection is Satellite, the MapTransformation provides several additional resources for controlling the perspective effect. mpSatelliteDistF defines the distance of the viewing satellite from the center of the globe in multiples of the global radius. mpSatelliteAngle1F defines the angular deviation of the line of sight from a line between the satellite position and the center of the globe. mpSatelliteAngle2F defines the direction of the angular deviation of the line of sight as a rotation from the horizontal axis of the viewplane.

Elliptical boundary

For any of the projections, you can set a resource, mpEllipticalBoundary, that limits the perimeter of the viewable area to an ellipse inscribed within the rectangular viewport.

Graphic primitive transformations

MapTransformation supports transformation into any of the map projections of graphic primitives using the data space primitive drawing routines NhlDataPolygon, NhlDataPolyline, and NhlDataPolymarker. Depending on the setting of the boolean resource mpGreatCircleLinesOn, lines or edges spanning the space between the user-supplied points of a polyline or polygon may be transformed in two different ways. One treats the lat-lon grid as a cartesian system; the other calculates the great circle route (the shortest distance on the surface of the globe) between each set of points.

Support functions

The MapTransformation object does not define any support functions, but inherits all the support functions available to its superclass.

Status

2. Range checking is inadequate for a number of the MapTransformation resources including mpLambertMeridianF, mpLambertParallel2F, mpLambertParallel1F, mpCenterLatF, and mpCenterLonF.

3. When mpCenterRotF has a non-zero value and mpLimitMode is set to NhlANGLES, it is possible that errors may occur even when the angle values are within the documented limits. This occurs in certain situations that have so far proved to be difficult to pin down. More work is required.


See also