https://github.com/dgreenheck/ez-tree
Procedural tree generator written with JavaScript and Three.js
https://github.com/dgreenheck/ez-tree
Last synced: 8 months ago
JSON representation
Procedural tree generator written with JavaScript and Three.js
- Host: GitHub
- URL: https://github.com/dgreenheck/ez-tree
- Owner: dgreenheck
- License: mit
- Created: 2024-04-22T22:46:05.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-01-14T20:14:51.000Z (12 months ago)
- Last Synced: 2025-05-02T09:05:53.219Z (8 months ago)
- Language: JavaScript
- Homepage: https://www.eztree.dev
- Size: 93.1 MB
- Stars: 722
- Watchers: 9
- Forks: 79
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome - dgreenheck/ez-tree - Procedural tree generator written with JavaScript and Three.js (JavaScript)
README
# 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
```js
npm i @dgreenheck/ez-tree
```
# Usage
```js
// Create new instance
const tree = new Tree();
// Set parameters
tree.options.seed = 12345;
tree.options.trunk.length = 20;
tree.options.branch.levels = 3;
// 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.
```bash
npm install
npm run app
```
# Running App with Docker
```bash
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.