PolygonOverlay
Union, difference and intersection of two polygons (DrawnPolygons): what "merge" and "cut" are made of.
Each takes the shapes and answers with the rings of the shape that results, as the model keeps them (see DrawnPolygon): the outline of every part, each followed by its holes, all in one list, so a result of two separate countries is the rings of both. An empty list means nothing is left (a difference of a shape from itself, an intersection of two shapes that don't touch). The caller builds the shape, with the id and look it wants (the first ring is the outline DrawnPolygon.vertices, the rest its extraRings).
Vertices. A vertex of the result that was a vertex of a or b keeps its id, its metadata and its exact position (when both have a vertex there, the one of a wins); one that is new, where the outlines cross, gets an id from newVertexId. No two vertices of a result share an id, even if the two inputs reuse one. Altitude is not part of the overlay: new vertices are at altitude 0.
The grid. Exact geometry does not join two neighbours whose shared border is written a hair's breadth apart (1e-12 degrees is enough to leave them two shapes, which is what two sources of the same border give). So the overlay is done on a grid of gridSize degrees: coordinates are rounded to it, and a gap or overlap smaller than a cell disappears. The default is a cell of 1e-7 degrees, about a centimetre. 0.0 is no grid: exact, and then a hair's breadth is a gap. The result's new vertices lie on the grid; the ones kept from the inputs keep their own position.
Not a sphere. Longitude and latitude are used as a flat plane, like the rest of the library (PolygonCenter, PolygonParts): fine for countries, small errors on long edges, and a shape that crosses the antimeridian is not handled.
The overlay itself is JTS's (OverlayNG, in its Kotlin Multiplatform port), see docs/PLAN.md (Faz 12b).
Functions
The rings of what is left of polygon when a strip of distanceMeters metres is taken off its inside all the way round (a setback), with mitred corners; a hole grows by the same distance. An empty list if nothing is left. Done on a flat map in metres around the plot, not on longitude and latitude, so the distance is the same in every direction; every corner of the result is new.
Why polygon cannot be used in an overlay (a line crosses itself, a hole is outside, a ring has too few points...), or null if it can.