📄 استفاده از سرویس عکس

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

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

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

نسخه‌ی اول

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

v1/filter1,param1_val1,param2_val2/filter2,...

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

مزایای نسخه‌ی اول

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

معایب نسخه‌ی اول

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

روش استفاده از نسخه‌ی اول

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

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

https://www.domain.ir/image.png?x-img=v1/filter,key_val/filter

Bash

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

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

فیلترهای نسخه‌ی اول

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

v1/autorotate

Bash

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

v1/blur,x_0,y_0,w_0,h_0,sigma_1.5

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

v1/crop,x_20,y_8,w_10,h_24

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

v1/format,type_webp,lossless_true

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

v1/grayscale

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

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

v1/optimize,q_100,lossless_true,bg_10-20-30

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

v1/resize,h_120,w_240

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

v1/rotate,angle_90

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

v1/watermark,x_10,y_20,image_aHR0cHM6Ly9kb21haW4uaXIvb3Zlci5wbmc

نسخه‌ی دوم

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

روش استفاده از نسخه‌ی دوم

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

apiVersion: delivery.sotoon.ir/v1
kind: Pixel
metadata:
  name: sample
  namespace: your-workspace-name
spec:
  filters:
    - name: filter1
      filter1:
        key: val
    - name: filter2

JSON

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

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

https://www.domain.ir/image.png?pixelate=sample

Bash

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

spec:
  locations:
    - path: "*.png"
      imgsvc:
        enabled: true
        defaultPreset: sample

JSON

فیلترهای نسخه‌ی دوم

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

• فیلتر blur:

- name: blur
  blur:
    left: 0
    top: 0
    width: 0
    height: 0
    sigma: 1.5
    amplitude: 0.2

JSON

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

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

• فیلتر composite:

- name: composite
  composite:
    left: 0
    top: 0
    url: "https://domain.ir/over.png"
    blend: multiply

JSON

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

clear, source, over, in, out, atop, dest, destover, destin, destout, destatop, xor, add, saturate, multiply, screen, overlay, darken, lighten, colourdodge, colourburn, hardlight, softlight, difference, exclusion, last

Bash

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

• فیلتر convert:

- name: convert
  convert:
    format: webp
    quality: 100
    compression: 6
    background:
      red: 10
      green: 20
      blue: 30
    interlace: true
    lossless: true
    strip: true

JSON

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

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

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

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

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

• فیلتر crop:

- name: crop
  crop:
    left: 0
    top: 0
    width: 120
    height: 240

JSON

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

• فیلتر draw:

- name: draw
  draw:
    shape: rectangle
    color:
      red: 10
      green: 20
      blue: 30
    rectangle:
      left: 0
      top: 0
      width: 100
      height: 50
      fill: true
    circle:
      center:
        left: 150
        top: 150
      radius: 100
      fill: true
    line:
      point1:
        left: 0
        top: 0
      point2:
        left: 100
        top: 100

JSON

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

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

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

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

• فیلتر flip:

- name: flip
  flip:
    direction: horizontal

JSON

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

• فیلتر gamma:

- name: gamma
  gamma:
    exponent: 2.4

JSON

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

• فیلتر gray:

- name: gray

JSON

• فیلتر optimize:

- name: optimize
  optimize:
    background:
      red: 10
      green: 20
      blue: 30
    quality: 75
    lossless: false

JSON

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

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

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

• فیلتر resize:

- name: resize
  resize:
    kind: unconstrained
    unconstrained:
      width: 100
      height: 50
    percent:
      scale: 0.5
    minimum:
      value: 100
    maximum:
      value: 100

JSON

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

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

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

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

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

• فیلتر rotate:

- name: rotate
  rotate:
    auto: false
    angle: 30
- name: rotate
  rotate:
    auto: true

JSON

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

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

• فیلتر sharpen:

- name: sharpen
  sharpen:
    sigma: 0.5
    threshold: 2.0
    brightening: 10.0
    darkening: 20.0
    flat: 0
    jaggy: 3.0

JSON

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

• فیلتر zoom:

- name: zoom
  zoom:
    horizontal: 2
    vertical: 2

JSON

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

تعیین فرمت عکس خروجی

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

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