Note passing off the first freeze to Jason for integration.

---------- Forwarded message ----------
Date: Fri, 5 Apr 2002 21:35:02 -0500 (EST)
From: cdent@burningchrome.com
Subject: frozen code


I've put my latest versions of the Spring layout code on ella at: 

  /home/cjdent/src/Spring

I'll leave it alone until we meet on Sunday.

I'm sorry this message is so long, but it is the current state of
affairs, please take the time to read it before you try and integrate
our various stuff: there's relevant stuff here, especially the
discussion of the problems with the math and the two hierarchy methods.
I've thus far been somewhat frustrated in the process because there
hasn't been a lot of chatting about what I've done and I need feedback
to keep it in line. The code is not as well commented as I would like,
so this is important commentary. 

As stated before my code doesn't deal with:

- input of node and edges info (all the testing has been done with
  hardcoded stuff in DrawableSpring.java. In addNodes() and
  addEdges().
- prettiness of nodes and edges. DrawableNode and DrawableEdge are
  extensions of Node and Edge and can be extended to include things
  like shape, color, label, etc
- Events or external controls of any kind.

I got stuck in (and enjoyed being in) the decoding of how best to do
the layout itself. I've made some fairly significant progress with
this, but there remain some issues:

- Constants and formulae used for the following need to be tweaked,
  I'm not getting perfect results:

  - calculation of inter-node repulsion, based on the repulsion value
    on the Nodes (Node.java) and the math in pushNodes() in
    SpringProcessor.java
  - calculation of spring/edge pull, based on the strength value on
    the Edges (Edge.java) and the math in pullEdges() in
    SpringProcessor.java
  - the pull of gravity, in gravity() in SpringProcessor.java
  - type of gravity, also in gravity(). The choice is between a
    gravity that sucks to the middle of the screen in a straight line,
    a more "real" gravity which causes orbiting, and a gravity which
    seeks the barycenter of all the nodes (instead of the screen).
  - manipulation of temperature in updateNodes() in
    SpringProcessor.java where it attempts to grow and shrink the
    window of motion for an individual node based on a decision
    about whether the motion is helping
  - decisions of when the graph is done, based on the global
    temperature of the scene, runP() and updateNodes() in
    SpringProcessor.java

  All these things together have -huge- impact on the appearance of
  the layout and thus are crucial to the value of the tool so I would
  very much like to focus on this area. Once we have a good system 
  for inputing graphs, and adjusting the constants (sliders and such)
  it will be easier to find good defaults.

- Window events are not being dealt with. When the updates on the
  DrawableSpring Panel stop (the thread quits) the screen doesn't
  get refreshed if it is occluded by another window or minimized then
  revealed.

  There's SpringDisplay and SpringApplet, one's a Frame, one's an Applet

- Related to the above: if a window is resized, that's not picked up.

- It's not clear that the decisions I've made for threading are right.
  Seems to work pretty well but I didn't use anything other than
  guesswork to get there.

- My Node model, and Node hierarchy model, is fairly complex and I
  think quite flexible but that's not really demonstrated in the
  demonstrations contained in addNodes() and addEdges() in
  DrawableSpring.java so here's more info:

  When a layout is created (a new SpringProcessor is started) it is
  provided with an EdgeList and a NodeList. These are generally a
  subset of all the Nodes and Edges currently known in memory. The
  subset can represent any selection of nodes and edges that the code
  desires. It is for the current display only. This makes it
  possible to input one global Node and Edge dataset, select N>1
  subsets of those and display N DrawableSpring panels. This allows
  for the display of context while viewing hierarchy that Jason and I
  have discussed: The primary panel has the current view while a
  secondary (scaled) panel has the previous collection of Nodes and
  Edges.

  When Nodes are entered they can be entered in a hierarchy. The Node
  object has an addChild() method that allows nodes to be added to it
  as children. This means, for example, that if you have five
  clusters, each of those clusters can be a Node and the members of
  each cluster are children of the node.

  Nodes also have a level. This is their "height" in the hierarchy. As
  you traverse the input, you enter current level. So in the cluster
  example above, a pseudo Node would represent the top (level 0),
  the five clusters would be level 1, and the children of each
  cluster would be level 2.

  The combination of level and children mean there can be three ways to
  traverse the hierarchy:

  - A cluster can be clicked. When it is clicked, code traverses that
    Node's list of children, and adds them to a newly created
    NodeList. An EdgeList is created that matches those nodes. The
    EdgeList and NodeList are used to create a new layout.
  - A slider can be adjusted, or a textfield used, to select a level
    in the hierarchy. A new NodeList can then be generated from those
    nodes that match the selected level. The EdgeList is generated
    from that NodeList. NodeList and EdgeList are used to create a new
    layout that may replace the previous one.
  - The union of these two methods. That is, dive into a single cluster,
    and then slide down the entire hierarchy below.

  Generating these lists may sound expensive, but it's cheap compared
  to the manipulations going into drawing. 

The code that is currently in place (at the path above and as an
applet at project4/test/">http://ella.slis.indiana.edu/~cjdent/project4/test/ ) is
displaying a similarity matrix used in my project 3. It is the
"Similarity Between Threads" matrix at the top of:

  http://ella.slis.indiana.edu/~cjdent/project3/figures.html
  
The results are quite different between the two systems. I've set
edges that have a strength of less than .93 off in the new code.
Perhaps I don't understand the way the slider to adjust edges was
working in the old code, but the difference in the results is _quite_
confusing and interesting. 

Jason: I'm looking forward to whatever we discover on Sunday. Just to
confirm that's 1pm outside of Franklin Hall, correct?

Both of you: please let me know of any comments you might have.

Thanks.