سرویس عکس فیلتر را بعد از دریافت از آپ‌استریم و قبل از تحویل به کاربر اعمال می‌کند. اگر کش روی همان قانون مسیر روشن باشد و پاسخ قابل‌کش باشد، خروجی تغییریافته می‌تواند کش شود.

نسخه فعلی x-img برابر v1 است.

برای اولین پردازش، اولین تصویر را با سرویس عکس تغییر دهید را دنبال می‌کنیم.

نحو

?x-img=v1/filter1,param1_val1,param2_val2/filter2,...
جزجداکنندهمثال
نسخهشروع رشتهv1
فیلترها/resize سپس format
پارامترهای یک فیلتر,w_100,h_100
نام و مقدار پارامتر_type_webp

نمونه:

https://example.com/images/bird.jpg?x-img=v1/resize,w_100/format,type_webp

زنجیره از چپ به راست اجرا می‌شود. مثال: v1/grayscale/rotate,angle_90/resize,percent_50 اول خاکستری می‌کند، بعد ۹۰ درجه می‌چرخاند، بعد هر ضلع را نصف می‌کند.

محل تعریف رشته

محلرفتار
فیلتر با QueryStringرشته فیلتر از پارامتر x-img در URL خوانده می‌شود
فیلتر ثابتهمان نحو v1/... در فیلد commands؛ x-img نادیده گرفته می‌شود

فیلتر ثابت درخواست‌های GET یا HEAD منطبق با آن قانون مسیر را به پردازش تصویر می‌فرستد. اگر فایل تصویر نباشد، پردازش انجام نمی‌شود و ممکن است پاسخ اصلی بدون تغییر برگردد؛ وضعیت 200 به‌تنهایی تایید پردازش نیست. این حالت را فقط روی مسیری می‌گذاریم که خروجی‌اش تصویر است.

فیلترها

resize

پارامتربازهپیش‌فرضتوضیح
w۰ تا ۱۰٬۰۰۰٬۰۰۰۰عرض هدف؛ 0 یعنی عرض تعیین نشده است.
h۰ تا ۱۰٬۰۰۰٬۰۰۰۰ارتفاع هدف؛ 0 یعنی ارتفاع تعیین نشده است.
percent۰ تا ۱۰۰—درصد اندازه ورودی؛ 0 تغییری ایجاد نمی‌کند و مقدار بیش از 100 به 100 محدود می‌شود.
min۰ تا ۱۰٬۰۰۰٬۰۰۰—کوچک کردن ضلع کوچک‌تر تا مقدار هدف، با حفظ نسبت تصویر.
max۰ تا ۱۰٬۰۰۰٬۰۰۰—کوچک کردن ضلع بزرگ‌تر تا مقدار هدف، با حفظ نسبت تصویر.

اگر فقط یکی از w یا h تعیین شود، نسبت تصویر حفظ می‌شود. اگر هر دو تعیین شوند، تصویر با حفظ نسبت کوچک‌نمایی می‌شود و از مرکز برش می‌خورد تا ابعاد هدف را پر کند؛ فضای سیاه اضافه نمی‌شود. ابعاد هدف به ابعاد ورودی محدود می‌شوند و resize تصویر را از اندازه ورودی بزرگ‌تر نمی‌کند.

پارامتر force در نحو فعلی پشتیبانی نمی‌شود. حالت‌های w/h، percent، min و max را در یک فیلتر ترکیب نمی‌کنیم؛ آخرین پارامتر مربوط به یک حالت، حالت پردازش را تعیین می‌کند.

bird.jpg?x-img=v1/resize,w_100,h_100
bird.jpg?x-img=v1/resize,w_400
bird.jpg?x-img=v1/resize,percent_50
bird.jpg?x-img=v1/resize,min_100
bird.jpg?x-img=v1/resize,max_100

crop

x و y نقطه شروع و w و h ابعاد ناحیه برش هستند. همه اختیاری‌اند، مقدار پیش‌فرض آن‌ها 0 و بازه هرکدام ۰ تا ۱۰٬۰۰۰٬۰۰۰ است. مقدار 0 برای w یا h یعنی استفاده از اندازه تصویر در آن محور؛ ناحیه به مرز تصویر محدود می‌شود. ناحیه‌ای که کاملا بیرون تصویر باشد، تغییری ایجاد نمی‌کند.

bird.jpg?x-img=v1/crop,x_200,y_70,w_100,h_100

rotate

angle زاویه چرخش بر حسب درجه است؛ مقدار منفی و اعشاری هم پذیرفته می‌شود. پیش‌فرض 0 است و بازه آن از منفی ۱۰٬۰۰۰٬۰۰۰ تا مثبت ۱۰٬۰۰۰٬۰۰۰ است.

bird.jpg?x-img=v1/rotate,angle_90

autorotate

اعمال EXIF Orientation. پارامتر ندارد.

bird.jpg?x-img=v1/autorotate

blur

بدون تعیین ناحیه، کل تصویر مات می‌شود. پارامترهای ناحیه مستقل و اختیاری‌اند و به مرز تصویر محدود می‌شوند.

پارامتربازهپیش‌فرض
sigma۰ تا ۱۰۰۰۱٫۵
x و y۰ تا ۱۰٬۰۰۰٬۰۰۰۰
w و h۰ تا ۱۰٬۰۰۰٬۰۰۰۰؛ استفاده از اندازه تصویر در همان محور

مقدار 0 برای sigma تصویر را تغییر نمی‌دهد.

bird.jpg?x-img=v1/blur
bird.jpg?x-img=v1/blur,sigma_5
bird.jpg?x-img=v1/blur,x_200,y_70,w_100,h_100,sigma_20

grayscale

پارامتر ندارد.

bird.jpg?x-img=v1/grayscale

format

پارامترالزامیمقادیرپیش‌فرض
typeخیرpng، webp، jpeg یا jpgjpeg
losslessخیرtrue / falsefalse؛ مربوط به خروجی WebP
bird.jpg?x-img=v1/format,type_png
bird.jpg?x-img=v1/format,type_webp

watermark

واترمارک از یک تصویر دریافت می‌شود. پارامتر image آدرس کامل آن تصویر با کدگذاری Base64 مناسب URL، بدون padding (=) است. واترمارک متنی و پارامترهای text، t، color، dpi و size در نحو فعلی پشتیبانی نمی‌شوند.

پارامترالزامیبازهپیش‌فرضتوضیح
imageبلهآدرس تصویر با Base64-URL بدون padding—تصویر واترمارک
xخیرمنفی ۱۰٬۰۰۰٬۰۰۰ تا مثبت ۱۰٬۰۰۰٬۰۰۰۰موقعیت افقی
yخیرمنفی ۱۰٬۰۰۰٬۰۰۰ تا مثبت ۱۰٬۰۰۰٬۰۰۰۰موقعیت عمودی
bird.jpg?x-img=v1/watermark,x_50,y_50,image_aHR0cHM6Ly9leGFtcGxlLmNvbS93YXRlcm1hcmsucG5n

optimize

کیفیت خروجی، حذف متادیتا، و در صورت پشتیبانی کلاینت تبدیل به WebP. lossless برای خروجی WebP به‌صورت پیش‌فرض خاموش است. حجم خروجی به تصویر و تنظیمات وابسته است.

پارامترالزامیبازهپیش‌فرضتوضیح
qخیر۰ تا ۱۰۰۷۵کیفیت
losslessخیرtrue / falsefalseWebP بدون افت
bgخیرR-G-B هر کانال ۰ تا ۲۵۵0-0-0فقط وقتی خروجی JPEG است و ورودی شفاف است

اگر هدر Accept شامل image/webp باشد خروجی WebP است؛ وگرنه JPEG یا PNG.

bird.jpg?x-img=v1/optimize,q_100,lossless_true,bg_255-255-255

فرمت خروجی

  • بدون format و بدون optimize: WebP ورودی اگر کلاینت WebP بپذیرد WebP می‌ماند؛ وگرنه PNG. PNG و JPEG ورودی همان فرمت می‌مانند. بقیه JPEG.
  • با format: مقدار type.
  • با optimize: strip؛ اگر کلاینت WebP بپذیرد WebP؛ وگرنه PNG برای ورودی WebP/PNG و JPEG برای بقیه.
  • چند format یا optimize: آخرین فیلتر معیار است. تغییر فرمت بعد از بقیه‌ی فیلترها اعمال می‌شود.

پذیرش WebP از هدر Accept خوانده می‌شود.

ادامه مسیر