                          FracTree V1.0
                                 
                            G. Bissell
                             
                             Contents
                                 
What is FracTree?                                     1
System Requirements                                   2
File List                                             3
Using FracTree                                        4
Rendering Trees with PovRay                           7
Examples                                              9
Thanks, and Hello's                                  11
Known Bugs, Limitations and Wish List                12
Legal Stuff                                          13

                         
1                       
                         What is FracTree?

FracTree is a program which creates fractal trees for use with the
PovRay raytracer, it conforms to the Version 2 standard of the
language.
The program is an MS-DOS executable designed to be run at the MS-
DOS prompt, though it is compatible with batch files.

FracTree is only a small package and as such asking a Shareware
fee for it is probably a bit of a cheek. However I would be more
than happy to accept donations (who wouldn't), just e-mail me for
my address. I can always hope can't I!

I can be contacted at:

gbissell@coventry.ac.uk

I am not sure wether that mail address will continue after Jun
1996.

If you have any problems don't  hesitate to mail me. I can't
guarantee a quick response but I will try to help anyone that
mails.


2
                        System Requirements

Processor : 286 or better
Memory    : 640k
Video Display  : VGA or better
Hard Disk : XXX for installation

FracTree runs in Real Mode with 286 instructions, and has 80X87
emulation. This means that the program will run on any machine
with a 286 or greater, with or without the presence of an FPU.
The program outputs trees to disk as it creates them, for this
reason it does not require a large memory area and will run with
only Base memory. Because of this even a 640k 286 with no
Extended/Expanded memory should have no memory problems running
FracTree.
Note that even simple tree files, such as the default (see next
section), can require over 100k of disk space. It is therefore
recommended that you run FracTree from a hard disk if you plan to
create complicated trees.
FracTree gives a simple graphical display to give the user an idea
of the form of the tree being created. It does this in mode MCGA
(320x200, 256 colour mode). This mode is available on all VGA
graphics cards and supported on every Super VGA card I have ever
used.


3
                             File List

Firstly you should have unzipped FracTree into it's own directory,
using the -d option.
You should have the following files:

FRACTREE.EXE   FracTree executable
FRACTREE.DOC   Word 6.0 version of this document
FRACTREE.TXT   This ASCII version of the document
README.1ST     Basic info
FILE_ID.DIZ    Simple program description
EXAMPLES       <DIR>

Contents of EXAMPLES directory:

TREEDEFL.INI   Default FracTree INI file
TREEDEFL.POV   Default PovRay file
TREEDEFL.GIF   Default Tree                            - 320x200x256 image

TREEDMF.INI    DMFWood4 FracTree INI file
TREEDMF.POV    DMFWood4 PovRay file
TREEDMF.GIF    DMFWood4 Tree                           - 320x200x256 image

TREELEAF.INI   Own Leaf FracTree INI file
SMILEY.GIF     Texture map, required by TREELEAF.POV   - 320x200x256 image
TREELEAF.POV   Own Leaf PovRay file
TREELEAF.GIF   Own Leaf Tree                           - 320x200x256 image

SCAPE.GIF      Example scene                           - 320x200x256 image
                          
                          
4                          
                          Using FracTree

Descriptors

FracTree is a very simple program to use. The only command line
parameter it takes is the name of an INI file to describe the tree
to output.
If no file name is given then the program uses its built in
defaults to output the tree.

The structure of an INI file may look a little daunting at first
but is actually quite simple. It can contain as many, or as few,
of the descriptors for the tree (missing descriptors are set to
the defaults) and can be in any order in the file.

Listed below is the file TREEDEFL.INI, it is actually a redundant
file as all of its descriptors are set to the programs defaults. I
shall however use it to explain the function of each of the
descriptors.

# FracTree ini file : TreeDefl.ini
#
# Outputs a tree identical to the default (no ini file specified)
#
# Output file name
file=treedefl.inc
# Object name
name=Tree1
# Start length
startlength=0.35
# Stop length
stoplength=0.03
# Thickness factor of a branch
thickness=1.0
# Maximum reduction factor
maxfactor=1.6
# Minimum reduction factor
minfactor=1.3
# Random seed
random=301275
# Number of branches at each node
branches=3
# Maximum angle between branches (degrees)
maxangle=90
# Minimum angle between two branches (degrees)
minangle=40
# Object to use for leaves, a predefined leaf (fractreeleaf) or a personally
# defined leaf (should be centered at the origin and approximately of unit
# length
leafobject=fractreeleaf
# Texture of branches
branchtexture=pigment { color Brown }
# Texture of leaves
leaftexture=pigment { color Green }

Firstly the character # tells the program that the rest of the
line is a comment and should be ignored.

These are the descriptors:

file=string
This specifies the file name to call the output tree, treedefl.inc
being the default. A name with a directory position is allowed,
e.g. c:\povray\mytree.inc

name=string
This specifies the object name to call the output tree. This is
the identifier that you will use in your PovRay files. The default
is Tree1, which would be used as object{Tree1} in PovRay. Note
that the case is important for this descriptor.

startlength=realnumber
This value is the length of the initial trunk of the tree, draw on
the positive y axis. A larger value will create a larger tree. The
default is 0.35, which with the stoplength and reduction factors
(see below) creates a tree that fits approximately into a unit
square. In other words the default tree is approximately 1 unit
tall, wide and deep.

stoplength=realnumber
This value is the branch length that, when reached, will indicate
to FracTree to end the branch with a leaf. A smaller value will
create a more complicated tree, as more reductions are required to
reach the smaller value. The default is 0.03, approximately 1/12th
of the start length.

thickness=realnumber
The thickness value allows the width of the branches to be
altered, with larger values giving wider branches. The default
value of 1.0 gives a well proportioned tree with a good branch
length to branch width ratio.

maxfactor=realnumber
minfactor=realnumber
These two values are very closely related, and as such will be
described together. When a new branch is created the current
length is divided by the reduction factor to make a shorter
branch. This reduction factor is a random number chosen to be
between these two values.
The defaults 1.6 and 1.3 respectively give a good fall off in the
length of the branches.
The closer the two values the less random difference there will be
in the reduction of each branch, e.g. 1.4 and 1.4 will mean that a
new branch is always 1/1.4 of the length of the previous.
Larger values will result in fewer branches, due to the fact the
branch length will reach the stoplength more quickly.
Warning:
The reduction factors must always be greater than 1.0.
Beware also of using reduction factors close to 1.0. More branches
will need to be created to reach the stoplength, which can result
in huge tree files.

random=integernumber
The random value allows the user to reproduce a tree exactly as
before. With the same descriptors and random seed FracTree will
always produce the same tree. By changing the random value
different trees with the same lengths and reduction factors can be
created.

branches=integernumber
At each fork in the tree a number of new branches at different
angles are created. This value allows the user to set how many
branches are created at each fork.
Note that as the length of a branch approaches the stoplength
FracTree reduces the number of branches created at each fork. This
is performed when the current length is likely to reach the
stoplength within the next few created branches (estimated using
the reduction factors).
If the reduction factors are large in comparison to the difference
between the startlength and stoplength then the branches
descriptor may seem to have no effect. This can be observed in the
TREELEAF.INI file (see example's section). Because of the larger
maxfactor the number of branches will always start at 2,
regardless of the setting of the branches descriptor.

maxangle=realnumber
minangle=realnumber
As with the reduction factors these two values are closely
related, as such they will be discussed together.
When a set of new branches are created at a fork they are given an
angle within the range of maxangle.
Obviously the larger the value the more the new branch can deviate
from the branch to which it is connected. Using very large values,
such as 270 can often yield trees that look more like bushes.
The minangle value is the minimum angle that two branches may
differ. Smaller values will allow the branches to group together,
whereas larger values will create trees that are more spread out.
Note that the angles are in degrees.

leafobject=string
The leafobject is the PovRay object that will be used for the
leaves at the end of branches.
The keyword fractreeleaf tells FracTree to use its own built in
leaf object. You should never need to use this if you wanted to
use the default leaf as you would just omit the leafobject line
from your INI file, or comment it out. It is present so that if
someone else wrote another program, written to output INI files it
would not have to worry about removing or commenting out the line,
it could just substitute the fractreeleaf string for the object.
If your own object name is placed in this field it must be defined
in the PovRay file used to render the tree, an example of this is
in the next section.

branchtexture=string
The branchtexture controls the texture used for the branches in
PovRay. The line must consist of a valid PovRay texture, which
will need to be included in the PovRay file for rendering.
An example of changing the textures is in the next section.

leaftexture=string
The leaftexture controls the texture used for the leaves in
PovRay. The same rules apply to the leaftexture as to the
branchtexture.

Note that the case of the descriptor fields is important, they
must be in lower case.

Using an INI File

To use an INI file with FracTree simply specify it in the command
line as mentioned previously.

e.g. To use the default INI file you would type

FRACTREE TREEDEFL.INI

FracTree attempts to read the INI file and then, after a keypress
will display and output the created tree.
The image at the top left of the screen is a plan view of the
tree, the bottom two images are the front and side views (left to
right).
Pressing a key exits FracTree, the created tree file should now be
in the directory specified. In the above example there should now
be a file TREEDEFL.INC in the current directory.

If FracTree cannot find the specified INI file it will result with
an error.
If FracTree finds a field in the INI file it does not know it will
halt with an error, and display the read field that it did not
understand.
Remember that the order of fields in an INI file is not important,
you can even have multiple definitions of the same descriptor, the
last read value will be used.
                    
                    
7                    
                    Rendering Trees with PovRay

To render FracTree include file you will need PovRay V2, and as
much memory as you can get your hands on!
Even small tree files tend to use a lot of memory in PovRay. With
8Mb of memory, a swap file, created with POVMOD.EXE will probably
be necessary.

Supplied INI Files

There are three example INI files in the FracTree package, each of
these files has a corresponding POV file.
The files are:

TREEDEFL.INI / TREEDEFL.POV
This is the default tree output by FracTree, as mentioned earlier
the INI for this default tree is not required, FracTree with no
INI file will produce the same tree.

TREEDMF.INI / TREEDMF.POV
This is the same tree as the default but with the DMFWood4 texture
for the branches and a shiny finish added to the leaves. The only
differences in the POV file from the previous are the inclusion of
the textures.inc (part of the PovRay package) and the change in
file name to include.

TREELEAF.INI / TREELEAF.POV
This INI file creates a less complex tree and sets the leaf object
to an object called MyLeaf. This object is defined in the POV
file, a large sphere which requires the file SMILEY.GIF (part of
the FracTree package).

All of the example POV files have a chequered floor, simply to
give the image an impression of depth, rather than having a tree
floating in space.
The light position and camera position were all chosen by trial
and error, trying to get an image that looked reasonable. If a
larger tree was used then the light and camera would have to be
changed accordingly.
For all of the above INI files the object name of the tree was
Tree1. Obviously different tree names would be required if more
than one type of tree were to be used in one scene.

Notes

Remember that the INI files are not the tree files for PovRay, you
must run FracTree with the INI file to produce an INC file for
PovRay to render.

Once the tree file has been included with the #include
"FILENAME.INC" command the tree must be placed using object
{Treeobjectname}.
The base of the trunk always starts at the origin, so any
rotation/scaling will be performed around the bottom of your tree.

When you create you own leaf object a normal size would be
somewhere around 1 unit in size. The default FracTree leaf is just
a scaled sphere:

sphere { < 0, 1, 0 >, 1 scale < 1, 2, 0.5 >  }

Note that this `leaf' is stretched in the Y axis. Your own leaves
should have their spine along the Y axis otherwise they may end up
attached by their middle, at odd angles to the last branch.
You do not need to change your leaf definition if you decide to
make a bigger tree, FracTree scales the leaves as it creates the
tree. However it may be a better idea to create all your trees
based on the 1 unit scale and then scale them to your required
size in PovRay. This is actually closer to the Quadrics method
that most of PovRay's primitives are based upon.
                             
                             
9                             
                             Examples

The example GIF files in this package, included in this document,
have all been dithered to 256 colours and are of a fairly low
resolution. They are simply intended to give an idea of what is
possible, not as an example of image quality.

Default

This is an example of the tree created by rendering the
TREEDEFL.INC file using the TREEDEFL.POV file.

  See TREEDEFL.GIF                                

DMFWood4

This is an example of the tree created by rendering the
TREEDMF.INC file using the TREEDMF.POV file.

  See TREEDMF.GIF                               

Own Leaf

This is an example of the tree created by rendering the
TREELEAF.INC file using the TREELEAF.POV file.
                                 
  See TREELEAF.GIF                                 

Landscape

Finally an example of what can be achieved with a few different
trees, a height field and some fog!
Though it is up to you to create the art, I'm a mediocre
programmer, and a poor artist ;)

  See SCAPE.GIF
                                 

11
                        Thanks, and Hello's

Firstly I must thank the POV-Team, and everyone who has
contributed to making it an excellent raytracer.

Thanks also to the people who have shown interest in this package.
Without them I would have never bothered to get this program into
an at least reasonably user friendly form.

Hello's to all the guy's I used to write games/utils/generally
cause trouble with at my old high school and college. Namely...

Edgey
Moz
Si
Suv
Andy
Tim, now `The Ginger-Head Man', why, I don't know. I don't want to
know!
Rob
Tubba


12
               Known Bugs, Limitations and Wish List

I wrote FracTree a long time ago, in those days it output trees
for Alexander Enzmann's PolyRay package. If I get a positive
response from people about FracTree I may add PolyRay support, and
possibly support for 3d Studio.

The completion of this version has been somewhat rushed because of
various people interested in copies. For this reason there are
probably many bugs lurking that I haven't found.

Of the problems the unstability of the file I/O is probably the
biggest cause for concern. The reading of the INI files is quite
strict and can lock up if faced with something it doesn't like.

As mentioned earlier FracTree lowers the number of branches
created as it nears the stoplength. This can sometimes be a little
confusing, with the program seeming to ignore the branches setting
in an INI file.

At the moment it seems that two leaves are output at the end of
branches, whilst this looks good for a `proper' tree it
complicates an image when a novelty effect is desired. The
TREELEAF.GIF file shows this, with the spheres cutting into one
another.

When creating a set of branches at a fork the minangle setting
only compares the current branch with the previously created
branch. For this reason two branches can be drawn, the correct
angle apart, and the third can go straight through the first
branch, as it is being compared with the second.

If a large minangle is used the program can have difficulty
`finding' an angle large enough and can slow down considerably.
The random routines that control these functions need to be re-
written.

When creating a tree FracTree makes two temporary files (temp1.$$$
and temp2.$$$) which it leaves on the current directory. These
files should be deleted by FracTree when it exits, in this version
however it does not.


13
                            Legal Stuff

It is unfortunate that this section has to be here at all, but
there's always someone out there determined to cause trouble.

COPYRIGHT

The executable code in this package may not be dissassembled,
hacked or modified in any way.
The documention may not be modified for distribution, though
editing for personal printing/viewing is permitted.
The three example INI files can, and are intended, to be modified
and used as a basis for new trees.
The three example POV files can be modified as above.
The three example tree GIF images are 256 colour dithered outputs
from PovRay using the POV and INC files. As such they are intended
to be reproduced by the user as test images and can be modified
and distributed as desired.
The texture file SMILEY.GIF, used by TREELEAF.POV may be modified
and distributed as desired.
The example image file SCAPE.GIF may not be modified, reproduced
or distributed in any other format than that of its original
status without my permission. Given the intended purpose for the
image I would be happy to supply a high resolution 24Bit version.
The POV/INI/INC files for this scene are not part of the package
and will not be released.

DISTRIBUTION

This package must be distributed in it's original zip form
FRACTREE.ZIP.
If stored on a system which allows more than 8 characters in a
file name, renaming of the file to indicate the version number is
permitted. For instance FRACTREEV1_0.ZIP.
No fee, other than the cost of media used to distribute this
package is permitted. This price must be reasonable, 5 pounds
sterling per floppy is considered an upper limit.
The distribution of your own INI files is something I would
encourage, though not as part of the FracTree package.

DISCLAIMER

This software, its documentation and example files are provided as
is without any guarantees or warranty as to their reliability or
accuracy.
I am not responsible for any damage or losses of any kind caused
by the use or misuse of the package.


                                 

                                 
