HypViewer version 1.1.2 TMM Thu May 9 17:44:27 2002 The HypViewer library provides layout and interactive navigation of node-link graphs in 3D hyperbolic space. The library can handle quite large graphs of up to 100,000 edges quickly and with minimal visual clutter. The hyperbolic view allows the user to see a great deal of the context around the current focus node. The guaranteed frame rate algorithm is provides fast reponse time on both large data sets with high-end machines and medium-sized data sets on low-end machines. The example viewers are all very bare-bones standalone applications which are really just to give some hints about how to use the library. I definitely recommend integrating this component with other more traditional UI components for the most effective user experience. Author: Tamara Munzner munzner@cs.stanford.edu http://graphics.stanford.edu/~munzner 650-853-2253 Contributors: Daniel W. McRobb, CAIDA, dwm@caida.org FreeBSD port, STL conversion, memory footprint reduction, etc. Matt Gressek, Agenetics, matt@agenetics.com most of Windows port ---------- Rights: See the full COPYRIGHT file. In short, you can use this for free if you don't redistribute it for a fee. Contact SGI if you want to license it for commercial redistribution. This code was originally written at SGI and Stanford. ---------- More info: The main URL for H3 is http://graphics.stanford.edu/~munzner/h3 API documentation is on the web at http://graphics.stanford.edu/~munzner/h3/HypViewer.html Papers with details on the algorithms are on the web at http://graphics.stanford.edu/~munzner/papers.html See the CHANGES file in this distribution for the changes between versions. ---------- Dependencies: Needs OpenGL, C++, STL. Note that the Mesa libraries on Linux will work for the OpenGL requirement, and are default-installed under RedHat. All device-dependent code is supposed to be segregated by ifdef statements, but caveat emptor. ---------- SOURCE CONTENTS src/ library source files include/ library include files data/ sample data files examples/ vksimple/ very simple ViewKit app, calls library xtsimple/ very simple Xt app, calls library vkxt/ more complex Xt or ViewKit app, keystroke callbacks show off more library functionality. see viewer.README for usage details. (Note: if you're wondering why you can't see the cycles in your graph, try hitting the 'u' button!) xtnofile/ Xt app showing the use of the addNode/addLink commands instead of reading data from an input file mfc/ Windows example app, includes source file directly instead of using libraries properly. someone who knows Windows better could fix this up much more cleanly, I'm sure. doc/ include/HypView.h and include/XHypViewer.h have internal comments which are automatically turned the HTML documents in here by cocoon, see http://www.stratasys.com/software/cocoon/ Makefile.* makefiles (ignore for Windows version) ---------- PORTING/COMPILING You will definitely need to change the ROOTDIR line in Makefile.main to set the correct pathname where you unpacked the files. If you're not compiling for Linux, then you'll also need to pick the right Makefile. line. The file Makefile.main is a shell that calls an OS/window system specific Makefile with all the real settings. You'll almost certainly have to adapt that specific Makefile. for your environment by changing various paths and so on. I'm afraid the ifdef conventions aren't very consistent. Sometime it's #ifdef FOO, other times it's #ifndef BAR. I'm sure if people start porting this to other platforms there will be a need to clean up the logic a bit. # to construct a Makefile for a new platform: # possible defs: # HYPXT - Xt (on top of X/Motif) window system # HYPVK - ViewKit window system. mainly found on SGI, but is crossplatform # HYPGLX is a superset of HYPVK and HYPXT # HYPGLUT - Mark Kilgard's window system # HYPIRIX - it's an SGI # HYPLINUX - it's a Linux box # WIN32 - it's a Windoze box # HYPFREE - it's a FreeBSD box # XPMSNAP - can be enabled for any of the X Windows ones # # The window system is supposed to be vaguely orthogonal to the CPU, # although you can't mix and match every combination. # # Define NAMESPACEHACK to either 'using namespace std;' or '': # in some compilers (including SGI CC and Microsoft Visual C++ the # former is critical for compiling STL, in others (older version of # g++?) apparently the right thing to do is leave it blank. The following Makefiles are provided in this distribution: irixxt: HYPXT HYPGLX HYPIRIX irixvk: HYPVK HYPGLX HYPIRIX irixglut: HYPGLUT HYPIRIX freext: HYPXT HYPGLX HYPFREE linuxxt: HYPXT HYPGLX HYPLINUX The irixxt is the most tested configuration. The irixglut one has also been tested. The irixvk one used to work but I don't have the ViewKit development environment installed on my machine anymore after my upgrade to Irix 6.5 so it hasn't been recently tested. The ViewKit version is somewhat deprecated anyway compared to the Xt one. The freext Makefile is just a prelim attempt which is completely untested, just wanted to give people the idea of what I had in mind. The linuxxt Makefile has been tested, albeit not extensively. I'm not positive that the Visual C++ project files will work on another Windows box without tweaking since they seem to encode hardwired path names in their files, but the relevant ifdef is of course WIN32. GLUT under Windows is untested but theoretically possible. If you port this software to another system please consider contributing the changes (especially the Makefiles) back to me for inclusion in the next release. I hope it should be pretty straightforward to get another Unix flavor working. Linux Compilation Notes: 1. If you see the following error message: /tmp/hypviewer/src/VkHypViewer.cpp:95: undefined reference to `glwMDrawingAreaWidgetClass' the solution is to download http://prdownloads.sourceforge.net/mesa3d/libGLw.tar.gz and unpack into /usr/lib. It doesn't seem to be included in the standard Mesa developer distribution. ---------- Possible future changes: The H3Viewer library supports a guaranteed frame rate, with one glaring exception. The mapping from hyperbolic to euclidean space is global, not incremental, so occasionally with big data sets everything will just freeze up for a few seconds while the remapping is computed. See papers for more details. I have some ideas on how to fix this.