ATV - A Tree Viewer
Version 1.9 (October 2001)
Copyright (C) 1999-2001 Washington University School of Medicine
and Howard Hughes Medical Institute
All rights reserved
----------------------------------------------------------------


Since ATV is part of the FORESTER framework it must be used in
conjunction with FORESTER. 


Please note: If used as an application (as opposed to an Applet),
it is highly recommended to use the "Java 1.2 version" (i.e. "ATVapp"
instead of "ATVapp_awt") since the "AWT version" is not being
actively supported anymore and lacks important capabilities
(such as printing and SDI).


The ".tar.Z" file is for Unix and Linux users.
The ".zip" file is for Microsoft Windows users.


Please email me at: zmasek@genetics.wustl.edu
for reporting bugs, comments, suggestions, complaints, ...



1. Obtaining FORESTER including ATV
-----------------------------------

ftp://ftp.genetics.wustl.edu/pub/eddy/software/

http://www.genetics.wustl.edu/eddy/atv/




2. Unpacking FORESTER including ATV
-----------------------------------

Unix, Linux:

  "uncompress forester.tar.Z"

  followed by:
    
  "tar -xvf forester.tar"



Microsoft Windows:

  Use a program such as WinZip to unzip "forester.zip".


In both cases, a new directory named "forester-1.x" will 
be created in your working directory. This directory contains 
all the unpacked files. 



3. Running ATV
--------------

3.1. Running the ATV application
--------------------------------

ATVapp requires Java 1.2 or greater.

ATVapp_awt requires Java 1.1.x or greater -- this version of ATV
is not supported anymore.

There are two ways to run the application -- either by compiling the
source code, or directly from the jar file ("ATVapp.jar" or "ATVapp_awt.jar",
dependent on the version of your JDK).



  - Compiling the source code:
    --------------------------

      Unix/Linux users please note: If "weird" errors occur
      (such as "class not found") you might want to inspect your
      CLASSPATH with "echo $CLASSPATH". Please make sure it
      contains a path to the current directory (".", "./") or a path
      to FORESTER (see below). Alternatively, you could use
      the "-classpath" option.


      o  for JDK 1.2 or greater:
         -----------------------

         compile with:
 
         "javac ATVapp.java"
        
         in the same directory as ATVapp.java
         (MS Windows users need to open a MS DOS prompt)
	

         then, to run ATVapp:

         "java ATVapp [name of tree file in NH or NHX format]"

         e.g. "java ATVapp testtree.nhx" -- to display to tree
              which is part of this distribution	



      o  for JDK 1.1.x or greater:
         -------------------------

         compile with:

         "javac ATVapp_awt.java"

         in the same directory as ATVapp_awt.java
         (MS Windows users need to open a MS DOS prompt window)


         then, to run ATVapp_awt:

         "java ATVapp_awt [name of tree file in NH or NHX format]"

         e.g. "java ATVapp_awt testtree.nhx" -- to display to
              tree which is part of this distribution	

         Please note: ATVapp_awt is not suppored anymore.




  - Directly from the jar file: 
    ---------------------------
      Remark. Requires the Java runtime environment, including
      command "jre". If you do not have this, or if this does
      not work for other reasons, you can always compile the
      source code, as described above.


      o  for JDK 1.2 or greater:
         -----------------------
      
         "jre -cp ATVapp.jar ATVapp"

         in the same directory as ATVapp.jar
         (MS Windows users need to open a MS DOS prompt window)



      o  for Java 1.1.x or greater:
         --------------------------
 
         "jre -cp ATVapp_awt.jar ATVapp_awt"

         in the same directory as ATVapp_awt.jar 
         (MS Windows users need to open a MS DOS prompt window)

         Please note: ATVapp_awt is not suppored anymore.

     


  - Making life easier:
    -------------------

      Add a path to FORESTER to your CLASSPATH so that you can (e.g.)
      "java ATVapp" anywhere. For Unix/Linux use (example):

      "setenv CLASSPATH ./:/path/to/otherclasses:/path/to/forester"

      For Windows NT go to: "My Computer" | "Control Panel" | "System"
      | "Environment" and add to CLASSPATH.

      For Unix/Linux use (example)
      "alias atv 'java ATVapp'"
      to save some typing

      Windows users can modify the supplied example .bat file
      ("ATVapp.bat") and use it to start ATV with a mouse click
      on its icon.

      Obviously, these commands are only examples, you need
      to modify them according to your directory structure and according
      to which version of ATV you are using and according to whether
      you are using the Java runtime environment.




3.2. Running the ATV Applet
---------------------------

Requirement: Java 1.1.x or greater.

File "ATVapplet.jar" needs to be placed into the same directory
as your HTML and your tree files (at least, this is the easiest
way, if you are more experienced with applets and HTML, you
will know what to do anyway).

You can obviously also compile the source code files with:
 "javac ATVapplet.java" 
and then use:
 "jar cf ATVapplet.jar [all resulting .class files]"
to create file "ATVapplet.jar" from the resulting .class files.

To use a ATV Applet in your web page, you need to place the
following into your HTML file: 

<APPLET ARCHIVE = "ATVapplet.jar"
 CODE = "forester.atv.ATVapplet.class"
 WIDTH = 200 HEIGHT = 50>
 <PARAM NAME = url_of_tree_to_load
  VALUE = place the URL of your tree file here>
</APPLET>


If you have more than one tree, it is easier to use JavaScript.

For an example, see
http://www.genetics.wustl.edu/eddy/atv/atvapplets/ATV_applets.html


For more information about ATV Applets please refer to the
documentation which is part of this distribution:
PDF:     "atv_documentation.pdf"
MS Word: "atv_documentation.doc"




4. Obtaining Java
-----------------

To download JDK 1.3 Standard Edition for Microsoft Windows:
http://java.sun.com/j2se/1.3/download-windows.html

To download JDK 1.2 Standard Edition for Linux:
http://java.sun.com/products/jdk/1.2/download-linux.html

To download JDK 1.2 Standard Edition for Solaris:
http://www.sun.com/software/solaris/java/download.html




5. More Information
-------------------

ATV documentation:
  PDF:     "atv_documentation.pdf"
  MS Word: "atv_documentation.doc"


API specification for FORESTER (HTML): 
  is in directory named "forester_API_specification":
  point your browser to "index.html"
  Or online at:
  http://www.genetics.wustl.edu/eddy/forester/forester_API_specification/
  

Java:
  http://java.sun.com/


Jar files:
  http://web2.java.sun.com/docs/books/tutorial/jar/basics/index.html



(last modified: 10/04/01)

Christian Zmasek


