Class: BRep

PD. BRep

Defines a multi-faceted boundary representation of a shape.

A boundary representation (BRep) is a method used in computer-based modelling to mathematically define a 3D shape based on its bounded volume. As the name suggests, the volume is defined by a set of one or more connected surfaces that, when taken together, define the boundary between what is considered inside and outside of the shape. For example, the volume of a spheroid can be represented by a single curved surface joined at the poles or the meridian. The volume of a cylinder requires three surfaces, being two planar ends and a curved surface joined at a seam that runs between them. The volume of a cuboid on the other hand, requires six separate rectangular planar surfaces.

Bounding surfaces within a BRep are called 'faces' and may be either planar or curved. Planar faces are flat surfaces defined by a single plane equation and a boundary of connected co-planar vertices (or points) that define the extents of the face. Curved faces do not have a single plane equation and often no boundary, but are instead defined by a series of triangles that each join three vertices. Each vertex then has its own surface normal that defines the curvature of the face at that point in space.

By defining the positions of these vertices and the face boundaries or triangulations that connect them, a BRep can define the shape of almost any 3D object. This includes solid objects that have a definite inside and outside, or open surfaces that have only a front and back without a volume.

Planar vs Curved Faces

The primary difference between a planar and curved face is that planar faces can be defined by just their boundary, from which their plane equation and triangulation can be automatically derived. When added to a renderable mesh, all vertices in the planar face's triangulation are output with the surface normal and color (if defined) of the face itself, rather than those assigned to individual vertices. This means that planar faces can share boundary vertices with other faces without having to worry about what normals or colors may have been assigned.

Curved faces on the other hand, can only be defined by their surface triangulation, with each vertex having its own surface normal (and color if defined). This means that curved faces must already have been triangulated before being added to the BRep, as there is no way to automatically derive this from just a boundary. When added to a renderable mesh, all vertices in the curved face's triangulation are output with their own surface normals and colors (if defined), allowing for smooth shading across the face. If a curved surface has a boundary or holes defined, these are only output as edges/outlines as the given triangulation fully defines the surface and must already accommodate them.

Whilst a curved surface may share vertices with other faces, this is only viable when the faces form part of a continuous surface, such as a fillet between two planar faces or multiple parts of the same curved or NURBS surface. If two curved faces meet at a sharp edge, then you should not share vertices but instead create separate vertices for each face at that position, each with their own normal and color (if required).

Surface normals can be assigned to a vertex via its PD.Point#normal property or PD.Point#setNormal method. Similarly, you can assign a vertex's color using the PD.Point#color property or PD.Point#setColor method, and/or its UV coordinates using the PD.Point#uv property and PD.Point#setUV method. As most PD.PolyMesh instances use an outline material that does not use a vertex's normal, uv or color, a BRep's edges and boundaries can share any vertices with the triangles of any face.

On a technical level, a curved face is signified by the constant component of its plane equation being set to NaN to indicate that there is no single plane equation for that face. The normal component will still be computed, but will be the average for all vertices in the face. See the isPlanar and isCurved methods for more detailed info on this.

Edges and Boundaries

By default, a BRep will add both triangles and boundary outlines for each face when rendered to a mesh. However, you can use edges to either augment the shape by adding additional lines, or to restrict the rendered outlines to only the ones that you have added. This is controlled by the hasUniqueEdges flag, which initially defaults to false.

If the BRep hasUniqueEdges flag is false or the edge list is empty, faces will be rendered with both their surfaces and outlines. If the edge list is not empty, the edges will be added as additional lines to the mesh.

If the BRep hasUniqueEdges flag is true and the edge list is not empty, it is assumed that the edge list defines all the required outlines for the surface and only the surface triangles of each faces will be added to the mesh.

Manifold or Non-Manifold

When the edges of all faces in a BRep are shared by exactly two faces, one in the direction v1 -> v2 and the other in the direction v2 -> v1, then it is said to be 'manifold', basically a closed shape that can be used to define a solid. You can think of a closed BRep as being able to hold water inside it and, no matter which way you turn it or shake it about, none of the water can escape from inside. If it can do this, then it can also define the extents of a solid object that has a definite inside (solid) and outside (space).

If any edge is only shared by a single face, then there must be an opening through which water can leak, so it is said to be an open shape and can be used to define a partial shell or open surface. In such cases, the BRep is said to be 'non-manifold' and cannot be used to define a solid, but can be used to define the front and back of a thin material. This is true also of edges that are shared by more than two faces, which can occur in theoretical shapes, but rarely in physically buildable geometry.

The flexibility of a BRep allows you to define not just open shapes, but also completely disjoint faces that represent things like the leaves of a tree or the separate panes of glass in a curtain wall or space frame. As a result, it is up to each developer to ensure that the BRep they create is suitable for their intended use, whether that be a closed solid, open shell or collections of disjoint faces.

Class Design

This class is designed to both define the shapes that the framework uses and be a flexible, efficient and relatively lightweight store for 3D geometry. In large modelling projects, potentially containing many tens of thousands of independent elements, it is simply not feasible for each one of them to store its own renderable mesh with flat vertex attribute and index buffers, and then to rely on THREE.js to manage them all as hierarchical objects within a scene. This may be feasible in small models, but once you get into larger projects with furniture, structure, services and landscaping, the overhead of maintaining and rendering them all quickly becomes prohibitively expensive.

Thus, the BRep class offers an interim storage format that can be quickly added to a renderable mesh, but in a way that can also be directly selected, edited and efficiently ray-traced for building performance analysis.

Efficiencies

The BRep data format uses a cache of PD.BRep.Face objects to store different parts of the surface(s) that form the geometry of an element within a model. Faces are designed to draw from a similar cache of shared PD.Point objects to use as their vertices. This allows faces that share a common edge to also share the vertices on that edge. Similarly, flat planar faces can share common vertices with other flat planar faces as each face can define its own surface normal when adding themselves to a mesh.

This means that a single vertex can be shared by multiple faces, multiple edges and multiple triangles. This not only allows for some complex analysis of the shape (such as finding shared edges or creases within surfaces), but also significant efficiency when storing geometry for later conversion to a PD.PolyMesh.

To maintain the efficiencies of this data structure, you must always use vertices created by the addVertex() and related methods when adding geometry. This method efficiently reuses PD.Point objects from the shared cache of vertices and will properly initialise and/or create them as needed. To significantly speed up the process of adding themselves to renderable meshes, boundaries and triangulations in the PD.BRep.Face class uses direct references to these reuseable PD.Point objects rather than indexes into the vertexList array. Whilst it may be tempting to create your own point instances when creating faces, this will likely create problems for you in the future, as described in the following section.

Reusability

This class is designed to be dynamically reused rather than thrown away whenever the BRep shape's geometry changes. A great deal of the dynamic editing of building geometry involves dragging things around or changing their shape. This typically results in mainly positional changes for multiple vertices across the BRep, with its overall structure (number of vertices, faces, edges and triangles) remaining very similar. Reusing the existing BRep often means no requirement for any additional memory allocation or garbage collection. If additional memory is required or some released, the amount is only the incremental difference rather than a reallocation of the entire set of arrays and objects.

You must therefore call the reuseStart() method to begin reusing the BRep, and then the reuseEnd() method when you are done using it in order to trim the internal arrays to their new length.

new BRep()

Creates a new multi-face boundary representation.

Author:

drajmarsh

Classes

Face
Factory
SelectionHandler
SphereGenerator

Members

:THREE.Color|number|null color

Stores the default color of the shape.

This value will bne overridden by any color assigned to individual faces or vertices within the BRep. If this value is null, the current mesh color will be used instead.

Type

THREE.Color | number | null

:Array.<PD.Point> edgeList

A list of vertex lists that add lines or edges to the shape.

This list is used and reused to create and store edges and outlines whenever some of the PD.BRep.add...() methods are used. Each edge is an array of two or more vertices that will be rendered as an open line. If you want this line closed, simply repeat the first vertex in the array at the end of the array.

If the hasUniqueEdges option is true and the edge list is not empty, it is assumed that the edge list defines all the required outlines for the BRep and faces will only be displayed with triangles.

If the hasUniqueEdges option is false or the edge list is empty, faces will be rendered with both their surfaces and outlines. If the edge list is not empty, the edges will be added as additional lines to the mesh.

Type

Array.<PD.Point>

:THREE.Box3 extents

The spatial extents of the BRep shape, in model units.

This is reset to empty when the reuseStart() method is called and updated automatically as you add vertices and faces to the BRep.

Type

THREE.Box3

:Array.<PD.BRep.Face> faceList

A list of faces that make up the BRep.

This list is is used and reused to create and store faces whenever any of the PD.BRep.add...() methods are used. Faces represent flat or curved surfaces that can form manifold geometry when all of their edges are shared, or non-manifold when there are openings in the shape or it is just a series of arbitrary disconnected surfaces floating in space.

Type

Array.<PD.BRep.Face>

:boolean hasUniqueEdges

Whether or not the edge list contains all of the unique edges of the BRep.

A BRep is a simple list of faces and doesn't typically know which of them are adjacent to each other. When rendered to a mesh, it typically includes both the surface triangles and outlines of each face. However, this means that any shared edges between adjacent faces are added twice, and will therefore be rendered twice (their vertices are only added once, but the triangle and edge indexes that reference those vertices will be repeated in the opposite order).

In most instances this is not a problem and makes the shape generation relatively simple and fast. However, the cost of this is a small amount of overhead as the mesh line index array is a bit bigger than it needs to be and, if you are using a semi-transparent line material, shared edges will appear slightly darker than unshared edges as they as drawn more than once.

You can overcome this when generating a BRep shape by first determining all the unique edges in the shape and using the addEdge() method to add them to the edgeList. If you then set this option to true, only the surfaces of each face will be added to the mesh, not their outlines, and only the edges in edgeList will be added as lines.

Type

boolean

:boolean hasVertexAttributes

Whether or not all faces and edges use only vertices in the shape's vertexList and all vertices each have their own surface normal and texture coordinate.

When you set this value to true, you must have created each face and edge using only references to PD.Point instances that have been added to the vertexList, and that each one in the triangulation of faces has a valid PD.Point#normal and PD.Point#uv properties.

This allows the BRep to render all its vertices in one go, rather than having to render them separately for each face that has a different surface normal.

Type

boolean

:boolean isBRep <readonly>

A flag identifying this object as a BRep.

Type

boolean

:number updateIndex

An optional index value used to check if the BRep geometry needs updating.

Some geometry generators store a value in this property whenever they update or change the geometry of a shape. They then increment their own internal value whenever any of their parameters change. They can then check to see if the value stored by a dependant BRep shape is less than their own value in order to only update it when actually required.

Type

number

:boolean useOverflowCache

Whether or not to use the overflow cache for vertices and faces.

BRep's always recycle existing vertices and faces when you call the reuseStart and reuseEnd methods. However, by default, any excess vertices and faces after a rebuild are discarded.

If you set this option to true, then any leftover vertices and faces will be stored in a persistent overflow cache and reused if the next rebuild requires more vertices or faces than the previous rebuild. This cache remains in memory until the BRep is destroyed or its clear() method is called.

Type

boolean

:Array.<PD.Point> vertexList

A list of PD.Point vertices that define the corners of each face/edge.

This list is used and reused to create and store vertices whenever any of the PD.BRep.add...() methods are used. Whilst each face stores its vertices by reference rather than index, you should still use this list by calling the addVertex() and related methods whenever you need one, even if you build your own faces directly. Having this list provides the ability to share vertices across multiple planar faces/edges, allowing for significant optimisation of both storage and interactive edit-ability.

Type

Array.<PD.Point>

:PD.BRep.Selection Selection <static>

Stores the handler for selecting and editing BReps within the model, if enabled.

To enable the selection and editing of BReps, call the PD.BRep.enableSelection method with the selection manager you wish to use (typically PD.GlobalActions.selectionManager) or, if PD.BRep.Selection already exists, call its PD.BRep.Selection.connectTo method. This will also augment the connected selection set to allow storing of one or more BReps and the faces, edges or vertices currently selected within them.

Type

PD.BRep.Selection

Methods

addClipperPathsByAxis(paths, plane [, axis])

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

As ClipperLib creates paths based on 2D {X,Y} objects, converting back to 3D [x,y,z] coordinates requires projecting them back onto a 3D plane. This method uses the the plane equation to determine the most suitable cartesian axis to use, the axis of greatest surface exposure.

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

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 way more than acceptable. It is required when performing operations on multiple surfaces that may not be on exactly the same plane - or on polylines 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 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 so than with axis-based conversion.

Parameters:

Name	Type	Argument	Description
`paths`	Array		One or more ClipperLib paths containing {X,Y} Clipper points.
`plane`	THREE.Plane \| number		An optional plane equation to project points onto or a Z-axis height.
`axis`	number	<optional>	The axis to project in if known, otherwise computed from plane.

Returns:

Returns an array of one or more new faces.

Type: Array.<PD.BRep.Face>

addEdge(vertices)

Reuses an existing open edge.

Parameters:

Name	Type	Argument	Description
`vertices`	Array.<PD.Point>	<repeatable>	Two or more vertices to create the edge from.

Returns:

Returns the edge array just added.

Type: Array.<PD.Point>

addEdgeCircleXY(center, radius [, incr])

Adds a circular loop of reusable edges in the XY plane.

This method reuses as existing edge or creates a new entry in edgeList by incrementing an internal counter that is reset to zero when the reuseStart() method is called.

Parameters:

Name	Type	Argument	Description
`center`	THREE.Vector3		The center of the circle.
`radius`	number		The radius of the circle, in mm.
`incr`	number	<optional>	The angle increment in radians, defaults to PI/6 (15deg).

Returns:

Returns the edge array just added.

Type: Array

addEdgeLoop(vertices)

Adds a loop of reusable edges, or creates and adds new ones.

This method reuses an existing edge or creates a new entry in edgeList by incrementing an internal counter that is reset to zero when the reuseStart() method is called.

This method will add an additional edge by appending the first vertex after the last in the list.

Parameters:

Name	Type	Argument	Description
`vertices`	Array.<PD.Point>	<repeatable>	Two or more vertices to create the edge from.

Returns:

Returns the edge array just added.

Type: Array.<PD.Point>

addEmptyFace( [makeCurved])

Retrieves the next reusable face in the BRep, or creates and adds a new one.

This method fetches from or creates new faces in faceList by incrementing an internal counter that is reset to zero when the reuseStart() method is called.

In addition to fetching/creating a face, this method clears the boundary, holes and triangles lists. By default it also resets the face to planar, however you can pass true for the makeCurved argument to set it as curved.

You can then use the PD.BRep#setBoundary and PD.BRep#setHole methods to create the faces.

Parameters:

Name	Type	Argument	Description
`makeCurved`	boolean	<optional>	An optional flag to set the face as curved, defaults to false.

Returns:

Returns an existing face or a newly created one.

Type: PD.Polygon

addEmptyVertex()

Retrieves the next reusable vertex in the BRep, or creates and adds a new one.

It fetches from or creates vertices in vertexList by incrementing an internal counter. Thus, you should only make calls to this method after previously calling the reuseStart() method to reset this counter back to zero when reusing existing vertices.

Returns:

Returns an existing vertex or a newly created one.

Type: PD.Point

addExtents(bbox [, reverse] [, cap])

Adds an axis-aligned 3D bounding box.

The image below shows the order that the vertices and faces are created.

    Z (height)
    |         (max)
    | 7--------6
    |/   (0)  /|
    4--------5 |
    | : Y    | | (depth)
    | :/     | |/
    | 3------|-2
    |/  (1)  |/
    0--------1 --- X (width)
 (min)

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	Argument	Default	Description
`bbox`	THREE.Box3			The bounding box to add.
`reverse`	boolean	<optional>	false	Whether or not to reverse each polygon, defaults to false.
`cap`	PD.CAP	<optional>		Whether or not to add bottom/top faces, defaults to `PD.CAP.BOTH`.

Returns:

Returns a list of the generated faces.

Type: Array.<PD.BRep.Face>

addExtentsArray(extents [, reverse] [, cap])

Adds a vector-array-based axis-aligned 3D bounding box to this BRep.

This method differs from the PD.BRep#addExtents method in that the given extents must be an object with min and max properties that are both [x,y,z] vector arrays.

The image below shows the order that the vertices and faces are created.

    Z (height)
    |         (max)
    | 7--------6
    |/   (0)  /|
    4--------5 |
    | : Y    | | (depth)
    | :/     | |/
    | 3------|-2
    |/  (1)  |/
    0--------1 --- X (width)
 (min)

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	Argument	Default	Description
`extents`	object			An object with `min` and `max` properties that are both [x,y,z] vector arrays.
`reverse`	boolean	<optional>	false	Whether or not to reverse each face polygon, defaults to false.
`cap`	PD.CAP	<optional>		Whether or not to add bottom/top faces, defaults to `PD.CAP.BOTH`.

Returns:

Returns a list of the generated faces.

Type: Array.<PD.BRep.Face>

addExtrudedPolyline(polyline, vector, botOffset, topOffset [, reverse] [, cap])

Adds an extruded polyline to the BRep.

                 ^
             _+--|---------+
         _.-' | _| /       :\
     _.-'   __||_|/        : \
   +'        _+------------+_.+
   |'.   _.-' .     __..--''\ |
   |_.'-'   __..--''       ' \|
   +    '+''  3. . . . . . 2_.+
   .'.   |. '       __..--''. .
   .  '.'|  __..--''         ..
   4 '  '+''                _ 1
    '    .          _ . - '
      '  .  _ . - '
        '0'

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

Parameters:

Name	Type	Argument	Description
`polyline`	PD.Polyline		The polyline or element path to extrude.
`vector`	THREE.Vector3		The normalised direction to extrude the polyline in.
`botOffset`	number		The distance to the `bottom` along the extrusion vector.
`topOffset`	number		The distance to the `top` along the extrusion vector.
`reverse`	boolean	<optional>	Whether or not to reverse each polygon, defaults to false.
`cap`	PD.CAP	<optional>	Whether or not to add bottom/top facets, defaults to `PD.CAP.NONE`.

Returns:

Returns a list of the generated faces.

Type: Array.<PD.BRep.Face>

addFace(vertices [, reverse] [, color] [, normal])

Adds a polygonal face with three or more vertices to this BRep.

The vertices must be given in sequence and in the order they occur in the boundary of the polygon. Faces use the right-hand-rule to calculate their surface normals.

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

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	Argument	Description
`vertices`	Array.<PD.Point> \| Array.<Array.<PD.Point>>		An array of `PD.Point` objects defining the face boundary.
`reverse`	boolean	<optional>	Whether or not to reverse the polygon, defaults to false.
`color`	THREE.Color \| number	<optional>	An optional color value to assign the face.
`normal`	THREE.Vector3	<optional>	An optional normalised direction vector.

Returns:

Returns the reused face or a newly created one.

Type: PD.BRep.Face

addFaceAndCheckAxis(vertices, axis [, color] [, normal])

Adds a polygonal face with three or more vertices.

This method checks the orientation of the surface normal and may reverse the order of vertices to ensures that it points in the same direction as the given axis.

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

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	Argument	Description
`vertices`	Array.<PD.Point>		An array of `PD.Point` objects defining the face boundary.
`axis`	PD.AXIS		The axis of a parent plane to match with.
`color`	THREE.Color \| number	<optional>	An optional color value to assign the face.
`normal`	THREE.Vector3	<optional>	An optional normalised direction vector.

Returns:

Returns the reused face or a newly created one.

Type: PD.BRep.Face

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

Adds a face as a triangular fan radiating from the first point.

This is a shortcut method for use when you know that the vertices are already coplanar and form a polygon without significant concavity. If the vertices are not coplanar or form a polygon with notable concavity, then using this method may produce some overlapping triangles.

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

Use the PD.BRep#addFaceAsTriangleFanFromCenter method if you want to compute the geometric center of the face and radiate the triangular fan from that point instead of the first point.

Parameters:

Name	Type	Argument	Description
`vertices`	Array		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 the face just added, or null in insufficient vertices.

Type: PD.BRep.Face | null

addFaceAsTriangleFanFromCenter(vertices [, color] [, normal] [, center])

Adds a face as a triangular fan radiating from the geometric center.

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

Use the PD.BRep#addFaceAsTriangleFan method if you want to use the first point of the face to radiate the triangular fan from instead of the geometric center.

Parameters:

Name	Type	Argument	Description
`vertices`	Array		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.
`center`	THREE.Vector3	<optional>	An optional center/apex position.

Returns:

Returns the face just added, or null in insufficient vertices.

Type: Array | null

addFacetsToCapSimilarProfiles(profiles [, reverse])

Creates two faces at each end of an array of profiles.

This method is typically used with a series of profiles created when offsetting a multi-point shape from a path contour. It assumes that the starting and ending points of each profile are all co-planar, which will be true when using offset profiles.

Two faces are created, the first by joining together all the start points in each profile and the second by joining all the end points of each profile. Any null or empty profiles will be safely skipped/ignored so that only valid points are added.

          +          +              _.3---------4
         /          /             .'            |
    +   /       +  / +          2          6----5
   /   4       /  3 /            \.4---------3
  /    +      / +  /    >>     .'            |
 5    /      1 /  2          5          1----2
     /        /               \         |
    6        0                 6--------0

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	Argument	Description
`profiles`	Array		An array of profiles generated from the same path but with different offsets.
`reverse`	boolean	<optional>	Whether or not to reverse the end facets, defaults to false.

Returns:

Returns an array of two reused faces.

Type: Array

addHoleToFace(face, contour)

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

If copyPoints is set to true, then the points in the contour array will be copied into the BRep and reused as vertices within the hole. If copyPoints is false, then it is critically important that the contour 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: 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
`face`	PD.BRep.Face	The face to add the hole to.
`contour`	Array.<PD.Point>	An array of points defining the hole.

Returns:

Returns true if the hole was added.

Type: boolean

addOctahedron(coords, size [, reverse])

Adds a 3D octahedron with the given dimensions.

The prism's surfaces will be aligned with the axis of the given local coordinate system and the

           _0_
         _/  \\_
       _/     \ \_
     _/        \  \_
    1----4------2---3
     \_        /  _/
       \_     / _/
         \_  /_/
           '5'

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	Argument	Description
`coords`	PD.LocalCoordinates		The local coordinates to use.
`size`	number		The size of the diamond in each local axis.
`reverse`	boolean	<optional>	Whether or not to reverse each polygon, defaults to false.

Returns:

Returns a list of the generated faces.

Type: Array.<PD.BRep.Face>

addPolygon(poly [, reverse] [, color])

Adds a polygonal face as a copy of the given polygon.

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	Argument	Description
`poly`	PD.Polygon		The polygon to copy.
`reverse`	boolean	<optional>	Whether or not to reverse the polygon, defaults to false.
`color`	THREE.Color \| number	<optional>	An optional color value to assign the face.

Returns:

Returns the reused face if polygon is valid, or null.

Type: PD.BRep.Face | null

addPrism(coords, width, depth, height [, reverse] [, cap])

Adds a 3D box with the given dimensions to this BRep.

The prism's surfaces will be aligned with the axis of the given local coordinate system.

  Z (height)
  |
  | 7--------6
  |/   (0)  /|
  4--------5 |
  | : Y    | | (depth)
  | :/     | |/
  | 3------|-2
  |/  (1)  |/
  0--------1 --- X (width)

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	Argument	Default	Description
`coords`	PD.LocalCoordinates			The local coordinates to use.
`width`	number			The width of the prism in the local X-axis.
`depth`	number			The depth of the prism in the local Y-axis.
`height`	number			The height of the prism in the local Z-axis.
`reverse`	boolean	<optional>	false	Whether or not to reverse each polygon, defaults to false.
`cap`	PD.CAP	<optional>		Whether or not to add bottom/top faces, defaults to `PD.CAP.BOTH`.

Returns:

Returns a list of the generated faces.

Type: Array.<PD.BRep.Face>

addQuad(vtx1, vtx2, vtx3, vtx4 [, reverse] [, color] [, normal])

Adds a single four-sided polygonal face to this BRep.

The four given vertices must be given in sequence and in the order they occur in the boundary of the polygon. Faces use the right-hand-rule to calculate their surface normals.

           |
       3---|-------2        1-----------2
      /   _| /    /        /      /    /
     / __|_|/    /        / _ _ _/    /
    /           /        /    |_|    /
   0-----------1        0-------|---3
                                |

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	Argument	Description
`vtx1`	PD.Point		The first vertex.
`vtx2`	PD.Point		The second vertex.
`vtx3`	PD.Point		The third vertex.
`vtx4`	PD.Point		The fourth vertex.
`reverse`	boolean	<optional>	Whether or not to reverse the face, defaults to false.
`color`	THREE.Color \| number	<optional>	An optional color value to assign the face.
`normal`	THREE.Vector3	<optional>	An optional normalised direction vector.

Returns:

Returns the reused face or a newly created one.

Type: PD.BRep.Face

addQuadOrTriangles(vtx1, vtx2, vtx3, vtx4 [, reverse] [, color])

Checks coplanarity and adds a either one four-sided face or two triangular faces.

The four given vertices must be given in sequence and in the order they occur in the boundary of the polygon. Faces use the right-hand-rule to calculate their surface normals.

           |
       3---|-------2        1-----------2
      /   _| /    /        /      /    /
     / __|_|/    /        / _ _ _/    /
    /           /        /    |_|    /
   0-----------1        0-------|---3
                                |

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	Argument	Description
`vtx1`	PD.Point		The first vertex.
`vtx2`	PD.Point		The second vertex.
`vtx3`	PD.Point		The third vertex.
`vtx4`	PD.Point		The fourth vertex.
`reverse`	boolean	<optional>	Whether or not to reverse the face, defaults to false.
`color`	THREE.Color \| number	<optional>	An optional color value to assign the face.

Returns:

Returns an array of 1 (quad) or 2 (triangles) reused faces.

Type: Array.<PD.BRep.Face>

addQuadsBetweenSimilarProfiles(profile1, profile2 [, reverse] [, closed])

Creates a series of quadrilateral faces that join two profiles.

This method assumes that both profiles travel in the same direction along their path, have the same number of vertices, are offset from each other by some reasonable distance and that each pairing forms a planar quadrilateral face.

             contour2
             4------------3                    9------------7
                           \                   |            |\
             contour1       \                  |            | \
  0          4------------3_.2  >>  3          8------------6_.5
   '.              __..--''\        |'.              __..--''\ |
     '.    __..--''         \       |  '.    __..--''         \|
  0    '1''                _.2      0    '2''                _.4
   '.              __..--''          '.   |          __..--''
     '.    __..--''                    '. |  __..--''
       '1''                              '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	Argument	Description
`profile1`	Array.<PD.Point>		The lower profile.
`profile2`	Array.<PD.Point>		The upper profile.
`reverse`	boolean	<optional>	Whether or not to reverse the polygon, defaults to false.
`closed`	boolean	<optional>	Whether or not to close the loop, defaults to false.

Returns:

Returns an array of quadrilateral faces.

Type: Array.<PD.BRep.Face>

addSweptProfileByPath(profile, path, index [, offsetPath] [, reverse] [, closed])

Adds a profile of connected 2D points that is swept along a contour of a 3D path.

This method transforms the profile along each vertex of the path contour, creating planar quadrilateral faces between each pair of transformed profile points. The profile's origin (0,0) is always located on the given path, or offset by the given offsetPath value.

        +----------+
        |\          \
        | \   shape  \
        |  4----------3
 X      |  |       _/  \
  .     +--|-----+'     \
   .     \ |      \     _2
    +  Z  \|       \  _/
     \ :   0--------1'
      \:
       + - - > Y
      path

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

Parameters:

Name	Type	Argument	Default	Description
`profile`	Array.<THREE.Vector2>			An array of connected points to be swept along the path.
`path`	PD.Path			The polyline or element path to sweep the points along.
`index`	number			The index of the path contour to sweep along.
`offsetPath`	number	<optional>		A distance to offset the sweep path from the given path, defaults to 0.
`reverse`	boolean	<optional>	false	Whether or not to reverse the orientation of each polygon, defaults to false.
`closed`	boolean	<optional>	false	Whether or not the profile is closed, defaults to false.

Returns:

Returns a list of the generated faces.

Type: Array.<PD.Brep.Face>

addSweptShapeByPath(shape, path, index [, offsetPath] [, reverse] [, curveSegments])

Adds a 2D shape that is swept along a contour of a 3D path.

This method transforms the shape along to each vertex of the path contour, creating planar quadrilateral faces between each pair of transformed shape points. The shape's origin (0,0) is always located on the given path, or offset by the given offsetPath value.

        +----------+
        |\          \
        | \   shape  \
        |  4----------3
 X      |  |       _/  \
  .     +--|-----+'     \
   .     \ |      \     _2
    +  Z  \|       \  _/
     \ :   0--------1'
      \:
       + - - > Y
      path

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

Parameters:

Name	Type	Argument	Description
`shape`	THREE.Shape		The 2D shape to sweep along the path.
`path`	PD.Path		The polyline or element path to extrude.
`index`	number		The index of the contour to sweep along.
`offsetPath`	number	<optional>	A distance to offset the sweep path from the given path, defaults to 0.
`reverse`	boolean	<optional>	Whether or not to reverse the orientation of each polygon, defaults to false.
`curveSegments`	number	<optional>	The number of segments to sample curves in (2 to 360), defaults to 12.

Returns:

Returns a list of the generated faces.

Type: Array.<PD.Brep.Face>

addTetrahedron(coords, size [, reverse])

Adds a 3D tetrahedron with the given dimensions.

The prism's surfaces will be aligned with the axis of the given local coordinate system and the

           _0_
         _/  \\_
       _/     \ \_
     _/        \  \_
    1----4------2---3

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	Argument	Description
`coords`	PD.LocalCoordinates		The local coordinates to use.
`size`	number		The size of the tetrahedron in each local axis.
`reverse`	boolean	<optional>	Whether or not to reverse each polygon, defaults to false.

Returns:

Returns a list of the generated faces.

Type: Array.<PD.BRep.Face>

addTriangle(vtx1, vtx2, vtx3 [, reverse] [, color] [, normal])

Adds a single three-sided triangular face to this BRep.

The three given vertices must be given in sequence and in the order they occur in the boundary of the polygon. Faces use the right-hand-rule to calculate their surface normals.

           |
        2--|-------1        1----------2
       /  _| /             /    /
      /__|_|/             /____/
     /                   /  |_|
    /                   /     |
   0                   0      |
                              |

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	Argument	Description
`vtx1`	PD.Point		The first vertex.
`vtx2`	PD.Point		The second vertex.
`vtx3`	PD.Point		The third vertex.
`reverse`	boolean	<optional>	Whether or not to reverse the face, defaults to false.
`color`	THREE.Color \| number	<optional>	An optional color value to assign the face.
`normal`	THREE.Vector3	<optional>	An optional normalised direction vector.

Returns:

Returns the reused face or a newly created one.

Type: PD.BRep.Face

addTruncatedCube(coords, size [, reverse])

Adds a cube to this BRep, but with corners truncated equally along each edge.

The truncated cube's surfaces will be aligned with the axis of the given local coordinate system.

     +--------+
   +            +
   |            |
   |            |
   +            +
     +--------+

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	Argument	Description
`coords`	PD.LocalCoordinates		The local coordinates to use.
`size`	number		The size of the cube in each local axis.
`reverse`	boolean	<optional>	Whether or not to reverse each polygon, defaults to false.

Returns:

Returns a list of the generated faces.

Type: Array.<PD.BRep.Face>

addTube(path, index, radius [, facets] [, offsetPath] [, reverse] [, color])

Generates a tubular shape by sweeping a circular profile along the given path contour.

Parameters:

Name	Type	Argument	Description
`path`	PD.Path		The polyline or element path to sweep the points along.
`index`	number		The index of the path contour to sweep along.
`radius`	number		The radius of the tube to sweep along the path, must be greater than zero.
`facets`	number	<optional>	The number of facets around the perimeter of the tube, defaults to 12.
`offsetPath`	number	<optional>	A distance to offset the sweep path from the given path, defaults to 0.
`reverse`	boolean	<optional>	Whether or not to reverse the orientation of each polygon, defaults to false.
`color`	THREE.Color \| number	<optional>	An optional color value to assign to faces, defaults to `undefined`.

Returns:

Returns a list of the generated faces.

Type: Array.<PD.Brep.Face>

addVertex( [vertex])

Sets the next reusable vertex in the BRep using either a {x,y,z} vector object or [x,y,z] vector array.

The argument to this method may be either a simple [x,y,z] vector array or an {x,y,z} object - such as a THREE.Vector3, PD.Point or similar vector object class. Internally, it uses the PD.Utils.copyVector3 utility method to determine the type of argument and copy its content.

Copying rather than using the given vertex is useful as you can use a single source vertex in multiple calls to this method, adjusting its position slightly prior to each call, to build your polygons.

Parameters:

Name	Type	Argument	Description
`vertex`	THREE.Vector3 \| Array.<number>	<optional>	An optional vertex to copy the content of.

Returns:

Returns an existing BRep vertex or a newly created one.

Type: PD.Point

addVertexFromArray(array)

Sets the next reusable vertex in the BRep using a vector array.

Use this method only with simple [x,y,z] vector arrays. It does not have the same checks as the addVertex() method and simply copies the first three array entries as X, Y and Z values.

Parameters:

Name	Type	Description
`array`	Array.<number>	An [x,y,z] coordinate array to copy the content of.

Returns:

Returns an existing BRep vertex or a newly created one.

Type: PD.Point

addVertexFromArrayWithAttribs(pos, normal [, uv] [, color])

Retrieves the next reusable vertex and sets additional vertex attributes.

Use this method to add vertices that have position as well as additional normal direction, UV texture coordinate and potentially color attributes. In this case, the size of each vector array is increased such that the first three entries store the x,y,z vertex position, the next three store the nx,ny,nz normal direction, the next two store the u,v texture coordinates and the last three store r,g,b colour information. Thus, each vector array can have up to 11 entries.

NOTE: Whilst you can leave arguments off at the end, you can't miss out intervening arguments when calling this method. For example, you can pass only the pos and normal arrays, which will create a vector array with 6 entries, but you can't just pass pos and color and leave out normal and uv, or set them to null. This will leave undefined entries in the vector array. If you don't want to have vertex-specific normals, texture coordinates or color, simply create a shared array with the common values and pass in each call.

Parameters:

Name	Type	Argument	Description
`pos`	Array.<number>		The [x,y,z] coordinate array.
`normal`	Array.<number>		The [nx,ny,nz] normalised direction vector array.
`uv`	Array.<number>	<optional>	An optional The [u,v] texture coordinate array.
`color`	Array.<number>	<optional>	An optional [r,g,b] color array.

Returns:

Returns an existing vertex or a newly created one.

Type: PD.Point

addVertexFromComponents(x, y, z)

Sets the next reusable vertex in the BRep using separate X, Y and Z cartesian coordinates.

Use this method when you have the individual axial coordinate values of the new vertex.

Parameters:

Name	Type	Description
`x`	number	The X coordinate to of the new vertex.
`y`	number	The Y coordinate to of the new vertex.
`z`	number	The Z coordinate to of the new vertex.

Returns:

Returns an existing BRep vertex or a newly created one with the given coordinates.

Type: PD.Point

addVertexFromVector(vector)

Sets the next reusable vertex in the BRep using a vector object.

Use this method only with known THREE.Vector3, PD.Point or similar {x,y,z} objects as it does not have the same checks as the addVertex() method, simply copying the 'x', 'y' and 'z' property values.

Parameters:

Name	Type	Description
`vector`	THREE.Vector3	The vector object to copy the content of.

Returns:

Returns an existing BRep vertex or a newly created one.

Type: PD.Point

clear()

Removes all vertices, faces and edges from the BRep.

NOTE: Calling this method releases all cached vertices and faces as well, completely freeing up all memory associated with this BRep. If the BRep is subsequently reused, everything will need to be recreated and reallocated.

Returns:

Returns this BRep to support method chaining.

Type: PD.BRep

clearSelection()

Deselects all faces in the BRep and all its vertices.

Returns:

Returns this BRep to support method chaining.

Type: PD.BRep

clipToClipperPath(boundary, shape [, axis] [, diff] [, callback])

Clips the BRep faces to the given ClipperLib Path in the given axis.

If given, the callback argument must be a function that takes the newly added vertex its single argument. This provides the caller with an opportunity to modify each vertex as they are added.

Parameters:

Name	Type	Argument	Description
`boundary`	Array.<{X, Y}>		A `ClipperLib.Path` defining the clip boundary.
`shape`	PD.BRep \| Array.<PD.BRep.Face>		The BRep to clip, or an array of BRep faces.
`axis`	PD.AXIS	<optional>	The axis to use when converting, defaults to the +Z axis.
`diff`	boolean	<optional>	When true, a difference operation is used rather than intersection.
`callback`	function	<optional>	A callback function to process each vertex in the BRep.

Returns:

Returns true if faces were added to the BRep.

Type: boolean

clipToHeight(height [, keepRidgeLines])

Clips a BRep shape to a maximum height in the Z-axis.

Parameters:

Name	Type	Argument	Default	Description
`height`	number			The Z-axis value to clip to, defaults to 2000mm or 6'.
`keepRidgeLines`	boolean	<optional>	false	Whether or not to just flatten trimmed faces rather than union them, defaults to false.

clipToPolygon(poly, brep [, axis])

Clips the BRep faces to the given path in the XY plane.

Parameters:

Name	Type	Argument	Description
`poly`	PD.Polygon		A `ClipperLib.Path` defining the clip boundary.
`brep`	PD.BRep		The BRep to clip.
`axis`	PD.AXIS	<optional>	The axis to use when converting, defaults to the +Z axis.

Returns:

Returns true if faces were added to the BRep.

Type: boolean

computePlaneIntersectionPoints(plane [, results])

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

This method cycles through all the boundary and hole lines within each face, computing the intersection points with the given plane and storing them in the results array. If no results array is provided, it will return a new array.

Parameters:

Name	Type	Argument	Description
`plane`	THREE.Plane		The plane to intersection all faces with.
`results`	Array.<THREE.Vector3>	<optional>	An optional array to the resulting intersection points to.

Returns:

Returns the results array, or a new array, with intersection points.

Type: Array.<THREE.Vector3>

computeSmoothNormals(smooth [, keepPlanar])

Computes the averaged surface normal of all triangulated vertices across all faces, or clears them if argument is false.

If the BRep has a combination of planar and curved faces, and you want the planar faces to remain flat, then you set the keepPlanar argument to true. This will ensure that the normals of planar faces are not averaged with the normals of curved faces. This will affect any curved faces that share edge vertices with planar faces, making the edge appear to curve smoothly into the flat face.

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

Parameters:

Name	Type	Argument	Default	Description
`smooth`	boolean			Whether or not to compute smooth vertex normals.
`keepPlanar`	boolean	<optional>	false	Whether or not to keep planar faces flat.

Returns:

Returns this BRep to support method chaining.

Type: PD.BRep

convertVectorArraysToPoints(contour)

Converts an array of [x,y,z] vector arrays to an array of {x,y,z} point objects using cached vertices.

As this method uses cached vertices, it should only be invoked between calls to the reuseStart() and reuseEnd() methods when you are rebuilding a BRep.

Parameters:

Name	Type	Description
`contour`	Array.<Array.<number>>	An array of sequential vector arrays to convert to vertices.

Returns:

Returns an array of point objects suitable for uses as face boundaries or holes contours.

Type: Array.<PD.Point>

copyDashedOutlineToPolyMesh(mesh, size)

Adds the face outlines to the given dynamic mesh.

Parameters:

Name	Type	Description
`mesh`	PD.PolyMesh	The dynamic mesh to add the polygon to.
`size`	number	The size of the dash in each line.

Returns:

Returns true if geometry was added to the mesh.

Type: boolean

copyFace(face [, reverse] [, color])

Adds a new face as a copy of the given face.

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	Argument	Description
`face`	PD.BRep.Face		The face to copy.
`reverse`	boolean	<optional>	Whether or not to reverse the polygon, defaults to false.
`color`	THREE.Color \| number	<optional>	An optional color value to assign the face.

Returns:

Returns the reused face if successfully copied, or null.

Type: PD.BRep.Face | null

copyOutlineToPolyMesh(mesh)

Adds the face outlines to the given dynamic mesh.

Parameters:

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

Returns:

Returns true if geometry was added to the mesh.

Type: boolean

copyPlanViewDashedOutlineToPolyMesh(mesh, size [, threshold])

Adds the outlines of only upward-facing faces in the BRep to the given dynamic mesh.

Parameters:

Name	Type	Argument	Description
`mesh`	PD.PolyMesh		The dynamic mesh to add the outlines to.
`size`	number		The size of the dash in each line.
`threshold`	number	<optional>	The minimum Z axis component value, defaults to 0.01.

Returns:

Returns true if geometry was added to the mesh.

Type: boolean

copyPlanViewOutlineToPolyMesh(mesh [, threshold])

Adds the outlines of only upward-facing faces in the BRep to the given dynamic mesh.

Parameters:

Name	Type	Argument	Description
`mesh`	PD.PolyMesh		The dynamic mesh to add the outlines to.
`threshold`	number	<optional>	The minimum Z axis component value, defaults to 0.01.

Returns:

Returns true if geometry was added to the mesh.

Type: boolean

copyPlanViewToPolyMesh(mesh [, threshold] [, noOutline] [, noColor])

Adds only upward-facing faces in the BRep to the given dynamic mesh.

Parameters:

Name	Type	Argument	Description
`mesh`	PD.PolyMesh		The dynamic mesh to add the polygon to.
`threshold`	number	<optional>	The minimum Z axis component value, defaults to 0.01.
`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

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

Adds shape faces to the given dynamic mesh.

The method adds both outlines and surfaces to the mesh.

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, surface colors are not set, defaults to false.

Returns:

Returns true if geometry was added to the mesh.

Type: boolean

extrudeContourToPlane(contour, plane, vector [, front] [, flip] [, closed])

Extrude a contour line by the given vector direction onto the given plane.

The method generates facets for each segment of the given contour where at least one of the points matches the side of the plane given by front. It uses the PD.Utils#isPointInFrontOfPlane method to make that determination.

If both of the segment points are on the same side, a quadrilateral facet is added. If only one segment point is on the same side, a triangular facet is added. If neither point matches front, then no facet is added.

Parameters:

Name	Type	Argument	Default	Description
`contour`	Array.<PD.Point>			The list of points to extrude.
`plane`	THREE.Plane			The plane to extrude facets towards.
`vector`	THREE.Vector3			The extrusion direction vector.
`front`	boolean	<optional>	true	Whether to extrude in front of the plane, defaults to true.
`flip`	boolean	<optional>	false	Whether to reverse the surface orientation, defaults to false.
`closed`	boolean	<optional>	false	Whether or not the contour is closed, defaults to false.

Returns:

Returns an array of faces.

Type: Array.<PD.BRep.Face>

extrudePolylineToPlane(polyline, plane [, vector] [, front] [, flip])

Extrude a polyline by its normal to the given plane.

Parameters:

Name	Type	Argument	Default	Description
`polyline`	PD.Polyline			The polyline to extrude.
`plane`	THREE.Plane			The plane to extrude towards.
`vector`	THREE.Vector3	<optional>		The extrusion direction vector, defaults to polyline normal.
`front`	boolean	<optional>	true	Whether to extrude in front or of behind plane, defaults to true.
`flip`	boolean	<optional>	false	Whether to reverse the surface orientation, defaults to false.

Returns:

Returns an array of facets.

Type: Array.<PD.Polygon>

findByRay(selection [, testOnly])

Checks if the given ray intersects any of the faces in the BRep.

This method takes an additional optional argument that allows it to be used by elements for hit-testing of the BRep to see if they were selected. By setting the testOnly argument to false, the method will return true on the first verified edge or triangle intersection without updating the selection.

Parameters:

Name	Type	Argument	Default	Description
`selection`	PD.Selection			The interactive selection accumulator.
`testOnly`	boolean	<optional>	false	Whether to just test for the first hit rather than actually select the closest edges/faces, defaults to false.

Returns:

Returns true if a face in the BRep was selected and the selection updated or, if testOnly is true, that the BRep was hit by the ray, otherwise false.

Type: boolean

findEdgesByFrustum(selection)

Searches for all edges inside frustum.

Parameters:

Name	Type	Description
`selection`	PD.Selection	The interactive selection accumulator.

Returns:

Returns an array of zero or more found edges.

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

findEdgesByRay(selection [, all])

Retrieves a list of edges intersected by the given ray.

Parameters:

Name	Type	Argument	Default	Description
`selection`	PD.Selection			The interactive selection accumulator.
`all`	boolean	<optional>	true	Whether to include all edges or just the first one found, defaults to true.

Returns:

Returns an array of intersected edges, or null if the ray does not hit the bounding box.

Type: Array.<PD.BRep.Face> | null

findFacesByFrustum(selection)

Searches for all faces inside or intersected by frustum.

Parameters:

Name	Type	Description
`selection`	PD.Selection	The interactive selection accumulator.

Returns:

Returns an array of zero or more found faces.

Type: Array.<PD.BRep.Face>

findFacesByRay(selection [, all])

Retrieves a list of faces intersected by the given ray.

Parameters:

Name	Type	Argument	Default	Description
`selection`	PD.Selection			The interactive selection accumulator.
`all`	boolean	<optional>	true	Whether to include all faces or just the first one found, defaults to true.

Returns:

Returns an array of intersected faces, or null if the ray does not hit the bounding box.

Type: Array.<PD.BRep.Face> | null

findFacesOfType(type)

Searches for faces of the given type in the face list.

Parameters:

Name	Type	Description
`type`	PD.FACET	The type of face to find.

Returns:

Returns an array of faces of the given type.

Type: Array

findVerticesByFrustum(selection)

Searches for vertices inside frustum and, if found, adds them to the selection.

Parameters:

Name	Type	Description
`selection`	PD.Selection	The interactive selection accumulator.

Returns:

Returns an array of zero or more found vertices.

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

findVerticesByRay(selection [, all])

Retrieves the closest intersected vertex or a list of distance-sorted vertices intersected by the given ray.

Parameters:

Name	Type	Argument	Default	Description
`selection`	PD.Selection			The interactive selection accumulator.
`all`	boolean	<optional>	true	Whether to include all vertices or just the closest one, defaults to true.

Returns:

Returns an array of intersected edges, or null if the ray does not hit the bounding box.

Type: Array.<PD.BRep.Face> | null

fitExtents(pt)

Extends the extents to fit the given pt.

Parameters:

Name	Type	Description
`pt`	THREE.Vector3	The coordinate to extend bounds to include.

Returns:

Returns this BRep to support method chaining.

Type: PD.BRep

fitExtentsToPoints(points)

Extends the extents to fit the given list of points.

Parameters:

Name	Type	Description
`points`	Array	The list of coordinate points to extend bounds to.

Returns:

Returns this BRep to support method chaining.

Type: PD.BRep

fromJSON(data)

Safely copy properties from a source object.

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

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.

Returns:

Returns this BRep to support method chaining.

Type: PD.BRep

Example

// Overriding this method.

class MyBRep extends PD.BRep {
     /// ...
     fromJSON(data) {

         super.fromJSON(data);

         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;

     };
     /// ...
 };

generateSurfaceEdgeFaces(baseLevel, flip)

Adds edge faces to a roughly horizontal faceted surface.

This method assumes that the current faces in the BRep form a roughly horizontal surface with shared vertices and edges. It searches for any exposed edges in the surface and generates vertical edge faces that extent up or down to the given base level in the Z-axis.

Parameters:

Name	Type	Description
`baseLevel`	number	The Z-axis level to extend vertical edges up/down to.
`flip`	boolean	Whether or not to reverse surface normals.

generateUniqueEdges(creaseAngle [, decimals])

Iterates the boundaries and holes in all planar faces and creates edges between adjacent faces whose surface normals vary by more than the given crease angle.

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

This method will also weld together coincident vertices to ensure that there are no duplicate vertices with the same 3D position in the BRep. If you know that this has already been done, you can pass a value of -1 for the decimals argument to skip this step. Otherwise the decimals argument determines the number of decimal places for testing vertices for coincidence, and should be a number between 0 and 6. If not given, this value will default to 1, which is 0.1mm precision.

Parameters:

Name	Type	Argument	Default	Description
`creaseAngle`	number			The angle between face normals above which edges are added, in decimal radians.
`decimals`	number	<optional>	3	The number of decimal places to use when comparing coordinates (0 or more), defaults to 1.

Returns:

Returns this BRep to support method chaining.

Type: PD.BRep

getApproxSizeOfJSON()

Retrieves a string describing the approximate size and content of this BRep when stored as a JSON string.

Returns:

Returns a succinct string detailing approximate size.

Type: string

getNextEdgeIndex()

Retrieves the ordinal index of the next reusable edge in the BRep.

Returns:

Returns an ordinal index in the edgeList property.

Type: number

getNextFaceIndex()

Retrieves the ordinal index of the next reusable face in the list.

Returns:

Returns an ordinal index in the faceList property.

Type: number

getNextVertexIndex()

Retrieves the ordinal index of the next reusable vertex in the BRep.

Returns:

Returns an ordinal index in the vertexList property.

Type: number

hasContent()

Determines whether or not the BRep has valid content.

This method checks for the presence of at least one edge or face with a valid boundary contour.

Returns:

Returns true if BRep has one or more valid edge/face.

Type: boolean

intersectRay(ray, target)

Determines the intersection point between a ray and this BRep.

Parameters:

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

Returns:

Return target if the BRep were intersected, or null if not.

Type: PD.BRep.Face | null

isBeingReused()

Checks if the BRep is in the process of being reused.

This method returns true if a call to reuseStart() has been made but not yet followed by a call to reuseEnd(), indicating that the BRep is still in reuse mode.

Returns:

Returns true if the BRep is in reuse mode and has not yet reused all its vertices, faces or edges.

Type: boolean

isInsideFrustum(frustum, intersect)

Checks if all faces of the BRep are within the selection frustum or, when intersection is set, if any are intersected.

Parameters:

Name	Type	Description
`frustum`	THREE.Frustum	The frustum to test against.
`intersect`	boolean	Whether to check for intersections.

Returns:

Returns true if all faces are inside.

Type: boolean

isPointInside(point)

Determines whether or not the given point is within any of the faces.

As triangles in a planar polygon are assumed to all share the same surface normal, this calculation can be much faster. This method also excludes points that are inside internal holes/contours if the polygon has been triangulated already.

Parameters:

Name	Type	Description
`point`	THREE.Vector3	The point to to check if inside.

Returns:

Returns true if inside, otherwise false.

Type: boolean

mergeAdjacentCoplanarFaces()

Attempts to union together adjacent coplanar faces.

Returns:

Returns the BRep to support method chaining.

Type: PD.BRep

moveBy(vector)

Moves the entire BRep by the given vector.

This method calls the PD.BRep#storeReferencePositions method first to store the reference positions of each vertex, and then calls the PD.BRep#transformFromReferencePositions method.

Parameters:

Name	Type	Description
`vector`	THREE.Vector3	The relative movement vector.

Returns:

Returns this BRep to support method chaining.

Type: PD.BRep

moveFromReferencePositions(vector)

Moves the BRep relative to its vertex reference positions.

For this method to work correctly, you must have previously called the PD.BRep#storeReferencePositions method to store the reference position of each vertex.

Parameters:

Name	Type	Description
`vector`	THREE.Vector3	The relative movement vector.

Returns:

Returns this BRep to support method chaining.

Type: PD.BRep

nextEdge( [currentEdge])

Retrieves the next ordinal edge in the faceList.

This method is used to cycle through existing edges in the BRep. If a reference edge is not given. or is not found within this BRep, the first edge in the list is returned. If there are no edges in the BRep, the method will return null.

Parameters:

Name	Type	Argument	Description
`currentEdge`	Array.<PD.Point>	<optional>	The current primary edge, which may not belong to the BRep.

Returns:

Returns the next edge in the list, or null if the list is empty.

Type: Array.<PD.Point> | null

nextFace( [currentFace])

Retrieves the next face in the faceList.

This method is used to cycle through existing faces in the BRep. If a reference face is not given. or is not found within this BRep, the first face in the list is returned. If there are no faces in the BRep, the method will return null.

Parameters:

Name	Type	Argument	Description
`currentFace`	PD.BRep.Face	<optional>	The current primary face, which may not belong to the BRep.

Returns:

Returns the next face in the list, or null if the list is empty.

Type: PD.BRep.Face | null

nextVertex( [currentVertex])

Retrieves the next ordinal vertex in the vertexList.

This method is used to cycle through existing vertices in the BRep. If a reference vertex is not given, or is not found within this BRep, the first vertex in the list is returned. If there are no vertices in the BRep, the method will return null.

Parameters:

Name	Type	Argument	Description
`currentVertex`	PD.Point	<optional>	The current primary vertex, which may not belong to the BRep.

Returns:

Returns the next vertex in the list, or null if the list is empty.

Type: PD.Point | null

prevEdge( [currentEdge])

Retrieves the previous ordinal edge in the edgeList.

This method is used to cycle through existing edges in the BRep. If a reference edge is not given. or is not found within this BRep, the last edge in the list is returned. If there are no edge in the BRep, the method will return null.

Parameters:

Name	Type	Argument	Description
`currentEdge`	Array.<PD.Point>	<optional>	The current primary edge, which may not belong to the BRep.

Returns:

Returns the previous edge in the list, or null if the list is empty.

Type: Array.<PD.Point> | null

prevFace( [currentFace])

Retrieves the previous face in the faceList.

This method is used to cycle through existing faces in the BRep. If a reference face is not given. or is not found within this BRep, the last face in the list is returned. If there are no faces in the BRep, the method will return null.

Parameters:

Name	Type	Argument	Description
`currentFace`	PD.BRep.Face	<optional>	The current primary face, which may not belong to the BRep.

Returns:

Returns the previous face in the list, or null if the list is empty.

Type: PD.BRep.Face | null

prevVertex( [currentVertex])

Retrieves the previous ordinal vertex in the vertexList.

This method is used to cycle through existing vertices in the BRep. If a reference vertex is not given. or is not found within this BRep, the last vertex in the list is returned. If there are no vertices in the BRep, the method will return null.

Parameters:

Name	Type	Argument	Description
`currentVertex`	PD.Point	<optional>	The current primary vertex, which may not belong to the BRep.

Returns:

Returns the previous vertex in the list, or null if the list is empty.

Type: PD.Point | null

reuseEnd()

Trims the face list to the recently reused geometry.

This method must be called after you have first called the PD.BRep.reuseStart method to reset the reusable indexes. Its role is to trim any extra vertices, faces or edges that have not been reused and are leftover from a previous geometry.

Returns:

Returns this BRep to support method chaining.

Type: PD.BRep

reuseStart()

Resets the face counters to begin reusing for new geometry.

Returns:

Returns this BRep to support method chaining.

Type: PD.BRep

reverse()

Reverses the order of vertices and normal orientations in every face.

Returns:

Returns this BRep to support method chaining.

Type: PD.BRep

scaleBy(scale)

Applies a scale factor to the BRep relative to its vertex reference positions.

For this method to work correctly, you must have previously called the PD.BRep#storeReferencePositions method to store the reference position of each vertex.

Parameters:

Name	Type	Description
`scale`	number	The scale factor to apply.

Returns:

Returns this BRep to support method chaining.

Type: PD.BRep

setBoundary(face, vertices)

Reuses the boundary of the face with the given vertices.

As this method allows individual vertices to be either {x,y,z} point-like objects or [x,y,z] vector arrays, you should use the PD.BRep#setBoundaryFromContour method instead if you wish to pass vertices as an array.

Parameters:

Name	Type	Argument	Description
`face`	PD.BRep.Face		The face to reuse the boundary from.
`vertices`	PD.Point	<repeatable>	One or more vertices to set the boundary contour to.

Returns:

Returns the boundary of the face.

Type: Array.<PD.Point>

setBoundaryFromContour(face, contour)

Reuses the boundary of the face with the given vertex array.

To send vertices as multiple separate arguments, use the PD.BRep#setBoundary method instead.

Parameters:

Name	Type	Description
`face`	PD.BRep.Face	The face to reuse the boundary from.
`contour`	Array.<PD.Point>	An array of sequential vertices to set the boundary contour to.

Returns:

Returns the boundary of the face.

Type: Array.<PD.Point>

setColor(color [, applyToFaces])

Sets the default color of the BRep and, optionally all faces in the face list.

Parameters:

Name	Type	Argument	Default	Description
`color`	THREE.Color \| Array.<number> \| number \| null			The color to set for each face.
`applyToFaces`	boolean	<optional>	false	Also set the color value of all faces the BRep, defaults to false.

Returns:

Returns this BRep to support method chaining.

Type: PD.BRep

setHole(face, index, vertices)

Reuses an existing hole from the face, or creates a new one.

NOTE: If an existing hole is not found at the given index, this method will create a new one and add it to the face at that index. It is therefore absolutely critical to call this method with sequential index values that start at zero to ensure that there are no missing entries in the face hole list.

To automatically fill the hole contour with vertices, simply include each vertex as an additional argument when calling this method. As this method allows individual vertices to be either {x,y,z} point-like objects or [x,y,z] vector arrays, you should use the PD.BRep#setHoleFromContour method instead if you wish to pass vertices as an array.

Parameters:

Name	Type	Argument	Description
`face`	PD.BRep.Face		The face to reuse the hole from.
`index`	number		The ordinal index of the hole to add/reuse.
`vertices`	PD.Point	<repeatable>	One or more vertices to set the hole contour to.

Returns:

Returns the existing contour or a newly created one.

Type: Array.<PD.Point>

setHoleFromContour(face, index [, contour])

Reuses an existing hole from the face, or creates a new one.

To automatically fill the hole contour with vertices, simply include them as an array arguments or as an array when calling this method.

To automatically fill the hole contour with vertices, simply include the array of vertices as the contour argument when calling this method. To send vertices as multiple separate arguments, use the PD.BRep#setHole method instead.

Parameters:

Name	Type	Argument	Description
`face`	PD.BRep.Face		The face to reuse the hole from.
`index`	number		The ordinal index of the hole to add/reuse.
`contour`	Array.<PD.Point>	<optional>	An array of sequential vertices to set the hole contour to.

Returns:

Returns the existing contour or a newly created one.

Type: Array.<PD.Point>

storeReferencePositions()

Stores the position of all vertices for later reference.

Returns:

Returns this BRep to support method chaining.

Type: PD.BRep

toBufferGeometry()

Converts surface geometry as best it can to a new THREE.BufferGeometry object.

This method copies only the surface triangles of the BRep to the new geometry.

Returns:

Returns a new THREE.BufferGeometry object.

Type: THREE.BufferGeometry

toJSON( [data])

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

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

This implementation is slightly different from other similar methods in that it does not maintain the exact same property names or data structure. Rather, it stores the BRep as an indexed face set as this is a more common geometry format that is easily transferable to other uses.

An indexed face set has a single vertices array that stores all the vertex positions in the mesh and a faces array that stores either the boundary contours of each face or the triangles that make up its surface. It may also optionally have an edges array that stores the unique edge lines.

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 MyBRep extends PD.BRep {

     /// ...

     toJSON(data) {

         data = super.toJSON(data);

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

     };

     /// ...

};

toOBJ( [scale] [, name] [, vertexOffset] [, normalOffset])

Produces a simple OBJ file for import into 3D apps.

Parameters:

Name	Type	Argument	Default	Description
`scale`	number	<optional>		A scale factor to use when exporting the BRep data, defaults to 0.001 (mm to m).
`name`	string	<optional>	BRep	The name of the object this BRep represents, defaults to 'BRep'.
`vertexOffset`	number	<optional>		The number of previous vertices in the file, defaults to zero.
`normalOffset`	number	<optional>		The number of previous normals in the file, defaults to zero.

Returns:

Returns the contents of an OBJ file representing this BRep.

Type: string

toPLY( [scale])

Generates the polyhedron in Polygon File Format.

Parameters:

Name	Type	Argument	Description
`scale`	number	<optional>	A scale factor to use when exporting the BRep data, defaults to 0.001 (mm to m).

Returns:

Returns the contents of a PLY files representing the polyhedra.

Type: string

toSTL( [scale] [, name])

Produces an STL file for 3D printing.

Parameters:

Name	Type	Argument	Default	Description
`scale`	number	<optional>		A scale factor to use when exporting the BRep data, defaults to 0.001 (mm to m).
`name`	string	<optional>	BRep	The name of the object this BRep represents, defaults to 'BRep'.

Returns:

Returns the contents of an STL files representing this BRep.

Type: string

toShape( [name])

Converts its geometry as best it can to a new PD.Shape object.

Parameters:

Name	Type	Argument	Description
`name`	string	<optional>	An optional name of the shape, defaults to 'PD.BRep'.

Returns:

Returns a PD.Shape geometry object.

Type: PD.Shape

toVRML( [scale])

Produces an VRML file for 3D printing.

Parameters:

Name	Type	Argument	Description
`scale`	number	<optional>	A scale factor to use when exporting the BRep data, defaults to 0.001 (mm to m).

Returns:

Returns the contents of a VRML files representing the polyhedra.

Type: string

toX3D( [scale])

Produces an X3D file for 3D printing.

Parameters:

Name	Type	Argument	Description
`scale`	string	<optional>	A scale factor to use when exporting the BRep data, defaults to 0.001 (mm to m).

Returns:

Returns a the contents of an X3D files representing the polyhedra.

Type: string

transformFromReferencePositions(matrix)

Applies a matrix to the BRep relative to its vertex reference positions.

For this method to work correctly, you must have previously called the PD.BRep#storeReferencePositions method to store the reference position of each vertex.

Parameters:

Name	Type	Description
`matrix`	THREE.Matrix4	The rotation and translation matrix to apply.

Returns:

Returns this BRep to support method chaining.

Type: PD.BRep

validateVertexList()

Ensures that all the vertices used by faces and edges are stored in the PD.BRep#vertexList array.

Any vertices not already in the vertex list are added. It is important that this is done before optimising or converting/exporting the BRep to other formats.

This method also sets the meshIndex property of each vertex to its index in the vertex list, so that it can be used by triangles to quickly access any vertex's position in the list.

Returns:

Returns this BRep to support method chaining.

Type: PD.BRep

weldCoincidentVertices( [decimals])

Iterates all faces and triangles to merge vertices that share the same positions and ensure that adjacent edges share the same vertices.

Parameters:

Name	Type	Argument	Description
`decimals`	number	<optional>	The number of decimal places when comparing millimeter coordinates, defaults to 1 (0.1mm).

Returns:

Returns this shape to support method chaining.

Type: PD.Shape

enableSelection(selectionManager) <static>

Enables the selection and editing of BReps within the model using the given selection manager.

The geometry defined by PD.BRep is used by some elements to store things like primitive shapes, undulating terrain, tree canopies, complex curves or forms created using constructive solid geometry (CSG). This method will create a new selection handler for BReps and assigns it to PD.BRep.Selection.

Parameters:

Name	Type	Description
`selectionManager`	PD.SelectionManager	The selection manager to connect to.

hasMatchingEdgeXY(point1, point2, faces, maxFaceIndex, ignoreFaceIndex) <static>

Checks if the two points have a matching edge in a roughly horizontal surface.

Parameters:

Name	Type	Description
`point1`	PD.Point	The first edge point to check.
`point2`	PD.Point	The second edge point to check.
`faces`	Array	The list of faces to check for edges in.
`maxFaceIndex`	number	The maximum face list index to check.
`ignoreFaceIndex`	number	The index of the face the points belongs to.

Returns:

Returns the matching point.

Type: PD.Point