docs/USAGE.md

# Usage Guide - Plant Disease Detection UI

This guide explains how to use the Plant Disease Detection application.

## For Developers

### Running Locally

**Quick Start:**
```bash
./quickstart.sh
```

**Manual Start:**
```bash
# Activate virtual environment
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Run the app
cd ui
python app.py
```

The app will be available at `http://localhost:7860`

### Development with Mock Model

During development, the app uses a mock model by default. This allows you to:
- Test the UI without waiting for model training
- Develop features in parallel with the ML team
- Verify the interface works correctly

To use the mock model:
```python
# In ui/app.py
demo = create_interface(use_mock=True)  # Default
```

### Switching to Real Model

Once your team has trained a model:

1. **Save your model:**
```python
# In your training script
torch.save(model.state_dict(), 'best_model.pth')
```

2. **Copy to models directory:**
```bash
cp path/to/best_model.pth models/
```

3. **Update model_loader.py with your architecture:**
```python
# Replace MockPlantDiseaseModel with your actual model
from your_training_code import YourCNNModel

def _load_real_model(self, model_name, model_path=None):
    model = YourCNNModel(num_classes=39)
    # ... rest of the code
```

4. **Change app.py to use real model:**
```python
demo = create_interface(use_mock=False)
```

### Testing

**Test individual components:**
```bash
# Test mock model
python models/mock_model.py

# Test model loader
python ui/model_loader.py

# Test utilities
python ui/utils.py
```

**Test with different images:**
1. Download example images:
   ```bash
   python download_examples.py --num 20
   ```

2. Run the app and test each feature:
   - Single image prediction
   - Batch processing
   - Model switching
   - Confidence threshold
   - Flagging predictions

## For End Users

### Single Image Classification

1. Open the app in your browser
2. Go to the **"Single Image"** tab
3. Upload an image:
   - Click the image upload area
   - Select a plant leaf photo from your computer
   - Supported formats: JPG, PNG
4. (Optional) Select a different model from the dropdown
5. (Optional) Adjust the confidence threshold
6. Click **"Predict Disease"**
7. View the results:
   - Top predictions shown as a chart
   - Detailed information about the top prediction
   - Raw JSON data available in the accordion

### Using Example Images

1. Go to the **"Example Images"** tab
2. Click on any example image
3. The image will be loaded into the predictor
4. Go back to the "Single Image" tab
5. Click "Predict Disease"

### Batch Processing

To classify multiple images at once:

1. Go to the **"Batch Processing"** tab
2. Click "Upload Multiple Images"
3. Select multiple image files (use Ctrl/Cmd + Click)
4. Click "Predict All"
5. View results for all images

### Flagging Incorrect Predictions

If you notice a wrong prediction:

1. After getting a prediction, expand **"Flag Incorrect Prediction"**
2. Enter feedback (e.g., "This is actually Apple Scab, not Black Rot")
3. Click **"Submit Flag"**
4. Your feedback is recorded for the developers

### Adjusting Confidence Threshold

The confidence threshold filters out low-confidence predictions:

1. Use the slider at the top: **"Confidence Threshold (%)"**
2. Move it right to see only high-confidence predictions
3. Move it left to see more predictions (including uncertain ones)

**Example:**
- Set to 50%: Only shows predictions the model is at least 50% confident about
- Set to 1%: Shows almost all predictions

### Understanding Results

**Prediction Display:**
```
Tomato - Late blight: 85.2%
Tomato - Early blight: 8.3%
Tomato - Leaf Mold: 3.1%
...
```

**Detailed Info:**
- **Top Prediction:** The most likely disease
- **Confidence:** How certain the model is (0-100%)
- **Plant:** The type of plant detected
- **Status:** Whether the plant is healthy or diseased

### Tips for Best Results

1. **Image Quality:**
   - Use clear, well-lit photos
   - Focus on the leaf
   - Avoid blurry images

2. **Image Content:**
   - Show the diseased area clearly
   - Include the whole leaf if possible
   - One leaf per image works best

3. **File Size:**
   - The app automatically resizes images
   - But uploading smaller images (<5MB) is faster

4. **Interpreting Confidence:**
   - >80%: High confidence - likely correct
   - 50-80%: Moderate confidence - possible
   - <50%: Low confidence - uncertain

## Advanced Features

### Switching Between Models

If your team trained multiple models:

1. Use the **"Select Model"** dropdown at the top
2. Options might include:
   - CNN from Scratch
   - Transfer Learning (ResNet18)
3. Each model may perform differently
4. Try both and compare results

### Viewing Raw Predictions

For technical analysis:

1. After prediction, expand **"Advanced: View Raw Predictions"**
2. See the raw probability scores in JSON format
3. Useful for debugging or detailed analysis

### Batch Results Analysis

When processing multiple images:

1. Results show the top prediction for each image
2. Format: `Image 1: Disease Name (confidence%)`
3. Scroll through all results
4. Use this for analyzing a collection of plants

## Integration with Training Pipeline

### For ML Team Members

**Updating the Model:**

After training a new model:

```python
# Option 1: Upload to ClearML (recommended)
from clearml import Task
task = Task.current_task()
# Model is automatically uploaded

# Then in UI:
loader.load_from_clearml(task_id="your_task_id")
```

```python
# Option 2: Save locally
torch.save(model.state_dict(), 'models/best_model.pth')

# Then in UI:
loader.load_model(model_path='models/best_model.pth')
```

```python
# Option 3: Upload to HuggingFace Hub
from huggingface_hub import HfApi
api = HfApi()
api.upload_file(
    path_or_fileobj="best_model.pth",
    path_in_repo="model.pth",
    repo_id="username/model-name"
)

# Then in UI:
loader.load_from_huggingface("username/model-name")
```

### Experiment Tracking

The UI can load any model from your ClearML experiments:

```python
# Get task ID from ClearML dashboard
# Then update model_loader.py or pass as parameter
```

## Troubleshooting

### Common Issues

**"Please upload an image"**
- Solution: Make sure you've selected an image before clicking Predict

**"No predictions above confidence threshold"**
- Solution: Lower the confidence threshold slider
- Or the image might not be a plant leaf

**"Error during prediction"**
- Check the error message in the output
- Verify the image is valid (not corrupted)
- Try a different image

**Slow predictions**
- First prediction may be slow (model loading)
- Subsequent predictions should be faster
- Batch processing might take longer for many images

**Example gallery is empty**
- Run `python download_examples.py` to download examples
- Or manually add images to `ui/examples/`

### Getting Help

1. Check the error message displayed in the UI
2. Look at the terminal/console for detailed errors
3. Refer to README.md for setup issues
4. Check docs/deployment_guide.md for deployment issues
5. Contact your team members or course TAs

## Recording a Demo Video

For your project submission:

### What to Include

1. **Introduction** (10 sec)
   - "This is our Plant Disease Detection system..."

2. **Single Image Demo** (30-60 sec)
   - Upload an image
   - Show prediction results
   - Explain the output

3. **Advanced Features** (30-60 sec)
   - Show model selection
   - Demonstrate batch processing
   - Show flagging feature

4. **Example Gallery** (15-30 sec)
   - Browse example images
   - Select and predict

5. **Conclusion** (10-15 sec)
   - Summarize capabilities
   - Mention accuracy/performance

### Recording Tips

- Use screen recording software (QuickTime, OBS, etc.)
- Enable audio narration
- Show your face (optional but personal)
- Keep it concise (2-3 minutes for basic, 5-6 for feature-rich)
- Test audio quality before final recording
- Practice once before recording

### Video Quality

- Resolution: At least 1080p
- Format: MP4 (most compatible)
- Audio: Clear voice, no background noise
- Editing: Simple cuts are fine, no need for fancy effects

## API Documentation

For programmatic use (advanced):

```python
from model_loader import get_model
from utils import preprocess_image, postprocess_predictions

# Load model
model, loader = get_model(use_mock=False)

# Prepare image
from PIL import Image
image = Image.open("path/to/leaf.jpg")
tensor = preprocess_image(image)

# Predict
import torch
with torch.no_grad():
    logits = model(tensor.to(loader.device))

# Get results
top_preds, all_preds = postprocess_predictions(logits)
print(top_preds)
```

## FAQ

**Q: Can I use this with my own plant images?**
A: Yes! Upload any plant leaf image. Works best with the plants/diseases in the training set.

**Q: How accurate is the model?**
A: Check the README or About tab for test accuracy. Typically 85-95% on validation set.

**Q: Can I add more disease categories?**
A: You'd need to retrain the model with additional data for new categories.

**Q: Is my data saved?**
A: Images uploaded during use are not saved unless you flag a prediction. Flagged data stays in memory only.

**Q: Can I run this offline?**
A: Yes, once installed, the app runs locally and doesn't need internet (except for downloading model from HF/ClearML).

**Q: How do I cite this in a report?**
A: Reference your team's GitHub repo and the deployed app URL.

## Next Steps

- **Test thoroughly:** Try various images, edge cases
- **Integrate real model:** Replace mock model with trained model
- **Deploy:** Follow deployment guide to put on HF Spaces
- **Record demo:** Create your submission video
- **Write report:** Document the UI features in your report

---

**Happy classifying! 🌱**