Drawing complex hierarchical information manually is both cumbersome and time consuming. This task should not be done manually, but with a suitable piece of software. TreeJuggler is such a tool. It can layout hierarchical information compactly and optimize the drawing for any aspect ratio you need. Here is how to use it…

Getting Started

To get started with Gravisto and TreeJuggler, visit Gravisto on Github. Please note that the former homepage of Gravisto is no longer available (see New Home for Gravisto for more information). After checking out the Java source code using the provided gravisto.psf, you will have a launch configuration for 64 and 32 bit available in your Eclipse IDE.

The TreeJuggler Toolbox

How Gravisto does what it does is answered in some detail in Juggling with Trees – How to Layout Hierarchical Information Compactly. In short: TreeJuggler is a tool to draw trees compactly. It is a plugin for Gravisto and can be used from a graphical user interface as well as from the command line. TreeJuggler is a toolbox of several algorithms which work together to produce a nice compact drawing. In the graphical user interface this toolbox is represented by the toolbar depicted in Figure 1.

Fig. 1: The TreeJuggler toolbox in Gravisto

Here is a short description of the algorithms. Going through the icons of Fig. 1 from left to right:

• DAG Splitter: This turns a directed acyclic graph (or DAG) into a tree by duplicating the nodes that have more than one incoming edge.
• Root Changer: Changes the root of a tree by reversing the direction of the edges accordingly.
• Tree K-nary Maker: Often there are problems with laying out trees compactly because some nodes have too many children. This algorithm introduces helper nodes to reduce the degree of the tree to some user given k.
• Helper Node Stripper: After your drawing is finished you obviously want to get rid of all the helper nodes that are cluttering up the drawing.
• Tip-over layout: A layout algorithm for trees in which all the child nodes are put next to each other or on top of each other. Figure 1 of Juggling with Trees – How to Layout Hierarchical Information Compactly shows a good example of a tip-over drawing.
• HV-layout: A layout algorithm for binary trees in which one child node is put on the right and the other one below its parent node. A quick introduction can be found here.
• Layout Refresher: The layout attributes of the drawing can be edited manually. For example, in a tip-over drawing, subtrees can be re-ordered or the alignment of the child nodes of a particular node can be changed from horizontal to vertical. After clicking “Refresh” the drawing is changed accordingly.

The Command Line Interface

The TreeJuggler Command Line Interface (or TreeJugglerCLI for short) uses the heuristic outlined in Loosen Up With TreeJuggler of Juggling with Trees – How to Layout Hierarchical Information Compactly to produce good drawings automatically. Here is an example program call:

TreeJugglerCLI -i tutorial.dot -o tutorial.pdf -d 50 -f -c

The following command line options are available (the ones marked with an asterisk are mandatory):
-i: Determines the .dot or .graphml input file (*).
-o: Specifies the .graphml, .pdf or .png output file (*).
-d: To specify the node distance option (*).
-r: The ratio of width to height the drawing is to be optimized for (* or -f as an alternative). A video that illustrates the effect of this parameter can be found in the article Getting Hierarchical Information into Shape.
-f: Specifies the paper format to be used or leave empty for auto mode.
-c: Coloring Mode. Subtrees that are duplicated by the DAG Splitter are colored. If the parameter is not given, no coloring will be done.
-a: Indicate the direction of the edges with arrows.
-h: Do not substitute HelperNodes by bends.

The above example will produce the following drawing (as a PDF):

Fig. 2: Result of the TreeJugglerCLI command above

Conclusion

I hope you now have some basic idea of how to use TreeJuggler. This tutorial is work in progress. Tell me what you think. What else should be included?