@antv/layout 2.0.0-alpha.1 → 2.0.0-alpha.2

package/src/algorithm/force-atlas2/simulation.ts

@@ -0,0 +1,445 @@
+import { isNumber } from '@antv/util';
+import { BaseSimulation } from '../base-simulation';
+import type { ID, NullablePosition } from '../../types';
+import type { GraphLib } from '../../model/data';
+import Body from './body';
+import Quad from './quad';
+import QuadTree from './quad-tree';
+import type {
+  ForceAtlas2LayoutOptions,
+  ParsedForceAtlas2LayoutOptions,
+} from './types';
+
+type PointTuple = [number, number];
+type ForceMap = Record<string, PointTuple>;
+type BodyMap = Record<string, Body>;
+type SizeMap = Record<string, number>;
+
+/**
+ * ForceAtlas2 Simulation
+ */
+export class Simulation extends BaseSimulation<ParsedForceAtlas2LayoutOptions> {
+  private sg = 0;
+  private forces: ForceMap = {};
+  private preForces: ForceMap = {};
+  private bodies: BodyMap = {};
+  private sizes: SizeMap = {};
+  private maxIteration = 0;
+
+  protected model!: GraphLib;
+
+  data(model: GraphLib, sizes: SizeMap): this {
+    this.model = model;
+    this.sizes = sizes;
+    return this;
+  }
+
+  initialize(options: Required<ForceAtlas2LayoutOptions>): void {
+    super.initialize(options);
+
+    this.maxIteration = options.maxIteration;
+
+    this.sg = 0;
+
+    this.initForces();
+  }
+
+  private initForces(): void {
+    const { model, options } = this;
+    const { kr, barnesHut } = options;
+    const nodes = model.nodes();
+
+    this.forces = {};
+    this.preForces = {};
+    this.bodies = {};
+
+    for (let i = 0; i < nodes.length; i += 1) {
+      const node = nodes[i];
+      this.forces[node.id] = [0, 0];
+      this.preForces[node.id] = [0, 0];
+
+      if (barnesHut) {
+        const params = {
+          id: i,
+          rx: node.x,
+          ry: node.y,
+          mass: 1,
+          g: kr,
+          degree: model.degree(node.id),
+        };
+        this.bodies[node.id] = new Body(params);
+      }
+    }
+  }
+
+  /**
+   * Set a node's fixed position
+   */
+  public setFixedPosition(id: ID, position: NullablePosition | null) {
+    const node = this.model.node(id);
+    if (!node) return;
+
+    const keys = ['fx', 'fy', 'fz'] as const;
+
+    if (position === null) {
+      // Unset fixed position
+      keys.forEach((key) => {
+        delete node[key];
+      });
+      return;
+    }
+
+    position.forEach((value, index) => {
+      if (
+        index < keys.length &&
+        (typeof value === 'number' || value === null)
+      ) {
+        node[keys[index]] = value;
+      }
+    });
+  }
+
+  private isNodeFixed(node: any): boolean {
+    return isNumber(node.fx) && isNumber(node.fy);
+  }
+
+  private syncFixedPositions(): void {
+    this.model.forEachNode((node) => {
+      if (this.isNodeFixed(node)) {
+        node.x = node.fx!;
+        node.y = node.fy!;
+      }
+    });
+  }
+
+  /**
+   * Execute one step of the simulation
+   */
+  protected runOneStep(): number {
+    const { model, options } = this;
+    const { preventOverlap, barnesHut } = options;
+    const iter = this.maxIteration - this.iteration;
+    const krPrime = 100;
+
+    // Save previous & reset current force vectors
+    const nodes = model.nodes();
+    for (let i = 0; i < nodes.length; i += 1) {
+      const { id } = nodes[i];
+      this.preForces[id] = [...(this.forces[id] || [0, 0])];
+      this.forces[id] = [0, 0];
+    }
+
+    this.syncFixedPositions();
+
+    // 1. Attractive forces (edges)
+    this.calculateAttractive(iter);
+
+    // 2. Repulsive forces + gravity
+    // 当启用 Barnes-Hut 且不需要防重叠时使用优化算法
+    if (barnesHut && !preventOverlap) {
+      this.calculateOptRepulsiveGravity();
+    } else {
+      this.calculateRepulsiveGravity(iter, krPrime);
+    }
+
+    // 3. Update positions
+    return this.updatePositions();
+  }
+
+  private calculateAttractive(iter: number): void {
+    const { model, options } = this;
+    const { preventOverlap, dissuadeHubs, mode, prune } = options;
+    const edges = model.edges();
+
+    for (let i = 0; i < edges.length; i += 1) {
+      const { source, target } = edges[i];
+      const sourceNode = model.node(source)!;
+      const targetNode = model.node(target)!;
+
+      const sourceDegree = model.degree(source);
+      const targetDegree = model.degree(target);
+      if (prune && (sourceDegree <= 1 || targetDegree <= 1)) continue;
+
+      const dirX = targetNode.x - sourceNode.x;
+      const dirY = targetNode.y - sourceNode.y;
+      let eucliDis = Math.hypot(dirX, dirY);
+      eucliDis = eucliDis < 1e-4 ? 1e-4 : eucliDis;
+
+      const nx = dirX / eucliDis;
+      const ny = dirY / eucliDis;
+
+      let effectiveDist = eucliDis;
+      // 当启用 preventOverlap 时,考虑节点大小,确保有效距离不为负
+      if (preventOverlap) {
+        effectiveDist = Math.max(
+          0,
+          eucliDis - this.sizes[source] - this.sizes[target],
+        );
+      }
+
+      let faSource = effectiveDist;
+      let faTarget = effectiveDist;
+
+      if (mode === 'linlog') {
+        faSource = Math.log(1 + effectiveDist);
+        faTarget = faSource;
+      }
+
+      if (dissuadeHubs) {
+        faSource = effectiveDist / sourceDegree;
+        faTarget = effectiveDist / targetDegree;
+      }
+
+      this.forces[source][0] += faSource * nx;
+      this.forces[source][1] += faSource * ny;
+      this.forces[target][0] -= faTarget * nx;
+      this.forces[target][1] -= faTarget * ny;
+    }
+  }
+
+  private calculateOptRepulsiveGravity(): void {
+    const { model, options } = this;
+    const { kg, center, prune, kr } = options;
+
+    const nodes = model.nodes();
+    const n = nodes.length;
+
+    // Compute bounding box and set body positions
+    let minx = Number.POSITIVE_INFINITY;
+    let maxx = Number.NEGATIVE_INFINITY;
+    let miny = Number.POSITIVE_INFINITY;
+    let maxy = Number.NEGATIVE_INFINITY;
+
+    for (let i = 0; i < n; i += 1) {
+      const node = nodes[i];
+      const { id, x, y } = node;
+      if (prune && model.degree(id) <= 1) continue;
+      const body = this.bodies[id];
+      if (!body) continue;
+      body.setPos(x, y);
+      if (x < minx) minx = x;
+      if (x > maxx) maxx = x;
+      if (y < miny) miny = y;
+      if (y > maxy) maxy = y;
+    }
+
+    let width = Math.max(maxx - minx, maxy - miny);
+    if (!isFinite(width) || width <= 0) width = 1;
+
+    const quadParams = {
+      xmid: (maxx + minx) / 2,
+      ymid: (maxy + miny) / 2,
+      length: width,
+      massCenter: center,
+      mass: n,
+    };
+    const quad = new Quad(quadParams);
+    const quadTree = new QuadTree(quad);
+
+    // Insert bodies into tree
+    for (let i = 0; i < n; i += 1) {
+      const { id } = nodes[i];
+      if (prune && model.degree(id) <= 1) continue;
+      const body = this.bodies[id];
+      if (body && body.in(quad)) quadTree.insert(body);
+    }
+
+    // Compute forces
+    for (let i = 0; i < n; i += 1) {
+      const node = nodes[i];
+      const { id, x, y } = node;
+      const degree = model.degree(id);
+      if (prune && degree <= 1) continue;
+
+      const body = this.bodies[id];
+      if (!body) continue;
+      body.resetForce();
+      quadTree.updateForce(body);
+      this.forces[id][0] -= body.fx;
+      this.forces[id][1] -= body.fy;
+
+      // Gravity toward center
+      const dx = x - center[0];
+      const dy = y - center[1];
+      let dist = Math.hypot(dx, dy);
+      dist = dist < 1e-4 ? 1e-4 : dist;
+      const nx = dx / dist;
+      const ny = dy / dist;
+      const fg = kg * (degree + 1);
+      this.forces[id][0] -= fg * nx;
+      this.forces[id][1] -= fg * ny;
+    }
+  }
+
+  private calculateRepulsiveGravity(iter: number, krPrime: number): void {
+    const { model, options } = this;
+    const { preventOverlap, kr, kg, center, prune } = options;
+    const nodes = model.nodes();
+    const n = nodes.length;
+
+    for (let i = 0; i < n; i += 1) {
+      const nodei = nodes[i];
+      const degreei = model.degree(nodei.id);
+
+      for (let j = i + 1; j < n; j += 1) {
+        const nodej = nodes[j];
+        const degreej = model.degree(nodej.id);
+        if (prune && (degreei <= 1 || degreej <= 1)) continue;
+
+        const dx = nodej.x - nodei.x;
+        const dy = nodej.y - nodei.y;
+        let dist = Math.hypot(dx, dy);
+        dist = dist < 1e-4 ? 1e-4 : dist;
+        const nx = dx / dist;
+        const ny = dy / dist;
+
+        let effDist = dist;
+        let fr: number;
+
+        // 当启用 preventOverlap 时,考虑节点大小
+        if (preventOverlap) {
+          const overlap = dist - this.sizes[nodei.id] - this.sizes[nodej.id];
+          if (overlap < 0) {
+            // 节点重叠,使用强推力
+            fr = krPrime * (degreei + 1) * (degreej + 1);
+          } else if (overlap === 0) {
+            // 节点刚好接触,无斥力
+            fr = 0;
+          } else {
+            // 节点未重叠,使用正常斥力
+            effDist = overlap;
+            fr = (kr * (degreei + 1) * (degreej + 1)) / effDist;
+          }
+        } else {
+          fr = (kr * (degreei + 1) * (degreej + 1)) / effDist;
+        }
+
+        this.forces[nodei.id][0] -= fr * nx;
+        this.forces[nodei.id][1] -= fr * ny;
+        this.forces[nodej.id][0] += fr * nx;
+        this.forces[nodej.id][1] += fr * ny;
+      }
+
+      // Gravity toward center
+      const gx = nodei.x - center[0];
+      const gy = nodei.y - center[1];
+      let gdist = Math.hypot(gx, gy);
+      gdist = gdist < 1e-4 ? 1e-4 : gdist;
+      const gnx = gx / gdist;
+      const gny = gy / gdist;
+      const fg = kg * (degreei + 1);
+      this.forces[nodei.id][0] -= fg * gnx;
+      this.forces[nodei.id][1] -= fg * gny;
+    }
+  }
+
+  private updatePositions(): number {
+    const { model, options } = this;
+    const { ks, tao, prune, ksmax, distanceThresholdMode = 'max' } = options;
+    const nodes = model.nodes();
+    const n = nodes.length;
+
+    const swgns: Record<string, number> = {};
+    const trans: Record<string, number> = {};
+
+    let swgG = 0;
+    let traG = 0;
+
+    // -------- ① 计算 swg / tra --------
+    for (let i = 0; i < n; i += 1) {
+      const { id } = nodes[i];
+      const degree = model.degree(id);
+      if (prune && degree <= 1) continue;
+
+      const prev = this.preForces[id] || [0, 0];
+      const cur = this.forces[id] || [0, 0];
+
+      const minusX = cur[0] - prev[0];
+      const minusY = cur[1] - prev[1];
+      const minusNorm = Math.hypot(minusX, minusY);
+
+      const addX = cur[0] + prev[0];
+      const addY = cur[1] + prev[1];
+      const addNorm = Math.hypot(addX, addY);
+
+      swgns[id] = minusNorm;
+      trans[id] = addNorm / 2;
+
+      swgG += (degree + 1) * swgns[id];
+      traG += (degree + 1) * trans[id];
+    }
+
+    // -------- ② 更新 sg --------
+    let usingSg = this.sg;
+    const preSG = this.sg;
+    if (swgG <= 0) {
+      usingSg = preSG > 0 ? preSG : 1;
+    } else {
+      usingSg = (tao * traG) / swgG;
+      if (preSG !== 0) {
+        usingSg = usingSg > 1.5 * preSG ? 1.5 * preSG : usingSg;
+      }
+    }
+    this.sg = usingSg;
+
+    // -------- ③ 新增：distance 累计 --------
+    let maxDistance = 0;
+    let minDistance = Infinity;
+    let sumDistance = 0;
+    let movedCount = 0;
+
+    // -------- ④ 更新位置 --------
+    for (let i = 0; i < n; i += 1) {
+      const node = nodes[i];
+      const id = node.id;
+      const degree = model.degree(id);
+
+      if (prune && degree <= 1) continue;
+      if (this.isNodeFixed(node)) continue;
+
+      const swgVal = swgns[id] || 0;
+      let sn = (ks * usingSg) / (1 + usingSg * Math.sqrt(swgVal));
+
+      let absForce = Math.hypot(this.forces[id][0], this.forces[id][1]);
+      absForce = absForce < 1e-4 ? 1e-4 : absForce;
+
+      const maxStep = ksmax / absForce;
+      if (sn > maxStep) sn = maxStep;
+
+      const dx = sn * this.forces[id][0];
+      const dy = sn * this.forces[id][1];
+
+      node.x += dx;
+      node.y += dy;
+
+      // -------- ⑤ 记录位移 --------
+      const dist = Math.hypot(dx, dy);
+      if (dist > 0) {
+        movedCount++;
+        sumDistance += dist;
+        if (dist > maxDistance) maxDistance = dist;
+        if (dist < minDistance) minDistance = dist;
+      }
+    }
+
+    // -------- ⑥ 根据 mode 返回 distance --------
+    switch (distanceThresholdMode) {
+      case 'min':
+        return minDistance;
+      case 'mean':
+        return movedCount > 0 ? sumDistance / movedCount : 0;
+      case 'max':
+      default:
+        return maxDistance;
+    }
+  }
+
+  public destroy(): void {
+    this.stop();
+    this.forces = {};
+    this.preForces = {};
+    this.bodies = {};
+    this.sizes = {};
+    this.off();
+  }
+}

package/src/algorithm/force-atlas2/types.ts

@@ -0,0 +1,106 @@
+import type { CommonForceLayoutOptions, NodeData, Size } from '../../types';
+
+/**
+ * <zh/> ForceAtlas2 力导向布局配置
+ *
+ * <en/> ForceAtlas2 layout configuration
+ */
+export interface ForceAtlas2LayoutOptions extends CommonForceLayoutOptions {
+  /**
+   * <zh/> 斥力系数，可用于调整布局的紧凑程度。kr 越大，布局越松散
+   *
+   * <en/> The repulsive coefficient, which can be used to adjust the compactness of the layout. The larger kr is, the more relaxed the layout is
+   * @defaultValue 5
+   */
+  kr?: number;
+  /**
+   * <zh/> 重力系数。kg 越大，布局越聚集在中心
+   *
+   * <en/> The gravitational coefficient. The larger kg is, the more clustered the layout is in the center
+   * @defaultValue 1
+   */
+  kg?: number;
+  /**
+   * <zh/> 控制迭代过程中，节点移动的速度
+   *
+   * <en/> Control the speed of node movement during iteration
+   * @defaultValue 0.1
+   */
+  ks?: number;
+  /**
+   * <zh/> 迭代过程中，最大的节点移动的速度上限
+   *
+   * <en/> The upper limit of the maximum node movement speed during iteration
+   * @defaultValue 10
+   */
+  ksmax?: number;
+  /**
+   * <zh/> 迭代接近收敛时停止震荡的容忍度
+   *
+   * <en/> The tolerance for stopping oscillation when iteration is close to convergence
+   * @defaultValue 0.1
+   */
+  tao?: number;
+  /**
+   * <zh/> 聚类模式、'linlog' 模式下，聚类将更加紧凑
+   * - 'nornal'：普通模式
+   * - 'linlog'：linlog模式
+   * <en/> Clustering mode, the clustering will be more compact in the 'linlog' mode
+   * - 'normal'：normal mode
+   * - 'linlog'：linlog mode
+   * @defaultValue 'normal'
+   */
+  mode?: 'normal' | 'linlog';
+  /**
+   * <zh/> 是否防止重叠
+   *
+   * <en/> Whether to prevent overlap
+   * @remarks
+   * <zh/> 必须配合下面属性 nodeSize 或节点数据中的 data.size 属性，只有在数据中设置了 data.size 或在该布局中配置了与当前图节点大小相同的 nodeSize 值，才能够进行节点重叠的碰撞检测
+   *
+   * <en/> Must be used with the following properties: nodeSize or data.size in the node data. Only when data.size or nodeSize with the same value as the current graph node size is set in the layout configuration, can the collision detection of node overlap be performed
+   * @defaultValue false
+   */
+  preventOverlap?: boolean;
+  /**
+   * <zh/> 是否打开 hub 模式。若为 true，相比与出度大的节点，入度大的节点将会有更高的优先级被放置在中心位置
+   *
+   * <en/> Whether to open the hub mode. If true, nodes with high out-degree will have higher priority than nodes with high in-degree to be placed in the center
+   * @defaultValue false
+   */
+  dissuadeHubs?: boolean;
+  /**
+   * <zh/> 是否打开 barnes hut 加速，即四叉树加速
+   *
+   * <en/> Whether to open the barnes hut acceleration, that is, the quad tree acceleration
+   * @remarks
+   * <zh/> 由于每次迭代需要更新构建四叉树，建议在较大规模图上打开。默认情况下为 undefined，当节点数量大于 250 时它将会被激活。设置为 false 则不会自动被激活
+   *
+   * <en/> It is recommended to open it on large-scale graphs. By default, it will be activated when the number of nodes is greater than 250. Setting it to false will not be activated automatically
+   */
+  barnesHut?: boolean;
+  /**
+   * <zh/> 是否开启自动剪枝模式
+   *
+   * <en/> Whether to enable the automatic pruning mode
+   * @remarks
+   * <zh/> 默认情况下为 undefined，当节点数量大于 100 时它将会被激活。注意，剪枝能够提高收敛速度，但可能会降低图的布局质量。设置为 false 则不会自动被激活
+   *
+   * <en/> By default, it will be activated when the number of nodes is greater than 100. Note that pruning can improve the convergence speed, but it may reduce the layout quality of the graph. Setting it to false will not be activated automatically
+   */
+  prune?: boolean;
+  /**
+   * <zh/> 节点大小（直径）。用于防止节点重叠时的碰撞检测
+   *
+   * <en/> Node size (diameter). Used for collision detection when preventing node overlap
+   */
+  nodeSize?: Size | ((d?: NodeData) => Size);
+  /**
+   * <zh/> 节点间距。用于防止节点重叠时的碰撞检测
+   *
+   * <en/> Node spacing. Used for collision detection when preventing node overlap
+   */
+  nodeSpacing?: number | ((d?: NodeData) => number);
+}
+
+export type ParsedForceAtlas2LayoutOptions = Required<ForceAtlas2LayoutOptions>;

package/src/algorithm/fruchterman/index.ts

@@ -0,0 +1,116 @@
+import { BaseLayoutWithIterations } from '../base-layout';
+import type { ID, NodeData, NullablePosition } from '../../types';
+import {
+  applySingleNodeLayout,
+  getNestedValue,
+  normalizeViewport,
+} from '../../util';
+import { initNodePosition } from '../../model/data';
+import { Simulation } from './simulation';
+import type {
+  FruchtermanLayoutOptions,
+  ParsedFruchtermanLayoutOptions,
+} from './types';
+
+export type { FruchtermanLayoutOptions };
+
+const DEFAULTS_LAYOUT_OPTIONS: Partial<FruchtermanLayoutOptions> = {
+  maxIteration: 1000,
+  gravity: 10,
+  speed: 5,
+  clustering: false,
+  clusterGravity: 10,
+  width: 300,
+  height: 300,
+  nodeClusterBy: 'data.cluster',
+  dimensions: 2,
+};
+
+export class FruchtermanLayout extends BaseLayoutWithIterations<FruchtermanLayoutOptions> {
+  public id = 'fruchterman';
+
+  private simulation: Simulation | null = null;
+
+  protected getDefaultOptions(): Partial<FruchtermanLayoutOptions> {
+    return DEFAULTS_LAYOUT_OPTIONS;
+  }
+
+  protected parseOptions(
+    options?: Partial<FruchtermanLayoutOptions>,
+  ): ParsedFruchtermanLayoutOptions {
+    const { clustering, nodeClusterBy } = this.options;
+    const clusteringEnabled = clustering && !!nodeClusterBy;
+    const nodeClusterByFunc =
+      typeof nodeClusterBy === 'string'
+        ? (node: NodeData) => getNestedValue(node, nodeClusterBy)
+        : nodeClusterBy!;
+
+    Object.assign((options ||= {}), normalizeViewport(options), {
+      clustering: clusteringEnabled,
+      nodeClusterBy: nodeClusterByFunc,
+    });
+
+    return options as ParsedFruchtermanLayoutOptions;
+  }
+
+  protected async layout(): Promise<void> {
+    const options = this.parseOptions(this.options);
+
+    const { dimensions, center, width, height } = options;
+
+    const n = this.model.nodeCount();
+    if (!n || n === 1) {
+      applySingleNodeLayout(this.model, center, dimensions);
+      return;
+    }
+
+    initNodePosition(this.model, width, height, dimensions);
+
+    const simulation = this.setSimulation();
+
+    simulation.data(this.model);
+    simulation.initialize(options);
+    simulation.restart();
+
+    return new Promise<void>((resolve) => {
+      simulation.on('end', () => resolve());
+    });
+  }
+
+  private setSimulation() {
+    const simulation = this.simulation || new Simulation();
+
+    if (!this.simulation) {
+      this.simulation = simulation.on('tick', () =>
+        this.options.onTick?.(this),
+      );
+    }
+
+    return this.simulation;
+  }
+
+  public restart(): void {
+    this.simulation?.restart();
+  }
+
+  public stop(): void {
+    this.simulation?.stop();
+  }
+
+  public tick(iterations: number = 1): void {
+    this.simulation?.tick(iterations);
+  }
+
+  public setFixedPosition(id: ID, position: NullablePosition | null): void {
+    this.simulation?.setFixedPosition(id, position);
+  }
+
+  public destroy(): void {
+    super.destroy();
+
+    this.stop();
+
+    this.simulation?.destroy();
+    this.simulation = null;
+  }
+}