''Note to non-wiki readers: This documentation is generated from the Eclipse wiki - if you have corrections or additions it would be awesome if you added them in [http://wiki.eclipse.org/Graphviz_DOT_as_a_DSL_for_Zest the original wiki page]''

The goal of this project is to implement the [http://www.graphviz.org/ Graphviz] [http://www.graphviz.org/doc/info/lang.html DOT language] as a domain-specific language (DSL) for [http://www.eclipse.org/gef/zest/ Zest: The Eclipse Visualization Toolkit], both as an input and output format. In other words, the goal is to transform both DOT graphs to Zest visualizations (to be used in Java SWT applications), and Zest visualizations to DOT graphs (to be rendered as image files with Graphviz).

+

This Eclipse feature provides support for the [http://www.graphviz.org/ Graphviz] [http://www.graphviz.org/doc/info/lang.html DOT language] in [http://www.eclipse.org/gef/zest/ Zest: The Eclipse Visualization Toolkit], both as an input and output format. It provides API und UI elements to transform both DOT graphs to Zest visualizations (to be used in Java SWT applications), and Zest visualizations to DOT graphs (to be rendered as image files with Graphviz).

−

==Resources==

+

== User Documentation ==

−

The main bug for this project is {{bug|277380}}. View a [https://bugs.eclipse.org/bugs/buglist.cgi?query_format=specific&order=relevance+desc&bug_status=__all__&product=GEF&content=%5Bdot4zest%5D complete list] of related bugs. If you have suggestions for this project you can [https://bugs.eclipse.org/bugs/enter_bug.cgi?bug_file_loc=http%3A%2F%2Fwiki.eclipse.org%2FGraphviz_DOT_as_a_DSL_for_Zest&bug_severity=enhancement&bug_status=NEW&comment=&component=Zest&contenttypeentry=&contenttypemethod=autodetect&contenttypeselection=text%2Fplain&data=&description=&flag_type-1=X&flag_type-2=X&flag_type-6=X&form_name=enter_bug&maketemplate=Remember%20values%20as%20bookmarkable%20template&op_sys=All&priority=P3&product=GEF&rep_platform=All&short_desc=%5Bdot4zest%5D%20New%20request%20summary&version=unspecified file a new bug]. The CVS repository for this project is located at ''cvs.dot4zest.berlios.de:/cvsroot/dot4zest''; [http://developer.berlios.de/cvs/?group_id=10849 access info]. You can also [http://download.berlios.de/cvstarballs/dot4zest-cvsroot.tar.gz download nightly CVS snapshots].

+

=== Installation ===

−

To run the current work in progress code, check out the bundles from the CVS repository above in Eclipse 3.4 (Ganymede). Besides the Zest and JET features (which are available from the Ganymede update site), you will need to install the oAW 4.3.1 Graphviz feature from the oAW update site at ''http://oawbranch.pluginbuilder.org/releases/p2-updateSite/''.

+

This feature is part of Zest 2. See further information on [[Zest#Zest_2.x|Zest 2]].

−

Run the ''*Suite.java'' test suites of the individual bundles (in src-test/) as JUnit tests to get an impression of the current implementation state.

The Zest Graph view can visualize DOT graphs in *.dot files or embedded in other files in the workspace. The view draws the DOT graphs using Zest and allows for image export of the current Zest graph. When automatic updating is enabled (see below), and a *.dot file or embedded DOT content is added to the workspace or altered in an editor, the Zest graph view is updated with the graph created from the DOT input. For instance, consider a file with the .dot extension, containing the following DOT graph definition:

The view contains buttons to toggle automatic updates, to load a specific file containing a DOT graph, and to layout the current graph. To export the current Zest graph as an image file by calling the ''dot'' executable, the view contains buttons to re-select the directory containing the ''dot'' executable, to enable export of the original DOT input, and to export as an image file (from left to right). When the image export button is selected, a PDF for the current graph is saved in the directory containing the file with the DOT input, and opened with the associated external editor, if one is available. In this example, the export looks like this:

−

/* Set up a directed Zest graph with a single connection: */

+

−

Graph graph = new Graph(shell, SWT.NONE);

+

−

graph.setConnectionStyle(ZestStyles.CONNECTIONS_DIRECTED);

+

−

GraphConnection edge = new GraphConnection(graph, SWT.NONE,

+

−

new GraphNode(graph, SWT.NONE, "Node 1"),

+

−

new GraphNode(graph, SWT.NONE, "Node 2"));

+

−

edge.setText("A dotted edge");

+

−

edge.setLineStyle(SWT.LINE_DOT);

+

−

/* Export the Zest graph to a DOT string or a DOT file: */

+

−

System.out.println(DotExport.exportZestGraph(graph));

+

−

DotExport.exportZestGraph(graph, new File("src-gen/DirectSample.dot"));

+

−

</pre>

+

−

See the included [http://cvs.berlios.de/cgi-bin/viewvc.cgi/dot4zest/org.eclipse.zest.dot.export/src-test/org/eclipse/zest/DotExportSample.java?view=markup sample] (from above), [http://cvs.berlios.de/cgi-bin/viewvc.cgi/dot4zest/org.eclipse.zest.dot.export/src-test/org/eclipse/zest/dot/test_data test files], and documentation for further information.

+

[[Image:DotZestM2Rendered.png]]

+

This provides a Zest-based DOT authoring environment. If a *.dot file or embedded DOT is edited, it will be visualized in the Zest Graph view (e.g. during editing), and can be exported as a PDF with Graphviz.

−

===Milestone 1===

+

At the same time the view provides a simple way to visualize *.dot file output of any kind of program, e.g. to visualize and debug internal data structures, results, etc: if a program running in Eclipse outputs any *.dot file in the workspace and the workspace is refreshed, the view will be updated with the corresponding Zest graph (if automatic updating is enabled, see above).

To use the API, create a new Plug-in project, add ''org.eclipse.gef4.zest.dot.core'' to the MANIFEST.MF dependencies, paste the code below into the source folder of the created project, and select ''Run As > Java Application'':

−

The intended timeline consists of 6 core and 2 optional milestones. This should ensure providing the core functionality described below even if things take longer than expected, and very flexible, integrated and complete (realizing and using all the connections in the figure below) support for existing Eclipse visualization technology if all works out as planned.

+

import org.eclipse.swt.SWT;

+

import org.eclipse.swt.layout.FillLayout;

+

import org.eclipse.swt.widgets.Display;

+

import org.eclipse.swt.widgets.Shell;

+

import org.eclipse.gef4.zest.dot.DotGraph;

+

+

public class SampleUsage {

+

+

public static void main(String[] args) {

+

Shell shell = new Shell();

+

DotGraph graph = new DotGraph("digraph{ 1->2 }", shell, SWT.NONE);

+

graph.add("2->3").add("2->4");

+

graph.add("node[label=zested]; edge[style=dashed]; 3->5; 4->6");

+

open(shell);

+

System.out.println(graph.toDot());

+

}

+

+

private static void open(final Shell shell) {

+

shell.setText(DotGraph.class.getSimpleName());

+

shell.setLayout(new FillLayout());

+

shell.setSize(600, 300);

+

shell.open();

+

Display display = shell.getDisplay();

+

while (!shell.isDisposed())

+

if (!display.readAndDispatch())

+

display.sleep();

+

display.dispose();

+

}

+

+

}

−

<table border="0" cellspacing="3" cellpadding="2" width="100%">

+

The complete sample usage is [http://git.eclipse.org/c/gef/org.eclipse.gef4.git/tree/org.eclipse.gef4.zest.tests/src/org/eclipse/gef4/zest/tests/dot/SampleUsage.java available in the repository], as well as working [http://git.eclipse.org/c/gef/org.eclipse.gef4.git/tree/org.eclipse.gef4.zest.tests/resources/tests DOT input samples].

I believe both Graphviz input and output for Zest would make a lot of sense: Graphviz is a very popular tool and its DOT language is widely used. Support for it could make using Zest very easy for many people who are familiar with DOT.

+

==== DOT import ====

−

It would also be useful for existing Eclipse tools that are based on Graphviz, like [http://abstratt.com/textuml/ TextUML] or [http://eclipsegraphviz.wiki.sourceforge.net/ EclipseGraphviz], and possibly others, for instance in the [http://tasktop.com/blog/eclipse/rich-editing-for-tasks-via-mylyn-wikitext Mylyn rich task editor] (for embedding DOT graphs in the wiki text markup, visualized with Zest).

+

During import of DOT graphs into Zest, the DOT layout specified in the input is mapped to the most suitable Zest layout algorithm - e.g. for the following DOT graph:

−

On the output side, Zest could benefit from Graphviz output as it provides a way to produce high-quality export into different file formats, e.g. for printing Zest visualizations, or using them in digital publications.

+

graph { 1--2--3; 2--4--5 }

−

As Graphviz supports many different node shapes, edge styles, layouts etc. the goal of this project is not to provide support for all Graphviz features (or even as many as possible), but to set up initial basic support (directed and undirected graphs, edge and node labels, edge styles, basic layout support) and focus on the infrastructure to make these transformations usable instead (see user interface section below), which will hopefully create a solid foundation for future expansion (see section on future ideas below).

+

If the graph defines a Graphviz layout, it is mapped to a Zest layout as below:

−

==Implementation==

+

graph[layout=dot];

−

I plan to implement the desired functionality based on [http://www.eclipse.org/modeling/ Eclipse Modeling] technologies, in particular [http://wiki.eclipse.org/Xtext Xtext] (part of [http://www.eclipse.org/modeling/tmf TMF]) and [http://wiki.eclipse.org/Xpand Xpand] (part of [http://www.eclipse.org/modeling/m2t M2T]) for the input part (parse DOT, generate Zest) and [http://wiki.eclipse.org/M2T-JET JET] for the output (see details below). The sketched approach (see figure on the right) depends on Eclipse components only (Xtext, Xpand, JET, and oAW).

An Xtext grammar, parser and Xpand generators for Graphviz DOT already exist in openArchitectureWare (oAW) 4.3 (the relevant bundles org.openarchitectureware.graphviz.*, are now part of the [http://code.google.com/p/emfmodelvisualizer/ EMF model visualizer project]).

+

graph[layout=twopi];

−

Based on this, my plan is to implement an Xpand generator that transforms Graphviz DOT descriptions into Java code that creates an equivalent Zest visualization (see figure on the right and M1 in the timeline below). I also want to provide a way to define Zest animations using the DOT language (by representing animation steps as subgraphs in DOT, see M5 in the timeline).

+

[[Image:Zest2-twopi-zest.png|150px]]

−

===Zest to DOT===

+

graph[layout=osage];

−

To transform Zest graph instances to the Graphviz DOT language I intend to use [http://wiki.eclipse.org/M2T-JET JET] (see figure on the right and M2 in the timeline).

+

[[Image:Zest2-osage-zest.png|150px]]

−

There are two reasons I plan to use JET instead of Xpand here. First, I'd like to be able to transform any Zest graph instance to DOT directly (not only those for which we have a DOT meta model instance that could act as the input to Xpand). Second, even if we had a DOT meta model instance (which we could create from the Zest graph), using Xpand would introduce a runtime dependency on the [http://wiki.eclipse.org/Modeling_Workflow_Engine_(MWE) Modeling Workflow Engine], whereas with JET we only introduce a dependency on a single class (the generator class JET created from the template).

+

==== DOT export ====

−

===User Interface===

+

When Zest graphs are exported to DOT (whether created from DOT or not), the most suitable Graphviz layout is choosen, e.g.:

−

To make these transformations available to the user, my general plan is to make the DOT to Zest transformations (which depend on Eclipse modeling technology at runtime) available as part of the workbench, while the generated Zest graph classes and the DOT output can be used directly and without (or with very little, see above) additional runtime dependencies, e.g. in pure Zest SWT applications.

To generate Zest from DOT, I intend to implement a wizard that creates a Zest graph subclass and basic sample usage code (see examples below) from a Graphviz DOT file or from direct DOT input inside the wizard (see M3 in the timeline). I imagine offering different DOT templates to the user (e.g. ''simple directed graph'', ''simple animation''), which can be edited in the wizard, with a live preview of what the Zest graph is going to look like next to it.

+

[[Image:Zest2-dot-graphviz.png|100px]]

−

Extending this kind of functionality, I'd like to implement a Zest project type where the DOT files are placed in a special folder (and can be edited conveniently using the DOT editor from oAW). Using a project builder, the corresponding Zest Graph implementation classes will be generated, which can be used from other parts of the project's code, similar to JET templates and generators (see M4 in the timeline).

To provide visualization of DOT graphs using Zest in a workbench, I want to create Xpand generators which provide compatibility with the EMF model visualizer language and its Zest-based visualization view (see dotted arrows in the figure above and M6 in the timeline).

From this, roughly the code below should be generated (comments to be generated omitted here). It's a Zest Graph subclass which is populated with the specified objects on construction, and includes export to DOT via a generator class generated by JET (commented out here to make the example compile). It also contains some sample usage code in a main method to make it runnable as a plain Java SWT application, which renders as shown in the image on the right.

+

digraph subgraphs {

−

+

subgraph cluster1 { 1 -> 2; 2 -> 3; 2 -> 4 }

−

[[Image:DotZestSimple.png|right|150px]]

+

subgraph cluster2 { a -> b; a -> c; a -> d }

+

}

−

<pre>

+

[[Image:DotZestSubgraphs1.png|400px]]

−

/** Zest Graph to be generated from "digraph simple { 1 -> 2 }" */

+

−

public class SimpleDirectedGraph extends Graph {

+

−

public SimpleDirectedGraph(Composite parent, int style) {

+

−

super(parent, style);

+

−

setConnectionStyle(ZestStyles.CONNECTIONS_DIRECTED);

+

−

GraphNode n1 = new GraphNode(this, SWT.NONE, "1");

+

−

GraphNode n2 = new GraphNode(this, SWT.NONE, "2");

+

−

new GraphConnection(this, SWT.NONE, n1, n2);

+

−

setLayoutAlgorithm(new TreeLayoutAlgorithm(

+

−

LayoutStyles.NO_LAYOUT_NODE_RESIZING), true);

+

−

}

+

−

public String toString() {

+

−

return super.toString(); // new GraphTemplate().generate(this);

+

−

}

+

−

public static void main(String[] args) {

+

−

Display d = new Display();

+

−

Shell shell = new Shell(d);

+

−

shell.setText(SimpleDirectedGraph.class.getSimpleName());

+

−

shell.setLayout(new FillLayout());

+

−

shell.setSize(100, 150);

+

−

new SimpleDirectedGraph(shell, SWT.NONE);

+

−

shell.open();

+

−

while (!shell.isDisposed()) {

+

−

while (!d.readAndDispatch()) { d.sleep(); }

+

−

}

+

−

}

+

−

}

+

−

</pre>

+

−

===Animation===

+

Cluster subgraphs can be labeled and can define their own layouts, e.g.:

In contrast to Graphviz, which only provides static graph visualization, Zest supports animations. By combining the Graphviz DOT language with Zest in a similar manner as described above, creating simple animations with Zest could become very easy.

+

[[Image:DotZestSubgraphs2.png|400px]]

−

For instance, defining an animation could be done by specifying the individual animation steps as subgraphs (with every subgraph defining how the current graph should be altered in the animation). Subgraphs render in individual boxes with Graphviz:

+

== Developer Documentation ==

−

<pre>

+

The goal of this feature is to implement the [http://www.graphviz.org/ Graphviz] [http://www.graphviz.org/doc/info/lang.html DOT language] as a domain-specific language (DSL) for [http://www.eclipse.org/gef/zest/ Zest: The Eclipse Visualization Toolkit], both as an input and output format. In other words, the goal is to transform both DOT graphs to Zest visualizations (to be used in Java SWT applications), and Zest visualizations to DOT graphs (to be rendered as image files with Graphviz).

−

digraph simple_animation {

+

−

subgraph cluster_0{ 1 -> 2 }

+

−

subgraph cluster_1{ 1 -> 3 }

+

−

}

+

−

</pre>

+

−

When converted to Zest, such an input could result in generated code as below (comments to be generated again omitted here). When executed, this application renders as on the first image on the right. After clicking the button it changes to the second image.

+

This feature started as a [http://socghop.appspot.com/student_project/show/google/gsoc2009/eclipse/t124022230869 project] in the [[Google Summer of Code 2009]] by [[User:Steeg.netcologne.de|Fabian Steeg]], mentored by Ian Bull, for [[GEF Zest Visualization|Zest]]. It is included in [[Zest#Zest_2.x|Zest 2]].

−

[[Image:DotZestAnimation1.png|right|200px]]

+

=== Resources ===

−

[[Image:DotZestAnimation2.png|right|200px]]

+

−

<pre>

+

[[Image:DotZestBundles.png|thumb|right|350px|Bundles and dependencies]]

Required imports for these examples (omitted above for better readability):

+

The main bug for this feature is {{bug|277380}}. View a [https://bugs.eclipse.org/bugs/buglist.cgi?query_format=specific&order=relevance+desc&bug_status=__all__&product=GEF&content=%5Bdot4zest%5D complete list] of related bugs. If you have suggestions for this feature you can [https://bugs.eclipse.org/bugs/enter_bug.cgi?bug_file_loc=http%3A%2F%2Fwiki.eclipse.org%2FGraphviz_DOT_as_a_DSL_for_Zest&bug_severity=enhancement&bug_status=NEW&comment=&component=Zest&contenttypeentry=&contenttypemethod=autodetect&contenttypeselection=text%2Fplain&data=&description=&flag_type-1=X&flag_type-2=X&flag_type-6=X&form_name=enter_bug&maketemplate=Remember%20values%20as%20bookmarkable%20template&op_sys=All&priority=P3&product=GEF&rep_platform=All&short_desc=%5Bdot4zest%5D%20New%20request%20summary&version=unspecified file a new bug]. The code for this feature is part of the Zest 2.0 Git repository. The dot4zest bundles are named ''org.eclipse.zest.dot.*''. See the general instructions for [[Zest#Setup|setting up Zest 2.0]].

−

<pre>

+

After changes to the Xtext grammar, run (Run As -&gt; MWE2 workflow) the ''GenerateDot.mwe2'' in the ''/src/org/eclipse/zest/internal/dot/parser'' folder of the core bundle. Make sure to set the project or workspace encoding to UTF-8.

−

import org.eclipse.draw2d.Animation;

+

−

import org.eclipse.swt.SWT;

+

−

import org.eclipse.swt.events.SelectionEvent;

+

−

import org.eclipse.swt.events.SelectionListener;

+

−

import org.eclipse.swt.layout.GridData;

+

−

import org.eclipse.swt.layout.GridLayout;

+

−

import org.eclipse.swt.widgets.Button;

+

−

import org.eclipse.swt.widgets.Composite;

+

−

import org.eclipse.swt.widgets.Display;

+

−

import org.eclipse.swt.widgets.Shell;

+

−

import org.eclipse.zest.core.widgets.Graph;

+

−

import org.eclipse.zest.core.widgets.GraphConnection;

+

−

import org.eclipse.zest.core.widgets.GraphNode;

+

−

import org.eclipse.zest.core.widgets.ZestStyles;

+

−

import org.eclipse.zest.layouts.LayoutStyles;

+

−

import org.eclipse.zest.layouts.algorithms.TreeLayoutAlgorithm;

+

−

</pre>

+

−

==Future Plans==

+

Run the ''All*.java'' test suites of the test bundle (''org.eclipse.zest.tests'') as JUnit or JUnit Pug-in tests to get an impression of the current implementation state. To use the UI components, run an Eclipse application configured with ''org.eclipse.zest.dot.ui'' and required plugins. See details on usage in the user documentation above.

−

Possible extensions of this project which are probably out of scope for the SOC period include:

+

===Motivation===

+

+

Graphviz is a very popular tool and its DOT language is widely used. Support for it could make using Zest very easy for many people who are familiar with DOT.

+

+

DOT integration for Zest could also be useful for existing Eclipse tools that are based on Graphviz, like [http://abstratt.com/textuml/ TextUML] or [http://eclipsegraphviz.wiki.sourceforge.net/ EclipseGraphviz], and others, for instance in the [http://tasktop.com/blog/eclipse/rich-editing-for-tasks-via-mylyn-wikitext Mylyn rich task editor] (for [http://fsteeg.wordpress.com/2010/02/07/diagrams-in-wiki-markup-with-mylyn-wikitext-dot-and-zest/ embedding DOT graphs in wiki text markup, visualized with Zest]).

+

+

On the output side, Zest can benefit from Graphviz output as it provides a way to produce high-quality export into different file formats, e.g. for printing Zest visualizations, or using them in digital publications.

+

+

===Implementation===

+

+

The dot4zest functionality is implemented based on [http://www.eclipse.org/modeling/ Eclipse Modeling] technologies, in particular [http://wiki.eclipse.org/Xtext Xtext] (part of [http://www.eclipse.org/modeling/tmf TMF]) for the input part (parse DOT, generate Zest) and [http://wiki.eclipse.org/M2T-JET JET] for the output (see details below).

+

+

[[Image:DotZestOverview.png|thumb|175px|right|Implementation of Graphviz DOT input and output for Zest using Eclipse modeling technology]]

+

+

====DOT to Zest====

+

+

Based on an Xtext grammar, dot4zest interprets the parsed DOT EMF model using the generated Xtext switch API to dynamically create Zest graphs. The Zest graph view uses this to display DOT with Zest (see above).

There are two reasons to use JET instead of Xpand here. First, this allows us to transform any Zest graph instance to DOT directly (not only those for which we have a DOT meta model instance that could act as the input to Xpand).

+

+

Second, even if we had a DOT meta model instance (which we could create from the Zest graph), using Xpand would introduce a runtime dependency on the [http://wiki.eclipse.org/Modeling_Workflow_Engine_(MWE) Modeling Workflow Engine], whereas with JET we only introduce a dependency on a single class (the generator class JET created from the template).

* Add animation support using something like ''subgraph cluster_animation_1 { label = "Step 1"; 1->2 }'' etc., where animation steps are represented as subgraphs in the DOT input (which if rendered with Graphviz results in a static description of the animation)

For instance, for the input below a Zest animation could be created that changes like this (this is an experimental illustation of the idea):

−

</pre>

+

+

digraph SampleAnimation {

+

/* We can specify a Zest layout for the animation here: */

+

layout=tree // = TreeLayoutAlgorithm

+

/* Global attributes can be defined for edges and nodes: */

+

node[label="Node"]

+

edge[label="Edge" style=dotted]

+

1;2;3;4;5

+

/* The single animation steps are marked by numbers: */

+

subgraph cluster_animation_0{ 1 -> 2 [label="Dashed" style=dashed]}

+

subgraph cluster_animation_1{ 1 -> 3 }

+

subgraph cluster_animation_2{ 3 -> 4; 3 -> 5}

+

}

+

+

After the first step:

+

+

[[Image:DotZestM5Screenshot1.png|200px]]

+

+

And the final state of the graph:

+

+

[[Image:DotZestM5Screenshot2.png|200px]]

+

+

The same input file, exported with Graphviz, shows the animation steps as subgraphs:

+

+

[[Image:DotZestAnimatedExport.png|200px]]

+

+

A possible use case for defining such animations with DOT is to easily create animated documentation, e.g. to explain data structures. The same file defining the animation could be used to export a PDF illustrating the steps in a static way.

[[Category:SOC]]

[[Category:SOC]]

[[Category:GEF]]

[[Category:GEF]]

Revision as of 15:29, 21 August 2013

Graphviz DOT as a DSL for Zest

Note to non-wiki readers: This documentation is generated from the Eclipse wiki - if you have corrections or additions it would be awesome if you added them in the original wiki page

This Eclipse feature provides support for the GraphvizDOT language in Zest: The Eclipse Visualization Toolkit, both as an input and output format. It provides API und UI elements to transform both DOT graphs to Zest visualizations (to be used in Java SWT applications), and Zest visualizations to DOT graphs (to be rendered as image files with Graphviz).

User Documentation

Installation

GUI

This feature adds a DOT editor and a Zest graph view to the UI:

Zest Graph View

The Zest Graph view can visualize DOT graphs in *.dot files or embedded in other files in the workspace. The view draws the DOT graphs using Zest and allows for image export of the current Zest graph. When automatic updating is enabled (see below), and a *.dot file or embedded DOT content is added to the workspace or altered in an editor, the Zest graph view is updated with the graph created from the DOT input. For instance, consider a file with the .dot extension, containing the following DOT graph definition:

The view contains buttons to toggle automatic updates, to load a specific file containing a DOT graph, and to layout the current graph. To export the current Zest graph as an image file by calling the dot executable, the view contains buttons to re-select the directory containing the dot executable, to enable export of the original DOT input, and to export as an image file (from left to right). When the image export button is selected, a PDF for the current graph is saved in the directory containing the file with the DOT input, and opened with the associated external editor, if one is available. In this example, the export looks like this:

This provides a Zest-based DOT authoring environment. If a *.dot file or embedded DOT is edited, it will be visualized in the Zest Graph view (e.g. during editing), and can be exported as a PDF with Graphviz.

At the same time the view provides a simple way to visualize *.dot file output of any kind of program, e.g. to visualize and debug internal data structures, results, etc: if a program running in Eclipse outputs any *.dot file in the workspace and the workspace is refreshed, the view will be updated with the corresponding Zest graph (if automatic updating is enabled, see above).

Editing

The Zest view can be used with the included DOT editor to visualize a DOT file:

API

Via the API, DOT can be imported to Zest graph instances, and Zest graph instances can be exported to DOT.

To use the API, create a new Plug-in project, add org.eclipse.gef4.zest.dot.core to the MANIFEST.MF dependencies, paste the code below into the source folder of the created project, and select Run As > Java Application:

Developer Documentation

The goal of this feature is to implement the GraphvizDOT language as a domain-specific language (DSL) for Zest: The Eclipse Visualization Toolkit, both as an input and output format. In other words, the goal is to transform both DOT graphs to Zest visualizations (to be used in Java SWT applications), and Zest visualizations to DOT graphs (to be rendered as image files with Graphviz).

Resources

Bundles and dependencies

The main bug for this feature is bug 277380. View a complete list of related bugs. If you have suggestions for this feature you can file a new bug. The code for this feature is part of the Zest 2.0 Git repository. The dot4zest bundles are named org.eclipse.zest.dot.*. See the general instructions for setting up Zest 2.0.

After changes to the Xtext grammar, run (Run As -> MWE2 workflow) the GenerateDot.mwe2 in the /src/org/eclipse/zest/internal/dot/parser folder of the core bundle. Make sure to set the project or workspace encoding to UTF-8.

Run the All*.java test suites of the test bundle (org.eclipse.zest.tests) as JUnit or JUnit Pug-in tests to get an impression of the current implementation state. To use the UI components, run an Eclipse application configured with org.eclipse.zest.dot.ui and required plugins. See details on usage in the user documentation above.

Motivation

Graphviz is a very popular tool and its DOT language is widely used. Support for it could make using Zest very easy for many people who are familiar with DOT.

On the output side, Zest can benefit from Graphviz output as it provides a way to produce high-quality export into different file formats, e.g. for printing Zest visualizations, or using them in digital publications.

Implementation

The dot4zest functionality is implemented based on Eclipse Modeling technologies, in particular Xtext (part of TMF) for the input part (parse DOT, generate Zest) and JET for the output (see details below).

Implementation of Graphviz DOT input and output for Zest using Eclipse modeling technology

DOT to Zest

Based on an Xtext grammar, dot4zest interprets the parsed DOT EMF model using the generated Xtext switch API to dynamically create Zest graphs. The Zest graph view uses this to display DOT with Zest (see above).

Zest to DOT

There are two reasons to use JET instead of Xpand here. First, this allows us to transform any Zest graph instance to DOT directly (not only those for which we have a DOT meta model instance that could act as the input to Xpand).

Second, even if we had a DOT meta model instance (which we could create from the Zest graph), using Xpand would introduce a runtime dependency on the Modeling Workflow Engine, whereas with JET we only introduce a dependency on a single class (the generator class JET created from the template).

Future Ideas

Add support for different Graphviz shapes through Zest custom figures, e.g. for UML class diagrams

Add support to visualize Graphviz subgraphs as separate Zest graphs that can be accessed from the main graph

Add animation support using something like subgraph cluster_animation_1 { label = "Step 1"; 1->2 } etc., where animation steps are represented as subgraphs in the DOT input (which if rendered with Graphviz results in a static description of the animation)

For instance, for the input below a Zest animation could be created that changes like this (this is an experimental illustation of the idea):

The same input file, exported with Graphviz, shows the animation steps as subgraphs:

A possible use case for defining such animations with DOT is to easily create animated documentation, e.g. to explain data structures. The same file defining the animation could be used to export a PDF illustrating the steps in a static way.