Create README.md

README.md

@@ -1,12 +1,208 @@
 ---
-title: 24679 HW3 Q2
-emoji: 🏃
-colorFrom: purple
-colorTo: purple
+title: Tomato Classifier
+emoji: 🍅
+colorFrom: red
+colorTo: green
 sdk: gradio
-sdk_version: 5.47.2
+sdk_version: 4.0.0
 app_file: app.py
 pinned: false
+license: mit
+short_description: Binary image classifier to detect tomatoes using MobileNetV3
+tags:
+- image-classification
+- pytorch
+- mobilenet
+- food
+- binary-classification
+- computer-vision
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🍅 Tomato vs Not-Tomato Classifier
+
+An interactive web application for classifying images as tomato or not-tomato using a MobileNetV3-Small neural network trained with AutoML.
+
+## 🎯 Overview
+
+This Gradio application provides a user-friendly interface for a binary image classifier that predicts whether an image contains a tomato. The model was trained using AutoML techniques (Optuna) on a small food dataset as part of a machine learning course assignment.
+
+## 🚀 Features
+
+- **Image Upload**: Support for PNG/JPG files up to 10MB
+- **Multiple Input Sources**: Upload from file, webcam, or clipboard
+- **Real-time Preview**: View both original and preprocessed images
+- **Confidence Visualization**: Interactive bar chart showing class probabilities
+- **Adjustable Threshold**: Control minimum confidence for predictions
+- **Example Images**: Pre-loaded examples to test the model
+- **Graceful Error Handling**: Validates file types and sizes with helpful error messages
+
+## 🤖 Model Information
+
+### Architecture
+- **Base Model**: MobileNetV3-Small (pretrained on ImageNet, fine-tuned)
+- **Task**: Binary classification (0 = not_tomato, 1 = tomato)
+- **Input Size**: 224×224 pixels
+- **Dropout**: 0.476
+- **Final Layers**: Custom classifier with dropout regularization
+
+### Training Details
+- **Framework**: PyTorch 2.4.1
+- **AutoML**: Optuna with 10 trials, pruning enabled
+- **Optimizer**: AdamW
+- **Learning Rate**: 1.186×10⁻⁵
+- **Weight Decay**: 0.000433
+- **Batch Size**: 16
+- **Early Stopping**: Patience of 6 epochs on validation F1
+- **Seed**: 42 (for reproducibility)
+
+### Performance Metrics
+- **Test Accuracy**: 83%
+- **Test F1 Score**: 0.80
+- **Training Dataset Size**: ~30 images (very small)
+- **Data Split**: 60/20/20 (train/val/test)
+
+## 📊 Dataset
+
+- **Source**: [Iris314/Food_tomatoes_dataset](https://huggingface.co/datasets/Iris314/Food_tomatoes_dataset)
+- **Size**: Approximately 30 images total
+- **Classes**: Binary (tomato / not-tomato)
+- **Stratification**: Stratified splits to maintain class balance
+
+## 🔧 Preprocessing Pipeline
+
+### Training Augmentations
+- Random resized crop
+- Horizontal flip (p=0.5)
+- Color jitter
+- Normalization (ImageNet statistics)
+
+### Evaluation Transforms
+1. **Resize**: 256×256 pixels
+2. **Center Crop**: 224×224 pixels
+3. **Normalize**: 
+   - Mean: [0.485, 0.456, 0.406]
+   - Std: [0.229, 0.224, 0.225]
+
+The application displays both the original image and the preprocessed version that the model actually processes, helping users understand how the model "sees" the input.
+
+## 📈 Usage Guide
+
+### Basic Classification
+1. Upload an image using the file uploader, webcam, or paste from clipboard
+2. Click "Classify Image" to get predictions
+3. View results including:
+   - Predicted class (Tomato or Not Tomato)
+   - Confidence score
+   - Probability distribution
+   - Visual confidence chart
+
+### Advanced Options
+- **Confidence Threshold**: Adjust the minimum confidence required (default: 50%)
+- **Show Preprocessing**: Toggle display of preprocessed image to see model input
+- **Examples**: Click example images to quickly test the model
+
+## ⚠️ Limitations & Known Issues
+
+### Dataset Limitations
+- **Very Small Dataset**: Only ~30 training images increases overfitting risk
+- **Limited Diversity**: May not generalize well to unusual tomato varieties or presentations
+
+### Known Failure Modes
+The model may struggle with:
+- Cartoon or illustrated tomatoes
+- Extreme viewing angles
+- Heavy shadows or overexposure
+- Multiple food items in one image
+- Cherry tomatoes or heirloom varieties
+- Processed tomato products (sauce, paste, soup)
+- Out-of-distribution backgrounds
+
+### Performance Considerations
+- Background and lighting variations can bias predictions
+- Not suitable for production or consequential decisions
+- Educational demonstration only
+
+## 🔗 Links & Resources
+
+- **Model Repository**: [kevinkyi/Homework2_NN](https://huggingface.co/kevinkyi/Homework2_NN)
+- **Dataset**: [Iris314/Food_tomatoes_dataset](https://huggingface.co/datasets/Iris314/Food_tomatoes_dataset)
+- **Framework**: [PyTorch](https://pytorch.org/)
+- **AutoML Tool**: [Optuna](https://optuna.org/)
+- **Model Architecture**: [MobileNetV3](https://arxiv.org/abs/1905.02244)
+
+## 🛠️ Technical Stack
+
+- **Frontend**: Gradio 4.x
+- **Backend**: PyTorch 2.x, TorchVision
+- **Model Loading**: Hugging Face Hub
+- **Visualization**: Matplotlib
+- **Compute**: CPU inference (no GPU required)
+
+## 📝 Inference Parameters
+
+The interface exposes the following key parameters:
+
+1. **Confidence Threshold** (0.0-1.0): Minimum confidence for classification
+2. **Show Preprocessing** (boolean): Display preprocessed image
+3. **Input Validation**: Automatic file size and type checking
+
+## 🎓 Educational Context
+
+This project was created as part of a machine learning course assignment (Homework 2) to demonstrate:
+- Neural network training with AutoML
+- Transfer learning with pretrained models
+- Hyperparameter optimization with Optuna
+- Model deployment with Gradio
+- Documentation best practices
+
+## 📄 License
+
+- **Code & Weights**: MIT License
+- **Dataset**: Follow original dataset's license terms
+- **Educational Use**: This model is for coursework demonstration only
+
+## 🙏 Acknowledgments
+
+- Dataset provided by classmate (Iris314)
+- AutoML powered by Optuna
+- Pretrained models from TorchVision
+- Trained on Google Colab (T4 GPU)
+- GenAI tools assisted with documentation and boilerplate code
+
+## ⚡ Quick Start
+
+To run locally:
+
+```bash
+# Clone the space
+git clone https://huggingface.co/spaces/YOUR_USERNAME/tomato-classifier
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Run the app
+python app.py
+```
+
+The application will automatically download the model weights from Hugging Face Hub on first run.
+
+## 🐛 Troubleshooting
+
+**Model won't load?**
+- Ensure you have internet connection for downloading weights
+- Check that all dependencies are installed
+- Verify PyTorch is properly installed
+
+**Low accuracy on your images?**
+- The model was trained on a very small dataset (~30 images)
+- Performance may vary significantly on images different from training data
+- Try adjusting lighting and background for better results
+
+**File upload errors?**
+- Ensure image is under 10MB
+- Supported formats: PNG, JPG, JPEG
+- Try converting or compressing large images
+
+---
+
+**Note**: This is an educational project demonstrating ML deployment practices. It should not be used for production applications or any consequential decision-making.