svgbatch
--------

The latest version of this documentation is online at `http://pypi.python.org/pypi/svgbatch`__

__ http://pypi.python.org/pypi/svgbatch

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

__ http://www.w3.org/TR/SVG11
__ 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.

__ http://www.glprogramming.com/red/chapter11.html
__ 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.

Dependencies
------------

Only tested on Windows, but should be cross-platform. Only tested on Python 2.5 and 2.6. Requires the fabulous `pyglet`__.

__ http://www.pyglet.org 


Status
------

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

__ http://www.inkscape.org


Download
--------

You can install *svgbatch* to your *site-packages* directory, making it
available for import by any Python programs on your computer. The automated way
to do this is to install setuptools, then use the command-line::

    easy_install svgbatch

The manual way to do the same thing is to download the source distribution
from the bottom of `the project PyPI page`__ and install manually, using the command-line::

    python setup.py install

__ http://pypi.python.org/pypi/svgbatch

Alternatively, the *svgbatch* package from the above source distribution can
be copied directly into your own project, which might be useful if you intend
to modify it.

Finally, to get the very latest (possibly broken) version, you might want to
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/svgbatch/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 representing a
    closed polygonal boundary (which may be convex.) A vertex is a pair of
    floats or ints.
  * ``bounds``: an object which provides the path's axis-aligned extents, as
    ``xmin``, ``xmax``, ``ymin`` and ``ymax``.
  * ``offset(x, y)``: adds 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__, whose 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
__ http://www.supereffective.org/pages/Squirtle-SVG-Library 


This project's tests use a slightly-modified embedded copy of `voidspace's
superbly useful mock library`__.

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


