The format for designing trees has been designed to be as small as possible, without losing flexibility. No mathematics go in the XML file, that is all handled by the tree generator. I shall first describe the overall idea behind the format, then play show and tell with an example and finally give a reference sheet with all the tags and their attributes.

The root tag of the file is the <tree> tag. It has no attributes. Inside the tree tag are any number of <branch> tags, and exactly one <root> tag. A <branch> tag has the attribute id which is a number unique to this branch. Inside the <branch> tag are any number of <child> tags, each with a ref attribute. The ref attribute is a number, that refers to the id of a branch. The <root> tag also has a ref attribute, which specifies what branch is the root.

A "branch" in this context is not one branch on the tree, but rather one branch type. It contains information about how long and thick the branch is. A child tag specifies placement and number of other branches sprouting from this branch.

Each branch on the tree has a "level". The root has the highest level, and the branch tips have level 1. Level 0 and below will be ignored. By default, a child branch is one level below its parent branch.

The properties of a branch or child are specified by value ranges. For example: <position value="0.5" /> means that a branch will be placed at the middle of its parent branch. If changed to <position min="0.5" max="1.0" /> it would imply that the branch can be placed anywhere from the middle to the tip of its parent branch. It is like this with every property - they have their own tag, and must contain either a value attribute, or a min and a max attribute. Setting min and max to the same value will have the same effect as using the value attribute.

For example:

<tree>
 
    <root ref="1" levels="6" />
 
    <branch id="1">
        <length value="100" />
        <radius value="20" />
        <child ref="1">
 
            <position value="0.95" />
            <pitch min="10" max="55" />
            <count min="2" max="3" />
 
        </child>
    </branch>

</tree>

In the example above, there is only one branch type, which is also the root. It has a length of 100 units, and a radius of 20. It has either 2 or 3 children (the count tag), each placed near the tip of the branch (the position tag), and the have an angle between 10 and 55 degrees away from the parent's angle (pitch). A pitch of 0 means it has the same direction as the parent, a pitch of 90 means it is orthogonal to the parent, and 180 means it is growing back into the parent branch (bad idea).

The tree we just made will look like this:


What you should notice is that the smaller branches has a length that is shorter than the root branch. But why? The branch says all branches have length 100, no? This is because I omitted a tag inside the child tag, called lengthScale. The length scale defines how much shorter the child branch is relative to its parent. The default value is 0.60 which typically gives a good result (it is close to the inverse of the square root of E, in case you wondered). We could specify it explicitly by writing <lengthScale value="0.60" /> inside the child tag. Similarly there is also a radiusScale tag, but that defaults to 1.00!! So how can it be 1.00 when the top branches are clearly thinner than the trunk? That is because radiusScale is relative to the radius of the parent at the point where it is created. Because a branch is thinner at its tip than at its root, this automatically makes branches smaller as they advance the tree. This actually means that the position tag is affecting the radius of the child branches.

Here is what would happen if we added the tag <lengthScale value="1.00" /> inside the child tag:


That didn't look too good, so let's set lengthScale back to its default value by removing the tag again. Now it is time to add some leaves to our tree. Making the texture for the leaves is another science in itself so we'll just use the texture from the Oak tree's leaves. We add the leaves by adding a <leaf> tag inside the branch tag:

<tree>
 
    <root ref="1" levels="6" />
 
    <branch id="1">
        <length value="100" />
        <radius value="20" />
		
		<leaf>
			<position value="1.00" />
			
			<width value="30" />
			<height value="30" />
		</leaf>
       <child ref="1">
 
            <position value="0.95" />
            <pitch min="10" max="55" />
            <count min="2" max="3" />
 
        </child>
    </branch>

</tree>

This will add a 30x30 leaf at the tip of every branch. It will look like this:


Note the leaves between every bend on the tree, those weren't what we wanted. We only wanted leaves at the highest branches, and not those that split into other branches. To fix this, we use the level attribute, like this: <leaf level="1" />. This is actually a shortcut added for convenience; it is the equivalent of adding this tag inside the leaf tag: <levelRange value="1" />. The default levelRange is 0 to 100, which practically means every branch regardless of its level. The levelRange tag also works for child branches if placed inside the child tag, however: The level attribute has a different meaning if placed in the child tag so don't confuse them. If level="2" is placed in the child tag, it is a shortcut for this tag: <relativeLevel value="2" /> which is a disaster! The default value of relativeLevel is -1 (minus one). As I mentioned earlier, branches are one level below its parent. It is actually relativeLevel that determines their level, and setting it to a non-negative value will make the tree infinitely large, so don't do that. relativeLevel should always be negative.

There is another problem with our tree. Ocassionally, the branches on the root are placed so unfortunately that they coincide with each other and/or leave holes in the trunk. This is somewhat apparent on this screenshot:


To remedy this problem, we decide that:

• The root must have 3 child branches (as opposed either to 2 or 3).
  
• The branches must not coincide with each other.

Now how to we accomplish this? The root needs to be treated specially, so we add a new branch only for the root. Additionally, we add an orientation tag inside the child tags to enforce a certain angle distance between the children. An orientation of 0.00 means all the children will be placed on top of each other (bad idea). 45.0 means there is a fixed angle of 45 degrees between each child branch, which keeps them from coinciding, but looks very artificial. So add the tag <orientation min="45" max="160" />. Our XML file now looks like this:

<tree>
 
    <root ref="2" levels="6" />
   <branch id="1">
        <length value="100" />
        <radius value="20" />
		
		<leaf>
			<position value="1.00" />
			
			<width value="30" />
			<height value="30" />
		</leaf>
       <child ref="1">
 
			<orientation min="45" max="160" />
            <position value="0.95" />
            <pitch min="10" max="55" />
            <count min="2" max="3" />
		
        </child>
    </branch>
	
    <branch id="2">
		<length value="100" />
		<radius value="20" />
		
		<child ref="1">
			<orientation min="45" max="160" />
			<position value="0.95" />
			<pitch min="20" max="55" />
			<count value="3" />
		</child>
	</branch>
</tree>

Note that we now have a another branch tag, with ID 2. We changed the root tag to refer to this ID instead, so the new branch is our root. The only difference is that the root tag has exactly three children (with ID 1). I removed the leaf from the root branch because it has no use there anyhow (the root is always level 6). I also added the orientation tag inside the child tags. This demonstrates a clumsy feature of this format, since the two branches are almost identical, but we have to copy and paste the entire part anyways. No way around that, we will have to deal with it.

This is what the tree looks like now:


Finally, we want to add a bit more flavor to those leaves. We do that by varying the vertex color a bit using the red, green, and blue tags inside the leaf tag:

		...
		<leaf>
			<position value="1.00" />
			
			<red min="200" max="255" />
			<green value="255" />
			<blue value="196" />
			
			<width value="30" />
			<height value="30" />
		</leaf>
		...

This will give the leaves some more exciting colors. Now the example is done, and our tree looks like this:




Quick reference sheet

Tags that are not listed are value ranges. They have the attributes min and max or value.

Tag	Attributes	Child tags	Default
tree		root, branch
root	ref, levels		levels=4
branch	id	length, radius, radiusEnd, child, leaf	length=10, radius=5, radiusEnd=0.5
child	ref, level	relativeLevel, levelRange, position, lengthScale, radiusScale, orientation, pitch, gravity, count	relativeLevel=-1, levelRange=0-100, position=0-1, lengthScale=0.6, radiusScale=1.0, orientation=0-360, pitch=0, gravity=0, count=1
leaf	level	levelRange, position, count, red, green, blue, width, height, scale	levelRange=0-100, position=1, count=1, red=255, green=255, blue=255, width=10, height=10, scale=1

For more examples, I suggest you look at the four tree designs that are included in the download.