mXrap - Clipping

Clipping

require.mx('mxjs/mesh/clipping.js');

Methods for clipping polygons.

clipPolygonToAABB
clipPolygonToBox
clipPolygonToHalfSpace
clipPolylines
clipTrianglesToAABB
clipTrianglesToBox
clipTrianglesToHalfSpace
clipTriangleToUnionOfConvexPolyhedrons
consolidateFacesAndVertices
triangulateFaces
Examples

Status	Name
	`Number` clipPolygonToAABB ( `Array<vec3>` ↑outVertices, `Array<vec3>` ↓inVertices, `Number` ↓numInVertices, `vec3` ↓minPoint, `vec3` ↓maxPoint ) Convenience function that calls `clipPolygonToHalfSpace` six times, to clip a single polygon into the space of an axis-aligned bounding box (AABB). The polygon is specified as an array of locations defining the outer points of the polygon in order (either CW or CCW).
	`Number` clipPolygonToBox ( `Array<vec3>` ↑outVertices, `Array<vec3>` ↓inVertices, `Number` ↓numInVertices, `vec3` ↓pointA, `vec3` ↓pointB, `vec3` ↓normalA1, `vec3` ↓normalA2, `vec3` ↓normalA3, `vec3` ↓normalB1, `vec3` ↓normalB2, `vec3` ↓normalB3 ) Convenience function that calls `clipPolygonToHalfSpace` six times, to clip a single polygon into the space of a box defined by 6 intersecting planes. Each plane needs to be the center point of a box face with an outward facing normal vector. The polygon is specified as an array of locations defining the outer points of the polygon in order (either CW or CCW).
	`Number` clipPolygonToHalfSpace ( `Array<vec3>` ↑outVertices, `Array<vec3>` ↓inVertices, `Number` ↓numInVertices, `vec3` ↓planePoint, `vec3` ↓planeNormal ) Clips a polygon to a halfspace, using a simple Sutherland–Hodgman implementation (see https://en.wikipedia.org/wiki/Sutherland%E2%80%93Hodgman_algorithm).
	clipPolylines ( `Object` ↓settings ) Clips polylines to the inside of a union of a set of (possibly unbounded) polyhedrons, each of which is defined as a set of planes (with normal vectors pointing outside of the clipping area). `Input Table` `Lines` table defining the triangular faces. Must have ID columns V1, V2, and V3, containing the indices of the relevant vertices in the vertices table (not the IDs - see `triangulateFaces` if you want a function that will prepare an appropriate faces table). It also requires a filter column named Deleted, which is used to mark faces that were completely removed because all three vertices are outside of the halfspace. `Input Table` `Vertices` table defining the vertices. Must have a point column named Location. `Output Table` `OutLines` table defining the triangular faces. Must have ID columns V1, V2, and V3, containing the indices of the relevant vertices in the vertices table (not the IDs - see `triangulateFaces` if you want a function that will prepare an appropriate faces table). It also requires a filter column named Deleted, which is used to mark faces that were completely removed because all three vertices are outside of the halfspace. `Output Table` `OutVertices` table defining the vertices. Must have a point column named Location. `[Object]` `planeSets` an array of objects, each object contains one set of planes and thus defines a convex (possibly unbounded) polyhedron. The clipping space is the union of these polyhedra. The objects should contain two members: normals, an array of plane normals; and points, an array of points on the plane. `Function` `onWriteVertex` (optional) a function to be called each time a vertex is written to the output vertices table. It receives the following arguments, in order: outIdx, the index that the vertex is written to; inIdx1, the index that the vertex was read from; inIdx2, if this output vertex is interpolated along a line segment (at the boundary of the clipping space), this is the index of the second vertex (and inIdx1 is the index of the first), otherwise this is `-1`; inIdxRatio, if this output vertex is interpolated along a line segment, this is the ratio between inIdx1 (at 0) and inIdx2 (at 1); outVertices, the table that the vertex is written to; inVertices, the table that the vertex was read from.
	clipTrianglesToAABB ( `Object` ↓settings ) Convenience function that calls clipTrianglesToHalfSpace six times, to effectively clip a collection of triangles to the space inside an axis-aligned bounding box (AABB). The `settings` object is expected to have the following properties: `Output Table` `faces` table defining the triangular faces. Must have ID columns V1, V2, and V3, containing the indices of the relevant vertices in the vertices table (not the IDs - see `triangulateFaces` if you want a function that will prepare an appropriate faces table). It also requires a filter column named Deleted, which is used to mark faces that were completely removed because all three vertices are outside of the halfspace. `Output Table` `vertices` table defining the vertices. Must have a point column named Location. `vec3` `minPoint` minimum point of the AABB. `vec3` `maxPoint` maximum point of the AABB. `Function` `onFaceSplit` (optional) a function to be called whenever a triangle is split into two triangles (if exactly one vertex of the triangle is outside the halfspace, the clipped triangle shape is defined by two triangles). Receives the following arguments, in order: newFaceIndex, the index of the new triangle; oldFaceIndex, the index of the old triangle (which is modified to become one of the two triangles that define the remaining shape); and faces, the faces table. `Function` `onVertexInterpolate` (optional) a function to be called whenever a new vertex is created at the point where a triangle edge (V1->V2) intersects the plane. Receives the following arguments, in order: newVertexIndex, the index of the new vertex; oldV1Index, the index of the old V1 vertex (which is inside the halfspace and will still be used in the clipped triangle); oldV2Index, the index of the old V2 vertex (which is outside the halfspace and will not be used in the clipped triangle); ratioV1V2, the fraction of the distance from V1 to V2 at which the edge intersects the plane; and vertices, the vertices table. `Boolean` `writeOutsideSplits` (optional) if true, when a triangle is intersected by the AABB, also create output triangles for the part outside of the AABB (which will be marked as deleted). Note that the `clipTrianglesToHalfSpace` function uses JS arrays to track edges that intersect the plane, so that a single edge does not produce duplicate output intersection vertices when it is shared by multiple clipped triangles. This means that this function could crash mXrap if a very large number of edges intersect any one of the six planes that form the AABB.
	clipTrianglesToBox ( `Object` ↓settings ) Convenience function that calls `clipTrianglesToHalfSpace` six times, to effectively clip a collection of triangles to the space inside a box defined by 6 intersecting planes. The `settings` object is expected to have the following properties: `Output Table` `faces` table defining the triangular faces. Must have ID columns V1, V2, and V3, containing the indices of the relevant vertices in the vertices table (not the IDs - see `triangulateFaces` if you want a function that will prepare an appropriate faces table). It also requires a filter column named Deleted, which is used to mark faces that were completely removed because all three vertices are outside of the halfspace. `Output Table` `vertices` table defining the vertices. Must have a point column named Location. `vec3` `pointA` a corner of the box. `vec3` `pointB` the corner diagonally opposite to pointA. `vec3` `normalA1` normal vector of face adjacent to pointA and facing inwards. `vec3` `normalA2` normal vector of face adjacent to pointA and facing inwards. `vec3` `normalA3` normal vector of face adjacent to pointA and facing inwards. `vec3` `normalB1` normal vector of face adjacent to pointB and facing inwards. `vec3` `normalB2` normal vector of face adjacent to pointB and facing inwards. `vec3` `normalB3` normal vector of face adjacent to pointB and facing inwards. `Function` `onFaceSplit` (optional) a function to be called whenever a triangle is split into two triangles (if exactly one vertex of the triangle is outside the halfspace, the clipped triangle shape is defined by two triangles). Receives the following arguments, in order: newFaceIndex, the index of the new triangle; oldFaceIndex, the index of the old triangle (which is modified to become one of the two triangles that define the remaining shape); and faces, the faces table. `Function` `onVertexInterpolate` (optional) a function to be called whenever a new vertex is created at the point where a triangle edge (V1->V2) intersects the plane. Receives the following arguments, in order: newVertexIndex, the index of the new vertex; oldV1Index, the index of the old V1 vertex (which is inside the halfspace and will still be used in the clipped triangle); oldV2Index, the index of the old V2 vertex (which is outside the halfspace and will not be used in the clipped triangle); ratioV1V2, the fraction of the distance from V1 to V2 at which the edge intersects the plane; and vertices, the vertices table. `Boolean` `writeOutsideSplits` (optional) if true, when a triangle is intersected by the AABB, also create output triangles for the part outside of the AABB (which will be marked as deleted). Note that the `clipTrianglesToHalfSpace` function uses JS arrays to track edges that intersect the plane, so that a single edge does not produce duplicate output intersection vertices when it is shared by multiple clipped triangles. This means that this function could crash mXrap if a very large number of edges intersect any one of the six planes that form the AABB.
	clipTrianglesToHalfSpace ( `Object` ↓settings ) Clips all triangular faces defined by the provided faces and vertices output tables so that they lie within the halfspace defined by the given plane. This implementation is based on Efficient Triangle and Quadrilateral Clipping within Shaders, Morgan McGuire, The Journal of Graphics, GPU, and Game Tools, 2011. https://casual-effects.com/research/McGuire2011Clipping/. The `settings` object is expected to have the following properties: `Output Table` `faces` table defining the triangular faces. Must have ID columns V1, V2, and V3, containing the indices of the relevant vertices in the vertices table (not the IDs - see `triangulateFaces` if you want a function that will prepare an appropriate faces table). It also requires a filter column named Deleted, which is used to mark faces that were completely removed because all three vertices are outside of the halfspace. `Output Table` `vertices` table defining the vertices. Must have a point column named Location. `vec3` `planePoint` a point on the plane that defines the halfspace. `vec3` `planeNormal` the normal direction of the plane that defines the halfspace (the normal points into the halfspace, i.e. triangles will be kept on the side of the plane that the normal points into, but will be clipped/removed on the other side). `Function` `onFaceSplit` (optional) a function to be called whenever a triangle is split into two triangles (if exactly one vertex of the triangle is outside the halfspace, the clipped triangle shape is defined by two triangles). Receives the following arguments, in order: newFaceIndex, the index of the new triangle; oldFaceIndex, the index of the old triangle (which is modified to become one of the two triangles that define the remaining shape); and faces, the faces table. `Function` `onVertexInterpolate` (optional) a function to be called whenever a new vertex is created at the point where a triangle edge (V1->V2) intersects the plane. Receives the following arguments, in order: newVertexIndex, the index of the new vertex; oldV1Index, the index of the old V1 vertex (which is inside the halfspace and will still be used in the clipped triangle); oldV2Index, the index of the old V2 vertex (which is outside the halfspace and will not be used in the clipped triangle); ratioV1V2, the fraction of the distance from V1 to V2 at which the edge intersects the plane; and vertices, the vertices table. `Boolean` `writeOutsideSplits` (optional) if true, when a triangle is intersected by the AABB, also create output triangles for the part outside of the AABB (which will be marked as deleted). Note that this function uses JS arrays to track edges that intersect the plane, so that a single edge does not produce duplicate output intersection vertices when it is shared by multiple clipped triangles. This means that the function could crash mXrap if a very large number of edges intersect the plane.
	clipTriangleToUnionOfConvexPolyhedrons ( `vec3` ↓v1, `vec3` ↓v2, `vec3` ↓v3, `Number` ↓v1ID, `Number` ↓v2ID, `Number` ↓v3ID, `Array` ↓planeSets, `Function` ↓writeVertex, `Function` ↓writeTriangle, `Boolean` ↓writeOuterTriangles, `Boolean` ↓writeInnerTriangles )
	consolidateFacesAndVertices ( `Table` faces, `Table` vertices, `Function` onMoveFace, `Function` onMoveVertex ) Consolidates output faces and vertices tables that have been clipped by the `clipTrianglesToHalfSpace` and/or `clipTrianglesToAABB` functions. These functions mark certain faces as deleted (using the filter column named `Deleted`) when the entire face is outside of the clipping area. They also rewrite faces to use different vertices, which can result in some vertices in the output table being unused. This function will move all non-deleted faces and used vertices to the beginning of the output table columns, and then resize the output tables down so that only the non-deleted faces and used vertices remain. It will also assign IDs to the consolidated vertices and update the faces table to use the new IDs (instead of the vertex indices as required by the aforementioned functions).
	triangulateFaces ( `Object` ↓settings ) Copies faces and vertices, transforming quads to triangles as it goes. The `settings` object is expected to have the following properties: `Table` `Faces` the input faces table, which should have columns V1, V2, V3, and optionally V4. `Table` `Vertices` the input vertices table, which should have columns ID and Location. `Output Table` `OutFaces` the output faces table, which should have columns V1, V2, and V3. `Output Table` `OutVertices` the output vertices table, which should have a column named Location. `Function` `onWriteFace` (optional) a function to be called each time a face is written to the output faces table. It receives the following arguments, in order: outIdx, the index that the face is written to; inIdx, the index that the face was read from; outFaces, the table that the face is written to; inFaces, the table that the face was read from. `Function` `onWriteVertex` (optional) a function to be called each time a vertex is written to the output vertices table. It receives the following arguments, in order: outIdx, the index that the vertex is written to; inIdx, the index that the vertex was read from; outVertices, the table that the vertex is written to; inVertices, the table that the vertex was read from. When this function is complete, the output faces have V1, V2, and V3 containing the table indices of the relevant vertices. This is the format required for the `clipTrianglesToHalfSpace` and `clipTrianglesToAABB` functions, so this function can be used to prepare input for those functions, even if you know that the input will never have quads (i.e. does not need triangulation).

Library Functions

numOutVertices = Lib.clipPolygonToAABB ( ↑outVertices, ↓inVertices, ↓numInVertices, ↓minPoint, ↓maxPoint ) Alpha

Convenience function that calls clipPolygonToHalfSpace six times, to clip a single polygon into the space of an axis-aligned bounding box (AABB). The polygon is specified as an array of locations defining the outer points of the polygon in order (either CW or CCW).

Parameters:

Array<vec3> ↑outVertices - an array that will receive the locations of the outer points of the clipped polygon. If the array already contains vec3s (or arrays) they will be reused.
Array<vec3> ↓inVertices - an array containing the locations of the outer points of the polygon in order (either CW or CCW).
Number ↓numInVertices - the number of input vertices in inVertices that identify the polygon (if the inVertices array is longer than this, the additional vertices are ignored).
vec3 ↓minPoint - minimum point of the AABB.
vec3 ↓maxPoint - maximum point of the AABB.

Returns: Number numOutVertices - the number of output vertices in outVertices that identify the clipped polygon (if the output array is longer than this, e.g. it is being reused from an earlier polygon, then the additional vertices should be ignored).

numOutVertices = Lib.clipPolygonToBox ( ↑outVertices, ↓inVertices, ↓numInVertices, ↓pointA, ↓pointB, ↓normalA1, ↓normalA2, ↓normalA3, ↓normalB1, ↓normalB2, ↓normalB3 ) Alpha

Convenience function that calls clipPolygonToHalfSpace six times, to clip a single polygon into the space of a box defined by 6 intersecting planes. Each plane needs to be the center point of a box face with an outward facing normal vector. The polygon is specified as an array of locations defining the outer points of the polygon in order (either CW or CCW).

Parameters:

Array<vec3> ↑outVertices - an array that will receive the locations of the outer points of the clipped polygon. If the array already contains vec3s (or arrays) they will be reused.
Array<vec3> ↓inVertices - an array containing the locations of the outer points of the polygon in order (either CW or CCW).
Number ↓numInVertices - the number of input vertices in inVertices that identify the polygon (if the inVertices array is longer than this, the additional vertices are ignored).
vec3 ↓pointA - a corner of the box.
vec3 ↓pointB - the corner diagonal opposite to pointA.
vec3 ↓normalA1 - normal vector of a plane intersecting point A and outwards facing.
vec3 ↓normalA2 - normal vector of a plane intersecting point A and outwards facing.
vec3 ↓normalA3 - normal vector of a plane intersecting point A and outwards facing.
vec3 ↓normalB1 - normal vector of a plane intersecting point A and outwards facing.
vec3 ↓normalB2 - normal vector of a plane intersecting point A and outwards facing.
vec3 ↓normalB3 - normal vector of a plane intersecting point A and outwards facing.

numOutVertices = Lib.clipPolygonToHalfSpace ( ↑outVertices, ↓inVertices, ↓numInVertices, ↓planePoint, ↓planeNormal ) Alpha

Clips a polygon to a halfspace, using a simple Sutherland–Hodgman implementation (see https://en.wikipedia.org/wiki/Sutherland%E2%80%93Hodgman_algorithm).

Parameters:

Array<vec3> ↑outVertices - an array that will receive the locations of the outer points of the clipped polygon. If the array already contains vec3s (or arrays) they will be reused.
Array<vec3> ↓inVertices - an array containing the locations of the outer points of the polygon in order (either CW or CCW).
Number ↓numInVertices - the number of input vertices in inVertices that identify the polygon (if the inVertices array is longer than this, the additional vertices are ignored).
vec3 ↓planePoint - a point on the plane that defines the halfspace.
vec3 ↓planeNormal - the normal direction of the plane that defines the halfspace (the normal points into the halfspace, i.e. the polygon will be kept on the side of the plane that the normal points into, but will be clipped/removed on the other side).

Lib.clipPolylines ( ↓settings ) Alpha

Clips polylines to the inside of a union of a set of (possibly unbounded) polyhedrons, each of which is defined as a set of planes (with normal vectors pointing outside of the clipping area).

Input Table Lines table defining the triangular faces. Must have ID columns V1, V2, and V3, containing the indices of the relevant vertices in the vertices table (not the IDs - see triangulateFaces if you want a function that will prepare an appropriate faces table). It also requires a filter column named Deleted, which is used to mark faces that were completely removed because all three vertices are outside of the halfspace.
Input Table Vertices table defining the vertices. Must have a point column named Location.
Output Table OutLines table defining the triangular faces. Must have ID columns V1, V2, and V3, containing the indices of the relevant vertices in the vertices table (not the IDs - see triangulateFaces if you want a function that will prepare an appropriate faces table). It also requires a filter column named Deleted, which is used to mark faces that were completely removed because all three vertices are outside of the halfspace.
Output Table OutVertices table defining the vertices. Must have a point column named Location.
[Object] planeSets an array of objects, each object contains one set of planes and thus defines a convex (possibly unbounded) polyhedron. The clipping space is the union of these polyhedra. The objects should contain two members: normals, an array of plane normals; and points, an array of points on the plane.
Function onWriteVertex (optional) a function to be called each time a vertex is written to the output vertices table. It receives the following arguments, in order: outIdx, the index that the vertex is written to; inIdx1, the index that the vertex was read from; inIdx2, if this output vertex is interpolated along a line segment (at the boundary of the clipping space), this is the index of the second vertex (and inIdx1 is the index of the first), otherwise this is -1; inIdxRatio, if this output vertex is interpolated along a line segment, this is the ratio between inIdx1 (at 0) and inIdx2 (at 1); outVertices, the table that the vertex is written to; inVertices, the table that the vertex was read from.

Parameters:

Object ↓settings

Lib.clipTrianglesToAABB ( ↓settings ) Alpha

Convenience function that calls clipTrianglesToHalfSpace six times, to effectively clip a collection of triangles to the space inside an axis-aligned bounding box (AABB). The settings object is expected to have the following properties:

Output Table faces table defining the triangular faces. Must have ID columns V1, V2, and V3, containing the indices of the relevant vertices in the vertices table (not the IDs - see triangulateFaces if you want a function that will prepare an appropriate faces table). It also requires a filter column named Deleted, which is used to mark faces that were completely removed because all three vertices are outside of the halfspace.
Output Table vertices table defining the vertices. Must have a point column named Location.
vec3 minPoint minimum point of the AABB.
vec3 maxPoint maximum point of the AABB.
Function onFaceSplit (optional) a function to be called whenever a triangle is split into two triangles (if exactly one vertex of the triangle is outside the halfspace, the clipped triangle shape is defined by two triangles). Receives the following arguments, in order: newFaceIndex, the index of the new triangle; oldFaceIndex, the index of the old triangle (which is modified to become one of the two triangles that define the remaining shape); and faces, the faces table.
Function onVertexInterpolate (optional) a function to be called whenever a new vertex is created at the point where a triangle edge (V1->V2) intersects the plane. Receives the following arguments, in order: newVertexIndex, the index of the new vertex; oldV1Index, the index of the old V1 vertex (which is inside the halfspace and will still be used in the clipped triangle); oldV2Index, the index of the old V2 vertex (which is outside the halfspace and will not be used in the clipped triangle); ratioV1V2, the fraction of the distance from V1 to V2 at which the edge intersects the plane; and vertices, the vertices table.
Boolean writeOutsideSplits (optional) if true, when a triangle is intersected by the AABB, also create output triangles for the part outside of the AABB (which will be marked as deleted).

Note that the clipTrianglesToHalfSpace function uses JS arrays to track edges that intersect the plane, so that a single edge does not produce duplicate output intersection vertices when it is shared by multiple clipped triangles. This means that this function could crash mXrap if a very large number of edges intersect any one of the six planes that form the AABB.

Parameters:

Object ↓settings

Lib.clipTrianglesToBox ( ↓settings ) Alpha

Convenience function that calls clipTrianglesToHalfSpace six times, to effectively clip a collection of triangles to the space inside a box defined by 6 intersecting planes. The settings object is expected to have the following properties:

Output Table faces table defining the triangular faces. Must have ID columns V1, V2, and V3, containing the indices of the relevant vertices in the vertices table (not the IDs - see triangulateFaces if you want a function that will prepare an appropriate faces table). It also requires a filter column named Deleted, which is used to mark faces that were completely removed because all three vertices are outside of the halfspace.
Output Table vertices table defining the vertices. Must have a point column named Location.
vec3 pointA a corner of the box.
vec3 pointB the corner diagonally opposite to pointA.
vec3 normalA1 normal vector of face adjacent to pointA and facing inwards.
vec3 normalA2 normal vector of face adjacent to pointA and facing inwards.
vec3 normalA3 normal vector of face adjacent to pointA and facing inwards.
vec3 normalB1 normal vector of face adjacent to pointB and facing inwards.
vec3 normalB2 normal vector of face adjacent to pointB and facing inwards.
vec3 normalB3 normal vector of face adjacent to pointB and facing inwards.
Function onFaceSplit (optional) a function to be called whenever a triangle is split into two triangles (if exactly one vertex of the triangle is outside the halfspace, the clipped triangle shape is defined by two triangles). Receives the following arguments, in order: newFaceIndex, the index of the new triangle; oldFaceIndex, the index of the old triangle (which is modified to become one of the two triangles that define the remaining shape); and faces, the faces table.
Function onVertexInterpolate (optional) a function to be called whenever a new vertex is created at the point where a triangle edge (V1->V2) intersects the plane. Receives the following arguments, in order: newVertexIndex, the index of the new vertex; oldV1Index, the index of the old V1 vertex (which is inside the halfspace and will still be used in the clipped triangle); oldV2Index, the index of the old V2 vertex (which is outside the halfspace and will not be used in the clipped triangle); ratioV1V2, the fraction of the distance from V1 to V2 at which the edge intersects the plane; and vertices, the vertices table.
Boolean writeOutsideSplits (optional) if true, when a triangle is intersected by the AABB, also create output triangles for the part outside of the AABB (which will be marked as deleted).

Parameters:

Object ↓settings

Lib.clipTrianglesToHalfSpace ( ↓settings ) Alpha

Clips all triangular faces defined by the provided faces and vertices output tables so that they lie within the halfspace defined by the given plane. This implementation is based on Efficient Triangle and Quadrilateral Clipping within Shaders, Morgan McGuire, The Journal of Graphics, GPU, and Game Tools, 2011. https://casual-effects.com/research/McGuire2011Clipping/. The settings object is expected to have the following properties:

Output Table faces table defining the triangular faces. Must have ID columns V1, V2, and V3, containing the indices of the relevant vertices in the vertices table (not the IDs - see triangulateFaces if you want a function that will prepare an appropriate faces table). It also requires a filter column named Deleted, which is used to mark faces that were completely removed because all three vertices are outside of the halfspace.
Output Table vertices table defining the vertices. Must have a point column named Location.
vec3 planePoint a point on the plane that defines the halfspace.
vec3 planeNormal the normal direction of the plane that defines the halfspace (the normal points into the halfspace, i.e. triangles will be kept on the side of the plane that the normal points into, but will be clipped/removed on the other side).
Function onFaceSplit (optional) a function to be called whenever a triangle is split into two triangles (if exactly one vertex of the triangle is outside the halfspace, the clipped triangle shape is defined by two triangles). Receives the following arguments, in order: newFaceIndex, the index of the new triangle; oldFaceIndex, the index of the old triangle (which is modified to become one of the two triangles that define the remaining shape); and faces, the faces table.
Function onVertexInterpolate (optional) a function to be called whenever a new vertex is created at the point where a triangle edge (V1->V2) intersects the plane. Receives the following arguments, in order: newVertexIndex, the index of the new vertex; oldV1Index, the index of the old V1 vertex (which is inside the halfspace and will still be used in the clipped triangle); oldV2Index, the index of the old V2 vertex (which is outside the halfspace and will not be used in the clipped triangle); ratioV1V2, the fraction of the distance from V1 to V2 at which the edge intersects the plane; and vertices, the vertices table.
Boolean writeOutsideSplits (optional) if true, when a triangle is intersected by the AABB, also create output triangles for the part outside of the AABB (which will be marked as deleted).

Note that this function uses JS arrays to track edges that intersect the plane, so that a single edge does not produce duplicate output intersection vertices when it is shared by multiple clipped triangles. This means that the function could crash mXrap if a very large number of edges intersect the plane.

Parameters:

Object ↓settings

Lib.clipTriangleToUnionOfConvexPolyhedrons ( ↓v1, ↓v2, ↓v3, ↓v1ID, ↓v2ID, ↓v3ID, ↓planeSets, ↓writeVertex, ↓writeTriangle, ↓writeOuterTriangles, ↓writeInnerTriangles ) Alpha

Parameters:

vec3 ↓v1 - the location of the triangle's vertex 1
vec3 ↓v2 - the location of the triangle's vertex 2
vec3 ↓v3 - the location of the triangle's vertex 3
Number ↓v1ID - the ID of the input triangle's vertex 1
Number ↓v2ID - the ID of the input triangle's vertex 2
Number ↓v3ID - the ID of the input triangle's vertex 3
Array ↓planeSets - an array of plane sets, where each plane set defines a convex polyhedron as a collection of halfspaces, represented as an object containing two members: normals, an array of normal vectors of the halfspaces; and points an array of points of the halfspaces.
Function ↓writeVertex - a function that handles the output vertices (e.g. by writing them to an output table). The function receives four parameters: location, a vec3 containing the vertex location; ratios, a vec3 containing the ratio of each input vertex that determines the location of this output vertex (e.g. if this vertex were halfway between input vertex 1 and 2, then ratios would be [0.5, 0.5, 0]); originalIDs, a vec3 containing the ID of the input triangle's vertices [1, 2, 3]; and triLerpLookup, an object that lives for the length of this triangle clipping and may be used to cache the location of generated output vertices. The function should return the ID of the output vertex (this value will be passed to the writeTriangle function).
Function ↓writeTriangle - a function that handles the output triangles (e.g. by writing them to an output table). The function receives five parameters: outV1ID, the ID of the first output vertex as returned by writeVertex; outV2ID; outV3ID; isInside true iff the triangle is inside the clipping region; triangle the internal representation of the triangle, an array of the form [V1 location, V2 location, V3 location, V1 ratios, V2 ratios, V3 ratios].
Boolean ↓writeOuterTriangles - (defaults to false). if true, then triangles outside the clipping region will also be passed to the writeTriangle function.
Boolean ↓writeInnerTriangles - (defaults to true). if true, then triangles inside the clipping region will be passed to the writeTriangle function.

Lib.consolidateFacesAndVertices ( faces, vertices, onMoveFace, onMoveVertex ) Alpha

Consolidates output faces and vertices tables that have been clipped by the clipTrianglesToHalfSpace and/or clipTrianglesToAABB functions. These functions mark certain faces as deleted (using the filter column named Deleted) when the entire face is outside of the clipping area. They also rewrite faces to use different vertices, which can result in some vertices in the output table being unused. This function will move all non-deleted faces and used vertices to the beginning of the output table columns, and then resize the output tables down so that only the non-deleted faces and used vertices remain. It will also assign IDs to the consolidated vertices and update the faces table to use the new IDs (instead of the vertex indices as required by the aforementioned functions).

Parameters:

Table faces - the (output) faces table, requires columns V1, V2, V3, and Deleted. The vertex columns (V1 etc.) are expected to contain the indices of the relevant vertices in the vertices table, i.e. in the range [0, numVertices).
Table vertices - the (output) vertices table, requires columns Location, ID.
Function onMoveFace - (optional) function to be called when a face is moved from one index to another, receives three arguments: newIdx, the new index of the face; oldIdx, the old index of the face; and faces, the faces table.
Function onMoveVertex - (optional) function to be called when a vertex is moved from one index to another, receives three arguments: newIdx, the new index of the vertex; oldIdx, the old index of the vertex; and vertices, the vertices table.

Lib.triangulateFaces ( ↓settings ) Alpha

Copies faces and vertices, transforming quads to triangles as it goes. The settings object is expected to have the following properties:

Table Faces the input faces table, which should have columns V1, V2, V3, and optionally V4.
Table Vertices the input vertices table, which should have columns ID and Location.
Output Table OutFaces the output faces table, which should have columns V1, V2, and V3.
Output Table OutVertices the output vertices table, which should have a column named Location.
Function onWriteFace (optional) a function to be called each time a face is written to the output faces table. It receives the following arguments, in order: outIdx, the index that the face is written to; inIdx, the index that the face was read from; outFaces, the table that the face is written to; inFaces, the table that the face was read from.
Function onWriteVertex (optional) a function to be called each time a vertex is written to the output vertices table. It receives the following arguments, in order: outIdx, the index that the vertex is written to; inIdx, the index that the vertex was read from; outVertices, the table that the vertex is written to; inVertices, the table that the vertex was read from.

When this function is complete, the output faces have V1, V2, and V3 containing the table indices of the relevant vertices. This is the format required for the clipTrianglesToHalfSpace and clipTrianglesToAABB functions, so this function can be used to prepare input for those functions, even if you know that the input will never have quads (i.e. does not need triangulation).

Parameters:

Object ↓settings - The setting object.

Category: Examples

An example of all the code needed to take input faces (triangles or quads) and vertices, and produce output faces and vertices clipped to an axis-aligned bounding box:

const LibClipping = require.mx('mxjs/mesh/clipping.js');
const glMatrix = require.mx('mxjs/base/math/matrix/gl-matrix.js');
const vec3 = glMatrix.vec3;

LibClipping.triangulateFaces({
  Faces: Polygons,
  Vertices: Vertex,
  OutFaces: OutPolygons,
  OutVertices: OutVertex,
  onWriteFace: function(outIdx, inIdx, outFaces, inFaces) {
    // Copy extra face properties
    outFaces.write_Group(outIdx, inFaces.read_Group(inIdx));
  },
  onWriteVertex: function(outIdx, inIdx, outVertices, inVertices) {
    // Copy extra vertex properties
    outVertices.write_MyProperty(outIdx, inVertices.read_MyProperty(inIdx));
  },
});

const AABBMin = vec3.create();
const AABBMax = vec3.create();

if (Controls.read_MinBoundingPoint(AABBMin) && Controls.read_MaxBoundingPoint(AABBMax)) {
  LibClipping.clipTrianglesToAABB({
    faces: OutPolygons,
    vertices: OutVertex,
    minPoint: AABBMin,
    maxPoint: AABBMax,
    onFaceSplit: function(newIdx, oldIdx, faces) {
      // Copy extra face properties
      faces.write_Group(newIdx, faces.read_Group(oldIdx));
    },
    onVertexInterpolate: function(newIdx, V1, V2, ratioV1V2, vertices) {
      // Copy extra vertex properties
      vertices.write_MyProperty(newIdx, vertices.read_MyProperty(V1));
    },
  });
}

LibClipping.consolidateFacesAndVertices(OutPolygons, OutVertex,
  function (newIdx, oldIdx, faces) {
    // Copy extra face properties
    faces.write_Group(newIdx, faces.read_Group(oldIdx));
  },
  function (newIdx, oldIdx, vertices) {
    // Copy extra vertex properties
    vertices.write_MyProperty(newIdx, vertices.read_MyProperty(oldIdx));
  });

Libraries

Categories

Classes

Clipping

Library Functions

Category: Examples