NCL Home > Documentation > HLUs > Classes

MapPlot class

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.

Synopsis

Header file:		ncarg/hlu/MapPlot.h
Class name:		mapPlotClass
Class pointer:		NhlmapPlotClass
Fortran class function:	NHLFMAPPLOTCLASS
Superclass:		Transform
Composite classes:	MapTransformation,PlotManager

Class-defined types

Type name:		NhlTMapDataBaseVersion
Definition:
typedef enum _NhlMapDataBaseVersion {
	NhlNCARG4_0      = 0, /* "Ncarg4_0", "LowRes" */
        NhlNCARG4_1      = 1, /* "Ncarg4_1", "MediumRes" */
	NhlRANGS_GSHHS   = 2  /* "RANGS_GSHHS", "RANGS", "HighRes" */
} NhlMapDataBaseVersion;

Type name:		NhlTMapDataResolution
Definition:
typedef enum _NhlMapDataResolution {
        NhlUNSPECIFIEDRESOLUTION = -1, /* "Unspecified", "UnspecifiedResolution" */
        NhlFINESTRESOLUTION	 =  0, /* "Finest", "FinestResolution" */
        NhlFINERESOLUTION	 =  1, /* "Fine", "FineResolution" */
        NhlMEDIUMRESOLUTION	 =  2, /* "Medium", "MediumResolution" */
        NhlCOARSERESOLUTION	 =  3, /* "Coarse", "CoarseResolution" */
        NhlCOARSESTRESOLUTION	 =  4  /* "Coarsest", "CoarsestResolution" */
} NhlMapDataResolution;

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;

Resources

Local resources

+---------------------------------------------------------------+
|			MapPlot Resource Set			|
|---------------------------------------------------------------|
| NAME				TYPE			ACCESS	|
|	CLASS				DEFAULT			|
|===============================================================|
| mpDataBaseVersion             NhlTMapDataBaseVersion  RCSG    |
|       MpDataBaseVersion               "Ncarg4_0"              |
|---------------------------------------------------------------|
| mpDataSetName                 NhlTString              RCSG    |
|       MpDataSetName	                "Earth..2"              |
|---------------------------------------------------------------|
| mpDataResolution              NhlTMapDataResolution   RCSG    |
|       MpDataResolution               "Unspecified"            |
|---------------------------------------------------------------|
| mpShapeMode                   NhlTMapShapeMode        RCSG    |
|       MpShapeMode                     "FixedAspectFitBB"      |
|---------------------------------------------------------------|
| mpAreaNames                   NhlTStringGenArray      RCSG    |
|       MpAreaNames              <array> (1) <array> (2)        |
|                               (Ncarg4_0)  (Ncarg4_1)          |
|---------------------------------------------------------------|
| mpAreaTypes                   NhlTIntegerGenArray     G       |
|       MpAreaTypes              <array> (1) <array> (2)        |
|                               (Ncarg4_0)  (Ncarg4_1)          |
|---------------------------------------------------------------|
| mpFixedAreaGroups             NhlTIntegerGenArray     G       |
|       MpFixedAreaGroups        <array> (1) <array> (2)        |
|                               (Ncarg4_0)  (Ncarg4_1)          |
|---------------------------------------------------------------|
| mpDynamicAreaGroups           NhlTIntegerGenArray     RCSG    |
|       MpDynamicAreaGroups      <array> (1) <array> (2)        |
|                               (Ncarg4_0)  (Ncarg4_1)          |
|---------------------------------------------------------------|
| mpAreaGroupCount              NhlTInteger             RCSG    |
|       MpAreaGroupCount                10                      |
|---------------------------------------------------------------|
| mpOutlineOn                   NhlTBoolean             RCSG    |
|       MpOutlineOn                     True                    |
|---------------------------------------------------------------|
| mpOutlineDrawOrder            NhlTDrawOrder           RCSG    |
|       MpOutlineDrawOrder              "PostDraw"              |
|---------------------------------------------------------------|
| mpOutlineBoundarySets         NhlTMapBoundarySets     RCSG    |
|       MpOutlineBoundarySets           "Geophysical"           |
|---------------------------------------------------------------|
| mpOutlineSpecifiers           NhlTStringGenArray      RCSG    |
|       MpOutlineSpecifiers             NULL                    |
|---------------------------------------------------------------|
| mpOutlineMaskingOn            NhlTBoolean             RCSG    |
|       MpOutlineMaskingOn              False                   |
|---------------------------------------------------------------|
| mpMaskOutlineSpecifiers       NhlTStringGenArray      RCSG    |
|       MpMaskOutlineSpecifiers         NULL                    |
|---------------------------------------------------------------|
| mpAreaMaskingOn               NhlTBoolean             RCSG    |
|       MpAreaMaskingOn                 False                   |
|---------------------------------------------------------------|
| mpMaskAreaSpecifiers          NhlTStringGenArray      RCSG    |
|       MpMaskAreaSpecifiers            NULL                    |
|---------------------------------------------------------------|
| mpFillOn                      NhlTBoolean             RCSG    |
|       MpFillOn                        False                   |
|---------------------------------------------------------------|
| mpFillDrawOrder               NhlTDrawOrder           RCSG    |
|       MpFillDrawOrder                 "Draw"                  |
|---------------------------------------------------------------|
| mpFillBoundarySets            NhlTMapBoundarySets     RCSG    |
|       MpFillBoundarySets              "Geophysical"           |
|---------------------------------------------------------------|
| mpFillPatternBackground       NhlTColorIndex          RCSG    |
|       FillBackgroundColor             "Background"            |
|---------------------------------------------------------------|
| mpMonoFillColor               NhlTBoolean             RCSG    |
|       MpMonoFillColor                 False                   |
|---------------------------------------------------------------|
| mpFillColor                   NhlTColorIndex          RCSG    |
|       FillColor                       "Foreground"            |
|---------------------------------------------------------------|
| mpFillColors                  NhlTColorIndexGenArray  RCSG    |
|       MpFillColors                    <array>                 |
|---------------------------------------------------------------|
| mpMonoFillPattern             NhlTBoolean             RCSG    |
|       MpMonoFillPattern               True                    |
|---------------------------------------------------------------|
| mpFillPattern                 NhlTFillIndex           RCSG    |
|       FillPattern                     "SolidFill"             |
|---------------------------------------------------------------|
| mpFillPatterns                NhlTFillIndexGenArray   RCSG    |
|       MpFillPatterns                  <array>                 |
|---------------------------------------------------------------|
| mpFillDotSizeF                NhlTFloat               RCSG    |
|       DotSizeF                        0.0                     |
|---------------------------------------------------------------|
| mpMonoFillScale               NhlTBoolean             RCSG    |
|       MpMonoFillScale                 True                    |
|---------------------------------------------------------------|
| mpFillScaleF                  NhlTFloat               RCSG    |
|       FillScaleF                      1.0                     |
|---------------------------------------------------------------|
| mpFillScales                  NhlTFloatGenArray       RCSG    |
|       MpFillScales                    <array>                 |
|---------------------------------------------------------------|
| mpFillAreaSpecifiers          NhlTStringGenArray      RCSG    |
|       MpFillAreaSpecifiers            NULL                    |
|---------------------------------------------------------------|
| 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    |
|       FillColor		        16                      |
|---------------------------------------------------------------|
| mpDefaultFillPattern          NhlTFillIndex           RCSG    |
|       FillPattern                     "SolidFill"             |
|---------------------------------------------------------------|
| mpDefaultFillScaleF           NhlTFloat               RCSG    |
|       FillScaleF                      1.0                     |
|---------------------------------------------------------------|
| mpOceanFillColor              NhlTColorIndex          RCSG    |
|       FillColor                       10                      |
|---------------------------------------------------------------|
| mpOceanFillPattern            NhlTFillIndex           RCSG    |
|       FillPattern                     "SolidFill"             |
|---------------------------------------------------------------|
| mpOceanFillScaleF             NhlTFloat               RCSG    |
|       FillScaleF                      1.0                     |
|---------------------------------------------------------------|
| mpLandFillColor               NhlTColorIndex          RCSG    |
|       FillColor                       8                       |
|---------------------------------------------------------------|
| mpLandFillPattern             NhlTFillIndex           RCSG    |
|       FillPattern                     "SolidFill"             |
|---------------------------------------------------------------|
| mpLandFillScaleF              NhlTFloat               RCSG    |
|       FillScaleF                      1.0                     |
|---------------------------------------------------------------|
| mpInlandWaterFillColor        NhlTColorIndex          RCSG    |
|       FillColor                       10                      |
|---------------------------------------------------------------|
| mpInlandWaterFillPattern      NhlTFillIndex           RCSG    |
|       FillPattern                     "SolidFill"             |
|---------------------------------------------------------------|
| mpInlandWaterFillScaleF       NhlTFloat               RCSG    |
|       FillScaleF                      1.0                     |
|---------------------------------------------------------------|
| mpGeophysicalLineColor        NhlTColorIndex          RCSG    |
|       LineColor                       "Foreground             |
|---------------------------------------------------------------|
| mpGeophysicalLineDashPattern  NhlTDashIndex           RCSG    |
|       LineDashPattern                 "SolidLine"             |
|---------------------------------------------------------------|
| mpGeophysicalLineDashSegLenF  NhlTFloat               RCSG    |
|       LineDashSegLenF                 <dynamic>               |
|---------------------------------------------------------------|
| mpGeophysicalLineThicknessF   NhlTFloat               RCSG    |
|       LineThicknessF                  1.0                     |
|---------------------------------------------------------------|
| mpUSStateLineColor            NhlTColorIndex          RCSG    |
|       LineColor                       "Foreground"            |
|---------------------------------------------------------------|
| mpUSStateLineDashPattern      NhlTDashIndex           RCSG    |
|       LineDashPattern                 "SolidLine"             |
|---------------------------------------------------------------|
| mpUSStateLineDashSegLenF      NhlTFloat               RCSG    |
|       LineDashSegLenF                 <dynamic>               |
|---------------------------------------------------------------|
| mpUSStateLineThicknessF       NhlTFloat               RCSG    |
|       LineThicknessF                  1.0                     |
|---------------------------------------------------------------|
| mpNationalLineColor           NhlTColorIndex          RCSG    |
|       LineColor                       "Foreground"            |
|---------------------------------------------------------------|
| mpNationalLineDashPattern     NhlTDashIndex           RCSG    |
|       LineDashPattern                 "SolidLine"             |
|---------------------------------------------------------------|
| mpNationalLineDashSegLenF     NhlTFloat               RCSG    |
|       LineDashSegLenF                 <dynamic>               |
|---------------------------------------------------------------|
| mpNationalLineThicknessF      NhlTFloat               RCSG    |
|       LineThicknessF                  1.0                     |
|---------------------------------------------------------------|
| mpGridAndLimbOn               NhlTBoolean             RCSG    |
|       MpGridAndLimbOn                 True                    |
|---------------------------------------------------------------|
| mpGridAndLimbDrawOrder        NhlTDrawOrder           RCSG    |
|       MpGridAndLimbDrawOrder          "PostDraw"              |
|---------------------------------------------------------------|
| mpGridMaskMode                NhlTMapGridMaskMode     RCSG    |
|       MpGridMaskMode                  "MaskNone"              |
|---------------------------------------------------------------|
| mpGridSpacingF                NhlTFloat               RCSG    |
|       MpGridSpacingF                  15.0                    |
|---------------------------------------------------------------|
| mpGridLatSpacingF             NhlTFloat               RCSG    |
|       MpGridLatSpacingF               15.0                    |
|---------------------------------------------------------------|
| mpGridLonSpacingF             NhlTFloat               RCSG    |
|       MpGridLonSpacingF               15.0                    |
|---------------------------------------------------------------|
| mpGridMaxLatF                 NhlTFloat               RCSG    |
|       MpGridMaxLatF                   15.0                    |
|---------------------------------------------------------------|
| mpGridPolarLonSpacingF        NhlTFloat               RCSG    |
|       MpGridPolarLonSpacingF          15.0                    |
|---------------------------------------------------------------|
| mpGridLineColor               NhlTColorIndex          RCSG    |
|       LineColor                       "Foreground"            |
|---------------------------------------------------------------|
| mpGridLineDashPattern         NhlTDashIndex           RCSG    |
|       LineDashPattern                 "SolidLine"             |
|---------------------------------------------------------------|
| mpGridLineDashSegLenF         NhlTFloat               RCSG    |
|       DashSegLenF                     <dynamic>               |
|---------------------------------------------------------------|
| mpGridLineThicknessF          NhlTFloat               RCSG    |
|       LineThicknessF                  1.0                     |
|---------------------------------------------------------------|
| mpLimbLineColor               NhlTColorIndex          RCSG    |
|       LineColor                       "Foreground"            |
|---------------------------------------------------------------|
| mpLimbLineDashPattern         NhlTDashIndex           RCSG    |
|       LineDashPattern                 "SolidLine"             |
|---------------------------------------------------------------|
| mpLimbLineDashSegLenF         NhlTFloat               RCSG    |
|       LineDashSegLenF                 <dynamic>               |
|---------------------------------------------------------------|
| mpLimbLineThicknessF          NhlTFloat               RCSG    |
|       LineThicknessF                  1.0                     |
|---------------------------------------------------------------|
| mpPerimOn                     NhlTBoolean             RCSG    |
|       EdgesOn                         False                   |
|---------------------------------------------------------------|
| mpPerimDrawOrder              NhlTDrawOrder           RCSG    |
|       MpPerimDrawOrder                "Draw"                  |
|---------------------------------------------------------------|
| mpPerimLineColor              NhlTColorIndex          RCSG    |
|       LineColor                       "Foreground"            |
|---------------------------------------------------------------|
| mpPerimLineDashPattern        NhlTDashIndex           RCSG    |
|       LineDashPattern                 "SolidLine"             |
|---------------------------------------------------------------|
| mpPerimLineDashSegLenF        NhlTFloat               RCSG    |
|       LineDashSegLenF                 <dynamic>               |
|---------------------------------------------------------------|
| mpPerimLineThicknessF         NhlTFloat               RCSG    |
|       LineThicknessF                  1.0                     |
|---------------------------------------------------------------|
| mpLabelsOn                    NhlTBoolean             RCSG    |
|       PlotLabelsOn                    False                   |
|---------------------------------------------------------------|
| mpLabelDrawOrder              NhlTDrawOrder           RCSG    |
|       MpLabelDrawOrder                "PostDraw"              |
|---------------------------------------------------------------|
| mpLabelFontHeightF            NhlTFloat               RCSG    |
|       FontHeightF                     <dynamic>               |
|---------------------------------------------------------------|
| mpLabelFontColor              NhlTColorIndex          RCSG    |
|       FontColor                       True                    |
+---------------------------------------------------------------+

Composite resources

MapTransformation resources

You can access all MapTransformation resources. The MapTransformation resources define the projection and the portion of the world map visible within the NDC viewport.

If tfPlotManagerOn is True when a MapPlot object is created, you can access all PlotManager resources. However, note that MapPlot intercepts certain PlotManager resources, as follows:

pmTickMarkDisplayMode
The default value of pmTickMarkDisplayMode is set to Never.

You can also access resources for any of composite classes of the PlotManager class. However, the PlotManager class modifies the access and behavior of some of the resources belonging to these classes, as follows:

The MapPlot class itself also modifies the access and behavior of a number of TickMark resources.

Additional modifications to TickMark resources

The MapPlot class disables a number of TickMark resources, since it sets them automatically in order to create suitable geographical ticks and labels based on the current map projection and limits. The disabled resources include:

In addition, the MapPlot class intercepts certain TickMark resources, including:

Resources that specify label and axis visibility:

By default, MapPlot decides which TickMark axes and labels to turn on. The axis and labels are always turned off if the viewport edge associated with the axis does not intersect the map projection space anywhere along its length. Otherwise the bottom X-Axis and left Y-Axis are turned on by default. The top X-Axis and right Y-Axis are by default turned on only if the labels differ in some way from those along the opposite axis. By explicitly setting these resources, however, any of the axes and labels can be turned on or off unconditionally, provided only that the viewport intersection test is met.

Resources that control label font height and major axis length:

MapPlot sets the resource tmEqualizeXYSizes True, forcing TickMark length and label fonts to the same size for all axes. It sets an initial size of 0.014 before viewport size scaling for the tm..MajorLengthF and tm..LabelFontHeightF resources. Additionally, it sets all the tm..MajorOutwardLengthF resources to the same value as the major length, causing all TickMark ticks to appear outside the MapPlot viewport. You may, however, set any one of the tm..LabelFontHeightF resources to set a uniform font height for the labels on all axes or any one of the tm..MajorLengthF resources to set a uniform tick length for all axes.

The label overlap prevention resource:

tmLabelAutoStride

By default, MapPlot sets the tmLabelAutoStride resource True in order to ensure that the TickMark labels will never overlap.

Superclass resources

You can access all resources defined by the superclasses of the MapPlot object class, including:

Description

The MapPlot object renders maps of the world in any of 10 different projections. It allows you to limit the projected view to a portion of the globe, as well as to limit the rendering to entities individually selected by name from either of the MapPlot databases. You can outline areas, you can fill areas, or you can mask areas, allowing previously rendered plot elements to remain visible.

MapPlot allows access to three different databases. containing points defining geophysical and (in two cases) political features of the globe. The original database, designated Ncarg4_0, is low resolution and is out out of date with respect to national borders. However, because of its lower resolution, rendering is fast for maps that span a major portion of the globe. Therefore this database remains the default. The second database, designated Ncarg4_1 defines twice as many named areas, has much higher resolution, and the political boundaries are up to date as of mid-year 1999. Because of the density of its data, it is best suited for plots of limited areas of the globe where the greater detail can be appreciated. The third database, designated RANGS contains coastline data only and has multi-resolution capabilities. Its highest resolution is much higher than even the Ncarg4_1 database.

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. Used in conjunction with area masking, these facilities allow you to 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 Greenwich Meridian and the International Dateline. In addition, you can draw a perimeter, either rectangular or elliptical, around the projected map area. Finally MapPlot now supports built-in geographical style tick marks.

MapPlot elements

There are seven basic elements provided by MapPlot:

Outlines: Map boundary outlines are turned on by default. Turn them off by setting mpOutlineOn to False. The drawing order is specified using mpOutlineDrawOrder.
Fill: Map area fill is turned off by default. Turn it on by setting mpFillOn True. The drawing order is specified using mpFillDrawOrder.
Masking: Masking is turned off by default. Turn it on by setting mpAreaMaskingOn. When masking is turned on, areas specified by name in the mpMaskAreaSpecifiers array resource remain empty when fill drawing occurs.
Grid and limb lines: Grid and limb lines are turned on by default. Turn them off by setting mpGridAndLimbOn to False. The drawing order is specified using mpGridAndLimbDrawOrder.
Perimeter line: The perimeter line is turned off by default. Turn it on by setting mpPerimOn to True. The drawing order is specified using mpPerimDrawOrder.
Labels: Labels are turned off by default. Turn them on by setting mpLabelsOn to True. The drawing order is specified using mpLabelDrawOrder.
Tick marks: TickMarks are turned off by default. Turn them on by setting pmTickMarkDisplayMode to Always or Conditional. Tick marks are always drawn during the PostDraw phase.

Controlling the MapPlot transformation

The MapPlot object itself contains the resources that control the rendering of plot features such as area outlines and fill, but you control the projection, its center, and how much of the globe is to appear using resources belonging to the MapPlot's composite MapTransformation object. Note that it is possible to overlay another plot object on a MapPlot object using one of the projections provided by the MapTransformation, and have no MapPlot elements appear in the plot. You would simply turn off each MapPlot element that is drawn by default. That is, you would set the resources mpOutlineOn, and mpGridAndLimbOn False.

The map projections provided by the MapTransformation 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. In this case, you can get the values of the MapTransformation resources mpLeftMapPosF, mpRightMapPosF, mpBottomMapPosF, and mpTopMapPosF in order to find the actual boundaries of the projected area.

The MapPlot databases and datasets

MapPlot currently contains three database versions, which are selected using the resource mpDataBaseVersion. Roughly the three databases may be categorized by the level of detail at which the geographical outlines are drawn. However, the databases also differ in the number of individual areas that are accessible; moveover, they differ fundamentally in the way the geographical entities are organized.

The original MapPlot Ncarg4_0 database contains 583 areas uniquely identified by name. It is the lowest resolution database, and, because it can be rendered more quickly at global scales, it is also the MapPlot default.

The Ncarg4_1 database version has a higher resolution than the original database, and uses a hierarchical model that is much more extensible. It is unique in that there are currently three different datasets with various different boundaries available with this database. You choose the dataset using the resource mpDataSetName. Depending on the dataset there are from 1085 to 6853 named areas. The datasets available are:

The RANGS database has coastline data only and contains no named areas, either geophysical or political. However, it is a multi-resolution database that is capable of much higher resolution than the other databases. The default resolution changes dynamically based on the range of map limits currently in effect. But you can also set the resolution explicitly using the resource mpDataResolution.

Area names

You can retrieve a list of all the area names in the MapPlot database being used by getting the value of the resource mpAreaNames. The list is stored in a fixed order. By setting the mpAreaNames resource you can change an area's name at runtime, but the boundary it describes remains fixed and always has the same element number within the mpAreaNames array. In addition to a name, each area has a type. Each area also belongs to two area groups that are used to determine its fill attributes.

There are no area names associated with the RANGS database.

Area types

You can retrieve an area's type using the read-only integer array resource mpAreaTypes. The number and meaning of the area type categories vary depending on the MapPlot database in use. The Ncarg4_0 database has eight categories while the Ncarg4_1 database currently has four.

When using the Ncarg4_0 database:

The elements of the mpAreaTypes array have the same ordering as the mpAreaNames array. There are 8 types, numbered from 0, as follows:

(0) mpOcean
(1) mpContinent
(2) mpLargeIsland
(3) mpSmallIsland
(4) mpInlandWater
(5) mpNational
(6) mpUSStateLand
(7) mpUSStateWater

The division between large islands and small islands is arbitrary; its purpose is to make it easy to create small scale maps with a less cluttered appearance and some savings of processing time. Each area has only one type, and its geophysical properties are considered first. In other words, areas are classified as mpNational only if they form a proper subset of a geophysical entity. For instance, Bolivia is of type mpNational because it is part, but not the whole, of the geophysical area North-and-South-America. On the other hand, Australia is both a geophysical entity (a continent) and a country, therefore its type is mpContinent. You do not use the area types directly to control the operation of MapPlot; however knowledge of an area's type is useful for understanding the MapPlot object's operation.

When using the Ncarg4_1 database:

The elements of the mpAreaTypes array have the same ordering as the mpAreaNames array. There are 4 or 5 types, depending on the choice of dataset, numbered from 1, as follows:

(1) land or water
(2) continental boundary
(3) national boundary
(4) state or provincial boundary
(5) county boundary or climate division

When using the RANGS database:

Area types are not distinguished.

Pre-defined string constants

Somewhat related to the area types are the pre-defined string constants that specify areas by category. You can use these strings as elements of any of the area specifier resources (mpFillAreaSpecifiers, mpOutlineSpecifiers, mpMaskAreaSpecifiers, and mpMaskOutlineSpecifiers). MapPlot handles all string constants in case-insensitive manner:

When using the Ncarg4_0 database:

The following string constants are recognized:

"NullArea"
"Land"
"Water"
"InlandWater"
"Oceans"
"Continents"
"Islands"
"LargeIslands"
"SmallIslands"
"AllUSStates"
"USStatesLand"
"USStatesWater"
"AllNational"
"AllGeophysical"

Unlike area types, the area categories described by these string constants can overlap. The category "Islands," for instance, includes all the members of "LargeIslands" and "SmallIslands." On the other hand, note that all members of the set "LargeIslands" are of type mpLargeIsland, so knowing an area's type can help you figure out whether it is a member of a particular constant string category.

The string "NullArea" specifies no area at all; it is useful for eliminating an element of one of the area specifier arrays without resizing the array or rearranging the remaining elements.

When using the Ncarg4_1 database:

The string "NullArea" specifies no area at all; it is useful for eliminating an element of one of the area specifier arrays without resizing the array or rearranging the remaining elements.

Available in version 4.2.0.a034 and later.
The following string constants are recognized:

"NullArea"
"States"
"Provinces"
"Counties"

Except for "NullArea" each of these area categories must be appended following a colon (:) to a parent area. For instance, to specify the states of Mexico, you could write the string "Mexico : States"; the counties of Iowa, "Iowa : counties". The strings "States" and "Provinces" are synonyms and can be used interchangeably. Of course, these categories are only applicable if you have selected a dataset (using mpDataSetName) that contains the referenced entities. If you choose the earth..3 dataset, the climate divisions for a US state can be displayed using the "counties" category.

When using the RANGS database:

No string constants are defined.

Boundary sets and area specifiers

The MapPlot object has two types of resources for specifying areas. The first type, supported for outlines and fill, uses resources of type NhlTMapBoundarySets to specify very generally the area sets to be used. The second type, supported for outlines, fill and area masking, allows you to specify groups of areas by category and individual areas by name using string array type resources. For outlines and fill, it is often convenient to use both resource types to complete the specification of the areas desired.

The string array resources allow individual specification of areas and area categories. 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 four: mpOutlineSpecifiers, mpFillAreaSpecifiers, mpMaskAreaSpecifiers, and mpMaskOutlineSpecifiers.

When using the Ncarg4_0 database:: The specifier strings you use for these resources may be any of the MapPlot pre-defined string constants, explicit names from the MapPlot Ncarg4_0 database, or matching substrings. All specifier strings are treated in a case-insensitive manner.
When using the Ncarg4_1 database:: The specifier strings you use for these resources may be names from any of the datasets (selected using mpDataSetNamecontained in the Ncarg4_1 database. The name may be a fully qualified name or contain any part of the basic name's parental hierarchy to the left of the basic name. If a non-unique name, such as "Long Island" (3 separate instances) is specified, all entities that match the name will be selected. The hierarchical parts should be separated using colon characters (':') and period characters ('.'), as shown in the tables for the respective datasets. The specifier strings are treated in a case-insensitive manner.
When using the Ncarg4_1 database:: Neither the NhlTMapBoundarySets type resources nor the specifier string resources are supported.

Substring matching

When using the Ncarg4_0 database:: You form a matching substring by placing the wildcard character '*' at either or both ends of the character group you want to match. For instance, the substring "canada*" matches all entries in the database beginning with the name "Canada," and "*lake*" would match all entries with the letters "lake" (any case) anywhere in the name.
When using the Ncarg4_1 or the RANGS database:: Substring matching is not supported.

Outlines

By default MapPlot draws area outlines, but you can turn them off by setting mpOutlineOn to False. You establish the basic set of outlines to use by choosing a value for the mpOutlineBoundarySets. If you wish, you can then add to the basic outline set by specifying other areas using the resource mpOutlineSpecifiers. Unlike fill, the current version of MapPlot">NhlTMapBoundarySets type resource mpOutlineBoundarySets. If you wish, you can then add to the basic outline set by specifying other areas using the resource mpOutlineSpecifiers. Unlike fill, the current version of MapPlot does not allow individual control of the lines defining the boundary of a particular area. However, you can set outline attributes for three general boundary categories, depending on which of the three basic datasets the line belongs to: geophysical, national, or U.S. States. MapPlot supports line color, line dash pattern, line dash segment length, and line thickness for each category.

Available in version 4.2.0.a034 and later.
You can also mask areas using mpMaskOutlineSpecifiers.

When using the RANGS database:: Only geophysical lines are available and the only line attribute supported is line color.

Area fill

Since area fill is more compute intensive and may not be appropriate for many plotting tasks, MapPlot turns it off by default. Set mpFillOn True to turn it on. MapPlot fill has more options than outlines, and thus is a bit more complicated to explain. Like outlines, you establish a basic set of fill areas using the NhlTMapBoundarySets type resource mpFillBoundarySets. To this set you can add other fill areas using the string array resource, mpFillAreaSpecifiers.

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.

Area groups

MapPlot defines a set of area groups that it uses to determine the "normal" fill attributes assigned to each filled area. By default there are 10 area groups, arranged as follows:

Group 0: Default group: Determines the fill attributes for areas that fall within the map projection boundaries, but otherwise are neither specified as fill areas nor as mask areas.
Group 1: Ocean group: Determines the fill attributes for the world oceans.
Group 2: Land group: Determines the fill attributes for continents and islands.
Group 3: Inland water group: Determines the fill attributes for lakes, inland seas, and all other bodies of water except the oceans.
Groups 4 through 9 (default) through 255 (maximum): Dynamic groups: By default, MapPlot assigns areas to the dynamic groups in such as way as to ensure that adjoining land areas never belong to the same group, and therefore have distinct fill attributes. However, the user may add more dynamic groups and reassign memberships in order to achieve any desired distribution of fill attributes.

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.

Setting fill attributes based on area groups

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 NhlSetValues 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 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: Neither area group array is used. Each area is assigned fill attributes using the default group number (0) as an index.
Geophysical: Each area is assigned fill attributes using its mpFixedAreaGroups group numbers as an index.
National: Each area is assigned fill attributes using its mpDynamicAreaGroups group number as an index.
USStates: If the area belongs within the USStates dataset, it is assigned fill attributes using its mpDynamicAreaGroups group number as an index. Otherwise it is assigned fill attributes using the default group number (0) as an index.
GeophysicalAndUSStates: If the area belongs within the USStates dataset it is assigned fill attributes using its mpDynamicAreaGroups group number as an index. Otherwise it is assigned fill attributes using its mpFixedAreaGroups group number as an index.
AllBoundaries: Each area is assigned fill attributes using its mpDynamicAreaGroups group number as an index.

For areas specified in the mpFillAreaSpecifiers array, you may explicitly set the fill attributes individually as explained in the next section. However, whenever a fill attribute is not explicitly set, MapPlot uses a group number either from the fixed or the dynamic area group arrays as an index into the fill attribute array resources.

When using the Ncarg4_0 database:: In this case, the choice is based on the setting of the mpSpecifiedFillPriority resource. If mpSpecifiedFillPriority has the value 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".
When using the Ncarg4_1 database:: MapPlot picks an index from the mpFixedAreaGroups if the area's type is 1 (mpGeophysical) or if its type is 2 (mpContinental) and its parent is Water. Otherwise it picks an index from the mpDynamicAreaGroups.
When using the RANGS database:: Only the Ocean, Land, and InlandWater groups are recognized and the only supported fill attribute is color. Neither the mpFixedAreaGroups or mpDynamicAreaGroups arrays are used. However, you can set the fill color of the three recognized groups using the "alias" resources: mpOceanFillColor, mpLandFillColor, and mpInlandWaterFillColor.

Explicitly setting fill attributes

You can explicitly set the fill attributes of areas specified in the mpFillAreaSpecifiers array using the array resources mpSpecifiedFillColors, mpSpecifiedFillPatterns, and mpSpecifiedFillScales. Each element of the specified fill attribute arrays provide an attribute value for the corresponding element of the mpFillAreaSpecifiers array. Explicit specification of fill attributes overrides fill attribute selection based on area group memberships. Explicit specification also overrides the Mono flag. Therefore, you can easily highlight an individual area by explicitly setting, for example, the appropriate element of mpSpecifiedFillPatterns to a unique pattern while the remaining areas are all set perhaps to SolidFill, as determined by the value of the mpFillPattern resource.

If you want to explicitly 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 UnspecifiedColor (-2); for mpSpecifiedFillPatterns the special fill pattern index UnspecifiedFill (-2); 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.

When using the RANGS database:: This feature is not supported.

Area masking

MapPlot allows you to specify areas or groups of areas that are to remain unfilled or masked. You enable and disable area masking using the resource, mpAreaMaskingOn. You specify individual areas or area categories that you want to mask using the string array resource, mpMaskAreaSpecifiers.

Alternatively, you can mask areas by setting their fill color to Transparent (-1).

When using the RANGS database:: Area masking is possible for the Ocean, Land, or InlandWater groups by setting mpOceanFillColor, mpLandFillColor, or mpInlandWaterFillColor respectively to Transparent (-1).

Masking and fill precedence

Since there is a potential for fill and masking specifications to conflict with each other, MapPlot has established an order of precedence for these specifiers. Explicitly named areas take precedence over area groups specified using mpFillBoundarySets or any of the pre-defined constants. Small areas take precedence over enclosing larger areas. Otherwise masking takes precedence over filling. Note that if the mpFillBoundarySets resource is set to the value 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.

Grid and limb line

By default MapPlot turns on the map grid and, where appropriate, the limb line; you can turn it off by setting the resource mpGridAndLimbOn False. Set the resource mpGridSpacingF to specify a uniform distance in degrees between grid lines both for longitude and for latitude. If you want different grid spacings for the latitude and the longitude, set the mpGridLonSpacingF and mpGridLatSpacingF resources instead. You can also exercise detailed control over the appearance of the grid in the polar regions using the mpGridMaxLatF and mpGridPolarLonSpacingF resources.

You can turn on grid masking and choose how to select the areas where grid lines do not appear with the NhlTMapGridMaskMode resource mpGridMaskMode. Note that grid masking operates independently of area masking, although it is possible to mask the grid over masked areas if you set mpGridMaskMode to 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.

Labels

MapPlot draws labels by default, but you can turn them off by setting the mpLabelsOn resource False. When labels are turned on, the text strings "NP", "SP", "EQ", "GM", and "ID" are written at the positions of the North Pole, the South Pole, the Equator, the Greenwich Meridian, and the International Dateline. You can control the size of labels using the resources mpLabelFontHeightF and their color using mpLabelFontColor. Currently, no other resources are available for labels.

Perimeter

By default MapPlot draws a rectangular perimeter around the projected map area, but you can turn it off by setting the boolean resource mpPerimOn False. If you set the MapTransformation resource mpEllipticalBoundary True, the perimeter will be elliptical instead of rectangular. You can set line attributes for the perimeter using the resources mpPerimLineColor, mpPerimLineDashPattern, mpPerimLineDashSegLenF, and mpPerimLineThicknessF.

TickMarks

MapPlot implements geographically-labelled tick marks using the PlotManager composite TickMark object. Turn tick marks on by setting the resource pmTickMarkDisplayMode to Always or Conditional. Tick marks are available for all map projections along any axis where the viewport edge intersects the map projection plane for some measurable distance. If the intersection test is met, by default the bottom and left axes are always turned on. The top and right axes are turned on only if the labels or locations would be different in some way from the opposite axes. However, you may explicitly control the state of any particular tick axis or its labels by setting the appropriate tm..On or tm..LabelOn resource.

MapPlot determines whether a particular axis shows divisions of latitude or longitude depending on which of theses dimensions varies most along the axis length. Currently this is a fixed behavior that cannot be overridden. MapPlot fixes font size and tick length to a uniform value for all axes and also decides the tick spacing in all cases. If tick labels are missing due to the effect of the TickMark resource tmLabelAutoStride, you may restore them by setting tmXBLabelFontHeightF to a suitably smaller value.

Support functions

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

Status

2. MapPlot does not support substring matching when using the new Ncarg4_1 map database. Due to the hierarchical nature of the new database, this capability is not as necessary as with the old database. Expect that if and when new matching facilities are developed, they will not work the same way as they do for the old database.

3. 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.