API Docs

Class: Path

BIM. Path

Defines a path for drawing and building element geometry to follow.

A Path is basically a sequence of BIM.Junction objects connected together by linear or curved segments. The ultimate aim of a Path is to generate one or more contours of vertices that follow the lines and curves defined by its points, and to store the angle, vectors, normals and cross-products that assist in the construction of higher level drawing and building elements. For example. the resulting contour(s) can be used to define the shape of a slab, the run of an extruded wall, the form of a complex window aperture, the line of a lofted stair railing, etc.

The junctions within a path provide the mechanism for defining where curves occur, their specific attributes and how the resulting path travels between them and the next junction in the path. When traversing arcs, beziers or splines, the path will ultimately be represented as a series of line segments generated by sampling along their curves at roughly equidistant spacings - as determined by the segments attribute of the curve. The word 'roughly' simply means that it is not always practical to calculate exact spacings on a bezier oe spline curve as that may not produce the optimal visual representation.

Paths can be either open (with separate start and end points) or closed (where the start and end points are the same to form a loop). This is determined by its isClosed property. When this is set to true, the last junction will be automatically connected back to the first.

By default, the junctions in a path do not have to be coplanar. However, in order to calculate unified normals for each point along the path, its plane equation will still be calculated from the average of all its junctions. To ensure that a path is always coplanar, you can set the isPlanar property to true. To use a plane other than XY, define it by setting the plane property as required.

Important:

When creating a path and adding points programmatically, you should always use the createNewPathPoint() method to create points rather than creating BIM.Junction instances directly. This allows the path to use a junction cache or for subclasses to create their own point types to suit their needs.

new Path( [config])

Creates a new path.

Parameters:
Name Type Argument Description
config object <optional>

A configuration object defining path parameters.
Properties of config:
Name Type Argument Description
element BIM.Element <optional>

The parent element to which this path belongs
contours Array <optional>

An array to be used to store linear contours.
lineColor THREE.Color <optional>

A color to use when rendering the outline, defaults to null.
fillColor THREE.Color <optional>

A color to use when rendering the closed surface, defaults to null.
extents THREE.Box3 <optional>

An optional box instance to store the calculated extents.
plane THREE.Plane <optional>

An optional plane to store the calculated plane equation.
normal THREE.Vector3 <optional>

An optional vector to store the calculated normal.
center PD.Point <optional>

An optional vector to store the calculated center point.
visible boolean <optional>

Whether or not the path should be rendered by its host element, defaults to true.
isClosed boolean <optional>

Whether or not each contour forms a closed loop, defaults to false.
isPlanar boolean <optional>

Forces all points in the polyline/polygon to lie on its plane, defaults to false.
isPolygon boolean <optional>

Whether or not the contours form a single polygon, defaults to false.
keepVertical boolean <optional>

Ensures that the plane normal and up-vector are always vertical, defaults to false.
showOutline boolean <optional>

A flag indicating whether or not to render outlines, defaults to true.
showSurface boolean <optional>

A flag indicating whether or not to render surfaces, defaults to true.
isRect boolean <optional>

Whether or not a polygon should be rectilinear when possible, defaults to false.
Author:
  • drajmarsh

Extends

Classes

SelectionHandler

Members

:PD.AXIS

axis

The major cartesian axis of the polygon (-3 to 3), defaults to zero.

This is mainly used to select the optimum cartesian plane to project the polyline onto when performing 3D->2D->3D operations such as clipping and offsetting. It is stored an a PD.AXIS whose values have the following meaning - 0:not_yet_known, 1:+X, -1:-X, 2:+Y, -2:-Y, 3:+Z, -3:-Z.

Type
Inherited From:
Overrides:
:PD.Point

center

Stores the calculated center position of the polygon.

The position of the center is automatically computed during a normal update if the polygon has changed.

Type
Inherited From:
Overrides:
:Array

contours

An array of contour arrays.

Each contour is an array of THREE.Vector3 instances or a subclass of that type, that are connected by a continuous line or a loop if the polyline is closed. To have multiple separate lines or loops, just add more contours to this array.

Contours within a polygon are slightly different in that the first contour always defines its outer boundary, and any subsequent contours define the inner boundaries of any holes or voids within it.

Type
  • Array
Inherited From:
Overrides:
:BIM.Element|null

element

The parent element to which this path belongs, defaults to null.

Type
:THREE.Box3

extents

The maximum and minimum extents of all contours.

Type
  • THREE.Box3
Inherited From:
Overrides:
:THREE.Color|null

fillColor

An optional color to use for the polygon surface.

Type
  • THREE.Color | null
Inherited From:
Overrides:
:boolean

hasChanged

Whether or not any contours have changed since last updated.

Type
  • boolean
Inherited From:
Overrides:
:boolean

hasCurves

Whether or not the path has one or more curved segments.

Type
  • boolean
Inherited From:
Overrides:
:number

id

A unique integer identifier for fast discovery.

Type
  • number
:boolean

isBIMPath <readonly>

A flag identifying this object as a BIM path.

Type
  • boolean
:boolean

isChanging

Whether or not the polygon is being interactively edited.

Type
  • boolean
Inherited From:
Overrides:
:boolean

isClosed

Whether or not each contour is a closed loop.

When a polyline is closed, the last point in each of its contours is always joined back to the first to form a closed loop. This affects rendering, snapping, offsetting and extrusion.

When the isPolygon flag is set, this value will always be true as polygons must always have closed loop boundaries.

Type
  • boolean
Inherited From:
Overrides:
:boolean

isConcave

Whether or not any part of the outer bounds is concave.

Type
  • boolean
Inherited From:
Overrides:
:boolean

isCurved

Whether or not the surface is curved with triangles already generated.

If this is set on a polygon, then it is assumed that the surface is not flat and has been (or soon will be) triangulated using an external method. The default surface tesselation cannot automatically discern how to best triangulate non-planar surface boundaries.

Type
  • boolean
Inherited From:
Overrides:
:boolean

isPath <readonly>

A flag identifying this object as a path.

Type
  • boolean
Inherited From:
Overrides:
:boolean

isPlanar

Whether or not all vertices lie in the same plane.

If this is set, all vertices in the polyline will be projected onto the current plane whenever they are moved or added. When not set, the plane equation is automatically calculated from the vertices, even if they are not co-planar. This give an 'average' plane that can be used as a normal for determining the directionality of the polyline.

Type
  • boolean
Inherited From:
Overrides:
:boolean

isPolygon

Whether or not the contours form a single polygon.

A polygon differs from a polyline in that it is always closed and it represents a single shape, with the first contour defining its outer boundary and any subsequent contours defining holes or voids within it.

Type
  • boolean
Inherited From:
Overrides:
:boolean

isPolyline <readonly>

A flag identifying this object as a polyline.

Type
  • boolean
Inherited From:
Overrides:
:boolean

isRect

Whether or not the polygon is rectilinear.

Type
  • boolean
Inherited From:
Overrides:
:boolean

keepVertical

Whether or not to keep the plane normal always vertical.

When this flag is set, the normal vector will always point in the direction of the vertical +Z axis regardless of the position of contour points. Whilst this may seem a bit esoteric, being able to specify it in a base polyline (or the BIM.Path subclass) has a whole range of uses, such as when defining railings that follow a stepped staircase, walls that follow an incline, columns at different levels and all sorts of other instances.

Type
  • boolean
Inherited From:
Overrides:
:THREE.Color|null

lineColor

The color to use when rendering the lines.

This value defaults to null and is only used if it is assigned.

Type
  • THREE.Color | null
Inherited From:
Overrides:
:THREE.Vector3

normal

The direction of the normal to this polyline, defaults to +Z axis.

The polygon normal (this value) and the plane normal are two separate objects. The two will typically coincide, but the polygon normal will always be calculated from boundary points even when isPlanar is set as this is used to detect if any points need adjusting back into the plane.

The only caveat to this is when keepVertical is set, in which case the polygon normal is always set to the +Z axis.

Type
  • THREE.Vector3
Inherited From:
Overrides:
:THREE.Plane|null

plane

The average plane equation of the outer boundary of the polygon.

If isPlanar is false (the default), the plane equation is recalculated as the average of all points in the outer boundary each time the polyline changes.

If isPlanar is true, all points in each contour of the polygon will be projected onto this plane whenever they are moved. In order to maintain dimensions and snap positions, this projection is always done along one of the major axis. This means that polygons with large variations in the XY plane and only small variation in the Z axis will be projected onto their plane in the Z axis, and the same for other axis.

Also, the polygon normal and the plane normal (this value) are two separate objects. The two will typically coincide, but the polygon normal will always be calculated from boundary points even when isPlanar is set as this is used to detect if any points need adjusting back into the plane.

The only caveat to this is when keepVertical is set, in which case the polygon normal is always set to the +Z axis.

Type
  • THREE.Plane | null
Inherited From:
Overrides:
:boolean

showOutline

Whether or not the polyline should include its outline(s) when meshed.

Type
  • boolean
Inherited From:
Overrides:
:boolean

showSurface

Whether or not the polyline should include its surface(s) when meshed.

Type
  • boolean
Inherited From:
Overrides:
:Array|null

triangles

A list of triangles that define a tessellated surface.

This is a flat array where each consecutive triplet of points form a separate triangle. Triangles are stored using the same point objects as used in the contour arrays. In fact, apart from some specific cases where the tesselation process may need to create a new interpolated vertex, they will almost always be pointers to the exact same point objects from within the contours array.

Triangles can only be calculated for closed polylines with contours that have at least three vertices (to form at least one triangle). You can compute the triangles for such a polyline using the tesselate() method.

When the isPolygon flag is set, triangles will be automatically computed during each update whenever its geometry has changed. For polylines when the isPolygon flag is not set, you must call the tesselate() method manually.

If the isCurved flag is also set on a polygon, then it is assumed that some other external tesselation method has been or will be used as the internal method cannot automatically discern how best to triangulate non-planar surface boundaries.

Type
  • Array | null
Inherited From:
Overrides:
:boolean

visible

Whether or not the path should be rendered by its host element.

Type
  • boolean
:BIM.Path.Selection

Selection <static>

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

To enable the selection and editing of paths, call the BIM.Path..enableSelection method with the selection manager you wish to use (typically PD.GlobalActions.selectionManager) or, if BIM.Path.Selection already exists, call its BIM.Path.Selection.connectTo method. This will also augment the connected selection set to allow storing of one or more paths and the junctions, segments, apertures or nodes currently selected within them.

Type
:object

icon <static>

The icon associated with this class in the PD.Registry.

See PD.Base.icon for more information on this object format.

Type
  • object
:number

pathId <static>

An internal counter for assigning numeric identifiers to new paths.

Type
  • number

Methods

addContour(contour [, index])

Append the given contour to the polyline's contour array.

If the given contour index is negative, it is treated as an offset from the end of the array, such that -1 is always the last contour.

Parameters:
Name Type Argument Description
contour Array

An array of two or more instances of THREE.Vector3 or a subclass.
index Array <optional>

An optional array index to insert at, defaults to the end of the array.
Inherited From:
Overrides:
Throws:

Occurs if the contour is not an array or contains less than two points.

Type
TypeError
Returns:

Returns the index at which the contour was added.

Type
number

addContourOrientedToAxis(contour [, index])

Append the given contour to the polyline's contour array.

If the normal of the contour does not match the current polyline axis, the order of points in the contour will be reversed so that it does.

If the given contour index is negative, it is treated as an offset from the end of the array, such that -1 is always the last contour.

Parameters:
Name Type Argument Description
contour Array

An array of two or more instances of THREE.Vector3 or a subclass.
index Array <optional>

An optional array index to insert at, defaults to the end of the array.
Inherited From:
Overrides:
Throws:

Occurs if the contour is not an array or contains less than two points.

Type
TypeError
Returns:

Returns the index at which the contour was added.

Type
number

addContourPoint(contourIndex, point)

Appends a point to the contour at the given index in the polyline.

If the given contour index is negative, it is treated as an offset from the end of the array, such that -1 is always the last contour.

Parameters:
Name Type Description
contourIndex number

The numeric index of the contour in the contours array.
point THREE.Vector3

The point to append to the contour.
Inherited From:
Overrides:
Returns:

Returns the index at which the vertex was added, or -1 if contour and/or vertex was invalid.

Type
number

addSubSurfaces(hostJunction, trackJunctions)

Inserts one or more virtual junctions along the path of the given junction.

A virtual junction is inserted whenever any junction from a different path sits on the line of a junction in this path, or where two paths intersect. This is used to ensure that sub-surfaces can be created from the path and are selectable/editable.

Rather than add virtual junctions to the path individually, this method is needed in order to properly distribute apertures across the new junctions so as to accurately maintain their positions. This means first sorting the new junctions by distance from the host junction, and then reassigning apertures to the appropriate new segments.

Parameters:
Name Type Description
hostJunction BIM.Junction

The host junction to insert any virtual junction(s) in.
trackJunctions BIM.Junction | Array.<BIM.Junction>

An external junction or array of external junctions for virtual junction(s) to track.
Returns:

Returns this path to support method chaining.

Type
PD.Path

addVirtualJunction(contour, index, hostJunction, trackJunction [, update])

Inserts a virtual junction along the path of the given junction.

A virtual junction is inserted whenever any junction from a different path sits on the line of a junction in this path, or where two paths intersect. This is used to ensure that sub-surfaces can be created from the path and are selectable/editable.

Parameters:
Name Type Argument Default Description
contour Array.<BIM.Junction>

The contour to insert the virtual junction in.
index number

The ordinal index of the junction within the contour.
hostJunction BIM.Junction

The junction to insert the virtual junction in.
trackJunction BIM.Junction

The external junction that the virtual junction tracks.
update boolean <optional>
 true

Whether or not to update affected junctions, defaults to true.
Returns:

Returns this path to support method chaining.

Type
PD.Path

addVirtualJunctions(hostJunction, trackJunctions [, update])

Inserts one or more virtual junctions along the path of the given junction.

A virtual junction is inserted whenever any junction from a different path sits on the line of a junction in this path, or where two paths intersect. This is used to ensure that sub-surfaces can be created from the path and are selectable/editable.

Rather than add virtual junctions to the path individually, this method is needed in order to properly distribute apertures across the new junctions so as to accurately maintain their positions. This means first sorting the new junctions by distance from the host junction, and then reassigning apertures to the appropriate new segments.

Parameters:
Name Type Argument Default Description
hostJunction BIM.Junction

The host junction to insert any virtual junction(s) in.
trackJunctions BIM.Junction | Array.<BIM.Junction>

An external junction or array of external junctions for virtual junction(s) to track.
update boolean <optional>
 true

Whether or not to update affected junctions, defaults to true.
Returns:

Returns this path to support method chaining.

Type
PD.Path

applyCallback(callback)

Applies a callback function to each path point in the path.

The callback function should take a single argument, being the path point to act upon.

Parameters:
Name Type Description
callback function

The callback function to apply to the path.
Inherited From:
Overrides:
Returns:

Returns this path to support method chaining.

Type
PD.Path

bothPointsOnSameBoundaryXY(point1, point2 [, tolerance])

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

Parameters:
Name Type Argument Description
point1 THREE.Vector3

The first point to to check if on boundary.
point2 THREE.Vector3

The second point to to check if on boundary.
tolerance number <optional>

The distance threshold to define closeness, defaults to 1e-3.
Inherited From:
Overrides:
Returns:

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

Type
boolean

checkToAddVirtualJunctions(kdTree)

Updates or removes any virtual junction from the path if they are no longer connected to their tracking junction.

Parameters:
Name Type Description
kdTree PD.Path.KDTreeXY

A KDTree of path junctions in the level.
Returns:

Returns true if any junctions were added.

Type
boolean

clearAllJunctionShellGeometry()

Clears the shell data in all path points.

Returns:

Returns this path to support method chaining.

Type
BIM.Path

clearContours()

Removes all existing contours within the polyline.

Inherited From:
Overrides:
Returns:

Returns this polyline to support method chaining.

Type
PD.Polyline

clearSelection()

Deselects the path and all its points.

Returns:

Returns this path to support method chaining.

Type
BIM.Path

clearVirtualJunctions()

Removes all virtual junctions from the path.

Returns:

Returns true if any junctions were removed.

Type
boolean

clone()

Creates and returns a deep copy of this path.

Inherited From:
Overrides:
Returns:

Returns the new path.

Type
BIM.Path

computeArea()

Calculates the surface area of a closed polyline in metres squared (m2).

If the isPolygon flag is set, the area of each contour after the first will be subtracted from the area of the first contour, as they are assumed to represent holes or voids within the outer polygonal area. If not set, then the areas of each contour are summed together.

Inherited From:
Overrides:
Returns:

Returns the surface area in metres squared (m2).

Type
number

computeAxis( [update_plane_eqn])

Calculates the extents and major axis in which the polyline sits.

This first computes the average normal of all points in the polyline using Newell's Method. From this it can determine the most appropriate axis to project the line in when performing 3D->2D->3D operations.

This method is typically called without any arguments. You should only set update_plane_eqn to true if you need to recompute the plane equation of a polyline whose PD.Polyline#isPlanar flag is true. This may be needed after having programmatically rotated or transformed the entire polyline.

Parameters:
Name Type Argument Description
update_plane_eqn boolean <optional>

An optional flag to force a recalculation of the plane equation even if the polyline is planar.
Inherited From:
Overrides:
Returns:

Returns true if a valid axis was calculated or false if insufficient points or they are all co-linear.

Type
boolean

computeBoundaryIntersectionPoint(from, to, target)

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

Parameters:
Name Type Description
from THREE.Vector3

The first point in the line.
to THREE.Vector3

The second point in the line.
target THREE.Vector3

The vector to receive the intersection point, may be the same as to.
Inherited From:
Overrides:
Returns:

Returns true if an intersection point was found.

Type
boolean

computeBounds(min, max)

Computes the bounding extents of the polyline/polygon.

For polygons, this method checks only the outer (first) contour. For polylines, all of the contours are checked.

Parameters:
Name Type Description
min THREE.Vector3

The point to receive the minimum extent.
max THREE.Vector3

The point to receive the maximum extent.
Inherited From:
Overrides:
Returns:

Returns true if min/max were set.

Type
boolean

computeClosestPointOnBoundary(point, target)

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

Parameters:
Name Type Description
point THREE.Vector3

The point to check if on boundary.
target THREE.Vector3

The vector to receive the closest point, may be the same as point.
Inherited From:
Overrides:
Returns:

Returns true if a closest point was found.

Type
boolean

computeContourNormal(contour_index, normal)

Calculates the surface normal of the given contour.

This method computes the average normal of all points in the list using Newell's Method.

Parameters:
Name Type Description
contour_index number

The ordinal index of the contour to check.
normal THREE.Vector3

A vector to receive the calculated normal.
Inherited From:
Overrides:
Returns:

Returns true if a valid normal was calculated or false if insufficient points or they are all co-linear.

Type
boolean

computeGeometricCenter(center)

Computes the geometric center of the polyline/polygon.

Parameters:
Name Type Description
center THREE.Vector3

The point to receive the center position.
Inherited From:
Overrides:
Returns:

Returns true if the center point was set.

Type
boolean

copyDashedOutlineToPolyMesh(mesh, size)

Adds the outline of the polyline to the given dynamic mesh.

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

Parameters:
Name Type Description
mesh PD.PolyMesh

The dynamic mesh to add the polyline to.
size number

The size of each dash in model units.
Inherited From:
Overrides:
Returns:

Returns true if geometry was added to the mesh.

Type
boolean

copyDraftingLinesToPolyMesh(mesh, size)

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

This method does NOT respect the showOutline flag as it is often used to given indicative visual feedback in plan view.

Parameters:
Name Type Description
mesh PD.PolyMesh

The dynamic mesh to add the polyline to.
size number

The size of the extended overrun, in model coordinates.
Inherited From:
Overrides:
Returns:

Returns true if geometry was added to the mesh.

Type
boolean

copyHilightLinesToPolyMesh(mesh, size)

Adds the outline as highlight lines to the given dynamic mesh.

This method does NOT respect the showOutline flag as it is often used to outline selected items in plan view.

Parameters:
Name Type Description
mesh PD.PolyMesh

The dynamic mesh to add the lines to.
size number

The width of the line, in model coordinates.
Inherited From:
Overrides:
Returns:

Returns true if geometry was added to the mesh.

Type
boolean

copyOutlineToPolyMesh(mesh [, color] [, update])

Adds the outline of the polyline to the given dynamic mesh.

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

Parameters:
Name Type Argument Default Description
mesh PD.PolyMesh

The dynamic mesh to add the polyline to.
color THREE.Color <optional>
 null

An optional color to render the triangles, defaults to null.
update boolean <optional>
 true

Whether or not to check if changed and include normal and line color, defaults to true.
Inherited From:
Overrides:
Returns:

Returns true if geometry was added to the mesh.

Type
boolean

copyOutlineToPolyMeshWithCallback(mesh, callback)

Add a dynamically transformed polyline to the given dynamic mesh.

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

Parameters:
Name Type Default Description
mesh PD.PolyMesh

The dynamic mesh to add the polyline to.
callback function null

A callback function that takes a point/vertex and returns a THREE.Vector3.
Inherited From:
Overrides:
Returns:

Returns true if geometry was added to the mesh.

Type
boolean

copySurfaceToPolyMesh(mesh [, color] [, update])

Adds any triangles the polyline has 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.

To have a surface, the polyline must have isClosed set and the tesselate() method already called to generate its triangles. If the isPolygon flag is set, then triangles will be automatically computed if anything has changed.

Parameters:
Name Type Argument Default Description
mesh PD.PolyMesh

The dynamic mesh to add the triangles to.
color THREE.Color <optional>
 null

An optional color to render the triangles, defaults to null.
update boolean <optional>
 true

Whether or not to check if changed and include normal and line color, defaults to true.
Inherited From:
Overrides:
Returns:

Returns true if geometry was added to the mesh.

Type
boolean

copySurfaceToPolyMeshReversed(mesh [, color] [, update])

Adds any triangles the polyline has to the given dynamic mesh in reverse orientation.

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.

To have a surface, the polyline must have isClosed set and the tesselate() method already called to generate its triangles. If the isPolygon flag is set, then triangles will be automatically computed if anything has changed.

Parameters:
Name Type Argument Default Description
mesh PD.PolyMesh

The dynamic mesh to add the triangles to.
color THREE.Color <optional>
 null

An optional color to render the triangles, defaults to null.
update boolean <optional>

Whether or not to check if changed and include normal and line color, defaults to true.
Inherited From:
Overrides:
Returns:

Returns true if geometry was added to the mesh.

Type
boolean

copyThickLinesToPolyMesh(mesh, size [, endcap])

Adds the outline as thick lines to the given dynamic mesh.

This method does NOT respect the showOutline flag as it is often used to outline selected items in plan view.

Parameters:
Name Type Argument Description
mesh PD.PolyMesh

The dynamic mesh to add the lines to.
size number

The width of the line, in model coordinates.
endcap PD.ENDCAP <optional>

How to start/end the line, defaults based on isClosed.
Inherited From:
Overrides:
Returns:

Returns true if geometry was added to the mesh.

Type
boolean

copyToPolyMesh(mesh, no_color)

Add the polyline 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 when rendering either component.

To have a surface, the polyline must have isClosed set and the tesselate() method already called to generate its triangles. If the isPolygon flag is set, then triangles will be automatically computed if anything has changed.

Parameters:
Name Type Description
mesh PD.PolyMesh

The dynamic mesh to add the polyline to.
no_color boolean

Whether to render without fill color, defaults to false.
Inherited From:
Overrides:
Returns:

Returns true if geometry was added to the mesh.

Type
boolean

copyToPolyMeshWithCallback(mesh, callback)

Add a dynamically transformed polyline to the given 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 when rendering either component.

To have a surface, the polyline must have isClosed set and the tesselate() method already called to generate its triangles. If the isPolygon flag is set, then triangles will be automatically computed if anything has changed.

Parameters:
Name Type Default Description
mesh PD.PolyMesh

The dynamic mesh to add the polyline to.
callback function null

A callback function that takes a point/vertex and returns a THREE.Vector3.
Inherited From:
Overrides:
Returns:

Returns true if geometry was added to the mesh.

Type
boolean

createNewPathPoint()

Creates a new junction suitable for use in this type of path.

This method overrides PD.Path to create a new BIM.Junction rather than a PD.PathPoint.

Inherited From:
Overrides:
Returns:

Returns a new path junction.

Type
BIM.Junction

distanceToBoundaryXY(point [, tolerance])

Calculates the shortest distance from the point to the facet boundary in the XY plane.

Parameters:
Name Type Argument Description
point THREE.Vector3

The point to to check if inside.
tolerance number <optional>

The distance threshold to define closeness, defaults to 1e-3.
Inherited From:
Overrides:
Returns:

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

Type
boolean

distributePointsByDistance(shell, spacing [, index])

Distributes points along a polyline at fixed intervals defined by a given spacing.

Parameters:
Name Type Argument Description
shell PD.Shell

The shell to reuse points from.
spacing number

The distance between distributed points.
index number <optional>

The index of the contour to use, defaults to 0.
Inherited From:
Overrides:
Returns:

The new array of points placed at the given intervals.

Type
Array.<PD.Point>

ensureDownwardsNormal( [update] [, reverseInner])

Checks the direction of the surface normal and reverses contour(s) such that the Z component of its normal is negative.

This method will ensure that the first contour is oriented such that its normal faces downwards in the negative Z axis, as per the right-hand rule. This works with any polyline at any orientation and tilt angle other than vertical. It does not rotate the position of vertices, but simply reverses the order of vertices within the contour and negates the normal vector so that its Z component is negative rather than positive.

If reverseInner is set to true and the isPolygon flag is set, then any internal contours will be reversed so that their normals face upwards instead. Whilst this framework does not particularly care about the orientation of internal contours, there are some processes that require internal hole contours to be oriented opposite to the boundary contour, which this will do.

If reverseInner is set to false (the default) or the isPolygon flag is not set, then subsequent/internal contours will be reversed so that their normals face downwards to match the first/boundary contour.

Parameters:
Name Type Argument Default Description
update boolean <optional>

When true, the path will update when changed, defaults to false.
reverseInner boolean <optional>
 false

When true, internal contours of polygonal paths will be made to face upwards, defaults to false.
Inherited From:
Overrides:
Returns:

Returns this polyline to support method chaining.

Type
PD.Polyline

ensureUpwardsNormal( [update] [, reverseInner])

Checks the direction of the surface normal and reverses contour(s) such that the Z component of its normal is positive.

This method will ensure that the first contour is oriented such that its normal faces upwards in the positive Z axis, as per the right-hand rule. This works with any polyline at any orientation and tilt angle other than vertical. It does not rotate the position of vertices, but simply reverses the order of vertices within the contour and negates the normal vector so that its Z component is positive rather than negative.

If reverseInner is set to true and the isPolygon flag is set, then any internal contours will be reversed so that their normals face downwards instead. Whilst this framework does not particularly care about the orientation of internal contours, there are some processes that require internal hole contours to be oriented opposite to the boundary contour, which this will do.

If reverseInner is set to false (the default) or the isPolygon flag is not set, then subsequent/internal contours will be reversed so that their normals face upwards to match the first/boundary contour.

Parameters:
Name Type Argument Default Description
update boolean <optional>

When true, the path will update when changed, defaults to false.
reverseInner boolean <optional>
 false

When true, internal contours of polygonal paths will be made to face downwards, defaults to false.
Inherited From:
Overrides:
Returns:

Returns this polyline to support method chaining.

Type
PD.Polyline

findContourAndIndex(point)

Determines which contour the given point belongs to and its ordinal index within that contour.

This method iterates through contours of the polyline, and checks if they contain the point. If found, it returns an array with the contour as the first item and the index of the point within that contour as the second item.

Parameters:
Name Type Description
point PD.Point

The point to determine the contour and index of.
Inherited From:
Overrides:
Returns:

Returns a [contour,index] array.

Type
Array

followExistingPath(path [, offset])

Makes this path follow the given path.

This method ensures that this path has the same number of contours and junctions as the given path, and copies each junctions position, height and orientation if it has one.

Parameters:
Name Type Argument Description
path BIM.Path

The existing path to follow.
offset number <optional>

An offset distance from each path segment in mm, defaults to zero.

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

Converts one or more 2D ClipperLib paths back into polygon contours.

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

If no plane equation is given, the XY plane is assumed (Z=0). If a number is given in place of the plane equation, then that number is used a Z-axis offset in the XY plane (Z = toNumber(plane)).

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

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

Parameters:
Name Type Argument Description
paths Array

One or more ClipperLib paths containing {X,Y} Clipper points.
plane THREE.Plane | number

The plane equation to project points onto or a Z-axis height.
shell PD.Shell <optional>

An optional shell to reuse vertices from.
offset number <optional>

An offset value from the plane in its axial direction.
quaternion THREE.Quaternion <optional>

An optional quaternion to use rather than computing it.
Inherited From:
Overrides:
Returns:

Returns this polyline to support method chaining.

Type
PD.Polyline

fromClipperPathsByAxis(paths, plane [, shell] [, offset])

Converts one or more 2D ClipperLib paths back into polygon contours.

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

If no plane equation is given, the XY plane is assumed (Z=0). If a number is given in place of the plane equation, then that number is used a Z-axis offset in the XY plane (Z = toNumber(plane)).

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

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

Parameters:
Name Type Argument Description
paths Array

One or more ClipperLib paths containing {X,Y} Clipper points.
plane THREE.Plane | number

An optional plane equation to project points onto or a Z-axis height.
shell PD.Shell <optional>

An optional shell to reuse vertices from.
offset number <optional>

An offset value from the plane in its axial direction.
Inherited From:
Overrides:
Returns:

Returns this polyline to support method chaining.

Type
PD.Polyline

fromJSON(data)

Safely copy properties from a source object instance.

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

Parameters:
Name Type Description
data object

The source object instance containing data to copy.
Inherited From:
Overrides:
Returns:

Returns this instance to support method chaining.

Type
PD.Base
Example
// Overriding this method.

class MyPath extends BIM.Path {
     /// ...
     fromJSON(data) {

         super.fromJSON(data);

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

         if ('evenMoreData' in data) {
             this.evenMoreData = new MyThingWithMoreData().fromJSON(data.evenMoreData);
         }

         return this;

     };
     ///...
 };

generateBRepContour(brep, contourIndex [, side] [, offsetXY] [, offsetZ])

Creates an offset contour from one of the contours in this path.

This method creates a new offset contour by creating new points in the given BRep, including points around curved path segments.

Parameters:
Name Type Argument Description
brep PD.BRep

The BRep to add points to.
contourIndex number

The index of the contour to copy.
side PD.SIDE <optional>

Which side of the path to generate, defaults to PD.SIDE.MIDDLE.
offsetXY number <optional>

An offset normal to the path lines, defaults to zero.
offsetZ number <optional>

An offset in the Z-axis, defaults to zero.
Inherited From:
Overrides:
Returns:

Returns the updated path.

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

generateOffsetPath(path [, side] [, offsetXY] [, offsetZ] [, update] [, callback])

Sets the path points of the given path so they are offset from this path.

This method also adds path points around curved segments so you can access the individual segments properties of complex curves.

By default the generated path will be updated once it has been changed. However, if you wish to modify the path further before updating it, you can set the update argument to false.

The optional callback function allows you to process each newly created path point as it is generated. The callback function is passed two arguments: the new path point and the original path point it was generated from.

Parameters:
Name Type Argument Default Description
path PD.Path

The path to offset from this one.
side PD.SIDE <optional>

Which side of the path to generate, defaults to PD.SIDE.MIDDLE.
offsetXY number | Array.<number> <optional>

An offset normal to the path lines or an [outer,inner] offset array for polygons with holes, defaults to zero.
offsetZ number <optional>

An offset in the Z-axis, defaults to zero.
update boolean <optional>
 true

Whether or not to update the generated path before returning, defaults to true.
callback function | null <optional>
 null

A optional function to be called for each new path point, defaults to null.
Inherited From:
Overrides:
Returns:

Returns the updated path.

Type
PD.Path

generateShellEdges(shell [, side] [, offset] [, inset])

Copies the path to shell edge lines, using vertices from the given shell and applying the offset as well as each path point's curve and projection.

Parameters:
Name Type Argument Description
shell PD.Shell

The shell to add the polygon to.
side PD.SIDE <optional>

Which side of the path to generate.
offset number <optional>

A base offset for external boundary, defaults to zero.
inset number <optional>

A base inset for internal boundaries, defaults to offset.
Inherited From:
Overrides:
Returns:

Returns the number of edges created.

Type
number

generateShellFacet(shell [, reverse] [, side] [, offset] [, inset] [, vector])

Copies the path to a closed polygonal shell facet, using vertices from the given shell and applying the offset as well as each path point's curve and projection.

    + - - - - - - - - - - - - - - + - + - offset
    : +-------------------------+ : - + -
    : | Outer boundary          | :
    : |                         | :
    : |       Inner boundary    | :
    : |       +-------------+ - | : - + -
    : |       | + - - - - + | - | : - + - inset
    : |       | :         : |   | :
    : |       | :         : |   | :       PD.SIDE.INSIDE
    : |       | + - - - - + |   | :       + - - - - - - - + innerEdgeOffset
    : |       +-------------+   | :       +------->-------+ path
    : |                         | :       / / / \ \ \ / / /
    : +-------------------------+ :       + - - - - - - - + outerEdgeOffset
    + - - - - - - - - - - - - - - +       PD.SIDE.OUTSIDE

This differs from the PD.Path#generateShellPolyline method in that it always creates a closed PD.Polygon and adds it as a facet to the given shell, even if the path is not closed.

Most of the actual work in this method is done by the PD.Path#getSegmentOffsetPoints method, which is called for each path point in each contour of the path.

Which Side

The side argument determines whether the PD.PathPoint#innerEdgeOffset, or PD.PathPoint#outerEdgeOffset, or the point's PD.PathPoint#projection properties are applied.

A side value of PD.SIDE.NONE means that only the given offset is used and the projection and material thickness values are ignored. A value of PD.SIDE.MIDDLE means that the offset and projection value are used, whereas PD.SIDE.INSIDE and PD.SIDE.OUTSIDE include the offset, projection and material thicknesses.

Parameters:
Name Type Argument Description
shell PD.Shell

The shell to add the polygon to.
reverse reverse <optional>

Whether or not to reverse the normal direction.
side PD.SIDE <optional>

Which side of the path to generate.
offset number <optional>

An optional base offset for outer boundary, defaults to zero.
inset number <optional>

An optional base inset for inner boundaries, defaults to the same value as offset.
vector THREE.Vector3 | number <optional>

An optional vector or Z-axis offset to apply to offset points, defaults to zero.
Inherited From:
Overrides:
Returns:

Returns the newly added polygonal facet.

Type
PD.Polygon

generateShellPolyline(shell [, poly] [, side] [, offset])

Copies the path to a polyline, using vertices from the given shell and applying the offset as well as each path point's curve and projection.

This differs from the PD.Path#generateShellFacet method in that it handles open paths and does not add edges or facets to the shell, even if the path is closed and polygonal. It simply uses the shell as a repository of reusable points.

Most of the actual work in this method is done by the PD.Path#getSegmentOffsetPoints method, which is called for each path point in each contour of the path.

Which Side

The side argument determines whether the PD.PathPoint#innerEdgeOffset, or PD.PathPoint#outerEdgeOffset, or the point's PD.PathPoint#projection properties are applied.

A side value of PD.SIDE.NONE means that only the given offset is used and the projection and material thickness values are ignored. A value of PD.SIDE.MIDDLE means that the offset and projection value are used, whereas PD.SIDE.INSIDE and PD.SIDE.OUTSIDE include the offset, projection and material thicknesses.

Parameters:
Name Type Argument Description
shell PD.Shell

The shell to add the polygon to.
poly PD.Polyline <optional>

An optional polyline to receive the vertices.
side PD.SIDE <optional>

Which side of the path to generate, defaults to PD.SIDE.MIDDLE.
offset number <optional>

An offset from the path lines, defaults to zero.
Inherited From:
Overrides:
Returns:

Returns the given polyline or a newly created one.

Type
PD.Polyline

getContour(contourIndex [, wantNull])

Retrieves the contour at the given index within the polyline.

If the given contour index is negative, it is treated as an offset from the end of the array, such that -1 is always the last contour.

Parameters:
Name Type Argument Default Description
contourIndex number

The numeric index of the required contour in the contours array.
wantNull boolean <optional>
 false

When true, returns null instead of an empty array when index out of range, defaults to false.
Inherited From:
Overrides:
Returns:

Returns a contour if found, which is basically an array of connected points, or an empty array / null.

Type
Array

getContourCount()

Retrieves the number of contours within the contour list of a polyline.

Inherited From:
Overrides:
Returns:

Returns the number of contours in the polyline.

Type
number

getContourIndexContainingPoint(point)

Determines the index of the contour that the given point belongs to, if any.

Parameters:
Name Type Description
point PD.Point

The point to determine the contour index of.
Inherited From:
Overrides:
Returns:

Returns the index of the contour, or -1 if point is not in this polyline.

Type
number

getContourPoint(contourIndex, vertexIndex)

Retrieves a point at the given index in a contour of the polyline.

If either the contour or vertex index is negative, it is treated as an offset from the end of the corresponding array, such that -1 is always the last contour or vertex in the contour.

Parameters:
Name Type Description
contourIndex number

The numeric index of the required contour in the contours array.
vertexIndex number

The numeric index of the required vertex within the contour array, may be negative.
Inherited From:
Overrides:
Returns:

Returns a vertex, or null if contour and/or vertex index is invalid.

Type
THREE.Vector3 | null

getContourPointCount(contourIndex)

Retrieves the number of points in the contour at the given index.

If the given contour index is negative, it is treated as an offset from the end of the array, such that -1 is always the last contour.

Parameters:
Name Type Description
contourIndex number

The numeric index of the required contour in the contours array.
Inherited From:
Overrides:
Returns:

Returns a contour, which is basically an array of points.

Type
number

getContours()

Retrieves the contours array for the polyline.

A polyline's contours is basically an array of zero or more point arrays.

Inherited From:
Overrides:
Returns:

Returns the contours array.

Type
Array.<Array>

getListOfJunctionsWithApertures(clear_flags)

Checks through the path for junctions with apertures.

Parameters:
Name Type Default Description
clear_flags boolean false

Whether or not to clear the isInserted and isExternal properties of each aperture, defaults to false.
Returns:

Returns a list of junctions with apertures in them.

Type
Array

getPointOnBoundary(point [, tolerance])

Determines if the given point is on or close the polyline boundary and returns segment start.

Parameters:
Name Type Argument Description
point THREE.Vector3

The point to check if on boundary.
tolerance number <optional>

The distance threshold to define closeness, defaults to 1e-3.
Inherited From:
Overrides:
Returns:

Returns the start of the found boundary segment.

Type
THREE.Vector3

getPointOnBoundaryXY(point [, tolerance])

Determines if the given point lies on or close to the facet boundary in the XY plane and returns segment start.

Parameters:
Name Type Argument Description
point THREE.Vector3

The point to to check if on boundary.
tolerance number <optional>

The distance threshold to define closeness, defaults to 1e-3.
Inherited From:
Overrides:
Returns:

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

Type
boolean

getSegmentOffsetPoints(shell, segment, contour [, side] [, offset])

Creates an array of points along the path point segment, reusing vertices from the given shell and applying curves, offsets and projections.

This method does not add any edges or facets to the given shell. It just treats the shell as a repository of reusable points.

Details

Each path point in a path can have its own projection offset, be assigned a material with a different internal and/or external thickness to the path points on either side, or be defined by a curve. Thus, the actual line joining the given path point with the next one in a path can often be very different from a straight line joining the two.

Also, the actual geometry generated from a path rarely travels directly along it. Walls, railings, fences and colonnades typically have both internal and external material thicknesses to consider. Slabs, ceilings, terrains and walkways typically have a projection beyond the boundary. This method sits at the core of all the generative functions that build such elements.

Which Side

The side argument determines whether the PD.PathPoint#innerEdgeOffset, or PD.PathPoint#outerEdgeOffset, or the point's PD.PathPoint#projection properties are applied.

A side value of PD.SIDE.NONE means that only the given offset is used and the projection and material thickness values are ignored. A value of PD.SIDE.MIDDLE means that the offset and projection value are used, whereas PD.SIDE.INSIDE and PD.SIDE.OUTSIDE include the offset, projection and material thicknesses.

      PD.SIDE.INSIDE
      + - - - - - - - + innerEdgeOffset
      / / / \ \ \ / / /
      +------->-------+ path
      \ \ \ / / / \ \ \
      / / / \ \ \ / / /
      + - - - - - - - + outerEdgeOffset
      PD.SIDE.OUTSIDE
Parameters:
Name Type Argument Description
shell PD.Shell

The shell to reuse points from.
segment PD.PathPoint

The path segment to generate the points along.
contour Array.<PD.Point>

The array to receive the new path segment points.
side PD.SIDE <optional>

Which side of the path to generate the points on, defaults to PD.SIDE.MIDDLE.
offset number <optional>

An additional offset from the projected path segment, defaults to zero.
Inherited From:
Overrides:
Returns:

Returns the contour array with points added along the path segment.

Type
Array.<PD.Point>

getSelectedJunctions()

Searches through the path for selected junctions.

Returns:

Returns a list of junctions whose selected property is true.

Type
Array

hasContent()

Determines whether or not the polyline has valid content.

Inherited From:
Overrides:
Returns:

Returns true if contours have more than one point.

Type
boolean

isDownwardsFacing()

Returns true if the polyline normal is facing downwards.

All polylines, closed or open, have a normal direction computed for them and stored in its normal property. Even a single point polyline will use the +Z axis as its normal direction. If consecutive points in a polyline are arranged in a counter-clockwise direction around the +Z axis, then according to the right-hand rule, the normal will point upwards (+Z).

If the points are arranged in a clockwise direction, then the normal will point downwards (-Z). This getter returns true if the Z component of the normal direction is less than zero.

Inherited From:
Overrides:
Returns:

Returns true if the polyline normal is facing downwards.

Type
boolean

isInsideContour(point [, index])

Determines whether or not the given point is within a contour of this polygon.

This method sums the signed angle between the given point and each line segment of the given contour boundary. If the total angle is near zero, then the point must be outside. If near 360, it must be inside.

Parameters:
Name Type Argument Description
point THREE.Vector3

The point to to check if inside.
index number <optional>

The index of the contour within the polyline, defaults to 0.
Inherited From:
Overrides:
Returns:

Returns true if inside, otherwise false.

Type
boolean

isInsideFrustum(frustum, intersect)

Determines whether or not the polygon is inside the given frustum or, when intersection is set, if it is intersected.

Parameters:
Name Type Description
frustum THREE.Frustum

The frustum to check if inside.
intersect boolean

Whether to also check for intersection selection.
Inherited From:
Overrides:
Returns:

Returns true if inside, otherwise false.

Type
boolean

isPointInside(point [, selecting])

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

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.

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

Parameters:
Name Type Argument Default Description
point THREE.Vector3

The point to to check if inside.
selecting boolean <optional>
 false

Whether or not this is being use to select a polygon, defaults to false.
Inherited From:
Overrides:
Returns:

Returns true if inside, otherwise false.

Type
boolean

isPointOnBoundary(point [, tolerance])

Determines if the given point is on the polyline boundary.

Parameters:
Name Type Argument Description
point THREE.Vector3

The point to to check if on boundary.
tolerance number <optional>

The distance threshold to define closeness, defaults to 1e-3.
Inherited From:
Overrides:
Returns:

Returns true if on boundary, otherwise false.

Type
boolean

isPointOnBoundaryXY(point [, tolerance])

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

Parameters:
Name Type Argument Description
point THREE.Vector3

The point to to check if on boundary.
tolerance number <optional>

The distance threshold to define closeness, defaults to 1e-3.
Inherited From:
Overrides:
Returns:

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

Type
boolean

isUpwardsFacing()

Returns true if the polyline normal is facing upwards.

All polylines, closed or open, have a normal direction computed for them and stored in its normal property. Even a single point polyline will use the +Z axis as its normal direction. If consecutive points in a polyline are arranged in a counter-clockwise direction around the +Z axis, then according to the right-hand rule, the normal will point upwards (+Z).

If the points are arranged in a clockwise direction, then the normal will point downwards (-Z). This getter returns true if the Z component of the normal direction is greater than or equal to zero.

Inherited From:
Overrides:
Returns:

Returns true if the polyline orientation is upwards.

Type
boolean

keepAspectRatio(aspect, index [, axis])

Maintains the relative aspect ratio of a closed rectangular contour.

Parameters:
Name Type Argument Description
aspect number

The aspect ratio (h/w) to maintain.
index number

The index of the outer contour vertex that was moved.
axis PD.AXIS <optional>

An optional axis override, defaults to X axis.
Inherited From:
Overrides:
Returns:

Returns true if the polygon is rectangular and its width/height changed.

Type
boolean

keepRectangular(index)

Maintains a polygon as rectangular by adjusting its bounding box.

This is used when the position of one corner of a rectangular polygon is changed. It computes the bounding box using the opposite corner and maintains its rectangular shape.

NOTE: The behaviour of this method is different to makeRectangularByCorners() in that the space size is limited to a minimum value and the opposite corners always remain opposite.

Parameters:
Name Type Description
index number

The index of the outer contour vertex that was moved.
Inherited From:
Overrides:
Returns:

Returns true if the polygon is rectangular and its width/height changed.

Type
boolean

makePlanar( [newPlane])

Ensures that all points in the polyline sit on the same plane.

If a new plane is given, it will be copied to both the polyline's own plane and normal, and the isPlanar flag set to true. This will ensure that the polyline remains planar with this plane.

You can also use this method to ensure that all points in the polyline are made coplanar with it's own plane as a one-off process, without setting the isPlanar flag, by simply not including the newPlane argument.

Parameters:
Name Type Argument Description
newPlane THREE.Plane <optional>

The plane to use, defaults to the polyline's own plane.
Inherited From:
Overrides:
Returns:

Returns true if any points were not coplanar and had to be moved into the plane, otherwise false.

Type
boolean

makeRectangularByCorners(contour, corner1, corner2 [, min_size])

Maintains a polygon as rectangular by adjusting its bounding box.

Parameters:
Name Type Argument Description
contour Array

The actual contour to keep rectangular.
corner1 THREE.Vector3

The first corner of the rectangle.
corner2 THREE.Vector3

The second corner of the rectangle.
min_size number <optional>

An optional minimum rectangle size, defaults to 25mm or 1".
Inherited From:
Overrides:
Returns:

Returns true if the polygon is rectangular and its width/height changed.

Type
boolean

moveBy(dx [, dy] [, dz])

Move all vertices by a relative vector.

Parameters:
Name Type Argument Description
dx number | THREE.Vector3

Either the X-axis movement component or a vector.
dy number <optional>

The Y-axis movement component.
dz number <optional>

The Z-axis movement component.
Inherited From:
Overrides:
Returns:

Returns this polyline to support method chaining.

Type
PD.Polyline

moveByMatrix4(matrix [, about])

Applies a dynamic transformation relative to the last snapshot.

Parameters:
Name Type Argument Description
matrix THREE.Matrix4

The 4x4 matrix to apply.
about THREE.Vector3 <optional>

An optional point about which to apply the transform.
Inherited From:
Overrides:
Returns:

Returns this path to support method chaining.

Type
PD.Path

moveByQuaternion(quat [, about])

Applies a dynamic transformation relative to the last snapshot.

Parameters:
Name Type Argument Description
quat THREE.Quaternion

The relative transform matrix.
about THREE.Vector3 <optional>

An optional point about which to apply the transform.
Inherited From:
Overrides:
Returns:

Returns this path to support method chaining.

Type
PD.Path

moveByVector3(vector)

Move the path by a vector relative to the last snapshot.

Parameters:
Name Type Description
vector THREE.Vector3

The relative movement vector.
Inherited From:
Overrides:
Returns:

Returns this path to support method chaining.

Type
PD.Path

overlapsXY(poly)

Determines if the given polygon/polyline overlaps this in the XY plane.

NOTE: If this polygon/polyline is not closed, this method will always return false.

Parameters:
Name Type Description
poly PD.Polyline

The polyline to check for overlap.
Inherited From:
Overrides:
Returns:

Returns true is polyline overlap in the XY plane, otherwise false.

Type
boolean

removeContour(contourIndex)

Removes a contour at the given index from the polyline's contour array.

If the given contour index is negative, it is treated as an offset from the end of the array, such that -1 is always the last contour.

Parameters:
Name Type Description
contourIndex number

The numeric index of the required contour in the contours array.
Inherited From:
Overrides:
Returns:

Returns true if the contour index was valid and the contour removed.

Type
boolean

removeVirtualJunction(contour, index, hostJunction, virtualJunction [, update])

Removes a virtual junction from the path of the given junction.

A virtual junction is removed when either the junction to which it belongs is moved (and it then no longer forms a 180 degree angle), or it is no longer coincident with junction that it is tracking. If the user selects and manually edits a virtual junction, it will be converted to a normal junction.

Removing a virtual junction deletes it from the sequence of junctions in the path, but it will still remain in the virtual junctions array for several minutes in case the two paths are subsequently reconnected or the action is undone.

Parameters:
Name Type Argument Default Description
contour Array.<BIM.Junction>

The contour to remove the virtual junction from.
index number

The ordinal index of the virtual junction within the contour.
hostJunction BIM.Junction

The junction that hosts the virtual junction.
virtualJunction BIM.Junction

The virtual junction to be removed.
update boolean <optional>
 true

Whether or not to update affected junctions, defaults to true.
Returns:

Returns this path to support method chaining.

Type
PD.Path

reverse( [forceUpdate])

Reverses the order of vertices as well as the normal orientation.

Parameters:
Name Type Argument Description
forceUpdate boolean <optional>

Whether or not to update even if polyline has not changed, defaults to false.
Inherited From:
Overrides:
Returns:

Returns this polyline to support method chaining.

Type
PD.Polyline

reverseContour(contourIndex)

Reverses the order of vertices in the contour at the given index.

Parameters:
Name Type Description
contourIndex number

The numeric index of the required contour in the contours array.
Inherited From:
Overrides:
Returns:

Returns true if the contour index was valid and the contour reversed.

Type
boolean

setContour(contourIndex, contour)

Replaces the contour at the given index within the polyline.

If the given contour index is negative, it is treated as an offset from the end of the array, such that -1 is always the last contour.

Parameters:
Name Type Description
contourIndex number

The numeric index of the required contour in the contours array.
contour Array

A new contour, which is basically an array of connected points.
Inherited From:
Overrides:
Throws:

Occurs if the contour is not a valid array.

Type
TypeError
Returns:

Returns true if the contour was replaced.

Type
boolean

setContours(contours)

Sets the array of contours that make up the polyline.

Parameters:
Name Type Description
contours Array

An array of one or more contours containing at least two points.
Inherited From:
Overrides:
Throws:

Occurs if contours is not a valid list of contours.

Type
TypeError
Returns:

Returns this polyline to support method chaining.

Type
PD.Polyline

setPointCache(pointCache)

Sets the point cache that this path should use when adding new points to itself.

Parameters:
Name Type Description
pointCache PD.PathPoint.Cache | null

A point cache to use for this path, or null to clear it.
Inherited From:
Overrides:
Returns:

Returns this path to support method chaining.

Type
PD.Path

shuffleContour(contourIndex, direction)

Shuffled the order of vertices in the contour at the given index.

Parameters:
Name Type Description
contourIndex number

The numeric index of the required contour in the contours array.
direction number

The direction of shuffle (1:Forwards/Right, -1:Backwards/Left).
Inherited From:
Overrides:
Returns:

Returns true if the contour index was valid and the contour reversed.

Type
boolean

storeRefData()

Snapshots the position of all components ready for a move.

Inherited From:
Overrides:
Returns:

Returns this path to support method chaining.

Type
PD.Path

tesselate()

Tessellates closed contours using the robust LibTess algorithm.

For closed polylines, each contour is treated as an independent and separate closed shape.

                             +----+                  +
            +-------+        |    |                _/ \
          _/        |   +----+    +----+         _/    \
        _/          +   |  contour[1]  |       _/       \
      _/ contour[0] |   +----+    +----+     _/          \
     +--------------+        |    |        _/  contour[2] \
                             +----+       +----------------+

For closed polygons, the first contour is treated as an outer boundary and each subsequent contour as a hole or void within that boundary. As polygons are assumed to have a surface, this method is automatically called during its normal update process, whenever its geometry has changed.

    +----------------------+
    | contour[0]           |
    |                      |
    |    +------------+    |
    |    | contour[1] |    |
    |    +------------+    +-------+
    |                              |
    |    +--------------------+    |
    |    |     contour[2]     |    |
    |    +--------------------+    |
    |                              |
    +------------------------------+

The vertices in each contour do not have to be co-planar or non-self-intersecting as the tesselator will do its best to work out what is appropriate in each case. However, some weird shape configurations will work and others won't, but the algorithm is pretty robust so the worst that can happen is simply an empty triangle list.

Inherited From:
Overrides:
Returns:

Returns a flat array of THREE.Vector3 objects from the contours array, where each consecutive triplet forms a triangle.

Type
Array

to2D_AsArrays( [axis])

Converts the contours in a polyline into an array of 2D vector arrays.

This method creates contours arrays of [x,y] vector arrays for use with 2D libraries. This differs from the ClipperLib-related methods which create {X,Y} point objects.

A 3D polyline is projected into a 2D cartesian plane using its plane equation to determine the most suitable cartesian axis to use. If no plane equation is available, the x and y components of the 3D points are used.

Parameters:
Name Type Argument Description
axis PD.AXIS <optional>

The axis to use when converting, defaults to this.axis.
Inherited From:
Overrides:
Returns:

Returns an array of one or more contour arrays, each containing [x,y] 2D vector arrays.

Type
Array

to2D_AsVectors( [axis])

Converts the contours in a polyline into an array of 2D points.

This method creates contours arrays of {x,y} point objects for use with 2D libraries. This differs from the ClipperLib-related methods which create {X,Y} point objects.

A 3D polyline is projected into a 2D cartesian plane using its plane equation to determine the most suitable cartesian axis to use. If no plane equation is available, the x and y components of the 3D points are used.

Parameters:
Name Type Argument Description
axis PD.AXIS <optional>

The axis to use when converting, defaults to this.axis.
Inherited From:
Overrides:
Returns:

Returns an array of one or more contour arrays, each containing {x,y} 2D point objects.

Type
Array

toClipperPaths( [clipCache])

Converts the contours in a polyline into 2D ClipperLib.Path arrays.

As ClipperLib works with 2D {X,Y} objects, the 3D polyline must be translated into a 2D cartesian plane. This method uses the surface normal to compute a quaternion to rotate contour points flat in the XY plane.

This quaternion is then applied to each point in the polyline. This is more computationally expensive than using the axis of greatest surface exposure, but better retains the orientation and winding order of points.

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

Parameters:
Name Type Argument Description
clipCache PD.Clipper.Cache <optional>

An optional cache for reusing 2D clipper points.
Inherited From:
Overrides:
Returns:

Returns an array of one or more ClipperLib.Path arrays, each containing {X,Y} Clipper points, one for each contour in the polyline/polygon.

Type
Array

toClipperPathsByAxis( [axis] [, clipCache])

Converts the contours in a polyline into 2D ClipperLib.Path arrays using the axis of greatest surface exposure.

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

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

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

Parameters:
Name Type Argument Description
axis PD.AXIS <optional>

The axis to use when converting, defaults to this.axis.
clipCache PD.Clipper.Cache <optional>

An optional cache for reusing 2D clipper points.
Inherited From:
Overrides:
Returns:

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

Type
Array

toGeoJSON()

Generates a GeoJSON object from this polyline or polygon.

The type of GeoJSON object depends on the type of polyline. A normal non-closed polyline is created as a GeoJSON.LineString if it has just a single contour, or a GeoJSON.MultiLineSTring if it has more than one.

If the isPolygon flag is set, a GeoJSON.Polygon object will be created with a boundary and any internal holes or voids the polygon has. If isPolygon flag is not set, but isClosed is, then either a single contour GeoJSON.Polygon is created or a GeoJSON.MultiPolygon with one polygon per contour.

Inherited From:
Overrides:
Returns:

Returns an object with type and coordinates properties.

Type
object
Examples
// LineString
{
  'type': 'LineString',
  'coordinates': [
     [ 0.0, 0.0 ], [ 2000.0, 0.0 ], [ 2000.0, 1000.0 ], [ 0.0, 1000.0 ]
  ]
}
// MultiLineString
{
  'type': 'MultiLineString',
  'coordinates': [
    [ [ 2500.0, 250.0 ], [ 4500.0, 250.0 ], [ 4500.0, 750.0 ], [ 2500.0, 750.0 ] ],
    [ [ 0.0, 0.0 ], [ 2000.0, 0.0 ], [ 2000.0, 1000.0 ], [ 0.0, 1000.0 ] ]
  ]
}

GeoJSON polygons are slightly different to LineStrings in that:

- Each linear ring is a closed LineString, with the first coordinate included
  and repeated as the last coordinate.

- The first and last positions MUST contain identical values and their
  representation SHOULD also be identical.

- Each linear ring MUST follow the right-hand rule with respect to the area it
  bounds, so exterior rings must be counterclockwise and holes are clockwise.

- For Polygons with more than one of these rings, the first MUST be the exterior
  ring, and any others MUST be interior rings.  The exterior ring bounds the surface,
  and the interior rings (if any) bound holes within the surface.
// Polygon
{
  'type': 'Polygon',
  'coordinates': [
    [ [ 0.0, 0.0 ], [ 2000.0, 0.0 ], [ 2000.0, 1000.0 ], [ 0.0, 1000.0 ] ],
    [ [ 500.0, 250.0 ], [ 500.0, 750.0 ], [ 1500.0, 750.0 ], [ 1500.0, 250.0 ] ]
  ]
}
// MultiPolygon
{
  'type': 'MultiPolygon',
  'coordinates': [
    [
      [ [ 0.0, 0.0 ], [ 2000.0, 0.0 ], [ 2000.0, 1000.0 ], [ 0.0, 1000.0 ] ],
      [ [ 500.0, 250.0 ], [ 500.0, 750.0 ], [ 1500.0, 750.0 ], [ 1500.0, 250.0 ] ]
    ],
    [
      [ [ 2500.0, 250.0 ], [ 4500.0, 250.0 ], [ 4500.0, 750.0 ], [ 2500.0, 750.0 ] ]
    ]
  ]
}

toJSON( [data])

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

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

Parameters:
Name Type Argument Description
data object <optional>

An optional parent object to append this data to.
Inherited From:
Overrides:
Returns:

Returns a Plain Old Javascript Object (POJO).

Type
object
Example
// Overriding this method.

class MyPath extends BIM.Path {
     /// ...
     toJSON(data) {

         data = super.toJSON(data);

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

     };
     /// ...
 };

translateInNormalDirection(distance)

Move all vertices by the given distance in the plane normal direction.

Parameters:
Name Type Description
distance number

The distance to move.
Inherited From:
Overrides:
Returns:

Returns this polyline to support method chaining.

Type
PD.Polyline

trimContourPointCount(contourIndex, count)

Trims the number of points in the contour at the given index.

If the given contour index is negative, it is treated as an offset from the end of the array, such that -1 is always the last contour.

You can only trim a contour to less points than it currently has, so the count value must be less than the contour array size.

Parameters:
Name Type Description
contourIndex number

The numeric index of the required contour in the contours array.
count number

The new number of points in contours array.
Inherited From:
Overrides:
Returns:

Returns the new number of points in the contour.

Type
number

unifyOrientation( [update])

Checks the direction of the surface normal and reverses each contour.

Parameters:
Name Type Argument Description
update boolean <optional>

When true, the path will update when changed, defaults to false.
Inherited From:
Overrides:
Returns:

Returns this polyline to support method chaining.

Type
PD.Polyline

updateConnections()

Updates the inter-connections between path points and their path properties.

This method links each path point's prev and next properties to the previous and next path point in the path, computes their distances, direction/normal vectors and a angles, and checks for convexity/concavity.

Inherited From:
Overrides:
Returns:

Returns this path to support method chaining.

Type
PD.Path

updateVirtualJunction(virtualJunction)

Checks the position of a virtual junction compared to its linked junction.

If the linked junction is no longer coincident with the path segment, the virtual junction will be removed from the path. If the linked junction has moved but is still coincident, the virtual junction will be updated to match its new position.

Parameters:
Name Type Description
virtualJunction BIM.Junction

The virtual junction to update.
Returns:

Returns true if the virtual junction position moved.

Type
boolean

updateVirtualJunctions(kdTree)

Updates or removes any virtual junction from the path if they are no longer connected to their tracking junction.

Parameters:
Name Type Description
kdTree PD.Path.KDTreeXY

A KDTree of path junctions in the level.

validateContours()

Ensures all points in each path contour are of type BIM.Junction.

This methods replaces any THREE.Vector3 or PD.Point objects with BIM.Junction objects, and must be done as a separate process before the underlying polyline is updated and junction properties are (re)computed.

For junctions that have their own wallConstruction property, or who belong to elements that have a wallConstruction property, this method also updates their inner and outer offset values to match the construction.

Inherited From:
Overrides:
Returns:

Returns this path to support method chaining.

Type
BIM.Path

convertToJunctions(contours) <static>

Ensures that an array of contours contains only junctions.

This methods replaces any THREE.Vector3 or PD.Point objects with BIM.Junction objects.

Parameters:
Name Type Description
contours Array

An array of one or more contours containing at least two points.
Returns:

Returns the contour array updated with junctions.

Type
Array

enableSelection(selectionManager) <static>

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

This method will create a new selection handler for paths and assigns it to BIM.Path.Selection.

Parameters:
Name Type Description
selectionManager PD.SelectionManager

The selection manager to connect to.