Synopsis

These are Ruby bindings to Clipper, Angus Johnson's Polygon clipping library. Because Clipper is not readily packaged, and is so beautifully self-contained, I've included the two required files in the package.

This release contains version 6.4.2 of Clipper.

To install:

gem install clipper

Build locally:

rake install

Simple Usage:

require 'clipper'

a = [[0, 0], [0, 100], [100, 100], [100, 0]]
b = [[-5, 50], [200, 50], [100, 5]]

c = Clipper::Clipper.new

c.add_subject_polygon(a)
c.add_clip_polygon(b)
c.union :non_zero, :non_zero

=> [[[100.0, 0.0], [0.0, 0.0], [0.0, 47.85714326530613], [-4.999999, 50.0],
     [0.0, 50.0], [0.0, 100.0], [100.0, 100.0], [100.0, 50.0],
     [200.0, 50.0], [100.0, 5.0]]]

Documentation

Clipper is a two-dimensional polygon clipping library. rbclipper, the Ruby bindings can be accessed by:

require 'clipper'

Polygons

Operations that accept or return polygons are specified as an array of [x,y] coordinates, for example, to specify a triangle:

triangle = [[0,0], [0,100], [50, -100]]

Clipper supports both holes and complex polygons. Coordinates for output polygons are clockwise for shells, and and counter-clockwise for holes. See force_orientation.

Note that since 2.8, Clipper defines orientation with respect to a downward-increasing Y axis, similar to how many 2D GUI/drawing APIs position coordinate (0,0) at the top-left corner. The bindings have followed Clipper proper in this regard.

Multiple polygons are represented as simply an array of polygons.

Fill Types

  • :even_odd

    A point is considered inside the polygon if the number of edge-crossings to get there from outside the shape is an even number.

  • :non_zero

    A point is considered inside the polygon if the number of edge-crossings to get there is greater than zero.

  • :positive

    Please read the official doc here

  • :negative

    Please read the official doc here

Clipper::Clipper Methods

  • Clipper#initialize(multiplier = 1048576)

Creates a new clipper object, with an option for multiplier. Default to 2^10 (1048576). The multiplier is used to transform coordinates of type double to type long long (long64). It is needed because the clipper library store points as IntPoint after version 4.0.

  • Clipper#add_subject_polygon(polygon)

Clipper#add_clip_polygon(polygon)

Adds a subject or clip polygon to the engine. Boolean operations are calculated as SUBJECT operatation CLIP. Multiple polygons can Pay attention to the orientation of the coordinates given; counter-clockwise for shells and clockwise for holes.

Multiple subject and clip polygons can be added to the engine for operations.

  • Clipper#add_subject_polygons(polygons)

Clipper#add_clip_polygons(polygons)

Add an array of polygons to the engine. Boolean operations consider every poly-polygon added in this manner to be the same object.

  • Clipper#intersection(subject_fill=:even_odd, clip_fill=:even_odd)

Clipper#union(subject_fill=:even_odd, clip_fill=:even_odd)

Clipper#difference(subject_fill=:even_odd, clip_fill=:even_odd)

Clipper#xor(subject_fill=:even_odd, clip_fill=:even_odd)

Performs a boolean operation on the polygons that have been added to the clipper object. The result is a list of polygons.