Creating Graphical Output

NCL uses the NCAR Graphics High Level Utilities Library (HLU) to produce its graphical output. Complete documentation on the HLUs is available from the HLU User Guide and the HLU Reference Guide. In addition, NCL source code examples using the HLU library can be obtained from the Quick Start Guide Examples documentation.

This section of the NCL reference guide covers some basics of using the HLU libraries and NCL's interface to the HLUs. This is not an exhaustive manual for the HLUs. This section is intended to be a basic overview of useful features.

HLU Basics

Plot creation can get very complex depending on how you want to look at your data. NCL's interface for creating graphics is called the High Level Utilities (HLUs). There are five basic steps needed to create a simple plot. Issues such as combining plots, multiple plot frames, adding maps, and annotations are covered later.

The following is a short script demonstrating these steps. The available plot types are listed in the HLU reference manual. The following creates a simple filled contour plot from a data file included with the NCAR Graphics release. The following script should run without modification on your system if the NCAR Graphics data directory was installed.

Setting the size of a plot

The resources vpXF, vpYF, vpWidthF,i and vpHeightF are used to specify the size of the output plot. The values of these resources can be set to values between 0.0 and 1.0. The output frame, regardless of which output device is open, has coordinates called Normalized Device Coordinates (NDC). These coordinates range from 0.0 to 1.0 along each axis of the output frame. The setvalues statement is used to assign values to each of these resources. Every object that can be drawn accepts these four resources for setting size.

Transformations

The transformation is defined as how the data coordinates are mapped to the screen. Contour plots, vector plots, and streamline plots all work the same way, xy plots are slightly different.

Conceptually you must think of two transformations. One is the natural transformation of the data which is defined by the data's coordinates. The second is the view transformation (how you want to look at the data). If the data's coordinates are evenly spaced, then the data's natural transformation is a Linear uniformly spaced transformation. In order to view the data in a different transformation you must create an additional plot, either a mapPlot, an irregularPlot, or a logLinearPlot and call the overlay procedure. This will allow you to select how the data are displayed.

A note about IrregularPlots. These are NOT randomly spaced plots, they are plots where the coordinates for each axis are not evenly spaced, but are still rectilinear, meaning all adjacent points along the X axis have the same Y coordinate and vice versa. This type of data's natural transformation is irregular; when the data is viewed, it is neither a linear projection nor a log projection. The tick marks will be irregularly spaced.

So to sum it up for contour plots and similar plots, if no coordinate values are set for the plot's scalar field, the transformation will be integer grid coordinates which represent the integer indexes of each grid point. If coordinates are set using the sfYCStartV, sfYCEndV, sfXCStartV, and sfXCEndV, then the HLUs assume that the grid points are equally spaced starting at the beginning and end of each coordinate range. In this case the default view will be use linear axis to display the contour. The resources sfYArray and sfXArray are used if the grid points are not equally spaced (this happens with the latitude coordinate for Gaussian grids). In this situation the output display is not a linear axis, it is called an irregular axis. This transformation essentially displays the grid with each point being equally spaced but marks the axis by the function defined by the sequence of points in the coordinate arrays. This type of transformation is especially useful for coordinate systems which are neither log base 10 nor linear. Example cn03 demonstrates this type of transformation.

Changing the data of a plot

Since the HLUs are object oriented, it is very simple to change the data for a plot. Changing the data does not require recreating plots. The setvalues statement is used to reset the data array in the plot's data object. For example, consider changing the above plot from using the first time step to using the second. The following is all that is needed to update the plot and redraw it: 

	setvalues data
		"sfDataArray" : data_file->p(1,:,:)
	end setvalues
	draw(contour)
	frame(xwks)
That's it. No need to do anything more. The contour plot is automatically informed that the data have changed, and it updates itself.

In XyPlot, it is possible to have multiple curves and data objects in a single plot. Because of this, a special function to add new data and a special procedure to remove old data can be used without affecting the data already in the plot. These routines are NhlAddData and NhlRemoveData. The return value from NhlAddData is called a Data Specific Object. It is used to allow individual customization of how a piece of data is displayed. For instance, it is used in the XyPlot to send line styles, labeling, and colors for each data object; see the XyPlot section on modifying a plot.

Modifying a plot

The setvalues statement can be used to modify a plot once it has been created. Modifications could be anything from resizing, to changing the data, to changing the colors.

Contour plots

The following are frequently used resources for configuring the ContourPlot object. For a full list of these resources and more descriptions, see the HLU reference guide section for ContourPlot.

Xy plots

The following are frequently used resources for configuring the XyPlot object. For a full list of these resources and more descriptions, see the HLU reference guide section for XyPlot. The most important thing to know about the XyPlot that makes it different from other plots is that it accepts multiple data objects. The data objects can be added and removed at will. Each data object can represent one or more curves. Since these can be added and deleted, it is difficult to specify colors and curve-specific attributes, like line styles and labels, in the XyPlot itself. Because of this the XyPlot uses a special data specific object for configuring colors and line styles that is associated with each of the XyPlot's data objects. In this way it is not confusing as to which color belongs to which piece of data.

The following are resources that apply to the XyPlot data specific object, objects referenced by the resource "xyCoordDataSpec":

Vector plots

The following are frequently used resources for configuring the VectorPlot object. For a full list of these resources and more descriptions, see the HLU reference guide section for VectorPlot. VectorPlot can display vectors in a variety of fashions. There are line vectors, filled vectors, and wind barbs. A variety of "looks" can be obtained by adjusting arrow head and tail sizes as well as shape.

Streamline plots

The following are frequently used resources for configuring the StreamLinePlot object. For a full list of these resources and more descriptions, see the HLU reference guide section for StreamLinePlot.

Legends, Label Bars, TickMarks, and Titles

Legends, Label Bars, TickMarks, and Titles are special types of annotations that are controlled by an object called a PlotManager. ContourPlot, VectorPlot, StreamLinePlot, XyPlot, and MapPlot are all PlotManagers. This means that they can accept overlayed plots, they accept PlotManager resources, and finally that they manage Legends, Label Bars, TickMarks, and Titles. When a PlotManager is "managing" one of these types of annotations, it means the user does not have to create and configure these objects. For example, when ContourPlot displays a LabelBar, it configures each of the LabelBar's filled boxes and sets the valid label resources. If users were to create a LabelBar manually, they'd have to set all the applicable LabelBar resources, including its position. The PlotManager takes care of these details. Also when an annotation like LabelBar is managed by a PlotManager, the LabelBar's resources can be directly set through the managing object (ContourPlot, XyPlot...) rather than through the LabelBar object itself.

The following resources are PlotManager resources that control the display of Legends, LabelBars, TickMarks, and Titles:

For specific resources, see the HLU reference guide sections for the LabelBar, Legend, Title, and TickMark objects.

Using maps

MapPlots are a special type of plot. Although instances of MapPlot don't accept data, they do provide a transformation from lat/lon coordinates to screen coordinates. Furthermore, one or more of the other types of plots can be overlayed using the overlay procedure. One important item to note is that MapPlot is really two objects: the MapPlot and the MapTransformation. The only reason to be aware of this is that some MapPlot resources -- those that configure map outlines and colors -- are documented in the MapPlot reference page, and others -- those that configure the transformation -- are documented in the MapTransformation section of the reference guide. Both sets of resources are set through a single MapPlot instance.

The following are important resources for configuring MapPlot:

Using Resource Files

Resource files are external text files that can be used to create default templates for resources. There are two user-editable default resource files. One can be put in your home directory and is named ".hluresfile", the other is named "ncl.res" and goes in the directory you're running NCL. Different directories can have different "ncl.res" files, which means different directories can have different default plot configurations. There are other more advanced uses of resource files which are not covered here. See the HLU user guide section on Understanding resources and the section on Using resource files. The file ".hluresfile" is used to supply resources globally, meaning every time you run NCL the defaults set in ".hluresfile" can be used. If the "ncl.res" file exists in NCL's current working directory, then the resources in "ncl.res" can be used. It is important to note that resources in an "ncl.res" file will override those in ".hluresfile".

Every time you create a plot, a name must be given to that plot. This name can be used to determine which resources should be applied to the plot being created. By using the name of the plot, specific resources can be directed to specific plots. For example, consider the following small resource file. This example shows how to set defaults for two different projections. By using this resource file, the NCL script is greatly shortened. To get an idea of how resource files work, run the following example on your own. Save the resources in a file called "ncl.res", and run the script in the same directory. This should be enough to convince you of the utility of resource files and of the convenience that carefully designed resource files can provide. 

	begin
		x = create "x" xWorkstationClass defaultapp end create
		mp0 = create "Pacific Ocean" mapPlotClass x
			"vpXF" : .01
			"vpYF" : .99
			"vpWidthF" : .9
			"vpHeightF" : .5
		end create
		mp1 = create "Atlantic Ocean" mapPlotClass x
			"vpXF" : .01
			"vpYF" : .49
			"vpWidthF" : .9
			"vpHeightF" : .5
		end create
		draw((/mp0,mp1/))
		update(x)
	end



	*Pacific Ocean*mpCenterLatF : 0.0
	*Pacific Ocean*mpCenterLonF : 180.0
	*Pacific Ocean*mpProjection : CYLINDRICALEQUIDISTANT
	*Pacific Ocean*mpLimitMode : LATLON
	*Pacific Ocean*mpMaxLatF : 67.67
	*Pacific Ocean*mpMinLatF : -34.0
	*Pacific Ocean*mpMaxLonF : 291.00
	*Pacific Ocean*mpMinLonF : 100.00
	*Pacific Ocean*vpYF : .92
	*Pacific Ocean*mpFillOn : True
	*Pacific Ocean*mpMonoFillColor : True
	*Pacific Ocean*mpMonoFillPattern : False
	*Pacific Ocean*mpMonoFillScale : False
	*Pacific Ocean*mpOceanFillPattern : -1
	*Pacific Ocean*mpLandFillPattern : 17
	*Pacific Ocean*mpLandFillScaleF : .70

	*Atlantic Ocean*mpCenterLatF : 0.0
	*Atlantic Ocean*mpCenterLonF : 0.0
	*Atlantic Ocean*mpProjection : CYLINDRICALEQUIDISTANT
	*Atlantic Ocean*mpLimitMode : LATLON
	*Atlantic Ocean*mpMaxLatF : 67.67
	*Atlantic Ocean*mpMinLatF : -34.0
	*Atlantic Ocean*mpMaxLonF : 17.
	*Atlantic Ocean*mpMinLonF : -98.0
	*Atlantic Ocean*vpYF : .92
	*Atlantic Ocean*mpFillOn : True
	*Atlantic Ocean*mpMonoFillColor : True
	*Atlantic Ocean*mpMonoFillPattern : False
	*Atlantic Ocean*mpMonoFillScale : False
	*Atlantic Ocean*mpOceanFillPattern : -1
	*Atlantic Ocean*mpLandFillPattern : 17
	*Atlantic Ocean*mpLandFillScaleF : .70

Using annotations

Annotations are an advanced topic. Essentially Annotations are ancillary plots that can be "attached" to plot that is a PlotManager. This means that the ancillary plot can be redrawn, moved, and even resized by drawing or changing the position of the PlotManager to which it is assigned. These ancillary plots can be TextItems, LabelBars, Legends, TickMarks, or other Plots. For each plot added to a PlotManager as an annotation, an object called an AnnoManager is created. This additional object contains resources for positioning the annotation. The following are key AnnoManager resources:

Drawing lines and polygons

Since lines and polygons need to have colors, dash patterns, and fill patterns associated with them, a special object is needed to specify these options. This object is called a GraphicStyle object. The GraphicStyle object can be modified just like other objects using setvalues. A custom GraphicStyle object can be created using the create command, or the default one can be retrieved from the current workstation using the resource "wkDefGraphicStyleId". The graphic style has resources for changing line styles, colors, polygon fill patterns, markers, and line labels. Also needed to draw lines and primitives is either a plot on which the line or polygon will be drawn, or a workstation on which the line or polygon will be drawn. If a plot is provided, then the polygon or line is clipped to the viewport of the plot. If a workstation is provided, then the polygon or line is clipped to the workstation frame.

There are six procedures that use the GraphicStyle object; three use data coordinates for points, and three use NDC or screen coordinates. Each takes a plot or workstation, a graphic style, and two vectors of coordinates either in NDC units or data coordinates. They are:

Reference Manual Control Panel

NG4 Home, Index, Examples, Glossary, Feedback, Ref Contents, Ref WhereAmI?