API Docs

Class: Path

PD. Path

Defines a path for quickly generating geometry.

A path is basically a sequence of points connected together by linear or curved segments. A PD.Path is different from a PD.Polyline in that all its vertices are PD.PathPoint objects (or a subclass) which store additional information about how to connect with previous and next path segments. This includes direct links to path points on either side, trigonometric data such as direction vectors, incoming and outgoing normals, up vectors and angles. It also allows for the definition of curved segments such as arcs, beziers and splines.

As this framework is an attempt to support the real-time generation of complex geometry as a user interactively drags or edits parametric data, having access to precomputed data such as angles, normals and cross-products greatly assists with this process and makes it much easier to generate offsets or insets.

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 path point will be automatically connected back to the first.

By default, the path points 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 path points. 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 PD.PathPoint instances directly. This allows the path to use a point cache or for subclasses to create their own point types to suit their needs.

new Path()

Author:
  • drajmarsh

Extends

Classes

KDTree3D
KDTreeXY

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

extents

The maximum and minimum extents of all contours.

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

fillColor

An optional color to use for the polygon surface.

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

isChanging

Whether or not the polygon is being interactively edited.

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

isConcave

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

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

isPath <readonly>

A flag identifying this object as a path.

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

isPolyline <readonly>

A flag identifying this object as a polyline.

Type
  • boolean
Inherited From:
:boolean

isRect

Whether or not the polygon is rectilinear.

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

showOutline

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

Type
  • boolean
Inherited From:
:boolean

showSurface

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

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

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:
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:
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:
Returns:

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

Type
number

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.
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:
Returns:

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

Type
boolean

clearContours()

Removes all existing contours within the polyline.

Inherited From:
Returns:

Returns this polyline to support method chaining.

Type
PD.Polyline

clone()

Creates and returns a deep copy of this path.

Returns:

Returns the new path.

Type
PD.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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
Returns:

Returns true if geometry was added to the mesh.

Type
boolean

createNewPathPoint()

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

If the path has a point cache, this method will retrieve the next point from the cache, otherwise it will create a new PD.PathPoint instance.

Subclasses should override this method to return a point of the appropriate type for their requirements. Subclasses may also wish to implement their own path point cache here if path contours are likely to be constantly changing size.

Returns:

Returns a new path point.

Type
PD.PathPoint

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:
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:
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:
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:
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:
Returns:

Returns a [contour,index] array.

Type
Array

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:
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:
Returns:

Returns this polyline to support method chaining.

Type
PD.Polyline

fromJSON(data [, no_contours])

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 Argument Description
data object

The source object containing data to copy.
no_contours boolean <optional>

An optional flag to allow a subclass to process contours, defaults to false.
Inherited From:
Returns:

Returns this polyline to support method chaining.

Type
PD.Polyline
Example
// Overriding this method.

class MyPolyline extends PD.Polyline {
     /// ...
     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;

     };
     /// ...
 };

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.
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.
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.
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.
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.
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:
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:
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:
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:
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:
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:
Returns:

Returns the contours array.

Type
Array.<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:
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:
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.
Returns:

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

Type
Array.<PD.Point>

hasContent()

Determines whether or not the polyline has valid content.

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

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

Type
boolean

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

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:
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:
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:
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:
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:
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:
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] [, no_contours])

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

This method is used to copy, store and save the data for a polyline, 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 Default Description
data object <optional>

An optional parent object to append this data to.
no_contours boolean <optional>
 false

An optional flag to allow a subclass to process contours, defaults to false.
Inherited From:
Returns:

Returns a Plain Old Javascript Object (POJO).

Type
object
Example
// Overriding this method.

class MyPolyline extends PD.Polyline {
     /// ...
     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:
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:
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:
Returns:

Returns this polyline to support method chaining.

Type
PD.Polyline

update( [forceUpdate])

Checks for changes and finalises the path ready for rendering.

This updates all the path point information as well as its plane equation, normal and

Parameters:
Name Type Argument Default Description
forceUpdate boolean <optional>
 false

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

Returns this path to support method chaining.

Type
PD.Path

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.

Returns:

Returns this path to support method chaining.

Type
PD.Path

validateContours()

Ensures all points in each path contour are of type PD.PathPoint.

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

Returns:

Returns this path to support method chaining.

Type
PD.Path

findNearestSegments_BruteForce(point, segments [, radius]) <static>

Finds the nearest segments to a given point within a specified radius.

This method searches for segments that are within a certain radius of a given point. It uses a simple distance check to filter out segments that are too far away.

Parameters:
Name Type Argument Description
point PD.PathPoint

The point to search for.
segments Array.<Segment>

The segments to search through.
radius number <optional>

The radius to search within, defaults to 5 model units.
Returns:

An array of segments that are within the radius of the point.

Type
Array.<Segment>