TreeForm v1.00 [Release Version] (1/21/97) FREEWARE by Peter Shafer, Copyright 1997. bug reports to: dearmad@europa.com TreeForm's home: www.europa.com/~dearmad TECHNICAL AND OTHER STUFF: For: MORAY modeler program; POLYRAY, Vivid, and POVray raytracers (with CTDS300 used to create the script file). Needs: DOS v3.3+, 256k. Legal: In the spirit of POVray, TreeForm is FREEWARE and can be given away, copied, and distributed for free as much as you want, as long as it is NEVER distributed for any profit or any fee whatsoever either privately or commercially either alone or as part of any compilation! TreeForm seems to run under both win 3.x, and win95 quite happily, if somewhat more slowly than when under DOS. And of course, more memory is required for it under Windows than the measly 256k or so it needs under DOS. INTRODUCTION TreeForm is a freeware utility designed to create recursive shapes in a somewhat tree-like form. It normally outputs two files: a User-Defined Object File (UDO) for direct use with the MORAY modeler, and a .CTD file, which is used by CTDS300 (Connect the Dots System v3.0) to create an include file for either the Polyray, POVray, or Vivid raytracers. The .CTD file can be written in either left- or right-handed coordinates, depending on whether you are going to use your tree-form from MORAY or directly script it into your scene. TreeForm will display either a 2D or simulated 3D image of the tree-form as it "grows." The option is up to you when you run TreeForm. The display output is designed to help you decide if the tree-form you just grew is worth keeping, or if you want to create another for your needs. TreeForm will also link directly to CTDS300 if you wish, thus creating your .INC file for you as well. This is done by running the TreeForm setup file first and telling it where to find your copy of CTDS300. USAGE Setup: "Treeform setup" [ENTER] This will run the subprogram designed to create a simple .INI file for TreeForm to use when auto-linking to CTDS300. Also, with this, you can chose to NOT link all the time to CTDS300 so that you can do whatever CTDS special functions you desire. Either way, it's best to run TreeForm setup at least once to avoid any errors. 2D mode (Fast): "Treeform" [ENTER] Treeform is run simply by executing it with "Treeform" [Enter]. This will default it to the 2D mode of display (as this is fastest). After it prompts you to input a few variables to help define your tree-form, it will draw the form and then save the files you need to render your tree. 3D mode (a little slower): "TreeForm 3d" [ENTER] Merely run TreeForm by entering "Treeform 3d". The 3D mode will draw a dim axis grid so you can better understand how your tree-form will look. Also, below the tree it will draw a "shadow" of the tree-form as if the sun were directly above your tree-form, so you can better understand where the branches actually are. VARIABLES The variables for each tree-form are very easy to understand, but quite numerous, so included are the following descriptions. First, some basic info on scaling your tree-forms: For display purposes, TreeForm now automatically scales the screen to best fit the possible maximum size of your Tree-Form based upon your variable inputs. So think of the variables as just basic units in your raytracer or MORAY, and use them as ratios. All numbers are kept to about 6 digit precision, so you'll have plenty of resolution should you want to scale and stuff in MORAY. Also, note that if you're using MORAY to place your tree-form and scale it, you don't need to worry so much about getting the size of your tree just right through TreeForm, just get the ratios between branch sizes and girth and other things the way you want them, then scale it easily in MORAY. If you're not using MORAY, then CTDS does prefix some handy information in the beginning of it's file created for you regarding your tree-form's size and whatnot. IMPORTANT SCALE NOTE: You would be wise to keep the TreeForm scales small as it works MUCH faster then, due to how I have set up the algorithm to structure the branches. VARIABLE DESCRIPTION Moray: This is an important variable, believe it or not. For some reason I will never be able to fathom, MORAY operates in a right- handed coordinate system while POLYRAY and POVray operate in Left-handed coordinate systems. Read a book on raytracing or math for info on this if you don't know what I mean here. Anyway, the .CTD file needs to be formatted specifically for MORAY, if you are planning on using MORAY to position, scale or texture your tree; if you're a script-writing tracer, then your .CTD file will not need to be formatted that way. This is a flag variable, where 0 = NOT FOR MORAY and 1 = output .CTD file FOR MORAY. When option 0 is chosen, no UDO file is written, as it would be useless. Gravity: To simulate a heavier or lighter gravity, all branches will tend to angle more toward the "ground" or float more toward the "sky." 0 is considered normal gravity, with negative amounts being low gravity and positive numbers being heavier and heavier. Amounts beyond 2 tend to create results not as you would expect, but try them, sometimes, weirdness is precisely what you want. I've found 0.5 gravity to be pretty good at lending weight. Wind: To simulate a wind-blown tree with various strengths of wind, I added this variable. It "blows" the tree-form generally toward one direction. 0 = no wind, negative numbers blow the tree one way and positive numbers the other. Any number is possible, but a range of about -2 to 2 is most realistic, with -1 to 1 being pretty useful actually! Basic Length: This is the basic length of the trunk and branches before they split into others. Each time a split occurs, the length will shorten by a factor: Length Change: The factor to change branch length each time into the recursion. So at a given Recursion (R) level the length would be factored by (Length Change)^(R-1). For example a 0.8 Length Change would make each branch generally 80% as long as the previous. Try numbers above 1, such 1.2 for some interesting effects. When a branch is found to extend less than 1/960th of the trunk's main length, it is pruned there, and not bothered with regardless of the current recursive level the growth is on. Length Random: A three-option variable where you can have the branch length vary from the above set calculation by a certain amount of randomness. 3 = NO RANDOMNESS, 2 = a small amount of randomness, 1 = a great deal of randomness (from .5 to 2 times the length). No randomness sometimes yields interesting African Savannah- like trees, flattened at the top. This is due to how I decided to calculate "length". Obviously I didn't do it using pythagoras' theorem, haha, but I find my cubicle way works better for the purpose of making trees, as I get better results. Basic Girth: This is the basic girth of the tree-form. Enter it as a diameter, NOT a radius. Girth Change: Hey! Just like the Length Change above, only it's for the Girth! Girth Random: Same as Length Random above but for the girth. I find this handy to leave constant mostly, but I include the option for randomness in case someone wants to use it. # of Splits: The number of branches from each splitting point. I've used numbers up to 10 so far with no problems (see Random Splits below); it just takes a loooong time if you have a high recursive level... 3 or 4 branches seem to be really nice. Random Splits: This is a flag to decide if the # of branch splits should be random or not. If they are than at any given splitting point there could be from 1 to "# of Splits" branches. Otherwise there will ALWAYS be a number of splits equal to "# of Splits" above. For this variable: 1=YES make them random, and any other number means it will NOT be random. WARNING: For some strange reason when you decide to have random splits there is an odd bug that causes an "out of memory" error due to a runaway recursion without any output. I have hunted this bug, but with no luck- I gave up; so for now, when you use random splits, just keep your Maximum Recursion at 7, anything above that causes crashes pretty regularly, while at this level it doesn't happen all the time. Branch Angle: This is the angle the branch will split from it's parent. Ranges from 15 to 55 are pretty good, but other odd angles are cool at times. Angle Random: Another flag variable. 1 = random branch angles from 1 degree up to the Branch Angle previously defined. 2 = some randomness, and Any other # = no randomness besides deciding whether the angle is split "left" or "right". That's sorta how this works... Maximum Recursions: This is the "depth" or distance to which a branch will be formed. Each break point is basically considered one level of recursion. This variable affects the overall length of branches, as well as the complexity of the tree-form. Also, the higher the recursion, the larger your tree-form can potentially grow. For now, the limit to this variable is 24. TreeForm Name: Enter the name of your declared object so your raytracer script can make references to it. The name can be up to 15 characters long. It defaults to "tree". If you are not writing a UDO file, then the .INC file created by CTDS300 if you auto-link to that will match the .CTD file's #, not the .UDO's file number which would be more usual. So it would be: TREE#.CTD and TREE#.INC, otherwise it would be TREE#.CTD, and TREE##.UDO and TREE##.INC. If this makes no sense, don't worry about it, everything works! :) SOME EXAMPLE FORMS Although the innate randomness built into TreeForm precludes my being able to give you numbers that will always create certain interesting shapes, I will give you some basics for tree-forms which will eventually yield some decent results. The variables are in the order TreeForm will ask you for them: 0 0 0 0 !MORAY variable 0=no, 1=yes. !change this if you need to. 0 0 .5 0 !gravity 0 0 1 0 !wind .3 .36 .28 .24 !base length .04 .16 .018 .04 !base girth .8 .9 .95 .5 !shrink rate length .9 .8 .9 .5 !shrink rate girth 1 1 2 2 !randomness of length 2 1 2 2 !randomness of girth 3 5 7 3 !maximum splits 0 1 1 0 !splits random? 45 45 20 90 !angle of splits 1 1 1 2 !angle random? 6 7 7 4 !maximum recursiveness [] [] [] [] !The name of your object. The last one is pretty weird! There are some VERY strange possibilities you can try! THE DISPLAY The display while your tree is being "grown" will show your tree in white along with some numbers, in 3D mode you will also see a blue grid and gray shadow (in 3D mode). The numbers in 2D mode are the coordinates for those minimum and maximum positions, just so you can get an idea as to how large or small your tree-form actually is in units. In 3D mode they are the tick scale for the grid. LIMITS Recursion: Artificially limited to 24 for right now. I may increase this if there are pleas for it, but heck, 24 levels is a lot! Most REAL trees recurse their form to about a perceived limit of 7 or 8 at most! If we exclude the "leaf" level. Also note that a Recursion level of 7 is for some reason a safer maximum when using random numbers of splits rather than constant amounts... for SOME reason... This bug is very elusive. Other than that, there are no limits I'm aware of yet- but I haven't been too keen in waiting the time it takes my little P100 to create a recursion 18 tree with 10 branch splits and a .95 shrink factor... just not interested... :) NOTES ON MORAY and UDO's Lutz has recently released a 2.5 version of Moray which I have not bothered to get yet. I noticed the UDO in 2.5 adds some features, but otherwise seems backward compatible for the format of UDO I use here. Any bugs, tell me about them. Also, don't be afraid to include lots of recursion (up to 24 levels for now in TreeForm) because the UDO object would then have too many edges to manipulate with any decent speed in MORAY; this is not so- TreeForm only follows the recursion up to the 5th level for the UDO display code in MORAY, so you're tree-thing will display fast. Just remember that the tree extends beyond the limbs shown in when you're editing through MORAY. Don't worry, the CTDS object follows your recursion the whole darn way... although I've noticed some odd problems with certain raytracers and CTDS objects that get too large... For practical reasons, I've found a recursion level of about 10 to be a maximum desired amount of detail. NOTES ON STRANGE THINGS For some strange effects, try making the Main Length about 1/10th of the girth, and you get this strange bubbly tree. Or try a wind of 10! (wacky flattened trees), or gravity of -10 or 10, or try an angle of branch splitting at 179 degrees and make the angles NOT random... there are a lot of possibilities for some interesting tree-forms. NOTES ON POSSIBLE FUTURE ENHANCEMENTS For any future releases I MAY be including some, none, or all of the following: 1) A more free-form development of the shape so shapes such as plasma-blasts like in the glass bubbles, or whatever could be made. Also, perhaps a more random branch-length should be accomplished. With additional variables, pine- like trees would be easier to accomplish. I don't know... just some random thoughts here. 2) When you have a LOT of branches, you may notice some of them growing into and even through each other. I did not want to bother coding any simultaneous vector checking algebra to make sure no lines intersected. I just didn't want too! So NYAH! It really would slow down the tree creation checking some 2000 equations toward the end of some trees with each branch created! But maybe in the final release... 3) Leaves: A separate pre-defined shape (made by you and already in it's own include file) that could be added throughout the growth of the tree-form, growing to a certain density of occurrence (you decide) and generally more dense at it proceeds to the outer limbs. With one usually at the end of all limbs; simulating leaves (or whatever). I'm not sure how to get CTDS300 to cooperate about this, and I'm not that interested in writing Raytracer-specific output, as I find CTDS handier. Any bugs should be reported to: dearmad@europa.com HISTORY v0.9: (1/17/97) Initial public release. (Beta). v0.95: (1/18/97) Second release of the beta, found some stupid bugs on my own and fixed them. Hopefully no one downloaded the 0.9 version! Was not disconnecting branches in the CTD file correctly due to the way it exited the branching routine without cleaning up a flag variable. Fixed! The counting variable was misplaced in another exiting routine, causing who-knows- what problems. Tough one to fix, but fixed! v1.0: (1/20/97) First true release: all envisioned features included. Added direct-linking to CTDS300 via an .INI file and all the file management that this entailed. Added routine to create .INI file. Added ability to name the tree object. Added exit information so user will know what files TreeForm wrote, as sometimes they will not have the same suffix # attached. Also added messages to generally inform user as to what is going on in regards to output. Added ability to NOT save a tree once it formed, so no extra files will need to be tracked down and deleted by user. Added auto-scaling feature. With this, the view screen will be automatically scaled to fit the tree-form's maximum size. Line which flagged unfinished branch split points had bad logic operator. Noticed during 2-branch constructions. FIXED! v1.0a (2/12/97) Fixed user noticed typo in the SETUP routine where POLYRAY and POLYray were printed, rather than POLYRAY and POVray... this naturally caused some confusion. Now it's easier to tell what to select for POVray format. :) No change in display of version number in program.