coursework-image-recognition-python/README.md

# Распознавание образов на 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) Клонирование репозитория

git clone <URL_репозитория>
cd raspznavanie-obrazov-python-cnn

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

Windows (PowerShell):

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

Windows (cmd):

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

Linux / macOS:

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

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

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

pip install -r src/requirements.txt

---

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

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

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

python src/app.py

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

cd src
python app.py

---

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

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

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

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

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

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

Из корня:

python src/train.py

Из папки src/:

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, можно проверить доступность:

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) Плохое распознавание нескольких цифр

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

---

📄 Лицензия

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