EZ-Tree

About

EZ-Tree is a procedural tree generator with dozens of tunable parameters. The standalone tree generation code is published as a library and can be imported into your own application for dynamically generating trees on demand. Additionally, there is a standalone web app which allows you to create trees within the browser and export as .PNG or .GLB files.

App

https://eztree.dev

Installation

npm i @dkostenevich/ez-tree

Usage

// Create new instance
const tree = new Tree();

// Set parameters
tree.options.seed = 12345;
tree.options.trunk.length = 20;
tree.options.branch.levels = 3;

tree.options.bark.assets.ao = '/assets/bark/oak_ao_1k.jpg';
tree.options.bark.assets.color = '/assets/bark/oak_color_1k.jpg';
tree.options.bark.assets.normal = '/assets/bark/oak_normal_1k.jpg';
tree.options.bark.assets.roughness = '/assets/bark/oak_roughness_1k.jpg';
tree.options.leaves.asset = '/assets/leaves/ash_color.png';

await tree.loadTextures(); // async function

// Generate tree and add to your Three.js scene
tree.generate();
scene.add(tree);

Any time the tree parameters are changed, you must call generate() to regenerate the geometry.

Running Standalone App Locally

To run the standalone app locally, you first need to build the EZ-Tree library before running the app.

npm install
npm run app

Running App with Docker

docker compose build
docker compose up -d

Tree Parameters

The TreeOptions class defines an options object that controls various parameters of a procedurally generated tree. Each property of this object allows for customization of the tree's appearance, including bark, branches, and leaves. Below is a detailed explanation of each property of the TreeOptions object.

General Properties

• seed: Sets the initial value for random generation, ensuring consistent tree generation when using the same seed.
• type: Defines the type of the tree, which can be set to one of the options from the TreeType enumeration (e.g., TreeType.Deciduous).

Bark Parameters

The bark object controls the appearance and properties of the tree trunk.

• type: Specifies the type of bark texture to use, selected from the BarkType enumeration (e.g., BarkType.Oak).
• tint: Determines the color tint applied to the bark, defined as a hexadecimal color value (e.g., 0xffffff for white).
• flatShading: Boolean property indicating whether to use flat shading (true) or smooth shading (false) for the bark.
• textured: Boolean value that indicates if a texture is applied to the bark (true or false).
• textureScale: Controls the scale of the bark texture in both the x and y axes. It is an object with properties x and y to define the scaling factors.

Branch Parameters

The branch object defines parameters for the trunk and branch levels of the tree.

• levels: Number of recursive branch levels. Setting this to 0 creates only the trunk, while higher values add more branches.
• angle: Defines the angle, in degrees, at which child branches grow relative to their parent branch. This is specified separately for each level.
• children: Specifies the number of child branches at each level, with the index (0, 1, 2, etc.) representing the level.
• force: Represents an external directional force encouraging tree growth, defined by direction (a vector object { x, y, z }) and strength (a numeric value).
• gnarliness: Defines how twisted or curled each branch level should be, specified for each level.
• length: Length of the branches at each level. This is an object with keys representing each level.
• radius: Radius (or thickness) of the branches at each level.
• sections: Number of segments along the length of each branch level, controlling the resolution of the branch mesh.
• segments: Number of radial segments that make up each branch, with a higher value resulting in a smoother cylinder.
• start: Specifies where along the parent branch (as a fraction from 0 to 1) the child branches should start forming.
• taper: Controls the tapering of the branches at each level. A value between 0 and 1 defines the reduction in radius from base to tip.
• twist: Defines the amount of twisting applied to each branch level.

Leaf Parameters

The leaves object defines properties that control the appearance and placement of leaves.

• type: Specifies the type of leaf texture, selected from the LeafType enumeration (e.g., LeafType.Oak).
• billboard: Defines how leaves are rendered. The Billboard enumeration can be set to Single or Double to indicate single or perpendicular double-sided leaves.
• angle: Defines the angle of the leaves relative to the parent branch, in degrees.
• count: Number of leaves to generate.
• start: Specifies where along the length of the branch (as a value between 0 and 1) leaves should start growing.
• size: Size of the leaves, represented as a numeric value.
• sizeVariance: Specifies how much variance in size each leaf instance should have, making the leaves look more natural.
• tint: Tint color applied to the leaves, defined as a hexadecimal color value (e.g., 0xffffff for white).
• alphaTest: Sets the alpha threshold for leaf transparency, controlling the transparency of the leaf textures.