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 ]

VolMorph v2.4b Documentation

For generating and visualising morphing sequences from one polygonal mesh to another. The morphing sequences are generated using maximal disc (or sphere in this case) shape-based interpolation, and triangulated using regularised marching tetrahedra. The whole process is described in detail in a technical report.

  • Obtaining, installing and running VolMorph
  • Program overview
  • Output data file formats
  • Command line options
  • Examples

  • Obtaining, installing and running VolMorph

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

    VolMorph 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. All options are passed to the program as command line parameters.

    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.

    Since OOGL models are not widely available on the internet, I have also written a utility to convert from 3DS format to OOGL, which can handle colours but not texture maps. This is a single 'C' file, which you are welcome to download and compile, though I would ask that you send me a copy if you manage to make it work better than I have! There is help available by using the '-h' command line option.

    Please note that VolMorph 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

    VolMorph can be started simply be running the program - there are some command line options, however these can also be entered at run time, and in any case the default values are usually appropriate. Once started, volmorph displays an empty 'chess board'. Files are loaded by using the 'File' then 'Open' buttons, and entering the 'Source' and 'Target' file names. Once these have been entered, each object is first sampled to three-dimensional arrays where each cell contains the distance to the original polygon. With antialiasing enabled (the default option), this array need not be that large to give a good quality morph - typically only 40 x 40 x 40 is sufficient, though this is dependent on the complexity of the models. Interpolation is then performed on these arrays, and both the original and intermediate surfaces are re-triangulated from this data using regularised marching tetrahedra, so that the morph sequence can be manipulated in real time.

    Once the source and target files have been sampled and triangulated, they are both displayed:

    Morphing start display

    The source surface is shown in translucent red, and the target surface in translucent green. At this point, a set of vectors can be created which link the source surface to the target surface, to provide some indication of how the morph should work. This is done simply by clicking and dragging:

    Morphing manual vectors

    Each vector is shown in blue, with the end points in green or red to indicate which surface they are connected to. This can be more easily seen by turning the display of the base off at this point, and setting the background colour to white, both through the `Display' option.

    Manual vector definition is only necessary on quite complex surfaces, since the second step, which is accessed by pressing <enter>, provides automatic definition of how the surfaces should be connected. In this stage, a set of spheres are estimated for each surface, which approximately represent the surface. These spheres enable a set of vectors to be calculated which indicate how the source and target surfaces should be connected - these vectors are used to guide the creation of the morphing sequence:

    Morphing automatic vectors

    Each vector is shaded from red to green, such that the direction of interpolation is clear. The number of vectors, and the distance over which they can connect the objects, can be controlled by using the '+', '-', '<' or '>' keys - '+' and '-' control the connectivity, whilst '<' and '>' control the number of spheres (and hence also vectors). In addition, individual vectors can be deleted by clicking on them (although they will re-appear if the connectivity is subsequently changed). Note that if the '-q' command line option was used, no vectors will be displayed.

    Help on what each key is used for is available at any time by pressing the 'Help' button:

    Morphing help

    Once the vectors look sensible, the morphing sequence can be initiated by pressing <enter>. Intermediate surfaces are then interpolated and triangulated, and displayed in the window as they are created. This will take anything from one minute upwards, dependent on the size of the volume, the number of vectors and the number of intermediate frames.

    After the intermediate surfaces have been created, the morph from the initial to the final surface is displayed in the window in real time. This means that the viewpoint can be moved, the lighting altered etc. while the surface is morphing. The video shown below is an example of this window running at actual speed (although the quality is much better in reality - the video quality has been compromised to make downloading easier):

    Morphing Window

    The viewpoint, lighting and model position can all be changed with the mouse. The left and right buttons rotate the scene, and the middle button moves it. If the <ctrl> key is held down during mouse presses, the action is to the light source, and if the <shift> key is held down, the action is to the object itself. Note that in all these cases, the movement will continue beyond mouse button release if the mouse was moving during release - i.e. the viewpoint, lighting and object position can be set in motion by use of the mouse.

    There are also other options, for instance the shadow can be turned on or off by pressing 'Display' then 'Shadow', and the window can be dumped to a sequence of files (to generate a movie) by using the space bar. In addition, the surfaces which make up the 3D morphing sequence can be written to OOGL or VRML format files while the morph is being created.

    The window will return to automatic vector definition mode by pressing <backspace>, and to the manual vector definition mode by pressing <backspace> again. Use <esc>, 'q' or the 'Quit' button to exit.


    Output data file formats

    VolMorph can output the morphing sequence in a sequence of files containing the surface triangulation, 'name###.off', or 'name###.wrl' where ### is the frame number and name is supplied by the user. The former are in OOGL format, which is suitable for use with the Geomview visualisation package, also available free for most Unix platforms. The latter are in VRML version 1.0, which can be viewed with any VRML viewer. The sphere representations can also be output as 'sphere###.sph' or 'sphere###.wrl'. 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.

    Note that these surface are output as the display lists are created - so, for instance, the sphere representations will only be output if (at some point) you view this representation.

    It is also possible to dump a sequence of images 'morph###.ppm', or 'morph###.bmp' of the VolMorph window - this feature is toggled on and off using the space bar. These images are in PPM format (except for the Windows version, which write in BMP format), which is just a sequence of bytes, one each for red, green and blue, giving three for each pixel. The file starts with a textual header indicating the type and size, and the source of the data. These files can be used to generate a movie of the morph sequence, for instance using SGI's dmconvert, or the freely available mpeg_encode.


    Command line options

    All of the options available through the buttons can also be supplied, in any order, as follows:

    volmorph [-o filename] [-v] [-f frames] [-p points] [-r resolution] [-c] [-z] [-a distance] [-q] [-h] [initial_file] [final_file]

    The initial and final files (in OOGL format) must always be supplied - all other options have default values, as listed below.

    Parameter Meaning Usage
     
    -o {filename} output file name {filename} defines the root of the output files containing the interpolated surfaces. The default is not to write output files.
     
    -v VRML format Output triangulation in VRML rather than OOGL format.
     
    -f {frames} interpolated frames {frames} defines the number of interpolated surfaces (inclusive) between the inital and final surfaces. Default is 20.
     
    -p {points} sampling points {points} sets the minimum number of points, in any direction, used to sample the initial and final files. The default is 20.
     
    -r {resolution} triangulation resolution {resolution} defines the resolution of the surface triangles compared to the sampled volume. The default value is 1. Larger values reduce the number of triangles (and the quality of the surface).
     
    -c scale centres Causes the initial and final surface to be translated such that the centres are coincident, before interpolating. Default is not to.
     
    -z scale centres and size Causes both the centre and size of the intial and final surfaces to be translated and scaled respectively. This is the default option.
    -a {distance} antialias surfaces Causes the sampled volumes to be initialised with the actual geometric distance from the input polygons, to a distance of {distance} voxels. Greatly improves the quality of the surfaces. Default is 1.1 - setting {distance} to 0 disables.
    -q quick interpolation Disables the use of vectors in the interpolation and defaults to shape-based interpolation. Default is to use vectors.
    -h or -? Help Displays a brief help screen.

    Examples

    Try running volmorph on the queen and pawn models, or a zipped version of both of them (after downloading and unzipping them), by using the command:

    volmorph white_pawn.off black_queen.off

    By increasing the connectivity of the vectors, you should be able to obtain a morph like that shown below:

    Initial morph Middle morph Final morph

    Alternatively, if you turn off the use of vectors, using the '-q' option:

    volmorph -q white_pawn.off black_queen.off

    This will generate a much poorer morphing sequence:

    Initial morph Middle morph Final morph

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