admesh-doc.txt

Note:  This manual is slightly out of date.  Specifically it doesn't
mention OFF, VRML, or DXF files.  However, there isn't much to know about
these options.  If you just type 'admesh --help' a list of options will be
printed.

This document describes the use of ADMesh version 0.93. ADMesh is a program
for processing triangulated solid meshes. Currently, ADMesh only reads the
STL file format that is used for rapid prototyping applications, although it
can write STL, VRML, OFF, and DXF files.

For information about compiling ADMesh, see the file INSTALL.  The file
README contains a brief description of ADMesh along with its features and
capabilities.

ADMesh is Copyrighted software and is distributed under the terms of the GNU
General Public License.  See the file COPYING for license information.

Invoking ADMesh
===============

ADMesh is executed as follows:
   admesh [OPTION]... file

By default, ADMesh performs all of the mesh checking and repairing options
on the input file.  This means that is checks exact, nearby,
remove-unconnected, fill-holes, normal-directions, and normal-values.  The
file type (ASCII or binary) is automatically detected.  The input file is
not modified unless it is specified by the --write option.  If the following
command line was input:
   admesh sphere.stl
The file sphere.stl would be opened and read, it would be checked and fixed
if necessary, and the results of processing would be printed out.  The
results would not be saved.

The default value for tolerance is the length of the shortest edge of the
mesh.  The default number of iterations is 2, and the default increment is
0.01% of the diameter of a sphere that encloses the entire mesh.

If any of the options --exact, --nearby, --remove-unconnected, --fill-holes,
--normal-directions, --reverse-all, --normal-values, or --no-check are
given, then no other checks besides that one will be done unless they are
specified or unless they are required by ADMesh before the specified check
can be done.  For example the following command line:
   admesh --remove-unconnected sphere.stl
would first do an exact check because it is required, and then the
unconnected facets would be removed.  The results would be printed and no
other checks would be done.

Examples
========

To perform all checks except for nearby, the following command line would be
used:
   admesh --exact --remove-unconnected --fill-holes \
          --normal-directions --normal-values sphere.stl

Actually, since the exact check is required by ADMesh before
remove-unconnected, and remove-unconnected is required before --fill-holes,
the above command line could be shortened as follows with the same results:
   admesh --fill-holes --normal-directions --normal-values sphere.stl

And again the same results could be achieved using the short options:
   admesh -fudev sphere.stl
or
   admesh -fdv sphere.stl
   
The following command lines do the same thing:
   admesh sphere.stl
   admesh -fundev sphere.stl
   admesh -f -u -n -d -e -v sphere.stl
since the -fundev options are implied by default.  To eliminate one of the
checks, just remove the letter of the check to eliminate from the "word"
'fundev'.

About

Option Summary
==============

ADMesh supports the following options, grouped by type.

*Mesh Transformation and Manipulation Options*
     --x-rotate=angle     Rotate CCW about x-axis by angle degrees
     --y-rotate=angle     Rotate CCW about y-axis by angle degrees
     --z-rotate=angle     Rotate CCW about z-axis by angle degrees
     --xy-mirror          Mirror about the xy plane
     --yz-mirror          Mirror about the yz plane
     --xz-mirror          Mirror about the xz plane
     --scale=factor       Scale the file by factor (multiply by factor)
     --translate=x,y,z    Translate the file to x, y, and z
     --merge=name         Merge file called name with input file

*Mesh Checking and Repairing Options*
 -e, --exact              Only check for perfectly matched edges
 -n, --nearby             Find and connect nearby facets. Correct bad facets
 -t, --tolerance=tol      Initial tolerance to use for nearby check = tol
 -i, --iterations=i       Number of iterations for nearby check = i
 -m, --increment=inc      Amount to increment tolerance after iteration=inc
 -u, --remove-unconnected Remove facets that have 0 neighbors
 -f, --fill-holes         Add facets to fill holes
 -d, --normal-directions  Check and fix direction of normals(ie cw, ccw)
     --reverse-all        Reverse the directions of all facets and normals
 -v, --normal-values      Check and fix normal values
 -c, --no-check           Don't do any check on input file

*File Output Options*
 -b, --write-binary-stl=name   Output a binary STL file called name
 -a, --write-ascii-stl=name    Output an ascii STL file called name

*Miscellaneous Options*
     --help               Display this help and exit
     --version            Output version information and exit







Mesh Transformation and Manipulation Options
============================================

'--x-rotate=angle'
'--y-rotate=angle'
'--z-rotate=angle'
   Rotate the entire mesh about the specified axis by the given number of
   degrees.  The rotation is counter-clockwise about the axis as seen by
   looking along the positive axis towards the origin, assuming that the
   coordinate system is as follows:

         y^
	  |
	  |   
	  |   
	  +------->
         /        x
	/
      z/

'--xy-mirror'
'--yz-mirror'
'--xz-mirror'
   Mirror the mesh about the specified plane.  Mirroring involves reversing
   the sign of all of the coordinates in a particular axis.  For example, to
   mirror a mesh about the xy plane, the signs of all of the z coordinates
   in the mesh are reversed.

'--scale=factor'
   Scale the mesh by the given factor.  This multiplies all of the
   coordinates by the specified number.  This option could be used to change
   the "units" (there are no units explicitly specified in an STL file) of
   the mesh.  For example, to change a part from inches to millimeters, just
   use the --scale=25.4 option.

'--translate=x,y,z'
   Translate the mesh to the position x,y,z.  This moves the minimum x, y,
   and z values of the mesh to the specified position.  For example, given a
   mesh that has the following initial minimum and maximum coordinate values:
      Min X =  4.000000, Max X =  5.000000
      Min Y =  1.000000, Max Y =  3.000000
      Min Z = -7.000000, Max Z = -2.000000
   if the option --translate=1,2,3 is specified, the final values will be:
      Min X =  1.000000, Max X =  2.000000
      Min Y =  2.000000, Max Y =  4.000000
      Min Z =  3.000000, Max Z =  8.000000
   The translate option is often used to translate a mesh with arbitrary
   minimum and maximum coordinates to 0,0,0.  Usually, translation is also
   required when merging two files.

'merge=name'
   Merge the specified file with the input file.  No translation is done, so
   if, for example, a file was merged with itself, the resulting file would
   end up with two meshes exactly the same, occupying exactly the same
   space.  So generally, translations need to be done to the files to be
   merged so that when the two meshes are merged into one, the two resulting
   parts are properly spaced.  If you know the nature of the parts to be
   merged, it is possible to "nest" one part inside the other.  Note,
   however, that no warnings will be given if one part intersects with the
   other.  

   It is possible to place one part against another, with no space in
   between, but you will still end up with two separately defined parts. If
   such a mesh was made on a rapid-prototyping machine, the result would
   depend on the nature of the machine.  Machines that use a photopolymer
   would produce a single solid part because the two parts would be "bonded"
   during the build process.  Machines that use a cutting process would
   yield two or more parts.

   A copy of a mesh can be made by using the --merge and --translate options
   at the same time.  For example, given a file called block.stl with the
   following size:
      Min X =  0.000000, Max X =  2.000000
      Min Y =  0.000000, Max Y =  2.000000
      Min Z =  0.000000, Max Z =  2.000000

   to create a file called 2blocks.stl that contains two of the parts
   separated by 1 unit in the x direction, the following command line would
   be used:
      admesh 
      --translate=3,0,0 --merge=block.stl --write-binary=2blocks.stl block.stl

   This would yield a binary STL file called 2blocks.stl with the following
   size:
      Min X =  0.000000, Max X =  5.000000
      Min Y =  0.000000, Max Y =  2.000000
      Min Z =  0.000000, Max Z =  2.000000
      

Mesh Checking and Repairing Options
===================================

'-e', '--exact'
   Check each facet of the mesh for its 3 neighbors.  Since each facet is a
   triangle, there should be exactly 3 neighboring facets for every facet in
   the mesh.  Since the mesh defines a solid, there should be no unconnected
   edges in the mesh.  When this option is specified, the 3 neighbors of
   every facet are searched for and, if found, the neighbors are added to an
   internal list that keeps track of the neighbors of each facet.  A facet
   is only considered a neighbor if two of its vertices EXACTLY match two of
   the vertices of another facet.  That means that there must be 0
   difference between the x, y, and z coordinates of the two vertices of the
   first facet and the two vertices of the second facet.

   Degenerate facets (facets with two or more vertices equal to each other)
   are removed during the exact check.  No other changes are made to the
   mesh.  An exact check is always done before any of the other checking and
   repairing options even if --exact isn't specified.  There is one
   exception to this rule; no exact check needs to be done before the
   --normal-values option.

'-n', '--nearby'
'-t', '--tolerance=tol'
'-i', '--iterations=i'
'-m', '--increment=inc'
   Checks each unconnected facet of the mesh for facets that are almost
   connected but not quite.  Due to round-off errors and other factors, it
   is common for a mesh to have facets with neighbors that are very close
   but don't match exactly.  Often, this difference is only in the 8th
   decimal place of the vertices, but these facets will not show up as
   neighbors during the exact check.  This option finds these nearby
   neighbors and it changes their vertices so that they match exactly.  The
   exact check is alway done before the nearby check, so only facets that
   remain unconnected after the exact check are candidates for the nearby
   check.

   The --tolerance=tol option is used to specify the distance that is
   searched for the neighboring facet.  By default, this value is set
   automatically by ADMesh to be the length of the shortest edge of the
   mesh. This value is used because it makes it unlikely for a facet that
   shouldn't be a neighbor to be found and matched as a neighbor.  If the
   tolerance is too big, then some facets could end up connected that should
   definitely not be connected.  This could create a "mobius part" that is
   not a valid solid. If this occurs, it can be seen by checking the value
   of "Backwards edges" that is printed after processing.  (The number of
   backwards edges should be 0 for a valid solid.)

   The --iterations=i and --increment=inc options are used together to
   gradually connect nearby facets using progressively larger tolerances.
   This helps to prevent incorrect connects but can also allow larger
   tolerances to be used.  The --iterations option gives the number of times
   that facets are checked for nearby facets, each time using a larger
   tolerance.  The --increment=inc option gives the amount that the
   tolerance is increased after each iteration.  The number specified by
   'inc' is added to the tolerance that was used in the previous iteration.
   If all of the facets are connected, no further nearby checks will be
   done.

'-f', '--fill-holes'

   Fill holes in the mesh by adding facets.  This is done after the exact
   check and after nearby check (if any nearby check is done).  If there are
   still unconnected facets, then facets will be added to the mesh,
   connecting the unconnected facets, until all of the holes have been
   filled.  This is guaranteed to completely completely fix all unconnected
   facets.  However, the resulting mesh may or may not be what the user
   expects.

'-d', '--normal-directions'

   Check and fix if necessary the directions of the facets.  This only deals
   with whether the vertices of all the facets are oriented clockwise or
   counterclockwise, it doesn't check or modify the value of the normal
   vector.  Every facet should have its vertices defined in a
   counterclockwise order when looked at from the outside of the part.  This
   option will orient all of the vertices so that they are all facing in the
   same direction.  However, it it possible that this option will make all
   of the facets facet inwards instead of outwards.  The algorithm tries to
   get a clue of which direction is inside and outside by checking the value
   of the normal vector so the chance is very good that the resulting mesh
   will be correct.  However, it doesn't explicitly check to find which
   direction is inside and which is outside.  In the future, I might write
   code to explicitly check for the inside and the outside, but until then,
   the current algorithm gets it right most of the time.

'--reverse-all'
   Reverses the directions of all of the facets and normals.  If the
   --normal-directions option ended up making all of the facets facet
   inwards instead of outwards, then this option can be used to reverse all
   of the facets.  It is up to the user to determine if the facets are
   facing inwards and if they need reversing.  In future versions of ADMesh,
   this process may be automated.  This option also fixes and updates the
   normal vector for each facet.

'-v', '--normal-values'
   Checks and fixes if necessary the normal vectors of every facet.  The
   normal vector will point outward for a counterclockwise facet.  The
   length of the normal vector will be 1.

'-c', '--no-check'
   Don't do any checks or modifications to the input file.  By default,
   ADMesh performs all processes (exact, nearby, remove_unconnected,
   fill-holes, normal-directions, and normals-values) on the input file.  If
   the --no-check option is specified, no checks or modifications will be
   made on the input file.  This could be used, for example, to translate an
   ASCII STL file to a binary STL file, with no modifications made.  A
   command line such as the following might be used:
      admesh
      --no-check --write-binary-stl=newblock.stl --translate=0,0,0 block.stl
   This would open the file block.stl, would translate it to 0,0,0 no checks
   would be performed and a binary STL file of the translated mesh would be
   written to newblock.stl.

'-b', '--write-binary-stl=name'
'-a,' '--write-ascii-stl=name'
   Write a binary STL file with the name specified.  The input file is not
   modified by ADMesh so the only way to preserve any modifications that
   have been made to the input file is to use one of the --write options. If
   the user wants to modify (overwrite) the input file, then the input file
   can also be specified for the --write option.  For example, to convert an
   input ASCII STL file called sphere.stl to a binary STL file, overwriting
   the original file, and performing no checks, the following command line
   would be used:
      admesh --write-binary-stl=sphere.stl --no-check sphere.stl

'--help'
   Display the possible command line options with a short description, and
   then exit.

'--version'

   Show the version information for ADMesh, and then exit.


ADMesh Output
=============

After ADMesh has processed a mesh, it prints out a page of information about
that mesh.  The output looks like the following:

================= Results produced by ADMesh version 0.95 =================
Input file         : sphere.stl
File type          : Binary STL file
Header             : Processed by ADMesh version 0.95
============== Size ==============
Min X = -1.334557, Max X = 1.370952
Min Y = -1.377953, Max Y = 1.377230
Min Z = -1.373225, Max Z = 1.242838
========= Facet Status ========== Original ============ Final ====
Number of facets                 :  3656                3656
Facets with 1 disconnected edge  :    18                   0
Facets with 2 disconnected edges :     3                   0
Facets with 3 disconnected edges :     0                   0
Total disconnected facets        :    21                   0
=== Processing Statistics ===     ===== Other Statistics =====
Number of parts       :     1        Volume   :  10.889216
Degenerate facets     :     0
Edges fixed           :    24
Facets removed        :     0
Facets added          :     0
Facets reversed       :     0
Backwards edges       :     0
Normals fixed         :     0

Description of Output
====================

The following describes the output information line by line.

Input file         : sphere.stl
   The name of the file that was read.
   
File type          : Binary STL file
   The type of file.  Currently, the only two possibilities are Binary STL
   file and ASCII STL file.  ADMesh automatically detect the type of input
   file.

Header             : Processed by ADMesh version 0.95
   The first 80 characters of the STL file.  The first 80 bytes of a binary
   STL file or the first line of an ASCII STL file can contain some text.
   Usually, the CAD system that has created that file, or the last program
   to process that file puts its name in the header.  ADMesh puts its own
   string in the header when it saves the file.
   
============== Size ==============
Min X = -1.334557, Max X = 1.370952
Min Y = -1.377953, Max Y = 1.377230
Min Z = -1.373225, Max Z = 1.242838
   This section gives the boundaries of the mesh.  The mesh will fit just
   inside a box of this size.
   
========= Facet Status ========== Original ============ Final ====
Number of facets                 :  3656                3656
Facets with 1 disconnected edge  :    18                   0
Facets with 2 disconnected edges :     3                   0
Facets with 3 disconnected edges :     0                   0
Total disconnected facets        :    21                   0
   Information about the quality of the mesh before, and after processing by
   ADMesh.  The number of facets gives an idea about the complexity and
   accuracy of the mesh.  Disconnected facets will fall into 3 categories.
   Some facets will have only one disconnected edge, some will have 2 edges
   disconnected, and some will have all 3 edges disconnected.  Of course,
   for a valid solid mesh, there should be 0 disconnected facets.
   
=== Processing Statistics ===
Number of parts       :     1
   This is the total number of separate parts in the file.  This can be a
   very useful indication of whether your file is correct.  Sometimes, the
   user of the CAD system that creates the mesh just puts several pieces
   together next to each other, and then outputs the mesh.  This might not
   cause any problems for a rapid prototyping system that uses a
   photopolymer because all of the parts will be "glued" together anyway
   during the build. However, a rapid prototyping machine that is based on
   cutting will cut each one of the parts individually and the result will
   be many parts that need to be glued together.  The number of parts is
   counted during --normal-directions, so if the --normal-directions check
   is eliminated, then the number of parts will read 0.

Degenerate facets     :     0
   Number of degenerate facets in the input file.  A degenerate facet is a
   facet that has two or more vertices exactly the same.  The resulting
   facet is just a line (if two vertices are the same) or could even be a
   point (if all 3 vertices are the same).  These facets add no information
   to the file and are removed by ADMesh during processing.
   
Edges fixed           :    24
   The total number of edges that were fixed by moving the vertices slightly
   during the nearby check.  This does not include facets that were added by
   --fill-holes.
   
Facets removed        :     0
   The total number of facets removed.  There are two cases where facets
   might be removed.  First, all degenerate facets in the input file are
   removed.  Second, if there are any completely unconnected facets (facets
   with 3 disconnected edges) after the exact and nearby checks, then these
   facets will be removed by --remove-unconnected.
   
Facets added          :     0
   Number of facets that have been added by ADMesh to the original mesh.
   Facets are only added during --fill-holes.  So this number represents the
   number of facets that had to be added to fill all of the holes, if any,
   in the original mesh.

Facets reversed       :     0
   The number of facets that were reversed during --normal-directions.  This
   only relates to the order of the vertices of the facet (CW or CCW), it
   has nothing to do with the value of the normal vector.

Backwards edges       :     0
   The number of edges that are backwards.  After ADMesh has finished all of
   the checks and processing, it verifies the results.  If the
   normal-directions check has been done then the NUMBER OF BACKWARDS EDGES
   SHOULD BE 0.  If it is not, then a "mobius part" has been created which
   is not a valid solid mesh.  In this case the mesh can be processed again,
   but a smaller tolerance on the nearby check should be used or no nearby
   check should be done.
   
Normals fixed         :     0
   The number of normal vectors that have been fixed.  During the
   normal-values check, ADMesh calculates the value of every facet and
   compares the result with the normal vector from the input file.  If the
   result is not within a fixed tolerance, then the normal is said to be
   fixed. Actually, for consistency, every normal vector is rewritten with
   the new calculated normal, even if the original normal was within
   tolerance. However, the normals that were within tolerance are not
   counted by normals fixed.