d3-graphviz

Renders SVG from graphs described in the DOT language using the @hpcc-js/wasm port of Graphviz and does animated transitions between graphs.

Features

• Rendering of SVG graphs from DOT source
• Animated transition of one graph into another
• Edge path tweening
• Node shape tweening
• Fade-in and fade-out of entering and exiting nodes and edges
• Animated growth of entering edges
• Panning & zooming of the generated graph

Graphviz methods typically return the Graphviz renderer instance, allowing the concise application of multiple operations on a given graph renderer instance via method chaining.

To render a graph, select an element, call selection.graphviz, and then render from a DOT source string. For example:

d3.select("#graph")
  .graphviz()
    .renderDot('digraph {a -> b}');

It is also possible to call d3.graphviz with a selector as the argument like so:

d3.graphviz("#graph")
    .renderDot('digraph {a -> b}');

This basic example can also be seen here.

A more colorful demo can be seen here.

Installing

The easiest way to use the library in your own application is to install it with NPM:

npm install d3-graphviz

If you don't use npm, you can download the latest release.

Building the library

You normally don't need to do this, but if you prefer, you can clone from github and build your own copy of the library with:

git clone https://github.com/magjac/d3-graphviz.git
cd d3-graphviz
npm install
npm run build

The built library will then be in build/d3-graphviz.js

Principles of Operation

Uses @hpcc-js/wasm to do a layout of a graph specified in the DOT language and generates an SVG text representation, which is analyzed and converted into a data representation. Then D3 is used to join this data with a selected DOM element, render the SVG graph on that element and to animate transitioning of one graph into another.

Contents

• API Reference
• Examples
• Building Applications with d3-graphviz
• Data Format
• Performance
• Requirements
• Support
• Development
• Credits

API Reference

• Defining the @hpcc-js/wasm Script Tag
• Creating a Graphviz Renderer
• Setting and Getting Options
• Getting the Graphviz version
• Rendering
• Images
• Creating Transitions
• Control Flow
• Controlling Fade-In & Fade-Out
• Controlling Animated Growth of Entering Edges
• Controlling Path Tweening
• Controlling Shape Tweening
• Maintaining Object Constancy
• Customizing Graph Attributes
• Accessing Elements of the Generated Graph
• Accessing the Extracted Data
• Modifying an Existing Graph and Animating the Changes
• Destroying the Graphviz Renderer

Defining the @hpcc-js/wasm Script Tag

The "@hpcc-js/wasm" script provides functions to do Graphviz layouts. If a web worker is used, these functions are called from the web worker which then loads and compiles the "@hpcc-js/wasm" script explicitly. In this case, it's unnecessary to let the browser also load and compile the script. This is accomplished by using the script tag "javascript/worker" which the browser does not identify to be Javascript and therefore does not compile. However, there are two d3-graphviz functions, drawNode and drawEdge that calls the layout functions directly and if they are going to be used, the script type must be "application/javascript" or "text/javascript".

Examples:

<script src="https://unpkg.com/@hpcc-js/wasm/dist/graphviz.umd.js" type="application/javascript/"></script>

This will always work, but will not be optimal if the script is used in a web worker only.

<script src="https://unpkg.com/@hpcc-js/wasm/dist/graphviz.umd.js" type="javascript/worker"></script>

This will work if a web worker is used and the drawNode and drawEdge functions are not used and will give shorter page load time.

The following table summarizes the recommended script type:

| | useWorker = true (default) or

useSharedWorker = true | useWorker = false and

useSharedWorker = false | |:--|:--|:--| | drawNode()/drawEdge() is not used | javascript/worker | application/javascript | | drawNode()/drawEdge() is used | application/javascript | application/javascript |

Creating a Graphviz Renderer

Creating a Graphviz Renderer on an Existing Selection

# selection.graphviz([options]) <>

Returns a new graphviz renderer instance on the first element in the given selection. If a graphviz renderer instance already exists on that element, instead returns the existing graphviz renderer instance. If options is specified and is an object, its properties are taken to be options to the graphviz renderer. All options except the useWorker and useSharedWorker options can also be changed later, using individual methods or the graphviz.options method, see below.

Supported options

Option	Default value
convertEqualSidedPolygons	true
engine	'dot'
fade	true
fit	false
growEnteringEdges	true
height	null
keyMode	'title'
scale	1
tweenPaths	true
tweenPrecision	1
tweenShapes	true
useWorker¹	true
useSharedWorker¹	false
width	null
zoom	true
zoomScaleExtent	[0.1, 10]
zoomTranslateExtent	[[-∞, -∞], [+∞, +∞]]

¹ Only has effect when the graphviz renderer instance is created.

All options are described below. Only the specified options will be changed. The others will keep their current values. If options is a boolean it is taken to be the useWorker option (for backwards compatibility).

The useWorker and useSharedWorker options

If the useSharedWorker option is truthy, a shared web worker will be used for the layout stage. Otherwise, if useWorker is truthy, a dedicated web worker will be used. If both are falsey, no web worker will be used.

Creating a Graphviz Renderer Using a Selector String or a Node

# d3.graphviz(selector[, options]) <>

Creates a new graphviz renderer instance on the first element matching the given selector string. If the selector is not a string, instead creates a new graphviz renderer instance on the specified node. If a graphviz renderer instance already exists on that element, instead returns the existing graphviz renderer instance. See selection.graphviz for a description of the options argument.

Setting and Getting Options

# graphviz.options([options]) <>

If options is specified it is taken to be an object whose properties are used to set options to the graphviz renderer. See selection.graphviz for a list of supported options. Most options can also be changed by individual methods which are described separately. If options is not specified, a copy of the currently set options are returned as an object.

Getting the Graphviz version

# graphviz.graphvizVersion() <>

Returns the Graphviz version.

Rendering

# graphviz.renderDot(dotSrc[, callback]) <>

Starts rendering of an SVG graph from the specified dotSrc string and appends it to the selection the Graphviz renderer instance was generated on. graphviz.renderDot returns "immediately", while the rendering is performed in the background. The layout stage is performed by a web worker (unless the use of a web worker was disabled when the renderer instance was created).

It is also possible to do the Graphviz layout in a first separate stage and do the actual rendering of the SVG as a second step like so:

d3.select("#graph")
  .graphviz()
    .dot('digraph {a -> b}')
    .render();

This enables doing the computational intensive layout stages for multiple graphs before doing the potentially synchronized rendering of all the graphs simultaneously.

# graphviz.dot(dotSrc[, callback]) <>

Starts computation of the layout of a graph from the specified dotSrc string and saves the data for rendering the SVG with graphviz.render at a later stage. graphviz.dot returns "immediately", while the layout is performed by a web worker in the backrgound. If callback is specified and not null, it is called with the this context as the graphviz instance, when the layout, data extraction and data processing has been finished.

# graphviz.render([callback]) <>

Starts rendering of an SVG graph from data saved by graphviz.dot and appends it to the selection the Graphviz renderer instance was generated on. graphviz.render returns "immediately", while the rendering is performed in the backrgound. If computation of a layout, started with the graphviz.dot method has not yet finished, the rendering task is placed in a queue and will commence when the layout is ready. If callback is specified and not null, it is called with the this context as the graphviz instance, when the graphviz renderer has finished all actions.

# graphviz.engine(engine) <>

Sets the Graphviz layout engine name to the specified engine string. In order to have effect, the engine must be set before calling graphviz.dot or graphviz.renderDot.