Visualization specification process

Introduction

This module discusses how to create HLU objects in NCL and how to change values in and retrieve values from those objects. Also discussed here is how to do overlays, that is, how to superimpose one plot on top of another.

Creating HLU objects

The way to create HLU objects in NCL is to use the create expression that is part of an NCL visualization block. The create expression is the NCL analog of the HLU NhlCreate function. Here is a simple example of using the NCL create expression to create a simple TickMark object: 

    box_id = create "Box" tickMarkClass xworkid
        "tmXBDataLeftF": 0.
        "tmXBDataRightF": 1.
        "tmYLDataTopF": 1.
        "tmYLDataBottomF": 0.
        "tmYLLabelsOn": "False"
    end create

In this example, box_id is returned as the object id of the TickMark object that is created; "Box" is the name of the created object; tickMarkClass is the class of object being created; xworkid is an id of an object to be used as the parent of the object being created. In this case, xworkid would be an object identifier for an X11 workstation that would need to have been created before the above create is done. Note how easy it is to specify values for resources in NCL creates.

Changing resource values

If you want to change the value of a resource in an object that has already been created, you can do this with the NCL setvalues expression. For example, suppose that after you did the create above, you wanted to specify a new value for the left X-axis value. You could do this with: 

    setvalues box_id
       "tmXBDataLeftF": -1.
    end setvalues

Values for HLU resources can also be assigned via a resource file as well as in the NCL visualization blocks. For details on setting values for resources, see the document Understanding resources in the HLU User Guide. To set resource values via a resource file, you must create an App object to supply the base name of the resource file. For example, the following NCL create expression would provide access to a resource file named "my_resources.res": 

    appid = create "my_resources" appClass defaultapp
       "appDefaultParent" : "True"
    end create

Retrieving resource values

Values for resources can easily be retrieved in NCL by using the getvalues expression. For example, 

    getvalues box_id
       "tmXBDataLeftF": x_left_value
    end getvalues

would return the current value for tmXBDataLeftF in the NCL variable x_left_value.

Overlays

Overlays allow you to have two or more transformation objects share the same data coordinate space. This allows you to superimpose one plot on another and have them share the same data transformations. Overlays are created starting with a base plot and adding transform objects using the NCL overlay procedure. Note that the base plot must be a plot object, that is an object belonging to the transform class that contains a PlotManager instance that is not itself an overlay. The only classes that can be instantiated as plot objects are those with the word plot in the class name. The NCL function NhlRemoveOverlay can be used to remove one or more plots from an overlay.

A thorough description of overlays and annotations is contained in the reference page for PlotManager.

Presented below is a very simple example of how to use the NCL overlay procedure. This example is for illustration only, since you would not want to create an overlay to do what it does (superimpose a curve on a background box). You would just use a single XyPlot object to do this. For more sophisticated examples of using overlays, see cn05n.ncl, xy10n.ncl, and mp03n.ncl. The Quick Start Guide explains how to run these examples. 

;
; Simple example of using the NCL overlay procedure.  This example
; is for illustration only - it does not reflect real-world usage.
;

;
; Create an X11 output workstation.
;

xworkid = create "simple" xWorkstationClass defaultapp
    "wkPause" : "True"
end create

;
; Create an XyPlot object that is just a box.  This object will be
; used as the base plot.
;

box_id = create "Box" xyPlotClass xworkid
    "tmXBLabelsOn": "False"
    "tmYLLabelsOn": "False"
    "tmXBOn": "False"
    "tmXTOn": "False"
    "tmYLOn": "False"
    "tmYROn": "False"
;
;   Specify the plot limits to conform with those of the subsequent overlay.
;
    "trXMinF": -1.
    "trXMaxF":  1.
    "trYMinF":  0.
    "trYMaxF":  1.
end create

;
; Create data for another XyPlot object that is simply a curve.  This
; object will be used as an overlay to the base plot.
;

dataid = create "xyData" coordArraysClass defaultapp
    "caXArray": (/ -1., 0., 1./)
    "caYArray": (/  0., 1., 0./)
end create

;
; Create the XyPlot overlay (by default PlotManager will not
; create a TickMark object for this object since pmTickMarkDisplayMode 
; is set to "NoCreate").
;

curve_id = create "Curve" xyPlotClass xworkid
    "xyCoordData": dataid
end create

;
; Overlay the curve on the box.
;

overlay(box_id,curve_id)

;
; Draw the plot which is the curve overlaid on the box.
;

draw(box_id)
frame(xworkid)

User Guide Control Panel

NG4.1 Home, Index, Examples, Glossary, Feedback, UG Contents, UG WhereAmI?

$Revision: 1.9 $ $Date: 1998/06/15 22:08:31 $