digit-ai-classifier

# 🧠 Handwritten Digit Recognizer

[![Python](https://img.shields.io/badge/Python-3.8%2B-blue.svg)](https://www.python.org/)
[![TensorFlow](https://img.shields.io/badge/TensorFlow-2.13.0-orange.svg)](https://www.tensorflow.org/)
[![Streamlit](https://img.shields.io/badge/Streamlit-1.28.0-red.svg)](https://streamlit.io/)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

Bu proje, **MNIST veri seti** kullanılarak eğitilmiş bir **CNN (Convolutional Neural Network)** modeli ile el yazısı rakamları (0-9) tanır. Interaktif bir **Streamlit** web arayüzü ile kullanıcılar kendi rakamlarını çizebilir ve gerçek zamanlı tahminler alabilir.

![Demo](https://img.shields.io/badge/Demo-Live-success)

---

## 🌟 Özellikler

- ✅ **%98+ Doğruluk** - MNIST test seti üzerinde yüksek performans
- 🎨 **Interaktif Arayüz** - Streamlit ile kullanıcı dostu web uygulaması
- 🧠 **CNN Mimarisi** - Derin öğrenme ile güçlü özellik çıkarımı
- 📊 **Detaylı Analizler** - Confusion matrix, sınıf bazlı doğruluk grafikleri
- 🔮 **Gerçek Zamanlı Tahmin** - Çizilen rakamları anında tanır
- 📈 **Görselleştirmeler** - Eğitim grafikleri ve tahmin sonuçları

---

## 🚀 Hızlı Başlangıç

### Otomatik Kurulum (Önerilen) 🎯

**macOS/Linux:**
```bash
cd digit-ai-classifier
./setup.sh
```

Script otomatik olarak:
- ✅ Sanal ortam oluşturur
- ✅ Bağımlılıkları yükler  
- ✅ Kurulumu test eder
- ✅ Sonraki adımları gösterir

### Manuel Kurulum

### 1️⃣ Projeyi İndir

Eğer GitHub'dan klonladıysanız:
```bash
git clone https://github.com/<username>/digit-ai-classifier.git
cd digit-ai-classifier
```

### 2️⃣ Sanal Ortam Oluştur

**macOS/Linux:**
```bash
python3 -m venv venv
source venv/bin/activate
```

**Windows:**
```bash
python -m venv venv
venv\Scripts\activate
```

### 3️⃣ Bağımlılıkları Yükle

```bash
pip install --upgrade pip setuptools wheel
pip install -r requirements.txt
```

⚠️ **Not:** TensorFlow kurulumu 5-10 dakika sürebilir.

### 4️⃣ Modeli Eğit

```bash
python src/train_model.py
```

Bu işlem:
- 📥 MNIST veri setini otomatik indirir
- 🏗️ CNN modelini eğitir (~5-10 dakika)
- 📊 Eğitim grafiklerini oluşturur
- 💾 Modeli `saved_models/mnist_cnn.h5` olarak kaydeder

### 5️⃣ Web Uygulamasını Başlat

```bash
streamlit run app/streamlit_app.py
```

🌐 Tarayıcınızda `http://localhost:8501` adresini açın ve rakam çizmeye başlayın! 🎉

---

## 📁 Proje Yapısı

```
digit-ai-classifier/
├── 📂 data/                          # Veri ve grafikler
│   ├── training_history.png         # Eğitim grafikleri
│   ├── confusion_matrix.png         # Confusion matrix
│   └── per_class_accuracy.png       # Sınıf bazlı doğruluk
│
├── 📂 notebooks/                     # Jupyter Notebook'lar
│   └── 01_explore_mnist.ipynb       # Veri keşfi ve görselleştirme
│
├── 📂 src/                           # Kaynak kodlar
│   ├── train_model.py               # Model eğitimi
│   ├── evaluate_model.py            # Model değerlendirme
│   └── predict_digit.py             # Tekil tahmin
│
├── 📂 app/                           # Streamlit uygulaması
│   └── streamlit_app.py             # Web arayüzü
│
├── 📂 saved_models/                  # Eğitilmiş modeller
│   ├── mnist_cnn.h5                 # Final model
│   └── mnist_cnn_best.h5            # En iyi checkpoint
│
├── requirements.txt                  # Python bağımlılıkları
├── .gitignore                        # Git ignore kuralları
└── README.md                         # Bu dosya
```

---

## 🛠️ Kullanım

### 📊 Model Değerlendirme

```bash
python src/evaluate_model.py
```

**Çıktılar:**
- Test doğruluğu ve loss
- Confusion matrix
- Sınıf bazlı performans grafikleri
- Yanlış tahmin edilen örnekler

### 🔮 Tekil Görüntü Tahmini

**MNIST test setinden rastgele:**
```bash
python src/predict_digit.py
```

**Kendi görüntünle:**
```bash
python src/predict_digit.py --image path/to/your/image.png
```

### 📓 Jupyter Notebook

```bash
jupyter notebook notebooks/01_explore_mnist.ipynb
```

MNIST veri setini keşfetmek ve görselleştirmek için.

---

## 🧠 Model Mimarisi

```
Model: Sequential CNN
_________________________________________________________________
Layer (type)                 Output Shape              Params
=================================================================
conv2d (Conv2D)             (None, 26, 26, 32)        320
max_pooling2d (MaxPooling)  (None, 13, 13, 32)        0
conv2d_1 (Conv2D)           (None, 11, 11, 64)        18,496
max_pooling2d_1 (MaxPool)   (None, 5, 5, 64)          0
conv2d_2 (Conv2D)           (None, 3, 3, 128)         73,856
flatten (Flatten)           (None, 1152)              0
dense (Dense)               (None, 128)               147,584
dropout (Dropout)           (None, 128)               0
dense_1 (Dense)             (None, 10)                1,290
=================================================================
Total params: 241,546
Trainable params: 241,546
```

**Katmanlar:**
- 3x Convolutional katman (32, 64, 128 filtre)
- 2x Max Pooling katman
- 1x Flatten katman
- 2x Dense katman (128, 10 nöron)
- 1x Dropout katman (%50)

**Optimizasyon:**
- Optimizer: Adam
- Loss: Sparse Categorical Crossentropy
- Metrics: Accuracy

---

## 📈 Sonuçlar

| Metrik | Değer |
|--------|-------|
| **Test Accuracy** | %98.5+ |
| **Test Loss** | 0.045 |
| **Eğitim Süresi** | ~5-10 dakika |
| **Model Boyutu** | ~950 KB |

### Sınıf Bazlı Performans

Tüm rakamlar (0-9) için %97+ doğruluk oranı.

---

## 🎨 Streamlit Uygulaması Özellikleri

✨ **Ana Özellikler:**
- 🖌️ Çizim tuvali (canvas)
- 🔮 Gerçek zamanlı tahmin
- 📊 Olasılık dağılımı grafikleri
- 🎯 Güven skoru gösterimi
- ⚙️ Model seçimi (best/final)
- 🖌️ Ayarlanabilir fırça kalınlığı

---

## 📦 Teknolojiler

- **Python 3.8+** - Programlama dili
- **TensorFlow 2.13** - Derin öğrenme framework'ü
- **Keras** - Yüksek seviye neural network API
- **Streamlit** - Web uygulaması framework'ü
- **OpenCV** - Görüntü işleme
- **Matplotlib & Seaborn** - Görselleştirme
- **NumPy & Pandas** - Veri işleme
- **Scikit-learn** - Metrikler ve değerlendirme

---

## 🔧 Geliştirme

### Yeni Özellikler Eklemek

1. **Özel veri seti** ile eğitim
2. **Transfer learning** ile daha iyi performans
3. **Model karşılaştırma** (CNN vs Dense vs SVM)
4. **Mobile deployment** (TensorFlow Lite)
5. **Web deployment** (Streamlit Cloud, HuggingFace Spaces)

### Katkıda Bulunma

1. Fork yapın
2. Feature branch oluşturun (`git checkout -b feature/amazing-feature`)
3. Commit yapın (`git commit -m 'Add amazing feature'`)
4. Push yapın (`git push origin feature/amazing-feature`)
5. Pull Request açın

---

## 📝 Lisans

Bu proje MIT Lisansı altında lisanslanmıştır. Detaylar için [LICENSE](LICENSE) dosyasına bakın.

---

## 🙏 Teşekkürler

- [MNIST Database](http://yann.lecun.com/exdb/mnist/) - Veri seti
- [TensorFlow](https://www.tensorflow.org/) - Framework
- [Streamlit](https://streamlit.io/) - Web framework

---

## 📧 İletişim

Sorularınız veya önerileriniz için:
- 🐙 GitHub: [@Can Uzlaş](https://github.com/canuzlas)
- 💼 LinkedIn: [@Can Uzlaş](https://linkedin.com/in/canuzlas)

---

<div align="center">

⭐ Bu projeyi beğendiyseniz yıldız vermeyi unutmayın! ⭐

Made with ❤️ using Python & TensorFlow

</div>