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

سرویس عکس از دو طریق قابل استفاده است:

• نسخه اول: تعریف فیلترها به صورت پشت سر هم.
• نسحه دوم: تعریف Preset و استفاده از آن.

در این نسخه فیلترها پشت سر هم و با فرمت زیر تعریف و استفاده می‌شوند:

همانطور که مشخص است فیلترها با کاراکتر «/» از هم جدا می‌شوند. هر فیلتر می‌تواند یک سری پارامتر به صورت key_value داشته باشد که این پارامترها با کاراکتر «,» از هم جدا می‌شوند.

• امکان راحت تغییر فیلترها برای تست و رسیدن به نتیجه دلخواه.

• امکان تغییر فیلترها توسط کاربر و انجام حمله EDoS در حالت غیر Forced.
• فرم غیر استاندارد URL و محدودیت تعداد کاراکتر URL.
• عدم امکان استفاده از یک مجموعه فیلتر یکسان برای چند CDN.
• خوانایی ضعیف.

برای استفاده از این نسخه دو روش وجود دارد:

• استفاده در URL به صورت Query String: در این حالت فیلترها بعنوان مقدار x-img تعیین می‌شوند. برای مثال:

• استفاده از طریق پنل: در این حالت که به آن Forced گفته می‌شود، فیلترها در بخش Forced Filter در تنظیمات یک لوکیشن تعیین می‌شوند:

برای تنظیم فیلترها و فعال‌سازی سرویس عکس باید در تنظیمات لوکیشن‌های یک CDN وارد tab تنظیمات اضافی شوید.

• فیلتر autorotate: برای چرخاندن خودکار عکس بر اساس EXIF Orientation استفاده می‌شود و پارامتری ندارد.

• فیلتر blur: برای اعمال Blur روی کل یا بخشی از عکس استفاده می‌شود و شامل پارامترهای زیر است:
  • پارامتر w: مقدار عرض ناحیه اعمال فیلتر است. اگر مقدار این پارامتر صفر باشد، عرض عکس اصلی استفاده خواهد شد.
  • پارامتر h: مقدار ارتفاع ناحیه اعمال فیلتر است. اگر مقدار این پارامتر صفر باشد، ارتفاع عکس اصلی استفاده خواهد شد.
  • پارامتر x: فاصله ناحیه اعمال فیلتر از لبه سمت چپ عکس است.
  • پارامتر y: فاصله ناحیه اعمال فیلتر از لبه بالایی عکس است.
  • پارامتر sigma: شدت اعمال فیلتر را تعیین می‌کند. مقدار ۰ تا ۱۰۰۰ دارد.

• فیلتر crop: برای برش بخشی از عکس استفاده می‌شود و شامل پارامترهای زیر است:
  • پارامتر w: مقدار عرض ناحیه اعمال فیلتر است. اگر مقدار این پارامتر صفر باشد، عرض عکس اصلی استفاده خواهد شد.
  • پارامتر h: مقدار ارتفاع ناحیه اعمال فیلتر است. اگر مقدار این پارامتر صفر باشد، ارتفاع عکس اصلی استفاده خواهد شد.
  • پارامتر x: فاصله ناحیه اعمال فیلتر از لبه سمت چپ عکس است.
  • پارامتر y: فاصله ناحیه اعمال فیلتر از لبه بالایی عکس است.

• فیلتر format: برای تبدیل فرمت عکس استفاده می‌شود و شامل پارامترهای زیر است:
  • پارامتر type: یکی از مقادیر jpeg, jpg, png, webp را دارد.
  • پارامتر lossless: تبدیل به فرمت webp در حالت lossless اتفاق می‌افتد. یکی از مقادیر true یا false را دارد. فعال کردن آن باعث افزایش چشم‌گیر سایز عکس خواهد شد.

• فیلتر grayscale: برای تغییر فضای رنگ عکس به سیاه و سفید استفاده می‌شود و پارامتری ندارد.

فیلتر optimize: عکس را strip و interlace می‌کند و در صورت پشتیبانی کلاینت فرمت عکس را به webp تبدیل خواهد کرد. برای توضیحات بیشتر قسمت «تعیین فرمت عکس خروجی» را در ادامه این مستند مطالعه کنید. این فیلتر شامل پارامترهای زیر می‌شود:

• • پارامتر lossless: اگر فرمت خروجی webp شود، این تبدیل فرمت در حالت lossless خواهد بود که با افزایش چشم‌گیر سایز عکس همراه است. یکی از مقادیر true یا false را می‌تواند داشته باشد.
  • پارامتر q: مقدار quality خروجی را تعیین می‌کند. مقدار ۰ تا ۱۰۰ دارد.
  • پارامتر bg: در صورتی که عکس ورودی transparent و خروجی jpeg مورد انتظار باشد، از این رنگ به جای alpha استفاده خواهد شد. مقادیر rgb با کاراکتر - از هم جدا می‌شوند و از ۰ تا ۲۵۵ هستند. در مثال زیر مقدار قرمز ۱۰، مقدار سبز ۲۰ و مقدار آبی ۳۰ است.

• فیلتر resize: برای تغییر اندازه عکس استفاده می‌شود و شامل پارامترهای زیر است:
  • پارامتر percent: عرض و ارتفاع عکس را به یک نسبت کوچک می‌کند و مقدار ۰ تا ۱۰۰ دارد.
  • پارامتر min: کمترین مقدار عرض یا ارتفاع عکس را تعیین می‌کند و مشخصه دیگر متناسب با مشخصه کوچکتر تغییر خواهد کرد.
  • پارامتر max: بیشترین مقدار عرض یا ارتفاع عکس را تعیین می‌کند و مشخصه دیگر متناسب با مشخصه بزرگتر تغییر خواهد کرد.
  • پارامتر w: اندازه عرض عکس را تعیین می‌کند. اگر مقدار آن صفر باشد، متناسب با تغییر اندازه ارتفاع تغییر خواهد کرد.
    پارامتر h: اندازه ارتفاع عکس را تعیین می‌کند. اگر مقدار آن صفر باشد، متناسب با تغییر اندازه عرض تغییر خواهد کرد.

• فیلتر rotate: میزان چرخش عکس را با واحد درجه تعیین می‌کند. شامل پارامتر زیر می‌شود:
  • پارامتر angle: زاویه چرخش عکس را تعیین می‌کند. اگر مقدار آن مثبت باشد، چرخش ساعتگرد و اگر مقدار آن منفی باشد، چرخش پادساعتگرد خواهد بود.

• فیلتر watermark: برای اضافه کردن یک عکس دیگر روی عکس اصلی استفاده می‌شود و شامل پارامترهای زیر می‌شود:
  • پارامتر image: آدرس فایل عکس اضافه‌شونده را تعیین می‌کند. مقدار آن باید base64 مناسب برای URL و بدون Padding باشد (encode).
  • پارامتر x: مقدار فاصله عکس اضافه شده از لبه سمت چپ عکس اصلی است.
  • پارامتر y: مقدار فاصله عکس اضافه شده از لبه بالایی عکس اصلی است.

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

برای استفاده از نسخه دوم لازم است که یک آبجکت kubernetes با فرمت زیر ساخته شود:

سپس بعد از apply کردن این object، برای استفاده از آن باید سرویس عکس برای لوکیشن مورد نظر در پنل فعال شود. به یکی از دو روش زیر می‌توان از Preset ساخته شده استفاده کرد:

• قرار دادن نام Preset در URL به صورت Query String برای کلید pixelate:

• تعیین Default Preset روی آبجکت CDN:

در نسخه‌ی دوم برخی فیلترها تغییر نام داده‌اند، پارامترهای بیشتری به برخی فیلترها اضافه شده است و همچنین فیلترهای جدیدی قابل استفاده هستند.

• فیلتر blur:

مقدار sigma بین ۰ تا ۱۰۰۰ و مقدار amplitude بین ۰/۰۰۱ تا ۱ است.

اگر مقدار width یا height صفر باشد، از مقدار عرض یا ارتفاع عکس اصلی استفاده خواهد شد.

• فیلتر composite:

مقدار blend می‌تواند یکی از مقادیر زیر باشد:

مقدار Default این پارامتر overlay است. مقادیر top و left می‌تواند منفی باشد.

• فیلتر convert:

مقدار format می‌تواند یکی از مقادیر jpeg, jpg, png, webp باشد.

مقدار quality بین ۰ تا ۱۰۰ است.

مقدار compression فقط برای فرمت png استفاده می‌شود و بین ۰ تا ۹ است.

مقادیر red, green, blue بین ۰ تا ۲۵۵ هستند.

مقدار lossless فقط برای webp استفاده می‌شود و در صورت فعال بودن، سایز عکس به صورت قابل توجهی زیاد می‌شود (تا ۴ برابر افزایش نسبت به عکس اصلی).

• فیلتر crop:

اگر مقدار width یا height صفر باشد، از مقدار عرض یا ارتفاع عکس اصلی استفاده خواهد شد.

• فیلتر draw:

مقدار shape می‌تواند یکی از مقادیر rectangle, circle, line باشد.

اگر مقدار width یا height صفر باشد، از مقدار عرض یا ارتفاع عکس اصلی استفاده خواهد شد.

مقادیر red, green, blue بین ۰ تا ۲۵۵ هستند.

اگر مقدار fill فعال باشد، مستطیل یا دایره به صورت توپر کشیده خواهند شد.

• فیلتر flip:

مقدار direction می تواند یکی از مقادیر horizontal یا vertical باشد.

• فیلتر gamma:

مقدار exponent بین ۰/۰۰۰۰۰۱ تا ۱۰۰۰ است.

• فیلتر gray:

• فیلتر optimize:

مقادیر red, green, blue بین ۰ تا ۲۵۵ هستند.

مقدار quality بین ۰ تا ۱۰۰ است.

مقدار lossless فقط برای webp استفاده می‌شود و در صورت فعال بودن، سایز عکس به صورت قابل توجهی زیاد می‌شود (تا ۴ برابر افزایش نسبت به عکس اصلی).

• فیلتر resize:

مقدار kind می‌تواند یکی از مقادیر unconstrained, percent, minimum, maximum باشد.

مقدار scale بین ۰ تا ۱ است.

اگر مقدار width یا height صفر باشد، متناسب با مقدار مشخصه دیگر تغییر خواهد کرد.

مقدار minimum کمترین مقدار عرض و یا ارتفاع عکس را تعیین می‌کند و مشخصه دیگر متناسب با مشخصه کوچکتر تغییر خواهد کرد.

مقدار maximum بیشترین مقدار عرض و یا ارتفاع عکس را تعیین می‌کند و مشخصه دیگر متناسب با مشخصه بزرگتر تغییر خواهد کرد.

• فیلتر rotate:

اگر مقدار auto فعال باشد (true)، عکس بر اساس EXIF Orientation چرخانده می‌شود و مقدار angle نادیده گرفته می‌شود.

مقدار angle زاویه چرخش عکس را تعیین می‌کند. اگر مقدار آن مثبت باشد، چرخش ساعتگرد و اگر مقدار آن منفی باشد، چرخش پادساعتگرد خواهد بود.

• فیلتر sharpen:

مقدار sigma بین ۰/۰۰۰۰۰۱ تا ۱۰۰۰۰ است.

• فیلتر zoom:

کمترین مقدار horizontal و vertical برابر با ۱ می‌باشد.

• اگر از هیچ فیلتر مرتبط با خروجی استفاده نشده باشد:
  • اگر فرمت ورودی WebP باشد و درخواست ورودی امکان پذیرش این فرمت را داشته باشد، فرمت خروجی WebP خواهد بود.
  • اگر فرمت ورودی WebP باشد و درخواست ورودی توانایی پذیرش این فرمت را نداشته باشد، فرمت خروجی PNG خواهد بود.
  • اگر فرمت ورودی PNG یا JPEG باشد، فرمت خروجی مطابق فرمت ورودی تعیین می‌شود.
  • در سایر موارد فرمت خروجی JPEG خواهد بود.
• اگر از فیلتر convert استفاده شده باشد، فرمت خروجی مطابق مقدار پارامتر format تعیین خواهد شد.
• اگر از فیلتر optimize استفاده شده باشد، ضمن strip کردن خروجی:
  • اگر درخواست ورودی امکان پذیرش فرمت WebP را داشته باشد، از این فرمت برای خروجی استفاده خواهد شد.
  • اگر فرمت ورودی WebP یا Png باشد و امکان پذیرش WebP وجود نداشته باشد، از فرمت PNG برای خروجی استفاده خواهد شد.
  • در سایر موارد از فرمت JPEG برای خروجی استفاده می‌شود.
• اگر از چند فیلتر optimize یا convert استفاده شده باشد، آخرین فیلتر ثبت‌شده معیار تعیین خروجی خواهد بود. لازم به ذکر است که تغییر فرمت به صورت Lazy و بعد از اعمال سایر فیلترها انجام خواهد شد.

تعیین پذیرش فرمت WebP از طریق مقدار هدر درخواست Accept، تعیین می‌شود.