luizbarboza / polyclip-ts

polyclip-ts

Apply boolean polygon clipping operations (intersection, union, difference, xor) to your Polygons & MultiPolygons.

Installing

If you use npm, npm install polyclip-ts. You can also download the latest release on GitHub. For vanilla HTML in modern browsers, import polyclip-ts from Skypack:

<script type="module">
import * as polyclip from "https://cdn.skypack.dev/polyclip-ts";

polyclip.intersection(…)
</script>

For legacy environments, you can load polyclip-ts’s UMD bundle from an npm-based CDN such as jsDelivr; a polyclip global is exported:

<script src="https://cdn.jsdelivr.net/npm/polyclip-ts/dist/polyclip-ts.umd.min.js"></script>
<script>
polyclip.intersection(…)
</script>

Quickstart

import * as polyclip from "polyclip-ts"

const poly1 = [[[0,0],[2,0],[0,2],[0,0]]]
const poly2 = [[[-1,0],[1,0],[0,1],[-1,0]]]

polyclip.union       (poly1, poly2 /* , poly3, ... */)
polyclip.intersection(poly1, poly2 /* , poly3, ... */)
polyclip.xor         (poly1, poly2 /* , poly3, ... */)
polyclip.difference  (poly1, poly2 /* , poly3, ... */)

API

/* All functions take one or more [multi]polygon(s) as input */

polyclip.union       (geom, ...moreGeoms)
polyclip.intersection(geom, ...moreGeoms)
polyclip.xor         (geom, ...moreGeoms)

/* The moreGeoms will be subtracted from the geom */
polyclip.difference  (geom, ...moreGeoms)

Input

Each positional argument (geom) may be either a Polygon or a MultiPolygon. The GeoJSON spec is followed, with the following notes/modifications:

• MultiPolygons may contain touching or overlapping Polygons.
• rings are not required to be self-closing.
• rings may contain repeated points, which are ignored.
• rings may be self-touching and/or self-crossing. Self-crossing rings will be interpreted using the non-zero rule.
• winding order of rings does not matter.
• inner rings may extend outside their outer ring. The portion of inner rings outside their outer ring is dropped.
• inner rings may touch or overlap each other.

Output

For non-empty results, output will always be a MultiPolygon containing one or more non-overlapping, non-edge-sharing Polygons. The GeoJSON spec is followed, with the following notes/modifications:

• outer rings will be wound counter-clockwise, and inner rings clockwise.
• inner rings will not extend outside their outer ring.
• rings will not overlap, nor share an edge with each other.
• rings will be self-closing.
• rings will not contain repeated points.
• rings will not contain superfluous points (intermediate points along a straight line).
• rings will not be self-touching nor self-crossing.
• rings may touch each other, but may not cross each other.

In the event that the result of the operation is the empty set, output will be a MultiPolygon with no Polygons: [].

Correctness

Run: npm test

The tests are broken up into unit tests and end-to-end tests. The end-to-end tests are organized as GeoJSON files, to make them easy to visualize thanks to GitHub's helpful rendering of GeoJSON files. Browse those tests here.

Performance

The Martinez-Rueda-Feito polygon clipping algorithm is used to compute the result in O((n+k)*log(n)) time, where n is the total number of edges in all polygons involved and k is the number of intersections between edges.

Authors

• Luiz F. M. Barboza
• Mike Fogel
• Alexander Milevski
• Vladimir Ovsyannikov

Based on

• A simple algorithm for Boolean operations on polygons by Francisco Martinez, Antonio Jesus Rueda, Francisco Ramon Feito (2009)

polyclip-ts's Issues

Discussing compatibility with polygon-clipping types

I'm interested in having the Turf project replace polygon-clipping with tis library. ( related issue ).

I've started on the work, but I'm also less experienced working with types and have run into some cases I'm not sure how to resolved.

Geom public vs private

The polygon-clipping library has a Geom type. This ibrary has it too, but it does not seem to exposed. Here's how the type is used by turf-union:

const geoms: polygonClipping.Geom[] = [];

Can this module export the same type for compatibility?

number type vs Position type

turf-union has this code:

 const unioned = polyclip.union(geoms[0], ...geoms.slice(1));
  if (unioned.length === 0) return null;
  if (unioned.length === 1) return polygon(unioned[0], options.properties);

There, polygon method comes from @turf/helpers

If I swap in polyclip-ts, I get this typing error with npm run build:

 Argument of type '(number[][] | null)[][]' is not assignable to parameter of type 'Position[][][]'.

How can this typing difference be smoothed over?

Thanks!

Two polygons with shared coords doesn't return intersecting but union works

I want to check if two polygons with are intersecting.
When the polygons have overlapping coords, intersection still returns that they are not intersecting

Example:

const poly1 = [
			[
				[72.723999, 18.976429],
				[72.723999, 19.324103],
				[73.100281, 19.324103], // <-- overlapping coords
				[73.100281, 18.976429], // <-- overlapping coords
				[72.723999, 18.976429],
			],
		];

const poly2 = [
			[
				[73.100281, 18.976429], // <-- overlapping coords
				[73.100281, 19.324103], // <-- overlapping coords
				[74.900281, 19.324103],
				[74.900281, 18.976429],
				[73.100281, 18.976429],
			],
		];

polyclip.intersection(poly1, poly2);

Is not intersecting ... Why? Bounds are overlapping:
[]

polyclip.union(poly1, poly2);

Union returns single polygon (correctly), because bounds are overlapping:
[[[[72.723999,18.976429],[74.900281,18.976429],[74.900281,19.324103],[72.723999,19.324103],[72.723999,18.976429]]]]

https://plnkr.co/edit/qDSAFfMQUsJFog2S

unable to complete output ring starting at

Doing a intersect on these two shapes seems to produce the unable to complete output ring starting at error

{
        type: 'Feature',
        properties: {},
        geometry: {
          type: 'Polygon',
          coordinates: [
            [
              [
                -94.01653361819794,
                44.91274384567805
              ],
              [
                -94.01648672631458,
                44.91275462177405
              ],
              [
                -94.01653344003874,
                44.91275386419229
              ],
              [
                -94.01653361819794,
                44.91274384567805
              ]
            ]
          ]
        }
      }

      {
        type: 'Feature',
        properties: {},
        geometry: {
          type: 'Polygon',
          coordinates: [
            [
              [
                -94.01654779292787,
                44.91274058822198
              ],
              [
                -94.0164867263146,
                44.91275462177405
              ],
              [
                -94.01650378031933,
                44.91275434520002
              ],
              [
                -94.01654762526815,
                44.912753634142746
              ],
              [
                -94.01654779292787,
                44.91274058822198
              ]
            ]
          ]
        }
      }

how can i use this in a website as .min.js package?

there is a npm to compile a min.js package but i cant figure out how to use it on a webpage ... can you help?

add test cases

• mfogel/polygon-clipping#75
• mfogel/polygon-clipping#83
• mfogel/polygon-clipping#86
• mfogel/polygon-clipping#90
• mfogel/polygon-clipping#91
• mfogel/polygon-clipping#93
• mfogel/polygon-clipping#94
• mfogel/polygon-clipping#95
• mfogel/polygon-clipping#96
• mfogel/polygon-clipping#98
• mfogel/polygon-clipping#101
• mfogel/polygon-clipping#105
• mfogel/polygon-clipping#111
• mfogel/polygon-clipping#115
• mfogel/polygon-clipping#118
• mfogel/polygon-clipping#122
• mfogel/polygon-clipping#124
• mfogel/polygon-clipping#129
• mfogel/polygon-clipping#139
• mfogel/polygon-clipping#140
• mfogel/polygon-clipping#141
• mfogel/polygon-clipping#142

TypeScript still cannot resolve types

          Fixed in version 0.16.5. Thanks for pointing out.

Originally posted by @luizbarboza in #10 (comment)

Unfortunately, package.json fix exists only in main branch, but not in 0.16.5 tag, so installing via npm results in missing types

npm package for 0.16.4 is missing sources

The published package on npmjs.com is missing the compiled sources in dist/ and types/. See see https://www.npmjs.com/package/polyclip-ts/v/0.16.4?activeTab=code, or do something like npm install polyclip-ts && ls ./node_modules/polyclip-ts to confirm.

wish: please keep a changelog or use Github Releases notes

It's very helpful for users to be able to easily see what's new so they can design if there are bug fixes or security updates that they should upgrade to take advantage of.

The version of the module is currently less than 1.0, implying that any release might have breaking changes.

The easiest way I've found to this is use Github Releases and make notes during each release.

Make optional to remove superfluous points

Thank you for migrating this to TS!
Can we add an option to skip removing superfluous points starting from this line?
Thanks