API Docs

Class: Clipper

PD. Clipper

new Clipper()

An interface to the ClipperLib polygon clipping library.

Author:
  • drajmarsh

Classes

Cache
Shape

Members

:ClipperLib.PolyFillType

defaultFill <static>

Stores a default fill type to use, initially ClipperLib.PolyFillType.pftNonZero.

Type
  • ClipperLib.PolyFillType

Methods

copyClipPathToPolyMesh(mesh, path [, Z]) <static>

Adds a clipper path in the XY plane as an outline to the given mesh.

Parameters:
Name Type Argument Description
mesh PD.PolyMesh

The mesh to add the path to.
path Array

The 2D Clipper path or paths to add.
Z number <optional>

The height of the path ijn the Z axis, defaults to zero.

createPathFromPointsByAxis(vertices [, axis] [, clipPath]) <static>

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.

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

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

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

createPathFromVectorArraysByAxis(vertices [, axis] [, clipPath]) <static>

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.

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

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

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

createPathWithOrientation(vertices [, axis] [, clipPath]) <static>

Converts an array of points to a 2D ClipperLib.Path and returns the orientation.

This method uses the signed area to determine the orientation of the path.

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

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

The cartesian axis to use when converting, defaults to the Z axis.
clipPath Array.<PD.ClipPt2D> <optional>

The array to receive the clipper points.
Returns:

Returns the orientation of the clipper path.

Type
boolean

dispose() <static>

Releases the shared polygon clipper and offsetter so they can be garbage collected.

Only call this method if you are sure your application has finished using polygon clipping and offsetting for some time. It is safe to reuse the same clipper object any number of times, so you should avoid disposing and recreating the the clipper over and over again. If you call the startClip() method after calling this method, a new clipper will be generated and cached.

intersectShapes(clipShape, subjShape, fill) <static>

Computes the intersection of two shapes.

Parameters:
Name Type Description
clipShape PD.Clipper.Shape | Array

The clip shape or array.
subjShape PD.Clipper.Shape | Array

The subject shape or array.
fill ClipperLib.PolyFillType

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

Returns resulting the intersection paths.

Type
Array

reusePathContour(clippath, contour) <static>

Converts a polyline contour and attempts to reuse a 2D ClipperLib.Path.

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.

Parameters:
Name Type Description
clippath Array

The reusable previously generated ClipperLib Path.
contour Array

The contour as an array of 3D points.
Returns:

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

Type
Array

startClip() <static>

Resets and retrieves the shared polygon clipping tool.

This method is typically the first method called when performing polygon clipping operations. It creates a shared ClipperLib.Clipper instance that can be used to add, subtract or intersect multiple 2D polygons. Only a single instance is ever created and is cleared and reused in all subsequent calls.

Returns:

Returns the polygon clipping calculator.

Type
ClipperLib.Clipper

startOffset( [miterLimit] [, arcTolerance]) <static>

Resets and retrieves the shared polygon offset tool.

This method is typically the first method called when performing polygon offset operations. It creates a shared ClipperLib.ClipperOffset instance that can be used to offset/inset multiple 2D polygons. Only a single instance is ever created and is cleared and reused in all subsequent calls.

Parameters:
Name Type Argument Description
miterLimit number <optional>

Sets the limit for paths where JoinType is jtMiter, defaults to 2,
arcTolerance number <optional>

Sets the rounding increment for paths where JoinType is jtRound or when EndType is etOpenRound, defaults to 1.
Returns:

Returns the polygon offset calculator.

Type
ClipperLib.ClipperOffset

subtractShapes(clipShape, subjShape, fill) <static>

Subtracts the clip shape from the subject shape.

Parameters:
Name Type Description
clipShape PD.Clipper.Shape | Array

The clip shape or array.
subjShape PD.Clipper.Shape | Array

The subject shape or array.
fill ClipperLib.PolyFillType

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

Returns resulting the intersection paths.

Type
Array

toPolygonContoursByAxis(paths, shell [, axis] [, W]) <static>

Converts a 2D ClipperLib path to 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 Description
paths Array | PolyTree

An array of ClipperLib paths, or a single path.
shell PD.Shell

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

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

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 THREE.Vector3 points.

Type
Array

toPolygonContoursByPlaneNormal(path, plane [, shell]) <static>

Converts a 2D ClipperLib path to 3D contours suitable for polylines/facets.

As ClipperLib works with 2D {X,Y} objects, each 2D point must be projected from the 2D XY plane onto the given plane. This method uses a quaternion to rotate from the Z-axis to the plane normal.

This means that, unless the plane is normal to one of the three cartesian axis, its shape in plan view or elevation will be skewed by the angle of the plane. To project onto a plane whilst maintaining its shape in one of the cartesian axis, use the toPolygonContoursByPlaneAxis() method instead.

Parameters:
Name Type Argument Description
path Array

An array of two or more ClipperPath points.
plane THREE.Plane

The plane to project the ClipperPath points back onto.
shell PD.Shell <optional>

An optional shell to reuse vertices and facets from.
Returns:

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

Type
Array

toPolygonContoursXY(path, shell [, Z]) <static>

Converts a 2D ClipperLib path to 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 Description
path Array

An array of two or more ClipperPath points.
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 THREE.Vector3 points.

Type
Array

toPolygonsByPlaneAxis(paths, plane, axis [, shell]) <static>

Converts a 2D ClipperLib path to 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 XY plane. This method uses the plane equation specified to determine the most suitable cartesian axis to use. You can optionally specify the axis in which to project the points onto the plane, but using the plane equation itself is usually best.

In order to maintain axial positions and dimensions, each point is projected onto the plane along the selected axis rather than using the plane's normal. This is so that, for example, a circular arc created in plan view but projected onto a sloped plane still remains a circular arc when viewed in plane. Similarly, an arched window drawn in elevation should remain an arched window when viewed from the same elevation.

To project directly onto a plane, use the toPolygonContoursByPlaneNormal() method instead.

Parameters:
Name Type Argument Description
paths Array | PolyTree

An array of ClipperLib paths, or a single path.
plane THREE.Plane

The plane to project 3D points back onto.
axis PD.AXIS

The axis to use, default is to compute from plane.
shell PD.Shell <optional>

An optional shell to reuse vertices and facets from.
Returns:

Returns an array of one or more polygons.

Type
Array

unionShapes(shapes, fill) <static>

Unions a set of shapes together.

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

An array of shapes to union together.
fill ClipperLib.PolyFillType

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

Returns resulting the unioned paths.

Type
Array