Ръководство за разработчици на PlacePix

Какво е PlacePix?

PlacePix е услуга за самостоятелно хоствани placeholder изображения, създадена за разработчици и дизайнерски екипи. За разлика от услугите за placeholder изображения от трети страни, които изискват външни мрежови повиквания и могат да изчезнат, PlacePix работи изцяло на ваша собствена инфраструктура. Поставете изображения в папки и незабавно получавайте URL крайни точки, които предоставят преоразмерени, филтрирани и форматирани изображения.

Услугата е написана на Python с FastAPI с обработка на изображения от Pillow и OpenCV. Поддържа разгръщане с Docker и съвместимо с S3 обектно хранилище.

Характеристики

• Нулева конфигурация — поставете изображения в папки и започнете
• Изрязване с разпознаване на лица — OpenCV открива и центрира лица
• Градиентни и SVG placeholder изображения — не се изискват изображения
• Предварителни настройки за социални медии — вградени размери за 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 поддържа всеки backend, съвместим с 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 Haar каскади.

Как работи

Когато заявка включва ?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 за градиентни placeholder изображения

Генерирайте линейни и радиални градиентни изображения на момента, без да качвате ресурси. Перфектно за геройски фонове, състояния на зареждане и дизайнерски макети.

Синтаксис на крайна точка

/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 placeholder изображения

SVG placeholder изображенията не изискват сървърна обработка на изображения. Генерират се като inline SVG с персонализируем цвят на фона, цвят на преден план и текстов етикет.

Крайна точка

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

Примери

# Стандартно placeholder изображение с wireframe
/svg/400/300

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

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

Защо SVG?

• Размер на файла под 500 байта
• Безкрайно мащабируем без загуба на качество
• Нулева сървърна обработка
• Перфектно за wireframe и прототипи с ниска точност

Предварителни настройки за социални медии

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

Дългоопашат сценарий: Instagram Story API

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

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

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

Крайни точки

# 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.

API за търсене по цвят

Всяко изображение в PlacePix се сканира за неговите 3 доминиращи цвята. Можете да търсите цялата библиотека по hex цвят, за да намерите изображения, които съвпадат с вашата цветова палитра.

Крайни точки

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

# Филтриране на всяка крайна точка по доминиращ цвят
/400/300/nature?color=d97706

# Списък на всички изображения, съвпадащи с цвят
/api/color/3b82f6

Как работи сканирането на цветове

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

Филтри и ефекти

Прилагайте филтри и ефекти в реално време към всяко изображение чрез параметри на заявката. Цялата обработка се извършва от страна на сървъра и се кешира за следващи заявки.

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

?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                    # Gaussian размиване (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                # Вътрешен отстъп

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

Генерирайте детерминистични аватари от всяко име или имейл. PlacePix поддържа два типа аватари: Буквен аватар (цветни инициали) и Multiavatar (мултикултурни векторни аватари).

Крайна точка

/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 placeholder изображение
• 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 докато изображенията се заредят)

Опит и квалификации

• Активни сътрудници в екосистемата с отворен код от 2008 г.
• Целият код е с отворен код под MIT лиценз и може да бъде проверен в GitHub

Често задавани въпроси

Как да разположа PlacePix с Docker?

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

Какво е интелигентното изрязване с разпознаване на лица?

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

Can I generate gradient placeholder images without uploading photos?

Да. Крайната точка /gradient/{width}/{height}/{from}/{to} генерира градиентни изображения изцяло от URL параметри. Не се изискват качени изображения. Можете също да създадете SVG placeholder изображения с /svg/{width}/{height}.

How do I generate Instagram story size placeholder images via 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 и base64 JSON. Използвайте .webp, .avif или .png като файлово разширение, или добавете ?format=webp като параметър на заявката. AVIF произвежда най-малките файлове; PNG е без загуба.

PlacePix безплатен ли е за търговска употреба?

Да. PlacePix е публикуван под MIT лиценз и е безплатен както за лична, така и за търговска употреба. Тъй като е самостоятелно хостван, няма ограничения за употреба, няма API ключове и няма таксуване на заявка.