NCL Home >
Documentation >
HLUs >
Classes
When the conic projection
If the projection is
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:
- MapPlot object
+---------------------------------------------------------------+ | 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:
MaximalAreamode shows the maximum possible visible area depending on the projection. The MapTransformation ignores all other extent limiting resources when this mode is set.LatLonmode 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 usingLatLonlimit 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.Anglesmode 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 theLambertConformalorRotatedMercatorprojections. Also, if mpProjection has the valueSatellite, the MapTransformation interprets the angles as deviations from the line of sight of the viewing satellite.NPCmode 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.NDCmode 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.Cornersmode limits the area to a rectangle with corners defined by the values of the resources mpLeftCornerLatF, mpLeftCornerLonF, mpRightCornerLatF, and mpLeftCornerLonF.Pointsmode 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 mpTopPointLonFWindowmode 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
- MapPlot object
- PlotManager object
- Transformation object
- Obj object