Parameter customizer

[samipfjo]

It's done! Full customizer GUI, including saving and loading to/from parameter files. The UX could be improved a bit with better label names, although I took the liberty of changing a few of them.

[friggog]

A few bugs I've found (also general ideas that don't need to be done anytime soon but just put down as I thought of them)

• Auto-fill from file list contains 'Custom' which gives an error if selected
• 'Tree Param' is also in that list but probably shouldn't exist at all, also throws an error
• Tropism parameter limits are wrong (maybe others too - see Appendix C of https://chewitt.me/Papers/CTH-Dissertation-2017.pdf)
• When loading parameters from file for the custom interface parameters are not reset to default when loading another tree. e.g. load bamboo and trunk count gets set to 50, load another tree afterwards and trunk count remains at 50
• For the array parameters (e.g. branches) the number of parameters needs to match the number of levels (not always 4). In practice more than 4 levels is basically never needed so it might be easier to limit levels to 4 for custom trees and hardcode the array parameters as you have done.
• I would move 'Tropism' to the box above and 'Base size' to be with the other array parameters
• Could potentially have a 'global parameter' box and 'array parameter' box rather than the current three, not sure of the best way to logically break up the parameters. Not a big deal really.
• Some parameter names can definitely be improved, I'll have to refresh my memory and get back to you (e.g. 'Flare' should probably be 'Trunk Flare')
• Not sure if possible but informative tooltips for each parameter would be amazing
• It might be worth just removing the L-system bits completely, it really doesn't add much
• There are LOADS of 'magic values' for parameters (see Appendix C), I'm not sure if we can work out a way to deal with these better, or if it's best to just have a good explanation somewhere on the repo, basically translate Appendix C into a markup README or something

Sorry for the long list, I've bolded what I think are more 'bugs' that probably need to be fixed for a merge, other stuff is just nice extras which we can deal with in the future!

[friggog]

I think that was what I was initially expecting but i definitely agree in it looking a bit scary to new users... maybe removing the first drop down but keeping to load preset section separate and at the top so it is distinct from all the complicated controls?

[friggog]

Have done a bit of work on this, think I have a good solution regarding UX. Here's a TODO list:

• Split into panels and remove LSystems functionality
• Remove Tree Param from list
• Remove LSystems code properly
• Tropism parameter fix
• Better customisation layout - improved, probably still changes to make
• Parameter load bugs
• Level limit
• Pruning is broken
• Load aspen parameters on init
• Can replace floor splits with branches[0] ?
• Results for same seed aren't consistent - they are but 0 is 'random seed', I've set default to one and will add description saying this
• Parameter names/tooltips
• Some params have option for level 0 that may not do anything
• Instructions doc/wiki

Not ideal to be working on the same branch but this way everything is contained in this PR.

[samipfjo]

Thanks for taking the initiative on moving forward with the changes. My life went to hell in various ways over the past couple of months, which has had me in varying states of disfunction. Funnily enough, I added working on this PR to my to-do list for the next week just this morning.

Let me know if there's any particular task you would like me to tackle; at this point I'm losing the trees for the forest (pun fully intended).

[friggog]

I'm just glad to have a bit of time to get back into this project - have forgotten writing most of this code... some of it isn't that bad! I've managed to fix up most of the outright problems and neatened things up. Currently the default tree is a right mess - not sure if the best thing is to update the defaults for all the parameters or to try and set the tree type and load the parameters at startup.

I'm happy to do the parameter names and descriptions as I have a pretty good knowledge having coded the generator itself. I'll also convert my descriptions from latex into a markdown wiki doc or something though this can be a longer term project.

Once that's all done (and with some testing) I think it's pretty much ready for a proper release!

Edit: only other thing to consider is animation using armatures, I think the way the curves are built should lend itself to armatures fairly well but it will probably be a significant amount of work to implement

[friggog]

Ok I'm pretty happy with everything, only remaining problem is that some params have option for level 0 that don't do anything. I don't know if we can/it's worth having some of the branch parameters with 4 levels and some with 3 without the layout going weird and it breaking parameter indices... Might be best just to leave as is.

It would be great if you could give everything a test and check you can't find any problems. I might have a crack at armatures and animation soonish (any input welcome!). Otherwise, as long as your testing doesn't find anything, I'm happy to merge this and post the add-on on some forums and see if people want to use it!

[friggog]

Leaf bend was making things look worse in my view (I don't think I ever got the implementation quite right...) so I have simplified it.
Also found another bug with the parameter limits

[samipfjo]

I really dig the new options layout; nice work! There are still some kinks, but I think the addon's almost ready for prime time after we take care of the ones I've found today.

The one thing I'd like to see added before prime time is a little bit of documentation. I'll copy the parameter descriptions you've given over into the README file as a bare-minimum. I think that would honestly be good enough for launch.

[friggog]

Yeah having the description in the README is a good start in terms of documentation, I'd like to have some visual descriptions of the different parameter effects ultimately but that will take some time to do...

Nice one picking up those issues, let me know when you're happy with everything/if there are any other issues you want to discuss!

If it helps this is the original descriptions (in LaTeX) that I copied those from:

\subsubsection{shape}
Integer 0--8, controls shape of the tree by altering the first level branch length. Predefined options conical, spherical, hemispherical, cylindrical, tapered cylindrical, flame, inverse conical, tend flame and custom respectively. Custom uses the envelope defined by the \textbf{prune\_*} parameters to control the tree shape directly rather than through pruning.
\subsubsection{g\_scale}
Float $>0$, scale of the entire tree.
\subsubsection{g\_scale\_v}
Float, maximum variation in \textbf{g\_scale}.
\subsubsection{levels}
Integer $>0$, number of levels of branching, typically 3 or 4.
\subsubsection{ratio}
Float $>0$, ratio of the stem length to radius.
\subsubsection{ratio\_power}
Float, how drastically the branch radius is reduced between levels.
\subsubsection{flare}
Float, by how much the radius of the base of the trunk increases.
\subsubsection{floor\_splits}
Integer $\ge0$, number of stems of the tree coming from the floor. See bamboo, Figure~\ref{fig:bamboo}.
\subsubsection{base\_splits}
Integer, number of splits at base height on trunk, if negative then the number of splits will be randomly chosen up to a maximum of $\abs{\mathbf{base\_splits}}$.
\subsubsection{base\_size[n]}
Float $\ge0$, proportion of branch on which no child branches/leaves are spawned.
\subsubsection{down\_angle[n]}
Float, controls the angle of the direction of a child branch (at level $n$) away from that of its parent (at level $n-1$).
\subsubsection{down\_angle\_v[n]}
Float, maximum variation in down angle \textbf{down\_angle[n]}, if $<0$ then the value of \textbf{down\_angle\_v[n]} is distributed along the parent stem.
\subsubsection{rotate[n]}
Float, angle about the parent branch (at level $n-1$) between each child branch. If $<0$ then child branches are directed \textbf{rotate[n]} degrees away from the downward direction in their parent local basis. For fanned branches, the fan will spread a total angle of \textbf{rotate[n]} and for whorled branches, each whorl will rotate by \textbf{rotate[n]}.
\subsubsection{rotate\_v[n]}
Float, maximum variation in \textbf{rotate[n]}. For fanned and whorled branches, each branch will vary in angle by \textbf{rotate\_v[n]}.
\subsubsection{branches[n]}
Integer $>0$, the maximum number of child branches at level $n$ on each parent stem.
\subsubsection{length[n]}
Float $>0$, the length of branches at level $n$ as a fraction of their parent branch's length.
\subsubsection{length\_v[n]}
Float, maximum variation in \textbf{length[n]}.
\subsubsection{taper[n]}
Float 0--3, controls the tapering of the radius of each branch along its length. If $<1$ then the branch tapers to \textbf{taper[n]} of its base radius at its end, so a value 1 results in conical tapering. At $\mathbf{taper[n]} = 2$ the radius remains uniform until the end of the stem where the branch is rounded off in a hemisphere, fractional values between 1 and 2 interpolate between conical tapering and this rounded end. Values $>2$ result in periodic tapering with a maximum variation in radius equal to $(\mathbf{taper[n]} - 2)$ of the base radius - so a value of 3 results in a series of adjacent spheres.
\subsubsection{seg\_splits[n]}
Float 0--2, maximum number of dichotomous branches at each segment of a branch, fractional values are distributed along the stem using a method similar to Floyd-Steinberg error diffusion.
\subsubsection{split\_angle[n]}
Float, angle between dichotomous branches.
\subsubsection{split\_angle\_v[n]}
Float, maximum variation in \textbf{split\_angle[n]}.
\subsubsection{curve\_res[n]}
Integer $>0$, number of segments in each branch.
\subsubsection{curve[n]}
Float, angle by which the direction of the stem will change from start to end, rotating about the stem's local $x$-axis.
\subsubsection{curve\_v[n]}
Float, maximum variation in \textbf{curve[n]}. Applied randomly at each segment.
\subsubsection{curve\_back[n]}
Float, angle in the opposite direction to \textbf{curve[n]} that the stem will curve back from half way along, creating S shaped branches.
\subsubsection{bend\_v[n]}
Float, maximum angle by which the direction of the stem may change from start to end, rotating about the stem's local $y$-axis. Applied randomly at each segment.
\subsubsection{branch\_dist[n]}
\label{sec:branch_dist_def}
Float $\ge0$, controls the distribution of branches along their parent stem. 0 indicates fully alternate branching, interpolating to fully opposite branching at 1. Values $>1$ indicate whorled branching with $n+1$ branches in each whorl. Fractional values result in a rounded integer number of branches in each whorl, with the difference propagated using a method similar to Floyd-Steinberg error diffusion.
\subsubsection{radius\_mod[n]}
Float $\ge0$, modifies the base radius of branches, only for use in special cases such as the weeping willow (Figure \ref{fig:willow}) where the standard radius model is not sufficient.
\subsubsection{leaf\_blos\_num}
Integer $\ge0$, number of leaves or blossom on each of the deepest level of branches.
\subsubsection{leaf\_shape}
Integer 1--10, predefined leaf shapes corresponding to ovate, linear, cordate, maple, palmate, spiky oak, rounded oak, elliptic, rectangle and triangle respectively.
\subsubsection{leaf\_scale}
Float $>0$, scale of leaves
\subsubsection{leaf\_scale\_x}
Float $>0$, $x$ direction scale of leaves.
\subsubsection{leaf\_bend}
Float 0--1, fractional amount by which leaves are reoriented to face the light (upwards and outwards).
\subsubsection{blossom\_shape}
Integer 1--3, predefined blossom shapes corresponding to cherry, orange and magnolia respectively.
\subsubsection{blossom\_scale}
Float $>0$, scale of blossom.
\subsubsection{blossom\_rate}
Float 0--1, fractional rate at which blossom occur relative to leaves.
\subsubsection{tropism}
Float Vector 3D, influence upon the growth direction of the tree in the $x$, $y$ and $z$ directions, the $z$ element only applies to branches in the second level and above ($n \ge 2$).
\subsubsection{prune\_ratio}
Float 0--1, fractional amount by which the effect of pruning is applied.
\subsubsection{prune\_width}
Float $>0$, width of the pruning envelope as a fraction of its height (the maximum height of the tree).
\subsubsection{prune\_width\_peak}
Float $\ge0$, the fractional distance from the bottom of the pruning up at which the peak width occurs.
\subsubsection{prune\_power\_low}
Float, the curvature of the lower section of the pruning envelope. $<1$ results in a convex shape, $>1$ in concave.
\subsubsection{prune\_power\_high}
Float, the curvature of the upper section of the pruning envelope. $<1$ results in a convex shape, $>1$ in concave.

[samipfjo]

Well, the description for **Radius Modifier** is missing, and it appears to be missing in the LaTeX as well.

[friggog]

Ah yeah forgot about that, it's a super hacky one I added specifically for the weeping willow. It basically is a manual override for the branch radius at a given level (normally defined based on the length and parent radius). In that case the branches are extremely long so are much too thick using the normal parameters, so I used radius_mod of 0.1 for the offending level of branches. We should probably dissuade people from using it generally as it is better to try and follow the normal parameterisation in almost all cases to give the most realistic branching structure.