ds-smart-farm-project/USAGE.md

Smart Farm Photo Keyword Tagging AI - Usage Guide

🚀 Quick Start

1. Installation

# Install dependencies
python3 -m pip install -r requirements.txt

2. Prepare Your Photos

• Place agricultural photos in data/raw/ directory
• Supported formats: JPG, JPEG, PNG, TIFF, BMP
• Any image size (system will handle resizing)

3. Run the System

# Basic usage - process all images in data/raw/
python3 src/main.py

# Specify custom directories
python3 src/main.py --input /path/to/your/photos --output /path/to/results

4. View Results

• Results saved as CSV in outputs/ directory
• Filename format: agricultural_keywords_YYYYMMDD_HHMMSS.csv

📊 Output Format

The system generates a CSV file with these columns:

Column	Description	Example
filename	Original image filename	farmer_cornfield.jpg
human_keywords	Manual keywords (for comparison)	farmer, corn, agriculture
ai_keywords	AI-generated keywords	farmer, corn, field, agriculture, male
ai_title	Descriptive title for stock photos	Farmer working in cornfield
location	GPS location if available	Iowa or GPS Location Available

🔧 Advanced Usage

Batch Processing

The system is designed for batch processing:

• Handles 500+ images efficiently
• Processes images sequentially to manage memory
• Progress tracking during processing

Custom Input Directories

# Process photos from custom directory
python3 src/main.py --input /Users/yourname/farm_photos --output /Users/yourname/results

Using the Jupyter Notebook

# Start Jupyter
jupyter notebook

# Open notebooks/agricultural_keyword_analysis.ipynb
# Run all cells for interactive analysis

📈 Performance

Expected Processing Times:

• Setup: ~30 seconds (model loading)
• Per Image: ~2-5 seconds
• Batch of 100: ~5-10 minutes
• Batch of 500: ~20-40 minutes

System Requirements:

• RAM: 4GB minimum, 8GB recommended
• Storage: 2GB for model files
• CPU: Any modern processor (GPU optional)

🎯 Keyword Quality

What the AI Recognizes Well:

• ✅ People (farmers, workers)
• ✅ Animals (cows, pigs, chickens)
• ✅ Equipment (tractors, tools)
• ✅ Crops (corn, wheat, vegetables)
• ✅ Settings (fields, barns, farms)

Current Limitations:

• ⚠️ May not distinguish farmer vs rancher perfectly
• ⚠️ Gender identification needs improvement
• ⚠️ Location extraction limited without GPS data
• ⚠️ Some agriculture-specific terms may be generic

🛠️ Troubleshooting

Common Issues:

"No images found"

• Check that images are in data/raw/ directory
• Verify file extensions are supported
• System will create sample data if no images found

"Model loading error"

• Ensure internet connection for first-time model download
• Check available disk space (2GB needed)
• Restart if download was interrupted

"Out of memory"

• Process smaller batches
• Close other applications
• Consider using a machine with more RAM

Getting Help:

1. Check the error message in terminal
2. Verify all dependencies are installed
3. Ensure input directory contains valid image files

📝 Example Workflow

# 1. Prepare your photos
mkdir -p data/raw
cp /path/to/your/farm/photos/* data/raw/

# 2. Run processing
python3 src/main.py

# 3. Check results
ls outputs/
cat outputs/agricultural_keywords_*.csv

# 4. Analyze with notebook
jupyter notebook notebooks/agricultural_keyword_analysis.ipynb

🔄 Integration with Existing Workflow

For Stock Photo Businesses:

1. Upload: Place new photos in data/raw/
2. Process: Run batch processing monthly
3. Review: Check AI keywords against human keywords
4. Export: Use CSV for your photo management system

Scaling Up:

• Process 1,000+ photos by running multiple batches
• Monitor processing time and adjust batch sizes
• Consider upgrading hardware for faster processing

📋 Next Steps for Production

1. Fine-tune model on your 30,000 tagged photos
2. Add location services for GPS coordinate conversion
3. Implement quality scoring for keyword confidence
4. Create web interface for easier use
5. Add batch scheduling for automated processing

---

Need help? Check the notebook examples or review the code documentation in src/ directory.