NCL Home > Documentation > HLUs > User Guide

Understanding the Application Programming Interface

HLU Application Programming Interface (API) overview

There are several classes that are important in the writing of HLU programs: application class, data classes, workstation class, and view class. The application class (App) allows user access to resource databases; it allows for the specification of resource datafile pathnames. Objects belonging to the data class (DataItem) define and input the data to be plotted. Objects of the view class create the plots. Objects of the workstation class set up the destination devices for the plots.

Version 4.1 contains the following classes that you may want to use in your HLU program:

  • Application class

    • App - Used to manage the resource database and other application-specific attributes.

  • DataComm and DataItem classes

    The DataComm class provides the functionality for its subclasses to communicate with the DataItem class. The DataItem class provides a way to describe data to the HLU library.

    At this writing, there are four DataItem subclasses:

    • ScalarField - Defines a 2-D dataset as is needed by the ContourPlot class from C or Fortran.

    • VectorField - Defines a 2-D dataset as is needed by the VectorPlot class or StreamlinePlot class from C or Fortran.

    • CoordArrays - A method for importing X and Y arrays of data from C or Fortran. It uses two arrays, caXArray and caYArray, to describe data to the HLU library. It is often used in combination with the XyPlot class.

    • CoordArrTable - A method for importing X and Y arrays of data (C interface only). It is often used in combination with the XyPlot class. It is useful in defining multiple coordinate arrays of different lengths.

  • Workstation subclasses

    There are currently three devices to which graphical output can be sent: an NCAR Computer Graphics Metafile (NCGM), a PostScript file, and an X11 window on the workstation monitor.

    • NcgmWorkstation - Draw commands are output to an NCAR Computer Graphics Metafile (NCGM).

    • PSWorkstation - Draw commands are output to a PostScript file.

    • XWorkstation - Draw commands are output to an X11 workstation window.

  • View subclasses

    There are two kinds of View classes; one needs data from a DataItem object, and the other does not.

    View objects that require a DataItem object:

    • ContourPlot - Draws a wide range of 2-D contour plots.

    • StreamlinePlot - Draws 2-D streamlines.

    • VectorPlot - Draws vectors at 2-D grid points.

    • XyPlot - Draws plots of field X versus field Y.

    View objects that do not require data input include:

    • GraphicStyle - controls the appearance of graphics primitives such as line, fill, marker, and text.

    • LabelBar - Draws boxes filled with colors or patterns and labels that relate the boxes to plot features.

    • Legend - Draws dashed lines and markers and associated labels that relate the lines/markers to plot features.

    • MapPlot - Draws world and regional maps in many scientifically useful projections.

    • TextItem - Draws strings of text.

    • TickMark - Draws plot grids with scaled, ticked, and labeled axes.

    • Title - Draws main, X, and Y axis titles.

  • Error class

    • Error - Used for logging and reporting errors.

  • Transformation class

    • Transform - Provides subclassed objects with the ability to handle coordinate transformations.

      There are a number of support functions associated with the Transform class that allow data to be defined in one space and retrieved in another, or for polylines to be drawn.

  • PlotManager class

    • PlotManager - Manages overlays of multiple graphical objects.

  • AnnoManager class

    • AnnoManager - Manages the overlay of annotational items and graphical objects.

  • Other classes

    There are additional classes in the HLU library. Most play a behind-the-scenes role. For a complete list see: