API Docs

Class: Polygon

PD. Polygon

Defines a closed 3D polygon.

This is a simple subclass of PD.Polyline that is always closed and polygonal. Polygons are typically flat and coplanar by default, but do not have to be so. Their structure allows for curved surfaces just as easily as flat ones, however curved surfaces must rely on an external engine to tesselate their surface triangles whereas flat planar triangles are handled automatically.

new Polygon( [config])

Creates a new 3D polygon.

Parameters:
Name Type Argument Description
config object <optional>

An optional configuration object.
Properties of config:
Name Type Argument Description
contours Array <optional>

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

A color to use when rendering the line.
fillColor THREE.Color <optional>

A color to use when rendering a polygon surface.
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.
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 THREE.Vector3 <optional>

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

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

Whether or not a polygon should be rectilinear when possible, defaults to false.
facetType PD.FACET <optional>

The role that this polygon plays within a shell.
Author:
  • drajmarsh

Extends

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

extents

The maximum and minimum extents of all contours.

Type
  • THREE.Box3
Inherited From:
Overrides:
:PD.FACET

facetType

The role that this polygon plays, typically within a shell.

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

isChanging

Whether or not the polygon is being interactively edited.

Type
  • boolean
Inherited From:
Overrides:
:boolean

isClosed <readonly>

Polygons are always closed so this will always be true.

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

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 <readonly>

A flag identifying this object as a polygon.

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:

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

asQuad(v1, v2, v3, v4 [, normal])

Provides a fast way of creating a simply quadrilateral polygon.

Polygon can be of any shape and contain any number of internal holes. This flexibility requires tests, checks and sometimes complex calculations to triangulate its surface and compute an appropriate surface normal.

However, PD.Shell objects sometimes just need to add a large number of simple triangles and quads to form a complex 3D form. This method offers a fast way of reusing existing polygons for that purpose by completely defining and resolving the polygon so that no further tests, checks or calculations are required.

Parameters:
Name Type Argument Description
v1 THREE.Vector3

The first quad point, in model coordinates.
v2 THREE.Vector3

The second quad point, in model coordinates.
v3 THREE.Vector3

The third quad point, in model coordinates.
v4 THREE.Vector3

The fourth quad point, in model coordinates.
normal THREE.Vector3 <optional>

An optional normalised direction vector.
Returns:

Returns this polygon to support method chaining.

Type
PD.Polygon

asTriangle(v1, v2, v3 [, normal])

Provides a fast way of creating a simple triangular polygon.

Polygon can be of any shape and contain any number of internal holes. This flexibility requires tests, checks and sometimes complex calculations to triangulate its surface and compute an appropriate surface normal.

However, PD.Shell objects sometimes just need to add a large number of simple triangles and quads to form a complex 3D form. This method offers a fast way of reusing existing polygons for that purpose by completely defining and resolving the polygon so that no further tests, checks or calculations are required.

Parameters:
Name Type Argument Description
v1 THREE.Vector3

The first triangle point, in model coordinates.
v2 THREE.Vector3

The second triangle point, in model coordinates.
v3 THREE.Vector3

The third triangle point, in model coordinates.
normal THREE.Vector3 <optional>

An optional normalised direction vector.
Returns:

Returns this polygon to support method chaining.

Type
PD.Polygon

asTriangleFan(vertices)

Provides a fast way of creating a simple triangular fan polygon.

Polygon can be of any shape and contain any number of internal holes. This flexibility requires tests, checks and sometimes complex calculations to triangulate its surface and compute an appropriate surface normal.

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

However, PD.Shell objects sometimes just need to add a large number of simple triangles and quads to form a complex 3D form. This method offers a fast way of reusing existing polygons for that purpose by completely defining and resolving the polygon so that no further tests, checks or calculations are required.

Parameters:
Name Type Description
vertices Array.<THREE.Vector3>

An array of ordered convex vertices, in model coordinates.
Returns:

Returns this polygon to support method chaining.

Type
PD.Polygon

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

clearContours()

Removes all existing contours within the polyline.

Inherited From:
Overrides:
Returns:

Returns this polyline to support method chaining.

Type
PD.Polyline

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

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

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 [, 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:
Overrides:
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;

     };
     /// ...
 };

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>

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

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

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

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

setFacetType(type)

Sets the facet type value for this polygon.

Because it returns the polygon itself, this method can be useful when you want to set the facet type on a newly created facet and maybe add it to an array or further process it without specifically assigning it to a variable.

Parameters:
Name Type Description
type PD.FACET

The type to assign the facet.
Returns:

Returns this polygon to support method chaining.

Type
PD.Polygon
Example
const facets = [];
for (const contour of polyList) {
    facets.push(shell.addFacet(contour, PD.REVERSE).setFacetType(PD.FACET.JAMB));
}

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

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

update( [forceUpdate])

Checks for changes and finalises the polyline ready for rendering.

For a polygon, this will update its normal and axis value.

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

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

newExtrudedPoint(vertex, vector) <static>

Create a new extruded vertex.

Parameters:
Name Type Description
vertex PD.Point

The base vertex to extrude.
vector THREE.Vector3

The extrusion vector.
Returns:

Returns a new extruded vertex.

Type
PD.Point

reuseAsExtrudedCurve(polygon, contour, extrusion) <static>

Checks the given polygon is valid and can be reused.

Parameters:
Name Type Description
polygon PD.Polygon

The polygon to try to reuse.
contour Array

The contour to extrude the curve from.
extrusion THREE.Vector

The extrusion vector to apply to the contour.
Returns:

Returns the given polygon.

Type
PD.Polygon

reuseAsQuad(polygon, vtx1, vtx2, vtx3, vtx4) <static>

Reuses the given polygon as a 4-sided shape.

Parameters:
Name Type Description
polygon PD.Polygon

The polygon to reuse.
vtx1 PD.Point

The bottom-left vertex.
vtx2 PD.Point

The bottom-right vertex.
vtx3 PD.Point

The top-right vertex.
vtx4 PD.Point

The top-left vertex.
Returns:

Returns the given polygon or a newly created one.

Type
PD.Polygon

reuseOrAddContour(poly, index) <static>

Retrieves an existing contour from a polyline, or creates a new one.

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

Parameters:
Name Type Description
poly PD.Polyline

The polyline/polygon to reuse contours from.
index number

The ordinal index of the contour to add/reuse.
Returns:

Returns the existing contour or a newly created one.

Type
Array

reuseOrAddPoint(contour, index [, vertex]) <static>

Check to copy the given vertex to an existing vertex or a new one.

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

Parameters:
Name Type Argument Default Description
contour Array

The contour to add/reuse a vertex from.
index number

The ordinal index of the vertex to add/reuse.
vertex PD.Point <optional>
 null

An optional vertex to copy the position from.
Returns:

Returns the existing vertex or a newly created one.

Type
PD.Point

reuseOrAddPolygon(polygons, index) <static>

Check to reuse a polygon rather than create a new one.

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

Parameters:
Name Type Description
polygons Array

The list of polygons to choose from.
index number

The ordinal index of the polygon to reuse.
Returns:

Returns an existing polygon or a newly created one.

Type
PD.Polygon

selectFromList(polygons, selection) <static>

Intersects each polygon in the list with the given selection ray and returns the closest intersected polygon.

Parameters:
Name Type Description
polygons Array

The list of polygons to choose from.
selection PD.Selection

The interactive selection accumulator.
Returns:

Returns an intersected polygon, or null.

Type
PD.Polygon