The latest version of this documentation is online at:

    http://code.google.com/p/svgload


Description
-----------

SvgBatch is a Python package to load SVG vector graphic files, and convert
them into pyglet Batch objects, for OpenGL rendering.

SVG:
    http://www.w3.org/TR/SVG11
pyglet:
    http://www.pyglet.org

The polygons from the SVG file are tessellated using GLU functions, and used to
create a pyglet Batch object of indexed vertex arrays of GL_TRIANGLES. The
Batch will aggregate all paths from an SVG file into a single OpenGL primitive
for rendering. Each path is also exposed in its untessellated form, so the
application could use them for things other than rendering, for example
collision detection.

GLU tessellation:
    http://www.glprogramming.com/red/chapter11.html
pyglet Batch:
    http://www.pyglet.org/doc/api/pyglet.graphics.Batch-class.html

Currently only a subset of SVG is handled - paths forming closed polygons,
filled with solid color. Each path may comprise multiple loops (disjoint areas
or holes), but must be made up from straight line edges. Arcs, beziers,
gradient fills and other SVG entities such as rectangles or text are not
currently handled.


Status
------

Nominally complete, and works with some simple SVG files that were generated by
Inkscape, but has not yet been used in earnest.

Inkscape:
    http://www.inkscape.org


Download
--------

You can import this package in your own Python projects by installing it to
your *site-packages* directory. If you have setuptools installed, do
this automatically with the command-line::

    easy_install svgbatch

Alternatively, download the source distribution from Google Code:

    http://code.google.com/p/svgload

The svgbatch directory from this can be incorporated as a package directly
within your own project's source, or else installed to your *site-packages*
using::

    python setup.py install

Finally, you could check it out from Subversion on Google Code:

    http://code.google.com/p/svgload/source/checkout 


Usage
-----

Very straightforward::

    svg = SvgBatch('data/logo.svg')
    batch = svg.create_batch()

`create_batch()` returns a pyglet Batch object, which can be rendered in
a pyglet program using `batch.draw()`. See `demo.py`:

    http://code.google.com/p/svgload/source/browse/trunk/demo.py

Your application can access the untessellated geometry of each path, indexed
by id, using::

    path = svg.path_by_id['pathid']

where `pathid` is the string ID of the path tag in the SVG file. A path's ID
can be set from within Inkscape by editing its object properties. The returned
Path object has the following attributes:

  * id: string, copied from the svg tag's id attribute
  * color: triple of unsigned bytes, (r, g, b)
  * loops: a list of loops. A loop is a list of vertices. A vertex is a pair of
    floats or ints.
  * bounds: an object which provides the axis-aligned extents of the path, as
    xmin, xmax, ymin, ymax.
  * offset(x, y): a method which will add the given offset to all vertices in
    the path


Known Issues
------------

  * It generally chokes on real-world SVG files other than the small ones I'm
    saving from Inkscape, due to unhandled SVG entities such as rectangles or
    text. Avoid this by just using closed, straight-edged paths filled with
    plain color.
  * I've only tested it on Windows. My lappy graphics chipset doesn't work for
    OpenGL stuff on Ubuntu since Jaunty. Thanks ATI.


Plans
-----

See TODO.txt:

    http://code.google.com/p/svgload/source/browse/trunk/docs/TODO.txt 


Acknowledgements
----------------

Many thanks to Martin O'Leary of supereffective.org, whos Squirtle module
formed a major inspiration for this project, and in particular for his
sublime tesselation code, which I have copied wholesale under the terms of the
BSD.

    http://www.supereffective.org/pages/Squirtle-SVG-Library 


This project's tests use voidspace's superbly useful mock library:

    http://www.voidspace.org.uk/python/mock


This project would be naught without the fabulous pyglet:

    http://www.pyglet.org 

