ADMesh - STL mesh manipulation tool¶

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.

Options¶

ADMesh supports the following options, grouped by type.

--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

-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

-b, --write-binary-stl=name   Output a binary STL file called name
-a, --write-ascii-stl=name    Output an ASCII STL file called name
    --write-off=name          Output a Geomview OFF format file called name
    --write-dxf=name          Output a DXF format file called name
    --write-vrml=name         Output a VRML format file called name

admesh --write-binary-stl=sphere.stl --no-check sphere.stl

--help               Display the 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.

--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 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.

--reverse-all

Reverses the directions of all of the facets and normals. If the --normal-directions option ended up making all of the facets facing 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. 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.

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.98 =================
Input file         : sphere.stl
File type          : Binary STL file
Header             : Processed by ADMesh version 0.98
============== 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

Input file         : sphere.stl

File type          : Binary STL file

Header             : Processed by ADMesh version 0.98

============== 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 ===
Number of parts       :     1

Degenerate facets     :     0

Edges fixed           :    24

Facets removed        :     0

Facets added          :     0

Facets reversed       :     0

Backwards edges       :     0

Normals fixed         :     0