Добавлено описание и документация для HVideoTool, включая функционал, требования, установку и запуск приложения для обнаружения цензуры на изображениях.
This commit is contained in:
Leonid Pershin
@@ -1,2 +1,170 @@
|
||||
# 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`) и **порога**
|
||||
уверенности прямо в тулбаре — удобно сравнивать.
|
||||
- Выбор файла весов модели кнопкой **«Модель…»**.
|
||||
|
||||
## Что НЕ делает (осознанно вне области задачи)
|
||||
|
||||
- Не **удаляет** и не **восстанавливает** зацензуренный контент.
|
||||
- Не **генерирует** изображения (никакого 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.
|
||||
|
||||
Reference in New Issue
Block a user