NCL Website header
NCL Home > Documentation > HLUs > Classes

ScalarField class

The ScalarField class supplies two-dimensional scalar field data.

Synopsis

Header file:		ncarg/hlu/ScalarField.h
Class name:		scalarFieldClass
Class pointer:		NhlscalarFieldClass
Fortran class pointer:	NHLFSCALARFIELDCLASS
Superclass:		DataItem
Composite classes:	<None>

Resources

Local resources

+---------------------------------------------------------------+
|			ScalarField Resource Set		|
|---------------------------------------------------------------|
| NAME				TYPE			ACCESS	|
|	CLASS				DEFAULT			|
|===============================================================|
| sfDataArray                   NhlTGenArray            RCSG    |
|       SfDataArray                     NULL                    |
|---------------------------------------------------------------|
| sfXArray                      NhlTGenArray            RCSG    |
|       SfXArray                        NULL                    |
|---------------------------------------------------------------|
| sfYArray                      NhlTGenArray            RCSG    |
|       SfYArray                        NULL                    |
|---------------------------------------------------------------|
| sfCopyData                    NhlTBoolean             RCSG    |
|       diCopyData                      True                    |
|---------------------------------------------------------------|
| sfExchangeDimensions          NhlTBoolean             RCSG    |
|       SfExchangeDimensions            False                   |
|---------------------------------------------------------------|
| sfMissingValueV               NhlTVariable            RCSG    |
|       SfMissingValueV                 NULL                    |
|---------------------------------------------------------------|
| sfDataMinV                    NhlTVariable            RCSG    |
|       SfDataMinV                      <Dynamic>               |
|---------------------------------------------------------------|
| sfDataMaxV                    NhlTVariable            RCSG    |
|       SfDataMaxV                      <Dynamic>               |
|---------------------------------------------------------------|
| sfXCStartV                    NhlTVariable            RCSG    |
|       SfXCStartV                      <Dynamic>               |
|---------------------------------------------------------------|
| sfXCEndV                      NhlTVariable            RCSG    |
|       SfXCEndV                        <Dynamic>               |
|---------------------------------------------------------------|
| sfYCStartV                    NhlTVariable            RCSG    |
|       SfYCStartV                      <Dynamic>               |
|---------------------------------------------------------------|
| sfYCEndV                      NhlTVariable            RCSG    |
|       SfYCEndV                        <Dynamic>               |
|---------------------------------------------------------------|
| sfXCStartSubsetV              NhlTVariable            RCSG    |
|       SfXCStartSubsetV                <Dynamic>               |
|---------------------------------------------------------------|
| sfXCEndSubsetV                NhlTVariable            RCSG    |
|       SfXCEndSubsetV                  <Dynamic>               |
|---------------------------------------------------------------|
| sfYCStartSubsetV              NhlTVariable            RCSG    |
|       SfYCStartSubsetV                <Dynamic>               |
|---------------------------------------------------------------|
| sfYCEndSubsetV                NhlTVariable            RCSG    |
|       SfYCEndSubsetV                  <Dynamic>               |
|---------------------------------------------------------------|
| sfXCStartIndex                NhlTInteger             RCSG    |
|       SfXCStartIndex                  <Dynamic>               |
|---------------------------------------------------------------|
| sfXCEndIndex                  NhlTInteger             RCSG    |
|       SfXCEndIndex                    <Dynamic>               |
|---------------------------------------------------------------|
| sfYCStartIndex                NhlTInteger             RCSG    |
|       SfYCStartIndex                  <Dynamic>               |
|---------------------------------------------------------------|
| sfYCEndIndex                  NhlTInteger             RCSG    |
|       SfYCEndIndex                    <Dynamic>               |
|---------------------------------------------------------------|
| sfXCActualStartF              NhlTFloat               G       |
|       SfXCActualStartF                <Dynamic>               |
|---------------------------------------------------------------|
| sfXCActualEndF                NhlTFloat               G       |
|       SfXCActualEndF                  <Dynamic>               |
|---------------------------------------------------------------|
| sfYCActualStartF              NhlTFloat               G       |
|       SfYCActualStartF                <Dynamic>               |
|---------------------------------------------------------------|
| sfYCActualEndF                NhlTFloat               G       |
|       SfYCActualEndF                  <Dynamic>               |
|---------------------------------------------------------------|
| sfXCStride                    NhlTInteger             RCSG    |
|       SfXCStride                      1                       |
|---------------------------------------------------------------|
| sfYCStride                    NhlTInteger             RCSG    |
|       SfYCStride                      1                       |
+---------------------------------------------------------------+

Composite resources

The ScalarField object class has no composite class objects.

Superclass resources

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


Description

The ScalarField class encapsulates the functionality required to pass a two-dimensional scalar field data array to a receiving HLU object. One resource must be set to create a ScalarField object: the two-dimensional array resource sfDataArray, which contains a reference to the storage location of the data array in memory.

Along with the actual data, the ScalarField 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. ScalarField 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 sfXCStartV and sfXCEndV for the X Axis or sfYCStartV and sfYCEndV 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, sfXArray or sfYArray. Depending on the number of elements, these arrays either specify the location of data cell centers or cell boundaries along each of the grid axes.

You can also specify a two-dimensional coordinate grid by setting sfXArray and sfYArray with equally-sized 2-D coordinate arrays. In this case, corresponding elements of the X and Y arrays respectively specify data locations along the X and Y data grid axes. If the coordinate arrays are the same size as the data array, they specify grid cell centers; if they have one more element along each dimension than the data array, they specify cell boundaries.

The ScalarField object automatically converts data specified using a variety of numerical types into the NhlTFloat type expected by HLU data receiver objects. The types it currently handles are:

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.

ScalarField can pre-process the array in a number of ways before handing it off to the receiving object. You can exchange the dimensions of the array, effectively turning the data on its side. 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 array to the receiver object, you can pass it any contiguous rectangular subset of the array, specified either by array index or, if not using 2D coordinate arrays, by location in the data coordinate space. Unless the data array dimension sizes also change, ScalarField preserves the subset resource settings when the data array changes. This makes it easy to step through a subset of a time- or level-related series of data arrays. If the dimension sizes change, ScalarField 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 ScalarField 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 (sfXArray and sfYArray) 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 sf...Array to NULL, sf...CStartV to the value of the array's first element, and sf...CEndV to the value of the array's last element.


See also