Class WeilerAthertonClipper

An implementation of the Weiler Atherton algorithm for clipping polygons. This currently only handles combinations that will not result in any holes. Support may be added for holes in the future.

This algorithm is faster than the Clipper library for this task because it relies on the unique properties of the circle, ellipse, or convex simple clip object. It is also more precise in that it uses the actual intersection points between the circle/ellipse and polygon, instead of relying on the polygon approximation of the circle/ellipse to find the intersection points.

For more explanation of the underlying algorithm, see: https://en.wikipedia.org/wiki/Weiler%E2%80%93Atherton_clipping_algorithm https://www.geeksforgeeks.org/weiler-atherton-polygon-clipping-algorithm https://h-educate.in/weiler-atherton-polygon-clipping-algorithm/

Constructors

constructor

Properties

polygon clipObject config CLIP_TYPES INTERSECTION_TYPES

Methods

#combineNoHoles #processIntersection #buildPointTrackingArray #buildIntersectionArray union intersect combine testForEnvelopment #consolidatePoints

Constructors

constructor

  • new WeilerAthertonClipper(polygon, clipObject, clipType, clipOpts): WeilerAthertonClipper

  • Construct a WeilerAthertonClipper instance used to perform the calculation.

    Parameters

    • polygon: Polygon

      Polygon to clip

    • clipObject: Rectangle | Circle

      Object used to clip the polygon

    • clipType: number

      Type of clip to use

    • clipOpts: object

      Object passed to the clippingObject methods toPolygon and pointsBetween

    Returns WeilerAthertonClipper

Properties

polygon

polygon: Polygon

clipObject

clipObject: Rectangle | Circle

config

config: object

Configuration settings

Param: config.clipType

One of CLIP_TYPES

Param: config.clipOpts

Object passed to the clippingObject methods toPolygon and pointsBetween

Static CLIP_TYPES

CLIP_TYPES: Readonly<{
    INTERSECT: 0;
    UNION: 1;
}> = ...

The supported clip types. Values are equivalent to those in ClipperLib.ClipType.

Type declaration

  • INTERSECT: 0
  • UNION: 1

Static INTERSECTION_TYPES

INTERSECTION_TYPES: Readonly<{
    OUT_IN: -1;
    IN_OUT: 1;
    TANGENT: 0;
}> = ...

The supported intersection types.

Type declaration

  • OUT_IN: -1
  • IN_OUT: 1
  • TANGENT: 0

Methods

Private #combineNoHoles

  • #combineNoHoles(trackingArray): [Polygon]

  • Clip the polygon with the clipObject, assuming no holes will be created. For a union or intersect with no holes, a single pass through the intersections will build the resulting union shape.

    Parameters

    • trackingArray: PolygonVertex[]

      Array of linked points and intersections

    Returns [Polygon]

Private #processIntersection

  • #processIntersection(ix, prevIx, wasTracingPolygon, newPoly): void

  • Given an intersection and the previous intersection, fill the points between the two intersections, in clockwise order.

    Parameters

    • ix: PolygonVertex

      Intersection to process

    • prevIx: PolygonVertex

      Previous intersection to process

    • wasTracingPolygon: boolean

      Whether we were tracing the polygon (true) or the clipObject (false).

    • newPoly: Polygon

      The new polygon that results from this clipping operation

    Returns void

Private #buildPointTrackingArray

  • #buildPointTrackingArray(): Point[]

  • Construct an array of intersections between the polygon and the clipping object. The intersections follow clockwise around the polygon. Round all intersections and polygon vertices to the nearest pixel (integer).

    Returns Point[]

Private #buildIntersectionArray

  • #buildIntersectionArray(): Point[]

  • Construct an array that holds all the points of the polygon with all the intersections with the clipObject inserted, in correct position moving clockwise. If an intersection and endpoint are nearly the same, prefer the intersection. Intersections are labeled with isIntersection and type = out/in or in/out. Tangents are removed.

    Returns Point[]

    Labeled array of points

Static union

  • union(polygon, clipObject, clipOpts?): Polygon[]

  • Union a polygon and clipObject using the Weiler Atherton algorithm.

    Parameters

    • polygon: Polygon

      Polygon to clip

    • clipObject: Rectangle | Circle

      Object to clip against the polygon

    • clipOpts: object = {}

      Options passed to the clipping object methods toPolygon and pointsBetween

    Returns Polygon[]

Static intersect

  • intersect(polygon, clipObject, clipOpts?): Polygon[]

  • Intersect a polygon and clipObject using the Weiler Atherton algorithm.

    Parameters

    • polygon: Polygon

      Polygon to clip

    • clipObject: Rectangle | Circle

      Object to clip against the polygon

    • clipOpts: object = {}

      Options passed to the clipping object methods toPolygon and pointsBetween

    Returns Polygon[]

Static combine

  • combine(polygon, clipObject, options?): Polygon[]

  • Clip a given clipObject using the Weiler-Atherton algorithm.

    At the moment, this will return a single PIXI.Polygon in the array unless clipType is a union and the polygon and clipObject do not overlap, in which case the [polygon, clipObject.toPolygon()] array will be returned. If this algorithm is expanded in the future to handle holes, an array of polygons may be returned.

    Parameters

    • polygon: Polygon

      Polygon to clip

    • clipObject: Rectangle | Circle

      Object to clip against the polygon

    • Optional options: {
          clipType: Readonly<{
              INTERSECT: 0;
              UNION: 1;
          }>;
          canMutate: boolean;
          clipOpts: object;
      } = {}

      Options which configure how the union or intersection is computed

      • clipType: Readonly<{
            INTERSECT: 0;
            UNION: 1;
        }>

        One of CLIP_TYPES

      • canMutate: boolean

        If the WeilerAtherton constructor could mutate or not the subject polygon points

      • clipOpts: object

        Options passed to the WeilerAthertonClipper constructor

    Returns Polygon[]

    Array of polygons and clipObjects

Static testForEnvelopment

  • testForEnvelopment(polygon, clipObject, clipType, clipOpts): Polygon[]

  • Test if one shape envelops the other. Assumes the shapes do not intersect.

    1. Polygon is contained within the clip object. Union: clip object; Intersect: polygon
    2. Clip object is contained with polygon. Union: polygon; Intersect: clip object
    3. Polygon and clip object are outside one another. Union: both; Intersect: null

    Parameters

    • polygon: Polygon

      Polygon to clip

    • clipObject: Rectangle | Circle

      Object to clip against the polygon

    • clipType: Readonly<{
          INTERSECT: 0;
          UNION: 1;
      }>

      One of CLIP_TYPES

    • clipOpts: object

      Clip options which are forwarded to toPolygon methods

    Returns Polygon[]

    Returns the polygon, the clipObject.toPolygon(), both, or neither.

Static Private #consolidatePoints

  • #consolidatePoints(labeledPoints): Point[]

  • Given an array of labeled points, consolidate into a tracking array of intersections, where each intersection contains its array of leadingPoints.

    Parameters

    • labeledPoints: Point[]

      Array of points, from _buildLabeledIntersectionsArray

    Returns Point[]

    Array of intersections

Settings

Member Visibility

Theme

On This Page

constructorpolygonclipObjectconfigCLIP_TYPESINTERSECTION_TYPES#combineNoHoles#processIntersection#buildPointTrackingArray#buildIntersectionArrayunionintersectcombinetestForEnvelopment#consolidatePoints