Ensight4Matlab

Ensight4Matlab let's you read, process, and write files in EnSight® Gold format from your C++ or MATLAB® code.

Table of Contents

• Installation
  • Requirements
  • Building the EnsightLib C++ library
  • Installing the library
  • Running tests
  • Building the MATLAB interface
• Usage
  • Overview
  • C++ Usage
  • MATLAB Usage
  • Point location and variable interpolation
• License
• Getting support
• Contributing
• Contributors

Installation

The Ensight4Matlab package consists of two major parts, a C++ library and a wrapper which provides a MATLAB language binding. The C++ library can be used on its own, whereas the MATLAB wrapper needs the C++ library installed first.

Requirements

The C++ library has dependencies on the following third party libraries:

• Eigen (version >= 3.2): A fast, header-only library for linear algebra, available at http://eigen.tuxfamily.org/. It should also be directly available from your distribution as package eigen3.
• Qt, either version 4 or 5.

For use with MATLAB, Qt 4 is recommended. (see below)

• OpenGL is needed for the example application.

The MATLAB wrapper depends on a compiled version of the C++ library and needs the MEX compiler to compile the MATLAB/C++ interface.

Warning: MATLAB ships with its own Qt 5 library which may be a different minor version than the one installed on your system. This may lead to version conflicts if you compile the C++ Ensight library with a Qt 5 version higher than the one provided by MATLAB. In this case, we recommend you compile with Qt 4 to avoid conflicts. Additionally, we have experienced stability problems with the R2015a/b releases of MATLAB, so we recommend against using Ensight4Matlab with these releases.

Building the EnsightLib C++ library

The EnsightLib library uses the Qt qmake build system. The library itself can be compiled alone, or also with test and example files. The easiest way to build everything at once is to run qmake on the file EnsightLibAndTests.pro in the project's root directory to create a Makefile, then run make.

> qmake-qt4 EnsightLibAndTests.pro
> make

Alternatively, you can compile just the library itself: From the directory ensight_lib first run qmake on EnsightLib.pro, then run make.

> cd ensight_lib
> qmake-qt4 EnsightLib.pro
> make

In both cases, this will create a file libEnsightLib.so in ensight_lib/lib (or a dll on Windows). The qmake-based Makefile does not create a target for make install, so you have to manually copy or link the .so file to e.g. /usr/lib if you want to make it globally accessible on your machine.

If you use a locally installed version of the Eigen library, you have to edit the include path defined in ensight_lib/EnsightLibConfig.pri. The corresponding line is:

# Include path to Eigen library: must contain the directory "Eigen/Dense"
INCLUDEPATH += /usr/include/eigen3

You can also edit the .pro file to compile a static library (instead of an .so) by uncommenting the config option:

CONFIG += staticlib

Installing the library

To use the library with MATLAB or the included examples, you need to make sure the EnsightLib library can be found. For this, you can either build the library as described above and copy it to a location in the global library search path, or use it from a local directory by specifying the LD_LIBRARY_PATH environment variable (Linux systems). For example, if the path to your compiled library is /home/USER/Ensight4Matlab/ensight_lib/lib/libEnsightLib.so, you would set the following:

> export LD_LIBRARY_PATH=/home/USER/Ensight4Matlab/ensight_lib/lib/:${LD_LIBRARY_PATH}

You can add this line to your .bashrc file to run it automatically.

If you don't install the library and also don't add set the appropriate LD_LIBRARY_PATH, the system won't be able to find the library, resulting in an error message similar to:

user:~/Ensight4Matlab/ensight_lib/examples/ensight_viewer> ./ensight_viewer
./ensight_viewer: error while loading shared libraries:
libEnsightLib.so.1: cannot open shared object file: No such file or directory

Running tests

Once you've set up your system to find the library, you can run some tests contained in directory ensight_lib/test. They are automatically build along the library if you built EnsightLibAndTests.pro, otherwise you can individually compile the same way with qmake-qt4 EnsightLibTest.pro and make as above. This will create a binary EnsightLibTest in the corresponding directory test. Before you run the tests, you also need to have unpacked the example data in data/jet.tar.bz2:

> cd data
> tar -xf jet.tar.bz2

You can also run the small examples located in ensight_lib/examples and compare the output produced by the write_file example to the reference output (ensight_lib/examples/data).

Building the MATLAB interface

To build the MATLAB interface, you need to make sure MATLAB can find the EnsightLib as described above, i.e. copy it to a global library location or set the LD_LIBRARY_PATH environment variable. This needs to be set before you start MATLAB.

Building the MATLAB interface is aided by two scripts: SETUP.m and runmex.m. In MATLAB, navigate to the EnsightMatlab directory containing these scripts, then run SETUP first followed by runmex.

The SETUP script will ask you to specify several include and library paths. These paths refer to:

• QT_INCLUDE_PATH: The include files for Qt, e.g. /usr/include
• QT_LIB_PATH: The Qt libraries, e.g. /usr/lib64
• EIGEN_PATH: The Eigen library. Same as used in your EnsightLibConfig.pri
• ENSIGHT_INCLUDE_PATH: The includes for the EnsightLib library, e.g. ../ensight_lib/include
• ENSIGHT_LIB_PATH: The path to your compiled EnsightLib library, same as specified in LD_LIBRARY_PATH above

Once you have specified these paths, call runmex to start the MEX compiler. If everything works, you get the message

MEX completed successfully.

You should also add the EnsightMatlab directory to your MATLAB search path to ensure MATLAB can find it irrespective of the current working directoy. Now run the examples to test the installation.

Usage

This package comes with a full C++ application example and two MATLAB scripts to demonstrate the usage of the library. For further details you can read the Doxygen documentation for the C++ library. The Matlab interface provides a list of available methods by typing methods EnsightLib, and help on the individual methods with help EnsightLib.METHOD, where METHOD is any of the listed methods.

Overview

A data set in EnSight Gold format describes 3D data. This data can either be static or transient, i.e. time-varying. The data consists of mesh geometry, represented as an unstructured grid, and optionally variables defined over the domain of the mesh, as well as constants. The mesh's domain is partitioned into one parts. Variables can either be scalar or vector valued. For instance, the example data set data/jet.encas contains the variables temperature and velocity, meaning each vertex of the mesh has a scalar temperature value and a 3D velocity vector.

The mesh is represented as follows: For each time step, the mesh consists of

• A list of 3D vertex coordinates
• A list of parts. In turn, each part contains lists of cells of different types, e.g. triangles, quadrangles, tetrahedra etc. Each cell is represented by indices into the coordinate list. For a complete list of available cell types see Figure 9-1 on page 9-6 of the Ensight User Manual.

Note: The EnSight Gold specification also allows structured grids. However, this functionality is not yet implemented.

On the filesystem, a data set consists of several files:

• A case file: This is the main file of the data set and describes its structure. It also contains the names of additional files. Suffix is usually .case or .encas
• One or more geometry files: Contains data of the mesh (vertex coordinates and connectivity) for each part and time step. Suffix is usually .geo or .geom
• Optionally: one or more files for each variable

C++ Usage

Examples for using the library with C++ are located in ensight_lib/examples. The directory contains several short command line examples as well as a GUI demo application. The command line examples demonstrate how to

• read and print information about a data set
• interpolate a variable in a data set
• create a data set with one part and one variable, and write the data to a file.

In addition to running the tests, you can also verify that the output produced by the write_file example is identical to the reference data by using the diff command. For a screenshot how the resulting file looks when loading in the viewer application, see Figure 3 below.

The directory ensight_lib/examples/ensight_viewer contains a demo application for the C++ library. This application is a simple OpenGL-based viewer for EnSight files. It is build using the qmake build process the same way as the EnsightLib library, see build instructions build instructions above. To run the resulting application, you also need to install the library as above.

If you have not done already, unpack the example data in data/jet.tar.bz2

> cd data
> tar -xf jet.tar.bz2

and load it in the viewer demo. You can see that the data consists of a several named parts, containing different types of cells (quadrangles, hexahedra), and several variables such as "temperature" and "velocity".

In the main window (left) you can select a representation mode, and either coloring according to a variable