QSM leaf cylinder library method

Leaf cylinder library generation

Function call

Leaf cylinder library is generated by calling the function generate_leaf_cylinder_library. The format for the basic function call is

LeafCylinderLibrary = generate_leaf_cylinder_library(...
    LibraryDistributions,Nodes,LeafProperties);

where LibraryDistributions is a struct contatining LOD and LSD distribution types, Nodes is a struct containing the discretization nodes for the library, and LeafProperties contains leaf base geometry and petiole length information. The function provides a struct LeafCylinderLibrary containing the leaf cylinders and metadata of the generated library.

Inputs

Library distributions

The required fields for LibraryDistributions are:

Field name	Description	Type
dTypeLODinc	LOD inclination angle distribution type	string
dTypeLODaz	LOD azimuth angle distribution type	string
dTypeLSD	LSD distribution type	string

Nodes

The required fields for Nodes are:

Field name	Description	Type
pLODinc1	LOD inclination angle parameter 1	double
pLODinc2	LOD inclination angle parameter 2	double
pLODaz1	LOD azimuth angle parameter 1	double
pLODaz2	LOD azimuth angle parameter 2	double
pLSD1	LSD parameter 1	double
pLSD2	LSD parameter 2	double
cylinderLength	Cylinder length	double
cylinderRadius	Cylinder radius	double
cylinderInclinationAngle	Cylinder inclination angle	double
cylinderAzimuthAngle	Cylinder azimuth angle	double
cylinderLeafArea	Leaf area per cylinder	double

Leaf properties

The required fields for LeafProperties are:

Field name	Description	Type
vertices	Vertice coordinates for leaf base geometry triangles	double
triangles	Indicators for the edges of each triangle	double
petioleLengthLimits	Leaf petiole length limits	double

Optional inputs

Optional inputs can be given after the required inputs as name-value pairs. Input called OptInput with value optValue is given as:

LeafCylinderLibrary = generate_leaf_cylinder_library(...
    LibraryDistributions,Nodes,LeafProperties,'OptInput',optValue);

The optional input options are:

Name	Description	Type
NLeafObjectsPerNode	Number of leaf cylinders generated per node	integer
PetioleDirectionDistribution	Petiole direction distribution function	function handle
Phyllotaxis	Leaf phyllotaxis pattern struct	struct
IntersectionPrevention	Intersection prevention flag	boolean

Number of leaf cylinders generated pre library node

An integer value to define how many unique leaf cylinders are generated for each library node. A higher value will diversify the output of the library but requires more computational effort in the generation. Default values is 3 leaf cylinders per node.

Petiole direction distribution

A function handle for the petiole direction distribution function on cylinder level. Defined over the interval $[0,2\pi]$ such that $0$ and $2\pi$ correspond to the upmost radial direction, and the value increases in clockwise direction when the cylinder is viewed in the direction of the cylinder axis. The default distribution for petiole directions is uniform distribution.

Leaf phyllotaxis pattern

A struct containing parameters for a phyllotaxis pattern of the leaves. Overrides the petiole direction distribution. More information on phyllotaxis can be found in the Phyllotaxis section in Additional Details. By default there is no phyllotaxis pattern.

Intersection prevention

A boolean value for turning intersection prevention of leaves off. Intersection prevention is computationally the heaviest part of the leaf generation, but assures more realistic foliage. If this is not needed, intersection prevention can be turned off. By default intersection prevention is on.

Output

The output LeafCylinderLibrary is a struct which contains the leaf cylinders as LeafModelTriangle-class objects, as well as library metadata. It is worth noting that despite the name leaf cylinder, the library does not actually contain explicit models for the cylinders themselves. However, the parameters of the cylinders in library nodes are contained in the library metadata. The fields of the output struct LeafCylinderLibrary are:

Field name	Description	Type
LeafBaseModel	Leaf base geometry and petiole limits	struct
LeafDistributions	Distribution types for LOD and LSD used in library generation	struct
LeafObjects	The leaf cylinders of the library	struct
Nodes	The Nodes struct used in library generation	struct
Properties	Library metadata	struct

Transforming leaf cylinders onto QSM

Foliage is added on a QSM by calling the function transform_leaf_cylinders. The format for the basic function call is

Leaves = transform_leaf_cylinders(QSM,LeafCylinderLibrary,...
    TargetLADD,ParamFunctions,targetLeafArea);

where QSM is a struct containing a quantitative structure model, LeafCylinderLibrary is a struct containing a leaf cylinder library, TargetLADD is a struct containing target distribution types and parameters for LADD, ParamFunctions is a struct containing the target parameter functions for LOD and LSD, and targetLeafArea is a value for the total leaf area to be added on the tree model. The fuction provides a LeafModelTriangle-class object Leaves containing information of the generated leaves and a QSMBCylindrical-class object containing information on the QSM.

Inputs

QSM

LeafGen uses the QSM format produced by the TreeQSM method. Optionally, a QSM can be intialized by defining a struct containing the basic information of the cylinders, in which case the required fields for the QSM struct are:

Field name	Description	Type
cylinder.start	Cylinder start points	double
cylinder.axis	Cylinder axes	double
cylinder.length	Cylinder lengths	double
cylinder.radius	Cylinder radii	double
cylinder.parent	Cylinder parent cylinders	integer
cylinder.branch	Cylinder branch index	integer

LeafCylinderLibrary

A leaf cylinder library struct generated using the generate_leaf_cylinder_library function.

Target LADD

The required fields for the TargetLADD struct are:

Field name	Description	Type
dTypeLADDh	LADD relative height distribution type	string
dTypeLADDd	LADD relative distance along subbranch distribution type	string
dTypeLADDc	LADD compass direction distribution type	string
pLADDh	LADD heightwise distribution parameters	double
pLADDd	LADD distancewise distribution parameters	double
pLADDc	LADD directionwise distribution parameters	double

Parameter functions for LOD and LSD

The required fields for the ParamFunctions struct are:

Field name	Description	Type
fun_pLODinc	Function for LOD inclination angle distribution parameters	function handle
fun_pLODaz	Function for LOD azimuth angle distribution parameters	function handle
fun_pLSD	Function for LSD distribution parameters	function handle

Target leaf area

totalLeafArea is a double-precision variable containing the target total leaf area for the foliage.

Outputs

Leaves

The output Leaves is a LeafModelTriangle-class object, which contains information of the generated foliage and functions for visualization. The contents of the class are:

Name	Description	Type
base_vertices	Base geometry vertice points	double
base_dimensions	Base geometry outer dimensions	double
base_triangles	Base geometry triangle definitions	double
base_area	Base geometry surface area	double
triangle_count	Number of triangles in base geometry	double
leaf_count	Total number of leaves	double
leaf_area	Surface areas of leaves	double
leaf_start_point	Start points of leaves	double
leaf_scale	Scale factors of leaves	double
leaf_direction	Tip direction vectors of leaves	double
leaf_normal	Normal vectors of leaves	double
leaf_parent	Parent cylinders of leaves	double
petiole_start_point	Petiole start points of leaves	double

QSMbc

The output QSMbc is a QSMBCylindrical-class object, which contains information of the QSM and functions for visualization. More infromation can be found from QSM-Blocks repository.