Features
ccNetViz enables enables custom styling of nodes and edges, curve edges, dynamic changes of the network, force-directed layout and basic graph interactivity. ccNetViz can be easily incorporated into single page applications using majority of web application frameworks (Example: ReactJS ). This page, designed using ReactJS, shows a sample of how ccNetViz can also help in styling the pages in a particular theme and at the same time look informative. ccNetViz boasts many intricate features for the flexibility of the programmer and all the major portions will be discussed in the each of the advanced example from coming chapters. The basic format in which ccNetViz library is used in creating a graph is shown below.
Basic Implementation
<!DOCTYPE html>
<html>
<head>
<title>ccNetViz example</title>
<style type="text/css">
#container {
width: 500px;
height: 500px;
}
</style>
<script src="dist/ccNetViz.min.js"></script>
</head>
<body>
<canvas id="container"/>
<script>
var graph = new ccNetViz(document.getElementById('container'), {
styles: {
node: { texture: "images/node.png", label: { hideSize: 16 } },
edge: { arrow: { texture: "images/arrow.png" } }
}});
var nodes = [
{ label: "Hello" },
{ label: "World" },
{ label: "!" }
];
var edges = [
{ source: nodes[0], target: nodes[1] },
{ source: nodes[1], target: nodes[2] },
{ source: nodes[2], target: nodes[1] }
];
graph.set(nodes, edges, "force");
graph.draw();
</script>
</body>
</html>
Some of the functions commonly used to generating a graph and designing it are explained below:
ccNetViz(element, options)
Creates new ccNetViz graph renderer attached to canvas element specified as first argument. The styles required for the particular layout and formatting can be done in the styles object and can be given as the second argument for options. The options argument basically customizes the graph and layouts according to the user. An example for the arguments can be seen below.
{
styles: {
background: { color: "rgb(0, 0, 0)" }, //background color of canvas, default: "rgb(255, 255, 255)"
node: { //predefined style
minSize: 8, //minimum size of node representation in pixels, default: 6
maxSize: 16, //maximum size of node representation in pixels, default: 16
color: "rgb(255, 0, 0)", //node color (combined with node image), default: "rgb(255, 255, 255)"
texture: "images/circle.png", //node image
label: {
hideSize: 16, //minimum size (height) for the label to be displayed
color: "rgb(120, 0, 0)", //label color, default: "rgb(120, 120, 120)"
font: { //label font
type: "Arial, Helvetica, sans-serif",
size: 15
}
}
},
edge: { //predefined style
width: 2, //edge width in pixels, default: 1
color: "rgb(86, 86, 86)", //edge color, default: "rgb(204, 204, 204)"
arrow: {
minSize: 6, //minimum size of arrow in pixels, default: 6
maxSize: 12, //maximum size of arrow, default: 12
aspect: 2, //aspect of arrow image, default: 1
texture: "images/arrow.png", //arrow image
hideSize: 2 //minimum size of arrow to be displayed
},
type: "line" //type of edge (supported types - "line", "dashed", "dotted", "chain-dotted")
},
nodeBlue: { //custom style
color: "rgb(0, 0, 255)"
},
nodeGiant: { //custom style
minSize: 16
},
nodeWithSmallBlueLabel: { //custom style
label: {
color: "rgb(0, 0, 255)",
font: { //label font
type: "Arial, Helvetica, sans-serif",
size: 11
}
}
},
nodeWithSDFFont: { //custom style with rendering SDF fonts
label: {
color: "rgb(0, 0, 255)",
font: {
type: "sdf",
texture: "fonts/OpenSans-Regular.png", //SDF (Signed distance field) texture
metrics: "fonts/OpenSans-Regular.json", //SDF metrics
size: 15,
outlineColor: "rgb(0,255,255)" //color of outline - optional ( if it is not setted - background color would be used )
}
}
},
edgeWideYellow: { //custom style
width: 4,
color: "rgb(255, 255, 0)"
},
edgeWithWhiteArrow: { //custom style
arrow: {
color: "rgb(255, 255, 255)"
}
}
},
onChangeViewport: function(viewport){}, //called every time viewport changes
onLoad: function(){}, //called when graph loaded
getNodesCount(){}, //callback to use if you want to force nodes count into this library (used to calculate curve excentricity and other built in options), expecting number as return value
getEdgesCount(){}, //callback to use if you want to force edges count into this library (used to calculate curve excentricity and other built in options), expecting number as return value
onDrag: function(viewport){}, //drag event, disable original event in case of return false
onZoom: function(viewport){}, //zoom event, disable original event in case of return false
onClick: function(){}, //called on click on graph
onDblClick: function(){}, //called on double click on graph
}
In a basic structure, there are predefined styles for nodes, edges and background.
- node: default
- edge: default
- background: default
All default property values of these styles can be overriden (as in example above). Besides overriding default styles (used for all nodes/edges) it is possible to define custom styles (like "nodeBlue" etc.) and then use this style just for specified subsets of nodes/edges. Property values specified for given custom style override default style values.
There are many options available for the SDF (signed distance field) fonts which can be used to display the text and titles in the graph. Helikar Lab has designed some common fonts which can be accessed from this page and also the user can generate fonts using node-fontnik.
set(nodes, edges, layout)
Sets the data to be displayed by given ccNetViz instance. "nodes" argument is an array of objects describing graph nodes. Each node can have following properties:
- label (optional): text label for given node (displayed if node labels are enabled by node label style)
- x, y (optional): predefined position for given node (if "layout" argument is not specified these positions will be used for graph layout)
- color (optional): ccNetViz.color object defining color for this given node (use this in case of coloring each node separately, for coloring groups of nodes use color property of node style)
- style (optional): name of custom style class used for this node (for example: "nodeBlue")
"edges" argument is an array of objects describing directed graph edges. There is also an option to show undirected graphs while defining the style of the graph which will be discussed in the further example implementations. Each edge in directed graphs has following properties:
- source: pointer to given source node object
- target: pointer to given target node object
- style (optional): name of custom style class used for this edge
Optional "layout" argument defines layout used to render this graph.
- Possible values: "force", "random", "circular", "tree".
If layout is not specified, positions are taken from each node x, y properties.
find(x, y, radius, nodes, edges)
findArea(x1, y1, x2, y2, nodes, edges)
draw()
- Renders current data into the element.
resize()
- Adjust graph for current canvas size.
resetView()
- Reset the zoom and panning for the graph.
setViewport(viewport)
- Set graph viewport.
"viewport" argument is an object with keys to modify (all of keys are optional). An example snippet for adjusting the viewport is shown below.
{
"x": 0.123, //x offset of viewport (number in range 0-1), optional
"y": 0.326, //y offset of viewport (number in range 0-1), optional
"size": 0.98, //size value of viewport (number in range 0-1) - the amount of original screen that is visible, optional
}
cntShownNodes()
- Get number of nodes
cntShownEdges()
- Get number of edges
remove()
- Clear graph and remove internal events from DOM.
nodes
- Property to access nodes data of given graph. Use this just to read current values, for modification use "set" method instead.
edges
- Property to access edges data of given graph. Use this just to read current values, for modification use "set" method instead.