README.md

---
title: CIFAR-10 Image Classifier
emoji: 🚀
colorFrom: blue
colorTo: red
sdk: gradio
sdk_version: "4.44.1"
app_file: app.py
pinned: false
---

# CIFAR-10 Image Classifier

This is a Gradio interface for a convolutional neural network trained on the CIFAR-10 dataset. The model can classify images into 10 different object categories: Airplane, Automobile, Bird, Cat, Deer, Dog, Frog, Horse, Ship, and Truck.

## Model Architecture

The neural network has the following architecture (based on the PyTorch CIFAR-10 Tutorial):
- Two convolutional layers with ReLU activation and max pooling
- Three fully connected layers
- Designed for 32x32 RGB input images

```
Input → Conv2d(3, 6, 5) → ReLU → MaxPool2d(2, 2) → 
Conv2d(6, 16, 5) → ReLU → MaxPool2d(2, 2) → 
Flatten → Linear(16*5*5, 120) → ReLU → 
Linear(120, 84) → ReLU → Linear(84, 10) → Output
```

## Features

- Interactive image classification interface with modern UI
- Example images for each CIFAR-10 class
- Real-time predictions with probability scores
- Support for custom image uploads
- Built-in drawing tool for creating test images
- Responsive design with gradient backgrounds and animations
- Automatic image preprocessing (resize to 32×32)

## How to Use with Your Existing Model

1. Place your trained PyTorch model file in the app directory and name it `model.pth`
2. Ensure your model uses the same architecture as defined in the Net class
3. Install the required dependencies:
   ```bash
   pip install -r requirements.txt
   ```

4. Run the application:
   ```bash
   python app.py
   ```

5. Access the interface at `http://localhost:7860` (or the URL provided in the terminal)

## Image Input Capabilities

The model can handle various types of image inputs:

### Supported Image Formats
- JPG, PNG, BMP, TIFF, and other common image formats
- Color images (RGB with 3 channels)
- Any resolution (automatically resized to 32×32 pixels)

### Robustness Features
- **Resolution Independence**: Works with images of any size (resized to 32×32)
- **Color Preservation**: Maintains RGB color information
- **Contrast Handling**: Works with both high and low contrast images
- **Noise Tolerance**: Can handle some image noise
- **Rotation Tolerance**: Some tolerance to slight rotations

### Best Practices for Good Results
1. **Center the object** in the image area
2. **Use clear contrast** between the object and background
3. **Fill most of the image** area with the object
4. **Avoid excessive noise** or artifacts
5. **Ensure the object is clearly visible**

## CIFAR-10 Classes

The model classifies images into these 10 categories:
1. **Airplane** - Aircraft flying in the sky
2. **Automobile** - Cars and vehicles on the road
3. **Bird** - Flying or perched birds
4. **Cat** - Domestic cats and felines
5. **Deer** - Wild deer and similar animals
6. **Dog** - Domestic dogs and canines
7. **Frog** - Amphibians like frogs
8. **Horse** - Horses and similar animals
9. **Ship** - Boats and ships on water
10. **Truck** - Trucks and heavy vehicles

## Deployment to Hugging Face Spaces

This application can be deployed to Hugging Face Spaces by:

1. Creating a new Space on Hugging Face
2. Uploading these files to the repository
3. Setting the SDK to "Gradio"
4. Adding the requirements in the requirements.txt file
5. Uploading your `model.pth` file

The Space will automatically run the `app.py` file as the entry point.

## Example Usage

The interface comes with simple example images representing each CIFAR-10 class. You can:
1. Click on any example image to load it
2. Upload your own image using the file browser
3. Draw an image using the built-in sketch tool
4. View the classification probabilities for each class

Try these examples:
- Simple drawings of objects from each class
- Photos of objects that match the CIFAR-10 categories
- Images with varying styles and backgrounds

## Technical Details

This implementation is based on the PyTorch CIFAR-10 tutorial and includes:
- Gradio interface with custom CSS styling
- Image preprocessing pipeline (resize to 32x32)
- Softmax probability output
- Example generation for demonstration
- Model loading functionality for your trained weights

The prediction function:
```python
model.eval()
with torch.no_grad():
    output = model(input_tensor)
    probabilities = F.softmax(output, dim=1)
```

The UI features:
- Animated gradient background
- Glass-morphism design elements
- Responsive layout for all screen sizes
- Interactive buttons with hover effects
- Clean, modern typography

## Requirements

- Python 3.6+
- PyTorch >= 1.7.0
- TorchVision >= 0.8.0
- Gradio >= 4.0.0
- Pillow >= 8.0.0
- NumPy >= 1.19.0

Install with:
```bash
pip install -r requirements.txt
```

## Troubleshooting

If you encounter issues:
1. Ensure your `model.pth` file is in the same directory as `app.py`
2. Verify that your model uses the same architecture as defined in the Net class
3. Check that all required dependencies are installed
4. Make sure you're using a compatible version of Python (3.6+)

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference