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) {#_projection} ​

源代码 · 返回一个以度为单位的新数组 [经度, 纬度]（通常以像素为单位），表示给定点的投影点。该点必须指定为一个二元素数组 [经度, 纬度]，单位为度。如果指定的点没有定义的投影位置（例如，当该点超出投影的裁剪范围时），则可能返回 null。

¥Source · Returns a new array [x, y] (typically in pixels) representing the projected point of the given point. The point must be specified as a two-element array [longitude, latitude] in degrees. May return null if the specified point has no defined projected position, such as when the point is outside the clipping bounds of the projection.

projection.invert(point) {#projection_invert} ​

源代码 · 返回一个以度为单位的新数组 [经度, 纬度]，表示给定投影点的非投影点。该点必须指定为一个二元素数组 [x, y]（通常以像素为单位）。如果指定的点没有定义的投影位置（例如，当该点超出投影的裁剪范围时），则可能返回 null。

¥Source · Returns a new array [longitude, latitude] in degrees representing the unprojected point of the given projected point. The point must be specified as a two-element array [x, y] (typically in pixels). May return null if the specified point has no defined projected position, such as when the point is outside the clipping bounds of the projection.

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

¥This method is only defined on invertible projections.

projection.stream(stream) {#projection_stream} ​

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

¥Source · Returns a projection stream for the specified output stream. Any input geometry is projected before being streamed to the output stream. A typical projection involves several geometry transformations: the input geometry is first converted to radians, rotated on three axes, clipped to the small circle or cut along the antimeridian, and lastly projected to the plane with adaptive resampling, scale and translation.

projection.preclip(preclip) {#projection_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) {#projection_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) {#projection_clipAngle} ​

源代码 · 如果指定了角度，则将投影的剪切圆半径设置为指定的度数并返回投影。如果角度为空，则切换到 对向子午线切割 而不是小圆裁剪。如果未指定角度，则返回当前剪辑角度，默认为 null。小圆裁剪与通过 projection.clipExtent 进行的视口裁剪无关。另请参阅 projection.preclip、geoClipAntimeridian、geoClipCircle。

¥Source · If angle is specified, sets the projection’s clipping circle radius to the specified angle in degrees and returns the projection. If angle is null, switches to antimeridian cutting rather than small-circle clipping. If angle is not specified, returns the current clip angle which defaults to null. Small-circle clipping is independent of viewport clipping via projection.clipExtent. See also projection.preclip, geoClipAntimeridian, geoClipCircle.

projection.clipExtent(extent) {#projection_clipExtent} ​

源代码 · 如果指定了范围，则将投影的视口裁剪范围设置为指定的像素边界并返回投影。范围边界以数组 [[x₀, y₀], [x₁, y₁]] 的形式指定，其中 x₀ 表示视口左侧，y₀ 表示顶部，x₁ 表示右侧，y₁ 表示底部。如果范围为 null，则不执行视口裁剪。如果未指定范围，则返回当前视口裁剪范围，默认为 null。视口裁剪与通过 projection.clipAngle 进行的小圆裁剪无关。另请参阅 projection.postclip、geoClipRectangle。

¥Source · If extent is specified, sets the projection’s viewport clip extent to the specified bounds in pixels and returns the projection. The extent bounds are specified as an array [[x₀, y₀], [x₁, y₁]], where x₀ is the left-side of the viewport, y₀ is the top, x₁ is the right and y₁ is the bottom. If extent is null, no viewport clipping is performed. If extent is not specified, returns the current viewport clip extent which defaults to null. Viewport clipping is independent of small-circle clipping via projection.clipAngle. See also projection.postclip, geoClipRectangle.

projection.scale(scale) {#projection_scale} ​

源代码 · 如果选择是一个选择， 将所选元素的 乘以 k，使得新的 k₁ = k₀k。如果未指定 scale，则返回当前的比例因子；默认比例尺与投影相关。比例因子与投影点之间的距离呈线性对应关系；但是，绝对比例因子在不同投影之间并不相等。

¥Source · If scale is specified, sets the projection’s scale factor to the specified value and returns the projection. If scale is not specified, returns the current scale factor; the default scale is projection-specific. The scale factor corresponds linearly to the distance between projected points; however, absolute scale factors are not equivalent across projections.

projection.translate(translate) {#projection_translate} ​

源代码 · 如果指定了 transform，则将投影的平移偏移量设置为指定的二元素数组 [tx, ty] 并返回投影。如果未指定 transform，则返回当前的平移偏移量，默认为 [480, 250]。平移偏移量决定了投影 center 的像素坐标。默认平移偏移将⟨0°,0°⟩置于 960×500 区域的中心。

¥Source · If translate is specified, sets the projection’s translation offset to the specified two-element array [tx, ty] and returns the projection. If translate is not specified, returns the current translation offset which defaults to [480, 250]. The translation offset determines the pixel coordinates of the projection’s center. The default translation offset places ⟨0°,0°⟩ at the center of a 960×500 area.

projection.center(center) {#projection_center} ​

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

¥Source · If center is specified, sets the projection’s center to the specified center, a two-element array of [longitude, latitude] in degrees and returns the projection. If center is not specified, returns the current center, which defaults to ⟨0°,0°⟩.

projection.angle(angle) {#projection_angle} ​

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

¥Source · If angle is specified, sets the projection’s post-projection planar rotation angle to the specified angle in degrees and returns the projection. If angle is not specified, returns the projection’s current angle, which defaults to 0°. Note that it may be faster to rotate during rendering (e.g., using context.rotate) rather than during projection.

projection.reflectX(reflect) {#projection_reflectX} ​

如果指定了 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) {#projection_reflectY} ​

如果指定了 reflect，则设置输出中是否反射（取反）y 维度。如果未指定 reflect，则在启用 y 轴反射的情况下返回 true，默认为 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) {#projection_rotate} ​

源代码 · 如果指定了角度，则将投影的 三轴球面旋转 设置为指定的值，该值必须是一个由 [lambda, phi, gamma] 组成的二元素或三元素数组，用于指定围绕 每个球面轴 的旋转角度（以度为单位）。（这些对应于 偏航、俯仰和滚转。）如果省略旋转角度 gamma，则默认为 0。另请参阅 geoRotation。如果未指定角度，则返回当前旋转角度，默认为 [0, 0, 0]。

¥Source · If angles is specified, sets the projection’s three-axis spherical rotation to the specified value, which must be a two- or three-element array of numbers [lambda, phi, gamma] specifying the rotation angles in degrees about each spherical axis. (These correspond to yaw, pitch and roll.) If the rotation angle gamma is omitted, it defaults to 0. See also geoRotation. If angles is not specified, returns the current rotation which defaults to [0, 0, 0].

projection.precision(precision) {#projection_precision} ​

源代码 · 如果指定了 precision，则将投影的 自适应重采样 的阈值设置为指定的像素值，并返回投影。此值对应于 道格拉斯-普克坐标系 距离。如果未指定精度，则返回投影的当前重采样精度，默认为 √0.5 ≅ 0.70710…

¥Source · If precision is specified, sets the threshold for the projection’s adaptive resampling to the specified value in pixels and returns the projection. This value corresponds to the Douglas–Peucker distance. If precision is not specified, returns the projection’s current resampling precision which defaults to √0.5 ≅ 0.70710…

projection.fitExtent(extent, object) {#projection_fitExtent} ​

源代码 · 设置投影的 scale 和 translate，以使指定的 GeoJSON 对象位于给定范围的中心。范围指定为数组 [[x₀, y₀], [x₁, y₁]]，其中 x₀ 表示边界框左侧，y₀ 表示顶部，x₁ 表示右侧，y₁ 表示底部。返回投影。

¥Source · Sets the projection’s scale and translate to fit the specified GeoJSON object in the center of the given extent. The extent is specified as an array [[x₀, y₀], [x₁, y₁]], where x₀ is the left side of the bounding box, y₀ is the top, x₁ is the right and y₁ is the bottom. Returns the projection.

例如，缩放和平移 新泽西州平面投影，使 GeoJSON 对象 nj 位于 960×500 边界框的中心，每边有 20 像素的填充：

¥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);

在确定新的比例和平移时，任何 裁剪范围 都将被忽略。用于计算给定对象边界框的 precision 以 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_fitSize} ​

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

¥Source · A convenience method for projection.fitExtent where the top-left corner of the extent is [0, 0]. The following two statements are equivalent:

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

projection.fitWidth(width, object) {#projection_fitWidth} ​

源代码 · 一个便捷的 projection.fitSize 方法，其高度根据对象的长宽比和给定的宽度约束自动选择。

¥Source · A convenience method for projection.fitSize where the height is automatically chosen from the aspect ratio of object and the given constraint on width.

projection.fitHeight(height, object) {#projection_fitHeight} ​

源代码 · 一个便捷的 projection.fitSize 方法，其宽度根据对象的长宽比和给定的高度约束自动选择。

¥Source · A convenience method for projection.fitSize where the width is automatically chosen from the aspect ratio of object and the given constraint on 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) {#_project} ​

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

¥Projects the specified point [lambda, phi] in radians, returning a new point [x, y] in unitless coordinates.

project.invert(x, y) {#project_invert} ​

project 的倒数。

¥The inverse of project.

geoProjection(project) ​

源代码 · 根据指定的 原始投影 项目构造一个新的投影。投影函数获取 radians 中给定点的经度和纬度，通常称为 lambda (λ) 和 phi (φ)，并返回一个表示其单位投影的双元素数组 [x, y]。投影函数不需要缩放或平移点，因为这些操作已由 projection.scale、projection.translate 和 projection.center 自动应用。同样，投影函数不需要执行任何球面旋转，因为 projection.rotate 在投影之前应用。

¥Source · Constructs a new projection from the specified raw projection, project. The project function takes the longitude and latitude of a given point in radians, often referred to as lambda (λ) and phi (φ), and returns a two-element array [x, y] representing its unit projection. The project function does not need to scale or translate the point, as these are applied automatically by projection.scale, projection.translate, and projection.center. Likewise, the project function does not need to perform any spherical rotation, as projection.rotate is applied prior to projection.

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

¥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 方法，则返回的 project 也将公开 projection.invert。

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

geoProjectionMutator(factory) ​

源代码 · 根据指定的 原始投影 工厂构造一个新的投影，并返回一个 mutate 函数，当原始投影发生变化时调用该函数。工厂函数必须返回原始投影。返回的 mutate 函数返回封装后的投影。例如，圆锥投影通常有两个可配置的平行线。合适的工厂函数（例如 geoConicEqualAreaRaw）应具有以下形式：

¥Source · Constructs a new projection from the specified raw projection factory and returns a mutate function to call whenever the raw projection changes. The factory must return a raw projection. The returned mutate function returns the wrapped projection. For example, a conic projection typically has two configurable parallels. A suitable factory function, such as geoConicEqualAreaRaw, would have the form:

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

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(methods) ​

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

¥Source · Defines an arbitrary transform using the methods defined on the specified methods object. Any undefined methods will use pass-through methods that propagate inputs to the output stream.

例如，反映 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。

¥Source · The identity transform can be used to scale, translate and clip planar geometry. It implements projection.scale, projection.translate, projection.fitExtent, projection.fitSize, projection.fitWidth, projection.fitHeight, projection.clipExtent, projection.angle, projection.reflectX and projection.reflectY.

geoClipAntimeridian ​

源代码 · 一个裁剪函数，用于转换流，使与对向子午线相交的几何图形（线或多边形）被一分为二，左右两侧各一个。通常用于预裁剪。

¥Source · A clipping function which transforms a stream such that geometries (lines or polygons) that cross the antimeridian line are cut in two, one on each side. Typically used for pre-clipping.

geoClipCircle(angle) ​

源代码 · 生成一个裁剪函数，该函数对流进行转换，使几何图形以投影 center 为中心，由一个半径为 angle 的小圆包围。通常用于预裁剪。

¥Source · Generates a clipping function which transforms a stream such that geometries are bounded by a small circle of radius angle around the projection’s center. Typically used for pre-clipping.

geoClipRectangle(x0, y0, x1, y1) ​

源代码 · 生成一个裁剪函数，该函数对流进行转换，使几何图形由坐标为 [[x0, y0], [x1, y1]] 的矩形包围。通常用于后裁剪。

¥Source · Generates a clipping function which transforms a stream such that geometries are bounded by a rectangle of coordinates [[x0, y0], [x1, y1]]. Typically used for post-clipping.