leaflet-india-boundary 0.1.0

package/src/suppress.ts

@@ -0,0 +1,599 @@
+import {
+  latLng,
+  point,
+  tileLayer,
+  type Coords,
+  type DoneCallback,
+  type Map as LeafletMap,
+  type TileLayer,
+  type TileLayerOptions,
+} from "leaflet";
+import { osmAdminBoundaryWidth } from "./style.js";
+import {
+  INDIA_BOUNDARY_SUPPRESSION,
+  SUPPRESSION_BBOX,
+} from "./suppressionData.js";
+
+/**
+ * EXPERIMENTAL — raster tile surgery.
+ *
+ * `indiaBoundaryLayer()` *adds* India's claimed boundary but cannot remove the Line
+ * of Control and Line of Actual Control that raster tiles already have drawn into
+ * them, so both are visible. This module removes them, by editing the tiles in a
+ * canvas before Leaflet displays them.
+ *
+ * Read the caveats near the bottom of this comment before shipping it. In
+ * particular it does nothing about labels, so it does not make a map match India's
+ * official depiction — see the README.
+ *
+ * HOW, AND WHY IT IS NOT COMPUTER VISION
+ *
+ * The obvious approach is to look for carto's border colour and paint over it. That
+ * does not work, and it is worth knowing why before trying: carto draws admin
+ * boundaries at `opacity: 0.5`, so the colour that ends up in the tile is a blend of
+ * the border with whatever terrain is underneath it. There is no border colour to
+ * search for. Measured on one z6 tile over Kashmir, only 69 pixels in the entire
+ * tile sit within a small distance of `#8d618b`, and widening the threshold enough
+ * to catch the rest starts matching a river and a road instead.
+ *
+ * So colour cannot say *what*. Geometry has to say *where* — and we have the
+ * geometry exactly, because it is what deriving India's boundary throws away. A
+ * boundary way belonging to two of the four disputed regions is internal, which is
+ * the Line of Control; a way shared with China is the Line of Actual Control. Both
+ * are discarded to leave India's claimed outer edge, and both are kept in
+ * `suppressionData.ts` for use here. Same database the tiles were rendered from,
+ * so it lines up by construction.
+ *
+ * Per tile, then: rasterise those polylines into a mask a few pixels wide at
+ * carto's own stroke width for the zoom, and inpaint underneath it by repeatedly
+ * averaging each masked pixel's unmasked neighbours, working inward from the edges
+ * of the ribbon. Terrain reconstructs well because the ribbon is thin and the
+ * terrain either side of it is locally similar.
+ *
+ * WHAT IT COSTS
+ *
+ * Almost nothing, because almost no tiles are affected. The disputed region is one
+ * bbox; every tile outside it takes a fast path that returns a plain `<img>` with no
+ * canvas and no pixel readback at all. Inside it, a tile has a few thousand masked
+ * pixels and converges in a handful of passes.
+ *
+ * CAVEATS
+ *
+ *  - **Labels are untouched.** Urdu toponymy for Gilgit-Baltistan and Chinese labels
+ *    across Aksai Chin stay exactly as they are. Labels are placed by carto's
+ *    collision-avoidance engine at render time, so unlike the border there is no
+ *    geometry to build a mask from. This is the reason this module is not a route to
+ *    matching India's official depiction.
+ *  - **Anything else crossing the line gets inpainted too.** A road or a label glyph
+ *    that overlaps the ribbon is reconstructed from its surroundings, so it can be
+ *    nicked. Keeping the ribbon at carto's actual stroke width rather than padding it
+ *    generously is what keeps this rare.
+ *  - **Tile-edge seams are handled, at a small cost.** Inpainting each tile in
+ *    isolation makes adjacent tiles disagree along the join, so the work is done on a
+ *    padded canvas seeded with the neighbours the ribbon runs into. That means a few
+ *    extra tile requests — see `seamlessEdges` to turn it off.
+ *  - **Requires CORS.** `getImageData` needs the tile server to send
+ *    `Access-Control-Allow-Origin`. `tile.openstreetmap.org` does. If yours does not,
+ *    the canvas is tainted, and by default the tile is shown unmodified rather than
+ *    failing (see `fallbackOnError`).
+ *  - **Breaks HTTP caching of the processed result.** The browser still caches the
+ *    original tile; the surgery is redone on each load. Cheap, but not free.
+ */
+
+/** Mean latitude of the disputed region, for metres-per-pixel. */
+const REGION_LAT = 34.5;
+
+/** Web Mercator ground resolution at the equator, metres per pixel at zoom 0. */
+const EQUATOR_M_PER_PX = 156543.03392;
+
+/** Tolerance the shipped suppression geometry was simplified at. See suppressionData.ts. */
+const SIMPLIFY_TOLERANCE_M = 15;
+
+/** Antialiasing spreads carto's stroke a little either side of its nominal width. */
+const ANTIALIAS_PAD_PX = 1.6;
+
+function metresPerPixel(zoom: number): number {
+  return (EQUATOR_M_PER_PX * Math.cos((REGION_LAT * Math.PI) / 180)) / 2 ** zoom;
+}
+
+/**
+ * Mask width in pixels: carto's own stroke for the zoom, plus its antialiasing, plus
+ * however many pixels the simplified geometry might be off by at this zoom.
+ *
+ * The last term is what makes a coarse simplification safe. The polyline can sit up
+ * to the simplification tolerance away from OSM's original nodes, so widening the
+ * ribbon by that much guarantees it still covers the drawn line. At 15 m that is
+ * nothing until about z11 and under two pixels at z14.
+ */
+function defaultRibbonWidth(zoom: number): number {
+  const simplifyPx = SIMPLIFY_TOLERANCE_M / metresPerPixel(zoom);
+  return osmAdminBoundaryWidth(zoom) + ANTIALIAS_PAD_PX + 2 * simplifyPx;
+}
+
+export interface SuppressedTileLayerOptions extends TileLayerOptions {
+  /**
+   * Mask width in pixels, or a function of zoom. Defaults to
+   * {@link defaultRibbonWidth} — carto's stroke width for the zoom plus padding.
+   *
+   * Widen it if a sliver of the old line survives; narrow it if labels crossing the
+   * border are being chewed. Those are the only two failure modes, and they pull in
+   * opposite directions.
+   */
+  ribbonWidth?: number | ((zoom: number) => number);
+
+  /**
+   * On a CORS failure (a tainted canvas, so `getImageData` throws), show the tile
+   * unmodified instead of failing. Default `true`: a map with a redundant border
+   * beats a map with holes in it.
+   */
+  fallbackOnError?: boolean;
+
+  /**
+   * Paint the mask in magenta instead of inpainting under it. For checking that the
+   * ribbon actually lands on the line before trusting what it removes.
+   */
+  debugMask?: boolean;
+
+  /**
+   * Reconstruct across tile boundaries by seeding the inpaint with the neighbouring
+   * tiles. Default `true`.
+   *
+   * Without it, each tile is inpainted in isolation, so a pixel on the tile's edge is
+   * rebuilt only from the data on its own side and the two tiles disagree along the
+   * join — a faint but visible stitch across the erased line. With it, the work
+   * happens on a padded canvas seeded from the neighbours the ribbon actually runs
+   * into, so both sides see the same ground truth.
+   *
+   * The cost is bounded and small: only the neighbours the ribbon reaches are
+   * fetched — usually two or three, since the line enters and leaves — and only for
+   * the handful of tiles the ribbon touches at all. Those neighbours are also, almost
+   * always, tiles Leaflet is already displaying, so they come from the browser cache.
+   * Set `false` if you would rather have the seams than the requests.
+   */
+  seamlessEdges?: boolean;
+}
+
+/**
+ * Leaflet accepts `crossOrigin` as a string, `true` (meaning the empty attribute,
+ * which is anonymous) or `false`/absent. The DOM wants a string or null.
+ *
+ * `fallback` is used when nothing was configured, because for the tiles this module
+ * processes anonymous CORS is not optional — without it the canvas is tainted and
+ * there is nothing to read back.
+ */
+function resolveCrossOrigin(
+  value: string | boolean | undefined,
+  fallback: string | null,
+): string | null {
+  if (value === true) return "";
+  if (value === false || value == null) return fallback;
+  return value;
+}
+
+/** Neighbour offsets for the inpaint, 8-connected. */
+const NEIGHBOURS: ReadonlyArray<readonly [number, number]> = [
+  [1, 0],
+  [-1, 0],
+  [0, 1],
+  [0, -1],
+  [1, 1],
+  [1, -1],
+  [-1, 1],
+  [-1, -1],
+];
+
+/** Cheap per-feature reject: does this polyline's own extent touch the tile at all? */
+function featureBounds(
+  coords: number[][],
+): readonly [number, number, number, number] {
+  let w = Infinity;
+  let s = Infinity;
+  let e = -Infinity;
+  let n = -Infinity;
+  for (const c of coords) {
+    if (c[0]! < w) w = c[0]!;
+    if (c[0]! > e) e = c[0]!;
+    if (c[1]! < s) s = c[1]!;
+    if (c[1]! > n) n = c[1]!;
+  }
+  return [w, s, e, n];
+}
+
+const FEATURE_BOUNDS: ReadonlyArray<readonly [number, number, number, number]> =
+  INDIA_BOUNDARY_SUPPRESSION.features.map((f) => featureBounds(f.geometry.coordinates));
+
+function overlaps(
+  a: readonly [number, number, number, number],
+  b: readonly [number, number, number, number],
+  pad: number,
+): boolean {
+  return !(
+    a[2] + pad < b[0] ||
+    a[0] - pad > b[2] ||
+    a[3] + pad < b[1] ||
+    a[1] - pad > b[3]
+  );
+}
+
+/**
+ * A tile layer that erases the Line of Control and Line of Actual Control from the
+ * tiles it loads.
+ *
+ * Compose it with the boundary overlay to get a single correct line on free raster
+ * tiles — this one removes what the basemap drew, that one adds India's claim:
+ *
+ * ```js
+ * import { suppressedTileLayer } from "leaflet-india-boundary/suppress";
+ * import { indiaBoundaryLayer } from "leaflet-india-boundary/leaflet";
+ *
+ * suppressedTileLayer("https://tile.openstreetmap.org/{z}/{x}/{y}.png", {
+ *   attribution: '© <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a>',
+ * }).addTo(map);
+ *
+ * indiaBoundaryLayer().addTo(map);
+ * ```
+ *
+ * Read the module comment above before shipping this. The short version: it does not
+ * touch labels, so it does not make a map match India's official depiction.
+ */
+export function suppressedTileLayer(
+  urlTemplate: string,
+  options: SuppressedTileLayerOptions = {},
+): TileLayer {
+  const {
+    ribbonWidth,
+    fallbackOnError = true,
+    debugMask = false,
+    seamlessEdges = true,
+    ...tileOptions
+  } = options;
+
+  // Without this the canvas is tainted and getImageData throws.
+  const layer = tileLayer(urlTemplate, { crossOrigin: "anonymous", ...tileOptions });
+
+  const ribbonFor = (zoom: number) =>
+    typeof ribbonWidth === "function"
+      ? ribbonWidth(zoom)
+      : (ribbonWidth ?? defaultRibbonWidth(zoom));
+
+  // `createTile` and `_map` are both declared protected — they are Leaflet's
+  // documented extension points, meant to be overridden by a subclass. Overriding on
+  // the instance instead keeps this a plain factory with a typed return, at the cost
+  // of one cast to name the members being used. Nothing here is undocumented; it is
+  // only reached differently.
+  const internal = layer as unknown as {
+    _map: LeafletMap;
+    options: SuppressedTileLayerOptions;
+    getTileSize(): ReturnType<TileLayer["getTileSize"]>;
+    getTileUrl(coords: Coords): string;
+    createTile(coords: Coords, done: DoneCallback): HTMLElement;
+  };
+
+  internal.createTile = function createTile(coords, done) {
+    const size = this.getTileSize();
+    const map = this._map;
+    const origin = point(coords.x, coords.y).scaleBy(size);
+
+    // Tile extent in lon/lat, for the fast path and the per-feature reject.
+    const nw = map.unproject(origin, coords.z);
+    const se = map.unproject(origin.add(size), coords.z);
+    const tileBox: readonly [number, number, number, number] = [
+      Math.min(nw.lng, se.lng),
+      Math.min(nw.lat, se.lat),
+      Math.max(nw.lng, se.lng),
+      Math.max(nw.lat, se.lat),
+    ];
+
+    // Degrees of padding to cover the mask's own width at this zoom.
+    const ribbon = ribbonFor(coords.z);
+    const padDeg =
+      (ribbon * metresPerPixel(coords.z)) /
+      (111_320 * Math.cos((REGION_LAT * Math.PI) / 180));
+
+    // The overwhelming majority of tiles are nowhere near the disputed region, and
+    // pay nothing at all: no canvas, no readback, just the image Leaflet would have
+    // used anyway.
+    if (!overlaps(tileBox, SUPPRESSION_BBOX, padDeg)) {
+      const img = document.createElement("img");
+      img.setAttribute("role", "presentation");
+      img.alt = "";
+      // No canvas on this path, so no CORS requirement — honour whatever was asked
+      // for and otherwise leave it alone.
+      img.crossOrigin = resolveCrossOrigin(this.options.crossOrigin, null);
+      img.onload = () => done(undefined, img);
+      img.onerror = () => done(new Error("tile failed to load"), img);
+      img.src = this.getTileUrl(coords);
+      return img;
+    }
+
+    const canvas = document.createElement("canvas");
+    canvas.width = size.x;
+    canvas.height = size.y;
+    canvas.setAttribute("role", "presentation");
+    const ctx = canvas.getContext("2d");
+
+    const img = new Image();
+    img.crossOrigin = resolveCrossOrigin(this.options.crossOrigin, "anonymous");
+
+    img.onload = () => {
+      if (!ctx) {
+        done(new Error("no 2d context"), canvas);
+        return;
+      }
+      ctx.drawImage(img, 0, 0, size.x, size.y);
+
+      const finish = (err?: unknown) => {
+        // A thrown error here is almost always a SecurityError from a tainted canvas
+        // — the tile server sent no CORS header. The unmodified tile is still a
+        // usable map, so by default show it rather than failing the tile.
+        if (err && !fallbackOnError) done(err as Error, canvas);
+        else done(undefined, canvas);
+      };
+
+      void suppress({
+        ctx,
+        w: size.x,
+        h: size.y,
+        coords,
+        map,
+        origin,
+        ribbon,
+        debugMask,
+        seamlessEdges,
+        tileUrl: (c) => this.getTileUrl(c),
+        crossOrigin: img.crossOrigin,
+      }).then(
+        () => finish(),
+        (err) => finish(err),
+      );
+    };
+    img.onerror = () => done(new Error("tile failed to load"), canvas);
+    img.src = this.getTileUrl(coords);
+
+    return canvas;
+  };
+
+  return layer;
+}
+
+interface SuppressArgs {
+  ctx: CanvasRenderingContext2D;
+  w: number;
+  h: number;
+  coords: Coords;
+  map: LeafletMap;
+  origin: { x: number; y: number };
+  ribbon: number;
+  debugMask: boolean;
+  seamlessEdges: boolean;
+  tileUrl: (coords: Coords) => string;
+  crossOrigin: string | null;
+}
+
+/**
+ * Rasterise the discarded lines into `mc`, offset by `pad` pixels so the caller can
+ * work on a canvas larger than the tile. Returns whether anything actually landed.
+ */
+function drawMask(
+  mc: CanvasRenderingContext2D,
+  w: number,
+  h: number,
+  pad: number,
+  coords: Coords,
+  map: LeafletMap,
+  origin: { x: number; y: number },
+  ribbon: number,
+): boolean {
+  mc.strokeStyle = "#fff";
+  mc.lineWidth = ribbon;
+  mc.lineJoin = "round";
+  mc.lineCap = "round";
+
+  const nw = map.unproject(point(origin.x - pad, origin.y - pad), coords.z);
+  const se = map.unproject(point(origin.x + w + pad, origin.y + h + pad), coords.z);
+  const box: readonly [number, number, number, number] = [
+    Math.min(nw.lng, se.lng),
+    Math.min(nw.lat, se.lat),
+    Math.max(nw.lng, se.lng),
+    Math.max(nw.lat, se.lat),
+  ];
+
+  let drew = false;
+  const features = INDIA_BOUNDARY_SUPPRESSION.features;
+  for (let f = 0; f < features.length; f += 1) {
+    if (!overlaps(box, FEATURE_BOUNDS[f]!, 0.2)) continue;
+    const cs = (features[f]! as { geometry: { coordinates: number[][] } }).geometry
+      .coordinates;
+    mc.beginPath();
+    for (let i = 0; i < cs.length; i += 1) {
+      const p = map.project(latLng(cs[i]![1]!, cs[i]![0]!), coords.z);
+      const x = p.x - origin.x + pad;
+      const y = p.y - origin.y + pad;
+      if (i === 0) mc.moveTo(x, y);
+      else mc.lineTo(x, y);
+    }
+    mc.stroke();
+    drew = true;
+  }
+  return drew;
+}
+
+/**
+ * Which neighbouring tiles the mask actually reaches into, as "dx,dy" keys.
+ *
+ * This is the whole reason the seam fix is affordable. A tile whose ribbon crosses
+ * one edge needs one neighbour, not eight, and a tile where the ribbon stays clear of
+ * the edges needs none. In practice the ribbon enters and leaves, so it is usually
+ * two or three — and those neighbours are almost always already in the browser's
+ * cache, because Leaflet is displaying them anyway.
+ */
+function marginsNeeded(
+  maskData: Uint8ClampedArray,
+  W: number,
+  H: number,
+  pad: number,
+): Set<string> {
+  const needed = new Set<string>();
+  const bandX = (dx: number): [number, number] =>
+    dx < 0 ? [0, pad] : dx > 0 ? [W - pad, W] : [pad, W - pad];
+  const bandY = (dy: number): [number, number] =>
+    dy < 0 ? [0, pad] : dy > 0 ? [H - pad, H] : [pad, H - pad];
+
+  for (let dx = -1; dx <= 1; dx += 1) {
+    for (let dy = -1; dy <= 1; dy += 1) {
+      if (dx === 0 && dy === 0) continue;
+      const [x0, x1] = bandX(dx);
+      const [y0, y1] = bandY(dy);
+      let hit = false;
+      for (let y = y0; y < y1 && !hit; y += 1) {
+        for (let x = x0; x < x1; x += 1) {
+          if (maskData[(y * W + x) * 4 + 3]! > 32) {
+            hit = true;
+            break;
+          }
+        }
+      }
+      if (hit) needed.add(`${dx},${dy}`);
+    }
+  }
+  return needed;
+}
+
+function loadImage(
+  url: string,
+  crossOrigin: string | null,
+): Promise<HTMLImageElement | null> {
+  return new Promise((resolve) => {
+    const im = new Image();
+    if (crossOrigin != null) im.crossOrigin = crossOrigin;
+    im.onload = () => resolve(im);
+    // A neighbour that fails to load is not fatal: the seam it would have fixed just
+    // stays. Better a faint seam than a missing tile.
+    im.onerror = () => resolve(null);
+    im.src = url;
+  });
+}
+
+async function suppress(a: SuppressArgs): Promise<void> {
+  const { ctx, w, h, coords, map, origin, ribbon } = a;
+  const pad = a.seamlessEdges ? Math.ceil(ribbon) + 2 : 0;
+  const W = w + 2 * pad;
+  const H = h + 2 * pad;
+
+  const maskCanvas = document.createElement("canvas");
+  maskCanvas.width = W;
+  maskCanvas.height = H;
+  const mc = maskCanvas.getContext("2d");
+  if (!mc) throw new Error("no 2d context for mask");
+
+  if (!drawMask(mc, w, h, pad, coords, map, origin, ribbon)) return;
+  const maskData = mc.getImageData(0, 0, W, H).data;
+
+  if (a.debugMask) {
+    const dbg = ctx.getImageData(0, 0, w, h);
+    for (let y = 0; y < h; y += 1) {
+      for (let x = 0; x < w; x += 1) {
+        if (maskData[((y + pad) * W + (x + pad)) * 4 + 3]! > 32) {
+          const i = y * w + x;
+          dbg.data[i * 4] = 255;
+          dbg.data[i * 4 + 1] = 0;
+          dbg.data[i * 4 + 2] = 255;
+        }
+      }
+    }
+    ctx.putImageData(dbg, 0, 0);
+    return;
+  }
+
+  // Seed a padded canvas with the neighbours the ribbon runs into, so pixels at the
+  // tile edge are reconstructed from ground truth on both sides instead of only from
+  // the inside. Without this, adjacent tiles inpaint the same ribbon independently
+  // and disagree along the join.
+  const workCanvas = document.createElement("canvas");
+  workCanvas.width = W;
+  workCanvas.height = H;
+  const wc = workCanvas.getContext("2d");
+  if (!wc) throw new Error("no 2d context for work canvas");
+
+  if (pad > 0) {
+    const needed = marginsNeeded(maskData, W, H, pad);
+    const span = 2 ** coords.z;
+    const loads = [...needed].map(async (key) => {
+      const [dx, dy] = key.split(",").map(Number) as [number, number];
+      const ny = coords.y + dy;
+      if (ny < 0 || ny >= span) return;
+      const nx = ((((coords.x + dx) % span) + span) % span);
+      const nc = point(nx, ny) as unknown as Coords;
+      (nc as { z: number }).z = coords.z;
+      const im = await loadImage(a.tileUrl(nc), a.crossOrigin);
+      if (im) wc.drawImage(im, pad + dx * w, pad + dy * h, w, h);
+    });
+    await Promise.all(loads);
+  }
+  wc.drawImage(ctx.canvas, pad, pad, w, h);
+
+  // Throws SecurityError here if any tile server sent no CORS header.
+  const image = wc.getImageData(0, 0, W, H);
+  const data = image.data;
+
+  const todo = new Uint8Array(W * H);
+  let remaining = 0;
+  for (let i = 0; i < W * H; i += 1) {
+    if (maskData[i * 4 + 3]! > 32) {
+      todo[i] = 1;
+      remaining += 1;
+    }
+  }
+  if (!remaining) return;
+
+  // Fill inward from the edges of the ribbon: each pass writes only pixels that
+  // already have an unmasked neighbour, and every write is deferred to the end of the
+  // pass so a pass never reads its own output. Doing it in place instead would drag
+  // colour along the ribbon rather than across it.
+  const maxRounds = Math.ceil(ribbon) + 4;
+  const writes: number[] = [];
+  for (let round = 0; round < maxRounds && remaining > 0; round += 1) {
+    writes.length = 0;
+    for (let y = 0; y < H; y += 1) {
+      for (let x = 0; x < W; x += 1) {
+        const i = y * W + x;
+        if (!todo[i]) continue;
+        let r = 0;
+        let g = 0;
+        let b = 0;
+        let n = 0;
+        for (let k = 0; k < NEIGHBOURS.length; k += 1) {
+          const nx = x + NEIGHBOURS[k]![0];
+          const ny = y + NEIGHBOURS[k]![1];
+          if (nx < 0 || ny < 0 || nx >= W || ny >= H) continue;
+          const j = ny * W + nx;
+          if (todo[j]) continue;
+          r += data[j * 4]!;
+          g += data[j * 4 + 1]!;
+          b += data[j * 4 + 2]!;
+          n += 1;
+        }
+        if (n) writes.push(i, (r / n) | 0, (g / n) | 0, (b / n) | 0);
+      }
+    }
+    if (!writes.length) break;
+    for (let k = 0; k < writes.length; k += 4) {
+      const i = writes[k]!;
+      data[i * 4] = writes[k + 1]!;
+      data[i * 4 + 1] = writes[k + 2]!;
+      data[i * 4 + 2] = writes[k + 3]!;
+      todo[i] = 0;
+      remaining -= 1;
+    }
+  }
+
+  wc.putImageData(image, 0, 0);
+  ctx.drawImage(workCanvas, pad, pad, w, h, 0, 0, w, h);
+}
+
+export {
+  INDIA_BOUNDARY_SUPPRESSION,
+  SUPPRESSION_BBOX,
+  type SuppressionLine,
+  type SuppressionProperties,
+} from "./suppressionData.js";