Graph VR Juggler JCONF files using GraphViz
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
xdot
LICENSE_1_0.txt
README.mkd
find_jconf.py
jconf-viz-screenshot.png
jconf-viz.py
jconf2dot.py
jconf2pdf
test-on-bundled-jconfs.sh

README.mkd

jconf graphing tools

Homepage: https://github.com/rpavlik/jconf-grapher/

At its core, this is a program to parse VR Juggler jconf configuration files and output Graphviz "dot" language input, which can be parsed by the Graphviz tools to create a human-usable map of the components and relationships in the configuration files. VR Juggler configurations have several layers of abstraction and indirection (devices, device proxies, proxy aliases) and this tool can help make the relationships clearer.

A GUI for exploring the rendered output is included.

jconf-viz screenshot

Requires

  • Python 2.x, at least 2.5 Python 2.5 (uses xml.etree.ElementTree to parse the XML-based jconf files)

  • Graphviz (dot) tools to convert the output into an image - not technically required but for any reasonable usage you want this.

    • Ubuntu/Debian: sudo apt-get install graphviz

    • Windows: You can use the installer from http://www.graphviz.org. You may need to reboot so that graphviz is in your PATH. To test, click Start, Run, and enter dot. If you see an error, it's not in the path. If it opens a black window and just sits there, then you're good to go. (Just close the window manually.)

    • Mac with homebrew: brew install graphviz

  • Additional dependencies for the minimal jconf2pdf wrapper script:

    • Bash shell - you probably already have this on any *nix system.
  • Additional dependencies for the GUI viewer jconf-viz:

    • GTK+ and PyGTK 2.10 or greater

      • Windows: Depending on the version of Python you installed, choose and install the matching "all-in-one" installer from http://www.pygtk.org/downloads.html. The default install options are correct.

      • Ubuntu/Debian: sudo apt-get install python-gtk2

      • Mac with homebrew: download pycairo.rb, pygobject.rb and pygtk.rb to /usr/local/Library/Formula. Then brew install pygtk.

Details

jconf-viz.py is a GUI application for exploring a visualization of a jconf file. You can pass a file at the command line, or open one in the GUI. Click a node to make it the center, left-drag in a blank area or middle (wheel) drag anywhere to move, use the scroll wheel to zoom. It will auto-reload to reflect file changes at most once a second.

(Mac users: you need to use X11 to execute the application to do so, right click on jconf-viz.py>"Open With">"Other...". Make sure "All Applications" is selected in the "Enable:" dropdown menu, choose /Applications/Utilities/X11, check the "Always open with box" and click on Open.)

jconf2dot.py takes as parameters one or more jconf files. It prints Graphviz ("dot") format descriptions of the relationships in the jconf files to standard output, which you can redirect to file or pipe right to the dot executable.

jconf2pdf is a simple shell script wrapper for jconf2dot. It passes along its arguments to jconf2dot, pipes the output to dot, and saves a PDF to the name of the first input file with ".pdf" appended. It's very minimal: if you want different output, just look at it as a guide - the "works" is really just a one-line pipeline.

Output Diagram Key

  • Grey filled ovals: proxy aliases
  • Outlined ovals: device proxies
  • 3D Boxes: other elements, assumed to be decives
  • "Egg" shapes: Users
  • Dotted-bordered boxes: Elements defined in a particular file. Nesting of boxes shows inclusion.

Author and License

Ryan Pavlik, rpavlik@iastate.edu abiryan@ryand.net http://academic.cleardefinition.com

This is free and open-source software. Enhancements are gladly welcomed.

jconf2dot.py, jconf2pdf, and find_jconf.py are all written by me, and available subject to the following copyright and license:

Copyright Iowa State University 2011

Distributed under the Boost Software License, Version 1.0.

(See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

The visualizer uses XDot, by Jose Fonseca, downloaded 18 May 2011 from http://xdot.jrfonseca.googlecode.com/hg/xdot.py. The jconf-viz.py application is based on code from XDot, so both XDot and the visualizer app are subject to the following copyright and license (the LGPL text is in the subdirectory xdot):

Copyright 2008 Jose Fonseca

Copyright 2011 Iowa State University

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this program. If not, see http://www.gnu.org/licenses/.