rsvg-convert.1

.\" -*- fill-column:100 -*-
.TH rsvg-convert 1
.SH NAME
rsvg-convert \- Render SVG documents to PNG images, or convert them to PDF or PS.
.SH SYNOPSIS
Convert an SVG to PNG at its "natural size" and write it to standard output:
.P
.RS
.B rsvg-convert
.I input.svg
.B >
.I output.png
.RE
.P
Specify an output filename; the input filename must be the last argument:
.P
.RS
.B rsvg-convert
.BI --output= output.png
.I input.svg
.RE
.P
Configure dots-per-inch (DPI), default is 96:
.P
.RS
.B rsvg-convert
.BI --dpi-x= 300
.BI --dpi-y= 300
.I input.svg
.B >
.I output.png
.RE
.P
Render an SVG at a specific pixel size, scaled proportionally:
.P
.RS
.B rsvg-convert
.BI --width= 1024
.BI --height= 768
.B --keep-aspect-ratio
.I input.svg
.B >
.I output.png
.RE
.P

.SH DESCRIPTION
.BR rsvg-convert
renders SVG documents into PNG raster images, or converts them to PDF or PS as vector objects.
By default
.BR rsvg-convert
will render an SVG document to a raster PNG image and write it to standard output:
.P
.RS
.B rsvg-convert
.I input.svg
.B >
.I output.png
.RE
.P
To select another format, use the
.B --format
option:
.P
.RS
.B rsvg-convert --format=pdf
.I input.svg
.B >
.I output.pdf
.RE
.P
You can use
.BR rsvg-convert
as part of a pipeline; without an argument for the input filename it will read the document from standard input:
.P
.RS
.B cat
.I input.svg
.B |
.B rsvg-convert
.B >
.I output.png
.RE
.P
.SS SPECIFYING THE RENDERED SIZE
You can use the
.B --width
and
.B --height
options to specify the size of the output image.  Most of the time you should specify
.B --keep-aspect-ratio
to scale the image proportionally; for compatibility with old versions this is not the default.
.P
.RS
.B rsvg-convert
.BI --width= 100
.BI --height= 200
.B --keep-aspect-ratio
.I input.svg
.B >
.I output.png
.RE
.P
You can also specify dimensions as CSS lengths, for example
.B 10px
or \"
.BR 8.5in .
The unit specifiers supported are as follows:
.RS
.TS
tab (@);
l lx.
px@T{
pixels (the unit specifier can be omitted)
T}
in@T{
inches
T}
cm@T{
centimeters
T}
mm@T{
millimeters
T}
pt@T{
points, 1/72 inch
T}
pc@T{
picas, 1/6 inch
T}
.TE
.RE
.P
The following will create a 600*900 pixel PNG, or 2*3 inches at 300 dots-per-inch:
.P
.RS
.B rsvg-convert
.BI --width= 2in
.BI --height= 3in
.B --keep-aspect-ratio
.BI --dpi-x= 300
.BI --dpi-y= 300
.I input.svg
.B >
.I output.png
.RE
.P
This will scale an SVG document to fit in an A4 page and convert it to PDF:
.P
.RS
.B rsvg-convert
.BI --format= pdf
.BI --width= 210mm
.BI --height= 297mm
.B --keep-aspect-ratio
.I input.svg
.B >
.I output.pdf
.RE
.P

.SS SPECIFYING A PAGE SIZE
By default the size of the output comes from the rendered size, which can be specified with the
.B --width
and
.B --height
options, but you can specify a page size independently of the rendered size with
.B --page-width
and
.BR --page-height ,
together with
.B --top
and
.B --left
to control the position of the rendered image within the page.

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:
.P
.RS
.B rsvg-convert
.BI --format= pdf
.BI --page-width= 297mm
.BI --page-height= 210mm
.BI --width= 10cm
.BI --height= 10cm
.B --keep-aspect-ratio
.BI --top= 5cm
.BI --left= 8cm
.I input.svg
.B >
.I output.pdf
.RE
.P

.SS SPECIFYING A SCALE FACTOR INSTEAD OF A RENDERED SIZE
The
.B --zoom
option lets you scale the natural size of an SVG document.  For example, if
.I 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):
.P
.RS
.B rsvg-convert
.BI --zoom=2.5
.I input.svg
.B >
.I output.png
.RE
.P
You can limit the maximum scaled size by specifying the
.B --width
and
.B --height
options together with
.BR --zoom.
Here, the image will be scaled 10x, but limited to 1000*1000\ pixels at the most:
.P
.RS
.B rsvg-convert
.BI --zoom=10
.BI --width=1000
.BI --height=1000
.I input.svg
.B >
.I output.png
.RE
.P
If you need different scale factors for the horizontal and vertical dimensions, use the
.B --x-zoom
and
.B --y-zoom
options instead of
.BR --zoom.

.SS 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:
.P
.RS
.B rsvg-convert
.BI --format= pdf
.I pg1.svg
.I pg2.svg
.I pg3.svg
.B >
.I out.pdf
.RE
.P
The size of each page will be computed, separately, as described in the
.B "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
.B --page-width
and
.B --page-height
options.
.P
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:
.P
.RS
.B rsvg-convert
.BI --format= pdf
.BI --page-width= 8.5in
.BI --page-height= 11in
.BI --width= 6.5in
.BI --height= 9in
.B --keep-aspect-ratio
.BI --top= 1in
.BI --left= 1in
.I pg1.svg
.I pg2.svg
.I pg3.svg
.B >
.I out.pdf
.RE
.P
.SS CONVERSION OF PIXELS BASED ON THE DOTS-PER-INCH
.B rsvg-convert
uses the
.B --dpi-x
and
.B --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:
.P
.in +4n
.EX
<svg xmlns="http://www.w3.org/2000/svg" width="2in" height="3in">
  <!-- graphical objects here -->
</svg>
.EE
.in
.P
The following commands create PNGs of different sizes for the example SVG above:
.P
.RS
.B rsvg-convert
.I two-by-three.svg
.B >
.I output.png
#### creates a 192*288\ pixel PNG
.P
.B rsvg-convert
.BI --dpi-x= 300
.BI --dpi-y= 300
.I two-by-three.svg
.B >
.I output.png
#### creates a 600*900\ pixel PNG
.RE
.P

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,
.B rsvg-convert
will generate a PNG 300x300 pixels in size:
.P
.RS
.B rsvg-convert
.BI --width= 299.5
.BI --height= 299.4
.I input.svg
.B >
.I output.png
#### outputs 300x300 pixel PNG with a fractionally-scaled image
.RE
.P
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:
.P
.RS
.B rsvg-convert
.BI --width= 1in
.BI --height= 1in
.I input.svg
.B >
.I output.png
#### outputs 96x96 pixel PNG
.RE
.P
Correspondingly, this will generate a 300x300 pixel PNG, since it is 1x1 inch at 300 DPI:
.P
.RS
.B rsvg-convert
.BI --width= 1in
.BI --height= 1in
.BI --dpi-x= 300
.BI --dpi-y= 300
.I input.svg
.B >
.I output.png
#### outputs 300x300 pixel PNG
.RE

.SS DEFAULT OUTPUT SIZE
If you do not specify
.B --width
or
.B --height
options for the output size,
.BR rsvg-convert
will figure out a "natural size" for the SVG as follows:
.IP \(bu 2
.B SVG with width and height in pixel units (px):
.B <svg\ width="96px"\ height="192px">
For PNG output, those same dimensions in pixels are used.  For PDF/PS/EPS, that pixel size is
converted to physical units based on the DPI value (see the
.B --dpi-x
and
.B --dpi-y
options),
.IP \(bu 2
.B SVG with width and height in physical units:
.B <svg\ width="1in"\ height="2in">
For PNG output, the
.B width
and
.B height
attributes get converted to pixels, based on the DPI value (see the
.B --dpi-x
and
.B --dpi-y
options).  For PDF/PS/EPS output, the width/height in physical units define the size of the PDF
unless you specify options for the page size; see
.B "SPECIFYING A PAGE SIZE"
above.
.IP \(bu 2
.B SVG with viewBox only:
.B <svg viewBox="0 0 20 30">
The size of the
.B viewBox
attribute gets used for the pixel size of the image as in the first case above.
.IP \(bu 2
.B SVG with width and height in percentages:
.B <svg width="100%" height="100%" viewBox="0 0 20 30">
Percentages are meaningless unless you specify a viewport size with the
.B --width
and
.B --height
options.  In their absence,
.B rsvg-convert
will just use the size of the
.B viewBox
for the pixel size, as described above.
.IP \(bu 2
.B SVG with no width, height, or viewBox:
.B rsvg-convert
will measure the extents of all graphical objects in the SVG document and render them at 1:1 scale
(1\ pixel for each CSS\ px\ unit).  It is strongly recommended that you give SVG documents an
explicit size with the
.B width, height,
or
.B viewBox
attributes.

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

.P
.RS
.B rsvg-convert
.BI --background-color= white
.I input.svg
.B >
.I output.png
#### opaque white
.RE
.P
.RS
.P
.B rsvg-convert
.B -b
.I '#ff000080'
.I input.svg
.B >
.I output.png
#### translucent red - use shell quotes so the # is not interpreted as a comment
.RE

.SS SELECTING A LANGUAGE FOR MULTI-LANGUAGE SVG

An SVG document can use the
.B <switch>
element and children with the
.B systemLanguage
attribute to provide different content depending on the user's language.  For example:
.P
.in +4n
.EX
<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>
.EE
.in
.P
You can use the
.B --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

.P
.RS
.B rsvg-convert
.BI --accept-language= es-MX
.I input.svg
.B >
.I output.png
#### selects Mexican Spanish; renders "Español".
.RE
.P

.SS USER STYLESHEET

You can include an extra CSS stylesheet to be used when rendering an SVG document with the
.B --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
.B !important
in its styles.
.P
.RS
.B rsvg-convert
.BI --stylesheet= extra-styles.css
.I input.svg
.B >
.I output.png
.RE
.P

For example, if this is
.IR input.svg :
.P
.in +4n
.EX
 <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>
.EE
.in
.P
And this is
.IR extra-styles.css :
.P
.in +4n
.EX
 \.recolorable { fill: blue; }

 * { color: green; }
.EE
.in
.P
Then the PNG created by the command above will have these elements:
.IP \(bu 2
A blue square instead of a red one, because of the selector for the the
.B recolorable
class.
.IP \(bu 2
Text in green, since a fill with
.B currentColor
gets substituted to the value of the
.B color
property, and the
.B *
selector applies to all elements.


.SH OPTIONS

.SS GENERAL OPTIONS
.TP
.I "\-f \-\-format [png, pdf, ps, eps, svg]"
Output format for the rendered document.  Default is png.
.TP
.I "\-o \-\-output filename"
Specify the output filename.  If unspecified, outputs to standard output.
.TP
.I "\-v \-\-version"
Display what version of rsvg-convert you are running.
.TP
.I "\-\-help"
Display a summary of usage and options.

.SS SIZE AND POSITION
.TP
.I "\-\-page-width length \-\-page-height length"
Page size of the output document; both options must be used together.  The default is to use the image's
width and height as modified by the options below.

.TP
.I "\-\-top length"
Distance between top edge of the page and the rendered image.  Default is 0.
.TP
.I "\-\-left length"
Distance between left edge of the page and the rendered image.  Default is 0.

.TP
.I "\-w \-\-width length"
Width of the rendered image.  If unspecified, the natural width of the image is used
as the default.  See the section "SPECIFYING DIMENSIONS" above for details.
.TP
.I "\-h \-\-height integer"
Height of the rendered image.  If unspecified, the natural height of the image is used
as the default.  See the section "SPECIFYING DIMENSIONS" above for details.
.TP
.I "\-a \-\-keep-aspect-ratio"
Specify that the aspect ratio is to be preserved, i.e. the image is scaled proportionally to fit in the
.B --width
and
.BR --height \.
If not specified, aspect ratio will not be preserved.

.TP
.I "\-d \-\-dpi-x number"
Set the X resolution of the image in pixels per inch.  Default is 96\ DPI.
.TP
.I "\-p \-\-dpi-y number"
Set the Y resolution of the image in pixels per inch.  Default is 96\ DPI.
.TP
.I "\-x \-\-x\-zoom number"
Horizontal scaling factor.  Default is 1.0.
.TP
.I "\-y \-\-y\-zoom number"
Vertical factor factor.  Default is 1.0.
.TP
.I "\-z \-\-zoom number"
Horizontal and vertical scaling factor.  Default is 1.0.

.SS CONTROLLING THE RENDERED APPEARANCE
.TP
.I "\-b \-\-background-color [black, white, #abccee, #aaa...]"
Specify the background color.  If unspecified, none is used as the default; this will create
transparent PNGs, or PDF/PS/EPS without a special background.
.TP
.I "\-s \-\-stylesheet filename.css"
Filename of a custom CSS stylesheet.
.TP
.I "\-l \-\-accept-language [es-MX,fr,en]"
Specify which languages will be used for SVG documents with multiple languages.  The string is
formatted like an HTTP Accept-Language header, which is a comma-separated list of BCP47 language
tags: https://www.rfc-editor.org/info/bcp47.  The default is to use the language specified by
environment variables; see the section "ENVIRONMENT VARIABLES" below.

.SS OPTIONS SPECIFIC TO PDF/PS/EPS OUTPUT
.TP
.I "\-\-keep-image-data"
Include the original, compressed images in the final output, rather than uncompressed RGB data. This
is the default behavior for PDF and (E)PS output.
.TP
.I "\-\-no-keep-image-data"
Do not include the original, compressed images but instead embed uncompressed RGB date in PDF or
(E)PS output. This will most likely result in larger documents that are slower to read.

.SS MISCELLANEOUS
.TP
.I "\-i \-\-export-id object-id"
Allows to specify an SVG object that should be exported based on its XML id.  If not specified, all
objects will be exported.
.TP
.I "\-u \-\-unlimited"
The XML parser has some guards designed to mitigate large CPU or memory consumption in the face of
malicious documents.  It may also refuse to resolve data: URIs used to embed image data.  If you are
running into such issues when converting a SVG, this option allows to turn off these guards.
.TP
.I "\-\-testing"
For developers only: render images for librsvg's test suite.

.SH ENVIRONMENT VARIABLES
.TP
.I "SOURCE_DATE_EPOCH"
If the selected output format is PDF, this variable can be used to control the CreationDate in the
PDF file.  This is useful for reproducible output.  The environment variable must be set to a
decimal number corresponding to a UNIX timestamp, defined as the number of seconds, excluding leap
seconds, since 01 Jan 1970 00:00:00 UTC.  The specification for this can be found at
https://reproducible-builds.org/specs/source-date-epoch/
.TP
.I System language
Unless the
.B --accept-language
option is specified, the default is to use the system's environment to detect the user's preferred
language.  This consults the environment variables
.IR LANGUAGE ,
.IR LC_ALL ,
.IR LC_MESSAGES ,
and
.IR LANG .

.SH MORE INFORMATION

https://gitlab.gnome.org/GNOME/librsvg

https://wiki.gnome.org/Projects/LibRsvg

http://www.w3.org/TR/SVG11/

http://www.w3.org/TR/SVG2

http://www.gnome.org/

.SH "AUTHORS"
Dom Lachowicz (cinamod@hotmail.com), Caleb Moore (c.moore@student.unsw.edu.au), Federico
Mena-Quintero (federico@gnome.org), and a host of others.