API Docs

Class: Cache

PD.Clipper. Cache

A utility class for caching ClipperLib path points.

The aim of this class is to minimise new memory allocations when regenerating ClipperLib paths by reusing a cache of previously created 2D points. It can be used by elements that need to dynamically regenerate their footprint from a free-form path.

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 the 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 aligning 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 Cache()

Author:
  • drajmarsh

Methods

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

Returns a {X,Y} ClipperLib point.

Type
object

addPoint()

Reuses a cached ClipperLib point or creates a new one.

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

Returns a {X,Y} ClipperLib point.

Type
object

clear()

Clears the cache and all its allocated memory.

Returns:

Returns this instance to support method chaining.

Type
PD.Clipper.Cache

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

Returns:

Returns the point cache size.

Type
number

getNextPointIndex()

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

Returns:

Returns the current next point index.

Type
number

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.

Returns:

Returns this instance to support method chaining.

Type
PD.Clipper.Cache

reuseStart()

Resets the point cache to begin reusing them.

Returns:

Returns this instance to support method chaining.

Type
PD.Clipper.Cache

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

Returns this instance to support method chaining.

Type
PD.Clipper.Cache

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

Returns this instance to support method chaining.

Type
PD.Clipper.Cache