Squirtle SVG mini-library version 0.2.4
=======================================


Squirtle is a mini-library for rendering SVGs from Python, using the Pyglet
multimedia library. It is designed to have a very simple interface, which allows
it to integrate easily into existing applications.

Example usage:
    import squirtle

    squirtle.setup_gl()

    my_svg = squirtle.SVG('filename.svg', anchor_x='center', anchor_y='center')
    my_svg.draw(100, 200, angle=15, scale=3)

Setting up
----------

To set up Squirtle, simply import the module and, once an OpenGL context has 
been created, call squirtle.setup_gl(). Usually in Pyglet this means something
like:

    import pyglet
    import squirtle

    win = pyglet.window.Window()
    squirtle.setup_gl()

If you are working with raw OpenGL calls as part of your application, you may
wish to incorporate the code from squirtle.setup_gl() into your own setup 
function. See the source code for further details.

Creating an SVG
---------------

SVG objects are instantiated simply by calling

    my_svg = squirtle.SVG(filename)

The filename argument can point to either an SVG or gzipped SVG (SVGZ) file.

There are also a collection of optional keyword arguments which can be used to
control the SVG created. For example:

    my_svg = squirtle.SVG('image.svg', anchor_x='center', anchor_y='center')

The anchor_x and anchor_y properties determine which point on the SVG is
considered to be the 'origin' when transforming and drawing. They default to the
bottom left corner. Anchor positions can be specified either numerically (in
pixels) or as symbolic names such as 'top', 'center', 'bottom', 'left' or 
'right'. They can also be modified after creation like so:

    my_svg = squirtle.SVG('image.svg')
    my_svg.anchor_x = my_svg.width * .75
    my_svg.anchor_y = 20

Note that the coordinate system used by Pyglet and the native SVG coordinate
system are flipped with respect to each other. All coordinates used in Squirtle
are in Pyglet-style (y increases upward) coordinates.

Two other options control the degree of subdivision used when rendering curves.
For example:

    my_svg = squirtle.SVG(filename, bezier_points=5, circle_points=12)

The bezier_points and circle_points options control the degree of subdivision
used on Bezier splines and elliptical arcs respectively. They default to 10 and
24. These properties cannot be changed after creation.

Drawing an SVG
--------------

At its most basic, rendering an SVG is as simple as:

    my_svg.draw(x, y)

This will render the given SVG, such that its (anchor_x, anchor_y) position is 
at screen coordinates (x, y). There are, of course, options which can be used to
modify the behaviour of this rendering. For example:

    my_svg.draw(x, y, z=-1)

This will draw the given SVG at a z-coordinate of -1, i.e. behind any other 
images which have been rendered. Note that using this to full effect requires
enabling OpenGL depth testing, and that SVGs with transparency may not render
correctly in this way.

The main advantages of SVG come from being able to freely rotate and scale
without loss of quality:

    my_svg.draw(x, y, angle=15, scale=3)

The angle and scale options control, rather obviously, the angle and scale at
which the SVG is rendered. Both options work around the pivot point given by
(anchor_x, anchor_y). Rotation is given in degrees counter-clockwise, and scale
is a simple multiplicative factor. It is also possible to give a 2-tuple of
scale values in order to scale anisotropically. For example, in order to flip
an SVG horizontally:

    my_svg.draw(x, y, scale=(-1, 1))

Limitations
-----------

Squirtle is at present quite limited in the SVG which it can render. Basic
geometric shapes, paths, polygons, etc work fine. Solid fills work, as do both
linear and radial gradients. Note that gradients may render slightly oddly due
to vertex colouring.

Significant aspects of the SVG specification which have not been implemented
include patterned fills, variable line widths, text and the symbol system.

Patches to improve on any of these limitations are greatly welcomed.

Changes since 0.2
-----------------

Fix errors in arc calculation.
Fix default winding rule for complex curves.
Fix support for SVGs created by Intaglio and some versions of Inkscape.
Improve efficiency when tesselating.
Fix crash bug on Win32 systems.

Changes since 0.1 (initial release)
-----------------------------------

Triangulation now uses the GLU tesselator functions, rather than the Python
code used previously. This should result in increased performance, as well as
allowing for more complex shapes.

Bugfixes for empty style definitions, and for radial gradients with inherited
properties.

Colophon
--------
Squirtle is released under a BSD license, which can be found in the accompanying
file LICENSE.txt

Bug reports, patches, etc, welcome to martin@supereffective.org