دليل مطور PlacePix

ما هو PlacePix؟

PlacePix هو خدمة صور بديلة ذاتية الاستضافة مبنية للمطورين وفرق التصميم. على عكس خدمات الصور البديلة التابعة لجهات خارجية التي تتطلب استدعاءات شبكة خارجية وقد تختفي، يعمل 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 أي 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 هذا باستخدام الاقتصاص الذكي المدرك للوجوه المدعوم من سلاسل Haar الخاصة بـ 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 الصور البديلة المتدرجة

إنشاء صور متدرجة خطية وشعاعية على الفور دون تحميل أي أصول. مثالية للخلفيات البطولية وحالات التحميل والنماذج الأولية للتصميم.

بناء جملة نقطة النهاية

/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 لا تتطلب معالجة صور من جانب الخادم. يتم إنشاؤها كـ SVG مضمن مع لون خلفية ولون مقدمة ونص قابل للتخصيص.

نقطة النهاية

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

أمثلة

# الصورة البديلة الافتراضية للإطار السلكي
/svg/400/300

# ألوان العلامة التجارية المخصصة
/svg/400/300?bg=1c1917&fg=0ea5e9

# مع نص مخصص
/svg/400/300?bg=0ea5e9&fg=ffffff&text=Hero+Section

لماذا SVG؟

• حجم الملف أقل من 500 بايت
• قابل للتطوير بلا نهاية دون فقدان الجودة
• صفر النفقات العامة لمعالجة الخادم
• مثالي للإطارات السلكية والنماذج الأولية منخفضة الدقة

الإعدادات المسبقة لوسائل التواصل الاجتماعي

يتضمن PlacePix أبعادًا محددة مسبقًا لمنصات التواصل الاجتماعي الشائعة وأحجام الشاشة. استخدمها لإنشاء صور بديلة ذات حجم مثالي لـ 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

حالة الاستخدام الطويلة: API Instagram Story

إذا كنت تبني أداة إدارة وسائل التواصل الاجتماعي وتحتاج إلى صور بديلة بحجم story Instagram، استخدم /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               # نقوش ثلاثية الأبعاد
?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                # الحشو الداخلي

Avatar Generator

Generate deterministic avatars from any name or email. PlacePix supports two avatar types: Letter Avatar (colored initials) and Multiavatar (multicultural vector avatars).

Endpoint

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

Parameters

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

Letter 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)

Examples

# 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

Why Use Letter Avatars?

• Zero external dependencies — no Gravatar or third-party avatar service
• Deterministic — the same name always produces the same color
• SVG support — infinitely scalable, perfect for HiDPI displays
• Six built-in color palettes for any brand aesthetic

Why Use Multiavatar?

• 12 billion unique multicultural avatars
• Deterministic — the same name always produces the same avatar
• Pure SVG output — tiny file size, infinitely scalable
• No external API calls required

مرجع سريع لواجهة REST API

تدعم جميع نقاط النهاية CORS وتُرجع الصور مع رؤوس التخزين المؤقت طويلة الأجل. إخراج JSON Base64 متاح للصور المصغرة الصغيرة.

نقاط نهاية الصور

• GET /{width}/{height}/{category} — صورة عشوائية من الفئة
• GET /{width}/{height} — صورة عشوائية من جميع الفئات
• GET /id/{id}/{width}/{height} — صورة محددة حسب المعرف
• 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 حتى يتم تحميل الصور)

الخبرة والاعتمادات

• مساهمون نشطون في النظام البيئي مفتوح المصدر منذ 2008
• جميع الأكواد مفتوحة المصدر بموجب ترخيص MIT وقابلة للتدقيق على GitHub

الأسئلة الشائعة

كيف أنشر PlacePix باستخدام Docker؟

شغّل docker run -d -p 3000:3000 -v ./images:/app/images riadvice/placepix:latest. قم بتركيب مجلد الصور الخاص بك ويبدأ الخدمة على الفور مع تمكين المسح الذكي.

ما هو الاقتصاص الذكي المدرك للوجوه؟

يستخدم PlacePix سلاسل Haar الخاصة بـ 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. اضبط نقطة النهاية وال bucket ومفتاح الوصول والمفتاح السري عبر متغيرات البيئة.

ما هي تنسيقات الإخراج المدعومة؟

WebP وAVIF وJPEG وPNG وSVG وJSON base64. استخدم .webp أو .avif أو .png كامتداد للملف، أو أضف ?format=webp كمعامل استعلام. AVIF ينتج أصغر الملفات؛ PNG بدون فقدان.

هل PlacePix مجاني للاستخدام التجاري؟

نعم. يتم إصدار PlacePix بموجب ترخيص MIT وهو مجاني لكل من الاستخدام الشخصي والتجاري. بما أنه ذاتي الاستضافة، لا توجد حدود للاستخدام، ولا مفاتيح API، ولا فوترة لكل طلب.