ScalarField class resource descriptions

sfDataArray
This resource specifies a two-dimensional array containing the data comprising a scalar field. There is no default for this resource, and it must be specified in order to create a ScalarField object successfully. The faster varying dimension (second dimension in C or NCL, first dimension in Fortran) is assumed to align with the X or horizontal axis of a rectangular coordinate system. However, you may exchange the dimensions of the array by appropriately setting the resource, sfExchangeDimensions. Although the ScalarField object always converts the data into type NhlTFloat before passing it along to ScalarField receiver objects, it accepts data arrays containing data of any of the following types:

Default: NULL

sfXArray
The values of the sfXArray resource sequentially represent the X-Axis coordinate of each successive element along the faster-varying dimension of the data array. If sfXArray is set to a non-NULL value, ScalarField checks to ensure first that it has the same number of elements as the X-axis dimension of the data array and second that it is monotonically increasing or descreasing. If the input array fails either of these tests, sfXArray is reset to its default value of NULL, and the data array is treated as if each element were equally spaced along the X Axis between the values of sfXCStartV and sfXCEndV. If the input array is valid, ScalarField replaces the current value of sfXCStartV with the value of the first element of sfXArray, and sfXCEndV with the value of the last element. You can specify sfXArray using a single-dimensioned array of any of the types allowed for sfDataArray.

V4.1 Status Note 1

Default: NULL

sfYArray
The values of the sfYArray resource sequentially represent the Y-Axis coordinate of each successive element along the slower-varying dimension of the data array. If sfYArray is set to a non-NULL value, ScalarField checks to ensure first that it has the same number of elements as the Y-axis dimension of the data array and second that it is monotonically increasing or descreasing. If the input array fails either of these tests, sfYArray is reset to its default value of NULL, and the data array is treated as if each element were equally spaced along the Y Axis between the values of sfYCStartV and sfYCEndV. If the input array is valid, ScalarField replaces the current value of sfYCStartV with the value of the first element of sfYArray, and sfYCEndV with the value of the last element. You can specify sfYArray using a single-dimensioned array of any of the types allowed for sfDataArray.

V4.1 Status Note 1

Default: NULL

sfCopyData
The boolean resource sfCopyData allows you to control whether the ScalarField object always copies the elements of the sfDataArray into a private memory area. If you set sfCopyData False, ScalarField will not copy the sfXArray or the sfYArray data and will try to avoid making a copy of the sfDataArray data. You are then responsible for ensuring that the data memory locations for these arrays are preserved intact for the lifetime of the ScalarField. In return, you save some dynamic memory space. Note that a number of circumstances require ScalarField to copy the data regardless. These include supplying data of any type other than NhlTFloat, requesting that the data dimensions be exchanged, or setting a stride value greater than 1 in either the X or the Y dimension. Also, if you specify a data array subset and one or both of the coordinate array resources (sfXArray and/or sfYArray) is non-NULL, copies are made of the subsetted part of the coordinate array.

Default: True

sfExchangeDimensions
When this boolean resource is set True, ScalarField exchanges the dimensions of the data array. Rows become columns and columns become rows; the fast varying dimension becomes the slow varying dimension and vice-versa. Whenever sfExchangeDimensions is True, ScalarField must copy the data array, regardless of the setting of the sfCopyData resource.

Default: False

sfMissingValueV
If you set sfMissingValueV to a non-NULL value, ScalarField treats occurrences of its value in the data array as representing an undefined value. If left unset, ScalarField assumes that all values in the data array are valid. You may set sfMissingValueV using any of the data types ScalarField accepts for the sfDataArray resource.

Default: NULL

sfDataMinV
By default the ScalarField object sets sfDataMinV to the smallest value in the data array. However, if you set the value of this resource, ScalarField does not process the array to find the minimum value. Instead it assumes that the set value is, in fact, the minimum value. You may set sfDataMinV using any of the data types ScalarField accepts for the sfDataArray resource.

Default: <dynamic>

sfDataMaxV
By default the ScalarField object sets sfDataMaxV to the largest value in the data array. However, if you set the value of this resource, ScalarField does not process the array to find the maximum value. Instead it assumes that the set value is, in fact, the maximum value. You may set sfDataMaxV using any of the data types ScalarField accepts for the sfDataArray resource.

Default: <dynamic>

sfXCStartV
This resource specifies the location along the X Axis of the first element of the faster-varying dimension of the data. If the array resource sfXArray is set and found to be valid, ScalarField overwrites the current value of sfXCStartV, replacing it with the value of the first element of sfXArray. Otherwise, you can set sfXCStartV to any value (presumably meaningful in the context of the your data). If sfXCStartV is greater than sfXCEndV, the direction of the data locations along the X Axis is opposite the direction of the positive X Axis. If sfXArray is NULL or invalid and sfXCStartV is not specified, ScalarField sets sfXCStartV to the value 0. You may set sfXCStartV using any of the data types ScalarField accepts for the sfDataArray resource.

Default: <dynamic>

sfXCEndV
This resource specifies the location along the X Axis of the last element of the faster-varying dimension of the data. If the array resource sfXArray is set and found to be valid, ScalarField overwrites the current value of sfXCEndV, replacing it with the value of the last element of sfXArray. Otherwise, you can set sfXCEndV to any value (presumably meaningful in the context of the your data). If sfXCStartV is greater than sfXCEndV, the direction of the data locations along the X Axis is opposite the direction of the positive X Axis. If sfXArray is NULL or invalid and sfXCEndV is not specified, ScalarField sets sfXCEndV to the size of the faster-varying data dimension minus one. You may set sfXCEndV using any of the data types ScalarField accepts for the sfDataArray resource.

Default: <dynamic>

sfYCStartV
This resource specifies the location along the Y Axis of the first element of the slower-varying dimension of the data. If the array resource sfYArray is set and found to be valid, ScalarField overwrites the current value of sfYCStartV, replacing it with the value of the first element of sfYArray. Otherwise, you can set sfYCStartV to any value (presumably meaningful in the context of the your data). If sfYCStartV is greater than sfYCEndV, the direction of the data locations along the Y Axis is opposite the direction of the positive Y Axis. If sfYArray is NULL or invalid and sfYCStartV is not specified, ScalarField sets sfYCStartV to the value 0. You may set sfYCStartV using any of the data types ScalarField accepts for the sfDataArray resource.

Default: <dynamic>

sfYCEndV
This resource specifies the location along the Y Axis of the last element along the slower-varying dimension of the data. If the array resource sfYArray is set and found to be valid, ScalarField overwrites the current value of sfYCStartV, replacing it with the value of the last element of sfYArray. Otherwise, you can set sfYCStartV to any value (presumably meaningful in the context of the your data). If sfYCStartV is greater than sfYCEndV, the direction of the data locations along the Y Axis is opposite the direction of the positive Y Axis. If sfYArray is NULL or invalid and sfYCEndV is not specified, ScalarField sets sfYCEndV to the size of the slower-varying data dimension minus one. You may set sfYCEndV using any of the data types ScalarField accepts for the sfDataArray resource.

Default: <dynamic>

sfXCStartSubsetV
sfXCStartSubsetV specifies the starting location along the X Axis of a rectangular sub-array of the data array. It should be set to a value within the data coordinate extent as established by the values of sfXCStartV and sfXCEndV. If it is outside the coordinate extent, ScalarField issues a warning and sets it to the value of sfXCStartV. If the values of sfXCStartSubsetV and sfXCEndSubsetV are oppositely directed from the direction established by sfXCStartV and sfXCEndV, ScalarField issues a warning and exchanges their values. When you do not explicitly set a value for sfXCStartSubsetV:

Since the data array grid consists of data located at discrete points, the location specified by sfXCStartSubsetV might well fall between two data points. In this case, ScalarField selects a beginning index for the array subset such that the requested location is included within the subset. Thus the subset array, as delivered to the receiving object, may represent a slightly larger area of the data coordinate space than requested. Get the value of the read-only resource sfXCActualStartF in order to find the exact start of the subset along the X Axis. You may set sfXCSubsetStartV using any of the data types that ScalarField accepts for the sfDataArray resource.

Default: <dynamic>

sfXCEndSubsetV
sfXCEndSubsetV specifies the ending location along the X Axis of a rectangular sub-array of the data array. It should be set to a value within the data coordinate extent as established by the values of sfXCStartV and sfXCEndV. If it is outside the coordinate extent, ScalarField issues a warning and sets it to the value of sfXCEndV. If the values of sfXCStartSubsetV and sfXCEndSubsetV are oppositely directed from the direction established by sfXCStartV and sfXCEndV, ScalarField issues a warning and exchanges their values. When you do not explicitly set a value for sfXCEndSubsetV:

Since the data array grid consists of data located at discrete points, the location specified by sfXCEndSubsetV might well fall between two data points. In this case, ScalarField selects an ending index for the array subset such that the requested location is included within the subset. Thus the subset array, as delivered to the receiving object, may represent a slightly larger area of the data coordinate space than requested. Get the value of the read-only resource sfXCActualEndF in order to find the exact end of the subset along the X Axis. You may set sfXCSubsetEndV using any of the data types that ScalarField accepts for the sfDataArray resource.

Default: <dynamic>

sfYCStartSubsetV
sfYCStartSubsetV specifies the starting location along the Y Axis of a rectangular sub-array of the data array. It should be set to a value within the data coordinate extent as established by the values of sfYCStartV and sfYCEndV. If it is outside the coordinate extent, ScalarField issues a warning and sets it to the value of sfYCStartV. If the values of sfYCStartSubsetV and sfYCEndSubsetV are oppositely directed from the direction established by sfYCStartV and sfYCEndV, ScalarField issues a warning and exchanges their values. When you do not explicitly set a value for sfYCStartSubsetV:

Since the data array grid consists of data located at discrete points, the location specified by sfYCStartSubsetV might well fall between two data points. In this case, ScalarField selects a beginning index for the array subset such that the requested location is included within the subset. Thus the subset array, as delivered to the receiving object, may represent a slightly larger area of the data coordinate space than requested. Get the value of the read-only resource sfYCActualStartF in order to find the exact start of the subset along the Y Axis. You may set sfYCSubsetStartV using any of the data types that ScalarField accepts for the sfDataArray resource.

Default: <dynamic>

sfYCEndSubsetV
sfYCEndSubsetV specifies the ending location along the Y Axis of a rectangular sub-array of the data array. It should be set to a value within the data coordinate extent as established by the values of sfYCStartV and sfYCEndV. If it is outside the coordinate extent, ScalarField issues a warning and sets it to the value of sfYCEndV. If the values of sfYCStartSubsetV and sfYCEndSubsetV are oppositely directed from the direction established by sfYCStartV and sfYCEndV, ScalarField issues a warning and exchanges their values. When you do not explicitly set a value for sfYCEndSubsetV:

Since the data array grid consists of data located at discrete points, the location specified by sfYCEndSubsetV might well fall between two data points. In this case, ScalarField selects an ending index for the array subset such that the requested location is included within the subset. Thus the subset array, as delivered to the receiving object, may represent a slightly larger area of the data coordinate space than requested. Get the value of the read-only resource sfYCActualEndF in order to find the exact end of the subset along the Y Axis. You may set sfYCSubsetEndV using any of the data types that ScalarField accepts for the sfDataArray resource.

Default: <dynamic>

sfXCStartIndex
This resource specifies the smaller of two indexes along the X-Axis dimension bounding a rectangular sub-array of the data array. Explicitly setting sfXCStartSubsetV overrides any value set for sfXCStartIndex and causes it to be set to the array index value associated with the closest data point such that the requested data coordinate location is included within the subset. Otherwise, when you set sfXCStartIndex, the data coordinate value indexed by its value is placed into sfXCStartSubsetV. sfXCStartIndex retains its value when the data array changes, unless the X-Axis dimension size also changes. In this case, assuming neither sfXCStartSubsetV nor sfXCStartIndex is explicitly set at the same time, sfXCStartIndex is set to 0.

Default: <dynamic>

sfXCEndIndex
This resource specifies the larger of two indexes along the X-Axis dimension bounding a rectangular sub-array of the data array. Explicitly setting sfXCEndSubsetV overrides any value set for sfXCEndIndex and causes it to be set to the array index value associated with the closest data point such that the requested data coordinate location is included within the subset. Otherwise, when you set sfXCEndIndex, the data coordinate value indexed by its value is placed into sfXCEndSubsetV. sfXCEndIndex retains its value when the data array changes, unless the X-Axis dimension size also changes. In this case, assuming neither sfXCEndSubsetV nor sfXCEndIndex is explicitly set at the same time, sfXCEndIndex is set to the size of the X-Axis dimension minus one.

Default: <dynamic>

sfYCStartIndex
This resource specifies the smaller of two indexes along the Y-Axis dimension bounding a rectangular sub-array of the data array. Explicitly setting sfYCStartSubsetV overrides any value set for sfYCStartIndex, and causes it to be set to the array index value associated with the closest data point such that the requested data coordinate location is included within the subset. Otherwise, when you set sfYCStartIndex, the data coordinate value indexed by its value is placed into sfYCStartSubsetV. sfYCStartIndex retains its value when the data array changes, unless the Y-Axis dimension size also changes. In this case, assuming neither sfYCStartSubsetV nor sfYCStartIndex is explicitly set at the same time, sfYCStartIndex is set to 0.

Default: <dynamic>

sfYCEndIndex
This resource specifies the larger of two indexes along the Y-Axis dimension bounding a rectangular sub-array of the data array. Explicitly setting sfYCEndSubsetV overrides any value set for sfYCEndIndex, and causes it to be set to the array index value associated with the closest data point such that the requested data coordinate location is included within the subset. Otherwise, when you set sfYCEndIndex, the data coordinate value indexed by its value is placed into sfYCEndSubsetV. sfYCEndIndex retains its value when the data array changes, unless the Y-Axis dimension size also changes. In this case, assuming neither sfYCEndSubsetV nor sfYCEndIndex is explicitly set at the same time, sfYCEndIndex is set to the size of the Y-Axis dimension minus one.

Default: <dynamic>

sfXCActualStartF
When a subset of the data is specified by location in data coordinate space using sfXCStartSubsetV, this location might well fall between two data points. In this case, ScalarField selects a beginning index for the array subset such that the requested location is included within the subset. Thus the subset array, as delivered to the receiving object, may represent a slightly larger area of the data coordinate space than requested. The read-only resource sfXCActualStartF always contains the actual starting location of the data subset along the X Axis.

Default: <dynamic>

sfXCActualEndF
When a subset of the data is specified by location in data coordinate space using sfXCEndSubsetV, this location might well fall between two data points. In this case, ScalarField selects an ending index for the array subset such that the requested location is included within the subset. Thus the subset array, as delivered to the receiving object, may represent a slightly larger area of the data coordinate space than requested. The read-only resource sfXCActualEndF always contains the actual ending location of the data subset along the X Axis.

Default: <dynamic>

sfYCActualStartF
When a subset of the data is specified by location in data coordinate space using sfYCStartSubsetV, this location might well fall between two data points. In this case, ScalarField selects a beginning index for the array subset such that the requested location is included within the subset. Thus the subset array, as delivered to the receiving object, may represent a slightly larger area of the data coordinate space than requested. The read-only resource sfYCActualStartF always contains the actual starting location of the data subset along the Y Axis.

Default: <dynamic>

sfYCActualEndF
When a subset of the data is specified by location in data coordinate space using sfYCEndSubsetV, this location might well fall between two data points. In this case, ScalarField selects an ending index for the array subset such that the requested location is included within the subset. Thus the subset array, as delivered to the receiving object, may represent a slightly larger area of the data coordinate space than requested. The read-only resource sfYCActualEndF always contains the actual ending location of the data subset along the Y Axis.

Default: <dynamic>

sfXCStride
When sfXCStride has a value greater than one, the ScalarField object creates a new array containing only columns indexed along the X dimension by successive multiples (starting with 0) of the sfXCStride value added to the starting index. The starting index is based on the current state of the applicable subsetting resources; it is 0 if no array subsetting is in effect. The resulting array is passed to the receiving plot object.

Note that if ending index minus starting index is not an exact multiple of the sfXCStride value, then the data coordinate range may be reduced slightly.

Default: 1

sfYCStride
When sfYCStride has a value greater than one, the ScalarField object creates a new array containing only rows indexed along the Y dimension by successive multiples (starting with 0) of the sfYCStride value added to the starting index. The starting index is based on the current state of the applicable subsetting resources; it is 0 if no array subsetting is in effect. The resulting array is passed to the receiving plot object.

Note that if ending index minus starting index is not an exact multiple of the sfYCStride value, then the data coordinate range may be reduced slightly.

Default: 1


Reference Manual Control Panel

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


$Revision: 1.15 $ $Date: 1998/08/19 01:09:20 $