add CLI option to adjust the clip buffer size (#564)

Co-authored-by: Dominik Winkler <dominik.winkler@materna.group>

Author: Rohten-dev

tiles/src/main/java/com/protomaps/basemap/Basemap.java

@@ -188,6 +188,8 @@ private static void printHelp() {
                                 Valid values: boundaries, buildings, landuse, landcover,
                                               places, pois, roads, transit, water, earth
         --clip=<path>           GeoJSON file path to clip tileset (optional)
+        --clip-buffer=<n>       Relative buffer around clip polygon (default: 4.0/256.0)
+              Use 0 for exact boundary, e.g. --clip-buffer=0
 
       Common Planetiler Options:
         --output=<path>         Output file path and format (e.g., output.pmtiles)
@@ -243,11 +245,17 @@ static void run(Arguments args) throws IOException {
     fontRegistry.setZipFilePath(pgfEncodingZip.toString());
 
     Clip clip = null;
+    double clipBuffer = args.getDouble("clip_buffer",
+      "Relative buffer around clip polygon. 0 for exact boundary.", Clip.DEFAULT_BUFFER);
+    if (clipBuffer < 0) {
+      LOGGER.error("Error: --clip-buffer must be >= 0, but was {}", clipBuffer);
+      System.exit(1);
+    }
     var clipArg = args.getString("clip", "File path to GeoJSON Polygon or MultiPolygon geometry to clip tileset.", "");
     if (!clipArg.isEmpty()) {
       clip =
         Clip.fromGeoJSONFile(args.getStats(), planetiler.config().minzoom(), planetiler.config().maxzoom(), true,
-          Paths.get(clipArg));
+          clipBuffer, Paths.get(clipArg));
     }
 
     List<String> availableLayers = List.of(

tiles/src/main/java/com/protomaps/basemap/postprocess/Clip.java

@@ -24,17 +24,20 @@ public class Clip implements ForwardingProfile.TilePostProcessor {
   private final Map<Integer, Map<TileCoord, List<List<CoordinateSequence>>>> boundaryTilesByZoom;
   private final Map<Integer, TiledGeometry.CoveredTiles> coveredTilesByZoom;
   private final Stats stats;
+  private final double boundaryBuffer;
 
-  static final double DEFAULT_BUFFER = 4.0 / 256.0;
+  public static final double DEFAULT_BUFFER = 4.0;
 
   // A TilePostProcessor that clips all layers to a given geometry.
   // the geometry must be in world coordinates ( world from 0 to 1 )
-  public Clip(Stats stats, int minzoom, int maxzoom, boolean doBuffer, Geometry input) {
+  public Clip(Stats stats, int minzoom, int maxzoom, boolean doBuffer, double clipBuffer, Geometry input) {
     this.stats = stats;
+    this.boundaryBuffer = clipBuffer / 256.0;
+
     double bufferAmount = 0;
     if (doBuffer) {
       var envelope = input.getEnvelope().getEnvelopeInternal();
-      bufferAmount = Math.max(envelope.getWidth(), envelope.getHeight()) * DEFAULT_BUFFER;
+      bufferAmount = Math.max(envelope.getWidth(), envelope.getHeight()) * boundaryBuffer;
     }
     var clipGeometry = input.buffer(bufferAmount);
     boundaryTilesByZoom = new HashMap<>();
@@ -45,21 +48,22 @@ public Clip(Stats stats, int minzoom, int maxzoom, boolean doBuffer, Geometry in
         double scale = 1 << i;
         Geometry scaled = AffineTransformation.scaleInstance(scale, scale).transform(clipGeometry);
         this.boundaryTilesByZoom.put(i,
-          sliceIntoTiles(scaled, 0, DEFAULT_BUFFER, i, extents.getForZoom(i)).getTileData());
+          sliceIntoTiles(scaled, 0, boundaryBuffer, i, extents.getForZoom(i)).getTileData());
         this.coveredTilesByZoom.put(i, getCoveredTiles(scaled, i, extents.getForZoom(i)));
       }
     } catch (GeometryException e) {
       throw new Planetiler.PlanetilerException("Error clipping", e);
     }
   }
 
-  public static Clip fromGeoJSONFile(Stats stats, int minzoom, int maxzoom, boolean doBuffer, Path path) {
+  public static Clip fromGeoJSONFile(Stats stats, int minzoom, int maxzoom, boolean doBuffer, double clipBuffer,
+    Path path) {
     var g = GeoJson.from(path);
     if (g.count() == 0) {
       throw new FileFormatException("Empty clipping geometry");
     }
     var feature = g.iterator().next();
-    return new Clip(stats, minzoom, maxzoom, doBuffer, latLonToWorldCoords(feature.geometry()));
+    return new Clip(stats, minzoom, maxzoom, doBuffer, clipBuffer, latLonToWorldCoords(feature.geometry()));
   }
 
   // Copied from elsewhere in planetiler

tiles/src/test/java/com/protomaps/basemap/postprocess/ClipTest.java

@@ -22,7 +22,7 @@ class ClipTest {
   void testLoadGeoJSON() {
     Path cwd = Path.of("").toAbsolutePath();
     Path pathFromRoot = Path.of("tiles", "src", "test", "resources", "clip.geojson");
-    var clip = Clip.fromGeoJSONFile(stats, 0, 0, false, cwd.resolveSibling(pathFromRoot));
+    var clip = Clip.fromGeoJSONFile(stats, 0, 0, false, Clip.DEFAULT_BUFFER, cwd.resolveSibling(pathFromRoot));
     assertNotNull(clip);
   }
 
@@ -32,7 +32,7 @@ void testLoadNonJSON() {
     Path pathFromRoot = Path.of("tiles", "src", "test", "resources", "empty.geojson");
     Path path = cwd.resolveSibling(pathFromRoot);
     assertThrows(FileFormatException.class, () -> {
-      Clip.fromGeoJSONFile(stats, 0, 0, false, path);
+      Clip.fromGeoJSONFile(stats, 0, 0, false, Clip.DEFAULT_BUFFER, path);
     });
   }
 
@@ -46,7 +46,8 @@ void testClipLine() throws GeometryException {
     ));
 
     // a rectangle that is 50% of the earths width, centered at null island.
-    var n = new Clip(stats, 0, 0, false, newPolygon(0.25, 0.25, 0.75, 0.25, 0.75, 0.75, 0.25, 0.75, 0.25, 0.25));
+    var n = new Clip(stats, 0, 0, false, Clip.DEFAULT_BUFFER,
+      newPolygon(0.25, 0.25, 0.75, 0.25, 0.75, 0.75, 0.25, 0.75, 0.25, 0.25));
     var clipped = n.postProcessTile(TileCoord.ofXYZ(0, 0, 0), Map.of("layer", unclipped));
 
     assertEquals(1, clipped.size());
@@ -64,7 +65,8 @@ void testClipLineMulti() throws GeometryException {
     ));
 
     // a rectangle that is 50% of the earths width, centered at null island.
-    var n = new Clip(stats, 0, 0, false, newPolygon(0.25, 0.25, 0.75, 0.25, 0.75, 0.75, 0.25, 0.75, 0.25, 0.25));
+    var n = new Clip(stats, 0, 0, false, Clip.DEFAULT_BUFFER,
+      newPolygon(0.25, 0.25, 0.75, 0.25, 0.75, 0.75, 0.25, 0.75, 0.25, 0.25));
     var clipped = n.postProcessTile(TileCoord.ofXYZ(0, 0, 0), Map.of("layer", unclipped));
 
     assertEquals(1, clipped.size());
@@ -82,7 +84,8 @@ void testClipPolygon() throws GeometryException {
     ));
 
     // a rectangle that is 50% of the earths width, centered at null island.
-    var n = new Clip(stats, 0, 0, false, newPolygon(0.25, 0.25, 0.75, 0.25, 0.75, 0.75, 0.25, 0.75, 0.25, 0.25));
+    var n = new Clip(stats, 0, 0, false, Clip.DEFAULT_BUFFER,
+      newPolygon(0.25, 0.25, 0.75, 0.25, 0.75, 0.75, 0.25, 0.75, 0.25, 0.25));
     var clipped = n.postProcessTile(TileCoord.ofXYZ(0, 0, 0), Map.of("layer", unclipped));
 
     assertEquals(1, clipped.size());
@@ -99,7 +102,8 @@ void testClipBelowMinZoom() throws GeometryException {
       Map.of("foo", "bar")
     ));
 
-    var n = new Clip(stats, 1, 1, false, newPolygon(0.25, 0.25, 0.75, 0.25, 0.75, 0.75, 0.25, 0.75, 0.25, 0.25));
+    var n = new Clip(stats, 1, 1, false, Clip.DEFAULT_BUFFER,
+      newPolygon(0.25, 0.25, 0.75, 0.25, 0.75, 0.75, 0.25, 0.75, 0.25, 0.25));
     var clipped = n.postProcessTile(TileCoord.ofXYZ(0, 0, 0), Map.of("layer", unclipped));
     assertEquals(0, clipped.size());
   }
@@ -112,7 +116,8 @@ void testClipWhollyOutside() throws GeometryException {
       Map.of("foo", "bar")
     ));
 
-    var n = new Clip(stats, 0, 0, false, newPolygon(0.25, 0.25, 0.75, 0.25, 0.75, 0.75, 0.25, 0.75, 0.25, 0.25));
+    var n = new Clip(stats, 0, 0, false, Clip.DEFAULT_BUFFER,
+      newPolygon(0.25, 0.25, 0.75, 0.25, 0.75, 0.75, 0.25, 0.75, 0.25, 0.25));
     var clipped = n.postProcessTile(TileCoord.ofXYZ(0, 0, 0), Map.of("layer", unclipped));
     assertEquals(0, clipped.size());
   }
@@ -125,7 +130,8 @@ void testClipInInterior() throws GeometryException {
       Map.of("foo", "bar")
     ));
 
-    var n = new Clip(stats, 0, 3, false, newPolygon(0.25, 0.25, 0.75, 0.25, 0.75, 0.75, 0.25, 0.75, 0.25, 0.25));
+    var n = new Clip(stats, 0, 3, false, Clip.DEFAULT_BUFFER,
+      newPolygon(0.25, 0.25, 0.75, 0.25, 0.75, 0.75, 0.25, 0.75, 0.25, 0.25));
     var clipped = n.postProcessTile(TileCoord.ofXYZ(3, 3, 3), Map.of("layer", unclipped));
     assertEquals(1, clipped.size());
     assertEquals(1, clipped.get("layer").size());
@@ -140,11 +146,46 @@ void testClipLineBuffer() throws GeometryException {
     ));
 
     // a rectangle that is 50% of the earths width, centered at null island.
-    var n = new Clip(stats, 0, 0, true, newPolygon(0.25, 0.25, 0.75, 0.25, 0.75, 0.75, 0.25, 0.75, 0.25, 0.25));
+    var n = new Clip(stats, 0, 0, true, Clip.DEFAULT_BUFFER,
+      newPolygon(0.25, 0.25, 0.75, 0.25, 0.75, 0.75, 0.25, 0.75, 0.25, 0.25));
     var clipped = n.postProcessTile(TileCoord.ofXYZ(0, 0, 0), Map.of("layer", unclipped));
 
     assertEquals(1, clipped.size());
     assertEquals(1, clipped.get("layer").size());
     assertEquals(newLineString(62, 128, 194, 128), clipped.get("layer").getFirst().geometry().decode());
   }
+
+  @Test
+  void testClipLineBufferZero() throws GeometryException {
+    List<VectorTile.Feature> unclipped = new ArrayList<>();
+    unclipped.add(new VectorTile.Feature("layer", 1,
+      VectorTile.encodeGeometry(newLineString(0, 128, 256, 128)),
+      Map.of("foo", "bar")
+    ));
+
+    var n = new Clip(stats, 0, 0, true, 0,
+      newPolygon(0.25, 0.25, 0.75, 0.25, 0.75, 0.75, 0.25, 0.75, 0.25, 0.25));
+    var clipped = n.postProcessTile(TileCoord.ofXYZ(0, 0, 0), Map.of("layer", unclipped));
+
+    assertEquals(1, clipped.size());
+    assertEquals(1, clipped.get("layer").size());
+    assertEquals(newLineString(64, 128, 192, 128), clipped.get("layer").getFirst().geometry().decode());
+  }
+
+  @Test
+  void testClipLineBufferLargerThanDefault() throws GeometryException {
+    List<VectorTile.Feature> unclipped = new ArrayList<>();
+    unclipped.add(new VectorTile.Feature("layer", 1,
+      VectorTile.encodeGeometry(newLineString(0, 128, 256, 128)),
+      Map.of("foo", "bar")
+    ));
+
+    var n = new Clip(stats, 0, 0, true, 8.0,
+      newPolygon(0.25, 0.25, 0.75, 0.25, 0.75, 0.75, 0.25, 0.75, 0.25, 0.25));
+    var clipped = n.postProcessTile(TileCoord.ofXYZ(0, 0, 0), Map.of("layer", unclipped));
+
+    assertEquals(1, clipped.size());
+    assertEquals(1, clipped.get("layer").size());
+    assertEquals(newLineString(60, 128, 196, 128), clipped.get("layer").getFirst().geometry().decode());
+  }
 }