toxi.geom.mesh
Class TriangleMesh

java.lang.Object
  extended by toxi.geom.mesh.TriangleMesh

public class TriangleMesh
extends java.lang.Object

A class to dynamically build, manipulate & export triangle meshes. Meshes are build face by face. The class automatically re-uses existing vertices and can create smooth vertex normals. Vertices and faces are directly accessible for speed & convenience.


Nested Class Summary
static class TriangleMesh.Face
           
static class TriangleMesh.Vertex
           
 
Field Summary
 java.util.ArrayList<TriangleMesh.Face> faces
          Face list
 java.lang.String name
          Mesh name
 java.util.LinkedHashMap<Vec3D,TriangleMesh.Vertex> vertices
          Vertex buffer & lookup index when adding new faces
 
Constructor Summary
TriangleMesh()
           
TriangleMesh(java.lang.String name)
          Creates a new mesh instance with an initial buffer size of 1000 vertices & 3000 faces.
TriangleMesh(java.lang.String name, int numV, int numF)
          Creates a new mesh instance with the given initial buffer sizes.
 
Method Summary
 void addFace(Vec3D a, Vec3D b, Vec3D c)
          Adds the given 3 points as triangle face to the mesh.
 void addMesh(TriangleMesh m)
          Adds all faces from the given mesh to this one.
 AABB center(Vec3D origin)
          Centers the mesh around the given pivot point (the centroid of its AABB).
 void clear()
          Clears all counters, and vertex & face buffers.
 TriangleMesh computeFaceNormals()
          Re-calculates all face normals.
 void computeVertexNormals()
          Computes the smooth vertex normals for the entire mesh.
 TriangleMesh copy()
          Creates a deep clone of the mesh.
 TriangleMesh flipVertexOrder()
          Flips the vertex ordering between clockwise and anti-clockwise.
 TriangleMesh flipYAxis()
          Flips all vertices along the Y axis and reverses the vertex ordering of all faces to compensate and keep the direction of normals intact.
 AABB getBoundingBox()
          Computes & returns the axis-aligned bounding box of the mesh.
 Sphere getBoundingSphere()
          Computes & returns the bounding sphere of the mesh.
 Vec3D getCentroid()
          Computes the mesh centroid, the average position of all vertices.
 int[] getFacesAsArray()
          Builds an array of vertex indices of all faces.
 float[] getMeshAsVertexArray()
          Creates an array of unravelled vertex coordinates for all faces using a stride setting of 3, resulting in a gap-less serialized version of all mesh vertex coordinates.
 float[] getMeshAsVertexArray(float[] verts, int offset, int stride)
          Creates an array of unravelled vertex coordinates for all faces.
 int getNumFaces()
          Returns the number of triangles used.
 int getNumVertices()
          Returns the number of actual vertices used (unique vertices).
 float[] getUniqueVerticesAsArray()
           
 float[] getVertexNormalsAsArray()
           
 float[] getVertexNormalsAsArray(float[] normals, int offset, int stride)
          Creates an array of unravelled vertex normal coordinates for all faces.
 TriangleMesh pointTowards(Vec3D dir)
          Rotates the mesh in such a way so that its "forward" axis is aligned with the given direction.
 TriangleMesh pointTowards(Vec3D dir, Vec3D forward)
          Rotates the mesh in such a way so that its "forward" axis is aligned with the given direction.
 void saveAsOBJ(OBJWriter obj)
          Saves the mesh as OBJ format by appending it to the given mesh OBJWriter instance.
 void saveAsOBJ(java.lang.String path)
          Saves the mesh as OBJ format to the given file path.
 void saveAsRaw(java.lang.String fileName)
          Saves the mesh in a simple, proprietary compact binary format written using the standard DataOutputStream methods.
 void saveAsSTL(java.lang.String fileName)
          Saves the mesh as binary STL format to the given file path.
 void saveAsSTL(java.lang.String fileName, boolean useFlippedY)
          Saves the mesh as binary STL format to the given file path.
 void saveAsSTL(java.lang.String fileName, STLWriter stl, boolean useFlippedY)
           
 java.lang.String toString()
           
 TriangleMesh transform(Matrix4x4 mat)
          Applies the given matrix transform to all mesh vertices and updates all face normals.
 TriangleMesh transform(Matrix4x4 mat, boolean updateNormals)
          Applies the given matrix transform to all mesh vertices.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

name

public java.lang.String name
Mesh name


vertices

public final java.util.LinkedHashMap<Vec3D,TriangleMesh.Vertex> vertices
Vertex buffer & lookup index when adding new faces


faces

public final java.util.ArrayList<TriangleMesh.Face> faces
Face list

Constructor Detail

TriangleMesh

public TriangleMesh()

TriangleMesh

public TriangleMesh(java.lang.String name)
Creates a new mesh instance with an initial buffer size of 1000 vertices & 3000 faces.

Parameters:
name - mesh name

TriangleMesh

public TriangleMesh(java.lang.String name,
                    int numV,
                    int numF)
Creates a new mesh instance with the given initial buffer sizes. These numbers are no limits and the mesh can be smaller or grow later on. They're only used to initialise the underlying collections.

Parameters:
name - mesh name
numV - initial vertex buffer size
numF - initial face list size
Method Detail

addFace

public void addFace(Vec3D a,
                    Vec3D b,
                    Vec3D c)
Adds the given 3 points as triangle face to the mesh. The assumed vertex order is anti-clockwise.

Parameters:
a -
b -
c -

addMesh

public void addMesh(TriangleMesh m)
Adds all faces from the given mesh to this one.

Parameters:
m - source mesh instance

center

public AABB center(Vec3D origin)
Centers the mesh around the given pivot point (the centroid of its AABB). Method also updates & returns the new bounding box.

Parameters:
origin - new centroid or null (defaults to {0,0,0})

clear

public void clear()
Clears all counters, and vertex & face buffers.


computeFaceNormals

public TriangleMesh computeFaceNormals()
Re-calculates all face normals.


computeVertexNormals

public void computeVertexNormals()
Computes the smooth vertex normals for the entire mesh.


copy

public TriangleMesh copy()
Creates a deep clone of the mesh. The new mesh name will have "-copy" as suffix.

Returns:
new mesh instance

flipVertexOrder

public TriangleMesh flipVertexOrder()
Flips the vertex ordering between clockwise and anti-clockwise. Face normals are updated automatically too.

Returns:
itself

flipYAxis

public TriangleMesh flipYAxis()
Flips all vertices along the Y axis and reverses the vertex ordering of all faces to compensate and keep the direction of normals intact.

Returns:
itself

getBoundingBox

public AABB getBoundingBox()
Computes & returns the axis-aligned bounding box of the mesh.

Returns:
bounding box

getBoundingSphere

public Sphere getBoundingSphere()
Computes & returns the bounding sphere of the mesh. The origin of the sphere is the mesh's centroid.

Returns:
bounding sphere

getCentroid

public Vec3D getCentroid()
Computes the mesh centroid, the average position of all vertices.

Returns:
centre point

getFacesAsArray

public int[] getFacesAsArray()
Builds an array of vertex indices of all faces. Each vertex ID corresponds to its position in the vertices HashMap. The resulting array will be 3 times the face count.

Returns:
array of vertex indices

getMeshAsVertexArray

public float[] getMeshAsVertexArray()
Creates an array of unravelled vertex coordinates for all faces using a stride setting of 3, resulting in a gap-less serialized version of all mesh vertex coordinates.

Returns:
float array of vertex coordinates
See Also:
getMeshAsVertexArray(float[], int, int)

getMeshAsVertexArray

public float[] getMeshAsVertexArray(float[] verts,
                                    int offset,
                                    int stride)
Creates an array of unravelled vertex coordinates for all faces. This method can be used to translate the internal mesh data structure into a format suitable for OpenGL Vertex Buffer Objects (by choosing stride=4). The order of the array will be as follows:

Parameters:
verts - an existing target array or null to automatically create one
offset - start index in arrtay to place vertices
stride - stride/alignment setting for individual coordinates
Returns:
array of xyz vertex coords

getNumFaces

public int getNumFaces()
Returns the number of triangles used.

Returns:
face count

getNumVertices

public int getNumVertices()
Returns the number of actual vertices used (unique vertices).

Returns:
vertex count

getUniqueVerticesAsArray

public float[] getUniqueVerticesAsArray()

getVertexNormalsAsArray

public float[] getVertexNormalsAsArray()
Returns:
array of xyz normal coords
See Also:
getVertexNormalsAsArray(float[], int, int)

getVertexNormalsAsArray

public float[] getVertexNormalsAsArray(float[] normals,
                                       int offset,
                                       int stride)
Creates an array of unravelled vertex normal coordinates for all faces. This method can be used to translate the internal mesh data structure into a format suitable for OpenGL Vertex Buffer Objects (by choosing stride=4). For more detail, please see getMeshAsVertexArray(float[], int, int)

Parameters:
normals - existing float array or null to automatically create one
offset - start index in array to place normals
stride - stride/alignment setting for individual coordinates (min value = 3)
Returns:
array of xyz normal coords
See Also:
getMeshAsVertexArray(float[], int, int)

pointTowards

public TriangleMesh pointTowards(Vec3D dir)
Rotates the mesh in such a way so that its "forward" axis is aligned with the given direction. This version uses the positive Z-axis as default forward direction.

Parameters:
dir - new target direction to point in
Returns:
itself

pointTowards

public TriangleMesh pointTowards(Vec3D dir,
                                 Vec3D forward)
Rotates the mesh in such a way so that its "forward" axis is aligned with the given direction. This version allows to specify the forward direction.

Parameters:
dir - new target direction to point in
forward - current forward axis
Returns:
itself

saveAsOBJ

public void saveAsOBJ(OBJWriter obj)
Saves the mesh as OBJ format by appending it to the given mesh OBJWriter instance.

Parameters:
obj -

saveAsOBJ

public void saveAsOBJ(java.lang.String path)
Saves the mesh as OBJ format to the given file path. Existing files will be overwritten.

Parameters:
path -

saveAsRaw

public final void saveAsRaw(java.lang.String fileName)
Saves the mesh in a simple, proprietary compact binary format written using the standard DataOutputStream methods. The format is as follows:

Parameters:
fileName -

saveAsSTL

public final void saveAsSTL(java.lang.String fileName)
Saves the mesh as binary STL format to the given file path. Existing files will be overwritten.

Parameters:
fileName -

saveAsSTL

public final void saveAsSTL(java.lang.String fileName,
                            boolean useFlippedY)
Saves the mesh as binary STL format to the given file path. The exported mesh can optionally have it's Y axis flipped by setting the useFlippedY flag to true. Existing files will be overwritten.

Parameters:
fileName -
useFlippedY -

saveAsSTL

public final void saveAsSTL(java.lang.String fileName,
                            STLWriter stl,
                            boolean useFlippedY)

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object

transform

public TriangleMesh transform(Matrix4x4 mat)
Applies the given matrix transform to all mesh vertices and updates all face normals.

Parameters:
mat -
Returns:
itself

transform

public TriangleMesh transform(Matrix4x4 mat,
                              boolean updateNormals)
Applies the given matrix transform to all mesh vertices. If the updateNormals flag is true, all face normals are updated automatically, however vertex normals need a manual update.

Parameters:
mat -
updateNormals -
Returns:
itself