NCL Website header
NCL Home > Documentation > HLUs > Classes

VectorField class

The VectorField class supplies two-dimensional vector field data.

Synopsis

Header file:		ncarg/hlu/VectorField.h
Class name:		vectorFieldClass
Class pointer:		NhlvectorFieldClass
Fortran class pointer:	NHLFVECTORFIELDCLASS
Superclass:		DataItem
Composite classes:	<None>

Resources

Local resources

+---------------------------------------------------------------+
|			VectorField Resource Set		|
|---------------------------------------------------------------|
| NAME				TYPE			ACCESS	|
|	CLASS				DEFAULT			|
|===============================================================|
| vfDataArray                   NhlTGenArray            RCSG    |
|       VfDataArray                     NULL                    |
|---------------------------------------------------------------|
| vfUDataArray                  NhlTGenArray            RCSG    |
|       VfUDataArray                    NULL                    |
|---------------------------------------------------------------|
| vfVDataArray                  NhlTGenArray            RCSG    |
|       VfVDataArray                    NULL                    |
|---------------------------------------------------------------|
| vfXArray                      NhlTGenArray            RCSG    |
|       VfXArray                        NULL                    |
|---------------------------------------------------------------|
| vfYArray                      NhlTGenArray            RCSG    |
|       VfYArray                        NULL                    |
|---------------------------------------------------------------|
| vfPolarData                   NhlTBoolean             RCSG    |
|       VfPolarData                     False                   |
|---------------------------------------------------------------|
| vfCopyData                    NhlTBoolean             RCSG    |
|       diCopyData                      True                    |
|---------------------------------------------------------------|
| vfExchangeDimensions          NhlTBoolean             RCSG    |
|       VfExchangeDimensions            False                   |
|---------------------------------------------------------------|
| vfExchangeUVData              NhlTBoolean             RCSG    |
|       VfExchangeUVData                False                   |
|---------------------------------------------------------------|
| vfSingleMissingValue          NhlTBoolean             RCSG    |
|       VfSingleMissingValue            True                    |
|---------------------------------------------------------------|
| vfMissingUValueV              NhlTVariable            RCSG    |
|       VfMissingUValueV                NULL                    |
|---------------------------------------------------------------|
| vfMissingVValueV              NhlTVariable            RCSG    |
|       VfMissingVValueV                NULL                    |
|---------------------------------------------------------------|
| vfMagMinV                     NhlTVariable            RCSG    |
|       VfMagMinV                       <Dynamic>               |
|---------------------------------------------------------------|
| vfMagMaxV                     NhlTVariable            RCSG    |
|       VfMagMaxV                       <Dynamic>               |
|---------------------------------------------------------------|
| vfUMinV                       NhlTVariable            RCSG    |
|       VfUMinV                         <Dynamic>               |
|---------------------------------------------------------------|
| vfUMaxV                       NhlTVariable            RCSG    |
|       VfUMaxV                         <Dynamic>               |
|---------------------------------------------------------------|
| vfVMinV                       NhlTVariable            RCSG    |
|       VfVMinV                         <Dynamic>               |
|---------------------------------------------------------------|
| vfVMaxV                       NhlTVariable            RCSG    |
|       VfVMaxV                         <Dynamic>               |
|---------------------------------------------------------------|
| vfXCStartV                    NhlTVariable            RCSG    |
|       VfXCStartV                      <Dynamic>               |
|---------------------------------------------------------------|
| vfXCEndV                      NhlTVariable            RCSG    |
|       VfXCEndV                        <Dynamic>               |
|---------------------------------------------------------------|
| vfYCStartV                    NhlTVariable            RCSG    |
|       VfYCStartV                      <Dynamic>               |
|---------------------------------------------------------------|
| vfYCEndV                      NhlTVariable            RCSG    |
|       VfYCEndV                        <Dynamic>               |
|---------------------------------------------------------------|
| vfXCStartSubsetV              NhlTVariable            RCSG    |
|       VfXCStartSubsetV                <Dynamic>               |
|---------------------------------------------------------------|
| vfXCEndSubsetV                NhlTVariable            RCSG    |
|       VfXCEndSubsetV                  <Dynamic>               |
|---------------------------------------------------------------|
| vfYCStartSubsetV              NhlTVariable            RCSG    |
|       VfYCStartSubsetV                <Dynamic>               |
|---------------------------------------------------------------|
| vfYCEndSubsetV                NhlTVariable            RCSG    |
|       VfYCEndSubsetV                  <Dynamic>               |
|---------------------------------------------------------------|
| vfXCStartIndex                NhlTInteger             RCSG    |
|       VfXCStartIndex                  <Dynamic>               |
|---------------------------------------------------------------|
| vfXCEndIndex                  NhlTInteger             RCSG    |
|       VfXCEndIndex                    <Dynamic>               |
|---------------------------------------------------------------|
| vfYCStartIndex                NhlTInteger             RCSG    |
|       VfYCStartIndex                  <Dynamic>               |
|---------------------------------------------------------------|
| vfYCEndIndex                  NhlTInteger             RCSG    |
|       VfYCEndIndex                    <Dynamic>               |
|---------------------------------------------------------------|
| vfXCActualStartF              NhlTFloat               RCSG    |
|       VfXCActualStartF                <Dynamic>               |
|---------------------------------------------------------------|
| vfXCActualEndF                NhlTFloat               RCSG    |
|       VfXCActualEndF                  <Dynamic>               |
|---------------------------------------------------------------|
| vfYCActualStartF              NhlTFloat               RCSG    |
|       VfYCActualStartF                <Dynamic>               |
|---------------------------------------------------------------|
| vfYCActualEndF                NhlTFloat               RCSG    |
|       VfYCActualEndF                  <Dynamic>               |
|---------------------------------------------------------------|
| vfXCStride                    NhlTInteger             RCSG    |
|       VfXCStride                      1                       |
|---------------------------------------------------------------|
| vfYCStride                    NhlTInteger             RCSG    |
|       VfYCStride                      1                       |
+---------------------------------------------------------------+

Composite resources

The VectorField object class has no composite class objects.

Superclass resources

Currently, no superclasses of the VectorField object class define any resources.


Description

The VectorField class encapsulates the functionality required to pass two-dimensional vector field data to a receiving plot object. VectorField allows you to package the field data in two different ways: as two separate 2-dimensional arrays or as a single 3-dimensional array with two elements in the slowest varying dimension. To present the data as two 2-D arrays, set the resources vfUDataArray and vfVDataArray. To pass in a single 3-D array, set instead the resource vfDataArray.

Along with the actual data, the VectorField stores and communicates crucial information about the data, such as the value used to represent missing data, and information about the coordinate system in which the data is located. VectorField supports both one and two dimensional coordinate arrays.

One dimensional coordinate axes may be regular or irregularly spaced. To specify a regular grid axis, you simply specify the start and end locations of the data, using vfXCStartV and vfXCEndV for the X Axis or vfYCStartV and vfYCEndV for the Y Axis. The spacing is implicitly determined based on the number of elements along each dimension of the data array. To specify irregularly-spaced coordinates, you set one or both of the coordinate array resources, vfXArray or vfYArray. These arrays explicitly specify the location of each data point along one of the grid axes.

You can also specify a two-dimensional coordinate grid by setting vfXArray and vfYArray with 2-D coordinate arrays equal in size to the last two dimensions of the data arrays. In this case, corresponding elements of the X and Y arrays respectively specify data locations along the X and Y data grid axes.

The VectorField object automatically converts data specified using a variety of numerical types into the NhlTFloat type expected by the receiving plot object. The types it currently handles are as follows:

Many of the supplementary resources may also be set using any of these types. Note that scalar resources capable of accepting any type have the suffix 'V' at the end of their name.

VectorField can pre-process the data arrays in a number of ways before handing them off to the receiving object. You can exchange the array dimensions or the U and V components of the data. You can reverse the direction of the data along either or both axes with suitable specification of the endpoints in data coordinate space. You can also make an overly dense array of data more sparse by specifying an index stride value along either or both the X and the Y dimensions. Note, however, that coordinate reversal and stride indexing are not supported when using 2D coordinate arrays.

Instead of sending the complete arrays to the receiver object, you can pass it any contiguous rectangular subset of the arrays, specified either by array index or, if not using 2D coordinate arrays, by location in the data coordinate space. Unless the data dimension sizes also change, VectorField preserves the subset resource settings when the data change. This makes it easy to step through a subset of a time or level related series of data. If the dimension sizes change, VectorField assumes that the meaning of the data has also changed and that therefore the currently defined subset, besides potentially being out of range, is most likely not meaningful. In this case, the subset resources are reset to include all elements of the data arrays.


Support functions

The VectorField object does not define any support functions, but inherits all the support functions available to its superclass.

Status

1. Note that even if the values of the coordinate array resources (vfXArray and vfYArray) are actually equally spaced, plot objects such as ContourPlot currently use the presence of a coordinate array as a signal that the data are irregularly spaced along the axis in question. In this case the plot object uses an IrregularTransformation object rather than a LogLinTransformation object when plotting the data. The practical consequence, besides a small performance penalty, is that it will then be necessary to overlay the plot on a LogLinPlot if it is desired to make the X Axis logarithmic. If the axis is actually regularly spaced, you can avoid this problem by setting vf...Array to NULL, vf...CStartV to the value of the array's first element, and vf...CEndV to the value of the array's last element.


See also