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.

• The term 'anchor' will be used here and in the code to refer to bend and control points collectively.
• To highlight anchor positions of an edge you should select the edge and unselect any other edges. Note that in determining the edge to highlight the anchor positions we assume that the unvisible edges are not selected.
• To add an anchor select the edge and unselect any other edge, right click where you want to add the anchor and click 'Add Bend Point' or 'Add Control Point' on the context menu (requires 'cytoscape.js-context-menus' extension). The context menu will distiguish between the edges and it will not be possible to a bend point on an unbundled bezier edge and vice versa.
• Bend points or control points can be added to edges which are not of type segments or unbundled bezier. The edge will then become segemetns or unbundled bezier accordingly.
• To remove an anchor select the edge and unselect any other edge, right click on the anchor and click 'Remove Bend Point' or 'Remove Control Point' on the context menu (requires 'cytoscape.js-context-menus' extension).
• To move an anchor drag and drop it when the edge is the only selected edge.
• Alternatively,
  • You can click anywhere on the edge (if it is the only selected edge) to introduce and relocate an anchor by dragging.
  • A bend point is removed if it is dropped near the line segment between its two neighbours.
• Drag and drop can also be used to quickly create and drag an anchor on a highlighted edge. The anchor type will be decided based on the edge type. This will not work with edges which are not segments or unbundled bezier.
• To reconnect an edge, select the handle (source or target), drag and drop on the new (source or target) node.

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.

Demo

Click here for demo

Dependencies

• Cytoscape.js ^3.3.0
• jQuery ^1.7.0 || ^2.0.0 || ^3.0.0
• Konva ^7.0.3
• cytoscape-undo-redo.js(optional) ^1.0.1
• cytoscape-context-menus.js(optional) ^2.0.0

Usage instructions

Download the library:

• via npm: npm install cytoscape-edge-editing,
• via bower: bower install cytoscape-edge-editing, or
• via direct download in the repository (probably from a tag).

require() the library as appropriate for your project:

CommonJS:

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

edgeEditing( cytoscape, jquery, konva ); // register extension

AMD:

require(['cytoscape', 'cytoscape-edge-editing', 'jquery', 'konva'], function( cytoscape, edge-editing, jquery, konva ){
  edge-editing( cytoscape, jquery, 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');
      },
      // 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,
      // 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 'Remove all bend points' and 'Remove all control points' options should be presented to the user
      enableMultipleAnchorRemovalOption: false,
      // whether the bend and control points can be moved by arrows
      moveSelectedAnchorsOnKeyEvents: function () {
          return true;
      },
      // this function handles reconnection of the edge, if undefined simply connect edge to its new source/target 
      // handleReconnectEdge (newSource.id(), newTarget.id(), edge.data())
      handleReconnectEdge: undefined,
      // this function checks validation of the edge and its new source/target
      validateEdge: function (edge, newSource, newTarget) {
         return 'valid';
      },
      // this function is called 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
    };

Build targets

• npm run build : Build ./src/** into cytoscape-edge-editing.js in production environment and minimize the file.
• npm run build:dev : Build ./src/** into cytoscape-edge-editing.js in development environment without minimizing the file.

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

• Metin Can Siper, Muhammed Salih Altun, Gledis Zeneli, Ugur Dogrusoz of i-Vis at Bilkent University

Alumni

• Ahmet Candiroglu