Data_Array

Synopsis

Stores an array of data.

group Data_Array {
int nvals; /* number of objects */
int veclen; /* vector length of each object */
int id; /* normals, temperature, pressure, coordinates, etc.*/
prim values[nvals][veclen]; /* actual data array */
int+opt null_flag = 0; /* indicates presence of NULL data */
prim+opt null_value; /* value assumed to be NULL data */
prim min => cache(min_array(magnitude(values), null_flag, null_value));
/* min value of data in each array */
prim max => cache(max_array(magnitude(values), null_flag, null_value));
/* max value of data in each array */
prim min_vec[veclen] => cache(min_array(values, null_flag, null_value));
/* min extent of data in each array */
prim max_vec[veclen] => cache(max_array(values, null_flag, null_value));
/* max extent of data in each array */
string+nonotify labels; /* ascii strings for the labels */
string+nonotify units; /* ascii strings for the labels */
};

Description

Data_Arrays are a generalized structure used to store:

•      the numeric data at each node (group Node_Data)

•      the numeric data at each cell (group Cell_Data)

•      the coordinate data in a Grid (group Grid)

More than any other group in the Field data type, the subobjects of Data_Array are redefined by other groups to tailor it to their specific needs.

Subobjects

nvals

An integer that sets the length (row index) of the values array that actually holds the numeric data. It is usually set by the group that is including the Data_Array. Node_Data sets nvals = nnodes. Cell_Data sets nvals = ncells. Grid sets nvals = nnodes.

There is no direct way to get/set nvals because nvals is defined by other groups.

In Node_Data or a structured Grid use FLDget_nnodes.

In Cell_Data use FLDget_ncells.

to get/set this by inheritance.

veclen

An integer that sets the width (column index) of the values array that actually holds the numeric data.

veclen has slightly different meanings, depending upon the group in which the Data_Array is being included.

Node_Data and Cell_Data have some number of components (nnode_data and ncell_data): (a, b, c). There is one Data_Array for each component. However, the components themselves can have subcomponents: (a, [b, c], d). b and c are the subcomponents of the second component. veclen defines the number of subcomponents in this Data_Array component. In the (a, [b, c], d) example, the first and third components' veclen = 1, while the second component's veclen = 2.

In Grids, veclen = nspace, where nspace is the number of coordinates associated with each node. Nodes that occur along a 1D line have one coordinate to specify their location, an X value, and nspace = 1. Nodes that occur in a 2D plane have two coordinates to specify their location, an X and a Y, and nspace = 2. Nodes that occur in 3D space have three coordinates to specify their location, an X, a Y, and a Z, and nspace = 3.

In Node_Data Data_Arrays, use FLDget_node_data_veclen, or FLDset_node_data_comp.

In Cell_Data Data_Arrays, use FLDget_cell_data_veclen.

In Grids, there is no FLD call to get or set veclen explicitly, because the value is going to be inherited from the value for nspace: use FLDget_nspace.

id

An integer that lets you give a numeric id to this Data_Array component, so that some other routine can discover what type of data it holds and treat it in a special way.

This field is primarily used by the Graphics Display Kit routines to flag a component as GD_NORMAL_DATA_ID, GD_COLOR_DATA_ID, GD_RGB_DATA_ID, GD_RADIUS_DATA_ID, or GD_UV_DATA_ID.

• •      See FLDget_node_data_id

values[nvals][veclen]

The array that contains the actual data.

This array starts out with type prim, meaning it has no defined type. The type is specified by the routines that get/set the data array (FLDget/set_node_data).

The data values in the array are stored in "row major" order (standard C and C++ order). Thus, an array declared values[3][2] like this



 

is actually stored in memory like this:



and you would step through each object in the array using offset references like this:


for (n=0; n<nnodes; n++) {
ind_in = n * in_veclen;
for (i=0; i<in_veclen; i++)
out_data[ind_in + i] = in_data[ind_in + i];
}

where nnodes = nvals, in_veclen is the veclen of this component, and in_data and out_data are input and output arrays.

Use the cross-referenced calls to programmatically get/set the values array for:

Node_Data

• •      FLDget_node_data
• •      FLDget_node_data
• Cell_Data
• •      
• Coordinates in Grids
• •      

null_flag

An optional integer. If 0, the Data_Array does not contain null data. Any other value flags the presence of null data. The default is 0 (no null data).

Null data means that some grid points may have no value associated with them; that value is missing. Null data is represented by a special value which does not otherwise occur in the data set; that value's presence at a particular node indicates that the data value for that component at that node is missing. The presence of null data elements is signified by this flag, and the value to use for the missing elements is specified by null_value below. Whenever the null_flag is true, all data values equal to the null_value are treated as missing. Otherwise they are treated as valid values. All supplied AVS/Express methods that deal with Node_Data and the Graphics Display Kit correctly handle null data.

Null data only has meaning in Node_Data and Cell_Data. AVS/Express modules that manipulate only Grids ignore the null_flag and treat the null_value as a coordinate location.

• •      
• •      

null_value

An optional data value, of the same type as the values array, that should be treated as a null value if null_flag is non-zero. See the discussion of null_flag above.

• •      
• •      

min => cache(min_array(magnitude(values), null_flag, null_value));
max => cache(max_array(magnitude(values), null_flag, null_value));

min and max are objects of the same type as the values array. Their value is determined by a function that calculates the magnitude of each subcomponent (veclen column) in the values array. This magnitude value is of interest to people with, for example, vector velocity data. The computation ignores null values. Then, the minimum and maximum of the magnitudes is returned.

The "cache" function means that this computation only occurs when min or max is queried, and the values array has changed. This reduces overhead.

Note that min and max are the minimum and maximum of the magnitude. This implies that veclen > 1. If veclen = 1 (there are no subcomponents--the component is scalar), then these functions return the minimum and maximum value in the component, not the magnitude, and min = min_vec and max = max_vec described below. AVS/Express methods that deal with only scalar data will therefore use min and max even when they might more properly use min_vec and max_vec.

min and max are only meaningful in Node_Data and Cell_Data Data_Arrays; they are meaningless in Grids.

Use the FLDget_node_data_minmax and FLDget_cell_data_minmax FLD library calls to get these values.

It is possible to set these values, even though they are normally determined by a function. Once explicitly set by the programmer, the value will not change until another explicit set is performed. You would set them when, for example, you are reading in a series of Node_Datas as part of an animation, and you want the same colormap range used for each new Node_Data. That is, if 256 is red and 0 is blue in the first Node_Data (min = 0 and max = 256), you do not want the colormap to be automatically rescaled such that 100 is now red and 50 is now blue in the second Node_Data (min = 50 and max = 100).

• •      
• •      

min_vec[veclen] => cache(min_array(values, null_flag, null_value))
max_vec[veclen] => cache(max_array(values, null_flag, null_value));

min_vec and max_vec are arrays of objects of the same type as the values array. Their values are determined by a function that calculates the minimum and maximum value of each subcomponent in the values array.

You frequently need to know what the highest and lowest values in a component are. For example:

•      In Node_Data and Cell_Data, you need to know them in order to scale colormaps to the range of the data. (As noted above, min and max generally serve this purpose in scalar components.)

•      In Grids, they represent the extents of the data in space. For example, that a 3D object exists from -25 to 13 in X, 4 to 100 in Y, and -66 to -7 in Z.

The "cache" function means that this computation only occurs when min_vec and max_vec are queried, and the values array has changed. This reduces overhead.

It is possible to set these values, even though they are normally determined by a function. Once explicitly set by the programmer, the value will not change until another explicit set is performed. You would set them when, for example, you are reading in a series of Node_Datas as part of an animation, and you want the same colormap range used for each new Node_Data. That is, if 256 is red and 0 is blue in the first Node_Data (min = 0 and max = 256), you do not want the colormap rescaled such that 100 is now red and 50 is now blue in the second Node_Data (min = 50 and max = 100). Similarly, in Grids, explicitly setting these values will prevent a series of input Grids from hopping around in the output window as each new Grid's extents change.

Use the following FLD library calls to get/set these values:

Node_Data

• •      
• Cell_Data
• •      
• Grids
• •      

labels

An optional string to hold a name for this component (e.g, "red," "green," "blue," "pressure," "temperature," "x-velocity," and so on).

The supplied AVS/Express macros use these strings to construct menus that let the user select, by name, which component of a field the macro should work on.

labels only have meaning in Node_Data and Cell_Data.

• •      
• •      

units

An optional string to hold a name for this component's units (e.g, "mm," "microns," "inch," and so on).

The Graphics Display Kit does not make use of this units object.

units can have meaning in any context, but are most applicable to Grids.

• •      
• •      
• •      

Files

v/fld/v

See also

Not applicable.

 




---