Splinetree Version 1
(c) Andrew Clinton '2000

------------------------------------------------------------------
1. Introduction

Splinetree is a Pov-Ray include file for Pov-Ray 3.1 (or above) that will create smooth, splinar trees.  The generation of a tree is controlled by several parameters which are explained below.  You should have the following files:

splinetree.inc				- The main include file
example1.pov -> example7.pov		- Example files
leafdefs.inc				- Contains preset leaf objects
maple1.tga -> maple3.tga		- image_map files with alpha channels
fallmaple1.tga -> fallmaple3.tga	- image_map files with alpha channels
pinkpetal.tga				- image_map file with alpha channel
readme.txt				- this file


For a quick start, just open the "example1.pov" file and hit render.  You should get a simple splinar tree.  All the variable descriptions are found below, so if you need to look something up just look here.

About 10-30 seconds of parsing time should be expected for the example trees.  The render and parse time on my machine are also shown in the example file headers.  Be warned that increasing the recursionmax or divisions variables can cause huge slowdowns and large increases in the complexity of the tree.

I recommend that you use the Mosaic Preview command (+SP64) to get a aliased preview of the tree before doing a final render.  Type +SP64 into your command line to use this.

Have fun, and let me know if you have any questions!

Andrew Clinton
ajclinto@engmail.uwaterloo.ca
http://povplace.addr.com/

------------------------------------------------------------------
2. Usage

To use the tree macro you must include the splinetree.inc file in your scene file.  If you wish to use the predefined leaves or bark texture you also need to include leafdefs.inc.  Place these lines in your code before declaring any variables:

#include "splinetree.inc"
#include "leafdefs.inc"

The majority of the variables must be initialized before calling the macro.  Look at "example1.pov" for examples of variable declarations.  Full descriptions are in section 3.

The macro can be called using the line:

splinetree(0,0)

The above command is usually all that is necessary, but the parameters may be changed if required.  There should be 2 entries, and generally they may be left as 0.

i.  The first parameter allows you to start building the tree from a higher initial recursion level.  For example, a value of 1 would begin tree creation from a major branch rather than from the trunk.  In this way, you may limit the amount of tree that is generated.  Regardless, the tree will still grow from the origin.

ii.  The second parameter allows you to give the trunk spline an initial slope.  The value is in degrees from the vertical.

If you are using MegaPov 0.4 or higher with splinetree, the scene will parse faster if you include the standard #version unofficial MegaPov 0.n; directive in your scene file and in the splinetree.inc file.


------------------------------------------------------------------
3. Variable Descriptions


Note on Exponential Interpolation
---------------------------------

Many of the variables that follow may be initialized in 2 ways.  They may be defined using the initialization macro, which accepts a start and end value and interpolates between them exponentially using the given base, or they may be specified using an array as was done in previous versions.  Below is the method you should use to initialize the variable using the exponential interpolation macro:

 init_<variable_name> (start_val, end_val, base)

 Example:

 init_branchl (3, 0.1, 0.5)

This will cause the tree to have a trunk of length 3, and end branches of length 0.1.  The base defines how the variable is interpolated at branches in between.  A base of 1 causes the variable to change linearly, bases lower than 1 cause the variable to decay exponentially.  In the example above, the branches would quickly decrease in length at the first few levels in the tree, then they would level off in upper branches without considerable changes in length.

The following macros use exponential interpolation:
 init_div
 init_branchl
 init_branchw
 init_tdev
 init_rdev
 init_twigprob
The following work differently:
 init_roots
 init_splinedev
 init_simplify


Main Variables
--------------

 #declare recursionmax = n;

Recursionmax defines the maximum number of recursion levels that will be used in the tree.   The trunk is level 0, major branches are level 1, and minor branches are level 2.  The end branches are at the recursionmax level.  In general, recursionmax is the number of times a branch will "split" before it reaches an end point.  Generally a value in the range of 4 to 7 is great.

 init_rand (structure_seed, root_seed, leaf_seed)

init_rand initializes the random number generator, which randomizes trees created.  The first seed is used for branch generation, the second is for roots, and the third is for leaf placement.  In this way, the random numbers used are separate (so the leaves may be removed without changing the tree structure).  If you don't like the first tree you generate, you can just change the first entry and you'll get a completely different structure.


Variables for Branching
-----------------------

 init_div (start_val, end_val, base)
  or
 #declare divisions = array[n] {d1,d2,...,dn}

This variable defines the number of branches that the tree will split into at each recursion level.  Use either init_div or declare the array yourself.  If you choose to declare the array, be sure to specify a number for each recursion level.


 init_tdev (start_val, end_val, base)

The translational deviance for each new branch created.  This variable controls how much randomness will there be in the positioning of each branch on its parent branch. Each value is given as a decimal indicating the maximum percentage of the total length of the parent branch that the new branch may be translated.  Values of 0.5 to 0.9 are generally good.


 init_rdev (start_val, end_val, base)

The rotational deviance.  This variable defines the maximum angle in degrees that a branch should make with its parent branch at each level.  The minimun angle will be half this. It is usually best to start with larger rotations, then decrease to smaller values.


Twigs
-----

 init_twigprob (start_val, end_val, base)

Defines the probability that a twig will appear on each level of branch.  With high probabilities, it is possible to get more than one twig per branch.  Choose a value between 0 and 1 (1 being the highest probability)


Branch Sizes
------------

 init_branchl (start_val, end_val, base)

Branch length.  Defines how long the branches will be in pov-units.  


 init_branchw (start_val, end_val, base)

Branch width.  Defines how wide the branches will be in pov-units.


Roots
-----

 init_roots (root_recursion)

This macro sets the number of recursion levels to be used for the root generation.


Gnarledness
-----------

 init_splinedev (min_val, max_val)

This variable defines the percentage deviance of the spline from a straight line.  A value of 0 is straight, while 1 is extremely warped.  Values between 0.1 and 0.3 usually give good results.  min_val is used at the low and high levels of the tree and max_val is used in the middle.  Other values are linearly interpolated.


Simplify to Cones/Sphere
------------------------

 init_simplify (num_simplify_levels, num_segments)
  or
 #declare simplify = array[r+1] {d1,d2,...,dr+1}

simplify allows you to revert to simplified (cone/sphere) branches at recursion levels of your choice.  The first parameter in init_simplify should be the number of levels you wish to simplify.  The second should be how many segments will be used in the simplified branches.  Ex. init_simplify (2,2) simplifies the last 2 levels, and uses 2 segments in creating the branches.


Variables Controlling Leaf Generation
-------------------------------------

#declare leafarray = array[n] {leaf1,leaf2,...,leafn}

Put all your leaf identifiers into this array.  The pre-set leaves are found in the leafdefs.inc file.  Just the #declared name is necessary.  If you don't want leaves on the tree, it is not necessary to include this.


#declare leafprob = array[n] {p1,p2,...,pn}

Defines the probability that each of the leaves in the above array will appear on any given endpoint.  You can use any values, provided their sum is not more than 1.  If the sum of these values is less than 1, some branches will be left without leaves.


#declare leafscale = array[n] {s1,s2,...,sn};

Defines the scale factor for each different leaf.  splinetree will provide some slight random scaling.


#declare leafnoise = array[n] {r1,r2,...,rn}

Defines how much random rotation is needed for each leaf.  A value of 0 gives no random rotations, while a value of 1 gives maximum rotation.  You can also provide a value of -1 to force the leaf to hang vertically, regardless of the orientation of the branch it grows from.


Feedback Variable
-----------------

#declare feedback = feedback_levels;

Indicate how many levels of feedback you would like in the message stream.  If you don't want feedback, supply 0 or delete the variable.


Branch Tendancy
---------------

#declare tendancy = <vector>

This variable defines in which direction the tree will tend to grow.  If you wish your branches to be pulled in some direction, supply that direction in the tendancy vector.  Values from 0 to 0.5 usually give decent results.  You can supply something larger but there is no guarantee that it will look good.

Global Transformation
---------------------

#declare global_transformation = transform {
	scale ...
	rotate ...
	translate ...
}

If you want to transform the tree, it is faster and more memory-efficient to supply the transformation in the global_transformation variable than to put the tree in a union and move it.


------------------------------------------------------------------
4. Misc

i. Making your own leaves

Leaf objects should be 1 unit in size.  The stem should come from the origin, and extend in the +y direction (or whatever direction you wish the leaf to be oriented with respect to a vertical stem).  You then need to place your leaf names into the leafarray variable, and specify the probabilities for each leaf to appear.

You are not limited to leaves, maybe try putting flowers/fruit/whatever on the tree - it is up to you.

ii. Branch texture

A texture called "branchtexture" must be defined before initiating the macro.  The texture should be aligned for placement on a vertical branch.

------------------------------------------------------------------

That's it - Enjoy!

