D3

投影 ​

🌐 Projections

投影将球面多边形几何转换为平面多边形几何。D3 提供了几类标准投影的实现：

🌐 Projections transform spherical polygonal geometry to planar polygonal geometry. D3 provides implementations of several classes of standard projections:

有关更多投影，请参见 d3-geo-projection 和 d3-geo-polygon。你可以使用 geoProjection 或 geoProjectionMutator 实现 自定义投影。

🌐 For more projections, see d3-geo-projection and d3-geo-polygon. You can implement custom projections using geoProjection or geoProjectionMutator.

投影(点) ​

🌐 projection(point)

来源 · 返回一个新的数组 [x, y]（通常以像素为单位），表示给定 point 的投影点。该点必须以两个元素的数组 [longitude, latitude]（以度为单位）指定。如果指定的 point 没有定义的投影位置，例如当点位于投影的裁剪边界之外时，可能返回 null。

projection.invert(point) ​

来源 · 返回一个新的数组 [经度, 纬度]（以度为单位），表示给定投影 point 的未投影点。该点必须以一个包含两个元素的数组 [x, y] 形式指定（通常以像素为单位）。如果指定的 point 没有定义的投影位置，例如当点位于投影的裁剪边界之外时，可能返回 null。

此方法仅在可逆投影上定义。

🌐 This method is only defined on invertible projections.

projection.stream(stream) ​

Source · 为指定的输出流返回一个投影流。任何输入几何体在被流式传输到输出流之前都会被投影。典型的投影涉及多个几何变换：输入几何体首先被转换为弧度，在三个轴上旋转，裁剪到小圆或沿子午线切割，最后通过自适应重采样、缩放和平移投影到平面上。

projection.preclip(preclip) ​

如果指定了 preclip，则将投影的球面剪裁设置为指定的函数并返回该投影；preclip 是一个函数，它接受一个 投影流 并返回一个剪裁后的流。如果未指定 preclip，则返回当前的球面剪裁函数。预剪裁通常用于沿反经线或沿小圆进行切割。

🌐 If preclip is specified, sets the projection’s spherical clipping to the specified function and returns the projection; preclip is a function that takes a projection stream and returns a clipped stream. If preclip is not specified, returns the current spherical clipping function. Preclipping is commonly used to cut along the antimeridian line or along a small circle.

projection.postclip(postclip) ​

如果指定了 postclip，则将投影的笛卡尔裁剪设置为指定的函数并返回该投影；postclip 是一个函数，它接受一个 投影流 并返回一个裁剪后的流。如果未指定 postclip，则返回当前的笛卡尔裁剪函数。后裁剪发生在平面上，当投影被限制在某个范围内（例如矩形）时。

🌐 If postclip is specified, sets the projection’s Cartesian clipping to the specified function and returns the projection; postclip is a function that takes a projection stream and returns a clipped stream. If postclip is not specified, returns the current Cartesian clipping function. Post-clipping occurs on the plane, when a projection is bounded to a certain extent such as a rectangle.

projection.clipAngle(angle) ​

来源 · 如果指定了 angle，则将投影的裁剪圆半径设置为指定的角度（以度为单位），并返回该投影。如果 angle 为 null，则切换为反经线裁剪而不是小圆裁剪。如果未指定 angle，则返回当前的裁剪角度，默认值为 null。小圆裁剪独立于通过 projection.clipExtent 的视口裁剪。另见 projection.preclip、geoClipAntimeridian、geoClipCircle。

projection.clipExtent(extent) ​

[来源]（https://github.com/d3/d3-geo/blob/main/src/projection/index.js） ·如果指定了范围，则将投影的视口剪辑范围设置为指定的像素界限，并返回投影。范围边界指定为数组 [[x₀， y₀]，[x₁， y₁]]，其中 x₀ 是视口的左侧， y₀ 是顶部， x₁ 是右侧， y₁ 是底部。如果extent为空，则不会进行视口裁剪。如果未指定范围，则返回当前视口剪辑范围，默认为空。视口裁剪与通过[投影.clipAngle]（#projection_clipAngle）小圆裁剪是独立的。另见 [投影.postclip]（#projection_postclip）、[geoClipRectangle]（#geoClipRectangle）。

projection.scale(scale) ​

来源 · 如果指定了 scale，则将投影的缩放因子设置为指定值并返回该投影。如果未指定 scale，则返回当前的缩放因子；默认缩放因子取决于具体投影。缩放因子与投影点之间的距离成线性关系；然而，不同投影的绝对缩放因子不相等。

projection.translate(translate) ​

来源 · 如果指定了 translate，则将投影的平移偏移设置为指定的两元素数组 [tx, ty] 并返回该投影。如果未指定 translate，则返回当前的平移偏移，默认值为 [480, 250]。平移偏移决定投影 中心 的像素坐标。默认的平移偏移将 ⟨0°,0°⟩ 放置在 960×500 区域的中心。

projection.center(center) ​

来源 · 如果指定了 center，则将投影的中心设置为指定的 center，它是一个包含 [经度, 纬度] 的两元素数组（单位为度），并返回该投影。如果未指定 center，则返回当前中心，默认为 ⟨0°,0°⟩。

projection.angle(angle) ​

Source · 如果指定了 angle，则将投影的投影后平面旋转角度设置为指定的 angle（以度为单位），并返回该投影。如果未指定 angle，则返回投影的当前角度，默认为 0°。请注意，在渲染过程中旋转（例如，使用 context.rotate）可能比在投影过程中旋转更快。

projection.reflectX(reflect) ​

如果指定了 reflect，则设置输出中 x 维度是否反射（取反）。如果未指定 reflect，则如果启用了 x 反射则返回 true，默认为 false。这对于从下方观察天体显示天空和天文数据可能很有用：当北方朝上时，赤经（东方方向）将指向左侧。

🌐 If reflect is specified, sets whether or not the x-dimension is reflected (negated) in the output. If reflect is not specified, returns true if x-reflection is enabled, which defaults to false. This can be useful to display sky and astronomical data with the orb seen from below: right ascension (eastern direction) will point to the left when North is pointing up.

projection.reflectY(reflect) ​

如果指定了 reflect，则设置输出中 y 维度是否被反射（取反）。如果未指定 reflect，则返回 y 反射是否启用，默认值为 false。这对于从标准的 空间参考系统（将正 y 视为向上）转换到显示坐标系统（如 Canvas 和 SVG，将正 y 视为向下）特别有用。

🌐 If reflect is specified, sets whether or not the y-dimension is reflected (negated) in the output. If reflect is not specified, returns true if y-reflection is enabled, which defaults to false. This is especially useful for transforming from standard spatial reference systems, which treat positive y as pointing up, to display coordinate systems such as Canvas and SVG, which treat positive y as pointing down.

projection.rotate(angles) ​

来源 · 如果指定了 angles，则将投影的 三轴球面旋转 设置为指定的值，该值必须是一个包含两或三项数字的数组 [lambda、phi、gamma]，用于指定关于 每个球面轴 的旋转角度（以度为单位）。 （这些对应于 偏航、俯仰和滚转。）如果省略旋转角度 gamma，则默认为 0。另见 geoRotation。如果未指定 angles，则返回当前旋转，默认值为 [0, 0, 0]。

projection.precision(precision) ​

来源 · 如果指定了 precision，则将投影的 自适应重采样 阈值设置为指定的像素值，并返回投影。该值对应于 Douglas–Peucker 距离。如果未指定 precision，则返回投影当前的重采样精度，默认值为 √0.5 ≅ 0.70710…

projection.fitExtent(extent, object) ​

[来源]（https://github.com/d3/d3-geo/blob/main/src/projection/index.js） ·将投影的[比例]（#projection_scale）和[translate]（#projection_translate）设置为符合指定GeoJSON 对象在指定范围中心的位置。范围指定为数组 [[x₀， y₀]， [x₁， y₁]]，其中 x₀ 是边界框的左侧，y₀ 是顶部，x₁ 是右边，y ₁ 是底部。返回投影。

例如，要缩放并移动新泽西州平面投影以适应中心位于 960×500 边界框、每边有 20 像素填充的 GeoJSON 对象 nj:

🌐 For example, to scale and translate the New Jersey State Plane projection to fit a GeoJSON object nj in the center of a 960×500 bounding box with 20 pixels of padding on each side:

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

在确定新的缩放和平移时，会忽略任何裁剪范围。用于计算给定对象边界框的精度是在有效缩放为150时计算的。

🌐 Any clip extent is ignored when determining the new scale and translate. The precision used to compute the bounding box of the given object is computed at an effective scale of 150.

projection.fitSize(size, object) ​

来源 · 一个projection.fitExtent的便捷方法，其中范围的左上角为[0, 0]。以下两条语句是等价的：

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

projection.fitWidth(width, object) ​

来源 · 一个方便的方法用于 projection.fitSize，其中高度是根据 object 的宽高比和给定的 width 限制自动选择的。

projection.fitHeight(height, object) ​

来源 · 一个方便的方法用于 projection.fitSize，其中宽度是根据 object 的宽高比和给定的 height 限制自动选择的。

原始预测 ​

🌐 Raw projections

原始投影是用于实现自定义投影的点变换函数；它们通常传递给 geoProjection 或 geoProjectionMutator。在这里公开它们是为了便于推导相关投影。原始投影接受以弧度为单位的球面坐标 [lambda, phi]（不是度数！）并返回一个点 [x, y]，通常在以原点为中心的单位方形内。

🌐 Raw projections are point transformation functions that are used to implement custom projections; they typically passed to geoProjection or geoProjectionMutator. They are exposed here to facilitate the derivation of related projections. Raw projections take spherical coordinates [lambda, phi] in radians (not degrees!) and return a point [x, y], typically in the unit square centered around the origin.

project(lambda, phi) ​

将指定点 [lambda, phi]（以弧度为单位）投影，返回一个新的点 [x, y]，其坐标无单位。

project.invert(x, y) ​

project 的逆运算。

🌐 The inverse of project.

geo投影(project) ​

🌐 geoProjection(project)

Source · 从指定的原始投影构建一个新的投影，project。project函数接受给定点的经度和纬度（以弧度为单位），通常称为lambda（λ）和phi（φ），并返回一个包含两个元素的数组[x, y]，表示其单位投影。project函数不需要缩放或平移点，因为这些会由projection.scale、projection.translate和projection.center自动应用。同样，project函数也不需要执行任何球面旋转，因为projection.rotate在投影之前已应用。

例如，球面墨卡托投影可以实现为：

🌐 For example, a spherical Mercator projection can be implemented as:

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

如果 project 函数暴露了一个 invert 方法，则返回的投影也将暴露 projection.invert。

🌐 If the project function exposes an invert method, the returned projection will also expose projection.invert.

geoProjectionMutator(工厂) ​

🌐 geoProjectionMutator(factory)

来源 · 从指定的原始投影 工厂 构建一个新的投影，并返回一个 mutate 函数，以在原始投影发生变化时调用。工厂 必须返回一个原始投影。返回的 mutate 函数返回封装后的投影。例如，圆锥投影通常有两个可配置的纬线。一个合适的 工厂 函数，例如 geoConicEqualAreaRaw，其形式如下：

js
// y0 and y1 represent two parallels
function conicFactory(phi0, phi1) {
  return function conicRaw(lambda, phi) {
    return […, …];
  };
}

使用 d3.geoProjectionMutator，你可以实现一个标准投影，该投影允许更改纬线，重新分配 geoProjection 内部使用的原始投影：

🌐 Using d3.geoProjectionMutator, you can implement a standard projection that allows the parallels to be changed, reassigning the raw projection used internally by geoProjection:

js
function conicCustom() {
  var phi0 = 29.5,
      phi1 = 45.5,
      mutate = d3.geoProjectionMutator(conicFactory),
      projection = mutate(phi0, phi1);

  projection.parallels = function(_) {
    return arguments.length ? mutate(phi0 = +_[0], phi1 = +_[1]) : [phi0, phi1];
  };

  return projection;
}

在创建可变投影时，通常不会公开 mutate 函数。

🌐 When creating a mutable projection, the mutate function is typically not exposed.

geoTransform(方法) ​

🌐 geoTransform(methods)

来源 · 使用指定的 methods 对象上定义的方法来定义任意变换。任何未定义的方法将使用透传方法，将输入传递到输出流。

例如，要反映 y 维度（另见 projection.reflectY）：

🌐 For example, to reflect the y-dimension (see also projection.reflectY):

js
const reflectY = d3.geoTransform({
  point(x, y) {
    this.stream.point(x, -y);
  }
});

或者定义仿射矩阵变换：

🌐 Or to define an affine matrix transformation:

js
function matrix(a, b, c, d, tx, ty) {
  return d3.geoTransform({
    point(x, y) {
      this.stream.point(a * x + b * y + tx, c * x + d * y + ty);
    }
  });
}

变换是一种广义投影；它实现了 projection.stream，并且可以传递给 path.projection。然而，它仅实现了其他投影方法的一部分，并表示任意几何变换，而不是从球面到平面坐标的投影。

🌐 A transform is a generalized projection; it implements projection.stream and can be passed to path.projection. However, it implements only a subset of the other projection methods, and represent arbitrary geometric transformations rather than projections from spherical to planar coordinates.

geoIdentity() ​

来源 · 恒等变换可用于缩放、平移和平面几何裁剪。它实现了 projection.scale、projection.translate、projection.fitExtent、projection.fitSize、projection.fitWidth、projection.fitHeight、projection.clipExtent、projection.angle、projection.reflectX 和 projection.reflectY。

geoClipAntimeridian ​

来源 · 一个裁剪函数，用于将流转换，使横跨反经线的几何图形（线或多边形）被切成两部分，各在一侧。通常用于预裁剪。

geoClipCircle(角度) ​

🌐 geoClipCircle(angle)

来源 · 生成一个裁剪函数，将流转换为几何图形被限制在投影 中心 周围半径为 angle 的小圆内。通常用于预裁剪。

geoClipRectangle(x0, y0, x1, y1) ​

Source · 生成一个裁剪函数，该函数可以转换一个流，使几何图形被坐标为 [[x0, y0], [x1, y1]] 的矩形所限制。通常用于后裁剪。