企业官网建设流程全解析

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

【免费下载链接】d3Bring data to life with SVG, Canvas and HTML. :bar_chart::chart_with_upwards_trend::tada:项目地址: https://gitcode.com/GitHub_Trending/d3/d3

本篇技术指南以 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)); }

要点复核：

八、小结

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。

【免费下载链接】d3Bring data to life with SVG, Canvas and HTML. :bar_chart::chart_with_upwards_trend::tada:项目地址: https://gitcode.com/GitHub_Trending/d3/d3