D3 等高线多边形生成详解：d3-contour 的 contours API、Marching Squares 原理与完整参数

本篇技术指南以 D3 官方文档中的 Contour polygons 章节为主体，系统讲解 d3-contour 模块如何通过 Marching Squares（行进方格）算法，将一张矩形数值网格转换为 GeoJSON MultiPolygon 等高线多边形。读完本文，你将能够：使用 d3.contours() 生成器对任意数值网格（如地表温度栅格、采样后的连续函数）计算等高线，正确配置 size、smooth、thresholds 等参数，并把结果交给 geoPath 渲染为 SVG。

一、d3-contour 在 D3 中的位置

D3 主包通过聚合各子模块对外提供统一 API。从 src/index.js 可以看到，主包直接 export * from "d3-contour"，因此引入 D3 后可以直接使用 d3.contours 与 d3.contourDensity 两个入口函数。当前仓库 package.json 声明的版本为 d3 7.9.0，其依赖中 d3-contour 为 ^4.0.2，本文所有 API 说明均以此版本为适用前提。

模块总览页面 docs/d3-contour.md 给出了模块的一句话定位：对矩形数值网格应用 Marching Squares 算法计算等高线多边形，并以火山 Maungawhau（Mount Eden）地形数据配合 Observable Plot 的 Plot.contour 做了可视化示例（数据见 docs/data/volcano.data.js）。该页面将文档拆分为两个部分：

• Contours：对已有数值网格求等高线，即本文主题；
• Density estimation：对散点数据做二维核密度估计后再生成等高线。

D3 v4 的发布说明（见 CHANGES.md）也印证了这一点：marching squares 与密度估计是通过独立的 d3-contour 模块引入 D3 生态的。完整的 API 索引收录在 docs/api.md 中。

二、核心输出：每个阈值对应一个 GeoJSON MultiPolygon

d3.contours 的工作契约非常明确：对每一个阈值（threshold）值，生成器构造一个 GeoJSON MultiPolygon 几何对象，表示输入值大于或等于该阈值的区域。几何位于平面坐标中，其中点 ⟨i + 0.5, j + 0.5⟩ 对应输入数组中的元素 values[i + j*n]（n 为列数）。

这一设计带来三个直接好处：

1. 输出即标准 GeoJSON。MultiPolygon 是 GeoJSON 规范中的标准几何类型，可以交给任意标准地理工具链做变换与展示，例如 geoPath（见 docs/d3-geo/path.md）、geoProject 与 geoStitch。官方示例中，地表温度等高线先以平面坐标生成，再经 Natural Earth 投影重投影展示。
2. 每个几何对象自带 value 属性。阈值值暴露在 geometry.value 上，因此着色（如 fill = d => colorScale(d.value)）无需额外查表。
3. 输入输出解耦。网格可以是任意来源的采样值：GeoTIFF 地表温度、云量 PNG 经模糊后的灰度值、或任意连续函数的采样值。官方演示覆盖了 Goldstein–Price 全局优化测试函数的等高线，以及 sin(x + y) * sin(x - y) 的动画等高线。

三、生成器与调用入口

d3.contours()

创建带有默认设置的新等高线生成器：

const contours = d3.contours()
    .size([width, height])
    .thresholds([0, 1, 2, 3, 4]);

生成器采用链式访问器模式：不传参数时各访问器返回当前值，传入参数时设置并返回生成器本身，方便链式调用。

contours(values)

调用生成器计算全部等高线，返回 GeoJSON MultiPolygon 几何对象数组：

const polygons = contours(grid);

每个几何对象表示输入 values 大于或等于对应阈值的区域，阈值即 geometry.value。该调用链对应源码实现 src/contours.js（位于 d3-contour 包内，由主包聚合导出）。

contours.contour(values, threshold)

只计算单个阈值对应的等高线，返回一个 MultiPolygon 几何对象，其 value 为该阈值。适合在动画或交互场景中，逐帧重算某一条等高线而不必重新计算整组阈值；contourDensity 数据上也有对应的 density.contours(data) 方法，可返回可复用的单阈值 contour(value) 函数并暴露网格最大密度 contour.max。

四、输入值网格的布局约定（重点）

这是使用 d3.contours 时最容易踩坑的地方。输入 values 必须满足：

• 长度为 n×m，其中 [n, m] 是生成器的 size；
• values[i + j*n] 表示位置 ⟨i, j⟩ 的值——即行主序中先按行存储，索引 = 列 + 行×列数。

官方文档给出的完整示例：构造 256×256 网格，采样定义在 -2 ≤ x ≤ 2、-2 ≤ y ≤ 1 上的 Goldstein–Price 函数（注意循环从 0.5 开始，使采样点落在单元格中心，与几何坐标 ⟨i + 0.5, j + 0.5⟩ 的约定一致）：

var n = 256, m = 256, values = new Array(n * m);
for (var j = 0.5, k = 0; j < m; ++j) {
  for (var i = 0.5; i < n; ++i, ++i, ++k) {
    values[k] = goldsteinPrice(i / n * 4 - 2, 1 - j / m * 3);
  }
}

function goldsteinPrice(x, y) {
  return (1 + Math.pow(x + y + 1, 2) * (19 - 14 * x + 3 * x * x - 14 * y + 6 * x * x + 3 * y * y))
      * (30 + Math.pow(2 * x - 3 * y, 2) * (18 - 32 * x + 12 * x * x + 48 * y - 36 * x * y + 27 * y * y));
}

注：以上循环写法严格遵循原文档代码；如果你的网格来源（如图像像素、DEM 栅格）是列主序或 y 轴向下增长，需要先做索引重排，否则等高线会整体错位或上下翻转。

返回的几何对象通常传给 geoPath（docs/d3-geo/path.md）渲染，关联投影使用 null 或 geoIdentity（docs/d3-geo/projection.md）——因为等高线本身就在平面坐标下，不需要地球投影。

五、生成器参数详解

contours.size(size)

设置输入 values 网格的预期尺寸。size 为数组 [n, m]，n 是网格列数（columns），m 是行数（rows），且 n、m 必须是正整数。不传参时返回当前尺寸，默认值为 [1, 1]。

从源码约定看，size 决定了每个单元格的平面几何范围：网格共 n×m 个单元格，每个单元格占据单位面积，顶点坐标为整数、中心为半整数。因此 size 必须与实际数组长度的行列切分严格一致，否则输出多边形会错位或越界。

contours.smooth(smooth)

设置是否对生成的等高线多边形做平滑。当 smooth 为 true（默认值）时，算法在单元格边界的交点处使用线性插值，让等高线穿过格点边界的连续位置而不是沿网格台阶状折线；设为 false 则得到阶梯状的精确边界。是否平滑直接决定视觉风格：对连续函数（如温度场）用默认平滑即可，对栅格化程度明显的原始数据可按需关闭。

contours.thresholds(thresholds)

设置阈值生成器，可以传入函数或数组；不传参时返回当前阈值生成器。默认实现为 Sturges 公式（即 d3-array 的 d3.thresholdSturges，见 docs/d3-array/bin.md），它会根据数据点数自动给出约 ⌈log₂n⌉ + 1 个阈值。

阈值的行为规则：

• 阈值是数组 [*x0*, *x1*, …]。第 k 个生成的 MultiPolygon 表示输入值 ≥ xk 的区域，阈值值暴露在 geometry.value；
• 每个阈值恰好生成一个几何对象，输出数组与阈值数组一一对应；
• 如果传入的是数字 count 而不是数组，则输入值的取值范围（extent，见 docs/d3-array/summarize.md）会被均匀划分为约 count 个 bin，内部使用 ticks 生成整洁的刻度值（见 docs/d3-array/ticks.md）。

六、从散点数据出发：与 contourDensity 的衔接

contours 处理的是已有的数值网格。如果你的数据是散点（如 53,940 颗钻石的重量-价格、Old Faithful 间歇泉的喷发时长-间隔时长），则应使用同模块的 d3.contourDensity 做快速二维高斯核密度估计，再得到等高线，从而避免大数据集的重叠绘制（overplotting）。密度估计器的关键参数（详见 docs/d3-contour/density.md）包括：

• x / y：坐标访问器，默认分别取 d[0]、d[1]；
• weight：点权重访问器，默认 1；
• size：估计器范围 [width, height]，默认 [960, 500]，等高线仅在定义尺寸内精确；
• cellSize：底层 bin 网格单元大小，默认 4，向下取整到最近的 2 的幂；
• thresholds：默认生成约 20 个整洁阈值；
• bandwidth：高斯核带宽（标准差），默认 20.4939…，实现会将其取整到最近的支持值，且必须非负。

两条路径共享同一套 Marching Squares 内核与 GeoJSON 输出格式，区别只在数值网格的来源：直接给定 vs. 核密度估计。

七、完整使用范式

结合以上各节，一个可复制的完整流程如下：

import * as d3 from "d3";

// 1. 准备 n×m 数值网格，values[i + j * n] 为位置 ⟨i, j⟩ 的值
const n = 256, m = 256;
const values = new Array(n * m);
for (let j = 0.5, k = 0; j < m; ++j) {
  for (let i = 0.5; i < n; ++i, ++k) {
    values[k] = Math.sin(i / n * Math.PI) * Math.cos(j / m * Math.PI);
  }
}

// 2. 配置生成器：尺寸 + 阈值（数组或 count 均可）
const contours = d3.contours()
    .size([n, m])
    .thresholds(9);          // 约 9 个整洁阈值；或显式传入 [0.1, 0.2, …]

// 3. 计算等高线：每个对象是带 value 的 GeoJSON MultiPolygon
const polygons = contours(values);

// 4. 用平面投影渲染（等高线本身即平面坐标）
const path = d3.geoPath(null);   // 或 d3.geoIdentity()
for (const polygon of polygons) {
  console.log(polygon.value, path(polygon));
}

要点复核：

参数	默认值	说明
size	[1, 1]	[n, m] 列数×行数，须为正整数，且与数组长度的行列切分一致
smooth	true	true 时在格点边界用线性插值平滑等高线
thresholds	Sturges 公式	数组 → 一阈值一 MultiPolygon；数字 → 用 ticks 均匀分箱
输出	—	GeoJSON MultiPolygon 数组，geometry.value 为阈值

八、小结

d3-contour 的核心价值在于：用 Marching Squares 把"矩形数值网格 → 等高线"这一 GIS 常见操作纳入了 D3 的标准工具链，输出为标准 GeoJSON MultiPolygon 且自带阈值 value，可无缝衔接 geoPath/投影变换/d3-scale 着色体系。使用时的三个关键约定必须记牢：输入索引布局 values[i + j*n]、size 与实际网格严格一致、每个阈值恰好产出一个多边形对象。需要处理散点数据时，切换到 contourDensity 即可复用同一套输出格式。

主要参考文件：docs/d3-contour/contour.md、docs/d3-contour/density.md、docs/d3-contour.md、docs/api.md、src/index.js、package.json。