The spacetree Blender add-on: Documentation

space tree add-on documentation

A professional version of this add-on, Space Tree Pro, is available on BlenderMarket. It offers among other things, a vastly simplified user interface, new functionality, you can sketch the light distribution with a grease pencil, tree parameters that are persistent (objects can be saved and altered later on), a library of assets (leaf and fruit particle systems, complete tree presets),better skinning and uv-maps, several workflow based tutorials and extensive reference documentation. The free version stays available of course.

intro

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 page is a work in progress. The text is more or less complete but I will be adding more illustrations in the near future.

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.

installation

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.

quick start

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.

parameter overview

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.

general

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.
Power
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.
Scale
This is the overall scale of the trunk diameter and its branches.
Tropism
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)

Crown shape

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.

Simple sphere

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.
Using groups

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.

debugging options

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.

22 comments:

  1. hello,

    What is the addon works with Blender 2.70

    thanks

    ReplyDelete
    Replies
    1. Use the Add/Mesh/Add Tree To Scene from the Header (footer?) bar. (It is not visible in the vertical tabs that are new with 2.70)

      Delete
  2. @philippe: should work fine, the lastest version from github was developed using the latest release candidate for 2.70

    https://github.com/varkenvarken/spacetree

    ReplyDelete
  3. On Blender 2.70 running SCA Tree Generator 0.2.14, I couldn't find Leaf Size, Leaf Random Size or Leaf Random Rotation is that correct? Or am I missing something?

    ReplyDelete
  4. @victornsy: That is correct, I am afraid this documentation page is a bit behind the developments :-/ The add-on currently works with particle systems for leaves instead of generating the geometry itself. That saves a lot of memory and is more versatile. However, it also means that if you want to change leaf size etc. you have to do that in the particle settings.

    You might check part III of the blog series:

    http://blenderthings.blogspot.nl/2014/03/a-new-tree-addon-part-iii-development.html

    I'll see if I can find the time to update this documentation :-)


    ReplyDelete
  5. I decided to download the free version, to see if I might want the pro version. However, as I tried to follow this quick-start tutorial, I found that "Scale" and "Power" seem to be missing. Am I doing something wrong?

    ReplyDelete
    Replies
    1. @Dustin, they are called Branch diameter and Branch tapering respectively and they are located below the skin options. Apart from the name they should behave exactly like the pro version.

      Delete
  6. I dont see the Power and scale parameters. I am using version 2.1.3. Is there something im missing?

    ReplyDelete
  7. I dont see the skin section either...

    ReplyDelete
  8. @jennifer:

    You need to uncheck the 'no modifiers' checkbox then there will be options for branch tapering and brnach diameter. I've highlighted them in the image below

    https://drive.google.com/open?id=0B6hOxcQKUAvXTHpBbWJLS1BBZUE

    ReplyDelete
  9. This comment has been removed by the author.

    ReplyDelete
  10. Once you click away from a tree, how do you get the generator plugin options back? I've lost several trees by accidently clicking on something else and losing the options

    ReplyDelete
    Replies
    1. This version of spacetree doesn't have persistent properties. this is indeed inconvenient and that is why i did implement them for the commercial version that is available on Blender Market.

      Delete
  11. This comment has been removed by the author.

    ReplyDelete
  12. Hi, I've got a problem in my Blender project: when I click On "Add Mesh > Add tree to the scene" the "SCATree Tool Panel" doesn't appear... I've also tried to press f6 (as some tutorials suggest) but nothing happened... do you know how can I solve this problem?
    Thank you

    ReplyDelete
  13. Hi Fabio,

    after Add>Mesh>Add tree to scene a panel will appear in the toolbox area (if the toolbox area is not visible you should press Ctrl-T).
    Depending on what else is in the toolbox area the SCA Tree panel might be small and near the bottom and you would also have to enlarge it.

    Also please note that these options are not persistent: after you create a tree you can update the options and change your tree as long as the new tree object is selected. If you select something else or switch to edit mode you cannot change the tree any more. (The pro version on https://blendermarket.com/creators/varkenvarken has persistent options)

    Hope this helps,

    regards,

    -- Michel.

    ReplyDelete
  14. Hi, thank you for the free version of your add-on.
    I've been able to set up trees, but once i add meshes in groups for the crown and exclusions, i get a bunch of errors.
    These errors persist even if i go back and disable shaping by groups. They last until i delete and start another tree.
    Please help?
    Attaching a screenshot of the errors, when trying out on the demo file you've provided on this page.

    https://imgur.com/a/0M8cU

    Thanks in advance..!

    ReplyDelete
  15. I think you might be using an old version of the add-on? Going from 2.76 to 2.77 something in the Blender Python API changed. The add-on was updated to fix that and the version on GitHub should be ok but I think I forgot to update the .zip file :-( I'll try and fix that as soon as possible

    ReplyDelete
  16. Thank you for your quick reply!!
    Especially on a thread this old haha... I'm really grateful.
    And the updated version you're talking about, is it the folder within the "src" folder on GirHub?
    "ray_cast fix to support blender 2.76 "

    But it's not in a zip, and try as i might, I could find just no way to download the files ehheh.. >.<

    Maybe I just am not so familiar with GitHub interface, so yeah it's possible the zip I downloaded is just older. (I think i got it from the 4 year old folder as opposed to the 2 year old one. my bad)

    I hope this works, and thank you, the zip uploaded would help me a lot :)

    ReplyDelete
  17. Ah yes. Silly me. I got it to work, your tip helped. I just copied the contents of the ONE .py file that was updated, and replaced my file in
    \AppData\Roaming\Blender Foundation\Blender\2.79\scripts\addons\add_mesh_space_tree__init__.py
    using notepad.

    Haha it works now. Updating the zip would help others, but right now I'm just overjoyed it works! :D :D :D
    Thanks a ton for giving us this wonderful add-on ^_____^
    I'm super grateful :')

    ReplyDelete