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:

./quickstart.sh

Manual Start:

# 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:

# 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:

# In your training script
torch.save(model.state_dict(), 'best_model.pth')

2. Copy to models directory:

cp path/to/best_model.pth models/

3. Update model_loader.py with your architecture:

# 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:

demo = create_interface(use_mock=False)

Testing

Test individual components:

# 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:

   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:

# 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")

# 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')

# 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:

# 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):

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! 🌱