OpenDX - Documentation
Full Contents QuickStart Guide User's Guide User's Reference
Previous Page Next Page Table of Contents Partial Table of Contents Index Search

B.2 Data Explorer Native Files

The Data Explorer native file format encapsulates the Data Explorer data model on disk (or on standard output as the result of an external conversion program). This file format is comprehensive and flexible in that it can represent any of the Objects created in Data Explorer. Thus, any Object can be exported at any point. A data file in this format can be imported into a Data Explorer session by specifying "dx" as the value of the format parameter for the Import module. For more information, see Import in IBM Visualization Data Explorer User's Reference.

Overview of the Native File Format

A Data Explorer file consists of a header section followed by an optional data section. The header section consists of a textual description of a collection of Objects. The data section contains the Array Object data, either as text or in binary, and is referred to by the header section. A header section can refer to Objects and data either in the current file or in other files.

Figure 83 shows data imbedded in its header. Another file cannot refer to data in this file because there is no specified data section. However, header sections in this file can refer to data sections in other files. This method is sometimes more convenient when creating data files with simple programs.

Figure 84 shows a header section referring to a data section in another file. The header refers to the data using the data file name and an offset location (in bytes from the beginning of the data section) in the file.

Figure 85 shows a header section and data section in the same file. The header refers to the data section using a byte offset, relative to the start of the data section.

Figure 83. Data Imbedded in a Header Section


Figure dinhd not
displayed.


Figure 84. Header Referring to Data in Another File


Figure hdrdat not
displayed.


Figure 85. Header and Data in the Same File


Figure hand not
displayed.


These configurations can be used in conjunction with each other. For example, a file can contain both a header and data and can refer to data both in the same file and in another file. A file can also have only a header and refer to data in either a data-only file or in a file that contains both a header and data. This flexibility allows you to construct a header that points to data in existing files, and lets you view and edit the header information (if necessary), using standard tools.

The following examples illustrate some of the ways you can import data using the Data Explorer native file format. You may wish to refer to the full specification of the syntax (see "Syntax of the Native File Format").

Examples

The basic way to create a data file is to first define the Arrays, or components, contained in a Field and to then describe how to collect the components together. To define a higher level structure, such as a series, first define the components, then the Fields, and then how to collect the Fields to make a series. The examples in this section illustrate the process.

In the first six examples, the data Objects can be viewed by the script shown here. Other scripts are shown with the later examples.

data = Import("filename.dx", format = "dx");
connections = ShowConnections(data);
connections = AutoColor(connections);
tubes = Tube(connections, 0.08);
camera = AutoCamera(tubes, "off diagonal");
image = Render(tubes, camera);
Display(image);

Note: For Figure 86 and Figure 87, the argument "off front" is used instead of "off diagonal."

Simply substitute the file name of the data file for filename in the Import statement. For information about how to use the Data Explorer script language, see Chapter 10. "Data Explorer Scripting Language".

Example 1. A Regular Grid

The following example illustrates the basic Objects of the data model, and shows how to imbed data as text in the header section. The Objects and data describe a regular grid. This file is found in /usr/local/dx/samples/data/regular.dx. Figure 86 shows the resulting structure. The axes diagram in the lower right corner of the figure indicates the orientation of the axes. This orientation applies to all subsequent examples as well.

Note that the positions are considered to increment in the order "last index varies fastest" when matching data to positions. For example, for this simple 4 x 2 x 3 grid, the order of the positions is [x0y0z0], [x0y0z1], [x0y0z2], [x0y1z0], and so on. This is because the deltas are specified in the order .x, y, z, so z is the last index. If the data was stored in the order [x0y0z0], [x1y0z0] ..., then the order of the delta clauses would be reversed, and the counts would be specified as 3 2 4.

When using the gridconnections keyword, it is not necessary to specify the "element type" or "ref" attribute, as these will automatically be set for you.

# This example describes a regular grid
# object 1 is the regular positions.
  The grid is 4 in x by 2 in y by 3 in z.  The origin is
# at [0 0 0], and the deltas are 1 in the first and third
# dimensions, and 2 in the second dimension
object 1 class gridpositions counts 4 2 3
origin  0   0   0
delta   1   0   0
delta   0   2   0
delta   0   0   1
# object 2 is the regular connections
object 2 class gridconnections counts 4 2 3
attribute "element type" string "cubes"
attribute "ref" string "positions"
# object 3 is the data, which is in a one-to-one correspondence with
# the positions ("dep" on positions).
# The data are matched to the positions in the order
# "last index varies fastest", i.e. (x0, y0, z0), (x0, y0, z1),
# (x0, y0, z2), (x0, y1, z0), etc.
object 3 class array type float rank 0 items 24 data follows
  1     3.4  5  2
  3.4   5.1  0.3  4.5
  1     2.3  4.1  2.1
  6     8   9.1  2.3
  4.5   5   3.0  4.3
  1.2   1.2  3.0  3.2
attribute "dep" string "positions"
# A field is created with three components: "positions", "connections",
# and "data"
object "regular positions regular connections" class field
component "positions" value 1
component "connections" value 2
component "data" value 3
end

Figure 86. Regular Grid Example. The argument "off front" has been substituted for "off diagonal" in the script used to generate this figure (see "Examples").

Figure reggrid not
displayed.


Example 2. A Regular Skewed Grid

This example is similar to the previous one. However, the "positions" component is changed slightly so that the Objects and data describe a regular skewed grid. This file is found in /usr/local/dx/samples/data/regularskewed.dx. Figure 87 shows the resulting structure.

# This example describes a regular grid, where the axes are
# non-orthogonal
# object 1 is the regular positions, where the deltas is non-orthogonal
object 1 class gridpositions counts 4 2 3
origin   0  0  0
delta    1  0.2  0
delta    0  2  0
delta    0  0  1
# object 2 is the regular connections
object 2 class gridconnections counts 4 2 3
# object 3 is the data, which is in a one-to-one correspondence with the
# positions ("dep" on positions)
object 3 class array type float rank 0 items 24 data follows
  1  3.4  5  2
  3.4  5.1  0.3  4.5
  1  2.3  4.1  2.1
  6  8  9.1  2.3
  4.5  5  3.0  4.3
  1.2  1.2  3.0  3.2
attribute "dep" string "positions"
# the field contains three components: "positions", "connections", and
# "data"
object "regular positions regular connections" class field
component "positions" value 1
component "connections" value 2
component "data" value 3
end

Figure 87. Regular Skewed Grid Example. The argument "off front" has been substituted for "off diagonal" in the script used to generate this figure (see "Examples").

Figure skwdgrid not
displayed.


Example 3. A Warped Regular Grid

Figure 88. Warped Regular Grid Example

Figure wrpdgrid not
displayed.


The example file (in /usr/local/dx/samples/data/deformedregular.dx) defines a warped regular grid and shows how to imbed data as text in a header section. The values of the "positions" component are irregular and must be enumerated. Figure 88 shows the resulting structure.

# The irregular, 3 dimensional positions
object 1 class array type float rank 1 shape 3 items 24 data follows

  0          0      0
  0          0      1
  0          0      2
  0          2      0
  0          2      1
  0          2      2
  1   0.841471   0
  1   0.841471   1
  1   0.841471   2
  1   2.841471   0
  1   2.841471   1
  1   2.841471   2
  2  0.9092974  0
  2  0.9092974  1
  2  0.9092974  2
  2   2.909297   0
  2   2.909297   1
  2   2.909297   2
  3    0.14112    0
  3    0.14112    1
  3    0.14112    2
  3    2.14112    0
  3    2.14112    1
  3    2.14112    2
# The regular connections
object 2 class gridconnections counts 4 2 3
# The data, in a one-to-one correspondence with the positions
object 3 class array type float rank 0 items 24 data follows
  1       3.4     5
  2       3.4     5.1
  0.3     4.5     1
  2.3     4.1     2.1
  6       8       9.1
  2.3     4.5     5
  3       4.3     1.2
  1.2     3       3.2
attribute "dep" string "positions"
# The field, with three components: "positions", "connections", and
# "data". The field is given the name "irreg positions regular connections".
object "irreg positions regular connections" class field
component "positions" value 1
component "connections" value 2
component "data" value 3
end

The positions are joined in the order "last index varies fastest," with the connections specified as 4 x 2 × 3: the first 3 positions are joined in a line, as are those in each set of 3 following. Then the first 6 positions are joined as a set of 2 quadrilaterals, as are the next 6 and so on (see Figure 88).

Example 4. An Irregular Grid

This example file (in /usr/local/dx/samples/data/irregular.dx) defines an irregular grid and shows how to imbed data as text in a header section. The values of the "positions" and "connections" components are irregular and must be enumerated. See Figure 89.

Figure 89. Irregular Grid Example

Figure irggrid not
displayed.


# The irregular positions, which are 24 3-dimensional points.
object 1 class array type float rank 1 shape 3 items 24 data follows
  0          0   0
  0          0   1
  0          0   2
  0          2   0
  0          2   1
  0          2   2
  1   0.841471   0
  1   0.841471   1
  1   0.841471   2
  1   2.841471   0
  1   2.841471   1
  1   2.841471   2
  2  0.9092974  0
  2  0.9092974  1
  2  0.9092974  2
  2   2.909297   0
  2   2.909297   1
  2   2.909297   2
  3    0.14112    0
  3    0.14112    1
  3    0.14112    2
  3    2.14112    0
  3    2.14112    1
  3    2.14112  2
# The irregular connections, which are 30 tetrahedra
object 2 class array type int rank 1 shape 4 items 30 data follows
  10  3  4  1
  3  10  9  6
  10  1  7  6
  6  1  3  10
  6  1  0  3
  10  1  4  5
  5  1  8  10
  8  5  2  1
  10  8  7  1
  5  8  11  10
  15  6  9  10
  10  6  13  15
  13  10  7  6
  15  13  12  6
  10  13  16  15
  17  10  11  8
  10  17  16  13
  17  8  14  13
  13  8  10  17
  13  8  7  10
  22  15  16  13
  15  22  21  18
  22  13  19  18
  18  13  15  22
  18  13  12  15
  22  13  16  17
  17  13  20  22
  20  17  14  13
  22  20  19  13
  17  20  23  22
attribute "element type" string "tetrahedra"
attribute "ref" string "positions"
# The data, which is in a one-to-one correspondence with the positions
object 3 class array type float rank 0 items 24 data follows
   1  3.4  5  2  3.4
   5.1  0.3  4.5  1  2.3
   4.1  2.1  6  8  9.1
   2.3  4.5  5  3  4.3
   1.2  1.2  3  3.2
attribute "dep" string "positions"
# the field, with three components: "positions", "connections", and
# "data"
object "irregular positions irregular connections" class field
component "positions" value 1
component "connections" value 2
component "data" value 3
end

Example 5. Header and Data in Separate Files

The following example uses a header file that contains no data. Instead, it refers to another file, irregirreg2.bin, that contains the data in binary format. This example contains the same information as "Example 4. An Irregular Grid", but the data is stored in a file separate from the header. If you use this sample header file in a script, the results are the same as in Figure 89. This file can be found in /usr/local/dx/samples/data/irregirreg2.dx.

object 1 class array type float rank 1 shape 3 items 24 msb binary
data file irregirreg2.bin,0
attribute "dep" string "positions"
object 2 class array type int rank 1 shape 4 items 30 msb binary
data file irregirreg2.bin,288
attribute "element type" string "tetrahedra"
attribute "ref" string "positions"
object 3 class array type float rank 0 items 24 msb binary
data file irregirreg2.bin,768
attribute "dep" string "positions"
object "irreg positions irreg connections binary file" class field
component "positions" value 1
component "connections" value 2
component "data" value 3
end

Often, you can use this method to point to existing data files. To do this, your header file must:

For example, suppose you have an existing data file written in the IEEE floating point format. It has the following characteristics:

Given all these conditions, the following Data Explorer header file imports the data (substituting the data file name for data_file_name):

object 1 class gridpositions counts 100 100 15
origin  50  100  10
delta   1  0  0
delta   0  1  0
delta   0  0  2
object 2 class gridconnections counts 100 100 15
attribute "element type" string "cubes"
attribute "ref" string "positions"
# It skips the first three bytes before reading the data values
object 3 class array type float rank 0 items 150000
ieee data file data_file_name,3
object "field" class field
component "positions" value 1
component "connections" value 2
component "data" value 3
end

Example 6. Product Arrays

The following examples show how to use Product Arrays to define positions that are composed of products of arrays. Such positions may be regular in one or more dimensions and irregular in one or more dimensions. The resulting product array is found as a product of all possible combinations of the terms comprising the Array.

The first data file defines data that has irregular positions in the xy plane but regular spacing in the z dimension. This file can be found in /usr/local/dx/samples/data/product1.dx. Figure 90 shows the resulting image.

# define a set of irregular points in the xy plane
object 1 class array type float rank 1 shape 3 items 8 data follows
      0.0  0.0  0.0
      0.0  1.1  0.0
      1.0  0.2  0.0
      1.1  1.3  0.0
      2.2  0.2  0.0
      2.5  1.1  0.0
      3.5  0.1  0.0
      3.4  1.0  0.0
# define a set of regular points in the z direction
object 2 class regulararray count 3
origin  0.0  0.0  0.0
delta   0.0  0.0  1.0
# create a product array of the irregular points in the xy plane and
# the regular points in the z direction
object 3 class product array
  term 1
  term 2
# create regular cube connections
object 4 class gridconnections counts 4 2 3
# the data component
object 5 class array type float rank 0 items 24 data follows
  1.0  2.1  2.0  1.0  4.5  6.7  8.1  2.0
 -0.9 -0.8  1.0  1.2  1.3  0.1  0.3  3.0
  1.2  3.2  4.1  0.9  2.0  1.0 -0.9  2.0
object "field" class field
 component "positions" 3
 component "connections" 4
 component "data" 5
end

Figure 90. Product Array Example with Irregular Points in the XY Plane

Figure prodarxy not
displayed.


The next data file defines a regular grid that is regular in the xy plane but has irregular positions in the z direction. This file can be found in /usr/local/dx/samples/data/product2.dx. Figure 91 shows the resulting image.
# define a set of regular points in the xy plane
object 1 class gridpositions 4 2 1
# define a set of irregular points in the z direction
object 2 class array type float rank 1 shape 3 items 3 data follows
  0.0  0.0  0.0
  0.0  0.0  1.0
  0.0  0.0  3.0
# create a product array of the regular points in the xy plane and
# the irregular points in the z direction
object 3 class product array
  term 1
  term 2
# create regular cube connections
object 4 class gridconnections counts 4 2 3
# the data component
object 5 class array type float rank 0 items 24 data follows
  1.0  2.1  2.0  1.0  4.5  6.7  8.1  2.0
 -0.9 -0.8  1.0  1.2  1.3  0.1  0.3  3.0
  1.2  3.2  4.1  0.9  2.0  1.0 -0.9  2.0
object "field" class field
 component "positions" 3
 component "connections" 4
 component "data" 5
end

Figure 91. Product Array Example with Irregular Points in the Z Direction

Figure prodarz not
displayed.


Example 7. Series

The following file defines the data for a series. It defines three data Array Objects, and then three Field Objects that are associated with the data. The grid definitions are in a separate file (pos_conn.data). This first file can be found in /usr/local/samples/data/regseries.dx.

# This example describes a data series with three member fields
# Object 1 is the data associated with the first frame in the
# series. The data is "dep" positions, or in a one-to-one
# correspondence with positions.
object 1 class array type float rank 1 shape 3 items 18 data follows
  1.0  0.1  0.0
  1.4  0.2  0.0
  1.0  0.0  0.0
  2.2  0.1  0.2
  1.0  0.0  0.0
  2.0  0.0  0.1
  0.9  0.1  0.0
  1.1 -0.4  0.0
  1.0  0.1  0.0
  1.2  0.1  0.1
  0.3  0.0  0.0
  1.0  0.1  0.1
  1.1 -0.4  0.2
  1.1  0.2  0.0
  1.1  0.1  0.0
  1.2  0.1  0.1
  1.1  0.0  0.0
  0.9  0.0  0.1
attribute "dep" string "positions"
# Object 2 is the data associated with the second frame in the series.
object 2 class array type float rank 1 shape 3 items 18 data follows
  0.0  1.1  0.0
  0.1  2.2  0.0
  0.0  1.0  0.0
  0.2  1.1 -0.2
  0.0  0.8  0.0
  0.0  1.9  0.4
  0.1  1.1  0.0
  0.1  1.2  0.0
  0.0  1.1  0.0
  0.2  2.1  0.1
  0.1  1.0  0.0
  0.0  0.8  0.1
  0.1  0.9 -0.2
  0.1  1.2  0.0
  0.1  1.1  0.0
  0.2  1.1 -0.4
  0.1  0.9  0.0
  0.2  0.9  0.1
attribute "dep" string "positions"
# Object 3 is the data associated with the third frame in the series.
object 3 class array type float rank 1 shape 3 items 18 data follows
  0.0  0.1  1.0
  0.1  0.2  1.0
  0.0  0.0  2.0
 -0.2  0.1  2.2
  0.0  0.1  0.9
  0.0  0.2  0.8
 -0.4  0.1  0.9
  0.1  0.2  1.9
  0.0  0.1  0.7
  0.2  0.1  1.1
 -0.1  0.0  2.0
  0.0  0.3  1.1
  0.1  0.1  1.2
 -0.5  0.2  1.0
  0.1  0.1  2.0
  0.2  0.1  1.4
  0.1 -0.3  0.9
  0.2  0.3  1.1
attribute "dep" string "positions"
# Object 4 is the first field in the series. The positions and
# connections are defined by objects 1 and 2 in a separate file,
# "pos_conn.data", and the data is given by object 1 in this file.
object 4 class field
component "positions" value file "pos_conn.data",1
component "connections" value file "pos_conn.data",2
component "data" value 1
# Object 5 is the second field in the series. The positions and
# connections are defined by objects 1 and 2 in a separate file,
# "pos_conn.data" (and are in fact the same positions and connections
# as those of the first field), and the data is given by object 2 in this file.
object 5 class field
component "positions" value file "pos_conn.data",1
component "connections" value file "pos_conn.data",2
component "data" value 2
# Object 6 is the third field in the series. The positions and
# connections are defined by objects 1 and 2 in a separate file,
# "pos_conn.data" (and are in fact the same positions and connections
# as those of the first field), and the data is given by object 3 in
# this file.
object 6 class field
component "positions" value file "pos_conn.data",1
component "connections" value file "pos_conn.data",2
component "data" value 3
# Here we create the series object with three members.
# The members are objects 4, 5, and 6, which we defined above.
# Each has a position tag associated with it (for example a time tag).
object "series" class series
member 0 value 4 position 1.3
member 1 value 5 position 2.5
member 2 value 6 position 4.5
end

The following file defines the grid for this time series. This file can be found in /usr/local/samples/data/pos_conn.data.

object 1 class gridpositions counts 3 2 3
origin  0  0  0
delta   1  0  0
delta   0  2  0
delta   0  0  1
object 2 class gridconnections counts 3 2 3
attribute "element type" string "cubes"
attribute "ref" string "positions"
end

 

 

Example 8. Two-dimensional Grid, Cell-centered Data

This example describes a regular 2-dimensional grid. In this example, unlike other examples presented here, the data are dependent on (in a one-to-one correspondence with) the "connections" rather than the "positions" component. Data Explorer interprets this as implying that the data value within each connection element is the constant given by the corresponding data value. For example, if you used AutoColor and rendered this Field, you would see blocks of constant color.

You can use the following script to render this Object:

  data = Import("/usr/local/samples/data/datadepconnections.dx", format="dx");
  colored = AutoColor(data);
  camera = AutoCamera(colored);
  Display(colored, camera);

The data file is located in /usr/local/samples/data/datadepconnections.dx.

# object 1 is the regular positions. The grid is 4x4. The origin is
# at [0 0], and the deltas are 1 in the first dimension, and
# 2 in the second dimension
object 1 class gridpositions counts 4 4
origin  0  0
delta   1  0
delta   0  2
# object 2 is the regular connections, quads, connecting the positions
object 2 class gridconnections counts 4 4
# object 3 is the data, which are in a one-to-one correspondence with
# the connections ("dep" on connections)
object 3 class array type float rank 0 items 9 data follows
  1  3.4  5  2
  3.2  5.5  0.3  4.5
  4.0
attribute "dep" string "connections"
# A field is created with three components: "positions", "connections",
# and "data"
object "regular positions regular connections" class field
component "positions" value 1
component "connections" value 2
component "data" value 3
end

Example 9. Faces, Loops, and Edges

Faces loops, and edges are used to define polygons. For example, you may wish to define regions of a map with polygons. A positions component identifies the vertices of the polygons, an edges component identifies how to connect positions, a loops component identifies the beginning of each loop by referring to the first edge of the loop, and a faces component identifies which loops make up a face. (A face may have more than one loop if the face has one or more holes in it.)

For more information about faces, loops, and edges, see "Faces, Loops, and Edges Components". Note that some modules do not accept this kind of data. However, the Refine module can be used to convert faces, loops, and edges data to triangles. See Refine in IBM Visualization Data Explorer User's Reference.

The following example describes a simple 2-dimensional data set consisting of five polygons. None of the polygons has holes. To view the data, you can use the following script:

g = Import("FacesLoopsEdges.dx");
c = AutoCamera(g);
colored = AutoColor(g);
Display(colored, c);

The data file is given below, and the resulting connections are illustrated in Figure 92. The data file can be found in /usr/local/dx/samples/data/FacesLoopsEdges.dx.

#
# Example of faces, loops and edges components.
# This example has no holes.
#
#
# Positions array.  These are a list of all the vertices of the object;
#   no particular order is required here.
#
object "position list" class array type float rank 1 shape 2 items 11
data follows
 0.133985  0.812452  # point number 0
 0.375019  0.896258  # point number 1
 0.532733  0.76484   # point number 2
 0.523806  0.404777  # point number 3
 0.300626  0.327407  # point number 4
 0.145888  0.508927  # point number 5
 0.68152   0.851137  # point number 6
 0.815428  0.758889  # point number 7
 0.94636   0.592248  # point number 8
 0.729132  0.416679  # point number 9
 0.535709  0.190524  # point number 10
#
#  Edges array.  This is a list of connected points, by point number.
#  All the edges associated with a particular face need to be listed
#  together. If points 10, 3 and 7 make a triangle, the list is
#  "10 3 7" and the 10 is not repeated. Note that below, for

#  readability, the connected points for each loop are
#  shown together. However line breaks are not significant
#  to the importer, and all of the following numbers could have
#  been on the same line, or one to a line, with the same result.

object "edge list" class array type int rank 0 items 21 data follows
  1  2  6  # edge point index 0
  0  5  4  3  2  1  # edge point index 3
  2  3  9  8  7  6  # edge point index 9
  3 10  9  # edge point index 15
  3  4 10  # edge point index 18
attribute "ref" string "positions"
#  Loops array.  This is a list of connected edges, by edge number.
#  Each number is the edge index of where the next loop starts.
object "loop list" class array type int rank 0 items 5 data follows
  0   # loop index 0
  3   #  1
  9   #  2
 15   #  3
 18   #  4
attribute "ref" string "edges"
#
#  Faces array.  This is list of which loops make faces.  If there are
#   no holes in the faces, this is list of all loops.  If two or more
#   loops actually describe the outside edges and inside hole edges of
#   a face, then this list contains the starting loop numbers of the
#   list of loops making up a face.
#
object "face list" class array type int rank 0 items 5 data follows
 0
 1
 2
 3
 4
attribute "ref" string "loops"
#  data array. Dependent on faces.
#
object "data" class array type float rank 0 items 5 data follows
  0  2.5  1.2  0.4  1.8
attribute "dep" string "faces"
#
#  Field definition to put the arrays together.
#
object "map" class field
  component "positions"  "position list"
  component "edges"  "edge list"
  component "loops"  "loop list"
  component "faces"  "face list"
  component "data"  "data"
end

Figure 92. Example of Faces, Loops, and Edges

Figure flexmp not
displayed.


Example 10. Faces, Loops, and Edges with a Hole

Figure 93. Example of Faces, Loops, and Edges with a Hole

Figure flehole not
displayed.


The following data file is identical to the previous data file except that the third polygon has a square hole in it. The resulting connections are illustrated in Figure 93.

#
# Example of faces, loops and edges components. The third face has a
# square hole in it.
#
#
# Positions array.  These are a list of all the vertices of the object;
#   no particular order is required here.
#
object "position list" class array type float rank 1 shape 2 items 15
data follows
  0.133985  0.812452  # point number 0
  0.375019  0.896258  # point number 1
  0.532733  0.76484   # point number 2
  0.523806  0.404777  # point number 3
  0.300626  0.327407  # point number 4
  0.145888  0.508927  # point number 5
  0.68152   0.851137  # point number 6
  0.815428  0.758889  # point number 7
  0.94636   0.592248  # point number 8
  0.729132  0.416679  # point number 9
  0.535709  0.190524  # point number 10
  0.600000  0.700000  # point number 11
  0.700000  0.700000  # point number 12
  0.700000  0.600000  # point number 13
  0.600000  0.600000  # point number 14
#
#  Edges array.  This is a list of connected points, by point number.  All
#  the edges associated with a particular face need to be listed together.
#  If points 10, 3 and 7 make a triangle, the list is "10 3 7" and the 10
#  is not repeated.  Following a polygon, the front of the polygon is
#  determined by the right-hand rule.
object "edge list" class array type int rank 0 items 25 data follows
  1  2  6  # edge point index 0
  0  5  4  3  2  1  # edge point index 3
  2  3  9  8  7  6  # edge point index 9
 11 12 13 14  # edge point index 15 (hole in third face)
  3 10  9  # edge point index 19
  3  4 10  # edge point index 22
attribute "ref" string "positions"
#
#  Loops array.  This is a list of connected edges, by edge number.  Each
#  number is the edge index of where the next loop starts.
object "loop list" class array type int rank 0 items 6 data follows
  0   # loop index 0
  3   #  1
  9   #  2
 15   #  3
 19   #  4
 22   #  5
attribute "ref" string "edges"
#
#  Faces array.  This is list of which loops make faces.  If there are
#   no holes in the faces, this is list of all loops.  If two or more
#   loops actually describe the outside edges and inside hole edges of
#   a face, then this list contains the starting loop numbers of the
#   list of loops making up a face.
#
object "face list" class array type int rank 0 items 5 data follows
 0
 1
 2
 4
 5
attribute "ref" string "loops"
#
#  data array. Dependent on faces.
#
object "data" class array type float rank 0 items 5 data follows
  0  2.5  1.2  0.4  1.8
attribute "dep" string "faces"
#
#
#  Field definition to put the arrays together.
#
object "map with hole" class field
  component "positions"  "position list"
  component "edges"  "edge list"
  component "loops"  "loop list"
  component "faces"  "face list"
  component "data"  "data"
end

Example 11. Three-dimensional Faces, Loops, and Edges

The following data file describes a faces, loops, and edges Object that exists in 3-dimensional space.

// To view the solid:
g = Import("solid.dx");
a = AutoCamera(g, [0.2 0.1 1.0]);
Display(g, a);
// To look at just the connections:
s = ShowConnections(g);
Display(s, a);

Use the first part of the script to view the solid, and the second part to view only the connections. The data file is given below, and the resulting connections are shown in Figure 94. This data file can be found in /usr/local/samples/data/solid.dx.

# Example of faces, loops and edges components.
#
# Positions array.  These are a list of all the vertices of the object;
#   no particular order is required here.
object "position list" class array type float rank 1 shape 3 items 12
data follows
  5.0  0.0  1.0  # point number 0
  5.0  0.0  5.0  # 1
  3.0  5.0  5.0  # 2
  4.5  0.0  1.5  # 3
  4.5  0.0  4.5  # 4
  3.0  4.0  5.0  # 5
  4.0  0.5  5.0  # 6
  1.5  0.0  1.5  # 7
  1.5  0.0  4.5  # 8
  2.0  0.5  5.0  # 9
  1.0  0.0  5.0  # 10
  1.0  0.0  1.0  # 11
#  Edges array.  This is a list of connected points, by point number.  All
#  the edges associated with a particular face need to be listed together.
#  If points 10, 3 and 7 make a triangle, the list is "10 3 7" and the 10
#  is not repeated.  If there is a hole in the triangle, the edges that
#  describe the hole must be listed right before or right after.
object "edge list" class array type int rank 0 items 23 data follows
  1  0  2  # edge point index 0
 10  1  2  # 3
  9  6  5  # 6
 10  1  0 11  # 9
  8  4  3  7  # 13
 11 10  2  # 17
  0 11  2  # 20
attribute "ref" string "positions"
#  Loops array.  This is a list of connected edges, by edge number.  Each
#   number is the edge index of where the next loop starts.
object "loop list" class array type int rank 0 items 7 data follows

Figure 94. Example of a Surface Using Faces, Edges, and Loops

Figure flesurf not
displayed.


 0  # loop index 0
 3  # 1
 6  # 2
 9  # 3
 13  # 4
 17  # 5
 20  # 6
attribute "ref" string "edges"
#  Faces array.  This is list of which loops make faces.  If there are
#   no holes in the faces, this is list of all loops.  If two or more
#   loops actually describe the outside edges and inside hole edges of
#   a face, then this list contains the starting loop numbers of the
#   list of loops making up a face.
object "face list" class array type int rank 0 items 5 data follows
 0
 1
 3
 5
 6
attribute "ref" string "loops"
#  Colors array.  To get flat shaded surfaces, there should be one color
#    per face, and one normal per face.  These are Red,Green,Blue values
#    between 0 (no color) and 1 (fully saturated).
object "color list" class array type float rank 1 shape 3 items 5 data follows
  0.6  0.3  0.6
  0.8  0.8  0.1
  0.9  0.4  0.9
  0.4  0.8  0.7
  0.8  0.8  0.8
attribute "dep" string "faces"
#  Normals array.
object "normal list" class array type float rank 1 shape 3 items 5
data follows
  0.93   0.37   0.0
  0.0    0.0    1.0
  0.0   -1.0    0.0
 -0.93   0.37   0.0
  0.0   -0.63  -0.78
attribute "dep" string "faces"
#  Field definition to put the arrays together.
object "solid" class field
  component "positions"  "position list"
  component "edges"   "edge list"
  component "loops"   "loop list"
  component "faces"   "face list"
  component "colors"  "color list"
  component "normals"  "normal list"
end

Example 12. Image Files

This Data Explorer header file reads an image (cylinder.rgb). The image is 350 x 300 and consists of RGB colors (3-vectors). You can read this image in, and display it, using the visual program /usr/local/dx/samples/programs/ReadImage.net. This file can be found in /usr/local/dx/samples/data/image.dx.
Note:It is easier to import a file in the RGB format by using the ReadImage module. This example illustrates the different aspects of header files.

   # First describe the positions. The image is written such that
   # x varies fastest, and the first pixel in the file is the one that is
   # to be displayed at the top left.
   # Because x varies fastest, the last delta specifies a vector in
   # the x direction.  Because the first pixel is at the top left,
   # the delta in the y direction is -1.
object 1 class gridpositions 300 350
origin  0  0
delta   0 -1
delta   1  0
   # Next describe the connections
   # The image is 350 pixels in x and 300 pixels in y.  Since
   # x is the last delta specified, the connections are specified as
   # 300 x 350
object 2 class gridconnections 300 350
attribute "ref" string "positions"
attribute "element type" string "quads"
   # Next indicate that the data can be found in the file "cylinder.rgb",
   # starting at byte 0.  There are three bytes (red, green, and blue)
   # for each pixel.
object 3 class array type byte rank 1 shape 3 ieee msb items 105000
data file cylinder.rgb,0
attribute "dep" string "positions"
   # We read the colors in as the "data" component. This allows us
   # to immediately begin operating on them (for example, to convert the
   # bytes to floating point colors)
object "image" class field
component "positions" 1
component "connections" 2
component "data" 3

Syntax of the Native File Format

A data file in the Data Explorer native format can contain a header section, a data section, or both. The header section defines a set of Objects, the data for which are contained in the data section or imbedded in the header. Each type of object that can be defined is described in the following subsections.

Header Section

The header section of a Data Explorer file consists of a sequence of Object definitions. Each Object definition consists of a sequence of clauses, beginning with an object clause. The clauses defining an Object can be in any order, except that the type and size information for an Array must be specified before the data if the data are imbedded in the header. A clause consists of a sequence of words separated by one or more blank spaces or new lines. Line breaks are not significant (except after the follows keyword, when data must follow on the next line). Multiple clauses can occur on one line, and a single clause can be split across lines. The following sections describe each of the types of Objects that can be defined. In these descriptions, the monospace font specifies literals; italics, non-literals; square brackets [ ], optional items; and a vertical list, alternatives.

In the header section (and text data sections), # is the comment character. All text from # to the end of the line is ignored.

Data Section

The data section is used for Array data when either an offset in the current file or in a separate file is specified in the Array Object definition. All other Objects, including Array Objects whose definitions use the 'data follows' specification, are self-contained; their definitions include all necessary information. These Objects do not use a data section.

The Data Explorer file format is flexible enough to describe many existing data formats without having to reformat the data. It allows you to specify byte order, which index varies fastest, whether the data type is floating point or byte, and whether the file format is binary or ASCII.

For data that is not in a format accepted by the Data Explorer native file format, you can either reformat the data so it is acceptable, or import the data using a general importer specification (see 5.1 , "General Array Importer" in IBM Visualization Data Explorer QuickStart Guide).

The data section consists of a set of data items specified as text or binary by the data clauses in the various Array Object definitions. Text and binary can be mixed in the same data section, because the data clauses specify portions of the data section by byte offsets. Binary representations can be in most-significant-byte-first (msb) or least-significant-byte-first (lsb) format, as specified by the relevant data or 'data mode' clause. Binary floating-point numbers currently must be in IEEE format.

If a Data Explorer file does not begin with a valid header (at least an end clause), it is assumed not to have a header section.

Objects

Every Object has a class and an identifying numeric or string name whose scope is the file containing the Object. The definition of an Object is introduced by an object clause that specifies the Object number or name and its class. The class keyword is optional (as are many of the keywords in the following list).

  objectnumber [class]group
       "name"   series
                      multigrid
                      compositefield
                      field
                      array
                      constantarray
                      gridpositions
                      regulararray
                      productarray
                      gridconnections
                      patharray
                      mesharray
                      xform
                      string
                      light
                      camera
                      clipped
                      screen  

The numeric or string name of an Object is used to refer to that Object in the definitions of other Objects. In general such references can take one of several forms:

  number
  "name"
  file file
  file file,number
  file file,"name"

An Object that has a string name can be imported with the Import module by specifying that string as the variable parameter of Import.

All Objects can have any number of named attributes specified by attribute clauses. The value of an attribute is an Object. The value can be specified as a string or list of strings by using the string keyword (in which case a String Object is created to hold the string), as a number by using the number keyword (in which case an Array Object is created to hold the number), or as an Object reference.

attribute "attribute-name" [value] string  "string" ...
                 number number
                 number
                 "name"
                 file file
                 file file,number
                 file file,"name"

Group Objects

A Group Object has any number of named or numbered members specified by member clauses. The value of the member is specified as an Object name or number in the current file or as an Object name or number in another file. Member numbers must be sequential, starting at 0, with no gaps in the numbering.

  object  number [class] group
        "name"
  member  "member-name" [value] number
         number          "name"
          file file
          file file,number
          file file,"name"

Series Objects

A Series Object is a subclass of Group Object, in which each member has in addition to its ordinal index a floating-point series position. The series position can be, for example, the time stamp for each member in a time series. A Series Object has any number of numbered members. The value of the member is specified as an Object name or number within the current file or as an Object name or number in another file. Member numbers must be sequential, starting at 0, with no gaps in the numbering.

  object  number [class] series
       "name"
  member  number [position] number [value]number
                 "name"
                 file file
                 file file,number
                 file file,"name"

Multigrid Objects

A Multigrid Object is a subclass of Group Object, in which each member is constrained to have the same data and connections type. This is used for representing a Field as a collection of primitive Fields. Fields may be spatially disjoint or they may overlap. A Multigrid Object has any number of named or numbered members specified by member clauses. The value of the member is specified as an Object name or number within the current file or as an Object name or number in another file. Member numbers must be sequential, starting at 0, with no gaps in the numbering.

  object  number [class] multigrid
        "name"
  member  "member-name" [value]  number
         number          "name"
       file file
       file file,number
       file file,"name"

Composite Field Objects

A Composite Field Object is a subclass of Group Object, in which each member is constrained to have the same data and connections type. In addition, Fields must be spatially disjoint and abutting, with boundary positions replicated exactly. A Composite Field Object has any number of named or numbered members specified by member clauses. The value of the member is specified as an Object name or number in the current file or as an Object name or number in another file. Member numbers must be sequential, starting at 0, with no gaps in the numbering.

  object  number [class] compositefield
        "name"
  member  "member-name" [value]  number
         number          "name"
       file file
       file file,number
       file file,"name"

Field Objects

A Field Object has any number of named components specified by component clauses. The value of the component is specified as an object name or number in the current file or as an Object name or number in another file.

  object  number [class] field
        "name"
  component  "component-name" [value]  number
              "name"
              file file
              file file,number
              file file,"name"

Array Objects

An Array Object specifies the type (default float), category (default real), rank (default 0), shape, and number of items. The types are defined as follows:

signed byte
unsigned byte
signed 2-byte integer
unsigned 2-byte integer
signed 4-byte integer
unsigned 4-byte integer
signed 8-byte integer
4 byte floating point
8 byte floating point
character string

Note: Lists are simply Arrays. Thus a list of integers is an Array of type "int"; a list of strings, an Array of type "string."

The categories are:

real--A number
complex--Two numbers representing the real and imaginary components.
The data is specified by an offset in bytes in the data section of the current file, an offset within the data section of another Data Explorer file, or by the keyword follows, indicating that the data begins immediately following the newline after the follows keyword. The offset is specified in bytes for both binary and text files.

Optional keywords before the data keyword specify the format and byte order of the data. The mode keyword before a data-location specification sets the default data encoding for all subsequent data clauses to be the most recently defined data encoding. The default data encoding is text (or ascii on all currently supported systems). The ieee keyword specifies the ANSI/IEEE standard 754 data format.

If binary (or ieee on all currently supported systems) is specified, the default byte order depends on the platform on which Data Explorer is running. On the DEC Alpha, the default byte order is lsb (least significant byte first). On all other platforms, the default byte order is msb (most significant byte first). The 'data mode' clause can be used outside an Array Object definition; see "Data Mode Clause" for more information.

  object  number [class] array
         "name"
  [type  [unsigned] byte ]
    signed byte
        unsigned short
        [signed] short
        unsigned int
        [signed] int
        hyper
        float
        double
        string
  [category  real     ]
            complex
  [rank number]
  [shape number ...]
  items number
  [  msb  ] [   text ] data [ mode ]  offset
     lsb      ieee                  file file,offset
              binary                follows
              ascii

If byte, short, or int are not prefixed with either signed or unsigned, by default, bytes are unsigned, shorts are signed and ints are signed. For compatibility with earlier versions, char is accepted as a synonym for byte.
Note: For string-type data, the Array rank should be 1 and the Array shape should be the length of the longest string plus 1.

Constant Array Objects

A Constant Array defines an Array whose elements all have the same value.

  object  number [class] constantarray
         "name"
  [type  [unsigned] byte ]
    signed byte
        unsigned short
        [signed] short
        unsigned int
        [signed] int
        hyper
        float
        double
        string
  [category  real     ]
            complex
  [rank number]
  [shape number ...]
  items number
  [  msb  ] [   text ] data [ mode ]  offset
     lsb      ieee                  file file,offset
              binary                follows
              ascii

If byte, short, or int are not prefixed with either signed or unsigned, by default, bytes are unsigned, shorts are signed and ints are signed. For compatibility with earlier versions, char is accepted as a synonym for byte.
Note:For string type data, the Array rank should be 1 and the Array shape should be the length of the string plus 1.

The only difference between the specification of a Constant Array and the specification of an Array is that for a Constant Array only one value is listed in the data section.

gridpositions Keyword

The gridpositions keyword is used to represent an n-dimensional grid of geometrically regular points in a compact form. It is a kind of Array Object and can be used in any context where an Array Object would be used. It is typically used as a regular positions component. The shape of the grid (number of points in each dimension) is specified by a list of n numbers following the optional counts keyword in the object clause. The number n of items in this list determines the dimensionality of the grid. The last item in this list corresponds to the fastest varying dimension.

A grid has an origin, which can be specified by an origin clause (which lists the n coordinates of the origin). If the origin clause is not present, the origin defaults to 0. The origin clause can be followed by n delta clauses, listing the deltas for each dimension. Each delta clause has n elements. The last delta clause corresponds to the fastest varying dimension. "Example 1. A Regular Grid" shows how to use the delta clause to specify a grid in which z varies fastest. If the delta clauses are not specified, the deltas default to unit vectors in each dimension, with the last dimension varying fastest.

  object  number [class]  gridpositions [counts]number...
         "name"
  origin number ...
  delta number ...
  [ delta number ... ]
  .
  ∶

The gridpositions keyword does not actually correspond to a primitive Object type in the system, but instead is a convenient way of representing an important special case of the more general product (Product Array Object) of n 1-dimensional Regular Arrays (Regular Array Objects). For most purposes the gridpositions keyword is sufficient and more convenient. The more primitive Regular and Product Arrays are described next.

Regular Array Objects

A Regular Array Object is a compact encoding of a linear sequence of equally spaced points in n-space. It is often combined in a Product Array with other Regular Array Objects to obtain a grid of equally-spaced points in n-space; in such a case, it is generally more convenient to use the gridpositions keyword described earlier.

A Regular Array Object is a linear sequence of points in n-space starting at some origin, specified by the origin clause, and separated by some constant delta, specified by the delta clause. The delta clause has the same number of elements as origin. The dimensionality of the space that the linear sequence is embedded in is determined by the number of coordinates specified in the origin clause. Regular Array Objects are always of rank 1.

  object  number [class] regulararray [items] number
         "name"
  [type  unsigned byte ]
    signed byte
        unsigned short
        signed short
        unsigned int
        signed int
        hyper
        float
        double
        string
  origin number ...
  delta number ...

Product Array Objects

A Product Array is a compact encoding of a generalized notion of a regular grid. It is frequently used to describe a rectilinear grid as a product of Regular Arrays; in such a case, it is generally more convenient to use the gridpositions keyword described earlier.

A Product Array is the set of all possible sums of the points of the terms forming the product. For example, the product of a set of Arrays, each of which is a Regular Array as described above, is a lattice of points with basis vectors equal to the deltas of the Regular Arrays and origin equal to the sum of the origins of the terms. A product of a Regular Array with an irregular Array is a "semi-regular" grid whose unit cells are prisms. A Product Array is specified by a list of term clauses naming the Arrays that form the product. The last term varies fastest in the resulting list of positions.

  object  number [class] productarray
         "name"
  term  number
      "name"
      file file
      file file,number
      file file,"name"

gridconnections Keyword

The gridconnections keyword is used to represent the n-dimensional cuboidal connections of a regular grid in a compact form. It is a kind of Array Object and can be used as the "connections" component of a Field. The shape of the grid (number of points in each dimension) are specified by a list of n numbers following the optional counts keyword in the object clause. The last number corresponds to the fastest varying component of the positions. The number n of items in this list determines the dimensionality of the grid. The last item in this list corresponds to the fastest varying dimension.

If this grid is part of a Composite Field Object, then meshoffsets must be specified to define where this grid is positioned relative to the entire Composite Field. The meshoffsets (one number for each dimension, and specified in the same order as counts) are the accumulated count of connections between the origin of the whole grid and the origin of this grid.

  object  number [class]  gridconnections
         "name"
  [counts] number...
  [ meshoffsets number... ]

The gridconnections keyword does not actually correspond to a primitive Object type in the system, but instead is a convenient way of representing an important special case of the more general mesh (Mesh Array Object) of n 1-dimensional paths (path Array Objects). For most purposes the gridconnections keyword is sufficient and more convenient. The more primitive Mesh and Path Arrays are described next.

Path Array Objects

A Path Array Object encodes linear regularity of connections. It is often combined in a Mesh Array with other Path Arrays to obtain a grid of connections; in such a case, it is generally more convenient to use the gridconnections keyword described earlier.

A Path Array is a set of n-1 line segments joining n points, where the ith line segment joins points i and i+1. The number of points n is specified by the number following the optional count keyword.

  object  number [class] patharray [count] number
         "name"

Mesh Array Objects

A Mesh Array is a compact encoding of a generalized notion of a regular grid of connections. It is frequently used to describe a rectangular grid of connections as a product of Path Arrays; in such a case, it is generally more convenient to use the gridconnections keyword described earlier.

A Mesh Array encodes multidimensional regularity of connections. It is a product of connection Arrays. The product is a set of interpolation elements where the product has one interpolation element for each pair of interpolation elements in the two multiplicands, and the number of sample points in each interpolation element is the product of the number of sample points in each of the multiplicands' interpolation elements. A Mesh Array is specified by a list of term clauses naming the Arrays that form the product. The last term varies fastest in the resulting list of connections.

  object  number [class] mesharray
         "name"
  term  number
         "name"
         file file
         file file,number
         file file,"name"

XForm Objects

An xform Object specifies another Object transformed for example by a rotation, scaling, or translation. The Object to be transformed is specified by an of clause, and the transform itself is specified by a 3×3 matrix specified by a times clause and a 3-vector specified by a plus clause.

  object  number [ class] xform [of] number
         "name"  "name"
                         file file
                         file file,number
                         file file,"name"
  [times]  a b c d e f g h i
  [plus]  j k l

This Object represents the Object specified in the of clause, where each point [x y z] in the Object has been transformed to the new point [x' y' z'] according to lb x prime   y prime   z prime rb = lb x   y   z rb %% left lbracket a rabove d rabove g %%%% b rabove e rabove h %%%% c rabove f rabove i right rbracket % plus lb j   k   l rb

String Objects

A String Object encapsulates a text string as an Object. For example, the values of Object attributes are frequently string Objects. However, String Objects as such generally do not appear in Data Explorer files because a string-valued Object attribute can be specified by using the string keyword as described in "Objects".

  object  number [class] string "string" ...
         "name"

Light Objects

A Light Object is used to place a light in a scene for the renderer. Lights can be either local or distant. Local lights have a position and a color. Distant lights are at infinity, and have a direction and a color. It is often not necessary to specify a light in a scene because the renderer has a default built-in light that is sufficient for most purposes. For ambient lights, only color can be specified, not direction or position. For distant lights, the direction can be absolute, or it can be relative to the current location of the camera, as specified in a 'from camera' clause.

  object  number [class] light [type]  distant
         "name"  local
                    ambient
  direction number number number [ from camera ]
  position number number number
  color number number number
      "color"
  position number number number
Note:In the current release of the Data Explorer, local lights are not supported.

Camera Objects

A Camera Object specifies a camera for rendering. Camera Objects are not generally found in Data Explorer files, but rather are generated as part of the execution of a script or network. The definition of a Camera Object is included here for completeness.

  object  number [class]
  camera [[type] orthographic]
         "name"
  from number number number
  to number number number
  width number
  resolution number
  aspect number
  up number number number
  angle number
  color number number number
              color name

Clipped Objects

A Clipped Object represents one Object (specified by the of keyword) clipped by another Object (specified by the by keyword). Generally, Clipped Objects are not specified in input data files, but rather are generated as a result of using the ClipPlane or ClipBox module.

object  number [class] clipped by   number of 
number
        "name"  "name"   "name"
    file file    file file
    file file,number  file file,number
    file file,"name"  file file,"name"

Screen Objects

Screen Objects represent an Object transformed so as always to face the camera. See Chapter 16. "Rendering" in the IBM Visualization Data Explorer Programmer's Reference for more information, specifically 16.5 , "Screen Class".

object number [class] screen [ world   ] [ behind  ] [of] number
   "name"             viewport inside  "name"
    pixel  infront  file file
     stationary   file file,number
             file file,"name"

Data Mode Clause

You can specify a default data section format using the 'data mode' clause. This clause can be used as part of an Array Object definition, or as a stand-alone clause in the header section. msb (most significant byte first) and lsb (least significant byte first) specify the byte order; text and 'binary' specify the data format. (On all current platforms, ieee is a synonym for binary, and ascii for text.)

  data mode  [  msb ] [  text ]
  lsb      ieee
         binary
         ascii

Default Clause

You can specify the default Object to be imported using the default clause. When a Data Explorer data file contains more than one Object (which is the usual case), the Import module (see Import in IBM Visualization Data Explorer User's Reference) decides which Object to import based on the value of the variable parameter (Object name or names) of the Import module, and the default clause (if specified). If variable is specified to Import, then those Objects specified are imported. If variable is not specified, but a default Object is specified with the default clause, then the default Object is imported. If variable is not specified, and no Object has been defined as the default, then the last Object in the file is imported.

   default number
          "name"

End Clause

The end of the header section is indicated by an end clause. The data section begins with the byte immediately following the first newline after the end clause.

  end


Full Contents QuickStart Guide User's Guide User's Reference

[ OpenDX Home at IBM | OpenDX.org ]