# Распознавание образов на Python с использованием CNN

Курсовая работа по дисциплине  
**«Программирование»**

---

## 📌 Описание проекта

Проект представляет собой программную реализацию системы **распознавания образов** (рукописных цифр) с использованием **сверточной нейронной сети (CNN)** на языке **Python**.

Реализовано:
- обучение нейронной сети на датасете **MNIST** (PyTorch + torchvision);
- сохранение обученной модели и повторное использование без переобучения;
- графический интерфейс **Tkinter** для ввода цифр мышью и получения результата распознавания;
- предобработка пользовательского ввода (поиск отдельных цифр на холсте, приведение к 28×28);
- сохранение метрик и графиков обучения (**accuracy/loss**) и логов обучения.

Проект предназначен для учебных и демонстрационных целей в рамках курсовой работы.

---

## 🎯 Цель и задачи работы

### Цель работы
Разработка программного приложения для распознавания образов с применением методов машинного обучения и нейронных сетей на языке Python.

### Задачи работы
- изучить теоретические основы распознавания образов;
- рассмотреть архитектуру сверточных нейронных сетей;
- реализовать CNN-модель для распознавания рукописных цифр;
- обучить модель на наборе данных MNIST;
- разработать графический интерфейс пользователя;
- провести тестирование и анализ результатов распознавания.

---

## 🧠 Используемые технологии

- **Язык программирования:** Python 3.10+ (рекомендуется 3.11)
- **Машинное обучение:** PyTorch, torchvision
- **Нейронные сети:** CNN (сверточная нейронная сеть)
- **GUI:** Tkinter
- **Обработка изображений:** Pillow
- **Визуализация:** Matplotlib

---

## 🗂 Структура проекта

> Важно: рабочие файлы находятся в папке `src/`, а `.gitignore` расположен в корне репозитория.

```text
raspoznavanie-obrazov-python-cnn/
│
├── .gitignore
├── README.md
└── src/
    ├── app.py                # GUI (Tkinter): рисование и распознавание
    ├── model.py              # Архитектура CNN
    ├── train.py              # Обучение модели и сохранение артефактов
    ├── preprocess.py         # Предобработка изображений (холст -> тензор MNIST)
    ├── utils.py              # Утилиты (логирование, сохранение метрик/графиков)
    ├── test_cuda.py          # Проверка доступности CUDA (опционально)
    ├── requirements.txt      # Зависимости проекта
    │
    ├── artifacts/            # Результаты обучения (создаётся автоматически)
    │   ├── mnist_cnn.pt       # Обученная модель (веса)
    │   ├── metrics.json       # Метрики обучения
    │   ├── training_plot.png  # График loss и accuracy
    │   ├── train.log          # Лог обучения
    │   └── last_debug.png     # Отладочный пример 28x28 (последний ввод)
    │
    └── data/                  # Датасет MNIST (скачивается автоматически)


---

## ⚙️ Установка и запуск

### 1) Клонирование репозитория

```bash
git clone <URL_репозитория>
cd coursework-image-recognition-python
```

### 2) Создание виртуального окружения

**Windows (PowerShell):**

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
```

**Windows (cmd):**

```bat
python -m venv .venv
.\.venv\Scripts\activate.bat
```

**Linux / macOS:**

```bash
python3 -m venv .venv
source .venv/bin/activate
```

### 3) Установка зависимостей

> Файл `requirements.txt` находится в `src/`.

```bash
pip install -r src/requirements.txt
```

---

## ▶️ Запуск приложения (GUI)

Запускать можно из корня репозитория или из папки `src/`.

### Вариант A (из корня репозитория)

```bash
python src/app.py
```

### Вариант B (из папки src)

```bash
cd src
python app.py
```

---

## 🏋️ Обучение и переобучение модели

### Автоматически при первом запуске

Если файла модели нет (`src/artifacts/mnist_cnn.pt`), приложение автоматически запустит обучение при первом старте.

### Переобучение из интерфейса

В GUI есть кнопка **«Переобучить (с аугментацией)»**, которая запускает обучение заново и сохраняет новую модель.

### Ручной запуск обучения (без GUI)

**Из корня:**

```bash
python src/train.py
```

**Из папки `src/`:**

```bash
cd src
python train.py
```

После обучения результаты сохраняются в:

* `src/artifacts/mnist_cnn.pt` — веса модели;
* `src/artifacts/metrics.json` — метрики обучения;
* `src/artifacts/training_plot.png` — график `loss` и `accuracy`;
* `src/artifacts/train.log` — лог обучения.

---

## 🧾 Как пользоваться приложением

1. Запустите `app.py`.
2. Нарисуйте на холсте **одну или несколько цифр**.
3. Пишите цифры **раздельно**, чтобы алгоритм корректно выделил их как отдельные компоненты.
4. Нажмите **«Распознать число»**.
5. Результат появится справа:

   * крупно — итоговая строка (например, `12`);
   * ниже — уверенность по каждой цифре.

Кнопка **«Очистить»** сбрасывает холст.

---

## ✅ Проверка CUDA (опционально)

Если у Вас есть видеокарта NVIDIA и установлен CUDA, можно проверить доступность:

```bash
python src/test_cuda.py
```

---

## 🛠 Типовые проблемы и решения

### 1) `ModuleNotFoundError: No module named ...`

Запускайте скрипты одним из корректных способов:

* `python src/app.py` из корня репозитория;
* `cd src` и `python app.py`.

### 2) Долго скачивается MNIST

При первом обучении `torchvision` скачает MNIST в `src/data/`. Это нормально.

### 3) Плохое распознавание нескольких цифр

Пишите цифры **раздельно** и не соединяйте их штрихами.
Алгоритм выделяет цифры как отдельные связные компоненты.

---

## 📄 Лицензия

Проект выполнен в учебных целях.

```
```