MESH: Measuring Error between Surfaces using the Hausdorff distance

                         ------------------------

The MESH tool measures the distance between two discrete surfaces described as
triangular meshes. The topology of the meshes needs not be the same, arbitrary
topologies can be compared.

* Requirements
To compile the program the Qt libraries, version 2.3.0 or later with the
support OpenGL compiled in, are required, in addition to a C and C++ compiler.
The Qt library source code can be downloaded for free at Trolltech's website 
(http://www.trolltech.com/developer/download ) for all the Unix-like systems. 
For Windows users, a precompiled Qt v2.3.0 is also available for free 
(provided it is used for non-commercial purposes). 
The MESH tool works identically with both *nix/Windows versions of Qt. We 
have been able to compile and run it successfully under Linux, Solaris 5.8, 
IRIX 6.5, Windows 98/Me/2000.
The MESH tool has also been tested to work using Qt version 3. You need to
have at least Qt 3.0.2 to make MESH work properly (due to layout bugs in
Qt 3.0.x, x < 2).

* Installation - Unix
The QTDIR environment variable should point to the QT installation directory.
Type 'make all' at the command prompt and the executable, mesh, will be
installed in the ./bin directory. To get a command line syntax, type
'./bin/mesh -h' at the command line prompt. The current Makefile requires
GNU make and supports Linux (with GCC), IRIX (with the MIPSPro compilers) 
and Solaris (with the Sun compiler). Other configurations might require some 
(hopefully minor) modifications.

* Specific notes for RedHat/Fedora :
      - If you experience crashes and/or various troubles with OpenGL apps, 
	and you are using NVidia's driver, please check that you are using 
	*recent* drivers (version 1.0-4191 or more, apparently they solved
	quite some issues in this release).
      - With Fedora 2, you have to use different compilation flags:
	 o line 355, replace "-lqt" with "-lqt-mt" in the LDLIBS value
	 o line 280, add a "-Wno-long-long" to the WARN_CXX_FLAGS value

* Notes for using Intel compiler (ICC) or Portland Group compiler (PGCC)
This section only applies for Linux. The Makefile will try to detect your
CPU model via '/proc/cpuinfo'. You can always override the detection by
setting the 'CPU' variable for your target machine after the detection 
code (around line 100).

* Installation - Windows
You *MUST* install the Qt library prior to any other step. Please note that 
you have to install it in a path that does not contain a space (e.g. not 
in 'C:\Program Files\Qt', but for instance in 'C:\Qt'). We provide the 
Micro$oft Visual C++ 6 dsp and dsw files needed to build the program.

* Input data format 
The input file format for the triangular meshes is a raw ASCII or binary
format, VRML2, Inventor 2.x, PLY ASCII format, SMF format (used by
M. Garland's 'QSlim') and Geomview's OFF (ASCII) format. 
On systems having zlib (>= 1.1) installed, MESH
offers the possiblity of directly reading gzipped files (gzipped VRML
is in the standard). Please note that most of Win32 systems do not
have zlib installed. Therefore, on such systems, the program is build
without this support for gzipped files.  However, it is possible to
install zlib on Win32 systems. If you did so, and wish to build MESH
with zlib on Win32 system, uncomment the relevant part in
'lib3d/include/model_in.h' (lines 83-85), tweak the project files, and
please provide feedback to us about your successes/failures. We have
been able to make it work, but this has not been 'automated' in the
build process under VC++ (this is your chance to add your name in the
author list ;-).


* The raw ASCII format describes the vertices, the vertex connectivity
and optionally the vertex normals. The first line should contain two to four
decimal numbers with the number of vertices, the number of triangles, the
number of vertex normals and face normals (if they are present). If the vertex
(face) normals are present, their number must equal the number of vertices
(faces). Follow the X, Y, Z affine coordinates for each vertex and then the
indices of the three vertices of each triangular face. The vertex indices are
zero based. If the vertex normals are given follows the X, Y, Z affine
coordinates of the vertex normal vectors, in the same order as the vertices.
If the face normals are given, they follow in the same format. The normal
vectors should all be normalized. 
* The raw binary format follows the same structure as its ASCII counterpart
above but provides for much faster I/O. However, these files are not portable
between machines. The first line must contain four decimal numbers and be
followed by the string 'bin'. If the vertex or face normals are not given
their number should be zero. Then follows a fixed 32 bit word to detect
endianness (i.e. byte order) changes and another 32 bit word to detect changes
in floating-point format (although the detection is not fool-proof, see the
source of model_in_raw.c for the exact values). Then follow all the vertex
coordinates, as 32 bit floats, the vertex indices of each face as 32 bit ints.
If the vertex normals are given they follow in the same format as the vertex
coordinates, and likewise for the face normals. The normal vectors should all
be normalized.
* The VRML2 parser reads IndexedFaceSet nodes, ignoring all
transformations, and does not support USE tags (DEF tags are ignored). Only
triangular meshes are accepted.
* The Inventor parser only reads the Coordinate3-point and 
IndexedFaceSet-coordIndex nodes. It will ignore all other fields, 
icluding Normal vectors.
* The SMF parser will *only* read vertices and triangular faces. It
will ignore everything else in the SMF specification (bindings, colors, 
transforms, begin/end ...).
* The PLY parser only reads vertices and triangular faces. It will not
read any unneeded 'property' field. The ASCII and binary format are
supported. If a binary model cannot be read, try to hand-edit the
header, turning the 'binary_big_endian' field into
'binary_little_endian' (or the contrary). This often occurs if you use
the 'ply2binary' tool, provided with the PLY package, which does not
test the endianness of the platform on which it is run. As a
consequence, if you run it under Linux (or another little-endian
platform), you will end up with a 'binary_big_endian' in your header,
whereas the bytes (written using 'fwrite') are in little-endian
order...
* The OFF parser only supports triangular faces and ignores all additional
  info, such as normals, colors. This reader in no case supports the full
  OFF spec, but should work for the most common cases.


Please report any bugs or comments to:

	Nicolas Aspert <[email protected]>