space tree add-on documentation
Some time ago I decided it would be a good idea to create a tree generation add-on for Blender that was simple to use end lent itself to easy integration into scenes. Like IvyGen I wanted it to be able to detect and interact with existing geometry and it should be dead simple to use. And so the spacetree add-on was born.
This document describes its installation and use. More about the background and algorithms used plus references to the original idea by Adam Runions on space colonization can be found in several articles on my blog. (If you search for the tag tree you will find the relevant posts). User feedback is collected mainly on this BlenderArtists thread.
Important note: generating trees is quite simple with this add-on but texturing the bark and leaves is not covered here so you must have some experience in applying materials in Blender.
The add-on has to be downloaded and installed in Blender using the following steps:
- Download the add-on from GitHub
- The add-on can be downloaded from GitHub as a zip file.
- go to GitHub
- click view raw to start the download of the zip file to your standard download location (this location may vary for different browsers)
- Install the zip file from user preferences
- Click File->User preferences
- Click add-ons
- Click install from file
- browse to the zipfile that you just downloaded and click ok.
- Enable the add-on
- Check the enable add-on checkbox to activate it.
If you later open another new blend file and have to enable it again you can find it in the add mesh section of the add-ons.
a basic tree
Once you have installed the spacetree add-on, generating a tree is as simple as positioning your 3d cursor at the position in the scene where you want to have your tree and selecting Add->Mesh->Add tree to scene.
At this point you will have the skeleton of a tiny tree (as seen on the right in the image below). Unchecking
no modifiers and clicking update tree will give the branches some substance. (middle image, note that the edges of the skeleton stay visible in the 3d View but they will not render)
Clicking Add leaves followed by clicking update tree will result in a small but perfectly formed tree with leaves (on the right. The leaves are plain squares)
From here any number of parameters may be changed to get the result you want. A mature tree with dense foliage as shown in the next image [img] is quite simple to create using the following settings [img]. Any materials you will have to apply yourself, typically one for the bark and a semi transparent uv-mapped leaf image for the leaves. An example is shown below. [img]
shaping the crown with groups
If you want to have more control over the shape of the tree you might want to use groups. In this example we want to generate a tree that grows partly in the shadow of a house. We will define a crown group that controls the outline of the crown, a shadow group that defines the shadow area and an exclusion group that defines an area that absolutely cannot be penetrated by branches.
Our sample scene looks like this:
(The .blend file is available on GitHub click view raw to download it) It contains two cubes grouped in a group "house", a larger cube consisting just of edges and vertices that is in a group "shadow" and a crown shape consisting of several meshes in a group called "crown". The 3d-cursor is positioned somewhere below the crown group and outside any meshes that make up the house group.
If we point the various group parameters to the correct groups and change the general parameters to produce a fairly bushy tree (as shown in the image below) then if we click update tree the following tree is produced:
Note that none of the branches ends up inside the house and that the shadow area is mostly avoided, resulting in a straight, branchless bole thas has a crown mostly above the shadow area.
This section tries to document each parameter and provides many example images. Because the spacetree add-on is a work-in-progress some parameters might not be covered (yet). If that is the case you might check my blog to see if there is an article covering the new parameter.
- Update tree
- Unlike most add-ons space tree will not update the tree it is generating on every parameter change. Because generating a tree takes quite some time (several seconds for large trees) updating it on each parameter change would result in a very sluggish interface. Therefore you have to click update tree to apply any settings you have changed and create a new tree.
- Random seed
- All trees are generated based on a quasi random distribution of points. Selecting a different random seed will result in a different distribution and hence in a different tree. This way you can generate a set of different but similar trees once you are satisfied with the other settings.
- Maximum iterations
- Each iteration new segments are added to the tree and endpoints within the kill distance removed. When there are no more endpoints the growth of the tree stops. By changing the maximum number of iterations we can terminate the growth of a tree before all endpoints are gone. This might for example be used to create juvenile trees but it is also a safeguard as large trees may take a long time to generate. You might for example tweak the other parameters first to get a nice shape and then simultaneously reduce the internode length and increase the maximum iterations to get a highly detailed tree.
trunk and branches
Trunk and branch shape
- Number of endpoints
- New tree segments will grow in the direction of the closest endpoints. By changing the number of endpoints the density of the branches is influenced. More endpoints will result in a tree with more forking branches.
- Internode length
- The length of each branch segment that is added to the tree skeleton. This is roughly (very roughly) analogous to the growth from a bud in a season (an internode). Decreasing the internode length will give a better defined tree.
- Influence range
- This determines which endpoints have an influence on the direction of new branch segments. Only those within influence range matter. The range is specified in multiples of the internode length. Reducing the influence range makes sense if you have a very large number of endpoints and want to reduce the time it takes to generate a tree. If the influence range is very small it affects the shape of the tree skeleton as well.
- Kill distance
- As the tree skeleton grows endpoints within kill distance are removed. Reducing the kill distance will influence the shape of the tree. The distance is specified in multiples of the internode length.
- When a branch forks the new branches are smaller in diameter than the parent branch. Power determines how fast this decrease in diameter propagates up the tree.
- This is the overall scale of the trunk diameter and its branches.
- Tropism is the preference newly formed tree segments have to grow upward (for positive values) or downward (for negative values). This may be used to mimic growth towards light or the influence of gravity.
- Number of new endpoints
- Most new branch segments will be formed on the outside of the growing tree. By adding extra endpoints during the generation process it will become more likely that new branches will be created inside the tree skeleton. The number of new endpoints is specified per thousand iterations, so a value of 3000 for example will give you 3 new endpoints per iteration on average.
- Top bias
- increasing this value will place more endpoints near the top of the crown, both for the default crown shape and the shape specified by a group of meshes.
- Surface bias
- increasing this value will preferentially place endpoints near the boundary of the crown shape (simple crown shape only)
The shape of the crown (that what determines the silhouet of a tree) might be specified by how the endpoints will be distributed. The default method places all endpoints inside a simple sphere while the use groups method uses a group a mesh objects to determine the boundary of the crown.
The simple sphere is actually an ellipsoid that is positioned some distance along the z-axis from the 3d cursor. This ellipsoid can be controlled with the following parameters:
- Crown size
- The horizontal radius of the ellipsoid in blender units.
- Crown shape
- The size of the vertical radius compared to the horizontal radius.
- Crown offset
- The offset of the centre of the ellipsoid relative to the 3d cursor.
The shape of the crown may also be specified by groups of mesh objects. If you check use object groups you get access to the following group selectors.
- Crown group
- The union of all objects in the crown group specifies the outline of the crown. These objects need not be just meshes but metaballs and bevelled curves are not tested.
- Shadow group
- Objects in the shadow group are subtracted from those in crown group. No endpoints will be generated within these objects. This might for example be used to model the influence of shadow. Note that generated branches may still enter this volume depending on the final distribution of end points.
- Exclusion group
- No branches will be generated inside the volume specified by the objects inside this group. This is stricter criterion than that of the shadow group. Normally you place the outline of buildings inside this exclusion group.
By default the generated tree will consist of a single trunk that originates at the position of the 3d cursor. If use trunk group is checked you can however select a group of objects of which `the origins will be used as the roots of one or more trunks.
- Trunk group
- Select the name of a group of objects. The origins will be used as the roots of the trunk(s). The group may contain any object but it probably will make most sense to use empties here. If no group is selected or if the group contains no objects a single trunk will be started at the position of the 3d cursor.
skinning options (modifiers)
A tree skeleton consisting just of vertices and edges won't render as anything visible. For that we need to give it so substance by applying a skin. This can be done by unchecking the no modifiers checkbox, which gives access to two different methods to skin the tree skeleton.
- Skinning method
- Here you can choose between Native (i.e directly calculated by the add-on) or Skin modifier (which will add Blenders modifier to the modifier stack. Each method gives a slightly different result, which one is best is for you to decide. The native method is however a lot faster and is therefore the default.
- Sub Surface
- Checking this option will add an extra sub surface modifier to the generated mesh.
leaves and blooms
By checking add leaves and/or add objects simple leaves and/or arbitrary objects can be attached to the tree branches. All leaves will be part of a single object parented to the trunk. Each leaf will be a simple square. Objects will duplicated and parented to the trunk.
The distribution of leaves and objects is governed by the same parameters but each has its seperate set. Those for leaves are explained below.
- Leaves per internode
- The average number of leaves per internode (branch segment)
- Leaf clustering
- How much leaves are clustered near the tip of an internode are spread along the length.
- Leaf size
- The size of the leaf.
- Leaf random size
- Maximum extra size randomly added to each leaf.
- Leaf random rotation
- Leaves are randomly rotated around the z-axis. The random rotation is the maximum extra rotation around the x- and y-axis that is randomly added to each leaf.
- Max connections
- Internodes that are further away from the tip of a branch than this number will not grow leaves.
With these options some information is shown that might be helpful while developing a tree model or tweaking the code of the add-on
- Show markers
- If checked the initial distribution of endpoints is shown as a collection of small tetrahedrons.
- Marker size
- The size of the markers.
- Show timings
- If checked the amount of time spent in various parts of the code is shown on the console.