README.md

---
title: ResNet-18 CIFAR-100 Classifier
emoji: 🖼️
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 5.49.1
app_file: app.py
pinned: false
---

# ResNet-18 CIFAR-100 Image Classifier 🎯

A high-performance image classifier trained on CIFAR-100 dataset, achieving **77.18% test accuracy**.

## Model Details

- **Architecture:** ResNet-18 (Custom CIFAR-100 variant)
- **Parameters:** ~11 million
- **Test Accuracy:** 77.18%
- **Train Accuracy:** 98.25%
- **Training Time:** ~70 minutes on RTX 4070 Laptop GPU
- **Dataset:** CIFAR-100 (60,000 32×32 color images in 100 classes)

## Training Configuration

### Advanced Techniques Used
1. **OneCycle Learning Rate Policy** - Gradual warmup + extended annealing
2. **Cutout Augmentation** - Randomly masks 8×8 patches
3. **Label Smoothing** (0.1) - Prevents overconfident predictions
4. **Gradient Clipping** - Stabilizes training during high-LR phase
5. **Data Augmentation** - Random crops, horizontal flips, normalization

### Hyperparameters
- Epochs: 100
- Batch Size: 128
- Max Learning Rate: 0.1
- Weight Decay: 5e-4
- Optimizer: SGD with momentum (0.9)

## 100 Classes

The model can classify images into these categories:

**Animals (42 classes):**
- Mammals: bear, beaver, camel, cattle, chimpanzee, dolphin, elephant, fox, hamster, kangaroo, leopard, lion, mouse, otter, porcupine, possum, rabbit, raccoon, seal, shrew, skunk, squirrel, tiger, whale, wolf
- Aquatic: aquarium_fish, crab, crocodile, flatfish, lobster, ray, shark, trout
- Insects/Small creatures: bee, beetle, butterfly, caterpillar, cockroach, snail, snake, spider, turtle, worm
- Reptiles: dinosaur, lizard

**Vehicles (5 classes):**
bicycle, bus, motorcycle, pickup_truck, streetcar, tank, tractor, train, rocket

**Household Items (11 classes):**
bed, chair, clock, couch, cup, keyboard, lamp, plate, table, telephone, television, wardrobe

**Food (5 classes):**
apple, mushroom, orange, pear, sweet_pepper

**Nature (13 classes):**
- Trees: maple_tree, oak_tree, palm_tree, pine_tree, willow_tree
- Flowers: orchid, poppy, rose, sunflower, tulip
- Landscapes: cloud, forest, mountain, plain, road, sea

**People (3 classes):**
baby, boy, girl, man, woman

**Structures (5 classes):**
bridge, castle, house, road, skyscraper

**Other (16 classes):**
aquarium_fish, bottle, bowl, bridge, can, castle, house, lawn_mower, rocket, sea, tank

## Usage

### On Hugging Face Spaces
Simply upload an image and get instant predictions with confidence scores!

### Local Usage

```python
import torch
from PIL import Image
from torchvision import transforms

# Load model
checkpoint = torch.load('checkpoints/resnet18_best.pth')
model = ResNet(BasicBlock, [2, 2, 2, 2], num_classes=100)
model.load_state_dict(checkpoint['model_state_dict'])
model.eval()

# Preprocess image
transform = transforms.Compose([
    transforms.Resize((32, 32)),
    transforms.ToTensor(),
    transforms.Normalize((0.5071, 0.4867, 0.4408), 
                        (0.2675, 0.2565, 0.2761))
])

image = Image.open('your_image.jpg')
img_tensor = transform(image).unsqueeze(0)

# Predict
with torch.no_grad():
    output = model(img_tensor)
    pred = output.argmax(dim=1)
```

## Performance Notes

- **Best for:** Small objects, centered subjects, simple backgrounds
- **Optimized for:** 32×32 images (will be automatically resized)
- **Categories:** Works best with the 100 CIFAR-100 classes listed above

## Training Curves

The model showed steady improvement throughout training:
- Epochs 1-30: Warmup phase (13.89% → 59.38%)
- Epochs 31-60: Peak learning (59.38% → 63.88%)
- Epochs 61-100: Fine-tuning (63.88% → 77.18%)

## Key Achievements

✅ Exceeded 73% target accuracy by **4.18%**  
✅ Stable training with no divergence  
✅ Effective use of OneCycleLR scheduler  
✅ Combined regularization techniques  
✅ Fast training (~70 minutes for 100 epochs)  

## Repository

Full training code, logs, and checkpoints available at: [GitHub Repository](https://github.com/yourusername/resnet-cifar100)

## Citation

If you use this model, please cite:

```bibtex
@misc{resnet18-cifar100,
  author = {Your Name},
  title = {ResNet-18 CIFAR-100 Image Classifier},
  year = {2024},
  publisher = {Hugging Face},
  howpublished = {\url{https://huggingface.co/spaces/yourusername/resnet18-cifar100}}
}
```

## License

MIT License - Feel free to use for research and educational purposes!