readme

生物物种进化历程的演示

TreeJuxtaposer Readme
February 8, 2005
Version 1.3

Contributors and Authors

Current Contributors, 2003-2004:
----------
Tamara Munzner			www.cs.ubc.ca/~tmm
Kristian Hildebrand		www.uni-weimar.de/~hildebr2
James Slack				www.cs.ubc.ca/~jslack

Original Version, 2001-2003:
----------
Tamara Munzner			www.cs.ubc.ca/~tmm
Francois Guimbretiere	www.cs.umd.edu/~francois
Serdar Tasiran			network.ku.edu.tr/~stasiran
Li Zhang				www.hpl.hp.com/personal/Li_Zhang
Yunhong Zhou			www.yunhongzhou.com

Previous Contributors:
----------
Zhihui Jeffrey Zhang	[e-mail] (2003)

http://olduvai.sourceforge.net/tj


1	What is TreeJuxtaposer?
2	Running TreeJuxtaposer
3	Mouse Interaction
4	Searching
5	Groups
6	Settings Panel
7	Keyboard shortcuts for users
8	Developer commands
9	Fonts
10	Compilation after checking out from CVS
11	Version Information
11.1	v1.0
11.2	v1.1
11.3    v1.2
11.4	v1.3


1	What is TreeJuxtaposer?
TreeJuxtaposer is an application for browsing trees and comparing
  them side by side. Although it was originally designed to support
  phylogenetic trees, it can be used on trees in any application domain.

Our AccordionDrawer technique for multiscale drawing allows fluid
  interaction even for very large trees, with guarantees on frame rate
  and the visibility of marked sections. The zoomable interface lets you
  stretch out parts of the tree you want to see in detail and the rest
  of the tree will be squished to make room. You can have more than
  one focus area at a time.


2	Running TreeJuxtaposer

Use any one of the following three options to get TreeJuxtaposer running:

  1. click on the tj.jar icon

  2. from the command line type "java -jar tj.jar [<file1> ... <fileN>]"

  3. from the command line, if you compiled TJ yourself: 
	"java TreeJuxtaposer.TreeJuxtaposer [<file1> ... <fileN>]"

Loading two or more trees allows side-by-side comparison. You can also
  load only a single tree to use TJ as a browsing viewer. You can load
  files either by specifying them as command line arguments or using the
  "File->Open" menu option with the running program.  Trees can later be
  unloaded with the "File->Delete" menu option.

The accepted file formats are Newick/New Hampshire (nodes delimited by
  parentheses and commas, the format of a Nexus tree block), or Nexus. 
  Interior node labels are allowed. Edge lengths are ignored in the
  current version.

You must put "-x " in front of the filename for each Nexus file on the
  command line, and can optionally include integers after the filename
  specifying which trees from the file to load. You will be asked which
  trees in the Nexus file that you want to use if you don't specify
  numbers on the command line.


3	Mouse Interaction

Moving the mouse over an edge highlights the node under the cursor in
  orange, and also the "best corresponding node" (BCN) to that node in all
  other trees. You will also see a light grey outline around the entire
  subtree beneath the mouseover node.

If you hold down the shift key, the box around the subtree gets
  thicker and you can resize it - when you start to drag the mouse,
  whatever corner is closest to the mousedown point will move.  The rest
  of the scene will change shape accordingly, and other windows will
  also resize in linked navigation mode (on by default).

You can also change shape by directly drawing a rectangle on the
  screen, and moving its boundaries in the same way. Drag out a
  rectangle, then drag one of the corners to make it larger or smaller. 


4	Searching

Selecting the Find menu item opens the Find window. By default, the
  entire list of labels appears in the top window. When you type in the
  box on the bottom, that list will be filtered to contain only the
  items that contain that substring. If the number of matching items is
  less than 200, then they will be highlighted with guaranteed
  visibility (default color is magenta). 


5	Groups

You can use the Groups panel to resize groups or create new ones using
  the mouse. There are eight groups. Four of them are computed by the
  system: mouseover (the object currently under the mouse, default color
  orange), differences (computed structural differences, default color
  red), found (search results, default color magenta), and LCA (least
  common ancestor of all items in group, default color dark green). Four
  of them are selected by the user, with default colors of blue, green,
  cyan, and purple. You put an item in the current mark group by hitting
  'm' when the mouse is over the item. To add items to the current mark
  group instead of replacing them, hit 'M' (shift-m). You can control
  with Mark Resolution radio buttons whether you mark just the node
  under the mouse, or the entire subtree beneath it (the default). You
  can change which group is the current mark group using the radio
  buttons on the bottom part of the panel.

The Bigger and Smaller buttons operate on all items of any group,
  resizing the whole forest of subtrees if the group contains more than
  one contiguous subtree. By default they only affect the vertical
  extent, but you can switch to just horizontal or both using the radio
  buttons. The reset button returns the view to the default overview
  position.

You can change the color of a group by hitting the colored square
  button. You can also clear just the currently active group (the one
  whose radio button is on) with the "Clear group" button, or all marks
  with the "Clear all" button. The found group is special: you can only
  clear it by erasing the text from the box at the bottom of the found
  panel.

If you turn on the "LCA" checkbox, then the path up to the least
  common ancestor of all the items in the group will be highlighted as
  items are added to the group.


6	Settings Panel

The Line Width slider controls the width of the tree edges, the
  default is one pixel wide. The Label Density slider controls how
  densely the labels are drawn on the screen, the default is
  near-maximum. 

You can set the minimum and maximum font size. You can toggle on and
  off the computed structural differences, the labels, and linked
  navigation between all the tree windows. 

You can control whether either the marks or the grey edges are
  automatically dimmed: saturation is controlled by the size of the
  screen area subtended by the subtree, and brightness is controlled by
  the depth in the tree. By default this feature is turned off for
  marks. 

You can also control the angle at which labels are drawn (only applies
  if you've picked a vertical rather than the default horizontal window
  orientation). 

The BCN score controls the level at which differences are marked. By
  default they're all marked, moving the slider to the right raises the
  threshold of difference. 


7	Keyboard shortcuts for users
 
r reset grid 
u show structural differences 
w draw labels 
e exit resize modes
k toggle whether trees move together with linked navigation
  default=on

mark what's under mouse, in active group color 
     m : mark subtree (default case) 
 [t] m : mark taxon 
 [n] m : mark taxon as above, but mnemonic is 'node' instead of
 'taxon'
 
  if you hold down shift key (M), add to active group instead of
  replace
 
change active group (i.e. switch to new mark color) 
        g : DEFAULT: change active mark group to next one (i.e. g++) 
 [0123] g : change active mark group to the one specified 
 
clear marks 
        c : DEFAULT: clear active group 
 [0123] c : clear specific group 
 [a]    c : clear all groups  (except the found group)
 
change size of group 
 [hva] b : make it bigger, in either horizontal or vertical or all
           directions  
 [hva] s : make it smaller, in either horizontal or vertical or all 
           directions. Default: vertical. 

  (if the group is a forest, only one of the subtrees will be
  highlighted with a box, but all will resize with b or s. when you
  drag with the mouse, only the boxed subtree will change size.

to leave keyboard resizing mode: 'e'


8	Developer commands

There are some developer/debugging commands that you can to
  with a two-key sequence, by first hitting '.', then the one of the
  keys below:
 
A show algorithm in action 
c toggle coloring grid
N redraw 
T toggle drawing tree 
H toggle mouseover flash
k change leaf length: short/medium/long 
R label position to the right 
w linethickness++ 
W linethickness-- 
m labelbuffer++ 
M labelbuffer-- 
e minFont-- 
E minFont++ 
x maxFont-- 
X maxFont++ 
p toggle label popup at cursor mode 
C toggle dimmarks
D toggle dimedges
j toggle jump (instead of animated transition) 
F generate performance stats 


9	Fonts

If you have the source code, you can create a new font file with the command:

java BitmapFont/BitmapFontsFamily Dialog 6 48 1 

which will generate the file Dialog.font in the current directory, and
	copy it to the file "OlduvaiFont". The following default fonts should
	exist on any machine with java:

Dialog, Arial == Sans-Serif, DialogInput == Monospaced 
 

10	Compilation after checking out from CVS

From the command line:

cd olduvai; 
javac {AccordionDrawer,AccordionTreeDrawer,Parser,BitmapFont,TreeJuxtaposer}/*.java

Using the build.xml file:

ant <targetname>

You'll get a list of all possible targets if you don't provide one


11	Version Information

11.1	v1.0
 - released January 11, 2004
 - original code, uses quadtrees
 - limited to approximately 500,000 total tree nodes in 1.5G heap memory
 - published (SIGGRAPH 2003, Munzner, et al.)
 
11.2	v1.1
 - released June 25, 2004
 - updated documentation
 - splitLine code for drawing, resizing, picking, culling
 - limited to approximately 2 million total tree nodes in 1.5G heap memory
 - flexible structure for use in future accordion drawing packages
 
11.3    v1.2
 - released October 19, 2004
 - bug fix release:
   - tree marking fixes (1-to-many marking now works)
   - nexus file loading/unloading fixes
   
11.4	v1.3
 - released February 8, 2005
 - line width tied to leaf traversal (thicker lines, more line overlap)
 - limited to approximately 3 million total tree nodes in 1.5G heap memory
 - peak scene rendering time of approximately 600ms:
   - Pentium4 3Ghz, 800x600, 3 million tree nodes, line width 1