PDF::Bu...age::SVG(3)

👑 NAME 👑

PDF::Builder::Resource::XObject::Image::SVG — support routines for the SVG (Scalable Vector Graphics) image library 🦋

(You've landed in the PDF::Builder::Resource::XObject::Image::SVG(3) page, from the User Contributed Perl Documentation. Welcome, bestie 💅)

It inherits from PDF::Builder::Resource::XObject::Image — family tree matters, okay?

⚠️ Okay so here's the one thing that makes this module different from literally every other image format: unlike the output of other image formats, image_svg() returns an array of anonymous hashes, one for each <svg> tag inside your SVG input. That's just the vibe. Full deets in "What is returned" down below 👇

---

✨ METHODS ✨

🌟 new

$res = PDF::Builder::Resource::XObject::Image::SVG->new($pdf, $file, %opts)

$file is your SVG input (peep the SVGPDF library for the details and limitations, fr fr). It can be any one of these three things:

• a filename 📄
• a string reference (with SVG content inside it) 🧵
• a filehandle 🔧

🎀 Options 🎀

• subimage => n — if your SVG file has multiple svg entries and they are not combined by SVGPDF's combine option into one image, this lets you pick which image to display. Any n goes, from 0 up to the number of svg images minus 1. The n-th element gets retained, and all the others get discarded. The default is to return the entire array and remove nothing, which lets you display multiple images in whatever order you want. See the whole discussion on combining multiple images in "Dealing with multiple image objects, and combining them". The default behavior of the display routine (object) is to display only the first element (and there has to be at least one, periodt).
• MScore => flag — set it true (a non-zero value) and a font callback for the 14 Microsoft Windows "core" extensions gets added to whatever other font callbacks the user gave. Those include "Georgia" serif, "Verdana" sans-serif, and "Trebuchet" sans-serif fonts, plus the "Wingdings" and "Webdings" symbology fonts. Non-Windows systems usually don't include these "core" fonts, so it may be unsafe to use them, ngl.

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). But this does not guarantee those fonts will be available on the machine used to read the resulting PDF! 😭

• compress => flag — set it true (a non-zero value; default is 1) and the resulting XObject stream gets compressed. That's what you'd normally do, obviously. Set it false (0) and the stream is left uncompressed instead. You might want that if you're trying to examine the stream in the finished PDF, like the t-test does. 🔍

🎀 SVGPDF Options 🎀

These are options which, if given, get 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 you. Go consult the SVGPDF library documentation for more details on these, bestie.

• pdf => PDF object — automatically set by the SVG routine, and it can not be overridden by the user. It gets passed to SVGPDF->new().
• fontsize => n — the font size (in points) for SVGPDF to use to scale text and figure the em and ex sizes. Default is 12 points. Passed on to both the SVGPDF->new() and $svg->process() SVGPDF methods.
• pagesize => [ width, height ] — the maximum dimensions of the resulting object, in case there are no dimensions given, or they're too large to display. Default is 595 pt x 842 pt (A4 page size), internal to SVGPDF. Passed to SVGPDF->new().
• grid => n — default is 0. A value greater than 0 indicates the spacing (in points) of a grid, for development/debugging purposes. Passed to SVGPDF->new().
• verbose => n — defaults to 0 (fatal messages only), but you can crank it higher to get informational messages out. Passed to SVGPDF->new().
• fc => \&fonthandler_callback — a list of one or more callbacks for the font handler. If the MScore flag is true (see above), another callback gets added to the list to handle MS Windows "core" font faces. 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, they'd need to be added to FontManager. You should check the resulting SVG files produced by Third-Party packages to see what fonts they're expecting. MathJax creates text characters as filled outlines in SVG, and does not appear to use any standard fonts.

• combine => 'method' — if an SVG defines multiple XObjects (because of multiple svg entries), they may be combined into a single XObject. 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 it may be in the future. Passed to $svg->process().
• sep => n — vertical space (in points) to add between individual images when combine is not 'none'. Default is 0 (no space between images). Passed to $svg->process().

🦋 What is returned 🦋

Returns an image in the SVG. But unlike other image formats, it's not actually some form of image object — it's 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 gets scaled up and down 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. And note that svgs 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 therefore 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 gets returned. If you set subimage => n, where n is a valid element number (0...), all elements except the n-th get discarded, leaving a single-element array. When it comes time for object() to display this XObject array, the first (0th) element gets displayed and any other elements are ignored. So the default behavior is effectively subimage => 0. You may call either object or image — image will simply pass everything on to object.

Remember that not setting subimage causes the entire array to be returned. You're free to rearrange and/or subset this array if you wish. If you want to display multiple images (in the PDF), 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, maybe 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.

That 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's 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 svgs scaled at different sizes — they may need rescaling to overlay properly. 👑

---

🎀 And that's the whole page, bestie. This one's from perl v5.42.0, dated 2026-01-17 — go forth and vector, no cap 💖✨