Main > GMT_IsoSurf
Dr Graham Treece, Department of Engineering
IsoSurf
Note that the functionality in this software is now available (and in many ways improved) in Stradview, which is much more powerful and has a much nicer interface. The only reason for continuing to use IsoSurf is if you need a command-line function.
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.
Program overview Obtaining, installing and running IsoSurf Input data file format Output data file formats Command line options Examples Versions
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.
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 (except 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!
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:
-
surface.off - the iso-surface triangulation in OOGL format, and
-
contours.off - the cross-sectional vectors in OOGL format - note that these will not be valid if the -m n option is used.
Or, if the
-v option is used, one file:
-
surface.wrl - the iso-surface triangulation in VRML format
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. |
Examples
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 :
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 :
Versions
Version 1.5c and d - September 2001
(d) fixed a bug when reading input files in Windows, and added
a high and a low threshold.
- (c) fixed a bug in thresholding introduced since version 1.5, leading to the generation of mesh-like surfaces.
Version 1.5b - August 2001
correct treatment of thresholds which exclude all data from
any particular slice of the volume.
Version 1.5 - May 2001
`-a' option added to centralise the output data around the
location (0,0,0).
- If no morphological filtering is used (i.e. `-m n'), the data values are used to locate the cross-section in each slice more precisely. This can result in smoother surfaces when using high resolutions.
Version 1.4 - September 2000
Co-ordinates of the vertices in the output surface shifted such that they can
be registered with the input data array. (0,0,0) is now at the start of the array.
- More information provided in the error messages.
Version 1.3 - June 2000
Can now write the surface triangulation in VRML version 1.0 format
as well as OOGL format. Added option '-v' for this purpose.
- Removed artificial limit on the number of maximal discs that can be extracted from each cross-section.
Version 1.2 - April 2000
Source only update to allow compilation under Windows 95/98/NT.
Version 1.1 - August 1999
First public release.
Version 1.0
Original private version.
