### Install PyBonsai on Linux/macOS

Source: https://context7.com/ben-edwards44/pybonsai/llms.txt

Clone the repository, navigate to the directory, and run the install script. Verify the installation by checking the version.

```bash
# Clone and install (Linux/macOS)
git clone https://github.com/Ben-Edwards44/PyBonsai.git
cd PyBonsai
sudo bash install.sh
```

```bash
# Verify
pybonsai --version
# PyBonsai version 1.2.4
```

--------------------------------

### Display Version and Help

Source: https://context7.com/ben-edwards44/pybonsai/llms.txt

Use the --version flag to display the installed PyBonsai version. Use --help to see all available command-line options and their descriptions.

```bash
pybonsai --version
```

```bash
pybonsai --help
```

--------------------------------

### Install PyBonsai on Linux

Source: https://github.com/ben-edwards44/pybonsai/blob/main/README.md

Install PyBonsai for all users on Linux by running the install.sh script. This creates a symlink in /usr/local/bin.

```bash
cd PyBonsai
sudo bash install.sh
```

--------------------------------

### Install pyinstaller on Windows

Source: https://github.com/ben-edwards44/pybonsai/blob/main/README.md

Install the pyinstaller package using pip. You may need to run the terminal in admin mode.

```bash
pip install pyinstaller
```

--------------------------------

### Display PyBonsai help information

Source: https://github.com/ben-edwards44/pybonsai/blob/main/README.md

Run pybonsai with the --help flag to display all available command-line options and their descriptions.

```bash
pybonsai --help
```

--------------------------------

### Using Line and Vector Classes in Python

Source: https://context7.com/ben-edwards44/pybonsai/llms.txt

Demonstrates the instantiation and basic usage of `Line` for line properties and `Vector` for vector arithmetic. Ensure `utils` is available in your Python path.

```python
from utils import Line, Vector

# --- Line usage ---
l = Line()
l.set_end_points((0, 0), (10, 10))
print(l.m)          # 1.0
print(l.get_y(5))   # 5.0
print(l.get_x(7))   # 7.0

import math
print(math.degrees(l.get_theta()))  # 45.0

# Vertical line
vl = Line()
vl.set_end_points((5, 3), (5, 9))
print(vl.is_vertical)   # True
print(vl.get_x(99))     # 5 (always returns the fixed x)

# --- Vector usage ---
v = Vector(3.0, 4.0)
print(v.mag())      # 5.0
v.normalise()
print(round(v.x, 4), round(v.y, 4))  # 0.6  0.8

v2 = Vector(1.0, 0.0)
v2 += Vector(0.0, 1.0)
print(v2.x, v2.y)   # 1.0  1.0

scaled = v2 * 3
print(scaled.x, scaled.y)  # 3.0  3.0
```

--------------------------------

### Instantiate and Draw Different Tree Types

Source: https://context7.com/ben-edwards44/pybonsai/llms.txt

Demonstrates instantiating various tree types (ClassicTree, FibonacciTree, etc.) and drawing them to a terminal window. Ensure necessary imports and options are set.

```python
import random
import draw
import tree as tree_module
from main import Options
from math import radians

random.seed(7)
opts = Options()
opts.instant = True
opts.num_layers = 9
opts.initial_len = 18
opts.angle_mean = radians(38)
opts.leaf_len = 5

window = draw.TerminalWindow(90, 30, opts)
root_pos = (window.width // 2, tree_module.Tree.BOX_HEIGHT + 4)

# Instantiate each type directly
classic = tree_module.ClassicTree(window, root_pos, opts)
# fib     = tree_module.FibonacciTree(window, root_pos, opts)
# off_fib = tree_module.OffsetFibTree(window, root_pos, opts)
# rand    = tree_module.RandomOffsetFibTree(window, root_pos, opts)

classic.draw()
window.draw()
window.reset_cursor()
```

--------------------------------

### Run PyBonsai executable on Windows

Source: https://github.com/ben-edwards44/pybonsai/blob/main/README.md

Navigate to the 'dist' folder and run the generated executable. You can also pass flags to customize the tree generation.

```bash
cd dist
main.exe
```

```bash
pybonsai --layers 10
```

--------------------------------

### Generate PyBonsai tree with instant mode

Source: https://github.com/ben-edwards44/pybonsai/blob/main/README.md

Use the --instant flag to display the finished tree immediately without animation.

```bash
pybonsai --instant
```

--------------------------------

### Display PyBonsai version

Source: https://github.com/ben-edwards44/pybonsai/blob/main/README.md

Run pybonsai with the --version flag to display the current version of the script.

```bash
pybonsai --version
```

--------------------------------

### Python API — Options Class for Programmatic Configuration

Source: https://context7.com/ben-edwards44/pybonsai/llms.txt

Configure PyBonsai tree generation programmatically using the `Options` class. Instantiate it and modify its attributes or use `set_option` to control various parameters.

```APIDOC
## Python API — `Options` class (`main.py`)

`Options` encapsulates all tunable parameters. It reads the terminal size on instantiation and stores defaults. `set_option(name, value)` accepts both long (`--layers`) and short (`-l`) flag names, making it straightforward to drive PyBonsai programmatically without going through the CLI.

### Example Usage
```python
import random
from math import radians
from main import Options, get_tree
import draw

# Instantiate with defaults (reads terminal size automatically)
opts = Options()

# Override programmatically
opts.num_layers = 10
opts.initial_len = 20
opts.angle_mean = radians(45)
opts.leaf_len = 6
opts.instant = True
opts.branch_chars = "~=:")
opts.leaf_chars = "&@#"
opts.type = 1               # FibonacciTree
opts.window_width = 100
opts.window_height = 35

# Create window and tree, then render
random.seed(42)
window = draw.TerminalWindow(opts.window_width, opts.window_height, opts)
t = get_tree(window, opts)
t.draw()
window.draw()
window.reset_cursor()
```
```

--------------------------------

### Build PyBonsai executable on Windows

Source: https://github.com/ben-edwards44/pybonsai/blob/main/README.md

Use pyinstaller to create an executable from main.py. This will generate a 'dist' folder containing the executable.

```bash
cd directory-that-contains-pybonsai
pyinstaller main.py
```

--------------------------------

### Programmatically Control PyBonsai Options

Source: https://context7.com/ben-edwards44/pybonsai/llms.txt

Instantiate the Options class and modify its attributes to customize tree generation. Use `set_option` to accept both long and short flag names.

```python
import random
from math import radians
from main import Options, get_tree
import draw

# Instantiate with defaults (reads terminal size automatically)
opts = Options()

# Override programmatically
opts.num_layers = 10
opts.initial_len = 20
opts.angle_mean = radians(45)
opts.leaf_len = 6
opts.instant = True
opts.branch_chars = "~=:".
opts.leaf_chars = "&#"
opts.type = 1               # FibonacciTree
opts.window_width = 100
opts.window_height = 35

# Create window and tree, then render
random.seed(42)
window = draw.TerminalWindow(opts.window_width, opts.window_height, opts)
t = get_tree(window, opts)
t.draw()
window.draw()
window.reset_cursor()
```

--------------------------------

### Configure Trunk Length and Branch Angle

Source: https://context7.com/ben-edwards44/pybonsai/llms.txt

Use --start-len or -S to set the root branch length (default 15). Use --angle or -a to set the mean angle in degrees for child branches (default 40).

```bash
pybonsai --start-len 25 --angle 20
```

```bash
pybonsai -S 10 -a 60
```

```bash
pybonsai --start-len 20 --angle 55 --layers 10 --instant
```

--------------------------------

### Build Standalone Executable on Windows

Source: https://context7.com/ben-edwards44/pybonsai/llms.txt

Use PyInstaller to create a standalone executable. Rename the executable and add the 'dist' directory to your system's PATH.

```bash
# Windows: build a standalone executable with PyInstaller
pip install pyinstaller
cd PyBonsai
pyinstaller main.py
# Executable appears at dist/main.exe — rename and add dist/ to PATH
rename dist\main.exe dist\pybonsai.exe
```

--------------------------------

### Set PyBonsai root branch length

Source: https://github.com/ben-edwards44/pybonsai/blob/main/README.md

Use the --start-len flag to set the initial length of the root branch.

```bash
pybonsai --start-len 20
```

--------------------------------

### Instant Rendering Mode

Source: https://context7.com/ben-edwards44/pybonsai/llms.txt

Use the --instant or -i flag to render the tree immediately without animation. This is useful for scripting or when a quick preview is needed. Animation is automatically disabled if stdout is not a TTY.

```bash
pybonsai --instant
```

```bash
pybonsai -i -s 99
```

```bash
pybonsai --instant > tree.txt
```

--------------------------------

### CLI Options for Canvas Dimensions and Window Behavior

Source: https://context7.com/ben-edwards44/pybonsai/llms.txt

Control the terminal canvas size and how the window behaves when the tree content exceeds it using `--width`, `--height`, and `--fixed-window` options.

```APIDOC
## CLI Option — `--width` / `-x`, `--height` / `-y`, `--fixed-window` / `-f`

Sets the maximum terminal canvas dimensions. By default PyBonsai reads the actual terminal size and clamps to 80×25. When `--fixed-window` is set, the window height never increases even if the tree grows taller than the canvas.

### Usage Examples
```bash
# Large canvas
pybonsai --width 120 --height 40

# Small thumbnail
pybonsai -x 40 -y 15 --instant

# Prevent window from expanding if tree overflows
pybonsai --fixed-window --layers 12

# Pipe-safe fixed small render
pybonsai -x 60 -y 20 -i -f > snapshot.txt
```
```

--------------------------------

### Clone PyBonsai repository

Source: https://github.com/ben-edwards44/pybonsai/blob/main/README.md

Clone the PyBonsai repository from GitHub to your local machine.

```bash
git clone https://github.com/Ben-Edwards44/PyBonsai.git
```

--------------------------------

### Select Tree Generation Type

Source: https://context7.com/ben-edwards44/pybonsai/llms.txt

Use the --type or -t option followed by an integer (0-3) to select a specific tree generation algorithm. If omitted, a random type is chosen (or deterministically if --seed is set).

```bash
pybonsai --type 0
```

```bash
pybonsai --type 1
```

```bash
pybonsai --type 2
```

```bash
pybonsai --type 3
```

```bash
pybonsai -t 2
```

--------------------------------

### Python API — TerminalWindow Class for Rendering

Source: https://context7.com/ben-edwards44/pybonsai/llms.txt

Utilize the `TerminalWindow` class for managing the character buffer and handling rendering operations, including character placement, color, and line drawing.

```APIDOC
## Python API — `TerminalWindow` class (`draw.py`)

`TerminalWindow` maintains a 2-D character buffer (`self.chars`) and handles all rendering concerns: ANSI 24-bit color wrapping via `colour_char()`, coordinate conversion between Cartesian plane space and screen array indices via `plane_to_screen()` / `screen_to_plane()`, animated vs. instant character placement via `set_char_instant()` / `set_char_wait()`, and thick-line drawing via `draw_line()`.

### Example Usage
```python
from draw import TerminalWindow
from main import Options

opts = Options()
opts.instant = True
opts.branch_chars = "~=:")

window = TerminalWindow(80, 25, opts)

# Place individual colored characters (screen coordinates)
window.set_char_instant(5, 10, "#", (0, 200, 0), True)   # green
window.set_char_instant(5, 11, "|", (180, 120, 50), True) # brown

# Place using Cartesian plane coordinates (auto-converted)
window.set_char_instant(30.0, 40.0, "@", (0, 255, 0), False)

# Draw a thick colored branch line between two plane points
window.draw_line((40, 10), (50, 20), ((200, 255), (150, 255), (0, 0)), width=2)

# Render the buffer to stdout
window.draw()
window.reset_cursor()
```
```

--------------------------------

### Python API — Tree Classes for Different Tree Types

Source: https://context7.com/ben-edwards44/pybonsai/llms.txt

Instantiate and draw different types of trees (`ClassicTree`, `FibonacciTree`, `OffsetFibTree`, `RandomOffsetFibTree`) by importing them from the `tree` module and calling their `draw()` method.

```APIDOC
## Python API — Tree classes (`tree.py`)

Four concrete tree classes all inherit from `RecursiveTree → Tree`. Each implements `draw()` which first renders the decorative planter box, then the trunk base, then recursively grows branches. `ClassicTree` uses a normal distribution for branch count; `FibonacciTree` follows the Fibonacci sequence; `OffsetFibTree` distributes branches along parent lengths; `RandomOffsetFibTree` randomizes placement and allows mid-branch leaves.

### Example Usage
```python
import random
import draw
import tree as tree_module
from main import Options
from math import radians

random.seed(7)
opts = Options()
opts.instant = True
opts.num_layers = 9
opts.initial_len = 18
opts.angle_mean = radians(38)
opts.leaf_len = 5

window = draw.TerminalWindow(90, 30, opts)
root_pos = (window.width // 2, tree_module.Tree.BOX_HEIGHT + 4)

# Instantiate each type directly
classic = tree_module.ClassicTree(window, root_pos, opts)
# fib     = tree_module.FibonacciTree(window, root_pos, opts)
# off_fib = tree_module.OffsetFibTree(window, root_pos, opts)
# rand    = tree_module.RandomOffsetFibTree(window, root_pos, opts)

classic.draw()
window.draw()
window.reset_cursor()
```
```

--------------------------------

### Render Characters and Lines in TerminalWindow

Source: https://context7.com/ben-edwards44/pybonsai/llms.txt

Utilize the `TerminalWindow` class to manage a character buffer and render graphics. Supports colored characters, Cartesian to screen coordinate conversion, and thick line drawing.

```python
from draw import TerminalWindow
from main import Options

opts = Options()
opts.instant = True
opts.branch_chars = "~=:".

window = TerminalWindow(80, 25, opts)

# Place individual colored characters (screen coordinates)
window.set_char_instant(5, 10, "#", (0, 200, 0), True)   # green
window.set_char_instant(5, 11, "|", (180, 120, 50), True) # brown

# Place using Cartesian plane coordinates (auto-converted)
window.set_char_instant(30.0, 40.0, "@", (0, 255, 0), False)

# Draw a thick colored branch line between two plane points
window.draw_line((40, 10), (50, 20), ((200, 255), (150, 255), (0, 0)), width=2)

# Render the buffer to stdout
window.draw()
window.reset_cursor()
```

--------------------------------

### Set Leaf Strand Length with CLI Option

Source: https://context7.com/ben-edwards44/pybonsai/llms.txt

Adjust the number of steps each leaf strand takes from its branch endpoint to control drooping. Default is 4.

```bash
# Short, tight leaf clusters
pybonsai --leaf-len 2
```

```bash
# Long drooping leaves
pybonsai -L 8
```

```bash
# Full example: weeping willow-like appearance
pybonsai --type 3 --leaf-len 10 --angle 50 --layers 8 --instant
```

--------------------------------

### Set PyBonsai leaf length

Source: https://github.com/ben-edwards44/pybonsai/blob/main/README.md

Use the --leaf-len flag to set the length of each leaf.

```bash
pybonsai --leaf-len 6
```

--------------------------------

### Set PyBonsai branch angle

Source: https://github.com/ben-edwards44/pybonsai/blob/main/README.md

Use the --angle flag to set the mean angle of branches to their parent in degrees. Higher values result in more arched trees.

```bash
pybonsai --angle 60
```

--------------------------------

### Customize PyBonsai branch characters

Source: https://github.com/ben-edwards44/pybonsai/blob/main/README.md

Use the --branch-chars flag to provide a string of characters that will be randomly chosen for branches.

```bash
pybonsai --branch-chars "~;:="
```

--------------------------------

### Fix PyBonsai window height

Source: https://github.com/ben-edwards44/pybonsai/blob/main/README.md

Use the --fixed-window flag to prevent the window height from increasing when the tree grows off-screen.

```bash
pybonsai --fixed-window
```

--------------------------------

### Customize PyBonsai leaf characters

Source: https://github.com/ben-edwards44/pybonsai/blob/main/README.md

Use the --leaf-chars flag to provide a string of characters that will be randomly chosen for leaves.

```bash
pybonsai --leaf-chars "&%#@"
```

--------------------------------

### Set PyBonsai animation delay

Source: https://github.com/ben-edwards44/pybonsai/blob/main/README.md

Use the --wait flag to specify the time delay in seconds between drawing characters when not in instant mode.

```bash
pybonsai --wait 0.1
```

--------------------------------

### Set Terminal Canvas Dimensions with CLI Options

Source: https://context7.com/ben-edwards44/pybonsai/llms.txt

Control the maximum width and height of the terminal canvas. Use `--fixed-window` to prevent the window from expanding if the tree grows taller than the canvas.

```bash
# Large canvas
pybonsai --width 120 --height 40
```

```bash
# Small thumbnail
pybonsai -x 40 -y 15 --instant
```

```bash
# Prevent window from expanding if tree overflows
pybonsai --fixed-window --layers 12
```

```bash
# Pipe-safe fixed small render
pybonsai -x 60 -y 20 -i -f > snapshot.txt
```

--------------------------------

### Customize Branch and Leaf Characters

Source: https://context7.com/ben-edwards44/pybonsai/llms.txt

Use --branch-chars or -c to specify characters for branches (default "~;:="). Use --leaf-chars or -C to specify characters for leaves (default "&%#@").

```bash
pybonsai --branch-chars '.,~' --leaf-chars '*oO'
```

```bash
pybonsai -c '|' -C '.'
```

```bash
pybonsai --leaf-chars '@&#' --branch-chars '~=:'
```

--------------------------------

### Set PyBonsai maximum width

Source: https://github.com/ben-edwards44/pybonsai/blob/main/README.md

Use the --width flag to set the maximum width of the generated tree.

```bash
pybonsai --width 100
```

--------------------------------

### CLI Option for Leaf Strand Length

Source: https://context7.com/ben-edwards44/pybonsai/llms.txt

Adjust the length of individual leaf strands using the `--leaf-len` option, which affects how far leaves droop from their branches.

```APIDOC
## CLI Option — `--leaf-len` / `-L`

Sets how many steps each individual leaf strand takes from its branch endpoint. Leaves droop downward due to a simulated gravity effect. Default is `4`.

### Usage Examples
```bash
# Short, tight leaf clusters
pybonsai --leaf-len 2

# Long drooping leaves
pybonsai -L 8

# Full example: weeping willow-like appearance
pybonsai --type 3 --leaf-len 10 --angle 50 --layers 8 --instant
```
```

--------------------------------

### Set PyBonsai number of branch layers

Source: https://github.com/ben-edwards44/pybonsai/blob/main/README.md

Use the --layers flag to control the number of branch layers, which affects the overall complexity of the tree.

```bash
pybonsai --layers 12
```

--------------------------------

### Set PyBonsai maximum height

Source: https://github.com/ben-edwards44/pybonsai/blob/main/README.md

Use the --height flag to set the maximum height of the generated tree.

```bash
pybonsai --height 50
```

--------------------------------

### Set Number of Tree Layers

Source: https://context7.com/ben-edwards44/pybonsai/llms.txt

Use the --layers or -l option followed by an integer to set the number of recursive branch layers. Higher values create denser, more complex trees. The default is 8.

```bash
pybonsai --layers 4
```

```bash
pybonsai --layers 14
```

```bash
pybonsai -l 10 -t 0 -i
```

--------------------------------

### Set Random Seed for Reproducibility

Source: https://context7.com/ben-edwards44/pybonsai/llms.txt

Use the --seed or -s option followed by an integer to set the random number generator's seed. This ensures that the generated tree is identical on subsequent runs with the same seed.

```bash
pybonsai --seed 42
```

```bash
pybonsai --seed 42 --type 1
```

```bash
pybonsai -s 42
```

--------------------------------

### Set PyBonsai tree type

Source: https://github.com/ben-edwards44/pybonsai/blob/main/README.md

Use the --type flag to specify the tree type by an integer between 0 and 3. Defaults to random.

```bash
pybonsai --type 2
```

--------------------------------

### Control Animation Speed

Source: https://context7.com/ben-edwards44/pybonsai/llms.txt

Use the --wait or -w option followed by a float value to control the delay in seconds between drawing each character during animated mode. A value of 0 (default) means no pause.

```bash
pybonsai --wait 0.05
```

```bash
pybonsai -w 0.005
```

```bash
pybonsai --seed 7 --wait 0.02
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.