README.md 3.66 KB
Newer Older
Edward Vigmond's avatar
Edward Vigmond committed
1 2
# meshalyzer

Axel Loewe's avatar
Axel Loewe committed
3 4
Meshalyzer is a graphical program for display time dependent data on 3D finite elment meshes. Of course, it can show static data on fewer dimensions as well.
It is developed to be compatible with the cardiac simulation environment [openCARP](http://www.opencarp.org).
Edward Vigmond's avatar
Edward Vigmond committed
5

Edward Vigmond's avatar
Edward Vigmond committed
6 7 8 9
<p align="center">
  <img src="examples.png" width="1000" title="output examples" alt="examples">
</p>

Axel Loewe's avatar
Axel Loewe committed
10
It uses its own file formats which are simple and easily converted to/from more popular formats like VTK.
Edward Vigmond's avatar
Edward Vigmond committed
11 12 13 14 15

## Features

* can work with very large data files (TB)
* offscreen rendering
Axel Loewe's avatar
Axel Loewe committed
16
* isosurfaces / lines
Edward Vigmond's avatar
Edward Vigmond committed
17 18 19 20 21 22
* cutting planes
* output images (with metadata) or sequences of images to make movies
* can save state
* link multiple instances to maintain view, colour scale, etc. across them
* can display time-dependent scalar and vector data
* display auxiliary grids
23
* fly through model views
Edward Vigmond's avatar
Edward Vigmond committed
24

25 26 27 28
## Installation

Please follow steps in the [INSTALL](INSTALL.md) file.

Edward Vigmond's avatar
Edward Vigmond committed
29
## VTK formats
Edward Vigmond's avatar
Edward Vigmond committed
30

Edward Vigmond's avatar
Edward Vigmond committed
31
Support for reading the VTK formats, the legacy format (.vtk) as well the unstructured grid format (.vtu), has been included. You need to edit the **make.conf** manually to specify the directory containing the dynamically linked libraries (`VTK_LIBDIR`) and the directory with the VTK header files (`VTK_INCDIR`). They
32
are commented out by default.
Edward Vigmond's avatar
Edward Vigmond committed
33 34

For Mac users, the easiest is to install `vtk` via [homebrew](https://brew.sh/): `brew install vtk`
35

36 37
    VTK_LIBDIR = /usr/local/lib???
    VTK_INCDIR = /usr/local/include/vtk-8.?
Jorge Sanchez's avatar
Jorge Sanchez committed
38 39 40
    
## Opening the example

41 42
The `example` folder contains an ellipsoid mesh representing a simplified left ventricle. 
The mesh is provided in VTK binary and openCARP ASCII format. Additionally, you can find 
Axel Loewe's avatar
Axel Loewe committed
43
simulated transmembrane voltage data in igb format in `example/vm.igb`.
44
You can visualize these data using meshalyzer, to do that please follow the steps below:
Jorge Sanchez's avatar
Jorge Sanchez committed
45
* Open meshalyzer
46 47
* Navigate to the `example` folder and open the `ellipsoid.pts` file
* To load the simulated data on the mesh click on the `File` menu
Axel Loewe's avatar
Axel Loewe committed
48
* Click on `Read IGB data` and go to `example`
49
* Open `vm.igb`
Edward Vigmond's avatar
Edward Vigmond committed
50 51
* To do everything from the command line with the VTK mesh
    `meshalyzer ellipsoid.vtk vm.igb`
52

53 54 55
## Rendering Versions

Under Linux and Windows, rendering has been improved to take advantage of modern OpenGL features. 
Edward Vigmond's avatar
Edward Vigmond committed
56 57
This will affect chiefly lighting and rendering speed. If you are running on an Applre machine there is one additional consideration.
If your screen is a Retine display, make sure that the following is set in *make.conf*:
58

Edward Vigmond's avatar
Edward Vigmond committed
59 60 61
    HAVE_RETINE := 1

If it is not a retina screen, set this variable to 0. You will know if this setting is correct because if not, either only 1/4 of the window will be used, or you will only see one quarter of the model.
62

63 64 65 66
## Run-time issues

* Most of the time, a bad mesh or bad data file is responsible for crashes.
    Ensure that
Axel Loewe's avatar
Axel Loewe committed
67
    1. node indexing starts at 0 and the number of nodes is correct
68
    2. there are no gaps in numbering
Axel Loewe's avatar
Axel Loewe committed
69 70
    3. the data file did not get truncated. Use
    `igbhead --jive`
71 72 73
    to correct if necessary.
    4. file formats are respected.

Axel Loewe's avatar
Axel Loewe committed
74 75
* It is possible that internally, a bad memory operation is performed. Try setting
`export MALLOC_CHECK_=1`
76 77 78
and see if it disappears.

* Make sure the proper dynamic libraries are getting linked. There can be conflicts with *fltk* or *vtk* if
Axel Loewe's avatar
Axel Loewe committed
79
  multiple versions are installed. In these cases a simple solution is to write a wrapper script which
80 81 82 83 84 85 86 87 88
  properly sets the environment variables like below:

  ```bash
  #!/bin/bash
  export LD_LIBRARY_PATH=/path_to_dylib1_dir:/path_to_dylib2_dir
  /path_to_meshalyzer/meshalyzer $*
  ```


89 90
#### Acknowledgement

Axel Loewe's avatar
Axel Loewe committed
91
The broadcast symbol was provided by [Online Web Fonts](http://www.onlinewebfonts.com).