API Docs

Class: Shape

PD.Clipper. Shape

A class for creating and manipulating complex ClipperLib shapes.

This class can also be used as a simple 2D clipper point cache without using any of the shape creation methods.

A ClipperLib shape is simply a collection of 2D paths. A path is simply an array of {X,Y} objects that define the 2D position of each corner in a closed line.

The nature of a shape is defined by the orientation of each path within it. All path's with a positive orientation represent filled areas and are referred to as a Boundary. All paths with a negative orientation represent unfilled holes within the filled areas and are referred to as a Hole.

ClipperLib shapes also maintain their own reusable point cache so that they can be efficiently reused.

The aim of this class is to make working with 2D boolean operations a little easier and more obvious than working with ClipperLib directly.

3D/2D Conversion

As ClipperLib works with 2D {X,Y} objects, all 3D paths must be projected onto a 2D plane. The methods in this class use axis-based conversion rather than plane-based conversions. This means that the 3D points within a path are projected using one of the three primary X, Y or Z cartesian axis. The axis of largest surface exposure is best for this purpose, which is calculated automatically for all polylines/polygons, and can be computed for any plane using the PD.Utils.computeMajorAxis() method.

The benefit of this approach is that all paths projected using the same cartesian axis share the same local coordinate space, so can be unioned, subtracted or differenced directly and the results projected back onto another plan in that axis. Whilst there may be some slight skewing of points if the 3D path does not align exactly with any of the primary cartesian axis, this is limited to a maximum difference of around 0.7071 which has no material impact on overall numerical accuracy.

Axis vs Plane Equation

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 different paths have different plane equations, or their points are not all exactly co-planar, then they will not share exactly the same local coordinate space, resulting in cumulative inaccuracies that can build up over multiple conversions, far more than with axis-based conversion.

new Shape()

Author:
  • drajmarsh

Extends

Methods

addBoundary2D(clipPath)

Add a new 2D boundary path to the shape.

This method ensures that the orientation of each 2D path is always positive to represent a filled area within the shape.

Parameters:
Name Type Description
clipPath Array.<PD.ClipPt2D> | Array.<Array.<PD.ClipPt2D>>

One or more arrays of 2D {X,Y} ClipperLib points.
Returns:

Returns true if path was valid and added.

Type
boolean

addBoundaryContour3D(vertices [, axis])

Add a new 2D boundary path using the array of 3D points.

This method ensures that the orientation of the resulting 2D path is always positive to represent a filled area within the shape.

As ClipperLib works with 2D {X,Y} objects, 3D points must be translated into a 2D cartesian plane. This method uses the given cartesian axis. If no axis is given, the X and Y components of the 3D points will be used.

Parameters:
Name Type Argument Default Description
vertices Array.<PD.Point>

An array of 3D points.
axis PD.AXIS <optional>
 0

An optional axis to project 2D points onto, defaults to Z axis.
Returns:

Returns an array of {X,Y} ClipperLib points.

Type
Array

addHole2D(clipPath)

Add a new 2D internal hole path to the shape.

This method ensures that the orientation of each 2D path is always negative to represent an unfilled hole within the shape.

Parameters:
Name Type Description
clipPath Array.<PD.ClipPt2D> | Array.<Array.<PD.ClipPt2D>>

One or more arrays of 2D {X,Y} ClipperLib points.
Returns:

Returns true if path was valid and added.

Type
boolean

addHoleContour3D(vertices [, axis])

Add a new 2D internal hole path using the array of 3D points.

This method ensures that the orientation of the resulting 2D path is always negative to represent an unfilled hole within the shape.

As ClipperLib works with 2D {X,Y} objects, 3D points must be translated into a 2D cartesian plane. This method uses the given cartesian axis. If no axis is given, the X and Y components of the 3D points will be used.

Parameters:
Name Type Argument Default Description
vertices Array.<PD.Point>

An array of 3D points.
axis PD.AXIS <optional>
 0

An optional axis to project 2D points onto, defaults to Z axis.
Returns:

Returns an array of {X,Y} ClipperLib points.

Type
Array

addIndexedPoint(X, Y)

Reuses a cached ClipperLib point or creates a new one.

Parameters:
Name Type Description
X number

The 2D X-axis component.
Y number

The 2D Y-axis component.
Inherited From:
Returns:

Returns a {X,Y} ClipperLib point.

Type
object

addOffsetPath(clipPath, offset [, joinType] [, endType])

Adds new path(s) to the shape that are offset from the given path(s).

Parameters:
Name Type Argument Description
clipPath Array.<PD.ClipPt2D> | Array.<Array.<PD.ClipPt2D>>

One or more arrays of 2D {X,Y} ClipperLib points.
offset number

The offset distance in model units (typically mm).
joinType ClipperLib.JoinType <optional>

The type of join to use at connections, defaults to jtMiter.
endType ClipperLib.EndType <optional>

The type of end to use for open paths, defaults to etClosedPolygon.
Returns:

Returns true if the offset worked and the new path added.

Type
boolean

addPaths(clipPath)

Add one or more raw 2D path(s) to the shape.

This method does no processing or orientation checking before adding the path(s), so only use this method if you are sure of the orientation and validity of each 2D path.

Parameters:
Name Type Description
clipPath Array.<PD.ClipPt2D> | Array.<Array.<PD.ClipPt2D>>

One or more arrays of 2D {X,Y} ClipperLib points.
Returns:

Returns true if path was valid and added.

Type
boolean

addPoint()

Reuses a cached ClipperLib point or creates a new one.

Inherited From:
Returns:

Returns a {X,Y} ClipperLib point.

Type
object

addPoint2D(X, Y)

Reuses a cached ClipperLib point or creates a new one.

Parameters:
Name Type Description
X number

The 2D X-axis component.
Y number

The 2D Y-axis component.
Inherited From:
Returns:

Returns a {X,Y} ClipperLib point.

Type
object

addPointXY(pt3D)

Gets the next cached point and sets it to using X and Y axis components.

Parameters:
Name Type Description
pt3D PD.Point

The 3D {x,y,z} point to add to the cache.
Inherited From:
Returns:

Returns a {X,Y} ClipperLib point.

Type
object

addPointXZ(pt3D)

Gets the next cached point and sets it to using X and Z axis components.

Parameters:
Name Type Description
pt3D PD.Point

The 3D {x,y,z} point to add to the cache.
Inherited From:
Returns:

Returns a {X,Y} ClipperLib point.

Type
object

addPointYZ(pt3D)

Gets the next cached point and sets it to using Y and Z axis components.

Parameters:
Name Type Description
pt3D PD.Point

The 3D {x,y,z} point to add to the cache.
Inherited From:
Returns:

Returns a {X,Y} ClipperLib point.

Type
object

addPolyline3D(polyline [, axis])

Adds boundaries and holes from a 3D polyline.

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

Parameters:
Name Type Argument Description
polyline PD.Polyline

A closed polyline or polygon.
axis PD.AXIS <optional>

An optional axis to project 2D points onto, defaults to polyline's axis.
Returns:

Returns an array of paths containing {X,Y} ClipperLib points.

Type
Array.<Array>

cleanPaths( [tolerance])

Remove duplicate vertices from all the paths within this shape.

This method removes points that are within the specified 'tolerance' distance of their preceding point in the path. The default distance is 1.5mm so that it supports geometric accuracy down to the nearest millimeter.

Parameters:
Name Type Argument Description
tolerance number <optional>

The tolerance for coincident and colinear points, defaults to 1.5mm.
Returns:

Returns true if the union worked and this shape was updated.

Type
boolean

clear()

Clears the shape and all the cached memory it currently stores.

Inherited From:
Overrides:
Returns:

Returns this instance to support method chaining.

Type
PD.Clipper.Shape

clonePathsFrom(shape)

Replaces the path contours in this shape with those in the given shape.

Parameters:
Name Type Description
shape PD.Clipper.Shape

The shape to copy path contours from.
Returns:

Returns the copied path contours.

Type
Array.<Array.<PD.ClipPt2D>>

computeSurfaceArea()

Calculates the surface area of the shape in metres squared (m2).

Returns:

Returns the calculates surface area in m2.

Type
number

createPathByAxisAndGetOrientation(vertices [, axis] [, clipPath])

Converts an array of points to a ClipperLib path.

This method uses the signed area to determine the orientation of the resulting 2D path. As this method returns the orientation, the path argument is required, and must be an array that will be filled with 2D points.

NOTE: This method only creates a 2D path and does not add it to the shape. To both create and add paths to the shape, use the addBoundaryContour3D(), addHoleContour3D(), and addPolyline3D() methods.

Parameters:
Name Type Argument Description
vertices Array.<PD.Point>

An array of 3D PD.Point objects.
axis PD.AXIS <optional>

An optional axis to project 2D points onto, defaults to Z axis.
clipPath Array.<PD.ClipPt2D> <optional>

An array to receive the clipper points.
Inherited From:
Returns:

Returns true if anti-clockwise oriented, false if clockwise.

Type
number

createPathFromPointsByAxis(vertices [, axis] [, clipPath])

Converts a polyline contour to a 2D ClipperLib.Path array.

As ClipperLib works with 2D {X,Y} objects, the 3D polyline contour must be translated into a 2D cartesian plane. This method uses the given cartesian axis. If no axis is given, the X and Y components of the 3D points are used.

If an array to receive the new path is provided, it will be reset to contain the converted 2D points. If not, a new array will be created and returned.

NOTE: This method only creates a 2D path and does not add it to the shape. To both create and add paths to the shape, use the addBoundaryContour3D(), addHoleContour3D(), and addPolyline3D() methods.

Parameters:
Name Type Argument Default Description
vertices Array.<PD.Point>

An array of 3D points.
axis PD.AXIS <optional>
 0

An optional axis to project 2D points onto, defaults to Z axis.
clipPath Array.<PD.ClipPt2D> <optional>

An optional path to receive the 2D clip points.
Inherited From:
Returns:

Returns the given path array filled with {X,Y} ClipperLib points, of a newly created array.

Type
Array

createPathFromPointsXY(vertices [, clipPath])

Converts 3D points to a 2D ClipperLib.Path array in the XY plane.

This method uses the X and Y components of the given points to generate an array of 2D {X,Y} objects. If an array to receive the new path is provided, it will be reset to contain the converted 2D points. If not, a new array will be created and returned.

NOTE: This method only creates a 2D path and does not add it to the shape. To both create and add paths to the shape, use the addBoundaryContour3D(), addHoleContour3D(), and addPolyline3D() methods.

Parameters:
Name Type Argument Description
vertices Array.<PD.Point>

An array of 3D points.
clipPath Array.<PD.ClipPt2D> <optional>

An optional path to receive the 2D points.
Inherited From:
Returns:

Returns the given path array filled with {X,Y} ClipperLib points, of a newly created one.

Type
Array

createPathFromVectorArraysByAxis(vertices [, axis] [, clipPath])

Converts a contour of [x,y,z] vector arrays to a 2D ClipperLib.Path array.

As ClipperLib works with 2D {X,Y} objects, the 3D polyline must be translated into a 2D cartesian plane. This method uses the given cartesian axis. If no axis is given, the X and Y components of the 3D [x,y,z] vector arrays are used.

If an array to receive the new path is provided, it will be reset to contain the converted 2D points. If not, a new array will be created and returned.

NOTE: This method only creates a 2D path and does not add it to the shape.

Parameters:
Name Type Argument Default Description
vertices Array.<Array.<number>>

An array of 3D [x,y,z] vector arrays.
axis PD.AXIS <optional>
 0

An optional axis to project 2D points onto, defaults to Z axis.
clipPath Array.<PD.ClipPt2D> <optional>

An optional path to receive the 2D clip points.
Inherited From:
Returns:

Returns the given path array filled with {X,Y} ClipperLib points, of a newly created array.

Type
Array

createPathsFromPolylineByAxis(polyline [, axis])

Converts a polyline into a series of 2D ClipperLib.Path arrays.

This method uses the polyline's axis of greatest surface exposure. If the polyline is also a polygon, the orientation of any holes in it will have the opposite orientation to the boundary.

NOTE: If calling this method from a PD.Clipper.Shape instance, it is important to note that it only creates 2D paths and does not add them to the shape. To both create and add paths to the shape, use the PD.Clipper.Shape#addBoundaryContour3D, PD.Clipper.Shape#addHoleContour3D and/or PD.Clipper.Shape#addPolyline3D methods.

Parameters:
Name Type Argument Description
polyline PD.Polyline

The polyline to generate pats for.
axis PD.AXIS <optional>

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

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

Type
Array

getCacheSize()

Retrieves the number of entries in the point cache.

Inherited From:
Returns:

Returns the point cache size.

Type
number

getNextPointIndex()

Retrieve the index of the next available point in the cache.

Inherited From:
Returns:

Returns the current next point index.

Type
number

getPath()

Retrieves a path contour within the shape.

Returns:

Returns the path contour.

Type
Array

getPathCount()

Retrieves the number of path contours in the shape.

Returns:

Returns the point cache size.

Type
number

getPathList()

Retrieves the array of path contours in the shape.

Returns:

Returns the point cache size.

Type
Array.<Array.<PD.ClipPt2D>>

hasContent()

Checks if the shape has any path data.

Returns:

Returns true if the shape has content.

Type
boolean

intersectWith(shape [, fill])

Computes the intersection of this with the given shape.

Parameters:
Name Type Argument Description
shape PD.Clipper.Shape | Array

The shape or path array to intersect with.
fill ClipperLib.PolyFillType <optional>

The fill type to use, defaults to PD.Clipper.defaultFill.
Returns:

Returns true if the intersection worked and this shape was updated.

Type
boolean

resetPaths()

Resets the path cache to begin reusing it.

As this just clears the path list and leaves the cached points,

Returns:

Returns this instance to support method chaining.

Type
PD.Clipper.Shape

reuseEnd()

Finalises the shape.

This method must be called after you have first called reuseStart() to reset the reusable index. Its role is to trim any excessive leftover data that has not been reused.

Inherited From:
Returns:

Returns this instance to support method chaining.

Type
PD.Clipper.Cache

reuseStart()

Resets the path and point cache to begin reusing them.

NOTE: This is a full reset that starts reusing everything. However, there are some applications where you may want to retain the point cache but reuse the path list. This can be done by calling the resetPaths() method one or more times between calls to the start and end methods.

Inherited From:
Overrides:
Returns:

Returns this instance to support method chaining.

Type
PD.Clipper.Shape

reverse()

Reverse the orientation of the shape.

This method reverses the direction of each path in the path list.

Returns:

Returns this instance to support method chaining.

Type
PD.Clipper.Shape

setCacheSize(new_size)

Sets the size of the point cache to the given number of entries.

Parameters:
Name Type Description
new_size number

The new size of the cache.
Inherited From:
Returns:

Returns this instance to support method chaining.

Type
PD.Clipper.Cache

setNextPointIndex(index)

Sets the index of the next available point in the cache.

This method is only for use when generating volatile clipping paths. This means that each new path is created, clipped and converted to something else all within the same function (or sub-functions), and not stored or referenced anywhere else at any other time.

To prevent the cache from persisting the points associated with these volatile shapes, you can use PD.Clipper.Cache#getNextPointIndex to store the current index just before you create each new path and, once you have used it and it is no longer required, call this method with the stored value to reset the index.

It is highly recommended that you store and reset indexes after processing individual paths as this will prevent the cache from growing excessively large. However, you need to be very careful when using this method as any cached points after the given index will be reused and their values overwritten.

Thus, if you create a volatile subject path and three volatile clip paths, and then subtract them, you cannot reset the index until the entire process is complete and all four paths are no longer needed or referenced. If you reset the index after creating each path, they will actually share the same points from the cache, and the last path created will set the values of points used by each of the other shapes as well as its own. As a result, any subtraction or other process will produce garbage values. In this case, you would store the index just before creating each of the paths, perform the subtraction, generate whatever geometry you need from the results, and then reset the index.

Parameters:
Name Type Description
index number

The new index within the cache.
Inherited From:
Returns:

Returns this instance to support method chaining.

Type
PD.Clipper.Cache

subtract(shape [, fill])

Subtracts the given shape from this shape.

Parameters:
Name Type Argument Description
shape PD.Clipper.Shape | Array

The shape or path array to subtract.
fill ClipperLib.PolyFillType <optional>

The fill type to use, defaults to PD.Clipper.defaultFill.
Returns:

Returns true if the subtraction worked and this shape was updated.

Type
boolean

subtractPaths(index [, fill])

Unions all the paths inside this shape into common outline(s).

Parameters:
Name Type Argument Description
index number

The index of the path to subtract from, defaults to zero.
fill ClipperLib.PolyFillType <optional>

The fill type to use, defaults to PD.Clipper.defaultFill.
Returns:

Returns true if the union worked and this shape was updated.

Type
boolean

toPolygonContoursByAxis(shell [, axis] [, W])

Converts the shape to one or more 3D contours suitable for polylines/facets.

As ClipperLib works with 2D {X,Y} objects, each 2D point must be projected into 3D from the 2D cartesian plane. This method uses a straight cartesian projection in the given axis at the given offset. If no axis is given, the Z-axis (XY plane) is used.

Parameters:
Name Type Argument Default Description
shell PD.Shell

The shell to reuse 3D vertices from.
axis PD.AXIS <optional>
 0

An optional axis in which to project 2D point, defaults to Z-axis.
W number <optional>
 0

An optional position of the path in the given axis, defaults to zero.
Returns:

Returns an array of one or more closed contours, each containing three or more points.

Type
Array.<PD.Point>

toPolygonContoursXY(shell [, Z])

Converts the shape to one or more 3D contours suitable for polylines/facets.

As ClipperLib works with 2D {X,Y} objects, each 2D point must be projected into 3D from the 2D cartesian plane. This method uses a straight cartesian projection in the Z-axis at the given offset.

Parameters:
Name Type Argument Description
shell PD.Shell

The shell to reuse 3D vertices from.
Z number <optional>

An optional position of the path in the Z axis, defaults to zero.
Returns:

Returns an array of one or more closed contours, each containing three or more points.

Type
Array.<PD.Point>

toShellFacets(shell [, axis] [, W] [, flip])

Converts the shape to one or more 3D polygonal facets in the shell.

As ClipperLib works with 2D {X,Y} objects, each 2D point must be projected into 3D from the 2D cartesian plane. This method uses a straight cartesian projection in the given axis at the given offset. If no axis is given, the Z-axis (XY plane) is used.

Parameters:
Name Type Argument Default Description
shell PD.Shell

The shell to reuse 3D vertices from.
axis PD.AXIS <optional>
 0

An optional axis in which to project 2D point, defaults to Z-axis.
W number <optional>
 0

An optional position of the path in the given axis, defaults to zero.
flip boolean <optional>
 false

Whether or not to reverse the surface normal direction of facets.
Returns:

Returns an array of newly created facets.

Type
Array.<PD.Polygon>

union( [fill])

Unions the boundary paths in this shape.

Parameters:
Name Type Argument Description
fill ClipperLib.PolyFillType <optional>

The fill type to use, defaults to PD.Clipper.defaultFill.
Returns:

Returns true if the union worked and this shape was updated.

Type
boolean

unionPaths( [fill])

Unions all the paths inside this shape into common outline(s).

Parameters:
Name Type Argument Description
fill ClipperLib.PolyFillType <optional>

The fill type to use, defaults to PD.Clipper.defaultFill.
Returns:

Returns true if the union worked and this shape was updated.

Type
boolean

unionWith(shapes [, fill])

Unions this shape with the given shape(s).

Parameters:
Name Type Argument Description
shapes Array.<PD.Clipper.Shape> | PD.Clipper.Shape

An array of shapes to union with this shape.
fill ClipperLib.PolyFillType <optional>

The fill type to use, defaults to PD.Clipper.defaultFill.
Returns:

Returns true if the union worked and this shape was updated.

Type
boolean

useIndexer( [decimals])

Instructs the cache to use an indexer to generate unique points at each coincident position.

After calling this method, any points added to the cache using the addIndexedPoint() method will be stored by a PD.Indexer and any subsequent point with the same coordinates (within a tolerance given by decimals) will be reused rather than creating a new point.

This is useful for both reducing the number of points in the cache and for ensuring that the edges of paths line up exactly.

Parameters:
Name Type Argument Default Description
decimals number <optional>
 1

The number of decimal places when comparing coordinates, defaults to 1 (0.1mm).
Inherited From:
Returns:

Returns this instance to support method chaining.

Type
PD.Clipper.Cache