The manual below is included in the download as a PDF file for easy reference. The PDF version also contains a proper table of contents as well as the FAQ.

Space Tree Pro Manual

The Space Tree Pro manual, © 2015-2019 Michel J. Anders, all rights reserved.

Intro

Trees are assets that can define a scene. They can be the center of attention, an important prop or just a background but in all those cases they add to the general mood by their shapes and colors. A key factor in the believability of a scene is how well the trees blend in with the environment. And this is where Space Tree Pro comes in, with its ability to create crown shapes based on how much light is available at a certain location, it's awareness to prevent branches from growing into impenetrable buildings and the possibility to grow multiple interacting trees or bushes at once.

While there are a few tree creation options available to Blender users, Space Tree Pro started out as an experiment to see how easy it was to implement the space colonization algorithm (see External references). This algorithm, where growing branches compete for markers reminiscent of available light, seemed to lend itself for easy interaction with the environment. Indeed, the initial versions worked quite well, so in the end I decided to clean up the code, reorder the user interface to suit most workflows better and to add some nice features, notably the option to define the distribution of markers with a grease pencil which creates endless possibilities to design unique trees.

This manual provides the installation instructions, references to tutorials and aims to be a complete reference manual for all the options available. There are some instruction videos available on YouTube as well and of course you can always ask me a question, for example on my blog: blog.michelanders.nl.

File contents

The zipfile you downloaded contains the following items:

Installation

System requirements

Space Tree Pro should work on any Blender installation with Blender 2.80 or newer. Be aware that the trees generated are moderately hi poly (i.e. the examples shown throughout this manual typically contain a hundred thousand quads, so when you want to have many different and large trees, memory might be an issue. Larger trees can also take quite some time to generate, so a fairly powerful machine is recommended for an optimal experience.

Unpacking and installing

Installing the addon is no different from almost every other addon for Blender:

• unzip the file you downloaded

it contains several files. Locate the zipfile space_tree_pro_280.zip, this contains the addon

• open Blender and go to the add ons

      Edit → Preferences... → Add-ons

click 'Install ...'

a file selection dialog will open. Navigate to where you have stored space_tree_pro_280.zip, select it and click ´Install Add-on from File...´

• enable the addon

by checking the checkbox in front of the name of the addon

Remember that Blender does not enable add-ons automatically when opening a file so if you want to add new trees or change existing trees in a .blend file don't forget to enable the addon. It can be found in the Add mesh section. 

First use

After the installation Space Tree Pro is ready for use. Select Add → Mesh → Tree from the 3d view to add a small tree skeleton at the position of the 3d cursor.

You can now change the properties of the tree. All properties are located in the Space Tree Pro tab of the toolbar and grouped in several panels.

Note that the toolbar is on the right of the 3D view and can be made visible by pressing N

Changing properties does not have an immediate effect, you have to click the Update tree button to actually change the tree. This method was chosen because generating more complex trees can take several seconds (depending on the power of your PC) and without an explicit update action this would render the interface sluggish or even unworkable. An additional advantage is that you might change more than one property before updating the tree.

Properties are persistent, which means they are stored along with all the other data of the tree. So even when you reopen a saved file or import a tree from another file you can change and update that tree from the Space Tree Pro panel in the toolbar (if you have enabled the add on).

Video tutorials

A number of short, tutorial style videos are available on YouTube. The current set is available in this playlist and consists of:

Short introduction

How to create trees with multiple branches

How to create a lane of trees

Training a rose along a wall with Space Tree Pro

Workflow

There are many ways to discover which settings make the ideal tree for you. Just tweaking the properties and seeing where they lead you is a valid approach that may lead to interesting results but often you can save a lot of time by using a systematic workflow.

Working from examples

Space tree pro comes with a small library of sample trees that you can use as is or that may be used as a starting point. Just make sure you have enabled the addon by checking Edit → Preferences... → Add-ons → Add mesh → Space Tree Pro. Then append one of the bundled tree examples from the Sample Trees directory with File → Append. Locate the .blend file (for example 'Oak Tree.blend') and then go to the Groups folder and select 'Tree' (Note that there might be other groups present). 

(A sample of ready to use trees included with the Space Tree Pro addon)

If you select the main Tree object from the group of objects you just imported, you can change its properties in the Space Tree Pro tab in the toolbar and update it.

Simple trees

Trees can also be made from scratch in a few distinct steps. The idea is to work from the ground up by defining first how the branches will develop, then how the general shape of the crown will look and finally adding detail like bark and leaves.

Adding a new tree

Add a new tree object in the 3D view by selecting Add → Mesh → Tree. A tiny skeleton of a tree will be positioned at the 3D cursor.

Controlling the branches

The next step is to increase the complexity of the branch structure. We can do this by adjusting three important properties in the Trunk and branches panel: Markers, Segment length and Kill distance. By setting Markers to 400, Segment length to 0.25 and Kill distance to 2.0 and clicking Update tree we get a much more developed branch structure:

The central idea in the algorithm used by the addon to generate a tree skeleton, is to distribute markers inside some volume and grow a branch in small steps towards the markers that are closest. When the growing branch reaches a marker this marker is removed (colored red in the illustration below). In the process of growing and removing markers the relation between markers and existing segments changes: a branch may grow a new segment but some markers may still be closest to the previous segment because they were outside the kill distance. This will lead to a side shoot.

So by lowering the Kill distance the growing tip of a branch will remove less markers, leading to more side shoots and thus a more complex tree. By shortening the segment length and increasing the number of markers we then improve the definition of the tree.

Shaping the crown

The outline of the crown of the tree is mainly determined by the shape of the volume that contains the markers. By default this is a sphere located straight above the 3d cursor, resulting in a straight trunk and a spherical crown:

In the picture above we can see both the generated branches (in green) and the distribution of the markers in the crown volume (in grey). 

The shape, position and size of this volume can be controlled with properties in the Crown panel. Setting Shape to 2.0, Taper to 1.8 and clicking Update tree will give a wider crown: 

Adding bark

Until now we defined the tree skeleton but we didn't give it any body. In fact if we would render the tree right now it wouldn't be visible because it consists of just vertices and edges.

By checking the Skin option and clicking Update tree we get an actual trunk: 

However a trunk without any material assigned is just a dull grey pipe, therefore select a material in the Bark material selection box and press Update tree.

Adding leaves

Although many trees lose their leaves in winter, most situations call for trees with leaves. These can be added in the Leaves panel. Space tree pro comes bundled with a small selection of sample trees with leaves and flowers and you can append the particles systems from those sample trees to your scene and then select from the Leaves selection box.

Interacting with the environment

Creating solitary trees is fine but in real life trees are often not in an isolated environment. If placed near buildings you have to make sure the branches do not penetrate walls and their shape might be influenced by shadows. Also many trees have artificial shapes when they are part of hedgerows or trained along a wall. Many of these effects can be attained with Space tree pro.

Collections

If we would like to shape a large tree near a wall, one way to do it is as follows:

• add a cube, scale it to resemble a 3 blender units high wall, apply any transformations and move it to a new collection 'Wall'

• roughly arrange a few spheres to represent the crown. Four or five of them with a diameter of 2 blender units each should do. Make it so that their centers are about 4 Blender units from the ground (i.e. level with the top of the wall) and position them in such a way that they partially intersect with our wall. Apply any transformations and move the spheres into a new collection 'Crown'

The result should resemble this

Next place the 3D cursor somewhere beneath the crown collection and select Add → Mesh → Tree. Change the number of markers in the Trunk and branches panel to 1000 and the segment length and kill distance to 0.25 and 1.5 respectively. In the Crown panel select 'Crown' in the selection box for the Crown group and 'Wall' in the selection box for the Exclusion group. Next click Update tree. The result should resemble this

(In the image on the right we turned the wall into a wireframe and if you look closely you will notice that none of the branches have penetrated the wall.

Multiple trunks

Often two or three trees grow closely together or simply have more than one trunk emerging from the ground. We can emulate this by creating a collection of empties and have the origins of those empties act as starting points for trunks.

In the previous scene, place three empties about half a blender unit apart near the root of our previously generated tree and add them to a new collection 'Trunks'. In the Trunks and branches panel select 'Trunks' in the Trunk collection selection group and click Update tree:

(Here we added a skin to make the trunks better visible)

Controlling tree shapes with grease pencil strokes

Sometimes tree shapes are very unique. They might have a curved trunk, a large protruding branch or part of the crown is much taller than the rest. Also some fruit and linden trees (lime trees) are trained along frames or walls in shapes that do not resemble any natural tree at all.

Many of these shapes can be created by controlling the distribution of markers along grease pencil strokes.

By enabling Grease Pencil, markers will be distributed around the strokes of the active grease pencil layer in addition to the other markers. To create a tree with a crown that bulges irregularly you would

• enable grease pencil drawing

by clicking on the Annotate tool

• draw one or more strokes to the side of 3d cursor

• select Add → Mesh → Tree

• enable grease pencil in the grease pencil panel

And select a suitable number of marker to distribute along the strokes. A few hundred should do.

• click Update tree

The newly created tree is nicely crooked, something we can appreciate better if we give it more body (with more endpoints, shorter branch segment length and a shorter kill distance) and a skin:

If we enable 'Grease pencil only' in the Grease pencil panel we can control the shape of the tree completely. Combined with the fact that you can snap grease pencil strokes to an object and that we can instruct the addon not to penetrate an object, it is not so complicated to create something like a climbing rose that is trained to a wall:

• start with the default scene containing just a cube.

• resize and reposition the cube so it's about 10 units wide, 5 units high and has its underside at z = 0

• add it to a new group 'Wall'

• draw with the Annotate tool a rough outline on the wall and make sure the strokes snap to the wall object

• position the 3d cursor near the base of the branches

• select Add → Mesh → Tree

• in the Grease pencil panel (in the Space tree pro tab in the toolbar) select Grease pencil and select Grease pencil only

• in the Crown panel, select Wall in the exclusion group selection box

• click Update tree

With a proper set of leaves and blooms added the rendered view might look like this:

Reference

Structure of a generated tree

The generated tree consists of several elements that together form the tree. When working with a generated tree it helps to know how these elements depend on each other.

Meshes

The tree is collection which makes appending or linking a tree from a library easy. The collection consists of two meshes: the Tree and the Leaf emitter.  Any markers you choose to display are a spearate mesh that are not part of the collection. The Leaf emitter and the Markers are parented to the tree and the Markers are only there if selected in the Advanced panel. The Leafemitter itself is not very noticeable as its faces are tiny (and will not be rendered if the particle systems that will be associated with it have the Emitter option unchecked). The tree mesh itself represents the trunk and branches. If skinned it consists not only of the faces of the bark but the vertices and edges of the tree skeleton remain part of the mesh.

Vertex groups, uv-maps and vertex color layers

The tree mesh and the leaf emitter mesh have a vertex group, named  'Leaf distribution' and ‘Leaves’ respectively. In the leaf emitter mesh this can be used to control the density of the leaves. The tree mesh if skinned also has two uv-layers and a vertex color layer which together can be used by bark materials to create seamless textures around the the branch joins.

Bark material

The tree mesh might also have a material associated with it if the user selects one in the Bark panel

Particle systems

The leaf emitter mesh might have one or more particle systems associated with it

Properties

Trunk and branches

Update Tree

update the tree based on the selected options. Depending on the power of your computer complex trees might take a few seconds to generate. This is too slow to be truly interactive so instead of experiencing sluggish behaviour on each option change this addon lets you change any number of options before you may explicitly update the tree. For convenience the Update Tree button is present in most panels.

Number of markers

The number of markers generated in the growing volume at the start

Number of new markers

The number of new endpoints generated in the growing volume per thousand iterations. These markers are added during the growth of the tree. Because these additional markers will be positioned near existing branches, adding more of them will generally lead to more complex trees.

Branch segment Length

Branch segment length in Blender Units. With smaller branch segment lengths the branches of the tree will look smoother

Kill Distance

Kill Distance as a multiple of the branch segment length. Any markers within this distance from any branch segment will be disabled. A smaller kill distance will lead to more complex trees.

Influence Range

Influence Range as a multiple of the branch segment length. Only markers within this range will be considered for determining a new branch direction. For large and complex trees that are generated with a lot of markers reducing the influence range may speed up the tree generation without changing the appearance much.

Tropism & Springiness

The tendency of branches to bend up or down due to gravity and their tendency to tip up again.

Branch Angle

The preferred angle of side shoots relative to the main branch

Branch Angle Weight

How much we prefer the branch angle over the direct direction, 1 is completely in favor of the branch angle.

Straight Weight

How much a main branch will follow its initial direction. Larger values will approximate the branch pattern of certain conifers.

Apical Control

The amount of apical control, i.e. how much a growing tip will suppress new shoots further down along a branch

Apical Falloff & Apical Timing

Falloff and duration of apical control along branch. A falloff < 1 will ease falloff, > 1 will sharpen it.

Trunks

Collection of objects whose locations specify trunk starting points. You could use this to create trees with multiple trunks or for example hedgerows consisting of rows of small shrubs. Normally you would use a group of empties for this purpose.

If no trunk collection is selected the origin of the tree object is used to start a single trunk or the 3D cursor is the starting point when adding a completely new tree.

Pruning Generation

Prune branches last touched in this generation (0 won't prune anything). The effect of the option is difficult to notice because depending on the kill distance all the markers might have been disabled long before the maximum number of iterations is reached. The Breaking Branches option might be more intuitive.

Breaking Branches

The number of branches that will be removed randomly after the trunk skeleton is generated. This mimics things like storm damage and may give a tree a unique character.

Random Seed

The seed governing random generation

Crown

Crown Size

Crown size. The Var option is only enabled if the random seed in the trunk and branches section is not zero, in which case a random amount is added to the crown size with a maximum specified by Var.

Crown Shape

Crown shape, how much it looks like a flattened ellipsoid. The Var option is only enabled if the random seed in the trunk and branches section is not zero, in which case a random amount is added to the crown shape with a maximum specified by Var.

Crown Taper

Crown shape, how much it looks like a droplet

Crown Offset

Crown offset, i.e. where the center of the crown is situated relative to the 3D cursor. This influences the length of the bole (main trunk). The Var option is only enabled if the random seed in the trunk and branches section is not zero, in which case a random amount is added to the crown offset with a maximum specified by Var.

Surface Bias

Surface bias (how much markers are favored near the surface)

Top Bias

Top bias (how much markers are favored near the top)

Crown Collection

Collection of objects that together specify the crown shape. If selected the simple ellipsoid controls will be disabled.

Shadow Group

Group of objects subtracted from the crown shape

Shadow density

Shadow density, bigger means less markers in shadow group volume

Exclusion Group

Group of objects that will not be penetrated by growing branches

Bumpiness

When using a simple ellipsoid for the crown shape it is possible to add some bumpiness to the general outline to prevent a profile that looks to smooth. The bumps will differ for each individual tree if you set a different random seed. In the image below the effect is shown for a bumpiness of 0.24 in the tree on the right.

Grease Pencil

Note that the Grease Pencil options are only enabled if there is an active grease pencil layer that is associated with the scene (not with the object!).

Only Grease Pencil Markers

Do not generate any other markers beside the ones generated along the grease pencil strokes. Will disable most options in the Crown panel.

Markers

Number of markers to generate along the strokes of the active grease pencil layer.

Radius

Radius around the grease pencil strokes wherein markers will be generated. The smaller the radius the better any branch will follow the grease pencil strokes.

Skin

The trunk and branches of a tree will only be skinned if the option in the header is checked.

Skinning

How the skin around the tree skeleton (the bark) is created. There are four options:

Spacetree: Native solution. Quick, low-poly but not optimal for small and highly curved branches

Skin modifier: uses Blenders built-in skin modifier. Rather slow but better looking although quite high poly

Convert to curve: converts the tree skeleton to a curve object with a bevel. Quite fast and good looking but cannot be uv-unwrapped

Ball-and-Pipe: creates a mesh based on spheres and cylinders. Quality similar to convert to curve.

Native                    Skin modifier

Convert to curve                Ball and pipe

For a moderate tree (1000 markers, 400 new markers, branch segment length 0.25, kill distance 1.0) the four skinning methods give the following numbers (on a Intel i7, 4 cores, your mileage may vary)

Branch tapering

How fast branches taper off towards the tip as they split.

Branch diameter

Branch base diameter (gets smaller near the tips).

Sub Surface

Add a subsurface modifier to the trunk skin.

Bark material

Bark material to use on trunk and branches.

Leaves and twigs

Leaves and/or other particle systems will only be generated if the option in the header is checked.

Leaf clustering

How much leaves cluster to the end of the branch. Higher values mean that leaves will appear at more segments from the tip.

Leaves & Other

Settings for a particle systems. To use particle settings from a predefined tree, append that sample tree (or a sample object with the same particle settings) to your scene (preferable in another layer) and its particle settings should appear in the Leaf distribution drop-down. Click Update Tree. The appended sample tree may then be deleted (the particle settings will remain because it still has a user: your own tree.

Density

This controls the number of particles in each of the particle systems.

Make unique

Setting this option will ensure that the settings of each particle system are unique. In Blender particle system settings are objects that are separate objects from the particle system proper and if these are not made unique then all the tree particle systems share all the settings. This is convenient when tweaking parameters like random size or rotation but also means that all trees sharing the same particle system settings will have the same number of leaves, because the number of particles is part of the settings too.

Advanced

Show Markers

Will generate a separate mesh with small objects at the positions of the markers. This may help in determining the shape of the crown and is used extensively in this manual to illustrate the effects of options.

Marker Scale

The size of the markers (only visible if show markers is checked).

Show last timings

Show timings of steps during last generation. For debugging purposes.

Maximum Iterations

The maximum number of iterations allowed for tree generation. Acts as a sort of emergency break to terminate the generation of trees that are very complex.

Emitter scale

Leaf emitter scale. Although normally the leaf emitter itself will not be rendered, the size of the emitter has a slight influence on the distribution of the leaves if the number of leaves is large. If there are more leaves than faces in the leaf emitter, individual leaves originate from different locations on the faces. Increase the emitter size then makes for a slightly more random appearance.

Distance

Leaf emitter quads closer than this distance to an object in the exclusion zone will not be generated.

Flip Angle

If a branch segment is not forked but the angle between two successive elements is larger than the flip angle, the new segment is moved from the tip to the side to give a better looking branch.

Lock

Prevents a model from changes. The model can still be copied with all its associated options but has to be explicitly unlocked by the user. This may help in preventing accidental changes, especially if a model was created with a grease pencil strokes and or groups that are no longer present in a new scene.