@deck.gl-community/graph-layers 9.0.2 → 9.1.0-beta.3

package/src/layouts/experimental/hive-plot-layout.ts

@@ -0,0 +1,182 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {GraphLayout, GraphLayoutOptions} from '../../core/graph-layout';
+import {Node} from '../../graph/node';
+import {EDGE_TYPE} from '../../core/constants';
+import {Graph} from '../../graph/graph';
+
+export type HivePlotLayoutOptions = GraphLayoutOptions & {
+  innerRadius?: number;
+  outerRadius?: number;
+  getNodeAxis?: (node: Node) => any;
+};
+
+export class HivePlotLayout extends GraphLayout<HivePlotLayoutOptions> {
+  static defaultOptions = {
+    innerRadius: 100,
+    outerRadius: 500,
+    getNodeAxis: (node: Node) => node.getPropertyValue('group')
+  } as const satisfies Readonly<Required<HivePlotLayoutOptions>>;
+
+  _name = 'HivePlot';
+  _graph: Graph;
+  _totalAxis: number;
+  _axis: Record<string, any>;
+  _nodeMap = {};
+  _nodePositionMap = {};
+
+  constructor(options: HivePlotLayoutOptions = {}) {
+    super(options);
+    this._options = {
+      ...HivePlotLayout.defaultOptions,
+      ...options
+    };
+  }
+
+  initializeGraph(graph: Graph) {
+    this.updateGraph(graph);
+  }
+
+  updateGraph(graph) {
+    const {getNodeAxis, innerRadius, outerRadius} = this._options;
+    this._graph = graph;
+    this._nodeMap = graph.getNodes().reduce((res, node) => {
+      res[node.getId()] = node;
+      return res;
+    }, {});
+
+    // bucket nodes into few axis
+
+    this._axis = graph.getNodes().reduce((res, node) => {
+      const axis = getNodeAxis(node);
+      if (!res[axis]) {
+        res[axis] = [];
+      }
+      res[axis].push(node);
+      return res;
+    }, {});
+
+    // sort nodes along the same axis by degree
+    this._axis = Object.keys(this._axis).reduce((res, axis) => {
+      const bucketedNodes = this._axis[axis];
+      const sortedNodes = bucketedNodes.sort((a, b) => {
+        if (a.getDegree() > b.getDegree()) {
+          return 1;
+        }
+        if (a.getDegree() === b.getDegree()) {
+          return 0;
+        }
+        return -1;
+      });
+      res[axis] = sortedNodes;
+      return res;
+    }, {});
+    this._totalAxis = Object.keys(this._axis).length;
+    const center = [0, 0];
+    const angleInterval = 360 / Object.keys(this._axis).length;
+
+    // calculate positions
+    this._nodePositionMap = Object.keys(this._axis).reduce((res, axis, axisIdx) => {
+      const axisAngle = angleInterval * axisIdx;
+      const bucketedNodes = this._axis[axis];
+      const interval = (outerRadius - innerRadius) / bucketedNodes.length;
+
+      bucketedNodes.forEach((node, idx) => {
+        const radius = innerRadius + idx * interval;
+        const x = Math.cos((axisAngle / 180) * Math.PI) * radius + center[0];
+        const y = Math.sin((axisAngle / 180) * Math.PI) * radius + center[1];
+        res[node.getId()] = [x, y];
+      });
+      return res;
+    }, {});
+  }
+
+  start() {
+    this._onLayoutChange();
+    this._onLayoutDone();
+  }
+
+  getNodePosition = (node) => this._nodePositionMap[node.getId()];
+
+  getEdgePosition = (edge) => {
+    const {getNodeAxis} = this._options;
+    const sourceNodeId = edge.getSourceNodeId();
+    const targetNodeId = edge.getTargetNodeId();
+
+    const sourcePosition = this._nodePositionMap[sourceNodeId];
+    const targetPosition = this._nodePositionMap[targetNodeId];
+
+    const sourceNode = this._nodeMap[sourceNodeId];
+    const targetNode = this._nodeMap[targetNodeId];
+
+    const sourceNodeAxis = getNodeAxis(sourceNode);
+    const targetNodeAxis = getNodeAxis(targetNode);
+
+    if (sourceNodeAxis === targetNodeAxis) {
+      return {
+        type: EDGE_TYPE.LINE,
+        sourcePosition,
+        targetPosition,
+        controlPoints: []
+      };
+    }
+
+    const controlPoint = computeControlPoint({
+      sourcePosition,
+      sourceNodeAxis,
+      targetPosition,
+      targetNodeAxis,
+      totalAxis: this._totalAxis
+    });
+
+    return {
+      type: EDGE_TYPE.SPLINE_CURVE,
+      sourcePosition,
+      targetPosition,
+      controlPoints: [controlPoint]
+    };
+  };
+
+  lockNodePosition = (node, x, y) => {
+    this._nodePositionMap[node.id] = [x, y];
+    this._onLayoutChange();
+    this._onLayoutDone();
+  };
+}
+
+function computeControlPoint({
+  sourcePosition,
+  sourceNodeAxis,
+  targetPosition,
+  targetNodeAxis,
+  totalAxis
+}): [number, number] {
+  const halfAxis = (totalAxis - 1) / 2;
+  // check whether the source/target are at the same side.
+  const sameSide =
+    (sourceNodeAxis <= halfAxis && targetNodeAxis <= halfAxis) ||
+    (sourceNodeAxis > halfAxis && targetNodeAxis > halfAxis);
+  // curve direction
+  const direction = sameSide && sourceNodeAxis <= halfAxis && targetNodeAxis <= halfAxis ? 1 : -1;
+
+  // flip the source/target to follow the clockwise diretion
+  const source = sourceNodeAxis < targetNodeAxis && sameSide ? sourcePosition : targetPosition;
+  const target = sourceNodeAxis < targetNodeAxis && sameSide ? targetPosition : sourcePosition;
+
+  // calculate offset
+  const distance = Math.hypot(source[0] - target[0], source[1] - target[1]);
+  const offset = distance * 0.2;
+
+  const midPoint = [(source[0] + target[0]) / 2, (source[1] + target[1]) / 2];
+  const dx = target[0] - source[0];
+  const dy = target[1] - source[1];
+  const normal = [dy, -dx];
+  const length = Math.hypot(dy, -dx);
+  const normalized = [normal[0] / length, normal[1] / length];
+  return [
+    midPoint[0] + normalized[0] * offset * direction,
+    midPoint[1] + normalized[1] * offset * direction
+  ];
+}

package/src/layouts/experimental/radial-layout.ts

@@ -0,0 +1,210 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {GraphLayout, GraphLayoutOptions} from '../../core/graph-layout';
+import {Node} from '../../graph/node';
+import {EDGE_TYPE} from '../../core/constants';
+import {Graph} from '../../graph/graph';
+
+export type RadialLayoutOptions = GraphLayoutOptions & {
+  radius?: number;
+  tree?: any;
+};
+
+const traverseTree = (nodeId, nodeMap) => {
+  const node = nodeMap[nodeId];
+  if (node.isLeaf) {
+    return node;
+  }
+  return {
+    ...node,
+    children: node.children.map((nid) => traverseTree(nid, nodeMap))
+  };
+};
+
+const getLeafNodeCount = (node, count) => {
+  if (!node.children || node.children.length === 0) {
+    return count + 1;
+  }
+  const sum = node.children.reduce((res, c) => {
+    return res + getLeafNodeCount(c, 0);
+  }, 0);
+  return count + sum;
+};
+
+const getTreeDepth = (node, depth = 0) => {
+  if (node.isLeaf) {
+    return depth;
+  }
+  return getTreeDepth(node.children[0], depth + 1);
+};
+
+const getPath = (node, targetId, path) => {
+  if (node.id === targetId) {
+    path.push(node.id);
+    return true;
+  }
+  const inChildren = node.children && node.children.some((c) => getPath(c, targetId, path));
+  if (inChildren) {
+    path.push(node.id);
+    return true;
+  }
+  return false;
+};
+
+export class RadialLayout extends GraphLayout<RadialLayoutOptions> {
+  static defaultOptions = {
+    radius: 500
+  };
+
+  _name = 'RadialLayout';
+  _graph: Graph = null;
+  // custom layout data structure
+  _hierarchicalPoints = {};
+  nestedTree;
+
+  constructor(options: RadialLayoutOptions = {}) {
+    super(options);
+    this._options = {
+      ...RadialLayout.defaultOptions,
+      ...options
+    };
+  }
+
+  initializeGraph(graph: Graph): void {
+    this.updateGraph(graph);
+  }
+
+  updateGraph(graph: Graph): void {
+    this._graph = graph;
+  }
+
+  start(): void {
+    const nodeCount = this._graph.getNodes().length;
+    if (nodeCount === 0) {
+      return;
+    }
+
+    const {tree} = this._options;
+
+    if (!tree || tree.length === 0) {
+      return;
+    }
+
+    const {radius} = this._options;
+    const unitAngle = 360 / nodeCount;
+
+    // hierarchical positions
+    const rootNode = tree[0];
+
+    const nodeMap = tree.reduce((res, node) => {
+      res[node.id] = {
+        ...node,
+        isLeaf: !node.children || node.children.length === 0
+      };
+      return res;
+    }, {});
+    // nested structure
+    this.nestedTree = traverseTree(rootNode.id, nodeMap);
+
+    const totalLevels = getTreeDepth(this.nestedTree, 0);
+    const distanceBetweenLevels = radius / (totalLevels - 1);
+
+    const calculatePosition = (node, level, startAngle, positionMap) => {
+      const isRoot = node.id === rootNode.id;
+
+      if (node.children && node.children.length !== 0) {
+        const groupSize = getLeafNodeCount(node, 0);
+        // center the pos
+        positionMap[node.id] = isRoot
+          ? [0, 0]
+          : rotate(
+              0,
+              0,
+              0,
+              distanceBetweenLevels * (level + 1),
+              startAngle + unitAngle * (groupSize / 2)
+            );
+        // calculate children position
+        let tempAngle = startAngle;
+        node.children.forEach((n) => {
+          calculatePosition(n, level + 1, tempAngle, positionMap);
+          tempAngle += getLeafNodeCount(n, 0) * unitAngle;
+        });
+      } else {
+        positionMap[node.id] = rotate(
+          0,
+          0,
+          0,
+          distanceBetweenLevels * (level + 1),
+          startAngle + unitAngle
+        );
+      }
+    };
+
+    this._hierarchicalPoints = {};
+    calculatePosition(this.nestedTree, 0, 0, this._hierarchicalPoints);
+    // layout completes: notifiy component to re-render
+    this._onLayoutChange();
+    this._onLayoutDone();
+  }
+
+  getNodePosition = (node) => {
+    return this._hierarchicalPoints[node.id];
+  };
+
+  // spline curve version
+  getEdgePosition = (edge) => {
+    const sourceNodeId = edge.getSourceNodeId();
+    const targetNodeId = edge.getTargetNodeId();
+    const sourceNodePos = this._hierarchicalPoints[sourceNodeId];
+    const targetNodePos = this._hierarchicalPoints[targetNodeId];
+
+    const sourcePath = [];
+    getPath(this.nestedTree, sourceNodeId, sourcePath);
+    const targetPath = [];
+    getPath(this.nestedTree, targetNodeId, targetPath);
+
+    const totalLevels = sourcePath.length;
+    let commonAncestorLevel = totalLevels - 1; // root
+    for (let i = 0; i < totalLevels; i++) {
+      if (sourcePath[i] === targetPath[i]) {
+        commonAncestorLevel = i;
+        break;
+      }
+    }
+
+    const wayPoints = [];
+    for (let i = 1; i <= commonAncestorLevel; i++) {
+      const nodeId = sourcePath[i];
+      wayPoints.push(this._hierarchicalPoints[nodeId]);
+    }
+    for (let i = commonAncestorLevel - 1; i > 0; i--) {
+      const nodeId = targetPath[i];
+      wayPoints.push(this._hierarchicalPoints[nodeId]);
+    }
+
+    return {
+      type: EDGE_TYPE.SPLINE_CURVE,
+      sourcePosition: sourceNodePos,
+      targetPosition: targetNodePos,
+      controlPoints: wayPoints
+    };
+  };
+
+  lockNodePosition = (node, x, y) => {
+    this._hierarchicalPoints[node.id] = [x, y];
+    this._onLayoutChange();
+    this._onLayoutDone();
+  };
+}
+
+function rotate(cx, cy, x, y, angle) {
+  const radians = (Math.PI / 180) * angle;
+  const cos = Math.cos(radians);
+  const sin = Math.sin(radians);
+  const nx = cos * (x - cx) + sin * (y - cy) + cx;
+  const ny = cos * (y - cy) - sin * (x - cx) + cy;
+  return [nx, ny];
+}

package/src/layouts/gpu-force/gpu-force-layout.ts

@@ -2,21 +2,32 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {BaseLayout} from '../../core/base-layout';
+import {GraphLayout, GraphLayoutOptions} from '../../core/graph-layout';
 
 import {EDGE_TYPE} from '../../core/constants';
 
-const defaultOptions = {
-  alpha: 0.3,
-  resumeAlpha: 0.1,
-  nBodyStrength: -900,
-  nBodyDistanceMin: 100,
-  nBodyDistanceMax: 400,
-  getCollisionRadius: 0
+export type GPUForceLayoutOptions = GraphLayoutOptions & {
+  alpha?: number;
+  resumeAlpha?: number;
+  nBodyStrength?: number;
+  nBodyDistanceMin?: number;
+  nBodyDistanceMax?: number;
+  getCollisionRadius?: number;
 };
 
-// TODO: this layout should be updated with the organizational and logic improvements made in d3-force
-export class GPUForceLayout extends BaseLayout {
+/**
+ * @todo this layout should be updated with the organizational and logic improvements made in d3-force
+ */
+export class GPUForceLayout extends GraphLayout<GPUForceLayoutOptions> {
+  static defaultOptions: Required<GPUForceLayoutOptions> = {
+    alpha: 0.3,
+    resumeAlpha: 0.1,
+    nBodyStrength: -900,
+    nBodyDistanceMin: 100,
+    nBodyDistanceMax: 400,
+    getCollisionRadius: 0
+  };
+
   protected readonly _name: string = 'GPU';
   private _d3Graph: any;
   private _nodeMap: any;
@@ -24,13 +35,17 @@ export class GPUForceLayout extends BaseLayout {
   private _graph: any;
   private _worker: Worker;
   private _callbacks: any;
-  constructor(options) {
-    super(options);
-    this._name = 'GPU';
-    this._options = {
-      ...defaultOptions,
+
+  constructor(options: GPUForceLayoutOptions = {}) {
+    const _options = {
+      ...GPUForceLayout.defaultOptions,
       ...options
     };
+
+    super(_options);
+
+    this._name = 'GPU';
+    this._options = _options;
     // store graph and prepare internal data
     this._d3Graph = {nodes: [], edges: []};
     this._nodeMap = {};
@@ -91,8 +106,8 @@ export class GPUForceLayout extends BaseLayout {
     }
 
     this._worker = new Worker(new URL('./worker.js', import.meta.url).href);
-    const {alpha, nBodyStrength, nBodyDistanceMin, nBodyDistanceMax, getCollisionRadius} = this
-      ._options as any;
+    const {alpha, nBodyStrength, nBodyDistanceMin, nBodyDistanceMax, getCollisionRadius} =
+      this._options;
     this._worker.postMessage({
       nodes: this._d3Graph.nodes,
       edges: this._d3Graph.edges,

package/src/layouts/{simple-layout/simple-layout.ts → simple-layout.ts}

@@ -2,30 +2,45 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {BaseLayout, BaseLayoutOptions} from '../../core/base-layout';
-import {Node} from '../../core/node';
-import {EDGE_TYPE} from '../../core/constants';
-import {Graph} from '../../core/graph';
-
-type AccessorVec2 = (node: Node) => [number, number];
-
-interface SimpleLayoutOptions extends BaseLayoutOptions {
-  nodePositionAccessor?: AccessorVec2;
-}
-
-const defaultOptions: Required<SimpleLayoutOptions> = {
-  nodePositionAccessor: (node) =>
-    [node.getPropertyValue('x'), node.getPropertyValue('y')] as [number, number]
+import {GraphLayout, GraphLayoutOptions} from '../core/graph-layout';
+import {Node} from '../graph/node';
+import {EDGE_TYPE} from '../core/constants';
+import {Graph} from '../graph/graph';
+
+export type SimpleLayoutOptions = GraphLayoutOptions & {
+  /** The accessor lets the application supply the position ([x, y]) of each node.
+   * @example
+    ```js
+    <GraphGL
+      {...otherProps}
+      layout={
+        new SimpleLayout({
+          nodePositionAccessor: node => [
+            node.getPropertyValue('x'),
+            node.getPropertyValue('y'),
+          ]
+        })
+      }
+    />
+    ```
+  */
+  nodePositionAccessor?: (node: Node) => [number, number];
 };
 
-export class SimpleLayout extends BaseLayout {
+/** A basic layout where the application controls positions of each node */
+export class SimpleLayout extends GraphLayout<SimpleLayoutOptions> {
+  static defaultOptions: Required<SimpleLayoutOptions> = {
+    nodePositionAccessor: (node) =>
+      [node.getPropertyValue('x'), node.getPropertyValue('y')] as [number, number]
+  };
+
   protected readonly _name = 'SimpleLayout';
   protected _graph: Graph | null = null;
   protected _nodeMap: Record<string, Node> = {};
-  protected _nodePositionMap: Record<string, AccessorVec2> = {};
+  protected _nodePositionMap: Record<string, (node: Node) => [number, number]> = {};
 
-  constructor(options = {}) {
-    super({...defaultOptions, ...options});
+  constructor(options: SimpleLayoutOptions = {}) {
+    super({...SimpleLayout.defaultOptions, ...options});
   }
 
   initializeGraph(graph: Graph): void {
@@ -57,7 +72,7 @@ export class SimpleLayout extends BaseLayout {
       return res;
     }, {});
     this._nodePositionMap = graph.getNodes().reduce((res, node) => {
-      res[node.getId()] = (this._options as any).nodePositionAccessor(node);
+      res[node.getId()] = this._options.nodePositionAccessor(node);
       return res;
     }, {});
   }

package/src/{utils → loaders}/create-graph.ts

@@ -2,11 +2,16 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {Edge} from '../core/edge';
-import {Node} from '../core/node';
-import {Graph} from '../core/graph';
+import {Edge} from '../graph/edge';
+import {Node} from '../graph/node';
+import {Graph} from '../graph/graph';
 
-export function createGraph({name, nodes, edges, nodeParser, edgeParser}) {
+/**
+ * @deprecated Use `new Graph(name, nodes, edges)`
+ * Create a graph from a list of Nodes and edges
+ */
+export function createGraph(props: {name; nodes; edges; nodeParser; edgeParser}) {
+  const {name, nodes, edges, nodeParser, edgeParser} = props;
   // create a new empty graph
   const graph = new Graph();
 

package/src/loaders/edge-parsers.ts

@@ -2,9 +2,10 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
+import type {EdgeOptions} from '../graph/edge';
 import {log} from '../utils/log';
 
-export function basicEdgeParser(edge) {
+export function basicEdgeParser(edge: any): Omit<EdgeOptions, 'data'> {
   const {id, directed, sourceId, targetId} = edge;
 
   if (sourceId === undefined || targetId === undefined) {

package/src/loaders/json-loader.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {createGraph} from '../utils/create-graph';
+import {createGraph} from './create-graph';
 import {basicNodeParser} from './node-parsers';
 import {basicEdgeParser} from './edge-parsers';
 import {log} from '../utils/log';

package/src/loaders/node-parsers.ts

@@ -2,9 +2,10 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
+import type {NodeOptions} from '../graph/node';
 import {log} from '../utils/log';
 
-export function basicNodeParser(node) {
+export function basicNodeParser(node: any): Pick<NodeOptions, 'id'> {
   if (node.id === undefined) {
     log.error('Invalid node: id is missing.')();
     return null;

package/src/loaders/simple-json-graph-loader.ts

@@ -0,0 +1,28 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {createGraph} from './create-graph';
+import {log} from '../utils/log';
+import {basicNodeParser} from './node-parsers';
+import {basicEdgeParser} from './edge-parsers';
+
+/** @deprecated Use loadSimpleJSONGraph */
+export const JSONLoader = ({json, nodeParser, edgeParser}) =>
+  loadSimpleJSONGraph(json, {nodeParser, edgeParser});
+
+/** A loader for a simple graph format  */
+export function loadSimpleJSONGraph(
+  json: Record<string, unknown>,
+  options?: {nodeParser; edgeParser}
+) {
+  const {nodeParser = basicNodeParser, edgeParser = basicEdgeParser} = options;
+  const {name = 'default', nodes, edges} = json;
+  if (!nodes) {
+    log.error('Invalid graph: nodes is missing.')();
+    return null;
+  }
+
+  const graph = createGraph({name, nodes, edges, nodeParser, edgeParser});
+  return graph;
+}