Provided by: libpdf-builder-perl_3.027-1_all 
NAME
PDF::Builder::Resource::XObject::Image::SVG - Support routines for SVG (Scalable Vector Graphics) image
library
Inherits from PDF::Builder::Resource::XObject::Image
Note that, unlike the output of other image formats, "image_svg()" returns an array of anonymous hashes,
one for each <svg> tag within the SVG input. See "What is returned" below for details.
METHODS
new
$res = PDF::Builder::Resource::XObject::Image::SVG->new($pdf, $file, %opts)
$file gives the SVG input (see the SVGPDF library for details and limitations). It may be a filename, a
string reference (with SVG content), or a filehandle.
Options:
subimage => n
If multiple "svg" entries are in an SVG file, and they are not combined by the SVGPDF "combine"
option into one image, this permits selection of which image to display. Any n may be given,
from 0 up to the number of "svg" images minus 1. The n-th element will be retained, and all
others discarded. The default is to return the entire array, and not remove any elements,
permitting display of mulitple images in any desired order. See the discussion on combining
multiple images "Dealing with multiple image objects, and combining them". The default behavior
of the display routine ("object") is to display only the first element (there must be at least
one).
MScore => flag
If set to true (a non-zero value), a font callback for the 14 Microsoft Windows "core" extensions
will be added to any other font callbacks given by the user. These include "Georgia" serif,
"Verdana" sans-serif, and "Trebuchet" sans-serif fonts, and "Wingdings" and "Webdings" symbology
fonts. Non-Windows systems usually don't include these "core" fonts, so it may be unsafe to use
them.
This option is enabled for all operating systems, not just MS Windows, so you can create PDFs
that make use of Windows "core" fonts (extension). This does not guarantee that such fonts will
be available on the machine used to read the resulting PDF!
compress => flag
If set to true (a non-zero value; default is 1), the resulting XObject stream will be compressed.
This is what you would normally do. On the other hand, setting it to false (0) leaves the stream
uncompressed. You may wish to do this if you want to examine the stream in the finished PDF, such
as is done for the t-test.
SVGPDF Options:
These are options which, if given, are passed on to the SVGPDF library. Some of them are fixed by
"image_svg" and can not be changed, while others are defaulted by "image_svg" but can be overridden
by the user.
You should consult the SVGPDF library documentation for more details on such options.
pdf => PDF object
This is automatically set by the SVG routine, and can not be overridden by the user. It is passed
to "SVGPDF->new()".
fontsize => n
This is the font size (in points) for SVGPDF to use to scale text and figure the em and ex sizes.
The default is 12 points. It is passed on to both the "SVGPDF->new()" and "$svg->process()"
SVGPDF methods.
pagesize => [ width, height ]
This is the maximum dimensions of the resulting object, in case there are no dimensions given, or
they are too large to display. The default is 595 pt x 842 pt (A4 page size), internal to SVGPDF.
It is passed to "SVGPDF->new()".
grid => n
The default is 0. A value greater than 0 indicates the spacing (in points) of a grid for
development/debugging purposes. It is passed to "SVGPDF->new()".
verbose => n
It defaults to 0 (fatal messages only), but the user may set it to a higher value for outputting
informational messages. It is passed to "SVGPDF->new()".
fc => \&fonthandler_callback
This is a list of one or more callbacks for the font handler. If the "MScore" flag is true (see
above), another callback will be added to the list to handle MS Windows "core" font faces. It is
passed to "SVGPDF->new()".
Note that some supporting packages, such as GnuPlot, make use of Windows fonts such as Arial,
which may or may not be installed on non-Windows platforms, and even for Windows, would need to
be added to FontManager. You should check the resulting SVG files produced by Third-Party
packages to see what fonts they are expecting. MathJax creates text characters as filled outlines
in SVG, and does not appear to use any standard fonts.
combine => 'method'
If there are multiple XObjects defined by an SVG (due to multiple "svg" entries), they may be
combined into a single XObject. The default is none, which does not combine XObjects. Currently,
the only other supported method is stacked, which vertically stacks images, with "sep" spacing
between them. At this writing, the bbox combine method is not supported by SVGPDF, but may be in
the future. It is passed to "$svg->process()".
sep => n
Vertical space (in points) to add between individual images when "combine" is not 'none'. The
default is 0 (no space between images). It is passed to "$svg->process()".
What is returned
Returns an image in the SVG. Unlike other image formats, it is not actually some form of image object,
but an array (of at least one element) containing XObjects of the SVG converted into PDF graphics and
text commands. If an SVG includes a pixel-based image, that image will be scaled up and down in the
normal image way, while PDF graphics and text are always fully scalable, both when setting an image size
and when zooming in and out in a PDF Reader.
A returned "object" is always an array of hashes (including the XObject as one of the elements), one per
"svg" tag. Note that "svg"s must be peers (top-level), and may not be nested one within another! In most
applications, an SVG file will have one "svg" tag and thus a single element in the array. However, some
SVGs will produce multiple array elements from multiple "svg" tags.
Dealing with multiple image objects, and combining them
If you don't set "subimage", the full array will be returned. If you set "subimage => n", where n is a
valid element number (0...), all elements except the n-th will be discarded, leaving a single element
array. When it comes time for object() to display this XObject array, the first (0th) element will be
displayed, and any other elements will be ignored. Thus, the default behavior is effectively "subimage =>
0". You may call either "object" or "image", as "image" will simply pass everything on to "object".
Remember that not setting "subimage" will cause the entire array to be returned. You are free to
rearrange and/or subset this array, if you wish. If you want to display (in the PDF) multiple images,
you can select one or more of the array elements to be processed (see the examples). If you want to stack
all of them vertically, perhaps with some space between them, consider using the "combine => 'stacked'"
option, but be aware that the total height of the single resulting image may be too large for your page!
You may need to output them separately, as many as will fit on a page.
This leaves the possibility of overlaying multiple images to overlap in one large combined image. You
have the various width and height (and bounding box coordinates), so it is possible to align images to
have the same origin. SVGPDF may get "combine => 'bbox'" at some point in the future, to automate this,
but for the time being you need to do it yourself. Keep an eye out for different "svg"s scaled at
different sizes; they may need rescaling to overlay properly.
perl v5.40.1 2025-08-10 PDF::Builder::...ect::Image::SVG(3pm)