cytoscape.js-edge-editing

cytoscape-edge-editing

Description

A Cytoscape.js extension enabling interactive editing of edge bend and control points for segment and unbundled bezier edges, respectively. It also allows for reconnection of edges to other source/target nodes. The extension is distributed under The MIT License.

Please cite the following paper when using this extension:

U. Dogrusoz , A. Karacelik, I. Safarli, H. Balci, L. Dervishi, and M.C. Siper, “Efficient methods and readily customizable libraries for managing complexity of large networks”, PLoS ONE, 13(5): e0197238, 2018.

Here is a demo:

Dependencies

Usage instructions

Download the library:

require() the library as appropriate for your project:

CommonJS:

var cytoscape = require('cytoscape');
var konva = require('konva');
var edgeEditing = require('cytoscape-edge-editing');

edgeEditing( cytoscape, konva ); // register extension

AMD:

require(['cytoscape', 'cytoscape-edge-editing', 'konva'], function( cytoscape, edge-editing, konva ){
  edge-editing( cytoscape, konva ); // register extension
});

Plain HTML/JS has the extension registered for you automatically, because no require() is needed.

API

var instance = cy.edgeEditing( options );

An instance has a number of functions available:

/*
* Get anchors of the given edge in an array A,
* A[2 * i] is the x coordinate and A[2 * i + 1] is the y coordinate
* of the ith anchor. (Returns undefined if the curve style is not segments nor unbundled bezier)
*/
instance.getAnchorsAsArray(ele);
// Initilize anchors for the given edges using 'options.bendPositionsFunction' and 'options.controlPositionsFunction'
instance.initAnchorPoints(eles);
// Removes anchor with some index from an edge
instance.deleteSelectedAnchor(ele, index);
// Get type of an edge as `bend`, `control` or `none`
instance.getEdgeType(ele);

You can also get an existing instance:

cy.edgeEditing('get'); // Returns undefined if the extension is not initialized yet

Or you can check if the extension is initilized before

cy.edgeEditing('initialized');

Default Options

    var options = {
      // A function parameter to get bend point positions, should return positions of bend points
      bendPositionsFunction: function(ele) {
        return ele.data('bendPointPositions');
      },
      // Return true to draw rounded corners for the bend points. Requires Cytoscape^3.29.0
      bendCornersIsRoundFunction: function(ele) {
        return false;
      },
      // A function parameter to get control point positions, should return positions of control points
      controlPositionsFunction: function(ele) {
        return ele.data('controlPointPositions');
      },
      // A function parameter to set bend point positions
      bendPointPositionsSetterFunction: function(ele, bendPointPositions) {
        ele.data('bendPointPositions', bendPointPositions);
      },
      // A function parameter to set bend point positions
      controlPointPositionsSetterFunction: function(ele, controlPointPositions) {
        ele.data('controlPointPositions', controlPointPositions);
      },
      // whether to initilize bend and control points on creation of this extension automatically
      initAnchorsAutomatically: true,
      // the classes of those edges that should be ignored
      ignoredClasses: [],
      // whether the bend editing operations are undoable (requires cytoscape-undo-redo.js)
      undoable: false,
      // the size of bend and control point shape is obtained by multipling width of edge with this parameter
      anchorShapeSizeFactor: 3,
      // z-index value of the canvas in which bend points are drawn
      zIndex: 999,
       /*An option that controls the distance (in pixels) within which a bend point is considered near the line segment between 
         its two neighbors and will be automatically removed
         min value = 0 , max value = 20 , values less than 0 are set to 0 and values greater than 20 are set to 20
       */
      bendRemovalSensitivity : 8,
      // to not show a menu item, pass `false` for corresponding menu item title. Below are 6 menu item titles.
      // title of add bend point menu item (User may need to adjust width of menu items according to length of this option)
      addBendMenuItemTitle: "Add Bend Point",
      // title of remove bend point menu item (User may need to adjust width of menu items according to length of this option)
      removeBendMenuItemTitle: "Remove Bend Point",
      // title of remove all bend points menu item
      removeAllBendMenuItemTitle: "Remove All Bend Points",
      // title of add control point menu item (User may need to adjust width of menu items according to length of this option)
      addControlMenuItemTitle: "Add Control Point",
      // title of remove control point menu item (User may need to adjust width of menu items according to length of this option)
      removeControlMenuItemTitle: "Remove Control Point",
      // title of remove all control points menu item
      removeAllControlMenuItemTitle: "Remove All Control Points",
      // whether the bend and control points can be moved by arrows
      moveSelectedAnchorsOnKeyEvents: function () {
          return true;
      },
      // Can be a function or boolean. If `false`, edge reconnection won't be active. If `true`, connects edge to its new source/target as usual. 
      // If a function is given, the function will be called with parameters: newSource.id(), newTarget.id(), edge.data(), location
      handleReconnectEdge: true,
      // Can be `false` or `true`. If `false`, it won't interact with anchors (control and bend points). If `false`, it won't show any context menu items as well.
      handleAnchors: true,
      // this function checks validation of the edge and its new source/target
      validateEdge: function (edge, newSource, newTarget) {
         return 'valid';
      },
      // this function is called with reconnected edge if reconnected edge is not valid according to `validateEdge` function
      actOnUnsuccessfulReconnection: undefined,
      // specifically for edge-editing menu items, whether trailing dividers should be used
      useTrailingDividersAfterContextMenuOptions: false,
      // Enable / disable drag creation of anchor points when there is at least one anchor already on the edge
      enableCreateAnchorOnDrag: true,
      // size of anchor point can be auto changed to compensate the impact of zoom
      enableFixedAnchorSize: false,
      // automatically remove anchor (bend point) if its previous segment and next segment is almost in a same line
      enableRemoveAnchorMidOfNearLine: true,
      // edge reconnection handles can be shown with select or hover events
      isShowHandleOnHover: false,
      anchorColor: '#000000',  // default anchor color is black
      endPointColor: '#000000' // default endpoint color is black
    };

Build targets

Publishing instructions

This project is set up to automatically be published to npm and bower. To publish:

  1. Build the extension : npm run build
  2. Commit the build : git commit -am "Build for release"
  3. Bump the version number and tag: npm version major|minor|patch
  4. Push to origin: git push && git push --tags
  5. Publish to npm: npm publish .
  6. If publishing to bower for the first time, you’ll need to run bower register cytoscape-edge-editing https://github.com/iVis-at-Bilkent/cytoscape.js-edge-editing.git

Team

Alumni

This site is open source. Improve this page.