CWEBP(1)                    General Commands Manual                   CWEBP(1)

نام (NAME)
       cwebp - فشرده‌سازی یک فایل تصویری به یک فایل WebP

خلاصه دستور (SYNOPSIS)
       cwebp [options] input_file -o output_file.webp

توضیحات (DESCRIPTION)
       این صفحه راهنما دستور cwebp را توضیح می‌دهد.

       دستور cwebp یک تصویر را با استفاده از قالب WebP فشرده می‌کند.  قالب
       ورودی می‌تواند PNG، JPEG، TIFF، WebP یا نمونه‌های خام Y'CbCr باشد.  نکته:
       فایل‌های متحرک PNG و WebP پشتیبانی نمی‌شوند.

گزینه‌ها (OPTIONS)
       گزینه‌های پایه عبارتند از:

       -o string
              نام فایل خروجی WebP را مشخص می‌کند. در صورت عدم ذکر، cwebp
              فشرده‌سازی را انجام می‌دهد اما تنها آمار را گزارش می‌کند.  استفاده
              از «-» به عنوان نام خروجی، خروجی را به 'stdout' هدایت می‌کند.

       -- string
              فایل ورودی را به طور صریح مشخص می‌کند. این گزینه زمانی مفید است
              که برای نمونه، نام فایل ورودی با یک «-» شروع شود. این گزینه باید
              در آخرین جایگاه قرار گیرد.  هر گزینه دیگری پس از آن نادیده گرفته
              خواهد شد.

       -h, -help
              خلاصه‌ای کوتاه از نحوه استفاده.

       -H, -longhelp
              خلاصه‌ای از تمام گزینه‌های ممکن.

       -version
              شماره نسخه را (به صورت major.minor.revision) چاپ کرده و خارج
              می‌شود.

       -lossless
              تصویر را بدون هیچ‌گونه اتلافی کدگذاری می‌کند. برای تصاویر دارای
              ناحیه کاملاً شفاف، مقادیر پیکسل‌های نامرئی (R/G/B یا Y/U/V) تنها
              در صورتی حفظ خواهند شد که از گزینه -exact استفاده شود.

       -near_lossless int
              سطح پیش‌پردازش تصویر نزدیک به بدون‌اتلاف (near-lossless) را تعیین
              می‌کند. این گزینه مقادیر پیکسل‌ها را برای کمک به فشرده‌سازی تنظیم
              می‌کند، اما کمترین اثر را روی کیفیت بصری دارد. این گزینه حالت
              فشرده‌سازی بدون‌اتلاف را به طور خودکار فعال می‌کند. محدوده آن از 0
              (حداکثر پیش‌پردازش) تا 100 (بدون پیش‌پردازش، پیش‌فرض) است. مقدار
              معمول در حدود 60 است. توجه داشته باشید که حالت بااتلاف با -q 100
              گاهی اوقات می‌تواند نتایج بهتری ایجاد کند.

       -q float
              ضریب فشرده‌سازی برای کانال‌های RGB را بین 0 تا 100 مشخص می‌کند.
              مقدار پیش‌فرض 75 است.
              در صورت فشرده‌سازی بااتلاف (پیش‌فرض)، یک ضریب کوچک فایلی کوچک‌تر با
              کیفیت پایین‌تر تولید می‌کند. بهترین کیفیت با استفاده از مقدار 100
              حاصل می‌شود.
              در صورت فشرده‌سازی بدون‌اتلاف (مشخص‌شده با گزینه -lossless)، ضریب
              کوچک‌تر سرعت فشرده‌سازی سریع‌تری را فراهم می‌سازد، اما فایل بزرگ‌تری
              تولید می‌کند. حداکثر فشرده‌سازی با استفاده از مقدار 100 به دست
              می‌آید.

       -z int حالت فشرده‌سازی lossless (بدون‌اتلاف) را با سطح مشخص‌شده بین 0 تا 9
              فعال می‌کند، که در آن سطح 0 سریع‌ترین و 9 کندترین است. حالت سریع
              اندازه فایل بزرگ‌تری نسبت به حالت‌های کندتر تولید می‌کند. یک مقدار
              پیش‌فرض مناسب -z 6 است. این گزینه در واقع یک میان‌بر برای برخی
              تنظیمات از پیش تعریف‌شده کیفیت و روش است. اگر گزینه‌های -q یا -m
              پس از آن استفاده شوند، اثر این گزینه باطل خواهد شد.

       -alpha_q int
              ضریب فشرده‌سازی برای فشرده‌سازی آلفا را بین 0 تا 100 مشخص می‌کند.
              فشرده‌سازی بدون‌اتلاف آلفا با مقدار 100 حاصل می‌شود، در حالی که
              مقادیر کمتر منجر به فشرده‌سازی بااتلاف می‌شوند. مقدار پیش‌فرض 100
              است.

       -preset string
              مجموعه‌ای از پارامترهای از پیش تعریف‌شده را متناسب با نوع خاصی از
              تصویر ورودی مشخص می‌کند. مقادیر ممکن عبارتند از: default، photo،
              picture، drawing، icon، text. از آنجا که -preset مقادیر سایر
              پارامترها را (به جز -q) بازنویسی می‌کند، این گزینه ترجیحاً باید در
              ابتدای ترتیب آرگومان‌ها قرار گیرد.

       -m int روش فشرده‌سازی مورد استفاده را مشخص می‌کند. این پارامتر مصالحه
              میان سرعت کدگذاری و اندازه و کیفیت فایل فشرده‌شده را کنترل می‌کند.
              مقادیر ممکن بین 0 تا 6 متغیر هستند. مقدار پیش‌فرض 4 است. با
              مقادیر بالاتر، کدگذار زمان بیشتری را صرف بررسی احتمالات کدگذاری
              اضافی و تصمیم‌گیری درباره بهبود کیفیت خواهد کرد. مقدار پایین‌تر
              می‌تواند منجر به زمان پردازش سریع‌تر به بهای اندازه فایل بزرگ‌تر و
              کیفیت فشرده‌سازی پایین‌تر شود.

       -crop x_position y_position width height
              تصویر مبدأ را به یک مستطیل با گوشه بالا-چپ در مختصات
              (x_position, y_position) و ابعاد width در height برش می‌دهد. این
              ناحیه برش باید به طور کامل در محدوده مستطیل تصویر مبدأ قرار
              داشته باشد. نکته: برش پیش از هرگونه مقیاس‌بندی اعمال می‌شود.

       -resize width height
              تصویر مبدأ را به مستطیلی با ابعاد width در height تغییر اندازه
              می‌دهد. اگر یکی از پارامترهای width یا height (نه هر دو) برابر 0
              باشد، مقدار با حفظ نسبت تصویر (aspect-ratio) محاسبه خواهد شد.
              نکته: مقیاس‌بندی پس از برش اعمال می‌شود.

       -resize_mode string
              رفتار گزینه -resize را تعیین می‌کند. مقادیر ممکن عبارتند از:
              down_only، up_only، always (پیش‌فرض). مقدار down_only تنها در
              صورتی از مقادیر مشخص‌شده توسط -resize استفاده می‌کند که عرض یا
              ارتفاع ورودی بزرگ‌تر از ابعاد داده‌شده باشد. به همین ترتیب،
              up_only تنها در صورتی تغییر اندازه می‌دهد که عرض یا ارتفاع ورودی
              کوچک‌تر از ابعاد داده‌شده باشد.

       -mt    در صورت امکان، از چندریسمانی (multi-threading) برای کدگذاری
              استفاده می‌کند.

       -low_memory
              میزان مصرف حافظه در کدگذاری بااتلاف را (معمولاً) با ذخیره چهار
              برابر اندازه فشرده‌شده کاهش می‌دهد. این کار سرعت کدگذاری را کاهش
              داده و اندازه خروجی و اعوجاج آن را اندکی تغییر می‌دهد. این پرچم
              فقط برای روش‌های 3 به بالا مؤثر است و به طور پیش‌فرض غیرفعال است.
              توجه داشته باشید که غیرفعال گذاشتن این پرچم اثرات جانبی بر جریان
              بیت (bitstream) دارد: برخی ویژگی‌های جریان بیت مانند تعداد بخش‌ها
              را اجبار می‌کند (مجبور به 1). توجه داشته باشید هنگام استفاده از
              این گزینه، گزارش دقیق‌تری از اندازه جریان بیت توسط cwebp چاپ
              می‌شود.


   گزینه‌های بااتلاف (LOSSY OPTIONS)
       این گزینه‌ها تنها هنگام انجام کدگذاری بااتلاف (حالت پیش‌فرض، با یا بدون
       آلفا) مؤثر هستند.


       -size int
              یک اندازه هدف (به بایت) برای دستیابی به خروجی فشرده‌شده تعیین
              می‌کند. فشرده‌ساز چندین دور کدگذاری جزئی انجام می‌دهد تا حد امکان
              به این هدف نزدیک شود. اگر هم از -size و هم از -psnr استفاده شود،
              مقدار -size اولویت خواهد داشت.

       -psnr float
              یک نسبت سیگنال به نویز اوج (PSNR) هدف (به دسی‌بل - dB) برای
              دستیابی به خروجی فشرده تعیین می‌کند. فشرده‌ساز چندین دور کدگذاری
              جزئی انجام می‌دهد تا حد امکان به این هدف نزدیک شود. اگر هر دو
              گزینه -size و -psnr استفاده شوند، مقدار -size اولویت خواهد داشت.

       -pass int
              حداکثر تعداد گذرها (pass) را برای استفاده در جستجوی دودویی
              گزینه‌های -size یا -psnr تنظیم می‌کند. حداکثر مقدار 10 و پیش‌فرض 1
              است. اگر گزینه‌های -size یا -psnr استفاده شوند اما -pass مشخص
              نشده باشد، مقدار پیش‌فرض '6' گذر استفاده خواهد شد. اگر -pass مشخص
              شود اما هیچ‌کدام از -size یا -psnr مشخص نشوند، مقدار هدف PSNR
              برابر با 40dB در نظر گرفته می‌شود.

       -qrange int int
              بازه مجاز برای ضریب کیفیت را مشخص می‌کند. این گزینه به‌ویژه هنگام
              استفاده از روش چندگذره (گزینه‌های -size یا -psnr) مفید است.
              پیش‌فرض 0 100 است. اگر ضریب کیفیت خارج از این بازه باشد، محدود
              (clamp) می‌شود. مقدار کمینه باید کمتر یا مساوی با مقدار بیشینه
              باشد.

       -af    فیلتر خودکار (auto-filter) را فعال می‌کند. این الگوریتم زمان
              بیشتری را صرف بهینه‌سازی قدرت فیلتر برای رسیدن به یک کیفیت متوازن
              خواهد کرد.

       -jpeg_like
              نگاشت پارامترهای داخلی را تغییر می‌دهد تا با اندازه مورد انتظار
              در فشرده‌سازی JPEG تطابق بهتری داشته باشد. این پرچم معمولاً فایل
              خروجی با اندازه‌ای مشابه معادل JPEG آن (برای تنظیم یکسان -q) اما
              با اعوجاج بصری کمتر تولید می‌کند.


       گزینه‌های پیشرفته:


       -f int قدرت فیلتر حذف بلوک‌ها (deblocking filter) را بین 0 (بدون فیلتر)
              و 100 (حداکثر فیلتر) مشخص می‌کند. مقدار 0 هرگونه فیلتر را غیرفعال
              می‌کند. مقدار بالاتر، قدرت فرایند فیلتر را که پس از رمزگشایی
              تصویر اعمال می‌شود، افزایش می‌دهد. هر چه مقدار بالاتر باشد، تصویر
              هموارتر و نرم‌تر به نظر می‌رسد. مقادیر معمول عموماً در محدوده 20 تا
              50 هستند.

       -sharpness int
              میزان تیزی و وضوح (sharpness) فیلتر را (در صورت استفاده) مشخص
              می‌کند. محدوده از 0 (بیشترین وضوح) تا 7 (کمترین وضوح) است. پیش‌فرض
              0 است.

       -strong
              از فیلتر قدرتمند استفاده می‌کند (اگر به لطف گزینه -f از فیلتر
              استفاده شود). فیلتر قدرتمند به طور پیش‌فرض فعال است.

       -nostrong
              فیلتر قدرتمند را غیرفعال کرده (اگر به لطف گزینه -f از فیلتر
              استفاده شود) و به جای آن از فیلتر ساده استفاده می‌کند.

       -sharp_yuv
              از تبدیل دقیق‌تر و شفاف‌تر RGB->YUV استفاده می‌کند. توجه داشته
              باشید که این فرایند کندتر از تبدیل پیش‌فرض و سریع 'fast' RGB->YUV
              است.

       -sns int
              دامنه شکل‌دهی نوفه فضایی (spatial noise shaping) را مشخص می‌کند.
              شکل‌دهی نوفه فضایی (یا به اختصار sns) به مجموعه‌ای کلی از
              الگوریتم‌های توکار اشاره دارد که برای تصمیم‌گیری در این مورد
              استفاده می‌شوند که کدام ناحیه از تصویر باید از بیت‌های نسبتاً کمتری
              استفاده کند، و این بیت‌ها به کدام بخش‌ها منتقل شوند تا کیفیت بهتری
              حاصل شود. محدوده ممکن از 0 (الگوریتم خاموش) تا 100 (حداکثر اثر)
              است. مقدار پیش‌فرض 50 است.

       -segments int
              تعداد بخش‌های مورد استفاده در طول قطعه‌بندی (segmentation)
              الگوریتم sns را تغییر می‌دهد. بخش‌ها باید در محدوده 1 تا 4 باشند.
              مقدار پیش‌فرض 4 است. این گزینه برای روش‌های 3 به بالا هیچ اثری
              ندارد، مگر اینکه از -low_memory استفاده شود.

       -partition_limit int
              کیفیت را با محدود کردن تعداد بیت‌های استفاده‌شده توسط برخی
              ماکروبلوک‌ها کاهش می‌دهد. محدوده از 0 (بدون کاهش کیفیت، پیش‌فرض) تا
              100 (کاهش کیفیت کامل) است. مقادیر کاربردی معمولاً برای تصاویر
              نسبتاً بزرگ حدود 30-70 هستند. در قالب VP8، بخش کنترل (control
              partition) دارای محدودیت 512 کیلوبایتی است و برای ذخیره این
              اطلاعات به کار می‌رود: آیا ماکروبلوک نادیده گرفته شده است (skip)،
              به کدام قطعه تعلق دارد، آیا به صورت حالت درون‌تصویری (intra) 4x4
              کدگذاری شده است یا 16x16، و در نهایت حالت‌های پیش‌بینی مورد
              استفاده برای هر یک از زیربلوک‌ها. برای یک تصویر بسیار بزرگ، 512
              کیلوبایت تنها فضایی برای چند بیت به ازای هر ماکروبلوک 16x16 باقی
              می‌گذارد. حداقل مطلق 4 بیت برای هر ماکروبلوک است. اطلاعات
              نادیده‌گیری، قطعه و حالت می‌توانند تقریباً تمام این 4 بیت را مصرف
              کنند (اگرچه این مورد نادر است)، که این برای تصاویر بسیار بزرگ
              مشکل‌ساز است. ضریب partition_limit دفعات استفاده از پرهزینه‌ترین
              حالت از نظر مصرف بیت (intra 4x4) را کنترل می‌کند. این گزینه زمانی
              مفید است که محدودیت 512k پر شود و این پیام نمایش یابد: Error
              code: 6 (PARTITION0_OVERFLOW: Partition #0 is too big to fit
              512k).  اگر استفاده از -partition_limit برای برآورده کردن قید
              512k کافی نباشد، باید از قطعات کمتری استفاده کرد تا بیت‌های
              سرایند بیشتری به ازای هر ماکروبلوک ذخیره شود. گزینه -segments را
              ببینید. توجه داشته باشید که گزینه‌های -m و -q نیز بر تصمیمات
              کدگذار و توانایی آن در برخورد با این محدودیت اثر می‌گذارند.


   گزینه‌های ثبت وقایع (LOGGING OPTIONS)
       این گزینه‌ها سطح خروجی را کنترل می‌کنند:

       -v     اطلاعات اضافی (به‌ویژه زمان کدگذاری) را چاپ می‌کند.

       -print_psnr
              میانگین PSNR (نسبت سیگنال به نویز اوج) را محاسبه و گزارش می‌کند.

       -print_ssim
              میانگین SSIM (معیار شباهت ساختاری، برای جزئیات بیشتر
              https://en.wikipedia.org/wiki/SSIM را ببینید) را محاسبه و گزارش
              می‌کند.

       -print_lsim
              معیار شباهت محلی (مجموع کمترین خطا در بین پیکسل‌های هم‌مکان
              همسایه) را محاسبه و گزارش می‌کند.

       -progress
              پیشرفت کدگذاری را به درصد گزارش می‌کند.

       -quiet هیچ چیزی چاپ نمی‌کند.

       -short تنها اطلاعات کوتاهی (اندازه فایل خروجی و PSNR) را برای اهداف
              آزمایشی چاپ می‌کند.

       -map int
              یک نقشه اسکی (ASCII-map) اضافی از اطلاعات کدگذاری خروجی می‌دهد.
              مقادیر ممکن نقشه از 1 تا 6 متغیر است. این گزینه فقط برای کمک به
              اشکال‌زدایی در نظر گرفته شده است.


   گزینه‌های اضافی (ADDITIONAL OPTIONS)
       گزینه‌های پیشرفته‌تر عبارتند از:

       -s width height
              مشخص می‌کند که فایل ورودی در واقع شامل نمونه‌های خام Y'CbCr بر
              اساس استاندارد ITU-R BT.601، در قالب خطی 4:2:0 است. صفحه روشنایی
              (luma) دارای اندازه width در height است.

       -pre int
              برخی مراحل پیش‌پردازش را مشخص می‌کند. استفاده از مقدار '2' باعث
              ایجاد دیترینگ (dithering) شبه‌تصادفی وابسته به کیفیت در طول تبدیل
              RGBA->YUVA می‌شود (فقط در فشرده‌سازی بااتلاف).

       -alpha_filter string
              روش فیلتر پیش‌بینانه را برای صفحه آلفا مشخص می‌کند. یکی از مقادیر
              'none'، 'fast' یا 'best'، به ترتیب افزایش پیچیدگی و کندی. پیش‌فرض
              'fast' است. در داخل برنامه، فیلتر آلفا با استفاده از چهار
              پیش‌بینی ممکن (none، horizontal، vertical، gradient) انجام می‌شود.
              حالت 'best' هر حالت را به نوبت آزمایش کرده و موردی را که اندازه
              کوچک‌تری می‌دهد انتخاب می‌کند. حالت 'fast' صرفاً سعی می‌کند بدون
              آزمایش همه حالت‌ها، یک حدس اولیه بزند.

       -alpha_method int
              الگوریتم مورد استفاده برای فشرده‌سازی آلفا را مشخص می‌کند: 0 یا 1.
              الگوریتم 0 به معنی عدم فشرده‌سازی است، 1 از قالب بدون‌اتلاف WebP
              برای فشرده‌سازی استفاده می‌کند. پیش‌فرض 1 است.

       -exact مقادیر RGB را در نواحی شفاف حفظ می‌کند. پیش‌فرض برای کمک به
              فشرده‌سازی، غیرفعال است.

       -blend_alpha int
              این گزینه کانال آلفا را (در صورت وجود) با استفاده از رنگ
              پس‌زمینه‌ای که به صورت شانزده‌شانزدهی با 0xrrggbb مشخص شده است، با
              مبدأ ترکیب می‌کند. کانال آلفا سپس به مقدار مات 255 بازنشانی
              می‌شود.

       -noalpha
              استفاده از این گزینه، کانال آلفا را نادیده می‌گیرد و حذف می‌کند.

       -hint string
              راهنمایی درباره نوع تصویر ورودی ارائه می‌دهد. مقادیر ممکن عبارتند
              از: photo، picture یا graph.

       -metadata string
              فهرستی با کاما جدا شده از فراداده‌ها برای کپی از ورودی به خروجی
              (در صورت وجود).  مقادیر معتبر: all، none، exif، icc، xmp.
              پیش‌فرض none است.

              نکته: ممکن است هر قالب ورودی از تمام این ترکیب‌ها پشتیبانی نکند.

       -noasm همه بهینه‌سازی‌های زبان اسمبلی را غیرفعال می‌کند.


وضعیت خروج (EXIT STATUS)
       اگر در طول اجرا مشکلی وجود نداشته باشد، cwebp با مقدار ثابت C یعنی
       EXIT_SUCCESS خارج می‌شود. این مقدار معمولاً صفر است.

       در صورت بروز خطا، cwebp با مقدار ثابت C یعنی EXIT_FAILURE خارج می‌شود.
       این مقدار معمولاً یک است.


مثال‌ها (EXAMPLES)
       cwebp -q 50 -lossless picture.png -o picture_lossless.webp
       cwebp -q 70 picture_with_alpha.png -o picture_with_alpha.webp
       cwebp -sns 70 -f 50 -size 60000 picture.png -o picture.webp
       cwebp -o picture.webp -- ---picture.png


نویسندگان (AUTHORS)
       دستور cwebp بخشی از libwebp است و توسط تیم WebP نوشته شده است.
       آخرین درخت منبع در نشانی زیر در دسترس است:
       https://chromium.googlesource.com/webm/libwebp

       این صفحه راهنما توسط Pascal Massimino <pascal.massimino@gmail.com> برای
       پروژه دبیان نوشته شده است (و ممکن است توسط دیگران نیز استفاده شود).


گزارش باگ‌ها (BUGS)
       لطفاً تمام باگ‌ها را به سامانه ردیابی مشکلات گزارش دهید:
       https://issues.webmproject.org
       وصله‌ها با استقبال پذیرفته می‌شوند! برای شروع به این صفحه مراجعه کنید:
       https://www.webmproject.org/code/contribute/submitting-patches


همچنین ببینید (SEE ALSO)
       dwebp(1), gif2webp(1)
       لطفاً برای اطلاعات بیشتر به https://developers.google.com/speed/webp
       مراجعه کنید.

                                April 10, 2025                        CWEBP(1)