NCL Home > Documentation > HLUs > Classes

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,
			CurvilinearTransformation,
			SphericalTransformation,
			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>                  |
|---------------------------------------------------------------|
| stScalarFieldData             NhlTInteger             RCSG    |
|       StScalarFieldData               <none>                  |
|---------------------------------------------------------------|
| stStreamlineDrawOrder         NhlTDrawOrder           RCSG    |
|       StStreamlineDrawOrder           "Draw"                  |
|---------------------------------------------------------------|
| stMapDirection                NhlTBoolean             RCSG    |
|       StMapDirection                  True                    |
|---------------------------------------------------------------|
| stLineStartStride             NhlTInteger             RCSG    |
|       StLineStartStride               2                       |
|---------------------------------------------------------------|
| stMinDistanceF                NhlTFloat               RCSG    |
|       StMinDistanceF                  0.0                     |
|---------------------------------------------------------------|
| 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                      |
|---------------------------------------------------------------|
| stArrowStride                 NhlTInteger             RCSG    |
|       StArrowStride                   2                       |
|---------------------------------------------------------------|
| stMinArrowSpacingF            NhlTFloatGenArray       RCSG    |
|       StMinArrowSpacingF              0.0                     |
|---------------------------------------------------------------|
| stArrowLengthF                NhlTFloat               RCSG    |
|       StArrowLengthF                  <dynamic>               |
|---------------------------------------------------------------|
| stLevels                      NhlTFloatGenArray       RCSG    |
|       Levels                          <dynamic>               |
|---------------------------------------------------------------|
| stLevelCount                  NhlTInteger             RCSG    |
|       StLevelCount                    16                      |
|---------------------------------------------------------------|
| stLevelSelectionMode          NhlTLevelSelectionMode  RCSG    |
|       LevelSelectionMode              "AutomaticLevels"       |
|---------------------------------------------------------------|
| stMaxLevelCount               NhlTInteger             RCSG    |
|       MaxLevelCount                   16                      |
|---------------------------------------------------------------|
| stLevelSpacingF               NhlTFloat               RCSG    |
|       LevelSpacingF                   <dynamic>               |
|---------------------------------------------------------------|
| stMinLevelValF                NhlTFloat               RCSG    |
|       MinLevelValF                    <dynamic>               |
|---------------------------------------------------------------|
| stMaxLevelValF                NhlTFloat               RCSG    |
|       MaxLevelValF                    <dynamic>               |
|---------------------------------------------------------------|
| stSpanLevelPalette               NhlTBoolean             RCSG    |
|       StSpanLevelPalette                 True                    |
|---------------------------------------------------------------|
| stLevelPalette                  NhlTColorDefinitionGenArray  RCSG    |
|       StLevelPalette                    <None>               |
|---------------------------------------------------------------|
| stLevelColors                 NhlTColorIndexGenArray  RCSG    |
|       StLevelColors                   <dynamic>               |
|---------------------------------------------------------------|
| stUseScalarArray              NhlTBoolean             RCSG    |
|       StUseScalarArray                False                   |
|---------------------------------------------------------------|
| stScalarMissingValColor       NhlTColorIndex          RCSG    |
|       StScalarMissingValColor         "Foreground"            |
|---------------------------------------------------------------|
| stMonoLineColor               NhlTBoolean             RCSG    |
|       StMonoLineColor                 True                    |
|---------------------------------------------------------------|
| 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                     |
|---------------------------------------------------------------|
| stExplicitLabelBarLabelsOn    NhlTBoolean             RCSG    |
|       StExplicitLabelBarLabelsOn      False                   |
|---------------------------------------------------------------|
| stLabelBarEndLabelsOn         NhlTBoolean             RCSG    |
|       StLabelBarEndLabelsOn           False                   |
|---------------------------------------------------------------|
| stLabelFormat                 NhlTString              RCSG    |
|       NumberFormat                    "*+^sg"                 |
+---------------------------------------------------------------+

Data specific resources

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

Composite resources

Transformation resources

Transformation class resources specify the extent, direction and grid type of the data coordinate system. The Transformation class is the superclass of all classes used to perform data transformations, and you can access all its resources. However, note that StreamlinePlot intercepts its 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.
  • trGridType
    trGridType is forced to LogLin if vfXArray and vfYArray have NULL values in the VectorField object. It is forced to Irregular if vfXArray and/or vfYArray contain 1D coordinate arrays. If vfXArray and vfYArray contain 2D coordinate arrays, trGridType defaults to Spherical but the user can choose to set it to Curvilinear.

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 to handle its transformations if either of the VectorField array resources vfXArray and/or vfYArray are set with one-dimensional arrays, 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

CurvilinearTransformation resources

StreamlinePlot uses the CurvilinearTransformation to handle its transformations if the VectorField array resources vfXArray and vfYArray are set with two-dimensional arrays and the Transformation class resource trGridType is set to Curvilinear. The CurvilinearTransformation class has no user-accessible resources.

SphericalTransformation resources

StreamlinePlot uses the SphericalTransformation to handle its transformations if the VectorField array resources vfXArray and vfYArray are set with two-dimensional arrays and the Transformation class resource trGridType is set to Spherical.. The SphericalTransformation class has no user-accessible resources.

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: Except for Legend, 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: The StreamlinePlot class itself modifies the access and behavior of a number of LabelBar resources.
Additional modifications to LabelBar resources
The StreamlinePlot class disables a number of LabelBar resources, since it sets them automatically based on the current values of certain relevant StreamlinePlot resources. The disabled resources include: In addition, the StreamlinePlot class intercepts certain LabelBar resources, 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. The streamlines may be progressively colored based upon the interpolated magnitude or other associated scalar value at each step-wise location of the streamline. It supports title, tick mark, and labelbar 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.

If you want to color the streamlines based on data other than the vector magnitudes, you must set the boolean resource stUseScalarArray True and also supply the streamlineplot with a ScalarField object. You do this by setting the resource stScalarFieldData using the id of an existing scalarfield. Currently, StreamlinePlot requires that the scalarfield have the same number of elements along each dimension (after subsetting and striding is performed) as does each component of the vectorfield. It also assumes that the data coordinate extents of the scalarfield match those of the vectorfield and ignores any explicitly set scalarfield coordinate extent values.

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 also supports topologically rectangular grids defined using 2D coordinate arrays.

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. If the grid is defined using 2D coordinate arrays, StreamlinePlot instantiates either the CurvilinearTransformation or the SphericalTransformation to handle the transformations.

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 and they are not set with 2D arrays, 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).

Use of the CurvilinearTransformation object

If both the VectorField coordinate array resources vfXArray and vfYArray are set using 2D coordinate arrays and the Transformation class resource trGridType is set to Curvilinear StreamlinePlot uses a CurvilinearTransformation object. As with the IrregularTransformation you cannot set the coordinate range outside, the range of the data. Also, since X and Y coordinate locations both vary along the grid edges, tickmarks are disabled. In order to place the the data in context, you need to overlay the streamlineplot on another plot such as a mapplot.

Use of the SphericalTransformation object

If both the VectorField coordinate array resources vfXArray and vfYArray are set using 2D coordinate arrays and the Transformation class resource trGridType is set to Spherical StreamlinePlot uses a CurvilinearTransformation object. As with the IrregularTransformation you cannot set the coordinate range outside the range of the data. Also, since X and Y coordinate locations both vary along the grid edges, tickmarks are disabled. In order to place the the data in context, you need to overlay the streamlineplot on another plot such as a mapplot.

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 three PlotManager intrinsic annotations, and also supplies a zero field message label of its own. The enabled PlotManager annotations include TickMark, Title, and LabelBar. StreamlinePlot displays tick marks by default. Titles will appear if you set the appropriate title string resource to a non-NULL string value. The LabelBar, which provides a key to the color scheme used for progressively colored streamlines, only appears if you set pmLabelBarDisplayMode appropriately. 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, stLineStartStride, and stMinDistanceF, and stMinLineSpacingF.

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.

The resources stLineStartStride and stMinDistanceF offer alternate ways to limit the number of streamlines started in order to control streamline density. 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. As a streamline is generated the grid boxes through which it passes are marked as ineligible for starting a new streamline. The stLineStartStride resource sets a stride value that determines which grid boxes are initially 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.

stLineStartStride works well for controlling density when the transformation from data space to NDC space is linear. However, when the transformation is non-linear, as with many map projections, a more uniform and legible plot may be achieved with the stMinDistanceF resource. This resource specifies a minimum distance in NDC space that must separate neighboring grid boxes for both to be initially eligible for starting a streamline. When this resource is set to a value greater than 0.0, StreamlinePlot calculates the NDC location of each grid point, and then based on the minimum distance value records the initially eligible grid boxes.

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.

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.

Streamline color

If stMonoLineColor is set True, you control the color used to render the streamlines by setting the resource stLineColor. If you set stMonoLineColor False StreamlinePlot draws each streamline with multiple colors, based on the interpolated magnitude or other associated scalar value at each step-wise location of the streamline. The array resource stLevelColors specifies the color indexes to use for multi-colored rendering.

Selecting levels

In order to support multi-colored streamlines, StreamlinePlot uses an array of level values to subdivide the range of scalars on which the coloring is based. By default, the levels apply to the range of vector magnitudes. However, if stUseScalarArray is set True and a scalarfield has been provided, the levels will apply to the range of the scalarfield data. The level array resource stLevels is specified in the same way as the ContourPlot resource cnLevels.

By appropriately setting the stLevelSelectionMode resource, you can choose from four level selection modes to set up the stLevels array. The default mode, AutomaticLevels, is easy to use. It selects a "nice" spacing starting from the smallest relatively round number greater than the minimum data value, such that the number of levels is as close as possible to, but less than, the value of the resource stMaxLevelCount. EqualSpacedLevels mode defines exactly stMaxLevelCount levels spaced evenly from the data minimum value to the data maximum value. In ManualLevels mode, you set the maximum and minimum levels using the resources stMinLevelValF and stMaxLevelValF with a spacing defined by the resource stLevelSpacingF. Finally, Explicit mode allows you to define the level values yourself by setting the array resource stLevels. The ManualLevels and ExplicitLevels modes have the advantage that they are independent of the maximum and minimum values of the particular dataset you are plotting, and therefore can be used to enforce consistency in the plots of a series of related datasets. ExplicitLevels is the only mode that allows you to establish variably spaced levels.

Once you have established the levels, you can retrieve the number of levels actually used by getting the value of the read-only resource stLevelCount.

Streamline line width

You can set the thickness of the streamlines using stLineThicknessF. Setting the streamline thickness also affects the thickness of the lines used to draw the directional arrows.

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 transitional 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.

See also