The MapPlot class draws outlined and/or filled maps of arbitrary regions of the globe and may be used to map overlay plots into a number of standard projections.
Header file: ncarg/hlu/MapPlot.h Class name: mapPlotClass Class pointer: NhlmapPlotClass Fortran class function: NHLFMAPPLOTCLASS Superclass: Transform Composite classes: MapTransObj,PlotManager
Type name: NhlTMapBoundarySets
Definition:
typedef enum _NhlMapBoundarySets {
NhlNOBOUNDARIES = 0, /* "NoBoundaries" */
NhlGEOPHYSICAL = 1, /* "Geophysical" */
NhlNATIONAL = 2, /* "National" */
NhlUSSTATES = 3, /* "USStates" */
NhlGEOPHYSICALANDUSSTATES = 4, /* "GeophysicalAndUSStates" */
NhlALLBOUNDARIES = 5 /* "AllBoundaries" */
} NhlMapBoundarySets;
Type name: NhlTSpecifiedFillPriority
Definition:
typedef enum _NhlSpecifiedFillPriority {
NhlGEOPHYSICALPRIORITY = 0, /* "GeophysicalPriority" */
NhlPOLITICALPRIORITY = 1 /* "PoliticalPriority" */
} NhlSpecifiedFillPriority;
Type name: NhlTMapGridMaskMode
Definition:
typedef enum _NhlMapGridMaskMode {
NhlMASKNONE = 0, /* "MaskNone" */
NhlMASKOCEAN = 1, /* "MaskOcean" */
NhlMASKNOTOCEAN = 2, /* "MaskNotOcean" */
NhlMASKLAND = 3, /* "MaskLand" */
NhlMASKNOTLAND = 4, /* "MaskNotLand" */
NhlMASKFILLAREA = 5, /* "MaskFillArea" */
NhlMASKMASKAREA = 6 /* "MaskMaskArea" */
} NhlMapGridMaskMode;
Type name: NhlTMapShapeMode
Definition:
typedef enum _NhlMapShapeMode {
NhlFREEASPECT = 0, /* "FreeAspect" */
NhlFIXEDASPECTFITBB = 1, /* "FixedAspectFitBB" */
NhlFIXEDASPECTNOFITBB = 2 /* "FixedAspectNoFitBB" */
} NhlMapShapeMode;
+---------------------------------------------------------------+ | MapPlot Resource Set | |---------------------------------------------------------------| | NAME TYPE ACCESS | | CLASS DEFAULT | |===============================================================| | mpDataBaseVersion NhlTString G | | MpDataBaseVersion "NCARG_4.0" | |---------------------------------------------------------------| | mpShapeMode NhlTMapShapeMode RCSG | | MpShapeMode "FixedAspectFitBB" | |---------------------------------------------------------------| | mpAreaNames NhlTStringGenArray RCSG | | MpAreaNames <array> | |---------------------------------------------------------------| | mpAreaTypes NhlTIntegerGenArray G | | MpAreaTypes <array> | |---------------------------------------------------------------| | mpFixedAreaGroups NhlTIntegerGenArray G | | MpFixedAreaGroups <array> | |---------------------------------------------------------------| | mpDynamicAreaGroups NhlTIntegerGenArray RCSG | | MpDynamicAreaGroups <array> | |---------------------------------------------------------------| | mpAreaGroupCount NhlTInteger RCSG | | MpAreaGroupCount 10 | |---------------------------------------------------------------| | mpOutlineOn NhlTBoolean RCSG | | MpOutlineOn True | |---------------------------------------------------------------| | mpOutlineDrawOrder NhlTDrawOrder RCSG | | MpOutlineDrawOrder "PostDraw" | |---------------------------------------------------------------| | mpOutlineBoundarySets NhlTMapBoundarySets RCSG | | MpOutlineBoundarySets "Geophysical" | |---------------------------------------------------------------| | mpOutlineSpecifiers NhlTStringGenArray RCSG | | MpOutlineSpecifiers <array> | |---------------------------------------------------------------| | mpAreaMaskingOn NhlTBoolean RCSG | | MpAreaMaskingOn False | |---------------------------------------------------------------| | mpMaskAreaSpecifiers NhlTStringGenArray RCSG | | MpMaskAreaSpecifiers <array> | |---------------------------------------------------------------| | mpFillOn NhlTBoolean RCSG | | MpFillOn False | |---------------------------------------------------------------| | mpFillDrawOrder NhlTDrawOrder RCSG | | MpFillDrawOrder "Draw" | |---------------------------------------------------------------| | mpFillBoundarySets NhlTMapBoundarySets RCSG | | MpFillBoundarySets "Geophysical" | |---------------------------------------------------------------| | mpFillPatternBackground NhlTColorIndex RCSG | | MpFillPatternBackground "Background" | |---------------------------------------------------------------| | mpMonoFillColor NhlTBoolean RCSG | | MpMonoFillColor False | |---------------------------------------------------------------| | mpFillColor NhlTColorIndex RCSG | | MpFillColor "Foreground" | |---------------------------------------------------------------| | mpFillColors NhlTColorIndexGenArray RCSG | | MpFillColors <array> | |---------------------------------------------------------------| | mpMonoFillPattern NhlTBoolean RCSG | | MpMonoFillPattern True | |---------------------------------------------------------------| | mpFillPattern NhlTFillIndex RCSG | | MpFillPattern "SolidFill" | |---------------------------------------------------------------| | mpFillPatterns NhlTFillIndexGenArray RCSG | | MpFillPatterns <array> | |---------------------------------------------------------------| | mpMonoFillScale NhlTBoolean RCSG | | MpMonoFillScale True | |---------------------------------------------------------------| | mpFillScaleF NhlTFloat RCSG | | MpFillScaleF 1.0 | |---------------------------------------------------------------| | mpFillScales NhlTFloatGenArray RCSG | | MpFillScales <array> | |---------------------------------------------------------------| | mpFillAreaSpecifiers NhlTStringGenArray RCSG | | MpFillAreaSpecifiers <array> | |---------------------------------------------------------------| | mpSpecifiedFillDirectIndexing NhlTBoolean RCSG | | MpSpecifiedFillDirectIndexing False | |---------------------------------------------------------------| | mpSpecifiedFillPriority NhlTSpecifiedFillPriority RCSG | | MpSpecifiedFillPriority "GeophysicalPriority" | |---------------------------------------------------------------| | mpSpecifiedFillColors NhlTColorIndexGenArray RCSG | | MpSpecifiedFillColors <dynamic array> | |---------------------------------------------------------------| | mpSpecifiedFillPatterns NhlTFillIndexGenArray RCSG | | MpSpecifiedFillPatterns <dynamic array> | |---------------------------------------------------------------| | mpSpecifiedFillScales NhlTFloatGenArray RCSG | | MpSpecifiedFillScales <dynamic array> | |---------------------------------------------------------------| | mpDefaultFillColor NhlTColorIndex RCSG | | MpDefaultFillColor 106 | |---------------------------------------------------------------| | mpDefaultFillPattern NhlTFillIndex RCSG | | MpDefaultFillPattern "SolidFill" | |---------------------------------------------------------------| | mpDefaultFillScaleF NhlTFloat RCSG | | MpDefaultFillScaleF 1.0 | |---------------------------------------------------------------| | mpOceanFillColor NhlTColorIndex RCSG | | MpOceanFillColor 104 | |---------------------------------------------------------------| | mpOceanFillPattern NhlTFillIndex RCSG | | MpOceanFillPattern "SolidFill" | |---------------------------------------------------------------| | mpOceanFillScaleF NhlTFloat RCSG | | MpOceanFillScaleF 1.0 | |---------------------------------------------------------------| | mpLandFillColor NhlTColorIndex RCSG | | MpLandFillColor 57 | |---------------------------------------------------------------| | mpLandFillPattern NhlTFillIndex RCSG | | MpLandFillPattern "SolidFill" | |---------------------------------------------------------------| | mpLandFillScaleF NhlTFloat RCSG | | MpLandFillScaleF 1.0 | |---------------------------------------------------------------| | mpInlandWaterFillColor NhlTColorIndex RCSG | | MpInlandWaterFillColor 104 | |---------------------------------------------------------------| | mpInlandWaterFillPattern NhlTFillIndex RCSG | | MpInlandWaterFillPattern "SolidFill" | |---------------------------------------------------------------| | mpInlandWaterFillScaleF NhlTFloat RCSG | | MpInlandWaterFillScaleF 1.0 | |---------------------------------------------------------------| | mpGeophysicalLineColor NhlTColorIndex RCSG | | MpGeophysicalLineColor "Foreground | |---------------------------------------------------------------| | mpGeophysicalLineDashPattern NhlTDashIndex RCSG | | MpGeophysicalLineDashPattern "SolidLine" | |---------------------------------------------------------------| | mpGeophysicalLineDashSegLenF NhlTFloat RCSG | | MpGeophysicalLineDashSegLenF <dynamic> | |---------------------------------------------------------------| | mpGeophysicalLineThicknessF NhlTFloat RCSG | | MpGeophysicalLineThicknessF 1.0 | |---------------------------------------------------------------| | mpUSStateLineColor NhlTColorIndex RCSG | | MpUSStateLineColor "Foreground" | |---------------------------------------------------------------| | mpUSStateLineDashPattern NhlTDashIndex RCSG | | MpUSStateLineDashPattern "SolidLine" | |---------------------------------------------------------------| | mpUSStateLineDashSegLenF NhlTFloat RCSG | | MpUSStateLineDashSegLenF <dynamic> | |---------------------------------------------------------------| | mpUSStateLineThicknessF NhlTFloat RCSG | | MpUSStateLineThicknessF 1.0 | |---------------------------------------------------------------| | mpNationalLineColor NhlTColorIndex RCSG | | MpNationalLineColor "Foreground" | |---------------------------------------------------------------| | mpNationalLineDashPattern NhlTDashIndex RCSG | | MpNationalLineDashPattern "SolidLine" | |---------------------------------------------------------------| | mpNationalLineDashSegLenF NhlTFloat RCSG | | MpNationalLineDashSegLenF <dynamic> | |---------------------------------------------------------------| | mpNationalLineThicknessF NhlTFloat RCSG | | MpNationalLineThicknessF 1.0 | |---------------------------------------------------------------| | mpGridAndLimbOn NhlTBoolean RCSG | | MpGridAndLimbOn True | |---------------------------------------------------------------| | mpGridAndLimbDrawOrder NhlTDrawOrder RCSG | | MpGridAndLimbDrawOrder "PostDraw" | |---------------------------------------------------------------| | mpGridSpacingF NhlTFloat RCSG | | MpGridSpacingF 0.1 | |---------------------------------------------------------------| | mpGridMaskMode NhlTMapGridMaskMode RCSG | | MpGridMaskMode "MaskNone" | |---------------------------------------------------------------| | mpGridLineColor NhlTColorIndex RCSG | | MpGridLineColor "Foreground" | |---------------------------------------------------------------| | mpGridLineDashPattern NhlTDashIndex RCSG | | MpGridLineDashPattern "SolidLine" | |---------------------------------------------------------------| | mpGridLineDashSegLenF NhlTFloat RCSG | | MpGridLineDashSegLenF <dynamic> | |---------------------------------------------------------------| | mpGridLineThicknessF NhlTFloat RCSG | | MpGridLineThicknessF 1.0 | |---------------------------------------------------------------| | mpLimbLineColor NhlTColorIndex RCSG | | MpLimbLineColor "Foreground" | |---------------------------------------------------------------| | mpLimbLineDashPattern NhlTDashIndex RCSG | | MpLimbLineDashPattern "SolidLine" | |---------------------------------------------------------------| | mpLimbLineDashSegLenF NhlTFloat RCSG | | MpLimbLineDashSegLenF <dynamic> | |---------------------------------------------------------------| | mpLimbLineThicknessF NhlTFloat RCSG | | MpLimbLineThicknessF 1.0 | |---------------------------------------------------------------| | mpPerimOn NhlTBoolean RCSG | | MpPerimOn True | |---------------------------------------------------------------| | mpPerimDrawOrder NhlTDrawOrder RCSG | | MpPerimDrawOrder "Draw" | |---------------------------------------------------------------| | mpPerimLineColor NhlTColorIndex RCSG | | MpPerimLineColor "Foreground" | |---------------------------------------------------------------| | mpPerimLineDashPattern NhlTDashIndex RCSG | | MpPerimLineDashPattern "SolidLine" | |---------------------------------------------------------------| | mpPerimLineDashSegLenF NhlTFloat RCSG | | MpPerimLineDashSegLenF <dynamic> | |---------------------------------------------------------------| | mpPerimLineThicknessF NhlTFloat RCSG | | MpPerimLineThicknessF 1.0 | |---------------------------------------------------------------| | mpLabelsOn NhlTBoolean RCSG | | MpLabelsOn True | |---------------------------------------------------------------| | mpLabelDrawOrder NhlTDrawOrder RCSG | | MpLabelDrawOrder "PostDraw" | |---------------------------------------------------------------| | mpLabelFontHeightF NhlTFloat RCSG | | MpLabelFontHeightF <dynamic> | |---------------------------------------------------------------| | mpLabelFontColor NhlTColorIndex RCSG | | MpLabelFontColor True | +---------------------------------------------------------------+
NoCreate will result in a warning, since tick marks have not yet
been implemented for map projections. Except for
TickMark resources, you can also access resources for
the PlotManager composite annotation objects. However, the
PlotManager object modifies the access and behavior of
some of the resources belonging to these objects, as follows:
You can use MapPlot as a base plot on which one or more plot objects, such as a ContourPlot object, are overlaid, thereby transforming its elements into the current map projection. You can also control the order of drawing of MapPlot elements relative to each other and to the elements of any overlaid plot objects. Using these facilities, you can limit overlay plots to the geographical boundaries for which their data have meaning. For instance, you can confine a contour plot of ocean temperatures to areas representing only the ocean. Note that unlike most plot objects, you cannot add the MapPlot as an overlay of another base plot. It can, however, be used as an annotation plot
MapPlot supports grids representing latitude and longitude. You can mask the grids independently of area masking. Also supported are labels for some key features of the world map, including the poles, the equator, the Grenwich Meridian and the International DateLine. Finally, you can draw a perimeter, either rectangular or elliptical, around the projected map area.
The map projections provided by the MapTransObj must retain their intrinsic shape in order to be considered "correct" projections. However, in some situations you may not care whether this shape is preserved. The MapPlot object provides a resource, mpShapeMode, that allows you to decide whether or not to preserve the shape intrinsic to the projection. Moreover, if shape is to be preserved, you can decide whether you want to shrink the MapPlot viewport to fit around the projected area, which is centered in the originally specified viewport; or whether you want the viewport to remain as originally specified, even if the projected area cannot completely fill the space.
The current version of the database is several years out of date. Since it can be expected to change from time to time, both to accommodate the current political realities and also to incorporate higher resolution data, MapPlot provides a means of maintaining compatibility, based on a string resource, mpDataBaseVersion, that allows the user to specify the version of the database required.
The areas in the MapPlot database are actually a concatentation of three distinct boundary sets. The first set contains geophysical boundaries; the second is a union of the geophysical set with interior national boundaries; the third contains (at a higher resolution) the boundaries of the U.S. States. You can specify that MapPlot draw any combination of the three sets (including none of them) using resources of type NhlTMapBoundarySets. For outlines and fill these resources are mpOutlineBoundarySets and mpFillBoundarySets.
The string array resources allow individual specification of areas and
area catagories. To the basic boundary specification (which might well
be NoBoundaries), you add other areas you want to outline
or fill and subtract areas you want to mask. You do this using string
array specifier resources, of which there are three: mpOutlineSpecifiers,
mpFillAreaSpecifiers,
and mpMaskAreaSpecifiers.
The specifier strings you use for these resources may be any of the
MapPlot pre-defined string constants,
explicit names from the MapPlot database, or matching
substrings. All specifier strings are case-insensitive.
Normally MapPlot determines the fill attributes for each area based on its group memberships within the fixed and dynamic area group arrays. However, for areas specified explicitly in the mpFillAreaSpecifiers array, you can override the usual fill attribute choices and pick the fill attributes explicitly. This will be explained further below.
MapPlot maintains two arrays of these area groups, accessible through the integer array resources mpFixedAreaGroups and mpDynamicAreaGroups. Both arrays are keyed to the mpAreaNames array, and within each array, the value of each element represents the area group assigned to an area. Most areas are assigned to different groups in the two area group areas, but in a number of cases, (all areas representing water bodies, for instance), MapPlot assigns an area to the same group in both arrays.
The mpFixedAreaGroups array is sometimes known as the geophysical group array, because it provides the indexes that allow you to distinguish land areas from water areas. As its name implies, you cannot modify the mpFixedAreaGroups resource. Within this array, based on area type, MapPlot assigns each area in the database either to the Ocean group, to the Land group, or to the InlandWater group (i.e. to groups 1, 2 or 3).
The mpDynamicAreaGroups array is sometimes called the political group array, since the default assignment of dynamic area group numbers guarantees that adjoining politically distinct areas belong to different area groups. However, you are free to assign area groups within the dynamic area group array in any way you please. You may use all the available area groups from 1 through the current value of mpAreaGroupCount.
The elements of the array resources used to set fill color, fill pattern, and fill scale are indexed through the area group numbers. In other words, the first element of each of these arrays defines a fill attribute for group 0, the second an attribute for group 1, and so forth. For convenience, you can also access the fill attribute resources of groups 0 through 4 using a set of resources with names corresponding to the area group name. These resources have names with the following prefixes: mpDefault..., mpOcean..., mpLand..., and mpInlandWater.... You can think of these resources as aliases for the corresponding array resource element. When an array resource and a named alias resource accessing one of its elements are set in the same SetValues call the named alias resource overrides.
Each of the three basic fill attributes supported by MapPlot, fill color, fill pattern, and fill pattern scale factor, provides both a scalar resource that you can use if you want to set all area groups to the same value, and an array resource that you use if you want to set each area group individually. The scalar fill attribute resources are mpFillColor, mpFillPattern, and mpFillScaleF. The array resources names, formed by pluralizing the scalar resource names (after removing the 'F' suffix, if present) are mpFillColors, mpFillPatterns, and mpFillScales. The boolean resources, mpMonoFillColor, mpMonoFillPattern, and mpMonoFillScale, specify use of the scalar resources when set to True, and the array resources when set False. Note that if a Mono resource is set True, the named alias resources applying to that attribute are ignored, since they are, after all, only aliases for particular elements of the array resource.
For each attribute that has the Mono resource set False, MapPlot finds a group number for each area either from the fixed area group array or the dynamic area group array and uses that number as an index into the appropriate array resource. How does MapPlot decide when to index based on the fixed area group number and when to index based on the dynamic area group number? For fill areas specified using only the mpFillBoundarySets resource, MapPlot chooses between the area group arrays as follows:
NoBoundaries
Geophysical
National
USStates
GeophysicalAndUSStates
AllBoundaries
GeophysicalPriority
MapPlot picks an index from the mpFixedAreaGroups
array to determine fill attributes. Otherwise, it picks an index from
the mpDynamicAreaGroups
array. You may reverse the fill priority for individual areas within
the mpFillAreaSpecifiers
array by prepending the exclamation mark character ('!') to the area's
specifier string. For instance, if mpSpecifiedFillPriority
is set to PoliticalPriority but you want Australia to be
displayed using its geophysical color, you would set the appropriate
mpFillAreaSpecifiers
element to the value "!australia".
SolidFill, as determined by the value of the mpFillPattern resource.
If you want to explcitly specify the attributes of only certain of
the areas specified in the mpFillAreaSpecifiers,
while others base their fill attributes on area group memberships as
discussed in the previous section, there are special values you can
assign to indicate an "unset" value. For mpSpecifiedFillColors
use the special color index NoColor (-1); for mpSpecifiedFillPatterns
the special fill pattern index NoPattern (-1); and
for mpSpecifiedFillScales
use the otherwise invalid value, 0.0.
By default, the specified fill attribute arrays directly set the attribute. In other words, the value of an element of mpSpecifiedFillColors represents an HLU color index, the value of an element of mpSpecifiedFillPatterns represents an HLU pattern index, and the value of an element of mpSpecifiedFillScales is a floating point number representing a fill scaling factor. However, if you set the resource mpSpecifiedFillDirectIndexing False, the values of these array elements are converted to integers and treated as group numbers. This facility allows you to use the specified fill attribute arrays to specify the fill attributes of an area indirectly by temporarily changing its group membership.
Noboundaries, it is possible that
areas within the map projection may remain unspecified either as
filled or masked. MapPlot fills these areas
using the default fill attributes.
MaskMaskArea.
You can set the line attributes for the grid and limb lines independently. Grid attributes are controlled using the resources mpGridLineColor, mpGridLineDashPattern, mpGridLineDashSegLenF, and mpGridLineThicknessF. You set limb line attributes using mpLimbLineColor, mpLimbLineDashPattern, mpLimbLineDashSegLenF, and mpLimbLineThicknessF.
5: Eventually you should be able to add groups of points that define your own areas, give them arbitrary names and add these areas to the area names array.
6: The resource mpAreaTypes needs to be made into an enumerated resource.
NG4 Home, Index, Examples, Glossary, Feedback, Ref Contents, Ref WhereAmI?