Developer's Reference
TOC PREV NEXT INDEX

7 Importing data from simple files using File Access objects

This chapter describes how to import data from simple files using modules in the File Access library.

This chapter discusses:

7.1 Overview

The File Access library is located in the Accessories page of the Network Editor under Utility Modules. It contains a number of objects that allow you to import data from simple data files:

You can use these objects to construct a mapping between an AVS/Express object and the data in a file. As the values in the AVS/Express object are accessed, AVS/Express automatically goes to the file to get the values. From the Network Editor, you can use the Add File Import Module tool to create these objects.

For a description of how to use the file access objects as a technique for importing data, see Section 3.7, Technique 4: Using File Access objects  [page 3-27] in the book Visualizing Your Data with AVS/Express.
For detailed information about using the Add File Import Module tool, see Section 4.2, Adding a file import module using the Add File Import Module tool  [page 4-26] in the User's Guide.
V access

The file objects can also be accessed through V, by prepending the module name with "FILE". For example, to create an instance of the file_scalar_ascii module, type:

-> FILE.file_scalar_ascii my_file_scalar_ascii;

The rest of this chapter provides reference information on each of the file access objects.

7.2 file

You use the file object to specify a filename. For example, you can create a filename object for each file that you need to read or search and connect each one to the appropriate reading and searching object as needed.

When you instance a file object, you set the name subobject to the pathname of the file containing the data. Once you set the name subobject, the file object's update method assigns values to the fptr, status, and cur_offset subobjects.

7.3 file_obj(file, offset, type, columns, ascii_binary [,stride])

The file_obj object reads an ASCII or a binary array from the file object (refer to page 7-4 in the Developer's Reference). It starts reading data at the offset position which is specified in bytes, and it reads the number of values corresponding to the dimensionality of the referencing object. If the dimensionality is not specified, it reads until the end of file. If the dimensionality is specified and the end of file is reached before the target object is filled, an error is reported.

Note: file_obj is the superclass of the file_obj_bin, file_scalar_ascii, and file_array_ascii objects described later in this chapter.

file is an object that identifies the file that will be accessed. Refer to page 7-4 in the Developer's Reference for more information.

offset specifies, in bytes, an offset from the beginning of the file.

type is an integer that specifies the type of data:

Value
Data type
0
Byte
1
Character
2
Short
3
Integer
4
Float
5
Double

columns is an array of 1s and 0s that represents words in the lines of an ASCII file. It indicates whether or not to read the words. This parameter is not used for binary files.

ascii_binary is 0 for ASCII files, 1 for binary files and 2 for portable binary (XDR) files. Alternatively you can specify this parameter using one of the strings: "ascii", "binary" or "xdr".

stride is an optional integer value that specifies how many "strides" must be taken to get to the next data value. It is relevant only for binary files, if is omitted, 1 is assumed.

7.4 file_obj_bin (file, offset, type [,stride])

file_obj_bin reads a binary array or binary scalar from the file object (refer to page 7-4 in the Developer's Reference). It starts reading data at the offset position which is specified in bytes. file_obj_bin reads a number of bytes corresponding to the type value and dimensionality of the referencing object. It reports an error if it reaches the end of file before the target object is filled.

Note: file_obj_bin does not perform byte-swapping necessary to read binary files created on foreign platforms that use incompatible binary data formats.

file is an object that identifies the file that will be accessed. Refer to page 7-4 in the Developer's Reference for more information.

offset specifies, in bytes, an offset from the beginning of the file.

type is an integer that specifies the type of data:

Value
Data type
0
Byte
1
Character
2
Short
3
Integer
4
Float
5
Double

stride is an optional integer value that specifies how many "strides" must be taken to get to the next data value. It is relevant only for binary files, if is omitted, 1 assumed.

Example

A binary file, myData, has an array of integers. To read the third integer:

file data_file {
name = "myData";
};
int value => file_obj_bin (data_file, 8, 3);

Note that the offset is calculated in bytes. A value of 8 indicates that the first two integers in the file are ignored.

Example

The inary file, myData, contains an array of integers. To read 100 integers, starting from position 200 in the file. To read 100 integers:

file data_file {
name = "myData";
};
int values[100] =>file_obj_bin (data_file,200,3);

7.5 file_scalar_ascii (file, offset, type)

The file_scalar_ascii object reads ASCII scalar data from file starting at the position specified by an offset in bytes. The integer type specifies the type of data:

Value
Data type
0
Byte
1
Character
2
Short
3
Integer
4
Float
5
Double

Example

ASCII file, data, contains an integer and a float:

128 666.777

To get the integer and float values:

file data_file {
name = "data";
};
int i_value => file_scalar_ascii(data_file, 0, 3);
int f_offset => file_skip_words(data_file, 0, 1);
float f_value => file_scalar_ascii(data_file, f_offset, 4);

7.6 file_array_ascii(file, offset, type, columns)

The file_array_ascii object reads an ASCII array from file starting at the position specified by an offset in bytes. The integer type specifies type of data:

Value
Data type
0
Byte
1
Character
2
Short
3
Integer
4
Float
5
Double

columns is an array of 1s and 0s that represents words in the lines of an ASCII file. It indicates whether or not to read the words.

file_array_ascii reads the number of words corresponding to the dimensionality of the referencing object. It reports an error if it finds the end of file before the target object is filled. The words must be separated by spaces.

Example

ASCII file, data, contains three columns of float numbers starting from line 100. There are 200 lines containing the array.

You want to extract the second and third components of the array:

file data_file{
name = "data";
};
int offset => file_skip_lines (data_file, 0, 100);
float values[200][2] =>
file_array_ascii(data_file,offset, 4, {0, 1, 1});

7.7 file_find_expr(file, offset, regular_expression)

The file_find_expr object searches for a pattern that matches a user-specified UNIX regular expression string. This capability only works on UNIX systems. It returns the offset in bytes of the next byte after the expression.

Example

In ASCII file, data, find the integer "ndim" that follows an expression:

ndim <any number of spaces> = <any number of spaces>


file data_file {
name = "data";
};
int offset => file_find_expr(data_file, 0, "ndim[ ]*=[ ]*");
int ndim => file_scalar_ascii(data_file, offset, 3);

7.8 file_skip_lines (file, offset, nlines)

The file_skip_lines object returns the offset in bytes of a location in file after skipping nlines in an ASCII file.

7.9 file_skip_words (file, offset, nwords)

The file_skip_words object returns the offset in bytes of a location after skipping nwords in an ASCII file. The words must be separated by spaces.

Example

To read the third integer on line 10 in the ASCII file, data:

file data_file {
name = "data";
};
/* skips 9 lines */
int line_offset=> file_skip_lines (data_file, 0, 9);
int offset => file_skip_words(data_file, line_offset, 2);
int value => file_scalar_ascii(file_file, offset, 3);

7.10 Example of importing a file with a uniform field

This example uses the file objects and V functions to import a file in AVS field format. It reads the hydrogen.fld file.

In the following example the "cache" function is used to prevent multiple accesses to the file from different modules.

file header_file {

file data_file {
name = "$AVS_PATH<0>/data/volume/hydrogen.dat";
};
/***
In the following example "cache" function is used to prevent
multiple access to file from different modules.
***/
Mesh_Unif+Node_Data+Scalar+Byte+OPort unif_field {
ndim => cache( /* find ndim */
file_scalar_ascii(header_file,
file_find_expr(header_file,0,"ndim[ ]*=[ ]*"),3)
);
int dim1 => cache( /* find dim1 */
file_scalar_ascii(header_file,
file_find_expr(header_file,0,"dim1[ ]*=[ ]*"),3)
);
int dim2 => cache( /* find dim2 */
file_scalar_ascii(header_file,
file_find_expr(header_file,0,"dim2[ ]*=[ ]*"),3)
);
int dim3 => cache( /* find dim3 */
file_scalar_ascii(header_file,
file_find_expr(header_file,0,"dim3[ ]*=[ ]*"),3)
);

dims => {dim1,dim2,dim3}; /* field dims array */

nspace => cache( /* find nspace */
file_scalar_ascii(header_file,
file_find_expr(header_file,0,"nspace[ ]*=[ ]*"),3)
);

points=>{0,0,0,dim1-1,dim2-1,dim3-1};

!node_data[0] {
veclen => cache( /* find veclen */
file_scalar_ascii(header_file,
file_find_expr(header_file,0,"veclen[ ]*=[ ]*"),3)
);

values => file_obj_bin(data_file, 3, 1); /* node data */
};
};

7.11 Example of importing a simple UCD ASCII File

This example uses the file objects and V functions to import a file in AVS ASCII UCD format. It reads the bluntfin.inp file.

To represent the general UCD file format using file objects is a rather challenging task. This example uses the fact that bluntfin.inp has just one hexahedral cell type. In general it is possible to use file objects with a UCD format only if there is just one cell type or a list of cells that is sorted by cell types. In this case it is possible to map UCD cells onto the Cell_Sets used in AVS/Express to represent different cell types.

In the following example the "cache" function is used to prevent multiple access to the file from different modules.

file ucd_file {
name="$AVS_PATH<0>/data/ucd/bluntfin.inp";
};

Mesh+Node_Data+OPort ucd_file_field {
int file_beg => cache(file_skip_lines(ucd_file,0, 18)); /* skip SCCS header */

nnodes => cache( /* number of nodes */
file_scalar_ascii(ucd_file, file_beg, 3));

int rncells =>cache( /* number of cells */
file_scalar_ascii(ucd_file,
file_skip_words(ucd_file, file_beg, 1), 3));

nspace=3; * UCD always have nspace = 3 */
coordinates {
values=> cache( /* xyz arrays, skip first column: node index */
file_array_ascii(ucd_file,
file_skip_lines(ucd_file,file_beg,1),4,{0,1,1,1}));
};
ncell_sets=1; /* we can use file objects only for sorted cell types */
Hex cell_set { /* only one cell set */
ncells => rncells; /* rncells defined before */
node_connect_list=> cache( /* cell connectivity, skip 3 columns: cell
index, cell_type and material_id */
file_array_ascii(ucd_file,
file_skip_lines(ucd_file,file_beg,1+nnodes),3,
{0,0,0,1,1,1,1,1,1,1,1}) -1);
};
int ncomps = 5; /* number of components in file */
nnode_data =1; /* read just one first component */
!node_data[0]{
veclen =>cache( /* offset for veclen is rather involved...*/
file_scalar_ascii(ucd_file,
file_skip_words(ucd_file,
file_skip_lines(ucd_file,file_beg,
1+nnodes+rncells),1), 3));
float values[nvals][veclen]=> cache( /* node data, just the second colunm */
file_array_ascii(ucd_file,
file_skip_lines(ucd_file,file_beg,
2+nnodes+rncells+ncomps),4,{0,1,0,0,0,0}));
};
};

These objects act like arrays in that you can connect them to field mapper modules; they import generic data, not field data.

Online examples are also available in:

v/examples.v
examples/file_ucd.v
example/fileuni.v

TOC PREV NEXT INDEX