holeify-contour

Convert d3-contour output into hole-aware GeoJSON polygons.

Why?

d3-contour (d3.contours(), d3.contourDensity()) outputs contours as MultiPolygon, but every ring is independent — there is no topological relationship (containment / holes). When you open the result in GIS tools like QGIS, polygons simply overlap without any holes punched through.

holeifyContour detects spatial containment between rings and reconstructs them into proper GeoJSON polygons with holes, ready for use in QGIS, Mapbox, Leaflet, or any GeoJSON-compatible tool.

Holeify your contours! 🕳️

Before → After

Before (d3-contour output)          After (holeifyContour)
┌─────────────────────┐           ┌─────────────────────┐
│ value=10            │           │ value=10            │
│  ┌───────────────┐  │           │  ┌ ─ ─ ─ ─ ─ ─ ─┐   │
│  │ value=20      │  │    →      │  │ (hole)       │   │
│  │               │  │           │  │              │   │
│  └───────────────┘  │           │  └ ─ ─ ─ ─ ─ ─ ─┘   │
└─────────────────────┘           └─────────────────────┘
   Overlapping polygons              Polygon with hole

Install

npm install holeify-contour

Usage

import { contours } from "d3-contour";
import { holeifyContour } from "holeify-contour";

// 1. Generate contours from your grid data
const generator = contours()
  .size([width, height])
  .thresholds([0, 10, 20, 30, 40, 50]);

const contourResult = generator(gridData);

// 2. Wrap as FeatureCollection<MultiPolygon>
const fc = {
  type: "FeatureCollection",
  features: contourResult.map((c) => ({
    type: "Feature",
    geometry: c,
    properties: { value: c.value },
  })),
};

// 3. Convert to hole-aware GeoJSON
const result = holeifyContour(fc);
// result: FeatureCollection<MultiPolygon>
// Each feature is grouped by value, with proper holes

API

holeifyContour(fc, toSortedAndMergedMultiPolygon?)

| Parameter | Type | Default | Description | | ------------------------------- | --------------------------------- | ------- | ----------------------------------------------------------------------------- | | fc | FeatureCollection<MultiPolygon> | — | d3-contour output | | toSortedAndMergedMultiPolygon | boolean | true | true: group by value into MultiPolygon. false: return individual Polygons |

Input Requirements

• FeatureCollection<MultiPolygon> format
• Each feature must have a numeric properties.value (contour level)

Algorithm

1. Decompose each MultiPolygon into individual rings, sorted by area (smallest first)
2. Find a representative interior point for each ring and insert it into a d3-quadtree
3. Iterate from smallest ring to largest. For each ring:
   • Query the quadtree to find candidate points within the bounding box
   • Run point-in-polygon to confirm actual containment
   • Assign confirmed children as holes of this ring
   • Remove assigned children from the quadtree so they are invisible to larger rings
4. (Optional) Group by contour value and merge into MultiPolygons

The key trick is step 3's quadtree removal. Without it, a grandparent ring would also claim grandchildren as direct holes, breaking the topology. By removing each ring from the quadtree once its parent is determined, only the immediate parent-child relationship is captured. This also makes the algorithm fast — each ring is visited at most once, and the quadtree narrows candidates from O(n) to the local neighborhood.

Benchmark

Run the benchmark script in sample/:

node sample/bench.mjs

| Dataset | Grid Size | Rings | d3-contour | holeifyContour | Total | Output Polygons | Holes | | ------- | ------------- | ------ | ---------- | -------------- | -------- | --------------- | ------ | | small | 82 x 73 | 209 | 6 ms | 5 ms | 11 ms | 191 | 190 | | medium | 380 x 359 | 1,993 | 54 ms | 51 ms | 105 ms | 1,828 | 1,827 | | large | 964 x 1,254 | 14,512 | 714 ms | 524 ms | 1,238 ms | 13,977 | 13,976 | | xlarge | 1,353 x 2,018 | 16,488 | 1,218 ms | 738 ms | 1,956 ms | 15,866 | 15,865 |

Measured with node sample/bench.mjs. Times may vary by hardware.

Export to GeoJSON

Save the holeified result as a .geojson file:

node sample/toGeojson.mjs small

Outputs sample/small_result.geojson. Available datasets: small, medium, large, xlarge.

Alternatives

No existing library solves this specific problem — reconstructing cross-threshold hole topology from d3-contour output. Here's how related tools compare:

| Library | What it does | Cross-level holes? | |---------|-------------|:------------------:| | d3-contour | Generates contours; handles holes within a single threshold level only | No | | topojson-client | Merges polygons via shared arcs (TopoJSON) | No | | @mapbox/geojson-rewind | Fixes winding order; assumes holes are already assigned | No | | polygon-clipping | Boolean ops (union/diff) on polygons; could work indirectly but slow and complex | Indirect | | Turf.js | GIS utilities; no module for contour ring nesting | No | | MarchingSquares.js | Marching squares output as flat paths, no hole structure | No | | contour-wasm | WASM-based marching squares, no hole structure | No |

d3-contour processes each threshold level independently — a value=20 polygon inside a value=10 polygon is output as a separate feature, not as a hole. holeifyContour fills this gap by detecting spatial containment across all threshold levels using quadtree-accelerated point-in-polygon tests.

License

MIT