/ 
Image-CairoSVG-0.17
River stage one • 1 direct dependent • 1 total dependent
/ Image::CairoSVG

NAME

Image::CairoSVG - Render SVG into a Cairo surface

SYNOPSIS

This example converts an SVG file into PNG:

use FindBin '$Bin';
use Cairo;
use Image::CairoSVG;
my $cairosvg = Image::CairoSVG->new ();
my $surface = $cairosvg->render ("$Bin/locust.svg");
$surface->write_to_png ("$Bin/locust.png");

This renders the following image:

(This example is included as synopsis.pl in the distribution. The input and output files are also included.)

VERSION

This documents Image::CairoSVG version 0.17 corresponding to git commit bcf7f3e01e92ea2f16c874e362c90ad677bcf34e released on Sun May 9 22:21:29 2021 +0900.

DESCRIPTION

This module renders SVG ("Scalable Vector Graphics") instructions into a Cairo surface. The user can then choose what to do with the surface, for example write it out to a PNG file.

METHODS

new

my $cairosvg = Image::CairoSVG->new (%arguments);

Arguments are as follows

surface

The user can supply a Cairo surface:

my $cairosvg = Image::CairoSVG->new (surface => $surface);

For example,

my $cairosvg = Image::CairoSVG->new (
    surface => Cairo::ImageSurface->create ('argb32', 100, 100)
);
context

The user can also supply a Cairo context:

my $cairosvg = Image::CairoSVG->new (context => $cr);

If a Cairo context and a surface are both supplied, the value of surface is ignored, a warning is printed, and the image is drawn using only the context value.

For simple drawing tasks, we recommend using the default surface generated by this module, which is the return value from "render". Only supply a surface if the module gets the dimensions of your image wrong. Only use a Cairo context if you want to include the image in some other image or rescale it. See "Scaling the output" for an example.

render

my $surface = $cairosvg->render ('some.svg');

Draw an SVG file or scalar into a Cairo surface. The return value is the surface drawn into. If the call value is a scalar containing what looks like XML, it is parsed from the scalar instead. This method guesses whether its argument is a file or a scalar by looking for a pair of angle brackets (<>) in its first argument. If it does not find angle brackets, it assumes the argument is a file name.

If the user did not supply a context or a surface to "new", a new Cairo::ImageSurface object is generated. If the user supplies a context argument with "new", the return value of render should be ignored. If the user supplied a surface with "new", the return value is just that surface.

If the user does not specify a surface, the generated surface returned by render is based on the attributes of the <svg> element, specifically either the width and height attributes, or the width and height specified in the viewBox attribute.

Calling with a scalar containing XML was added in version 0.08.

EXAMPLES

Scaling the output

This example shows how to scale the output image using Cairo commands.

use FindBin '$Bin';
use Cairo;
use Image::CairoSVG;
# Using defaults
my $dcairosvg = Image::CairoSVG->new ();
my $dsurface = $dcairosvg->render ("$Bin/urn.svg");
$dsurface->write_to_png ("$Bin/durn.png");
# Scale to 200 pixels
my $size = 200;
my $twsize = 36;
my $surface = Cairo::ImageSurface->create ('argb32', $size, $size);
my $context = Cairo::Context->create ($surface);
my $cairosvg = Image::CairoSVG->new (context => $context);
$context->scale ($size/$twsize, $size/$twsize);
$cairosvg->render ("$Bin/urn.svg");
$surface->write_to_png ("$Bin/urn.png");

The default size looks like this:

The scaled image looks like this:

(This example is included as scale.pl in the distribution. The original image is part of the Twitter Emoji collection, 1f3fa.svg, representing U+1F3FA AMPHORA. This illustration is used under the terms of CC-BY 4.0)

DRAWING METHODS

The drawing methods of the module are as follows.

circle

$cairosvg->circle (%attr);

Draw the circle specified by the SVG attributes in %attr into the surface of $cairosvg.

ellipse

$cairosvg->ellipse (%attr);

Draw the ellipse specified by the SVG attributes in %attr into the surface of $cairosvg.

line

$cairosvg->line (%attr);

Render the line specified by the SVG attributes in %attr into the surface specified by $cairosvg. Given SVG input of the form <line >, this renders it onto the Cairo surface.

path

$cairosvg->path (%attr);

Given an SVG path element, send its attribute key / value pairs as %attr to render into the Cairo surface of $cairosvg. This uses Image::SVG::Path to parse the "d" attibute of the path.

This converts any quadratic bezier curves found in the path into cubic bezier curves, since Cairo does not support quadratic bezier curves.

polygon

$cairosvg->polygon (%attr);

Draw the polygon specified by the points attribute of %attr, closing the path.

polyline

$cairosvg->polyline (%attr);

Similar to "polygon" except that it doesn't close the path.

processUse

$cairosvg->processUse (%attr);

Process a <use> SVG element. It relies on $cairosvg already having processed the XML file in order to find the used element.

rect

$cairosvg->rect (%attr);

Draw the rectangle specified by %attr into the surface contained in $cairosvg.

If the rectangle has rounded corners (a non-zero rx attribute), a shim function is used to draw the rectangle, since Cairo has no native support for rectangles with rounded corners.

DEPENDENCIES

This module depends on the following other modules.

Cairo

Cairo is used for rendering the image.

Carp

Carp is used for reporting errors.

Image::SVG::Path

Image::SVG::Path is used for parsing the "path" information of the SVG, see "path".

Math::Trig

This is used for the value of pi, and for various functions related to drawing arcs, and for converting angles between radians (used by Cairo) and degrees (used by SVG).

XML::Parser

XML::Parser is used for parsing SVG files.

SEE ALSO

Demonstration website and blog articles

This demonstration website shows the output of Image::CairoSVG on the Super Tiny Icons collection and the Twitter Emoji Collection.

Please see "BUGS" below for notable errors in the rendering.

Blog articles

I've written some blog articles about extending the SVG support in this module.

Trying to get SVG right

This was the first article, where I had discovered that the module's arc-drawing code and arc-parsing code was not working.

Improvements to Image::CairoSVG

This illustrates some of the improvements made.

Other software

CairoSVG

CairoSVG is a Python SVG renderer in Cairo. Originally the elliptical arc drawing part of Image::CairoSVG was based on it, but this was replaced in version 0.14 of this module by code based on the W3 Consortium standards.

Image::LibRSVG

Perl extension for a Gnome library called librsvg which converts SVG to PNG or JPEG, etc. We have not tested this library.

Image::Magick

Does SVG to PNG conversion.

Image::SVG::Path

This is a specialised module for reading the "d" attribute of SVG paths.

Image::SVG::Transform

Read the "transform" attribute of an SVG element.

MarpaX::Languages::SVG::Parser

This extends the Marpa::R2 parser to parse SVG.

SVG

This is for generating SVG documents.

SVG::Parser

Parse the XML for SVG files. It can use either XML::Parser or XML::SAX but XML::Parser seems not to work. See https://rt.cpan.org/Ticket/Display.html?id=136404.

SVG::Rasterize

Rasterize SVG content to pixel graphics. We couldn't get this to produce output. See https://rt.cpan.org/Ticket/Display.html?id=136405.

More information

Perl Maven article

SVG - Scalable Vector Graphics with Perl - article at Perl Maven

Perl Cairo tutorial

The Cairo module is mostly undocumented. This Perl Cairo tutorial may be useful if you need to go beyond defaults.

BUGS

Various parts of the SVG standard are not implemented, as follows.

If viewing the HTML version of this page, the illustrations below each bug description demonstrate instances from the Super Tiny Icons collection where the bug causes a rendering problem. See "Demonstration website and blog articles" above.

Clip paths

Clip paths (clipping the output image to a given path) are not supported. These are supported in Cairo so it should be possible to add them.

Input SVG Output of Image::CairoSVG
Elliptical arcs

Circular arcs are produced correctly but elliptical arcs in paths are not handled correctly. This is because there are no primitives in Cairo for these shapes, so they need to be implemented via Cairo transforms.

Input SVG Output of Image::CairoSVG
Gradients

Gradients are not supported.

There is support in Cairo so it should be possible to add them.

Input SVG Output of Image::CairoSVG
shadows

Shadows are not supported.

stroke-dasharray

stroke-dasharray is not supported.

Input SVG Output of Image::CairoSVG
Text

Text rendering is not supported at all.

Transforms

Some transforms (matrix, skew) are not handled. There is some support for matrix transformations but the matrix transformations in Cairo are completely undocumented so it's based on guesswork and reading the Cairo source code. See https://rt.cpan.org/Ticket/Display.html?id=136410.

Input SVG Output of Image::CairoSVG
Units

Millimetre units are quite common in Inkscape output, so these are supported. Inches are also supported incidentally since in SVG millimetres are defined as 25.4 inches, and inches are defined by having 96 pixels per inch, but not all other possible units are.

AUTHOR

Ben Bullock, <bkb@cpan.org>

COPYRIGHT & LICENCE

This package and associated files are copyright (C) 2014-2021 Ben Bullock.

You can use, copy, modify and redistribute this package and associated files under the Perl Artistic Licence or the GNU General Public Licence.