The sections below describe how to install The Tree Project program and use
You first need to install the program before you can use it. Installation requires basic computer skills. Also, you need to have Java installed on your computer. But first follow the instructions below to avoid an unnecessary Java installation.
Follow these steps to install the program:
- Download the executable code, which comes in the form of a zip file called ‘code.V5.0.zip’, and save it to a convenient location on your hard drive. The download should only take a few seconds. Note that the current version of the code is 5.0.
- Extract the contents of the zip file by double clicking on it and then choosing ‘Extract’ or ‘Extract all’ or something like that. (For example in Windows Dutch version you would choose ‘Alle bestanden uitpakken’).
- Navigate to the folder where the contents were placed: you should see directories called ‘config’, ‘images’ and ‘trees’ and a file called ‘TTP.jar’ (or ‘TTP’ if the extension is hidden).
- Double click on the TTP.jar file. If all goes well then you should see a short animation:
Congratulations! You successfully installed and started the program!
Note: Due to a bug in more recent Java implementations, you may have to manually stretch the screen a little bit to see all the buttons.
What if it doesn't work?
There may be several reasons why things didn't work out…
- Maybe Java is not installed on your computer?
- For Windows: Press Windows key+R and enter cmd and then in the black DOS box enter java -version (Note: the Windows key is somewhere between Ctrl and Alt).
- For Linux: Open a terminal or terminal emulator and enter java -version
- If Java is installed, maybe be you have an old version? I used Java version 1.8.0 to compile the program. Then if you use an older version of Java the program will not work.
- In some Linux versions a .jar file will not just execute by double
clicking. You have to explicitly tell it to open with java -jar
or OpenJDK Java Runtime and/or make it an executable as well.
Right click on the TTP.jar file to adjust these properties.
However, in my case it did not fully function even then: although the screen above appeared, for some reason the properties file and The Tree Project logo (which you should see when you choose About in the Help menu) were not read.
For me to get it to work in Linux I use a terminal emulator, then cd to the directory where TTP.jar is stored and give the java -jar TTP.jar command.
Anyone knows what might be the cause? Then please contact me by sending an e-mail to the address given on the home page.
- If you're Java savvy, you may also download the source code given on
the home page and compile and run it.
- For Windows: From a DOS box cd to the src directory and give the javac tree\Tree.java command to compile the program and then java tree.Tree to run it.
- For Linux: From a terminal emulator cd to the src directory and give the javac tree/Tree.java command to compile the program and then java tree.Tree to run it.
- If all this does not help, contact me by sending an e-mail to the address given on the home page.
So you started the program. Now imagine that you view your model through a screen. You move through your 3D model by moving the screen, using the twelve buttons of the ‘Screen control’ panel on the right. There are six buttons to shift the screen, see the left-hand picture below, and six buttons to rotate the screen, see the right-hand picture below.
For example the ‘UP’ button corresponds with the arrow pointing up in the left-hand picture and will move the screen upwards (so the model looks to be going down), and the ‘PUSH TOP’ button corresponds with the curved arrow at the top of the screen in the right-hand picture and will tilt the screen by pushing at the top.
The properties file
Because The Tree Project in its current form shows wireframe models, we just see a bunch of lines on the screen. If all lines are of equal thickness and color, there is no way of telling which lines are closer and which lines are farther away. Now, for shapes that are well known, such as a cube, the human mind recognizes these shapes and kind of infers which lines are closer and which lines are farther away. However, this does not always work. So what The Tree Project does, is to reduce the width of the lines and fade to the background color as they get farther away.
The width reduction factor and the fade to background factor are some constants >= 0. Value 0 means no width reduction or fade to background effect at all. The larger these values get, the larger the effect. I found that a good value for the width reduction factor is 0.5 and a good value for the fade to background factor is 0.1.
You set these properties in the configuration file called ‘properties.txt’ in the ‘config’ directory.
The configuration file also allows you to set the background color, the pen width (the width of the wireframe lines were there no width reduction) and the pen color (the color of the wireframe lines were there no fade to background).
Creating your own models
By choosing the ‘Open…’ menu item in the ‘File’ menu you can read other tree files. A tree file contains a model.
The first time that you choose ‘Open…’, the ‘trees’ directory is shown, but of course you can put your tree files anywhere you want.
To define a model, you create a set of nodes and a set of branches to
connect the nodes.
Each node has an x, y and z coordinate in 3D space.
The picture above also shows the start position of the screen through which you view a model.
Now, a tree file contains all the definitions for the nodes and branches that make up a model. Actually, a tree file is a file that conforms to a set of simple rules:
- it is a plain text file;
- the [NODES] token indicates that the lines hereafter contain node definitions (zero, one or more nodes can be defined);
- a node definition has the form nodeName nodeX nodeY nodeZ with nodeName the name of the node and nodeX, nodeY and nodeZ the x, y and z coordinates of the node respectively;
- nodeName can be any string and nodeX, nodeY and nodeZ must be floating point numbers;
- the [BRANCHES] token indicates that the lines hereafter contain branch definitions (zero, one or more branches can be defined);
- a branch definition has the form branchName nodeP nodeQ with branchName the name of the branch and nodeP and nodeQ the end points of the branch;
- branchName can be any string and nodeP and nodeQ must be the names of nodes that have been defined earlier in the file;
- whitespace is used as the delimiter pattern (a space, a tab, a new line, or any combination);
- the [NODES] and [BRANCHES] tokens are case insensitive;
- comments are preceded by an exclamation mark, the remainder of the line after the exclamation mark is considered to be a comment.
For example, the file ‘pyramid.ttp’ in the ‘trees’ directory is a valid tree file:
! pyramid: first define the base nodes, second define the apex node ! p = pyramid ! n = node ! b = branch [NODES] ! nodeName nodeX nodeY nodeZ pn1 -250.0 0.0 1000.0 pn2 250.0 0.0 1000.0 pn3 250.0 0.0 1500.0 pn4 -250.0 0.0 1500.0 [BRANCHES] ! branchName nodeP nodeQ pb1 pn1 pn2 pb2 pn2 pn3 pb3 pn3 pn4 pb4 pn4 pn1 [NODES] pn5 0.0 500.0 1250.0 [BRANCHES] pb5 pn1 pn5 pb6 pn2 pn5 pb7 pn3 pn5 pb8 pn4 pn5
As you would expect, when you read this tree file using ‘Open…’ you will see a pyramid.
Note that things become complicated very easily. Use ‘Open…’ to read the tree file called ‘city.ttp’. Although more impressive than a simple pyramid, note how cluttered things become when using wireframe lines. Also try to open this file in a normal text editor and see how complex the file is! This calls for new features:
- Display of solid surfaces instead of wireframe lines;
- Provision of an easy to use graphical editor instead of having to edit a text file;
- Possibility to use the mouse to travel through a model.
If you think about these features, you will soon realize that these are major tasks. But I will start working on them in the future.