This is documentation for basemap.gs, a Grads script that overlays a land or ocean mask that exactly matches the coastal outlines of the three Grads map files: lowres, mres, and hires. Basemap works by overlaying polygons on top of an existing display; once they are all drawn, the polygons appear as a solid region that covers the land or ocean areas. Basemap does not actually mask the data, it only masks the display of the data.
basemap.gs L(and)/O(cean) <fill_color> <outline_color> <L(owres)/M(res)/H(ires)>
The land and ocean masks are composed of hundreds of polygons that are specified in accompanying ASCII files. The ASCII files must be downloaded from the Grads script library. Once you have downloaded these files and stored them in a convenient location, you must update your copy of basemap.gs to include the path of the location of these files. The script will not work without these files.
- The default values for the optional arguments are: fill_color 15, outline_color 0, and Lowres.
- For the low and medium resolution map files, coverage is global. For the high resolution map, coverage is limited to North America (0-90N, 170W-10W).
- Basemap will work with any scaled or latlon map projection. If you are using Grads version 1.8+, this script will also work properly with the robinson projection and polar stereographic projections from 0-90, 15-90, and 20-90 (North and South). Other projections will work but are not guaranteed because Grads may not clip the basemap polygons properly. A solution to this problem is to use "set mpvals" to override the dimension environment limits. See example #2 below.
- A special basemap option is available to mask out the Mexican and Canadian land regions surrounding the US, so that only the conterminous states are seen. See Example #3 below.
Basemap and Transparent Colors
grads version 2.1+ has the capability to add a transparency level to any defined color. This feature is especially complementary to basemap's capabilities because the land/ocean areas can be subtly identified without completely covering up the displayed data underneath the mask. Unfortunately, the polygons in the basemap database were not created with transparency in mind, and many of them overlap. Overlapping semi-transparent polygons will appear darker in the areas where the overlap occurs because the alpha channel value is being applied twice to the same set of pixels. This spoils the desired effect of the semi-transparent land/ocean mask.
To avoid this, you can plot a transparent color value using a color mask. How this operates "under the hood" is somewhat like double buffering. When the masked color number is encountered, a mask is set up, the same size of the screen image. While that color number is being plotted, the plotting is done to the mask image instead. The mask image can be thought of as simply zeros and ones -- 0 indicating that the color has not been drawn there, 1 that it has. When the drawing action is terminated, at the conclusion of a 'draw' or 'display' command or when another color number is being used, then the "masked" color is drawn to the main plot using a masked paint operation, where the color is painted to the plot everywhere where the mask image was 1. To set a color to be masked, simply specify its alpha channel value as negative. The positive of that value will be used to draw the actual color, when rendered via the mask.
The bottom line is that basemap script will not work with transparent colors -- you must use the custom shapefiles instead. It is important to note that the shapefiles that were created based on the basemap polygon data do not conform to the official ESRI Shapefile Technical Specification. They will display properly when used with GrADS, but do not use these custom shapefiles for any other purpose or with any other shapefile-handling tool.
These commands were used to generate the three panels in the image below, where the land areas are filled in with basemap.gs.set lat 46.8 51.2set lon -128.5 -121.75set gxout grfillset ylab offset xlab offset mpdset lowresset vpage 0 3.6 4 8.5 set poli ondraw title LOWRESd u10m basemap O 15 1 Lset poli offset vpage 3.4 7.0 4 8.5 set mpdset mres d u10mset vpage 6.8 10.4 4 8.5basemap O 15 1 M draw title MRES set mpdset hires set poli offdraw title HIRESd u10mbasemap O 15 1 H
This set of commands demonstrates how to overcome the lack of proper clipping for some domains and projections.set mproj npsset lon -180 180set lat 0 90set mpvals -180 180 60 90display sstbasemap L
To mask out the Mexican and Canadian land regions surrounding the US, so that only the conterminous states are seen, change your land polygon file from lpoly_lowres.asc to lpoly_US.asc: ftp://cola.gmu.edu/grads/scripts/lpoly_US.ascThen run basemap twice:basemap o 0 0 (<- that's oh zero zero) ;* mask out oceanbasemap L 0 0 ;* mask out non-US landThis will only work properly if your domain is within the boundaries 20N-50N, 130W-60W. Low-res maps only. Here is an example of how this can look:
These commands were used to generate the three panels in the image below using transparent color masking and shapefiles instead of the basemap script in order to achieve a semi-transaprent land mask. For each panel, the data and the map outlines are drawn first, then the shapefiles are overlaid using the same semi-transparent color for the fill and outline.'set rgb 16 1 1 1 -80''set map 0 1 3''set shpopts 16''set line 16''set mpdset lowres''set vpage 0 3.6 0 4' 'd u10m''draw title LOWRES SHAPEFILE''draw shp grads_lowres_land' 'set vpage 3.4 7.0 0 4''draw shp grads_mres_land''set mpdset mres' 'set poli off' 'd u10m' 'draw title MRES SHAPEFILE''draw shp grads_hires_land''set vpage 6.8 10.4 0 4' 'set mpdset hires' 'd u10m'
'draw title HIRES SHAPEFILE'