d3-contour

此库通过将marching squares应用于一个由数值组成的矩形数组来计算轮廓多边形。例如这是Maungawhau的拓补结构（来自R的经典volcano数据集和terrain.colors）：

对于每个阈值，等值线生成器构造一个GeoJSON MultiPolygon几何对象，表示输入值大于或等于阈值的区域。几何形状处于平面坐标中，其中⟨ i + 0.5，j +0.5⟩对应输入数值数组中的元素i + jn。下面是一个加载GeoTIFF表面温度的例子和一个通过模糊噪波单色PNG来产生云团部分平滑等值线的例子：

由于等值线多边形是GeoJSON，因此可以使用标准工具对它们进行转换和显示; 例如，另请参阅d3.geoPath，d3.geoProject和d3.geoStitch。将上面的表面温度等值线显示在自然地球投影中：

等值线图还可以通过采样来可视化连续函数。这是Goldstein-Price函数（用于全局优化的测试函数）和sin(x + y)sin(x - y)的简单动画：

等值线还可以显示点云的估计密度，这对避免在大型数据集中出现重叠绘图特别有用。此库实现了快速的二维核密度估计；另请参阅d3.contourDensity。下面是散点图，展示了Old Faithful（老实泉，美国黄石国家公园的一处景点）的间歇时间和爆发时间之间的关系：

这是密度等值线图，展示了53,940颗钻石的重量和价格之间的关系：

Installing

如果你使用npm，请键入npm install d3-contour。否则，请下载最新版本。你也可以直接从d3js.org加载，作为standalone library（独立库）或D3 4.0的一部分来使用。支持AMD，CommonJS和vanilla环境。在vanilla环境下，会输出一个全局的d3：

<script src="https://d3js.org/d3-contour.v1.min.js"></script>
<script>

// Populate a grid of n×m values where -2 ≤ x ≤ 2 and -2 ≤ y ≤ 1.
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, ++k) {
    values[k] = goldsteinPrice(i / n * 4 - 2, 1 - j / m * 3);
  }
}

// Compute the contour polygons at log-spaced intervals; returns an array of MultiPolygon.
var contours = d3.contours()
    .size([n, m])
    .thresholds(d3.range(2, 21).map(p => Math.pow(2, p)))
    (values);

// See https://en.wikipedia.org/wiki/Test_functions_for_optimization
  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));
}

</script>

API Reference

d3.contours()

使用默认配置构建一个新的等值线生成器。

contours(values)

计算给定values数组的等值线，返回一个由GeoJSON MultiPolygon geometry objects组成的数组。每个几何对象都表示输入值大于或等于对应阈值的区域；每个几何对象的阈值暴露为geometry.value。

输入的values必须是一个长度为n×m的数组，其中[n, m]为此等高线生成器的大小；另外，每个values[i + jn]必须表示位置⟨i, j⟩的值。例如，为Goldstein–Price function构建一个256×256的网格，其中-2 ≤ x ≤ 2且-2 ≤ y ≤ 1：

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, ++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));
}

返回的几何对象通常会被传入d3.geoPath来展示，使用null或d3.geoIdentity作为关联的投影。

contours.contour(values, threshold)

计算单条等值线，返回一个由GeoJSON MultiPolygon geometry objects组成的数组。每个几何对象都表示输入值大于或等于对应阈值的区域；每个几何对象的阈值暴露为geometry.value。

输入的values必须是一个长度为n×m的数组，其中[n, m]为此等值线生成器的大小；另外，每个values[i + jn]必须表示位置⟨i, j⟩的值。另请参阅contours了解更多。

contours.size([size])

如果指定了size，则设置输入values网格的期望大小到等值线生成器并返回此等值线生成器。size指定为一个数组[n, m]，其中n表示网格中列的数量，而m表示网格中行的数量；n和m必须为正整数。如果不指定size，则返回当前的大小，默认为[1, 1]。

contours.smooth([smooth])

如果指定了smooth，则设置是否使用线性插值来平滑生成的等值线多边形。如果不指定smooth，则返回当前的平滑标志，默认为true。

contours.thresholds([thresholds])

如果指定了thresholds，则设置阈值生成器为给定的函数或数组，并返回此等值线生成器。如果不指定thresholds，则返回当前的阈值生成器，默认通过Sturges’ formula实现。

阈值定义为一个数值数组[x0, x1, …]，第一条生成的等值线对应输入值大于或等于x0的区域；第二条等值线对应于输入值大于或等于x1的区域，以此类推。因此，对于每个指定的阈值，只有生成一个MultiPolygon几何对象；阈值暴露为geometry.value。

如果指定的是count而不是thresholds，则输入值的范围会被均匀的划分为大约count个区间；另请参阅d3.ticks。

Density Estimation

d3.contourDensity()

使用默认配置构建一个新的密度估计器。

density(data)

估计给定data数组的密度等值线，返回一个由GeoJSON MultiPolygon geometry objects组成的数组。

每个几个对象都表示每平方像素的估计点数大于或等于相应阈值的区域；每个几何对象的阈值都暴露为geometry.value。返回的几个对象通常会被传入d3.geoPath用于展示，使用null或d3.geoIdentity作为关联的投影。另请参阅d3.contours。

每个数据点的x坐标和y坐标都使用density.x和density.y计算。每个生成的等值线只在估计器定义的大小内精确。

density.x([x])

如果指定了x，则设置x坐标访问器。如果不指定x，则返回当前的x坐标访问器，默认为：

function x(d) {
  return d[0];
}

density.y([y])

如果指定了y，则设置y坐标访问器。如果不指定y，则返回当前的y坐标访问器，默认为：

function y(d) {
  return d[1];
}

density.size([size])

如果指定了size，则设置密度估计器的大小为给定的边界，并返回此估计器。如果指定size为一个数组[width, height]，则其中width为最大的x值，而height为最大的y值。如果不指定size，则返回当前的大小，默认为 [960, 500]。估计密度等值线只在定义的大小内精确。

density.cellSize([cellSize])

如果指定了cellSize，则设置底层网格的单个单元格为给定的正值，并返回此估计器。如果不指定sellSize，则返回当前的单元格大小，默认为4。单元格大小会舍入到接近2的幂。较小的单元格会产生更多详细的轮廓多边形，但计算起来会很吃力。

density.thresholds([thresholds])

如果指定了thresholds，则设置阈值生成器为给定的函数或数组，并返回此等高线生成器。如果不指定thresholds，则返回当前的阈值生成器，默认生成大约20个良好舍入的密度阈值。

阈值定义为一个数值数组[x0, x1, …]，第一条生成的密度等值线对应输入值大于或等于x0的区域；第二条等值线对应于输入值大于或等于x1的区域，以此类推。因此，对于每个指定的阈值，只有生成一个MultiPolygon几何对象；阈值暴露为geometry.value。第一个值x0通常应该大于0。

如果指定的是count而不是thresholds，则输入值的范围会被均匀的划分为大约count个区间；另请参阅d3.ticks。

density.bandwidth([bandwidth])

如果指定了bandwidth，则设置高斯核的带宽（标准差）并返回此估计。如果不指定bandwidth，则返回当前的带宽，默认为20.4939…。指定的bandwidth目前通过此实现舍入到最近支持的值，且必须是非负的。

Contours (d3-contour)