rsvg-convert(1) User Commands rsvg-convert(1)

rsvg-convert - رندر کردن اسناد SVG به تصاویر PNG یا تبدیل آن‌ها به PDF یا PS

تبدیل یک فایل SVG به PNG با «اندازه طبیعی» آن و نوشتن در خروجی استاندارد:

rsvg-convert input.svg > output.png

مشخص کردن نام فایل خروجی؛ نام فایل ورودی باید آخرین آرگومان باشد:

rsvg-convert --output=output.png input.svg

تنظیم نقطه در اینچ (DPI) برای فایل‌های SVG دارای واحدهای فیزیکی، مانند <svg width="5cm" height="3cm"> - پیش‌فرض 96 DPI است:

rsvg-convert --dpi-x=300 --dpi-y=300 input.svg > output.png

رندر کردن SVG با اندازه پیکسلی مشخص، با حفظ تناسب تصویر:

rsvg-convert --width=1024 --height=768 --keep-aspect-ratio input.svg > output.png

دستور rsvg-convert اسناد SVG را به تصاویر شطرنجی (رستر) PNG رندر می‌کند یا آن‌ها را به عنوان اشیای برداری به PDF یا PS تبدیل می‌نماید. به صورت پیش‌فرض، rsvg-convert سند SVG را به یک تصویر رستر PNG رندر کرده و در خروجی استاندارد می‌نویسد:

rsvg-convert input.svg > output.png

برای انتخاب قالبی دیگر، از گزینه --format استفاده کنید:

rsvg-convert --format=pdf input.svg > output.pdf

می‌توانید از rsvg-convert به عنوان بخشی از یک خط لوله (پایپ‌لاین) استفاده کنید؛ بدون تعیین آرگومانی برای نام فایل ورودی، سند از ورودی استاندارد خوانده خواهد شد:

cat input.svg | rsvg-convert > output.png

می‌توانید از گزینه‌های --width و --height برای مشخص کردن اندازه تصویر خروجی استفاده کنید. در بیشتر موارد باید گزینه --keep-aspect-ratio را مشخص کنید تا مقیاس تصویر به صورت متناسب تغییر کند؛ جهت سازگاری با نگارش‌های قدیمی‌تر، این حالت پیش‌فرض نیست.

rsvg-convert --width=100 --height=200 --keep-aspect-ratio input.svg > output.png

همچنین می‌توانید ابعاد را بر حسب طول‌های CSS مانند 10px یا 8.5in مشخص کنید. شناسه‌های یکای پشتیبانی‌شده عبارتند از:

px پیکسل (شناسه یکا می‌تواند حذف شود)
in اینچ
cm سانتی‌متر
mm میلی‌متر
pt پوینت، 1/72 اینچ
pc پایکا، 1/6 اینچ

دستور زیر یک تصویر PNG به اندازه 600*900 پیکسل یا 2*3 اینچ با تراکم ۳۰۰ نقطه در اینچ تولید می‌کند:

rsvg-convert --width=2in --height=3in --keep-aspect-ratio --dpi-x=300 --dpi-y=300 input.svg > output.png

دستور زیر مقیاس سند SVG را برای گنجاندن در یک صفحه A4 تنظیم کرده و آن را به PDF تبدیل می‌کند:

rsvg-convert --format=pdf --width=210mm --height=297mm --keep-aspect-ratio input.svg > output.pdf

به صورت پیش‌فرض، اندازه خروجی از روی اندازه رندرشده تعیین می‌شود که می‌توان آن را با گزینه‌های --width و --height مشخص کرد؛ اما شما می‌توانید اندازه صفحه را مستقل از اندازه رندرشده با استفاده از گزینه‌های --page-width و --page-height، به همراه --top و --left برای کنترل موقعیت تصویر رندرشده در صفحه مشخص کنید. به طور خلاصه:

  • --page-width و --page-height با یکدیگر - اندازه صفحه را تعیین می‌کنند.
  • --top و --left - حاشیه‌ها را تعیین می‌کنند.
  • --width و --height - اندازه رندرشده را تعیین می‌کنند.

دستور زیر یک PDF در حالت افقی (landscape) با اندازه A4 می‌سازد، با تغییر مقیاس سند SVG به 10*10 سانتی‌متر و قرار دادن آن به طوری که گوشه بالا-چپ آن ۵ سانتی‌متر از بالای صفحه و ۸ سانتی‌متر از سمت چپ صفحه فاصله داشته باشد:

rsvg-convert --format=pdf --page-width=297mm --page-height=210mm --width=10cm --height=10cm --keep-aspect-ratio --top=5cm --left=8cm input.svg > output.pdf

گزینه --zoom به شما امکان می‌دهد اندازه طبیعی یک سند SVG را تغییر مقیاس دهید. به عنوان مثال، اگر input.svg سندی با اندازه اعلان‌شده 100*200 پیکسل باشد، دستور زیر آن را با ابعاد 250*500 پیکسل (بزرگ‌نمایی 2.5) رندر می‌کند:

rsvg-convert --zoom=2.5 input.svg > output.png

می‌توانید حداکثر اندازه مقیاس‌شده را با تعیین گزینه‌های --width و --height همراه با --zoom محدود کنید. در اینجا، مقیاس تصویر ۱۰ برابر می‌شود، اما حداکثر به ابعاد 1000*1000 پیکسل محدود خواهد شد:

rsvg-convert --zoom=10 --width=1000 --height=1000 input.svg > output.png

اگر به ضرایب مقیاس متفاوتی برای ابعاد افقی و عمودی نیاز دارید، به جای --zoom از گزینه‌های --x-zoom و --y-zoom استفاده کنید.

قالب‌های خروجی "pdf"، "ps" و "eps" از چندین صفحه پشتیبانی می‌کنند. این اسناد می‌توانند با ترکیب چندین فایل ورودی SVG ایجاد شوند. به عنوان مثال، این فایل PDF سه صفحه خواهد داشت:

rsvg-convert --format=pdf page1.svg page2.svg page3.svg > out.pdf

اندازه هر صفحه به صورت جداگانه، همان‌طور که در بخش اندازه پیش‌فرض خروجی شرح داده شده است، محاسبه می‌شود. این موضوع ممکن است منجر به تولید یک فایل PDF با صفحاتی با اندازه‌های متفاوت گردد. اگر لازم است فایلی PDF ایجاد کنید که تمام صفحات آن دقیقاً یک اندازه باشند، از گزینه‌های --page-width و --page-height استفاده کنید.

برای نمونه، دستور زیر یک فایل PDF سه‌صفحه‌ای از سه سند SVG تولید می‌کند. همه صفحات به صورت عمودی (portrait) در اندازه US Letter هستند و مقیاس هر SVG طوری تنظیم شده است که ۱ اینچ حاشیه در اطراف هر صفحه وجود داشته باشد (از این رو عرض 6.5 اینچ و ارتفاع 9 اینچ برای اندازه رندرشده در نظر گرفته شده است).

rsvg-convert --format=pdf --page-width=8.5in --page-height=11in --width=6.5in --height=9in --keep-aspect-ratio --top=1in --left=1in pg1.svg pg2.svg pg3.svg > out.pdf

دستور rsvg-convert از گزینه‌های --dpi-x و --dpi-y برای پیکربندی نقطه در اینچ (DPI) استفاده می‌کند که بر اساس آن پیکسل‌ها به/از واحدهای فیزیکی مانند اینچ یا سانتی‌متر تبدیل می‌شوند. مقدار پیش‌فرض برای هر دو گزینه 96 DPI است.

این نمونه SVG را در نظر بگیرید که ابعاد اسمی آن 2*3 اینچ تعریف شده است:

<svg xmlns="http://www.w3.org/2000/svg" width="2in" height="3in">
  <!-- graphical objects here -->
</svg>

دستورات زیر برای نمونه SVG بالا تصاویر PNG با اندازه‌های مختلف تولید می‌کنند:

rsvg-convert two-by-three.svg > output.png #### یک تصویر PNG با ابعاد 192*288 پیکسل می‌سازد

rsvg-convert --dpi-x=300 --dpi-y=300 two-by-three.svg > output.png #### یک تصویر PNG با ابعاد 600*900 پیکسل می‌سازد

توجه داشته باشید که ابعاد نهایی پیکسلی به نزدیک‌ترین پیکسل به سمت بالا گرد می‌شوند تا از بریده شدن لبه‌های راست و پایین جلوگیری شود. در مثال زیر، rsvg-convert یک تصویر PNG با ابعاد 300x300 پیکسل تولید خواهد کرد:

rsvg-convert --width=299.5 --height=299.4 input.svg > output.png #### خروجی تصویری ۳۰۰ در ۳۰۰ پیکسلی با مقیاس‌بندی کسری است

اگر ابعاد را با واحدهای فیزیکی مشخص کنید، در مقدار نقطه در اینچ (DPI) ضرب می‌شوند تا ابعاد بر حسب پیکسل به دست آیند. به عنوان مثال، دستور زیر یک PNG با ابعاد 96x96 پیکسل تولید می‌کند، زیرا ابعاد آن 1x1 اینچ با پیش‌فرض 96 DPI است:

rsvg-convert --width=1in --height=1in input.svg > output.png #### خروجی تصویری ۹۶ در ۹۶ پیکسلی تولید می‌کند

به همین ترتیب، دستور زیر یک PNG با ابعاد 300x300 پیکسل ایجاد می‌کند، زیرا ابعاد آن 1x1 اینچ در تراکم 300 DPI است:

rsvg-convert --width=1in --height=1in --dpi-x=300 --dpi-y=300 input.svg > output.png #### خروجی تصویری ۳۰۰ در ۳۰۰ پیکسلی تولید می‌کند

اگر گزینه‌های --width یا --height را برای اندازه خروجی مشخص نکنید، rsvg-convert یک «اندازه طبیعی» برای SVG به صورت زیر تعیین می‌کند:

  • SVG با عرض و ارتفاع بر حسب پیکسل (px): <svg width="96px" height="192px"> برای خروجی PNG، از همان ابعاد پیکسلی استفاده می‌شود. برای خروجی PDF/PS/EPS، این اندازه پیکسلی بر اساس مقدار DPI به واحدهای فیزیکی تبدیل می‌شود (گزینه‌های --dpi-x و --dpi-y را ببینید).
  • SVG با عرض و ارتفاع بر حسب واحدهای فیزیکی: <svg width="1in" height="2in"> برای خروجی PNG، ویژگی‌های width و height بر اساس مقدار DPI به پیکسل تبدیل می‌شوند (گزینه‌های --dpi-x و --dpi-y را ببینید). برای خروجی PDF/PS/EPS، عرض/ارتفاع در واحدهای فیزیکی، اندازه PDF را تعیین می‌کنند مگر اینکه گزینه‌هایی برای اندازه صفحه مشخص کنید؛ بخش تعیین اندازه صفحه در بالا را ببینید.
  • SVG فقط با viewBox: <svg viewBox="0 0 20 30"> اندازه ویژگی viewBox برای اندازه پیکسلی تصویر مشابه مورد اول در بالا استفاده می‌شود.
  • SVG با عرض و ارتفاع درصدی: <svg width="100%" height="100%" viewBox="0 0 20 30"> درصدها بی‌معنی هستند مگر اینکه اندازه درگاه دید (viewport) را با گزینه‌های --width و --height مشخص کنید. در غیاب آن‌ها، rsvg-convert صرفاً از اندازه viewBox برای اندازه پیکسلی، مطابق توضیحات بالا استفاده خواهد کرد.
  • SVG بدون عرض، ارتفاع، یا viewBox: دستور rsvg-convert ابعاد تمام اشیای گرافیکی موجود در سند SVG را اندازه‌گیری کرده و آن‌ها را در مقیاس 1:1 رندر می‌کند (۱ پیکسل برای هر واحد CSS px). اکیداً توصیه می‌شود که با ویژگی‌های width، height یا viewBox اندازه مشخصی به اسناد SVG اختصاص دهید.

می‌توانید از گزینه --background-color (به اختصار -b) برای مشخص کردن رنگ پس‌زمینه‌ای که در بخش‌های شفاف تصویر ظاهر می‌شود استفاده کنید. این گزینه از همان قواعد نحوی ویژگی color در CSS پشتیبانی می‌کند؛ بنابراین می‌توانید از قالب‌های #rrggbb، نام‌های رنگی در CSS مانند white یا rgba() استفاده کنید.

rsvg-convert --background-color=white input.svg > output.png #### سفید مات
rsvg-convert -b '#ff000080' input.svg > output.png #### قرمز نیمه‌شفاف - استفاده از کوتیشن‌های شل تا کاراکتر # به عنوان کامنت تفسیر نشود

یک سند SVG می‌تواند از عنصر <switch> و فرزندان آن با ویژگی systemLanguage برای ارائه محتوای مختلف بر اساس زبان کاربر استفاده کند. به عنوان مثال:

<svg xmlns="http://www.w3.org/2000/svg" width="200" height="100">
  <rect width="200" height="100" fill="white"/>
  <g transform="translate(30, 30)" font-size="20">
    <switch allowReorder="yes">
      <text systemLanguage="es">Español</text>
      <text systemLanguage="de">Deutsch</text>
      <text systemLanguage="fr">Français</text>
      <text>English fallback</text>
    </switch>
  </g>
</svg>

می‌توانید از گزینه --accept-language برای انتخاب زبانی که هنگام رندر استفاده می‌شود بهره ببرید. این گزینه رشته‌هایی قالب‌بندی‌شده مشابه هدر HTTP Accept-Language را می‌پذیرد که فهرستی جداشده با کاما از تگ‌های زبان BCP47 است: https://www.rfc-editor.org/info/bcp47

rsvg-convert --accept-language=es-MX input.svg > output.png #### زبان اسپانیایی مکزیک را انتخاب کرده و عبارت "Español" را رندر می‌کند.

می‌توانید یک شیوه‌نامه (استایل‌شیت) CSS اضافی را با گزینه --stylesheet برای استفاده هنگام رندر کردن یک سند SVG ضمیمه کنید. این استایل‌شیت دارای منشأ کاربری در CSS (user origin) خواهد بود، در حالی که استایل‌های تعریف‌شده در سند SVG دارای منشأ پدیدآورنده (author origin) خواهند بود.

rsvg-convert --stylesheet=extra-styles.css input.svg > output.png

لطفاً توجه داشته باشید که طبق قوانین آبشاری CSS، یک استایل‌شیت کاربر لزوماً بر استایل‌های تعریف‌شده در یک سند SVG غلبه نمی‌کند. برای بازنویسی قطعی آن‌ها، باید استایل‌های اضافی خود را با !important تنظیم کنید.

مطابق با مشخصات آبشاری CSS (https://www.w3.org/TR/css-cascade-4/#cascade-sort)، اعلان‌های استایل اولویت‌های زیر را دارند. اعلان‌ها از مبداهایی که دیرتر در فهرست آمده‌اند بر اعلان‌های مبداهای پیشین اولویت دارند:

  • اعلان‌های عادی عامل کاربر (استایل‌شیت‌های خود librsvg).
  • اعلان‌های عادی کاربر (از استایل‌شیت کاربری شما).
  • اعلان‌های عادی پدیدآورنده (از سند SVG).
  • اعلان‌های !important پدیدآورنده (از سند SVG).
  • اعلان‌های !important کاربر (از استایل‌شیت کاربری شما).
  • اعلان‌های !important عامل کاربر (استایل‌شیت‌های خود librsvg).

پس از آن، ویژگی اختصاصی بودن (specificity) در CSS و ترتیب ظهور اعلان‌ها در نظر گرفته می‌شوند.

فایل input.svg زیر را در نظر بگیرید؛ توجه کنید که مستطیل دارای صفت نمایشی fill="red" و کلاس recolorable است:

<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100">
  <rect width="200" height="100" fill="white"/>
  <rect class="recolorable" x="10" y="10" width="50" height="50" fill="red"/>
  <text x="10" y="80" font-size="20" fill="red">Hello</text>
</svg>

و این محتوای extra-styles.css است:

.recolorable { fill: blue !important; }
text { fill: green !important; }

در این حالت، تصویر PNG ایجاد شده توسط دستور فوق دارای این ویژگی‌ها خواهد بود:

  • یک مربع آبی به جای قرمز، به دلیل انتخاب‌گر کلاس recolorable. اعلان fill: blue !important; بر صفت نمایشی fill="red" اولویت دارد.
  • متن به رنگ سبز، زیرا صفت fill="red" با fill: green !important بازنویسی می‌شود.

قالب خروجی سند رندرشده. مقادیر مجاز عبارتند از: png, pdf, pdf1.4, pdf1.5, pdf1.6, pdf1.7, ps, eps, svg. پیش‌فرض png است. برای جزئیات بیشتر درباره قابلیت‌های هر نگارش، بخش «نگارش‌های پی‌دی‌اف» را ببینید.
مشخص کردن نام فایل خروجی. در صورت عدم تعیین، در خروجی استاندارد نوشته می‌شود.
نمایش نگارش فعال rsvg-convert.
-?, --help
نمایش خلاصه‌ای از نحوه استفاده و گزینه‌ها.

در موارد زیر، مقادیر length باید با قواعد نحوی <length> در CSS مشخص شوند: https://developer.mozilla.org/en-US/docs/Web/CSS/length. برای نمونه، 640px یا 25cm.

عرض صفحه سند خروجی. پیش‌فرض استفاده از عرض تصویر است که توسط گزینه‌های زیر تغییر می‌کند. باید همراه با --page-height استفاده شود.
ارتفاع صفحه سند خروجی. پیش‌فرض استفاده از ارتفاع تصویر است که توسط گزینه‌های زیر تغییر می‌کند. باید همراه با --page-width استفاده شود.
فاصله میان لبه بالایی صفحه و تصویر رندرشده. پیش‌فرض 0 است.
فاصله میان لبه چپ صفحه و تصویر رندرشده. پیش‌فرض 0 است.
عرض تصویر رندرشده. در صورت عدم تعیین، از عرض طبیعی تصویر استفاده می‌شود. برای جزئیات، بخش «تعیین اندازه رندرشده» در بالا را ببینید.
ارتفاع تصویر رندرشده. در صورت عدم تعیین، از ارتفاع طبیعی تصویر استفاده می‌شود. برای جزئیات، بخش «تعیین اندازه رندرشده» در بالا را ببینید.
مشخص کردن حفظ نسبت ابعاد تصویر. در صورت عدم تعیین، نسبت ابعاد حفظ نخواهد شد. تصویر به صورت متناسب برای جای‌گیری در --width و --height مقیاس‌بندی می‌شود.
تنظیم وضوح افقی (X) تصویر بر حسب نقطه در اینچ (DPI). پیش‌فرض 96 DPI است.
تنظیم وضوح عمودی (Y) تصویر بر حسب نقطه در اینچ (DPI). پیش‌فرض 96 DPI است.
ضریب مقیاس‌بندی افقی. پیش‌فرض 1.0 است.
ضریب مقیاس‌بندی عمودی. پیش‌فرض 1.0 است.
ضریب مقیاس‌بندی افقی و عمودی هم‌زمان. پیش‌فرض 1.0 است.

مشخص کردن رنگ پس‌زمینه. مقدار color باید با قواعد نحوی <color> در CSS مشخص شود: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value؛ به عنوان نمونه، black، #ff0000، rgba(0.0, 1.0, 0.0, 1.0). پیش‌فرض none است؛ این حالت تصاویر PNG شفاف یا PDF/PS/EPS بدون پس‌زمینه خاص ایجاد می‌کند.
نام فایل یک شیوه‌نامه (استایل‌شیت) سفارشی CSS.
مشخص کردن زبان‌های مورد استفاده برای اسناد SVG چندزبانه. این مقدار مانند هدر HTTP Accept-Language قالب‌بندی می‌شود که فهرستی از تگ‌های زبان BCP47 با جداکننده کاما است: https://www.rfc-editor.org/info/bcp47 برای نمونه es-MX,fr,en. پیش‌فرض استفاده از زبان مشخص‌شده توسط متغیرهای محیطی است؛ بخش «متغیرهای محیطی» را در زیر ببینید.

برای اسناد SVG که به تصاویر PNG یا JPEG ارجاع می‌دهند، تصاویر فشرده اصلی در خروجی نهایی قرار می‌گیرند، نه داده‌های فشرده‌نشده RGB. این رفتار پیش‌فرض برای خروجی‌های PDF و (E)PS است.
عدم گنجاندن تصاویر فشرده اصلی و در عوض جاسازی داده‌های فشرده‌نشده RGB در خروجی PDF یا (E)PS. این کار به احتمال زیاد منجر به اسناد بزرگ‌تری می‌شود که بارگذاری و خواندن آن‌ها کندتر است.

امکان مشخص کردن یک شیء SVG برای برون‌بری بر اساس صفت id در XML آن شیء. در صورت عدم تعیین، تمامی اشیا برون‌بری می‌شوند.
غیرفعال کردن محافظ‌های تجزیه‌گر XML. تجزیه‌گر XML دارای سازوکارهای حفاظتی برای مهار مصرف بیش از حد پردازنده یا حافظه در برابر اسناد مخرب است. همچنین ممکن است از تجزیه URIهای data: که برای جاسازی داده‌های تصویری در اسناد SVG استفاده می‌شوند خودداری کند. در صورت برخورد با چنین مواردی هنگام تبدیل SVG، این گزینه امکان غیرفعال‌سازی این محافظ‌ها را می‌دهد.
صرفاً ویژه توسعه‌دهندگان: رندر کردن تصاویر برای آزمون‌های خودکار librsvg.
تولید اسکریپت تکمیل خودکار تب (Tab completion) برای پوسته مشخص‌شده. مقادیر مجاز عبارتند از: bash, elvish, fish, powershell, zsh. سپس Rsvg-convert اسکریپت مناسب را در خروجی استاندارد می‌نویسد.

اگر قالب خروجی انتخابی PDF باشد، می‌توان از این متغیر برای کنترل فیلد CreationDate در فایل PDF استفاده کرد. این قابلیت برای تولید خروجی‌های تکرارپذیر (reproducible) مفید است. این متغیر محیطی باید روی یک عدد ده‌دهی متناظر با برچسب زمانی یونیکس (تعداد ثانیه‌های سپری‌شده از 01 Jan 1970 00:00:00 UTC بدون احتساب ثانیه‌های کبیسه) تنظیم شود. مشخصات این استاندارد در نشانی زیر در دسترس است: https://reproducible-builds.org/specs/source-date-epoch
مگر در صورتی که گزینه --accept-language مشخص شده باشد، حالت پیش‌فرض استفاده از محیط سیستم برای تشخیص زبان ترجیحی کاربر است. این سازوکار متغیرهای محیطی LANGUAGE، LC_ALL، LC_MESSAGES و LANG را بررسی می‌کند.

گزینه --format=pdf باعث می‌شود rsvg-convert خروجی را با جدیدترین نگارش PDF پشتیبانی‌شده تولید کند. به طور معمول این روش استاندارد است، مگر اینکه از ابزارهایی استفاده کنید که فایل‌های PDF حاصل را مصرف می‌کنند اما فقط از نگارش‌های خاصی پشتیبانی می‌نمایند.

برای نمونه، ابزارهای LaTeX مانند pdflatex در صورتی که تصویری PDF با نگارشی جدیدتر از سند اصلی درج کنید، ممکن است هشداری مشابه زیر صادر نمایند:

PDF inclusion: found PDF version <1.7> but at most version <1.5> allowed

در این حالت، ممکن است نیاز داشته باشید نگارش PDF تولیدی rsvg-convert را محدود کنید. به جای --format=pdf، می‌توانید از موارد زیر استفاده کنید:

از جریان‌های شیء PDF (object streams) استفاده نمی‌کند؛ فایل‌ها ممکن است بزرگ‌تر باشند زیرا فشرده‌سازی کمتری دارند.
امکان ایجاد فایل‌های PDF با قابلیت انتخاب و جستجوی متن را فراهم می‌کند.
بدون رفتار ویژه.
امکان گنجاندن مطمئن نام‌فایل‌های دارای نویسه‌های UTF-8 در اشیای پیوند را فراهم می‌سازد.

اگر از ابزارهای LaTeX استفاده می‌کنید، ممکن است بخواهید گزینه‌هایی مانند \pdfminorversion=6 را بررسی نمایید.

مخزن کد مبدأ و ردیاب اشکالات Librsvg: https://gitlab.gnome.org/GNOME/librsvg

صفحه پروژه در ویکی: https://gnome.pages.gitlab.gnome.org/librsvg

مشخصات SVG1.1: https://www.w3.org/TR/SVG11

مشخصات SVG2: https://www.w3.org/TR/SVG2

صفحه پروژه گنوم (GNOME): https://www.gnome.org