Руководство разработчика PlacePix

Что такое PlacePix?

PlacePix — это сервис самостоятельно размещённых изображений placeholder, созданный для разработчиков и дизайнерских команд. В отличие от сторонних сервисов placeholder, требующих внешних сетевых вызовов и могущих исчезнуть, PlacePix работает полностью на вашей собственной инфраструктуре. Поместите изображения в папки и мгновенно получите URL конечные точки, которые предоставляют изменённые по размеру, отфильтрованные и отформатированные изображения.

Сервис написан на Python с использованием FastAPI с обработкой изображений на базе Pillow и OpenCV. Поддерживает развёртывание Docker и совместимое с S3 объектное хранилище.

Возможности

• Нулевая конфигурация — поместите изображения в папки и начните
• Обрезка с распознаванием лиц — OpenCV обнаруживает и центрирует лица
• Градиентные и SVG плейсхолдеры — изображения не требуются
• Пресеты для социальных сетей — встроенные размеры Instagram, YouTube, TikTok
• Поиск по цвету — найдите изображения, соответствующие палитре вашего бренда
• Буквенные аватары — детерминистичные изображения профилей из имён

Руководство по развёртыванию Docker

Самый быстрый способ запустить PlacePix — с помощью Docker. Одна команда развёртывает весь сервис с умным сканированием, извлечением цветов и встроенным конструктором URL.

Развёртывание одной строкой

docker run -d -p 3000:3000 \
  -v ./images:/app/images \
  riadvice/placepix:latest

Docker Compose (Рекомендуется)

services:
  placepix:
    image: riadvice/placepix:latest
    ports:
      - "3000:3000"
    volumes:
      - ./images:/app/images
      - ./data:/app/data
    environment:
      - HOST=0.0.0.0:3000
      - UPLOAD_ENABLED=true
      - WATERMARK_ENABLED=false
    restart: unless-stopped

Постоянные данные и окружение

Смонтируйте как /app/images (ваша библиотека изображений), так и /app/data (кэш сканирования и метаданные), чтобы сохранить состояние при перезапуске контейнера. Настройте поведение через переменные окружения или файл .env.

OVHcloud S3-совместимое хранилище

PlacePix поддерживает любой S3-совместимый бэкенд. Для OVHcloud Object Storage установите:

S3_ENABLED=true
S3_ENDPOINT=https://s3.rbx.io.cloud.ovh.net
S3_ACCESS_KEY=your-key
S3_SECRET_KEY=your-secret
S3_BUCKET=your-bucket
S3_REGION=rbx

Умная обрезка с распознаванием лиц

Стандартная центральная обрезка может разрезать лица на портретной фотографии. PlacePix решает это с помощью умной обрезки с распознаванием лиц, работающей на каскадах Хаара OpenCV.

Как это работает

Когда запрос включает ?fit=smart, PlacePix сканирует изображение на наличие человеческих лиц с помощью OpenCV. Если лица обнаружены, окно обрезки смещается так, чтобы центроид лица находился как можно ближе к точкам пересечения золотого сечения. Если лица не найдены, происходит откат к стандартной центральной обрезке.

Примеры API

# Обрезка с распознаванием лиц (обнаруживает и центрирует лица)
/400/300/people?fit=smart

# Стандартная центральная обрезка
/400/300/people?fit=crop

# Заполнение обложки (может растянуть)
/400/300/people?fit=cover

# Содержание (letterboxing)
/400/300/people?fit=contain

Когда использовать умную обрезку

• Портретная фотография и снимки головы
• Страницы команды, где лица важны
• Миниатюры для социальных сетей
• Любой сценарий, где геометрическая центральная обрезка портит композицию

API градиентных плейсхолдеров

Генерируйте линейные и радиальные градиентные изображения на лету без загрузки ресурсов. Идеально для фонов hero, состояний загрузки и дизайнерских макетов.

Синтаксис эндпоинта

/gradient/{width}/{height}/{from_hex}/{to_hex}

Примеры

# Простой линейный градиент (сверху вниз)
/gradient/800/400/3b82f6/10b981

# Градиент под углом 45 градусов
/gradient/800/400/e11d48/f59e0b?angle=45

# Радиальный градиент от центра
/gradient/800/400/1e293b/64748b?gradient_type=radial

# С выходным форматом
/gradient/800/400/0ea5e9/ffffff?format=webp&quality=80

Справочник параметров

• {from_hex} / {to_hex} — hex цвета без префикса #
• ?angle=45 — линейный угол в градусах (0-360)
• ?gradient_type=radial — переключает на радиальный градиент
• ?format=webp — выход WebP (меньший размер файла)

Генератор SVG-плейсхолдеров

SVG-плейсхолдеры не требуют серверной обработки изображений. Они генерируются как inline SVG с настраиваемым цветом фона, цветом переднего плана и текстовой меткой.

Эндпоинт

/svg/{width}/{height}?bg={hex}&fg={hex}&text={label}

Примеры

# Плейсхолдер wireframe по умолчанию
/svg/400/300

# Пользовательские цвета бренда
/svg/400/300?bg=1c1917&fg=0ea5e9

# С пользовательским текстом
/svg/400/300?bg=0ea5e9&fg=ffffff&text=Hero+Section

Почему SVG?

• Размер файла менее 500 байт
• Бесконечно масштабируем без потери качества
• Нулевая серверная обработка
• Идеально для wireframes и прототипов с низкой точностью

Пресеты для социальных сетей

PlacePix включает предопределённые размеры для популярных социальных платформ и размеров экранов. Используйте их для генерации идеально подходящих по размеру изображений placeholder для Instagram, YouTube, TikTok, LinkedIn, X (Twitter) и стандартных дисплеев.

Instagram

/preset/instagram-square/nature     # 1080x1080
/preset/instagram-portrait/nature  # 1080x1350
/preset/instagram-story/nature     # 1080x1920

YouTube

/preset/youtube-thumbnail/nature   # 1280x720
/preset/youtube-banner/nature      # 2560x423

TikTok

/preset/tiktok-video/nature        # 1080x1920 (9:16)

LinkedIn

/preset/linkedin-post/nature       # 1200x627

X (Twitter)

/preset/twitter-header/nature      # 1500x500

Размеры экранов

/preset/mobile/nature              # 375x812
/preset/tablet/nature              # 768x1024
/preset/desktop/nature             # 1920x1080
/preset/4k/nature                  # 3840x2160

Сценарий использования Long-Tail: Instagram Story API

Если вы создаёте инструмент управления социальными сетями и вам нужны изображения placeholder размера Instagram Story, используйте /preset/instagram-story/{category}. Комбинируйте с ?fit=smart для портретных фото и ?format=webp&quality=70 для оптимизированной доставки.

API поиска по цвету

Каждое изображение в PlacePix сканируется на наличие 3 доминирующих цветов. Вы можете искать всю библиотеку по hex цвету, чтобы найти изображения, соответствующие палитре вашего бренда.

Эндпоинты

# Получить изображение, соответствующее конкретному hex цвету
/color/0ea5e9/400/300

# Отфильтровать любой эндпоинт по доминирующему цвету
/400/300/nature?color=d97706

# Список всех изображений, соответствующих цвету
/api/color/3b82f6

How Color Scanning Works

При запуске PlacePix извлекает наиболее частые цвета из каждого изображения, используя кластеризацию k-means в цветовом пространстве LAB. Это даёт перцептивно точные совпадения, а не сырые RGB средние значения. Страница палитры (/palette) визуализирует эти цветы и позволяет просматривать по категориям оттенков.

Фильтрация по ориентации

Фильтруйте случайные изображения по их исходному соотношению сторон перед выбором. Это полезно, когда вам нужны изображения, которые естественно подходят для макета — альбомная для заголовков, портретная для карточек или квадратная для миниатюр.

Конечные точки

# Landscape images (width > height)
/400/300?orientation=landscape

# Portrait images (height > width)
/400/300?orientation=portrait

# Squarish images (within 15% of 1:1 by default)
/400/300?orientation=squarish

# Combined with other filters
/400/300/nature?orientation=landscape&seed=spring
/color/0ea5e9/400/300?orientation=portrait
/api/color/3b82f6?orientation=landscape

Конфигурация

Допуск squarish настраивается через переменную окружения ORIENTATION_SQUARISH_TOLERANCE (по умолчанию: 0.15). Значение 0.15 означает, что изображения с соотношением сторон между 0.85 и 1.15 считаются квадратными. Установите 0.0 для строго 1:1.

Как это работает

PlacePix считывает размеры изображений из заголовков файлов во время начального сканирования (локальные файлы) и во время фонового сканирования метаданных (изображения S3). Размеры хранятся в памяти и используются для фильтрации пула кандидатов перед случайным или детерминированным выбором. Если запрошена ориентация, но нет подходящих изображений, возвращается 404.

Фильтры и эффекты

Применяйте фильтры и эффекты в реальном времени к любому изображению через параметры запроса. Вся обработка выполняется на стороне сервера и кэшируется для последующих запросов.

Корректировка цвета

?grayscale=1               # Чёрно-белое
?sepia=1                   # Тёплый сепия тон
?tint=0ea5e9               # Hex наложение цвета
?brightness=1.3            # 0,0 до 2,0
?contrast=1.2              # 0,0 до 2,0
?saturation=2.0            # 0,0 до 2,0
?invert=true               # Инвертировать цвета
?posterize=4               # Уровни цвета (1-8)
?duotone=ff0000,0000ff     # Двухцветная карта

Эффекты изображения

?blur=2                    # Размытие по Гауссу (1-10)
?sharpen=1.5               # Уровень резкости
?emboss=true               # 3D рельеф
?edges=sobel               # Обнаружение краёв
?edges=canny               # Края Canny
?halftone=4                # Точечный узор
?oil_painting=true         # Стиль масляной живописи
?pencil_sketch=true        # Карандашный рисунок
?cartoon=true              # Эффект мультфильма
?vignette=0.5              # Затемнение краёв (0-1)

Параметры наложения

?text=Hello+World          # Наложение текста
?border=4,ffffff           # Ширина и цвет рамки
?watermark=1               # Применить настроенный водяной знак
?padding=20                # Внутренний отступ

Генератор Аватаров

Генерируйте детерминированные аватары из любого имени или email. PlacePix поддерживает два типа аватаров: Буквенный аватар (цветные инициалы) и Multiavatar (мультикультурные векторные аватары).

Endpoint

/avatar/{size}/{name}
/avatar/{size}/{name}.{ext}

Параметры

• type — avatar type: letter (default) or multiavatar
• size — pixel size (e.g. 64, 128, 256)
• name — any string; used as seed for the avatar

Буквенный аватар (type=letter)

• circle — crop to a circle shape
• border={width} — добавить рамку
• border_color={hex} — цвет рамки
• bg={hex} — override background color
• fg={hex} — override text/foreground color
• single=true — use only the first letter
• uppercase=false — preserve lowercase letters
• palette={name} — choose from flatui, material, pastel, neon, cool, warm

Multiavatar (type=multiavatar)

• env — include environment background (true by default, false to omit)
• part — specific part code (optional, e.g. 11)
• theme — specific theme code (optional, e.g. C)

Примеры

# Simple 128px letter avatar
/avatar/128/John+Doe

# Circle letter avatar with custom border
/avatar/128/John+Doe?circle=true&border=2&border_color=ffffff

# Single initial, pastel palette
/avatar/64/Alice?single=true&palette=pastel

# SVG letter output (scalable, under 500 bytes)
/avatar/128/John+Doe.svg

# Multiavatar (multicultural vector avatar)
/avatar/128/Binx+Bond?type=multiavatar

# Multiavatar without environment background
/avatar/128/Binx+Bond?type=multiavatar&env=false

# Specific multiavatar version
/avatar/128/Binx+Bond?type=multiavatar&part=11&theme=C

Почему использовать буквенные аватары?

• Нулевые внешние зависимости — никакого Gravatar или сторонних сервисов аватаров
• Детерминированный — одно и то же имя всегда даёт один и тот же цвет
• Поддержка SVG — бесконечно масштабируемый, идеален для HiDPI-дисплеев
• Шесть встроенных цветовых палитр для любой эстетики бренда

Почему использовать Multiavatar?

• 12 миллиардов уникальных мультикультурных аватаров
• Детерминированный — одно и то же имя всегда даёт один и тот же аватар
• Чистый SVG-вывод — маленький размер файла, бесконечно масштабируемый
• Внешние API-вызовы не требуются

Краткий справочник REST API

Все эндпоинты поддерживают CORS и возвращают изображения с заголовками долгосрочного кэширования. Выход Base64 JSON доступен для маленьких миниатюр.

Эндпоинты изображений

• GET /{width}/{height}/{category} — Случайное изображение из категории
• GET /{width}/{height} — Случайное изображение из всех категорий
• GET /id/{id}/{width}/{height} — Конкретное изображение по ID
• GET /ratio/{ratio}/{width}/{category} — Изображение с соотношением сторон
• GET /preset/{preset}/{category} — Пресет для социальных сетей
• GET /color/{hex}/{width}/{height} — Изображение с совпадающим цветом
• GET /gradient/{w}/{h}/{from}/{to} — Градиентное изображение
• GET /svg/{width}/{height} — SVG плейсхолдер
• GET /avatar/{size}/{name} — Буквенный аватар (PNG/SVG)

Эндпоинты метаданных

• GET /api/images — Список категорий и итогов
• GET /api/info/id/{id} — Метаданные изображения (размеры, цвета, формат)
• GET /api/color/{hex} — Изображения, совпадающие с цветом

Эндпоинты здоровья

• GET /health — Проверка работоспособности (Docker/K8s)
• GET /ready — Проверка готовности (503 пока изображения не загружены)

Экспертиза и рекомендации

• Активные участники экосистемы open source с 2008 года
• Весь код с открытым исходным кодом под лицензией MIT и доступен для аудита на GitHub

Часто задаваемые вопросы

Как развернуть PlacePix с помощью Docker?

Запустите docker run -d -p 3000:3000 -v ./images:/app/images riadvice/placepix:latest. Смонтируйте вашу папку с изображениями, и сервис запустится немедленно с включённым умным сканированием.

Что такое умная обрезка с распознаванием лиц?

PlacePix использует каскады Хаара OpenCV для обнаружения лиц на изображениях. Когда вы добавляете ?fit=smart к любому URL, область обрезки смещается, чтобы центрироваться на обнаруженных лицах, а не использовать геометрический центр. Если лицо не найдено, происходит откат к стандартной центральной обрезке.

Могу ли я генерировать градиентные плейсхолдеры без загрузки фото?

Да. Эндпоинт /gradient/{width}/{height}/{from}/{to} генерирует градиентные изображения полностью из параметров URL. Загруженные изображения не требуются. Вы также можете создавать SVG плейсхолдеры с /svg/{width}/{height}.

Как генерировать плейсхолдеры размера Instagram Story через API?

Используйте эндпоинт пресета: /preset/instagram-story/{category}. Это возвращает изображение 1080x1920. Комбинируйте с ?format=webp&quality=70 для оптимизированной доставки и ?fit=smart для безопасной обрезки портретов.

Поддерживает ли PlacePix S3-совместимое хранилище объектов?

Да. PlacePix работает с OVHcloud Object Storage, AWS S3, MinIO и любым S3-совместимым провайдером. Настройте эндпоинт, бакет, ключ доступа и секретный ключ через переменные окружения.

Какие форматы вывода поддерживаются?

WebP, AVIF, JPEG, PNG, SVG и JSON base64. Используйте .webp, .avif или .png как расширение файла, или добавьте ?format=webp как параметр запроса. AVIF даёт самые маленькие файлы; PNG без потерь.

PlacePix бесплатен для коммерческого использования?

Да. PlacePix выпущен под лицензией MIT и бесплатен как для личного, так и для коммерческого использования. Поскольку он self-hosted, нет ограничений по использованию, API ключей и оплаты за запрос.