pmtiles-swarm 0.68.0 → 0.68.1

package/CHANGELOG.md

@@ -4,6 +4,28 @@
 ### ✨ Features and improvements
 - _...Add new stuff here..._
 
+### 🐞 Bug fixes
+- _...Add new stuff here..._
+
+## 0.68.1
+### ✨ Features and improvements
+- **A cutline may have holes in it, which is to say it may be a real boundary.** 0.68.0 refused
+  any shape with interior rings, on the reasoning that the even-odd fill would treat a hole as
+  solid. It does not — a ray to a point inside a hole crosses the outer ring and then the inner
+  one, which is two crossings, which is outside — so the refusal protected against nothing and
+  turned away almost every boundary worth clipping to. A country is islands and enclaves and
+  lakes; the German cutline this was written for is ninety-three rings.
+
+  Tested rather than reasoned about, because getting it wrong fills in exactly the ground somebody
+  cut out.
+
+  The documentation now also says how a shapefile becomes a cutline, since that is where every
+  real one starts: one `ogr2ogr -t_srs EPSG:4326`, and the filename is the name the recipe uses.
+  With a note to simplify — a boundary drawn for surveying carries far more detail than a tile can
+  show, and every point of it is a segment to index and test.
+
+
+
 ### 🐞 Bug fixes
 - _...Add new stuff here..._
 

package/docs/tile-stacks.md

@@ -857,8 +857,38 @@ coordinates inlined in one is neither. A rectangle is small enough to sit in the
 recipe itself, so `bounds` does.
 
 WGS84 on purpose. Web Mercator is arithmetic from there — no projection library,
-no dependency, no CRS handling beyond refusing what is not WGS84. Anything else
-converts once with the `ogr2ogr` that produced the shapefile in the first place.
+no dependency, no CRS handling beyond refusing what is not WGS84.
+
+### Getting a shapefile in
+
+A cutline usually starts life as a shapefile in a projected CRS, because that is
+what `gdalwarp -cutline` wants. One `ogr2ogr` converts it, and it is the same
+tool that produced the shapefile in the first place:
+
+```sh
+ogr2ogr -t_srs EPSG:4326 \
+  data/cutlines/germany.geojson \
+  datasets/OpenDTM_DE/cutline/germany_cutline_25832.shp
+```
+
+The name of the file is the name the recipe uses, so that one becomes
+`"cutline": "germany"`. Nothing has to restart: cutlines are read when the node
+starts and the console lists whatever is there.
+
+**Simplify it.** A national boundary drawn for surveying carries far more detail
+than a tile can show — Germany's is ninety-three rings and sixty-five thousand
+points in its first record alone — and every one of them is a segment to index
+and to test. What matters is being right to about a pixel at the deepest zoom
+served, which at z14 is roughly five metres:
+
+```sh
+ogr2ogr -t_srs EPSG:4326 -simplify 0.0001 out.geojson in.shp
+```
+
+Holes and islands are kept, and want to be: a country is islands and enclaves
+and lakes. Under the even-odd rule an interior ring needs no special handling
+and gets none — a ray to a point inside one crosses the outer ring and then the
+inner ring, which is two crossings, which is outside.
 
 Edges are treated as straight lines in Mercator after their endpoints are
 projected. That is what every rasteriser does, GDAL's included, and the error

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmtiles-swarm",
-  "version": "0.68.0",
+  "version": "0.68.1",
   "description": "BitTorrent distribution for PMTiles map archives: create torrents, watch folders, publish and subscribe to RSS feeds, and seed through qBittorrent or an embedded client",
   "type": "module",
   "main": "src/index.js",

package/src/cutline.js

@@ -48,9 +48,13 @@ export function worldY(lat) {
 /**
  * Reads the rings out of GeoJSON, whatever shape it arrived in.
  *
- * Only the outer rings are kept. A hole is a real thing and this does not
- * pretend to handle one -- the even-odd rule below would treat it as solid --
- * so a cutline with holes is refused rather than silently filled in.
+ * Every ring, interior ones included. Under the even-odd rule a hole needs no
+ * special handling and gets none: a ray to a point inside one crosses the outer
+ * ring and then the inner ring, which is two crossings, which is outside. An
+ * earlier version of this refused shapes with holes on the assumption that they
+ * would be filled in. They are not, and refusing them would have turned away
+ * almost every real boundary -- a country is islands and enclaves and lakes,
+ * and Germany's is ninety-three rings.
  * @param {object} geojson - A Feature, FeatureCollection, or bare geometry.
  * @returns {number[][][]} - Rings of `[lon, lat]`.
  */
@@ -58,13 +62,9 @@ export function ringsOf(geojson) {
   const rings = [];
 
   const fromPolygon = (coordinates) => {
-    if (coordinates.length > 1) {
-      throw new Error(
-        'this cutline has interior rings, and clipping to a shape with holes ' +
-          'is not something this does',
-      );
+    for (const ring of coordinates) {
+      if (ring?.length >= 4) rings.push(ring);
     }
-    if (coordinates[0]?.length >= 4) rings.push(coordinates[0]);
   };
 
   const walk = (node) => {