StreamlinePlot class

The StreamlinePlot class represents a vector field by drawing streamlines.

Synopsis

Header file:		ncarg/hlu/StreamlinePlot.h
Class name:		streamlinePlotClass
Class pointer:		NhlstreamlinePlotClass
Fortran class function:	NHLFSTREAMLINEPLOTCLASS
Superclass:		DataComm
Composite classes:	LogLinTransformation,IrregularTransformation,PlotManager

Data specific class
Class name:		streamlinePlotDataDepClass
Class pointer:		NhlstreamlinePlotDataDepClass
Fortran class function:	NHLFSTREAMLINEPLOTDATADEPCLASS
Superclass:		DataSpec

Class-defined types

Resources

Local resources

+---------------------------------------------------------------+
|		StreamlinePlot Resource Set			|
|---------------------------------------------------------------|
| NAME				TYPE			ACCESS	|
|	CLASS				DEFAULT			|
|===============================================================|
| stVectorFieldData             NhlTInteger             RCSG    |
|       StVectorFieldData               <none>                  |
|---------------------------------------------------------------|
| stStreamlineDrawOrder         NhlTDrawOrder           RCSG    |
|       StStreamlineDrawOrder           "Draw"                  |
|---------------------------------------------------------------|
| stMapDirection                NhlTBoolean             RCSG    |
|       StMapDirection                  True                    |
|---------------------------------------------------------------|
| stStepSizeF                   NhlTFloat               RCSG    |
|       StStepSizeF                     <dynamic>               |
|---------------------------------------------------------------|
| stMinLineSpacingF             NhlTFloatGenArray       RCSG    |
|       StMinLineSpacingF               <dynamic>               |
|---------------------------------------------------------------|
| stMinStepFactorF              NhlTFloatGenArray       RCSG    |
|       StMinStepFactorF                2.0                     |
|---------------------------------------------------------------|
| stLengthCheckCount            NhlTInteger             RCSG    |
|       StLengthCheckCount              35                      |
|---------------------------------------------------------------|
| stCrossoverCheckCount         NhlTInteger             RCSG    |
|       StCrossoverCheckCount           -1                      |
|---------------------------------------------------------------|
| stLineStartStride             NhlTInteger             RCSG    |
|       StLineStartStride               2                       |
|---------------------------------------------------------------|
| stArrowStride                 NhlTInteger             RCSG    |
|       StArrowStride                   2                       |
|---------------------------------------------------------------|
| stArrowLengthF                NhlTFloat               RCSG    |
|       StArrowLengthF                  <dynamic>               |
|---------------------------------------------------------------|
| stMinArrowSpacingF            NhlTFloatGenArray       RCSG    |
|       StMinArrowSpacingF              0.0                     |
|---------------------------------------------------------------|
| stLineThicknessF              NhlTFloat               RCSG    |
|       LineThicknessF                  1.0                     |
|---------------------------------------------------------------|
| stLineColor                   NhlTInteger             RCSG    |
|       LineColor                       "Foreground"            |
|---------------------------------------------------------------|
| stNoDataLabelOn               NhlTBoolean             RCSG    |
|       AnnotationLabelsOn              True                    |
|---------------------------------------------------------------|
| stNoDataLabelString           NhlTString              RCSG    |
|       StNoDataLabelString             <dynamic>               |
|---------------------------------------------------------------|
| stZeroFLabelOn                NhlTBoolean             RCSG    |
|       AnnotationLabelsOn              True                    |
|---------------------------------------------------------------|
| stZeroFLabelString            NhlTString              RCSG    |
|       StZeroFLabelString              <dynamic>               |
|---------------------------------------------------------------|
| stZeroFLabelFontHeightF       NhlTFloat               RCSG    |
|       FontHeightF                     <dynamic>               |
|---------------------------------------------------------------|
| stZeroFLabelTextDirection     NhlTTextDirection       RCSG    |
|       TextDirection                   "Across"                |
|---------------------------------------------------------------|
| stZeroFLabelFont              NhlTFont                RCSG    |
|       Font                            "pwritx"                |
|---------------------------------------------------------------|
| stZeroFLabelFontColor         NhlTColorIndex          RCSG    |
|       FontColor                       "Foreground"            |
|---------------------------------------------------------------|
| stZeroFLabelFontAspectF       NhlTFloat               RCSG    |
|       FontAspectF                     1.3125                  |
|---------------------------------------------------------------|
| stZeroFLabelFontThicknessF    NhlTFloat               RCSG    |
|       FontThicknessF                  1.0                     |
|---------------------------------------------------------------|
| stZeroFLabelFontQuality       NhlTFontQuality         RCSG    |
|       FontQuality                     "High"                  |
|---------------------------------------------------------------|
| stZeroFLabelConstantSpacingF  NhlTFloat               RCSG    |
|       TextConstantSpacingF            0.0                     |
|---------------------------------------------------------------|
| stZeroFLabelAngleF            NhlTFloat               RCSG    |
|       TextAngleF                      0.0                     |
|---------------------------------------------------------------|
| stZeroFLabelFuncCode          NhlTCharacter           RCSG    |
|       TextFuncCode                    :                       |
|---------------------------------------------------------------|
| stZeroFLabelBackgroundColor   NhlTColorIndex          RCSG    |
|       FillBackgroundColor             "Background"            |
|---------------------------------------------------------------|
| stZeroFLabelPerimOn           NhlTBoolean             RCSG    |
|       EdgesOn                         True                    |
|---------------------------------------------------------------|
| stZeroFLabelPerimSpaceF       NhlTFloat               RCSG    |
|       EdgeBorderWidthF                0.33                    |
|---------------------------------------------------------------|
| stZeroFLabelPerimColor        NhlTColorIndex          RCSG    |
|       EdgeColor                       "Foreground"            |
|---------------------------------------------------------------|
| stZeroFLabelPerimThicknessF   NhlTFloat               RCSG    |
|       EdgeThicknessF                  1.0                     |
|---------------------------------------------------------------|
| stZeroFLabelZone              NhlTInteger             RCSG    |
|       StZeroFLabelZone                0                       |
|---------------------------------------------------------------|
| stZeroFLabelSide              NhlTPosition            RCSG    |
|       StZeroFLabelSide                "Bottom"                |
|---------------------------------------------------------------|
| stZeroFLabelJust              NhlTJustification       RCSG    |
|       StZeroFLabelJust                "CenterCenter"          |
|---------------------------------------------------------------|
| stZeroFLabelParallelPosF      NhlTFloat               RCSG    |
|       StZeroFLabelParallelPosF        0.0                     |
|---------------------------------------------------------------|
| stZeroFLabelOrthogonalPosF    NhlTFloat               RCSG    |
|       StZeroFLabelOrthogonalPosF      0.0                     |
+---------------------------------------------------------------+

Data specific resources

The StreamlinePlot class does not currently use any data specific resources.

Composite resources

Transformation resources

Transformation class resources specify the extent and direction of the data coordinate system. As the superclass of both LogLinTransformation and IrregularTransformation, you can access all Transformation resources. However, note that StreamlinePlot intercepts these resources, as follows:

trXMinF
By default trXMinF is set to the minimum data coordinate value along the X Axis, as determined from the contents of the VectorField object.
trXMaxF
By default trXMaxF is set to the maximum data coordinate value along the X Axis, as determined from the contents of the VectorField object.
trXReverse
By default trXReverse is set based on the direction of the X Axis implied by the contents of the VectorField object.
trYMinF
By default trYMinF is set to the minimum data coordinate value along the Y Axis, as determined from the contents of the VectorField object.
trYMaxF
By default trYMaxF is set to the maximum data coordinate value along the Y Axis, as determined from the contents of the VectorField object.
trYReverse
By default trYReverse is set based on the direction of the Y Axis implied by the contents of the VectorField object.

LogLinTransformation resources

The StreamlinePlot class uses the LogLinTransformation to handle its transformations as long as neither of the VectorField array resources, vfXArray or vfYArray, is set. LogLinTransformation has resources for selecting between linear and logarithmic coordinates for each axis.

You can access all LogLinTransformation resources. However, note that StreamlinePlot intercepts LogLinTransformation resources, as follows:

trXLog
StreamlinePlot issues a warning if trXLog is set True when the set value of trXMinF is less than or equal to 0.0. In this case it resets trXLog to False. If the IrregularTransformation resource trXAxisType is set, StreamlinePlot sets trXLog True if trXAxisType is set to LogAxis. If trXAxisType is set to any other value, it sets trXLog False.
trYLog
StreamlinePlot issues a warning if trYLog is set True when the set value of trYMinF is less than or equal to 0.0. In this case it resets trYLog to False. If the IrregularTransformation resource trYAxisType is set, StreamlinePlot sets trYLog True if trYAxisType is set to LogAxis. If trYAxisType is set to any other value, it sets trYLog False.

IrregularTransformation resources

StreamlinePlot automatically uses the IrregularTransformation instead of the LogLinTransformation to handle its transformations if either of the VectorField arrays vfXArray or vfYArray is set, implying that one or both of the coordinate axes is irregularly spaced.

All Transformation superclass resources are accessible. However, StreamlinePlot blocks access to all resources specific to the IrregularTransformation except for:

In addition, StreamlinePlot intercepts these IrregularTransformation resources:

trXAxisType
If the VectorField resource vfXArray is non-NULL and trXAxisType is set to any other value than IrregularAxis, StreamlinePlot switches to a coordinate extent bounded by 0 and the length of the X-Axis dimension minus one. If trXAxisType is not set, but the LogLinTransformation resource trXLog is set, StreamlinePlot sets trXAxisType to LogAxis if trXLog is True; if trXLog is False, it changes trXAxisType to LinearAxis if it had been set to LogAxis and leaves it unchanged otherwise. trXAxisType can be set to LogAxis without error only when the X-Axis coordinate extent as passed from the VectorField is entirely positive. If this is not the case, trXAxisType will default to LinearAxis.
V4.1 Status Note 1
trYAxisType
If the VectorField resource vfYArray is non-NULL and trYAxisType is set to any other value than IrregularAxis, StreamlinePlot switches to a coordinate extent bounded by 0 and the length of the Y-Axis dimension minus one. If trYAxisType is not set, but the LogLinTransformation resource trYLog is set, StreamlinePlot sets trYAxisType to LogAxis if trYLog is True; if trYLog is False, it changes trYAxisType to LinearAxis if it had been set to LogAxis and leaves it unchanged otherwise. trYAxisType can be set to LogAxis without error only when the Y-Axis coordinate extent as passed from the VectorField is entirely positive. If this is not the case, trYAxisType will default to LinearAxis.
V4.1 Status Note 1

PlotManager resources

If tfPlotManagerOn is True when a StreamlinePlot object is created, you can access all PlotManager resources. However, note that StreamlinePlot intercepts certain PlotManager resources, as follows:

pmLabelBarDisplayMode
The pmLabelBarDisplayMode resource is hard-coded to its default value of NhlNOCREATE in XyPlot.
pmLegendDisplayMode
The pmLegendDisplayMode resource is hard-coded to its default value of NhlNOCREATE in StreamlinePlot.
pmTickMarkDisplayMode
The default value of pmTickMarkDisplayMode is set to Conditional.
pmTitleDisplayMode
The default value of pmTitleDisplayMode is set to Conditional.

Except for Legend and LabelBar, you can access resources for any of the composite classes of the PlotManager class. However, the PlotManager class modifies the access and behavior of some of the resources belonging to these classes, as follows:

Superclass resources

You can set all resources defined by the superclasses of the StreamlinePlot object class, including:

Description

A StreamlinePlot object, or streamlineplot, represents a vector field using streamlines, based on two-dimensional data provided by an instance of the VectorField class. It supports title and tick mark annotations that automatically adjust themselves to the state of the streamlineplot.

The StreamlinePlot class provides a number of resources that you can use to influence the way the streamlines are generated and displayed.

Data input

The only resource you must set in order to generate a streamlineplot is stVectorFieldData. This resource specifies the id of an existing VectorField object. The vectorfield accepts data in a variety of types and configurations, and allows you to specify how it is to be interpreted. As received by the streamlineplot, the data are accompanied by information specifying the extents of the data in the data coordinate system, the minimum and maximum data magnitudes, as well as the minimum and maximum values of each component of the vector. Also, if either or both of the data coordinate axes is irregularly spaced, the vectorfield communicates information defining this spacing.

Coordinate transformations

StreamlinePlot intrinsically supports linear, logarithmic, and irregular rectangular gridded data coordinate spaces. It does not yet, on its own, support the transformation of an irregular data space into either a linear or a logarithmic space. However, such transformations are easily accomplished using the overlay mechanism.

StreamlinePlot instantiates child objects to manage transformations between the data coordinate system and NDC space. The LogLinTransformation manages linear and logarithmic transformations, and the IrregularTransformation manages the transformation if one or both axes are irregularly spaced. By default the data coordinate extents are based on the extents of the supplied VectorField object data, but you may adjust them using resources belonging to the transformation objects.

Use of the LogLinTransformation object

StreamlinePlot uses a LogLinTransformation object as long as the VectorField resources vfXArray and vfYArray are both NULL. The coordinate extents of a linear axis may arbitrarily intersect or encompass the data extent. If you set a logarithmic axis, then the coordinate extent of that axis must be entirely positive, but otherwise may intersect or extend beyond the data extent.

Use of the IrregularTransformation object

If either of the VectorField coordinate array resources vfXArray and vfYArray are non-NULL, then StreamlinePlot uses an IrregularTransformation object. Note that StreamlinePlot treats an axis with an associated coordinate array as irregular even if the coordinate array actually has evenly spaced values. StreamlinePlot represents an irregular axis not by stretching and compressing various regions of the plot, but by displaying it with irregularly spaced tick marks.

In addition to a small performance penalty, there are some restrictions associated with use of the IrregularTransformation object. Although you may limit the coordinate extent to a subspace of the data coordinate extent of the VectorField object data, you are not allowed to define a coordinate range that extends outside the range of the data coordinates of an irregular axis. Using the IrregularTransformation resources trXAxisType or trYAxisType, it is possible to set an irregular axis to LinearAxis or even, under certain conditions, to LogAxis, but the results are probably not what you want. Since StreamlinePlot does not intrinsically support a linearization transformation for irregularly spaced data, it can only switch to a linear system by replacing the data coordinates with array index coordinates, which are, in fact, linearly spaced. To properly transform irregularly spaced data into a linear or logarithmic coordinate system, you must use the overlay mechanism (V4.1 Status Note 1).

Overlays

In addition to the built-in transformation support, you can map a streamlineplot into a variety of other coordinate spaces by adding it as an overlay to a base plot. You can overlay a streamlineplot on a mapplot to transform the data into any of 10 different map projections. You can transform irregularly gridded vector data into a linear or logarithmic space by overlaying the streamlineplot on a loglinplot. You can also make a streamlineplot into an overlay of any other plot object, including a contourplot, an irregularplot, a vectorplot, or an xyplot. Use the NhlAddOverlay function to perform an overlay.

Mapping the vector direction

In certain situations, such as when the coordinate system is irregular or when the units along each coordinate axis are different, you may want to draw streamlines within a coordinate space but without transforming the directional components relative to the space. StreamlinePlot has a boolean resource called stMapDirection that allows you to specify whether the direction as well as the location is to be mapped into the coordinate space defined by the transformation currently in effect. When you set this resource to False, the direction is rendered in a uniform coordinate system. The U component of the vector data will be parallel to the X Axis, and the V component will be parallel to the Y Axis with units of equal size in each direction.

Draw order

The StreamlinePlot class allows you specify when the streamlines are drawn in relation to other plot elements of an overlay. You control the drawing order using the stStreamlineDrawOrder resource. There are three drawing phases: the predraw phase, the draw phase, and the postdraw phase. By default, the StreamlinePlot object draws its streamlines during the draw phase. When a streamlineplot is drawn by itself, the drawing order is not important. However, when a streamlineplot is an overlay, you often need to adjust the drawing order to ensure that the features you want to see remain visible.

Annotations

Like all plot objects, a streamlineplot is by default instantiated with a plotmanager to manage overlays and annotations on its behalf. StreamlinePlot enables two PlotManager intrinsic annotations, and also supplies a zero field message label of its own. The enabled PlotManager annotations include TickMark and Title. StreamlinePlot displays tick marks by default. Titles will appear if you set the appropriate title string resource to a non-NULL string value. As with any plot object, you can also add arbitrary user-defined external annotations to a streamlineplot.

Streamline generation resources

StreamlinePlot supplies several resources that influence the way it generates streamlines. The most important of these are stStepSizeF, stMinLineSpacingF, and stLineStartStride.

stStepSizeF specifies the basic step size (in NDC units) that StreamlinePlot uses to calculate the next point on the streamline. Although StreamlinePlot can usually be counted on to come up with a reasonable value for the step size based on the viewport and the size of the data grid, and although it performs some adaptive step sizing based on the field topology, you will find, in general, that setting a smaller step size will result in a more accurate plot. The drawback is that the streamlines will take a bit longer to generate.

stMinLineSpacingF specifies how close in NDC space streamlines are allowed to approach each other before being terminated. StreamlinePlot dynamically calculates a default value for this resource, again based on the viewport size and the number of elements in the data grid. As the value of this resource increases, the streamlines gradually disintegrate into a series of short disconnected lines. Smaller values result in a denser plot with fewer separate lines.

The stLineStartStride resource also affects the streamline density, but not in quite the same way as stMinLineSpacingF. It specifies at how many points within the data grid streamlines may be started. Streamlines always begin at the center of a 'grid box', that is, at a point in data space located equally distant from four points on the grid where vector data values are defined. If you set stLineStartStride to a value greater than 1, some of these potential starting points will not be considered eligible for starting a streamline. For instance, when stLineStartStride is set to its default value of 2, only every other grid box (along each data dimension) will be initially eligible. As the drawing operation progresses, many of these initially eligible boxes become ineligible when a streamline in progress passes through the area defined by the outline of the box.

Streamline style resources

You can set the streamline color using stLineColor and you can set the thickness of the streamline using stLineThicknessF. Setting the streamline thickness also affects the thickness of the lines used to draw the directional arrows.

Directional arrow resources

You can set the length of the lines used to draw each directional arrow using the resource stArrowLengthF.

You can control the directional arrow spacing in two different ways. The resource stArrowStride works in a similar manner to stLineStartStride. It specifies which data grid boxes are eligible for a directional arrow. For example, when stArrowStride has its default value, 2, every second grid box (along each dimension) is eligible for a directional arrow.

The stArrowStride resource works well unless a non-linear transformation is in effect. In such cases, as for instance in many map transformations, the arrows may be reasonably spaced in the lower latitudes, but become unacceptably crowded near the poles. The resource stMinArrowSpacingF was designed to help solve this problem. It allows a directional arrow to be drawn only if at least the NDC distance specified by its value has been added to the streamline since the previous directional arrow.

Zero field annotation

StreamlinePlot provides a zero field annotation that outputs a diagnostic message if you attempt to draw an instance using a vectorfield that contains only zero magnitude vectors or missing values. This annotation also outputs a message if you draw without setting the stVectorFieldData resource to the id of an existing vectorfield. You can individually control the contents of each of these messages as well as whether they should appear at all. The applicable resources are:

for controlling the zero field message, and

for the no data message.

All the remaining resources for the zero field annotation have the prefix stZeroFLabel. These include a complete set of text attribute resources, as well as resources for controlling position according to the locational conventions of the PlotManager Location Control Model.

Status

1. The support for irregular transformations is at a transistional stage. Eventually, StreamlinePlot will be able to perform transformations from irregular coordinates to linear and logarithmic coordinates without using the overlay mechanism. This will eliminate the need for a switch to the index coordinate system.

Copyright

Copyright 1987-1999 University Corporation for Atmospheric Research
The use of this Software is governed by a License Agreement.

NCAR Graphics is a registered trademark of the University Corporation for Atmospheric Research.

Reference Manual Control Panel

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

$Revision: 1.11 $ $Date: 1999/04/08 21:32:37 $