Data files for some examples
Example pages containing:
Polygons, Polymarkers, Polylines, Text
This page describes how to use
routines to add markers, lines, filled areas (polygons), and text on
an existing plot or anywhere outside a plot (known as
" or the "frame").
Drawing primivites on a plot
To draw primitives on top of a plot, you must use the plot's data
space. On a map plot, for example, you would use lat/lon
values to position the primitives. The routines for drawing
primitives on a plot are:
The difference between the "add" versions of these routines (which are
functions) and the other routines (which are procedures) is that the
"add" functions actually attach the primitive to the existing plot,
and you won't see the primitive until you actually draw the plot. If
the plot is resized, the primitive will be resized accordingly. This
can be useful if you plan to
use gsn_panel to panel the plot
later and want the primitives to be resized.
Important note: since these are functions, you need to make
sure that every return value is unique. If you reuse the same
variable to add primitives to a plot, then only the last primitive
that you add will be visible. See example "polyg_4.ncl" below.
The procedural versions of these routines simply draw the
primitive when you call procedure, and do not attach the primitive to
the plot. These routines are a little easier to use because you don't
have to worry about the return value. They can also be faster if you
are drawing tons of primitives, because less memory is used.
Drawing primivites on the NDC square
To draw primitives on the NDC square or frame, you must use values
from 0.0 to 1.0 for the location of the primitive(s). Location (0,0)
represents the lower left corner of the square, and (1,1) represents
the upper right corner of the square. The procedures for drawing in
NDC space are:
Note that there are no "add" versions of these routines, because there
is nothing for which to attach the primitives.
Useful tip: the drawNDCGrid
procedure draws a grid and labels the NDC locations. This is very
useful to help you position primitives in the NDC square. See example
Potential backwards-incompatible change
There is a potential incompatible change
and gsn_add_polygon in NCL
version 6.2.0 and later, when
attaching lines or polygons to a map.
Previously, drawing a polyline around the equator, for example, could
be specified using 2-element arrays. For example:
lnid = gsn_add_polyline(wks,map,(/0,360/),(/0,0/),lnres)
Now, however, in order to eliminate a number of ambiguous situations and to make user code simpler in most cases, a new behavior has been introduced: the line between two points on the globe always follows the shortest path. In the example above, the behavior in NCL V6.2.0 leads to a 0-length line. The recommended approach now for drawing a line around the equator is to use four points, such that the distance from one to the next is always less than 180 degrees. For example:
lnid = gsn_add_polyline(wks,map,(/0,120,240,360/),(/0,0,0,0/),lnres)
This code comes from Mark Stevens of CGD NCAR. To teach himself
NCL, he decided to try and plot the climate divisions that are used
by the NCDC. Outstanding job Mark! By the way this is the most
exciting plot to watch as it draws. Each state is done separately.
Can you name each state as it draws?
will add polygons in ndc(page) coordinates while
will add them in plot coordinates.
The "climdiv_polygons.nc" netCDF file used in this script is available
This is the same code as example one, except that Mark is now
coloring each polygon with a precipitation value.
= False, turns off the lat/lon grid.
= True, enables area masking. This then allows the
map to be divided into different areas by setting the resource
, e.g. (/"Water","Land"/). These designated areas
can then be filled by setting the resource
to various colors. In this case, they were
set to zero to mask them entirely.
A plot with poly markers added. You would be able to panel this
plot. There are numerous
to choose from.
is the plot interface that will add polymarkers
to a plot so that they can be paneled. There is also
which adds the polymarkers in page coordinates.
IMPORTANT: note the syntax on the use of this function:
dum1 = gsn_add_polymarker(wks,plot,glon(inds),glat(inds),polyres)
. With this function, you need to set it equal to some sort of
dummy variable. Do not set it equal to plot like we do in all other
cases. Also, if you do panel this type of plot, do not delete that
dummy variable or over write it.
Demonstrates the use of a polygon to shade an xy curve.
Demonstrates adding polylines.
The trick with this plot is to create an array of dummy graphic
variables. When you use
the result must be a graphic variable. In a loop,
you must not over write the dummy variable, which is why we need an
Demonstrates how to create your own polymarker.
As of NCL version 4.2.0.a030, you can make your own marker using
. You give the function the character and font table you
want the marker taken from, and provide sizing and placement values. The
function returns a marker index that can be used with
This example shows how to plot values at station locations using
different colors and marker sizes for each station point. The station
values are grouped depending on which range of values they fall in,
and then every marker in this group gets the same color and size.
A legend is added at the bottom, using calls to gsn_polymarker and gsn_text_ndc.
This example shows how to draw the Meteorological Subdivisions of
India. The first script draws the subdivisions given the boundary
coordinates for each subdivision in an ASCII file. The second
script draws the subdivisions from a shapefile.
In the first script, the left plot
uses gsn_add_polyline to attach
the subdivision outlines to the base map. The right panel
uses gsn_add_polygon add filled
The first script produces two images: the first image uses NCL's
map outlines to draw the states of India
(USE_SHAPEFILE_OUTLINES=False). The second image uses outlines
from a shapefile (USE_SHAPEFILE_OUTLINES=True).
In the second script, the left panel
to add the subdivision outlines and the right panel
to add filled subdivisions. It draws India outlines from the same
shapefile as the second frame of the first script.
The third image with the India outlines and subdivisions coming
from shapefiles seems to be the best "match" between the two sets
This example shows how to draw various polylines and polygons on a
several generic tickmark backgrounds to create a series of bar
charts. The gsn_add_polyline
used to create the polylines and polygons and gsn_panel
is used to panel all the plots
on one frame.
: This example
shows how to draw the political divisions of Brazil. It was
contributed to us by Mateus da Silva Teixeira from IPMet, who
gave us permission to include it and the data files. It is based
on example 9
that draws the Indian
The data files can be downloaded via the estados_brasil.tar tar file.
You need to type "tar -xvf estados_brasil.tar" to extract the files.
In version 5.1.0, you
will be able to generate the states of Brazil using a new NCL map
database. See example
16 on the "maps only" page.
: An example of "layering"
different plot objects to get a particular effect.
As the extratropical polygons (red/blue) require the ocean to overlay the polygons,
and the tropical polygons (green/yellow) require the land to overlay the polygons,
the only way to get the desired effect is to draw two plots, and to set
tfPolyDrawOrder equal to Draw.
A third blank plot is drawn over the previous two to draw the border
This is a reproduction of figure 1b from Kutzbach et al. 2008, Climate Dynamics, 30:567-579.
: An example showing
how to overlay filled boxes on a map using different methods:
The third method is the preferred one if you want straight edges for
your polygon and you want to be able to attach the box to your map
(for paneling or resizing later).
: Draws a line on an
existing map between two points on the globe using two different
to create a great circle path between two
locations. Uses gsn_add_polyline
add the polyline. Any map projection can be used.
: This is a
minimal script to plot the location of stations on a map background.
: This is a
simple script to color plot the location of stations on a map background
and manually add a legend. (Donated by Lisi Pei.)
This example shows how to draw partially transparent filled polygons
using the gsFillOpacityF
introduced in NCL 6.1.0
The point of this example is to show how various boxes look when they
overlaid in a different order. The middle column was drawn starting
with the red box starting first. The right column was drawn with the
yellow box starting first.
: This script
was written mainly to show how to read an ASCII file with groupings
of headers and data.
It then creates a map of color-coded surface wind speed values
based on an array of levels. A new function
called span_color_indexes is used to select a
nice span of colors through the given color map. This function
was added in NCL
: Demonstrates how to
overlay a scatter plot (of filled squares) on a map plot, when the
scatter plot is not in lat/lon space. The key is to use
to create a
canvas for drawing the filled polygons, making sure that the four
corners of the blank plot correspond with the four corners of the
cylindrical equidistant map plot that is created.
You then set tfDoNDCOverlay to
True to make sure that when the blank plot is overlaid on the map
plot using the overlay procedure, it simply
lines up the corners of the two plots and does the draw.
In this example, the blank plot goes from 0,ny+1 in the Y direction,
and 0,nx+1 in the x direction. This corresponds to the following
x = 0 --> lon = -180
x = nx+1 --> lon = 180
y = 0 --> lon = -90
y = ny+1 --> lon = 90
: This script
is an overall demonstration of the various primitive drawing
routines, both for adding or drawing primitives on a plot, and
for drawing primitives in NDC space.
The first frame shows primitives drawn using the map plot's data space
Note the use of unique_string to
generate a unique attribute name, which is then attached to the
existing map variable as a way of creating a unique name for each
An NDC grid is drawn using
drawNDCGrid. This was used to
determine the NDC locations for the primitives in the second frame of
: This script
shows how to draw a map of mainland United States with Alaska, Hawaii,
and Puerto Rico added as annotations at the bottom. Each state is
colored based on population in 2014, using shapefiles downloaded
. The "states.shp" set
of files is available on our data page
: This script
shows how to draw a larger map with a smaller map as an annotation.
Each map is customized by drawing various outlines, turning
tickmarks on/off, and adding text strings and markers.
The USA_adm2.shp shapefile downloaded from
gadm.org is used to specifically
draw the counties of Colorado only, while the USA_adm1.shp shapefile
is used to draw the remaining state outlines.
: This script shows how
to draw large, smooth, hollow circles on a plot.
If you try to draw large circles using gsn_add_polymarker
and a marker index of 4
, they will
The first plot draws a single circle on a map
using nggcog to create the circle and
gsn_add_polyline to add the circle
to the map. A hollow circle using marker index 4
and gsn_add_polymarker and is also
drawn for comparison.
The second plot draws circles and ellipses using an unadvertised
function called "circle_ll" contributed by Arindam Chakraborty. The
circles are added to the plot using