Обновить README.md

README.md

@@ -1,23 +1,23 @@
+````markdown
 # Распознавание образов на Python с использованием CNN
 
 Курсовая работа по дисциплине  
-**«[указать название дисциплины]»**
+**«Программирование»**
 
 ---
 
 ## 📌 Описание проекта
 
-Данный проект представляет собой программную реализацию системы **распознавания образов**  
+Проект представляет собой программную реализацию системы **распознавания образов** (рукописных цифр) с использованием **сверточной нейронной сети (CNN)** на языке **Python**.
-(рукописных цифр) с использованием **сверточной нейронной сети (CNN)** на языке программирования **Python**.
 
-В рамках работы реализовано:
+Реализовано:
-- обучение нейронной сети на датасете **MNIST**,
+- обучение нейронной сети на датасете **MNIST** (PyTorch + torchvision);
-- сохранение и повторное использование обученной модели,
+- сохранение обученной модели и повторное использование без переобучения;
-- графический пользовательский интерфейс (GUI) на базе **Tkinter**,
+- графический интерфейс **Tkinter** для ввода цифр мышью и получения результата распознавания;
-- визуализация результатов обучения (графики, метрики),
+- предобработка пользовательского ввода (поиск отдельных цифр на холсте, приведение к 28×28);
-- демонстрация процесса распознавания пользовательского ввода.
+- сохранение метрик и графиков обучения (**accuracy/loss**) и логов обучения.
 
-Проект разработан в рамках выполнения курсовой работы и предназначен для учебных и демонстрационных целей.
+Проект предназначен для учебных и демонстрационных целей в рамках курсовой работы.
 
 ---
 
@@ -38,10 +38,10 @@
 
 ## 🧠 Используемые технологии
 
-- **Язык программирования:** Python 3
+- **Язык программирования:** Python 3.10+ (рекомендуется 3.11)
-- **Машинное обучение:** PyTorch
+- **Машинное обучение:** PyTorch, torchvision
-- **Нейронные сети:** сверточная нейронная сеть (CNN)
+- **Нейронные сети:** CNN (сверточная нейронная сеть)
-- **Графический интерфейс:** Tkinter
+- **GUI:** Tkinter
 - **Обработка изображений:** Pillow
 - **Визуализация:** Matplotlib
 
@@ -49,20 +49,177 @@
 
 ## 🗂 Структура проекта
 
+> Важно: рабочие файлы находятся в папке `src/`, а `.gitignore` расположен в корне репозитория.
+
 ```text
 raspoznavanie-obrazov-python-cnn/
 │
-├── app.py                # Графический интерфейс (Tkinter)
+├── .gitignore
-├── model.py              # Архитектура CNN
+├── README.md
-├── train.py              # Обучение модели и сохранение артефактов
+└── src/
-├── preprocess.py         # Предобработка изображений
+    ├── app.py                # GUI (Tkinter): рисование и распознавание
-├── utils.py              # Вспомогательные функции (логирование, графики)
+    ├── model.py              # Архитектура CNN
-├── requirements.txt      # Зависимости проекта
+    ├── train.py              # Обучение модели и сохранение артефактов
-│
+    ├── preprocess.py         # Предобработка изображений (холст -> тензор MNIST)
-├── artifacts/            # Результаты обучения
+    ├── utils.py              # Утилиты (логирование, сохранение метрик/графиков)
-│   ├── mnist_cnn.pt      # Обученная модель
+    ├── test_cuda.py          # Проверка доступности CUDA (опционально)
-│   ├── metrics.json      # Метрики обучения
+    ├── requirements.txt      # Зависимости проекта
-│   ├── training_plot.png # График loss и accuracy
+    │
-│   └── train.log         # Лог обучения
+    ├── artifacts/            # Результаты обучения (создаётся автоматически)
-│
+    │   ├── mnist_cnn.pt       # Обученная модель (веса)
-└── data/                 # Данные MNIST (загружаются автоматически)
+    │   ├── metrics.json       # Метрики обучения
+    │   ├── training_plot.png  # График loss и accuracy
+    │   ├── train.log          # Лог обучения
+    │   └── last_debug.png     # Отладочный пример 28x28 (последний ввод)
+    │
+    └── data/                  # Датасет MNIST (скачивается автоматически)
+````
+
+---
+
+## ⚙️ Установка и запуск
+
+### 1) Клонирование репозитория
+
+```bash
+git clone <URL_репозитория>
+cd raspznavanie-obrazov-python-cnn
+```
+
+### 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) Плохое распознавание нескольких цифр
+
+Пишите цифры **раздельно** и не соединяйте их штрихами.
+Алгоритм выделяет цифры как отдельные связные компоненты.
+
+---
+
+## 📄 Лицензия
+
+Проект выполнен в учебных целях.
+
+```
+```