Анализатор визуальной композиции

Веб-сервис объективной оценки композиции изображений на основе компьютерного зрения и LLM. Принимает изображение и возвращает измеримые метрики композиции (баланс, цветовая гармония, распределение внимания, правило третей, контраст) плюс текстовый разбор от языковой модели.

Ключевой принцип: ИИ работает поверх числовых данных, вычисленных собственным CV-пайплайном, а не «смотрит» на картинку. Инженерная ценность — в анализе изображения, а не в вызове модели.

Архитектура

Трёхзвенная (раздел 2 ТЗ): SPA → REST API → пайплайн обработки.

[1] Загрузка   → [2] CV-анализ → [3] AI-интерпретация → [4] Визуальный отчёт
   (React)        (OpenCV/skimage   (LLM получает JSON     (подсветка зон +
                   /sklearn → JSON)   с числами, не картинку) шкалы + текст)

Граница между фронтом и бэком — JSON-контракт (backend/app/schemas.py), зафиксированный первым (раздел 3 ТЗ).

Стек

Слой	Технология
Фронтенд	React + Vite + Tailwind CSS (Canvas для наложения зон)
Бэкенд / API	Python + FastAPI
CV-обработка	OpenCV + scikit-image + Pillow
Карта внимания	Saliency (спектральный остаток, NumPy FFT)
Палитра	scikit-learn (K-means) в CIELAB
AI-слой	LLM через абстракцию провайдера (заменяем)

Метрики (ядро продукта, раздел 4)

Метрика	Метод
Палитра и гармония	K-means в CIELAB → доминанты → схемы по HSV-углам
Баланс	визуальный вес (яркость+насыщенность+края Собеля) → смещение центра масс
Внимание	saliency спектральным остатком → локальные максимумы → концентрация
Правило третей	попадание горячих точек в узлы/линии сетки третей
Контраст	гистограмма яркости: глобальный разброс + локальный между областями

Все метрики нормированы в 0..1 и проверены на синтетических изображениях с заранее известным результатом → backend/tests/test_metrics.py.

AI-слой (раздел 5)

LLM подключается через абстракцию провайдера (backend/app/ai/provider.py):

• anthropic — облачная модель через API;
• heuristic — детерминированный fallback без сети, выводит разбор прямо из чисел метрик (продукт работает без API-ключа);
• auto (по умолчанию) — облако при наличии ключа, иначе fallback.

Ответ запрашивается строго в JSON-схеме (summary, strengths, improvements), валидируется, при несоответствии — повтор запроса (раздел 5.2: защита от «воды»).

Запуск

Нужны Python 3.13 и Node 20+. Два терминала:

# 1) Бэкенд (создаст venv и поставит зависимости при первом запуске)
./backend/run.sh                       # → http://localhost:8000

# 2) Фронтенд
cd frontend && npm install && npm run dev   # → http://localhost:5173

Откройте http://localhost:5173. Загрузите JPG/PNG — получите полный отчёт. Кнопка «демо-отчёт» показывает интерфейс на моках без бэкенда.

Чтобы включить облачный LLM: cp backend/.env.example backend/.env и вписать ANTHROPIC_API_KEY. Без ключа используется встроенный разбор по числам.

Аккаунты и личный кабинет (F-06 / F-07)

Регистрация и вход — на собственном бэкенде: пароли хешируются bcrypt, сессия держится на JWT. Хранилище — SQLite по умолчанию (файл data/app.db); переход на PostgreSQL — сменой DATABASE_URL, код от драйвера не зависит (см. db.py).

• Анализ доступен и анонимно. Если запрос авторизован (заголовок Authorization: Bearer <token>), разбор сохраняется в историю пользователя.
• В личном кабинете: данные профиля и статистика — число разборов, средние баллы по метрикам, лучший результат, динамика последних разборов.

API

Метод	Путь	Назначение
POST	/api/analyze	загрузка изображения → отчёт по контракту (опц. авторизация)
POST	/api/auth/register	регистрация → JWT
POST	/api/auth/login	вход → JWT
GET	/api/auth/me	текущий пользователь
GET	/api/profile/stats	статистика кабинета (требует авторизации)
GET	/static/saliency/{id}.png	карта заметности
GET	/health	статус + активный LLM-провайдер
GET	/docs	Swagger UI (автодокументация FastAPI)

curl -F "file=@image.jpg;type=image/jpeg" http://localhost:8000/api/analyze

Тесты

backend/.venv/bin/python backend/tests/test_metrics.py

Реализованный объём

Полностью покрыты все требования MUST (раздел 6):

• F-01 загрузка JPG/PNG с валидацией типа/размера;
• F-02 вычисление всех 5 метрик по контракту;
• F-03 наложение зон внимания и сетки третей на изображение (Canvas);
• F-04 шкалы по каждой метрике (0..1);
• F-05 AI-разбор: сильные стороны и рекомендации со ссылками на числа.

Реализованы требования SHOULD: F-06 (регистрация и вход) и F-07 (история разборов и статистика в личном кабинете). Остальные COULD (экспорт, сравнение версий, freemium) в архитектуре предусмотрены, но пока не реализованы.

Структура

backend/
  app/
    schemas.py          # контракт (единый источник истины)
    config.py           # конфигурация (метрики, LLM-провайдер, БД, JWT)
    main.py             # FastAPI: /api/analyze + роутеры
    pipeline/           # CV-ядро: 5 метрик + общая сеточная агрегация
    ai/                 # абстракция LLM + эвристический fallback
    auth/               # регистрация/вход: bcrypt + JWT (security, deps, router)
    db.py, models.py    # SQLAlchemy: User, Analysis
    profile.py          # статистика личного кабинета
    storage.py          # сохранение карт заметности (локально; в проде S3)
    utils.py            # общие хелперы (clamp01, linear_score)
  tests/test_metrics.py # проверка достоверности метрик
frontend/
  src/
    main.jsx, App.jsx   # роутинг (react-router) + AuthProvider
    api.js, mock.js     # клиент API (+auth) и моки (Этап 2 ТЗ)
    auth/AuthContext.jsx# сессия пользователя (JWT в localStorage)
    pages/              # AnalyzerPage, AuthPage, ProfilePage
    components/         # NavBar, Avatar, Uploader, ImageCanvas, MetricsPanel, ...

Автор и лицензия

© 2026 Александр Жучков. Все права защищены.

Проект опубликован для демонстрации (портфолио / производственная практика). Использование, копирование и распространение кода без письменного согласия автора не допускается — подробности в файле LICENSE.