head	1.3;
access;
symbols;
locks; strict;
comment	@# @;


1.3
date	99.10.07.01.03.24;	author munzner;	state Exp;
branches;
next	1.2;

1.2
date	99.10.07.00.05.30;	author munzner;	state Exp;
branches;
next	1.1;

1.1
date	99.09.16.07.59.26;	author munzner;	state Exp;
branches;
next	;


desc
@@


1.3
log
@namespacehack update
@
text
@HypViewer version 1.0
Wed Oct  6 18:01:10 1999

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-723-3154

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. 

More info:

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

Dependencies:

Needs OpenGL, C++, STL. Note that the Mesa libraries on Linux should
work for the OpenGL requirement.

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.

 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

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
# 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

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.

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 (Linux, whatever) then
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. 

----------

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. 
@


1.2
log
@first release try
@
text
@d2 1
a2 1
Tue Oct  5 01:00:25 1999
d12 5
d29 1
a29 1
 Windows Borland port
d86 6
a91 1
PORTING
d111 5
d123 16
a138 4
I doubt 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.
@


1.1
log
@Initial revision
@
text
@d1 2
a2 1
Sun Feb 21 02:06:17 1999
d4 7
a10 41
This code has been modified by Daniel W. McRobb at CAIDA
(dwm@@caida.org).  The Ok* classes are gone, replaced by STL and standard
C++ classes (array types replaced by STL <vector>, OkStr replaced by
<string>).  This eliminated the troublesome large macros, and made thing
much easier to port to a GNU environment.  Currently the glut interface
works on Solaris 2.7.  The rest will be fixed and tested soon, except
ViewKit (since I don't have ViewKit anywhere).  Near-term porting target
are FreeBSD 3.0 and Linux using X/OGL from Xi Graphics (see
http://www.xig.com/) and Linux using Mesa/GLIDE.  In all likelihood,
plain old Mesa (no hardware accelerated 3D) will work on speedy machines
too since the drawing rate isn't tremendous (hypviewer is mostly optimized
for interaction and does minimal drawing during user interaction).

Mon Oct 19 15:26:17 1998

This version of the H3/H3Viewer source has been tested to compile and
run on SGIs. The main library code should work across multiple
platforms. Device dependencies are segregated by #ifdef barriers.
Currently, the flavors that work are GLUT (Mark Kilgard's window
system independent toolkit) and ViewKit. I've started making an
Xt-only version, which should be quite similar to the Vk version, but
that's not ready yet. Both the Vk and the Xt versions use the GLX
defines.

The example application code has more device dependencies. Both the Vk 
and Xt versions are in the vk directory. The glut version is in its
own directory. There's also a simplevk app that's more barebones than
the vk version. 

Since I haven't tried compiling and running on anything but an SGI
yet, I'm sure there are a lot of unfound device dependencies. I got
most of the way through fixing the warnings/errors from using g++
instead of SGI's CC, but that's not quite finished either.

The GLUT version *should* work on Windows, just download the libraries
from http://reality.sgi.com/opengl/glut3/glut3.html. I haven't yet
tried compiling the code using VisualC++. 

The doc/ctools directory has SGI binaries from the nice documentation
tool cocoon. Grab the version for your platform at
http://www-users.cs.umn.edu/~kotula/cocoon/cocoon.htm
d13 1
d19 8
d43 2
a44 2
Needs OpenGL and C++. Note that the Mesa libraries on Linux should
work for the OpenGL requirement. 
d49 70
a118 1
Planned changes:
d120 1
a120 5
One of the most confusing things about the current API is that you
have to explicitly enable groups, or else they're not drawn. It would
be more intuitive to have them drawn by default, and make the
application programmer explicitly turn them off. I might get to that
change one of these days soon.
@
