


=encoding UTF-8

=head1 NAME

Image::CairoSVG - render SVG into a Cairo surface

=head1 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");


=begin html 

<p>
This renders the following image:
</p>
<img width="451.271" height="187.542" src='https://fastapi.metacpan.org/source/BKB/Image-CairoSVG-0.16/examples/locust.png'>

=end html

(This example is included as L<F<synopsis.pl>|https://fastapi.metacpan.org/source/BKB/Image-CairoSVG-0.16/examples/synopsis.pl> in the distribution. The L<input|https://fastapi.metacpan.org/source/BKB/Image-CairoSVG-0.16/examples/locust.svg> and L<output files|https://fastapi.metacpan.org/source/BKB/Image-CairoSVG-0.16/examples/locust.png> are also included.)

=head1 VERSION

This documents Image::CairoSVG version 0.16
corresponding to git commit L<6bab4288745016723b4513f54789fe5b1b454899|https://github.com/benkasminbullock/image-cairosvg/commit/6bab4288745016723b4513f54789fe5b1b454899> released on Mon May 3 13:29:36 2021 +0900. 

=head1 DESCRIPTION

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

=head1 METHODS

=head2 new

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

Arguments are as follows

=over

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

=item 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
C<surface> is ignored, a warning is printed, and the image is drawn
using only the C<context> value.

=back

For simple drawing tasks, we recommend using the default surface
generated by this module, which is the return value from
L</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 L</Scaling the output>
for an example.

=head2 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 L</new>, a new
Cairo::ImageSurface object is generated. If the user supplies a
context argument with L</new>, the return value of render should be
ignored. If the user supplied a surface with L</new>, the return value
is just that surface.

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

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

=head1 EXAMPLES

=head2 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");


=begin html 

<p>
The default size looks like this:
</p>
<img width="36" height="36" src='https://fastapi.metacpan.org/source/BKB/Image-CairoSVG-0.16/examples/durn.png'>
<p>
The scaled image looks like this:
</p>
<img width="200" height="200" src='https://fastapi.metacpan.org/source/BKB/Image-CairoSVG-0.16/examples/urn.png'>

=end html

(This example is included as
L<F<scale.pl>|https://fastapi.metacpan.org/source/BKB/Image-CairoSVG-0.16/examples/scale.pl> in the distribution. The original image
is part of the L<Twitter Emoji
collection|https://twemoji.twitter.com/>, 1f3fa.svg, representing
U+1F3FA AMPHORA, used under L<CC-BY
4.0|https://creativecommons.org/licenses/by/4.0/>)

=head1 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 C<line>
element, you can parse its attributes with an XML parser, then send
the hash of key/value pairs in the attributes to L</line>.

=head2 line

    $cairosvg->line (%attr);

Render an SVG line onto the surface specified by C<$cairosvg>.  Given
SVG input of the form C<< <line > >>, this renders it onto the Cairo
surface.

=head2 path

    $cairosvg->path (%attr);

Given an SVG path element, send its attribute key / value pairs as
C<%attr> to render into the Cairo surface of C<$cairosvg>. This uses
L<Image::SVG::Path> to render the "d" attibute of the path. It also
converts quadratic bezier curves into cubic bezier curves, since Cairo
does not support quadratic bezier curves.

=head2 rect

    $cairosvg->rect (%attr);

=head2 ellipse

    $cairosvg->ellipse (%attr);

=head2 circle

    $cairosvg->circle (%attr);

=head2 polygon

    $cairosvg->polygon (%attr);

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

=head2 polyline

    $cairosvg->polyline (%attr);

The same as L</polygon> except that it doesn't close the path.

=head1 DEPENDENCIES

=over

=item L<Cairo>

Cairo is used for rendering the image.

=item L<Carp>

Carp is used for reporting errors.

=item L<Image::SVG::Path>

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

=item L<Math::Trig>

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

=item L<XML::Parser>

XML::Parser is used for parsing SVG files.

=back

=head1 SEE ALSO

=head2 Demonstration website - Super Tiny Icons

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

=head2 Other software

=over

=item CairoSVG

L<CairoSVG|http://cairosvg.org/> 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.

=back

=head2 Other CPAN modules related to SVG

=over

=item L<Image::LibRSVG>

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

=item L<Image::Magick>

Does SVG to PNG conversion.

=item L<Image::SVG::Path>

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

=item L<Image::SVG::Transform>

Read the "transform" attribute of an SVG element.

=item L<MarpaX::Languages::SVG::Parser>

This extends the L<Marpa::R2> parser to parse SVG.

=item L<SVG>

This is for generating SVG documents.

=item L<SVG::Parser>

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

=item L<SVG::Rasterize>

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

=back

=head2 More information

=over

=item Perl Maven article

L<SVG - Scalable Vector Graphics with Perl|http://perlmaven.com/scalable-vector-graphics-with-perl> - article at Perl Maven

=item Perl Cairo tutorial

This L<Perl Cairo
tutorial|https://www.lemoda.net/cairo/cairo-tutorial/index.html> may
be useful if you need to go beyond defaults.

=back

=head1 BUGS

=over

=item Clip paths

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

=item Copied paths

Does not support xlink:href (copied paths).

=item 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.

=item fill-rule

The C<fill-rule> attribute is not supported.

=item Gradients

Gradients are not supported.

=item Groups

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

=item Inherited fill / stroke values

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

=item stroke-dasharray

stroke-dasharray is not supported.

=item Transforms

Some transforms are not handled.

=item 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.

=back



=head1 AUTHOR

Ben Bullock, <bkb@cpan.org>

=head1 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.



