CIBC:Documentation:SCIRun:UserGuide:ImportExport
This chapter describes the format of text-based data files and the use of SCIRun's reader and writer modules to import/export SCIRun data objects from/to text files.
SCIRun's reader and writer modules support two classes of data formats: SCIRun's persistent format and text-based formats. This chapter discusses text-based formats.
In general, it is best to save data in SCIRun's persistent format. SCIRun's persistent format loads faster, supports better numerical precision, and is usually smaller than its text-based counterpart. SCIRun's persistent data files are portable between machine architectures. Text-based data are used primarily to import data generated by other software into SCIRun and to export SCIRun generated data to other software.
Using Readers and Using Writers discuss the use of SCIRun's reader and writer modules to read and write text-based data. Text-based File Formats describes the format of text-based data files.
Contents
Using Readers
This section describes the use of SCIRun's reader modules to read text-based data.
Control dialogs for all reader modules are similar. They contain a file type popup menu that selects the type (binary or text) of file to read as input. The dialog's file browser is used to choose a file. The figure below shows the control dialog for module ReadMatrix. When reading a SCIRun matrix file, item SCIRun Matrix File (*.mat) is selected from the file type popup menu. When reading a text-based matrix file then one of TextDenseMatrix (*.*) or TextSparseRowMatrix (*.*) is selected from the file type popup menu depending on the type of matrix stored in the text file.
When reading unstructured field data from a text file, module FieldReader reads data from a node coordinate file and a separate node connectivity file. However only one of the files is chosen with the file browser. FieldReader assumes the other file's name differs only in its extension.
Module ReadField can read only field geometry (node coordinate and node connectivity) data from text files. Module ReadMatrix is used to read field data values. Module SwapFieldDataWithMatrixEntries is used to merge field geometry data (from module ReadField) with field data values to form a complete filed. The figure below shows the arrangement of these three modules.
Using Writers
This section describes the use of SCIRun's writer modules to write text-based data.
Control dialogs for all writer modules are similar. They contain a file type popup menu that selects the type (e.g. text or binary) of file (or possibly files for text output) to write as output. The dialog's file browser is used to specify an output file. The figure below shows the control dialog for module WriteField.
When writing unstructured field data to text files, module WriteField writes data to a node coordinate file and a separate node connectivity file. However only one of the files is specified in the dialog. WriteField assumes the other file's name differs only in its extension.
When writing to text files, module WriteField can write only field geometry (node coordinate and node connectivity) data. Module WriteField is used to write field data values. Module SwapFieldDataWithMatrixEntries is used to split field geometry data from field data values, sending field geometry data to module WriteField and field node data to module WriteField. The figure below shows the arrangement of these three modules.
Text-based File Formats
SCIRun's reader and writer modules read and write text files containing the following data:
- Node coordinates
- Node connectivities
- Structured mesh parameters
- Column matrices
- Dense matrices
- Sparse row matrices
- Color map parameters
SCIRun unstructured field types are stored in two or three text files. Curve, hex volume, quad surface, tet volume, and tri surface fields each require three files: a node coordinate, a connectivity, and a column matrix file. Point cloud fields require no connectivity file.
Note that field readers read node coordinate and connectivity files only. Therefore, to construct a complete field from text-based files a ReadField module is used to read node coordinate and connectivity data and a ReadMatrix module is used to read field data from a matrix file. Outputs from modules ReadField and ReadField are sent to module SwapFieldDataWithMatrixEntries, which combines their outputs to create complete field object. See Using Readers for more information.
When writing a field, use module SwapFieldDataWithMatrixEntries to split a field into a geometry stream and a data stream. Send the geometry stream to module WriteField, which writes node coordinate and connectivity files, and send the data stream to module WriteMatrix, which writes field data to a matrix file. See Using Writers for more information.
The structured (curve, quad surface, and hex volume) field types each require only a node coordinate file.
SCIRun column matrix, dense matrix, and sparse row matrix data are stored in column matrix, dense matrix and sparse matrix files respectively.
A Colormap is stored in a colormap file.
Node Coordinate File
Node coordinate files have the extension .pts. A node coordinate file contains the coordinates of every node in a mesh.
Field reader and writer modules import/export pts files.
The format is as follows:
N x0 y0 z0 x1 y1 z1
. . .
xN yN zN
N is the number of nodes in the file. Each remaining line defines the coordinates of one mesh node.
Connectivity Files
SCIRun supports five unstructured mesh types. Each mesh type is described by a corresponding type of node connectivity file. Curve meshes are made up of edge elements contained in edge files. Surface meshes composed of triangular elements are stored in fac files. Surface meshes composed of quadrilateral elements are stored in quad files. Volume meshes composed of tetrahedral elements are stored in tet files. Volume meshes composed of hexahedral elements are stored in hex file.
Edge files have the file extension .edge. Fac files have the extension .fac. Likewise for quad, tet, and hex files.
Field reader and writer modules import/export edge, fac, quad, tet, and hex connectivity files.
Connectivity files are formatted as follows:
N Node indicies of element 0 Node indicies of element 1
.
.
.
Node indicies of element N
N specifies the number of elements in a file.
Each remaining line specifies node indices of one element. Node indices are assumed to be zero-based.
Edge files have two node indices per line, fac files have three, quad and tet files have four, and hex files have eight node indices per line. For example, a fac file looks like the following:
N i0 j0 k0 i1 j1 k0
. . .
iN jN kN
Structured Meshes
Structured meshes are stored in node coordinate (pts) files. Only node coordinates are needed. Connectivities are implicit because node coordinates are stored in scan-line order.
For example, in a structured hexahedral mesh, the list of nodes comprising element ei, j, k is {ni, j, k, ni, j, k+1, ni, j+1, k+1, ni, j+1, k, ni+1, j, k, ni+1, j, k+1, ni+1, j+1, k+1, ni+1, j+1, k}
The formats of node coordinate files for structured meshes differ slightly from node coordinate files described in Node Coordinate File Format. Node coordinate files for structured meshes specify the number of indices in each dimension of the mesh.
A structured curve field node coordinate file looks like this:
NI x0 y0 z0 x1 y1 z1
. . .
xN yN zN
The node coordinate file for a structured quadrilateral surface field looks like this:
NI NJ x0 y0 z0 x1 y1 z1
. . .
xN yN zN
The node coordinate file for a structured hexahedral volume field looks like this:
NI NJ NK x0 y0 z0 x1 y1 z1
. . .
xN yN zN
Column Matrix
The column matrix file format is:
N v0 v1 . . . vN
N specifies the number of matrix rows. N is followed by a list of data values.
Dense Matrix
The dense matrix file format is:
N M v(0,0) v(0,1)...v(0,M) v(1,0) v(1,1)...v(1,M)
.
.
.
v(N,0) v(N,1)...v(N,M)
N, M are the number of matrix rows and columns respectively. Following N and M is a list of data values given in row major order.
Sparse Row Matrix
The sparse row matrix file format is:
NR NC NE r0 c0 v0 r1 c1 v1
. . .
rNE cNE vNE
NR, NC, and NE specify the number of rows, number of columns, and number of matrix entries respectively.
Remaining lines are matrix entries. Each entry consists of a row index, a column index, and a data value. Entries must have ascending row indices. Column indices must be in ascending order for rows with multiple entries.
Color Map
The color map file format is:
N r1 g1 b1 a1 v1 r2 g2 b2 a2 v2
.
.
.
rN gN bN aN vN
N specifies the number of color map entries in the file.
Each line following N is a color map entry consisting of an RGB color entry, an alpha value, and a data value. All RGB, alpha, and data values are in the range 0.0 to 1.0 inclusive.
