# PhenoAI: A deep learning Python framework to process close-range time-lapse PhenoCam data
<div align="center">
**Advanced Deep Learning Framework for Automated Phenological Analysis of Close-Range Time-Lapse PhenoCam Data**
</div>
<div align="center">
<img src="https://raw.githubusercontent.com/kharesiddhartha/phenoAI/main/assets/Graphical_Abstract_updated.jpg" alt="PhenoAI Graphical Abstract" width="70%" />
</div>
## 🌿 Overview
PhenoAI is a deep learning framework designed to automate the processing chain of phenological analysis of vegetation from close-range time-lapse PhenoCam data. This framework implements several techniques to provide comprehensive vegetation monitoring, segmentation, and temporal analysis capabilities.
> **Research Publication**: This work is part of the research paper:
> **"PhenoAI: A deep learning Python framework to process close-range time-lapse PhenoCam data"**
> *by Akash Kumar, Siddhartha Khare, and Sergio Rossi*
> Published in **Ecological Informatics, 2025**
### 🎯 Key Features
- **🔬 Advanced Image Quality Control**: Automated detection and filtering of low-quality images
- **🌱 Vegetation Segmentation**: Deep learning-powered vegetation extraction using semantic segmentation
- **📊 ROI Analysis**: K-means clustering-based Region of Interest (ROI) generation and analysis
- **📈 Vegetation Indices**: Comprehensive calculation of multiple vegetation indices (GCC, BCC, VCI, etc.)
- **🖥️ Professional GUI**: Advanced parameter tuning interface with real-time preview
- **⚡ Batch Processing**: Efficient processing of large-scale time-lapse datasets
- **📋 Interactive CLI**: User-friendly command-line interface with guided workflows
## 🚀 Quick Start
### Installation
```bash
# Install from PyPI (recommended)
pip install phenoai-package
# Or install with TensorFlow support
pip install phenoai-package[tensorflow]
# Or install all optional dependencies
pip install phenoai-package[all]
```
**📦 Model File Download:**
Due to PyPI size limitations, the pre-trained model (355MB) is not included in the package. Download it separately:
- **GitHub Release**: Download `Basic_Vegetation_Model.h5` from the latest release
- **Direct Download**: Available in the GitHub repository under `/Model/` directory
- **Alternative**: The framework will prompt you to download the model on first use
### Alternative Installation Methods
```bash
# From GitHub releases (if PyPI is not available)
pip install https://github.com/kharesiddhartha/phenoAI/releases/download/v1.2.0/phenoai-1.2.0-py3-none-any.whl
# For development
git clone https://github.com/kharesiddhartha/phenoAI.git
cd phenoAI
pip install -e .
```
### Basic Usage
```bash
# Launch interactive mode (recommended for beginners)
python -m phenoAI.cli --interactive
# Or if installed globally
phenoai --interactive
# Direct usage with parameters
python -m phenoAI.cli --input ./images --output ./results
```
## 📋 Detailed Usage Guide
### 1. Interactive Command Line Interface
The easiest way to get started is using the interactive CLI:
```bash
python -m phenoAI.cli --interactive
```
This will present you with a menu-driven interface:
```
🌿 PhenoAI v1.2.0 - Phenological Analysis Framework
📚 Advanced Deep Learning for Close-Range PhenoCam Data Analysis
Select workflow:
1. 🔍 Image Quality Control
2. 🌱 Vegetation Segmentation
3. 📊 ROI Generation and Analysis
4. 📈 Vegetation Index Calculation
5. 🎯 Complete Workflow (All Steps)
6. 🖥️ Parameter Tuning GUI
7. ❌ Exit
Enter your choice (1-7):
```
### 2. Step-by-Step Workflow
#### Step 1: Image Quality Control
```python
from phenoAI import PhenoAI
# Initialize framework
analyzer = PhenoAI()
# Set input directory containing your time-lapse images
analyzer.input_dir = "path/to/your/images"
# Run quality control
quality_results = analyzer.step1_image_quality_control()
# Results will be saved to:
# - Output/01_processing/high_quality_images/
# - Output/02_low_quality_images/
```
**Features:**
- Automated blur detection using Laplacian variance
- Brightness and contrast analysis
- Noise level assessment
- Histogram-based quality metrics
#### Step 2: Vegetation Segmentation
```python
# Run vegetation segmentation on quality-filtered images
segmentation_results = analyzer.step2_vegetation_segmentation()
# Results include:
# - Vegetation masks (binary)
# - Vegetation extraction (RGB)
# - Segmentation metrics and confidence scores
```
**Deep Learning Model:**
- Uses advanced semantic segmentation (DeepLabV3+ architecture)
- Pre-trained on diverse vegetation datasets
- Supports multiple vegetation types (grass, crops, trees, etc.)
- Confidence-based result filtering
#### Step 3: ROI Generation and Analysis
```python
# Generate ROIs using K-means clustering on vegetation areas
roi_results = analyzer.step3_roi_generation()
# Interactive ROI preview with professional GUI
analyzer.display_roi_preview_popup(segmentation_results)
# Select specific ROIs for analysis
analyzer.selected_rois = [0, 2, 4, 6] # or use 'all'
```
**ROI Features:**
- K-means clustering on vegetation pixels
- Polygon-based ROI boundaries
- Interactive preview with colorful cluster visualization
- Customizable ROI selection
#### Step 4: Vegetation Index Calculation
```python
# Calculate comprehensive vegetation indices
vi_results = analyzer.step4_vegetation_indices()
# Available indices:
# - GCC (Green Chromatic Coordinate)
# - BCC (Blue Chromatic Coordinate)
# - RCC (Red Chromatic Coordinate)
# - ExG (Excess Green)
# - VCI (Vegetation Contrast Index)
```
### 3. Advanced Parameter Tuning
Launch the professional GUI for parameter optimization:
```python
from phenoAI.gui import run_parameter_tuning
# Launch parameter tuning interface
run_parameter_tuning()
```
**GUI Features:**
- Real-time parameter adjustment with live preview
- 5 sample images per filter type
- Instant detection status feedback
- Professional Tkinter interface
- Save/load parameter configurations
### 4. Batch Processing
```python
# Process multiple directories
import os
from phenoAI import PhenoAI
directories = [
"dataset1/time_series_1/",
"dataset1/time_series_2/",
"dataset2/wheat_2024/"
]
for directory in directories:
analyzer = PhenoAI()
analyzer.input_dir = directory
analyzer.output_dir = f"results/{os.path.basename(directory)}"
# Run complete workflow
analyzer.run_full_workflow()
```
## 🛠️ Advanced Configuration
### Custom Model Integration
```python
# Use custom segmentation model
analyzer = PhenoAI()
analyzer.segmentation_model_path = "path/to/your/custom_model.h5"
# Set custom vegetation labels
analyzer.selected_vegetation_label = "crop" # or "grass", "tree", etc.
```
### ROI Configuration
```python
# Customize ROI generation parameters
roi_params = {
"n_clusters": 8, # Number of K-means clusters
"min_roi_size": 100, # Minimum ROI size in pixels
"max_roi_size": 5000, # Maximum ROI size in pixels
"roi_shape": "polygon" # ROI shape type
}
analyzer.set_roi_parameters(roi_params)
```
### Quality Control Thresholds
```python
# Adjust quality control parameters
quality_params = {
"blur_threshold": 100.0, # Laplacian variance threshold
"brightness_min": 50, # Minimum brightness
"brightness_max": 200, # Maximum brightness
"contrast_threshold": 30 # Minimum contrast
}
analyzer.set_quality_parameters(quality_params)
```
## 📊 Output Structure
PhenoAI generates a comprehensive output directory structure:
```
Output/
├── 01_processing/
│ ├── high_quality_images/ # Quality-filtered images
│ └── processing_log.json # Processing metadata
├── 02_low_quality_images/ # Rejected images with reasons
├── 03_segmentation_outputs/ # Vegetation masks and extractions
│ ├── masks/ # Binary vegetation masks
│ ├── extractions/ # RGB vegetation extractions
│ └── metrics/ # Segmentation confidence scores
├── 04_roi_analysis/ # ROI results and visualizations
│ ├── roi_boundaries/ # ROI polygon coordinates
│ ├── roi_previews/ # Visual ROI overlays
│ └── cluster_analysis/ # K-means clustering results
├── 05_vegetation_indices/ # Calculated indices
│ ├── gcc_results/ # GCC time series
│ ├── exg_results/ # ExG time series
│ └── comprehensive_indices/ # All indices combined
└── reports/
├── summary_report.html # Comprehensive analysis report
├── quality_metrics.csv # Quality control statistics
├── segmentation_metrics.csv # Segmentation performance
└── temporal_analysis.csv # Time-series vegetation indices
```
## 🧪 Example Workflows
### Workflow 1: Basic Vegetation Monitoring
```python
from phenoAI import PhenoAI
# Initialize analyzer
analyzer = PhenoAI()
analyzer.input_dir = "wheat_field_2024/"
# Run complete automated workflow
results = analyzer.run_full_workflow()
# Access results
print(f"Processed {len(results['high_quality_images'])} images")
print(f"Generated {len(results['rois'])} ROIs")
print(f"GCC temporal trend: {results['vegetation_indices']['gcc_trend']}")
```
### Workflow 2: Custom ROI Analysis
```python
# Step-by-step processing with custom ROI selection
analyzer = PhenoAI()
analyzer.input_dir = "crop_monitoring/"
# Quality control
quality_results = analyzer.step1_image_quality_control()
# Vegetation segmentation
seg_results = analyzer.step2_vegetation_segmentation(quality_results)
# Generate and preview ROIs
analyzer.step3_roi_generation(seg_results)
analyzer.display_roi_preview_popup(seg_results)
# Manual ROI selection
analyzer.selected_rois = [1, 3, 5, 7, 9] # Select specific ROIs
# Calculate indices for selected ROIs only
vi_results = analyzer.step4_vegetation_indices(roi_subset=analyzer.selected_rois)
```
### Workflow 3: Parameter Optimization
```python
# Launch GUI for parameter tuning
from phenoAI.gui import run_parameter_tuning
# Interactive parameter optimization
run_parameter_tuning()
# Apply optimized parameters
analyzer = PhenoAI()
analyzer.load_parameters("optimized_params.json")
analyzer.run_full_workflow()
```
## 🔧 Troubleshooting
### Common Issues and Solutions
#### 1. Model Loading Issues
```python
# If segmentation model fails to load
analyzer = PhenoAI()
analyzer.download_pretrained_model() # Download latest model
analyzer.segmentation_model_path = "Model/Basic_Vegetation_Model.h5"
```
#### 2. Memory Issues with Large Datasets
```python
# Process in smaller batches
analyzer.set_batch_size(32) # Reduce batch size
analyzer.enable_memory_optimization(True)
```
#### 3. GUI Issues
```python
# If GUI fails to launch
import tkinter as tk
try:
root = tk.Tk()
root.destroy()
print("✅ Tkinter available")
except:
print("❌ Tkinter not available - install tkinter package")
```
### Performance Optimization
```python
# Enable GPU acceleration (if available)
analyzer.enable_gpu(True)
# Parallel processing
analyzer.set_num_workers(4) # Adjust based on CPU cores
# Memory-efficient processing
analyzer.enable_lazy_loading(True)
```
## 📚 API Reference
### Core Classes
#### `PhenoAI`
Main analysis framework class.
**Methods:**
- `step1_image_quality_control()` - Image quality filtering
- `step2_vegetation_segmentation()` - Deep learning segmentation
- `step3_roi_generation()` - ROI clustering and generation
- `step4_vegetation_indices()` - Vegetation index calculation
- `run_full_workflow()` - Complete automated processing
#### `ParameterTuningGUI`
Advanced parameter optimization interface.
**Features:**
- Real-time parameter adjustment
- Multi-image preview
- Parameter persistence
- Export/import configurations
### Utility Functions
```python
from phenoAI.utils import (
calculate_vegetation_index,
apply_quality_filters,
generate_roi_polygons,
create_temporal_plots
)
# Calculate custom vegetation index
custom_vi = calculate_vegetation_index(
image_path="sample.jpg",
index_type="GCC",
roi_coordinates=[(100, 100), (200, 200)]
)
```
## 🤝 Contributing
We welcome contributions to PhenoAI! Please follow these guidelines:
1. **Fork the repository** and create a feature branch
2. **Follow PEP 8** coding standards
3. **Add comprehensive tests** for new features
4. **Update documentation** for API changes
5. **Submit a pull request** with detailed description
### Development Setup
```bash
# Clone for development
git clone https://github.com/your-username/phenoAI.git
cd phenoAI
# Create virtual environment
python -m venv phenoai_dev
source phenoai_dev/bin/activate # On Windows: phenoai_dev\Scripts\activate
# Install in development mode
pip install -e .[dev]
# Run tests
python -m pytest tests/
```
## 📄 Citation
If you use PhenoAI in your research, please cite our paper:
```APA
Kumar, A., Khare, S., & Rossi, S. (2025). PhenoAI: A deep learning Python framework to process close-range time-lapse PhenoCam data. Ecological Informatics, 88, 103134. https://doi.org/10.1016/j.ecoinf.2025.103134
```bibtex
@article{KUMAR2025103134,
title = {PhenoAI: A deep learning Python framework to process close-range time-lapse PhenoCam data},
journal = {Ecological Informatics},
volume = {88},
pages = {103134},
year = {2025},
issn = {1574-9541},
doi = {https://doi.org/10.1016/j.ecoinf.2025.103134},
url = {https://www.sciencedirect.com/science/article/pii/S1574954125001438},
author = {Akash Kumar and Siddhartha Khare and Sergio Rossi},
keywords = {Close-range Remote Sensing, GCC, Forest Phenology, PhenoCam, Python, Deep Learning}
}
```
## 📞 Support & Contact
- **Issues**: [GitHub Issues](https://github.com/kharesiddhartha/phenoAI/issues)
- **Discussions**: [GitHub Discussions](https://github.com/kharesiddhartha/phenoAI/discussions)
- **Email**: [akash_k@ce.iitr.ac.in](mailto:akash_k@ce.iitr.ac.in), [siddhartha.khare@ce.iitr.ac.in](mailto:siddhartha.khare@ce.iitr.ac.in)
## 📋 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- Deep learning models based on DeepLabV3+ architecture
- Vegetation index calculations following established remote sensing protocols
- GUI framework built with Python Tkinter
- Segmentation pipeline inspired by computer vision best practices
---
<div align="center">
**PhenoAI v1.2.0** - Advancing Phenological Research with Deep Learning
*Developed by Akash Kumar, Siddhartha Khare and Sergio Rossi | Published in Ecological Informatics 2025*
[](https://github.com/kharesiddhartha/phenoAI)
[](https://github.com/kharesiddhartha/phenoAI/fork)
</div>
Raw data
{
"_id": null,
"home_page": null,
"name": "phenoai-package",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "phenology, computer vision, image analysis, vegetation indices, remote sensing",
"author": null,
"author_email": "Akash Kumar <akash_k@ce.iitr.ac.in>, Siddhartha Khare <siddhartha.khare@ce.iitr.ac.in>, Sergio Rossi <sergio.rossi@uqac.ca>",
"download_url": "https://files.pythonhosted.org/packages/a9/38/1d3e2ea9bcb2539096c7e5fb0494fee80b4ec1ef81cacf42c5c569749770/phenoai_package-1.2.1.post1.tar.gz",
"platform": "any",
"description": "# PhenoAI: A deep learning Python framework to process close-range time-lapse PhenoCam data\r\n\r\n<div align=\"center\">\r\n\r\n\r\n\r\n\r\n\r\n\r\n**Advanced Deep Learning Framework for Automated Phenological Analysis of Close-Range Time-Lapse PhenoCam Data**\r\n\r\n</div>\r\n\r\n<div align=\"center\">\r\n <img src=\"https://raw.githubusercontent.com/kharesiddhartha/phenoAI/main/assets/Graphical_Abstract_updated.jpg\" alt=\"PhenoAI Graphical Abstract\" width=\"70%\" />\r\n</div>\r\n\r\n## \ud83c\udf3f Overview\r\n\r\nPhenoAI is a deep learning framework designed to automate the processing chain of phenological analysis of vegetation from close-range time-lapse PhenoCam data. This framework implements several techniques to provide comprehensive vegetation monitoring, segmentation, and temporal analysis capabilities.\r\n\r\n> **Research Publication**: This work is part of the research paper: \r\n> **\"PhenoAI: A deep learning Python framework to process close-range time-lapse PhenoCam data\"** \r\n> *by Akash Kumar, Siddhartha Khare, and Sergio Rossi* \r\n> Published in **Ecological Informatics, 2025**\r\n\r\n### \ud83c\udfaf Key Features\r\n\r\n- **\ud83d\udd2c Advanced Image Quality Control**: Automated detection and filtering of low-quality images\r\n- **\ud83c\udf31 Vegetation Segmentation**: Deep learning-powered vegetation extraction using semantic segmentation\r\n- **\ud83d\udcca ROI Analysis**: K-means clustering-based Region of Interest (ROI) generation and analysis\r\n- **\ud83d\udcc8 Vegetation Indices**: Comprehensive calculation of multiple vegetation indices (GCC, BCC, VCI, etc.)\r\n- **\ud83d\udda5\ufe0f Professional GUI**: Advanced parameter tuning interface with real-time preview\r\n- **\u26a1 Batch Processing**: Efficient processing of large-scale time-lapse datasets\r\n- **\ud83d\udccb Interactive CLI**: User-friendly command-line interface with guided workflows\r\n\r\n## \ud83d\ude80 Quick Start\r\n\r\n### Installation\r\n\r\n```bash\r\n# Install from PyPI (recommended)\r\npip install phenoai-package\r\n\r\n# Or install with TensorFlow support\r\npip install phenoai-package[tensorflow]\r\n\r\n# Or install all optional dependencies\r\npip install phenoai-package[all]\r\n```\r\n\r\n**\ud83d\udce6 Model File Download:**\r\nDue to PyPI size limitations, the pre-trained model (355MB) is not included in the package. Download it separately:\r\n- **GitHub Release**: Download `Basic_Vegetation_Model.h5` from the latest release\r\n- **Direct Download**: Available in the GitHub repository under `/Model/` directory\r\n- **Alternative**: The framework will prompt you to download the model on first use\r\n\r\n### Alternative Installation Methods\r\n\r\n```bash\r\n# From GitHub releases (if PyPI is not available)\r\npip install https://github.com/kharesiddhartha/phenoAI/releases/download/v1.2.0/phenoai-1.2.0-py3-none-any.whl\r\n\r\n# For development\r\ngit clone https://github.com/kharesiddhartha/phenoAI.git\r\ncd phenoAI\r\npip install -e .\r\n```\r\n\r\n### Basic Usage\r\n\r\n```bash\r\n# Launch interactive mode (recommended for beginners)\r\npython -m phenoAI.cli --interactive\r\n\r\n# Or if installed globally\r\nphenoai --interactive\r\n\r\n# Direct usage with parameters\r\npython -m phenoAI.cli --input ./images --output ./results\r\n```\r\n\r\n## \ud83d\udccb Detailed Usage Guide\r\n\r\n### 1. Interactive Command Line Interface\r\n\r\nThe easiest way to get started is using the interactive CLI:\r\n\r\n```bash\r\npython -m phenoAI.cli --interactive\r\n```\r\n\r\nThis will present you with a menu-driven interface:\r\n\r\n```\r\n\ud83c\udf3f PhenoAI v1.2.0 - Phenological Analysis Framework\r\n\ud83d\udcda Advanced Deep Learning for Close-Range PhenoCam Data Analysis\r\n\r\nSelect workflow:\r\n1. \ud83d\udd0d Image Quality Control\r\n2. \ud83c\udf31 Vegetation Segmentation \r\n3. \ud83d\udcca ROI Generation and Analysis\r\n4. \ud83d\udcc8 Vegetation Index Calculation\r\n5. \ud83c\udfaf Complete Workflow (All Steps)\r\n6. \ud83d\udda5\ufe0f Parameter Tuning GUI\r\n7. \u274c Exit\r\n\r\nEnter your choice (1-7):\r\n```\r\n\r\n### 2. Step-by-Step Workflow\r\n\r\n#### Step 1: Image Quality Control\r\n\r\n```python\r\nfrom phenoAI import PhenoAI\r\n\r\n# Initialize framework\r\nanalyzer = PhenoAI()\r\n\r\n# Set input directory containing your time-lapse images\r\nanalyzer.input_dir = \"path/to/your/images\"\r\n\r\n# Run quality control\r\nquality_results = analyzer.step1_image_quality_control()\r\n\r\n# Results will be saved to:\r\n# - Output/01_processing/high_quality_images/\r\n# - Output/02_low_quality_images/\r\n```\r\n\r\n**Features:**\r\n- Automated blur detection using Laplacian variance\r\n- Brightness and contrast analysis\r\n- Noise level assessment\r\n- Histogram-based quality metrics\r\n\r\n#### Step 2: Vegetation Segmentation\r\n\r\n```python\r\n# Run vegetation segmentation on quality-filtered images\r\nsegmentation_results = analyzer.step2_vegetation_segmentation()\r\n\r\n# Results include:\r\n# - Vegetation masks (binary)\r\n# - Vegetation extraction (RGB)\r\n# - Segmentation metrics and confidence scores\r\n```\r\n\r\n**Deep Learning Model:**\r\n- Uses advanced semantic segmentation (DeepLabV3+ architecture)\r\n- Pre-trained on diverse vegetation datasets\r\n- Supports multiple vegetation types (grass, crops, trees, etc.)\r\n- Confidence-based result filtering\r\n\r\n#### Step 3: ROI Generation and Analysis\r\n\r\n```python\r\n# Generate ROIs using K-means clustering on vegetation areas\r\nroi_results = analyzer.step3_roi_generation()\r\n\r\n# Interactive ROI preview with professional GUI\r\nanalyzer.display_roi_preview_popup(segmentation_results)\r\n\r\n# Select specific ROIs for analysis\r\nanalyzer.selected_rois = [0, 2, 4, 6] # or use 'all'\r\n```\r\n\r\n**ROI Features:**\r\n- K-means clustering on vegetation pixels\r\n- Polygon-based ROI boundaries\r\n- Interactive preview with colorful cluster visualization\r\n- Customizable ROI selection\r\n\r\n#### Step 4: Vegetation Index Calculation\r\n\r\n```python\r\n# Calculate comprehensive vegetation indices\r\nvi_results = analyzer.step4_vegetation_indices()\r\n\r\n# Available indices:\r\n# - GCC (Green Chromatic Coordinate)\r\n# - BCC (Blue Chromatic Coordinate)\r\n# - RCC (Red Chromatic Coordinate)\r\n# - ExG (Excess Green)\r\n# - VCI (Vegetation Contrast Index)\r\n```\r\n\r\n### 3. Advanced Parameter Tuning\r\n\r\nLaunch the professional GUI for parameter optimization:\r\n\r\n```python\r\nfrom phenoAI.gui import run_parameter_tuning\r\n\r\n# Launch parameter tuning interface\r\nrun_parameter_tuning()\r\n```\r\n\r\n**GUI Features:**\r\n- Real-time parameter adjustment with live preview\r\n- 5 sample images per filter type\r\n- Instant detection status feedback\r\n- Professional Tkinter interface\r\n- Save/load parameter configurations\r\n\r\n### 4. Batch Processing\r\n\r\n```python\r\n# Process multiple directories\r\nimport os\r\nfrom phenoAI import PhenoAI\r\n\r\ndirectories = [\r\n \"dataset1/time_series_1/\",\r\n \"dataset1/time_series_2/\",\r\n \"dataset2/wheat_2024/\"\r\n]\r\n\r\nfor directory in directories:\r\n analyzer = PhenoAI()\r\n analyzer.input_dir = directory\r\n analyzer.output_dir = f\"results/{os.path.basename(directory)}\"\r\n \r\n # Run complete workflow\r\n analyzer.run_full_workflow()\r\n```\r\n\r\n## \ud83d\udee0\ufe0f Advanced Configuration\r\n\r\n### Custom Model Integration\r\n\r\n```python\r\n# Use custom segmentation model\r\nanalyzer = PhenoAI()\r\nanalyzer.segmentation_model_path = \"path/to/your/custom_model.h5\"\r\n\r\n# Set custom vegetation labels\r\nanalyzer.selected_vegetation_label = \"crop\" # or \"grass\", \"tree\", etc.\r\n```\r\n\r\n### ROI Configuration\r\n\r\n```python\r\n# Customize ROI generation parameters\r\nroi_params = {\r\n \"n_clusters\": 8, # Number of K-means clusters\r\n \"min_roi_size\": 100, # Minimum ROI size in pixels\r\n \"max_roi_size\": 5000, # Maximum ROI size in pixels\r\n \"roi_shape\": \"polygon\" # ROI shape type\r\n}\r\n\r\nanalyzer.set_roi_parameters(roi_params)\r\n```\r\n\r\n### Quality Control Thresholds\r\n\r\n```python\r\n# Adjust quality control parameters\r\nquality_params = {\r\n \"blur_threshold\": 100.0, # Laplacian variance threshold\r\n \"brightness_min\": 50, # Minimum brightness\r\n \"brightness_max\": 200, # Maximum brightness\r\n \"contrast_threshold\": 30 # Minimum contrast\r\n}\r\n\r\nanalyzer.set_quality_parameters(quality_params)\r\n```\r\n\r\n## \ud83d\udcca Output Structure\r\n\r\nPhenoAI generates a comprehensive output directory structure:\r\n\r\n```\r\nOutput/\r\n\u251c\u2500\u2500 01_processing/\r\n\u2502 \u251c\u2500\u2500 high_quality_images/ # Quality-filtered images\r\n\u2502 \u2514\u2500\u2500 processing_log.json # Processing metadata\r\n\u251c\u2500\u2500 02_low_quality_images/ # Rejected images with reasons\r\n\u251c\u2500\u2500 03_segmentation_outputs/ # Vegetation masks and extractions\r\n\u2502 \u251c\u2500\u2500 masks/ # Binary vegetation masks\r\n\u2502 \u251c\u2500\u2500 extractions/ # RGB vegetation extractions\r\n\u2502 \u2514\u2500\u2500 metrics/ # Segmentation confidence scores\r\n\u251c\u2500\u2500 04_roi_analysis/ # ROI results and visualizations\r\n\u2502 \u251c\u2500\u2500 roi_boundaries/ # ROI polygon coordinates\r\n\u2502 \u251c\u2500\u2500 roi_previews/ # Visual ROI overlays\r\n\u2502 \u2514\u2500\u2500 cluster_analysis/ # K-means clustering results\r\n\u251c\u2500\u2500 05_vegetation_indices/ # Calculated indices\r\n\u2502 \u251c\u2500\u2500 gcc_results/ # GCC time series\r\n\u2502 \u251c\u2500\u2500 exg_results/ # ExG time series\r\n\u2502 \u2514\u2500\u2500 comprehensive_indices/ # All indices combined\r\n\u2514\u2500\u2500 reports/\r\n \u251c\u2500\u2500 summary_report.html # Comprehensive analysis report\r\n \u251c\u2500\u2500 quality_metrics.csv # Quality control statistics\r\n \u251c\u2500\u2500 segmentation_metrics.csv # Segmentation performance\r\n \u2514\u2500\u2500 temporal_analysis.csv # Time-series vegetation indices\r\n```\r\n\r\n## \ud83e\uddea Example Workflows\r\n\r\n### Workflow 1: Basic Vegetation Monitoring\r\n\r\n```python\r\nfrom phenoAI import PhenoAI\r\n\r\n# Initialize analyzer\r\nanalyzer = PhenoAI()\r\nanalyzer.input_dir = \"wheat_field_2024/\"\r\n\r\n# Run complete automated workflow\r\nresults = analyzer.run_full_workflow()\r\n\r\n# Access results\r\nprint(f\"Processed {len(results['high_quality_images'])} images\")\r\nprint(f\"Generated {len(results['rois'])} ROIs\")\r\nprint(f\"GCC temporal trend: {results['vegetation_indices']['gcc_trend']}\")\r\n```\r\n\r\n### Workflow 2: Custom ROI Analysis\r\n\r\n```python\r\n# Step-by-step processing with custom ROI selection\r\nanalyzer = PhenoAI()\r\nanalyzer.input_dir = \"crop_monitoring/\"\r\n\r\n# Quality control\r\nquality_results = analyzer.step1_image_quality_control()\r\n\r\n# Vegetation segmentation\r\nseg_results = analyzer.step2_vegetation_segmentation(quality_results)\r\n\r\n# Generate and preview ROIs\r\nanalyzer.step3_roi_generation(seg_results)\r\nanalyzer.display_roi_preview_popup(seg_results)\r\n\r\n# Manual ROI selection\r\nanalyzer.selected_rois = [1, 3, 5, 7, 9] # Select specific ROIs\r\n\r\n# Calculate indices for selected ROIs only\r\nvi_results = analyzer.step4_vegetation_indices(roi_subset=analyzer.selected_rois)\r\n```\r\n\r\n### Workflow 3: Parameter Optimization\r\n\r\n```python\r\n# Launch GUI for parameter tuning\r\nfrom phenoAI.gui import run_parameter_tuning\r\n\r\n# Interactive parameter optimization\r\nrun_parameter_tuning()\r\n\r\n# Apply optimized parameters\r\nanalyzer = PhenoAI()\r\nanalyzer.load_parameters(\"optimized_params.json\")\r\nanalyzer.run_full_workflow()\r\n```\r\n\r\n## \ud83d\udd27 Troubleshooting\r\n\r\n### Common Issues and Solutions\r\n\r\n#### 1. Model Loading Issues\r\n```python\r\n# If segmentation model fails to load\r\nanalyzer = PhenoAI()\r\nanalyzer.download_pretrained_model() # Download latest model\r\nanalyzer.segmentation_model_path = \"Model/Basic_Vegetation_Model.h5\"\r\n```\r\n\r\n#### 2. Memory Issues with Large Datasets\r\n```python\r\n# Process in smaller batches\r\nanalyzer.set_batch_size(32) # Reduce batch size\r\nanalyzer.enable_memory_optimization(True)\r\n```\r\n\r\n#### 3. GUI Issues\r\n```python\r\n# If GUI fails to launch\r\nimport tkinter as tk\r\ntry:\r\n root = tk.Tk()\r\n root.destroy()\r\n print(\"\u2705 Tkinter available\")\r\nexcept:\r\n print(\"\u274c Tkinter not available - install tkinter package\")\r\n```\r\n\r\n### Performance Optimization\r\n\r\n```python\r\n# Enable GPU acceleration (if available)\r\nanalyzer.enable_gpu(True)\r\n\r\n# Parallel processing\r\nanalyzer.set_num_workers(4) # Adjust based on CPU cores\r\n\r\n# Memory-efficient processing\r\nanalyzer.enable_lazy_loading(True)\r\n```\r\n\r\n## \ud83d\udcda API Reference\r\n\r\n### Core Classes\r\n\r\n#### `PhenoAI`\r\nMain analysis framework class.\r\n\r\n**Methods:**\r\n- `step1_image_quality_control()` - Image quality filtering\r\n- `step2_vegetation_segmentation()` - Deep learning segmentation\r\n- `step3_roi_generation()` - ROI clustering and generation\r\n- `step4_vegetation_indices()` - Vegetation index calculation\r\n- `run_full_workflow()` - Complete automated processing\r\n\r\n#### `ParameterTuningGUI`\r\nAdvanced parameter optimization interface.\r\n\r\n**Features:**\r\n- Real-time parameter adjustment\r\n- Multi-image preview\r\n- Parameter persistence\r\n- Export/import configurations\r\n\r\n### Utility Functions\r\n\r\n```python\r\nfrom phenoAI.utils import (\r\n calculate_vegetation_index,\r\n apply_quality_filters,\r\n generate_roi_polygons,\r\n create_temporal_plots\r\n)\r\n\r\n# Calculate custom vegetation index\r\ncustom_vi = calculate_vegetation_index(\r\n image_path=\"sample.jpg\",\r\n index_type=\"GCC\",\r\n roi_coordinates=[(100, 100), (200, 200)]\r\n)\r\n```\r\n\r\n## \ud83e\udd1d Contributing\r\n\r\nWe welcome contributions to PhenoAI! Please follow these guidelines:\r\n\r\n1. **Fork the repository** and create a feature branch\r\n2. **Follow PEP 8** coding standards\r\n3. **Add comprehensive tests** for new features\r\n4. **Update documentation** for API changes\r\n5. **Submit a pull request** with detailed description\r\n\r\n### Development Setup\r\n\r\n```bash\r\n# Clone for development\r\ngit clone https://github.com/your-username/phenoAI.git\r\ncd phenoAI\r\n\r\n# Create virtual environment\r\npython -m venv phenoai_dev\r\nsource phenoai_dev/bin/activate # On Windows: phenoai_dev\\Scripts\\activate\r\n\r\n# Install in development mode\r\npip install -e .[dev]\r\n\r\n# Run tests\r\npython -m pytest tests/\r\n```\r\n\r\n## \ud83d\udcc4 Citation\r\n\r\nIf you use PhenoAI in your research, please cite our paper:\r\n\r\n```APA\r\nKumar, A., Khare, S., & Rossi, S. (2025). PhenoAI: A deep learning Python framework to process close-range time-lapse PhenoCam data. Ecological Informatics, 88, 103134. https://doi.org/10.1016/j.ecoinf.2025.103134\r\n\r\n```bibtex\r\n@article{KUMAR2025103134,\r\ntitle = {PhenoAI: A deep learning Python framework to process close-range time-lapse PhenoCam data},\r\njournal = {Ecological Informatics},\r\nvolume = {88},\r\npages = {103134},\r\nyear = {2025},\r\nissn = {1574-9541},\r\ndoi = {https://doi.org/10.1016/j.ecoinf.2025.103134},\r\nurl = {https://www.sciencedirect.com/science/article/pii/S1574954125001438},\r\nauthor = {Akash Kumar and Siddhartha Khare and Sergio Rossi},\r\nkeywords = {Close-range Remote Sensing, GCC, Forest Phenology, PhenoCam, Python, Deep Learning}\r\n}\r\n```\r\n\r\n## \ud83d\udcde Support & Contact\r\n\r\n- **Issues**: [GitHub Issues](https://github.com/kharesiddhartha/phenoAI/issues)\r\n- **Discussions**: [GitHub Discussions](https://github.com/kharesiddhartha/phenoAI/discussions)\r\n- **Email**: [akash_k@ce.iitr.ac.in](mailto:akash_k@ce.iitr.ac.in), [siddhartha.khare@ce.iitr.ac.in](mailto:siddhartha.khare@ce.iitr.ac.in)\r\n\r\n## \ud83d\udccb License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n## \ud83d\ude4f Acknowledgments\r\n\r\n- Deep learning models based on DeepLabV3+ architecture\r\n- Vegetation index calculations following established remote sensing protocols\r\n- GUI framework built with Python Tkinter\r\n- Segmentation pipeline inspired by computer vision best practices\r\n\r\n---\r\n\r\n<div align=\"center\">\r\n\r\n**PhenoAI v1.2.0** - Advancing Phenological Research with Deep Learning\r\n\r\n*Developed by Akash Kumar, Siddhartha Khare and Sergio Rossi | Published in Ecological Informatics 2025*\r\n\r\n[](https://github.com/kharesiddhartha/phenoAI)\r\n[](https://github.com/kharesiddhartha/phenoAI/fork)\r\n\r\n</div>\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Automated Phenological Analysis Package for PhenoCam Data",
"version": "1.2.1.post1",
"project_urls": {
"Bug Reports": "https://github.com/kharesiddhartha/phenoAI/issues",
"Documentation": "https://github.com/kharesiddhartha/phenoAI#readme",
"Homepage": "https://github.com/kharesiddhartha/phenoAI",
"Source": "https://github.com/kharesiddhartha/phenoAI"
},
"split_keywords": [
"phenology",
" computer vision",
" image analysis",
" vegetation indices",
" remote sensing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "89d19aae3099a0b8dda379132984bfb5c7718ac2ebd08b952700e0f677994771",
"md5": "06c9c67bf0c7a77d09e6e30ddb846321",
"sha256": "96a2c3ac98854b130c122849c00c1748ab680b3cc7a16626871800e5831bd492"
},
"downloads": -1,
"filename": "phenoai_package-1.2.1.post1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "06c9c67bf0c7a77d09e6e30ddb846321",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 99661,
"upload_time": "2025-08-03T17:58:30",
"upload_time_iso_8601": "2025-08-03T17:58:30.877109Z",
"url": "https://files.pythonhosted.org/packages/89/d1/9aae3099a0b8dda379132984bfb5c7718ac2ebd08b952700e0f677994771/phenoai_package-1.2.1.post1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a9381d3e2ea9bcb2539096c7e5fb0494fee80b4ec1ef81cacf42c5c569749770",
"md5": "c3f2524178a26fd3bb98077ef8d2b48c",
"sha256": "f6cf24ba4615e96d9194d63ea10d31d803b5fa27af9458fc1b2ce5122a1df2fd"
},
"downloads": -1,
"filename": "phenoai_package-1.2.1.post1.tar.gz",
"has_sig": false,
"md5_digest": "c3f2524178a26fd3bb98077ef8d2b48c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 2555984,
"upload_time": "2025-08-03T17:58:33",
"upload_time_iso_8601": "2025-08-03T17:58:33.723105Z",
"url": "https://files.pythonhosted.org/packages/a9/38/1d3e2ea9bcb2539096c7e5fb0494fee80b4ec1ef81cacf42c5c569749770/phenoai_package-1.2.1.post1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-03 17:58:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kharesiddhartha",
"github_project": "phenoAI",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "numpy",
"specs": [
[
">=",
"1.19.0"
]
]
},
{
"name": "scipy",
"specs": [
[
">=",
"1.7.0"
]
]
},
{
"name": "opencv-python",
"specs": [
[
">=",
"4.5.0"
]
]
},
{
"name": "pillow",
"specs": [
[
">=",
"8.0.0"
]
]
},
{
"name": "matplotlib",
"specs": [
[
">=",
"3.3.0"
]
]
},
{
"name": "plotly",
"specs": [
[
">=",
"5.0.0"
]
]
},
{
"name": "pandas",
"specs": [
[
">=",
"1.3.0"
]
]
},
{
"name": "pyyaml",
"specs": [
[
">=",
"5.4.0"
]
]
},
{
"name": "scikit-learn",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "scikit-image",
"specs": [
[
">=",
"0.18.0"
]
]
},
{
"name": "tqdm",
"specs": [
[
">=",
"4.60.0"
]
]
},
{
"name": "h5py",
"specs": [
[
">=",
"3.0.0"
]
]
},
{
"name": "seaborn",
"specs": [
[
">=",
"0.11.0"
]
]
},
{
"name": "statsmodels",
"specs": [
[
">=",
"0.12.0"
]
]
}
],
"lcname": "phenoai-package"
}
JSON
