Stochastic Recursive Fractal Tree

Math essence

Iterative stack-based recursion (avoids Python recursion limit). For each branch at heading h and length L: x2 = x + L*cos(h), y2 = y + L*sin(h). Children: n = randint(n_min, n_max+1), angle = +/- jitter_angle drawn from uniform[a-j, a+j] or normal(a, j). Branch stamped to canvas with a disk brush of thickness that decays geometrically per level. Leaves stamped when leaf_size>0 at terminal branches.

Parameters

Reference

First 60 lines of reference.py. Full source: library_external/shiffman_pearson_textbook/recursiveTree/reference.py

from __future__ import annotations

from typing import ClassVar

import numpy as np


class RecursiveTree:
    """Stochastic recursive fractal tree — Nature of Code Ch. 8, Example 8.7.

    Builds a branching fractal tree from a stack-based recursion. The root
    trunk grows upward; at each generation it produces ``n_branches`` child
    branches, each rotated by an angle drawn from a normal distribution
    centered at ``branch_angle_deg`` with spread ``angle_jitter_deg`` (or a
    uniform distribution in ``[-angle_jitter_deg, +angle_jitter_deg]`` when
    ``jitter_mode='uniform'`` — the textbook default). Each child's length
    is the parent's length multiplied by ``length_decay``. Recursion stops
    when the branch length drops below ``min_length`` (8 levels by default).

    This is the textbook stochastic fractal tree from Shiffman's Example 8.7
    'A Stochastic Tree', and is also covered in Pearson's *Generative Art*
    as a Python/Processing canonical motif.

    ``step(n)`` does not strictly evolve — the tree is grown once and the
    canvas is reused — but each call advances the random seed and re-grows
    the tree, producing a new stochastic tree image so the corpus has
    variation across step indices.
    """

    family: ClassVar[str] = "shiffman_pearson_textbook"
    sketch: ClassVar[str] = "recursiveTree"

    def __init__(
        self,
        dim: int = 600,
        root_length: float = 130.0,
        length_decay: float = 0.72,
        branch_angle_deg: float = 25.0,
        angle_jitter_deg: float = 15.0,
        jitter_mode: str = "uniform",
        n_branches_min: int = 2,
        n_branches_max: int = 3,
        levels: int = 8,
        trunk_thickness: float = 4.0,
        thickness_decay: float = 0.72,
        bg_color: tuple[int, int, int] = (245, 240, 230),
        ink_color: tuple[int, int, int] = (50, 35, 25),
        leaf_color: tuple[int, int, int] | None = None,
        leaf_size: float = 0.0,
        seed: int | None = None,
    ) -> None:
        self.dim = dim
        self.root_length = root_length
        self.length_decay = length_decay
        self.branch_angle_deg = branch_angle_deg
        self.angle_jitter_deg = angle_jitter_deg
        self.jitter_mode = jitter_mode
        self.n_branches_min = n_branches_min
        self.n_branches_max = n_branches_max
        self.levels = levels