Overview | All Modules | Tutorial | User's Guide | Programming Guide

COVISE Online Documentation

Module category: IO


This is a module to read ASCII files to create points (with or without scalar or vector values) or a grid. It is created to handle all (senseful) types of formats. So there are very many parameters, to fit as many formats as possible.
It is strongly recommended to use the Control Panel instead the Module Parameter list, because the module maps the available parameters dynamically to the Control Panel. Due to that, you don't have to worry about parameters that have no influence to the reading process.
The most importent parameter is the data format, because the modul reads the file with help from this parameter.
There are different examples below.

Available on all supported platforms.


Name Type Description
FilePath Browser File of interest
Max line length Integer length of the max line in the file
Geometry Type Choice Geometry of the input data
Header Boolean Does the file contain an header? (For grids only. Contains the dimensions)
Header Byte Offset Integer Skip X Bytes for header readout
Header Line Skip Integer Skip X lines for header readout
Dim Pattern String Pattern to scan the dimensions from the header
DimX Integer X Dimension (grid only)
UniDist X Integer Uniform distance in X direction (grid only)
DimY Integer Y Dimension (grid only)
UniDist Y Integer Uniform distance in Y direction (grid only)
DimZ Integer Z Dimension (grid only)
UniDist Z Integer Uniform distance in Z direction (grid only)
Data interleaving Boolean Is the data input in an interleaved format?
Number of Points Integer Number of Points (will be calculated for grids)
Data Byte Offset Integer Skip X Bytes for data readout
Data Line Skip Integer Skip X lines for data readout
Data Format String Format to scan the data
Grid Index Iteration Order Choice Iteration order of the index (Structured Grid only)
Print results to console Boolean Print the result in Format: x,y,z(coords) - scalar - x,y,z(value)
Print debug info to console Boolean Print used parameters and their values
Scale Float Scale factor (if factor is 1 it will be ignored)

Output Ports

Name Type(s) Description
Geometry Points
Uniform Grid
Rectilinear Grid
Structured Grid
Points or a grid
ScalarData Float
Scalar data
VectorData Vec3
Vector data

File Format

The file format parameter is the most importent one, because here you can tell the module how the ASCII file is written. The module uses the file format string to parse the ASCII file.

First you have to know how to mark the values in your format string. Therefore are some escape sequences defined, very simular to the sscanf command in the C++ programming language.

Escape Symbol Input Type Example
%XP the x-part of the coords of an point file format: %XP, %YP, %ZP
%YP the y-part of the coords of an point file format: %XP, %YP, %ZP
%ZP the z-part of the coords of an point file format: %XP, %YP, %ZP
%S a scalar value (i.e. mass of a star) file format: point: %XP %YP %ZP value: %S
%XV the x-part of a vector Value (i.e. velocity inside a streaming model) file format: (%XP,%YP,%ZP)|(%XV,%YV,%ZV)
%XV the y-part of a vector Value (i.e. velocity inside a streaming model) file format: (%XP,%YP,%ZP)|(%XV,%YV,%ZV)
%XV the z-part of a vector Value (i.e. velocity inside a streaming model) file format: (%XP,%YP,%ZP)|(%XV,%YV,%ZV)
%F a dummy value. Will be ignored file format: %F. point: %XP, %YP, %ZP
\n a newline, if a reading sequence is expanded to more then one line or data is not interleaved
(see also documentation on interleaved or non-interleaved file formats)
file format: %XP,%YP,%ZP\n%S
%% if your format contains '%' to skip interpreting it file format: in percent: %F%%, absolut value: %S
note: If you have your data in an non-interleaved format, separate the jumps with '\n' (see example for non-interleaved data format below)

Examples for file format strings:
File example Format string example Annotations
1, 0, 0
3, 0, 0
1, 2, 0
3, 2, 0
1, 0, 2
3, 0, 2
1, 2, 2
3, 2, 2
%XP, %YP, %ZP Defines the edges of a cube in interleaved format
1, 0, 0
3, 0, 0
1, 2, 0
3, 2, 0
%XP, %YP, %ZP\n%S Defines the edges of a rectangle in interleaved format and corresponding scalar values in a new line

Now you could connect a sphere module to the first two ports (points and scalar values) and you
get four points with different sizes.

About the header

When creating a grid, you can read the dimensions from the header, so you don't have to care about the right dimensions. You have to mark the header box and insert a pattern in the dim pattern line. Because the dimension values are integer type, you can only read integers.
The escape symbol is the %d to read the dimension value.

If you click on the print results checkbox you can see on the console if your dimensions are recognized correctly everytime you change the pattern.

file example:
dimensions = 3 x 4 x 16

// data...

pattern example:
dimensions = %d x %d x %d

About the offsets

You can skip lines or bytes to the readout point of your choice. This is important if your header is not in the first line or your data does not start in the first line (esp. if you have an header). The counter starts at 1.

Note: You cannot apply Byte AND line offset at the same time for the header or the data. You can apply Byte offset for header and line offset for data or revers.

About the dimensions and the uniform distances

The dimensions are only usable, if you have a grid creation active in the geometry choice box. The UniDist function does only work with a rectangular or a structured grid.
You can read your dimensions from the header of your file (see 'About the header') or type them manually. Note that if the header box is marked, the manual typed dimensions will be overwritten.
With the UniDist function, you can create an uniform grid when creating a grid, which can be partly or complete overwriten by the data from the file.

This setting will create a uniform grid with the dimensions 40 x 40 x 16 and an uniform distance of 1 in all directions. From the file comes values for the z-coords, they will replace the preset values. The result will be a uniform grid in x and y direction and a structured grid in z direction.

Data interleaving

When reading a file you have to determine how your data is given. There are two basic possibilities:
Interleaved: The data is given as a set of values. To read out a file with that format, activate the checkbox Data interleaving.

Non-interleaved: If the data is formated in the way, that first all x values, then all y-values, etc. are given we speak of an non-interlived data format. Make sure the above mentioned checkbox is free.

That is an interleaved format.
The file format pattern to read that is:
(%XP, %YP, %ZP)
That are the same vectors in an non-interleaved format
The file format pattern to read that is:

Grid Index Iteration Order

There are different ways you can sort your coordinates. When reading out just points it is not nesessary to have an eye on this, but when creating a structured grid, the connectivity is really different, because it is just implizit given.
The standard index iteration order is k, j, i (or z, y, x). But some applications write the index in i, j, k order. In that case the module has to re-sort them and you have to choose the i, j, k order in the drop down menue.
If your grid looks weird and you are sure that all other parameters are right, try to resort the vectors by changing the Grid Index Iteration Order setting.

That is an 2 x 3 x 3 grid in an k, j, i sequence
->iteration sequence z, y, x
The same grid in an i, j, k sequence
->iteration sequence x,y,z
0, 0, 0
0, 0, 1
0, 0, 2
0, 1, 0
0, 1, 1
0, 1, 2
0, 2, 0
0, 2, 1
0, 2, 2
1, 0, 0
1, 0, 1
1, 0, 2
1, 1, 0
1, 1, 1
1, 1, 2
1, 2, 0
1, 2, 1
1, 2, 2
0, 0, 0
1, 0, 0
0, 1, 0
1, 1, 0
0, 2, 0
1, 2, 0
0, 0, 1
1, 0, 1
0, 1, 1
1, 1, 1
0, 2, 1
1, 2, 1
0, 0, 2
1, 0, 2
0, 1, 2
1, 1, 2
0, 2, 2
1, 2, 2

Authors: Martin Aumüller, Ruth Lang, Daniela Rainer, Jürgen Schulze-Döbold, Andreas Werner, Peter Wolf, Uwe Wössner
Copyright © 1993-2016 HLRS, 2004-2014 RRZK, 2005-2014 Visenso
COVISE Version 2016.3