نحوه استفاده از سرویس پردازش تصویر ستون
در این مستند به توضیح هریک از قابلیت‌های سرویس پردازش تصویر می‌پردازیم. در مثال‌هایی که در این مستند آمده است، از تصویر زیر (bird.jpg) به عنوان ورودی استفاده شده است.
از این قابلیت برای تغییر اندازه عکس‌ها استفاده می‌شود. به دو روش مختلف می‌توان ازاین قابلیت استفاده کرد:
روش اول: با استفاده از پارامترهای height و width (با ارسال مقدار آرگومانهای h و w) به صورت زیر استفاده می‌شود:
bird.jpg?x-img=v1/resize,h_100,w_100
خروجی:
همانطور که در خروجی دستور قبلی مشاهده می‌شود، اندازه خروجی به 100×100 تغییر یافته ولی نسبت طول و عرض تصویر حفظ شده و فضای خالی با پس‌زمینه سیاه پر شده است. با استفاده از پارامتر force، تصویر خروجی اصطلاحا stretch شده و پس‌زمینه سیاه ایجاد نخواهد شد. مقدار پیش‌فرض پارامتر force برابر با false است.
bird.jpg?x-img=v1/resize,h_100,w_100,force_true
خروجی:
روش دوم: در صورتی که مقادیر percent و w,h همزمان ارسال شوند، فقط مقدار percent در نظر گرفته می‌شود. همچنین در صورتی که فقط یکی از مقادیر w یا h ارسال شود، نسبت تصویر حفظ شده و پارامتر دیگر (w یا hی که ذکر نشده است) به نسبت پارامتر ذکر شده، تغییر داده می‌شود.
bird.jpg?x-img=v1/resize,w_400
| default value | optional | value range | resize |
|---|---|---|---|
| From 1 to the image's width | w | ||
| Yes (if percent exist) | From 1 to the image's height | h | |
| false | Yes | true (t), false (f) | force |
| Yes (if w and h exist) | From 1 | percent |
روش سوم: استفاده از پارامترهای min و max.
با استفاده از پارامتر min از بین مقدار ارتفاع یا عرض تصویر هر کدام که کوچکتر باشد، برابر با مقدار min خواهد شد و مقدار مشخصه دیگر (عرض یا ارتفاع) متناسب با این مقدار تغییر خواهد کرد. برای مثال اگر اندازه عرض تصویر 300 و اندازه ارتفاع آن 200 باشد. بعد از اعمال فیلتر زیر:
bird.jpg?x-img=v1/resize,min_100
اندازه ارتفاع (مقدار کوچکتر) 100 و اندازه عرض 150 می‌شود.
با استفاده از پارامتر max از بین مقدار ارتفاع یا عرض تصویر هر کدام که بزرگتر باشد، برابر با مقدار max خواهد شد و مقدار مشخصه دیگر (عرض یا ارتفاع) متناسب با این مقدار تغییر خواهد کرد. برای مثال اگر اندازه عرض تصویر 300 و اندازه ارتفاع آن 200 باشد. بعد از اعمال فیلتر زیر:
bird.jpg?x-img=v1/resize,max_100
اندازه عرض (مقدار بزرگتر) 100 و اندازه ارتفاع 67 می‌شود.
برای برش یک تصویر به پارامترهای x و y به عنوان نقطه شروع و width و height به عنوان اندازه تصویر خروجی نیاز است.
bird.jpg?x-img=v1/crop,x_200,y_70,w_100,h_100
خروجی:
| Default value | Optional | value range | crop |
|---|---|---|---|
| No | From 0 to the image's width | x | |
| No | From 0 to the image's height | y | |
| No | From 1 to image's width - x | w | |
| No | From 1 to image's height - y | h |
برای چرخاندن یک تصویر به پارامتر angle برای تعیین زاویه چرخش نیاز است. مقادیر ۹۰، ۱۸۰ و ۲۷۰ برای angle پشتیبانی می‌شوند و چرخش به صورت ساعت‌گرد انجام می‌گردد.
bird.jpg?x-img=v1/rotate,angle_90
خروجی:
| Default value | Optional | Value range | Rotate |
|---|---|---|---|
| No | 90, 180, 270 | angle |
برای اعمال EXIF Orientation و چرخش خودکار تصاویر می‌توانید از فیلتر autorotate استفاده کنید. برای مثال:
bird.jpg?x-img=v1/autorotate
مات کردن یک تصویر به دو صورت امکان‌پذیر است:
در حالت اول کل تصویر مات می‌شود:
bird.jpg?x-img=v1/blur
همچنین با ارسال پارامتر sigma می‌توان مقدار مات شدن تصویر را کنترل کرد. مقدار پیش‌فرض sigma برابر با ۱۰، و رنج آن بین ۱ تا ۱۰۰ است.
bird.jpg?x-img=v1/blur,sigma_5
خروجی:
در حالت دوم امکان مات کردن بخشی از تصویر با ارسال پارامترهای x,y,w,h (مشابه crop) امکان‌پذیر است.
bird.jpg?x-img=v1/blur,x_200,y_70,w_100,h_100,sigma_20
در حالت دوم امکان مات کردن بخشی از تصویر با ارسال پارامترهای x,y,w,h (مشابه crop) امکان‌پذیر ا
| Default Value | Optional | Value range | Blur |
|---|---|---|---|
| 10 | Yes | From 1 to 100 | sigma |
| 0 | Yes (if one of them exists,other parameters should exist) | From 0 to the image's width | x |
| 0 | Yes (if one of them exists,other parameters should exist) | From 0 to the image's height | y |
| Image's width | Yes (if one of them exists,other parameters should exist) | From 1 to image's width - x | w |
| Image's height | Yes (if one of them exists,other parameters should exist) | From 1 to image's height - y | h |
خاکستری کردن تصاویر به صورت زیر قابل انجام است:
bird.jpg?x-img=v1/grayscale
خروجی:
برای تغییر فرمت تصاویر، با مشخص کردن مقدار پارامتر type به صورت زیر عمل می‌شود:
bird.jpg?x-img=v1/format,type_png
bird.jpg?x-img=v1/format,type_webp
انواع فرمت پشتیبانی شده شامل png, webp, jpg, tiff, gif می‌باشد.
| Default Value | Optional | Value Range | Format |
|---|---|---|---|
| No | png, webp, jpg, tiff, gif | type |
این قابلیت برای افزودن watermark به تصویر اصلی استفاده می‌شود که شامل دو حالت مختلف است:
حالت اول اضافه کردن تصویر، که به نیاز به پارامترهای x و y برای مشخص نمودن محل اضافه شدن واترمارک و پارامتر image برای مشخص نمودن آدرس کامل تصویر مورد نظر به عنوان واترمارک استفاده می‌شود. پارامتر image باید به صورت base64-url-encoded تبدیل شده باشد.
bird.jpg?x-img=v1/watermark,x_50,y_50,image_base64UrlEncoded==
خروجی:
همچنین امکان تعیین مقدار کدری (opacity) تصویر واترمارک با ارسال پارامتر t وجود دارد. برای مثال:
bird.jpg?x-img=v1/watermark,x_50,y_50,image_base64UrlEncoded==,t_10
برای این حالت نیز پارامتر t و همچنین پارامترهای color ،size و dpi به صورت اختیاری قابل تنظیم است.
در صورتی که مقادیر text و image همزمان ارسال شوند، فقط مقدار image و پارامترهای مرتبط با آن در نظر گرفته می‌شوند.
| Default value | Optional | Value range | Watermark |
|---|---|---|---|
| Yes (if text exists) | Base64 URL encoded of watermark image’s address | image | |
| No (if image exists) | From 0 to the image’s width | x | |
| No (if image exists) | From 0 to the image’s height | y | |
| Yes (should not exist with image together) | Base64 URL encoded of the watermark text | text | |
| 100 | Yes | From 0 to 100 | t |
| FFFFFF | Yes | From 0000 to FFFF (hex value of RGB) | color |
| 100 | Yes | From 0 | dpi |
| 12 | Yes | The font size (from 1) | size |
این امکان وجود دارد که چند پردازش متفاوت را به صورت همزمان بر روی یک تصویر اعمال نمود (با استفاده از pipe کردن متوالی دستورات). برای مثال:
bird.jpg?x-img=v1/grayscale/rotate,angle_90/resize,percent_50
که ابتدا تصویر مورد نظر به grayscale تبدیل می‌شود، سپس تصویر grayscale شده به اندازه ۹۰ درجه چرخش داده می‌شود و نتیجه آن نیز تغییر اندازه داده شده و هر ضلع آن نصف (۵۰ درصد) حالت قبلی می‌شود. خروجی تصویر به صورت زیر خواهد بود:
فیلتر optimize به منظور تغییر کیفیت تصویر خروجی تعبیه شده است. با استفاده از این فیلتر می‌توان میزان کیفیت تصویر نهایی را به صورت بدون افت (lossless) تعریف کرد. با فعال کردن این فیلتر، امکان تعریف مقدار interlace هم برای تصویر خروجی وجود دارد. برای کاهش حجم عکس خروجی، متادیتای تصویر هم از آن حذف می‌شود.
در صورتی که کلاینت (مثلا browser) درخواست image/webp را در هدر accept درخواست http اضافه کند، تصویر نهایی به صورت خودکار به فرمت webp آماده و ارسال می‌شود. در صورت عدم ارسال این درخواست، فرمت تصویر JPEG یا PNGخواهد بود.
اگر فرمت نهایی تصویر JPEG شود و تصویر دارای کانال alpha باشد، نواحی transparent به رنگ مشکی دیده می‌شوند. برای تغییر رنگ زمینه می‌توانید از پارامتر bg استفاده کنید.
دستور زیر را به عنوان مثال در نظر بگیرید:
bird.jpg?x-img=v1/optimize,q_100,lossless_true,bg_255-255-255
متغیر q نشان‌دهنده‌ی میزان کیفیت است. کیفیت تصویر در این دستور برابر با ۱۰۰ قرار داده شده است. در صورتی که مقداری برای q تعریف نشود، کیفیت تصویر به صورت پیش‌فرض برابر با ۶۰ در نظر گرفته می‌شود. مقدار lossless هم به صورت پیش‌فرض در حالت فعال یا true قرار دارد. پس نتیجه‌ی پردازش این درخواست تصویری با کیفیت ۱۰۰ و به صورت lossless است.
پارامتر bg زمانی کارایی دارد که تصویر با فرمت JPEG آماده شود و رنگ زمینه transparent باشد. مقدار آن به صورت R-G-B تعریف می‌شود که بیانگر مقادیر کانال‌های قرمز، سبز و آبی است. مثلا در مثال قبل رنگ زمینه سفید خواهد بود. این پارامتر برای خروجی‌های webp و PNG اثری ندارد.
نکته: توجه کنید که در صورت روشن بودن lossless حجم تصاویر تا ۴ برابر افزایش خواهد یافت.