Visualization with GraphVIZ DOT

AutomataLib provides a very convenient way of visualizing automata and graphs, using the well-known GraphVIZ DOT tool. Visualization here means both exporting them to a DOT file, which can be processed for rendering by external tools (such as those distributed with GraphVIZ), and also rendering and displaying them directly from your application using a Java interface. This page will guide you on how to accomplish this.

Impatient readers interested in application only may skip right to the example.

Prerequisites

In order to use DOT for visualizing automata and graphs, the GraphVIZ software has to be installed on your machine (downloads page). Additionally, the dot (dot.exe on Windows) utility has to be installed in a directory contained in the PATH environment variable.

Customizing the Rendering

The central interface for customizing how an automaton or graph is rendered is VisualizationHelper (source, javadoc) from the automata-api artifact. This interface declares two methods to implement:

• getStateProperties() allows to define GraphVIZ properties for single nodes (states), or signal to suppress rendering them by returning false. For example, invoking properties.put(SHAPE, "box") will lead to the current node being rendered as a rectangle instead of a circle.
• getEdgeProperties() allows to define GraphVIZ properties for single edges (transitions), or signal to suppress rendering them by returning false. For example, invoking properties.put("style", "dashed") will lead to the respective edge being drawn using a dashed line.

In case you want to explicitly target DOT-based rendering, you may implemented the refined DOTVisualizationHelper (source, javadoc) interface which delcares to additional methods:

• writePreamble() can be used to write arbitrary GraphVIZ statements before the actual body of the graph is written (but after the opening digraph {). This could, for example, include additional nodes.
• writePostamble() can be used to write arbitrary GraphVIZ statements after the actual body of the graph has been written. In this method, nodes (states) from the graph (automaton) can be referenced by a mapping providing their ID, which is not possible in the writePreamble method.

Graphs

A graph can be annotated with custom information about how it prefers to be rendered by overriding the default #getVisualizationHelper method on the Graph (source, javadoc) interface.

Rendering an Automaton or Graph Object to DOT

Transforming an Automaton or Graph object to a DOT description is handled by the GraphDOT (source, javadoc) utility class. The procedure slightly differs, depending on whether an Automaton or a Graph should be rendered, and whether or not this comes with instructions how it prefers to be rendered.

All of the methods mentioned below take a parameter of type Appendable, to which the DOT description is written. Appendable is a very lean interface, implemented by most of the Java framework classes appropriate for this goal, like StringBuilder, BufferedWriter and so on.

Visualizing DOT in Your Application

The Visualization (source, javadoc) factory provides several methods that facilitate interaction with an external visualizer. For using the DOT-based visualizer provided by AutomataLib, you need to provide the dot-visualizer JAR (of the automata-dot-visualizer artifact) on the classpath (e.g., via a Maven runtime dependency). The service loader mechanism of the JVM will then automatically load the respective classes and opens a (Swing) window displaying the rendering result (or a message box, if there were errors during rendering). The optional modal parameter decides whether or not the window shall be modal or not. In the former case, the call to close() will block, and execution (in the calling thread) will not proceed until the window is closed.

Example

The following listing shows how a simple graph can be visualized in a modal window.

Graph<?,?> graph = ...;

Visualization.visualize(graph, true);