Main > GMT_EqnSurf
Dr Graham Treece, Department of Engineering
EqnSurf
For displaying isosurfaces of functions of three variables. Regularised marching tetrahedra is used to triangulate the surface. The equation is input via a flexible equation parser.
Program overview Obtaining, installing and running EqnSurf Output data file format Command line options Examples Versions
Program overview
The equation to be evaluated is supplied as a text string, with the characters '
x', '
y' and '
z' in place of the three variables. This string can contain logarithmic and trigonometric functions (including '
pi'), standard operations ('
+', '
-', '
*', '
/' and '
^' for powers) and brackets. Numbers are in floating point format, i.e. -0.001 can be entered as '
-0.001' or '
-1e-3'.
This string is first parsed to ensure priority is given to more important operators, by inserting additional brackets. For instance, the string '
-x^2-(y+1)^2-z/3*10' would be replaced by '
(((-x)^2)-((y+1)^2))-((z/3)*10)'. This ensures that the actual evaluation of the equation, which runs forwards through the string, will work correctly, i.e. 1-1-1 = (1-1)-1 = -1, rather than 1-1-1 = 1-(1-1) = 1. The equation is entered by selecting the 'File' then 'Equation' buttons:
This equation is evaluated over a user specified volume, defined by it's centre and range from this centre point. The range is supplied by pressing the 'Limits' then either of the 'x', 'y' or 'z' buttons. After changing these values, the 'Update' button must be used to update the surface:
The isosurface at a user specified threshold is extracted from this volume and triangulated using regularised marching tetrahedra at a user specified resolution, then displayed:
The surface can be rotated by using the mouse buttons, or alternatively the light can be rotated by holding down the
<ctrl> key while using the mouse buttons. There are various other functions, either available from the menu or from mouse or key presses. The latter can be displayed by pressing the 'Help' button:
For instance, the window can be dumped to a file by using the space bar. Alternatively, it is possible to display the intersection of the surface with the grids rather than the surface itself, by pressing 'Display' then 'Contour':
You can move any of the grids by clicking on them (be sure to click close to one of the blue lines) and dragging. Note that the drag works by always moving a grid one way for dragging upwards and the other way for dragging downwards, independant of the viewpoint. This is so that a grid can be moved even if you are looking directly at it. The intersections are automatically updated and displayed as the grids are moved.
If you only want to visualise the surface, the grids and axes can be turned off by pressing 'Display' then 'Axes':
If you want to take a screen shot, use 'File' then 'Save Screen' to select the file name, then the space bar to save. In the Windows version this will be saved in uncompressed 24-bit
.BMP format, in all other versions it will be saved as a
.PPM . Alternatively the surface triangulation can be saved in a 3D model format, either OOGL or VRML, using the 'File' then 'Save Surface' buttons.
Finally, use 'q', the escape key, or the 'Quit' button to exit.
Output data file formats
EqnSurf creates the file '
equation.off', or '
equation.wrl'containing the iso-surface triangulation. The former is in OOGL format, which is suitable for use with the
Geomview visualisation package, also available free for most Unix platforms. The latter is in VRML version 1.0 format, which can be viewed with any VRML viewer. The order of the vertices in each triangle is consistent, and surface normals are provided for each vertex, so the triangulation can be correctly displayed with either faceted or smooth shading.
Obtaining, installing and running EqnSurf
EqnSurf has been compiled for several environments. If none of the binary executables below are suitable for your platform, please
e-mail me - it may well be possible to compile the software for your platform.
Once you have downloaded the executable, unzip it using
gunzip (except for the Windows executable) - there is only a single file, which does not need a parameter file nor any environment variables. Options are either passed to the program as command line parameters, or can be supplied at run time.
You will also need either
OpenGL or an equivalent version - the software has been implemented on Linux using
Mesa, for instance. The windows are constructed using
GLUT (the GL Utility Toolkit), so you will need to get a copy of that too. Both Mesa and GLUT are freely available from the internet for a wide variety of platforms. Windows users will need
opengl32.dll,
glu32.dll (which are installed with Windows) as well as
glut32.dll which is available free from
GLUT for Win32.
Please note that EqnSurf is a research tool, and is intended for research / personal use only. Whilst the author would like to think it is fairly well written, it comes with no reliability guarantees - use at your own risk!
Command line options
All of the options available through the buttons can also be supplied as command line options, in any order, as follows:
eqnsurf [-l x,y,z] [-c x,y,z] [-t threshold] [-r resolution] [-v] [-h] [equation]
The equation (a string described in the program overview) must always be supplied - all other options have default values, as listed below.
| Parameter |
Meaning |
Usage |
| |
-l {x,y,z} |
Evaluation limits |
x, y and z are the limits of the evaluation volume, as offsets (in both directions) from the centre. These are floating point values seperated by a comma, but no spaces. The default is {1,1,1}. |
| |
-c {x,y,z} |
Centre of evaluation |
x, y and z are the location of the centre of the evaluation volume. These are floating point values seperated by a comma, but no spaces. The default is {0,0,0}. |
| |
-t {threshold} |
Iso-surface threshold |
The surface is extracted for which the equation is greater than or equal to {threshold}, which is a floating point value. The default value is 0. |
| |
-r {resolution} |
Sampling resolution |
{resolution} defines the resolution of the grid which is used to evaluate the equation and from which the iso-surface is extracted. This is a floating point value. The default value is 0.04. |
| |
-v |
VRML format |
Causes output to be generated in VRML rather than OOGL format. |
| |
-h or -? |
Help |
Displays a brief help screen. |
Examples
Running eqnsurf using the command line :
eqnsurf "(3-3*x)^2*exp(-x^2-(y+1)^2) - 10*(x/5-x^3-y^5)*exp(-x^2-y^2) - 1/3*exp(-(x+1)^2-y^2) - 3*z" -l 3,3,6 -r 0.2
or :
eqnsurf "(x^2+y^2+z^2-0.5)*(x-0.2)*(y-0.1)" -t 0.01 -r 0.08
will give the triangulations shown below :
Versions
Version 2.4 - January 2001
Compiled and tested Linux version for XFree 4.0, using Direct Rendering.
- Coordinates in output file are now correct, rather than arbitrarily scaled.
- Can now choose to output screen dumps in either PPM or BMP formats.
Version 2.3 - September 2000
Changed operation of text boxes within the menus, such that new data is
entered if the box is un-selected, not just on pressing .
Version 2.2 - June 2000
Can now generate equation triangulation in VRML version 1.0 as well as
in OOGL.
- Windows version now writes .BMP files as the screen dump rather than .PPM files, since that seemed more useful.
Version 2.1 - April 2000
Major re-write of the command / response structure to allow sensible
compilation under Windows 95/98/NT. Arguments can now be set via a
menu system, and diagnostic output and errors are displayed in the
window.
- Updated the function to clip the surface to the bounds provided by the axes. Now works in all situations - hence removed the 'fudge' parameter '-p'.
- Various other source only updates to allow compilation under Windows 95/98/NT.
Version 2.0 - February 2000
Added a graphical back end, using OpenGL and GLUT. Once equation surface
has been calculated, now opens a window to display the surface, in
which it can be manipulated and intersected with the 'x', 'y' and
'z' axes.
Version 1.1 - August 1999
First public release.
