| |
|
|
|
2
AVS/Express Field data type
This chapter describes the AVS/Express field data type and how to read field data into it using the Read_Field module.
- Introduction, Section 2.1
- Field data hierarchy, Section 2.2
- Field types, Section 2.3
- Using the Read_Field module, Section 2.4
- Field format overview, Section 2.5
- Data type structure - fld.v, Section 2.6
In general, the AVS/Express Object Manager makes no assumptions about the data it manages. However, to provide the optimized set of visualization tools included in the Data Visualization Kit, a set of visualization-specific data structures are defined. These structures are collectively known as a Field.
The AVS/Express Field data type is implemented in V (which means that it can be modified and extended) and provides one unified data schema that is capable of representing:
- the numeric data and uniform, rectilinear, and irregular coordinate grids commonly found in scientific, imaging, and finite difference applications
- the unstructured cell data commonly found in finite element analysis. applications
- the geometric data used to model objects
This chapter describes the AVS/Express field format and how to read in data in that format. However, you are not limited to data in the field format, as the next section discusses.
You do not have to use the AVS/Express field data type, as defined, in order to use AVS/Express. Instead, you can:
- extend or modify the AVS/Express field data type to suit your data structures, or
- define your own data schema using V, or
- use the OMX mechanism to generate V equivalents of your C or C++ data structures.
However, other parts of AVS/Express do require the AVS/Express Field data type - or at least part of the field data type - as input. These include:
- Data Visualization Kit - Macros, Base Modules, the FLD library, and most of the UTIL visualization library
- Data display components of the Graphics Display Kit - All viewers including SimpleViewer and Viewer
If you do extend or modify the Field data type, create your own data type, or rely on V generated arbitrary data structures defined using a programming language, then you will need to either:
- translate your data into the AVS/Express Field data format before using one of the AVS/Express supplied components, or
- modify the AVS/Express supplied component to accept your data type
To import AVS field, image, volume, geometry, or UCD data into AVS/Express, use the Read_xxxx data input macros described in Chapter 5, "Macros.
You have several options for importing your data into AVS/Express, including:
- using mapper modules to convert arrays of data into Fields
- importing your data from a file with the Data Visualization Kit file objects
- if you have the AVS Compatibility Kit, using AVS-supplied or public domain AVS conversion macros to read various input data formats
Fields consist of two major components:
- Mesh - A geometric description that specifies where and how the data is
located and organized in space- Data - Scalar or vector values defined at specific domain locations
A simplified version of the basic field data type hierarchy is shown in the figure below.
The Mesh is a geometric description that specifies where and how the data is located and organized in space. The mesh has two subcomponents:
- Grid - Defines the location of nodes in space
- Cells - Specify node (grid) connectivity and the type of interpolation between nodes
The grid defines the location of nodes in space. For example, a grid may specify an irregular field that exists in three dimensions, the number of data nodes it contains, and the X, Y, Z coordinates in space of each node.
The nodes in structured and unstructured meshes are arranged in particular grid structures.
Uniform, rectilinear, and irregular fields all exist as structured meshes. They consist of nodes arrayed on a one-, two-, or three-dimensional hexagonal grid. This is all the information that is required to know how the nodes are organized and connected in space.
Meshes can also be unstructured. In unstructured meshes (where cell data is unstructured), nodes exist in space, but as part of a higher organization called a Cell. The nodes are connected together in a certain order to form point, line, triangle, quadrilateral, tetrahedral, pyramid, prism, or hexahedral cells. These cells collectively form the field.
Geometries can exist as unstructured meshes. For example, a geometry is one type of unstructured mesh where the nodes are connected together in polygon or polytriangle cells that form the surface of an object.
Cells specify node (grid) connectivity and the type of interpolation between nodes. This is complicated by the fact that unstructured meshes can contain more than one kind of cell. For example, a single object may be composed of a combination of tetrahedral and hexahedral cells. You cannot use the same algorithms to deal with tetrahedral cells and hexahedral cells.
To simplify the cell mechanism, AVS/Express provides a Cell Set abstraction that allows cells with the same properties to be grouped together for separate processing. Unstructured meshes exist as a Cells array of Cell Sets. If all the cells are of one type, then there is one Cell Set. If they are of different types, then there are as many Cell Sets as there are cell types.
Structured meshes exist as one Cell Set and the entire cell mechanism can therefore be ignored.
The Data subobject holds any numeric data associated with each node in the mesh. This Node_Data could be the density values from an MRI scan, the RGB values of a color image, the X, Y, and Z velocity values from a fluid flow simulation, the displacement values in a finite element analysis model, or stock prices over time in a financial model. If the field represents geometric data (here called a "geometry"), the numeric data could be the polygon colors, normals, or the uvws required for texture mapping.
Because finite element analysis problems often contain data at both the nodes of a cell (temperature, pressure) and for the cell as a whole (stress), an additional subelement, Cell_Data, is available that can store data for the cell as a unit.
AVS/Express field data is classified into different types, according to the type of mesh and the associated specification of computational-to-physical space mapping used. The four types are (from least- to most-structured):
- Unstructured - Has a general collection of nodes or cells with no implicit connectivity. Cell connectivity and node coordinates are explicitly defined in the mesh.
- Structured (or irregular) - Connectivity is assumed according to some rule (usually array order). No explicit connectivity information is supplied.
- Rectilinear - Subclass of the Structured Field type that assumes one particular connectivity rule. No explicit connectivity information is supplied.
- Uniform - Subclass of the Structured Field type that makes even more specific assumptions about connectivity than the Rectilinear Field; consequently even less positional information is explicitly supplied.
Unstructured fields are used to represent data that is not arranged in any regular pattern. None of the required spatial or connectivity information can be implied from the shape of the grid, and must therefore be provided explicitly in the field.
The following data must be supplied to specify an unstructured field:
- number of grid locations, or nodes (nnodes)
- number of coordinates specifying each node (nspace)
- coordinates defining the nodes (coodinates.values)
- Cell Set(s) to provide connectivity information (a cell set type, ncell_sets, ncells, and node_connect_list).
An array of ten nodes ((x,y) or (x,y,z)) would be required to specify the unstructured field shown in the previous diagram.
Like unstructured fields, structured fields (sometimes known as irregular fields) require that you provide all coordinate information. However, the nodes that compose the mesh in a structured field are arranged in a fashion regular enough that they can be specified in a 2- or 3-dimensional array. Connectivity information for the grid can be inferred from the array structure and therefore need not be supplied explicitly.
The following data must be supplied to completely specify a structured field:
- the number of coordinates specifying each node (nspace)
- the number of elements in the dims array (ndim)
- an array of computational dimensions (dims)
- an array of points defining the grid (coordinates.values).
Note: You do not need to provide a cell set since the structure of the grid can be determined from the array structure. Also note that the structured field specification defines two additional components, npoints and points, that are not used in structured fields but that are inherited and used by the rectilinear and uniform field subclasses can inherit these components.
In structured fields, coordinate space might not have the same number of dimensions as computational space. Each data element in computational space is explicitly mapped to a point in coordinate space. This allows for a variety of mappings. For example, a 3D computational space can be mapped to a 3D coordinate space in which each cell has curvilinear bounds. A 1D computational space can be mapped to a 2D or 3D coordinate space that does not have cells, but rather consists of a set of scattered points with a data element at each point.
The following figure illustrates various computational to coordinate space mappings for structured fields. In the figure, ndims is the dimensionality of the data array (a 1D array of numbers, a 2D array of numbers, a 3D array of numbers). The space is the line (1D), plane (2D), or volume (3D) within which the data points exist. To establish the mapping between the two, each element of the data array must have an explicit X(1D), XY(2D), or XYZ(3D) location in space defined for it.
An array of ten nodes and a second array defining the dimensions of the nodes (5,2) would be required to specify the structured field shown in the following diagram.
An array of coordinates for 18 nodes and another array specifying the dimensions of the nodes, {6,3}, would be required to specify the example unstructured field shown in the following diagram.
In a rectilinear field, each array index in each dimension of the computational space is mapped to a physical coordinate. This produces a physical space whose axes are orthogonal, but the spacing among the elements is not necessarily equal. This means that less explicit spatial information than for either unstructured or structured fields is required since more of the geometry can be implied.
An explicit mapping between the computational and physical spaces can therefore be established by specifying coordinate data for all of the points along each axis. The position of any data point can then be inferred from its location in the array. Note that in a rectilinear field, lines connecting the lattice points are always mutually orthogonal-all the angles are right angles.
The following data must be supplied to completely specify a structured field:
- the number of coordinates specifying each node (nspace)
- the number of computational dimensions (ndim)
- an array of computational dimensions (dims)
- an array defining the extents of the field in space (points)
The coordinates of six x-locations and five y-locations are required to specify the example rectilinear field shown in the previous diagram.
A uniform field has no computational-to-physical space mapping between data elements. Only the minima and maxima in each coordinate dimension are specified - the position of any data point is inferred from its location in the array and the dimensions of the mesh.
Uniform fields are therefore the most efficient to store of the four possible field types, but the least flexible in terms of the shapes of data set that they can represent.
Uniform fields have the same specification requirements as rectilinear fields but have a smaller points array (which specifies only the two points that represent the maximum and minimum bounds of the grid). To completely specify a uniform field, you must specify:
- the number of coordinates specifying each node (nspace)
- the number of computational dimensions (ndim)
- an array of computational dimensions (dims)
- an array defining the extents of the field in space (points)
Only the coordinates of two points - the (0,0) object of the array and the
(i_max, j_max) object of the array are required to specify the following uniform field.The Read_Field module reads an AVS/Express field data structure from a disk file into a network.
The read_field module can read files in the native AVS field file format into an AVS/Express network. An AVS field file (suffix .fld) has the following components:
- an ASCII header that describes the field
- two separator characters that divide the ASCII header from the data and coordinate information
- a binary area containing the data and coordinate information
The write_field module creates files in this format.
The ASCII header contains a series of text lines, each of which is either a comment or a TOKEN=VALUE pair. For example, the following header defines a field of type "field 2D 4-vector byte", which is the AVS/Express image format:
# AVS field file
#
ndim=2 # number of computational dimensions
dim1=512
dim2=480
nspace=2 # number of physical dimensions
veclen=4
data=byte
field=uniform
The first two lines are comments, indicated by the # character. Note that the first line of the header must begin as follows:
In this example, comments also occur at the end of the third and sixth lines. Any characters following (and including) # in a header line are ignored. Comments are not required.
The ASCII header must be followed by two formfeed characters (that is, Ctrl-L, octal 14, decimal 12, hex 0C), in order to separate it from the binary area. This scheme allows you use the more(1) shell command to examine the header. When more stops at the formfeeds, press "q" to quit. This avoids the problem of the binary data garbling the screen.
The binary area contains both data values and coordinate mapping data. This section describes the components of the binary by looking at how the size of this area is calculated.
The size of the data values section of the binary area is calculated by taking the product of:
- all the dimensions of the field: (dim1 * dim1 * ... dim1),
- the number of data values per field element: (dim1), and
- the byte size of the primitive data type: (dim1).
Thus, the size (in bytes) of the data values section is:
( dim1 * dim1 * ... dim1 * dim1 * dim1 )
- All the data values for a field element are stored together.
- The first array index varies most quickly (FORTRAN-style).
The size of the coordinate mapping data section of the binary area depends on the field type: uniform, rectilinear, or irregular.
- For uniform fields, coordinate mapping data contains two values for each physical dimension (n-space) of the data, one associated with the minimum extent of the data, and the other associated with the maximum extent.
The minimum and maximum extent values in the coordinate binary area are copies of the min_ext and max_ext values in the field data structure, except when the field has been cropped, downsized, or interpolated. Then the field data structure contains the original field's min_ext and max_ext values, while the coordinate section of the binary area contains the minimum and maximum extent of the subsetted data. Mapper modules can use this additional extent information to properly locate their geometric representation of the subsetted data in world coordinate space. The extents in the coordinate binary area are stored in this order: minimum x, maximum x, minimum y, maximum y, minimum z..., and so on.
The size of the coordinate mapping data section for a uniform field is simply:
( 2 * nspace ) * sizeof(float)
Note: sizeof(float) refers to the size, in bytes, of a single-precision floating-point number. On 32-bit architectures, this will be 4.
- For rectilinear fields, there is one coordinate for each array index in each dimension of computational space. Thus, the size of the coordinates area is:
( dim1 + dim2 ... + dimx ) * sizeof(float)
All of the X-coordinates are stored together, at the beginning of the coordinates area. Following these are all the Y-coordinates, and so on.
- For irregular fields, each field element is mapped to a point in nspace-dimensional physical space. Thus, the size of the coordinates area is:
( dim1 * dim2 ... * dimx ) * nspace * sizeof(float)
As with rectilinear fields, all of the X-coordinates are stored together, at the beginning of the coordinates area. Following these are all the Y-coordinates, and so on.
The following ASCII header describes a volume (3D uniform field) with a single byte of data for each field element. This format might be used to represent CAT scan data, where all of the 2D slices are equally spaced:
# AVS field file
ndim=3 # number of dimensions in the field
dim1=64 # dimension of axis 1
dim2=64 # dimension of axis 2
dim3=64 # dimension of axis 3
nspace=3 # number of physical coordinates per point
veclen=1 # number of components at each point
data=byte # data type (byte, integer, float, double)
field=uniform # field type (uniform, rectilinear, irregular)
In the binary area, the data area occupies this amount of space:
(64 * 64 * 64) * 1 * 1 = 262,144 bytes
The coordinates area occupies (2 * 4) * 3 bytes. The total binary area occupies 262,168 bytes.
The following ASCII header describes a volume (3D uniform field) whose data for each field element is a 3D vector of single-precision values. This format might be used to represent a volume of data from a sampling device where the samples are not equally spaced.
# AVS field file
ndim=3 # number of dimensions in the field
dim1=27 # dimension of axis 1
dim2=25 # dimension of axis 2
dim3=32 # dimension of axis 3
nspace=3 # number of physical coordinates per point
veclen=3 # number of components at each point
data=float # data type (byte, integer, float, double)
field=uniform # field type (uniform, rectilinear, irregular)
In the binary area, the data area occupies this amount of space:
(27 * 25 * 32) * 4 * 3 = 259,200 bytes
The coordinates area occupies (2 * 4) * 3 bytes. The total binary area occupies 259,224 bytes.
The following ASCII header describes an irregular volume (3D irregular field) with one single-precision value for each field element. The binary area includes an (X,Y,Z) coordinate triple for each field element, indicating the corresponding point in physical space. This format might be used to represent velocity data from a simulation of fluid flow around a curved object (for example, an airplane wing). Note that the data type is specified as xdr_float. This means that the data file is written in Sun Microsystems' external data representation (XDR) format. This allows for transporation of field files between machines of dissimilation data storage architectures ("big-endian" vs "little-endian"). When using Read_Field, if Auto is selected on the control panel, Read_Field will look at the data specification. If it is simply float, (or integer, or double), it will assume the file is written in the system's native format. If it is xdr_integer, xdr_float, or xdr_double it will translate the XDR format into its native format. If Portable is selected rather than Auto, it will always assume the file is written in XDR format.
# AVS field file
ndim=3 # number of dimensions in the field
dim1=40 # dimension of axis 1
dim2=32 # dimension of axis 2
dim3=32 # dimension of axis 3
nspace=3 # number of physical coordinates per point
veclen=1 # number of components at each point
data=xdr_float # data type (byte, integer, float, double)
field=irregular # field type (uniform, rectilinear, irregular)
In the binary area, the data area occupies this amount of space:
(40 * 32 * 32) * 4 * 1 = 163,840 bytes
The coordinates area occupies this amount of space:
(40 * 32 * 32) * 4 * 3 = 491,520 bytes
As the example below shows, the ASCII description file contains a series of text lines that define the AVS/Express field to construct. Each line is either:
- a comment
- a required line in the form token=value
- an optional line in the form token=value
- a variable or coord parsing specification
The following ASCII description file imports 3D curvilinear data with a vector of values at each point into an AVS/Express field of type "field 3D 3-vector irregular float". This type of data often occurs in computational fluid dynamics applications. The data and coordinate information are in separate files, both of which were written as straight binary data. Both files happen to have a serial organization. In the data file, all of vector element 1's values appear, then all of vector element 2's, then all of vector element 3's values. In the X, Y, Z coordinate file, all the X coordinate values appear, then all the Y's, then all the Z's.
Each line's meaning is explained in detail below.
# AVS field file the string "# AVS/Express" must be the first five
# characters in the file.
#
# When a '#' character appears in a line,
# the rest of the line is a comment
#
ndim=3 # REQUIRED - the number of dimensions
dim1=40 # REQUIRED - dimension of axis 1
dim2=32 # REQUIRED - dimension of axis 2
dim3=32 # REQUIRED - dimension of axis 3
nspace=3 # REQUIRED - coordinates per point
veclen=3 # REQUIRED - components at each point
data=float # REQUIRED - data type
field=irregular # REQUIRED - field type
min_ext=-1.0 -1.0 -1.0 # OPTIONAL - coordinate space extent
max_ext=1.0 1.0 1.0 # OPTIONAL - coordinate space extent
label=x-velocity # OPTIONAL - label for variable 1
label=y-velocity # OPTIONAL - label for variable 2
label=z-velocity # OPTIONAL - label for variable 3
unit=miles-per-second # OPTIONAL - unit label for variable 1
unit=miles-per-second # OPTIONAL - unit label for variable 2
unit=miles-per-second # OPTIONAL - unit label for variable 3
min_val=-2.1 -0.3 -3.7 # OPTIONAL - minimum data values
max_val=5.79 3.54 1.50 # OPTIONAL - maximum data values
#
# For each coordinate X, Y, and Z: data reading instructions
#
coord 1 file=/jetdata/wing.bin filetype=binary skip=12
coord 2 file=/jetdata/wing.bin filetype=binary skip=163852
coord 3 file=/jetdata/wing.bin filetype=binary skip=327692
#
# For each value in the vector: data reading instructions
#
variable 1 file=/jetdata/wdata.bin filetype=binary skip=28
variable 2 file=/jetdata/wdata.bin filetype=binary skip=163868
variable 3 file=/jetdata/wdata.bin filetype=binary skip=327708
Any characters following (and including) # in a header line are ignored.
NOTE: The first five characters in the ASCII description file must be "# AVS/Express" or Read_Field will not recognize the file as valid.
The example above shows all of the required TOKEN=VALUE token names: an ASCII description file that is missing one or more of these lines causes Read_Field to generate an error. Required TOKEN=VALUE pairs are stored in the AVS/Express field that Read_Field produces as output.
Optional TOKEN=VALUE pairs are stored in the output AVS/Express field as well, if they are provided. min_ext and max_ext are stored in the output AVS/Express field even if they are not specified, as Read_Field calculates them if they are not provided.
The variable and coord lines are not stored in the output AVS/Express field. They are only instructions to Read_Field.
With the exception of filenames, ASCII description file specifications are not case-sensitive. You can surround the = character with any amount of white space (including none at all). For example, "dim2 = 32", "DIM 2 =32", and "Dim2=32" are all equivalent.
Below is a complete description of all of the tokens recognized by the Read_Field parser:
The number of computational dimensions in the field. For an image, ndim = 2. For a volume, ndim = 3.
dim1 = value (required)
dim2 = value (required, depending on total number of dimensions)
dim3 = value (required, depending on total number of dimensions)
...
The dimension size of each axis (the array bound for each dimension of the computational array). The number of dimx entries must match the value of ndim. For instance, if you specify a 3D computational space field (ndim=3), you must specify the length of the X dimension (dim1), the length of the Y dimension (dim2), and the length of the Z dimension (dim3). Note that counting is 1-based, not 0-based. If you have scatter data (ndim=1) in 3D coordinate space (nspace=3), there will be only dim1=value.
The dimensionality of the physical space that corresponds to the computational space (number of physical coordinates per field element).
In many cases, the values of nspace and ndim are the same - the physical and computational spaces have the same dimensionality. But you might embed a 2D computational field in 3D physical space to define a manifold; or you might embed a 1D computational field in 3D physical space to define an arbitrary set of points (a "scatter").
The number of data values for each field element. All the data values must be of the same primitive type (for example, integer), so that the collection of values is conceptually a veclen-dimensional vector. If veclen=1, the single data value is, effectively, a scalar. Thus, the term scalar field is often used to describe such a field.
The primitive data type of all the data values. xdr_integer, sdr_float, and xdr_double may also be specified. If Auto is selected on input, read_field will examine the data= field. If the specification is unqualified, it assumes the file is written in the native format for the platform ("big-endian" vs "little-endian"). If it is xdr_value, it will read it as Sun MicroSystems' external data format (XDR) and translate it into the native format. If Portable is selected, it assumes XDR format no matter what is placed here.
The field type. A uniform field has no computational-to-physical space mapping. The field implicitly takes its mapping from the organization of the computational array of field elements.
For a rectilinear field, each array index in each dimension of the computational space is mapped to a physical coordinate. This produces a physical space whose axes are orthogonal, but the spacing among elements is not necessarily equal.
For an irregular field, there is no restriction on the correspondence between computational space and physical space. Each element in the computational space is assigned its own physical coordinates.
min_ext = x-value [y-value] [z-value]... (optional)
max_ext = x-value [y-value] [z-value]... (optional)
The minimum and maximum coordinate value that any member data point occupies in space, for each axis in the data. If you do not supply this value, Read_Field calculates it and stores it in the output AVS/Express field data structure. This value can be used by modules downstream to, for example, size the volume bounds drawn around the data in the Geometry Viewer or put minimum and maximum values on coordinate parameter manipulator dials (probe). Values can be separated by blanks and/or commas.
If you do not know the extents, don't guess-let Read_Field calculate them. Most downstream modules use whatever values are supplied, without checking their validity. If the wrong numbers are specified, incorrect results will be computed.
Allows you to title the individual elements in a vector of values. These labels are stored in the output AVS/Express field data structure. Subsequent modules that work on the individual vector elements (for example, extract scalar) will label their parameter widgets with the strings provided here instead of the default "Channel 0, Channel 1...", and so on. You can either use one label line as shown here, or separate label lines as shown in the example above. In either case, the labels are applied to the elements of the vector in the order encountered. You can also label single scalar values, though downstream modules may ignore such a label. Any alphanumeric string is acceptable. You can separate strings with blanks and/or commas.
Allows you to specify a string that describes the unit of measurement for each vector element. You can either use one unit line as shown here, or separate unit lines as shown in the example above. In either case, the unit specifications are applied to the elements of the vector in the order encountered. You can also specify the unit for a single scalar value, though downstream modules may ignore it. Any alphanumeric string is acceptable. You can separate strings with blanks and/or commas.
For each data element in a scalar or vector field, allows you to specify the minimum and maximum data values. These values are stored in the output AVS/Express field data structure. This is used by subsequent modules that need to normalize the data. Values can be separated by blanks and/or commas.
Read_Field does not calculate these values if you do not supply them (unlike min_ext and max_ext). If you do not know these values, don't guess-just leave these optional lines out. In this case, the write field module can, at your instruction, compute these values when it creates an AVS field file. Most downstream modules use whatever values are supplied, without checking their validity. If the wrong numbers are specified, incorrect results will be computed.
variable n file=filespec filetype=type skip=n offset=m stride=p
coord n file=filespec filetype=type skip=n offset=m stride=p
(Both of these specifications must be on a single line. There is no support for continuation characters.) variable specifies where to find data information, its type, and how to read it. coord specifies where to find coordinate information, its type, and how to read it. It is used when the data is rectilinear or irregular.
The individual parameters are interpreted as follows:
- n - An integer value that specifies which element of a data vector or which coordinate (1 for x, 2 for y, 3 for z, and so on) the subsequent read instructions apply to. n does not default to 1 and must be specified.
- file = filespec - The name of the file containing the data or coordinates. The filespec can be an absolute full pathname to a file, or it can be a filespec relative to the directory that contains the field ASCII header. For example, an absolute pathname might be /home/myuserid/experiment/data. In a relative pathname specification, if the ASCII file of field parsing instructions exists in the file /home/myuserid/experiment/readit.fld and the data and coordinates file are in the subdirectory /home/myuserid/experiment/data, you can name these files as xdata/xyzs and data/values. The advantage of this second approach is that you can move the directories containing your data around without having to change the contents of the ASCII parsing instruction file.
- filetype = ascii - ascii means that the data or coordinate information is in an ASCII file. In ASCII files, float data can be specified in either real (0.1) or scientific notation (1.00000e-01) format interchangeably.
- filetype = unformatted - the file is written in FORTRAN unformatted format. (FORTRAN unformatted data is binary data with additional words written at the beginning and end of each data block stating the number of bytes or words in the data block.) In general, Read_Field can read unformatted files where all variables of one type (for example, all the X coordinates) were output as one "record" in a single write statement. This is usually the case.
- filetype = binary - the file is written in straight binary format, such as that produced by UNIX output routines, write and fwrite.
See the warning on binary compatibility among different hardware platforms in Section 5.74, Read_Field [page 5-178].
In each case, Read_Field will use the data type specified in the earlier data={byte,float,integer,double} statement when it interprets the file.
For binary or unformatted files, skip specifies the number of bytes to skip over before starting to read the data.
There are two motivations for skip. First, data files often include header information irrelevant to the AVS/Express field data type. Second, if the file contains, for example, all X data values, then all Y data values, skip provides a way to space across the irrelevant data to the correct starting point.
You can only use skip once at the start of the file. There is no way to skip, read, stride, then skip again.
You must simply know what value to use for skip based on your knowledge of the software that produced the original data file, the number of data elements, and the type (byte, float, double, integer, etc.)
- offset = m - offset is only relevant to ASCII files; it is ignored for binary and unformatted files. offset specifies the number of columns to space over before starting to read the first datum. (The stride specification determines how subsequent data are read.) Hence, to read the fourth column of numbers in an ASCII file, use offset=3.
In ASCII files, columns must be separated by one or more blank characters. Commas, semicolons, TAB characters, and so on, are not recognized as delimiters. If necessary, edit ASCII files to meet this restriction.
offset defaults to 0 (the first column, no columns spaced over).
- stride = p - stride assumes you are "standing on" the data value just read. stride specifies how many "strides" must be taken to get to the next data value. In ASCII files, stride means stride forward p delimited items. In binary and unformatted files, stride means stride forward p * the size of the data type (byte, float, double, integer). In a file where the data or coordinate values are sequential, one after the other, the stride would be 1. Note that this presumes homogeneous data in binary and unformatted files - double-precision values could not be intermixed with single precision values.
The stride value will be repeatedly used until the number of data items indicated by the product of the dimensions (for example, dim1 * dim2 * dim3) have been read.
Here are some skip, offset, and stride examples for ASCII data. "A's" are vector component 1; "B's" are vector component 2.
To read A: skip=1, offset=3, stride=5 To read B: skip=1, offset=4, stride=5
To read A: skip=0, offset=0, stride=1 To read B: skip=3, offset=0, stride=1
To read A: skip=0, offset=0, stride=2 To read B: skip=0, offset=1, stride=2
TEMP1=A1 TEMP2=A2 TEMP3=A3 TEMP4=A4
TEMP5=A5 TEMP6=A6 TEMP7=A7 TEMP8=A8
PRESS=B1 PRESS=B2 PRESS=B3 PRESS=B4
PRESS=B5 PRESS=B6 PRESS=B7 PRESS=B8
Read_Field cannot read this file until the data labels and equal signs are edited out.
You have some 3-dimensional, curvilinear data that projects the amount and location of wood that will be eaten after five years by a colony of termites. The data is in one ASCII file, decay.dat, as a long sequential, numbered list of 1250 consumed-wood values that looks like this:
The coordinates that correspond to the data values are in a separate ASCII file, loc.dat, that looks like this:
LOC,1,0,0.2500000,0.0000000e+00,1.105255,0.0000000e+00;
LOC,2,0,0.2500000,0.0000000e+00,1.000000,0.0000000e+00;
LOC,3,0,0.5000000,0.0000000e+00,1.552552,0.0000000e+00;
LOC,4,0,0.5000000,0.0000000e+00,1.442042,0.0000000e+00;
LOC,5,0,0.5000000,0.0000000e+00,1.331531,0.0000000e+00;
...
In the data file, the second column represents the data. In the coordinate file, the fourth through sixth columns are the x, y, and z coordinates, respectively.
First, to read this data, you must use a text editor to globally edit out the commas and semi-colons, changing them to spaces. The files now look like:
1 1002.707
2 1443.971
...
LOC 1 0 0.2500000 0.0000000e+00 1.105255 0.0000000e+00
LOC 2 0 0.2500000 0.0000000e+00 1.000000 0.0000000e+00
...
The following ASCII description file, decay.fld, would import the data into AVS/Express field format:
# AVS field file
#
# Termite Decay after Five Years
#
ndim=3 # number of dimensions in the field
dim1=25 # dimension of axis 1
dim2 =10 # dimension of axis 2
dim3 =5 # dimension of axis 3
nspace=3 # number of physical coordinates
veclen=1 # number of elements at each point
data=float # data type (byte, integer, float, double)
field=irregular # field type (uniform, rectilinear, irregular)
coord 1 file=/Termite/loc.dat filetype=ascii offset=3 stride=7
coord 2 file=/Termite/loc.dat filetype=ascii offset=4 stride=7
coord 3 file=/Termite/loc.dat filetype=ascii offset=5 stride=7
variable 1 file=/Temite/decay.dat filetype=ascii offset=1 stride=2
The following ASCII description file specifies how to convert the volume data in the file /usr/avs/data/volume/hydrogen.dat into an AVS/Express field. hydrogen.dat is a series of binary byte values that represent the probability of finding an electron at various locations around a hydrogen nucleus. The first three bytes in the file give the X, Y, and Z dimensions of the data-however, this information is not part of the actual data and must be skipped over. You could examine these three bytes and determine what to use for the dimensions in the ASCII description file. Thereafter, it is just a matter of reading successive bytes. offset is not used because this is not an ASCII file. stride is allowed to default to 1.
# AVS field file
ndim=3 # number of dimensions in the field
dim1=64 # dimension of axis 1
dim2=64 # dimension of axis 2
dim3=64 # dimension of axis 3
nspace=3 # number of physical coordinates per point
veclen=1 # number of components at each point
data=byte # data type (byte, integer, float, double)
field=uniform # field type (uniform, rectilinear, irregular)
variable 1 file=/usr/avs/data/volume/hydrogen.dat filetype=binary skip=3
This ASCII description file specifies how to use Read_Field to convert the image data in /usr/avs/data/image/mandrill.x into an AVS/Express field. The first two words in mandrill.x are 32-bit integers that specify the horizontal and vertical dimensions of the image. This information must be skipped over - you must supply it in the ASCII description file. Thereafter, mandrill.x is a succession of 32-bit straight binary words, one word per pixel. However, in AVS/Express, each of these words is considered to be a vector of four bytes. The first byte is the "alpha" (or "transparency") value for the pixel, and the second through fourth bytes are the red, green, and blue values for each pixel. Thus, this whole file is treated as a series of binary bytes.
# AVS field file
#
ndim = 2 # number of dimensions in the field
nspace=2 # number of physical coordinates
dim1=500 # dimension of axis 1
dim2=480 # dimension of axis 2
veclen=4 # number of components at each point
data=byte # data type (byte, integer, float, double)
field=uniform # field type (uniform, rectilinear, irregular)
label = alpha, red, green, blue # labels the vector elements
variable 1 file=/usr/avs/data/image/mandrill.x filetype=binary skip=8 stride=4
variable 2 file=/usr/avs/data/image/mandrill.x filetype=binary skip=9 stride=4
variable 3 file=/usr/avs/data/image/mandrill.x filetype=binary skip=10 stride=4
variable 4 file=/usr/avs/data/image/mandrill.x filetype=binary skip=11 stride=4
This ASCII description file reads a FORTRAN unformatted ARC 3D dataset. The file is 34x34x34, made up of floating point numbers. It is irregular; therefore there are both computational and coordinate data in two separate files. The vector length is 6. The data file is written as a 24-byte header that must be skipped over followed by all vector 1 values, all vector 2 values, and so on. The coordinate file is written as a 12-byte header (a full word for each of the X, Y, and Z dimensions) followed by all X cooordinates, all Y coordinates, then all Z coordinates. Using a relative file specification the filenames will be interpreted relative to the directory of this ASCII description file.
# AVS field file
# to read an Arc 3D file that's 34x34x34z
ndim = 3
dim1 = 34
dim2 = 34
dim3 = 34
nspace = 3
veclen = 6
data = float
field = irregular
#
coord 1 file=for003.dat filetype=unformatted skip=20 stride=1
coord 2 file=for003.dat filetype=unformatted skip=157236 stride=1
coord 3 file=for003.dat filetype=unformatted skip=314452 stride=1
#
variable 1 file=for004.dat filetype=unformatted skip=32 stride=1
variable 2 file=for004.dat filetype=unformatted skip=157248 stride=1
variable 3 file=for004.dat filetype=unformatted skip=314464 stride=1
variable 4 file=for004.dat filetype=unformatted skip=471680 stride=1
variable 5 file=for004.dat filetype=unformatted skip=628896 stride=1
variable 6 file=for004.dat filetype=unformatted skip=786112 stride=1
Given that the coordinate file header is 12 bytes, why is the skip value 20? It is 20 because Read_Field must be directed to skip over the one word FORTRAN unformatted record header, and the one word FORTRAN unformatted record trailer (12+4+4=20). The same 20 bytes must be added to the skip value for coords 2 and 3. Similarly, the data file's 24-byte header must have eight bytes added to it for a total of 32. Read_Field correctly deals with the remaining "invisible" FORTRAN unformatted record header and trailer words in the remainder of the file, provided that all values pertaining to a dimensions (X, Y, or Z) and/or all values pertaining to a vector (for example, all x-momentums) were written as one record. It will also work if the records were written as repeating groups (for example, X, Y, Z; X, Y, Z; X, Y, Z; and so on) or (vec1, vec2, vec3, vec4, vec5, vec6: repeat). It will not work if the output was generated as "first half of X's; second half of X's", since the intermediate FORTRAN formatting words will throw off its strides.
A field is a generalization of the familiar array structure. Whereas each element of an array has a single data value (for example, byte or integer), each element of an AVS/Express field can have a list of data values. Thus, a field can be described as an n-dimensional array with an m-dimensional vector of values at each array location (where n and m are any integers). Moreover, the field can include coordinate data, so that each field element is mapped to a real-world location.
The AVS/Express field datatype has the following components:
The number of computational dimensions in the field. For an image, ndim = 2. For a volume, ndim = 3.
The dimension size of each axis (the array bound for each dimension of the computational array). The number of dimx entries is based on the value of ndim.
The dimensionality of the physical space that corresponds to the computational space (number of physical coordinates per field element).
The number of data values for each field element. All the data values must be of the same primitive type (for example, integer), so that the collection of values is conceptually a veclen-dimensional vector. If veclen=1, the single data value is, effectively, a scalar. Thus, the term scalar field is often used to describe such a field.
The primitive data type of all the data values: must be one of byte, integer, single, or double.
The field type, one of uniform, rectilinear, or irregular.
The minimum and maximum coordinate value that any member data point occupies in space, for each axis in the data.
The minimum and maximum data value in the field.
A title for each of the individual elements in a vector of values.
A string that describes the unit of measurement for each vector element.
The data values for the field.
The computational-to-physical space mapping coordinate data values appropriate for the mesh type.
The AVS/Express Field data type is defined in v/fld.v, which, like other V files, is interpreted by the AVS/Express Object Manager at runtime. The Field data type is defined hierarchically. The fld.v file is organized into the following functional pieces. Each of these is described in detail in the remaining sections.
- The functions defined at the beginning of the file are not central to understanding it. They just specify utility functions used by later objects.
- General Field Subobjects. These define the basic structural objects of the Field data subtype. Data_Array, Grid, Cell_Set, Cells, Node_Data, and Cell_Data are the primary subobjects. Note how Grid, Node_Data, and Cell_Data use the already-defined Data_Array in their own definitions.
Mesh, Data, and Field combine these basic structural objects into higher abstractions.
- Field Subclasses. These subobjects tailor the definitions of the basic structural objects to specific data types. They both give values to existing subobjects defined earlier, and add subobjects necessary to complete the definition.
- Field Subtypes. These subobjects are a convenient way to set specific properties of the basic structural objects. By merging, for example, Grid+Space3, you turn a Grid into a 3D Grid. Data_Array+Int turns a Data_Array into an integer Data_Array.
- Cells. These subobjects set the specific properties of the unstructured mesh cell defined originally in Cell_Set.
There are two fundamental ideas to keep in mind:
- You use only the parts of the hierarchy necessary to represent your data. If, for example, you have a uniform field, then all you need is Node_Data and a minimal version of a Grid called Grid_Unif. These are already combined for you into a field subclass called Field_Unif. Cell_Data and Cells can be ignored.
- Any object can appear 0, 1, or n times. For example, you could represent time-series data as one Mesh, with many Datas - a different Data for each time step in the sequence.
|
| |
|
|
|
Copyright © 2001 Advanced Visual Systems
Inc.
All rights reserved.
