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 ]

IsoSurf v1.5d Documentation

For extracting triangulated isosurfaces from blocks of data at varying resolutions, using regularised marching tetrahedra. If the resolution is higher than the inter-plane spacing, disc-guided interpolation is used to interpolate the cross-sectional data.

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

  • Obtaining, installing and running IsoSurf

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

    IsoSurf has been compiled for several environments. If none of the binary executables below are suitable for your platform, please e-mail me - since the software does not have a graphical front end, nor uses any special libraries, it is highly likely that it will compile successfully on your platform.

    Once you have downloaded the executable, unzip it using gunzip (exvept the Windows executable which is not compressed) - 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.

    Please note that IsoSurf 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 input data is first read, then thresholded at a user-defined value, resulting in a set of binary cross-sections. These cross-sections can optionally be filtered using a morphological opening and/or closing with a disc size appropriate to the sampling resolution. This operation ensures that the contours do not contain features which are smaller than the sampling resolution. If no morphological filtering is used, the original data values are used to define the location of the cross-section in each slice more accurately - this can result in smoother surfaces at very high resolution.

    Having done this, each cross-section is transformed such that pixels in the image represent the minimum distance to the contour in that image (discussed further in a technical report). This improves both the interpolation of the surface and the smoothness of the surface display.

    Surface triangulation is performed at a user-defined resolution, using regularised marching tetrahedra (described in a technical report). If this resolution is greater than the inter-plane spacing (the z resolution), then additional planes are interpolated using disc-guided interpolation (described in another technical report). For faster though less realistic results, shape-based interpolation can optionally be used instead of the previous technique. Obviously higher resolutions will lead to greater surface detail, but also greater numbers of triangles - and therefore longer processing times for visualisation.

    The filtered cross-sections are also extracted and saved to a file as vectors which can be displayed in 3-D - this can be helpful in defining a sensible threshold for the input data.

    As an extremely rough guide, triangles can be generated at about 4000 per second on typical modern hardware - plus several seconds for pre-processing (more if a very large filter is required due to a very low sampling resolution). This drops to 1000 or less triangles per second if the cross-sections also require interpolation - in this case the processing time is dependent on the complexity of the input data.

    Input data file format

    The original input data is assumed to be from a stack of parallel images, each of the same size. This is suitable for most medical imaging applications. The input data file should be structured as a `block of bytes', where the x coordinate varies fastest, then y, then z. If the input data is actually stored in one separate file per image, these files should be combined (e.g. using cat) into one file before running the program.

    The input data can be stored as unsigned char, unsigned short or signed short. The resolution need not be the same in each of the x, y and z directions - in general it is expected that the z resolution (i.e. the spacing between each image) will be less than the x and y resolution, although this is not a requirement. The x, y and z calibration, and the input data type, can be supplied as command line arguments.

    Output data file formats

    IsoSurf creates two files:

    Or, if the -v option is used, one file:

    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 format, which can be viewed by 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. The surface is guaranteed to be both manifold and closed, save that the user can optionally prevent triangulation of the first and last planes.

    The point positions are calibrated according to the user-defined scale parameters (the `-s' argument), such that the point (0,0,0) is at the origin of the input data array.

    Command line options

    Any number of command line options can be supplied, in any order, as follows:

    isosurf [-i filename] [-d x,y,z] [-f format] [-s x,y,z] [-t low,high] [-r resolution] [-m filter] [-c] [-v] [-q] [-a] [-h]

    The data dimensions (-d option) must always be supplied - all other options have default values, as listed below.

    Parameter Meaning Usage
    -i {filename} Input file name {filename} is the full name of the file containing the input data. Default is 'data.bin'.
    -d {x,y,z} Data dimensions x, y and z are the dimensions of the input data array. These are integers seperated by a comma, but no spaces. This parameter must be supplied.
    -f {format} Data format The storage type of the input data. {format} can be 'c' for unsigned char, 'u' for unsigned short or 's' for short. The default is unsigned char.
    -s {x,y,z} Data scale factors The actual physical distance represented by one step in each of the x, y and z directions. These are floats separated by a comma, but no spaces. The default is 1.0 in all directions.
    -t {low,high} Iso-surface threshold The object is extracted for which the data is greater than or equal to {low}, and less than or equal to {high}, both of which are integers. The default values are 1,255.
    -r {resolution} Sampling resolution {resolution} defines the resolution of the grid which is used to sample the data and from which the iso-surface is extracted. This is a float, in scaled units, as per the given data scale factors. Default value is 1.0.
    -m {filter} Type of filter The type of filtering operation performed on the thresholded cross-sections. {filter} can be 'o' for opening, 'c' for closing, 'b' for both or 'n' for neither. The default is both, which is appropriate for data containing small objects and holes. If neither is used, the data will not be filtered, but the grey scale values will be used to locate the cross-section more accurately within each slice.
    -c Exclude end caps Causes the first and last planes not to be triangulated.
    -v VRML output Generate VRML rather than OOGL output.
    -a Centralise the output data Causes the output mesh to be centred around the point (0, 0, 0). The scale remains unaltered.
    -q Quick interpolation If the data requires interpolation, this causes shape-based interpolation to be used, rather than the default maximal disc guided interpolation.
    -h or -? Help Displays a brief help screen.


    Try running IsoSurf on the gzipped demo data or zipped demo data, by typing this command line (after downloading and un-zipping the data) :

    isosurf -t 2,255 -i demo_data.bin -d 300,300,2 -s 1,1,30 -r 6

    This should give the contours and triangulation shown below :

    Demo data contours Demo data triangulation

    You can change the size of the triangles by altering the '-r' option. Adding the '-c' option causes the end caps not to be triangulated, as follows :

    Demo data triangulation - no caps

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