Metadata-Version: 2.4
Name: traitly
Version: 0.1.1
Summary: Computer vision toolkit for high-throughput fruit phenotyping.
Project-URL: Repository, https://github.com/mariameraz/traitly
Project-URL: Documentation, https://traitly.readthedocs.io/en/latest/
Project-URL: Issues, https://github.com/mariameraz/traitly/issues
Project-URL: Changelog, https://github.com/mariameraz/traitly/blob/main/CHANGELOG.md
Project-URL: Demo, https://huggingface.co/spaces/mariameraz/traitly
Author-email: Maria Alejandra Torres Meraz <ma.torresmeraz@gmail.com>, Hector Lopez Moreno <hectorlpzmno@gmail.com>
License: AGPL-3.0-or-later
License-File: LICENSE
Keywords: fruit-morphology,plant-breeding,plant-phenotyping
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.9
Requires-Dist: easyocr<2.0,>=1.7
Requires-Dist: matplotlib<4.0,>=3.7
Requires-Dist: numpy<3.0,>=1.24
Requires-Dist: opencv-contrib-python<5.0,>=4.8
Requires-Dist: pandas<4.0,>=2.0
Requires-Dist: psutil<8.0,>=5.9
Requires-Dist: rich-argparse>=1.0
Requires-Dist: scipy<2.0,>=1.10
Requires-Dist: tqdm<5.0,>=4.64
Requires-Dist: ultralytics<9.0,>=8.0
Provides-Extra: app
Requires-Dist: pymupdf<2.0,>=1.23; extra == 'app'
Requires-Dist: shiny<2.0,>=1.0; extra == 'app'
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Provides-Extra: pdf
Requires-Dist: pymupdf<2.0,>=1.23; extra == 'pdf'
Description-Content-Type: text/markdown

<div align="center">
<h1>Traitly</h1>

[![PyPI](https://img.shields.io/pypi/v/traitly?logo=pypi&logoColor=white)](https://pypi.org/project/traitly)
[![Python 3.9+](https://github.com/mariameraz/traitly/actions/workflows/python_compatibility.yml/badge.svg)](https://github.com/mariameraz/traitly/actions/workflows/python_compatibility.yml)
[![MultiOS](https://github.com/mariameraz/traitly/actions/workflows/pytest_multi_os.yml/badge.svg)](https://github.com/mariameraz/traitly/actions/workflows/pytest_multi_os.yml)
[![Testing](https://github.com/mariameraz/traitly/actions/workflows/pytest.yml/badge.svg?branch=main)](https://github.com/mariameraz/traitly/actions/workflows/pytest.yml)
[![Coverage](https://codecov.io/gh/mariameraz/traitly/branch/main/graph/badge.svg)](https://codecov.io/gh/mariameraz/traitly)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19447593.svg)](https://doi.org/10.5281/zenodo.19447593)
[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-green?logo=gnu&logoColor=white)](https://github.com/mariameraz/traitly/blob/main/LICENSE)


<a href="https://traitly.readthedocs.io/en/latest/">Documentation</a> ⋆
<a href="https://traitly.readthedocs.io/en/latest/installation/">Installation</a> ⋆
<a href="https://traitly.readthedocs.io/en/latest/user_guide/overview/">User Guide</a> ⋆
<a href="https://traitly.readthedocs.io/en/latest/tutorials/overview/">Tutorials</a>

</div>

<br>

Página disponible en: [![Spanish](https://img.shields.io/badge/Idioma-Espa%C3%B1ol-pink)](README_ES.md)


**Traitly** is an open-source Python tool for automated, high-throughput fruit phenotyping from digital images. Using computer vision methods, it quantifies morphological, symmetry, and color traits across both internal structures and the external appearance of the fruit.

It supports both single-image analysis and batch processing workflows, making it easy to handle large image datasets with just a few lines of code, which is especially useful in plant breeding programs and research.

</br>

### What can Traitly do?

Traitly processes fruit images to measure:

* **Fruit morphology**: Area, perimeter, circularity, dimensions, and aspect ratio
* **Locule anatomy**: Locule number, size distribution, and spatial arrangement
* **Pericarp structure**: Thickness, uniformity (CV), and surface irregularity (lobedness)
* **Color phenotypes**: Multi-channel analysis (RGB, HSV, Lab) across different fruit regions

</br>

## Publications & Presentations

Posters related to Traitly can be found in this folder:

- [Posters](https://drive.google.com/drive/folders/1AvlHWKcDvoE9m9QcmCJ5o-ma9W-LNQMe?usp=share_link) ★ˎˊ˗

These materials provide additional methodological details and results from research derived from our package.

</br>

## Usage

Traitly can be run in different ways:

| Environment                | Status         |
| -------------------------- | -------------- |
| Jupyter Notebook           | ✔ Available    |
| Command line (CLI)         | ✔ Available    |
| Web app (Shiny)            | ✔ Available    |

 ⤷ You can also try our [interactive demo](https://huggingface.co/spaces/mariameraz/traitly) onlineˎˊ˗

---

Below is a basic example of how to use **Traitly**.

### ⋆ Python usage

#### Internal fruit morphology analysis
```python
from traitly.fruit_phenotyping import FruitInternalAnalyzer

# Single image analysis
path = 'PATH/my_image.jpg'
analyzer = FruitInternalAnalyzer(path)  # Initialize the FruitInternalAnalyzer class
analyzer.load_image()                   # Read the image
analyzer.setup_measurements()           # Obtain label and reference size information
analyzer.generate_fruit_mask()          # Create a binary mask to segment fruits and locules
analyzer.detect_fruits()                # Filter detected fruits
analyzer.analyze_morphology()           # Run the morphology analysis
analyzer.analyze_color()                # Run the color analysis
analyzer.results.save_all()             # Save results (color and morphology .csv files and annotated image)
analyzer.save_parameters()              # Save session parameters as .txt and .json files

# Batch analysis
path = 'PATH/my_folder'
json = 'my_parameters.json'
analyzer = FruitInternalAnalyzer(path)
analyzer.analyze_folder(json_path = json)
```

#### External fruit morphology analysis
```python
from traitly.fruit_phenotyping import FruitExternalAnalyzer

# Single image analysis
path = 'PATH/my_image.jpg'
analyzer = FruitExternalAnalyzer(path)       # Initialize the FruitExternalAnalyzer class
analyzer.load_image()                        # Read the image
analyzer.setup_measurements()                # Obtain label and reference size information
analyzer.generate_fruit_mask()               # Create a binary mask to segment fruits
analyzer.detect_fruits()                     # Filter detected fruits
analyzer.analyze_morphology()                # Run the morphology analysis
analyzer.analyze_color(color_channel='RGB')  # Extract mean RGB channel values for each fruit
analyzer.results.save_all()                  # Save results (color and morphology .csv files and annotated image)
analyzer.save_parameters()                   # Save session parameters as .txt and .json files

# Batch analysis
path = 'PATH/my_folder'
json = 'my_parameters.json'
analyzer = FruitExternalAnalyzer(path)
analyzer.analyze_folder(json_path = json)
```

### ⋆ Command-line usage

```bash
# Run the web app
traitly-app

# Internal morphology analysis (single image or folder)
traitly --fruit_internal -i tests/sample_data/
traitly --fruit_internal -i tests/sample_data/ -o results/ --num_cores 4
traitly --fruit_internal -i tests/sample_data/ --json config.json

# External morphology analysis (single image or folder)
traitly --fruit_external -i tests/sample_data/
traitly --fruit_external -i tests/sample_data/ -o results/ --json config.json --num_cores 4
```

</br>

For more detailed examples, [check our tutorials](https://traitly.readthedocs.io/en/latest/tutorials/overview/) ᯓ★

</br>

## Citation

We are working on a manuscript describing this software and its applications, expected to be submitted in **Spring–Summer 2026**. In the meantime, if you use Traitly in your research, please cite it as:

> Torres-Meraz, M. A., Lopez-Moreno, H., & Zalapa, J. (2026). Traitly: A Python Toolkit for High-Throughput Fruit Phenotyping. Zenodo. https://doi.org/10.5281/zenodo.18738366

</br>


## Contact

For questions or comments about the project, feel free to reach out to:

* [ma.meraz@proton.me](mailto:ma.meraz@proton.me)
* [torresmeraz@wisc.edu](mailto:torresmeraz@wisc.edu)

We are open to collaborations, including adding new traits, and creating tutorials or workflows for specific crops or plant tissues.

<br>
    
## Contributions

Inspired by [All Contributors](https://allcontributors.org/), we recognize all kinds of contributions, not just code:

<!-- CONTRIBUTORS-START -->
| Contributor | Role |
|-------------|------|
| [<img src="https://github.com/mariameraz.png" width="44" height="44" valign="middle">&nbsp;María Meraz](https://github.com/mariameraz) | 💻 📆 🚧 📓 ✅ 🐛 📖 ⚠️ 🤔 🌍 |
| [<img src="https://github.com/hector-LM.png" width="44" height="44" valign="middle">&nbsp;Héctor López](https://github.com/hector-LM) | 📖 📓 ✅ 🤔 🐛 🔣 🌍 |
| Juan Zalapa | 🔣 |
<!-- CONTRIBUTORS-END -->

<br> 
    
## Acknowledgements ♡

We thank the developers of [OpenCV](https://opencv.org/), [Ultralytics](https://github.com/ultralytics/ultralytics), [EasyOCR](https://github.com/JaidedAI/EasyOCR), [NumPy](https://numpy.org/), [Pandas](https://pandas.pydata.org/), [Matplotlib](https://matplotlib.org/), and [Shiny](https://shiny.posit.co/py/), as well as all  open-source libraries that made this project possible.
