(译)D3-force

原文: https://github.com/d3/d3/blob/master/API.md#forces-d3-force

d3.forceSimulation( [nodes] )

使用指定的节点数据和无强度力创建一个新的模拟。若未指定 nodes，默认为空数组。该模拟是自启动的；在该模拟运行时使用 simulation.on  监听每个瞬间（呼吸）事件。如果你想要手动运行模拟，调用 simulation.stop, 然后需要调用  simulation.tick .

simulation.nodes（[nodes]）

每个 node 必须是一个对象模型，下面几个属性将会被仿真系统添加：
index-节点在 nodes 数组中的索引

• x-节点当前的 x 坐标
• y-节点当前的 y-坐标
• vx-节点当前的 x 方向速度
• vy-节点当前的 y 方向速度

固定给定节点的位置，你需要两个特定的额外的属性：

• fx - 节点的固定 x-位置
• fy - 节点的固定 y-位置

force(）

force()是一个用以修改节点位置和速度的函数；在这种情况下，force  可以用来模拟电荷或重力之类的经典物理力学，也可以用来解决几何约束，例如将节点保持在边界框内或者保持节点之间的相对距离。

link froce(弹簧模型)

可以根据 link distance 将有关联的两个节点拉近或者推远。力的强度与被链接两个节点的距离成比例，类似弹簧力。

d3.forceManyBody()

创建一个使用默认参数的电荷力模型。
manyBody.strength([strength]) 如果指定了  strength  则将强度访问器设置为指定的数值或者方法，重新评估每个节点的强度访问器并返回此电荷力。若强度为正值则表示节点之间相互吸引，负值表示节点之间相互排斥。

simulation.alphaTarget([target])

如果指定了  target  则将当前的目标  alpha  设置为指定的值，需要在 [0, 1] 之间。如果没有指定  target  则返回当前默认的目标  alpha  值, 默认为 0.

simulation.force(name[, force])

如果指定了  force  则表示为仿真添加指定  name  的  force(力学模型)  并返回仿真。如果没有指定  force  则返回当前仿真的对应  name  的力模型，如果没有对应的  name  则返回  undefined. (默认情况下仿真没有任何力学模型，需要手动添加).

enter( )

操作的意义在于通过此函数返回一个集合，这个集合里面包含的就是没有被可视化的数据；

simulation.on(typenames, [listener])

---

Forces

forces 是一个简单的改变节点位置和速度的函数；在这个模拟环境中，一个 forces 能施加一个典型的物理力，比如电荷力或重力，或者它可以解决一个几何约束， 例如将节点保持在边界框内或将链接节点保持在固定距离之外。
举个例子，一个简单的朝着原点（0，0）移动节点的定位力可能实现为：

function force(alpha) {
  for (var i = 0, n = nodes.length, node, k = alpha * 0.1; i < n; ++i) {
    node = nodes[i]
    node.vx -= node.x * k
    node.vy -= node.y * k
  }
}

力模拟通常读取节点当前的位置坐标，然后增加/减去这个节点的速度<vx, vy>,
然而，力模拟也可以’偷看‘预期的节点下一个位置<x+vx, y+vy>;这对于通过 通过迭代松弛解决几何约束力是很有必要的。力模拟也可以改变位置方向，这有时可以避免增加模拟的能量，比如在视口模拟重入的时候。

模拟通常要组合多个力，这个模块提供几个供您享用：

1. Centering 定心力
2. Collision 碰撞力
3. Links 链接力
4. Many-body 多体力（电荷）
5. Positioning 定位力

Centering 定心力

定心力一致的调动节点以至于所有节点(如果多有节点的质量相等则为质心)都是在给定的位置<x,y>。
每一个施加了这个力的节点的位置会被改变；但是它的速度不变，这样做通常会导致节点超出目标中心并且围着这个中心震荡。这个力帮助节点保持在视口的中心，不像定位力，会扭曲它们的相对位置。

1. d3.forceCenter([x, y])

使用指定的 x 和 y 坐标创建新的定心力。如果 x 和 y 是未指定,默认<0, 0>

2. center.x([x])

如果指定了 x，则将定心位置的 x 坐标设置为指定的数值并返回此力。如果没有指定 x，则返回当前 x 坐标，该坐标默认为 0。

3. center.y([y])

如果指定了 y，则将定心位置的 y 坐标设置为指定的数值并返回此力。如果没有指定 y，则返回当前 y 坐标，默认为 0。

var simulation = d3
  .forceSimulation(nodes)
  .force('charge', d3.forceManyBody())
  .force('link', d3.forceLink(links))
  .force('center', d3.forceCenter().x().y())

Collision 碰撞力

碰撞力将节点视为具有给定半径的圆，而不是点，并且阻止节点重叠。通常情况下，两个节点 a 和 b 是分开的所以 a 和 b 之间的距离至少是两个节点的半径之和。为了减少抖动，这是一个默认的软约束，具有可配置的强度和迭代次数。

1. d3.forceCollide([radius])

以一个特定的半径创建一个新的圆形碰撞力。如果这个半径没有设置，所有的节点都默认为常数 1。

2. collide.radius([radius])

如果给定了半径，将半径访问器设为一个特定的数字或者函数，重新评估每一个节点的半径访问器，并且返回这个模拟。如果没有给定半径，返回当前的半径访问器，默认如下：

function radius() {
  return 1
}

这个半径访问器会被这个模拟中的每一个节点调用，传递节点及其从零开始的索引。然后，结果数被存储在内部，这样每个节点的半径只在初始化力或使用新的半径调用此方法时重新计算，而不是在力的每个应用程序上。

3. collide.strength([strength])

如果指定了强度，设置这个力强度为[0, 1]之间的数字，并返回这个模拟。如果未指定强度，返回当前的强度，默认是 0.7。

通过迭代松弛来解决重叠节点。对于每个节点来说，在下个确定的呼吸事件决定的预计（使用预期的位置<x+vx, y+vy>）将会重叠它的其他节点，z 这个节点的速度会改变，推着这个节点超出另一个将会重叠的节点。 速度的变化被力的强度减弱，这样同时重叠的分辨率可以混合在一起来找到一个稳定的解决方案。

4. collide.iterations([iterations])

如果指定了迭代次数，给每一个应用设置迭代次数的值为一个特定的数字并且返回这个模拟。如果未指定迭代次数，返回当前的迭代次数，默认值为 1。增加迭代次数大大增加了约束的钢度并且避免节点的部分重合，但是也增加了计算力的运行时成本。

Links 链接力

根据想要的链接距离，链接力将链接在一起的节点推到一起或分开。这个力的强度与链接节点和目标节点的距离差成比例，类似于弹簧力。

1. d3.forceLink([links])

创建一个新的链接力，传一个特定的 links 和默认参数。如果 links 未指定，它将默认是一个空数组。

2. link.links([links])

如果 links 未指定，设置与此力关联的链接数组，重新计算每一个链接参数的距离和强度，并返回这个模拟。如果 links 未指定，返回默认值是空数组的当前的链接数组。

每个链接是一个拥有如下属性的对象：

• source - 这个链接的源头节点
• target - 这个链接的目标节点
• index -  将从零开始的索引转换成链接，通过这种方法分配

为了方便，一个链接的源头和目标接节点的属性可以用除对象引用外的数值或字符串字符初始化；看 link.id。当这个链接力被初始化（或当节点或链接改变的时候重新初始化），任意 link.source 或 link.target 的那个非对象属性将会被对应给定目标标识符的对象引用替换。

如果指定的链接数组被改变，例如当链接增加或从模拟中删除的时候，必须用新的数组重新调用这个方法，以通知更改的力度。这个力不会去创建特定数组的防御副本。

3. link.id([id])

如果指定了 id，以特定的函数设置这个节点的 id 访问器并返回这个模拟。如果未指定，然会当前的节点 id 访问器，默认数值类型的节点索引：

function id(d) {
  return d.index
}

默认 id 访问器允许每一个链接的源或者目标的值指定为节点数组从零开始的索引。例如：

var nodes = [{ id: 'Alice' }, { id: 'Bob' }, { id: 'Carol' }]

var links = [
  { source: 0, target: 1 }, // Alice → Bob
  { source: 1, target: 2 } // Bob → Carol
]

现在考虑一个不同的 id 访问器，它返回一个字符串：

function id(d) {
  return d.id
}

有了这个访问器，你可以使用命名的源和目标：

var nodes = [{ id: 'Alice' }, { id: 'Bob' }, { id: 'Carol' }]

var links = [
  { source: 'Alice', target: 'Bob' },
  { source: 'Bob', target: 'Carol' }
]

当用一个 JSON 数据展现图谱/图形时，这是一个极其有用的例子。参考这个例子。
当这个模拟初始化的时候，id 访问器被每一个节点调用，同时当节点或者链接改变的时候，传递节点及其从零开始的索引。

4. link.distance([distance])

如果指定了距离，将距离访问器设置未特定的数字或函数，重新计算每个链接的距离访问器，并且返回这个模拟。如果未指定距离，返回当前的距离访问器，默认如下：

function distance() {
  return 30
}

这个距离访问器被每个链接调用，传递链接及其从零开始的索引。这个数值的结果将会被存储在内部，当这个模拟初始化或者用一个新的距离调用这个方法的时候会重新计算每一个链接之间的距离，而不是这个模拟的每个应用程序上。

5. link.strength([strength])

如果指定了强度，将强度访问器者设置为特定的数字或这个函数，重新计算每个链接的强度访问器，并返回这个强度。如果未指定，返回当前的强度访问器，默认如下：

function strength(link) {
  return 1 / Math.min(count(link.source), count(link.target))
}

其中 count(node)是一个函数，它返回给定节点作为源或目标的链接数。之所以选择此默认值，是因为它会自动降低连接到紧密连接节点的链接的强度，从而提高稳定性。

为每个链接调用强度访问器，传递链接及其从零开始的索引。然后，结果数被存储在内部，这样，只有在初始化 force 或使用新强度调用此方法时，才会重新计算每个链接的强度，而不是在 force 的每个应用程序上。

6. link.iterations([iterations])

如果指定了迭代，则将每个应用程序的迭代次数设置为指定的次数并返回该强制。如果没有指定迭代，则返回默认为 1 的当前迭代计数。迭代次数的增加极大地增加了约束的刚度，对于复杂的结构如网格是有用的，但也增加了评估力的运行时成本。

Many-Body 多体力

多体力在多有节点之间相互作用。如果强度时正数，它相当于引力（吸引），如果强度是负数，它相当于静电电荷斥力。该实现使用四叉树和 Barnes-Hut 近似来极大地提高性能;  他的精确性可以用 theta 参数定制。

不像链接力，它仅仅受两个链接的节点影响，这个电荷斥力是全局的；每个节点会影响每个其他的节点，即使他们不是相互连接的子图。

1. d3.forceManyBody()

用默认的参数创建一个新的多体力。

2. manyBody.strength([strength])

如果指定强度，将强度访问器设为一个特定的数字或函数，重新计算每个节点的强度访问器，并返回这个强度。正数使节点相互吸引，负数使节点相互排斥。如果未指定，返回当前的强度访问器，默认为：

function strength() {
  return -30
}

在模拟中，每个节点都会调用强度访问器传递节点及从零开始的索引。这个返回的结果会保存在本地，所以当这个模拟初始化或用一个新的强度调用这个方法的时候，每一个节点的强度重新计算，而不是在模拟的每个应用程序上。

3. manyBody.theta([theta])

如果指定 theta，将 Barnes–Hut 近似准则设置为特定的数值，并发返回这个模拟。如果未指定，返回默认值：0.9。

为了加速计算，模拟执行 在每个应用程序中使用 O(n log n)得出的 Barnes-Hut 近似值，n 是节点数量。对于每个应用程序，使用四叉树存储当前节点的位置。对于每个节点。结合所有给定计算出的所有其他节点的力。对于一个很远的节点集群，电荷力可以近似于用一个独立的、大的节点。这个 theta 的参数值决定了这个近似值的精确度： 如果四叉树单元的宽度 w / l 与从节点到单元质心的距离 l 之比小于 theta，则给定单元中的所有节点都视为单个节点，而不是单独处理。

4. manyBody.distanceMin([distance])

如果指定距离，将它设置为节点之间的最小距离。如果未指定，返回默认值 1. 最小的距离建立了相邻节点的力强度的上线，从而避免不稳定。特别是避免了两个节点完全重合时无限强的力。在这种情况下，力的方向时随机的。

5. manyBody.distanceMax([distance])

如果指定距离，将它设置为两个节点间的最大距离。如果未指定，返回默认值无穷大。指定一个有限大的最大距离提高了性能并且生成更加本地化的布局。

Positioning 定位力

x 和 y 的定位力以可配置的强度将节点推向给定的尺寸预期的位置。径向力是相似的，除了它时将节点推向给定圆的最近点。这个力的强度是跟节点的位置和目标位置的一维距离成正例。虽然这些力可以作用于单个节点，但是它主要作用于所有节点的全局力。

1. d3.forceX([x])

沿着 x 轴给定位置 x 创建一个新的定位力。如果 x 未指定，默认未 0.

2. x.strength([strength])

如果指定了 strength，将它设置为特定的数值或者函数，重新计算每个节点的强度访问器。并且返回这个强度。强度决定了节点的 x 方向速度增加多少。例如，强度的值是 0.1 就表示节点应该从当前的 x 位置到目标位置要移动 1/10 的距离。较高的值可以更快的将节点移动到目标位置，这通常是以其他力或约束为代价的。超出 0~1 的值是不推荐的。
如果强度未指定，返回默认值：

function strength() {
  return 0.1
}

模拟中的每个节点都会调用这个强度访问器，传递节点和从零开始的索引。返回的结果会存储在本地，这样，只有在初始化 force 或使用新 x 调用此方法时，才会重新计算每个节点的目标 x 坐标，而不是在 force 的每个应用程序上。

3. x.x([x])

如果指定了 x，将其设置为特定数值址或函数，重新计算每个节点的 x 访问器，并返回这个模拟。如果未指定，返回默认值：

function x() {
  return 0
}

这个模拟中的每个节点都会调用这个 x 访问器，传递节点和从零开始的索引。结果会存储在本地，这样只有模拟初始化或者用新的 x 调用这个方法的时候会重新计算每个节点的目标 x 坐标。

4. d3.forceY([y])

5. y.strength([strength])

6. y.y([y])

7. d3.forceRadial(radius[, x][, y])

创建一个新的定位力沿着特定圆心和半径的圆。如果 x 和 y 未指定，默认值<0,0>。

8. radial.strength([strength])

如果指定强度，将其设置未特定的数值或函数，重新计算每个节点的强度计算器，并返回这个模拟。强度决定了节点的 x 和 y 轴方向的速度增加多少。例如：对于每个应用来说，值为 0.1 表示节点从当前位置到这个圆的最近的点要移动 1/10 的距离。比较高的值表示节点到目标位置的速度更快，通常是以其他力或约束为代价的。超出 0~1 的值是不推荐的。
如果未指定，返回默认值：

function strength() {
  return 0.1
}

为模拟中的每个节点调用强度访问器，传递节点及其从零开始的索引。然后，结果数被存储在内部，这样，只有在初始化 force 或使用新强度调用此方法时，才会重新计算每个节点的强度，而不是在 force 的每个应用程序上。

9. radial.radius([radius])

如果指定了半径，将其设置为特定的值或函数，重新计算每个节点的半径访问器，并返回这个模拟。如果未指定返回当前的半径访问器。
为模拟中的每个节点调用 radius 访问器，传递节点及其从零开始的索引。然后，结果数被存储在内部，以便仅在初始化 force 或使用新半径调用此方法时重新计算每个节点的目标半径，而不是在 force 的每个应用程序上。

10. radial.x([x])

如果指定了 x，则将圆心的 x 坐标设置为指定的数值并返回此力。如果没有指定 x，则返回中心的当前 x 坐标，默认为 0。

11. radial.y([y])

如果指定了 y，则将圆心的 y 坐标设置为指定的数值并返回此力。如果没有指定 y，则返回中心的当前 y 坐标，默认为 0。

注：本文是笔者阅读文档自译版，如跟官方文档有出入谨以官方为准。

本文有不到之处欢迎交流指正，感谢~

打赏