knee_seg

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/CMD

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

---

3) Первичная установка (одна команда)

Запустите установочный скрипт:

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 и запустите снова:

chcp 65001
scripts\setup.cmd

---

4) Запуск приложения

Вариант 1 — скриптом (дабл-клик по файлу):

scripts\run_app.cmd

Вариант 2 — напрямую из venv:

.\.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, можно поставить инструменты разработчика (линтеры, тесты):

.\.venv\Scripts\pip.exe install -e .[dev]

Рекомендованные инструменты: pytest, ruff, mypy.

---

7) Типовые команды

# активация 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 можно переконвертировать:

  (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) Чистка окружения

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