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.
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 84. Header
Referring to Data in Another File
 |
Figure 85. Header and
Data in the Same File
 |
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").
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".
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/lpp/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").
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/lpp/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 88. Warped
Regular Grid Example
The example file (in /usr/lpp/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).
This example file (in /usr/lpp/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
# 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
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/lpp/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
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/lpp/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
# 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
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/lpp/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/lpp/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
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/lpp/samples/data/datadepconnections.dx", format="dx");
colored = AutoColor(data);
camera = AutoCamera(colored);
Display(colored, camera);
The data file is located in /usr/lpp/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
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/lpp/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 93. Example of
Faces, Loops, and Edges with a Hole
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
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/lpp/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
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
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/lpp/dx/samples/programs/ReadImage.net. This file can be found in /usr/lpp/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
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.
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.
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.
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"
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"
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"
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"
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"
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"
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:
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:
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. |
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.
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 ... ]
.
&ratio.
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.
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 ...
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"
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.
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"
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"
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
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"
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. |
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
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 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"
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
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"
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
[Data Explorer Home Page | Contact Data Explorer | Same document on Data Explorer Home Page ]