Multi-step-graphviz NPM

Graphviz Steps Parser

Graphviz files parser to allow multiple Graphviz sequences in one file.

Have you ever wanted animated Graphviz diagrams? The kind you see when you look at the demos in d3-graphviz.

You could just use d3-graphviz, but you have to code all the examples and create new dot source strings for each step in the animation.

Or you can use the Graphviz Steps Parser which parses a Graphviz dot string with some extra annotations as comments, and it identifies each step in the diagram and helps you generate sequences of dot strings suitable for animating via the d3-graphviz library.

Quick Example

This Graphviz dot source, has 3 steps in it, you can spot them as the # comments in the source.

digraph G {
    a -> b
    # STEP add c
    a -> c
    c -> b
    # STEP add d
    a -> d
    d -> b
    # END
    b -> end
}

This will still render as a normal Graphviz diagram:

npm.io

If you use the same source with Graphviz Steps Parser to parse it into individual dot strings then you can render each of them using d3-graphviz then you can render it as an animated graph.

npm.io

online example

Using it yourself

If you are familiar with Javascript then you should be able to get started by looking at the source code for the generate.demo.html application.

Until we create a proper editor, if you want to work from your own dot file you can:

open editor example
click anywhere on the screen
paste in your Graphviz graph at the input prompt
click OK

For web usage you can include the graphviz-step-parser.js from the dist folder:

<script src="graphviz-step-parser.js"></script>

You also need to add the d3-graphviz dependencies:

<script src="https://cdnjs.cloudflare.com/ajax/libs/d3/7.8.0/d3.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@hpcc-js/wasm/dist/graphviz.umd.js" type="javascript/worker"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/d3-graphviz/5.0.2/d3-graphviz.min.js"></script>

A simple `npm` usage example

https://www.npmjs.com/package/multi-step-graphviz

npm install multi-step-graphviz

Then using require:

var GraphvizSteps = require('multi-step-graphviz');

var stepDot=`
digraph G {
    a -> b
    # STEP add c
    a -> c
    c -> b
    # STEP add d
    a -> d
    d -> b
    # END
    b -> end
}`;

var stepParser = new GraphvizSteps.GraphvizStepParser();
stepParser.parse(stepDot);
var dots = stepParser.dotVersions;

console.log(dots.length);
console.log(dots[0]);
console.log(dots[1]);
console.log(dots[2]);

Basic Example

All directives to control the animation are added as "#" comments in the Graphviz.

e.g.

digraph G {
    a -> b
    # STEP
    b -> c
    # END
}

The two most important are:

"# STEP" lines under this are part of a step
"# END" everything after this is the end of the graph

Everything before the first "# START" is included in all animation steps.

e.g. the example above converts into two graphs

digraph G {
    a -> b
}

digraph G {
    a -> b
    b -> c
}

Reference

All directives should be added to the graph as # comment lines e.g. # STEP
There are 3 top level directives STEP, END, DIRECTIVE
All animated Graphs should have an END directive comment to make sure the generated graph is valid
A STEP directive comment starts an animation step and everything under it until the next step is included
Directives can be named e.g. # Step add c to describe what happens in the step
The name can be used with lower level directives
There are 3 lower level directives UNCOMMENT_//, DISABLE_STEP <stepname>, ENABLE_STEP <stepname>
DISABLE_STEP <stepname> will disable an earlier named step
Lower level directives can be nested for easier visibility
A DIRECTIVE comment is used when we want to define some lower level directives which apply for to all following steps e.g.

digraph G {
    a -> b
    # STEP remove later
    a -> c
    # DIRECTIVE
    #   DISABLE_STEP remove later
    # STEP
    a -> d
    # STEP
    d -> e
    # END
}

A DIRECTIVE comment does not output a Graphviz dot graph, it is applied to later steps
ENABLE_STEP <stepname> will enable an earlier named step e.g.

digraph G {
    a -> b
    # STEP enable disable
    a -> c
    # DIRECTIVE
    #   DISABLE_STEP enable disable
    # STEP
    a -> d
    # DIRECTIVE
    #   ENABLE_STEP enable disable
    # STEP
    d -> e
    # END
}

UNCOMMENT_// will uncomment any // commented lines in the step

   # STEP add c
   #    UNCOMMENT_//
   // a -> c

UNCOMMENT_// is used when we might want to use the Graphviz as a 'final' output in a normal Graphviz tool and we have some temporary Graphviz commands that are useful when shown as an intermediate step, but not in the final output.

Hints and Tips

I find it useful to create the animation from top to bottom.
Disabling steps later when I don't need them.
If I find that a section is temporary and not needed for the final output then I comment the Graphviz lines out with // and add UNCOMENT_// as a lower level directive in the STEP
Graphviz handles duplicate definitions well so we don't have to disable previous steps e.g.

digraph G {
    a -> b
    a[label="Hello"]
    # STEP
    b [label="World"]
    # STEP
    b [label="World", shape=square]
    # STEP
    b [label="World", shape=square, style=filled, fillcolor=red]
    # END
}

This project is still in its early stages so I've been using screen capture tools to record the graphs from the editor and example html pages.