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

package/src/algorithm/force/repulsive.ts

@@ -0,0 +1,200 @@
+import { octree } from 'd3-octree';
+import { quadtree } from 'd3-quadtree';
+import type { PointObject } from '../../types';
+import { AccMap } from './types';
+import type { GraphLib } from '../../model/data';
+
+/**
+ * Repulsive force based on Coulomb's law
+ * Uses Barnes-Hut optimization with quadtree/octree
+ */
+export function forceRepulsive(
+  factor: number = 1,
+  coulombDisScale: number = 0.005,
+  dimensions: number = 2,
+) {
+  function force(model: GraphLib, accMap: AccMap) {
+    const coulombDisScale2 = coulombDisScale * coulombDisScale;
+    forceNBody(model, factor, coulombDisScale2, accMap, dimensions);
+  }
+
+  force.factor = function (_?: number) {
+    return arguments.length ? ((factor = _!), force) : factor;
+  };
+
+  force.coulombDisScale = function (_?: number) {
+    return arguments.length ? ((coulombDisScale = _!), force) : coulombDisScale;
+  };
+
+  force.dimensions = function (_?: number) {
+    return arguments.length ? ((dimensions = _!), force) : dimensions;
+  };
+
+  return force;
+}
+
+const theta2 = 0.81; // Barnes-Hut approximation threshold
+const epsilon = 0.1; // 为了防止出现除0的情况，加一个epsilon
+
+interface InternalNode {
+  id: string;
+  x: number;
+  y: number;
+  z: number;
+  vx: number;
+  vy: number;
+  vz: number;
+  weight: number;
+  size: number;
+}
+
+export function forceNBody(
+  model: GraphLib,
+  factor: number,
+  coulombDisScale2: number,
+  accMap: { [id: string]: PointObject },
+  dimensions: number = 2,
+) {
+  const weightParam = factor / coulombDisScale2;
+  const nodes = model.nodes();
+
+  const data = nodes.map((node, i) => {
+    const { nodeStrength, x, y, z, size, mass } = node;
+    return {
+      x,
+      y,
+      z,
+      size,
+      index: i,
+      id: node.id,
+      vx: 0,
+      vy: 0,
+      vz: 0,
+      weight: weightParam * nodeStrength,
+      mass: mass || 1,
+    };
+  });
+
+  const tree = (
+    dimensions === 2
+      ? quadtree(
+          data,
+          (d: any) => d.x,
+          (d: any) => d.y,
+        )
+      : octree(
+          data,
+          (d: any) => d.x,
+          (d: any) => d.y,
+          (d: any) => d.z,
+        )
+  ).visitAfter(accumulate); // init internal node
+
+  const nodeMap = new Map();
+  data.forEach((n) => {
+    nodeMap.set(n.id, n);
+    // @ts-ignore
+    computeForce(n, tree, dimensions);
+  });
+  data.map((n) => {
+    const id = n.id;
+    // 从 0 开始，= 初始化 + 加斥力
+    accMap[id] = {
+      x: n.vx / n.mass,
+      y: n.vy / n.mass,
+      z: n.vz / n.mass,
+    };
+  });
+  return accMap;
+}
+
+function accumulate(treeNode: any) {
+  let accWeight = 0;
+  let accX = 0;
+  let accY = 0;
+  let accZ = 0;
+  let accSize = 0;
+  const numChildren = treeNode.length;
+
+  if (numChildren) {
+    // internal node, accumulate 4 child quads
+    for (let i = 0; i < numChildren; i++) {
+      const q = treeNode[i];
+      if (q && q.weight) {
+        accWeight += q.weight;
+        accX += q.x * q.weight;
+        accY += q.y * q.weight;
+        accZ += q.z * q.weight;
+        accSize += q.size * q.weight;
+      }
+    }
+    treeNode.x = accX / accWeight;
+    treeNode.y = accY / accWeight;
+    treeNode.z = accZ / accWeight;
+    treeNode.size = accSize / accWeight;
+    treeNode.weight = accWeight;
+  } else {
+    // leaf node
+    const q = treeNode;
+    treeNode.x = q.data.x;
+    treeNode.y = q.data.y;
+    treeNode.z = q.data.z;
+    treeNode.size = q.data.size;
+    treeNode.weight = q.data.weight;
+  }
+}
+
+const apply = (
+  treeNode: any,
+  x1: number,
+  arg1: number,
+  arg2: number,
+  arg3: number,
+  arg4: number,
+  arg5: number,
+  node: InternalNode,
+  dimensions: number,
+) => {
+  if (treeNode.data?.id === node.id) return;
+  const x2 = dimensions === 2 ? arg2 : dimensions === 3 ? arg4 : arg1;
+
+  const dx = node.x - treeNode.x || epsilon;
+  const dy = node.y - treeNode.y || epsilon;
+  const dz = node.z - treeNode.z || epsilon;
+  const pos = [dx, dy, dz];
+  const width = x2 - x1;
+  let len2 = 0;
+  for (let i = 0; i < dimensions; i++) {
+    len2 += pos[i] * pos[i];
+  }
+  const len1 = Math.sqrt(len2);
+  const len3 = len1 * len2;
+
+  // far node, apply Barnes-Hut approximation
+  if (width * width * theta2 < len2) {
+    const param = treeNode.weight / len3;
+    node.vx += dx * param;
+    node.vy += dy * param;
+    node.vz += dz * param;
+    return true;
+  }
+  // near quad, compute force directly
+  if (treeNode.length) return false; // internal node, visit children
+
+  // leaf node
+
+  if (treeNode.data !== node) {
+    const param = treeNode.data.weight / len3;
+    node.vx += dx * param;
+    node.vy += dy * param;
+    node.vz += dz * param;
+  }
+};
+
+// @ts-ignore
+function computeForce(node: InternalNode, tree: any, dimensions: number) {
+  // @ts-ignore
+  tree.visit((treeNode, x1, y1, arg2, arg3, arg4, arg5) =>
+    apply(treeNode, x1, y1, arg2, arg3, arg4, arg5, node, dimensions),
+  );
+}

package/src/algorithm/force/simulation.ts

@@ -0,0 +1,172 @@
+import { isNumber } from '@antv/util';
+import { BaseSimulation } from '../base-simulation';
+import type { LayoutNode, NullablePosition } from '../../types';
+import type { GraphLib } from '../../model/data';
+import type { AccMap, ParsedForceLayoutOptions } from './types';
+
+interface Force {
+  (model: GraphLib, accMap: AccMap): void;
+  [key: string]: any;
+}
+
+export class ForceSimulation extends BaseSimulation<ParsedForceLayoutOptions> {
+  private forces = new Map<string, Force>();
+  private velMap: AccMap = {};
+
+  protected model!: GraphLib;
+
+  data(model: GraphLib): this {
+    this.model = model;
+
+    model.forEachNode((node) => {
+      this.velMap[node.id] = { x: 0, y: 0, z: 0 };
+    });
+
+    return this;
+  }
+
+  force(name: string, force?: Force | null) {
+    if (arguments.length === 1) return this.forces.get(name) || null;
+    if (force === null) this.forces.delete(name);
+    else if (force) this.forces.set(name, force);
+    return force || null;
+  }
+
+  protected runOneStep(): number {
+    const accMap: AccMap = {};
+    const nodes = this.model.nodes();
+    if (!nodes.length) return 0;
+
+    nodes.forEach((n) => {
+      accMap[n.id] = { x: 0, y: 0, z: 0 };
+    });
+
+    this.forces.forEach((force) => {
+      force(this.model, accMap);
+    });
+
+    this.updateVelocity(accMap);
+    const distance = this.updatePosition();
+
+    this.monitor(accMap, nodes);
+
+    return distance;
+  }
+
+  setFixedPosition(nodeId: string, position: NullablePosition | null) {
+    const node = this.model.node(nodeId);
+    if (!node) return;
+
+    const keys = ['fx', 'fy', 'fz'] as const;
+
+    if (position === null) {
+      keys.forEach((k) => delete node[k]);
+      return;
+    }
+
+    position.forEach((v, i) => {
+      if (i < keys.length && (typeof v === 'number' || v === null)) {
+        node[keys[i]] = v;
+      }
+    });
+
+    const vel = this.velMap[nodeId];
+    if (vel) {
+      vel.x = 0;
+      vel.y = 0;
+      vel.z = 0;
+    }
+  }
+
+  private updateVelocity(accMap: AccMap) {
+    const {
+      damping = 0.9,
+      maxSpeed = 100,
+      interval = 0.02,
+      dimensions = 2,
+    } = this.options;
+
+    this.model.nodes().forEach((node) => {
+      const id = node.id;
+      let vx = (this.velMap[id].x + accMap[id].x * interval) * damping;
+      let vy = (this.velMap[id].y + accMap[id].y * interval) * damping;
+      let vz =
+        dimensions === 3
+          ? (this.velMap[id].z + accMap[id].z * interval) * damping
+          : 0;
+
+      const vLen = Math.sqrt(vx * vx + vy * vy + vz * vz);
+      if (vLen > maxSpeed) {
+        const k = maxSpeed / vLen;
+        vx *= k;
+        vy *= k;
+        vz *= k;
+      }
+
+      this.velMap[id] = { x: vx, y: vy, z: vz };
+    });
+  }
+
+  private updatePosition(): number {
+    const {
+      distanceThresholdMode = 'mean',
+      interval = 0.02,
+      dimensions = 2,
+    } = this.options;
+
+    const nodes = this.model.nodes();
+    let sum = 0;
+    let judge =
+      distanceThresholdMode === 'max'
+        ? -Infinity
+        : distanceThresholdMode === 'min'
+        ? Infinity
+        : 0;
+
+    nodes.forEach((node) => {
+      const id = node.id;
+
+      if (isNumber(node.fx) && isNumber(node.fy)) {
+        node.x = node.fx;
+        node.y = node.fy;
+        if (dimensions === 3 && isNumber(node.fz)) node.z = node.fz;
+        return;
+      }
+
+      const dx = this.velMap[id].x * interval;
+      const dy = this.velMap[id].y * interval;
+      const dz = dimensions === 3 ? this.velMap[id].z * interval : 0;
+
+      node.x += dx;
+      node.y += dy;
+      if (dimensions === 3) node.z = (node.z || 0) + dz;
+
+      const dist = Math.sqrt(dx * dx + dy * dy + dz * dz);
+
+      if (distanceThresholdMode === 'max') judge = Math.max(judge, dist);
+      else if (distanceThresholdMode === 'min') judge = Math.min(judge, dist);
+      else sum += dist;
+    });
+
+    return distanceThresholdMode === 'mean' ? sum / nodes.length : judge;
+  }
+
+  private monitor(accMap: AccMap, nodes: LayoutNode[]) {
+    const { monitor, dimensions = 2 } = this.options;
+    if (!monitor) return;
+
+    let energy = 0;
+    nodes.forEach((node) => {
+      const a = accMap[node.id];
+      const v2 = a.x * a.x + a.y * a.y + (dimensions === 3 ? a.z * a.z : 0);
+      energy += (node.mass || 1) * v2 * 0.5;
+    });
+
+    monitor({
+      energy,
+      nodes,
+      edges: this.model.edges(),
+      iterations: this.iteration,
+    });
+  }
+}

package/src/algorithm/force/types.ts

@@ -0,0 +1,265 @@
+import type {
+  CommonForceLayoutOptions,
+  EdgeData,
+  NodeData,
+  Point,
+  Size,
+} from '../../types';
+
+export type AccMap = { [id: string]: { x: number; y: number; z: number } };
+
+/**
+ * <zh/> 向心力配置，包括叶子节点、离散点、其他节点的向心中心及向心力大小
+ *
+ * <en/> Centripetal configuration, including the center of the leaf node, the center of the scattered point, and the center of the other nodes
+ */
+export interface CentripetalOptions {
+  /**
+   * <zh/> 叶子节点（即度数为 1 的节点）受到的向心力大小
+   * - number: 固定向心力大小
+   * - ((node: NodeData, nodes: NodeData[], edges: EdgeData[]) => number): 可根据节点、边的情况返回不同的值
+   * <en/> The centripetal force of the leaf node (i.e., the node with degree 1)
+   * - number: fixed centripetal force size
+   * - ((node: NodeData, nodes: NodeData[], edges: EdgeData[]) => number): return different values according to the node, edge, and situation
+   * @defaultValue 2
+   */
+  leaf?:
+    | number
+    | ((node: NodeData, nodes: NodeData[], edges: EdgeData[]) => number);
+  /**
+   * <zh/> 离散节点（即度数为 0 的节点）受到的向心力大小
+   * - number: 固定向心力大小
+   * - ((node: NodeData, nodes: NodeData[], edges: EdgeData[]) => number): 可根据节点情况返回不同的值
+   * <en/> The centripetal force of the scattered node (i.e., the node with degree 0)
+   * - number: fixed centripetal force size
+   * - ((node: NodeData) => number): return different values according to the node situation
+   * @defaultValue 2
+   */
+  single?: number | ((node: NodeData) => number);
+  /**
+   * <zh/> 除离散节点、叶子节点以外的其他节点（即度数 > 1 的节点）受到的向心力大小
+   * - number: 固定向心力大小
+   * - ((node: NodeData) => number): 可根据节点的情况返回不同的值
+   * <en/> The centripetal force of the other nodes (i.e., the node with degree > 1)
+   * - number: fixed centripetal force size
+   * - ((node: NodeData) => number): return different values according to the node situation
+   * @defaultValue 1
+   */
+  others?: number | ((node: NodeData) => number);
+  /**
+   * <zh/> 向心力发出的位置，可根据节点、边的情况返回不同的值、默认为图的中心
+   *
+   * <en/> The position where the centripetal force is emitted, which can return different values according to the node, edge, and situation. The default is the center of the graph
+   */
+  center?: (
+    node: NodeData,
+    nodes: NodeData[],
+    edges: EdgeData[],
+    width: number,
+    height: number,
+  ) => {
+    x: number;
+    y: number;
+    z?: number;
+    centerStrength?: number;
+  };
+}
+
+interface FormatCentripetalOptions extends CentripetalOptions {
+  leaf: (node: NodeData, nodes: NodeData[], edges: EdgeData[]) => number;
+  /** Force strength for single nodes. */
+  single: (node: NodeData) => number;
+  /** Force strength for other nodes. */
+  others: (node: NodeData) => number;
+}
+
+export interface ForceLayoutOptions extends CommonForceLayoutOptions {
+  /**
+   * <zh/> 边的长度
+   * - number: 固定长度
+   * - ((edge?: EdgeData, source?: any, target?: any) => number): 根据边的信息返回长度
+   * <en/> The length of the edge
+   * - number: fixed length
+   * - ((edge?: EdgeData, source?: any, target?: any) => number): return length according to the edge information
+   * @defaultValue 200
+   */
+  linkDistance?:
+    | number
+    | ((edge?: EdgeData, source?: any, target?: any) => number);
+  /**
+   * <zh/> 节点作用力，正数代表节点之间的引力作用，负数代表节点之间的斥力作用
+   *
+   * <en/> The force of the node, positive numbers represent the attraction force between nodes, and negative numbers represent the repulsion force between nodes
+   * @defaultValue 1000
+   */
+  nodeStrength?: number | ((d?: NodeData) => number);
+  /**
+   * <zh/> 边的作用力（引力）大小
+   *
+   * <en/> The size of the force of the edge (attraction)
+   * @defaultValue 50
+   */
+  edgeStrength?: number | ((d?: EdgeData) => number);
+  /**
+   * <zh/> 是否防止重叠，必须配合下面属性 nodeSize 或节点数据中的 data.size 属性，只有在数据中设置了 data.size 或在该布局中配置了与当前图节点大小相同的 nodeSize 值，才能够进行节点重叠的碰撞检测
+   *
+   * <en/> Whether to prevent overlap, must be used with the following properties nodeSize or data.size in the node data, and only when the data.size is set in the data or the nodeSize value is configured with the same value as the current graph node size in the layout configuration, can the node overlap collision detection be performed
+   * @defaultValue true
+   */
+  preventOverlap?: boolean;
+  /**
+   * <zh/> 节点大小（直径）。用于防止节点重叠时的碰撞检测
+   *
+   * <en/> The size of the node (diameter). Used for collision detection when preventing node overlap
+   */
+  nodeSize?: Size | ((d?: NodeData) => Size);
+  /**
+   * <zh/> preventOverlap 为 true 时生效, 防止重叠时节点边缘间距的最小值。可以是回调函数, 为不同节点设置不同的最小间距
+   *
+   * <en/> It is effective when preventOverlap is true. The minimum spacing of the node edge when preventing overlap. It can be a callback function to set different minimum spacing for different nodes
+   */
+  nodeSpacing?: number | ((d?: NodeData) => number);
+  /**
+   * <zh/> 阻尼系数，取值范围 [0, 1]。数字越大，速度降低得越慢
+   *
+   * <en/> Damping coefficient, the range of the value is [0, 1]. The larger the number, the slower the speed will decrease
+   * @defaultValue 0.9
+   */
+  damping?: number;
+  /**
+   * <zh/> 一次迭代的最大移动长度
+   *
+   * <en/> The maximum movement length of one iteration
+   * @defaultValue 200
+   */
+  maxSpeed?: number;
+  /**
+   * <zh/> 库伦系数，斥力的一个系数，数字越大，节点之间的斥力越大
+   *
+   * <en/> Coulomb's coefficient, a coefficient of repulsion, the larger the number, the larger the repulsion between nodes
+   * @defaultValue 0.005
+   */
+  coulombDisScale?: number;
+  /**
+   * <zh/> 中心力大小，指所有节点被吸引到 center 的力。数字越大，布局越紧凑
+   *
+   * <en/> The size of the center force, which attracts all nodes to the center. The larger the number, the more compact the layout
+   * @defaultValue 10
+   */
+  gravity?: number;
+  /**
+   * <zh/> 斥力系数，数值越大，斥力越大
+   *
+   * <en/> The repulsion coefficient, the larger the number, the larger the repulsion
+   * @defaultValue 1
+   */
+  factor?: number;
+  /**
+   * <zh/> 控制每个迭代节点的移动速度
+   *
+   * <en/> Control the movement speed of each iteration node
+   * @defaultValue 0.02
+   */
+  interval?: number;
+  /**
+   * <zh/> 向心力配置，包括叶子节点、离散点、其他节点的向心中心及向心力大小
+   *
+   * <en/> Centripetal configuration, including the centripetal center of leaf nodes, discrete points, and the centripetal center of other nodes
+   */
+  centripetalOptions?: CentripetalOptions;
+  /**
+   * <zh/> 是否需要叶子结点聚类
+   *
+   * <en/> Whether to cluster leaf nodes
+   * @remarks
+   * <zh/> 若为 true，则 centripetalOptions.single 将为 100；centripetalOptions.leaf 将使用 getClusterNodeStrength 返回值；getClusterNodeStrength.center 将为叶子节点返回当前所有叶子节点的平均中心
+   *
+   * <en/> If it is true, centripetalOptions.single will be 100; centripetalOptions.leaf will use the return value of getClusterNodeStrength; getClusterNodeStrength.center will be the average center of all leaf nodes
+   * @defaultValue false
+   */
+  leafCluster?: boolean;
+  /**
+   * <zh/> 是否需要全部节点聚类
+   *
+   * <en/> Whether to cluster all nodes
+   * @remarks
+   * <zh/> 若为 true，将使用 nodeClusterBy 配置的节点数据中的字段作为聚类依据。 centripetalOptions.single、centripetalOptions.leaf、centripetalOptions.others 将使用 getClusterNodeStrength 返回值；leaf、centripetalOptions.center 将使用当前节点所属聚类中所有节点的平均中心
+   *
+   * <en/> If it is true, the node data configured by nodeClusterBy will be used as the clustering basis. centripetalOptions.single, centripetalOptions.leaf, centripetalOptions.others will use the return value of getClusterNodeStrength; leaf、centripetalOptions.center will use the average center of all nodes in the current cluster
+   * @defaultValue false
+   */
+  clustering?: boolean;
+  /**
+   * <zh/> 指定节点数据中的字段名称作为节点聚类的依据，clustering 为 true 时生效，自动生成 centripetalOptions，可配合 clusterNodeStrength 使用
+   *
+   * <en/> Specify the field name of the node data as the clustering basis for the node, and it takes effect when clustering is true. You can combine it with clusterNodeStrength to use it
+   */
+  nodeClusterBy?: (node: NodeData) => string;
+  /**
+   * <zh/> 配合 clustering 和 nodeClusterBy 使用，指定聚类向心力的大小
+   *
+   * <en/> Use it with clustering and nodeClusterBy to specify the size of the centripetal force of the cluster
+   * @defaultValue 20
+   */
+  clusterNodeStrength?: number | ((node: NodeData) => number);
+  /**
+   * <zh/> 防止重叠的力强度，范围 [0, 1]
+   *
+   * <en/> The strength of the force that prevents overlap, range [0, 1]
+   * @defaultValue 1
+   */
+  collideStrength?: number;
+  /**
+   * <zh/> 每个节点质量的回调函数，如参为节点内部流转数据，返回值为质量大小
+   *
+   * <en/> The callback function for the mass of each node, if the parameter is the internal circulation data of the node, the return value is the size of the mass
+   * @param node - <zh/> 节点数据 | <en/> NodeData data
+   * @returns <zh/> 节点质量大小 | <en/> Mass size of the node
+   */
+  getMass?: (node?: NodeData) => number;
+  /**
+   * <zh/> 每个节点中心力的 x、y、强度的回调函数，若不指定，则没有额外中心力
+   *
+   * <en/> The callback function for the center force of each node, if not specified, there will be no additional center force
+   * @param node - <zh/> 节点数据 | <en/> NodeData data
+   * @param degree - <zh/> 节点度数 | <en/> NodeData degree
+   * @returns <zh/> 中心力 x、y、强度 | <en/> Center force x、y、strength
+   */
+  getCenter?: (node?: NodeData, degree?: number) => number[];
+  /**
+   * <zh/> 每个迭代的监控信息回调，energy 表示布局的收敛能量。若配置可能带来额外的计算能量性能消耗，不配置则不计算
+   *
+   * <en/> The callback function for monitoring information of each iteration, energy indicates the convergence energy of the layout. If not configured, it will not calculate
+   * @param params - <zh/> 监控信息 | <en/> Monitoring information
+   */
+  monitor?: (params: {
+    energy: number;
+    nodes: NodeData[];
+    edges: EdgeData[];
+    iterations: number;
+  }) => void;
+}
+
+export interface ParsedForceLayoutOptions extends ForceLayoutOptions {
+  width: number;
+  height: number;
+  center: Point;
+  minMovement: number;
+  maxIteration: number;
+  factor: number;
+  interval: number;
+  damping: number;
+  maxSpeed: number;
+  coulombDisScale: number;
+  centripetalOptions: FormatCentripetalOptions;
+  nodeSize: (d?: NodeData) => number;
+  getMass: (d?: NodeData) => number;
+  nodeStrength: (d?: NodeData) => number;
+  edgeStrength: (d?: EdgeData) => number;
+  linkDistance: (
+    edge?: EdgeData,
+    source?: NodeData,
+    target?: NodeData,
+  ) => number;
+  clusterNodeStrength: (node?: NodeData) => number;
+}