EZ-Tree

The textures used in EZ-Tree are subject to different licenses depending on their type:

• Bark Textures (located in bark/): Sourced from ambientcg.com and released under the Creative Commons CC0 1.0 Universal license (public domain). While attribution is not legally required, it is provided as a courtesy.
• Leaf Textures (located in leaves/): Bundled with the EZ-Tree demo app and licensed under the project's own license (refer to the repository's main LICENSE file).

For performance in scenes with many trees, use generateLODs() instead of generate(). This builds the tree at multiple levels of detail hosted in a THREE.LOD object inside the tree group. The renderer automatically switches levels based on camera distance.

All levels share the same skeleton (maintaining silhouette consistency) and use the same bark and leaf materials, allowing tree.update(time) to animate wind across all levels simultaneously.

Note: Calling generate() after generateLODs() will tear down the LOD system and restore a single full-detail mesh pair. If exporting to GLB, a tree generated with generateLODs() will include all LOD levels.

const tree = new Tree();
tree.loadPreset('Ash Medium');
tree.generateLODs(); // instead of generate()
scene.add(tree);

Use Docker Compose to run the application:

docker compose build
docker compose up -d

To run the web app locally, build the library first, then start the app:

npm install
npm run app

To use the EZ-Tree library in your application, install it using npm:

npm i @dgreenheck/ez-tree

You can run the EZ-Tree application in a containerized environment using Docker Compose. The tree-gen-app service maps port 5173 to your host, allowing you to access the application locally.

To enable live development, the configuration mounts the local ./src and ./public directories into the container. The application is started with NODE_ENV=development and configured to listen on 0.0.0.0 to ensure the host can reach the service.

To generate a tree, instantiate the Tree class, configure its options object, and call generate(). Note that you must call generate() every time you change parameters to update the geometry. The resulting tree object can be added directly to a Three.js scene.

// 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);

You can pass an array of custom LOD configurations to generateLODs(). Each object defines a distance at which the level triggers and a detail object to control mesh reduction.

tree.generateLODs([
  { distance: 0, detail: {} }, // full detail
  {
    distance: 80,
    hysteresis: 0.05,
    detail: {
      sectionStride: 3,    // sample every 3rd ring along each branch
      segmentFactor: 0.75, // reduce radial segments to 75% (min 3)
      leafStride: 2,       // keep every 2nd leaf...
      leafScale: 1.4,      // ...enlarged to preserve canopy coverage
      billboard: 'single', // drop the second crossed leaf quad
    },
  },
]);

The Trellis constructor accepts an options object to define the grid's physical properties and appearance.

Required/Supported keys:

• color: The color of the trellis cylinders (e.g., hex value).
• cylinderRadius: The radius of the cylinders forming the grid.
• width: The total width of the trellis grid along the X axis.
• height: The total height of the trellis grid along the Y axis.
• spacing: The distance between horizontal and vertical lines.
• position: An object { x, y, z } defining the base position of the trellis.

The branch object defines trunk and branch structure:

• levels: Number of recursive branch levels (0 is just a trunk).
• angle: Array of angles (in degrees) for child branches relative to parents per level.
• children: Number of child branches at each level (indexed by level).
• force: Directional growth force: { direction: { x, y, z }, strength: number }.
• gnarliness: Array of twist/curl values per level.
• length: Object mapping levels to branch lengths.
• radius: Array of thickness values per level.
• sections: Number of segments along the length (resolution).
• segments: Number of radial segments (smoothness).
• start: Fraction (0 to 1) along parent branch where children start.
• taper: Reduction in radius from base to tip (0 to 1).
• twist: Amount of twisting per level.