Class: Shell

PD. Shell

A shell is a collection of polygonal planar facets that define the surfaces of a facetted 3D shape.

In this framework, shells are used as a flexible and relatively efficient means of storing building geometry before it is converted to a THREE.Mesh or a set of GPU buffers for rendering. In large modelling projects, potentially containing many tens of thousands of independent elements, it is simply not feasible to store each individual element as a mesh with flat attribute and index buffers, and then rely solely on THREE.js to manage them effectively. Using shells offers an interim storage point for element geometry that the framework can use for its own internal purposes and that can be relatively quickly and efficiently added to a renderable mesh whenever required.

Shells also structure element geometry in a way that makes individual surfaces more easily addressable, selectable, editable and reusable than a standard mesh based on GPU index/attribute buffers. When dynamically editing a parametric building element, its shell may need to be regenerated in its entirety up to 60 times a second. As a result, all aspects of a shell are designed to be dynamically reused, and the vast majority of regenerations tend to be positional rather than structural, resulting in exactly the same number of vertices, edges and surfaces as the previous shell, but with some in different positions. In these cases, reusing the existing shell vert often means no requirement for any memory allocation or garbage collection at all. If additional memory is required or some released, the amount is only the incremental difference rather than a complete replacement of the entire set of arrays.

To reuse a shell, you must call the reuseStart() method to begin with. When done, call the reuseEnd() method to trim the vertex, facet and edge lists to the new length. If you are using an element's shell within its own BIM.Element#rebuild() method, you do not need to call either method as the BIM.Element#update() should already handle this automatically for you.

Structure of a Shell

Each facet in a shell is an independent PD.Polygon defined by a closed boundary contour and any number of internal opening contours. Facets are typically planar, which the PD.Polygon class handles well. Whilst you can bend this class to use curves and non-planar surfaces, it is not really optimised for this, whereas the PD.BRep class is.

The reason that shells are not optimised for curved surfaces is that this framework ultimately needs to convert complex building geometry into models that are suitable for analysis and simulation, and the majority of third-party tools that perform such functions almost universally require planar facets as input. Whilst some analysis tools can handle curved surfaces, they typically do so by internally tessellating them into a series of planar facets anyway.

Thus, the shell class is typically used for building geometry such as walls, floors, roofs and ceilings, and focuses on being able to quickly and efficiently create, edit and manage large numbers of planar facets.

Facets may be constructed with common edges to form a manifold solid that completely bounds a volume of space, or as a series of disconnected facets floating independently in space to form any arbitrary non-manifold shape. It is important to note that the shell itself does not know which of these it is, so the host application needs to both determine and track this.

When defining a manifold solid, this kind of shell can be represented as a memory-optimised shape with edges and faces that share common vertices. To do this, use the vertexList array to store the unique vertices that make up the corners of the shape, then create the facets and edges using references to the vertices in that list. Each polygonal facet will calculate its own normal and surface triangles from those vertices.

Rather than have separate create and update methods, the shell class has common methods to reuse different parts, if they exist, or create them as and when required. This way, you can use the same methods to generate and regenerate shell geometry with minimal or no impact on memory allocation and/or garbage collection.

new Shell()

Creates a new simple shell.

Author:

drajmarsh

Examples

/// Example 1:
const shape_in_plan = [ new THREE.Vector3(...), ... ];
const shell = someObject.existingShell:

shell.reuseStart();
shell.addExtrudedContour(shape_in_plan, PD.Utils.Z_Axis, 0.0, 2400.0, PD.FORWARD, PD.CLOSED, PD.CAP.BOTH);
shell.reuseEnd();

/// Example 2:
shell.reuseStart();
const red = new THREE.Color(1.0, 0.0, 0.0);
const bottom = shell.addFacet(shape_in_plan);
const extruded_facets = shell.addExtrudedPolyline(bottom, PD.Utils.Z_Axis, 0.0, 2400.0, PD.FORWARD, PD.CAP.TOP);
for (const facet of extruded_facets) {
    facet.fillColor = red
}
shell.reuseEnd();

/// Example 3:
shell.reuseStart();

const moved_shape = [];
shape_in_plan.forEach((point) => {
    let vtx = shell.addVertex(point);
    vtx.x += Math.random() * 1000.0;
    vtx.z += Math.random() * 2400.0;
    moved_shape.push(vtx);
});

const bottom_facet = shell.addEmptyFacet();
shell.setContour(bottom_facet, 0, moved_shape);
bottom_facet.update();

shell.reuseEnd();

/// Example 4:
shell.reuseStart();

const outer_boundary = [];
const cabinet_shape = cabinet.path.getContour(0);
cabinet_shape.forEach((point) => {
    outer_boundary.push(shell.addVertex(point));
});

const inner_boundary = [];
const hole_for_sink = MyCoolUtils.SinkGenerator.generateHole(cabinet);
hole_for_sink.forEach((point) => {
    inner_boundary.push(shell.addVertex(point));
});

const top = shell.addEmptyFacet();
shell.setContour(top, 0, outer_boundary);
shell.setContour(top, 1, inner_boundary);
top_surface.update();

shell.reuseEnd();

Classes

Factory
KDTreeOrientation

Members

:Array.<Array.<PD.Point>> edgeList

A list of edge lines to be rendered with this shell geometry.

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 PD.Shell#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 shell and facets will only be displayed with surface triangles.

If the PD.Shell#hasUniqueEdges option is false or the edge list is empty, facets 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.

This list is used and reused to create and store edges whenever any of the PD.Shell.add...() methods are called to generate shell geometry. As a result, it should only be considered stable and complete when used outside of calls to reuseStart() and reuseEnd().

Type

Array.<Array.<PD.Point>>

:THREE.Box3 extents

The 3D extents of the shell as a bounding box.

Type

THREE.Box3

:Array.<PD.Polygon> facetList

A list of PD.Polygon objects that make up this shell geometry.

Facets represent flat surfaces that can form manifold geometry when all of their edges are shared, or non-manifold when there are openings or it is just a series of arbitrary disconnected surfaces floating in space.

This list is used and reused to create and store facets whenever any of the PD.Shell.add...() methods are called to generate shell geometry. As a result, it should only be considered stable and complete when used outside of calls to reuseStart() and reuseEnd().

Type

Array.<PD.Polygon>

:boolean hasUniqueEdges

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

A shell is a simple list of facets 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 facet. However, this means that any shared edges between adjacent facets are added twice, and will therefore be rendered twice.

In most instances this is not a problem and makes shell generation much simpler and faster. However, the cost 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 are drawn more than once.

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

Type

boolean

:boolean hasUniqueVertices

Stores whether or not the shell's vertices are unique and shared.

This is only ever true when extra special care is taken by the host application to ensure that each corner position is only represented by a single vertex in the shell's vertexList and that any facets that pass through that corner position reference the same vertex in the list.

This is typically only possible if you create all of the corner vertices of a shape first and then reference them directly when generating each facet. The primitives and extrusion methods in this shell class do their best to share vertices when generating facets, but they don't check for existing geometry already generated.

When a mesh has unique vertices, it becomes possible to detect shared edges and perform a range of useful additional processes such as inflation and deflation or more advanced dynamic editing.

Type

boolean

:boolean isShell <readonly>

A flag identifying this object as a shell.

Type

boolean

:BIM.Path|null linkedToPath

An optional path that the shell is linked to.

This simply stores the linked path and is used as an indicator that the shell needs to be updated whenever the path changes. Exactly how the shell is regenerated from the path is up to each individual element type class.

Type

BIM.Path | null

:Array.<PD.Point> vertexList

A list of PD.Point vertices defining the corners of each facet/edge.

The use of this list is optional as each facet stores a direct reference to the vertices that make up each of its boundary loops. However, having this list provides the shell with the ability to share vertices across multiple facets/edges and access them, potentially optimising both storage and interactive edit-ability.

This list is used and reused to create and store vertices whenever any of the PD.Shell.add...() methods are called to generate shell facets or edges. As a result, it should only be considered stable and complete when used outside of calls to reuseStart() and reuseEnd().

Type

Array.<PD.Point>

Methods

addCircle(coords, radius_x, radius_y [, reverse])

Adds a flat circle with the given parameters to this shell.

The circle's edges will be aligned with the axis of the given local coordinate system.

NOTE: This method reuses vertices and facets already in the shell, 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.
`radius_x`	number			The radius of the cylinder in the local X-axis.
`radius_y`	number			The radius of the cylinder in the local Y-axis.
`reverse`	boolean	<optional>	false	Whether or not to reverse each polygon, defaults to false.

Returns:

Returns a list of the generated facets.

Type: Array

addCylinder(coords, radius_x, radius_y, height [, reverse] [, cap])

Adds a cylinder with the given parameters to this shell.

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

NOTE: This method reuses vertices and facets already in the shell, 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.
`radius_x`	number			The radius of the cylinder in the local X-axis.
`radius_y`	number			The radius of the cylinder in the local Y-axis.
`height`	number			The height of the cylinder 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 facets, defaults to `PD.CAP.BOTH`.

Returns:

Returns a list of the generated facets.

Type: Array

addDuplicateFacet(facet, vector [, reverse])

Creates a duplicate of the given facet with the given offset.

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

Parameters:

Name	Type	Argument	Default	Description
`facet`	PD.Polygon			The facet/polygon to duplicate.
`vector`	THREE.Vector3 \| number		null	An offset vector or a vertical distance, defaults to null.
`reverse`	boolean	<optional>	false	Whether or not to reverse the facet, defaults to false.

Returns:

Returns the newly created facet.

Type: PD.Polygon

addEdge(vertices)

Adds one or more reusable edges to the shell, or creates and adds new ones.

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.

To add a closed loop, either use the addEdgeLoop() method instead or duplicate the first vertex at the end.

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

addEdgeCircleXY(center, radius [, incr])

Adds a horizontal circle of reusable edges to the shell.

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 to the shell, or creates and adds new ones.

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.

This method will add an additional edge by joining the last vertex to the last.

Parameters:

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

Returns:

Returns the edge array just added.

Type: Array

addEmptyFacet()

Retrieves the next reusable facet in the shell, or creates and adds a new one.

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

In addition to fetching/creating a facet, this method also ensures that there is a valid first contour in the polygon, resets the contour count to 1, clears the triangle list and sets the isClosed, showSurface, showOutline and hasChanged flags to true.

You can then use the PD.Shell#setContour method to add contours to the facet.

Returns:

Returns an existing polygonal facet or a newly created one.

Type: PD.Polygon

addEmptyVertex()

Retrieves the next reusable vertex in the shell, 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 shell vertex or a newly created one.

Type: PD.Point

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

Adds an axis-aligned 3D box to this shell.

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

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

NOTE: This method reuses vertices and facets already in the shell, 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 facets, defaults to `PD.CAP.BOTH`.

Returns:

Returns a list of the generated facets.

Type: Array

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

Adds an axis-aligned 3D box to this shell.

This method differs from the PD.Shell#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 facets are created.

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

NOTE: This method reuses vertices and facets already in the shell, 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 facet polygon, defaults to false.
`cap`	PD.CAP	<optional>		Whether or not to add bottom/top facets, defaults to `PD.CAP.BOTH`.

Returns:

Returns a list of the generated facets.

Type: Array

addExtrudedContour(contour, vector, botOffset, topOffset [, reverse] [, close] [, cap])

Adds an extruded contour to the shell.

A contour is simply an array of sequentially connects points.

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

NOTE: If either the bottom or top offset is zero, this method will directly reference the actual vertices given in the contour as the first or second pair of points in each extruded side facet. If these are volatile or shared points, and their values may change independent of this geometry, then you should clone them first.

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

Parameters:

Name	Type	Argument	Description
`contour`	Array		The array of `PD.Point` objects to extrude.
`vector`	THREE.Vector3		The direction to extrude the contour 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.
`close`	boolean	<optional>	Whether or not to join the last point back to the first.
`cap`	PD.CAP	<optional>	If closed, whether or not to add bottom/top facets, defaults to `PD.CAP.NONE`.

Returns:

Returns a list of the generated facets.

Type: Array

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

Adds an extruded polyline to the shell.

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

NOTE: If either the bottom or top offset is zero and the extrusion is not reversed, this method will directly reference the actual vertices given in the contour as the first two points of each extruded side facet. If these are volatile or shared points, and their values may change independent of this geometry, then you should clone them first.

NOTE: This method reuses vertices and facets already in the shell, 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 facets.

Type: Array.<PD.Polygon>

addExtrudedShape(shape, pos, direction, botOffset, topOffset [, reverse])

Adds a shape that is extruded in a vector direction to the shell.

The shape's origin (0,0) is always located at the start position.

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

Parameters:

Name	Type	Argument	Default	Description
`shape`	THREE.Shape			The polyline or element path to extrude.
`pos`	THREE.Vector3			The position to extrude from.
`direction`	PD.Point			The direction to extrude in.
`botOffset`	number			The distance to start extruding along the extrusion vector.
`topOffset`	number			The distance to finish extruding along the extrusion vector.
`reverse`	boolean	<optional>	false	Whether or not to reverse each polygon, defaults to false.

Returns:

Returns a list of the generated facets.

Type: Array

addFacet(vertices [, reverse])

Adds a polygonal facet with three or more vertices to this shell.

The vertices must be given in sequence and in the order they occur in the boundary of the polygon. Facets 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 facets already in the shell, so must only be used between calls to reuseStart() and reuseEnd().

Parameters:

Name	Type	Argument	Description
`vertices`	Array		An array of `PD.Point` objects defining the facet boundary.
`reverse`	boolean	<optional>	Whether or not to reverse the polygon, defaults to false.

Returns:

Returns the reused facet or a newly created one.

Type: PD.Polygon

addFacetAndCheckAxis(vertices, axis)

Adds a polygonal facet with three or more vertices to this shell.

The polygonal facet is created such that its normal direction matches the given major axis.

The vertices must be given in sequence and in the order they occur in the boundary of the polygon. Facets 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 facets already in the shell, so must only be used between calls to reuseStart() and reuseEnd().

Parameters:

Name	Type	Description
`vertices`	Array	An array of `PD.Point` objects defining the facet boundary.
`axis`	PD.AXIS	The axis of a parent plane to match with.

Returns:

Returns the reused facet or a newly created one.

Type: PD.Polygon

addFacetAsTriangleFan(vertices [, reverse])

Adds a facet 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-''

Parameters:

Name	Type	Argument	Description
`vertices`	Array		Three or more vertices to create the facet from.
`reverse`	boolean	<optional>	Whether or not to reverse the facet, defaults to false.

Returns:

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

Type: Array | null

addFacetByLoopingPlanarProfiles(profile1, profile2 [, reverse])

Creates a facet by using two coplanar profiles as edges.

This method is typically used with two profiles created by the generateProfileFromPathContour() method using the same path contour but with different offsets. As a result, it assumes that both profiles lie on the same plane and travel in the same direction along the path but are offset from each other by some reasonable distance.

It creates the facet by simply joining the first and last two points in each profile to form a loop. The starting point and direction of the loop depends on the value of the reverse argument.

      profile1
     __..1..__                __..1..__                __..4..__
0--''         ''--2      2--''         ''--0      3--''         ''--5
        profile2      >>  \ reverse = false \  or  \  reverse = true \
        __..1..__          \     __..4..__   \      \     __..1..__   \
   0--''         ''--2      3--''         ''--5      2--''         ''--0

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

Parameters:

Name	Type	Argument	Description
`profile1`	Array		The first array of `PD.Points` to connect.
`profile2`	Array		The second array of `PD.Points` to connect.
`reverse`	boolean	<optional>	Whether or not to reverse the polygon, defaults to false.

Returns:

Returns a single reused facet.

Type: PD.Polygon

addFacetOffsetFromPathContour(path, innerOffset, outerOffset [, offsetZ] [, contourIndex])

Adds a polygon that is offset from the junctions of a path contour.

This method uses the junctions themselves to offset the two edge lines, and then ClipperLib to clean up the resulting shape.

Parameters:

Name	Type	Argument	Description
`path`	BIM.Path		The path to offset.
`innerOffset`	number		The closest offset distance in the normal direction of each path segment, in mm.
`outerOffset`	number		The farthest offset distance in the normal direction of each path segment, in mm.
`offsetZ`	number	<optional>	The offset distance in the absolute Z-axis in mm, defaults to zero.
`contourIndex`	number	<optional>	The index of the polyline contour to offset, defaults to zero.

Returns:

Returns the newly added polygon.

Type: PD.Polygon

addFacetsByLoopingProfiles(profile1, profile2 [, reverse] [, tolerance] [, checkPlanar])

Creates one or more facets using two coplanar profiles as edges.

This method is typically used with two profiles created by the generateProfileFromPathContour() method using the same path contour but with different offsets. If both profiles lie on the same plane and travel in the same direction along the path, then a single planar facet will be created.

If any part of the two profiles are not coplanar, or the checkPlanar argument is false, then more than one facet will be created where the non-planarity occurs.

It creates the facet by simply joining the first and last two points in each profile to form a loop. The starting point and direction of the loop depends on the value of the reverse argument.

      profile1
     __..1..__                __..1..__                __..4..__
0--''         ''--2      2--''         ''--0      3--''         ''--5
        profile2      >>  \ reverse = false \  or  \  reverse = true \
        __..1..__          \     __..4..__   \      \     __..1..__   \
   0--''         ''--2      3--''         ''--5      2--''         ''--0

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

Parameters:

Name	Type	Argument	Description
`profile1`	Array		The first array of `PD.Points` to connect.
`profile2`	Array		The second array of `PD.Points` to connect.
`reverse`	boolean	<optional>	Whether or not to reverse the polygon, defaults to false.
`tolerance`	number	<optional>	The planarity test threshold, defaults to 5mm.
`checkPlanar`	boolean	<optional>	Whether or not to check for and create complex planar surfaces, defaults to true.

Returns:

Returns an array of one or moe reused facets.

Type: Array.<PD.Polygon>

addFacetsToCapSimilarProfiles(profiles [, reverse])

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

This method is typically used with a series of profiles created by the generateProfileFromPathContour() method using the same path contour but with different horizontal and vertical offsets. As a result, it assumes that all profiles start and end relative to the same end points of the path and therefore lie on the same plane.

Two facets are created, the first by joining together all the first 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 facets already in the shell, 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 facets.

Type: Array

addOctahedron(coords, size [, reverse])

Adds a 3D octahedron with the given dimensions to this shell.

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

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

NOTE: This method reuses vertices and facets already in the shell, 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 facets.

Type: Array

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

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

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 facets already in the shell, 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 facets, defaults to `PD.CAP.BOTH`.

Returns:

Returns a list of the generated facets.

Type: Array

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

Adds a single four-sided polygonal facet to this shell.

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

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

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

Parameters:

Name	Type	Argument	Description
`vtx1`	PD.Point		The bottom-left vertex.
`vtx2`	PD.Point		The bottom-right vertex.
`vtx3`	PD.Point		The top-right vertex.
`vtx4`	PD.Point		The top-left vertex.
`reverse`	boolean	<optional>	Whether or not to reverse the polygon, defaults to false.

Returns:

Returns the reused facet or a newly created one.

Type: PD.Polygon

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

Creates a series of quadrilateral facets that join two profiles.

This method is typically used with two profiles created by the generateProfileFromPathContour() method using the same path contour but with different offsets in the up direction. As a result, it assumes that both profiles travel in the same direction along the path, have the same number of vertices, are offset from each other by some reasonable distance and that each pairing forms a planar quadrilateral facet.

             profile2
             4------------3                    9------------7
                           \                   |            |\
             profile1       \                  |            | \
  0          4------------3_.2  >>  3          8------------6_.5
   '.              __..--''\        |'.              __..--''\ |
     '.    __..--''         \       |  '.    __..--''         \|
  0    '1''                _.2      0    '2''                _.4
   '.              __..--''          '.   |          __..--''
     '.    __..--''                    '. |  __..--''
       '1''                              '1''

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

Parameters:

Name	Type	Argument	Description
`profile1`	Array		The lower profile.
`profile2`	Array		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.
`outlines`	boolean	<optional>	Whether or not to show facet outlines, defaults to false.

Returns:

Returns an array of reused facets.

Type: Array

addSweptShapeByPath(shape, path, contourIndex [, offsetDist] [, reverse] [, outlines])

Adds a shape that is swept along a path to the shell.

The shape's origin (0,0) is always located on the path.

This method sweeps a 2D shape along a 3D path by projecting the shape onto a plane that is normal to the path at each junction. It then generates trapezoidal facets between the points of each sequential pair of profiles to generate the swept geometry.

The path must be a valid BIM.Path as this method uses junction-based logic to compute the offset profiles.

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

NOTE: This method reuses vertices and facets already in the shell, 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`	BIM.Path		The element path to sweep the shape along.
`contourIndex`	number		The index of the path contour to sweep along.
`offsetDist`	number	<optional>	The distance to offset the sweep path from the given path, defaults to 0.0.
`reverse`	boolean	<optional>	Whether or not to reverse the orientation of each polygon, defaults to false.
`outlines`	boolean	<optional>	Whether or not to show facet outlines, defaults to false.

Returns:

Returns a list of the generated facets.

Type: Array

addSweptShapeByPathWithPlanarCheck(shape, path, contourIndex [, offsetDist] [, reverse] [, outlines])

Adds a shape that is swept along a path to the shell.

The shape's origin (0,0) is always located on the path.

This method is similar to PD.Shell#addSweptShapeByPath, but generates a series of profiles that run parallel to the path, each offset by the UV coordinates of the shape. It then checks each pair of profiles to see if all their points are entirely coplanar, in which case it can generate a single polygonal facet that follows the two profiles. If not coplanar, it generates a series of trapezoidal facets just as addSweptShapeByPath would.

The path must be a valid BIM.Path as this method uses junction-based logic to compute the offset profiles.

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

NOTE: This method reuses vertices and facets already in the shell, 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`	BIM.Path		The element path to sweep the shape along.
`contourIndex`	number		The index of the path contour to sweep along.
`offsetDist`	number	<optional>	A distance to offset the sweep path from the given path, defaults to 0.0.
`reverse`	boolean	<optional>	Whether or not to reverse the orientation of each polygon, defaults to false.
`outlines`	boolean	<optional>	Whether or not to show facet outlines, defaults to false.

Returns:

Returns a list of the generated facets.

Type: Array

addSweptShapeByPolyline(shape, polyline [, reverse])

Adds a shape that is swept along a path to the shell.

The shape's origin (0,0) is always located on the path.

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

Parameters:

Name	Type	Argument	Default	Description
`shape`	THREE.Shape			The 2D shape to sweep along the path.
`polyline`	PD.Polyline			The polyline or element path to extrude.
`reverse`	boolean	<optional>	false	Whether or not to reverse each polygon, defaults to false.

Returns:

Returns a list of the generated facets.

Type: Array

addSweptShapeSegment(lastVertices, nextVertices, direction, plane [, reverse])

Extrudes a 2D shape in the given direction, trimmed by two end planes.

The shape's origin (0,0) is located at the given position and oriented such that the virtual Z axis in in the given direction.

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

Parameters:

Name	Type	Argument	Default	Description
`lastVertices`	Array.<PD.Point>			An array of 3D points to extrude and trim.
`nextVertices`	Array.<PD.Point>			An array to receive the trimmed 3D points.
`direction`	THREE.Vector3			The direction vector to sweep the last vertices in.
`plane`	THREE.Plane			The trimming plane to intersect the vertices with.
`reverse`	boolean	<optional>	false	Whether or not to reverse each facet, defaults to false.

Returns:

Returns a list of the generated facets.

Type: Array

addTetrahedron(coords, size [, reverse])

Adds a 3D tetrahedron with the given dimensions to this shell.

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

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

NOTE: This method reuses vertices and facets already in the shell, 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 facets.

Type: Array

addToIndexedShell(faceMesh, pointIndexer [, ignoreFacet])

Add the contents of this shell to an indexed face mesh.

An indexed face mesh is a type of geometry format that 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 as ordinal indexes into the vertices array. It may optionally also have an edges array that stores a set of unique edge lines, again as ordinal indexes.

Such shell objects are typically identified by having a type property with the value IndexedShell. If there is more than one boundary contour for a face, the first is always the outer boundary and each subsequent contour is an inner boundary defining a hole within it.

In this method, vertices are added to the given pointIndexer object, to ensures that only unique positions have ordinal indexes, and facets are added to the faces list in the given faceMesh object. The calling code uses the pointIndexer to build the vertices array.

Indexed face meshes are an even more lightweight format than a Shell. They are typically used for the transmission of 3D geometry data to and from 3D graphics and modeling applications that accept only flat planar surfaces. The inclusion of face normals or plane equations is optional, but they do not store colors, vertex normals, texture coordinates or any other topological data. This information is typically generated on-the-fly by the receiving application as needed.

Due to their simplicity and efficiency, as well as their wide support, this framework uses indexed face meshes for exporting geometry and as an optional format for copying and pasting parts of the building geometry.

Parameters:

Name	Type	Argument	Description
`faceMesh`	object		An indexed face mesh to add facets to.
`pointIndexer`	PD.Indexer		An indexer for adding vertices to.
`ignoreFacet`	PD.Polygon	<optional>	An optional facet to ignore, typically a ceiling.

Returns:

Returns true if any facets were added.

Type: boolean

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

Adds a single three-sided triangular facet to this shell.

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

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

NOTE: This method reuses vertices and facets already in the shell, 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 polygon, defaults to false.

Returns:

Returns the reused facet or a newly created one.

Type: PD.Polygon

addTruncatedCube(coords, size [, reverse])

Adds a cube to this shell, 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 and the

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

NOTE: This method reuses vertices and facets already in the shell, 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 facets.

Type: Array

addVertex( [vertex])

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

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.Point.copyAttribs 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 vector object or array to copy the content of.

Returns:

Returns an existing shell vertex or a newly created one.

Type: PD.Point

addVertexFromArray(vector)

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

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
`vector`	THREE.Vector3	The vector object to copy the content of.

Returns:

Returns an existing shell 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 copy the content of.
`y`	number	The Y coordinate to copy the content of.
`z`	number	The Z coordinate to copy the content of.

Returns:

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

Type: PD.Point

addVertexFromVector(vector)

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

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	An {x,y,z} vector object to copy the content of.

Returns:

Returns an existing shell vertex or a newly created one.

Type: PD.Point

checkAndUpdateExtents(extents [, empty])

Sets the given extents to that of the shell.

Parameters:

Name	Type	Argument	Default	Description
`extents`	THREE.Box3			The extents to update.
`empty`	boolean	<optional>	false	Whether or not to empty the extents first, defaults to false.

Returns:

Returns this shell to support method chaining.

Type: PD.Shell

clear()

Removes all vertices, facets and edges from the shell.

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

Returns:

Returns this shell to support method chaining.

Type: PD.Shell

clearSelection()

Deselects all facets in the shell and all its vertices.

This method iterates all facets in the shell and sets the PD.Point#selected flag to false.

Returns:

Returns this shell to support method chaining.

Type: PD.Shell

computeExtents()

Recomputes the bounding box extents of the shell.

Returns:

Returns this shell to support method chaining.

Type: PD.Shell

computeSurfaceArea()

Computes the total surface area of the shell.

Returns:

Returns the surface area of this shell in m2.

Type: number

copyEdgesToPolyMesh(mesh)

Adds any edge lines in the shell to the given dynamic mesh.

Parameters:

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

Returns:

Returns true if any edge geometry was added to the mesh.

Type: boolean

copyOutlineToPolyMesh(mesh)

Adds the outline of each facet in the shell to the given dynamic mesh.

This method does NOT respect the showOutline flag as it is often used to highlight a shell even if its outline is not normally shown.

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 only upward-facing facets in the shell to the given dynamic mesh.

The method adds the outline to the mesh, as well as the surface if it has one. This method respects the showOutline and showSurface flags of each facet when rendering.

Parameters:

Name	Type	Argument	Description
`mesh`	PD.PolyMesh		The dynamic mesh to add the polygon 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 [, all])

Adds only upward-facing facets in the shell to the given dynamic mesh.

The method adds the outline to the mesh, as well as the surface if it has one. This method respects the showOutline and showSurface flags of each facet when rendering.

Parameters:

Name	Type	Argument	Description
`mesh`	PD.PolyMesh		The dynamic mesh to add the polygon to.
`all`	boolean	<optional>	Whether or not to include all facets rather than just upwards ones.

Returns:

Returns true if geometry was added to the mesh.

Type: boolean

copySurfaceToPolyMesh(mesh)

Adds the surface of each facet in the shell to the given dynamic mesh.

The method does NOT respect the showSurface flag as it is often used to highlight a polygon even if its surface is not normally shown.

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

copyToPolyMesh(mesh [, no_color])

Adds the facets in the shell to the given dynamic mesh.

The method adds the outline to the mesh, as well as the surface if it has one. This method respects the showOutline and showSurface flags of each facet when rendering.

Parameters:

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

Returns:

Returns true if geometry was added to the mesh.

Type: boolean

extrudeContourByVector(contour, vector, distance [, 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.
`vector`	THREE.Vector3			The extrusion direction vector.
`distance`	number			The distance to extrude in the vector direction.
`flip`	boolean	<optional>	false	Whether to reverse the surface orientation, defaults to false.
`closed`	boolean	<optional>	false	Whether or not the contour is closed.

Returns:

Returns an array of facets.

Type: Array.<PD.Polygon>

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

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

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

Type: Array.<PD.Polygon>

extrudePolylineToPlane(polyline, plane [, 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.
`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)

Checks if the given ray intersects any of the facets in the shell.

Parameters:

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

Returns:

Returns the facet that was intersected, or null.

Type: PD.Polygon | null

findFacetsOfType(type)

Searches for facets of the given type in the facet list.

Parameters:

Name	Type	Description
`type`	PD.FACET	The type of facet to include.

Returns:

Returns an array of facets of the given type.

Type: Array

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 shell to support method chaining.

Type: PD.Shell

Example

// Overriding this method.

class MyShell extends PD.Shell {
     /// ...
     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;

     };
     /// ...
 };

generateExtrudedContour(contour, vector, distance)

Creates a new array of points offset from the given contour.

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

Parameters:

Name	Type	Description
`contour`	Array	An array of `PD.Point` objects.
`vector`	THREE.Vector3	The direction to extrude the contour in.
`distance`	number	The Z offset distance from the contour in mm.

Returns:

Returns an array of one or more reused vertices.

Type: Array

generateProfileFromPathContour(contour, offsetY [, offsetZ])

Creates an array of points offset from the junctions in a path contour.

This method does its best to create a line that runs as parallel as possible to the path of the given contour. When all points in a contour are coplanar, this is relatively straightforward and predictable. However, when a contour zigs and zags all over the place and moves significantly out of plane, basic math means that some interesting and relatively un-straightforward shapes are likely.

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

Parameters:

Name	Type	Argument	Default	Description
`contour`	Array			An array of `BIM.Junction` objects.
`offsetY`	number			The offset distance in the normal direction of each path segment, in mm.
`offsetZ`	number	<optional>	0	The offset distance in the absolute Z-axis in mm, defaults to zero.

Returns:

Returns an array of one or more reused vertices.

Type: Array

getNewFacetFactory(coords)

Creates a new instance of a factory utility for adding facets to the shell.

Parameters:

Name	Type	Description
`coords`	PD.LocalCoordinates	The local coordinates to create the facet in.

Returns:

Returns a shell facet factory helper instance.

Type: PD.Shell.Factory

getNextEdgeIndex()

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

Returns:

Returns an ordinal index in the edgeList property.

Type: number

getNextFacetIndex()

Retrieves the ordinal index of the next reusable facet in the shell.

Returns:

Returns an ordinal index in the facetList property.

Type: number

getNextVertexIndex()

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

Returns:

Returns an ordinal index in the vertexList property.

Type: number

hasContent()

Determines whether or not the shell has valid content.

As a shell is primarily a surface representation, this method checks for the presence of at least one facet with a valid boundary contour.

Returns:

Returns true if shell has one or more valid facets.

Type: boolean

intersectRay(ray, target [, front])

Determines the intersection point between a ray and this shell.

If multiple facets are intersected, this method returns the one whose intersection point is closest to the ray origin.

NOTE: Facets of type PD.FACET.HIDDEN still obstruct rays.

Parameters:

Name	Type	Argument	Default	Description
`ray`	THREE.Ray			The ray to intersect the extents with.
`target`	THREE.Vector3			The vector to receive the intersection point.
`front`	boolean	<optional>	false	An optional flag to ensure that only front-facing surfaces are intersected, defaults to false.

Returns:

Returns the closest facet that was intersected or null if nothing was hit.

Type: PD.Polygon | null

isInsideFrustum(frustum, intersect)

Checks if all facets of the shell are within the selection frustum.

Parameters:

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

Returns:

Returns true if all facets are inside.

Type: boolean

isPointInside(point)

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

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 - except when selecting a polygon-based element.

Parameters:

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

Returns:

Returns true if inside, otherwise false.

Type: boolean

loftBetweenFacets(facet1, facet2 [, reverse])

Lofts new surfaces between two given surfaces.

Parameters:

Name	Type	Argument	Description
`facet1`	PD.Polygon		The facet within the given shell to loft from.
`facet2`	PD.Polygon		The facet within the given shell to loft to.
`reverse`	boolean	<optional>	Whether or not to reverse surface orientations, defaults to false.

Returns:

Returns an array of facets.

Type: Array.<PD.Polygon>

moveFromReferencePositions(vector)

Moves the shell relative to its vertex reference positions.

This method iterates all facets in the shell and calls the PD.Point#moveByVector3 method on each vertex. For this method to work correctly, you must have previously called the PD.Shell#storeReferencePositions method to store the reference position of each vertex.

Parameters:

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

Returns:

Returns this shell to support method chaining.

Type: PD.Shell

offsetAndExtrudeContour(coords, contour, axis, offset, distance [, flip] [, closed] [, joinType] [, endType])

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

NOTE: The 3D points in contour must be given in relative local coordinates, meaning that their x, y and z values reference the local coordinate axis rather than the cartesian axis. If you have absolute 3D coordinates in model space, you can easily convert them to relative coordinates using the PD.LocalCoordinates#cartesianToLocal method, as shown in the example below.

Parameters:

Name	Type	Argument	Description
`coords`	PD.LocalCoordinates		The local coordinate system to use.
`contour`	Array.<PD.Point>		The list of relative 3D points to offset and extrude.
`axis`	PD.AXIS		The local axis to extrude along.
`offset`	THREE.Vector3		The offset to apply to the contour.
`distance`	number		The distance to extrude in the given axis.
`flip`	boolean	<optional>	Whether to reverse the surface orientation, defaults to false.
`closed`	boolean	<optional>	Whether or not the contour is closed.
`joinType`	ClipperLib.JoinType	<optional>	The join type to use, defaults to `jtMiter` (closed) or `jtRound` (open).
`endType`	ClipperLib.endType	<optional>	The end type to use, defaults to `etClosedPolygon` (closed) or `etOpenRound` (open).

Returns:

Returns an array of facets.

Type: Array.<PD.Polygon>

Example

/// Convert absolute to relative coordinates in place.
for (const vtx of contour) {
    coords.cartesianToLocal(vtx, vtx);
}
/// Convert absolute to relative coordinates as copy.
const relative_vertices = [];
for (const vtx of contour) {
    relative_vertices.push(coords.cartesianToLocal(vtx, shell.addVertex());
}

shell.offsetAndExtrudeContour(coords, contour, PD.AXIS.Z_POS, 250.0, 1000.0, PD.REVERSE, false);

projectContourOntoPlane(contour, direction, plane)

Projects a contour by the given direction vector onto the given plane.

This method does not generate any facets, just a new copy of the given contour with points projected in the direction of the given vector onto the given plane.

Parameters:

Name	Type	Description
`contour`	Array.<PD.Point>	The contour of points to project.
`direction`	THREE.Vector3	The direction in which to project the points.
`plane`	THREE.Plane	The plane onto which to project points.

Returns:

Returns an array of projected points.

Type: Array.<PD.Point>

projectPolylineOntoPlane(polyline, plane)

Projects a polyline by its normal onto the given plane.

This method does not generate any facets, just a new set of one or more contours that are projected in the direction of the polyline normal onto the given plane.

Parameters:

Name	Type	Description
`polyline`	PD.Polyline	The polyline to extrude.
`plane`	THREE.Plane	The plane to project onto.

Returns:

Returns an array of projected contours.

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

reuseEnd()

Trims the facet and vertex lists to the recently reused geometry.

This method must be called after you have first called reuseStart() to reset the reusable indexes. Its role is to trim any extra vertices or facets that have not been reused and are leftover from a previous geometry regeneration.

For example, the corners of an offset polygon may become less acute as you drag some vertices, meaning that some chamfers are not longer needed so the total number of vertices and facets is less than it was in the previous regeneration. If you don't call this method when you are finished regenerating the shell extruded from the offset polygon, there will likely be some spurious facets left-over from the previous geometry that will still be rendered.

Returns:

Returns this shell to support method chaining.

Type: PD.Shell

reuseStart()

Resets the facet and vertex counters to begin reusing this shell for new geometry.

To iterate through reusable vertices in the shell, use the addVertex() method. For reusable facets, call the addEmptyFacet() method to get the next one, then call the setContour() method for each boundary and void. When done, don't forget to call reuseEnd() to trim the vertex and facet arrays to the reused size.

Returns:

Returns this shell to support method chaining.

Type: PD.Shell

reverse()

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

This method iterates the contours of each facet in the shell and reverses their order so that their surface normals flip direction.

Returns:

Returns this shell to support method chaining.

Type: PD.Shell

setContour(polygon, index, vertices)

Reuses an existing contour from the polygon, or creates a new one.

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

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

Parameters:

Name	Type	Argument	Description
`polygon`	PD.Polygon		The polygon to reuse contours from.
`index`	number		The ordinal index of the contour to add/reuse.
`vertices`	PD.Point	<repeatable>	One or more vertices or arrays of vertices to set the contour to.

Returns:

Returns the existing contour or a newly created one.

Type: Array

splitContourByPlane(contour, plane [, frontList] [, behindList] [, closed])

Splits a polygon into one or more polygons by the given plane.

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

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

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

Parameters:

Name	Type	Argument	Default	Description
`contour`	Array.<PD.Point>			The list of points to split.
`plane`	THREE.Plane			The plane to split the contour by.
`frontList`	Array.<PD.Point>	<optional>		The list to store areas in front of the plane (same direction as surface normal).
`behindList`	Array.<PD.Point>	<optional>		The list to store areas behind the plane (opposite direction to surface normal).
`closed`	boolean	<optional>	false	Whether or not the contour is closed, defaults to false.

Returns:

Returns true if contour was clipped.

Type

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

Type

boolean

storeReferencePositions()

Stores the position of all vertices for later reference.

This method iterates all facets in the shell and calls the PD.Point#storeRefPoint method on each vertex.

Returns:

Returns this shell to support method chaining.

Type: PD.Shell

toFacetedMesh()

Converts the shell contents to a simple list of facets.

A faceted shell has a single facets array that stores the plane equation (plane) and boundary contours (boundaries) of each face. Each boundary contour is a list of [x,y,z] vector arrays defining the position of its vertices. If there is more than one boundary contour for a face, the first is always the outer boundary and each subsequent contour is an inner boundary defining a hole within it.

Such shell objects are typically identified by having a type property with the value FacetedShell.

Faceted shells are not quite as optimised as indexed face shells, as they do not reuse vertices between facets. However, they are simpler to work with for some applications.

Returns:

Returns facet data as a Plain Old Javascript Object (POJO).

Type: object

toIndexedShell()

Convert the contents of this shell to a simple indexed shell.

An indexed face shell is a type of geometry format that has a single vertices array that stores all the vertex positions in the mesh as [x,y,z] vector arrays, and a faces array that stores either the boundary contours of each face or the triangles that make up its surface as ordinal indexes into the vertices array. It may optionally also have an edges array that stores a set of unique edge lines, again as ordinal indexes, and an extents array that stores the bounding minimum and maximum coordinates as two [x,y,z] vector arrays.

Returns:

Returns an indexed shell as a Plain Old Javascript Object (POJO).

Type: object

toJSON( [data])

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

This method is used to copy, store and save the data for a shell, 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.

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 shell as a Plain Old Javascript Object (POJO).

Type: object

Example

// Overriding this method.

class MyShell extends PD.Shell {

     /// ...

     toJSON(data) {

         data = super.toJSON(data);

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

     };

     /// ...

};

transformFromReferencePositions(matrix)

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

This method iterates all facets in the shell and calls the PD.Point#applyMatrix4 method on each vertex. For this method to work correctly, you must have previously called the PD.Shell#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 shell to support method chaining.

Type: PD.Shell

weldCoincidentVertices( [decimals])

Iterates all facets 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

copyPlanViewOutlineToPolyMesh(mesh, facets) <static>

Adds only upward-facing facets to the given dynamic mesh.

The method adds to the mesh the outline of only those facets whose plane normal points upwards relative to the horizontal plane. This includes even those facets with a slight incline. This method does not respect the showOutline flag of each facet when rendering.

Parameters:

Name	Type	Description
`mesh`	PD.PolyMesh	The dynamic mesh to add the polygons to.
`facets`	Array	The list of facets to copy.

Returns:

Returns true if geometry was added to the mesh.

Type: boolean