NCL Website header
NCL Home> Application examples> Maps and map projections || Data files for some examples

Example pages containing: tips | resources | functions/procedures

NCL map outlines

NCL has three resolutions of map outline databases available through the mpDataBaseVersion resource.

Note that the behavior of this resource has changed in NCL V6.4.0!

This resource can take one of four values; see the "dynamic" value for details about the change in V6.4.0:

  1. "LowRes" - the default prior to NCL V6.4.0; recommended for global maps and not for regional areas

  2. "MediumRes" - recommended for regional maps; has more up-to-date political boundaries

  3. "HighRes" - a high-resolution coastline database; cannot be used for global maps as it will not be drawn correctly. Requires a "RANGS" database that you need to download and install. Go to the RANGS page for more information.

  4. "Dynamic" - new default behavior introduced with NCL V6.4.0; the LowRes database is used unless either of mpFillBoundarySets or mpOutlineBoundarySets is set to something other than "Geophysical", in which case the MediumRes database is used. (see example 6 below).

To turn NCL map outlines on or off, set the mpOutlineOn resource to True or False. You can also turn map fill on and off by setting mpFillOn resource to True or False to turn on/off map fill.

There are many resources for customizing the look of your map outlines. You can see the full list of map resources here. Here's a sample:

mpGeophysicalLineColor mpGeophysicalLineThicknessF mpGeophysicalLineDashPattern
mpNationalLineColor mpNationalLineThicknessF mpNationalLineDashPattern
mpProvincialLineColor mpProvincialLineThicknessF mpProvincialLineDashPattern
mpUSStateLineColor mpUSStateLineThicknessF mpUSStateLineDashPattern
mpCountyLineColor mpCountyLineThicknessF mpCountyLineDashPattern
In some cases, NCL's map outlines may not give you the outlines or resolution you desire. We recommend that people use shapefiles, which you can find numerous, free examples of using a web browser search. The Global Administrative Database (GADM) (http://www.gadm.org) offers various levels of outlines for many countries in the shapefile format. See the shapefiles examples page for more information.

This page shows you various comparisons of the three map databases, as well as how to add your own map outlines via shapefiles or simple polyline draws via:

mapoutlines_1.ncl: Shows how to draw the Changjiang and Huanghe Rivers on a zoomed in map of China, using gsn_add_polyline.

The script was contributed by Dr. Xiao-Feng Li of the Institute of Atmospheric Physics (IAP), Chinese Acadmey of Sciences (CAS), modified from a GrADS code from Dr. Pinwen Guo (NUIST) and NCL code of Dr. Jun Cheng (NUIST).

mapoutlines_2.ncl: Shows how to draw outlines of Switzerland using shapefiles downloaded from http://www.gadm.org/country.

This example draws a panel plot, comparing NCL outlines with shapefile outlines.

mapoutlines_3.ncl: This script demonstrates the difference in resolution between the three available map databases in NCL, via a zoomed in map of Norway and Sweden.

mpDataBaseVersion is used to set the database that NCL uses to draw the basemap. By default, mpDataBaseVersion is set to "LowRes".

If you want to use the "HighRes" map database, you will have to download the RANGS database.

mapoutlines_4.ncl: This example draws the same contours as the previous example, but uses gsn_add_shapefile_polylines to attach outlines read in from Sweden and Norway shapefiles downloaded from http://www.gadm.org/country.
mapoutlines_5.ncl: This script demonstrates the difference in resolution between the low resolution and medium resolution map databases of NCL, and a world shapefile downloaded from http://www.ngdc.noaa.gov/mgg/shorelines/data/gshhg/latest/.

You cannot use the "HighRes" database with a global map, so the shapefile outlines are your best bet if you need more resolution.

mapoutlines_5_zoom.ncl: This script is similar to the mapoutlines_5.ncl one above, except it includes the "HighRes" database, if installed. It produces two panel plots, so you can compare the various map outlines.

mapoutlines_6.ncl: This script illustrates new default map database behavior introduced in NCL V6.4.0, and shows how to override the defaults. As with prior versions of NCL, the default map database is LowRes, unless either of the boundary-set resources mpFillBoundarySets or mpOutlineBoundarySets are set to anything other than "Geophysical", in which case the MediumRes database is used. This represents a balance between performance and accuracy for common use-cases. The LowRes database is more than adequate for global scale maps depicting land/ocean boundaries, whereas the more detailed MediumRes database is preferred for its more up-to-date political boundaries.

The default behavior can be overridden by explicitly setting mpDataBaseVersion to the desired database name.

shapefiles_15.ncl: This example is another one showing the difference between map outlines in NCL and map outlines added from a shapefile. The first plot in the panel shows the counties of Colorado as plotted from NCL, and the second plot shows the counties as plotted from the USA_adm2 shapefile downloaded from http://www.gadm.org/country.

The left image is from running NCL V6.3.0 on this script. The right image is from running NCL V6.4.0.

In NCL versions 6.3.0 and earlier, the NCL outlines will not show the county of Broomfield or the updated counties around Denver. In NCL version 6.4.0, the NCL map databases were updated to reflect the current Colorado counties.