The Cola.js physics simulation layout for Cytoscape.js (demo, non-animated demo, compound demo, constraint demo)
The cola
layout uses a force-directed physics simulation with several sophisticated constraints, written by Tim Dwyer. For more information about Cola and its parameters, refer to its documentation.
It supports noncompound and compound graphs well.
- Cytoscape.js ^3.2.0
- Cola.js ^3.1.2
Download the library:
- via npm:
npm install cytoscape-cola
, - via bower:
bower install cytoscape-cola
, or - via direct download in the repository (probably from a tag).
Import the library as appropriate for your project:
ES import:
import cytoscape from 'cytoscape';
import cola from 'cytoscape-cola';
cytoscape.use( cola );
CommonJS require:
let cytoscape = require('cytoscape');
let cola = require('cytoscape-cola');
cytoscape.use( cola ); // register extension
AMD:
require(['cytoscape', 'cytoscape-cola'], function( cytoscape, cola ){
cola( cytoscape ); // register extension
});
Plain HTML/JS has the extension registered for you automatically, because no require()
is needed.
Call the layout, e.g. cy.layout({ name: 'cola', ... })
, with options:
// default layout options
var defaults = {
animate: true, // whether to show the layout as it's running
refresh: 1, // number of ticks per frame; higher is faster but more jerky
maxSimulationTime: 4000, // max length in ms to run the layout
ungrabifyWhileSimulating: false, // so you can't drag nodes during layout
fit: true, // on every layout reposition of nodes, fit the viewport
padding: 30, // padding around the simulation
boundingBox: undefined, // constrain layout bounds; { x1, y1, x2, y2 } or { x1, y1, w, h }
nodeDimensionsIncludeLabels: false, // whether labels should be included in determining the space used by a node
// layout event callbacks
ready: function(){}, // on layoutready
stop: function(){}, // on layoutstop
// positioning options
randomize: false, // use random node positions at beginning of layout
avoidOverlap: true, // if true, prevents overlap of node bounding boxes
handleDisconnected: true, // if true, avoids disconnected components from overlapping
convergenceThreshold: 0.01, // when the alpha value (system energy) falls below this value, the layout stops
nodeSpacing: function( node ){ return 10; }, // extra spacing around nodes
flow: undefined, // use DAG/tree flow layout if specified, e.g. { axis: 'y', minSeparation: 30 }
alignment: undefined, // relative alignment constraints on nodes, e.g. {vertical: [[{node: node1, offset: 0}, {node: node2, offset: 5}]], horizontal: [[{node: node3}, {node: node4}], [{node: node5}, {node: node6}]]}
gapInequalities: undefined, // list of inequality constraints for the gap between the nodes, e.g. [{"axis":"y", "left":node1, "right":node2, "gap":25}]
centerGraph: true, // adjusts the node positions initially to center the graph (pass false if you want to start the layout from the current position)
// different methods of specifying edge length
// each can be a constant numerical value or a function like `function( edge ){ return 2; }`
edgeLength: undefined, // sets edge length directly in simulation
edgeSymDiffLength: undefined, // symmetric diff edge length in simulation
edgeJaccardLength: undefined, // jaccard edge length in simulation
// iterations of cola algorithm; uses default values on undefined
unconstrIter: undefined, // unconstrained initial layout iterations
userConstIter: undefined, // initial layout iterations with user-specified constraints
allConstIter: undefined, // initial layout iterations with all constraints including non-overlap
};
- The
alignment
option isn't as flexible as the raw Cola option. Here, only integers can be used to specify relative positioning, so it's a bit limited. If you'd like to see a more sophisticated implementation, please send a pull request.
npm run test
: Run Mocha tests in./test
npm run build
: Build./src/**
intocytoscape-cola.js
npm run watch
: Automatically build on changes with live reloading (N.b. you must already have an HTTP server running)npm run dev
: Automatically build on changes with live reloading with webpack dev servernpm run lint
: Run eslint on the source
N.b. all builds use babel, so modern ES features can be used in the src
.
This project is set up to automatically be published to npm and bower. To publish:
- Build the extension :
npm run build:release
- Commit the build :
git commit -am "Build for release"
- Bump the version number and tag:
npm version major|minor|patch
- Push to origin:
git push && git push --tags
- Publish to npm:
npm publish .
- If publishing to bower for the first time, you'll need to run
bower register cytoscape-cola https://github.com/cytoscape/cytoscape.js-cola.git
- Make a new release for Zenodo.