نام (NAME)

chafa - تولیدکننده هنر نویسه‌ای و تصاویر شبیه‌سازی‌شده در ترمینال

خلاصه دستور (SYNOPSIS)

chafa [OPTION...] [IMAGE...]

توضیحات (DESCRIPTION)

chafa یک ابزار خط فرمان است که داده‌های تصویری، از جمله تصاویر متحرک GIF را به قالب‌های گرافیکی یا هنر نویسه‌ای ANSI/Unicode مناسب برای نمایش در ترمینال تبدیل می‌کند. این ابزار از قابلیت‌های گسترده‌ای پشتیبانی می‌کند که امکان استفاده از آن را روی دستگاه‌های مختلف، از تله‌پرینترهای قدیمی گرفته تا شبیه‌سازهای مدرن ترمینال و هر دستگاهی در این میان، فراهم می‌سازد.

می‌توانید یک یا چند فایل ورودی را مشخص کنید، اما رفتار پیش‌فرض هنگام مشخص کردن چند فایل کمی متفاوت است؛ برای نمونه، زمانی که بیش از یک فایل ورودی وجود داشته باشد، پویانمایی‌ها به صورت بی‌پایان تکرار نخواهند شد.

گزینه‌های عمومی (GENERAL OPTIONS)

--files path

خواندن فهرستی از مسیرها جهت پردازش از path، یا '-' برای ورودی استاندارد (stdin). مسیرها باید با خط جدید (newline) از یکدیگر جدا شوند.

می‌تواند چندین بار مشخص شود. هر مسیر اضافی دیگری در خط فرمان، در انتهای کار پردازش خواهد شد.

--files0 path

خواندن فهرستی از مسیرها جهت پردازش از path، یا '-' برای ورودی استاندارد (stdin). مسیرها باید با بایت‌های NUL از یکدیگر جدا شوند. در صورتی که سیستم‌فایل شما اجازه وجود خط جدید در نام فایل‌ها را می‌دهد (مانند POSIX)، این روش پایدارتر و ایمن‌تر است. در ترکیب با سایر ابزارهایی که از این قابلیت پشتیبانی می‌کنند مفید است، مانند:

find . -type f -print0 | chafa --files0 -

می‌تواند چندین بار مشخص شود. هر مسیر اضافی دیگری در خط فرمان، در انتهای کار پردازش خواهد شد.

-h, --help

نمایش متن راهنمای مختصر.

--probe arg

بررسی قابلیت‌های ترمینال و انتظار برای پاسخ [auto, on, off]. یک عدد حقیقی مثبت نشان‌دهنده حداکثر زمان انتظار برای پاسخ به ثانیه است. پیش‌فرض 5.0 است.

--probe-mode mode

نحوه بررسی قابلیت‌های ترمینال [any, ctty, stdio]. مقدار "any" پیش‌فرض است و با هر روش در دسترسی بررسی را انجام می‌دهد. مقدار "ctty" پایانه کنترلی (معمولاً ‎/dev/tty‎) را بررسی می‌کند که در زمان قرار داشتن chafa درون یک خط لوله (پایپ) کاربرد دارد؛ در صورت انجام در پس‌زمینه ممکن است مسدود شود. مقدار "stdio" صرفاً ورودی/خروجی استاندارد را در نظر می‌گیرد.

--version

نمایش اطلاعات نسخه، ویژگی‌ها و حق نشر.

کدگذاری خروجی (OUTPUT ENCODING)

-f, --format format

تنظیم قالب خروجی؛ یکی از [iterm, kitty, sixels, symbols]. مقدار پیش‌فرض در صورت پشتیبانی ترمینال متصل، یکی از iterm، kitty یا sixels است و در غیر این صورت به symbols ("هنر ANSI") بازمی‌گردد.

-O num, --optimize num

فشرده‌سازی خروجی با استفاده هوشمندانه از توالی‌های کنترلی [0-9]. مقدار 0 بهینه‌سازی را غیرفعال می‌کند و 9 تمام بهینه‌سازی‌های موجود را فعال می‌سازد. مقدار پیش‌فرض 5 است، به جز زمانی که با "-c none"; استفاده شود که در آن حالت پیش‌فرض 0 خواهد بود.

--relative bool

استفاده از موقعیت‌یابی نسبی مکان‌نما [on, off]. هنگام فعال بودن، از توالی‌های کنترلی برای قرار دادن تصاویر نسبت به مکان‌نما استفاده می‌شود. هنگام غیرفعال بودن، از خطوط جدید برای جداسازی سطرها استفاده خواهد شد؛ برای نمونه جهت سازگاری با 'less -R'. پیش‌فرض off است.

--passthrough mode

عبور مستقیم پروتکل گرافیکی [auto, none, screen, tmux]. برای نمایش گرافیک‌های پیکسلی از درون تسهیم‌کننده‌ها استفاده می‌شود. پیش‌فرض auto است که در صورت تشخیص ترمینال Kitty به همراه یکی از تسهیم‌کننده‌های پشتیبانی‌شده، حالت عبور مستقیم را فعال می‌کند. سایر ترکیب‌ها باید به صورت دستی فعال شوند؛ همراه با گزینه -f برای انتخاب پروتکل گرافیکی مناسب استفاده کنید.

--polite bool

حالت محتاطانه [on, off]. توالی‌های کنترلی فرار را که در موارد نادر ممکن است باعث سردرگمی ترمینال یا سایر برنامه‌ها شوند مهار می‌کند. پیش‌فرض off است.

اندازه و چیدمان (SIZE AND LAYOUT)

--align ALIGN

تراز کردن تصاویر در درگاه دید (viewport). ترازهای زیر پشتیبانی می‌شوند: left، right، top، bottom، hcenter، vcenter، center. دو تراز عمود بر هم را می‌توان با کاما جدا کرد، برای نمونه "center,right". معنای "center" به زمینه بستگی دارد و در صورت ابهام، پیش‌فرض آن "hcenter" است. مقدار "center,center" در امتداد هر دو محور تصویر را مرکزچین می‌کند.

مرکزچین کردن عمودی زمانی منطقی است که همراه با "--clear" استفاده شود، یا احتمالاً به عنوان بخشی از ساختاری که مکان‌نما از قبل در گوشه بالا-چپ نما قرار گرفته باشد، یا نمای فرعی هنگام استفاده با "--relative on";.

-C bool, --center bool

مرکزچین کردن افقی تصاویر در نما [on, off]. پیش‌فرض off است. این گزینه منسوخ شده است؛ به جای آن از "--align center"; استفاده کنید.

--clear

پاک کردن صفحه قبل از پردازش هر فایل.

--exact-size mode

تلاش برای تطابق دقیق با اندازه ورودی [auto, on, off]. در صورت فعال بودن، این گزینه سایر تنظیمات اندازه را نادیده گرفته و تصاویر خروجی را دقیقاً در ابعاد پیکسلی ورودی‌ها تولید می‌کند. در حالت auto، در صورتی که اندازه خروجی برابر یا کمی بزرگتر از ورودی باشد، از مقیاس‌بندی اجتناب شده (به ازای افزودن حاشیه/padding) عمل می‌شود. هنگام غیرفعال بودن، هیچ حاشیه‌ای افزوده نمی‌شود و تصویر برای جا گرفتن در گستره خانه متناظر مقیاس‌بندی می‌شود. پیش‌فرض auto است.

--fit-width

برازش تصویر با عرض نما، با احتمال فراتر رفتن از ارتفاع آن.

--font-ratio width/height

نسبت عرض به ارتفاع قلم هدف. می‌تواند به عنوان یک عدد حقیقی یا کسر مشخص شود. پیش‌فرض 1/2 است. این مورد فقط در حالت نماد (symbol mode) اعمال خواهد شد.

--grid colsxrows

چیدمان تصاویر در یک شبکه با cols ستون و rows سطر در هر صفحه نمایش. هر یک از cols یا rows می‌تواند حذف شود، برای نمونه ‎--grid 4‎ یا ‎--grid x4‎، که در این حالت تخصیص خانه‌ها تقریباً مربع خواهد بود. اگر "auto" مشخص شود، ابعاد به طور خودکار انتخاب می‌شوند.

-g

نام مستعار برای "--grid auto";.

--label bool

برچسب‌گذاری [on, off]. در صورت فعال بودن، هر تصویر با نام فایل خود برچسب‌گذاری می‌شود. پیش‌فرض off است.

-l

نام مستعار برای "--label on";.

--margin-bottom num

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

--margin-right num

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

--scale num

مقیاس‌بندی تصویر با در نظر گرفتن حداکثر ابعاد ترمینال. مقدار 1.0 تقریبی از ابعاد پیکسلی اصلی است. برای استفاده از تمام فضای موجود، مقدار "max" را مشخص کنید. پیش‌فرض برای گرافیک پیکسلی 1.0 و برای نمادها 4.0 است.

-s widthxheight, --size widthxheight

تنظیم حداکثر ابعاد تصویر خروجی بر حسب ستون‌ها و سطرها. به طور پیش‌فرض این مقدار برابر با اندازه نما خواهد بود (بخش --view-size را ببینید).

--stretch

کشیدن تصویر برای جا گرفتن در ابعاد خروجی؛ نسبت ابعاد نادیده گرفته می‌شود. به طور ضمنی شامل --scale max است.

--view-size widthxheight

تنظیم اندازه نما بر حسب ستون‌ها و سطرها. به طور پیش‌فرض اندازه ترمینال شما خواهد بود، یا اگر تشخیص اندازه با شکست مواجه شود، 80x25 در نظر گرفته می‌شود. اگر یکی از ابعاد حذف شود (مثلاً با ارائه اندازه به صورت 80x یا x25)، به تقریبی معقول از بی‌نهایت تنظیم خواهد شد.

پویانمایی و زمان‌بندی (ANIMATION AND TIMING)

--animate bool

مجاز بودن اجرای پویانمایی [on, off]. پیش‌فرض on است. هنگام غیرفعال بودن، یک فریم ثابت از هر پویانمایی نمایش داده می‌شود.

-d, --duration seconds

مدت زمان نمایش هر فایل به ثانیه. پیش‌فرض برای تصاویر ثابت و پویانمایی‌ها هنگام مشخص کردن چندین فایل صفر است. اگر یک پویانمایی منفرد مشخص شود، پیش‌فرض بی‌نهایت یا "inf" است. پویانمایی‌ها همیشه حداقل یک‌بار به طور کامل پخش می‌شوند، حتی اگر مدت زمان مثلاً صفر باشد. برای اطلاعات بیشتر بخش "مدت زمان (DURATION)" را ببینید.

--speed speed

تنظیم سرعت پخش پویانمایی‌ها. این مقدار می‌تواند یک ضریب بدون واحد باشد (کسرها مجاز هستند)، یا یک عدد حقیقی به همراه پسوند "fps" برای اعمال نرخ فریم خاص.

--watch

پایش یک فایل ورودی تکی و بازنمایش آن در زمان تغییر محتویات. تا زمان توقف دستی توسط کاربر یا در صورت تنظیم --duration تا پایان مهلت زمانی اجرا می‌شود.

رنگ‌ها و پردازش (COLORS AND PROCESSING)

--bg color

رنگ پس‌زمینه نمایش (نام رنگ یا کد هگز). ورودی‌های دارای شفافیت جزئی با این رنگ ترکیب می‌شوند. نام رنگ‌ها بر اساس نام‌های ارائه‌شده در X.Org است. پیش‌فرض مشکی (black) است، یا رنگ پس‌زمینه پیش‌فرض ترمینال در زمان فعال بودن قابلیت کاوش (بخش --probe را ببینید).

-c mode, --colors mode

تنظیم حالت رنگ خروجی؛ یکی از [none, 2, 8, 16/8, 16, 240, 256, full]. حالت ۲۴۰ رنگ نسبت به ۲۵۶ رنگ ترجیح داده می‌شود، زیرا ۱۶ رنگ پایین‌تر غیرقابل‌اعتماد هستند و در ترمینال‌های مختلف تفاوت دارند. حالت ۱۶ رنگ از افزونه‌های aixterm برای تولید ۱۶ رنگ پیش‌زمینه و پس‌زمینه استفاده می‌کند. حالت 16/8 امکان استفاده از ۸ رنگ به علاوه ۸ رنگ "روشن" دیگر در پیش‌زمینه را از طریق توالی اسکیپ "bold" فراهم می‌سازد. حالت ۲ رنگ فقط کدهای ANSI را برای رنگ معکوس و بازنشانی ویژگی‌ها ارسال می‌کند، در حالی که "none" هیچ توالی فراری منتشر نخواهد کرد.

در حالت sixel، مقدار "full" به صورت پویا یک پالت ۲۵۶ رنگ برای هر تصویر یا فریم پویانمایی ایجاد می‌کند. سایر حالت‌ها به پالت‌های توکار اشاره دارند. مقادیر "none" و "2" قابل تعویض با یکدیگر هستند و از رنگ‌های مشخص‌شده پیش‌زمینه/پس‌زمینه استفاده می‌کنند (بخش‌های --fg و --bg را ببینید).

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

--color-extractor extractor

روش استخراج رنگ از یک ناحیه؛ یکی از [average, median]. روش میانه (median) معمولاً خروجی شفاف‌تر و واضح‌تری تولید می‌کند، در حالی که میانگین (average) ممکن است روی تصاویر دارای نویز عملکرد بهتری داشته باشد. پیش‌فرض average است.

--color-space cs

فضای رنگی استفاده‌شده برای کوانتیزاسیون؛ یکی از [rgb, din99d]. پیش‌فرض rgb است که سریع‌تر ولی با دقت کمتر عمل می‌کند.

--dither type

نوع ترام‌ریزی (dithering) برای اعمال در طول کوانتیزاسیون. یکی از [none, ordered, diffusion, noise]. مقدار "Bayer" مترادف با "ordered" است و "fs" (Floyd-Steinberg) مترادف با "diffusion" می‌باشد. پیش‌فرض در حالت sixel برابر با "noise" و در سایر حالت‌ها "none" است.

--dither-grain widthxheight

ابعاد دانه‌های ترام‌ریزی. به صورت width x height مشخص می‌شود که هر کدام می‌تواند یکی از مقادیر [1, 2, 4, 8] پیکسل باشد. یک خانه نویسه بر اساس تعریف در هر دو جهت ۸ پیکسل است. مقدار پیش‌فرض 4x4 در حالت نماد و 1x1 در حالت sixel است.

--dither-intensity intensity

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

--fg color

رنگ پیش‌زمینه نمایش (نام رنگ یا کد هگز). به همراه رنگ پس‌زمینه مشخص‌شده توسط --bg، پالت ترمینال را در حالت‌های رنگی 2 و none تعیین می‌کند. نام رنگ‌ها بر اساس نام‌های ارائه‌شده در X.Org است. پیش‌فرض سفید (white) است، یا رنگ پیش‌زمینه پیش‌فرض ترمینال در زمان فعال بودن قابلیت کاوش (بخش --probe را ببینید).

--invert

وارونه‌سازی رنگ‌ها. برای نمایش با پس‌زمینه‌های روشن در حالت‌های رنگی 2 و none کاربرد دارد. مقادیر --fg و --bg را جابجا می‌کند.

-p bool, --preprocess bool

پیش‌پردازش تصویر [on, off]. در حالت ۱۶ رنگ یا کمتر به طور پیش‌فرض on است و در غیر این صورت off می‌باشد. این گزینه رنگ‌ها و کنتراست را قبل از تبدیل بهبود می‌بخشد که در حالت‌های با تعداد رنگ کم مفید است.

-t threshold, --threshold threshold

آستانه‌ای که بالاتر از آن شفافیت کامل استفاده خواهد شد [0.0 - 1.0]. تنظیم روی 0.0 یک تصویر خالی رندر می‌کند، در حالی که مقدار 1.0 هرگونه شفافیت را با رنگ پس‌زمینه جایگزین می‌کند (قابل تنظیم با --bg).

تخصیص منابع (RESOURCE ALLOCATION)

--threads num

حداکثر تعداد رشته‌های (threads) پردازنده برای استفاده. در صورت مشخص نشدن یا مقادیر منفی، برابر با تعداد هسته‌های در دسترس CPU خواهد بود.

-w num, --work num

میزان بار پردازشی از نظر CPU و حافظه [1-9]. مقدار 1 کم‌هزینه‌ترین و 9 دقیق‌ترین است. پیش‌فرض 5 است.

گزینه‌های اضافی برای کدگذاری نمادها (EXTRA OPTIONS FOR SYMBOL ENCODING)

--fg-only

دست‌نخورده باقی گذاشتن رنگ پس‌زمینه. این گزینه خروجی خانه نویسه‌ای را فقط با رنگ‌های پیش‌زمینه تولید می‌کند و از بازنشانی یا وارونه‌سازی رنگ‌ها خودداری خواهد کرد.

--fill symbols

مشخص کردن نمادهای نویسه‌ای برای پر کردن/گرادیان‌ها. پیش‌فرض none است. استفاده از آن شبیه به --symbols است؛ بخش زیر را ببینید.

--glyph-file file

بارگذاری اطلاعات گلیف‌ها از فایل، که می‌تواند هر فایل فونت پشتیبانی‌شده توسط FreeType باشد (مانند TTF، PCF و غیره). خطوط پیرامونی گلیف‌ها جایگزین خطوط موجود، از جمله موارد توکار خواهند شد. در حالت نماد برای پشتیبانی از فونت‌های سفارشی یا بهبود کیفیت با یک فونت خاص مفید است. توجه داشته باشید این مورد تنها زمانی معنا دارد که ترمینال خروجی از یک فونت منطبق استفاده کند. می‌تواند چندین بار مشخص شود.

--symbols symbols

مشخص کردن نمادهای نویسه‌ای برای به‌کارگیری در خروجی نهایی. برای نحوه استفاده کامل و فهرست دسته‌های نماد به بخش زیر مراجعه کنید.

وضعیت خروج (EXIT STATUS)

chafa در صورت موفقیت مقدار 0، در صورت شکست جزئی مقدار 1 و در صورت شکست کامل مقدار 2 را برمی‌گرداند (از جمله هنگام فراخوانی بدون هیچ آرگومان).

وضعیت	مفهوم
0	موفقیت
1	برخی از فایل‌ها در نمایش با شکست مواجه شدند
2	تمام فایل‌ها در نمایش با شکست مواجه شدند

نمادها (SYMBOLS)

دسته‌های پذیرفته‌شده برای --symbols و --fill عبارتند از: [all, none, space, solid, stipple, block, border, diagonal, dot, quad, half, hhalf, vhalf, inverted, braille, technical, geometric, ascii, legacy, sextant, wedge, wide, narrow]. برخی از نمادها به چندین دسته تعلق دارند؛ برای نمونه مورب‌ها (diagonals) کادر (borders) نیز محسوب می‌شوند.

می‌توانید نویسه‌های خاصی را با حرف "u" و به دنبال آن یک نقطه کد هگزادسیمال اضافه کنید، برای نمونه "ue080"، یا محدوده‌ای از نقاط کد را با جدا کردن اندیس اول و آخر با ".." مشخص کنید، مانند "u100..u200".

مجموعه نمادها همچنین می‌توانند به عنوان رشته‌ای از نویسه‌های UTF-8 درون کروشه مشخص شوند، مانند [abcd]. برای گنجاندن کروشه بسته در مجموعه، آن را با بک‌اسلش اسکیپ کنید.

می‌توانید فهرستی از دسته‌ها را که با کاما از هم جدا شده‌اند مشخص کنید، یا با افزودن پیشوند + و - نمادهایی را نسبت به مجموعه موجود اضافه یا حذف نمایید. ترتیب درج این موارد مهم است.

مجموعه نماد پیش‌فرض برای تمام حالت‌ها block+border+space-wide-inverted است به جز حالت "none" که از block+border+space-wide استفاده می‌کند (شامل نمادهای معکوس).

مدت زمان (DURATION)

برای پاسخگویی به هر دو کاربرد تعاملی و پردازش دسته‌ای، مدت زمان یک پویانمایی بر اساس چند قانون ساده تعیین می‌شود:

1.اگر یک یا چند آرگومان --duration وجود داشته باشد، آخرین مورد معتبر شناخته شده و روی تمام فایل‌ها اعمال می‌شود.

2.در غیر این صورت، اگر یک ترمینال کنترلی متصل باشد (که نشان‌دهنده یک نشست تعاملی است) و فقط یک آرگومان فایل ارائه شده باشد و آن فایل یک پویانمایی باشد، مدت زمان نامحدود خواهد داشت.

3.در غیر این صورت (عدم وجود ترمینال کنترلی، چندین فایل، یا تصویری ثابت بودن فایل)، مدت زمان صفر خواهد بود که باعث می‌شود پویانمایی‌ها یک‌بار پخش شده و سپس متوقف شوند.

مثال‌ها (EXAMPLES)

chafa in.gif

نمایش یک تصویر GIF احیاناً متحرک در ترمینال. اگر این تصویر یک پویانمایی باشد، تا زمانی که کاربر وقفه ایجاد کند (معمولاً با ctrl-c) اجرا خواهد شد. تمام پارامترها بر اساس محیط جاری به طور خودکار شناسایی می‌شوند.

chafa -c full -s 200 in.gif

مانند مورد بالا، اما اجبار خروجی تمام‌رنگ (truecolor) با عرض ۲۰۰ نویسه و محاسبه ارتفاع با حفظ نسبت ابعاد تصویر اصلی.

chafa -c 16 --color-space din99d --symbols -dot in.jpg

تولید خروجی ۱۶ رنگ با انتخاب رنگ ادراکی و خودداری از استفاده از نمادهای نقطه‌ای (dot).

chafa -c none --symbols block+border-solid in.png

تولید خروجی بدون رنگ با استفاده از نمادهای بلوکی و کادر، با اجتناب از نماد بلوک یکدست (solid).