API Docs

Class: SurfaceShell

BIM.Analysis. SurfaceShell

A shell made up of BIM.Analysis.Surface instances rather than polygons.

This is used by the analysis model to store its simulation surfaces.

new SurfaceShell()

Author:
  • drajmarsh

Extends

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
Inherited From:
:THREE.Box3

extents

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

Type
  • THREE.Box3
Inherited From:
: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
Inherited From:
: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
Inherited From:
: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
Inherited From:
:boolean

isShell <readonly>

A flag identifying this object as a shell.

Type
  • boolean
Inherited From:
: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
Inherited From:
: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
Inherited From:

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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited 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).
Inherited From:
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.
Inherited 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.

Inherited From:
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.

Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.

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.

Parameters:
Name Type Argument Description
vertex THREE.Vector3 | Array.<number> <optional>

An optional vector object or array to copy the content of.
Inherited From:
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.

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.

Parameters:
Name Type Description
vector THREE.Vector3

The vector object to copy the content of.
Inherited From:
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.

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.

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.
Inherited From:
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.

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.

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.

Parameters:
Name Type Description
vector THREE.Vector3

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

Inherited From:
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.

Inherited From:
Returns:

Returns this shell to support method chaining.

Type
PD.Shell

computeExtents()

Recomputes the bounding box extents of the shell.

Inherited From:
Returns:

Returns this shell to support method chaining.

Type
PD.Shell

computeSurfaceArea()

Computes the total surface area of the shell.

Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.

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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.

Inherited From:
Returns:

Returns an ordinal index in the edgeList property.

Type
number

getNextFacetIndex()

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

Inherited From:
Returns:

Returns an ordinal index in the facetList property.

Type
number

getNextVertexIndex()

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

Inherited From:
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.

Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.

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 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).
Inherited From:
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.
Inherited From:
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.
Inherited From:
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.

Inherited From:
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.

Inherited From:
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.

Inherited From:
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.
Inherited From:
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.
Inherited From:
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.

Inherited From:
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.

Inherited From:
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.

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.

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.

Inherited From:
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.
Inherited From:
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.
Inherited From:
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).
Inherited From:
Returns:

Returns this shape to support method chaining.

Type
PD.Shape