# d3-geo

地图投影有时作为点的转换实现。比如球形墨卡托:

function mercator(x, y) {
  return [x, Math.log(Math.tan(Math.PI / 4 + y / 2))];
}

如果你的几何包含连续无限的点集时，这是一个合理的数学方法。然而，计算机并没有无限的内存，所以我们必须使用离散几何，比如多边形和折线!

离散几何使得从球面投影到平面更加困难。球面多边形的边缘是geodesics(测地线) (opens new window)great arc (opens new window)()的部分)，而不是直线。测地线投射到平面上，除了 gnomonic 之外所有的地图投影都是曲线，因此精确的投影需要沿每条弧插值。D3 使用 adaptive sampling(自适应采样) (opens new window)灵感来 line simplification method(线简化方法) (opens new window)，以平衡精度和性能。

多边形和折线的投影还必须处理球面与平面的拓扑差异。一些投影需要切割对向子午线 (opens new window) 的几何图形，而另一些投影则需要将几何图形 [裁剪为一great arc (opens new window)()](https://bl.ocks.org/mbostock/3021474)。

球面多边形还需要一个 winding order convention(缠绕顺序约定) (opens new window) 来确定多边形的哪边是内边: 小于半球的多边形的外环必须是顺时针方向, 而 larger than a hemisphere(大于半球的多边形的外环) (opens new window) 必须是逆时针的. 代表孔的内圈必须使用与其外圈的相反的环绕顺序。这种环绕规则也被 TopoJSON (opens new window) 和 ESRI shapefiles (opens new window) 采用。但是，它与 GeoJSON 的 RFC 7946 相反。(另请注意，标准 GeoJSON WGS84 使用平面的等距坐标，而不是球面坐标，因此可能需要 stitching (opens new window) 以去除对对向子午线的切割)。

D3的方法提供了很好的表现力: 你可以为你的数据选择正确的投影和样貌。D3 支持许多常见的投影以及特殊的地理投影 (opens new window). 更多信息可以参考工具制作指南 (opens new window).

D3 使用 GeoJSON (opens new window) 来表现地理特征. (也可以参考TopoJSON (opens new window), 一种更加紧密的对 GeoJSON 的编码). 可以使用 shp2geo (opens new window) 将 shape 文件转为 GeoJSON, 这是 shapefile package (opens new window) 的一部分. 有关 d3-geo 和相关工具的介绍，请参阅 Command-Line Cartography (opens new window).

# Installing

使用 NPM: npm install d3-geo. 此外还可以下载 latest release (opens new window). 可以直接从 d3js.org (opens new window) 以 standalone library (opens new window) 或作为 D3 4.0 (opens new window) 的一部分直接引入. 支持 AMD, CommonJS 和基础的标签引入形式. 如果使用标签引入会暴露 d3 全局变量:

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

var projection = d3.geoNaturalEarth1(),
    path = d3.geoPath(projection);

</script>

在浏览器中测试 d3-geo. (opens new window)

# API Reference

Paths
Projections (Azimuthal, Composite, Conic, Cylindrical)
Raw Projections
Spherical Math
Spherical Shapes
Streams
Transforms
Clipping

# Paths

地理路径生成器, d3.geoPath 与 d3-shape (opens new window) 很像: 给定一个 GeoJSON 或者特征对象，会生成一个 SVG 路径字符串，也可以将其渲染到 Canvas (opens new window) 上. 建议使用 Canvas 进行动态或者交互式投影以提高性能. 路径生成器可以与 projections 或 transforms 一起使用，或者可以直接将平面几何呈现到 Canvas 或 SVG 中.

# d3.geoPath([projection[, context]]) <> (opens new window)

使用默认的设置创建一个新的地理路径生成器. 如果指定了 projection, 则设置当前投影. 如果指定了 context 则设置当前当前上下文.

# path(object[, arguments…]) <> (opens new window)

渲染指定的 object, 可以是一个 GeoJSON 特征或者几何对象:

Point - 单个点.
MultiPoint - 一组点集.
LineString - 一组点集表示的连续的线.
MultiLineString - 组点集数组表示的多条线.
Polygon - 点集数组表示的多边形(可能有镂空).
MultiPolygon - 表示多个多边形的点集.
GeometryCollection - 一组几何对象.
Feature - 包含上述几何对象之一的特征.
FeatureCollection - 一组集合特征.

也支持类型为 Sphere, 在绘制地球轮廓时很有用; 球体没有坐标系. 任何额外的参数都会传递给 pointRadius 访问器.

显示多个特征时, 可以将其与特征集合结合:

svg.append("path")
    .datum({type: "FeatureCollection", features: features})
    .attr("d", d3.geoPath());

或者使用多个 path 元素:

svg.selectAll("path")
  .data(features)
  .enter().append("path")
    .attr("d", d3.geoPath());

多个 path 元素通常比单个 path 元素慢. 但是多个 path 在单独设置样式以及交互时很有用(比如点击和鼠标移入). Canvas 的渲染(可以参考path.context) 通常比 SVG 更快, 但是需要更多的精力去设置样式和交互.

# path.area(object) <> (opens new window)

返回指定的 GeoJSON 对象投影后的平面区域的面积(通常是平方像素). Point, MultiPoint, LineString 和 MultiLineString 面积为零. 对于 Polygon 和 MultiPolygon, 这个方法会首先计算外环的面积，然后减去镂空的面积. 这个方法遵循任何 projection 的裁剪; 参考 projection.clipAngle 和 projection.clipExtent. 这与 d3.geoBounds 的平面形式等价.

# path.bounds(object) <> (opens new window)

返回指定的 GeoJSON 对象投影后的平面包裹框(通常是像素). 包裹框被表示为一个二维数组: [[x₀, y₀], [x₁, y₁]], 其中 x₀ 是最小 x-坐标, y₀ 是最小 y-坐标, x₁ 是最大 x-坐标, and y₁ 是最大 y-坐标. 这对于缩放到特定的特性非常方便. (注意, 在投影平面坐标中, 最小纬度通常是最大 y 值, 而最大纬度通常是最小 y 值). 这个方法遵循任何 projection 的裁剪; 参考 projection.clipAngle 和 projection.clipExtent. 这与 d3.geoArea 的平面形式等价.

# path.centroid(object) <> (opens new window)

返回指定的 GeoJSON 对象投影后的平面质心(通常是像素). 这对于标记州或县的边界或显示符号非常方便. 例如非邻接统计地图 (opens new window) 可以以质心为中心进行缩放. 这个方法遵循任何 projection 的裁剪; 参考 projection.clipAngle 和 projection.clipExtent. 这与 d3.geoCentroid 的平面形式等价.

# path.measure(object) <> (opens new window)

返回指定的 GeoJSON 对象投影后的平面周长(通常是像素). Point, MultiPoint, LineString 和 MultiLineString 周长为零. 对于 Polygon 和 MultiPolygon, 这个方法会计算所有环的总长度. 这个方法遵循任何 projection 的裁剪; 参考 projection.clipAngle 和 projection.clipExtent. 这与 d3.geoLength 的平面形式等价.

# path.projection([projection]) <> (opens new window)

如果指定了 projection 则将当前投影设置为指定的投影. 如果没有指定 projection 则返回当前的投影, 默认为 null. null 投影表示一个恒等转换: 输入的集合不被计算, 而是直接在原始坐标中呈现. 这对于预投影 (opens new window) 来说省略了坐标计算因此速度更快, 或用于等矩形投影的快速绘制.

给定的 projection 通常是 D3 的内置地理投影; 但是任何暴露 projection.stream 函数的对象都可以被使用. 参考 D3 的 transforms 获取有关任意几何变换的更多例子.

# path.context([context]) <> (opens new window)

如果指定了 context 则将当前渲染上下设置为指定的 context 并返回当前路径生成器. 如果 context 为 null 则path generator 将返回 SVG 路径字符串; 如果 context 非 null 则路径生成器将调用指定上下文上的方法来呈现几何图形. 上下文必须实现 CanvasRenderingContext2D API (opens new window) 的以下子集:

context.beginPath()
context.moveTo(x, y)
context.lineTo(x, y)
context.arc(x, y, radius, startAngle, endAngle)
context.closePath()

如果没有指定 context 则返回当前的渲染上下文, 默认为 null.

# path.pointRadius([radius]) <> (opens new window)

如果指定了 radius 则将当前显示的 Point 和 MultiPoint 的半径设置为指定的数值. 如果没有指定 radius 则返回当前半径访问器, 默认为 4.5. 半径通常被指定为一个常数, 也可以被指定为一个返回数值的函数, 函数形式可以为每个特征单独计算半径值, 会传递 path generator 的参数. 例如, 如果你的 GeoJSON 数据有额外的数属性, 你可以使用访问器函数的形式去设置不同的半径; 也可以使用 d3.symbol (opens new window) 和 projection 来获取更大的灵活性.

# Projections

投影可以将球面多边形几何映射为平面多边形几何. D3 提供集中标准投影的实现:

Azimuthal(方位投影)
Composite(合成投影)
Conic(圆锥投影)
Cylindrical(圆柱投影)

更多投影参考 d3-geo-projection (opens new window). 你也可以使用 d3.geoProjection 或者 d3.geoProjectionMutator 实现自定义投影

# projection(point) <> (opens new window)

返回一个新的数组 [x, y](通常是像素) 来表示给定的 point 经过投影后的坐标. 给定的点必须是以度为单位的 [longitude, latitude] 形式. 如果给定的 point 没有定义投影位置则可能返回 null, 比如当点在投影的裁剪边界之外时.

# projection.invert(point) <> (opens new window)

根据指定的点坐标 [x, y](通常是像素) 计算出该点对应的经过投影前的以度为单位的坐标 [longitude, latitude](逆投影). 如果指定的点没有定义投影位置时可能返回 null, 例如当点在投影的裁剪边界之外时.

这种方法只定义在可逆投影上.

# projection.stream(stream) <> (opens new window)

为指定的输出 stream(流) 返回 projection stream(投影流). 任何输入的几何图形输出之前都会被投影. 一个典型的投影包括几个几何变换: 首先将输入几何图形转换为弧度, 三轴旋转, 裁剪或沿着对向子午线剪切, 最后通过自适应重采样, 缩放和平移投影到平面上.

# projection.preclip([preclip])

如果指定了 preclip 则将投影的球形裁剪设置为指定的裁剪函数并返回投影. 如果没有指定 preclip 则返回当前的预裁剪函数(参考 preclip).

# projection.postclip([postclip])

如果指定了 postclip, 则将投影的笛卡尔裁剪设置为指定的函数并返回投影. 如果没有指定 postclip 则返回当前的笛卡尔坐标裁剪(参考 postclip).

# projection.clipAngle([angle]) <> (opens new window)

如果指定了 angle 则以度为单位设置投影的裁剪角度并返回投影. 如果 angle 为 null 则切换为对向子午线裁剪 (opens new window) 而不是 small-circle 裁剪. 如果没有指定 angle 则返回当前的裁剪角度, 默认为 null. small-circle 独立于通过 projection.clipExtent 定义的视窗裁剪.

可以参考 projection.preclip, d3.geoClipAntimeridian, d3.geoClipCircle.

# projection.clipExtent([extent]) <> (opens new window)

如果指定了 extent 则将投影的视窗裁剪范围设置为指定的像素包裹框并返回投影. extent 以数组 [[x₀, y₀], [x₁, y₁]] 的形式指定, 其中 x₀ 为视窗的左侧坐标, y₀ 为顶部, x₁ 为右侧, y₁ 为底部坐标. 如果 extent 为 null 则不会执行视窗裁剪. 如果 extent 没有指定则返回当前的视窗裁剪范围, 默认为 null. 视窗裁剪独立于通过 projection.clipAngle 设置的 small-circle 裁剪.

参考 projection.postclip, d3.geoClipRectangle.

# projection.scale([scale]) <> (opens new window)

如果指定了 scale 则将投影的缩放因子设置为指定的值并返回投影. 如果没有指定 scale 则返回当前的缩放因子, 默认的缩放因子由具体的投影方式决定. 缩放因子与投影点之间的距离成线性关系; 但是在不同的投影中不同.

# projection.translate([translate]) <> (opens new window)

如果指定了 translate 则将投影的平移偏移量设置为指定的二元数组 [t_x, t_y] 并返回投影. 如果没有指定 translate 则返回当前的平移偏移, 默认为 [480, 250]. 平移偏移量决定了投影中心的像素坐标. 默认的平移偏移量将 ⟨0°,0°⟩ 放置在 960×500 的区域中心.

# projection.center([center]) <> (opens new window)

如果指定了 center 则将投影的中心设置为指定的以度为单位的 longitude 和 latitude 组成的二元数组 center 并返回投影. 如果没有指定 center 则返回当前的投影中心, 默认为 ⟨0°,0°⟩.

# projection.angle([angle]) <> (opens new window)

如果指定了 angle 则将投影后的旋转角度设置为指定的以度为单位的角度并返回投影. 如果没有指定 angle 则返回当前投影角度, 默认为 0°. 注意, 在渲染期间旋转(比如使用 context.rotate (opens new window)) 可能比通过投影旋转更快.

# projection.rotate([angles]) <> (opens new window)

如果指定了 rotation 则将投影的三轴球形旋转 (opens new window) 设置为指定的 angles, 角度必须是包含两个或三个元素的表示旋转角度的数组 [lambda, phi, gamma] 用以表示每个球面轴 (opens new window). (分别对应偏航，俯仰和横滚 (opens new window)) 如果 gamma 没有指定则默认为 0. d3.geoRotation 也同理. 如果没有指定 rotation 则返回当前的角度默认为 [0, 0, 0].

# projection.precision([precision]) <> (opens new window)

如果指定了 precision 则将投影的自适应重采样阈值设置为指定的像素值并返回投影. 这个值对应 Douglas–Peucker (opens new window) 距离. 如果 precision 没有指定则返回投影当前的采样精度, 默认为 √0.5 ≅ 0.70710…

# projection.fitExtent(extent, object) <> (opens new window)

调整投影的 scale 和 translate 使给定的 GeoJSON object 适应在 extent 范围中. extent 以 [[x₀, y₀], [x₁, y₁]] 的形式指定, 其中 x₀ 为包裹框的左边界, y₀ 为上边界, x₁ 为右边界, y₁ 为下边界. 返回投影.

例如, 对 New Jersey State Plane projection (opens new window) 进行缩放和平移以将 GeoJSON 对象 nj 位于 960×500 的包裹框内, 并设置边距为 20:

var projection = d3.geoTransverseMercator()
    .rotate([74 + 30 / 60, -38 - 50 / 60])
    .fitExtent([[20, 20], [940, 480]], nj);

在确定了缩放和平移之后, 任何 clip extent 将会被忽略. 用来计算给定对象包裹框的 precision 计算的有效等级为 150.

# projection.fitSize(size, object) <> (opens new window)

projection.fitExtent 的便捷用法, 其中左上角坐标为 [0, 0]. 下面两个用法是等效的:

projection.fitExtent([[0, 0], [width, height]], object);
projection.fitSize([width, height], object);

# projection.fitWidth(width, object) <> (opens new window)

projection.fitSize 的便捷用法, 其中高度是根据对象的宽高比和宽度自动计算的.

# projection.fitHeight(height, object) <> (opens new window)

projection.fitSize 的便捷用法, 其中宽度是根据对象的宽高比和高度自动计算的.

# Azimuthal Projections

方位投影把球体直接投射到平面上.

# d3.geoAzimuthalEqualArea() <> (opens new window)
# d3.geoAzimuthalEqualAreaRaw

# d3-geo

# Installing

# API Reference

# Paths

# Projections

# Azimuthal Projections

# Composite Projections

# Conic Projections

# Cylindrical Projections

# Raw Projections

# Spherical Math

# Spherical Shapes

# Streams

# Transforms

# Clipping