PlantArchitecture.py

Go to the documentation of this file.

"""
High-level PlantArchitecture interface for PyHelios.
 
This module provides a user-friendly interface to the plant architecture modeling
capabilities with graceful plugin handling and informative error messages.
"""
 
import functools
import logging
import math
import os
import weakref
from contextlib import contextmanager
from pathlib import Path
from typing import Any, Callable, Dict, List, Optional, Union
 
from .Context import Context, check_context_alive
from .exceptions import HeliosInvalidArgumentError
from .plugins.registry import get_plugin_registry, require_plugin
from .wrappers import UPlantArchitectureWrapper as plantarch_wrapper
from .wrappers.DataTypes import vec3, vec2, int2, AxisRotation
try:
    from .validation.datatypes import validate_vec3, validate_vec2, validate_int2
except ImportError:
    # Fallback validation functions for when validation module is not available
    def validate_vec3(value, name, func):
        if hasattr(value, 'x') and hasattr(value, 'y') and hasattr(value, 'z'):
            return value
        if isinstance(value, (list, tuple)) and len(value) == 3:
            from .wrappers.DataTypes import vec3
            return vec3(*value)
        raise ValueError(f"{name} must be vec3 or 3-element list/tuple")
 
    def validate_vec2(value, name, func):
        if hasattr(value, 'x') and hasattr(value, 'y'):
            return value
        if isinstance(value, (list, tuple)) and len(value) == 2:
            from .wrappers.DataTypes import vec2
            return vec2(*value)
        raise ValueError(f"{name} must be vec2 or 2-element list/tuple")
 
    def validate_int2(value, name, func):
        if hasattr(value, 'x') and hasattr(value, 'y'):
            return value
        if isinstance(value, (list, tuple)) and len(value) == 2:
            from .wrappers.DataTypes import int2
            return int2(*value)
        raise ValueError(f"{name} must be int2 or 2-element list/tuple")
from .validation.core import validate_positive_value
from .assets import get_asset_manager
from .plant_architecture_params import (
    BudState,
    PhytomerParameters,
    ShootParameters,
    CarbohydrateParameters,
    NitrogenParameters,
    RandomParameter,
    RandomParameterFloat,
    RandomParameterInt,
)
 
logger = logging.getLogger(__name__)
 
 
def _validate_build_parameters(build_parameters: Optional[dict], plant_model: Optional[str],
                               accepted: Optional[List[str]] = None) -> None:
    """Check build parameter types, and names against those the plant model accepts.
 
    The native library also rejects a name the model does not accept, but raising here
    gives callers a ValueError like every other argument check, before anything is built.
 
    Args:
        build_parameters: Mapping supplied by the caller, or None.
        plant_model: Label of the currently loaded model, used in the error message.
        accepted: Names the model accepts, from getPlantModelBuildParameterNames(), or None
            to check types only (the native library still checks the names).
 
    Raises:
        ValueError: If build_parameters is not a dict of str -> number, or contains a key
            the model does not accept.
    """
    if build_parameters is None:
        return
 
    if not isinstance(build_parameters, dict):
        raise ValueError("build_parameters must be a dict or None")
 
    for key, value in build_parameters.items():
        if not isinstance(key, str):
            raise ValueError("build_parameters keys must be strings")
        if isinstance(value, bool) or not isinstance(value, (int, float)):
            raise ValueError("build_parameters values must be numeric (int or float)")
 
    if not build_parameters or accepted is None:
        return
 
    unknown = sorted(set(build_parameters) - set(accepted))
    if not unknown:
        return
 
    if accepted:
        accepted_description = f"accepts only: {', '.join(accepted)}"
    else:
        accepted_description = "accepts no build parameters"
 
    raise ValueError(
        f"Unknown build parameter(s) {', '.join(repr(k) for k in unknown)}. "
        f"Plant model '{plant_model}' {accepted_description}."
    )
 
 
def _resolve_user_path(filepath: Union[str, Path]) -> str:
    """
    Convert relative paths to absolute paths before changing working directory.
 
    This preserves the user's intended file location when the working directory
    is temporarily changed for C++ asset access. Absolute paths are returned unchanged.
 
    Args:
        filepath: File path to resolve (string or Path object)
 
    Returns:
        Absolute path as string
    """
    path = Path(filepath)
    if not path.is_absolute():
        return str(Path.cwd() / path)
    return str(path)
 
 
@contextmanager
def _plantarchitecture_working_directory():
    """
    Context manager that temporarily changes working directory to where PlantArchitecture assets are located.
 
    PlantArchitecture C++ code uses hardcoded relative paths like "plugins/plantarchitecture/assets/textures/"
    expecting assets relative to working directory. This manager temporarily changes to the build directory
    where assets are actually located.
 
    Raises:
        RuntimeError: If build directory or PlantArchitecture assets are not found, indicating a build system error.
    """
    # Find the build directory containing PlantArchitecture assets
    # Try asset manager first (works for both development and wheel installations)
    asset_manager = get_asset_manager()
    working_dir = asset_manager._get_helios_build_path()
 
    if working_dir and working_dir.exists():
        plantarch_assets = working_dir / 'plugins' / 'plantarchitecture'
    else:
        # For wheel installations, check packaged assets
        current_dir = Path(__file__).parent
        packaged_build = current_dir / 'assets' / 'build'
 
        if packaged_build.exists():
            working_dir = packaged_build
            plantarch_assets = working_dir / 'plugins' / 'plantarchitecture'
        else:
            # Fallback to development paths
            repo_root = current_dir.parent
            build_lib_dir = repo_root / 'pyhelios_build' / 'build' / 'lib'
            working_dir = build_lib_dir.parent
            plantarch_assets = working_dir / 'plugins' / 'plantarchitecture'
 
            if not build_lib_dir.exists():
                raise RuntimeError(
                    f"PyHelios build directory not found at {build_lib_dir}. "
                    f"PlantArchitecture requires native libraries to be built. "
                    f"Run: build_scripts/build_helios --plugins plantarchitecture"
                )
 
    if not plantarch_assets.exists():
        raise RuntimeError(
            f"PlantArchitecture assets not found at {plantarch_assets}. "
            f"Build system failed to copy PlantArchitecture assets. "
            f"Run: build_scripts/build_helios --clean --plugins plantarchitecture"
        )
 
    # Verify essential assets exist
    assets_dir = plantarch_assets / 'assets'
    if not assets_dir.exists():
        raise RuntimeError(
            f"PlantArchitecture assets directory not found: {assets_dir}. "
            f"Essential assets missing. Rebuild with: "
            f"build_scripts/build_helios --clean --plugins plantarchitecture"
        )
 
    # Change to the build directory temporarily
    original_dir = os.getcwd()
    try:
        os.chdir(working_dir)
        logger.debug(f"Changed working directory to {working_dir} for PlantArchitecture asset access")
        yield working_dir
    finally:
        os.chdir(original_dir)
        logger.debug(f"Restored working directory to {original_dir}")
 
 
class PlantArchitectureError(Exception):
    """Raised when PlantArchitecture operations fail."""
    pass
 
 
def is_plantarchitecture_available():
    """
    Check if PlantArchitecture plugin is available for use.
 
    Returns:
        bool: True if PlantArchitecture can be used, False otherwise
    """
    try:
        # Check plugin registry
        plugin_registry = get_plugin_registry()
        if not plugin_registry.is_plugin_available('plantarchitecture'):
            return False
 
        # Check if wrapper functions are available
        if not plantarch_wrapper._PLANTARCHITECTURE_FUNCTIONS_AVAILABLE:
            return False
 
        return True
    except Exception:
        return False
 
 
def _surfaces_phytomer_callback_errors(method):
    """Re-raise an exception from a Python phytomer creation or callback function out of the call that ran it.
 
    ctypes cannot propagate an exception out of a callback, so the trampolines built by
    :meth:`PlantArchitecture.setPhytomerCreationFunction` and :meth:`PlantArchitecture.setPhytomerCallbackFunction`
    store it and make the native call fail; this decorator then raises the stored exception in place of the
    resulting native error.
    """
    @functools.wraps(method)
    def wrapper(self, *args, **kwargs):
        self._pending_callback_error = None
        try:
            result = method(self, *args, **kwargs)
        except Exception as native_error:
            self._raise_pending_callback_error(native_error)
            raise
        self._raise_pending_callback_error()
        return result
    return wrapper
 
 
class PlantArchitecture:
    """
    High-level interface for plant architecture modeling and procedural plant generation.
 
    PlantArchitecture provides access to the comprehensive plant library with 25+ plant models
    including trees (almond, apple, olive, walnut), crops (bean, cowpea, maize, rice, soybean),
    and other plants. This class enables procedural plant generation, time-based growth
    simulation, and plant community modeling.
 
    This class requires the native Helios library built with PlantArchitecture support.
    Use context managers for proper resource cleanup.
 
    Example:
        >>> with Context() as context:
        ...     with PlantArchitecture(context) as plantarch:
        ...         plantarch.loadPlantModelFromLibrary("bean")
        ...         plant_id = plantarch.buildPlantInstanceFromLibrary(base_position=vec3(0, 0, 0), age=30)
        ...         plantarch.advanceTime(10.0)  # Grow for 10 days
    """
 
    def __new__(cls, context=None):
        """
        Create PlantArchitecture instance.
        Explicit __new__ to prevent ctypes contamination on Windows.
        """
        return object.__new__(cls)
 
    def __init__(self, context: Context):
        """
        Initialize PlantArchitecture with a Helios context.
 
        Args:
            context: Active Helios Context instance
 
        Raises:
            PlantArchitectureError: If plugin not available in current build
            RuntimeError: If plugin initialization fails
        """
        # Check plugin availability
        registry = get_plugin_registry()
        if not registry.is_plugin_available('plantarchitecture'):
            raise PlantArchitectureError(
                "PlantArchitecture not available in current Helios library. "
                "Rebuild PyHelios with PlantArchitecture support:\n"
                "  build_scripts/build_helios --plugins plantarchitecture\n"
                "\n"
                "System requirements:\n"
                f"  - Platforms: Windows, Linux, macOS\n"
                "  - Dependencies: Extensive asset library (textures, OBJ models)\n"
                "  - GPU: Not required\n"
                "\n"
                "Plant library includes 25+ models: almond, apple, bean, cowpea, maize, "
                "rice, soybean, tomato, wheat, and many others."
            )
 
        self.context = context
        self._plantarch_ptr = None
        # Label passed to the most recent loadPlantModelFromLibrary(), used to validate
        # build parameters against the model that actually consumes them.
        self._current_plant_model = None
 
        # Create PlantArchitecture instance with asset-aware working directory
        with _plantarchitecture_working_directory():
            self._plantarch_ptr = plantarch_wrapper.createPlantArchitecture(context.getNativePtr())
 
        if not self._plantarch_ptr:
            raise PlantArchitectureError("Failed to initialize PlantArchitecture")
 
    def _check_context_alive(self):
        """Raise if the owning Context has been destroyed (see Context.check_context_alive)."""
        check_context_alive(getattr(self, "context", None), "PlantArchitecture")
 
    def __enter__(self):
        """Context manager entry"""
        return self
 
    def __exit__(self, exc_type, exc_val, exc_tb):
        """Context manager exit - cleanup resources"""
        if hasattr(self, '_plantarch_ptr') and self._plantarch_ptr:
            plantarch_wrapper.destroyPlantArchitecture(self._plantarch_ptr)
            self._plantarch_ptr = None
 
    def __del__(self):
        """Destructor to ensure C++ resources freed even without 'with' statement."""
        if hasattr(self, '_plantarch_ptr') and self._plantarch_ptr is not None:
            try:
                plantarch_wrapper.destroyPlantArchitecture(self._plantarch_ptr)
                self._plantarch_ptr = None
            except Exception as e:
                import warnings
                warnings.warn(f"Error in PlantArchitecture.__del__: {e}")
 
    def loadPlantModelFromLibrary(self, plant_label: str) -> None:
        """
        Load a plant model from the built-in library.
 
        Args:
            plant_label: Plant model identifier from library. Available models include:
                       "almond", "apple", "bean", "bindweed", "butterlettuce", "capsicum",
                       "cheeseweed", "cowpea", "easternredbud", "grapevine_VSP", "maize",
                       "olive", "pistachio", "puncturevine", "rice", "sorghum", "soybean",
                       "strawberry", "sugarbeet", "tomato", "cherrytomato", "walnut", "wheat"
 
        Raises:
            ValueError: If plant_label is empty or invalid
            PlantArchitectureError: If model loading fails
 
        Example:
            >>> plantarch.loadPlantModelFromLibrary("bean")
            >>> plantarch.loadPlantModelFromLibrary("almond")
        """
        if not plant_label:
            raise ValueError("Plant label cannot be empty")
 
        if not plant_label.strip():
            raise ValueError("Plant label cannot be only whitespace")
 
        self._reject_inside_phytomer_callback("loadPlantModelFromLibrary")
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                plantarch_wrapper.loadPlantModelFromLibrary(self._plantarch_ptr, plant_label.strip())
        except Exception as e:
            raise PlantArchitectureError(f"Failed to load plant model '{plant_label}': {e}")
 
        self._current_plant_model = plant_label.strip()
 
    def _validate_build_parameters(self, build_parameters: Optional[dict]) -> None:
        """Validate build parameters against the names the loaded model declares natively."""
        accepted = None
        if isinstance(build_parameters, dict) and build_parameters and self._current_plant_model is not None:
            accepted = self.getPlantModelBuildParameterNames(self._current_plant_model)
        _validate_build_parameters(build_parameters, self._current_plant_model, accepted)
 
    @_surfaces_phytomer_callback_errors
    def buildPlantInstanceFromLibrary(self, base_position: vec3, age: float,
                                     build_parameters: Optional[dict] = None) -> int:
        """
        Build a plant instance from the currently loaded library model.
 
        Args:
            base_position: Cartesian (x,y,z) coordinates of plant base as vec3
            age: Age of the plant in days (must be >= 0)
            build_parameters: Optional dict of species-specific parameter overrides, such
                            as trellis dimensions, trunk height and scaffold count, grape
                            cluster size, or sorghum tillers and panicle form. Only some models
                            accept them, and a key the model does not accept raises ValueError:
                            - almond, almond_independence, apple, pistachio, walnut:
                              trunk_height, num_scaffolds, scaffold_angle
                            - grapevine_VSP: vine_spacing, trunk_height, berry_diameter,
                              cluster_berry_count
                            - grapevine_Wye: trunk_height, cordon_spacing, vine_spacing,
                              catch_wire_height, berry_diameter, cluster_berry_count
                            - sorghum: tiller_count, panicle_type, and the panicle form,
                              grain and glume keys
                            All other models accept none. getPlantModelBuildParameterNames()
                            returns the full list for a model. Out-of-range or non-finite
                            values, and fractional values for parameters that count something
                            (e.g. num_scaffolds, tiller_count), raise PlantArchitectureError.
                            The plant keeps its build parameters (see getPlantBuildParameters()).
 
        Returns:
            Plant ID for the created plant instance
 
        Raises:
            ValueError: If age is negative or build_parameters is invalid
            PlantArchitectureError: If plant building fails
            RuntimeError: If no model has been loaded
 
        Example:
            >>> plant_id = plantarch.buildPlantInstanceFromLibrary(base_position=vec3(2.0, 3.0, 0.0), age=45.0)
            >>> # With custom parameters
            >>> plant_id = plantarch.buildPlantInstanceFromLibrary(
            ...     base_position=vec3(0, 0, 0),
            ...     age=30.0,
            ...     build_parameters={'trunk_height': 2.0}
            ... )
        """
        # Parameter type validation
        if not isinstance(base_position, vec3):
            raise ValueError(f"base_position must be a vec3, got {type(base_position).__name__}")
 
        # Convert position to list for C++ interface
        position_list = [base_position.x, base_position.y, base_position.z]
 
        # Validate age (allow zero)
        if age < 0:
            raise ValueError(f"Age must be non-negative, got {age}")
 
        self._validate_build_parameters(build_parameters)
 
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                return plantarch_wrapper.buildPlantInstanceFromLibrary(
                    self._plantarch_ptr, position_list, age, build_parameters
                )
        except Exception as e:
            raise PlantArchitectureError(f"Failed to build plant instance: {e}")
 
    @_surfaces_phytomer_callback_errors
    def buildPlantCanopyFromLibrary(self, canopy_center: vec3,
                                  plant_spacing: vec2,
                                  plant_count: int2, age: float,
                                  germination_rate: float = 1.0,
                                  build_parameters: Optional[dict] = None) -> List[int]:
        """
        Build a canopy of regularly spaced plants from the currently loaded library model.
 
        Args:
            canopy_center: Cartesian (x,y,z) coordinates of canopy center as vec3
            plant_spacing: Spacing between plants in x- and y-directions (meters) as vec2
            plant_count: Number of plants in x- and y-directions as int2
            age: Age of all plants in days (must be >= 0)
            germination_rate: Probability that each plant position will be occupied (0 to 1).
                            A value of 1.0 means all positions are filled; 0.5 means roughly
                            half the positions will have plants. Default is 1.0.
            build_parameters: Optional dict of species-specific parameter overrides,
                            applied to every plant in the canopy. Only some models
                            accept them, and a key the model does not accept raises ValueError.
                            See buildPlantInstanceFromLibrary() for the per-model list.
 
        Returns:
            List of plant IDs for the created plant instances
 
        Raises:
            ValueError: If age is negative, germination_rate is not in [0, 1],
                       plant count values are not positive, or build_parameters is invalid
            PlantArchitectureError: If canopy building fails
 
        Example:
            >>> # 3x3 canopy with 0.5m spacing, 30-day-old plants
            >>> plant_ids = plantarch.buildPlantCanopyFromLibrary(
            ...     canopy_center=vec3(0, 0, 0),
            ...     plant_spacing=vec2(0.5, 0.5),
            ...     plant_count=int2(3, 3),
            ...     age=30.0
            ... )
            >>> # With 80% germination rate and custom parameters
            >>> plant_ids = plantarch.buildPlantCanopyFromLibrary(
            ...     canopy_center=vec3(0, 0, 0),
            ...     plant_spacing=vec2(1.5, 2.0),
            ...     plant_count=int2(5, 3),
            ...     age=45.0,
            ...     germination_rate=0.8,
            ...     build_parameters={'trunk_height': 1.8}
            ... )
        """
        # Parameter type validation
        if not isinstance(canopy_center, vec3):
            raise ValueError(f"canopy_center must be a vec3, got {type(canopy_center).__name__}")
        if not isinstance(plant_spacing, vec2):
            raise ValueError(f"plant_spacing must be a vec2, got {type(plant_spacing).__name__}")
        if not isinstance(plant_count, int2):
            raise ValueError(f"plant_count must be an int2, got {type(plant_count).__name__}")
 
        # Validate age (allow zero)
        if age < 0:
            raise ValueError(f"Age must be non-negative, got {age}")
 
        # Validate germination rate
        if not isinstance(germination_rate, (int, float)):
            raise ValueError(f"germination_rate must be a number, got {type(germination_rate).__name__}")
        if germination_rate < 0 or germination_rate > 1:
            raise ValueError(f"germination_rate must be between 0 and 1, got {germination_rate}")
 
        # Validate count values
        if plant_count.x <= 0 or plant_count.y <= 0:
            raise ValueError("Plant count values must be positive integers")
 
        self._validate_build_parameters(build_parameters)
 
        # Convert to lists for C++ interface
        center_list = [canopy_center.x, canopy_center.y, canopy_center.z]
        spacing_list = [plant_spacing.x, plant_spacing.y]
        count_list = [plant_count.x, plant_count.y]
 
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                return plantarch_wrapper.buildPlantCanopyFromLibrary(
                    self._plantarch_ptr, center_list, spacing_list, count_list, age,
                    germination_rate, build_parameters
                )
        except Exception as e:
            raise PlantArchitectureError(f"Failed to build plant canopy: {e}")
 
    @_surfaces_phytomer_callback_errors
    def advanceTime(self, dt: float, plant_id: Optional[int] = None,
                    plant_ids: Optional[List[int]] = None,
                    years: Optional[int] = None) -> None:
        """
        Advance time for plant growth and development.
 
        Updates plants in the simulation, potentially adding new phytomers, growing
        existing organs, transitioning phenological stages, and updating plant geometry.
 
        By default every plant advances together. Pass plant_id or plant_ids to advance a
        subset, which is what staggered planting dates and mixed-age stands require.
 
        Args:
            dt: Time step to advance in days (must be >= 0)
            plant_id: Advance only this plant. Mutually exclusive with plant_ids.
            plant_ids: Advance only these plants. Mutually exclusive with plant_id.
            years: Advance this many whole years in addition to dt days. Applies to all
                plants and cannot be combined with plant_id or plant_ids.
 
        Raises:
            ValueError: If dt or years is negative, or selectors are combined
            PlantArchitectureError: If time advancement fails
 
        Note:
            Large time steps are more efficient than many small steps. The timestep value
            can be larger than the phyllochron, allowing multiple phytomers to be produced
            in a single call.
 
        Example:
            >>> plantarch.advanceTime(10.0)                     # all plants, 10 days
            >>> plantarch.advanceTime(10.0, plant_id=early)     # one plant only
            >>> plantarch.advanceTime(10.0, plant_ids=[a, b])   # a subset
            >>> plantarch.advanceTime(0.0, years=4)             # all plants, 4 years
        """
        if dt < 0:
            raise ValueError(f"Time step must be non-negative, got {dt}")
 
        selectors = sum(x is not None for x in (plant_id, plant_ids, years))
        if selectors > 1:
            raise ValueError("Pass at most one of plant_id, plant_ids, or years")
 
        if plant_id is not None and plant_id < 0:
            raise ValueError(f"plant_id must be non-negative, got {plant_id}")
        if plant_ids is not None and any(pid < 0 for pid in plant_ids):
            raise ValueError("plant_ids must all be non-negative")
        if years is not None and years < 0:
            raise ValueError(f"years must be non-negative, got {years}")
 
        self._reject_inside_phytomer_callback("advanceTime")
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                if plant_id is not None:
                    plantarch_wrapper.advanceTimeForPlant(self._plantarch_ptr, plant_id, dt)
                elif plant_ids is not None:
                    if not plant_ids:
                        return
                    plantarch_wrapper.advanceTimeForPlants(self._plantarch_ptr, plant_ids, dt)
                elif years is not None:
                    plantarch_wrapper.advanceTimeYears(self._plantarch_ptr, years, dt)
                else:
                    plantarch_wrapper.advanceTime(self._plantarch_ptr, dt)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to advance time by {dt} days: {e}")
 
    def enableAttractionPoints(self, points: List[vec3],
                               plant_id: Optional[int] = None,
                               view_half_angle_deg: Optional[float] = None,
                               look_ahead_distance: float = 0.1,
                               attraction_weight: float = 0.6) -> None:
        """
        Steer shoot growth toward a set of target points.
 
        Attraction points are the counterpart to collision avoidance: collision tells a
        plant what to grow around, attraction tells it what to grow toward. This is how
        trellis wires, espalier targets and greenhouse supports are modelled.
 
        Steering applies to growth that happens after this call, since the direction is
        chosen as each phytomer is constructed. Enable the points before advanceTime().
 
        Args:
            points: Target locations as a list of vec3
            plant_id: Apply to this plant only. Applies to every plant when None.
            view_half_angle_deg: Half-angle of the search cone in degrees. Defaults to
                45 for the global form and 80 for the per-plant form, matching the
                native defaults, which differ between the two.
            look_ahead_distance: How far ahead a shoot tip looks, in meters
            attraction_weight: Strength of the steering, 0 to 1
 
        Raises:
            ValueError: If points is empty or contains a non-vec3, or plant_id is negative
            PlantArchitectureError: If the operation fails
 
        Example:
            >>> wires = [vec3(x, 0, 2.1) for x in range(0, 10)]
            >>> plantarch.enableAttractionPoints(wires)
        """
        self._validate_attraction_points(points)
        if plant_id is not None and plant_id < 0:
            raise ValueError(f"plant_id must be non-negative, got {plant_id}")
 
        if view_half_angle_deg is None:
            view_half_angle_deg = 45.0 if plant_id is None else 80.0
 
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                plantarch_wrapper.enableAttractionPoints(
                    self._plantarch_ptr, plant_id, points,
                    view_half_angle_deg, look_ahead_distance, attraction_weight
                )
        except Exception as e:
            raise PlantArchitectureError(f"Failed to enable attraction points: {e}")
 
    def disableAttractionPoints(self, plant_id: Optional[int] = None) -> None:
        """
        Stop steering growth toward attraction points.
 
        Args:
            plant_id: Disable for this plant only. Disables globally when None.
 
        Raises:
            ValueError: If plant_id is negative
            PlantArchitectureError: If the operation fails
        """
        if plant_id is not None and plant_id < 0:
            raise ValueError(f"plant_id must be non-negative, got {plant_id}")
 
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                plantarch_wrapper.disableAttractionPoints(self._plantarch_ptr, plant_id)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to disable attraction points: {e}")
 
    def updateAttractionPoints(self, points: List[vec3],
                               plant_id: Optional[int] = None) -> None:
        """
        Replace the current attraction point set.
 
        Args:
            points: Replacement target locations as a list of vec3
            plant_id: Update this plant only. Updates globally when None.
 
        Raises:
            ValueError: If points is empty or contains a non-vec3, or plant_id is negative
            PlantArchitectureError: If the operation fails
        """
        self._validate_attraction_points(points)
        if plant_id is not None and plant_id < 0:
            raise ValueError(f"plant_id must be non-negative, got {plant_id}")
 
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                plantarch_wrapper.updateAttractionPoints(self._plantarch_ptr, plant_id, points)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to update attraction points: {e}")
 
    def appendAttractionPoints(self, points: List[vec3],
                               plant_id: Optional[int] = None) -> None:
        """
        Add to the current attraction point set.
 
        Args:
            points: Additional target locations as a list of vec3
            plant_id: Append for this plant only. Appends globally when None.
 
        Raises:
            ValueError: If points is empty or contains a non-vec3, or plant_id is negative
            PlantArchitectureError: If the operation fails
        """
        self._validate_attraction_points(points)
        if plant_id is not None and plant_id < 0:
            raise ValueError(f"plant_id must be non-negative, got {plant_id}")
 
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                plantarch_wrapper.appendAttractionPoints(self._plantarch_ptr, plant_id, points)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to append attraction points: {e}")
 
    def setAttractionParameters(self, view_half_angle_deg: float,
                                look_ahead_distance: float,
                                attraction_weight: float,
                                obstacle_reduction_factor: float = 0.75,
                                plant_id: Optional[int] = None) -> None:
        """
        Tune how strongly attraction points steer growth.
 
        Args:
            view_half_angle_deg: Half-angle of the search cone in degrees
            look_ahead_distance: How far ahead a shoot tip looks, in meters
            attraction_weight: Strength of the steering, 0 to 1
            obstacle_reduction_factor: Scales attraction where an obstacle intervenes
            plant_id: Apply to this plant only. Applies globally when None.
 
        Raises:
            ValueError: If plant_id is negative
            PlantArchitectureError: If the operation fails
        """
        if plant_id is not None and plant_id < 0:
            raise ValueError(f"plant_id must be non-negative, got {plant_id}")
 
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                plantarch_wrapper.setAttractionParameters(
                    self._plantarch_ptr, plant_id, view_half_angle_deg,
                    look_ahead_distance, attraction_weight, obstacle_reduction_factor
                )
        except Exception as e:
            raise PlantArchitectureError(f"Failed to set attraction parameters: {e}")
 
    @staticmethod
    def _validate_attraction_points(points) -> None:
        """Reject point sets the native layer would misread or silently ignore."""
        if not isinstance(points, (list, tuple)):
            raise ValueError(
                f"points must be a list of vec3, got {type(points).__name__}"
            )
        if not points:
            raise ValueError("points cannot be empty")
        for index, point in enumerate(points):
            if not isinstance(point, vec3):
                raise ValueError(
                    f"points[{index}] must be a vec3, got {type(point).__name__}"
                )
 
    def setProgressCallback(self, callback):
        """Set a callback to receive progress updates during long-running operations.
 
        The callback fires during advanceTime() and adjustFruitForObstacleCollision()
        as the underlying ProgressBar updates.
 
        Args:
            callback: A callable(progress: float, message: str) where progress is
                      in [0, 1], or None to clear the callback.
 
        Raises:
            ValueError: If callback is not callable and not None.
        """
        if callback is not None:
            if not callable(callback):
                raise ValueError(
                    f"callback must be callable or None, got {type(callback).__name__}"
                )
 
            def _c_callback(progress, message_bytes):
                msg = message_bytes.decode('utf-8') if isinstance(message_bytes, bytes) else str(message_bytes)
                callback(progress, msg)
 
            self._check_context_alive()
            self._progress_callback_ref = plantarch_wrapper.PROGRESS_CALLBACK(_c_callback)
            self._check_context_alive()
            plantarch_wrapper.setProgressCallback(self._plantarch_ptr, self._progress_callback_ref)
        else:
            self._check_context_alive()
            plantarch_wrapper.setProgressCallback(self._plantarch_ptr, None)
            self._progress_callback_ref = None
 
    def setCancelFlag(self, cancel_flag):
        """Register an external cancellation flag polled during long plant builds.
 
        ``cancel_flag`` is a ctypes.c_int that, when set non-zero from another
        thread, stops the canopy build loop and the advanceTime() growth loop
        between plants/timesteps — so a long generation can be aborted mid-build
        (returning whatever was built so far). Set it before the build call; pass
        None to clear. The flag is caller-owned and must outlive the build.
        """
        self._check_context_alive()
        plantarch_wrapper.setCancelFlag(self._plantarch_ptr, cancel_flag)
 
    def getCurrentShootParameters(self, shoot_type_label: str, return_typed: bool = False):
        """
        Get current shoot parameters for a shoot type.
 
        Returns the full nested shoot and phytomer parameter set, including the
        internode/petiole/leaf/peduncle/inflorescence sub-structures and the leaf
        prototype. Every numeric field is a RandomParameter spec with a
        'distribution' and 'parameters'.
 
        Args:
            shoot_type_label: Label for the shoot type. Labels are species-specific,
                e.g. "trifoliate" (bean), "trunk"/"scaffold" (almond).
            return_typed: If True, return a typed
                :class:`pyhelios.plant_architecture_params.ShootParameters`
                object instead of a plain nested dict.
 
        Returns:
            A nested ``dict`` (default) or a ``ShootParameters`` object containing:
            - Geometric parameters (max_nodes, insertion_angle_tip, etc.)
            - Growth parameters (phyllochron_min, elongation_rate_max, etc.)
            - Boolean flags (flowers_require_dormancy, etc.)
            - ``phytomer_parameters`` with nested internode/petiole/leaf/peduncle/
              inflorescence parameters and the leaf prototype
 
        Raises:
            ValueError: If shoot_type_label is empty
            PlantArchitectureError: If parameter retrieval fails
 
        Example:
            >>> plantarch.loadPlantModelFromLibrary("bean")
            >>> params = plantarch.getCurrentShootParameters("trifoliate")
            >>> print(params['max_nodes'])
            {'distribution': 'constant', 'parameters': [25.0]}
            >>> print(params['phytomer_parameters']['leaf']['pitch'])
            {'distribution': 'normal', 'parameters': [0.0, 20.0]}
        """
        if not shoot_type_label:
            raise ValueError("Shoot type label cannot be empty")
 
        if not shoot_type_label.strip():
            raise ValueError("Shoot type label cannot be only whitespace")
 
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                params = plantarch_wrapper.getCurrentShootParameters(
                    self._plantarch_ptr, shoot_type_label.strip()
                )
        except Exception as e:
            # An unknown label is the common case here, and the native error does not say
            # which labels exist. Name them so the caller does not have to guess.
            available = ""
            try:
                labels = self.listShootTypeLabels()
                if labels:
                    available = f" Available shoot types: {', '.join(sorted(labels))}."
            except Exception:
                pass
            raise PlantArchitectureError(f"{e}.{available}")
 
        return ShootParameters.from_dict(params) if return_typed else params
 
    def defineShootType(self, shoot_type_label: str, parameters: Union[dict, ShootParameters]) -> None:
        """
        Define a custom shoot type with specified parameters.
 
        Allows creating new shoot types or modifying existing ones. Pass either a
        nested parameter ``dict`` (use :meth:`getCurrentShootParameters` as a
        template) or a typed
        :class:`pyhelios.plant_architecture_params.ShootParameters` object.
 
        Redefining an existing library shoot type preserves that species' built-in
        phytomer creation and callback functions, so species-specific organ behavior
        (such as maize forming ears rather than a tassel at every node) is retained.
 
        Args:
            shoot_type_label: Unique name for this shoot type
            parameters: A nested dict matching the ShootParameters structure, or a
                ShootParameters object.
 
        Raises:
            ValueError: If shoot_type_label is empty, or parameters is not a dict
                or ShootParameters
            PlantArchitectureError: If shoot type definition fails
 
        Example:
            >>> from pyhelios.plant_architecture_params import ShootParameters, RandomParameterFloat
            >>> plantarch.loadPlantModelFromLibrary("bean")
            >>> sp = plantarch.getCurrentShootParameters("trifoliate", return_typed=True)
            >>> sp.max_nodes = RandomParameterFloat.constant(20)
            >>> sp.phytomer_parameters.leaf.pitch = RandomParameterFloat.uniform(40, 50)
            >>> plantarch.defineShootType("TallStem", sp)
        """
        if not shoot_type_label:
            raise ValueError("Shoot type label cannot be empty")
 
        if not shoot_type_label.strip():
            raise ValueError("Shoot type label cannot be only whitespace")
 
        if isinstance(parameters, ShootParameters):
            parameters = parameters.to_dict()
        elif not isinstance(parameters, dict):
            raise ValueError(
                f"Parameters must be a dict or ShootParameters, got {type(parameters).__name__}"
            )
 
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                plantarch_wrapper.defineShootType(
                    self._plantarch_ptr, self.context.context, shoot_type_label.strip(), parameters
                )
        except Exception as e:
            raise PlantArchitectureError(f"Failed to define shoot type '{shoot_type_label}': {e}")
 
    def getDefaultCarbohydrateParameters(self, return_typed: bool = False):
        """
        Get a default-constructed set of carbohydrate-model parameters.
 
        The native API exposes no per-plant getter for carbohydrate parameters, so
        this returns the C++ defaults as a template to modify and apply via
        :meth:`setPlantCarbohydrateParameters`.
 
        Args:
            return_typed: If True, return a typed
                :class:`pyhelios.plant_architecture_params.CarbohydrateParameters`.
 
        Returns:
            A flat ``dict`` (default) or ``CarbohydrateParameters`` object.
        """
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                params = plantarch_wrapper.getDefaultCarbohydrateParameters()
        except Exception as e:
            raise PlantArchitectureError(f"Failed to get default carbohydrate parameters: {e}")
        return CarbohydrateParameters.from_dict(params) if return_typed else params
 
    def setPlantCarbohydrateParameters(self, plant_id: int, parameters: Union[dict, CarbohydrateParameters]) -> None:
        """
        Set carbohydrate-model parameters for a plant.
 
        Args:
            plant_id: Target plant instance ID
            parameters: A flat dict or a CarbohydrateParameters object.
 
        Raises:
            ValueError: If parameters is not a dict or CarbohydrateParameters
            PlantArchitectureError: If the operation fails
        """
        if isinstance(parameters, CarbohydrateParameters):
            parameters = parameters.to_dict()
        elif not isinstance(parameters, dict):
            raise ValueError(
                f"Parameters must be a dict or CarbohydrateParameters, got {type(parameters).__name__}"
            )
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                plantarch_wrapper.setPlantCarbohydrateParameters(self._plantarch_ptr, plant_id, parameters)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to set carbohydrate parameters for plant {plant_id}: {e}")
 
    def getDefaultNitrogenParameters(self, return_typed: bool = False):
        """
        Get a default-constructed set of nitrogen-model parameters.
 
        The native API exposes no per-plant getter for nitrogen parameters, so this
        returns the C++ defaults as a template to modify and apply via
        :meth:`setPlantNitrogenParameters`.
 
        Args:
            return_typed: If True, return a typed
                :class:`pyhelios.plant_architecture_params.NitrogenParameters`.
 
        Returns:
            A flat ``dict`` (default) or ``NitrogenParameters`` object.
        """
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                params = plantarch_wrapper.getDefaultNitrogenParameters()
        except Exception as e:
            raise PlantArchitectureError(f"Failed to get default nitrogen parameters: {e}")
        return NitrogenParameters.from_dict(params) if return_typed else params
 
    def setPlantNitrogenParameters(self, plant_id: int, parameters: Union[dict, NitrogenParameters]) -> None:
        """
        Set nitrogen-model parameters for a plant.
 
        Args:
            plant_id: Target plant instance ID
            parameters: A flat dict or a NitrogenParameters object.
 
        Raises:
            ValueError: If parameters is not a dict or NitrogenParameters, or the dict
                contains a key that is not a nitrogen parameter
            PlantArchitectureError: If the operation fails
        """
        if isinstance(parameters, NitrogenParameters):
            parameters = parameters.to_dict()
        elif not isinstance(parameters, dict):
            raise ValueError(
                f"Parameters must be a dict or NitrogenParameters, got {type(parameters).__name__}"
            )
        unknown = sorted(set(parameters) - set(NitrogenParameters().to_dict()))
        if unknown:
            raise ValueError(
                f"Unknown nitrogen parameter(s) {unknown}; valid keys are "
                f"{sorted(NitrogenParameters().to_dict())}. remobilization_age_threshold was removed "
                f"in helios-core 1.3.88 (see leaf_remobilization_rate and leaf_senescence_duration_fraction)."
            )
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                plantarch_wrapper.setPlantNitrogenParameters(self._plantarch_ptr, plant_id, parameters)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to set nitrogen parameters for plant {plant_id}: {e}")
 
    def getAvailablePlantModels(self) -> List[str]:
        """
        Get list of all available plant models in the library.
 
        Returns:
            List of plant model names available for loading
 
        Raises:
            PlantArchitectureError: If retrieval fails
 
        Example:
            >>> models = plantarch.getAvailablePlantModels()
            >>> print(f"Available models: {', '.join(models)}")
            Available models: almond, apple, bean, cowpea, maize, rice, soybean, tomato, wheat, ...
        """
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                return plantarch_wrapper.getAvailablePlantModels(self._plantarch_ptr)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to get available plant models: {e}")
 
    def getPlantModelBuildParameterNames(self, plant_model: str) -> List[str]:
        """
        Get the names of the build parameters a library plant model accepts.
 
        These are the keys that may be passed as ``build_parameters`` to
        :meth:`buildPlantInstanceFromLibrary` and :meth:`buildPlantCanopyFromLibrary` for the
        model; any other key is rejected. The model does not need to be loaded.
 
        Args:
            plant_model: Name of the plant model (see :meth:`getAvailablePlantModels`)
 
        Returns:
            Names of the model's structure parameters (training system, tillers) followed by
            its organ parameters (flower and fruit form); empty if the model accepts none
 
        Raises:
            ValueError: If ``plant_model`` is not a non-empty string
            PlantArchitectureError: If the model does not exist in the library
            RuntimeError: If the native library predates helios-core v1.3.93
 
        Example:
            >>> plantarch.getPlantModelBuildParameterNames("grapevine_VSP")
            ['vine_spacing', 'trunk_height', 'berry_diameter', 'cluster_berry_count']
        """
        if not isinstance(plant_model, str) or not plant_model.strip():
            raise ValueError("Plant model must be a non-empty string")
        self._check_context_alive()
        try:
            return plantarch_wrapper.getPlantModelBuildParameterNames(self._plantarch_ptr, plant_model)
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to get the build parameter names of plant model '{plant_model}': {e}")
 
    def listShootTypeLabels(self, plant_model: Optional[str] = None,
                            plant_id: Optional[int] = None) -> List[str]:
        """
        Get the shoot type labels defined for a plant model.
 
        Shoot type labels are species-specific strings such as "trunk" or "scaffold", and
        every shoot-parameter call takes one. Use this to discover the valid labels rather
        than guessing them.
 
        Args:
            plant_model: Query this library model without changing the currently loaded
                one. Use getAvailablePlantModels() for valid names. Mutually exclusive
                with plant_id.
            plant_id: Query the shoot types captured by this plant instance when it was
                created. Mutually exclusive with plant_model.
 
        With neither argument, queries the currently loaded model, which requires a prior
        call to loadPlantModelFromLibrary().
 
        Returns:
            List of shoot type label strings.
 
        Raises:
            ValueError: If both plant_model and plant_id are given, or plant_id is negative
            PlantArchitectureError: If no model is loaded, or the model or plant is unknown
 
        Example:
            >>> plantarch.loadPlantModelFromLibrary("almond")
            >>> plantarch.listShootTypeLabels()
            ['proleptic', 'scaffold', 'sylleptic', 'trunk']
            >>> plantarch.listShootTypeLabels(plant_model="bean")
            ['trifoliate', 'unifoliate']
        """
        if plant_model is not None and plant_id is not None:
            raise ValueError("Pass either plant_model or plant_id, not both")
        if plant_id is not None and plant_id < 0:
            raise ValueError(f"plant_id must be non-negative, got {plant_id}")
        if plant_model is not None and not plant_model.strip():
            raise ValueError("plant_model cannot be empty or only whitespace")
 
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                return plantarch_wrapper.listShootTypeLabels(
                    self._plantarch_ptr,
                    plant_model.strip() if plant_model is not None else None,
                    plant_id,
                )
        except Exception as e:
            raise PlantArchitectureError(f"Failed to list shoot type labels: {e}")
 
    def getAllUUIDs(self) -> List[int]:
        """
        Get UUIDs of every plant primitive in the model.
 
        Spans every plant, unlike the per-plant getters, which is what canopy-wide work
        such as assigning optical properties or reading flux by organ type needs.
 
        Returns:
            List of primitive UUIDs
 
        Raises:
            PlantArchitectureError: If retrieval fails
 
        Example:
            >>> ids = plantarch.getAllUUIDs()
        """
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                return plantarch_wrapper.getAllUUIDs(self._plantarch_ptr)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to get primitive UUIDs: {e}")
 
    def getAllLeafUUIDs(self) -> List[int]:
        """
        Get UUIDs of every leaf primitive in the model.
 
        Spans every plant, unlike the per-plant getters, which is what canopy-wide work
        such as assigning optical properties or reading flux by organ type needs.
 
        Returns:
            List of leaf primitive UUIDs
 
        Raises:
            PlantArchitectureError: If retrieval fails
 
        Example:
            >>> ids = plantarch.getAllLeafUUIDs()
        """
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                return plantarch_wrapper.getAllLeafUUIDs(self._plantarch_ptr)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to get leaf primitive UUIDs: {e}")
 
    def getAllInternodeUUIDs(self) -> List[int]:
        """
        Get UUIDs of every internode primitive in the model.
 
        Spans every plant, unlike the per-plant getters, which is what canopy-wide work
        such as assigning optical properties or reading flux by organ type needs.
 
        Returns:
            List of internode primitive UUIDs
 
        Raises:
            PlantArchitectureError: If retrieval fails
 
        Example:
            >>> ids = plantarch.getAllInternodeUUIDs()
        """
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                return plantarch_wrapper.getAllInternodeUUIDs(self._plantarch_ptr)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to get internode primitive UUIDs: {e}")
 
    def getAllPetioleUUIDs(self) -> List[int]:
        """
        Get UUIDs of every petiole primitive in the model.
 
        Spans every plant, unlike the per-plant getters, which is what canopy-wide work
        such as assigning optical properties or reading flux by organ type needs.
 
        Returns:
            List of petiole primitive UUIDs
 
        Raises:
            PlantArchitectureError: If retrieval fails
 
        Example:
            >>> ids = plantarch.getAllPetioleUUIDs()
        """
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                return plantarch_wrapper.getAllPetioleUUIDs(self._plantarch_ptr)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to get petiole primitive UUIDs: {e}")
 
    def getAllPeduncleUUIDs(self) -> List[int]:
        """
        Get UUIDs of every peduncle primitive in the model.
 
        Spans every plant, unlike the per-plant getters, which is what canopy-wide work
        such as assigning optical properties or reading flux by organ type needs.
 
        An empty list means no plant has reached the corresponding growth stage,
        which is a legitimate result rather than a failure.
 
        Returns:
            List of peduncle primitive UUIDs
 
        Raises:
            PlantArchitectureError: If retrieval fails
 
        Example:
            >>> ids = plantarch.getAllPeduncleUUIDs()
        """
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                return plantarch_wrapper.getAllPeduncleUUIDs(self._plantarch_ptr)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to get peduncle primitive UUIDs: {e}")
 
    def getAllFlowerUUIDs(self) -> List[int]:
        """
        Get UUIDs of every flower primitive in the model.
 
        Spans every plant, unlike the per-plant getters, which is what canopy-wide work
        such as assigning optical properties or reading flux by organ type needs.
 
        An empty list means no plant has reached the corresponding growth stage,
        which is a legitimate result rather than a failure.
 
        Returns:
            List of flower primitive UUIDs
 
        Raises:
            PlantArchitectureError: If retrieval fails
 
        Example:
            >>> ids = plantarch.getAllFlowerUUIDs()
        """
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                return plantarch_wrapper.getAllFlowerUUIDs(self._plantarch_ptr)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to get flower primitive UUIDs: {e}")
 
    def getAllFruitUUIDs(self) -> List[int]:
        """
        Get UUIDs of every fruit primitive in the model.
 
        Spans every plant, unlike the per-plant getters, which is what canopy-wide work
        such as assigning optical properties or reading flux by organ type needs.
 
        An empty list means no plant has reached the corresponding growth stage,
        which is a legitimate result rather than a failure.
 
        Returns:
            List of fruit primitive UUIDs
 
        Raises:
            PlantArchitectureError: If retrieval fails
 
        Example:
            >>> ids = plantarch.getAllFruitUUIDs()
        """
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                return plantarch_wrapper.getAllFruitUUIDs(self._plantarch_ptr)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to get fruit primitive UUIDs: {e}")
 
    def getAllObjectIDs(self) -> List[int]:
        """
        Get object IDs of every plant compound object in the model.
 
        Spans every plant, unlike the per-plant getters, which is what canopy-wide work
        such as assigning optical properties or reading flux by organ type needs.
 
        Returns:
            List of object IDs
 
        Raises:
            PlantArchitectureError: If retrieval fails
 
        Example:
            >>> ids = plantarch.getAllObjectIDs()
        """
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                return plantarch_wrapper.getAllObjectIDs(self._plantarch_ptr)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to get object IDs: {e}")
 
    def getAllPlantIDs(self) -> List[int]:
        """
        Get IDs of every plant instance in the model.
 
        Spans every plant, unlike the per-plant getters, which is what canopy-wide work
        such as assigning optical properties or reading flux by organ type needs.
 
        Returns:
            List of plant IDs
 
        Raises:
            PlantArchitectureError: If retrieval fails
 
        Example:
            >>> ids = plantarch.getAllPlantIDs()
        """
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                return plantarch_wrapper.getAllPlantIDs(self._plantarch_ptr)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to get plant IDs: {e}")
 
    def getAllPlantObjectIDs(self, plant_id: int) -> List[int]:
        """
        Get all object IDs for a specific plant.
 
        Args:
            plant_id: ID of the plant instance
 
        Returns:
            List of object IDs comprising the plant
 
        Raises:
            ValueError: If plant_id is negative
            PlantArchitectureError: If retrieval fails
 
        Example:
            >>> object_ids = plantarch.getAllPlantObjectIDs(plant_id)
            >>> print(f"Plant has {len(object_ids)} objects")
        """
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
 
        self._check_context_alive()
        try:
            return plantarch_wrapper.getAllPlantObjectIDs(self._plantarch_ptr, plant_id)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to get object IDs for plant {plant_id}: {e}")
 
    def getPlantLeafObjectIDs(self, plant_id: int) -> List[int]:
        """
        Get object IDs for all leaf objects on a specific plant.
 
        Args:
            plant_id: ID of the plant instance
 
        Returns:
            List of object IDs, one per leaf
 
        Raises:
            ValueError: If plant_id is negative
            PlantArchitectureError: If retrieval fails
 
        Warning:
            Do **not** pair this result positionally with :meth:`getPlantLeafBases`.
            The two are built by independent traversals of the shoot tree, so their
            index correspondence is not guaranteed by the native API.
 
        Example:
            >>> leaf_ids = plantarch.getPlantLeafObjectIDs(plant_id)
            >>> print(f"Plant has {len(leaf_ids)} leaves")
        """
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
 
        self._check_context_alive()
        try:
            return plantarch_wrapper.getPlantLeafObjectIDs(self._plantarch_ptr, plant_id)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to get leaf object IDs for plant {plant_id}: {e}")
 
    def getPlantPetioleObjectIDs(self, plant_id: int) -> List[int]:
        """
        Get object IDs for all petiole objects on a specific plant.
 
        Petioles are the stalks attaching leaves to the stem, so this is the
        structural counterpart to :meth:`getPlantLeafObjectIDs`.
 
        Args:
            plant_id: ID of the plant instance
 
        Returns:
            List of object IDs, one per petiole
 
        Raises:
            ValueError: If plant_id is negative
            PlantArchitectureError: If retrieval fails
 
        Example:
            >>> petiole_ids = plantarch.getPlantPetioleObjectIDs(plant_id)
            >>> print(f"Plant has {len(petiole_ids)} petioles")
        """
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
 
        self._check_context_alive()
        try:
            return plantarch_wrapper.getPlantPetioleObjectIDs(self._plantarch_ptr, plant_id)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to get petiole object IDs for plant {plant_id}: {e}")
 
    def getPlantPeduncleObjectIDs(self, plant_id: int) -> List[int]:
        """
        Get object IDs for all peduncle objects on a specific plant.
 
        Peduncles are the stalks bearing flowers and fruit.
 
        Args:
            plant_id: ID of the plant instance
 
        Returns:
            List of object IDs, one per peduncle. Empty if the plant has not
            reached its reproductive stage, which is a normal result rather than
            an error.
 
        Raises:
            ValueError: If plant_id is negative
            PlantArchitectureError: If retrieval fails
 
        Example:
            >>> peduncle_ids = plantarch.getPlantPeduncleObjectIDs(plant_id)
            >>> print(f"Plant has {len(peduncle_ids)} peduncles")
        """
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
 
        self._check_context_alive()
        try:
            return plantarch_wrapper.getPlantPeduncleObjectIDs(self._plantarch_ptr, plant_id)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to get peduncle object IDs for plant {plant_id}: {e}")
 
    def getPlantFlowerObjectIDs(self, plant_id: int) -> List[int]:
        """
        Get object IDs for all flower (inflorescence) objects on a specific plant.
 
        Args:
            plant_id: ID of the plant instance
 
        Returns:
            List of object IDs, one per flower. Empty if the plant has not
            flowered -- or has already flowered and set fruit, since flowers are
            replaced by fruit as growth proceeds. Both are normal results rather
            than errors.
 
        Raises:
            ValueError: If plant_id is negative
            PlantArchitectureError: If retrieval fails
 
        Example:
            >>> flower_ids = plantarch.getPlantFlowerObjectIDs(plant_id)
            >>> print(f"Plant has {len(flower_ids)} flowers")
        """
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
 
        self._check_context_alive()
        try:
            return plantarch_wrapper.getPlantFlowerObjectIDs(self._plantarch_ptr, plant_id)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to get flower object IDs for plant {plant_id}: {e}")
 
    def getPlantFruitObjectIDs(self, plant_id: int) -> List[int]:
        """
        Get object IDs for all fruit objects on a specific plant.
 
        Args:
            plant_id: ID of the plant instance
 
        Returns:
            List of object IDs, one per fruit. Empty if the plant has not
            fruited, which is a normal result rather than an error -- fruit
            appear only once a plant reaches the reproductive stage, so a plant
            built at a young age or from a model with no fruit yields ``[]``.
 
        Raises:
            ValueError: If plant_id is negative
            PlantArchitectureError: If retrieval fails
 
        Example:
            >>> fruit_ids = plantarch.getPlantFruitObjectIDs(plant_id)
            >>> print(f"Plant has {len(fruit_ids)} fruit")
            >>> # Object IDs are Context object IDs, so the usual queries apply:
            >>> uuids = context.getObjectPrimitiveUUIDs(fruit_ids[0])
        """
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
 
        self._check_context_alive()
        try:
            return plantarch_wrapper.getPlantFruitObjectIDs(self._plantarch_ptr, plant_id)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to get fruit object IDs for plant {plant_id}: {e}")
 
    def getPlantLeafBases(self, plant_id: int) -> List[vec3]:
        """
        Get the attachment base position of every leaf on a specific plant.
 
        The base is where the leaf attaches to its petiole, not the leaf centroid.
 
        Args:
            plant_id: ID of the plant instance
 
        Returns:
            List of vec3 base positions, one per leaf
 
        Raises:
            ValueError: If plant_id is negative
            PlantArchitectureError: If retrieval fails
 
        Warning:
            Do **not** pair this result positionally with
            :meth:`getPlantLeafObjectIDs`. The two are built by independent
            traversals of the shoot tree, so their index correspondence is not
            guaranteed by the native API.
 
        Example:
            >>> bases = plantarch.getPlantLeafBases(plant_id)
            >>> print(f"First leaf attaches at {bases[0]}")
        """
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
 
        self._check_context_alive()
        try:
            flat = plantarch_wrapper.getPlantLeafBases(self._plantarch_ptr, plant_id)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to get leaf bases for plant {plant_id}: {e}")
 
        return [vec3(float(flat[i]), float(flat[i + 1]), float(flat[i + 2]))
                for i in range(0, len(flat), 3)]
 
    def getAllPlantUUIDs(self, plant_id: int, include_hidden: bool = False) -> List[int]:
        """
        Get all primitive UUIDs for a specific plant.
 
        Args:
            plant_id: ID of the plant instance
            include_hidden: If True, also include UUIDs of hidden prototype
                primitives managed by this PlantArchitecture instance.
 
        Returns:
            List of primitive UUIDs comprising the plant (and optionally hidden prototypes)
 
        Raises:
            ValueError: If plant_id is negative
            PlantArchitectureError: If retrieval fails
 
        Example:
            >>> uuids = plantarch.getAllPlantUUIDs(plant_id)
            >>> print(f"Plant has {len(uuids)} primitives")
        """
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
 
        self._check_context_alive()
        try:
            return plantarch_wrapper.getAllPlantUUIDs(self._plantarch_ptr, plant_id, include_hidden)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to get UUIDs for plant {plant_id}: {e}")
 
    def getAllShootIDs(self, plant_id: int) -> List[int]:
        """
        Get the IDs of all shoots belonging to a plant.
 
        Shoot IDs are contiguous 0-based indices into the plant's shoot tree, in creation
        order; shoot 0 is always the base stem. The returned IDs can be passed to
        :meth:`getShoot`, :meth:`getShootChildIDs`, etc.
 
        Args:
            plant_id: ID of the plant instance
 
        Returns:
            List of shoot IDs for the plant
        """
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
        self._check_context_alive()
        try:
            return plantarch_wrapper.getAllPlantShootIDs(self._plantarch_ptr, plant_id)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to get shoot IDs for plant {plant_id}: {e}")
 
    def getShoot(self, plant_id: int, shoot_id: int) -> Dict[str, Any]:
        """
        Get a read-only view of a shoot's topology.
 
        Args:
            plant_id: ID of the plant instance
            shoot_id: Shoot index within the plant (see :meth:`getAllShootIDs`)
 
        Returns:
            A dict with keys ``rank``, ``parent_shoot_id`` (-1 for the base stem),
            ``parent_node_index``, and ``node_count``.
        """
        if plant_id < 0 or shoot_id < 0:
            raise ValueError("Plant ID and shoot ID must be non-negative")
        self._check_context_alive()
        try:
            return plantarch_wrapper.getPlantShootTopology(self._plantarch_ptr, plant_id, shoot_id)
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to get shoot {shoot_id} of plant {plant_id}: {e}")
 
    def getShootChildIDs(self, plant_id: int, shoot_id: int) -> List[int]:
        """Get the child shoot IDs of a shoot (flattened across parent node indices)."""
        if plant_id < 0 or shoot_id < 0:
            raise ValueError("Plant ID and shoot ID must be non-negative")
        self._check_context_alive()
        try:
            return plantarch_wrapper.getPlantShootChildIDs(self._plantarch_ptr, plant_id, shoot_id)
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to get child shoots of shoot {shoot_id}, plant {plant_id}: {e}")
 
    def getParentShootID(self, plant_id: int, shoot_id: int) -> int:
        """
        Get the ID of the shoot a shoot grew from.
 
        Args:
            plant_id: ID of the plant instance
            shoot_id: Shoot index within the plant (see :meth:`getAllShootIDs`)
 
        Returns:
            ID of the parent shoot, or -1 if this is the base stem shoot.
 
        Note:
            A pruned shoot still reports the parent it grew from, even though it is no
            longer listed among that parent's children.
 
        Example:
            >>> parent = plantarch.getParentShootID(plant_id, shoot_id=3)
        """
        return self._shootScalarQuery("getParentShootID", plant_id, shoot_id, "parent shoot ID")
 
    def getShootRank(self, plant_id: int, shoot_id: int) -> int:
        """
        Get the branching rank of a shoot.
 
        Rank is the botanical branching order: the base stem is rank 0, a branch off it
        is rank 1, and so on. A shoot created by :meth:`appendShoot` continues its
        parent's axis rather than branching from it, so it keeps the parent's rank.
        Rank is therefore not the same as :meth:`getShootDepth`.
 
        Args:
            plant_id: ID of the plant instance
            shoot_id: Shoot index within the plant
 
        Returns:
            Branching rank of the shoot.
 
        Example:
            >>> rank = plantarch.getShootRank(plant_id, shoot_id=3)
        """
        return self._shootScalarQuery("getShootRank", plant_id, shoot_id, "shoot rank")
 
    def getShootDepth(self, plant_id: int, shoot_id: int) -> int:
        """
        Get the number of shoots between a shoot and the base stem shoot.
 
        The base stem has depth 0, its children depth 1, and so on. Unlike
        :meth:`getShootRank` this counts every step in the shoot tree, including axis
        continuations created by :meth:`appendShoot`.
 
        Args:
            plant_id: ID of the plant instance
            shoot_id: Shoot index within the plant
 
        Returns:
            Number of steps from this shoot to the base stem shoot.
        """
        return self._shootScalarQuery("getShootDepth", plant_id, shoot_id, "shoot depth")
 
    def isShootPruned(self, plant_id: int, shoot_id: int) -> bool:
        """
        Report whether a shoot has been pruned away entirely.
 
        :meth:`pruneBranch` called with ``node_index=0`` removes all of a shoot's
        phytomers and geometry but keeps the shoot in the plant's tree so that shoot IDs
        stay stable. Such a shoot is still returned by :meth:`getAllShootIDs` but is
        inert: it has zero nodes, contributes no leaf area, and cannot be queried for
        geometry. Use this to skip those shoots when walking :meth:`getAllShootIDs`.
 
        Args:
            plant_id: ID of the plant instance
            shoot_id: Shoot index within the plant
 
        Returns:
            True if the shoot was pruned away and no longer forms part of the plant.
 
        Example:
            >>> live = [s for s in plantarch.getAllShootIDs(plant_id)
            ...         if not plantarch.isShootPruned(plant_id, s)]
        """
        return self._shootScalarQuery("isShootPruned", plant_id, shoot_id, "pruned state")
 
    def getPathToRoot(self, plant_id: int, shoot_id: int) -> List[int]:
        """
        Get the chain of shoots connecting a shoot to the base stem shoot.
 
        Args:
            plant_id: ID of the plant instance
            shoot_id: Shoot index within the plant
 
        Returns:
            Shoot IDs ordered from the given shoot to the base stem shoot, including
            both. For the base stem shoot this is a single element.
 
        Example:
            >>> path = plantarch.getPathToRoot(plant_id, shoot_id=5)
        """
        return self._shootScalarQuery("getPathToRoot", plant_id, shoot_id, "path to root")
 
    def getChildShootIDs(self, plant_id: int, shoot_id: int) -> List[int]:
        """
        Get the shoots that grew directly out of a shoot.
 
        Ordered by the node they attach to. This includes shoots created by
        :meth:`appendShoot`, which continue the parent's axis rather than branching from
        it; compare their :meth:`getShootRank` with the parent's to tell the two apart.
        Pruned shoots are not included.
 
        Args:
            plant_id: ID of the plant instance
            shoot_id: Shoot index within the plant
 
        Returns:
            IDs of the direct children of the shoot, empty if it has none.
        """
        return self._shootScalarQuery("getChildShootIDs", plant_id, shoot_id, "child shoot IDs")
 
    def getAllDescendantShootIDs(self, plant_id: int, shoot_id: int) -> List[int]:
        """
        Get every shoot descending from a shoot.
 
        Collected depth-first, so a shoot is always listed before its own descendants.
        The shoot itself is not included, and pruned shoots are omitted.
 
        Args:
            plant_id: ID of the plant instance
            shoot_id: Shoot whose descendants to collect
 
        Returns:
            IDs of all descendants of the shoot, empty if it has none.
 
        Example:
            >>> descendants = plantarch.getAllDescendantShootIDs(plant_id, shoot_id=1)
            >>> print(f"Branch carries {len(descendants)} sub-shoots")
        """
        return self._shootScalarQuery("getAllDescendantShootIDs", plant_id, shoot_id,
                                      "descendant shoot IDs")
 
    def getShootHierarchyMap(self, plant_id: int) -> Dict[int, List[int]]:
        """
        Get the parent-to-children structure of a plant.
 
        Only shoots that actually have children appear as keys. Pruned shoots appear
        neither as keys nor among the children.
 
        Args:
            plant_id: ID of the plant instance
 
        Returns:
            Dict mapping shoot ID to the IDs of its direct children.
 
        Example:
            >>> hierarchy = plantarch.getShootHierarchyMap(plant_id)
            >>> print(f"{len(hierarchy)} shoots carry branches")
        """
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
        self._check_context_alive()
        try:
            return plantarch_wrapper.getShootHierarchyMap(self._plantarch_ptr, plant_id)
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to get shoot hierarchy of plant {plant_id}: {e}")
 
    def _shootScalarQuery(self, wrapper_fn_name: str, plant_id: int, shoot_id: int,
                          description: str):
        """Shared body for the per-shoot hierarchy accessors."""
        if plant_id < 0 or shoot_id < 0:
            raise ValueError("Plant ID and shoot ID must be non-negative")
        self._check_context_alive()
        try:
            return getattr(plantarch_wrapper, wrapper_fn_name)(
                self._plantarch_ptr, plant_id, shoot_id)
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to get {description} of shoot {shoot_id}, plant {plant_id}: {e}")
 
    def getShootInternodeVertices(self, plant_id: int, shoot_id: int) -> List[tuple]:
        """Get the woody internode polyline vertices of a shoot as a list of (x, y, z) tuples."""
        if plant_id < 0 or shoot_id < 0:
            raise ValueError("Plant ID and shoot ID must be non-negative")
        self._check_context_alive()
        try:
            return plantarch_wrapper.getPlantShootInternodeVertices(self._plantarch_ptr, plant_id, shoot_id)
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to get internode vertices of shoot {shoot_id}, plant {plant_id}: {e}")
 
    def getShootInternodeRadii(self, plant_id: int, shoot_id: int) -> List[float]:
        """Get the per-vertex woody internode radii of a shoot."""
        if plant_id < 0 or shoot_id < 0:
            raise ValueError("Plant ID and shoot ID must be non-negative")
        self._check_context_alive()
        try:
            return plantarch_wrapper.getPlantShootInternodeRadii(self._plantarch_ptr, plant_id, shoot_id)
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to get internode radii of shoot {shoot_id}, plant {plant_id}: {e}")
 
    # =========================================================================
    # Built-geometry organ queries (helios-core 1.3.85+)
    # =========================================================================
 
    def _plantFloatVector(self, wrapper_fn_name: str, plant_id: int, description: str) -> List[float]:
        """Shared body for the per-organ built-geometry queries."""
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
        self._check_context_alive()
        try:
            return getattr(plantarch_wrapper, wrapper_fn_name)(self._plantarch_ptr, plant_id)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to get {description} for plant {plant_id}: {e}")
 
    def getPlantLeafAreas(self, plant_id: int) -> List[float]:
        """
        Get the built one-sided surface area of every leaf on a plant.
 
        Measured from the geometry that was actually built, rather than reported from
        the shoot type's parameters. The two answer different questions: the shoot type
        gives the distribution a parameter was drawn from, while this gives what the
        plant ended up with.
 
        This reports present area, so a leaf part-way through its growth is counted at
        its current size. Leaves are visited shoot by shoot and then phytomer by phytomer,
        the same order as :meth:`getPlantLeafObjectIDs`. Leaves whose geometry does not
        exist (removed, senesced, or never built) are omitted rather than reported as
        zero, so the result can be shorter than the list from :meth:`getPlantLeafObjectIDs`.
        Each area is blade area: a leaflet's petiolule belongs to its leaf object but is not
        counted (helios-core 1.3.89+).
 
        Requires helios-core v1.3.85 or newer.
 
        Args:
            plant_id: ID of the plant instance
 
        Returns:
            One-sided surface area (m^2) of each leaf on the plant
 
        Raises:
            ValueError: If plant_id is negative
            PlantArchitectureError: If the query fails or the library predates v1.3.85
 
        Example:
            >>> areas = plantarch.getPlantLeafAreas(plant_id)
            >>> print(f"{len(areas)} leaves, mean {sum(areas)/len(areas):.4f} m^2")
        """
        return self._plantFloatVector("getPlantLeafAreas", plant_id, "leaf areas")
 
    def getPlantInternodeLengths(self, plant_id: int) -> List[float]:
        """
        Get the built length of every internode on a plant.
 
        Measured along the internode's node positions as they were built, so a shoot
        whose geometry was prescribed by :meth:`addShootFromNodePositions` reports its
        measured lengths and a grown shoot reports what growth produced. See
        :meth:`getPlantLeafAreas` for why this differs from reading the shoot type's
        ``internode_length_max``.
 
        Internodes are visited shoot by shoot and then phytomer by phytomer, so the
        result has one entry per phytomer on the plant.
 
        Requires helios-core v1.3.85 or newer.
 
        Args:
            plant_id: ID of the plant instance
 
        Returns:
            Length (m) of each internode on the plant
 
        Raises:
            ValueError: If plant_id is negative
            PlantArchitectureError: If the query fails or the library predates v1.3.85
        """
        return self._plantFloatVector("getPlantInternodeLengths", plant_id, "internode lengths")
 
    def getPlantLeafInclinations(self, plant_id: int) -> List[float]:
        """
        Get the inclination angle of every leaf on a plant.
 
        The angle between each leaf blade and the horizontal, computed from its
        area-weighted normal so that a curved or folded blade is summarized by the
        direction it mostly faces. 0 degrees is a horizontal blade and 90 degrees a
        vertical one; because a blade is a surface, a normal pointing down describes the
        same inclination as its opposite pointing up, so the angle is folded about the
        horizontal and never exceeds 90 degrees.
 
        Ordering and the treatment of missing geometry match :meth:`getPlantLeafAreas`.
        A blade whose facet normals cancel exactly is additionally omitted, since it
        faces no single direction.
 
        Requires helios-core v1.3.85 or newer.
 
        Args:
            plant_id: ID of the plant instance
 
        Returns:
            Inclination angle (degrees, in [0, 90]) of each leaf on the plant
 
        Raises:
            ValueError: If plant_id is negative
            PlantArchitectureError: If the query fails or the library predates v1.3.85
        """
        return self._plantFloatVector("getPlantLeafInclinations", plant_id, "leaf inclinations")
 
    def isShootGeometryPrescribed(self, plant_id: int, shoot_id: int) -> bool:
        """
        Report whether a shoot's existing geometry was prescribed by the caller rather than generated.
 
        True for a shoot built by :meth:`addShootFromNodePositions`, whose internode path
        follows measured node positions. Such a shoot's existing phytomers are exempt
        from the re-scaling and re-curving performed by :meth:`advanceTime`, so a caller
        reading geometry back can tell which parts of a plant are measurement and which
        are model output.
 
        Requires helios-core v1.3.85 or newer.
 
        Args:
            plant_id: ID of the plant instance
            shoot_id: Shoot index within the plant
 
        Returns:
            True if the shoot was built from prescribed node positions
 
        Raises:
            ValueError: If either ID is negative
            PlantArchitectureError: If the query fails or the library predates v1.3.85
        """
        return self._shootScalarQuery("isShootGeometryPrescribed", plant_id, shoot_id,
                                      "prescribed-geometry state")
 
    def getPlantAge(self, plant_id: int) -> float:
        """
        Get the current age of a plant in days.
 
        Args:
            plant_id: ID of the plant instance
 
        Returns:
            Plant age in days
 
        Raises:
            ValueError: If plant_id is negative
            PlantArchitectureError: If retrieval fails
 
        Example:
            >>> age = plantarch.getPlantAge(plant_id)
            >>> print(f"Plant is {age} days old")
        """
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
 
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                return plantarch_wrapper.getPlantAge(self._plantarch_ptr, plant_id)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to get age for plant {plant_id}: {e}")
 
    def getPlantMaxAge(self, plant_id: int) -> float:
        """
        Get the maximum age of a plant, beyond which it stops growing.
 
        Args:
            plant_id: ID of the plant instance
 
        Returns:
            Maximum plant age in days. See :meth:`setPlantMaxAge`.
 
        Raises:
            ValueError: If plant_id is negative
            PlantArchitectureError: If retrieval fails
 
        Example:
            >>> max_age = plantarch.getPlantMaxAge(plant_id)
        """
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
        self._check_context_alive()
        try:
            return plantarch_wrapper.getPlantMaxAge(self._plantarch_ptr, plant_id)
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to get maximum age of plant {plant_id}: {e}")
 
    def setPlantMaxAge(self, plant_id: int, max_age: float) -> None:
        """
        Set the maximum age of a plant, beyond which it stops growing.
 
        Once a plant's age reaches this value, :meth:`advanceTime` stops advancing it and
        its geometry becomes static. The default is 999 days. Every plant model in the
        library sets its own value as part of its builder (an apple tree, for example,
        uses 1460 days), but a plant assembled manually with :meth:`addPlantInstance`
        keeps the default and so silently stops growing after 999 days.
 
        Setting a maximum age below the plant's current age is permitted, and freezes the
        plant at its current form.
 
        Args:
            plant_id: ID of the plant instance
            max_age: Maximum age of the plant in days. Must be non-negative.
 
        Raises:
            ValueError: If plant_id is negative or max_age is negative
            PlantArchitectureError: If the plant does not exist
 
        Example:
            >>> plantarch.setPlantMaxAge(plant_id, 1460.0)
        """
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
        if max_age < 0:
            raise ValueError(f"Maximum age must be non-negative, got {max_age}")
        self._check_context_alive()
        try:
            plantarch_wrapper.setPlantMaxAge(self._plantarch_ptr, plant_id, max_age)
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to set maximum age of plant {plant_id}: {e}")
 
    def getPlantHeight(self, plant_id: int) -> float:
        """
        Get the height of a plant in meters.
 
        Args:
            plant_id: ID of the plant instance
 
        Returns:
            Plant height in meters (vertical extent)
 
        Raises:
            ValueError: If plant_id is negative
            PlantArchitectureError: If retrieval fails
 
        Example:
            >>> height = plantarch.getPlantHeight(plant_id)
            >>> print(f"Plant is {height:.2f}m tall")
        """
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
 
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                return plantarch_wrapper.getPlantHeight(self._plantarch_ptr, plant_id)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to get height for plant {plant_id}: {e}")
 
    def getPlantLeafArea(self, plant_id: int) -> float:
        """
        Get the total leaf area of a plant in m².
 
        Leaf area is blade area: the petiolules (leaflet stalks) of compound leaves are
        excluded (helios-core 1.3.89+; earlier versions counted them as leaf).
 
        Args:
            plant_id: ID of the plant instance
 
        Returns:
            Total leaf area in square meters
 
        Raises:
            ValueError: If plant_id is negative
            PlantArchitectureError: If retrieval fails
 
        Example:
            >>> leaf_area = plantarch.getPlantLeafArea(plant_id)
            >>> print(f"Total leaf area: {leaf_area:.3f} m²")
        """
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
 
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                return plantarch_wrapper.sumPlantLeafArea(self._plantarch_ptr, plant_id)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to get leaf area for plant {plant_id}: {e}")
 
    def optionalOutputObjectData(self, object_data_labels: Union[str, List[str]]) -> None:
        """
        Enable optional output object data to be written to the Context.
 
        By default, the plant architecture model only writes a minimal set of
        object data. This method enables additional object data fields so that
        they are available on the Context's compound objects after building.
 
        Args:
            object_data_labels: A single label or a list of labels to enable.
                Valid labels include: "age", "rank", "plantID", "plant_name",
                "plant_height", "plant_type", "phenology_stage", "leafID",
                "peduncleID", "closedflowerID", "openflowerID", "fruitID",
                "carbohydrate_concentration". The special label "all" enables
                every available field.
 
        Raises:
            ValueError: If a label is empty or not a string
            PlantArchitectureError: If an invalid label is supplied or the
                operation otherwise fails
 
        Example:
            >>> plantarch.optionalOutputObjectData("age")
            >>> plantarch.optionalOutputObjectData(["rank", "plant_height"])
            >>> plantarch.optionalOutputObjectData("all")
        """
        if isinstance(object_data_labels, str):
            labels = [object_data_labels]
        else:
            labels = list(object_data_labels)
 
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                for label in labels:
                    plantarch_wrapper.optionalOutputObjectData(self._plantarch_ptr, label)
        except ValueError:
            raise
        except Exception as e:
            raise PlantArchitectureError(f"Failed to enable optional output object data: {e}")
 
    def setPlantPhenologicalThresholds(
        self,
        plant_id: int,
        time_to_dormancy_break: float,
        time_to_flower_initiation: float,
        time_to_flower_opening: float,
        time_to_fruit_set: float,
        time_to_fruit_maturity: float,
        time_to_dormancy: float,
        max_leaf_lifespan: float = 1e6,
        is_evergreen: bool = False
    ) -> None:
        """
        Set phenological timing thresholds for plant developmental stages.
 
        Controls the timing of key phenological events based on thermal time
        or calendar time depending on the plant model.
 
        Args:
            plant_id: ID of the plant instance
            time_to_dormancy_break: Degree-days or days until dormancy ends
            time_to_flower_initiation: Time until flower buds are initiated
            time_to_flower_opening: Time until flowers open
            time_to_fruit_set: Time until fruit begins developing
            time_to_fruit_maturity: Time until fruit reaches maturity
            time_to_dormancy: Time until plant enters dormancy
            max_leaf_lifespan: Maximum leaf lifespan in days (default: 1e6)
            is_evergreen: If True, the plant retains leaves through dormancy
                instead of shedding them at senescence (default: False)
 
        Raises:
            ValueError: If plant_id is negative
            PlantArchitectureError: If phenology setting fails
 
        Example:
            >>> # Set phenology for perennial fruit tree
            >>> plantarch.setPlantPhenologicalThresholds(
            ...     plant_id=plant_id,
            ...     time_to_dormancy_break=60,    # Spring: 60 degree-days
            ...     time_to_flower_initiation=90,  # Early spring flowering
            ...     time_to_flower_opening=105,    # Bloom period
            ...     time_to_fruit_set=120,         # Fruit set after pollination
            ...     time_to_fruit_maturity=200,    # Summer fruit maturation
            ...     time_to_dormancy=280,          # Fall dormancy
            ...     max_leaf_lifespan=180          # Deciduous - 6 month leaf life
            ... )
        """
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
 
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                plantarch_wrapper.setPlantPhenologicalThresholds(
                    self._plantarch_ptr,
                    plant_id,
                    time_to_dormancy_break,
                    time_to_flower_initiation,
                    time_to_flower_opening,
                    time_to_fruit_set,
                    time_to_fruit_maturity,
                    time_to_dormancy,
                    max_leaf_lifespan,
                    is_evergreen
                )
        except Exception as e:
            raise PlantArchitectureError(f"Failed to set phenological thresholds for plant {plant_id}: {e}")
 
    def disablePlantPhenology(self, plant_id: int) -> None:
        """
        Disable phenological progression for a plant.
 
        The plant continues to grow, but no phenological stage is ever scheduled: it does not
        enter dormancy, and flower and fruit stages are skipped. This is the explicit form of the
        state a plant is already in when :meth:`setPlantPhenologicalThresholds` has never been
        called on it, so it is mainly useful for turning phenology back off on a plant that had
        thresholds set earlier.
 
        Args:
            plant_id: Identifier of the plant whose phenology is to be disabled
 
        Warning:
            Avoid calling this on a plant that already has fruiting buds: a later
            :meth:`advanceTime` can compute a negative fruit scale factor. A plant that never had
            thresholds set is already in the no-phenology state and does not need it.
 
        Raises:
            ValueError: If plant_id is negative
            PlantArchitectureError: If disabling phenology fails
 
        Example:
            >>> plantarch.setPlantPhenologicalThresholds(plant_id, 60, 90, 105, 120, 200, 280)
            >>> plantarch.disablePlantPhenology(plant_id)  # growth only, no dormancy or fruiting
        """
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
 
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                plantarch_wrapper.disablePlantPhenology(self._plantarch_ptr, plant_id)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to disable phenology for plant {plant_id}: {e}")
 
    # Dormancy control methods
    def makePlantDormant(self, plant_id: int) -> None:
        """
        Force a plant into a dormant state immediately.
 
        It is the counterpart to scheduling dormancy
        through :meth:`setPlantPhenologicalThresholds`: this forces the state now, rather than
        waiting for a degree-day threshold to be crossed.
 
        Dormancy strips the plant's leaves and marks its non-dormant buds dormant, so a
        custom-built plant can be put into the same over-winter state that a library-built
        perennial reaches through phenology.
 
        Args:
            plant_id: Identifier of the plant to make dormant
 
        Raises:
            ValueError: If plant_id is negative
            PlantArchitectureError: If the plant does not exist or the call fails
 
        Example:
            >>> plant_id = plantarch.addPlantInstance(vec3(0, 0, 0), 0.0)
            >>> plantarch.addBaseStemShoot(plant_id, 3, AxisRotation(0, 0, 0),
            ...                            0.01, 0.1, 1.0, 1.0, 0.9, "trifoliate")
            >>> plantarch.makePlantDormant(plant_id)
        """
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
 
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                plantarch_wrapper.makePlantDormant(self._plantarch_ptr, plant_id)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to make plant {plant_id} dormant: {e}")
 
    def breakPlantDormancy(self, plant_id: int) -> None:
        """
        Break dormancy for all shoots on a plant, returning it to an active state.
 
        This is the counterpart to :meth:`makePlantDormant`. Note that it only revives buds that
        are not dead, so a plant that was repeatedly made dormant may not recover every bud.
 
        Args:
            plant_id: Identifier of the plant whose dormancy should be broken
 
        Raises:
            ValueError: If plant_id is negative
            PlantArchitectureError: If the plant does not exist or the call fails
 
        Example:
            >>> plantarch.makePlantDormant(plant_id)
            >>> plantarch.breakPlantDormancy(plant_id)  # resume growth in spring
        """
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
 
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                plantarch_wrapper.breakPlantDormancy(self._plantarch_ptr, plant_id)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to break dormancy for plant {plant_id}: {e}")
 
    def isPlantDormant(self, plant_id: int) -> bool:
        """
        Check whether a plant is dormant.
 
        Args:
            plant_id: Identifier of the plant to check
 
        Returns:
            True if all shoots on the plant are dormant, False otherwise
 
        Raises:
            ValueError: If plant_id is negative
            PlantArchitectureError: If the plant does not exist or the query fails
 
        Example:
            >>> plantarch.makePlantDormant(plant_id)
            >>> plantarch.isPlantDormant(plant_id)
            True
        """
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
 
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                return plantarch_wrapper.isPlantDormant(self._plantarch_ptr, plant_id)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to query dormancy state for plant {plant_id}: {e}")
 
    # Pruning and organ removal methods
    def pruneBranch(self, plant_id: int, shoot_id: int, node_index: int) -> None:
        """
        Prune a shoot at a node, removing that node and everything distal to it.
 
        The phytomer at ``node_index`` is deleted along with every phytomer above it
        on the same shoot, and the cut recurses into every child shoot attached at or
        above that node. The shoot's woody internode tube is trimmed back to the cut
        and its apical bud is terminated, so the pruned axis will not resume growing.
        Pruning at ``node_index=0`` therefore removes the entire shoot and its whole
        branch system.
 
        Args:
            plant_id: ID of the plant instance
            shoot_id: Shoot index within the plant (see :meth:`getAllShootIDs`)
            node_index: Node on the shoot to cut at, in ``[0, node_count)``
 
        Raises:
            ValueError: If any identifier is negative
            PlantArchitectureError: If the plant or shoot does not exist, if
                ``node_index`` is beyond the shoot's current node count, or if the
                native call fails
 
        Note:
            A pruned shoot currently keeps its ID in :meth:`getAllShootIDs` with a
            ``node_count`` of 0 rather than disappearing. Do not rely on either
            behavior; traverse with :meth:`getShoot` and treat ``node_count == 0``
            as "nothing left here".
 
            Called from a phytomer creation or callback function (see
            :meth:`setPhytomerCreationFunction`, :meth:`setPhytomerCallbackFunction`), the
            arguments are checked immediately but the cut is deferred: it is applied at the end
            of the current time step of :meth:`advanceTime`, or before the build call that ran
            the function returns. Until then the shoot still looks uncut. Deferred cuts are
            applied in the order requested, and one whose shoot or node an earlier cut already
            removed does nothing.
 
        Example:
            >>> # Remove a whole branch and everything growing off it
            >>> plantarch.pruneBranch(plant_id, shoot_id=3, node_index=0)
            >>> # Head back a leader, keeping its lowest 5 nodes
            >>> plantarch.pruneBranch(plant_id, shoot_id=0, node_index=5)
        """
        if plant_id < 0 or shoot_id < 0 or node_index < 0:
            raise ValueError("Plant ID, shoot ID and node index must be non-negative")
 
        self._check_context_alive()
        try:
            plantarch_wrapper.pruneBranch(self._plantarch_ptr, plant_id, shoot_id, node_index)
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to prune shoot {shoot_id} of plant {plant_id} at node {node_index}: {e}")
 
    def harvestPlant(self, plant_id: int) -> None:
        """
        Harvest a plant by removing its flowers and fruit.
 
        Every non-dormant floral bud on the plant is killed, which deletes the
        associated flower, fruit and peduncle geometry from the Context. Vegetative
        structure is untouched and the plant continues to grow afterwards.
 
        Args:
            plant_id: ID of the plant instance to harvest
 
        Raises:
            ValueError: If plant_id is negative
            PlantArchitectureError: If the plant does not exist or the call fails
 
        Note:
            Leaves are **not** removed. Use :meth:`removePlantLeaves` to defoliate.
 
        Example:
            >>> before = len(plantarch.getPlantFruitObjectIDs(plant_id))
            >>> plantarch.harvestPlant(plant_id)
            >>> len(plantarch.getPlantFruitObjectIDs(plant_id)) < before
            True
        """
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
 
        self._check_context_alive()
        try:
            plantarch_wrapper.harvestPlant(self._plantarch_ptr, plant_id)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to harvest plant {plant_id}: {e}")
 
    def removePlantLeaves(self, plant_id: int) -> None:
        """
        Remove all leaves from every shoot on a plant.
 
        Leaf and petiole geometry is deleted from the Context. Buds are left alive,
        so the plant can produce new leaves as it continues to grow.
 
        Args:
            plant_id: ID of the plant instance to defoliate
 
        Raises:
            ValueError: If plant_id is negative
            PlantArchitectureError: If the plant does not exist or the call fails
 
        Example:
            >>> plantarch.removePlantLeaves(plant_id)
            >>> plantarch.getPlantLeafObjectIDs(plant_id)
            []
        """
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
 
        self._check_context_alive()
        try:
            plantarch_wrapper.removePlantLeaves(self._plantarch_ptr, plant_id)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to remove leaves from plant {plant_id}: {e}")
 
    def removeShootLeaves(self, plant_id: int, shoot_id: int) -> None:
        """
        Remove all leaves from a single shoot.
 
        Args:
            plant_id: ID of the plant instance
            shoot_id: Shoot index within the plant (see :meth:`getAllShootIDs`)
 
        Raises:
            ValueError: If either identifier is negative
            PlantArchitectureError: If the plant or shoot does not exist
 
        Example:
            >>> # Strip the leaves off a grapevine trunk, as in a trained architecture
            >>> plantarch.removeShootLeaves(plant_id, shoot_id=0)
        """
        self._removeShootOrgans("removeShootLeaves", plant_id, shoot_id, "leaves")
 
    def removeShootVegetativeBuds(self, plant_id: int, shoot_id: int) -> None:
        """
        Mark every vegetative bud on a single shoot as dead.
 
        Despite the name, nothing is removed: each axillary vegetative bud on the shoot
        is set to ``BudState.DEAD`` and the bud entries themselves stay in place, so
        :meth:`getShootVegetativeBudCount` still sees them and the unfiltered count is
        unchanged. Dead buds are skipped when dormancy breaks, so the shoot keeps its
        existing structure but produces no new lateral shoots -- the standard way to stop
        a trained axis from throwing new canes, and to stop the old wood of a
        reconstructed tree re-growing.
 
        This is exactly equivalent to setting every bud on the shoot to
        ``BudState.DEAD``; the shoot's own apex is unaffected, so pair it with
        :meth:`terminateApicalBud` to stop the shoot extending as well.
 
        Args:
            plant_id: ID of the plant instance
            shoot_id: Shoot index within the plant (see :meth:`getAllShootIDs`)
 
        Raises:
            ValueError: If either identifier is negative
            PlantArchitectureError: If the plant or shoot does not exist
 
        See Also:
            :meth:`getShootVegetativeBudCount`, to confirm the buds are dead rather than
            gone, and :meth:`terminateApicalBud`, for the shoot's apex.
 
        Example:
            >>> plantarch.removeShootVegetativeBuds(plant_id, shoot_id=1)
        """
        self._removeShootOrgans("removeShootVegetativeBuds", plant_id, shoot_id,
                                "vegetative buds")
 
    def removeShootFloralBuds(self, plant_id: int, shoot_id: int) -> None:
        """
        Kill all floral buds on a single shoot.
 
        Existing flower, fruit and peduncle geometry on the shoot is deleted and no
        new flowers will form there.
 
        Args:
            plant_id: ID of the plant instance
            shoot_id: Shoot index within the plant (see :meth:`getAllShootIDs`)
 
        Raises:
            ValueError: If either identifier is negative
            PlantArchitectureError: If the plant or shoot does not exist
 
        Example:
            >>> plantarch.removeShootFloralBuds(plant_id, shoot_id=1)
        """
        self._removeShootOrgans("removeShootFloralBuds", plant_id, shoot_id, "floral buds")
 
    def _removeShootOrgans(self, wrapper_fn_name: str, plant_id: int, shoot_id: int,
                           organ_description: str) -> None:
        """Shared body for the three shoot-level organ removal methods."""
        if plant_id < 0 or shoot_id < 0:
            raise ValueError("Plant ID and shoot ID must be non-negative")
 
        self._check_context_alive()
        try:
            getattr(plantarch_wrapper, wrapper_fn_name)(self._plantarch_ptr, plant_id, shoot_id)
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to remove {organ_description} from shoot {shoot_id} "
                f"of plant {plant_id}: {e}")
 
    # Shoot hierarchy traversal
    def getShootIDsByRank(self, plant_id: int) -> Dict[int, List[int]]:
        """
        Group a plant's shoot IDs by branching rank.
 
        Rank 0 is the base stem, rank 1 its direct branches, and so on. Shoots that have
        been pruned away are not included.
 
        Args:
            plant_id: ID of the plant instance
 
        Returns:
            Dict mapping rank to the list of shoot IDs at that rank. Ranks with no live
            shoots are omitted from the dict.
 
        Raises:
            ValueError: If plant_id is negative
            PlantArchitectureError: If the plant does not exist
 
        Example:
            >>> by_rank = plantarch.getShootIDsByRank(plant_id)
            >>> print(f"{len(by_rank.get(1, []))} primary branches")
        """
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
        self._check_context_alive()
        try:
            groups = plantarch_wrapper.getShootIDsByRank(self._plantarch_ptr, plant_id)
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to get shoot IDs by rank for plant {plant_id}: {e}")
 
        # Native returns one group per rank, indexed by rank, with empty groups for ranks
        # that have no live shoots. The dict form drops those empties.
        return {rank: shoot_ids for rank, shoot_ids in enumerate(groups) if shoot_ids}
 
    def getTerminalShootIDs(self, plant_id: int) -> List[int]:
        """
        Get the plant's terminal shoots -- those carrying no child shoots.
 
        These are the tips of the shoot tree. Note that this is a topological test rather
        than a botanical one: a shoot whose axis is continued by :meth:`appendShoot` has
        that continuation as a child and so is not terminal. Pruned shoots are omitted.
 
        Args:
            plant_id: ID of the plant instance
 
        Returns:
            List of terminal shoot IDs.
 
        Raises:
            ValueError: If plant_id is negative
            PlantArchitectureError: If the plant does not exist
 
        Example:
            >>> tips = plantarch.getTerminalShootIDs(plant_id)
        """
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
        self._check_context_alive()
        try:
            return plantarch_wrapper.getTerminalShootIDs(self._plantarch_ptr, plant_id)
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to get terminal shoots for plant {plant_id}: {e}")
 
    # Bulk pruning built on the traversal helpers
    def pruneShootsByRank(self, plant_id: int, min_rank: int) -> List[int]:
        """
        Prune every shoot at or above a given branching rank.
 
        This is the "remove higher-order branches" thinning operation: passing
        ``min_rank=3`` leaves the base stem and its first two orders of branching
        intact and cuts everything finer. Because :meth:`pruneBranch` already
        recurses into child shoots, only the shallowest shoot on each pruned axis is
        cut and the rest follow.
 
        Args:
            plant_id: ID of the plant instance
            min_rank: Lowest rank to prune. Must be at least 1 -- rank 0 is the base
                stem, and pruning it would destroy the plant.
 
        Returns:
            Ascending list of the shoot IDs actually cut. Shoots removed as a side
            effect of a shallower cut are not listed.
 
        Raises:
            ValueError: If plant_id is negative or min_rank is less than 1
            PlantArchitectureError: If the plant does not exist
 
        Note:
            To remove a whole plant use :meth:`deletePlantInstance`; to cut the base
            stem itself call :meth:`pruneBranch` directly.
 
        Example:
            >>> pruned = plantarch.pruneShootsByRank(plant_id, min_rank=3)
            >>> print(f"Cut {len(pruned)} higher-order branches")
        """
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
        if min_rank < 1:
            raise ValueError(
                f"min_rank must be at least 1, got {min_rank}. Rank 0 is the base stem; "
                "use deletePlantInstance() to remove the whole plant, or pruneBranch() "
                "to cut the base stem explicitly.")
 
        by_rank = self.getShootIDsByRank(plant_id)
        targets = {shoot_id
                   for rank, shoot_ids in by_rank.items() if rank >= min_rank
                   for shoot_id in shoot_ids}
        return self._pruneShallowest(plant_id, targets)
 
    def pruneShootSubtree(self, plant_id: int, shoot_id: int,
                          include_self: bool = True) -> List[int]:
        """
        Prune a shoot and everything growing off it.
 
        Args:
            plant_id: ID of the plant instance
            shoot_id: Root of the branch system to remove
            include_self: If True (default) the shoot itself is cut at node 0. If
                False the shoot is kept and only its child shoots are cut.
 
        Returns:
            Ascending list of the shoot IDs actually cut. Shoots removed as a side
            effect of a shallower cut are not listed.
 
        Raises:
            ValueError: If either identifier is negative
            PlantArchitectureError: If the plant or shoot does not exist
 
        Example:
            >>> # Remove a whole branch system
            >>> plantarch.pruneShootSubtree(plant_id, shoot_id=2)
            >>> # Keep the cane but strip everything growing off it
            >>> plantarch.pruneShootSubtree(plant_id, shoot_id=2, include_self=False)
        """
        if plant_id < 0 or shoot_id < 0:
            raise ValueError("Plant ID and shoot ID must be non-negative")
 
        if include_self:
            return self._pruneShallowest(plant_id, {shoot_id})
        return self._pruneShallowest(plant_id, set(self._liveChildShootIDs(plant_id, shoot_id)))
 
    def pruneTerminalShoots(self, plant_id: int, stride: int = 2) -> List[int]:
        """
        Thin a plant by pruning every *stride*-th terminal shoot.
 
        Terminal shoots are taken in ascending ID order and every ``stride``-th one
        starting from the first is cut, so ``stride=2`` removes about half the tips
        and ``stride=3`` about a third. The base stem is never cut.
 
        Args:
            plant_id: ID of the plant instance
            stride: Spacing between pruned tips. Must be at least 1; ``stride=1``
                prunes every terminal shoot.
 
        Returns:
            Ascending list of the shoot IDs actually cut.
 
        Raises:
            ValueError: If plant_id is negative or stride is less than 1
            PlantArchitectureError: If the plant does not exist
 
        Example:
            >>> pruned = plantarch.pruneTerminalShoots(plant_id, stride=2)
            >>> print(f"Thinned {len(pruned)} tips")
        """
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
        if stride < 1:
            raise ValueError(f"stride must be at least 1, got {stride}")
 
        targets = set()
        for index, shoot_id in enumerate(self.getTerminalShootIDs(plant_id)):
            if index % stride != 0:
                continue
            if self.getShootRank(plant_id, shoot_id) == 0:
                continue  # never cut the base stem
            targets.add(shoot_id)
        return self._pruneShallowest(plant_id, targets)
 
    def _childShootIDsOrEmpty(self, plant_id: int, shoot_id: int) -> List[int]:
        """Return a shoot's child IDs, or an empty list if it no longer resolves."""
        try:
            return self.getShootChildIDs(plant_id, shoot_id)
        except PlantArchitectureError:
            return []
 
    def _liveChildShootIDs(self, plant_id: int, shoot_id: int) -> List[int]:
        """Child shoot IDs that have not been pruned away, ascending."""
        # getChildShootIDs already excludes pruned shoots, so no second filter is needed.
        return sorted(set(self._childShootIDsOrEmpty(plant_id, shoot_id)))
 
    def _pruneShallowest(self, plant_id: int, target_shoot_ids) -> List[int]:
        """Prune every target that something shallower has not already removed.
 
        pruneBranch() recurses into child shoots, so cutting a shoot also empties
        every shoot descended from it. Targets are therefore visited in ascending
        shoot ID order -- a child shoot is always created after its parent and so
        always has the higher ID -- which puts each shoot after its ancestors. By
        the time a descendant of an already-cut shoot comes up it has nothing left
        on it and is skipped, so no shoot is cut twice and the returned list holds
        only the cuts that actually did something.
        """
        pruned = []
        for shoot_id in sorted(set(target_shoot_ids)):
            if self._isPrunedOrGone(plant_id, shoot_id):
                continue  # gone already, either pruned above or pruned earlier
            self.pruneBranch(plant_id, shoot_id, 0)
            pruned.append(shoot_id)
        return pruned
 
    def _isPrunedOrGone(self, plant_id: int, shoot_id: int) -> bool:
        """Whether a shoot has been pruned away or no longer resolves at all."""
        try:
            return self.isShootPruned(plant_id, shoot_id)
        except PlantArchitectureError:
            return True
 
    # Collision detection methods
    def enableSoftCollisionAvoidance(self,
                                    target_object_UUIDs: Optional[List[int]] = None,
                                    target_object_IDs: Optional[List[int]] = None,
                                    enable_petiole_collision: bool = False,
                                    enable_fruit_collision: bool = False) -> None:
        """
        Enable soft collision avoidance for procedural plant growth.
 
        This method enables the collision detection system that guides plant growth away from
        obstacles and other plants. The system uses cone-based gap detection to find optimal
        growth directions that minimize collisions while maintaining natural plant architecture.
 
        Args:
            target_object_UUIDs: List of primitive UUIDs to avoid collisions with. If empty,
                                avoids all geometry in the context.
            target_object_IDs: List of compound object IDs to avoid collisions with.
            enable_petiole_collision: Enable collision detection for leaf petioles
            enable_fruit_collision: Enable collision detection for fruit organs
 
        Raises:
            PlantArchitectureError: If collision detection activation fails
 
        Note:
            Collision detection adds computational overhead. Use setStaticObstacles() to mark
            static geometry for BVH optimization and improved performance.
 
        Example:
            >>> # Avoid all geometry
            >>> plantarch.enableSoftCollisionAvoidance()
            >>>
            >>> # Avoid specific obstacles
            >>> obstacle_uuids = context.getAllUUIDs()
            >>> plantarch.enableSoftCollisionAvoidance(target_object_UUIDs=obstacle_uuids)
            >>>
            >>> # Enable collision detection for petioles and fruit
            >>> plantarch.enableSoftCollisionAvoidance(
            ...     enable_petiole_collision=True,
            ...     enable_fruit_collision=True
            ... )
        """
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                plantarch_wrapper.enableSoftCollisionAvoidance(
                    self._plantarch_ptr,
                    target_UUIDs=target_object_UUIDs,
                    target_IDs=target_object_IDs,
                    enable_petiole=enable_petiole_collision,
                    enable_fruit=enable_fruit_collision
                )
        except Exception as e:
            raise PlantArchitectureError(f"Failed to enable soft collision avoidance: {e}")
 
    def enableGroundClipping(self, ground_height: float = 0.0) -> None:
        """
        Enable automatic removal of plant organs that fall below the ground plane.
 
        Organ vertices below `ground_height` are clipped as plant geometry is
        built, which prevents drooping leaves and low branches from poking
        through a ground tile.
 
        Args:
            ground_height: Height of the ground plane (default 0.0)
 
        Raises:
            ValueError: If ground_height is not a number
            PlantArchitectureError: If the call fails
 
        Example:
            >>> plantarch.enableGroundClipping(0.0)
            >>> plantarch.advanceTime(30.0)
        """
        self._check_context_alive()
 
        if isinstance(ground_height, bool) or not isinstance(ground_height, (int, float)):
            raise ValueError(f"Ground height must be a number, got {type(ground_height).__name__}")
 
        try:
            plantarch_wrapper.enableGroundClipping(self._plantarch_ptr, float(ground_height))
        except Exception as e:
            raise PlantArchitectureError(f"Failed to enable ground clipping: {e}")
 
    def disableMessages(self) -> None:
        """
        Suppress standard output from the plantarchitecture plugin.
 
        This silences progress bars and informational messages the C++ plugin
        writes to stdout, including the "BVH not cached" warning emitted during
        the first growth steps of a collision-enabled canopy (before any plant
        geometry exists for the BVH to contain).
 
        Raises:
            PlantArchitectureError: If the call fails
 
        Example:
            >>> plantarch.disableMessages()
            >>> plantarch.advanceTime(30.0)  # runs quietly
        """
        self._check_context_alive()
        try:
            plantarch_wrapper.disableMessages(self._plantarch_ptr)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to disable messages: {e}")
 
    def enableMessages(self) -> None:
        """
        Re-enable standard output from the plantarchitecture plugin.
 
        Raises:
            PlantArchitectureError: If the call fails
 
        Example:
            >>> plantarch.enableMessages()
        """
        self._check_context_alive()
        try:
            plantarch_wrapper.enableMessages(self._plantarch_ptr)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to enable messages: {e}")
 
    def disableCollisionDetection(self) -> None:
        """
        Disable collision detection for plant growth.
 
        This method turns off the collision detection system, allowing plants to grow
        without checking for obstacles. This improves performance but plants may grow
        through obstacles and other geometry.
 
        Raises:
            PlantArchitectureError: If disabling fails
 
        Example:
            >>> plantarch.disableCollisionDetection()
        """
        self._check_context_alive()
        try:
            plantarch_wrapper.disableCollisionDetection(self._plantarch_ptr)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to disable collision detection: {e}")
 
    def setSoftCollisionAvoidanceParameters(self,
                                           view_half_angle_deg: float = 80.0,
                                           look_ahead_distance: float = 0.1,
                                           sample_count: int = 256,
                                           inertia_weight: float = 0.4) -> None:
        """
        Configure parameters for soft collision avoidance algorithm.
 
        These parameters control the cone-based gap detection algorithm that guides
        plant growth away from obstacles. Adjusting these values allows fine-tuning
        the balance between collision avoidance and natural growth patterns.
 
        Args:
            view_half_angle_deg: Half-angle of detection cone in degrees (0-180).
                                Default 80° provides wide field of view.
            look_ahead_distance: Distance to look ahead for collisions in meters.
                                Larger values detect distant obstacles. Default 0.1m.
            sample_count: Number of ray samples within cone. More samples improve
                         accuracy but reduce performance. Default 256.
            inertia_weight: Weight for previous growth direction (0-1). Higher values
                           make growth smoother but less responsive. Default 0.4.
 
        Raises:
            ValueError: If parameters are outside valid ranges
            PlantArchitectureError: If parameter setting fails
 
        Example:
            >>> # Use default parameters (recommended)
            >>> plantarch.setSoftCollisionAvoidanceParameters()
            >>>
            >>> # Tune for dense canopy with close obstacles
            >>> plantarch.setSoftCollisionAvoidanceParameters(
            ...     view_half_angle_deg=60.0,  # Narrower detection cone
            ...     look_ahead_distance=0.05,   # Shorter look-ahead
            ...     sample_count=512,           # More accurate detection
            ...     inertia_weight=0.3          # More responsive to obstacles
            ... )
        """
        # Validate parameters
        if not (0 <= view_half_angle_deg <= 180):
            raise ValueError(f"view_half_angle_deg must be between 0 and 180, got {view_half_angle_deg}")
        if look_ahead_distance <= 0:
            raise ValueError(f"look_ahead_distance must be positive, got {look_ahead_distance}")
        if sample_count <= 0:
            raise ValueError(f"sample_count must be positive, got {sample_count}")
        if not (0 <= inertia_weight <= 1):
            raise ValueError(f"inertia_weight must be between 0 and 1, got {inertia_weight}")
 
        self._check_context_alive()
        try:
            plantarch_wrapper.setSoftCollisionAvoidanceParameters(
                self._plantarch_ptr,
                view_half_angle_deg,
                look_ahead_distance,
                sample_count,
                inertia_weight
            )
        except Exception as e:
            raise PlantArchitectureError(f"Failed to set collision avoidance parameters: {e}")
 
    def setCollisionRelevantOrgans(self,
                                  include_internodes: bool = False,
                                  include_leaves: bool = True,
                                  include_petioles: bool = False,
                                  include_flowers: bool = False,
                                  include_fruit: bool = False) -> None:
        """
        Specify which plant organs participate in collision detection.
 
        This method allows filtering which organs are considered during collision detection,
        enabling optimization by excluding organs unlikely to cause problematic collisions.
 
        Args:
            include_internodes: Include stem internodes in collision detection
            include_leaves: Include leaf blades in collision detection
            include_petioles: Include leaf petioles in collision detection
            include_flowers: Include flowers in collision detection
            include_fruit: Include fruit in collision detection
 
        Raises:
            PlantArchitectureError: If organ filtering fails
 
        Example:
            >>> # Only detect collisions for stems and leaves (default behavior)
            >>> plantarch.setCollisionRelevantOrgans(
            ...     include_internodes=True,
            ...     include_leaves=True
            ... )
            >>>
            >>> # Include all organs
            >>> plantarch.setCollisionRelevantOrgans(
            ...     include_internodes=True,
            ...     include_leaves=True,
            ...     include_petioles=True,
            ...     include_flowers=True,
            ...     include_fruit=True
            ... )
        """
        self._check_context_alive()
        try:
            plantarch_wrapper.setCollisionRelevantOrgans(
                self._plantarch_ptr,
                include_internodes,
                include_leaves,
                include_petioles,
                include_flowers,
                include_fruit
            )
        except Exception as e:
            raise PlantArchitectureError(f"Failed to set collision-relevant organs: {e}")
 
    def enableSolidObstacleAvoidance(self,
                                    obstacle_UUIDs: List[int],
                                    avoidance_distance: float = 0.5,
                                    enable_fruit_adjustment: bool = False,
                                    enable_obstacle_pruning: bool = False) -> None:
        """
        Enable hard obstacle avoidance for specified geometry.
 
        This method configures solid obstacles that plants cannot grow through. Unlike soft
        collision avoidance (which guides growth), solid obstacles cause complete growth
        termination when encountered within the avoidance distance.
 
        Args:
            obstacle_UUIDs: List of primitive UUIDs representing solid obstacles
            avoidance_distance: Minimum distance to maintain from obstacles (meters).
                               Growth stops if obstacles are closer. Default 0.5m.
            enable_fruit_adjustment: Adjust fruit positions away from obstacles
            enable_obstacle_pruning: Remove plant organs that penetrate obstacles
 
        Raises:
            ValueError: If obstacle_UUIDs is empty or avoidance_distance is non-positive
            PlantArchitectureError: If solid obstacle configuration fails
 
        Example:
            >>> # Simple solid obstacle avoidance
            >>> wall_uuids = [1, 2, 3, 4]  # UUIDs of wall primitives
            >>> plantarch.enableSolidObstacleAvoidance(wall_uuids)
            >>>
            >>> # Close avoidance with fruit adjustment
            >>> plantarch.enableSolidObstacleAvoidance(
            ...     obstacle_UUIDs=wall_uuids,
            ...     avoidance_distance=0.1,
            ...     enable_fruit_adjustment=True
            ... )
        """
        if not obstacle_UUIDs:
            raise ValueError("Obstacle UUIDs list cannot be empty")
        if avoidance_distance <= 0:
            raise ValueError(f"avoidance_distance must be positive, got {avoidance_distance}")
 
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                plantarch_wrapper.enableSolidObstacleAvoidance(
                    self._plantarch_ptr,
                    obstacle_UUIDs,
                    avoidance_distance,
                    enable_fruit_adjustment,
                    enable_obstacle_pruning
                )
        except Exception as e:
            raise PlantArchitectureError(f"Failed to enable solid obstacle avoidance: {e}")
 
    def setStaticObstacles(self, target_UUIDs: List[int]) -> None:
        """
        Mark geometry as static obstacles for collision detection optimization.
 
        This method tells the collision detection system that certain geometry will not
        move during the simulation. The system can then build an optimized Bounding Volume
        Hierarchy (BVH) for these obstacles, significantly improving collision detection
        performance in scenes with many static obstacles.
 
        Args:
            target_UUIDs: List of primitive UUIDs representing static obstacles
 
        Raises:
            ValueError: If target_UUIDs is empty
            PlantArchitectureError: If static obstacle configuration fails
 
        Note:
            Collision avoidance must be enabled BEFORE calling this method -- the
            native call raises "Collision detection must be enabled before setting
            static obstacles" otherwise.
            Static obstacles cannot be modified or moved after being marked static.
 
        Example:
            >>> # Enable collision avoidance first
            >>> plantarch.enableSoftCollisionAvoidance()
            >>> # Then mark ground and building geometry as static
            >>> static_uuids = ground_uuids + building_uuids
            >>> plantarch.setStaticObstacles(static_uuids)
        """
        if not target_UUIDs:
            raise ValueError("target_UUIDs list cannot be empty")
 
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                plantarch_wrapper.setStaticObstacles(self._plantarch_ptr, target_UUIDs)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to set static obstacles: {e}")
 
    def getPlantCollisionRelevantObjectIDs(self, plant_id: int) -> List[int]:
        """
        Get object IDs of collision-relevant geometry for a specific plant.
 
        This method returns the subset of plant geometry that participates in collision
        detection, as filtered by setCollisionRelevantOrgans(). Useful for visualization
        and debugging collision detection behavior.
 
        Args:
            plant_id: ID of the plant instance
 
        Returns:
            List of object IDs for collision-relevant plant geometry
 
        Raises:
            ValueError: If plant_id is negative
            PlantArchitectureError: If retrieval fails
 
        Example:
            >>> # Get collision-relevant geometry
            >>> collision_obj_ids = plantarch.getPlantCollisionRelevantObjectIDs(plant_id)
            >>> print(f"Plant has {len(collision_obj_ids)} collision-relevant objects")
            >>>
            >>> # Highlight collision geometry in visualization
            >>> for obj_id in collision_obj_ids:
            ...     context.setObjectColor(obj_id, RGBcolor(1, 0, 0))  # Red
        """
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
 
        self._check_context_alive()
        try:
            return plantarch_wrapper.getPlantCollisionRelevantObjectIDs(self._plantarch_ptr, plant_id)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to get collision-relevant object IDs for plant {plant_id}: {e}")
 
    # File I/O methods
    def writePlantMeshVertices(self, plant_id: int, filename: Union[str, Path]) -> None:
        """
        Write all plant mesh vertices to file for external processing.
 
        This method exports all vertex coordinates (x,y,z) for every primitive in the plant,
        writing one vertex per line. Useful for external processing such as computing bounding
        volumes, convex hulls, or performing custom geometric analysis.
 
        Args:
            plant_id: ID of the plant instance to export
            filename: Path to output file (absolute or relative to current working directory)
 
        Raises:
            ValueError: If plant_id is negative or filename is empty
            PlantArchitectureError: If plant doesn't exist or file cannot be written
 
        Example:
            >>> # Export vertices for convex hull analysis
            >>> plantarch.writePlantMeshVertices(plant_id, "plant_vertices.txt")
            >>>
            >>> # Use with Path object
            >>> from pathlib import Path
            >>> output_dir = Path("output")
            >>> output_dir.mkdir(exist_ok=True)
            >>> plantarch.writePlantMeshVertices(plant_id, output_dir / "vertices.txt")
        """
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
        if not filename:
            raise ValueError("Filename cannot be empty")
 
        # Resolve path before changing directory
        absolute_path = _resolve_user_path(filename)
 
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                plantarch_wrapper.writePlantMeshVertices(
                    self._plantarch_ptr, plant_id, absolute_path
                )
        except Exception as e:
            raise PlantArchitectureError(f"Failed to write plant mesh vertices to {filename}: {e}")
 
    def writePlantStructureXML(self, plant_id: int, filename: Union[str, Path]) -> None:
        """
        Save plant structure to XML file for later loading.
 
        This method exports the complete plant architecture to an XML file, including
        all shoots, phytomers, organs, and their properties. The saved plant can be
        reloaded later using readPlantStructureXML().
 
        Args:
            plant_id: ID of the plant instance to save
            filename: Path to output XML file (absolute or relative to current working directory)
 
        Raises:
            ValueError: If plant_id is negative or filename is empty
            PlantArchitectureError: If plant doesn't exist or file cannot be written
 
        Note:
            The XML format preserves the complete plant state including:
            - Shoot structure and hierarchy
            - Phytomer properties and development stage
            - Organ geometry and attributes
            - Growth parameters and phenological state
 
        Example:
            >>> # Save plant at current growth stage
            >>> plantarch.writePlantStructureXML(plant_id, "bean_day30.xml")
            >>>
            >>> # Later, reload the saved plant
            >>> loaded_plant_ids = plantarch.readPlantStructureXML("bean_day30.xml")
            >>> print(f"Loaded {len(loaded_plant_ids)} plants")
        """
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
        if not filename:
            raise ValueError("Filename cannot be empty")
 
        # Resolve path before changing directory
        absolute_path = _resolve_user_path(filename)
 
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                plantarch_wrapper.writePlantStructureXML(
                    self._plantarch_ptr, plant_id, absolute_path
                )
        except Exception as e:
            raise PlantArchitectureError(f"Failed to write plant structure XML to {filename}: {e}")
 
    def writeQSMCylinderFile(self, plant_id: int, filename: Union[str, Path]) -> None:
        """
        Export plant structure in TreeQSM cylinder format.
 
        This method writes the plant structure as a series of cylinders following the
        TreeQSM format (Raumonen et al., 2013). Each row represents one cylinder with
        columns for radius, length, start position, axis direction, branch topology,
        and other structural properties. Useful for biomechanical analysis and
        quantitative structure modeling.
 
        Args:
            plant_id: ID of the plant instance to export
            filename: Path to output file (absolute or relative, typically .txt extension)
 
        Raises:
            ValueError: If plant_id is negative or filename is empty
            PlantArchitectureError: If plant doesn't exist or file cannot be written
 
        Note:
            The TreeQSM format includes columns for:
            - Cylinder dimensions (radius, length)
            - Spatial position and orientation
            - Branch topology (parent ID, extension ID, branch ID)
            - Branch hierarchy (branch order, position in branch)
            - Quality metrics (mean absolute distance, surface coverage)
 
        Example:
            >>> # Export for biomechanical analysis
            >>> plantarch.writeQSMCylinderFile(plant_id, "tree_structure_qsm.txt")
            >>>
            >>> # Use with external QSM tools
            >>> import pandas as pd
            >>> qsm_data = pd.read_csv("tree_structure_qsm.txt", sep="\\t")
            >>> print(f"Tree has {len(qsm_data)} cylinders")
 
        References:
            Raumonen et al. (2013) "Fast Automatic Precision Tree Models from
            Terrestrial Laser Scanner Data" Remote Sensing 5(2):491-520
        """
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
        if not filename:
            raise ValueError("Filename cannot be empty")
 
        # Resolve path before changing directory
        absolute_path = _resolve_user_path(filename)
 
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                plantarch_wrapper.writeQSMCylinderFile(
                    self._plantarch_ptr, plant_id, absolute_path
                )
        except Exception as e:
            raise PlantArchitectureError(f"Failed to write QSM cylinder file to {filename}: {e}")
 
    def writePlantStructureUSD(self, plant_id: int, filename: Union[str, Path],
                               elastic_modulus: float = 5e9,
                               wood_density: float = 800.0,
                               *,
                               damping_time_constant: float = 0.02,
                               static_friction: float = 0.5,
                               dynamic_friction: float = 0.3,
                               restitution: float = 0.1,
                               organ_spring_stiffness: float = 10.0,
                               organ_spring_damping: float = 1.0,
                               leaf_mass_per_area: float = 0.05,
                               fruit_mass: float = 0.01,
                               flower_mass: float = 0.002,
                               solver_position_iterations: int = 32,
                               min_segment_length: float = 0.001,
                               armature_stability_ratio: float = 8.0,
                               physics_steps_per_second: float = 60.0,
                               damping_ratio: Optional[float] = None) -> None:
        """
        Export plant structure as a USD articulated rigid body for NVIDIA IsaacSim physics.
 
        Each tube segment becomes a capsule-shaped rigid link connected to its parent by a joint
        that locks translation, limits bending to +/-60 degrees and carries a spring on each
        rotation axis, with stiffness derived from beam bending stiffness (E*I/L). Leaves, fruits,
        and flowers are represented as mass bodies attached by spring links.
 
        Beam stiffness on a short, light segment is stiffer than a physics solver can integrate at
        a typical step rate, so each joint is given armature (an artificial inertia) that caps its
        natural frequency at armature_stability_ratio * physics_steps_per_second. Armature adds no
        weight, so deflection under gravity is unchanged. If the simulation runs at a coarser step
        than physics_steps_per_second, set that parameter to match or the plant may be unstable.
 
        Args:
            plant_id: ID of the plant instance to export
            filename: Output file path (should have .usda extension)
            elastic_modulus: Young's modulus (Pa) for joint stiffness, K = E*I/L
            wood_density: Wood density (kg/m^3) used to compute mass from capsule volume
            damping_time_constant: Damping time constant (s) of the joints between stem, petiole
                and peduncle segments; joint damping is this value times the joint stiffness.
                Must be non-negative.
            static_friction: Static friction coefficient for collision material
            dynamic_friction: Dynamic friction coefficient for collision material
            restitution: Restitution (bounciness) for collision material
            organ_spring_stiffness: Spring stiffness (N*m/rad) for organ attachment joints
            organ_spring_damping: Damping (N*m*s/rad) for organ attachment joints
            leaf_mass_per_area: Leaf mass per unit area (kg/m^2)
            fruit_mass: Mass per fruit (kg)
            flower_mass: Mass per flower (kg)
            solver_position_iterations: PhysX articulation solver position iteration count
            min_segment_length: Minimum segment length (m); shorter segments are skipped
            armature_stability_ratio: Cap on each joint's own natural frequency, as a multiple of
                the physics step rate. Lower is more stable. Must be positive.
            physics_steps_per_second: Physics step rate (Hz) the simulation is expected to run at,
                used to size the joint armature. Must be positive.
            damping_ratio: Removed; raises ValueError if given. See the note below.
 
        Raises:
            ValueError: If plant_id is negative, filename is empty, a damping or armature
                parameter is out of range, or the removed damping_ratio parameter is given
            PlantArchitectureError: If plant doesn't exist or file cannot be written
 
        Note:
            ``damping_ratio`` was removed in helios-core 1.3.90, where joint damping became
            proportional to stiffness. Use ``damping_time_constant`` (seconds) instead; the two
            are not interchangeable.
 
        Example:
            >>> plantarch.writePlantStructureUSD(plant_id, "plant.usda")
        """
        if damping_ratio is not None:
            raise ValueError(
                "writePlantStructureUSD() no longer accepts damping_ratio: joint damping is now "
                "proportional to stiffness and is set with damping_time_constant (seconds, default 0.02). "
                "The two are not interchangeable, so the old value cannot be converted."
            )
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
        if not filename:
            raise ValueError("Filename cannot be empty")
        if damping_time_constant < 0:
            raise ValueError(f"damping_time_constant must be non-negative, got {damping_time_constant}")
        if armature_stability_ratio <= 0:
            raise ValueError(f"armature_stability_ratio must be positive, got {armature_stability_ratio}")
        if physics_steps_per_second <= 0:
            raise ValueError(f"physics_steps_per_second must be positive, got {physics_steps_per_second}")
 
        absolute_path = _resolve_user_path(filename)
 
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                plantarch_wrapper.writePlantStructureUSD(
                    self._plantarch_ptr, plant_id, absolute_path,
                    elastic_modulus=elastic_modulus, wood_density=wood_density,
                    damping_time_constant=damping_time_constant,
                    armature_stability_ratio=armature_stability_ratio,
                    physics_steps_per_second=physics_steps_per_second,
                    static_friction=static_friction, dynamic_friction=dynamic_friction,
                    restitution=restitution,
                    organ_spring_stiffness=organ_spring_stiffness,
                    organ_spring_damping=organ_spring_damping,
                    leaf_mass_per_area=leaf_mass_per_area, fruit_mass=fruit_mass,
                    flower_mass=flower_mass,
                    solver_position_iterations=solver_position_iterations,
                    min_segment_length=min_segment_length
                )
        except Exception as e:
            raise PlantArchitectureError(f"Failed to write plant structure USD to {filename}: {e}")
 
    def registerGrowthFrame(self, plant_id: int, min_segment_length: float = 0.001) -> None:
        """
        Capture a snapshot of the plant's geometry as a growth animation frame.
 
        Call this after each :meth:`advanceTime` step to record the plant state for later
        animation export via :meth:`writePlantGrowthUSD`.
 
        Args:
            plant_id: ID of the plant instance to capture
            min_segment_length: Minimum segment length (m); shorter segments are skipped
 
        Raises:
            ValueError: If plant_id is negative
            PlantArchitectureError: If plant doesn't exist
        """
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
 
        self._check_context_alive()
        try:
            plantarch_wrapper.registerGrowthFrame(self._plantarch_ptr, plant_id, min_segment_length)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to register growth frame for plant {plant_id}: {e}")
 
    def writePlantGrowthUSD(self, plant_id: int, filename: Union[str, Path],
                            seconds_per_frame: float = 1.0) -> None:
        """
        Export all registered growth frames as a time-sampled USD animation file.
 
        The resulting file can be imported directly into Blender. This is a visual-only
        export — no physics prims, joints, or collision shapes are written.
 
        Args:
            plant_id: ID of the plant instance to export
            filename: Output file path (should have .usda extension)
            seconds_per_frame: Duration in seconds each growth frame occupies (default: 1.0)
 
        Raises:
            ValueError: If plant_id is negative or filename is empty
            PlantArchitectureError: If plant doesn't exist or file cannot be written
        """
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
        if not filename:
            raise ValueError("Filename cannot be empty")
 
        absolute_path = _resolve_user_path(filename)
 
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                plantarch_wrapper.writePlantGrowthUSD(
                    self._plantarch_ptr, plant_id, absolute_path, seconds_per_frame
                )
        except Exception as e:
            raise PlantArchitectureError(f"Failed to write plant growth USD to {filename}: {e}")
 
    def clearGrowthFrames(self, plant_id: int) -> None:
        """
        Clear stored growth animation frames for a plant.
 
        Args:
            plant_id: ID of the plant instance whose frames should be cleared
 
        Raises:
            ValueError: If plant_id is negative
        """
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
 
        self._check_context_alive()
        try:
            plantarch_wrapper.clearGrowthFrames(self._plantarch_ptr, plant_id)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to clear growth frames for plant {plant_id}: {e}")
 
    def getGrowthFrameCount(self, plant_id: int) -> int:
        """
        Get the number of registered growth frames for a plant.
 
        Args:
            plant_id: ID of the plant instance to query
 
        Returns:
            Number of frames registered via :meth:`registerGrowthFrame`
 
        Raises:
            ValueError: If plant_id is negative
        """
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
 
        self._check_context_alive()
        try:
            return plantarch_wrapper.getGrowthFrameCount(self._plantarch_ptr, plant_id)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to get growth frame count for plant {plant_id}: {e}")
 
    @_surfaces_phytomer_callback_errors
    def readPlantStructureXML(self, filename: Union[str, Path], quiet: bool = False) -> List[int]:
        """
        Load plant structure from XML file.
 
        This method reads plant architecture data from an XML file previously saved with
        writePlantStructureXML(). The loaded plants are added to the current context
        and can be grown, modified, or analyzed like any other plants.
 
        Args:
            filename: Path to XML file to load (absolute or relative to current working directory)
            quiet: If True, suppress console output during loading (default: False)
 
        Returns:
            List of plant IDs for the loaded plant instances
 
        Raises:
            ValueError: If filename is empty
            PlantArchitectureError: If file doesn't exist, cannot be parsed, or loading fails
 
        Note:
            The XML file can contain multiple plant instances. All plants in the file
            will be loaded and their IDs returned in a list. Plant models referenced
            in the XML must be available in the plant library.
 
        Example:
            >>> # Load previously saved plants
            >>> plant_ids = plantarch.readPlantStructureXML("saved_canopy.xml")
            >>> print(f"Loaded {len(plant_ids)} plants")
            >>>
            >>> # Continue growing the loaded plants
            >>> plantarch.advanceTime(10.0)
            >>>
            >>> # Load quietly without console messages
            >>> plant_ids = plantarch.readPlantStructureXML("bean_day45.xml", quiet=True)
        """
        if not filename:
            raise ValueError("Filename cannot be empty")
 
        # Resolve path before changing directory
        absolute_path = _resolve_user_path(filename)
 
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                return plantarch_wrapper.readPlantStructureXML(
                    self._plantarch_ptr, absolute_path, quiet
                )
        except Exception as e:
            raise PlantArchitectureError(f"Failed to read plant structure XML from {filename}: {e}")
 
    # Custom plant building methods
    def addPlantInstance(self, base_position: vec3, current_age: float) -> int:
        """
        Create an empty plant instance for custom plant building.
 
        This method creates a new plant instance at the specified location without any
        shoots or organs. Use addBaseStemShoot(), appendShoot(), and addChildShoot() to
        manually construct the plant structure. This provides low-level control over
        plant architecture, enabling custom morphologies not available in the plant library.
 
        Args:
            base_position: Cartesian (x,y,z) coordinates of plant base as vec3
            current_age: Current age of the plant in days (must be >= 0)
 
        Returns:
            Plant ID for the created plant instance
 
        Raises:
            ValueError: If age is negative
            PlantArchitectureError: If plant creation fails
 
        Example:
            >>> # Create empty plant at origin
            >>> plant_id = plantarch.addPlantInstance(vec3(0, 0, 0), 0.0)
            >>>
            >>> # Now add shoots to build custom plant structure
            >>> shoot_id = plantarch.addBaseStemShoot(
            ...     plant_id, 1, AxisRotation(0, 0, 0), 0.01, 0.1, 1.0, 1.0, 0.8, "mainstem"
            ... )
        """
        # Parameter type validation
        if not isinstance(base_position, vec3):
            raise ValueError(f"base_position must be a vec3, got {type(base_position).__name__}")
 
        # Convert position to list for C++ interface
        position_list = [base_position.x, base_position.y, base_position.z]
 
        # Validate age
        if current_age < 0:
            raise ValueError(f"Age must be non-negative, got {current_age}")
 
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                return plantarch_wrapper.addPlantInstance(
                    self._plantarch_ptr, position_list, current_age
                )
        except Exception as e:
            raise PlantArchitectureError(f"Failed to add plant instance: {e}")
 
    def deletePlantInstance(self, plant_id: int) -> None:
        """
        Delete a plant instance and all associated geometry.
 
        This method removes a plant from the simulation, deleting all shoots, organs,
        and associated primitives from the context. The plant ID becomes invalid after
        deletion and should not be used in subsequent operations.
 
        Args:
            plant_id: ID of the plant instance to delete
 
        Raises:
            ValueError: If plant_id is negative
            PlantArchitectureError: If plant deletion fails or plant doesn't exist
 
        Example:
            >>> # Delete a plant
            >>> plantarch.deletePlantInstance(plant_id)
            >>>
            >>> # Delete multiple plants
            >>> for pid in plant_ids_to_remove:
            ...     plantarch.deletePlantInstance(pid)
        """
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
 
        self._reject_inside_phytomer_callback("deletePlantInstance")
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                plantarch_wrapper.deletePlantInstance(self._plantarch_ptr, plant_id)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to delete plant instance {plant_id}: {e}")
 
    @_surfaces_phytomer_callback_errors
    def addBaseStemShoot(self,
                        plant_id: int,
                        current_node_number: int,
                        base_rotation: AxisRotation,
                        internode_radius: float,
                        internode_length_max: float,
                        internode_length_scale_factor_fraction: float,
                        leaf_scale_factor_fraction: float,
                        radius_taper: float,
                        shoot_type_label: str) -> int:
        """
        Add a base stem shoot to a plant instance (main trunk/stem).
 
        This method creates the primary shoot originating from the plant base. The base stem
        is typically the main trunk or primary stem from which all other shoots branch.
        Specify growth parameters to control the shoot's morphology and development.
 
        **IMPORTANT - Shoot Type Requirement**: Shoot types must be defined before use. The standard
        workflow is to load a plant model first using loadPlantModelFromLibrary(), which defines
        shoot types that can then be used for custom building. The shoot_type_label must match a
        shoot type defined in the loaded model.
 
        Args:
            plant_id: ID of the plant instance
            current_node_number: Starting node number for this shoot (typically 1)
            base_rotation: Orientation as AxisRotation(pitch, yaw, roll) in radians (use math.radians() to convert)
            internode_radius: Base radius of internodes in meters (must be > 0)
            internode_length_max: Maximum internode length in meters (must be > 0)
            internode_length_scale_factor_fraction: Scale factor for internode length (0-1 typically)
            leaf_scale_factor_fraction: Scale factor for leaf size (0-1 typically)
            radius_taper: Rate of radius decrease along shoot (0-1, where 1=no taper)
            shoot_type_label: Label identifying shoot type - must match a type from loaded model
 
        Returns:
            Shoot ID for the created shoot
 
        Raises:
            ValueError: If parameters are invalid (negative IDs, non-positive dimensions, empty label)
            PlantArchitectureError: If shoot creation fails or shoot type doesn't exist
 
        Example:
            >>> from pyhelios.types import vec3, AxisRotation
            >>>
            >>> # REQUIRED: Load a plant model to define shoot types
            >>> plantarch.loadPlantModelFromLibrary("bean")
            >>>
            >>> # Create empty plant for custom building
            >>> plant_id = plantarch.addPlantInstance(vec3(0, 0, 0), 0.0)
            >>>
            >>> # Add base stem using a shoot type from the loaded model. Labels are
            >>> # species-specific: bean defines "unifoliate"/"trifoliate", almond
            >>> # defines "trunk"/"scaffold"/"proleptic"/"sylleptic". There is no
            >>> # generic "stem" type.
            >>> shoot_id = plantarch.addBaseStemShoot(
            ...     plant_id=plant_id,
            ...     current_node_number=1,
            ...     base_rotation=AxisRotation(0, 0, 0),  # Upright
            ...     internode_radius=0.01,       # 1cm radius
            ...     internode_length_max=0.1,    # 10cm max length
            ...     internode_length_scale_factor_fraction=1.0,
            ...     leaf_scale_factor_fraction=1.0,
            ...     radius_taper=0.9,            # Gradual taper
            ...     shoot_type_label="trifoliate"  # Must match loaded model
            ... )
        """
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
        if current_node_number < 0:
            raise ValueError("Current node number must be non-negative")
        if internode_radius <= 0:
            raise ValueError(f"Internode radius must be positive, got {internode_radius}")
        if internode_length_max <= 0:
            raise ValueError(f"Internode length max must be positive, got {internode_length_max}")
        if not shoot_type_label or not shoot_type_label.strip():
            raise ValueError("Shoot type label cannot be empty")
 
        # Convert rotation to list for C++ interface
        rotation_list = base_rotation.to_list()
 
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                return plantarch_wrapper.addBaseStemShoot(
                    self._plantarch_ptr, plant_id, current_node_number, rotation_list,
                    internode_radius, internode_length_max,
                    internode_length_scale_factor_fraction, leaf_scale_factor_fraction,
                    radius_taper, shoot_type_label.strip()
                )
        except Exception as e:
            error_msg = str(e)
            if "does not exist" in error_msg.lower() and "shoot type" in error_msg.lower():
                raise PlantArchitectureError(
                    f"Shoot type '{shoot_type_label}' not defined. "
                    f"Load a plant model first to define shoot types:\n"
                    f"  plantarch.loadPlantModelFromLibrary('bean')  # or other model\n"
                    f"Original error: {e}"
                )
            raise PlantArchitectureError(f"Failed to add base stem shoot: {e}")
 
    @_surfaces_phytomer_callback_errors
    def appendShoot(self,
                   plant_id: int,
                   parent_shoot_id: int,
                   current_node_number: int,
                   base_rotation: AxisRotation,
                   internode_radius: float,
                   internode_length_max: float,
                   internode_length_scale_factor_fraction: float,
                   leaf_scale_factor_fraction: float,
                   radius_taper: float,
                   shoot_type_label: str) -> int:
        """
        Append a shoot to the end of an existing shoot.
 
        This method extends an existing shoot by appending a new shoot at its terminal bud.
        Useful for creating multi-segmented shoots with varying properties along their length,
        such as shoots with different growth phases or developmental stages.
 
        **IMPORTANT - Shoot Type Requirement**: The shoot_type_label must match a shoot type
        defined in a loaded plant model. Load a model with loadPlantModelFromLibrary() before
        calling this method.
 
        Args:
            plant_id: ID of the plant instance
            parent_shoot_id: ID of the parent shoot to extend
            current_node_number: Starting node number for this shoot
            base_rotation: Orientation as AxisRotation(pitch, yaw, roll) in radians (use math.radians() to convert)
            internode_radius: Base radius of internodes in meters (must be > 0)
            internode_length_max: Maximum internode length in meters (must be > 0)
            internode_length_scale_factor_fraction: Scale factor for internode length (0-1 typically)
            leaf_scale_factor_fraction: Scale factor for leaf size (0-1 typically)
            radius_taper: Rate of radius decrease along shoot (0-1, where 1=no taper)
            shoot_type_label: Label identifying shoot type - must match loaded model
 
        Returns:
            Shoot ID for the appended shoot
 
        Raises:
            ValueError: If parameters are invalid (negative IDs, non-positive dimensions, empty label)
            PlantArchitectureError: If shoot appending fails, parent doesn't exist, or shoot type not defined
 
        Example:
            >>> # Load model to define shoot types
            >>> plantarch.loadPlantModelFromLibrary("bean")
            >>>
            >>> # Append shoot with reduced size to simulate apical growth
            >>> new_shoot_id = plantarch.appendShoot(
            ...     plant_id=plant_id,
            ...     parent_shoot_id=base_shoot_id,
            ...     current_node_number=10,
            ...     base_rotation=AxisRotation(0, 0, 0),
            ...     internode_radius=0.008,      # Smaller than base
            ...     internode_length_max=0.08,   # Shorter internodes
            ...     internode_length_scale_factor_fraction=1.0,
            ...     leaf_scale_factor_fraction=0.8,  # Smaller leaves
            ...     radius_taper=0.85,
            ...     shoot_type_label="trifoliate"
            ... )
        """
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
        if parent_shoot_id < 0:
            raise ValueError("Parent shoot ID must be non-negative")
        if current_node_number < 0:
            raise ValueError("Current node number must be non-negative")
        if internode_radius <= 0:
            raise ValueError(f"Internode radius must be positive, got {internode_radius}")
        if internode_length_max <= 0:
            raise ValueError(f"Internode length max must be positive, got {internode_length_max}")
        if not shoot_type_label or not shoot_type_label.strip():
            raise ValueError("Shoot type label cannot be empty")
 
        # Convert rotation to list for C++ interface
        rotation_list = base_rotation.to_list()
 
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                return plantarch_wrapper.appendShoot(
                    self._plantarch_ptr, plant_id, parent_shoot_id, current_node_number,
                    rotation_list, internode_radius, internode_length_max,
                    internode_length_scale_factor_fraction, leaf_scale_factor_fraction,
                    radius_taper, shoot_type_label.strip()
                )
        except Exception as e:
            error_msg = str(e)
            if "does not exist" in error_msg.lower() and "shoot type" in error_msg.lower():
                raise PlantArchitectureError(
                    f"Shoot type '{shoot_type_label}' not defined. "
                    f"Load a plant model first to define shoot types:\n"
                    f"  plantarch.loadPlantModelFromLibrary('bean')  # or other model\n"
                    f"Original error: {e}"
                )
            raise PlantArchitectureError(f"Failed to append shoot: {e}")
 
    @_surfaces_phytomer_callback_errors
    def addChildShoot(self,
                     plant_id: int,
                     parent_shoot_id: int,
                     parent_node_index: int,
                     current_node_number: int,
                     shoot_base_rotation: AxisRotation,
                     internode_radius: float,
                     internode_length_max: float,
                     internode_length_scale_factor_fraction: float,
                     leaf_scale_factor_fraction: float,
                     radius_taper: float,
                     shoot_type_label: str,
                     petiole_index: int = 0) -> int:
        """
        Add a child shoot at an axillary bud position on a parent shoot.
 
        This method creates a lateral branch shoot emerging from a specific node on the
        parent shoot. Child shoots enable creation of branching architectures, with control
        over branch angle, size, and which petiole position the branch emerges from (for
        plants with multiple petioles per node).
 
        **IMPORTANT - Shoot Type Requirement**: The shoot_type_label must match a shoot type
        defined in a loaded plant model. Load a model with loadPlantModelFromLibrary() before
        calling this method.
 
        Args:
            plant_id: ID of the plant instance
            parent_shoot_id: ID of the parent shoot
            parent_node_index: Index of the parent node where child emerges (0-based)
            current_node_number: Starting node number for this child shoot
            shoot_base_rotation: Orientation as AxisRotation(pitch, yaw, roll) in radians (use math.radians() to convert)
            internode_radius: Base radius of child shoot internodes in meters (must be > 0)
            internode_length_max: Maximum internode length in meters (must be > 0)
            internode_length_scale_factor_fraction: Scale factor for internode length (0-1 typically)
            leaf_scale_factor_fraction: Scale factor for leaf size (0-1 typically)
            radius_taper: Rate of radius decrease along shoot (0-1, where 1=no taper)
            shoot_type_label: Label identifying shoot type - must match loaded model
            petiole_index: Which petiole at the node to branch from (default: 0)
 
        Returns:
            Shoot ID for the created child shoot
 
        Raises:
            ValueError: If parameters are invalid (negative values, non-positive dimensions, empty label)
            PlantArchitectureError: If child shoot creation fails, parent doesn't exist, or shoot type not defined
 
        Example:
            >>> import math
            >>> # Load model to define shoot types
            >>> plantarch.loadPlantModelFromLibrary("bean")
            >>>
            >>> # Add lateral branch at 45-degree angle from node 3
            >>> branch_id = plantarch.addChildShoot(
            ...     plant_id=plant_id,
            ...     parent_shoot_id=main_shoot_id,
            ...     parent_node_index=3,
            ...     current_node_number=1,
            ...     shoot_base_rotation=AxisRotation(math.radians(45), math.radians(90), 0),  # 45° out, 90° around
            ...     internode_radius=0.005,      # Thinner than main stem
            ...     internode_length_max=0.06,   # Shorter internodes
            ...     internode_length_scale_factor_fraction=1.0,
            ...     leaf_scale_factor_fraction=0.9,
            ...     radius_taper=0.8,
            ...     shoot_type_label="trifoliate"
            ... )
            >>>
            >>> # Add second branch from opposite petiole
            >>> branch_id2 = plantarch.addChildShoot(
            ...     plant_id, main_shoot_id, 3, 1, AxisRotation(math.radians(45), math.radians(270), 0),
            ...     0.005, 0.06, 1.0, 0.9, 0.8, "trifoliate", petiole_index=1
            ... )
        """
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
        if parent_shoot_id < 0:
            raise ValueError("Parent shoot ID must be non-negative")
        if parent_node_index < 0:
            raise ValueError("Parent node index must be non-negative")
        if current_node_number < 0:
            raise ValueError("Current node number must be non-negative")
        if internode_radius <= 0:
            raise ValueError(f"Internode radius must be positive, got {internode_radius}")
        if internode_length_max <= 0:
            raise ValueError(f"Internode length max must be positive, got {internode_length_max}")
        if not shoot_type_label or not shoot_type_label.strip():
            raise ValueError("Shoot type label cannot be empty")
        if petiole_index < 0:
            raise ValueError(f"Petiole index must be non-negative, got {petiole_index}")
 
        # Convert rotation to list for C++ interface
        rotation_list = shoot_base_rotation.to_list()
 
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                return plantarch_wrapper.addChildShoot(
                    self._plantarch_ptr, plant_id, parent_shoot_id, parent_node_index,
                    current_node_number, rotation_list, internode_radius,
                    internode_length_max, internode_length_scale_factor_fraction,
                    leaf_scale_factor_fraction, radius_taper, shoot_type_label.strip(),
                    petiole_index
                )
        except Exception as e:
            error_msg = str(e)
            if "does not exist" in error_msg.lower() and "shoot type" in error_msg.lower():
                raise PlantArchitectureError(
                    f"Shoot type '{shoot_type_label}' not defined. "
                    f"Load a plant model first to define shoot types:\n"
                    f"  plantarch.loadPlantModelFromLibrary('bean')  # or other model\n"
                    f"Original error: {e}"
                )
            raise PlantArchitectureError(f"Failed to add child shoot: {e}")
 
    # =========================================================================
    # Reconstruction from measured geometry (helios-core 1.3.85+)
    # =========================================================================
 
    @staticmethod
    def _validateNodesAndRadii(node_positions, node_radii, positions_name: str, radii_name: str):
        """Validate a measured node path and return it as plain lists for the ctypes layer."""
        if not isinstance(node_positions, (list, tuple)):
            raise ValueError(f"{positions_name} must be a list of vec3, got {type(node_positions).__name__}")
        if not isinstance(node_radii, (list, tuple)):
            raise ValueError(f"{radii_name} must be a list of floats, got {type(node_radii).__name__}")
        if len(node_positions) < 2:
            raise ValueError(f"{positions_name} must contain at least two positions, got {len(node_positions)}")
        if len(node_radii) != len(node_positions):
            raise ValueError(
                f"{radii_name} must have one entry per position: got {len(node_radii)} radii "
                f"for {len(node_positions)} positions")
        positions = []
        for i, pt in enumerate(node_positions):
            if not isinstance(pt, vec3):
                raise ValueError(f"{positions_name}[{i}] must be a vec3, got {type(pt).__name__}")
            positions.append([pt.x, pt.y, pt.z])
        radii = []
        for i, r in enumerate(node_radii):
            if isinstance(r, bool) or not isinstance(r, (int, float)):
                raise ValueError(f"{radii_name}[{i}] must be a number, got {type(r).__name__}")
            if r <= 0:
                raise ValueError(f"{radii_name}[{i}] must be positive, got {r}")
            radii.append(float(r))
        return positions, radii
 
    @_surfaces_phytomer_callback_errors
    def addShootFromNodePositions(self,
                                  plant_id: int,
                                  parent_shoot_id: int,
                                  parent_node_index: int,
                                  node_positions: List[vec3],
                                  node_radii: List[float],
                                  shoot_type_label: str,
                                  growth_shoot_type_label: Optional[str] = None,
                                  petiole_index: int = 0) -> int:
        """
        Add a shoot whose internode geometry is prescribed by measured node positions.
 
        This builds a single shoot, rendered as one continuous internode tube, that
        follows a path given by the caller rather than one generated from the shoot
        type's curvature and tortuosity parameters. It is intended for reconstructing a
        plant from measured geometry such as a QSM, a digitized skeleton or
        photogrammetry. A shoot built through :meth:`addBaseStemShoot`,
        :meth:`appendShoot` or :meth:`addChildShoot` is an extrapolation from its base
        rotation and cannot follow a measured curve; approximating one by chaining many
        short shoots produces a separate tube object per link, which leaves visible gaps
        at every bend.
 
        The supplied positions are the phytomer endpoints: N+1 positions define N
        internodes and therefore N phytomers. The shoot type's ``internode.length_segments``
        still controls how finely each internode is subdivided, with the intermediate
        nodes interpolated along the straight segment between the two prescribed
        endpoints. The caller controls internode length by choosing how many nodes to
        supply.
 
        The prescribed phytomers are created fully elongated and are therefore not
        re-scaled or re-curved by subsequent calls to :meth:`advanceTime`. New phytomers
        added at the shoot apex as the plant grows are generated normally, continuing from
        the direction of the final prescribed internode, and use the mean of the
        prescribed internode lengths as their target length. Prescribed radii act as a
        lower bound: a shoot type with a non-zero ``girth_area_factor`` may thicken an
        internode during growth but never thins one, so a girth area factor of zero
        preserves the prescribed radii exactly.
 
        When ``parent_shoot_id`` is non-negative the base of the shoot is seated on the
        parent as :meth:`addChildShoot` does (offset from the attachment node to the
        surface of the parent internode) and the whole path is translated onto that
        point. All relative geometry is preserved; only the absolute position changes,
        and an error is raised if the discrepancy is large enough that the shoot would
        not be connected to its parent.
 
        **Separate growth type.** Building measured wood calls for curvature and
        tortuosity of zero so the measured path is not fought, a node cap at least as
        large as the longest measured branch, and often a girth area factor of zero so
        the measured radii are preserved. None of those describe how the plant should
        grow: a shoot inheriting them extends perfectly straight and never reaches its
        node cap. Pass ``growth_shoot_type_label`` to take the node caps, the gravitropic
        curvature of phytomers added at the apex, and the type of the shoots this shoot's
        vegetative buds produce from a different shoot type. ``girth_area_factor`` and
        bud-break probability are deliberately still taken from the build type, and the
        build type remains the label reported by the shoot. A measured branch longer
        than the growth type's ``max_nodes`` is accepted and simply stops extending.
 
        Requires helios-core v1.3.85 or newer.
 
        Args:
            plant_id: ID of the plant instance
            parent_shoot_id: ID of the shoot to attach to, or ``-1`` to create a base stem
                shoot at the start of a new plant
            parent_node_index: Node of the parent shoot at which the new shoot is added.
                Ignored when ``parent_shoot_id`` is ``-1``
            node_positions: Internode node positions in world coordinates, ordered from the
                base of the shoot to its tip. At least two are required, and no two
                consecutive positions may be coincident
            node_radii: Radius of the shoot at each node, one per position. All must be > 0
            shoot_type_label: Shoot type whose parameters build the measured geometry.
                Must already be defined (by :meth:`loadPlantModelFromLibrary` or
                :meth:`defineShootType`)
            growth_shoot_type_label: Optional shoot type whose parameters govern the
                shoot's future growth. ``None`` grows the shoot with ``shoot_type_label``
            petiole_index: Petiole within the parent node to attach to (default 0)
 
        Returns:
            ID of the newly created shoot
 
        Raises:
            ValueError: If any ID is out of range, a position is not a vec3, a radius is
                not positive, fewer than two nodes are given, or the counts differ
            PlantArchitectureError: If the native build fails (undefined shoot type,
                coincident consecutive nodes, base too far from the parent, ...) or the
                library predates v1.3.85
 
        Note:
            Like every other manually added shoot, the new shoot is created dormant.
            Call :meth:`breakPlantDormancy` before :meth:`advanceTime` if it is to grow.
 
        Example:
            >>> plantarch.loadPlantModelFromLibrary("bean")
            >>> plant_id = plantarch.addPlantInstance(vec3(0, 0, 0), 0.0)
            >>> path = [vec3(0, 0, 0), vec3(0.01, 0, 0.1), vec3(0.03, 0.01, 0.2), vec3(0.04, 0.01, 0.3)]
            >>> radii = [0.006, 0.005, 0.004, 0.003]
            >>> stem = plantarch.addShootFromNodePositions(plant_id, -1, 0, path, radii, "unifoliate")
            >>> assert plantarch.isShootGeometryPrescribed(plant_id, stem)
        """
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
        if parent_shoot_id < -1:
            raise ValueError("Parent shoot ID must be -1 (base stem) or a non-negative shoot ID")
        if parent_node_index < 0:
            raise ValueError("Parent node index must be non-negative")
        if petiole_index < 0:
            raise ValueError(f"Petiole index must be non-negative, got {petiole_index}")
        if not isinstance(shoot_type_label, str) or not shoot_type_label.strip():
            raise ValueError("Shoot type label cannot be empty")
        if growth_shoot_type_label is not None:
            if not isinstance(growth_shoot_type_label, str) or not growth_shoot_type_label.strip():
                raise ValueError("Growth shoot type label cannot be empty when given")
            growth_shoot_type_label = growth_shoot_type_label.strip()
        positions, radii = self._validateNodesAndRadii(node_positions, node_radii, "node_positions", "node_radii")
 
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                return plantarch_wrapper.addShootFromNodePositions(
                    self._plantarch_ptr, plant_id, parent_shoot_id, parent_node_index,
                    positions, radii, shoot_type_label.strip(), growth_shoot_type_label, petiole_index)
        except Exception as e:
            error_msg = str(e)
            if "does not exist" in error_msg.lower() and "shoot type" in error_msg.lower():
                raise PlantArchitectureError(
                    f"Shoot type not defined ('{shoot_type_label}'"
                    f"{', ' + repr(growth_shoot_type_label) if growth_shoot_type_label else ''}). "
                    f"Load a plant model or define the shoot type first:\n"
                    f"  plantarch.loadPlantModelFromLibrary('bean')  # or defineShootType(...)\n"
                    f"Original error: {e}")
            raise PlantArchitectureError(f"Failed to add shoot from node positions: {e}")
 
    def setPetioleNodePositions(self,
                                plant_id: int,
                                shoot_id: int,
                                node_index: int,
                                petiole_index: int,
                                node_positions: List[vec3],
                                node_radii: List[float]) -> None:
        """
        Prescribe the path of a petiole on an existing phytomer from measured node positions.
 
        This is the organ-level counterpart of :meth:`addShootFromNodePositions`. Where
        that method prescribes the internode skeleton of a shoot, this one prescribes the
        centerline of a single petiole hanging off it, so that a reconstruction from
        labelled measurements (a segmented point cloud, a digitized plant) can follow the
        measured petiole rather than the path the shoot type's petiole pitch and
        curvature would generate.
 
        The supplied positions are the nodes of the petiole tube, ordered from the base
        outward. Their number is free and need not match the shoot type's
        ``petiole.length_segments``; the petiole tube is rebuilt to match. The first
        position is snapped onto the tip of the internode the petiole grows from and the
        rest of the path is translated by the same amount, so all relative geometry is
        preserved exactly. An error is raised if that discrepancy is large enough that
        the petiole would not be attached to the stem.
 
        The prescribed petiole is not re-scaled by subsequent calls to
        :meth:`advanceTime`, and its radii are held as given.
 
        Requires helios-core v1.3.85 or newer.
 
        Args:
            plant_id: ID of the plant instance
            shoot_id: ID of the shoot carrying the phytomer
            node_index: Index of the phytomer within the shoot, counted from the base
            petiole_index: Index of the petiole within the phytomer
            node_positions: Petiole node positions in world coordinates, base to tip. At
                least two are required, and no two consecutive positions may be coincident
            node_radii: Radius of the petiole at each node, one per position. All must be > 0
 
        Raises:
            ValueError: If any index is negative, a position is not a vec3, a radius is
                not positive, fewer than two nodes are given, or the counts differ
            PlantArchitectureError: If the native call fails or the library predates v1.3.85
 
        Note:
            Call this **before** :meth:`setPetioleLeafGeometry` for the same petiole, since
            leaf placement is oriented from the petiole axis.
        """
        for name, v in (("Plant ID", plant_id), ("Shoot ID", shoot_id),
                        ("Node index", node_index), ("Petiole index", petiole_index)):
            if v < 0:
                raise ValueError(f"{name} must be non-negative")
        positions, radii = self._validateNodesAndRadii(node_positions, node_radii, "node_positions", "node_radii")
 
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                plantarch_wrapper.setPetioleNodePositions(
                    self._plantarch_ptr, plant_id, shoot_id, node_index, petiole_index, positions, radii)
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to set petiole node positions (plant {plant_id}, shoot {shoot_id}, "
                f"node {node_index}, petiole {petiole_index}): {e}")
 
    def setPetioleLeafGeometry(self,
                               plant_id: int,
                               shoot_id: int,
                               node_index: int,
                               petiole_index: int,
                               leaf_bases: List[vec3],
                               leaf_rotations: List[AxisRotation],
                               leaf_sizes: List[float]) -> None:
        """
        Prescribe the base position, orientation and size of every leaf on a petiole.
 
        This is the leaf-level counterpart of :meth:`setPetioleNodePositions`, intended
        for the same reconstruction workflow. Every leaf on the petiole is prescribed in
        one call: for a compound leaf the leaflets are not independent, since a
        leaflet's roll and yaw signs and the prototype it is a copy of all follow from
        its position along the petiole. A species with one leaf per petiole passes
        one-element lists.
 
        Each leaf is rebuilt from its prototype and re-oriented through the same
        rotation chain used when a leaf is grown. The prescribed base, orientation and
        size are held exactly and are not changed by :meth:`advanceTime`; prescribed
        leaves are additionally exempt from the self-weight droop.
 
        **Rotation units and frame.** ``leaf_rotations`` are given in **radians**, as
        pitch, yaw and roll relative to the petiole and internode axes, not to world
        axes (the same convention as the native ``Phytomer::leaf_rotation``). The full
        chain that places a leaf includes the petiole's own azimuth and a
        size-dependent correction and is not invertible, so there is no exact
        conversion from a world-frame blade orientation; a caller fitting to measured
        data should iterate by forward evaluation, reading the resulting geometry back
        from the Context.
 
        Requires helios-core v1.3.85 or newer.
 
        Args:
            plant_id: ID of the plant instance
            shoot_id: ID of the shoot carrying the phytomer
            node_index: Index of the phytomer within the shoot, counted from the base
            petiole_index: Index of the petiole within the phytomer
            leaf_bases: Base position of each leaf in world coordinates, one per leaf on
                the petiole, in the petiole's existing leaf order
            leaf_rotations: ``AxisRotation(pitch, yaw, roll)`` of each leaf in **radians**
            leaf_sizes: Fully elongated size of each leaf in meters. All must be > 0
 
        Raises:
            ValueError: If any index is negative, a base is not a vec3, a rotation is not
                an AxisRotation, a size is not positive, or the three lists differ in length
            PlantArchitectureError: If the number of leaves does not match the petiole
                (the count is fixed when the phytomer is created), the native call
                fails, or the library predates v1.3.85
 
        Note:
            Rebuilding each leaf discards primitive data a caller has attached to it.
            The object label and material are restored; other primitive data is not.
        """
        for name, v in (("Plant ID", plant_id), ("Shoot ID", shoot_id),
                        ("Node index", node_index), ("Petiole index", petiole_index)):
            if v < 0:
                raise ValueError(f"{name} must be non-negative")
        for name, seq in (("leaf_bases", leaf_bases), ("leaf_rotations", leaf_rotations), ("leaf_sizes", leaf_sizes)):
            if not isinstance(seq, (list, tuple)):
                raise ValueError(f"{name} must be a list, got {type(seq).__name__}")
        n = len(leaf_bases)
        if n < 1:
            raise ValueError("leaf_bases must contain at least one leaf")
        if len(leaf_rotations) != n or len(leaf_sizes) != n:
            raise ValueError(
                f"leaf_bases, leaf_rotations and leaf_sizes must have the same length: "
                f"got {n}, {len(leaf_rotations)} and {len(leaf_sizes)}")
        bases = []
        for i, b in enumerate(leaf_bases):
            if not isinstance(b, vec3):
                raise ValueError(f"leaf_bases[{i}] must be a vec3, got {type(b).__name__}")
            bases.append([b.x, b.y, b.z])
        rotations = []
        for i, r in enumerate(leaf_rotations):
            if not isinstance(r, AxisRotation):
                raise ValueError(f"leaf_rotations[{i}] must be an AxisRotation, got {type(r).__name__}")
            rotations.append([r.pitch, r.yaw, r.roll])
        sizes = []
        for i, sz in enumerate(leaf_sizes):
            if isinstance(sz, bool) or not isinstance(sz, (int, float)):
                raise ValueError(f"leaf_sizes[{i}] must be a number, got {type(sz).__name__}")
            if sz <= 0:
                raise ValueError(f"leaf_sizes[{i}] must be positive, got {sz}")
            sizes.append(float(sz))
 
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                plantarch_wrapper.setPetioleLeafGeometry(
                    self._plantarch_ptr, plant_id, shoot_id, node_index, petiole_index,
                    bases, rotations, sizes)
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to set petiole leaf geometry (plant {plant_id}, shoot {shoot_id}, "
                f"node {node_index}, petiole {petiole_index}): {e}")
 
    def setPetioleLeafCount(self, plant_id: int, shoot_id: int, node_index: int,
                            petiole_index: int, leaf_count: int) -> None:
        """
        Change the number of leaves (leaflets) on one petiole of an existing phytomer.
 
        The leaves are rebuilt procedurally. By default the count is set by the shoot type's
        ``leaf.leaves_per_petiole``; use this to match a measured compound leaf with a
        different number of leaflets before calling :meth:`setPetioleLeafGeometry`.
 
        Args:
            plant_id: Plant identifier.
            shoot_id: Shoot identifier.
            node_index: Index of the phytomer along the shoot.
            petiole_index: Index of the petiole on that phytomer.
            leaf_count: Number of leaves to place on the petiole. Must be at least 1.
 
        Raises:
            ValueError: If any index is negative or ``leaf_count`` is less than 1.
            PlantArchitectureError: If the operation fails.
 
        Note:
            Call this **before** :meth:`setPetioleLeafGeometry` for the same petiole, whose
            ``leaf_count`` must match the number of leaves on the petiole.
        """
        for name, v in (("Plant ID", plant_id), ("Shoot ID", shoot_id),
                        ("Node index", node_index), ("Petiole index", petiole_index)):
            if v < 0:
                raise ValueError(f"{name} must be non-negative")
        if leaf_count < 1:
            raise ValueError(f"Leaf count must be at least 1, got {leaf_count}")
 
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                plantarch_wrapper.setPetioleLeafCount(
                    self._plantarch_ptr, plant_id, shoot_id, node_index, petiole_index, leaf_count)
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to set petiole leaf count (plant {plant_id}, shoot {shoot_id}, "
                f"node {node_index}, petiole {petiole_index}): {e}")
 
    def setShootInternodeLengthMax(self, plant_id: int, shoot_id: int,
                                   internode_length_max: float) -> None:
        """
        Set the target length of internodes grown at the apex of an existing shoot.
 
        A shoot built by :meth:`addShootFromNodePositions` otherwise grows toward the mean
        of its prescribed internode lengths; use this to give newly grown internodes a
        different target length.
 
        Args:
            plant_id: Plant identifier.
            shoot_id: Shoot identifier.
            internode_length_max: Target internode length in meters. Must be positive.
 
        Raises:
            ValueError: If an identifier is negative or the length is not positive.
            PlantArchitectureError: If the operation fails.
 
        Note:
            This value is **not** saved by :meth:`writePlantStructureXML`, so it must be
            set again after :meth:`readPlantStructureXML`.
        """
        if plant_id < 0 or shoot_id < 0:
            raise ValueError("Plant ID and shoot ID must be non-negative")
        if internode_length_max <= 0:
            raise ValueError(f"Internode length must be positive, got {internode_length_max}")
 
        self._check_context_alive()
        try:
            with _plantarchitecture_working_directory():
                plantarch_wrapper.setShootInternodeLengthMax(
                    self._plantarch_ptr, plant_id, shoot_id, internode_length_max)
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to set shoot internode length max (plant {plant_id}, "
                f"shoot {shoot_id}): {e}")
 
    # Bud and apex control
    def terminateApicalBud(self, plant_id: int, shoot_id: int) -> None:
        """
        Stop a shoot's apex from adding any further phytomers.
 
        The shoot keeps everything it already has, and its vegetative buds keep whatever
        state they are in -- this kills only the apical meristem. The shoot therefore stops
        extending at its tip but can still throw laterals; to stop those as well, pair this
        with :meth:`removeShootVegetativeBuds`.
 
        This is the standard way to freeze the old wood of a reconstructed tree before
        growing it forward with :meth:`advanceTime`.
 
        Args:
            plant_id: ID of the plant instance
            shoot_id: Shoot index within the plant (see :meth:`getAllShootIDs`)
 
        Raises:
            ValueError: If either identifier is not a non-negative int
            PlantArchitectureError: If the plant or shoot does not exist
 
        Example:
            >>> # Freeze the measured scaffold so only last year's growth extends
            >>> for shoot_id in plantarch.getTerminalShootIDs(plant_id):
            ...     plantarch.terminateApicalBud(plant_id, shoot_id)
        """
        self._validateShootIdentifiers(plant_id, shoot_id)
 
        self._check_context_alive()
        try:
            plantarch_wrapper.terminateShootApicalBud(self._plantarch_ptr, plant_id, shoot_id)
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to terminate the apical bud of shoot {shoot_id} "
                f"of plant {plant_id}: {e}")
 
    def getShootVegetativeBudCount(self, plant_id: int, shoot_id: int,
                                   state: Optional[BudState] = None) -> int:
        """
        Count a shoot's axillary vegetative buds, summed over all phytomers and petioles.
 
        Buds are never removed from a shoot -- only their state changes -- so the
        unfiltered count is stable over the shoot's life and makes a useful denominator.
 
        Args:
            plant_id: ID of the plant instance
            shoot_id: Shoot index within the plant (see :meth:`getAllShootIDs`)
            state: Count only buds in this :class:`~pyhelios.BudState`. ``None``
                (the default) counts buds in every state.
 
        Returns:
            The number of matching vegetative buds.
 
        Raises:
            ValueError: If an identifier is negative, or ``state`` is not a BudState
            PlantArchitectureError: If the plant or shoot does not exist
 
        Note:
            ``BudState.DEAD`` means "will produce nothing further", which covers both buds
            that were killed and buds that have **already broken into a child shoot**. A
            dead-bud count is therefore not a count of killed buds. To test whether a shoot
            can still grow, count the live states instead -- for example the unfiltered
            total minus the dead count.
 
        Example:
            >>> from pyhelios import BudState
            >>> total = plantarch.getShootVegetativeBudCount(plant_id, 0)
            >>> dead = plantarch.getShootVegetativeBudCount(plant_id, 0, BudState.DEAD)
            >>> print(f"{total - dead} buds can still break")
        """
        self._validateShootIdentifiers(plant_id, shoot_id)
        bud_state = -1 if state is None else int(self._validateBudState(state))
 
        self._check_context_alive()
        try:
            return plantarch_wrapper.getShootVegetativeBudCount(
                self._plantarch_ptr, plant_id, shoot_id, bud_state)
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to count the vegetative buds of shoot {shoot_id} "
                f"of plant {plant_id}: {e}")
 
    def getPlantLeafCount(self, plant_id: int) -> int:
        """
        Get the number of leaf objects on a plant.
 
        Counts compound leaf objects, not primitives -- a leaf built from many triangles
        counts once, and a compound leaf contributes one per leaflet. Equivalent to
        ``len(getPlantLeafObjectIDs(plant_id))`` without materializing the ID list.
 
        Args:
            plant_id: ID of the plant instance
 
        Returns:
            The number of leaf objects.
 
        Raises:
            ValueError: If plant_id is not a non-negative int
            PlantArchitectureError: If the plant does not exist
 
        Example:
            >>> print(f"{plantarch.getPlantLeafCount(plant_id)} leaves")
        """
        if isinstance(plant_id, bool) or not isinstance(plant_id, int):
            raise ValueError(f"Plant ID must be a non-negative int, got {type(plant_id).__name__}")
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
 
        self._check_context_alive()
        try:
            return plantarch_wrapper.getPlantLeafCount(self._plantarch_ptr, plant_id)
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to get the leaf count of plant {plant_id}: {e}")
 
    @staticmethod
    def _validateShootIdentifiers(plant_id: int, shoot_id: int) -> None:
        """Reject non-int and negative plant/shoot identifiers.
 
        bool is excluded explicitly: it is an int subclass, so True would otherwise pass
        as shoot 1.
        """
        for name, value in (("Plant ID", plant_id), ("Shoot ID", shoot_id)):
            if isinstance(value, bool) or not isinstance(value, int):
                raise ValueError(
                    f"{name} must be a non-negative int, got {type(value).__name__}")
        if plant_id < 0 or shoot_id < 0:
            raise ValueError("Plant ID and shoot ID must be non-negative")
 
    @staticmethod
    def _validateBudState(state) -> BudState:
        """Coerce a BudState (or its int value) and reject anything else.
 
        A bare int is accepted because BudState is an IntEnum, but it still has to name a
        real state -- an out-of-range value would be cast onto the C++ enum, which is
        undefined behavior.
        """
        if isinstance(state, bool) or not isinstance(state, int):
            raise ValueError(f"State must be a BudState, got {type(state).__name__}")
        try:
            return BudState(int(state))
        except ValueError:
            raise ValueError(
                f"State must be a BudState value in 0..5, got {int(state)}")
 
    def enableLeafAngleDistributionTracking(self, plant_ids, beta_mu_inclination: float,
                                            beta_nu_inclination: float, eccentricity: float,
                                            ellipse_rotation_degrees: float,
                                            lambda_degrees: float) -> None:
        """
        Steer leaf inclination and azimuth toward a prescribed distribution as the plant grows.
 
        Each leaf is given a target angle as it emerges and turns onto it while it expands,
        so a fully grown leaf never moves again: the plant matches the distribution at every
        stage without leaves shifting from one timestep to the next. Targets are not drawn
        independently per leaf, so the arrangement the model generated is preserved: each emerging leaf takes the bin that best trades
        closeness to the angle the model gave it against how far that bin is below its share
        of the plant's leaf area.
 
        Pass a list of plant IDs to realize the distribution over a canopy as a whole, in
        which case an individual plant need not follow the distribution on its own.
 
        Enabling tracking on an already-tracked plant replaces its target, so the target may
        be varied over the plant's life.
 
        Args:
            plant_ids: A single plant ID, or a sequence of plant IDs to steer together
            beta_mu_inclination: Mean parameter of the Beta inclination distribution
            beta_nu_inclination: Shape parameter of the Beta inclination distribution
            eccentricity: Eccentricity of the ellipse defining the azimuth distribution
            ellipse_rotation_degrees: Rotation of that ellipse (degrees)
            lambda_degrees: How strongly to favour filling the distribution over keeping each
                leaf near the angle the model gave it. Zero leaves the plant unchanged; values
                of order 180 match the distribution as closely as the growing plant allows.
 
        Raises:
            ValueError: If any plant ID is not a non-negative int, or the list is empty
            PlantArchitectureError: If a plant does not exist
            RuntimeError: If the native library predates helios-core v1.3.87
 
        Example:
            >>> plantarch.enableLeafAngleDistributionTracking(
            ...     plant_id, 2.0, 1.5, 0.5, 0.0, 180.0)
            >>> plantarch.advanceTime(plant_id, 20)
        """
        multi = not isinstance(plant_ids, int) or isinstance(plant_ids, bool)
        ids = self._validatePlantIdList(plant_ids) if multi else [
            self._validatePlantIdentifier(plant_ids)]
 
        self._check_context_alive()
        try:
            if multi:
                plantarch_wrapper.enablePlantLeafAngleDistributionTrackingMulti(
                    self._plantarch_ptr, ids, beta_mu_inclination, beta_nu_inclination,
                    eccentricity, ellipse_rotation_degrees, lambda_degrees)
            else:
                plantarch_wrapper.enablePlantLeafAngleDistributionTracking(
                    self._plantarch_ptr, ids[0], beta_mu_inclination, beta_nu_inclination,
                    eccentricity, ellipse_rotation_degrees, lambda_degrees)
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to enable leaf angle distribution tracking for {ids}: {e}")
 
    def enableLeafElevationAngleDistributionTracking(self, plant_id: int,
                                                     beta_mu_inclination: float,
                                                     beta_nu_inclination: float,
                                                     lambda_degrees: float) -> None:
        """
        Steer leaf inclination toward a Beta distribution as the plant grows, leaving azimuth
        to the procedural model.
 
        The inclination-only counterpart of :meth:`enableLeafAngleDistributionTracking`.
 
        Args:
            plant_id: ID of the plant instance
            beta_mu_inclination: Mean parameter of the Beta inclination distribution
            beta_nu_inclination: Shape parameter of the Beta inclination distribution
            lambda_degrees: How strongly to favour filling the distribution over keeping each
                leaf near the angle the model gave it
 
        Raises:
            ValueError: If ``plant_id`` is not a non-negative int
            PlantArchitectureError: If the plant does not exist
            RuntimeError: If the native library predates helios-core v1.3.87
        """
        plant_id = self._validatePlantIdentifier(plant_id)
 
        self._check_context_alive()
        try:
            plantarch_wrapper.enablePlantLeafElevationAngleDistributionTracking(
                self._plantarch_ptr, plant_id, beta_mu_inclination, beta_nu_inclination,
                lambda_degrees)
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to enable leaf elevation angle distribution tracking for "
                f"plant {plant_id}: {e}")
 
    def enableLeafAzimuthAngleDistributionTracking(self, plant_id: int, eccentricity: float,
                                                   ellipse_rotation_degrees: float,
                                                   lambda_degrees: float) -> None:
        """
        Steer leaf azimuth toward an ellipsoidal distribution as the plant grows, leaving
        inclination to the procedural model.
 
        The azimuth-only counterpart of :meth:`enableLeafAngleDistributionTracking`.
 
        Args:
            plant_id: ID of the plant instance
            eccentricity: Eccentricity of the ellipse defining the azimuth distribution
            ellipse_rotation_degrees: Rotation of that ellipse (degrees)
            lambda_degrees: How strongly to favour filling the distribution over keeping each
                leaf near the angle the model gave it
 
        Raises:
            ValueError: If ``plant_id`` is not a non-negative int
            PlantArchitectureError: If the plant does not exist
            RuntimeError: If the native library predates helios-core v1.3.87
        """
        plant_id = self._validatePlantIdentifier(plant_id)
 
        self._check_context_alive()
        try:
            plantarch_wrapper.enablePlantLeafAzimuthAngleDistributionTracking(
                self._plantarch_ptr, plant_id, eccentricity, ellipse_rotation_degrees,
                lambda_degrees)
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to enable leaf azimuth angle distribution tracking for "
                f"plant {plant_id}: {e}")
 
    def disableLeafAngleDistributionTracking(self, plant_id: int) -> None:
        """
        Stop steering a plant's leaf angles toward a prescribed distribution.
 
        Leaves already steered keep the orientation they have reached; leaves emerging
        afterward are left where the procedural model puts them.
 
        Args:
            plant_id: ID of the plant instance
 
        Raises:
            ValueError: If ``plant_id`` is not a non-negative int
            PlantArchitectureError: If the plant does not exist
            RuntimeError: If the native library predates helios-core v1.3.87
        """
        plant_id = self._validatePlantIdentifier(plant_id)
 
        self._check_context_alive()
        try:
            plantarch_wrapper.disablePlantLeafAngleDistributionTracking(
                self._plantarch_ptr, plant_id)
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to disable leaf angle distribution tracking for "
                f"plant {plant_id}: {e}")
 
    def isLeafAngleDistributionTrackingEnabled(self, plant_id: int) -> bool:
        """
        Whether a plant's leaf angles are being steered toward a prescribed distribution.
 
        Args:
            plant_id: ID of the plant instance
 
        Returns:
            True if tracking is in effect for this plant
 
        Raises:
            ValueError: If ``plant_id`` is not a non-negative int
            PlantArchitectureError: If the plant does not exist
            RuntimeError: If the native library predates helios-core v1.3.87
        """
        plant_id = self._validatePlantIdentifier(plant_id)
 
        self._check_context_alive()
        try:
            return plantarch_wrapper.isPlantLeafAngleDistributionTrackingEnabled(
                self._plantarch_ptr, plant_id)
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to query leaf angle distribution tracking for "
                f"plant {plant_id}: {e}")
 
    def getPetioleLength(self, plant_id: int, shoot_id: int, node_index: int,
                         petiole_index: Optional[int] = None) -> float:
        """
        Current length of a phytomer's petioles, measured along the centerline.
 
        This is the length right now, not the mature length the petiole is growing toward,
        so it rises as the petiole elongates. Contrast the leaf readers, which report the
        size a leaf is expanding toward. The length is an arclength rather than a
        base-to-tip distance, so a petiole drooping under its leaves reports the same
        length as a rigid one of the same age.
 
        With ``petiole_index`` omitted, returns the mean over every petiole on the
        phytomer. Petioles at one node are parallel structures rather than segments in
        series, so their lengths are not additive and the mean is the meaningful summary.
        A phytomer with no petiole -- a leafless woody type, or one whose leaf has been
        shed -- reports 0.0.
 
        Args:
            plant_id: ID of the plant instance
            shoot_id: Shoot index within the plant
            node_index: Phytomer index within the shoot
            petiole_index: Petiole within the phytomer; ``None`` for the phytomer mean
 
        Returns:
            Current petiole arclength in meters
 
        Raises:
            ValueError: If any identifier is not a non-negative int
            PlantArchitectureError: If the plant, shoot, node or petiole does not exist
            RuntimeError: If the native library predates helios-core v1.3.87
        """
        self._validateShootIdentifiers(plant_id, shoot_id)
        node_index = self._validateNodeIndex(node_index)
        if petiole_index is not None:
            petiole_index = self._validatePetioleIndex(petiole_index)
 
        self._check_context_alive()
        try:
            return plantarch_wrapper.getPetioleLength(
                self._plantarch_ptr, plant_id, shoot_id, node_index, petiole_index)
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to get the petiole length of node {node_index} of shoot "
                f"{shoot_id} of plant {plant_id}: {e}")
 
    def scalePetioleMaxLength(self, plant_id: int, shoot_id: int, node_index: int,
                              scale_factor: float) -> None:
        """
        Scale the fully-elongated length every petiole on a phytomer is growing toward.
 
        The petiole counterpart of internode max-length scaling. The petiole's present
        length is left where it is and only its target changes, so a phytomer creation
        function can give a leaf born on a young plant a shorter final petiole without
        moving the petiole that is already there.
 
        Args:
            plant_id: ID of the plant instance
            shoot_id: Shoot index within the plant
            node_index: Phytomer index within the shoot
            scale_factor: Factor to scale the fully-elongated length by; must be positive
 
        Raises:
            ValueError: If an identifier is invalid or ``scale_factor`` is not positive
            PlantArchitectureError: If the plant, shoot or node does not exist
            RuntimeError: If the native library predates helios-core v1.3.87
        """
        self._validateShootIdentifiers(plant_id, shoot_id)
        node_index = self._validateNodeIndex(node_index)
        scale_factor = self._validateScaleFactor(scale_factor)
 
        self._check_context_alive()
        try:
            plantarch_wrapper.scalePetioleMaxLength(
                self._plantarch_ptr, plant_id, shoot_id, node_index, scale_factor)
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to scale the petiole max length of node {node_index} of shoot "
                f"{shoot_id} of plant {plant_id}: {e}")
 
    def setPetioleScaleFraction(self, plant_id: int, shoot_id: int, node_index: int,
                                petiole_index: int,
                                petiole_scale_factor_fraction: float) -> None:
        """
        Set one petiole's current length as a fraction of its fully-elongated length,
        leaving the leaves it carries at the size they are.
 
        A petiole is a stem segment rather than part of the blade and goes on extending
        after the blade has finished expanding, which is why its growth is driven by the
        shoot's internode rate rather than the leaf expansion rate. The leaves ride out
        along the petiole as it lengthens without changing size.
 
        Args:
            plant_id: ID of the plant instance
            shoot_id: Shoot index within the plant
            node_index: Phytomer index within the shoot
            petiole_index: Petiole within the phytomer
            petiole_scale_factor_fraction: Fraction of the fully-elongated length
                (1.0 for a fully-elongated petiole)
 
        Raises:
            ValueError: If any identifier is not a non-negative int
            PlantArchitectureError: If the plant, shoot, node or petiole does not exist
            RuntimeError: If the native library predates helios-core v1.3.87
        """
        self._validateShootIdentifiers(plant_id, shoot_id)
        node_index = self._validateNodeIndex(node_index)
        petiole_index = self._validatePetioleIndex(petiole_index)
 
        self._check_context_alive()
        try:
            plantarch_wrapper.setPetioleScaleFraction(
                self._plantarch_ptr, plant_id, shoot_id, node_index, petiole_index,
                petiole_scale_factor_fraction)
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to set the petiole scale fraction of node {node_index} of shoot "
                f"{shoot_id} of plant {plant_id}: {e}")
 
    def setPetioleAndLeafScaleFraction(self, plant_id: int, shoot_id: int, node_index: int,
                                       petiole_index: int,
                                       petiole_scale_factor_fraction: float,
                                       leaf_scale_factor_fraction: float) -> None:
        """
        Set a petiole's length and its leaves' size together, each as a fraction of its own
        fully-elongated value.
 
        The two fractions are applied in one pass, so the leaves are scaled, re-seated
        along the rescaled petiole and bent under their new weight once rather than twice.
        Use this rather than the two single-fraction calls when advancing both.
 
        Args:
            plant_id: ID of the plant instance
            shoot_id: Shoot index within the plant
            node_index: Phytomer index within the shoot
            petiole_index: Petiole within the phytomer
            petiole_scale_factor_fraction: Fraction of the fully-elongated petiole length
            leaf_scale_factor_fraction: Fraction of the fully-elongated leaf scale factor
 
        Raises:
            ValueError: If any identifier is not a non-negative int
            PlantArchitectureError: If the plant, shoot, node or petiole does not exist
            RuntimeError: If the native library predates helios-core v1.3.87
        """
        self._validateShootIdentifiers(plant_id, shoot_id)
        node_index = self._validateNodeIndex(node_index)
        petiole_index = self._validatePetioleIndex(petiole_index)
 
        self._check_context_alive()
        try:
            plantarch_wrapper.setPetioleAndLeafScaleFraction(
                self._plantarch_ptr, plant_id, shoot_id, node_index, petiole_index,
                petiole_scale_factor_fraction, leaf_scale_factor_fraction)
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to set the petiole and leaf scale fractions of node {node_index} "
                f"of shoot {shoot_id} of plant {plant_id}: {e}")
 
    def scaleLeafSizeMax(self, plant_id: int, shoot_id: int, node_index: int,
                         scale_factor: float) -> None:
        """
        Scale the size every leaf on a phytomer is expanding toward, leaving the blades
        where they are.
 
        The blade's present size is untouched and only its target changes, so the expansion
        fraction moves the other way: a fully-expanded leaf given a larger target becomes a
        partly-expanded leaf of the same size and goes on growing on the next
        :meth:`advanceTime`. This is what hands a leaf built from measured geometry back to
        the growth model still the size it was measured.
 
        A factor small enough to put the target below the leaf's present size is the one
        case in which the blade does move: the leaf is taken down to the new target, and the
        leaflets of a compound leaf are then re-seated along the petiole, discarding a
        placement prescribed by :meth:`setPetioleLeafGeometry`.
 
        Args:
            plant_id: ID of the plant instance
            shoot_id: Shoot index within the plant
            node_index: Phytomer index within the shoot
            scale_factor: Factor to scale the mature leaf size by; must be positive
 
        Raises:
            ValueError: If an identifier is invalid or ``scale_factor`` is not positive
            PlantArchitectureError: If the plant, shoot or node does not exist
            RuntimeError: If the native library predates helios-core v1.3.87
        """
        self._validateShootIdentifiers(plant_id, shoot_id)
        node_index = self._validateNodeIndex(node_index)
        scale_factor = self._validateScaleFactor(scale_factor)
 
        self._check_context_alive()
        try:
            plantarch_wrapper.scaleLeafSizeMax(
                self._plantarch_ptr, plant_id, shoot_id, node_index, scale_factor)
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to scale the max leaf size of node {node_index} of shoot "
                f"{shoot_id} of plant {plant_id}: {e}")
 
    def setLeafNormal(self, plant_id: int, shoot_id: int, node_index: int,
                      petiole_index: int, leaf_index: int, target_normal: vec3) -> None:
        """
        Re-aim one leaf so its blade faces a given direction.
 
        The roll and pitch that carry the blade onto ``target_normal`` are applied as a
        single rotation about the leaf's own base, so the leaf stays attached to its petiole
        and keeps the azimuth of the petiole it hangs from. The angles are recorded on the
        phytomer, which is what makes the new orientation survive a
        :meth:`writePlantStructureXML` / :meth:`readPlantStructureXML` round trip --
        rotating the leaf object directly through the Context changes the geometry without
        changing the record and is silently lost on reload.
 
        Args:
            plant_id: ID of the plant instance
            shoot_id: Shoot index within the plant
            node_index: Phytomer index within the shoot
            petiole_index: Petiole within the phytomer
            leaf_index: Leaf within the petiole
            target_normal: Direction the blade should face, in world coordinates. Need not
                be normalized.
 
        Raises:
            ValueError: If an identifier is invalid, or ``target_normal`` is not a vec3
            PlantArchitectureError: If the leaf has no geometry, the blade's facet normals
                cancel, or the target cannot be reached by a roll-pitch pair
            RuntimeError: If the native library predates helios-core v1.3.87
 
        Example:
            >>> from pyhelios.types import vec3
            >>> plantarch.setLeafNormal(plant_id, 0, 3, 0, 0, vec3(0, 0, 1))
        """
        self._validateShootIdentifiers(plant_id, shoot_id)
        node_index = self._validateNodeIndex(node_index)
        petiole_index = self._validatePetioleIndex(petiole_index)
        leaf_index = self._validatePetioleIndex(leaf_index, name="Leaf index")
        if not isinstance(target_normal, vec3):
            raise ValueError(
                f"Target normal must be a vec3, got {type(target_normal).__name__}")
 
        self._check_context_alive()
        try:
            plantarch_wrapper.setLeafNormal(
                self._plantarch_ptr, plant_id, shoot_id, node_index, petiole_index,
                leaf_index, target_normal.x, target_normal.y, target_normal.z)
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to set the normal of leaf {leaf_index} on petiole "
                f"{petiole_index} of node {node_index} of shoot {shoot_id} "
                f"of plant {plant_id}: {e}")
 
    def bendPetioleUnderLeafWeight(self, plant_id: int, shoot_id: int, node_index: int,
                                   petiole_index: int, include_posed_leaves: bool = False) -> None:
        """
        Bend one petiole, and the leaves it carries, under the weight of its leaflets.
 
        The petiole is bent as a tapered cantilever clamped at its insertion, for the leaf's
        current size and the petiole's age. The bent shape is always computed from the
        recorded undeformed rest shape rather than the current shape, so repeated calls do
        not accumulate and creep the petiole downward. The insertion stays clamped, so the
        petiole keeps leaving the stem at its generated pitch and the droop appears beyond it
        as curvature along the length.
 
        This is normally driven by the growth model from
        ``PhytomerParameters.petiole.flexibility``; call it directly only to re-bend a petiole
        after changing its geometry or its flexibility (:meth:`setPetioleFlexibility`) yourself.
        It does nothing for a rigid petiole (flexibility left at zero), a petiole whose
        centerline was prescribed, one carrying a prescribed leaf, or when neither the load nor
        the compliance has changed since the last call.
 
        A leaf counts as prescribed once it has been posed by :meth:`setLeafNormal`,
        :meth:`setLeafAngleDistribution` or :meth:`setPetioleLeafGeometry`, so after any of
        those its petiole no longer bends. Pass ``include_posed_leaves=True`` to bend it anyway:
        the posed leaves are then carried along the petiole and turned with it, which moves them
        away from the orientation they were given.
 
        Args:
            plant_id: ID of the plant instance
            shoot_id: Shoot index within the plant
            node_index: Phytomer index within the shoot
            petiole_index: Petiole within the phytomer
            include_posed_leaves: Also bend a petiole that carries posed leaves
 
        Raises:
            ValueError: If any identifier is not a non-negative int, or
                ``include_posed_leaves`` is not a bool
            PlantArchitectureError: If the plant, shoot, node or petiole does not exist
            RuntimeError: If the native library predates helios-core v1.3.87
        """
        self._validateShootIdentifiers(plant_id, shoot_id)
        node_index = self._validateNodeIndex(node_index)
        petiole_index = self._validatePetioleIndex(petiole_index)
 
        if not isinstance(include_posed_leaves, bool):
            raise ValueError(
                f"include_posed_leaves must be a bool, got {type(include_posed_leaves).__name__}")
 
        self._check_context_alive()
        try:
            bend = (plantarch_wrapper.bendPetioleWithPosedLeavesUnderLeafWeight if include_posed_leaves
                    else plantarch_wrapper.bendPetioleUnderLeafWeight)
            bend(self._plantarch_ptr, plant_id, shoot_id, node_index, petiole_index)
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to bend petiole {petiole_index} of node {node_index} of shoot "
                f"{shoot_id} of plant {plant_id}: {e}")
 
    def recordPetioleRestShape(self, plant_id: int, shoot_id: int, node_index: int,
                               petiole_index: int) -> None:
        """
        Record one petiole's current centerline as its undeformed rest shape.
 
        :meth:`bendPetioleUnderLeafWeight` always bends from the recorded rest shape, so a
        petiole whose centerline has been replaced wholesale -- by
        :meth:`setPetioleNodePositions`, for instance -- must have its new shape recorded
        before it will droop from it. This also marks the petiole as needing to be bent
        again, so the next bend is not skipped as redundant.
 
        Args:
            plant_id: ID of the plant instance
            shoot_id: Shoot index within the plant
            node_index: Phytomer index within the shoot
            petiole_index: Petiole within the phytomer
 
        Raises:
            ValueError: If any identifier is not a non-negative int
            PlantArchitectureError: If the plant, shoot, node or petiole does not exist
            RuntimeError: If the native library predates helios-core v1.3.87
        """
        self._validateShootIdentifiers(plant_id, shoot_id)
        node_index = self._validateNodeIndex(node_index)
        petiole_index = self._validatePetioleIndex(petiole_index)
 
        self._check_context_alive()
        try:
            plantarch_wrapper.recordPetioleRestShape(
                self._plantarch_ptr, plant_id, shoot_id, node_index, petiole_index)
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to record the rest shape of petiole {petiole_index} of node "
                f"{node_index} of shoot {shoot_id} of plant {plant_id}: {e}")
 
    def setLeafAngleDistribution(self, plant_ids, beta_mu_inclination: float,
                                 beta_nu_inclination: float, eccentricity: Optional[float] = None,
                                 ellipse_rotation_degrees: float = 0.0) -> None:
        """
        Re-aim every leaf of a finished plant so that its leaf angles follow a prescribed distribution.
 
        Inclination is made to follow a Beta distribution. If ``eccentricity`` is given, azimuth
        is also made to follow an ellipsoidal distribution; otherwise each leaf keeps its azimuth.
        Angles are not sampled per leaf: leaves are ordered by their current angle, weighted by leaf
        area, and each takes the angle at its own position in the target distribution. The leaf
        arrangement of the plant is therefore kept, a leaf held steeper than its neighbour stays
        steeper, and the method can be called repeatedly with changing parameters (for example
        once per timestep) to move the canopy smoothly between distributions.
 
        This moves leaves that already exist. To steer leaves as they emerge on a growing plant,
        use :meth:`enableLeafAngleDistributionTracking`.
 
        Each leaf is re-aimed about its own base, so it stays attached to its petiole, and the
        angles are recorded on the phytomer so they survive an XML round trip.
 
        Args:
            plant_ids: A single plant ID, or a sequence of plant IDs over which the distribution
                is realized as a whole
            beta_mu_inclination: First parameter of the Beta inclination distribution; must be
                positive
            beta_nu_inclination: Second parameter of the Beta inclination distribution; must be
                positive. The mean leaf inclination from horizontal is 90 * nu / (mu + nu)
                degrees, so raising nu relative to mu makes the leaves steeper.
            eccentricity: Eccentricity of the ellipse defining the azimuth distribution, in
                [0, 1], where 0 is a uniform azimuth distribution. ``None`` (the default) leaves
                leaf azimuths as they are.
            ellipse_rotation_degrees: Rotation of that ellipse (degrees); used only when
                ``eccentricity`` is given
 
        Raises:
            ValueError: If a plant ID is not a non-negative int, the list is empty, a Beta
                parameter is not positive, or eccentricity is outside [0, 1]
            PlantArchitectureError: If a plant does not exist
            RuntimeError: If the native library predates this binding
 
        Example:
            >>> plantarch.setLeafAngleDistribution(plant_id, 2.0, 1.5)
        """
        multi = not isinstance(plant_ids, int) or isinstance(plant_ids, bool)
        ids = self._validatePlantIdList(plant_ids) if multi else [
            self._validatePlantIdentifier(plant_ids)]
        values = {}
        for name, value in (("beta_mu_inclination", beta_mu_inclination),
                            ("beta_nu_inclination", beta_nu_inclination),
                            ("eccentricity", 0.0 if eccentricity is None else eccentricity),
                            ("ellipse_rotation_degrees", ellipse_rotation_degrees)):
            if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
                raise ValueError(f"{name} must be a finite number, got {value!r}")
            values[name] = float(value)
        if values["beta_mu_inclination"] <= 0 or values["beta_nu_inclination"] <= 0:
            raise ValueError("beta_mu_inclination and beta_nu_inclination must be positive")
        if not 0.0 <= values["eccentricity"] <= 1.0:
            raise ValueError(f"eccentricity must be between 0 and 1, got {eccentricity}")
 
        self._check_context_alive()
        try:
            plantarch_wrapper.setPlantLeafAngleDistribution(
                self._plantarch_ptr, ids, values["beta_mu_inclination"],
                values["beta_nu_inclination"],
                None if eccentricity is None else values["eccentricity"],
                values["ellipse_rotation_degrees"])
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to set the leaf angle distribution of {ids}: {e}")
 
    def getPetioleFlexibility(self, plant_id: int, shoot_id: int, node_index: int) -> float:
        """
        Bending flexibility of the petioles of one phytomer.
 
        The value is drawn from ``PhytomerParameters.petiole.flexibility`` when the phytomer is
        created and held for its life. 0 is a rigid petiole.
 
        Args:
            plant_id: ID of the plant instance
            shoot_id: Shoot index within the plant
            node_index: Phytomer index within the shoot
 
        Returns:
            Dimensionless petiole flexibility
 
        Raises:
            ValueError: If any identifier is not a non-negative int
            PlantArchitectureError: If the plant, shoot or node does not exist
            RuntimeError: If the native library predates this binding
        """
        self._validateShootIdentifiers(plant_id, shoot_id)
        node_index = self._validateNodeIndex(node_index)
 
        self._check_context_alive()
        try:
            return plantarch_wrapper.getPetioleFlexibility(
                self._plantarch_ptr, plant_id, shoot_id, node_index)
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to get the petiole flexibility of node {node_index} of shoot "
                f"{shoot_id} of plant {plant_id}: {e}")
 
    def setPetioleFlexibility(self, plant_id: int, shoot_id: int, node_index: int,
                              flexibility: float) -> None:
        """
        Replace the bending flexibility of the petioles of one existing phytomer.
 
        This changes how far the petioles droop under their leaflets' weight without rebuilding
        the plant. The geometry does not move until :meth:`bendPetioleUnderLeafWeight` is called
        for each petiole (or the plant next grows), which bends from the recorded rest shape, so
        raising and lowering the flexibility is reversible. If the leaves have been posed, for
        example by :meth:`setLeafAngleDistribution`, bend with ``include_posed_leaves=True``.
 
        Note:
            :meth:`bendPetioleUnderLeafWeight` does nothing at a flexibility of exactly zero, so
            a petiole that has been bent is returned to its rest shape with a small positive
            value rather than zero.
 
        Args:
            plant_id: ID of the plant instance
            shoot_id: Shoot index within the plant
            node_index: Phytomer index within the shoot
            flexibility: Dimensionless petiole flexibility; must be finite and non-negative
 
        Raises:
            ValueError: If an identifier is invalid or ``flexibility`` is not a finite
                non-negative number
            PlantArchitectureError: If the plant, shoot or node does not exist
            RuntimeError: If the native library predates this binding
 
        Example:
            >>> plantarch.setPetioleFlexibility(plant_id, 0, 3, 2.0)
            >>> plantarch.bendPetioleUnderLeafWeight(plant_id, 0, 3, 0)
        """
        self._validateShootIdentifiers(plant_id, shoot_id)
        node_index = self._validateNodeIndex(node_index)
        if (isinstance(flexibility, bool) or not isinstance(flexibility, (int, float))
                or not math.isfinite(flexibility) or flexibility < 0):
            raise ValueError(
                f"Flexibility must be a finite non-negative number, got {flexibility!r}")
 
        self._check_context_alive()
        try:
            plantarch_wrapper.setPetioleFlexibility(
                self._plantarch_ptr, plant_id, shoot_id, node_index, float(flexibility))
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to set the petiole flexibility of node {node_index} of shoot "
                f"{shoot_id} of plant {plant_id}: {e}")
 
    # ------------------------------------------------------------------
    # Phytomer creation function (helios-core 1.3.88)
    # ------------------------------------------------------------------
 
    def setPhytomerCreationFunction(self, shoot_type_label: str,
                                    callback: Optional[Callable[[int, int, int, int, int, int, float], None]]) -> None:
        """
        Install a Python function that the plugin calls once for every new phytomer of a shoot type.
 
        This is the Python counterpart of assigning
        ``phytomer_parameters.phytomer_creation_function`` in C++. It is how a model varies a
        phytomer's growth targets with its position on the plant -- for example scaling leaf and
        petiole size with node rank -- using the per-phytomer methods such as
        :meth:`scaleLeafPrototypeScale`, :meth:`scalePetioleMaxLength` and
        :meth:`scaleInternodeMaxLength`.
 
        The callback is called as::
 
            callback(plant_id, shoot_id, node_index, shoot_node_index,
                     parent_shoot_node_index, shoot_max_nodes, plant_age)
 
        after the plugin has attached the new phytomer to its shoot, so
        ``(plant_id, shoot_id, node_index)`` addresses it through any per-phytomer method.
        ``node_index`` is the phytomer's index on its shoot. ``shoot_node_index`` is the value the
        plugin passes to a C++ creation function, kept for porting C++ models: during growth it
        equals ``node_index``, but while a shoot's initial phytomers are built by
        :meth:`addBaseStemShoot`, :meth:`appendShoot` or :meth:`addChildShoot` it is the shoot's
        initial node count (a one-node base stem passes 1 for phytomer 0).
        ``parent_shoot_node_index`` is the node of the parent shoot this shoot grows from,
        ``shoot_max_nodes`` the shoot's node limit and ``plant_age`` the plant's age in days.
        The return value is ignored.
 
        The callback fires for phytomers created while building shoots as well as during
        :meth:`advanceTime`. If it raises, the exception propagates out of the call that created
        the phytomer (``advanceTime``, ``addBaseStemShoot``, ...) with its original type, and no
        further callbacks run during that call; the plant is left as it was when the exception was
        raised, partly grown. Changes the callback makes to the length of an internode prescribed
        by :meth:`addShootFromNodePositions` are undone by the plugin.
 
        Which shoots are affected:
 
        - The function is stored on the shoot type, and each shoot copies its type's parameters
          when it is created, so shoots created before this call keep whatever function they had.
        - Shoots created while a Python callback is installed look it up by label each time, so
          replacing the callback or clearing it with ``None`` also takes effect for them.
        - ``None`` restores the function the shoot type had before a Python callback was first
          installed on it, usually the library one (for example the library ``tomato`` model's
          ``mainstem`` function, which rescales every new phytomer's leaves and internode by plant
          age). To build without a library function, define a new shoot type from the parameters
          (see below), which carries none.
        - Redefining an existing label with :meth:`defineShootType` keeps its creation function.
          A new label defined from another type's parameters (for example
          ``defineShootType("my_stem", getCurrentShootParameters("mainstem"))``) starts with
          none, because the parameter dict carries no functions: it inherits neither a Python
          callback nor a library function.
 
        Args:
            shoot_type_label: An existing shoot type label
            callback: A callable taking the seven arguments above; the name of a library creation
                function (see :meth:`getLibraryPhytomerCreationFunctionNames`), which installs that
                native function in place of whatever the type had; or ``None`` to restore the
                function the type had before a Python callback was installed
 
        Raises:
            ValueError: If the label is not a non-empty str, the callback is neither callable, a str
                nor None, or the name is empty
            PlantArchitectureError: If the shoot type does not exist or the name is not a library
                creation function
            RuntimeError: If the native library predates helios-core v1.3.88
        """
        if not isinstance(shoot_type_label, str) or not shoot_type_label:
            raise ValueError(
                f"Shoot type label must be a non-empty str, got {type(shoot_type_label).__name__}")
        if isinstance(callback, str):
            self._setLibraryPhytomerFunction(shoot_type_label, callback, creation=True)
            return
        if callback is not None and not callable(callback):
            raise ValueError(
                f"Phytomer creation callback must be callable, a library function name or None, "
                f"got {type(callback).__name__}")
 
        native_callback = None if callback is None else self._makePhytomerCreationTrampoline(callback)
        self._check_context_alive()
        try:
            plantarch_wrapper.setPhytomerCreationFunction(self._plantarch_ptr, shoot_type_label, native_callback)
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to set the phytomer creation function of shoot type '{shoot_type_label}': {e}")
 
        # The native registry now holds native_callback (or nothing), so this is the reference that must stay alive.
        callbacks = self.__dict__.setdefault('_phytomer_creation_callbacks', {})
        if native_callback is None:
            callbacks.pop(shoot_type_label, None)
        else:
            callbacks[shoot_type_label] = native_callback
 
    def setPhytomerCallbackFunction(self, shoot_type_label: str,
                                    callback: Optional[Callable[[int, int, int, float], None]]) -> None:
        """
        Install a Python function that the plugin calls for every phytomer of a shoot type on every time step.
 
        This is the Python counterpart of assigning
        ``phytomer_parameters.phytomer_callback_function`` in C++. Use it for per-phytomer logic that must
        run as the plant develops rather than once at creation (for that, see
        :meth:`setPhytomerCreationFunction`), for example adjusting growth targets with phytomer age.
 
        The callback is called as::
 
            callback(plant_id, shoot_id, node_index, phytomer_age)
 
        once per phytomer per :meth:`advanceTime` sub-step, after the phytomer's age has been advanced, so
        ``(plant_id, shoot_id, node_index)`` addresses it through any per-phytomer method and
        ``phytomer_age`` (days) equals :meth:`getPhytomerAge` at that moment. ``advanceTime`` divides its
        interval into sub-steps of at most the shortest phyllochron (and at most 1 day for intervals shorter
        than that), so the number of calls per phytomer is the number of sub-steps, not the number of days. It
        also runs inside :meth:`buildPlantInstanceFromLibrary` and :meth:`buildPlantCanopyFromLibrary` when
        they grow a plant to its starting age. The return value is ignored.
 
        Performance: the cost scales with (phytomers x sub-steps), so keep the callback's own work light,
        especially for large populations that change slowly, such as a dormant tree over many days.
 
        If the callback raises, the exception propagates out of the call that advanced time with its original
        type, and no further callbacks run during that call; the plant is left partly advanced.
 
        Which phytomers are affected:
 
        - The function is copied into each phytomer when the phytomer is created, so phytomers created
          before this call do not call a newly installed function. Install it before building the plant.
        - Phytomers created while a Python callback is installed look it up by label on each call, so
          replacing the callback or clearing it with ``None`` also takes effect for them.
        - ``None`` restores the function the shoot type had before a Python callback was first
          installed on it, usually the library one. Clearing a callback that was never installed
          changes nothing.
        - As with :meth:`setPhytomerCreationFunction`, redefining an existing label with
          :meth:`defineShootType` keeps the function, but a new label defined from another type's parameter
          dict starts with none.
 
        Args:
            shoot_type_label: An existing shoot type label
            callback: A callable taking the four arguments above; the name of a library callback
                function (see :meth:`getLibraryPhytomerCallbackFunctionNames`), which installs that
                native function in place of whatever the type had; or ``None`` to restore the
                function the type had before a Python callback was installed
 
        Raises:
            ValueError: If the label is not a non-empty str, the callback is neither callable, a str
                nor None, or the name is empty
            PlantArchitectureError: If the shoot type does not exist or the name is not a library
                callback function
            RuntimeError: If the native library predates this function
        """
        if not isinstance(shoot_type_label, str) or not shoot_type_label:
            raise ValueError(
                f"Shoot type label must be a non-empty str, got {type(shoot_type_label).__name__}")
        if isinstance(callback, str):
            self._setLibraryPhytomerFunction(shoot_type_label, callback, creation=False)
            return
        if callback is not None and not callable(callback):
            raise ValueError(
                f"Phytomer callback function must be callable, a library function name or None, "
                f"got {type(callback).__name__}")
 
        native_callback = None if callback is None else self._makePhytomerCallbackTrampoline(callback)
        self._check_context_alive()
        try:
            plantarch_wrapper.setPhytomerCallbackFunction(self._plantarch_ptr, shoot_type_label, native_callback)
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to set the phytomer callback function of shoot type '{shoot_type_label}': {e}")
 
        # The native registry now holds native_callback (or nothing), so this is the reference that must stay alive.
        callbacks = self.__dict__.setdefault('_phytomer_callbacks', {})
        if native_callback is None:
            callbacks.pop(shoot_type_label, None)
        else:
            callbacks[shoot_type_label] = native_callback
 
    def _setLibraryPhytomerFunction(self, shoot_type_label: str, function_name: str, creation: bool) -> None:
        kind = "creation" if creation else "callback"
        if not function_name:
            raise ValueError(f"Library phytomer {kind} function name cannot be empty")
        self._check_context_alive()
        setter = (plantarch_wrapper.setPhytomerCreationFunctionByName if creation
                  else plantarch_wrapper.setPhytomerCallbackFunctionByName)
        try:
            setter(self._plantarch_ptr, shoot_type_label, function_name)
        except RuntimeError:
            raise
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to set the phytomer {kind} function of shoot type '{shoot_type_label}' "
                f"to library function '{function_name}': {e}")
        # The library function replaced any Python callback, which no longer needs to be kept alive.
        registry = '_phytomer_creation_callbacks' if creation else '_phytomer_callbacks'
        self.__dict__.setdefault(registry, {}).pop(shoot_type_label, None)
 
    def _getLibraryPhytomerFunctionName(self, shoot_type_label: str, creation: bool) -> Optional[str]:
        if not isinstance(shoot_type_label, str) or not shoot_type_label:
            raise ValueError(
                f"Shoot type label must be a non-empty str, got {type(shoot_type_label).__name__}")
        self._check_context_alive()
        getter = (plantarch_wrapper.getPhytomerCreationFunctionName if creation
                  else plantarch_wrapper.getPhytomerCallbackFunctionName)
        try:
            return getter(self._plantarch_ptr, shoot_type_label) or None
        except RuntimeError:
            raise
        except Exception as e:
            kind = "creation" if creation else "callback"
            raise PlantArchitectureError(
                f"Failed to get the phytomer {kind} function of shoot type '{shoot_type_label}': {e}")
 
    def getPhytomerCreationFunctionName(self, shoot_type_label: str) -> Optional[str]:
        """
        Get the name of the library creation function a shoot type carries.
 
        Use it to carry a library model's creation function over to a new shoot type, which
        :meth:`defineShootType` starts without::
 
            params = plantarch.getCurrentShootParameters("proleptic")
            plantarch.defineShootType("my_shoot", params)
            name = plantarch.getPhytomerCreationFunctionName("proleptic")
            if name:
                plantarch.setPhytomerCreationFunction("my_shoot", name)
 
        Args:
            shoot_type_label: An existing shoot type label
 
        Returns:
            The library function's name, or ``None`` if the shoot type has no creation function
            or has a Python one
 
        Raises:
            ValueError: If the label is not a non-empty str
            PlantArchitectureError: If the shoot type does not exist
            RuntimeError: If the native library predates this function
        """
        return self._getLibraryPhytomerFunctionName(shoot_type_label, creation=True)
 
    def getPhytomerCallbackFunctionName(self, shoot_type_label: str) -> Optional[str]:
        """
        Get the name of the library per-timestep callback function a shoot type carries.
 
        Args:
            shoot_type_label: An existing shoot type label
 
        Returns:
            The library function's name, or ``None`` if the shoot type has no callback function
            or has a Python one
 
        Raises:
            ValueError: If the label is not a non-empty str
            PlantArchitectureError: If the shoot type does not exist
            RuntimeError: If the native library predates this function
        """
        return self._getLibraryPhytomerFunctionName(shoot_type_label, creation=False)
 
    @staticmethod
    def getLibraryPhytomerCreationFunctionNames() -> List[str]:
        """
        List the library phytomer creation functions that :meth:`setPhytomerCreationFunction` accepts by name.
 
        These are the functions the library plant models use, for example
        ``"AlmondPhytomerCreationFunction"`` or ``"TomatoPhytomerCreationFunction"``.
 
        Returns:
            Function names, sorted
 
        Raises:
            RuntimeError: If the native library predates this function
        """
        return plantarch_wrapper.getLibraryPhytomerCreationFunctionNames()
 
    @staticmethod
    def getLibraryPhytomerCallbackFunctionNames() -> List[str]:
        """
        List the library per-timestep callback functions that :meth:`setPhytomerCallbackFunction` accepts by name.
 
        These are the functions the library plant models use, for example
        ``"AlmondSpurPhytomerCallbackFunction"`` (grows spurs on a model that defines a ``spur``
        shoot type) or ``"GrapevinePhytomerCallbackFunction"`` (pulls fruit-zone leaves).
 
        Returns:
            Function names, sorted
 
        Raises:
            RuntimeError: If the native library predates this function
        """
        return plantarch_wrapper.getLibraryPhytomerCallbackFunctionNames()
 
    def _makePhytomerCallbackTrampoline(self, callback):
        """Wrap callback so an exception is stored for re-raising instead of being lost inside ctypes."""
        owner = weakref.ref(self)
 
        def trampoline(plant_id, shoot_id, node_index, phytomer_age):
            plantarch = owner()
            if plantarch is None or getattr(plantarch, '_pending_callback_error', None) is not None:
                return 1
            plantarch._phytomer_callback_depth = getattr(plantarch, '_phytomer_callback_depth', 0) + 1
            try:
                callback(plant_id, shoot_id, node_index, phytomer_age)
            except BaseException as e:
                plantarch._pending_callback_error = e
                return 1
            finally:
                plantarch._phytomer_callback_depth -= 1
            return 0
 
        return plantarch_wrapper.PHYTOMER_CALLBACK(trampoline)
 
    def _makePhytomerCreationTrampoline(self, callback):
        """Wrap callback so an exception is stored for re-raising instead of being lost inside ctypes."""
        owner = weakref.ref(self)
 
        def trampoline(plant_id, shoot_id, node_index, shoot_node_index, parent_shoot_node_index,
                       shoot_max_nodes, plant_age):
            plantarch = owner()
            if plantarch is None or getattr(plantarch, '_pending_callback_error', None) is not None:
                return 1
            plantarch._phytomer_callback_depth = getattr(plantarch, '_phytomer_callback_depth', 0) + 1
            try:
                callback(int(plant_id), int(shoot_id), int(node_index), int(shoot_node_index),
                         int(parent_shoot_node_index), int(shoot_max_nodes), float(plant_age))
            except BaseException as e:
                plantarch._pending_callback_error = e
                return 1
            finally:
                plantarch._phytomer_callback_depth -= 1
            return 0
 
        return plantarch_wrapper.PHYTOMER_CREATION_CALLBACK(trampoline)
 
    def _reject_inside_phytomer_callback(self, method_name: str) -> None:
        """Raise if called from a Python phytomer creation or callback function.
 
        The native plugin skips these operations inside a callback and only prints a warning, which
        disableMessages() suppresses, so the call would otherwise appear to succeed.
        """
        if getattr(self, '_phytomer_callback_depth', 0) > 0:
            raise PlantArchitectureError(
                f"{method_name}() cannot be called from inside a phytomer creation or callback function, "
                f"because it changes plant structure while the plant is being grown. Call it from outside "
                f"the function, for example between calls to advanceTime(). pruneBranch() is the only "
                f"structural edit a callback can make; it takes effect at the end of the current time step."
            )
 
    def _raise_pending_callback_error(self, native_error: Optional[BaseException] = None) -> None:
        """Raise, and clear, an exception stored by a phytomer creation or callback function."""
        pending = getattr(self, '_pending_callback_error', None)
        if pending is None:
            return
        self._pending_callback_error = None
        raise pending from native_error
 
    # ------------------------------------------------------------------
    # Per-phytomer growth targets and live phyllotaxy (helios-core 1.3.88)
    # ------------------------------------------------------------------
 
    def _phytomerCall(self, description: str, plant_id: int, shoot_id: int, node_index: int, fn, *args):
        """Call a per-phytomer wrapper, turning an out-of-range index into ValueError."""
        self._check_context_alive()
        try:
            return fn(self._plantarch_ptr, plant_id, shoot_id, node_index, *args)
        except HeliosInvalidArgumentError as e:
            raise ValueError(str(e)) from None
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to {description} of node {node_index} of shoot {shoot_id} of plant {plant_id}: {e}")
 
    def setInternodeMaxLength(self, plant_id: int, shoot_id: int, node_index: int, length: float) -> None:
        """
        Set the fully-elongated length of one existing internode.
 
        Only this phytomer's target changes; compare :meth:`setShootInternodeLengthMax`, which
        sets the target for internodes the shoot has yet to produce. A target below the
        internode's present length shortens it immediately; a larger target leaves the present
        length alone and the internode grows toward it on later :meth:`advanceTime` calls.
 
        Args:
            plant_id: ID of the plant instance
            shoot_id: Shoot index within the plant
            node_index: Phytomer index within the shoot
            length: Fully-elongated internode length in meters; must be positive and finite
 
        Raises:
            ValueError: If an identifier is invalid, ``length`` is not positive and finite, or ``node_index`` is past the end of the shoot
            PlantArchitectureError: If the plant or shoot does not exist
            RuntimeError: If the native library predates helios-core v1.3.88
        """
        self._validateShootIdentifiers(plant_id, shoot_id)
        node_index = self._validateNodeIndex(node_index)
        if isinstance(length, bool) or not isinstance(length, (int, float)) or not math.isfinite(length) \
                or not length > 0:
            raise ValueError(f"Internode max length must be a positive, finite number, got {length!r}")
        self._phytomerCall("set the internode max length", plant_id, shoot_id, node_index,
                           plantarch_wrapper.setInternodeMaxLength, float(length))
 
    def scaleInternodeMaxLength(self, plant_id: int, shoot_id: int, node_index: int, scale_factor: float) -> None:
        """
        Scale the fully-elongated length of one existing internode.
 
        As :meth:`setInternodeMaxLength`, relative to the current target: a factor below one
        shortens an internode that is already longer than its new target, and a factor above one
        lets it grow further.
 
        Args:
            plant_id: ID of the plant instance
            shoot_id: Shoot index within the plant
            node_index: Phytomer index within the shoot
            scale_factor: Factor to scale the fully-elongated length by; must be positive
 
        Raises:
            ValueError: If an identifier is invalid, ``scale_factor`` is not positive, or ``node_index`` is past the end of the shoot
            PlantArchitectureError: If the plant or shoot does not exist
            RuntimeError: If the native library predates helios-core v1.3.88
        """
        self._validateShootIdentifiers(plant_id, shoot_id)
        node_index = self._validateNodeIndex(node_index)
        scale_factor = self._validateScaleFactor(scale_factor)
        self._phytomerCall("scale the internode max length", plant_id, shoot_id, node_index,
                           plantarch_wrapper.scaleInternodeMaxLength, scale_factor)
 
    def scaleLeafPrototypeScale(self, plant_id: int, shoot_id: int, node_index: int, scale_factor: float,
                                petiole_index: Optional[int] = None) -> None:
        """
        Scale a phytomer's leaves now: both the blades' present size and the size they grow toward.
 
        The leaves are rescaled about their bases immediately and keep their expansion fraction,
        so a half-expanded leaf stays half-expanded toward a proportionally larger or smaller
        mature size. This is what a C++ phytomer creation function does to size a new leaf by its
        position on the plant. Contrast :meth:`scaleLeafSizeMax`, which moves only the target and
        leaves the blades as they are.
 
        Args:
            plant_id: ID of the plant instance
            shoot_id: Shoot index within the plant
            node_index: Phytomer index within the shoot
            scale_factor: Factor to scale the leaves by; must be positive
            petiole_index: Scale only the leaves of this petiole; ``None`` for every petiole
 
        Raises:
            ValueError: If an identifier is invalid, ``scale_factor`` is not positive, or an index is out of range
            PlantArchitectureError: If the plant or shoot does not exist
            RuntimeError: If the native library predates helios-core v1.3.88
        """
        self._validateShootIdentifiers(plant_id, shoot_id)
        node_index = self._validateNodeIndex(node_index)
        scale_factor = self._validateScaleFactor(scale_factor)
        if petiole_index is not None:
            petiole_index = self._validatePetioleIndex(petiole_index)
        self._phytomerCall("scale the leaf prototype", plant_id, shoot_id, node_index,
                           plantarch_wrapper.scaleLeafPrototypeScale, scale_factor, petiole_index)
 
    def setShootPhyllotacticAngle(self, plant_id: int, shoot_id: int, mean_deg: float,
                                  sd_deg: Optional[float] = None) -> None:
        """
        Set the phyllotactic angle that one shoot's next phytomers are created with.
 
        Each new phytomer draws its angle from its shoot's own copy of the shoot parameters, so
        calling this before a time step sets the angle of the phytomers produced during that step
        without touching any phytomer already built, any other shoot, or the shoot type. Calling
        it before every step drives a node-by-node angle sequence.
 
        With ``sd_deg`` omitted the angle is the constant ``mean_deg``. With ``sd_deg`` given the
        angle is drawn from a normal distribution, which draws from the Context random generator
        for every new phytomer even when ``sd_deg`` is 0 -- matching a C++ caller of
        ``phyllotactic_angle.normalDistribution(mean, sd)``, which matters when reproducing a C++
        run draw for draw.
 
        Args:
            plant_id: ID of the plant instance
            shoot_id: Shoot index within the plant
            mean_deg: Phyllotactic angle, or its mean, in degrees
            sd_deg: Standard deviation in degrees (non-negative), or ``None`` for a constant
 
        Raises:
            ValueError: If an identifier is invalid or an angle is not finite, or ``sd_deg`` is negative
            PlantArchitectureError: If the plant or shoot does not exist
            RuntimeError: If the native library predates helios-core v1.3.88
        """
        self._validateShootIdentifiers(plant_id, shoot_id)
        if isinstance(mean_deg, bool) or not isinstance(mean_deg, (int, float)) or not math.isfinite(mean_deg):
            raise ValueError(f"Mean phyllotactic angle must be a finite number, got {mean_deg!r}")
        if sd_deg is not None and (isinstance(sd_deg, bool) or not isinstance(sd_deg, (int, float))
                                   or not math.isfinite(sd_deg) or sd_deg < 0):
            raise ValueError(
                f"Phyllotactic angle standard deviation must be a finite, non-negative number or None, got {sd_deg!r}")
        self._check_context_alive()
        try:
            plantarch_wrapper.setShootPhyllotacticAngle(
                self._plantarch_ptr, plant_id, shoot_id, float(mean_deg), None if sd_deg is None else float(sd_deg))
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to set the phyllotactic angle of shoot {shoot_id} of plant {plant_id}: {e}")
 
    # ------------------------------------------------------------------
    # Per-phytomer readouts (helios-core 1.3.88)
    # ------------------------------------------------------------------
 
    def getPhytomerAge(self, plant_id: int, shoot_id: int, node_index: int) -> float:
        """
        Age of one phytomer in days, counted from its creation.
 
        Raises:
            ValueError: If an identifier is invalid or ``node_index`` is past the end of the shoot
            PlantArchitectureError: If the plant or shoot does not exist
            RuntimeError: If the native library predates helios-core v1.3.88
        """
        self._validateShootIdentifiers(plant_id, shoot_id)
        node_index = self._validateNodeIndex(node_index)
        return self._phytomerCall("get the age", plant_id, shoot_id, node_index, plantarch_wrapper.getPhytomerAge)
 
    def getInternodeLength(self, plant_id: int, shoot_id: int, node_index: int) -> float:
        """
        Present length of one internode in meters, measured along its node positions.
 
        Raises:
            ValueError: If an identifier is invalid or ``node_index`` is past the end of the shoot
            PlantArchitectureError: If the plant or shoot does not exist
            RuntimeError: If the native library predates helios-core v1.3.88
        """
        self._validateShootIdentifiers(plant_id, shoot_id)
        node_index = self._validateNodeIndex(node_index)
        return self._phytomerCall("get the internode length", plant_id, shoot_id, node_index,
                                  plantarch_wrapper.getInternodeLength)
 
    def getInternodeRadius(self, plant_id: int, shoot_id: int, node_index: int) -> float:
        """
        Radius in meters at the base of one internode.
 
        Raises:
            ValueError: If an identifier is invalid or ``node_index`` is past the end of the shoot
            PlantArchitectureError: If the plant or shoot does not exist
            RuntimeError: If the native library predates helios-core v1.3.88
        """
        self._validateShootIdentifiers(plant_id, shoot_id)
        node_index = self._validateNodeIndex(node_index)
        return self._phytomerCall("get the internode radius", plant_id, shoot_id, node_index,
                                  plantarch_wrapper.getInternodeRadius)
 
    def getInternodeNodePositions(self, plant_id: int, shoot_id: int, node_index: int) -> List[vec3]:
        """
        Positions of one internode's nodes, from its base to its tip.
 
        The first position is the tip of the previous internode on the shoot.
 
        Raises:
            ValueError: If an identifier is invalid or ``node_index`` is past the end of the shoot
            PlantArchitectureError: If the plant or shoot does not exist
            RuntimeError: If the native library predates helios-core v1.3.88
        """
        self._validateShootIdentifiers(plant_id, shoot_id)
        node_index = self._validateNodeIndex(node_index)
        points = self._phytomerCall("get the internode node positions", plant_id, shoot_id, node_index,
                                    plantarch_wrapper.getInternodeNodePositions)
        return [vec3(*p) for p in points]
 
    def getInternodeAxisVector(self, plant_id: int, shoot_id: int, node_index: int, stem_fraction: float) -> vec3:
        """
        Unit direction of one internode at a fraction of its length.
 
        Args:
            plant_id: ID of the plant instance
            shoot_id: Shoot index within the plant
            node_index: Phytomer index within the shoot
            stem_fraction: Position along the internode, 0 at its base and 1 at its tip
 
        Raises:
            ValueError: If an identifier is invalid, ``stem_fraction`` is outside [0, 1], or ``node_index`` is past the end of the shoot
            PlantArchitectureError: If the plant or shoot does not exist
            RuntimeError: If the native library predates helios-core v1.3.88
        """
        self._validateShootIdentifiers(plant_id, shoot_id)
        node_index = self._validateNodeIndex(node_index)
        stem_fraction = self._validateStemFraction(stem_fraction)
        return vec3(*self._phytomerCall("get the internode axis", plant_id, shoot_id, node_index,
                                        plantarch_wrapper.getInternodeAxisVector, stem_fraction))
 
    def getPetioleAxisVector(self, plant_id: int, shoot_id: int, node_index: int, stem_fraction: float,
                             petiole_index: int) -> vec3:
        """
        Unit direction of one petiole at a fraction of its length.
 
        Args:
            plant_id: ID of the plant instance
            shoot_id: Shoot index within the plant
            node_index: Phytomer index within the shoot
            stem_fraction: Position along the petiole, 0 at its base and 1 at its tip
            petiole_index: Petiole within the phytomer
 
        Raises:
            ValueError: If an identifier is invalid, ``stem_fraction`` is outside [0, 1], or an index is out of range (a phytomer whose leaf was shed has no petioles)
            PlantArchitectureError: If the plant or shoot does not exist
            RuntimeError: If the native library predates helios-core v1.3.88
        """
        self._validateShootIdentifiers(plant_id, shoot_id)
        node_index = self._validateNodeIndex(node_index)
        stem_fraction = self._validateStemFraction(stem_fraction)
        petiole_index = self._validatePetioleIndex(petiole_index)
        return vec3(*self._phytomerCall("get the petiole axis", plant_id, shoot_id, node_index,
                                        plantarch_wrapper.getPetioleAxisVector, stem_fraction, petiole_index))
 
    def getPetioleVertices(self, plant_id: int, shoot_id: int, node_index: int, petiole_index: int) -> List[vec3]:
        """
        Centerline vertices of one petiole, from its base at the node to its tip.
 
        Raises:
            ValueError: If an identifier is invalid or an index is out of range
            PlantArchitectureError: If the plant or shoot does not exist
            RuntimeError: If the native library predates helios-core v1.3.88
        """
        self._validateShootIdentifiers(plant_id, shoot_id)
        node_index = self._validateNodeIndex(node_index)
        petiole_index = self._validatePetioleIndex(petiole_index)
        points = self._phytomerCall("get the petiole vertices", plant_id, shoot_id, node_index,
                                    plantarch_wrapper.getPetioleVertices, petiole_index)
        return [vec3(*p) for p in points]
 
    def getPetioleRadii(self, plant_id: int, shoot_id: int, node_index: int, petiole_index: int) -> List[float]:
        """
        Radius in meters of one petiole at each of its centerline vertices (see :meth:`getPetioleVertices`).
 
        Raises:
            ValueError: If an identifier is invalid or an index is out of range
            PlantArchitectureError: If the plant or shoot does not exist
            RuntimeError: If the native library predates helios-core v1.3.88
        """
        self._validateShootIdentifiers(plant_id, shoot_id)
        node_index = self._validateNodeIndex(node_index)
        petiole_index = self._validatePetioleIndex(petiole_index)
        return self._phytomerCall("get the petiole radii", plant_id, shoot_id, node_index,
                                  plantarch_wrapper.getPetioleRadii, petiole_index)
 
    def getPhytomerLeafObjectIDs(self, plant_id: int, shoot_id: int, node_index: int) -> List[List[int]]:
        """
        Object IDs of one phytomer's leaves, grouped by petiole.
 
        Returns one list per petiole with one object ID per leaf (leaflet) on that petiole, in the
        order :meth:`getLeafBasePosition` indexes them. A phytomer whose leaves were shed returns
        empty lists.
 
        Raises:
            ValueError: If an identifier is invalid or ``node_index`` is past the end of the shoot
            PlantArchitectureError: If the plant or shoot does not exist
            RuntimeError: If the native library predates helios-core v1.3.88
        """
        self._validateShootIdentifiers(plant_id, shoot_id)
        node_index = self._validateNodeIndex(node_index)
        return self._phytomerCall("get the leaf object IDs", plant_id, shoot_id, node_index,
                                  plantarch_wrapper.getPhytomerLeafObjectIDs)
 
    def getLeafBasePosition(self, plant_id: int, shoot_id: int, node_index: int, petiole_index: int,
                            leaf_index: int) -> vec3:
        """
        Position where one leaf (leaflet) attaches to its petiole.
 
        Raises:
            ValueError: If an identifier is invalid or an index is out of range
            PlantArchitectureError: If the plant or shoot does not exist
            RuntimeError: If the native library predates helios-core v1.3.88
        """
        self._validateShootIdentifiers(plant_id, shoot_id)
        node_index = self._validateNodeIndex(node_index)
        petiole_index = self._validatePetioleIndex(petiole_index)
        leaf_index = self._validatePetioleIndex(leaf_index, name="Leaf index")
        return vec3(*self._phytomerCall("get the leaf base position", plant_id, shoot_id, node_index,
                                        plantarch_wrapper.getLeafBasePosition, petiole_index, leaf_index))
 
    # ------------------------------------------------------------------
    # Per-model leaf inclination distribution and plant nitrogen (helios-core 1.3.88)
    # ------------------------------------------------------------------
 
    def getPlantModelLeafInclinationDistribution(self, plant_model_name: str) -> tuple:
        """
        Beta leaf inclination distribution ``(mu, nu)`` that a library plant model declares.
 
        Plants built from a model that declares a distribution have their leaf inclinations
        steered toward it automatically. Returns ``(0.0, 0.0)`` when the model declares none.
 
        Raises:
            ValueError: If ``plant_model_name`` is not a non-empty str
            PlantArchitectureError: If the model is not in the library
            RuntimeError: If the native library predates helios-core v1.3.88
        """
        self._validatePlantModelName(plant_model_name)
        self._check_context_alive()
        try:
            return plantarch_wrapper.getPlantModelLeafInclinationDistribution(self._plantarch_ptr, plant_model_name)
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to get the leaf inclination distribution of plant model '{plant_model_name}': {e}")
 
    def setPlantModelLeafInclinationDistribution(self, plant_model_name: str, beta_mu: float,
                                                 beta_nu: float) -> None:
        """
        Set or clear the Beta leaf inclination distribution of a library plant model.
 
        Plants built from the model afterwards are steered toward the distribution. Two positive
        values set it; ``(0, 0)`` clears it, restoring the model's unsteered leaf angles.
 
        Raises:
            ValueError: If the name is not a non-empty str, or the Beta parameters are not both positive or both zero
            PlantArchitectureError: If the model is not in the library
            RuntimeError: If the native library predates helios-core v1.3.88
        """
        self._validatePlantModelName(plant_model_name)
        for name, v in (("beta_mu", beta_mu), ("beta_nu", beta_nu)):
            if isinstance(v, bool) or not isinstance(v, (int, float)) or not math.isfinite(v) or v < 0:
                raise ValueError(f"Beta parameter {name} must be a finite, non-negative number, got {v!r}")
        if (beta_mu > 0) != (beta_nu > 0):
            raise ValueError(
                f"Beta parameters must both be positive to set a distribution or both zero to clear it, "
                f"got ({beta_mu}, {beta_nu})")
        self._check_context_alive()
        try:
            plantarch_wrapper.setPlantModelLeafInclinationDistribution(
                self._plantarch_ptr, plant_model_name, float(beta_mu), float(beta_nu))
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to set the leaf inclination distribution of plant model '{plant_model_name}': {e}")
 
    def doesPlantModelDeclareLeafInclinationDistribution(self, plant_model_name: str) -> bool:
        """
        Whether a library plant model declares a leaf inclination distribution.
 
        Raises:
            ValueError: If ``plant_model_name`` is not a non-empty str
            PlantArchitectureError: If the model is not in the library
            RuntimeError: If the native library predates helios-core v1.3.88
        """
        self._validatePlantModelName(plant_model_name)
        self._check_context_alive()
        try:
            return plantarch_wrapper.doesPlantModelDeclareLeafInclinationDistribution(
                self._plantarch_ptr, plant_model_name)
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to query the leaf inclination distribution of plant model '{plant_model_name}': {e}")
 
    def getPlantAvailableNitrogen(self, plant_id: int) -> float:
        """
        Nitrogen (g N) in a plant's available pool, awaiting allocation to its organs.
 
        Raises:
            ValueError: If ``plant_id`` is not a non-negative int
            PlantArchitectureError: If the plant does not exist
            RuntimeError: If the native library predates helios-core v1.3.88
        """
        plant_id = self._validatePlantIdentifier(plant_id)
        self._check_context_alive()
        try:
            return plantarch_wrapper.getPlantAvailableNitrogen(self._plantarch_ptr, plant_id)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to get the available nitrogen of plant {plant_id}: {e}")
 
    def getLeafBladeArea(self, leaf_object_id: int) -> float:
        """
        One-sided blade area (m²) of a single leaf object.
 
        A leaf object can carry a petiolule -- the stalk joining a leaflet to its rachis
        (see :attr:`pyhelios.plant_architecture_params.LeafPrototype.build_petiolule`) --
        whose primitives are labelled ``"petiolule"`` rather than ``"leaf"``. This reports
        the area of the object without them, which is what every leaf-area quantity of the
        plugin (:meth:`sumPlantLeafArea`, :meth:`getPlantLeafAreas`) means as of
        helios-core 1.3.89. ``Context.getObjectArea()`` on the same object includes the
        petiolule.
 
        Args:
            leaf_object_id: Object ID of the leaf (e.g. from :meth:`getPlantLeafObjectIDs`)
 
        Returns:
            Blade area in m²
 
        Raises:
            ValueError: If ``leaf_object_id`` is not a non-negative int
            PlantArchitectureError: If the object does not exist
            RuntimeError: If the native library predates helios-core v1.3.89
        """
        if isinstance(leaf_object_id, bool) or not isinstance(leaf_object_id, int):
            raise ValueError(
                f"Leaf object ID must be a non-negative int, got {type(leaf_object_id).__name__}")
        if leaf_object_id < 0:
            raise ValueError("Leaf object ID must be non-negative")
        self._check_context_alive()
        try:
            return plantarch_wrapper.getLeafBladeArea(self._plantarch_ptr, leaf_object_id)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to get the blade area of leaf object {leaf_object_id}: {e}")
 
    def getShadowLightExposureAtPoint(self, plant_id: int, position: vec3) -> float:
        """
        Local light exposure at a point from a plant's shadow-propagation grid.
 
        Exposure runs from 0 (fully shaded) to 1 (unshaded), and is the quantity that drives
        shade-based branch shedding at each dormancy boundary in parameter-based growth
        (after Palubicki et al. 2009): branches deep in the crown interior see a low
        exposure while branches on the crown surface do not. Returns 1 when the plant has no
        canopy yet, or when the shadow grid is disabled because the carbohydrate model is
        active. Intended for inspection and testing; it is a cheap surrogate for light
        interception, not a radiation calculation.
 
        Args:
            plant_id: ID of the plant
            position: Query position in world coordinates
 
        Returns:
            Local light exposure in [0, 1]
 
        Raises:
            ValueError: If ``plant_id`` is not a non-negative int or ``position`` is not a vec3
            PlantArchitectureError: If the plant does not exist
            RuntimeError: If the native library predates helios-core v1.3.89
        """
        plant_id = self._validatePlantIdentifier(plant_id)
        if not isinstance(position, vec3):
            raise ValueError(f"Position must be a vec3, got {type(position).__name__}")
        self._check_context_alive()
        try:
            return plantarch_wrapper.getShadowLightExposureAtPoint(
                self._plantarch_ptr, plant_id, (position.x, position.y, position.z))
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to get the shadow-grid light exposure of plant {plant_id}: {e}")
 
    def getSeasonPeakLightExposureAtPoint(self, plant_id: int, position: vec3) -> float:
        """
        Local light exposure at a point under the plant's most recent seasonal peak canopy.
 
        Like :meth:`getShadowLightExposureAtPoint`, but read from the shadow grid captured
        when the plant's leaf area last reached its seasonal maximum rather than from the
        current canopy. Through dormancy, when a deciduous plant has no leaves and the current
        exposure is 1 everywhere, this still gives the light each point stood in over the past
        summer. The "apple" and "apple_fruitingwall" library models use it to decide how many
        flowers each bud forms.
 
        Args:
            plant_id: ID of the plant
            position: Query position in world coordinates
 
        Returns:
            Local light exposure in [0, 1]; 1 before the plant's first season in leaf, or when
            the carbohydrate model is active
 
        Raises:
            ValueError: If ``plant_id`` is not a non-negative int or ``position`` is not a vec3
            PlantArchitectureError: If the plant does not exist
            RuntimeError: If the native library predates helios-core v1.3.93
        """
        plant_id = self._validatePlantIdentifier(plant_id)
        if not isinstance(position, vec3):
            raise ValueError(f"Position must be a vec3, got {type(position).__name__}")
        self._check_context_alive()
        try:
            return plantarch_wrapper.getSeasonPeakLightExposureAtPoint(
                self._plantarch_ptr, plant_id, (position.x, position.y, position.z))
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to get the season-peak light exposure of plant {plant_id}: {e}")
 
    def getPlantBuildParameters(self, plant_id: int) -> Dict[str, float]:
        """
        Get the build parameters a plant was built with.
 
        These are the ``build_parameters`` given to :meth:`buildPlantInstanceFromLibrary` or
        :meth:`buildPlantCanopyFromLibrary`. A plant keeps them for its life (some, such as the
        sorghum ``tiller_count``, are read as it grows), and they are saved and restored by
        :meth:`writePlantStructureXML` / :meth:`readPlantStructureXML`. Parameters that were not
        given are absent and take the model's default where they are read.
 
        Args:
            plant_id: ID of the plant
 
        Returns:
            Dict of build parameter names to values; empty for a plant not built from the
            library or built without parameters
 
        Raises:
            ValueError: If ``plant_id`` is not a non-negative int
            PlantArchitectureError: If the plant does not exist
            RuntimeError: If the native library predates helios-core v1.3.93
 
        Example:
            >>> plantarch.loadPlantModelFromLibrary("sorghum")
            >>> plant_id = plantarch.buildPlantInstanceFromLibrary(
            ...     vec3(0, 0, 0), 30.0, build_parameters={"tiller_count": 2})
            >>> plantarch.getPlantBuildParameters(plant_id)
            {'tiller_count': 2.0}
        """
        plant_id = self._validatePlantIdentifier(plant_id)
        self._check_context_alive()
        try:
            return plantarch_wrapper.getPlantBuildParameters(self._plantarch_ptr, plant_id)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to get the build parameters of plant {plant_id}: {e}")
 
    # ------------------------------------------------------------------
    # Plant-level queries
    # ------------------------------------------------------------------
 
    def getPlantName(self, plant_id: int) -> str:
        """
        Get the name of the plant model a plant was built from.
 
        For a plant built with :meth:`buildPlantInstanceFromLibrary` this is the label passed
        to :meth:`loadPlantModelFromLibrary` (e.g. ``"bean"``). A plant assembled by hand with
        :meth:`addPlantInstance` reports whatever name the native library assigned to it.
 
        Args:
            plant_id: ID of the plant instance
 
        Returns:
            Plant model name
 
        Raises:
            ValueError: If ``plant_id`` is not a non-negative int
            PlantArchitectureError: If the plant does not exist
            RuntimeError: If the native library predates this binding
 
        Example:
            >>> plantarch.loadPlantModelFromLibrary("bean")
            >>> plant_id = plantarch.buildPlantInstanceFromLibrary(vec3(0, 0, 0), 20)
            >>> plantarch.getPlantName(plant_id)
            'bean'
        """
        plant_id = self._validatePlantIdentifier(plant_id)
        self._check_context_alive()
        try:
            return plantarch_wrapper.getPlantName(self._plantarch_ptr, plant_id)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to get the name of plant {plant_id}: {e}")
 
    def determinePhenologyStage(self, plant_id: int) -> str:
        """
        Determine the phenological stage of a plant.
 
        The stage is decided in this order: ``"dormant"`` if every shoot is dormant;
        ``"reproductive"`` if the plant carries any flower or fruit; ``"senescent"`` if it is
        past 90% of the time from dormancy break to dormancy (only when a dormancy threshold
        is set, see :meth:`setPlantPhenologicalThresholds`); otherwise ``"vegetative"``.
 
        Args:
            plant_id: ID of the plant instance
 
        Returns:
            One of ``"dormant"``, ``"vegetative"``, ``"reproductive"`` or ``"senescent"``
 
        Raises:
            ValueError: If ``plant_id`` is not a non-negative int
            PlantArchitectureError: If the plant does not exist
            RuntimeError: If the native library predates this binding
 
        Example:
            >>> plantarch.determinePhenologyStage(plant_id)
            'vegetative'
        """
        plant_id = self._validatePlantIdentifier(plant_id)
        self._check_context_alive()
        try:
            return plantarch_wrapper.determinePhenologyStage(self._plantarch_ptr, plant_id)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to determine the phenology stage of plant {plant_id}: {e}")
 
    def getShootNodeCount(self, plant_id: int, shoot_id: int) -> int:
        """
        Get the current number of nodes (phytomers) on one shoot.
 
        Args:
            plant_id: ID of the plant instance
            shoot_id: Shoot index within the plant (see :meth:`getAllShootIDs`; 0 is the base stem)
 
        Returns:
            Number of nodes on the shoot
 
        Raises:
            ValueError: If ``plant_id`` or ``shoot_id`` is not a non-negative int
            PlantArchitectureError: If the plant does not exist or the shoot ID is out of range
            RuntimeError: If the native library predates this binding
 
        Example:
            >>> plantarch.getShootNodeCount(plant_id, 0)
            6
        """
        self._validateShootIdentifiers(plant_id, shoot_id)
        self._check_context_alive()
        try:
            return plantarch_wrapper.getShootNodeCount(self._plantarch_ptr, plant_id, shoot_id)
        except Exception as e:
            raise PlantArchitectureError(
                f"Failed to get the node count of shoot {shoot_id} on plant {plant_id}: {e}")
 
    def getPlantStemHeight(self, plant_id: int) -> float:
        """
        Get the height of a plant's main stem in meters.
 
        The vertical extent of the base stem shoot, extended by any shoot of the same rank
        appended to its tip. Unlike :meth:`getPlantHeight`, leaves, branches and
        inflorescences reaching above the stem are not counted.
 
        Args:
            plant_id: ID of the plant instance
 
        Returns:
            Vertical extent of the main stem (m)
 
        Raises:
            ValueError: If ``plant_id`` is not a non-negative int
            PlantArchitectureError: If the plant does not exist or has no stem geometry
            RuntimeError: If the native library predates this binding
 
        Example:
            >>> plantarch.getPlantStemHeight(plant_id)
            0.21
        """
        plant_id = self._validatePlantIdentifier(plant_id)
        self._check_context_alive()
        try:
            return plantarch_wrapper.getPlantStemHeight(self._plantarch_ptr, plant_id)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to get the stem height of plant {plant_id}: {e}")
 
    def getPlantBasePosition(self, plant_ids: Union[int, List[int]]) -> Union[vec3, List[vec3]]:
        """
        Get the base position of one plant or of several plants.
 
        For a plant with no shoots yet, this is the position at which its first shoot will be
        placed.
 
        Args:
            plant_ids: A single plant ID, or a sequence of plant IDs
 
        Returns:
            A vec3 for a single plant ID, or a list of vec3 (in the order given) for a sequence
 
        Raises:
            ValueError: If a plant ID is not a non-negative int or the sequence is empty
            PlantArchitectureError: If a plant does not exist
            RuntimeError: If the native library predates this binding
 
        Example:
            >>> plantarch.getPlantBasePosition(plant_id)
            vec3(0.0, 0.0, 0.0)
        """
        multi = not isinstance(plant_ids, int) or isinstance(plant_ids, bool)
        ids = self._validatePlantIdList(plant_ids) if multi else [self._validatePlantIdentifier(plant_ids)]
        self._check_context_alive()
        try:
            if multi:
                return [vec3(*p) for p in plantarch_wrapper.getPlantBasePositions(self._plantarch_ptr, ids)]
            return vec3(*plantarch_wrapper.getPlantBasePosition(self._plantarch_ptr, ids[0]))
        except Exception as e:
            raise PlantArchitectureError(f"Failed to get the base position of plant(s) {ids}: {e}")
 
    def setPlantBasePosition(self, plant_id: int, base_position: vec3) -> None:
        """
        Set the base position of a plant, moving the plant if it has already been built.
 
        For a plant with no shoots, this only stores the position, and the first shoot added
        with :meth:`addBaseStemShoot` is placed there. For a plant that already has shoots, the
        whole plant is translated by the difference between the new and old base position --
        its geometry, stored organ positions, per-plant attraction points and cached shading
        state -- and later growth continues from the moved position.
 
        Note:
            Do not also translate the plant's objects in the Context (e.g. with
            ``Context.translateObject``), or the plant will be moved twice. This cannot be
            called from inside a phytomer creation or callback function.
 
        Args:
            plant_id: ID of the plant instance
            base_position: New base position (vec3)
 
        Raises:
            ValueError: If ``plant_id`` is not a non-negative int or ``base_position`` is not a vec3
            PlantArchitectureError: If the plant does not exist
            RuntimeError: If the native library predates this binding
 
        Example:
            >>> plant_id = plantarch.addPlantInstance(vec3(0, 0, 0), 0)
            >>> plantarch.setPlantBasePosition(plant_id, vec3(1, 2, 0))
        """
        plant_id = self._validatePlantIdentifier(plant_id)
        if not isinstance(base_position, vec3):
            raise ValueError(f"Base position must be a vec3, got {type(base_position).__name__}")
        self._check_context_alive()
        try:
            plantarch_wrapper.setPlantBasePosition(
                self._plantarch_ptr, plant_id, (base_position.x, base_position.y, base_position.z))
        except Exception as e:
            raise PlantArchitectureError(f"Failed to set the base position of plant {plant_id}: {e}")
 
    def getPlantInternodeObjectIDs(self, plant_id: int, shoot_type_label: Optional[str] = None) -> List[int]:
        """
        Get the object IDs of a plant's internode (tube) objects.
 
        Each shoot is one tube object spanning all its internodes, so the list has one entry
        per shoot that has geometry. The structural counterpart to
        :meth:`getPlantLeafObjectIDs`.
 
        Args:
            plant_id: ID of the plant instance
            shoot_type_label: If given, only internodes of shoots of this type
                (e.g. ``"stem"``) are returned
 
        Returns:
            List of internode object IDs
 
        Raises:
            ValueError: If ``plant_id`` is not a non-negative int or ``shoot_type_label`` is
                not a non-empty str
            PlantArchitectureError: If the plant does not exist, or no shoot on it has the
                given shoot type label
            RuntimeError: If the native library predates this binding
 
        Example:
            >>> stem_ids = plantarch.getPlantInternodeObjectIDs(plant_id)
        """
        plant_id = self._validatePlantIdentifier(plant_id)
        if shoot_type_label is not None and (not isinstance(shoot_type_label, str) or not shoot_type_label):
            raise ValueError(
                f"Shoot type label must be a non-empty str, got {type(shoot_type_label).__name__}")
        self._check_context_alive()
        try:
            return plantarch_wrapper.getPlantInternodeObjectIDs(self._plantarch_ptr, plant_id, shoot_type_label)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to get internode object IDs for plant {plant_id}: {e}")
 
    def _plantAngleDistribution(self, fn_name: str, plant_ids, num_bins, normalize, what: str) -> List[float]:
        multi = not isinstance(plant_ids, int) or isinstance(plant_ids, bool)
        ids = self._validatePlantIdList(plant_ids) if multi else [self._validatePlantIdentifier(plant_ids)]
        if isinstance(num_bins, bool) or not isinstance(num_bins, int) or num_bins < 1:
            raise ValueError(f"num_bins must be a positive int, got {num_bins!r}")
        if not isinstance(normalize, bool):
            raise ValueError(f"normalize must be a bool, got {type(normalize).__name__}")
        self._check_context_alive()
        try:
            return getattr(plantarch_wrapper, fn_name)(self._plantarch_ptr, ids, num_bins, normalize)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to get the leaf {what} distribution of plant(s) {ids}: {e}")
 
    def getPlantLeafInclinationAngleDistribution(self, plant_ids: Union[int, List[int]], num_bins: int,
                                                 normalize: bool = True) -> List[float]:
        """
        Get the leaf-area-weighted leaf inclination angle distribution of one or more plants.
 
        Each leaf blade facet adds its area to the bin of its inclination (the angle between
        the facet normal and vertical, folded into 0-90 degrees). Petiolules are excluded.
        Several plants are pooled into one histogram.
 
        Args:
            plant_ids: A single plant ID, or a sequence of plant IDs to pool
            num_bins: Number of histogram bins, evenly spaced between 0 and 90 degrees
            normalize: If True (default), the bins sum to 1; otherwise they hold leaf area (m^2).
                A plant with no leaves gives all-zero bins either way.
 
        Returns:
            List of ``num_bins`` values
 
        Raises:
            ValueError: If a plant ID is invalid, the sequence is empty, ``num_bins`` is not a
                positive int, or ``normalize`` is not a bool
            PlantArchitectureError: If a plant does not exist
            RuntimeError: If the native library predates this binding
 
        Example:
            >>> plantarch.getPlantLeafInclinationAngleDistribution(plant_id, 9)
        """
        return self._plantAngleDistribution("getPlantLeafInclinationAngleDistribution", plant_ids,
                                            num_bins, normalize, "inclination")
 
    def getPlantLeafAzimuthAngleDistribution(self, plant_ids: Union[int, List[int]], num_bins: int,
                                             normalize: bool = True) -> List[float]:
        """
        Get the leaf-area-weighted leaf azimuth angle distribution of one or more plants.
 
        Each leaf blade facet adds its area to the bin of its normal's azimuth (0-360
        degrees). Petiolules are excluded. Several plants are pooled into one histogram.
 
        Args:
            plant_ids: A single plant ID, or a sequence of plant IDs to pool
            num_bins: Number of histogram bins, evenly spaced between 0 and 360 degrees
            normalize: If True (default), the bins sum to 1; otherwise they hold leaf area (m^2).
                A plant with no leaves gives all-zero bins either way.
 
        Returns:
            List of ``num_bins`` values
 
        Raises:
            ValueError: If a plant ID is invalid, the sequence is empty, ``num_bins`` is not a
                positive int, or ``normalize`` is not a bool
            PlantArchitectureError: If a plant does not exist
            RuntimeError: If the native library predates this binding
 
        Example:
            >>> plantarch.getPlantLeafAzimuthAngleDistribution([p1, p2], 12)
        """
        return self._plantAngleDistribution("getPlantLeafAzimuthAngleDistribution", plant_ids,
                                            num_bins, normalize, "azimuth")
 
    def resamplePhytomerParameters(self, phytomer_parameters: Union[dict, PhytomerParameters]
                                   ) -> Union[dict, PhytomerParameters]:
        """
        Draw one realization of a set of phytomer parameters.
 
        Mirrors the native ``PhytomerParameters::resample()``, which each phytomer calls
        once when it is created (helios-core 1.3.89+) to draw its own values of every
        distributed parameter. The draw uses the Context's random generator, so it follows
        ``Context.seedRandomGenerator()``. Every field with a distribution (uniform, normal,
        weibull, discrete values) comes back as a constant holding the value drawn for it;
        constant fields, and fields that are not random parameters, are returned unchanged
        and consume no random draws. The input is not modified.
 
        Args:
            phytomer_parameters: A :class:`pyhelios.plant_architecture_params.PhytomerParameters`
                or its dict form (e.g. ``getCurrentShootParameters(label)["phytomer_parameters"]``)
 
        Returns:
            The realization, of the same type as the input
 
        Raises:
            ValueError: If ``phytomer_parameters`` is not a dict or PhytomerParameters
            PlantArchitectureError: If the parameters cannot be parsed natively
            RuntimeError: If the native library predates helios-core v1.3.89
        """
        typed = isinstance(phytomer_parameters, PhytomerParameters)
        if typed:
            params_dict = phytomer_parameters.to_dict()
        elif isinstance(phytomer_parameters, dict):
            params_dict = phytomer_parameters
        else:
            raise ValueError(
                f"Phytomer parameters must be a dict or PhytomerParameters, got "
                f"{type(phytomer_parameters).__name__}")
        self._check_context_alive()
        try:
            result = plantarch_wrapper.resamplePhytomerParameters(self.context.context, params_dict)
        except Exception as e:
            raise PlantArchitectureError(f"Failed to resample phytomer parameters: {e}")
        return PhytomerParameters.from_dict(result) if typed else result
 
    @staticmethod
    def _validateStemFraction(stem_fraction) -> float:
        if isinstance(stem_fraction, bool) or not isinstance(stem_fraction, (int, float)) \
                or not 0.0 <= stem_fraction <= 1.0:
            raise ValueError(f"Stem fraction must be a number in [0, 1], got {stem_fraction!r}")
        return float(stem_fraction)
 
    @staticmethod
    def _validatePlantModelName(plant_model_name) -> None:
        if not isinstance(plant_model_name, str) or not plant_model_name:
            raise ValueError(
                f"Plant model name must be a non-empty str, got {type(plant_model_name).__name__}")
 
    @staticmethod
    def _validatePlantIdentifier(plant_id) -> int:
        """Reject a non-int or negative plant ID, returning it as a plain int."""
        if isinstance(plant_id, bool) or not isinstance(plant_id, int):
            raise ValueError(
                f"Plant ID must be a non-negative int, got {type(plant_id).__name__}")
        if plant_id < 0:
            raise ValueError("Plant ID must be non-negative")
        return int(plant_id)
 
    @classmethod
    def _validatePlantIdList(cls, plant_ids) -> List[int]:
        """Coerce a sequence of plant IDs, rejecting an empty or malformed one."""
        if isinstance(plant_ids, (str, bytes)) or not hasattr(plant_ids, '__iter__'):
            raise ValueError(
                f"Plant IDs must be an int or a sequence of ints, got "
                f"{type(plant_ids).__name__}")
        ids = [cls._validatePlantIdentifier(p) for p in plant_ids]
        if not ids:
            raise ValueError("Plant ID list must not be empty")
        return ids
 
    @staticmethod
    def _validateNodeIndex(node_index, name: str = "Node index") -> int:
        """Reject a non-int or negative phytomer index."""
        if isinstance(node_index, bool) or not isinstance(node_index, int):
            raise ValueError(
                f"{name} must be a non-negative int, got {type(node_index).__name__}")
        if node_index < 0:
            raise ValueError(f"{name} must be non-negative")
        return int(node_index)
 
    @classmethod
    def _validatePetioleIndex(cls, petiole_index, name: str = "Petiole index") -> int:
        """Reject a non-int or negative petiole/leaf index."""
        return cls._validateNodeIndex(petiole_index, name=name)
 
    @staticmethod
    def _validateScaleFactor(scale_factor, name: str = "Scale factor") -> float:
        """Reject a non-numeric or non-positive scale factor."""
        if isinstance(scale_factor, bool) or not isinstance(scale_factor, (int, float)):
            raise ValueError(
                f"{name} must be a positive number, got {type(scale_factor).__name__}")
        if not scale_factor > 0:
            raise ValueError(f"{name} must be positive, got {scale_factor}")
        return float(scale_factor)
 
    def is_available(self) -> bool:
        """
        Check if PlantArchitecture is available in current build.
 
        Returns:
            True if plugin is available, False otherwise
        """
        return is_plantarchitecture_available()
 
 
# Convenience function
def create_plant_architecture(context: Context) -> PlantArchitecture:
    """
    Create PlantArchitecture instance with context.
 
    Args:
        context: Helios Context
 
    Returns:
        PlantArchitecture instance
 
    Example:
        >>> context = Context()
        >>> plantarch = create_plant_architecture(context)
    """
    return PlantArchitecture(context)