الاقتصاص الذكي

اقتصاص ذكي مدرك للموضوع أو الوجوه أو قائم على القص. يستخدم استراتيجيات الانتباه/الإنتروبيا في Sharp واكتشاف الوجوه بالذكاء الاصطناعي للتأطير الذكي.

نقطة نهاية API

POST /api/v1/tools/image/smart-crop

المعالجة: غير متزامنة (تُرجع 202، مع استقصاء /api/v1/jobs/{jobId}/progress للحالة عبر SSE)

حزمة النموذج: face-detection (200-300 ميغابايت) - مطلوبة فقط لوضع face

المعاملات

المعامل	النوع	مطلوب	الافتراضي	الوصف
file	file	نعم	-	ملف الصورة (متعدد الأجزاء)
mode	string	لا	"subject"	وضع الاقتصاص: subject، face، trim. (تُربط القيمتان القديمتان attention وcontent بـ subject وtrim)
strategy	string	لا	"attention"	استراتيجية وضع الموضوع: attention أو entropy
width	integer	لا	-	العرض المستهدف بالبكسل
height	integer	لا	-	الارتفاع المستهدف بالبكسل
padding	integer	لا	0	نسبة الحشو حول الموضوع (0-50)
facePreset	string	لا	"head-shoulders"	إعداد تأطير الوجه المسبق: closeup، head-shoulders، upper-body، half-body
sensitivity	number	لا	0.5	حساسية اكتشاف الوجوه (0-1)
threshold	integer	لا	30	عتبة وضع القص لاكتشاف الخلفية (0-255)
padToSquare	boolean	لا	false	حشو الناتج المقصوص ليصبح مربعًا
padColor	string	لا	"#ffffff"	لون الخلفية للحشو
targetSize	integer	لا	-	الحجم المستهدف للمخرجات المحشوة (بالبكسل)
quality	integer	لا	-	جودة المخرجات (1-100)

مثال طلب

curl -X POST http://localhost:1349/api/v1/tools/image/smart-crop \
  -F "[email protected]" \
  -F 'settings={"mode":"face","width":1080,"height":1080,"facePreset":"head-shoulders"}'

الاستجابة

الاستجابة الأولية (202 Accepted)

{
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "async": true
}

التقدّم (SSE على /api/v1/jobs/{jobId}/progress)

event: progress
data: {"phase":"processing","percent":50}

النتيجة النهائية (عبر SSE)

{
  "phase": "complete",
  "percent": 100,
  "result": {
    "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "downloadUrl": "/api/v1/download/{jobId}/portrait_smartcrop.jpg",
    "originalSize": 500000,
    "processedSize": 320000
  }
}

الأوضاع

وضع الموضوع

يستخدم استراتيجية الانتباه أو الإنتروبيا في Sharp لإيجاد المنطقة الأكثر إثارة للاهتمام بصريًا ويقتص حولها.

وضع الوجه

يكتشف الوجوه باستخدام الذكاء الاصطناعي، ثم يؤطّر الاقتصاص حول الوجوه المكتشفة باستخدام facePreset المحدد. يعود إلى وضع الموضوع (استراتيجية الانتباه) إذا لم يُكتشف أي وجه.

وضع القص

يزيل الحدود/الخلفية المنتظمة من الصورة. يحشو الناتج اختياريًا ليصبح مربعًا بلون خلفية وحجم مستهدف محددين.

ملاحظات

• تستخدم هذه الأداة مصنع createToolRoute مع executionHint: "long"، لذا تُرجع 202 مع تقدّم SSE.
• يتطلب وضع الوجه حزمة النموذج face-detection (200-300 ميغابايت).
• يعمل وضعا الموضوع والقص دون أي حزمة نموذج للذكاء الاصطناعي.
• يحدد facePreset مدى إحكام تأطير الاقتصاص للوجوه المكتشفة: closeup هو الأكثر إحكامًا، وhalf-body هو الأوسع.
• إذا لم يُحدد عرض/ارتفاع، فسيكون الافتراضي 1080x1080.