toxi.geom.mesh
Class TriangleMesh

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

All Implemented Interfaces:

Intersector3D, Mesh3D

Direct Known Subclasses:

WETriangleMesh

public class TriangleMesh
extends java.lang.Object
implements Mesh3D, Intersector3D

An extensible class to dynamically build, manipulate & export triangle meshes. Meshes are built face by face. This implementation automatically re-uses existing vertices and can generate smooth vertex normals. Vertice and face lists are directly accessible for speed & convenience.

Field Summary

static int	DEFAULT_NUM_FACES Default size for face list
static int	DEFAULT_NUM_VERTICES Default size for vertex list
static int	DEFAULT_STRIDE Default stride setting used for serializing mesh properties into arrays.
java.util.ArrayList<Face>	faces Face list
java.lang.String	name Mesh name
java.util.LinkedHashMap<Vec3D,Vertex>	vertices Vertex buffer & lookup index when adding new faces

Constructor Summary

TriangleMesh()

TriangleMesh(java.lang.String name)
Creates a new mesh instance with initial default buffer sizes.

TriangleMesh(java.lang.String name, int numV, int numF)
Creates a new mesh instance with the given initial buffer sizes.

Method Summary

TriangleMesh	addFace(Vec3D a, Vec3D b, Vec3D c) Adds the given 3 points as triangle face to the mesh.
TriangleMesh	addFace(Vec3D a, Vec3D b, Vec3D c, Vec2D uvA, Vec2D uvB, Vec2D uvC) Adds the given 3 points as triangle face to the mesh and assigns the given texture coordinates to each vertex.
TriangleMesh	addFace(Vec3D a, Vec3D b, Vec3D c, Vec3D n)
TriangleMesh	addFace(Vec3D a, Vec3D b, Vec3D c, Vec3D n, Vec2D uvA, Vec2D uvB, Vec2D uvC)
TriangleMesh	addMesh(Mesh3D m) Adds all faces from the given mesh to this one.
AABB	center(ReadonlyVec3D origin) Centers the mesh around the given pivot point (the centroid of its AABB).
TriangleMesh	clear() Clears all counters, and vertex & face buffers.
Vec3D	computeCentroid() Computes the mesh centroid, the average position of all vertices.
TriangleMesh	computeFaceNormals() Re-calculates all face normals.
TriangleMesh	computeVertexNormals() Computes the smooth vertex normals for the entire mesh.
TriangleMesh	copy() Creates a deep clone of the mesh.
TriangleMesh	faceOutwards() Changes the vertex order of faces such that their normal is facing away from the mesh centroid.
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.
Vertex	getClosestVertexToPoint(ReadonlyVec3D p)
float[]	getFaceNormalsAsArray() Creates an array of unravelled normal coordinates.
float[]	getFaceNormalsAsArray(float[] normals, int offset, int stride) Creates an array of unravelled normal coordinates.
java.util.List<Face>	getFaces()
int[]	getFacesAsArray() Builds an array of vertex indices of all faces.
IsectData3D	getIntersectionData()
float[]	getMeshAsVertexArray() Creates an array of unravelled vertex coordinates for all faces using a stride setting of 4, resulting in a serialized version of all mesh vertex coordinates suitable for VBOs.
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).
TriangleMesh	getRotatedAroundAxis(Vec3D axis, float theta)
TriangleMesh	getRotatedX(float theta)
TriangleMesh	getRotatedY(float theta)
TriangleMesh	getRotatedZ(float theta)
TriangleMesh	getScaled(float scale)
TriangleMesh	getScaled(Vec3D scale)
TriangleMesh	getTranslated(Vec3D trans)
float[]	getUniqueVerticesAsArray()
Vertex	getVertexAtPoint(Vec3D v)
Vertex	getVertexForID(int id)
float[]	getVertexNormalsAsArray() Creates an array of unravelled vertex normal coordinates for all faces.
float[]	getVertexNormalsAsArray(float[] normals, int offset, int stride) Creates an array of unravelled vertex normal coordinates for all faces.
java.util.Collection<Vertex>	getVertices()
TriangleMesh	init(java.lang.String name, int numV, int numF)
boolean	intersectsRay(Ray3D ray) Checks if entity intersects with the given ray.
Triangle3D	perforateFace(Face f, float size)
TriangleMesh	pointTowards(ReadonlyVec3D dir) Rotates the mesh in such a way so that its "forward" axis is aligned with the given direction.
TriangleMesh	pointTowards(ReadonlyVec3D dir, ReadonlyVec3D forward) Rotates the mesh in such a way so that its "forward" axis is aligned with the given direction.
void	removeFace(Face f)
TriangleMesh	rotateAroundAxis(Vec3D axis, float theta)
TriangleMesh	rotateX(float theta)
TriangleMesh	rotateY(float theta)
TriangleMesh	rotateZ(float theta)
void	saveAsOBJ(OBJWriter obj) Saves the mesh as OBJ format by appending it to the given mesh OBJWriter instance.
void	saveAsOBJ(java.io.OutputStream stream) Saves the mesh as OBJ format to the given OutputStream.
void	saveAsOBJ(java.lang.String path) Saves the mesh as OBJ format to the given file path.
void	saveAsSTL(java.io.OutputStream stream) Saves the mesh as binary STL format to the given OutputStream.
void	saveAsSTL(java.io.OutputStream stream, boolean useFlippedY) Saves the mesh as binary STL format to the given OutputStream.
void	saveAsSTL(java.io.OutputStream stream, STLWriter stl, boolean useFlippedY) Saves the mesh as binary STL format to the given OutputStream and using the supplied STLWriter instance.
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)
TriangleMesh	scale(float scale)
TriangleMesh	scale(Vec3D scale)
TriangleMesh	setName(java.lang.String name)
java.lang.String	toString()
WETriangleMesh	toWEMesh()
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.
TriangleMesh	translate(Vec3D trans)
TriangleMesh	updateVertex(Vec3D orig, Vec3D newPos)

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

DEFAULT_NUM_VERTICES

public static final int DEFAULT_NUM_VERTICES

Default size for vertex list

See Also:

Constant Field Values

DEFAULT_NUM_FACES

public static final int DEFAULT_NUM_FACES

Default size for face list

See Also:

Constant Field Values

DEFAULT_STRIDE

public static final int DEFAULT_STRIDE

Default stride setting used for serializing mesh properties into arrays.

See Also:

Constant Field Values

name

public java.lang.String name

Mesh name

vertices

public java.util.LinkedHashMap<Vec3D,Vertex> vertices

Vertex buffer & lookup index when adding new faces

faces

public java.util.ArrayList<Face> faces

Face list

Constructor Detail

TriangleMesh

public TriangleMesh()

TriangleMesh

public TriangleMesh(java.lang.String name)

Creates a new mesh instance with initial default buffer sizes.

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 TriangleMesh addFace(Vec3D a,
                            Vec3D b,
                            Vec3D c)

Description copied from interface: Mesh3D

Adds the given 3 points as triangle face to the mesh. The assumed vertex order is anti-clockwise.

Specified by:

addFace in interface Mesh3D

addFace

public TriangleMesh addFace(Vec3D a,
                            Vec3D b,
                            Vec3D c,
                            Vec2D uvA,
                            Vec2D uvB,
                            Vec2D uvC)

Description copied from interface: Mesh3D

Adds the given 3 points as triangle face to the mesh and assigns the given texture coordinates to each vertex. The assumed vertex order is anti-clockwise.

Specified by:

addFace in interface Mesh3D

Returns:

itself

addFace

public TriangleMesh addFace(Vec3D a,
                            Vec3D b,
                            Vec3D c,
                            Vec3D n)

Specified by:

addFace in interface Mesh3D

addFace

public TriangleMesh addFace(Vec3D a,
                            Vec3D b,
                            Vec3D c,
                            Vec3D n,
                            Vec2D uvA,
                            Vec2D uvB,
                            Vec2D uvC)

Specified by:

addFace in interface Mesh3D

addMesh

public TriangleMesh addMesh(Mesh3D m)

Adds all faces from the given mesh to this one.

Specified by:

addMesh in interface Mesh3D

Parameters:

m - source mesh instance

center

public AABB center(ReadonlyVec3D origin)

Description copied from interface: Mesh3D

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

Specified by:

center in interface Mesh3D

Parameters:

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

clear

public TriangleMesh clear()

Clears all counters, and vertex & face buffers.

Specified by:

clear in interface Mesh3D

computeCentroid

public Vec3D computeCentroid()

Description copied from interface: Mesh3D

Computes the mesh centroid, the average position of all vertices.

Specified by:

computeCentroid in interface Mesh3D

Returns:

centre point

computeFaceNormals

public TriangleMesh computeFaceNormals()

Re-calculates all face normals.

Specified by:

computeFaceNormals in interface Mesh3D

computeVertexNormals

public TriangleMesh computeVertexNormals()

Computes the smooth vertex normals for the entire mesh.

Specified by:

computeVertexNormals in interface Mesh3D

Returns:

itself

copy

public TriangleMesh copy()

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

Returns:

new mesh instance

faceOutwards

public TriangleMesh faceOutwards()

Description copied from interface: Mesh3D

Changes the vertex order of faces such that their normal is facing away from the mesh centroid.

Specified by:

faceOutwards in interface Mesh3D

Returns:

itself

flipVertexOrder

public TriangleMesh flipVertexOrder()

Description copied from interface: Mesh3D

Flips the vertex ordering between clockwise and anti-clockwise. Face normals are updated automatically too.

Specified by:

flipVertexOrder in interface Mesh3D

Returns:

itself

flipYAxis

public TriangleMesh flipYAxis()

Description copied from interface: Mesh3D

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

Specified by:

flipYAxis in interface Mesh3D

Returns:

itself

getBoundingBox

public AABB getBoundingBox()

Description copied from interface: Mesh3D

Computes & returns the axis-aligned bounding box of the mesh.

Specified by:

getBoundingBox in interface Mesh3D

Returns:

bounding box

getBoundingSphere

public Sphere getBoundingSphere()

Description copied from interface: Mesh3D

Computes & returns the bounding sphere of the mesh. The origin of the sphere is the mesh's centroid.

Specified by:

getBoundingSphere in interface Mesh3D

Returns:

bounding sphere

getClosestVertexToPoint

public Vertex getClosestVertexToPoint(ReadonlyVec3D p)

Specified by:

getClosestVertexToPoint in interface Mesh3D

getFaceNormalsAsArray

public float[] getFaceNormalsAsArray()

Creates an array of unravelled normal coordinates. For each vertex the normal vector of its parent face is used. This is a convienence invocation of getFaceNormalsAsArray(float[], int, int) with a default stride = 4.

Returns:

array of xyz normal coords

getFaceNormalsAsArray

public float[] getFaceNormalsAsArray(float[] normals,
                                     int offset,
                                     int stride)

Creates an array of unravelled normal coordinates. For each vertex the normal vector of its parent face is used. 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)

getFaces

public java.util.List<Face> getFaces()

Specified by:

getFaces in interface Mesh3D

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

getIntersectionData

public IsectData3D getIntersectionData()

Specified by:

getIntersectionData in interface Intersector3D

Returns:

intersection data parcel

getMeshAsVertexArray

public float[] getMeshAsVertexArray()

Creates an array of unravelled vertex coordinates for all faces using a stride setting of 4, resulting in a serialized version of all mesh vertex coordinates suitable for VBOs.

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:

• Face 1:
  • Vertex #1
    • x
    • y
    • z
    • [optional empty indices to match stride setting]
  • Vertex #2
    • x
    • y
    • z
    • [optional empty indices to match stride setting]
  • Vertex #3
    • x
    • y
    • z
    • [optional empty indices to match stride setting]
• Face 2:
  • Vertex #1
  • ...etc.

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

Description copied from interface: Mesh3D

Returns the number of triangles used.

Specified by:

getNumFaces in interface Mesh3D

Returns:

face count

getNumVertices

public int getNumVertices()

Description copied from interface: Mesh3D

Returns the number of actual vertices used (unique vertices).

Specified by:

getNumVertices in interface Mesh3D

Returns:

vertex count

getRotatedAroundAxis

public TriangleMesh getRotatedAroundAxis(Vec3D axis,
                                         float theta)

getRotatedX

public TriangleMesh getRotatedX(float theta)

getRotatedY

public TriangleMesh getRotatedY(float theta)

getRotatedZ

public TriangleMesh getRotatedZ(float theta)

getScaled

public TriangleMesh getScaled(float scale)

getScaled

public TriangleMesh getScaled(Vec3D scale)

getTranslated

public TriangleMesh getTranslated(Vec3D trans)

getUniqueVerticesAsArray

public float[] getUniqueVerticesAsArray()

getVertexAtPoint

public Vertex getVertexAtPoint(Vec3D v)

getVertexForID

public Vertex getVertexForID(int id)

getVertexNormalsAsArray

public float[] getVertexNormalsAsArray()

Creates an array of unravelled vertex normal coordinates for all faces. Uses default stride = 4.

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)

getVertices

public java.util.Collection<Vertex> getVertices()

Specified by:

getVertices in interface Mesh3D

init

public TriangleMesh init(java.lang.String name,
                         int numV,
                         int numF)

Specified by:

init in interface Mesh3D

intersectsRay

public boolean intersectsRay(Ray3D ray)

Description copied from interface: Intersector3D

Checks if entity intersects with the given ray. Further intersection details can then be queried via the IsectData3D instance returned by Intersector3D.getIntersectionData().

Specified by:

intersectsRay in interface Intersector3D

Parameters:

ray - ray to check

Returns:

true, if ray hits the entity

perforateFace

public Triangle3D perforateFace(Face f,
                                float size)

pointTowards

public TriangleMesh pointTowards(ReadonlyVec3D 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(ReadonlyVec3D dir,
                                 ReadonlyVec3D 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

removeFace

public void removeFace(Face f)

rotateAroundAxis

public TriangleMesh rotateAroundAxis(Vec3D axis,
                                     float theta)

rotateX

public TriangleMesh rotateX(float theta)

rotateY

public TriangleMesh rotateY(float theta)

rotateZ

public TriangleMesh rotateZ(float theta)

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.io.OutputStream stream)

Saves the mesh as OBJ format to the given OutputStream. Currently no texture coordinates are supported or written.

Parameters:

stream -

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 -

saveAsSTL

public final void saveAsSTL(java.io.OutputStream stream)

Saves the mesh as binary STL format to the given OutputStream.

Parameters:

stream -

See Also:

saveAsSTL(OutputStream, boolean)

saveAsSTL

public final void saveAsSTL(java.io.OutputStream stream,
                            boolean useFlippedY)

Saves the mesh as binary STL format to the given OutputStream. The exported mesh can optionally have it's Y axis flipped by setting the useFlippedY flag to true.

Parameters:

stream -

useFlippedY -

saveAsSTL

public final void saveAsSTL(java.io.OutputStream stream,
                            STLWriter stl,
                            boolean useFlippedY)

Saves the mesh as binary STL format to the given OutputStream and using the supplied STLWriter instance. Use this method to export data in a custom STLColorModel. The exported mesh can optionally have it's Y axis flipped by setting the useFlippedY flag to true.

Parameters:

stream -

stl -

useFlippedY -

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)

scale

public TriangleMesh scale(float scale)

scale

public TriangleMesh scale(Vec3D scale)

setName

public TriangleMesh setName(java.lang.String name)

Specified by:

setName in interface Mesh3D

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

toWEMesh

public WETriangleMesh toWEMesh()

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

translate

public TriangleMesh translate(Vec3D trans)

updateVertex

public TriangleMesh updateVertex(Vec3D orig,
                                 Vec3D newPos)