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.

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.

NAME

METHODS

new