PyRootSim

Synthetic Root System Architecture Simulator

PyRootSim is an open-source Python package that generates annotated synthetic datasets of Arabidopsis thaliana root system architectures — binary masks, per-root label images, and skeleton data — with configurable discontinuity injection (controlled occlusions producing 2, 3, or 4 connected components with OBB annotations). Ready for machine learning tasks such as root discontinuity detection, discontinuity inpainting, instance segmentation, and root graph classification.

Default configurations approximate Arabidopsis thaliana morphology based on visual references. They have not been validated by a plant scientist and should not be treated as biologically calibrated.

Installation

pip install pyrootsim

To run the tutorial notebook:

pip install pyrootsim[tutorial]

Quick Start

from pyrootsim.roots.primary import generate_single_primary_root
from pyrootsim.roots.lateral import generate_lateral_root_inline

# Generate a single primary root
primary = generate_single_primary_root("05_Medium_Smooth_Snake", root_id=0, seed=42)

# Attach lateral roots
composite = generate_lateral_root_inline(
    primary_data=primary,
    config_name="05_Medium_Smooth_Snake",
    lateral_mode_name="E_medium_small",
    seed=42,
)

print(f"Composite mask shape: {composite['combined_mask'].shape}")
print(f"Lateral count: {composite['metadata']['num_laterals']}")

Pipeline Overview

PyRootSim's full pipeline has six stages:

Full Pipeline Example

from pyrootsim.dataset.orchestrator import generate_rsa_dataset
from pyrootsim.dish.composer import generate_all_dishes
from pyrootsim.dataset.splitter import split_clean_vs_occluded, split_train_val_test
from pyrootsim.discontinuity.orchestrator import run_occlusion_pipeline

# 1. Generate individual roots (40 per config × mode cell)
generate_rsa_dataset(output_dir="RSA_dataset", num_per_cell=40, base_seed=42)

# 2. Compose petri dishes
generate_all_dishes(rsa_input_dir="RSA_dataset", output_dir="petri_dishes",
                    num_dishes=800, base_seed=42)

# 3. Split clean vs. occluded
split_clean_vs_occluded(input_dir="petri_dishes", occluded_dir="to_occlude",
                        clean_dir="clean", num_clean=150, seed=42)

# 4. Apply discontinuities
run_occlusion_pipeline(petri_dish_dir="to_occlude",
                       output_dir="occluded", base_seed=42)

# 5. Final train/val/test split
split_train_val_test(clean_csv_path="clean/clean_split_metadata.csv",
                     occluded_csv_path="to_occlude/occluded_split_metadata.csv",
                     clean_img_dir="clean", occluded_img_dir="occluded",
                     output_base_dir="final_dataset", seed=42)

See examples/tutorial.ipynb for a complete walkthrough with visualisations.

Root Configurations

PyRootSim ships with 12 primary root configurations across 4 length categories:

Each category has up to 12 lateral branching modes (few/medium/many × small/horizontal/arched/mixed), plus a "no laterals" mode for short roots.

Outputs

Each processed dish produces:

• *_mask.png — Binary root mask
• *_labels.png — Per-root label image (plant_id × 100 + lateral_id)
• *_overlap.png — Pixels shared by multiple roots
• *_metadata.json — Generation parameters
• *_mask_occluded.png — Mask after discontinuity injection
• *_obb_all.txt — OBB annotations in YOLOv8 format (class 0 = 2cc, 1 = 3cc, 2 = 4cc)
• *_occlusion_meta.json — Per-occlusion details

License

MIT License. See LICENSE for details.

Citation

If you use PyRootSim in your research, please cite:

@software{pyrootsim,
  author = {Mansilha, Francisco Ribeiro},
  title = {PyRootSim: Synthetic Root System Architecture Simulator},
  year = {2026},
  url = {https://github.com/FranciscoRMansilha/PyRootSim},
}

Dedicated to my grandfather, António Ribeiro.