ds-smart-farm-project/USAGE.md

# Smart Farm Photo Keyword Tagging AI - Usage Guide

## 🚀 Quick Start

### 1. Installation
```bash
# 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
```bash
# 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
```bash
# Process photos from custom directory
python3 src/main.py --input /Users/yourname/farm_photos --output /Users/yourname/results
```

### Using the Jupyter Notebook
```bash
# 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

```bash
# 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.