# HVideoTool

Десктопная утилита с графическим интерфейсом для **обнаружения уже наложенной
цензуры** (мозаика, пикселизация, размытие, чёрные плашки) на **картинках**.
Открываете папку с изображениями (или раскадровываете ролик кнопкой «Создать из
ролика…») — приложение прогоняет каждый кадр через детектор, **обводит найденные
области** и показывает **подробный список** того, что нашлось на каждой картинке.
Отобранные кадры можно перемещать в **коллекции** (для сбора датасета/примеров).

> Инструмент для просмотра, отладки детекции и отбора кадров. Видео раскадровывает
> через ffmpeg (ставится автоматически с пакетом `imageio-ffmpeg`; системный ffmpeg
> из PATH используется в приоритете), либо через OpenCV.

---

## Возможности

- **Создать из ролика…** — раскадровка видео в папку-коллекцию. Два режима:
  **только ключевые кадры** (в разы быстрее — декодируются лишь I-кадры) и
  **каждый N-й кадр**; опциональный даунскейл (меньше файлов и нагрузки на диск/АВ).
  ffmpeg идёт в комплекте (`imageio-ffmpeg`); системный ffmpeg из PATH — в приоритете.
- **Коллекции**: «Создать коллекцию…» + «В коллекцию» (Ctrl+M) перемещает выбранные
  кадры в активную папку-коллекцию (мультивыбор поддерживается).
- **Открыть папку** с картинками (`.jpg/.png/.bmp/.webp/.tif`) — список слева.
- Картинка с **обводкой контуром** найденных областей — по центру.
- **Подробная таблица детекций** справа: тип, уверенность, bbox, число точек
  полигона. Выбор строки **подсвечивает** конкретную область на картинке.
- **Ленивая детекция**: картинка прогоняется при первом открытии, результат
  кэшируется. Кнопка **«Детектировать все»** обходит всю папку.
- Переключение **детектора** (`classic` / `yolo` / `combined`) и **порога**
  уверенности прямо в тулбаре — удобно сравнивать.
- Выбор файла весов модели кнопкой **«Модель…»**.

## Восстановление (расцензуривание)

Кнопка **«Расцензурить кадр»** восстанавливает найденные области на текущем кадре,
**«Показать оригинал/результат»** переключает вид, **«Сохранить результат»** пишет
`<имя>_restored.jpg` (в активную коллекцию или рядом с кадром).

> ⚠️ Сейчас движок восстановления — **инпейнт (cv2)**: он *заполняет* область по
> окружению, но **не реконструирует** скрытые детали (замазывает, а не раскрывает).
> Настоящее восстановление мозаики требует генеративной модели (DeepMosaics или
> [LADA](https://github.com/ladaapp/lada) на BasicVSR++) и **GPU NVIDIA/CUDA**; на
> аниме качество таких моделей ограничено. Движок подключается через интерфейс
> `core/restore/base.Restorer` (`build_restorer`) — инпейнт сейчас стоит заглушкой.

## Что НЕ делает (осознанно вне области задачи)

- Не **генерирует** изображения через диффузию (никакого ControlNet/SDXL).
- Не детектирует «контент, который следовало бы зацензурить» (NSFW) — ищем
  именно **уже наложенную** цензуру.
- Полноценное генеративное восстановление пока не подключено (см. выше).

---

## Требования

- **ОС:** Windows 11 x64 (основная целевая платформа).
- **Python:** 3.11+.
- **GPU (опционально):** NVIDIA + CUDA для YOLO-детектора. CPU-режим работает, но
  медленный. Для `classic` детектора ни torch, ни GPU не нужны.

## Установка

```powershell
git clone https://github.com/mrleo1nid/HVideoTool.git
cd HVideoTool
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .
```

Этого достаточно для `classic` детектора — **PyTorch/CUDA не требуются**. Они
нужны только для YOLO/комбинированного детектора (см.
[Модель детектора](#модель-детектора)).

## Запуск

```powershell
# Без аргументов — папку открываете в приложении (тулбар → «Открыть папку…»)
python -m hvideotool

# Необязательно: сразу открыть папку / переопределить детектор и модель
python -m hvideotool "C:\path\to\images" --detector yolo --model models\lada_mosaic_detection_model_v4_accurate.pt
```

Выбор детектора, путь к модели и порог сохраняются в `~/HVideoTool/settings.json`
и применяются при следующем запуске.

---

## Модель детектора

Интерфейс детектора абстрагирован (`core/detection/base.py`), детектор
выбирается в тулбаре (или флагом `--detector`):

- `classic` — эвристический classic-CV детектор (`core/detection/classic_cv.py`).
  Различает `mosaic` / `blur` / `black_bar`, без весов и без GPU.
  **Приблизительный**: на реальном видео даёт много ложных срабатываний, заточен
  скорее под рисованный/аниме контент — но и там ненадёжен.
- `yolo` — ML-детектор на базе [Ultralytics](https://github.com/ultralytics/ultralytics)
  (`core/detection/yolo.py`). **Сегментационная** модель — маски превращаются в
  контуры. Рекомендуемые веса — [**LADA mosaic detection**](https://huggingface.co/ladaapp/lada).
- `combined` — `CompositeDetector`: YOLO (мозаика) + classic-CV (плашки/размытие),
  результаты объединяются с дедупликацией по IoU.

> **⚠️ Берите правильную модель.** Для YOLO нужна модель **детекции цензуры**
> (LADA `lada_mosaic_detection_model_v4_accurate.pt`). Если по ошибке указать
> обычную COCO-модель (`yolo11n-seg.pt`), она будет детектить людей/предметы и
> помечать их как `unknown` — это и есть «шум». Файл LADA лежит в `models/`.

> **Домен важен.** Модель LADA обучена на **реальном видео** (JAV); на части
> рисованного/аниме контента работает, на части — плохо. Хорошего публичного
> YOLO-детектора цензуры для аниме нет — это потребовало бы обучения своей модели.

**Своя модель мозаики для аниме.** Можно обучить **YOLO11-seg** на синтетике
(накладываем мозаику на чистые кадры → авторазметка) и подключить `.pt` в наш
`YoloDetector` **без изменений кода**. Инструменты — в
[`scripts/training/`](scripts/training/README.md):

```powershell
python scripts\training\gen_mosaic_dataset.py --input C:\clean_frames --output dataset_mosaic
python scripts\training\train_mosaic.py --data dataset_mosaic\data.yaml --epochs 100
# затем: тулбар → Детектор yolo → «Модель…» → runs\segment\mosaic\weights\best.pt
```

Установка YOLO-детектора:

```powershell
pip install -e ".[yolo]"
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

curl.exe -L -o models\lada_mosaic_detection_model_v4_accurate.pt `
  "https://huggingface.co/ladaapp/lada/resolve/main/lada_mosaic_detection_model_v4_accurate.pt?download=true"

python -m hvideotool --detector yolo --model models\lada_mosaic_detection_model_v4_accurate.pt
```

> **⚠️ Лицензия.** Ultralytics YOLO и веса LADA — **AGPL-3.0**. Classic-CV детектор
> от этого свободен.

---

## Архитектура (кратко)

```
hvideotool/
├── __main__.py              # точка входа + CLI (всё опционально)
├── app.py                   # инициализация QApplication
├── config.py                # настройки: пороги детекции, оверлей, детектор/модель
├── settings_store.py        # детектор/модель/порог/последняя папка → settings.json
├── ui/
│   ├── main_window.py       #   окно: список файлов | картинка | таблица детекций
│   └── image_view.py        #   отрисовка картинки + оверлей-контуры (QPainter)
└── core/
    ├── imageio.py           #   unicode-safe чтение/запись картинок (Windows-пути)
    ├── video/frame.py       #   Frame (картинка BGR + индекс + pts) — вход детектора
    └── detection/
        ├── base.py          #   Detector (ABC): detect(frame) -> list[Detection]
        ├── factory.py       #   build_detector(config) -> classic/yolo/combined
        ├── types.py         #   Detection (+ to_dict/from_dict), CensorType
        ├── classic_cv.py    #   эвристический детектор (mosaic/blur/black_bar)
        ├── yolo.py          #   YOLO-детектор (Ultralytics, маски→полигоны)
        └── composite.py     #   CompositeDetector: объединение детекторов
```

Детекция синхронная (по клику/по кнопке «Детектировать все»); тяжёлый YOLO на CPU
заметно медленнее, чем на CUDA.

## Технологический стек

| Компонент            | Выбор                                            |
|----------------------|--------------------------------------------------|
| Язык                 | Python ≥ 3.11                                    |
| GUI                  | PySide6 (Qt 6)                                   |
| Обработка картинок   | OpenCV / NumPy                                   |
| Детектор (без весов) | classic-CV эвристика (без GPU)                   |
| Детектор (ML)        | Ultralytics YOLO + PyTorch/CUDA (LADA)           |

## Лицензия

TBD.