# KneeSeg — README для разработчика (Windows)

Этот документ объясняет, как быстро развернуть проект у себя на ПК, запускать приложение и вносить изменения. Проект ориентирован на **Windows + Python 3.12.10**, GUI на **PyQt5**. Точка входа: `from knee.app import main; main()`.

---

## 1) Требования
- Windows 10/11 x64
- Python **3.12.10** (желательно из Microsoft Store или с python.org)
- Права на установку пакетов в виртуальное окружение в каталоге проекта
- Git

> Версия Python закреплена в файле `.python-version` (3.12.10).

---

## 2) Клонирование проекта
```powershell
# PowerShell/CMD

cd <projectDir>
git clone https://git.physics.itmo.ru/nikita.babich/knee_seg
cd knee_seg
```

---

## 3) Первичная установка (одна команда)
Запустите установочный скрипт:
```bat
scripts\setup.cmd
```
Что делает скрипт:
1. Создаёт виртуальное окружение `.venv` (если ещё нет).
2. Обновляет `pip/setuptools/wheel` внутри `.venv`.
3. **Сканирует импорты** в `src\` и формирует/обновляет `requirements.in` (скриптом `tools\scan_imports.py`).
4. Ставит проект в режиме **editable**: `pip install -e .`.
5. Ставит зависимости из `requirements.in`.
6. Создаёт/обновляет `requirements.lock.txt` (зафиксированные версии).

Если в выводе консоли видны «кракозябры», переключите кодировку в CMD на UTF‑8 и запустите снова:
```bat
chcp 65001
scripts\setup.cmd
```

---

## 4) Запуск приложения
Вариант 1 — скриптом (дабл-клик по файлу):
```bat
scripts\run_app.cmd
```
Вариант 2 — напрямую из venv:
```powershell
.\.venv\Scripts\python.exe -c "from knee.app import main; main()"
```

---

## 5) Структура проекта (общее)
```
project-root/
├─ src/
│  └─ knee/                  # основной пакет приложения
│     ├─ app.py              # точка входа (main)
│     ├─ ...                 # модули, виджеты, утилиты
├─ tools/
│  └─ scan_imports.py        # сканер импортов → requirements.in
├─ scripts/
│  ├─ setup.cmd / setup.ps1  # автонастройка окружения (Windows)
│  └─ run_app.cmd            # запуск приложения
├─ pyproject.toml            # метаданные проекта и зависимости
├─ requirements.in           # список зависимостей (источник)
├─ requirements.lock.txt     # зафиксированные версии (freeze)
├─ .python-version           # версия Python (3.12.10)
└─ README.md                 # этот документ
```

---

## 6) Рабочий процесс разработки
### 6.1 Изменения в коде
- Работайте в отдельных ветках (`feature/...`, `fix/...`).
- Импорты в коде используйте **пакетные** (пример):
  ```python
  # правильно
  from knee import image_label
  from knee.constants import SOME_CONST

  # избегайте «голых» импортов топ-уровня
  # import image_label
  # from constants import SOME_CONST
  ```
  Так Python и инструменты корректно воспринимают локальные модули, а сканер не добавляет их в зависимости.

### 6.2 Обновление зависимостей
Когда вы добавили импорт новой внешней библиотеки:
```powershell
# пересобрать requirements.in по импортам
.\.venv\Scripts\python.exe tools\scan_imports.py --src src --out requirements.in

# установить обновления
.\.venv\Scripts\pip.exe install -r requirements.in

# обновить lock-файл
.\.venv\Scripts\pip.exe freeze | Out-File -Encoding ascii requirements.lock.txt
```
> Альтернатива: просто снова запустить `scripts\setup.cmd` — он выполнит те же действия автоматически.

### 6.3 Dev-инструменты
Если в `pyproject.toml` определён раздел `[project.optional-dependencies].dev`, можно поставить инструменты разработчика (линтеры, тесты):
```powershell
.\.venv\Scripts\pip.exe install -e .[dev]
```
Рекомендованные инструменты: `pytest`, `ruff`, `mypy`.

---

## 7) Типовые команды
```powershell
# активация venv (сеанс PowerShell)
.\.venv\Scripts\Activate.ps1

# запуск приложения
python -c "from knee.app import main; main()"

# установка зависимостей из requirements.in
pip install -r requirements.in

# полная переустановка редактируемого пакета
pip uninstall -y KneeSeg
pip install -e .

# автогенерация зависимостей по импортам
python tools\scan_imports.py --src src --out requirements.in
```

---

## 8) Решение проблем
- **UnicodeDecodeError при сборке из `pyproject.toml`**: проверьте, что `README.md` сохранён в UTF‑8 без BOM. В PowerShell можно переконвертировать:
  ```powershell
  (Get-Content -Raw -Encoding Unicode README.md) | Set-Content -NoNewline -Encoding utf8 README.md
  ```
- **`No matching distribution found for ...`**: вероятнее всего, локальный модуль попал в `requirements.in`. Удалите его из файла и перегенерируйте зависимости с помощью `tools\scan_imports.py`.
- **Проблемы с PyQt5 на «чистой» системе**: убедитесь, что установлен Visual C++ Redistributable (x64), а также, что приложение запускается из созданного `.venv`.
- **Кракозябры в выводе CMD**: выполните `chcp 65001` перед запуском `scripts\setup.cmd`.

---

## 9) Чистка окружения
```powershell
# деактивация venv
Deactivate
# удаление окружения
Remove-Item -Recurse -Force .venv
# повторная установка
scripts\setup.cmd
```