Search Contact information
University of Cambridge Home Department of Engineering
University of Cambridge > Engineering Department > Machine Intelligence Lab > Medical Imaging Group

Graham Treece

[ Introduction | Teaching | Research | Publications | Software | Videos | Personal ]

EqnSurf v2.4 Documentation

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.

  • Obtaining, installing and running EqnSurf
  • Program overview
  • Output data file format
  • Command line options
  • Examples

  • Obtaining, installing and running EqnSurf

    See the revisions page for the new features and fixes in this version.

    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!


    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:

    EqnSurf Equation

    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:

    EqnSurf Updating

    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:

    EqnSurf Start

    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.


    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 :

    Triangulated peaks surface Triangulated 'bubble' surface

    © 2005 Cambridge University Engineering Dept and Graham Treece .
    Information provided by gmt11