PlacePix Geliştirici Rehberi

PlacePix Nedir?

PlacePix, geliştiriciler ve tasarım ekipleri için oluşturulmuş kendi barındırılan bir yer tutucu görüntü hizmetidir. Harici ağ çağrıları gerektiren ve kaybolabilen üçüncü taraf yer tutucu hizmetlerinin aksine, PlacePix tamamen kendi altyapınızda çalışır. Görüntüleri klasörlere bırakın ve anında yeniden boyutlandırılmış, filtrelenmiş ve formatlanmış görüntüler sunan URL uç noktaları alın.

Hizmet, görüntü işleme Pillow ve OpenCV tarafından desteklenen FastAPI kullanılarak Python'da yazılmıştır. Docker dağıtımını ve S3 uyumlu nesne depolamayı destekler.

Özellikler

• Sıfır yapılandırma — görüntüleri klasörlere bırakın ve başlayın
• Yüz tanımalı kırpma — OpenCV yüzleri algılar ve merkezler
• Gradyan ve SVG yer tutucuları — görüntü gerekmez
• Sosyal medya ön ayarları — Instagram, YouTube, TikTok boyutları dahili
• Renk arama — marka paletinize uyan görüntüleri bulun
• Harf avatarları — isimlerden deterministik profil görüntüleri

Docker Dağıtım Kılavuzu

PlacePix'i çalıştırmanın en hızlı yolu Docker'dır. Tek bir komut, akıllı tarama, renk çıkarma ve gömülü URL oluşturucu ile tüm hizmeti dağıtır.

Tek Satır Dağıtım

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

Docker Compose (Önerilen)

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

Kalıcı Veri ve Ortam

Konteyner yeniden başlatmalarında durumu korumak için hem /app/images (görüntü kitaplığınız) hem de /app/data (tarama önbelleği ve meta veriler) bağlayın. Davranışı ortam değişkenleri veya bir .env dosyası aracılığıyla yapılandırın.

OVHcloud S3 Uyumlu Depolama

PlacePix herhangi bir S3 uyumlu backend'i destekler. OVHcloud Object Storage için şunları ayarlayın:

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

Yüz Algılayan Akıllı Kırpma

Standart orta kırpma, portre fotoğrafçılığında yüzleri kesebilir. PlacePix, OpenCV Haar kaskadlarıyla desteklenen yüz tanımalı akıllı kırpma ile bunu çözer.

Nasıl Çalışır

Bir istek ?fit=smart içerdiğinde, PlacePix OpenCV kullanarak görüntüdeki insan yüzlerini tarar. Yüzler algılanırsa, kırpma penceresi yüz ağırlık merkezinin altın oran kesişim noktalarına olabildiğince yakın olması için kaydırılır. Hiç yüz bulunamazsa, standart orta kırpmaya geri döner.

API Örnekleri

# Yüz tanımalı kırpma (yüzleri algılar ve merkezler)
/400/300/people?fit=smart

# Standart orta kırpma
/400/300/people?fit=crop

# Kapak doldurma (esneyebilir)
/400/300/people?fit=cover

# İçerme (letterboxing)
/400/300/people?fit=contain

Akıllı Kırpma Ne Zaman Kullanılır

• Portre fotoğrafçılığı ve kafa çekimleri
• Yüzlerin önemli olduğu takım sayfaları
• Sosyal medya küçük resimleri
• Geometrik merkez kırpmanın kompozisyonu bozduğu her senaryo

Gradyan Yer Tutucu API

Herhangi bir kaynak yüklemeden anında doğrusal ve radyal gradyan görüntüleri oluşturun. Kahraman arka planları, yükleme durumları ve tasarım maketleri için mükemmel.

Endpoint Sözdizimi

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

Örnekler

# Basit doğrusal gradyan (yukarıdan aşağıya)
/gradient/800/400/3b82f6/10b981

# 45 derecelik açılı gradyan
/gradient/800/400/e11d48/f59e0b?angle=45

# Merkezden radyal gradyan
/gradient/800/400/1e293b/64748b?gradient_type=radial

# Çıktı formatı ile
/gradient/800/400/0ea5e9/ffffff?format=webp&quality=80

Parametre Referansı

• {from_hex} / {to_hex} — # öneki olmadan hex renkler
• ?angle=45 — derece cinsinden doğrusal açı (0-360)
• ?gradient_type=radial — radyal gradyana geçer
• ?format=webp — WebP çıktısı (daha küçük dosya boyutu)

SVG Yer Tutucu Oluşturucu

SVG placeholder'ları sunucu tarafı görüntü işlemesi gerektirmez. Özelleştirilebilir arka plan rengi, ön plan rengi ve metin etiketi ile inline SVG olarak oluşturulurlar.

Endpoint

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

Örnekler

# Default wireframe placeholder
/svg/400/300

# Custom brand colors
/svg/400/300?bg=1c1917&fg=0ea5e9

# With custom text
/svg/400/300?bg=0ea5e9&fg=ffffff&text=Hero+Section

Neden SVG?

• Dosya boyutu 500 byte'ın altında
• Kalite kaybı olmadan sonsuz ölçeklenebilir
• Sıfır sunucu işleme maliyeti
• Wireframe'ler ve düşük kaliteli prototipler için mükemmel

Sosyal Medya Ön Ayarları

PlacePix, popüler sosyal medya platformları ve ekran boyutları için önceden tanımlanmış boyutlar içerir. Instagram, YouTube, TikTok, LinkedIn, X (Twitter) ve standart ekranlar için mükemmel boyutlu placeholder görüntüleri oluşturmak için bunları kullanın.

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

Ekran Boyutları

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

Uzun Kuyruk Kullanım Durumu: Instagram Story API

Bir sosyal medya yönetim aracı oluşturuyorsanız ve Instagram story boyutu yer tutucu görüntülerine ihtiyacınız varsa, /preset/instagram-story/{category} kullanın. Portre fotoğrafları için ?fit=smart ile ve optimize edilmiş teslimat için ?format=webp&quality=70 ile birleştirin.

Yön Filtreleme

Seçimden önce rastgele görüntüleri yerel en boy oranlarına göre filtreleyin. Bu, başlıklar için yatay, kartlar için dikey veya küçük resimler için kare gibi doğal olarak bir düzene sığan görüntülere ihtiyaç duyduğunuzda kullanışlıdır.

Uç Noktalar

# 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

Yapılandırma

squarish toleransı ORIENTATION_SQUARISH_TOLERANCE ortam değişkeni üzerinden yapılandırılabilir (varsayılan: 0.15). 0.15 değeri, en boy oranı 0.85 ile 1.15 arasında olan görüntülerin kare olarak kabul edildiği anlamına gelir. Tam 1:1 için 0.0 olarak ayarlayın.

Nasıl Çalışır

PlacePix, başlangıç taraması sırasında (yerel dosyalar) ve arka plan meta veri taraması sırasında (S3 görüntüleri) dosya başlıklarından görüntü boyutlarını okur. Boyutlar bellekte saklanır ve rastgele veya seed tabanlı seçimden önce aday havuzunu filtrelemek için kullanılır. Bir yön istenir ancak eşleşen görüntü yoksa 404 döndürülür.

Filtreler ve Efektler

Sorgu parametreleri aracılığıyla herhangi bir görüntüye gerçek zamanlı filtreler ve efektler uygulayın. Tüm işleme sunucu tarafında yapılır ve sonraki istekler için önbelleğe alınır.

Renk Ayarlamaları

?grayscale=1               # Siyah ve beyaz
?sepia=1                   # Sıcak sepya tonu
?tint=0ea5e9               # Hex renk kaplaması
?brightness=1.3            # 0,0 ile 2,0 arası
?contrast=1.2              # 0,0 ile 2,0 arası
?saturation=2.0            # 0,0 ile 2,0 arası
?invert=true               # Renkleri tersine çevir
?posterize=4               # Renk seviyeleri (1-8)
?duotone=ff0000,0000ff     # İki renkli harita

Görüntü Efektleri

?blur=2                    # Gauss bulanıklığı (1-10)
?sharpen=1.5               # Keskinleştirme miktarı
?emboss=true               # 3D kabartma
?edges=sobel               # Kenar algılama
?edges=canny               # Canny kenarları
?halftone=4                # Nokta deseni
?oil_painting=true         # Yağlı boya stili
?pencil_sketch=true        # Kalem eskizi
?cartoon=true              # Çizgi film efekti
?vignette=0.5              # Kenarları karart (0-1)

Yerleşim Parametreleri

?text=Hello+World          # Metin yerleşimi
?border=4,ffffff           # Kenarlık genişliği ve rengi
?watermark=1               # Yapılandırılmış filigranı uygula
?padding=20                # İç dolgu

Avatar Oluşturucu

Herhangi bir isim veya e-postadan deterministik avatarlar oluşturun. PlacePix iki avatar türünü destekler: Harf Avatarı (renkli baş harfler) ve Multiavatar (çok kültürlü vektör avatarlar).

Endpoint

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

Parametreler

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

Harf Avatarı (type=letter)

• circle — crop to a circle shape
• border={width} — kenarlık ekle
• border_color={hex} — kenarlık rengi
• 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)

Örnekler

# 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

Neden Harf Avatarı Kullanmalı?

• Sıfır harici bağımlılık — Gravatar veya üçüncü taraf avatar hizmeti yok
• Deterministik — aynı isim her zaman aynı rengi üretir
• SVG desteği — sonsuz ölçeklenebilir, HiDPI ekranlar için mükemmel
• Herhangi bir marka estetiği için altı yerleşik renk paleti

Neden Multiavatar Kullanmalı?

• 12 milyar benzersiz çok kültürlü avatar
• Deterministik — aynı isim her zaman aynı avatarı üretir
• Saf SVG çıktısı — küçük dosya boyutu, sonsuz ölçeklenebilir
• Harici API çağrılarına gerek yok

REST API Hızlı Referans

Tüm uç noktalar CORS'u destekler ve uzun süreli önbellek başlıklarıyla görüntüleri döndürür. Base64 JSON çıktısı küçük küçük resimler için kullanılabilir.

Görüntü Uç Noktaları

• GET /{width}/{height}/{category} — Kategoriden rastgele görüntü
• GET /{width}/{height} — Tüm kategorilerden rastgele görüntü
• GET /id/{id}/{width}/{height} — ID'ye göre belirli görüntü
• GET /ratio/{ratio}/{width}/{category} — En boy oranı görüntüsü
• GET /preset/{preset}/{category} — Sosyal medya ön ayarı
• GET /color/{hex}/{width}/{height} — Renk eşleşen görüntü
• GET /gradient/{w}/{h}/{from}/{to} — Gradyan görüntüsü
• GET /svg/{width}/{height} — SVG yer tutucu
• GET /avatar/{size}/{name} — Harf avatarı (PNG/SVG)

Meta Veri Uç Noktaları

• GET /api/images — Kategorileri ve toplamları listele
• GET /api/info/id/{id} — Görüntü meta verisi (boyutlar, renkler, format)
• GET /api/color/{hex} — Bir renkle eşleşen görüntüler

Sağlık Uç Noktaları

• GET /health — Canlılık sondası (Docker/K8s)
• GET /ready — Hazır olma sondası (503 görüntüler yüklenene kadar)

Uzmanlık ve Referanslar

• 2008'den beri açık kaynak ekosistemine aktif katkıda bulunanlar
• Tüm kod MIT Lisansı altında açık kaynak ve GitHub'da denetlenebilir

Sıkça Sorulan Sorular

Docker ile PlacePix'i nasıl dağıtırım?

docker run -d -p 3000:3000 -v ./images:/app/images riadvice/placepix:latest komutunu çalıştırın. Görüntü klasörünüzü bağlayın ve hizmet akıllı tarama etkinleştirilmiş olarak hemen başlar.

Yüz algılayan akıllı kırpma nedir?

PlacePix, görüntülerde yüzleri tespit etmek için OpenCV Haar kaskadlarını kullanır. Herhangi bir URL'ye ?fit=smart eklediğinizde, kırpma bölgesi geometrik merkezi kullanmak yerine tespit edilen yüzleri ortalamak için kaydırılır. Yüz bulunamazsa, standart orta kırpmaya geri döner.

Fotoğraf yüklemeden gradyan yer tutucu görüntüleri oluşturabilir miyim?

Evet. /gradient/{width}/{height}/{from}/{to} uç noktası, gradyan görüntülerini tamamen URL parametrelerinden oluşturur. Yüklenen görüntülere gerek yoktur. Ayrıca /svg/{width}/{height} ile SVG yer tutucuları da oluşturabilirsiniz.

API ile Instagram story boyutu yer tutucu görüntülerini nasıl oluştururum?

Ön ayar uç noktasını kullanın: /preset/instagram-story/{category}. Bu, 1080x1920 bir görüntü döndürür. Optimize edilmiş teslimat için ?format=webp&quality=70 ile ve portre-güvenli kırpma için ?fit=smart ile birleştirin.

PlacePix S3 uyumlu nesne depolamayı destekliyor mu?

Evet. PlacePix, OVHcloud Object Storage, AWS S3, MinIO ve herhangi bir S3 uyumlu sağlayıcı ile çalışır. Ortam değişkenleri aracılığıyla uç nokta, kova, erişim anahtarı ve gizli anahtarı yapılandırın.

Hangi çıktı formatları destekleniyor?

WebP, AVIF, JPEG, PNG, SVG ve base64 JSON. Dosya uzantısı olarak .webp, .avif veya .png kullanın veya sorgu parametresi olarak ?format=webp ekleyin. AVIF en küçük dosyaları üretir; PNG kayıpsızdır.

PlacePix ticari kullanım için ücretsiz mi?

Evet. PlacePix MIT Lisansı altında yayınlanmıştır ve hem kişisel hem de ticari kullanım için ücretsizdir. Kendi barındırılan olduğu için, kullanım limiti yoktur, API anahtarı yoktur ve istek başına faturalama yoktur.