Metadata-Version: 2.4
Name: deadleaves
Version: 0.3.0
Summary: A package to generate dead leaves images.
Author-email: Lynn Schmittwilken <lynn.schmittwilken@tu-darmstadt.de>, Swantje Mahncke <swantje.mahncke@tu-darmstadt.de>
Maintainer-email: Lynn Schmittwilken <lynn.schmittwilken@tu-darmstadt.de>, Swantje Mahncke <swantje.mahncke@tu-darmstadt.de>
License-Expression: EUPL-1.2
Project-URL: Repository, https://github.com/ag-perception-wallis-lab/deadleaves.git
Project-URL: Issues, https://github.com/ag-perception-wallis-lab/deadleaves/issues
Project-URL: Documentation, https://deadleaves.readthedocs.io/
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: GPU :: NVIDIA CUDA
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENCE.txt
Requires-Dist: pandas>=2.3.2
Requires-Dist: torch>=2.8.0
Requires-Dist: torchquad>=0.5.0
Requires-Dist: torchvision>=0.23.0
Dynamic: license-file

# DeadLeaves

<p align=center>
An open-source Python package for creating dead leaves images in a systematic, yet flexible way.
</p>

[![Tests](https://github.com/ag-perception-wallis-lab/deadleaves/actions/workflows/test.yml/badge.svg)](https://github.com/ag-perception-wallis-lab/deadleaves/actions/workflows/test.yml)
[![Py versions](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![Documentation Status](https://readthedocs.org/projects/deadleaves/badge/?version=latest)](https://deadleaves.readthedocs.io/en/latest/?badge=latest)

<p align=center>
<img src=docs/_static/logo_dead_leaves.png width=300>
</p>


## Core functionalities

- generating dead leaves images with properties (e.g. sizes, orientations, colors) drawn from a wide range of distributions (e.g. uniform, normal, Poisson, power-law, constant) or directly from an image.
- picking from various leaf shapes (circles, ellipsoids, rectangles, regular polygons).
- sampling in different color spaces (RGB, HSV, Gray-scale).
- applying different noise or image textures, either to the entire image or per-leaf.
- varying the image area covered by leaves, i.e. choosing between sparser or denser sampling and position mask.
- creating arbitrarily complex leaf configurations by adding dependencies between leaf features (e.g. space-dependent color gradients).

![](docs/_static/figures/examples.png)

## Installation

You may install `deadleaves` from PyPI using `pip`:

```
pip install deadleaves
```

OR (for developers), install from source:

1. Clone the repository from GitHub:
```
git clone git@github.com:ag-perception-wallis-lab/deadleaves.git
```
2. Install `deadleaves` to your local python library using pip, by running from the top-level directory:
```
pip install .
```
To install in developer/editable mode run `pip install -e .` at the root directory. 
This makes changes to files immediately usable, rather than having to reinstall the package after every change.


## Dependencies

We recommend using a Python version `3.12` or newer.
The dependencies should be automatically installed (at least using `pip`). `deadleaves`s required dependencies are: 

- [PyTorch](https://pytorch.org/)
- [Torchquad](https://torchquad.readthedocs.io/en/main/)
- [Torchvision](https://docs.pytorch.org/vision/stable/index.html)
- [Pandas](https://pandas.pydata.org/)
