/ 
Image-CairoSVG-0.15
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 into a 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.15 corresponding to git commit 65b8cba385c30a84dc1897d40012c461ae1b6bc1 released on Sun May 2 12:55:05 2021 +0900.

DESCRIPTION

This module renders some kinds of SVG ("Scalable Vector Graphics") instructions into a Cairo surface.

METHODS

new

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

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)
);

The user can also supply a Cairo context:

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

If a Cairo context is supplied, the value of surface is ignored, and the image is drawn using the context value.

For a simple drawing task, use the surface generated by the module, 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.

render

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

Draw an SVG file into a Cairo surface. The return value is the surface drawn into.

If the user did not supply a context or a surface in "new", a new Cairo::ImageSurface object is generated. If the user supplied a context with "new", the return value is undefined and should be ignored. If the user supplied a surface with "new", the return value is just that surface.

If the call value is a scalar containing what looks like XML, it is parsed from the scalar instead.

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, used under CC-BY 4.0)

DRAWING METHODS

All of these methods take the attributes of the specific element after which they're named. So, for example, if you have an SVG line element, you can parse its attributes with an XML parser, then send the hash of key/value pairs in the attributes to "line".

line

$cairosvg->line (%attr);

Render an SVG line onto 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 render the "d" attibute of the path. It also converts quadratic bezier curves into cubic bezier curves.

rect

$cairosvg->rect (%attr);

ellipse

$cairosvg->ellipse (%attr);

circle

$cairosvg->circle (%attr);

polygon

$cairosvg->polygon (%attr);

Draws a polygon based on the points attribute, closing the path.

polyline

$cairosvg->polyline (%attr);

The same as "polygon" except that it doesn't close the path.

DEPENDENCIES

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.

Math::Trig

Used for the value of pi and various functions related to drawing arcs.

XML::Parser

XML::Parser is used for parsing SVG files.

SEE ALSO

Demonstration website - Super Tiny Icons

The demonstration website https://benkasminbullock.github.io/supertinyiconscairosvg/ shows the output of Image::CairoSVG on the Super Tiny Icons collection and the Twitter Emoji Collection.

Other software

CairoSVG

CairoSVG is a Python SVG renderer in Cairo. Originally parts of this were based on it, but these parts were all replaced in version 0.14 of this module by code based on the W3 Consortium code.

Image::LibRSVG

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

Image::SVG::Path

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

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. I 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

This Perl Cairo tutorial may be useful if you need to go beyond defaults.

BUGS

Clip paths

Does not support clip paths (clipping the output image to a given path).

Copied paths

Does not support xlink:href (copied paths).

Elliptical arcs

Elliptical arcs are not handled correctly. There are no primitives in Cairo for these shapes so they will need to be implemented via Cairo transforms.

Gradients

Gradients are not supported.

Groups

Groups are not supported, although inherited fill/stroke and other attributes are supported.

Inherited fill / stroke values

The handling of fill and stroke inherited from parent elements may be somewhat patchy.

Opacity

Opacity support is missing.

stroke-dasharray

stroke-dasharray is not supported.

Transforms

Transforms are not handled. Cairo does have facilities to do transforms so implementing them should not be too difficult.

Units

Units have been added haphazardly as they have been found in actual SVG documents. Although pixel units seem easy enough to understand, we're not exactly sure what the correct treatment of units such as millimetres or percents should be, so there is some guesswork at the moment.

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.

cairosvg licence

Some parts of the module (specifically the SVG arc drawing code) are translations from the above-mentioned Python program "cairosvg", which is under the "GNU LESSER GENERAL PUBLIC LICENSE Version 3, 29 June 2007". I'm not really sure how or if this affects the code, but just in case it causes legal issues for someone downstream, I'm mentioning it here.