SPECIFYING THE RENDERED SIZE¶

You can use the --width and --height options to specify the size of the output image. Most of the time you should specify --keep-aspect-ratio to scale the image proportionally; for compatibility with old versions this is not the default.

You can also specify dimensions as CSS lengths, for example 10px or 8.5in. The unit specifiers supported are as follows:

The following will create a 600*900 pixel PNG, or 2*3 inches at 300 dots-per-inch:

This will scale an SVG document to fit in an A4 page and convert it to PDF:

SPECIFYING A PAGE SIZE¶

By default the size of the output comes from the rendered size, which can be specified with the --width and --height options, but you can specify a page size independently of the rendered size with --page-width and --page-height, together with --top and --left to control the position of the rendered image within the page. In short:

This will create a PDF with a landscape A4 page, by scaling an SVG document to 10*10 cm, and placing it with its top-left corner 5 cm away from the top and 8 cm from the left of the page:

SPECIFYING A SCALE FACTOR INSTEAD OF A RENDERED SIZE¶

The --zoom option lets you scale the natural size of an SVG document. For example, if input.svg is a document with a declared size of 100*200 pixels, then the following command will render it at 250*500 pixels (zoom 2.5):

You can limit the maximum scaled size by specifying the --width and --height options together with --zoom. Here, the image will be scaled 10x, but limited to 1000*1000 pixels at the most:

If you need different scale factors for the horizontal and vertical dimensions, use the --x-zoom and --y-zoom options instead of --zoom.

CREATING A MULTI-PAGE DOCUMENT¶

The "pdf", "ps", and "eps" output formats support multiple pages. These can be created by combining multiple input SVG files. For example, this PDF file will have three pages:

The size of each page will be computed, separately, as described in the DEFAULT OUTPUT SIZE section. This may result in a PDF being produced with differently-sized pages. If you need to produce a PDF with all pages set to exactly the same size, use the --page-width and --page-height options.

For example, the following command creates a three-page PDF out of three SVG documents. All the pages are portrait US Letter, and each SVG is scaled to fit so that there is a 1in margin around each page (hence the width of 6.5in and height of 9in for the rendered size).

CONVERSION OF PIXELS BASED ON THE DOTS-PER-INCH¶

rsvg-convert uses the --dpi-x and --dpi-y options to configure the dots-per-inch (DPI) by which pixels will be converted to/from physical units like inches or centimeters. The default for both options is 96 DPI.

Consider this example SVG, which is nominally declared to be 2*3 inches in size:

<svg xmlns="http://www.w3.org/2000/svg" width="2in" height="3in">


  <!-- graphical objects here -->
</svg>

The following commands create PNGs of different sizes for the example SVG above:

Note that the final pixel dimensions are rounded up to the nearest pixel, to avoid clipping off the right/bottom edges. In the following example, rsvg-convert will generate a PNG 300x300 pixels in size:

If you specify dimensions in physical units, they will be multiplied by the dots-per-inch (DPI) value to obtain dimensions in pixels. For example, this will generate a 96x96 pixel PNG, since it is 1x1 inch at the default 96 DPI:

Correspondingly, this will generate a 300x300 pixel PNG, since it is 1x1 inch at 300 DPI:

DEFAULT OUTPUT SIZE¶

If you do not specify --width or --height options for the output size, rsvg-convert will figure out a "natural size" for the SVG as follows:

BACKGROUND COLOR¶

You can use the --background-color option (-b for short) to specify the background color that will appear in parts of the image that would otherwise be transparent. This option accepts the same syntax as the CSS color property, so you can use #rrggbb syntax, or CSS named colors like white, or rgba().

SELECTING A LANGUAGE FOR MULTI-LANGUAGE SVG¶

An SVG document can use the <switch> element and children with the systemLanguage attribute to provide different content depending on the user's language. For example:

<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>

You can use the --accept-language option to select which language to use when rendering. This option accepts strings formatted like an HTTP Accept-Language header, which is a comma-separated list of BCP47 language tags: https://www.rfc-editor.org/info/bcp47

USER STYLESHEET¶

You can include an extra CSS stylesheet to be used when rendering an SVG document with the --stylesheet option. The stylesheet will have the CSS user origin, while styles declared in the SVG document will have the CSS author origin. This means your extra stylesheet's styles will override or augment the ones in the document, unless the document has !important in its styles.

For example, if this is input.svg:

<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="currentColor">Hello</text>
</svg>

And this is extra-styles.css:

.recolorable { fill: blue; }
* { color: green; }

Then the PNG created by the command above will have these elements:

GENERAL OPTIONS¶

SIZE AND POSITION¶

In the following, <length> values must be specified with CSS <length> syntax: https://developer.mozilla.org/en-US/docs/Web/CSS/length. For example, 640px or 25cm.

CONTROLLING THE RENDERED APPEARANCE¶

OPTIONS SPECIFIC TO PDF/PS/EPS OUTPUT¶

MISCELLANEOUS¶