API Docs Class: Face

new Face()

Creates a new BRep face.

Author:

drajmarsh

Members

:Array.<PD.Point> boundary

A sequential list of points defining the outer boundary.

Type

Array.<PD.Point>

:THREE.Color|null color

Stores the color of the face if different to the shape.

Type

THREE.Color | null

:PD.FACET faceType

The role that this face plays within the larger shape.

Type

PD.FACET

:Array.<Array.<PD.Point>> holes

A list of internal holes, each as a sequential list of points defining the inner boundary.

Type

Array.<Array.<PD.Point>>

:boolean isFace <readonly>

A flag identifying this object as a BRep face.

Type

boolean

:THREE.Plane plane

The plane equation of the BRep face.

NOTE: Faces use the value of THREE.Plane#constant as a flag to indicate whether the face is planar or curved. if the constant is not NaN, the face is planar. Otherwise it is assumed to be curved. As a result, you should always check the plane.constant property before using the plane equation. You can do this quickly using the PD.BRep.Face#isPlanar and PD.BRep.Face#isCurved methods.

Type

THREE.Plane

:Array.<PD.Point>|null triangles

A list of triangles that define the face's tessellated surface.

This is a flat array where each consecutive triplet of points form a separate triangle. Triangles are stored using the same point objects as used in the boundary and holes arrays. In fact, apart from some particular cases where the tesselation process may need to create a new interpolated vertex, they will almost always be references to the exact same point objects that define the outer and/or inner boundaries.

Type

Array.<PD.Point> | null

Methods

addHole(vertices)

Adds a new hole to the face if it is planar.

NOTE 1: It is important that the vertices array contain only points created using the addVertex() or related methods. This is because faces use the meshIndex property of each point in many of their operations, which is set to the appropriate value when the host BRep iterates its vertexList. If a point is not in the vertex list, it will very likely have an invalid meshIndex value, causing the operation to not work correctly.

NOTE 2: This method only adds holes in planar faces. Inserting holes in curved faces using a contour of points is not currently supported. To add a hole to a curved face, you must modify the triangles that make up the surface to accommodate the hole.

Parameters:

Name	Type	Description
`vertices`	Array.<PD.Point> \| Array.<Array.<PD.Point>>	An array of points or an array of arrays of points.

Returns:

Returns true if one or more holes were added.

Type: boolean

asQuad(v1, v2, v3, v4 [, color] [, normal])

Provides a fast way of creating a simple quadrilateral face.

A face can be of any shape and contain any number of internal holes. This flexibility requires tests, checks and sometimes complex calculations to triangulate its surface and compute an appropriate plane equation.

However, PD.Shell and PD.BRep objects sometimes need to add a large number of simple triangles and quads to form a complex 3D form. This method offers a fast way of reusing existing faces for that purpose by completely defining and finalising the face in one call so that no further tests, checks or calculations are required.

Parameters:

Name	Type	Argument	Description
`v1`	PD.Point		The first quad point, in model coordinates.
`v2`	PD.Point		The second quad point, in model coordinates.
`v3`	PD.Point		The third quad point, in model coordinates.
`v4`	PD.Point		The fourth quad point, in model coordinates.
`color`	THREE.Color \| number	<optional>	An optional color value to assign the face.
`normal`	THREE.Vector3	<optional>	An optional normalised direction vector.

Returns:

Returns this face to support method chaining.

Type: PD.BRep.Face

asTriangle(v1, v2, v3 [, color] [, normal])

Provides a fast way of creating a simple triangular face.

Parameters:

Name	Type	Argument	Description
`v1`	PD.Point		The first triangle point, in model coordinates.
`v2`	PD.Point		The second triangle point, in model coordinates.
`v3`	PD.Point		The third triangle point, in model coordinates.
`color`	THREE.Color \| number	<optional>	An optional color value to assign the face.
`normal`	THREE.Vector3	<optional>	An optional normalised direction vector.

Returns:

Returns this face to support method chaining.

Type: PD.BRep.Face

asTriangleFan(vertices [, color] [, normal])

Provides a fast way of creating a convex polygonal face.

This method computes the plane equation from the given vertices and arranges surface triangles using a triangle fan, as shown below. You should only use this method if you know that the vertices form a planar convex polygon.

            _.3--------2_
       _.-''   \      /  \_
    4''         \    /     \_
     \ ' .      |   /        \_
      \    ' .  \  /         _.1
       5--..__ '. /  __..--''
              ''-0-''

Parameters:

Name	Type	Argument	Description
`vertices`	Array.<PD.Point>		Three or more vertices to create the face from.
`color`	THREE.Color \| number	<optional>	An optional color value to assign the face.
`normal`	THREE.Vector3	<optional>	An optional normalised direction vector.

Returns:

Returns this face to support method chaining.

Type: PD.BRep.Face

asTriangleFanFromApex(vertices, apex [, color] [, normal])

Provides a fast way of creating a simple polygonal face.

This method computes the plane equation from the given vertices and arranges surface triangles using a triangle fan that radiates around the given apex, as shown below. You should only use this method if you know that the vertices form a simple planar polygon.

            _.3--------2_
       _.-''   \   __/   \_
    4''_ _      \ /        \_
     \     ' ' - o - . _     \_
      \          |       ' ' _.1
       5--..__   |   __..--''
              ''-0-''

Parameters:

Name	Type	Argument	Description
`vertices`	Array.<PD.Point>		Two or more vertices to create the face from.
`apex`	PD.POint		The apex point somewhere inside the polygonal boundary.
`color`	THREE.Color \| number	<optional>	An optional color value to assign the face.
`normal`	THREE.Vector3	<optional>	An optional normalised direction vector.

Returns:

Returns this face to support method chaining.

Type: PD.BRep.Face

bothPointsOnSameBoundaryXY(point1, point2 [, tolerance])

Determines if the given points are on or close to the same face boundary in the XY plane.

Parameters:

Name	Type	Argument	Description
`point1`	THREE.Vector3		The first point to to check if on boundary.
`point2`	THREE.Vector3		The second point to to check if on boundary.
`tolerance`	number	<optional>	The distance threshold to define closeness, defaults to 1e-3.

Returns:

Returns true if both points on the same boundary in the XY plane, otherwise false.

Type: boolean

computeArea()

Calculates the surface area of the face, in metres squared (m2).

Returns:

Returns the surface area in metres squared (m2).

Type: number

computeBoundaryIntersectionPointXY(from, to, target)

Computes the first intersection point, if any, between the give line segment and any of the boundary segments on the polygon.

Parameters:

Name	Type	Description
`from`	THREE.Vector3	The first point in the line.
`to`	THREE.Vector3	The second point in the line.
`target`	THREE.Vector3	The vector to receive the intersection point, may be the same as `to`.

Returns:

Returns true if an intersection point was found and target was updated.

Type: boolean

computeBoundingEdgesFromTriangles()

Analyzes the triangles in the face and computes those edges that are not shared with adjacent triangles.

Only call this method after all faces and vertices have been added, and if you are sure that all vertices used in the face triangles are also in the PD.BRep#vertexList array. If you are unsure, call the PD.BRep#validateVertexList method first.

The resulting edges can be used to create bounding edge loops or for creating wireframes or edge highlighting.

Returns:

Returns an array of open edges, each in the form [p1, p2].

Type: Array.<Array.<PD.Point>>

computeBounds(min, max)

Computes the bounding extents of the face and updates the arguments.

Unlike a PD.Polygon, faces do not store their own extents. Thus, this method is used to update the given arguments if any point in this face is outside their existing range.

NOTE: This method changes values within the min and max parameters.

Parameters:

Name	Type	Description
`min`	THREE.Vector3	The point to receive the minimum extent.
`max`	THREE.Vector3	The point to receive the maximum extent.

Returns:

Returns true if min/max were set.

Type: boolean

computeClosestPointOnBoundary(point, target)

Computes the closest point that lies on the boundary of the face.

Parameters:

Name	Type	Description
`point`	THREE.Vector3	The point to check if on boundary.
`target`	THREE.Vector3	The vector to receive the closest point, may be the same as `point`.

Returns:

Returns true if a closest point was found.

Type: boolean

computeClosestPointOnBoundaryXY(point, target)

Computes the closest point that lies on the boundary of the face in the XY plane.

Parameters:

Name	Type	Description
`point`	THREE.Vector3	The point to check if on boundary.
`target`	THREE.Vector3	The vector to receive the closest point, may be the same as `point`.

Returns:

Returns true if a closest point was found.

Type: boolean

computeGeometricCenter(center)

Computes the geometric center of the face.

NOTE: This method changes values within the center parameter.

Parameters:

Name	Type	Description
`center`	THREE.Vector3	The point to receive the center position.

Returns:

Returns true if the center point was computed and set.

Type: boolean

computePerimeter()

Calculates the total perimeter length of the face, in millimetres.

Returns:

Returns the total perimeter length in millimetres (mm).

Type: number

computePlaneEquation( [makePlanar])

Calculates the plane equation of the face.

This method uses Newell's Method to compute the surface normal. If the surface is tagged as non-planar (where plane.constant == NaN), then the plane equation will not be calculated. However, you can pass true for the makePlanar argument to set the face as planar and calculate its plane equation

Parameters:

Name	Type	Argument	Description
`makePlanar`	boolean	<optional>	An optional flag to set the face as planar and calculate a plane equation.

Returns:

Returns true if a valid plane equation was calculated or false if non-planar, there were insufficient points or they are all co-linear.

Type: boolean

computePlaneIntersectionPoints(plane, intersection, results)

Computes all the intersection points between this face boundary and hole line segments with the given plane.

This method cycles through all the boundary and hole lines within the face, or its triangles if non-planar, computing the intersection points with the given plane and storing them in the results array.

Parameters:

Name	Type	Description
`plane`	THREE.Plane	The plane to intersection all faces with.
`intersection`	THREE.Vector3	The point to temporarily store intersection points.
`results`	Array.<THREE.Vector3>	The array to the resulting intersection points to.

Returns:

Returns the array of intersection points.

Type: Array.<THREE.Vector3>

computeSliceProfile(polygon, indexer [, results])

Determines any sliced lines that the given polygon makes across this face.

The indexer is used to store unique [x,y,z] vector arrays defining the end points of each slice line. Slice lines are then stored as arrays of two (2) vertex indices in the results array.

               +
               |\
               | \
               |  \
               |   \
               |    \
               |     \
             _+---o---\---+.
         _.-'  |   \   \ 2  '.
     _.-'      +    \   +     '.
   +'       1   \    \  |   __..+
    '.           \  __o.--''
      '.    __..--''    |
        '+''       \    |
                    \   |
                     \  |
                      \ |
                       \|
                        +

Parameters:

Name	Type	Argument	Description
`polygon`	PD.Polygon		The polygon defining the cutting plane.
`indexer`	PD.Indexer		The indexer to add unique [x,y,z] vector arrays to.
`results`	Array.<Array.<number>>	<optional>	An array of edges to add any intersection lines to.

Returns:

Returns the results array or a newly created array, containing [index1,index2,face] entries.

Type: Array.<Array>

computeVertexNormals()

Computes the averaged normal of all triangulated vertices used to define the surface of a curved face.

Returns:

Returns true if this face is curved and the triangle vertex normals were updated.

Type: boolean

copyDashedLinesToPolyMesh(mesh, size)

Adds the outline as architectural-style extended lines to the given mesh.

NOTE: This method does NOT reuse any shared vertices that may have already been added to the mesh.

Parameters:

Name	Type	Description
`mesh`	PD.PolyMesh	The dynamic mesh to add the drafting to.
`size`	number	The size of line dashes, in model coordinates.

Returns:

Returns true if geometry was added to the mesh.

Type: boolean

copyDraftingLinesToPolyMesh(mesh, size)

Adds the outline as architectural-style extended lines to the given mesh.

NOTE: This method does NOT reuse any shared vertices that may have already been added to the mesh.

Parameters:

Name	Type	Description
`mesh`	PD.PolyMesh	The dynamic mesh to add the drafting to.
`size`	number	The size of the extended overrun, in model coordinates.

Returns:

Returns true if geometry was added to the mesh.

Type: boolean

copyOutlineToPolyMesh(mesh)

Adds the outline of the face to the given mesh.

NOTE: This method does NOT reuse any shared vertices that may have already been added to the mesh.

Parameters:

Name	Type	Description
`mesh`	PD.PolyMesh	The dynamic mesh to add the outline to.

Returns:

Returns true if geometry was added to the mesh.

Type: boolean

copySharedDraftingLinesToPolyMesh(mesh, size)

Adds an architectural-style extended outline to the given mesh using shared vertex indices.

NOTE: This method checks each vertex to see if it has already been added to the mesh. Thus, it must be called only after all vertex indexes have been cleared/reset.

Parameters:

Name	Type	Description
`mesh`	PD.PolyMesh	The dynamic mesh to add the drafting to.
`size`	number	The size of the extended overrun, in model coordinates.

Returns:

Returns true if geometry was added to the mesh.

Type: boolean

copySharedOutlineToPolyMesh(mesh)

Adds a face outline to the given mesh using shared vertex indices.

NOTE: This method checks each vertex to see if it has already been added to the mesh. Thus, it must be called only after all vertex indexes have been cleared/reset.

Parameters:

Name	Type	Description
`mesh`	PD.PolyMesh	The dynamic mesh to add the outline to.

Returns:

Returns true if geometry was added to the mesh.

Type: boolean

copySurfaceToPolyMesh(mesh [, noColor])

Add face surface triangles to the given mesh.

NOTE: This method clears and resets mesh vertex indexes and checks each vertex to see if it has already been added to the mesh. Once this method has been called, it is safe to use the PD.BRep.Face#copySharedOutlineToPolyMesh and PD.BRep.Face#copySharedDraftingLinesToPolyMesh methods which also check each vertex to see if it has already been added to the mesh.

Parameters:

Name	Type	Argument	Description
`mesh`	PD.PolyMesh		The dynamic mesh to add the polygon to.
`noColor`	boolean	<optional>	When true, the surface color is not set, defaults to false.

Returns:

Returns true if geometry was added to the mesh.

Type: boolean

copyToPolyMesh(mesh [, noOutline] [, noColor])

Adds the face to the given dynamic mesh.

This methods first calls the PD.BRep.Face#copySharedOutlineToPolyMesh method and, if outlines are being rendered, either the PD.BRep.Face#copySharedOutlineToPolyMesh or PD.BRep.Face#copySharedDraftingLinesToPolyMesh methods. This means that it makes its best efforts to reuse any vertices that may have already been added to the mesh rather that adding them more than once.

Parameters:

Name	Type	Argument	Description
`mesh`	PD.PolyMesh		The dynamic mesh to add the polygon to.
`noOutline`	boolean	<optional>	When true, boundary outlines are not included, defaults to false.
`noColor`	boolean	<optional>	When true, the surface color is not set, defaults to false.

Returns:

Returns true if geometry was added to the mesh.

Type: boolean

fromClipperPaths(paths, plane [, brep] [, offset] [, quaternion])

Converts one or more 2D ClipperLib paths back into a BRep face.

As ClipperLib works with 2D {X,Y} objects, they must be transformed from the XY cartesian plane back into 3D space. This method uses the the given plane equation normal to compute a quaternion to rotate points from the XY plane. This quaternion is applied to each point in the paths, which is more computationally expensive than using the axis of greatest surface exposure, but better retains the orientation and winding order of points.

Using quaternions to rotate the points to and from the XY plane results in the 2D rotated positions always align correctly with their 3D positions on the surface of the plane. However, if polygons have slightly different plane equations or their points are not all exactly co-planar, then small cumulative inaccuracies can build up over multiple conversions, far more than the with axis-based conversion. Thus, use this method only if you know that the plane equations you are using are consistent across all faces.

If no plane equation is given, the XY plane is assumed (Z=0). If a number is given in place of the plane equation, then that number is used a Z-axis offset in the XY plane (Z = toNumber(plane)). An optional offset can be given to move the 3D points along the plane normal by the given amount, which can be useful to avoid surface Z-fighting.

If you have already computed the quaternion to rotate the points to/from the XY plane, you can provide it as the last argument to avoid it having to be computed again.

Parameters:

Name	Type	Argument	Description
`paths`	Array		One or more ClipperLib paths containing {X,Y} Clipper points.
`plane`	THREE.Plane \| number		The plane equation to project points onto or a Z-axis height.
`brep`	PD.BRep	<optional>	An optional shell to reuse vertices from.
`offset`	number	<optional>	An offset value from the plane in its axial direction.
`quaternion`	THREE.Quaternion	<optional>	An optional quaternion to use rather than computing it.

Returns:

Returns this BRep face to support method chaining.

Type: PD.Polyline

fromJSON(data, vertices)

Safely copy properties from a source object.

See the PD.Base#fromJSON method for more details.

NOTE: You should avoid calling this method directly on faces unless you really know what you are doing. You should use the host BRep PD.BRep#fromJSON method instead. This is because vertices in this method are imported as their index within the host BRep's PD.BRep#vertexList rather than their position, normal and uv coordinates. This makes it absolutely necessary that the host BRep vertex list has already been loaded before this method can reference them via the vertices argument.

Override this method in derived classes to read additional properties, but call super.fromJSON(data); at the top of the method.

Parameters:

Name	Type	Description
`data`	object	The source object containing data to copy.
`vertices`	Array.<PD.Point>	The list of vertices that vertex array reference.

Returns:

Returns this face to support method chaining.

Type: PD.BRep.Face

Example

// Overriding this method.

class MyFace extends PD.BRep.Face {
     /// ...
     fromJSON(data, vertices) {

         super.fromJSON(data, vertices);

         if ('extraData' in data) {
             this.extraData = PD.Utils.toIntegerInRange(data.extraData, this.extraData, 0, 16);
         }

         if ('evenMoreData' in data) {
             this.evenMoreData = PD.Utils.toNumber(data.evenMoreData, this.evenMoreData);
         }

         return this;

     };
     /// ...
 };

hasContent()

Determines whether or not the face has valid content.

Returns:

Returns true if the face has a boundary and/or triangles.

Type: boolean

intersectRay(ray, target)

Determines the intersection point between a ray and this face.

Parameters:

Name	Type	Description
`ray`	THREE.Ray	The ray to intersect the face with.
`target`	THREE.Vector3	The vector to receive the intersection point.

Returns:

Return true if the face was intersected, or false if not.

Type: boolean

isCurved()

Determines whether or not the face is curved and does not have a valid plane equation.

When a face is curved, the normals of each of its individual vertices will used when it is meshed rather than its plane equation normal. The normal component of its plane equation will still be calculated from its vertices, but the constant component will be set to NaN to indicate that it is curved and has no single plane equation. This can sometimes allow for some small optimisations where flat and curved faces can share vertices, with the vertex normal being computed only for the curved face. Unless they are two parts of a continuously curved surface, two curved faces should not share vertices unless the normals at each vertex are equal.

A curved face requires its PD.BRep.Face#triangles array to define the curve, and that it be generated as part of the face creation process. This is because the face class has no knowledge of the equations to use for the curve or how to tesselate it. This is the role of the host application or generator class.

Returns:

Returns true if the face is curved and/or non-planar.

Type: boolean

isInsideFrustum(frustum, intersect)

Determines whether or not the polygon is inside the given frustum.

Parameters:

Name	Type	Description
`frustum`	THREE.Frustum	The frustum to check if inside.
`intersect`	boolean	Whether to also check for intersection selection.

Returns:

Returns true if inside, otherwise false.

Type: boolean

isPlanar()

Determines whether or not the face is planar and has a valid plane equation.

When a face is flat, the normal component of its plane equation will be used for all vertices when it is meshed rather than their individual vertex normals. This can sometimes allow for small optimisations where planar faces can share vertices with curved surfaces. An example of this would be the flat top and bottom faces of a cylinder sharing vertices with the curved side face. In this case, the vertex normals are computed only for the curved face, which will used those normals directly, whilst the planar top and bottom faces will use only the share position data, with their plane normals being used instead of the vertex normals.

For the same reason, flat planar faces can share vertices with any number of other flat planar faces as their vertex normals are ignored in favour of the plane equation normal. Also, if the PD.BRep.Face#triangles array is empty, the face will be automatically tessellated based on its outer boundary and any holes it contains.

Returns:

Returns true if the face is planar and has a valid plane equation.

Type: boolean

isPointInside(point [, selecting])

Determines whether or not the given point is within the surface of this face.

As triangles in a planar face are assumed to all share the same surface normal, this calculation can be reasonably fast. This method also correctly handles points that are inside internal holes/contours.

When the selecting argument is true, only the outer boundary of the face is tested as this allows for subsequent drilling down into holes and openings. This means that triangle intersection is not used when selecting a face.

Parameters:

Name	Type	Argument	Description
`point`	THREE.Vector3		The point to to check if inside.
`selecting`	boolean	<optional>	Whether or not this is being use to select a face, defaults to false.

Returns:

Returns true if inside, otherwise false.

Type: boolean

isPointInsideHole(point, index)

Determines whether or not the given point is within an internal hole.

This method only works for planar faces which have at least one hole. Its sums the signed angle between the given point and each line segment of the given contour boundary. If the total angle is near zero, then the point must be outside. If near 360, it must be inside.

Parameters:

Name	Type	Description
`point`	THREE.Vector3	The point to to check if inside.
`index`	number	The index of the contour within the polyline.

Returns:

Returns true if inside, otherwise false.

Type: boolean

isPointOnBoundary(point [, tolerance])

Determines if the given point is on or close to the face boundary.

Parameters:

Name	Type	Argument	Description
`point`	THREE.Vector3		The point to to check if inside.
`tolerance`	number	<optional>	The distance threshold to define closeness, defaults to 1e-3.

Returns:

Returns true if on boundary, otherwise false.

Type: boolean

isPointOnBoundaryXY(point [, tolerance])

Determines if the given point lies on or close to the face boundary in the XY plane.

Parameters:

Name	Type	Argument	Description
`point`	THREE.Vector3		The point to to check if inside.
`tolerance`	number	<optional>	The distance threshold to define closeness, defaults to 1e-3.

Returns:

Returns true if on boundary in the XY plane, otherwise false.

Type: boolean

naiveTrimToPlane(brep, plane)

Naively trims a convex face to the given plane.

This method is much simpler and, as the name indicates, more naive than the splitByPlane methods as it is intended for use only with concave faces and to re-use existing faces and vertices at the plane intersection points rather than creating new ones.

               +
               |\
               | \
               |  \
               |   \
               |    \
               |     \
   +--------------+  -\ -  +
   |           |   \   \    .
   |    face   +    \   +    .
   |            \    \  |     .
   +------------------+ | -  - +
                  \     |
                   \    |
                    \   |
                     \  |
                      \ |
                       \|
                   <--- + plane

Parameters:

Name	Type	Description
`brep`	PD.BRep	The parent BRep in case new vertices are required.
`plane`	THREE.Plane	The plane to clip the face with.

Returns:

Returns true if face is valid and all or part in front.

Type: boolean

resetMeshIndexes()

Resets the PD.Point#meshIndex property of all vertices to -1.

Returns:

Returns this face to support method chaining.

Type: PD.BRep.Face

reverse()

Reverses the order of vertices as well as the surface normal and plane equation.

Returns:

Returns this face to support method chaining.

Type: PD.BRep.Face

setBoundary(vertices)

Sets the outer boundary of the face if it is planar.

Parameters:

Name	Type	Description
`vertices`	Array.<PD.Point>	An array of points or an array of arrays of points.

Returns:

Returns true the boundary was set.

Type: boolean

shareWithShell(shell [, reverse])

Adds the face to the given shell.

NOTE: This method is intended for quickly sharing faces with element and junction shells for selection purposes rather than replicating entire shapes. As a result, the shell facets will share the BRep vertices rather than creating new copies.

Parameters:

Name	Type	Argument	Default	Description
`shell`	PD.Shell			The shell to add the face to.
`reverse`	boolean	<optional>	false	If true, the face orientation will be reversed, defaults to false.

Returns:

Returns the newly added facet or null if the face was invalid.

Type: PD.Polygon

splitByPlane(brep, plane, frontFaces, rearFaces)

Splits a face into one or more faces by the given plane.

               +
               |\
               | \
               |  \
               |   \
               |    \
               |     \
             _+---+---\----+
         _.-'  |   \   \ 2  \
     _.-'      +    \   +    \
   +'       1   \    \  |   _.+
    '.           \  __+.--''
      '.    __..--''    |
        '+''       \    |
                    \   |
                     \  |
                      \ |
                       \|
                        +

Given a plane and two arrays, this method splits this face into areas that are on either side of the plane. The areas on each side are added to the two arrays. If either of the arrays are not given, the faces to be added to that side will be ignored.

NOTE: This method reuses vertices and faces already in the BRep, so must only be used between calls to reuseStart() and reuseEnd().

Parameters:

Name	Type	Description
`brep`	PD.BRep	The BRep to add new points and faces to.
`plane`	THREE.Plane	The plane to clip the face with.
`frontFaces`	Array.<PD.BRep.Face>	The list to store areas in front of the plane (same direction as surface normal).
`rearFaces`	Array.<PD.BRep.Face>	The list to store areas behind the plane (opposite direction to surface normal).

Returns:

Returns true if face is valid and was either in front, behind or split.

Type: boolean

splitByPlaneOnlyIfConvex(brep, plane, frontFaces, rearFaces)

Splits a face into one or more faces by the given plane.

               +
               |\
               | \
               |  \
               |   \
               |    \
               |     \
             _+---+---\----+
         _.-'  |   \   \ 2  \
     _.-'      +    \   +    \
   +'       1   \    \  |   _.+
    '.           \  __+.--''
      '.    __..--''    |
        '+''       \    |
                    \   |
                     \  |
                      \ |
                       \|
                        +

NOTE: This method reuses vertices and faces already in the BRep, so must only be used between calls to reuseStart() and reuseEnd().

Parameters:

Name	Type	Description
`brep`	PD.BRep	The BRep to add new points and faces to.
`plane`	THREE.Plane	The plane to clip the face with.
`frontFaces`	Array.<PD.BRep.Face>	The list to store areas in front of the plane (same direction as surface normal).
`rearFaces`	Array.<PD.BRep.Face>	The list to store areas behind the plane (opposite direction to surface normal).

Returns:

Returns true if face is valid and was either in front, behind or split.

Type: boolean

tesselate(brep)

Tessellates a face using the robust LibTess algorithm.

Parameters:

Name	Type	Description
`brep`	PD.BRep	The BRep this face belongs to.

Returns:

Returns a flat array of points from the given face, where each consecutive triplet forms a triangle.

Type: Array

toClipperPaths( [clipCache])

Converts face boundary and holes into 2D ClipperLib.Path arrays.

As ClipperLib works with 2D {X,Y} objects, a 3D face must be transformed from its 3D orientation to a flat cartesian plane. This method uses the face's plane equation normal to compute a quaternion that rotates the face onto the XY plane. This quaternion is applied to each point in the face, which is more computationally expensive than using the axis of greatest surface exposure, but better retains the orientation and winding order of points.

Using quaternions to rotate the points to and from the XY plane results in the 2D rotated positions always align correctly with their 3D positions on the surface of the plane. However, if faces have slightly different plane equations or their points are not all exactly co-planar, then small cumulative inaccuracies can build up over multiple conversions, far more than the with axis-based conversion. Thus, use this method only if you know that the plane equations you are using are consistent across all faces.

Parameters:

Name	Type	Argument	Description
`clipCache`	PD.Clipper.Cache	<optional>	An optional cache for reusing 2D clipper points.

Returns:

Returns an array of one or more ClipperLib.Path arrays, each containing {X,Y} Clipper points for the outer boundary and any holes within it.

Type: Array

toClipperPathsByAxis( [axis] [, clipCache])

Converts the outer boundary and holes of a face into 2D ClipperLib.Path arrays using the axis of greatest surface exposure.

As ClipperLib works with 2D {X,Y} objects, the 3D face must be translated into a 2D cartesian plane. This method uses the given axis or, if no axis is given, the calculated axis for the face.

Converting to 2D and then back to 3D in the axis with the largest surface exposure involves only a small amount of maths so is very quick and accuracy is more than acceptable. It is required when performing operations on multiple shapes that may not be on exactly the same plane - or on faces whose points may not all be exactly co-planar - as positions will be very stable even after multiple conversions. However, if the plane normal is not exactly aligned with one of the cartesian axis, then the 2D point positions will be skewed slightly compared to their positions on the surface of the plane.

Using quaternions to rotate the points to and from the XY plane results in the 2D rotated positions always aligning correctly with their 3D positions on the surface of the plane. However, if faces have slightly different plane equations or their points are not all exactly co-planar, then small cumulative inaccuracies can build up over multiple conversions, far more than when using the axis-based conversion implemented in this method.

Parameters:

Name	Type	Argument	Description
`axis`	PD.AXIS	<optional>	The axis to use when converting, defaults to `this.axis`.
`clipCache`	PD.Clipper.Cache	<optional>	An optional cache for reusing 2D clipper points.

Returns:

Returns an array of one or more ClipperLib.Path arrays, each containing {X,Y} Clipper points.

Type: Array

toJSON( [data])

Converts the face to a simple POJO for conversion to JSON.

This method is used to copy, store and save the data for a face, so the returned object must have all the properties required to be able to rebuild this instance in its entirety when passed to the class constructor.

NOTE: You should avoid calling this method directly on faces unless you really know what you are doing. You should use the host BRep PD.BRep#toJSON method instead. This is because vertices in this method are exported as their index within the host BRep's PD.BRep#vertexList rather than their position, normal and uv coordinates. This makes it absolutely necessary that the PD.BRep#validateVertexList method on the the host BRep has been called immediately prior in order to have properly set the PD.Point#meshIndex values on each vertex for export.

Override this method in derived classes to add additional properties, but call data = super.toJSON(data); at the top of the method, as shown in the example below.

Parameters:

Name	Type	Argument	Description
`data`	object	<optional>	An optional parent object to append this data to.

Returns:

Returns a Plain Old Javascript Object (POJO).

Type: object

Example

// Overriding this method.

class MyFace extends PD.BRep.Face {
     /// ...
     toJSON(data) {

         data = super.toJSON(data);

         data.extraData = this.extraData;
         data.evenMoreData = this.evenMoreData;
         return data;

     };
     /// ...
 };

update(brep)

Computes the plane equation and surface triangulation.

A valid surface argument is required so that any new interpolated vertices created during the tesselation process can be drawn from and stored in the pool of reusable vertices forming the surface.

Parameters:

Name	Type	Description
`brep`	PD.BRep	The BRep this face belongs to.

Returns:

Returns this face to support method chaining.

Type: PD.BRep.Face

addSharedContourDraftingLinesToPolyMesh(contour, mesh, size, closed) <static>

Joins an array of points with architectural-style extended lines in the given mesh.

NOTE: This method checks each vertex to see if it has already been added to the mesh. Thus, it must be called only after all vertex indexes have been cleared/reset.

Parameters:

Name	Type	Description
`contour`	Array.<PD.Point>	The sequential list of points to add.
`mesh`	PD.PolyMesh	The dynamic mesh to add the drafting lines to.
`size`	number	The size of the extended overrun, in model coordinates.
`closed`	boolean	Whether or not to join the last point to the first.

addSharedContourOutlineToPolyMesh(contour, mesh [, closed]) <static>

Joins an array of points with lines in the given mesh.

NOTE: This method checks each vertex to see if it has already been added to the mesh. Thus, it must be called only after all vertex indexes have been cleared/reset.

Parameters:

Name	Type	Argument	Description
`contour`	Array.<PD.Point>		The sequential list of points to add.
`mesh`	PD.PolyMesh		The dynamic mesh to add the drafting lines to.
`closed`	boolean	<optional>	Whether or not to join the last point to the first, defaults to false.