pybonsai 0.1.0__tar.gz

pybonsai-0.1.0/.gitignore

@@ -0,0 +1,2 @@
+__pycache__/
+.cursor/

pybonsai-0.1.0/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2025 Ivan Karlov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

pybonsai-0.1.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: pybonsai
+Version: 0.1.0
+Summary: A project that generates ASCII art trees in your terminal.
+Project-URL: Source, https://github.com/DaEtoJostka/PyBonsai
+Project-URL: Original, https://github.com/Ben-Edwards44/PyBonsai
+Author: Ben Edwards
+Author-email: Ivan Karlov <karlovivan679@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: pybonsai
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# PyBonsai :palm_tree:
+
+PyBonsai is a Python script that generates procedural ASCII art trees in the comfort of your terminal.
+
+## About :seedling:
+
+<img src="Images/demo.gif" align="right" width="450px">
+
+PyBonsai is inspired by the amazing [cbonsai](https://gitlab.com/jallbrit/cbonsai) repository.
+Whereas cbonsai grows bonsai trees, PyBonsai trees look more like trees you would find in a forest (oak, ash and so on).
+
+The trees are configurable via CLI options to make them different sizes, more or less complex, grow at different rates, or use a different set of characters. See [useage](#useage-wrench) for more information.
+
+Currently, PyBonsai supports 4 different types of tree. Details of these are shown in the [tree types](#tree-types-leaves) section.
+
+PyBonsai uses [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code) for colouring characters. Almost all modern terminals will support this but, if yours does not, PyBonsai will not work.
+
+If you encounter an issue with PyBonsai, or have an idea for an improvement, do not be afraid to open an issue.
+
+## Installation :link:
+
+Requirements:
+
+- Python 3.9 or greater
+
+To use PyBonsai, you need to first clone the repository:
+
+    git clone https://github.com/Ben-Edwards44/PyBonsai.git
+
+### Linux
+
+To install for all users, run the included `install.sh` script to create a symlink in `/usr/local/bin`
+
+    cd PyBonsai
+    sudo bash install.sh
+
+Verify the installation by running:
+
+    pybonsai --version
+
+### Windows
+
+After cloning the repository you need to follow these steps in order to run PyBonsai in your terminal:
+
+1. Install the `pyinstaller` package
+
+```
+pip install pyinstaller
+```
+
+> You may need to run the terminal in admin mode while installing `pyinstaller`
+
+2. Change to the directory containing the cloned repo and run the `pyinstaller` command on `main.py`
+
+```
+cd directory-that-contains-pybonsai
+pyinstaller main.py
+```
+
+This will create a new `dist` folder with an executable of the PyBonsai, you can test it by changing to the `dist` folder and running `main.exe`
+
+```
+cd dist
+main.exe
+```
+
+You should see something like this:
+
+<img src="Images/demo-windows.gif" width="450px">
+
+<br />
+
+Now rename the `main.exe` to `pybonsai.exe`
+
+3. Copy the path of the `dist` folder and add it to your `Path` environment variable
+
+<img src="Images/env-example.png" width="450px">
+
+<br />
+
+Now you can run PyBonsai with the command `pybonsai.exe` or `pybonsai`
+
+You can even pass flags
+
+```
+pybonsai --layers 10
+```
+
+### MacOS
+
+Please note that PyBonsai has not been tested on MacOS, but I see no reason why it would not work on Mac OS.
+To install PyBonsai, you will need to clone the repository and add it to your system's PATH.
+
+## Usage :wrench:
+
+Run `pybonsai --help` for useage:
+
+    USEAGE pybonsai [OPTION]...
+
+    PyBonsai procedurally generates ASCII art trees in your terminal.
+
+    OPTIONS:
+        -h, --help            display help
+            --version         display version
+
+        -s, --seed            seed for the random number generator
+
+        -i, --instant         instant mode: display finished tree immediately
+        -w, --wait            time delay between drawing characters when not in instant mode [default 0]
+
+        -c, --branch-chars    string of chars randomly chosen for branches [default "~;:="]
+        -C, --leaf-chars      string of chars randomly chosen for leaves [default "&%#@"]
+
+        -x, --width           maximum width of the tree [default 80]
+        -y, --height          maximum height of the tree [default 25]
+
+        -t, --type            tree type: integer between 0 and 3 inclusive [default random]
+        -S, --start-len       length of the root branch [default 15]
+        -L, --leaf-len        length of each leaf [default 4]
+        -l, --layers          number of branch layers: more => more branches [default 8]
+        -a, --angle           mean angle of branches to their parent, in degrees; more => more arched trees [default 40]
+
+        -f, --fixed-window    do not allow window height to increase when tree grows off screen
+
+The following images demonstrate the use of the different options:
+
+| Effect               | Image                                              |
+| -------------------- | -------------------------------------------------- |
+| Big tree             | ![big tree](/Images/options/big.png)               |
+| Different characters | ![different characters](/Images/options/chars.png) |
+| Longer leaves        | ![longer leaves](/Images/options/leafy.png)        |
+
+## Tree Types :leaves:
+
+PyBonsai supports 4 different tree types. Unless specified with the `--type` option, the tree type will be chosen at random.
+
+All tree types are generated recursively and are, essentially, variations on [this](https://www.youtube.com/watch?v=0jjeOYMjmDU) basic fractal tree.
+
+| Type             | Image                                       | Description                                                                                                              |
+| ---------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| Classic          | ![classic](/Images/types/classic.png)       | The number of child branches is normally distributed with $\mu = 2$ and $\sigma = 0.5$.                                  |
+| Fibonacci        | ![fib](/Images/types/fib.png)               | The number of branches on the $n^{th}$ layer is the $n^{th}$ fibonacci number.                                           |
+| Offset fibonacci | ![offset fib](/Images/types/offset_fib.png) | Similar to above, except child branches grow in the middle of the parent as well as the end.                             |
+| Random fibonacci | ![random fib](/Images/types/rand_fib.png)   | Similar to above, except child branches grow at random positions on the parent and leaves can grow in the middle layers. |

pybonsai-0.1.0/README.md

@@ -0,0 +1,144 @@
+# PyBonsai :palm_tree:
+
+PyBonsai is a Python script that generates procedural ASCII art trees in the comfort of your terminal.
+
+## About :seedling:
+
+<img src="Images/demo.gif" align="right" width="450px">
+
+PyBonsai is inspired by the amazing [cbonsai](https://gitlab.com/jallbrit/cbonsai) repository.
+Whereas cbonsai grows bonsai trees, PyBonsai trees look more like trees you would find in a forest (oak, ash and so on).
+
+The trees are configurable via CLI options to make them different sizes, more or less complex, grow at different rates, or use a different set of characters. See [useage](#useage-wrench) for more information.
+
+Currently, PyBonsai supports 4 different types of tree. Details of these are shown in the [tree types](#tree-types-leaves) section.
+
+PyBonsai uses [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code) for colouring characters. Almost all modern terminals will support this but, if yours does not, PyBonsai will not work.
+
+If you encounter an issue with PyBonsai, or have an idea for an improvement, do not be afraid to open an issue.
+
+## Installation :link:
+
+Requirements:
+
+- Python 3.9 or greater
+
+To use PyBonsai, you need to first clone the repository:
+
+    git clone https://github.com/Ben-Edwards44/PyBonsai.git
+
+### Linux
+
+To install for all users, run the included `install.sh` script to create a symlink in `/usr/local/bin`
+
+    cd PyBonsai
+    sudo bash install.sh
+
+Verify the installation by running:
+
+    pybonsai --version
+
+### Windows
+
+After cloning the repository you need to follow these steps in order to run PyBonsai in your terminal:
+
+1. Install the `pyinstaller` package
+
+```
+pip install pyinstaller
+```
+
+> You may need to run the terminal in admin mode while installing `pyinstaller`
+
+2. Change to the directory containing the cloned repo and run the `pyinstaller` command on `main.py`
+
+```
+cd directory-that-contains-pybonsai
+pyinstaller main.py
+```
+
+This will create a new `dist` folder with an executable of the PyBonsai, you can test it by changing to the `dist` folder and running `main.exe`
+
+```
+cd dist
+main.exe
+```
+
+You should see something like this:
+
+<img src="Images/demo-windows.gif" width="450px">
+
+<br />
+
+Now rename the `main.exe` to `pybonsai.exe`
+
+3. Copy the path of the `dist` folder and add it to your `Path` environment variable
+
+<img src="Images/env-example.png" width="450px">
+
+<br />
+
+Now you can run PyBonsai with the command `pybonsai.exe` or `pybonsai`
+
+You can even pass flags
+
+```
+pybonsai --layers 10
+```
+
+### MacOS
+
+Please note that PyBonsai has not been tested on MacOS, but I see no reason why it would not work on Mac OS.
+To install PyBonsai, you will need to clone the repository and add it to your system's PATH.
+
+## Usage :wrench:
+
+Run `pybonsai --help` for useage:
+
+    USEAGE pybonsai [OPTION]...
+
+    PyBonsai procedurally generates ASCII art trees in your terminal.
+
+    OPTIONS:
+        -h, --help            display help
+            --version         display version
+
+        -s, --seed            seed for the random number generator
+
+        -i, --instant         instant mode: display finished tree immediately
+        -w, --wait            time delay between drawing characters when not in instant mode [default 0]
+
+        -c, --branch-chars    string of chars randomly chosen for branches [default "~;:="]
+        -C, --leaf-chars      string of chars randomly chosen for leaves [default "&%#@"]
+
+        -x, --width           maximum width of the tree [default 80]
+        -y, --height          maximum height of the tree [default 25]
+
+        -t, --type            tree type: integer between 0 and 3 inclusive [default random]
+        -S, --start-len       length of the root branch [default 15]
+        -L, --leaf-len        length of each leaf [default 4]
+        -l, --layers          number of branch layers: more => more branches [default 8]
+        -a, --angle           mean angle of branches to their parent, in degrees; more => more arched trees [default 40]
+
+        -f, --fixed-window    do not allow window height to increase when tree grows off screen
+
+The following images demonstrate the use of the different options:
+
+| Effect               | Image                                              |
+| -------------------- | -------------------------------------------------- |
+| Big tree             | ![big tree](/Images/options/big.png)               |
+| Different characters | ![different characters](/Images/options/chars.png) |
+| Longer leaves        | ![longer leaves](/Images/options/leafy.png)        |
+
+## Tree Types :leaves:
+
+PyBonsai supports 4 different tree types. Unless specified with the `--type` option, the tree type will be chosen at random.
+
+All tree types are generated recursively and are, essentially, variations on [this](https://www.youtube.com/watch?v=0jjeOYMjmDU) basic fractal tree.
+
+| Type             | Image                                       | Description                                                                                                              |
+| ---------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| Classic          | ![classic](/Images/types/classic.png)       | The number of child branches is normally distributed with $\mu = 2$ and $\sigma = 0.5$.                                  |
+| Fibonacci        | ![fib](/Images/types/fib.png)               | The number of branches on the $n^{th}$ layer is the $n^{th}$ fibonacci number.                                           |
+| Offset fibonacci | ![offset fib](/Images/types/offset_fib.png) | Similar to above, except child branches grow in the middle of the parent as well as the end.                             |
+| Random fibonacci | ![random fib](/Images/types/rand_fib.png)   | Similar to above, except child branches grow at random positions on the parent and leaves can grow in the middle layers. |

pybonsai-0.1.0/install.sh

@@ -0,0 +1,7 @@
+#!/bin/bash
+
+INSTALL_DIR="/usr/local/bin"
+
+chmod +x main.py
+
+ln -s "$(pwd)/main.py" "$INSTALL_DIR/pybonsai"

pybonsai-0.1.0/pybonsai/__main__.py

@@ -0,0 +1,222 @@
+#!/usr/bin/env python3
+
+
+#   
+#                #&                                  
+#              %&@&                                  
+#       &%@% %&  %@|                                 
+#    &&@@&%#@%_\@@&&@#       @=&                     
+#   &#@# #%##  ;&@%#  %@    @% &%                    
+#     @  %  #&  %%~|       @%@%@&#                   
+#                  |;;         # %                   
+#                     \\        @ % %@%#             
+#                      |~     =;@ __%%               
+#                      =|   ~_=___  %&#              
+#                      || /~         % #             
+#                      |//           &               
+#                      |=                            
+#                      ~|                            
+#                      ;|                            
+#       .---.        ./||\.    .-.     
+#   
+#       I speak for the trees, for the trees have no voice.
+#       - The Lorax, 1971
+#   
+
+
+from . import draw
+from . import tree
+import argparse
+import sys
+
+import random
+from math import radians
+from os import get_terminal_size
+
+
+VERSION = "1.2.2"
+DESC = "PyBonsai procedurally generates ASCII art trees in your terminal."
+
+
+class Options:
+    #stores all parameters that can be edited via the command line arguments
+    
+    #default values
+    NUM_LAYERS = 8
+    INITIAL_LEN = 15
+    ANGLE_MEAN = 40
+
+    LEAF_LEN = 4
+
+    INSTANT = False
+    WAIT_TIME = 0
+
+    BRANCH_CHARS = "~;:="
+    LEAF_CHARS = "&%#@"
+
+    WINDOW_WIDTH = 80
+    WINDOW_HEIGHT = 25
+
+    FIXED = False
+
+    def __init__(self):
+        #set the default values
+        self.num_layers = Options.NUM_LAYERS
+        self.initial_len = Options.INITIAL_LEN
+        self.angle_mean = radians(Options.ANGLE_MEAN)
+
+        self.leaf_len = Options.LEAF_LEN
+
+        self.instant = Options.INSTANT
+        self.wait_time = Options.WAIT_TIME
+
+        self.branch_chars = Options.BRANCH_CHARS
+        self.leaf_chars = Options.LEAF_CHARS
+
+        self.user_set_type = False
+        self.type = random.randint(0, 3)
+        self.fractal_mode = False
+
+        self.fixed_window = Options.FIXED
+
+        self.window_width, self.window_height = self.get_default_window()
+
+    def get_default_window(self):
+        #ensure the default values fit the current terminal size
+        width, height = get_terminal_size()
+
+        #check the default values fit the current terminal
+        width = min(width, Options.WINDOW_WIDTH)
+        height = min(height, Options.WINDOW_HEIGHT)
+
+        return width, height
+    
+    def set_seed(self, seed):
+        random.seed(seed)
+
+        #the type must be re-chosen because the rng seed has been changed (this ensures repeatable results)
+        if not self.user_set_type:
+            self.type = random.randint(0, 3)
+
+
+def _print_help():
+    OPTION_DESCS = f"""OPTIONS:
+    -h, --help            display help
+        --version         display version
+
+    -s, --seed            seed for the random number generator
+
+    -i, --instant         instant mode: display finished tree immediately
+    -w, --wait            time delay between drawing characters when not in instant mode [default {Options.WAIT_TIME}]
+
+    -c, --branch-chars    string of chars randomly chosen for branches [default "{Options.BRANCH_CHARS}"]
+    -C, --leaf-chars      string of chars randomly chosen for leaves [default "{Options.LEAF_CHARS}"]
+
+    -x, --width           maximum width of the tree [default {Options.WINDOW_WIDTH}]
+    -y, --height          maximum height of the tree [default {Options.WINDOW_HEIGHT}]
+
+    -t, --type            tree type: integer between 0 and 3 inclusive [default random]
+    -S, --start-len       length of the root branch [default {Options.INITIAL_LEN}]
+    -L, --leaf-len        length of each leaf [default {Options.LEAF_LEN}]
+    -l, --layers          number of branch layers: more => more branches [default {Options.NUM_LAYERS}]
+    -a, --angle           mean angle of branches to their parent, in degrees; more => more arched trees [default {Options.ANGLE_MEAN}]
+
+    -f, --fixed-window    do not allow window height to increase when tree grows off screen
+"""
+    usage = "usage: pybonsai [-h] [--version] [-s SEED] [-i] [-w WAIT] [-c BRANCH_CHARS]\n" \
+            "                  [-C LEAF_CHARS] [-x WIDTH] [-y HEIGHT] [-t {{0,1,2,3}}]\n" \
+            "                  [-S START_LEN] [-L LEAF_LEN] [-l LAYERS] [-a ANGLE] [-f]"
+    
+    print(usage)
+    print()
+    print(DESC)
+    print()
+    print(OPTION_DESCS)
+    exit()
+
+
+def parse_cli_args():
+    if '-h' in sys.argv or '--help' in sys.argv:
+        _print_help()
+    #convert sys.argv into a dictionary in the form {option_name : option_value}
+    options = Options()
+    default_width, default_height = options.get_default_window()
+
+    parser = argparse.ArgumentParser(
+        description=DESC,
+        epilog = "Based on PyBonsai by Ben Edwards.",
+        add_help=False
+    )
+    parser.add_argument('--version', action='version', version=f'PyBonsai version {VERSION}')
+    parser.add_argument('-s', '--seed', type=int)
+    parser.add_argument('-i', '--instant', action='store_true')
+    parser.add_argument('-w', '--wait', type=float, default=options.wait_time)
+    parser.add_argument('-c', '--branch-chars', type=str, default=options.branch_chars)
+    parser.add_argument('-C', '--leaf-chars', type=str, default=options.leaf_chars)
+    parser.add_argument('-x', '--width', type=int, default=default_width)
+    parser.add_argument('-y', '--height', type=int, default=default_height)
+    parser.add_argument('-t', '--type', type=int, choices=range(4))
+    parser.add_argument('-S', '--start-len', type=int, default=options.initial_len)
+    parser.add_argument('-L', '--leaf-len', type=int, default=options.leaf_len)
+    parser.add_argument('-l', '--layers', type=int, default=options.num_layers)
+    parser.add_argument('-a', '--angle', type=int, default=Options.ANGLE_MEAN)
+    parser.add_argument('-f', '--fixed-window', action='store_true')
+
+    args = parser.parse_args()
+
+    # Update options with parsed arguments
+    options.instant = args.instant
+    options.wait_time = args.wait
+    options.branch_chars = args.branch_chars
+    options.leaf_chars = args.leaf_chars
+    options.window_width = args.width
+    options.window_height = args.height
+    options.initial_len = args.start_len
+    options.leaf_len = args.leaf_len
+    options.num_layers = args.layers
+    options.angle_mean = radians(args.angle)
+    options.fixed_window = args.fixed_window
+
+    if args.seed is not None:
+        options.set_seed(args.seed)
+
+    if args.type is not None:
+        options.type = args.type
+        options.user_set_type = True
+    
+    return options
+
+
+def get_tree(window, options):
+    root_x = window.width // 2
+
+    root_y = tree.Tree.BOX_HEIGHT + 4
+    root_y = root_y + root_y % 2  #round to nearest even number (odd numbers cause off-by-one errors as chars are twice as tall as they are wide)
+
+    root_pos = (root_x, root_y)
+
+    if options.type == 0:
+        t = tree.ClassicTree(window, root_pos, options)
+    elif options.type == 1:
+        t = tree.FibonacciTree(window, root_pos, options)
+    elif options.type == 2:
+        t = tree.OffsetFibTree(window, root_pos, options)
+    else:
+        t = tree.RandomOffsetFibTree(window, root_pos, options)
+
+    return t
+
+
+def main():
+    options = parse_cli_args()
+    window = draw.TerminalWindow(options.window_width, options.window_height, options)
+
+    t = get_tree(window, options)
+
+    t.draw()
+    window.draw()
+    window.reset_cursor()
+
+
+if __name__ == "__main__":
+    main()

pybonsai-0.1.0/pybonsai/draw.py

@@ -0,0 +1,243 @@
+import math
+from . import utils
+import random
+from time import sleep
+
+
+#ANSI escape codes (https://en.wikipedia.org/wiki/ANSI_escape_code)
+END_COLOUR = "\033[00m"
+HIDE_CURSOR = "\033[?25l"  #not supported in all terminals
+SHOW_CURSOR = "\033[?25h"  #not supported in all terminals
+
+CHAR_THRESHOLD = 0.3
+
+
+class TerminalWindow:
+    CHAR_WIDTH = 1
+    CHAR_HEIGHT = 2
+
+    BACKGROUND_CHAR = " "
+
+    def __init__(self, width, height, options):
+        self.width = width
+        self.height = height
+
+        self.options = options
+
+        self.chars = [[TerminalWindow.BACKGROUND_CHAR for _ in range(width)] for _ in range(height)]
+
+    colour_char = lambda self, char, r, g, b: f"\033[38;2;{r};{g};{b}m{char}{END_COLOUR}"  #ANSI escape code for 24 bit true colour (which most modern terminals support)
+
+    def extract_colour(self, coloured_char):
+        #get the rgb colour from an ANSI coloured character
+        splitted = coloured_char.split(";")
+
+        r = int(splitted[2])
+        g = int(splitted[3])
+
+        b = ""
+        for i in splitted[4]:
+            if i == "m":
+                break
+            else:
+                b += i
+
+        b = int(b)
+
+        return r, g, b
+
+    def clear_chars(self):
+        self.chars = [[TerminalWindow.BACKGROUND_CHAR for _ in range(self.width)] for _ in range(self.height)]
+
+    def draw(self):
+        print(HIDE_CURSOR, end="")
+
+        for i in self.chars:
+            print("".join(i))
+
+        print(f"\033[{self.height}A", end="")  #move cursor to the top after we have finished
+        print(SHOW_CURSOR, end="")
+
+        self.needs_clear = True
+
+    def reset_cursor(self):
+        #cursor will have been left at the top from drawing, so we need to place it back at the bottom
+        print(f"\033[{self.height}B", end="")
+
+    def plane_to_screen(self, x, y):
+        #convert cartesian coords to array indices
+        scaled_x = x / TerminalWindow.CHAR_WIDTH
+        scaled_y = y / TerminalWindow.CHAR_HEIGHT
+
+        inx1 = round(self.height - scaled_y)
+        inx2 = round(scaled_x)
+
+        return inx1, inx2
+    
+    def screen_to_plane(self, x, y):
+        #convert array indices to cartesian coords (inverse of plane_to_screen())
+        swapped_x = y
+        swapped_y = self.height - x
+
+        scaled_x = swapped_x * TerminalWindow.CHAR_WIDTH
+        scaled_y = swapped_y * TerminalWindow.CHAR_HEIGHT
+
+        return scaled_x, scaled_y
+    
+    def increase_height(self, delta_height):
+        if self.options.fixed_window:
+            return False
+        
+        self.height += delta_height
+
+        for _ in range(delta_height):
+            self.chars.insert(0, [TerminalWindow.BACKGROUND_CHAR for _ in range(self.width)])
+
+        return True
+
+    def set_char_instant(self, x, y, char, colour, is_screen_coords):
+        if not is_screen_coords:
+            x, y = self.plane_to_screen(x, y)
+
+        #check the point will fit
+        if x < 0:
+            height_changed = self.increase_height(abs(x))
+
+            if height_changed:
+                x = 0
+
+        if not 0 <= x < self.height or not 0 <= y < self.width:
+            return
+
+        coloured = self.colour_char(char, colour[0], colour[1], colour[2])
+        self.chars[x][y] = coloured
+
+    def set_char_wait(self, x, y, char, colour, is_screen_coords, wait_time):
+        #in non instant mode, we want to draw each new character after it is set
+        self.set_char_instant(x, y, char, colour, is_screen_coords)
+
+        self.draw()
+        sleep(wait_time)
+
+    def get_line_char(self, line):
+        theta = line.get_theta()
+
+        upper = math.pi / 2 * (2 / 3)
+        lower = math.pi / 2 * (1 / 3)
+
+        if abs(theta) > upper:
+            return "|"
+        elif abs(theta) < lower:
+            return "_"
+        elif theta > 0:
+            return "/"
+        else:
+            return "\\"
+        
+    def choose_colour(self, colour):
+        if type(colour[0]) == int:
+            #the colour is not a range, so no choice must be made
+            return colour
+        elif len(colour[0]) == 2:
+            #colour should be random with rgb values in the given range
+            rand_colour = []
+            for lower, upper in colour:
+                value = random.randint(lower, upper)
+                rand_colour.append(value)
+
+            return rand_colour
+        else:
+            raise Exception("Invalid colour argument")
+        
+    def draw_steep_line(self, start, end, colour, width, char, mid_line):
+        start_inx, _ = self.plane_to_screen(*start)
+        end_inx, _ = self.plane_to_screen(*end)
+
+        step = 1 if end_inx > start_inx else -1
+
+        for inx1 in range(start_inx, end_inx + step, step):
+            dists = []
+            #get the distance away from the mid line for each cell
+            for inx2 in range(self.width):
+                x, y = self.screen_to_plane(inx1, inx2)
+
+                desired_x = mid_line.get_x(y)
+                dist = abs(desired_x - x)
+
+                dists.append([dist, inx2])
+                
+            #draw the n closest cells (n = width)
+            dists.sort()
+            for i in range(width):
+                if i >= len(dists):
+                    break
+
+                if random.uniform(0, 1) < CHAR_THRESHOLD:
+                    chosen_char = random.choice(self.options.branch_chars)
+                else:
+                    chosen_char = char
+
+                chosen_colour = self.choose_colour(colour)
+
+                if self.options.instant:
+                    self.set_char_instant(inx1, dists[i][1], chosen_char, chosen_colour, True)
+                else:
+                    self.set_char_wait(inx1, dists[i][1], chosen_char, chosen_colour, True, self.options.wait_time)
+
+    def draw_shallow_line(self, start, end, colour, width, char, mid_line):
+        _, start_inx = self.plane_to_screen(*start)
+        _, end_inx = self.plane_to_screen(*end)
+
+        step = 1 if end_inx > start_inx else -1
+
+        for inx2 in range(start_inx, end_inx + step, step):
+            dists = []
+            #get the distance away from the mid line for each cell
+            for inx1 in range(self.height):
+                x, y = self.screen_to_plane(inx1, inx2)
+
+                desired_y = mid_line.get_y(x)
+                dist = abs(desired_y - y)
+
+                dists.append([dist, inx1])
+                
+            #draw the n closest cells (n = width)
+            dists.sort()
+            for i in range(width):
+                if i >= len(dists):
+                    break
+
+                if random.uniform(0, 1) < CHAR_THRESHOLD:
+                    chosen_char = random.choice(self.options.branch_chars)
+                else:
+                    chosen_char = char
+
+                chosen_colour = self.choose_colour(colour)
+
+                if self.options.instant:
+                    self.set_char_instant(dists[i][1], inx2, chosen_char, chosen_colour, True)
+                else:
+                    self.set_char_wait(dists[i][1], inx2, chosen_char, chosen_colour, True, self.options.wait_time)
+
+    def check_line_bounds(self, start, end):
+        #if the line will not fit in the current window, update the window size so that it willoptions
+        h1, _ = self.plane_to_screen(*start)
+        h2, _ = self.plane_to_screen(*end)
+
+        room_from_top = min(h1, h2)
+
+        if room_from_top < 0:
+            self.increase_height(abs(room_from_top))
+    
+    def draw_line(self, start, end, colour, width):
+        mid_line = utils.Line()
+        mid_line.set_end_points(start, end)
+
+        char = self.get_line_char(mid_line)
+
+        self.check_line_bounds(start, end)
+
+        if mid_line.is_vertical or abs(mid_line.m) >= 1:
+            self.draw_steep_line(start, end, colour, width, char, mid_line)
+        else:
+            self.draw_shallow_line(start, end, colour, width, char, mid_line)

pybonsai-0.1.0/pybonsai/tree.py

@@ -0,0 +1,416 @@
+import math
+from . import utils
+import random
+
+
+class Tree:
+    #base tree class - not a drawable tree
+    BOX_HEIGHT = 3
+    MAX_TOP_WIDTH = 35
+
+    MOUND_THRESHOLD = 0.1
+    SOIL_CHAR_THRESHOLD = 0.1
+
+    SOIL_CHARS = ".~*"
+
+    MOUND_WIDTH_MEAN = 2
+    MOUND_WIDTH_STD_DEV = 1
+
+    SOIL_COLOUR = (0, 150, 0)
+    BOX_COLOUR = (200, 200, 200)
+
+    BRANCH_COLOUR = ((200, 255), (150, 255), (0, 0))  #range of rgb values
+
+    def __init__(self, window, root_pos, options):
+        self.window = window
+        self.root_x, self.root_y = root_pos
+        self.options = options
+
+        self.box_top_width = self.get_box_width()
+
+    def get_box_width(self):
+        width = min(self.window.width // 3, Tree.MAX_TOP_WIDTH)
+
+        if width % 2 == 0:
+            width += 1  #width should be odd to allow tree to go in middle
+
+        return width
+
+    def draw_box(self):
+        root_inx1, root_inx2 = self.window.plane_to_screen(self.root_x, self.root_y)
+
+        for i in range(Tree.BOX_HEIGHT):
+            inx1 = root_inx1 + i
+            width = self.box_top_width - i * 2
+
+            for x in range(width):
+                inx2 = root_inx2 - width // 2 + x
+
+                if x == 0:
+                    char = "\\"
+                    colour = Tree.BOX_COLOUR
+                elif x == width - 1:
+                    char = "/"
+                    colour = Tree.BOX_COLOUR
+                elif i == 0:
+                    char = "_"
+                    colour = Tree.SOIL_COLOUR
+                elif i == Tree.BOX_HEIGHT - 1:
+                    char = "_"
+                    colour = Tree.BOX_COLOUR
+                else:
+                    if random.uniform(0, 1) < Tree.SOIL_CHAR_THRESHOLD:
+                        char = random.choice(Tree.SOIL_CHARS)
+                    else:
+                        char = " "
+
+                    colour = Tree.SOIL_COLOUR
+
+                self.window.set_char_instant(inx1, inx2, char, colour, True)
+
+        self.draw_box_feet(root_inx1, root_inx2)
+        self.draw_all_mounds(root_inx1, root_inx2)  #must be called after the top layer has been drawn normally
+
+    def draw_box_feet(self, root_inx1, root_inx2):
+        #draw feet for the box        
+        inx1 = root_inx1 + Tree.BOX_HEIGHT
+        offset = self.box_top_width // 2 - Tree.BOX_HEIGHT - 1
+
+        for sign in range(-1, 2, 2):
+            inx2 = root_inx2 + sign * offset
+            self.window.set_char_instant(inx1, inx2, "‾", Tree.BOX_COLOUR, True)
+
+    def draw_all_mounds(self, root_inx1, root_inx2):
+        #draw .---._____.--. on top layer      
+        num_drawn = 0
+        for i in range(1, self.box_top_width):
+            inx2 = root_inx2 - self.box_top_width // 2 + i
+
+            if random.uniform(0, 1) < Tree.MOUND_THRESHOLD / (num_drawn + 1):
+                num_drawn += 1
+                max_width = self.box_top_width - i - 1
+
+                self.draw_mound(root_inx1, inx2, max_width)
+
+    def draw_mound(self, inx1, start_inx2, max_width):
+        top_width = round(random.normalvariate(Tree.MOUND_WIDTH_MEAN, Tree.MOUND_WIDTH_STD_DEV))
+        top_width = min(top_width, max_width - 2)
+
+        if top_width <= 0:
+            return
+
+        for i in range(top_width + 2):
+            inx2 = start_inx2 + i
+
+            if i == 0 or i == top_width + 1:
+                char = "."
+            else:
+                char = "-"
+
+            self.window.set_char_instant(inx1, inx2, char, Tree.SOIL_COLOUR, True)
+
+    def draw_tree_base(self, trunk_width):
+        #just add some extra padding at the bottom of the trunk to look nice. Must be called after tree is grown
+        inx1, inx2 = self.window.plane_to_screen(self.root_x, self.root_y)
+
+        left_x = inx2 - trunk_width // 2
+        right_x = inx2 + trunk_width // 2
+
+        #off-by-one error: line drawing moves left to right, causing trunk to be to the left of the center, so move the base right to compensate
+        if trunk_width % 2 == 0:
+            right_x -= 1
+
+        self.window.set_char_instant(inx1, left_x - 2, ".", (255, 255, 0), True)
+        self.window.set_char_instant(inx1, left_x - 1, "/", (255, 255, 0), True)
+        self.window.set_char_instant(inx1, right_x + 1, "\\", (255, 255, 0), True)
+        self.window.set_char_instant(inx1, right_x + 2, ".", (255, 255, 0), True)
+
+
+class RecursiveTree(Tree):
+    #all recursive tree types are based off of the fractal canopy: https://en.wikipedia.org/wiki/Fractal_canopy
+    ANGLE_STD_DEV = math.radians(8)
+
+    LEN_SCALE = 0.75
+
+    MAX_INITIAL_WIDTH = 6
+
+    def __init__(self, window, root_pos, options):
+        super().__init__(window, root_pos, options)
+
+    def get_end_coords(self, start_x, start_y, length, theta):
+        x = start_x + length * math.sin(theta)
+        y = start_y + length * math.cos(theta)
+
+        return x, y
+    
+    def get_initial_params(self):
+        initial_width = self.options.initial_len // 5
+        initial_angle = random.normalvariate(0, RecursiveTree.ANGLE_STD_DEV)
+
+        #ensure the width is in a suitable range
+        initial_width = max(0, initial_width)
+        initial_width = min(RecursiveTree.MAX_INITIAL_WIDTH, initial_width)
+
+        return initial_width, initial_angle
+
+
+class ClassicTree(RecursiveTree):
+    #trees with a random number of branches on each layer
+    MEAN_BRANCHES = 2
+    BRANCHES_STD_DEV = 0.5
+
+    def __init__(self, window, root_pos, options):
+        super().__init__(window, root_pos, options)
+
+    def draw_branch(self, x, y, layer, length, width, theta):
+        if layer >= self.options.num_layers:
+            leaves = Leaves(self.window, (x, y), self.options)
+            leaves.draw()
+
+            return
+        
+        end_x, end_y = self.get_end_coords(x, y, length, theta)
+
+        self.window.draw_line((x, y), (end_x, end_y), ClassicTree.BRANCH_COLOUR, round(width))
+
+        self.draw_end_branches(x, y, layer, length, width, theta)
+
+    def draw_end_branches(self, start_x, start_y, layer, length, width, theta):
+        sign = 1
+        num_branches = max(0, round(random.normalvariate(ClassicTree.MEAN_BRANCHES, ClassicTree.BRANCHES_STD_DEV)))
+
+        step = length / num_branches if num_branches != 0 else 0
+
+        new_width = max(1, width - 1)
+        new_length = length * ClassicTree.LEN_SCALE
+
+        for i in range(num_branches):
+            dist_up_branch = (i + 1) * step  #branches are linearly distributed along the parent
+            new_theta = theta + sign * random.normalvariate(self.options.angle_mean, ClassicTree.ANGLE_STD_DEV)
+
+            x, y = self.get_end_coords(start_x, start_y, dist_up_branch, theta)  #start point of new branch
+
+            self.draw_branch(x, y, layer + 1, new_length, new_width, new_theta)
+
+            sign *= -1  #ensure next branch is on opposite side of the parent
+
+    def draw(self):
+        initial_width, initial_angle = self.get_initial_params()
+
+        self.draw_box()
+        self.draw_tree_base(initial_width)
+
+        self.draw_branch(self.root_x, self.root_y, 1, self.options.initial_len, initial_width, initial_angle)
+
+
+class FibonacciTree(RecursiveTree):
+    #trees with a fibonacci number of branches on each layer
+    def __init__(self, window, root_pos, options):
+        super().__init__(window, root_pos, options)
+
+        self.fib = self.fib_nums()
+        self.branch_nums = self.generate_branch_nums()
+
+    def fib_nums(self):
+        fib = [1, 1]
+
+        for _ in range(self.options.num_layers):
+            fib.append(fib[-1] + fib[-2])
+
+        return fib
+    
+    def generate_branch_nums(self):
+        #generate the number of child branches branching off of each parent
+        branch_nums = [[1]]  #1st index is the layer from the root, 2nd index is the position of the parent branch in its layer
+        for i in range(self.options.num_layers):
+            num_branches = self.fib[i + 2]
+            num_parents = sum(branch_nums[-1])
+
+            base = num_branches // num_parents
+            diff = num_branches - base * num_parents
+
+            current_nums = [base + 1 if x < diff else base for x in range(num_parents)]
+
+            random.shuffle(current_nums)
+
+            branch_nums.append(current_nums)
+
+        return branch_nums
+    
+    def draw_branch(self, x, y, layer_inx, branch_inx, length, width, theta):
+        if layer_inx > self.options.num_layers:
+            leaf = Leaves(self.window, (x, y), self.options)
+            leaf.draw()
+
+            return
+        
+        end_x, end_y = self.get_end_coords(x, y, length, theta)
+
+        self.window.draw_line((x, y), (end_x, end_y), FibonacciTree.BRANCH_COLOUR, round(width))
+
+        self.draw_end_branches(x, y, layer_inx, branch_inx, length, width, theta)
+
+    def draw_end_branches(self, start_x, start_y, layer_inx, branch_inx, length, width, theta):
+        #draw the child branches off of the end of the parent branch
+        sign = 1
+        num_branches = self.branch_nums[layer_inx][branch_inx]
+        new_width = max(1, width - 1)
+
+        x, y = self.get_end_coords(start_x, start_y, length, theta)
+
+        for i in range(num_branches):
+            angle = random.normalvariate(self.options.angle_mean, FibonacciTree.ANGLE_STD_DEV)
+            new_theta = theta + sign * angle
+
+            new_len = length * FibonacciTree.LEN_SCALE
+
+            self.draw_branch(x, y, layer_inx + 1, branch_inx + i, new_len, new_width, new_theta)
+ 
+            sign *= -1
+
+    def draw(self):
+        initial_width, initial_angle = self.get_initial_params()
+
+        self.draw_box()
+        self.draw_tree_base(initial_width)
+
+        self.draw_branch(self.root_x, self.root_y, 1, 0, self.options.initial_len, initial_width, initial_angle)
+
+
+class OffsetFibTree(FibonacciTree):
+    #similar to fibonacci tree, but branches grow from the middle of the parent branch
+    def __init__(self, window, root_pos, options):
+        super().__init__(window, root_pos, options)
+
+    def draw_end_branches(self, start_x, start_y, layer_inx, branch_inx, length, width, theta):
+        sign = 1
+        num_branches = self.branch_nums[layer_inx][branch_inx]
+
+        step = length / num_branches if num_branches != 0 else 0
+
+        new_width = max(1, width - 1)
+        new_length = length * ClassicTree.LEN_SCALE
+
+        for i in range(num_branches):
+            dist_up_branch = (i + 1) * step  #branches are now linearly distributed along the parent branch
+            new_theta = theta + sign * random.normalvariate(self.options.angle_mean, OffsetFibTree.ANGLE_STD_DEV)
+
+            x, y = self.get_end_coords(start_x, start_y, dist_up_branch, theta)
+
+            self.draw_branch(x, y, layer_inx + 1, branch_inx + i, new_length, new_width, new_theta)
+
+            sign *= -1
+
+
+class RandomOffsetFibTree(FibonacciTree):
+    #an offset fib tree, but the branches are randomly placed along parent branch and leaves can grow on non end branches
+    GROW_END_THRESHOLD = 0.5
+
+    NON_END_MIN = 0.3
+    NON_END_MAX = 0.9
+
+    def __init__(self, window, root_pos, options):
+        super().__init__(window, root_pos, options)
+
+    def draw_end_branches(self, start_x, start_y, layer_inx, branch_inx, length, width, theta):
+        sign = 1
+        num_branches = self.branch_nums[layer_inx][branch_inx]
+
+        new_width = max(1, width - 1)
+        new_length = length * ClassicTree.LEN_SCALE
+
+        need_leaves = True
+        for i in range(num_branches):
+            grow_at_end = random.uniform(0, 1) < RandomOffsetFibTree.GROW_END_THRESHOLD
+
+            if grow_at_end:
+                #this branch will grow at the end of the parent, so do not draw leaves at the end of the parent
+                need_leaves = False
+                dist_up_branch = length
+            else:
+                #this branch will grow at a random distance along the parent (not the end), so we may need leaves at the end of the parent
+                dist_up_branch = random.uniform(length * RandomOffsetFibTree.NON_END_MIN, length * RandomOffsetFibTree.NON_END_MAX)
+
+            new_theta = theta + sign * random.normalvariate(self.options.angle_mean, OffsetFibTree.ANGLE_STD_DEV)
+
+            x, y = self.get_end_coords(start_x, start_y, dist_up_branch, theta)
+
+            self.draw_branch(x, y, layer_inx + 1, branch_inx + i, new_length, new_width, new_theta)
+
+            sign *= -1
+
+        if need_leaves:
+            #no branches have grown at the end of the parent, so we can grow leaves
+            end_pos = self.get_end_coords(start_x, start_y, length, theta)
+
+            leaves = Leaves(self.window, end_pos, self.options)
+            leaves.draw()
+
+
+class FractalTree(RecursiveTree):
+    """A simple recursive tree that splits into two branches at the end of each branch."""
+    NUM_BRANCHES = 2
+
+    def __init__(self, window, root_pos, options):
+        super().__init__(window, root_pos, options)
+
+    def draw_branch(self, x, y, layer, length, width, theta):
+        if layer >= self.options.num_layers:
+            leaves = Leaves(self.window, (x, y), self.options)
+            leaves.draw()
+            return
+        
+        end_x, end_y = self.get_end_coords(x, y, length, theta)
+        self.window.draw_line((x, y), (end_x, end_y), Tree.BRANCH_COLOUR, round(width))
+        self.draw_end_branches(x, y, layer, length, width, theta)
+
+    def draw_end_branches(self, start_x, start_y, layer, length, width, theta):
+        sign = 1
+        new_width = max(1, width - 1)
+        new_length = length * self.LEN_SCALE
+
+        x, y = self.get_end_coords(start_x, start_y, length, theta)
+
+        for _ in range(self.NUM_BRANCHES):
+            angle = random.normalvariate(self.options.angle_mean, self.ANGLE_STD_DEV)
+            new_theta = theta + sign * angle
+            self.draw_branch(x, y, layer + 1, new_length, new_width, new_theta)
+            sign *= -1
+
+    def draw(self):
+        initial_width, initial_angle = self.get_initial_params()
+        self.draw_box()
+        self.draw_tree_base(initial_width)
+        self.draw_branch(self.root_x, self.root_y, 1, self.options.initial_len, initial_width, initial_angle)
+
+
+class Leaves:
+    NUM_LEAVES = 4
+
+    def __init__(self, window, branch_end, options):
+        self.window = window
+        self.branch_x, self.branch_y = branch_end
+        self.options = options
+
+    def draw(self):
+        g = utils.Vector(0, -1)
+
+        for _ in range(Leaves.NUM_LEAVES):
+            vel = utils.Vector(random.uniform(-1, 1), random.uniform(-1, 1))  #random starting velocity for the leaves to step along
+            vel.normalise()
+            pos = utils.Vector(self.branch_x, self.branch_y)
+
+            for i in range(self.options.leaf_len):
+                pos += vel
+
+                colour = (0, random.randint(75, 255), 0)
+                char = random.choice(self.options.leaf_chars)
+
+                if self.options.instant:
+                    self.window.set_char_instant(pos.x, pos.y, char, colour, False)
+                else:
+                    self.window.set_char_wait(pos.x, pos.y, char, colour, False, self.options.wait_time)
+
+                #make the leaves droop downwards by adding some gravity force
+                weight = i / self.options.leaf_len
+                vel += g * weight

pybonsai-0.1.0/pybonsai/utils.py

@@ -0,0 +1,66 @@
+import math
+
+
+class Line:
+    #line in form y = mx + c
+    def __init__(self):
+        self.start = None
+        self.end = None
+
+        self.m = None
+        self.c = None
+
+        self.is_vertical = False
+
+    def get_y(self, x):
+        if not self.is_vertical:
+            return self.m * x + self.c
+        
+    def get_x(self, y):
+        if self.is_vertical:
+            return self.c
+        elif self.m != 0:
+            return (y - self.c) / self.m
+
+    def set_end_points(self, start, end):
+        self.start = start
+        self.end = end
+
+        if self.start[0] == self.end[0]:
+            self.is_vertical = True
+            self.m = None
+            self.c = self.start[0]
+        else:
+            self.m = (self.start[1] - self.end[1]) / (self.start[0] - self.end[0])
+            self.c = self.start[1] - self.m * self.start[0]
+
+    def set_gradient(self, m, point):
+        self.m = m
+        self.c = point[1] - m * point[0]
+    
+    def get_theta(self):
+        #get angle above x axis
+        if self.is_vertical:
+            return math.pi / 2
+        else:
+            return math.atan(self.m)
+
+
+class Vector:
+    def __init__(self, x, y):
+        self.x = x
+        self.y = y
+
+    mag = lambda self: (self.x**2 + self.y**2)**0.5
+
+    def __iadd__(self, other_vec):
+        return Vector(self.x + other_vec.x, self.y + other_vec.y)
+    
+    def __mul__(self, scalar):
+        return Vector(self.x * scalar, self.y * scalar)
+    
+    def normalise(self):
+        m = self.mag()
+
+        self.x /= m
+        self.y /= m

pybonsai-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "pybonsai"
+version = "0.1.0"
+description = "A project that generates ASCII art trees in your terminal."
+license = {text = "MIT"}
+readme = "README.md"
+requires-python = ">=3.9"
+keywords = ["pybonsai"]
+authors = [
+    {name = "Ben Edwards"},
+    {name = "Ivan Karlov", email = "karlovivan679@gmail.com"}
+]
+classifiers = [
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+[project.scripts]
+pybonsai = "pybonsai.__main__:main"
+
+[project.urls]
+"Source" = "https://github.com/DaEtoJostka/PyBonsai"
+"Original" = "https://github.com/Ben-Edwards44/PyBonsai"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["pybonsai"]

pybonsai-0.1.0/uv.lock

@@ -0,0 +1,8 @@
+version = 1
+revision = 2
+requires-python = ">=3.9"
+
+[[package]]
+name = "pybonsai"
+version = "0.1.0"
+source = { editable = "." }