Skip to content

Commit 3872c4e

Browse files
abhinavj98abhinavj98
committed
Updated document
1 parent 2f09745 commit 3872c4e

File tree

7 files changed

+417
-144
lines changed

7 files changed

+417
-144
lines changed

‎docs/make.bat‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
11+
set BUILDDIR=_build
12+
set SOURCEDIR=source
13+
14+
15+
if "%1" == "" goto help
16+
17+
%SPHINXBUILD% -M %1 "%SOURCEDIR%" "%BUILDDIR%" %SPHINXOPTS% %O%
18+
19+
popd
20+
goto end
21+
22+
:help
23+
%SPHINXBUILD% -M help "%SOURCEDIR%" "%BUILDDIR%" %SPHINXOPTS% %O%
24+
25+
popd
26+
:end

‎docs/source/files.rst‎

Lines changed: 57 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,51 +1,74 @@
11
Files and Directory Structure
22
=============================
33

4-
This document provides an overview of the important files and directories in the `lpy_treesim` project.
4+
The project is organized so that every custom tree lives wholly inside the
5+
`examples/` package, while the shared runtime sits at the repository root.
56

6-
Top-Level Files
7-
---------------
7+
Top-level Python modules
8+
------------------------
89

9-
- **`README.rst`**: The main README file for the project.
10-
- **`helper.py`**: Contains helper functions used by other scripts in the project.
11-
- **`stochastic_tree.py`**: The core module for generating stochastic trees.
12-
- **`.gitignore`**: A file that specifies which files and directories to ignore in a Git repository.
10+
``base_lpy.lpy``
11+
The canonical L-Py grammar. It loads extern variables that point to your
12+
prototype dictionary, simulation classes, and color manager, then drives the
13+
derivation/prune/tie loop.
1314

14-
`docs/`
15-
-------
15+
``simulation_base.py``
16+
Defines `SimulationConfig` and `TreeSimulationBase`. All simulation files in
17+
`examples/<TreeName>` inherit from these classes.
1618

17-
This directory contains the documentation for the project.
19+
``stochastic_tree.py``
20+
Hosts the `TreeBranch`, `BasicWood`, `Support`, and related data structures
21+
referenced by prototypes.
1822

19-
- **`Makefile`**: A makefile with commands to build the documentation.
20-
- **`source/`**: The source files for the documentation, written in reStructuredText.
21-
- **`conf.py`**: The configuration file for Sphinx, the documentation generator.
22-
- **`index.rst`**: The main entry point for the documentation.
23-
- **`installation.rst`**: Instructions on how to install the project.
24-
- **`usage.rst`**: An explanation of how to use the project.
25-
- **`files.rst`**: An overview of the important files and directories in the project.
26-
- **`resources.rst`**: A list of resources related to the project.
27-
- **`methods.rst`**: A description of the methods used in the project.
28-
- **`_static/`**: Static files, such as images and videos, that are used in the documentation.
23+
``color_manager.py``
24+
Implements `ColorManager`, which tracks per-instance color IDs and can dump
25+
them via `export_mapping` to JSON.
2926

30-
`examples/`
31-
-----------
27+
Documentation (`docs/`)
28+
-----------------------
3229

33-
This directory contains example `.lpy` files that demonstrate how to use `lpy_treesim`.
30+
Sphinx project containing the pages you are reading now. Run `make html` inside
31+
`lpy_treesim/docs` to build the site locally.
3432

35-
- **`legacy/`**: Older example files.
36-
- **`UFO/`**: Examples related to the UFO cherry tree architecture.
33+
Examples (`examples/`)
34+
----------------------
3735

38-
`modules_test/`
39-
---------------
36+
Each subfolder describes one tree training system. For `UFO` you will find:
4037

41-
This directory contains test files for the modules in the project. The files in this folder use classes and functions defined in `stochastic_tree.py` and can be a good example of how to use the `BasicWood`, `Wire`, and `Support` classes.
38+
``examples/UFO/UFO_prototypes.py``
39+
Prototype classes (`Trunk`, `Branch`, `Spur`, etc.) plus the
40+
`basicwood_prototypes` dictionary.
4241

43-
`other_files/`
44-
--------------
42+
``examples/UFO/UFO_simulation.py``
43+
`UFOSimulationConfig` and `UFOSimulation`, consumed by the base grammar.
4544

46-
These files may or may not work. They were used in previous iterations of `lpy_treesim` and are kept for reference.
45+
``examples/UFO/UFO.lpy``
46+
Optional GUI entry point if you want to run the species manually inside
47+
L-Py. Most development happens via `base_lpy.lpy`, but the standalone files
48+
are helpful for debugging.
4749

48-
`tree_generation/`
49-
------------------
50+
Add a new tree type by duplicating this directory and renaming files to match
51+
your `--tree_name` argument.
5052

51-
This directory contains scripts for generating and converting tree models.
53+
Tree generation utilities (`tree_generation/`)
54+
---------------------------------------------
55+
56+
``tree_generation/make_n_trees.py``
57+
CLI entry point that imports the base grammar, wires in your prototypes, and
58+
exports `.ply` meshes plus `{...}_colors.json` label maps. Accepts
59+
`--num_trees`, `--namespace`, `--rng-seed`, and `--output_dir`.
60+
61+
``tree_generation/helpers.py``
62+
Contains `write` (PLY serializer) and other small utilities referenced by
63+
the generator.
64+
65+
Supporting assets
66+
-----------------
67+
68+
``dataset/``
69+
Destination for generated `.ply` files by default. Subfolders such as
70+
`test_output/` are safe to delete or replace with your own datasets.
71+
72+
``media/`` and ``other_files/``
73+
Legacy L-Py grammars, renderings, and experiments kept for historical
74+
reference.

‎docs/source/index.rst‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,16 @@
66
Welcome to lpy_treesim's documentation!
77
=======================================
88

9+
`lpy_treesim` bundles a reusable L-Py grammar (`base_lpy.lpy`),
10+
prototype definitions, and automation scripts so you can describe a new tree
11+
architecture and batch-generate thousands of 3D assets. These docs walk
12+
through the entire workflow:
13+
14+
* set up the environment and dependencies,
15+
* design prototypes plus simulation parameters,
16+
* run the `make_n_trees.py` generator with deterministic naming, and
17+
* understand how the supporting modules fit together.
18+
919
.. toctree::
1020
:maxdepth: 2
1121
:caption: Contents:

‎docs/source/installation.rst‎

Lines changed: 36 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,65 +1,63 @@
11
Installation
2-
==============
2+
============
33

4-
This document provides instructions on how to install `lpy_treesim` and its dependencies.
4+
`lpy_treesim` ships as a Python package plus a collection of L-Py grammars, so
5+
you need both the OpenAlea/L-Py toolchain and the Python modules in this repo.
56

67
Prerequisites
78
-------------
89

9-
- **Python 3.x**: Make sure you have a working Python 3 installation.
10-
- **Conda**: `lpy_treesim` relies on the Conda package manager to handle its environment and dependencies. If you don't have Conda, you can install it by following the official documentation: https://docs.conda.io/projects/conda/en/latest/user-guide/install/
10+
- **Conda (recommended)** for installing `openalea.lpy` and PlantGL.
11+
- **Python 3.9+** for running the helper scripts.
12+
- A GPU is not required; everything runs on CPU.
1113

12-
Installing L-Py
13-
---------------
14+
Set up the L-Py environment
15+
---------------------------
1416

15-
`lpy_treesim` is built on top of L-Py, a Python-based L-system simulator. To install L-Py, follow these steps:
17+
1. Create a dedicated environment that contains L-Py and PlantGL:
1618

17-
1. **Create a Conda Environment**: Open your terminal and create a new Conda environment named `lpy`:
19+
.. code-block:: bash
1820
19-
.. code-block:: bash
21+
conda create -n lpy openalea.lpy plantgl python=3.9 -c fredboudon -c conda-forge
2022
21-
conda create -n lpy openalea.lpy -c fredboudon -c conda-forge
23+
2. Activate the environment any time you work on the project:
2224

23-
2. **Activate the Environment**: Activate the newly created environment:
25+
.. code-block:: bash
2426
25-
.. code-block:: bash
27+
conda activate lpy
2628
27-
conda activate lpy
29+
3. Validate the installation by launching the GUI (optional but handy for
30+
debugging grammars):
2831

29-
3. **Run L-Py**: You can now run L-Py to ensure it's installed correctly:
32+
.. code-block:: bash
3033
31-
.. code-block:: bash
34+
lpy
3235
33-
lpy
36+
Install `lpy_treesim`
37+
---------------------
3438

35-
For more detailed information and troubleshooting, refer to the official L-Py documentation: https://lpy.readthedocs.io/en/latest/user/installing.html
39+
With the environment active, clone and install the package in editable mode so
40+
that L-Py can import your custom prototypes:
3641

37-
Installing `lpy_treesim`
38-
------------------------
39-
40-
Once you have L-Py set up, you can install `lpy_treesim`:
41-
42-
1. **Clone the Repository**: Clone this repository to your local machine:
43-
44-
.. code-block:: bash
45-
46-
git clone https://github.com/your-username/lpy_treesim.git
47-
cd lpy_treesim
48-
49-
2. **Install Dependencies**: The required Python packages are listed in the `requirements.txt` file. You can install them using pip:
42+
.. code-block:: bash
5043
51-
.. code-block:: bash
44+
git clone https://github.com/OSUrobotics/lpy_treesim.git
45+
cd lpy_treesim
46+
pip install -e .
5247
53-
pip install -r requirements.txt
48+
Editable installs expose modules such as `lpy_treesim.ColorManager` and ensure
49+
`examples/<tree>` can import the shared base grammar.
5450

55-
Running the Examples
56-
--------------------
51+
Optional tooling
52+
-----------------
5753

58-
The `examples` directory contains several examples that demonstrate how to use `lpy_treesim`. To run an example, navigate to the `examples` directory and run the desired script:
54+
The repository includes a Sphinx documentation project. To build the docs
55+
locally install Sphinx, then run `make`:
5956

6057
.. code-block:: bash
6158
62-
cd examples
63-
python example_script.py
59+
cd lpy_treesim/lpy_treesim/docs
60+
pip install sphinx
61+
make html
6462
65-
Replace `example_script.py` with the actual name of the example you want to run.
63+
Open `_build/html/index.html` in a browser to preview the rendered docs.

‎docs/source/methods.rst‎

Lines changed: 60 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,74 @@
11
Methods
22
=======
33

4-
This document describes the methods and algorithms used in the `lpy_treesim` project.
4+
`lpy_treesim` marries biologically inspired L-systems with rule-based care
5+
operations (tying, pruning, support placement) so you can synthesize
6+
orchard-ready tree geometries. This page explains how the major pieces interact.
57

6-
L-System for Tree Generation
7-
----------------------------
8+
Prototype-driven L-System
9+
-------------------------
810

9-
`lpy_treesim` uses the L-Py language to define the growth rules of the trees. L-Py is a Python-based implementation of L-systems, which are a type of formal grammar that can be used to model the growth of plants and other biological systems.
11+
`base_lpy.lpy` is the only grammar we execute at runtime. Rather than handcode
12+
every rule, it reads extern variables that point to Python classes in
13+
`examples/<TreeName>`:
1014

11-
The L-system used in `lpy_treesim` is defined in the `.lpy` files in the `examples` directory. These files contain the axiom and production rules that determine the structure of the tree.
15+
``prototype_dict_path``
16+
Imports the shared `basicwood_prototypes` mapping. Each entry contains a
17+
`TreeBranch` subclass plus its `BasicWoodConfig`, which exposes stochastic
18+
bending, bud spacing, lengths, and colors.
1219

13-
- **Axiom**: The axiom is the initial state of the L-system. It is a string of symbols that represents the starting point of the tree.
14-
- **Production Rules**: The production rules are a set of rules that specify how the symbols in the L-system are replaced over time. Each rule consists of a predecessor and a successor. The predecessor is a symbol that is replaced by the successor.
20+
``trunk_class_path``
21+
The entry class that seeds the axiom. All other branches sprout from the
22+
prototypes configured on this trunk.
1523

16-
By iteratively applying the production rules to the axiom, the L-system generates a sequence of strings that represents the growth of the tree.
24+
``simulation_class_path`` / ``simulation_config_class_path``
25+
Provide training-system-specific behaviors (e.g., UFO trellis vs. Envy
26+
spindle). The config dataclass is serialized and handed to the runtime
27+
simulation via `TreeSimulationBase`.
1728

18-
Pruning and Tying Algorithms
19-
----------------------------
29+
During each derivation step the grammar delegates to your Python classes to
30+
decide when buds break, which prototype to spawn, and how to orient each new
31+
segment. Because everything happens inside Python, you can use NumPy, random
32+
sampling, and heuristics tailored to your target cultivar.
2033

21-
`lpy_treesim` includes algorithms for pruning and tying the branches of the tree. These algorithms are used to control the shape and size of the tree.
34+
Tying, pruning, and supports
35+
---------------------------
2236

23-
- **Pruning**: The pruning algorithm removes branches from the tree that are too long or that are growing in the wrong direction. This is done by defining a set of rules that specify which branches to remove.
24-
- **Tying**: The tying algorithm connects branches of the tree together. This is done by defining a set of rules that specify which branches to connect and how to connect them.
37+
The base simulation loop interleaves three routines:
2538

26-
The pruning and tying algorithms are implemented in the `stochastic_tree.py` module.
39+
1. **Derive**: expand the L-system string using the prototype logic.
40+
2. **Tie**: after a configurable number of iterations (`num_iteration_tie`), the
41+
simulation attaches branches to the virtual support wires generated by
42+
`TreeSimulationBase.generate_points()`.
43+
3. **Prune**: after `num_iteration_prune`, branches that exceed thresholds (age,
44+
curvature, or spacing) are removed. The decision functions live inside
45+
`stochastic_tree.py` and can be augmented via your prototypes.
2746

28-
API Reference
29-
-------------
47+
All three phases reuse the `ColorManager` so instance labels remain stable even
48+
after pruning removes geometry.
3049

31-
.. automodule:: stochastic_tree
32-
:members:
50+
Batch export pipeline
51+
---------------------
52+
53+
`tree_generation/make_n_trees.py` wraps the grammar in a CLI tool:
54+
55+
* Builds a fresh `Lsystem` object per tree and injects the extern dictionary.
56+
* Seeds Python's RNG per tree so stochastic decisions differ while still being
57+
reproducible when `--rng-seed` is provided.
58+
* Calls `sceneInterpretation` to convert the final string into a PlantGL scene.
59+
* Writes the mesh using `tree_generation.helpers.write`, which emits ASCII PLY
60+
with normals and color attributes.
61+
* Dumps `{namespace}_{tree_name}_{index:05d}_colors.json` containing the mapping
62+
from instance IDs to semantic roles (spur, branch, trunk, tie, etc.).
63+
64+
The naming scheme caps at 99,999 trees per run; start a new namespace if you
65+
need more.
66+
67+
Extending the system
68+
--------------------
69+
70+
To add a brand-new method (new pruning heuristic, new tie behavior), derive from
71+
the appropriate class in `simulation_base.py` or `stochastic_tree.py` and inject
72+
your class via the extern dictionary. Because all extern paths are strings,
73+
`make_n_trees.py` can consume any importable module without further code
74+
changes.

‎docs/source/resources.rst‎

Lines changed: 19 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,29 @@
11
Resources
22
=========
33

4-
This page provides a list of resources related to the `lpy_treesim` project.
4+
This section collects official links plus background material on L-systems and
5+
training systems referenced by `lpy_treesim`.
56

6-
Project Links
7+
Project links
78
-------------
89

9-
- **GitHub Repository**: `https://github.com/your-username/lpy_treesim <https://github.com/your-username/lpy_treesim>`_
10-
- **Documentation**: `https://lpy_treesim.readthedocs.io/en/latest/ <https://lpy_treesim.readthedocs.io/en/latest/>`_
10+
- **GitHub**: `https://github.com/OSUrobotics/lpy_treesim <https://github.com/OSUrobotics/lpy_treesim>`_
11+
- **Issue tracker**: Use the GitHub repo to report bugs or request new tree
12+
templates.
1113

12-
L-Py Resources
13-
--------------
14+
L-Py and Plant Modeling
15+
-----------------------
1416

15-
- **L-Py Documentation**: `https://lpy.readthedocs.io/en/latest/ <https://lpy.readthedocs.io/en/latest/>`_
16-
- **L-Py Training Material**: `https://github.com/fredboudon/lpy-training <https://github.com/fredboudon/lpy-training>`_
17-
- **L-Py Paper**: `https://example.com/lpy-paper <https://example.com/lpy-paper>`_ (Replace with the actual link to the L-Py paper)
17+
- **L-Py documentation**: `https://lpy.readthedocs.io/en/latest/ <https://lpy.readthedocs.io/en/latest/>`_
18+
- **OpenAlea/PlantGL**: `https://openalea.readthedocs.io/en/latest/ <https://openalea.readthedocs.io/en/latest/>`_
19+
- **L-Py training notebooks** (official tutorials):
20+
`https://github.com/fredboudon/lpy-training <https://github.com/fredboudon/lpy-training>`_
21+
- **Foundational paper**: Prusinkiewicz & Lindenmayer, *The Algorithmic Beauty
22+
of Plants*, for a deep dive into L-systems.
1823

19-
Other Resources
20-
---------------
24+
Supporting tooling
25+
------------------
2126

22-
- **Conda Documentation**: `https://docs.conda.io/en/latest/ <https://docs.conda.io/en/latest/>`_
23-
- **Sphinx Documentation**: `https://www.sphinx-doc.org/en/master/ <https://www.sphinx-doc.org/en/master/>`_
27+
- **Conda documentation**: `https://docs.conda.io/en/latest/ <https://docs.conda.io/en/latest/>`_
28+
- **Sphinx documentation**: `https://www.sphinx-doc.org/en/master/ <https://www.sphinx-doc.org/en/master/>`_
29+
- **PLY file format**: `http://paulbourke.net/dataformats/ply/ <http://paulbourke.net/dataformats/ply/>`_ (useful when post-processing meshes).

0 commit comments

Comments
 (0)