# PIDDLE

### Plug-In Drawing, Does Little Else

### Abstract

PIDDLE is a Python module for creating two-dimensional graphics in a manner that is both cross-platform and cross-media; that is, it can support screen graphics (e.g. QuickDraw, Windows, Tk) as well as file output (PostScript, PDF, GIF, etc.). It makes use of the native 2D drawing calls of each backend, for maximum efficiency and quality. It works by defining a base class (piddle.Canvas) with methods for all supported drawing primitives. A particular drawing context is provided in the form of a derived class. PIDDLE applications will be able to automatically select an appropriate backend for the user's environment.

### NEWS

2002-02-08: After a long hiatus, I've uploaded version 1.0.14. This is the first version to use distutils. Installation should now be as easy as "python setup.py install" I've also thrown in more exprimental backends--better to get them out there than just have them languish. The new backends include SVG, GTK, Xfig, and improved TK support. Thanks to all who contributed code! Note, I've dropped the "b" marking the beta nature of the distribution. Got tired of keeping track of whether it's a beta package or not. You should view the documentation to see which backends are solid and which are exprimental (see below). Because of the not-so-positive connotations of the name "piddle", I have put together a a development version with the same functionality and interface under the the name "SPING" (Simple Platform Independent Graphics). I'm looking for feedback on the name choice and if you have a better name, please let us know on the piddle mailing list pythonpiddle@yahoogroups.com . In addition to the name change, Sping is designed to be used as a python package and is being developed using the Python Imaging Library version 1.1. To make it easier to use PIL 1.1 on Windows, I've made a binary version of PIL 1.1 available as well (compiled under tk/tcl version 8.0.5). You can download the latest versions of Sping and PIL-1.1-win32-bin . If you have problems reaching these links go to the alternative download page .

Important note: Sping 1.1.x, with it's odd numbered point release, is the development branch of piddle, also known as the unstable branch. Stick with the piddle-1.x releases if you require more guarantees of a stable and fixed api. On the other hand, if you need new features, Sping-1.1.x is where they'll be added.

### Status

PIDDLE is reaching the end of beta testing and with the 1.0 stable release of select backends coming soon (4th quarter 2000 is the current best guess). The PDF, PIL, wxWindows, PS, TK, and Quick Draw backends are solid. The other backends will be included in the 1.0 distribution with opportunities for further development in the development version (versions 1.1.x). If you do find a bug still lurking, please send email to the PIDDLE mailing list at pythonpiddle@yahoogroups.com .

### Piddle and Python 2.0

Piddle itself works perfectly with Python 2.0 and above. If you are upgrading, make sure to upgrade/recompile any extension modules that you wish to use (e.g. PIL) so that they work with Python 2.0 as well.

### Downloads

- The latest stable is available from our Source Forge download page here in the form of .zip and .tgz archives. If you receive a "security error" when attempting to access the download page, your browser probably does not support the "https" protocol. You may download from the alternative download page instead.
- You may also want to look at CVS access and other information for developers if you want the latest experimental version. Visit the Sourceforge Project Page at https://sourceforge.net/projects/piddle/ to submit or view bug reports.
- PIL support: PIL binaries for win32 are available from the PIL downloads page

As of Febuary 8, 2002, the current release is 1.0.14 , however, see the download page for the latest information.

As of 12 December 2000, the current release is 1.0b13 , however, see the download page for the latest information.

Please note that PIDDLE requires Python 1.5.2, because it uses the "extend" list method, which is not available in older versions of Python. In addition, it now includes distutils support which can be added to Python 1.5.2, but which comes by default with versions 1.6, 2.0 and above.

The standard distribution includes the following back-end renderers:

Backend | Requires | Author | Maintainer | Interactive? | Notes
--- | --- | --- | --- | --- | ---
PDF |  | Andy Robinson | Andy Robinson | No |
PIL | PIL | Joe Strout | Chris Lee | No |
QuickDraw | MacPython | Joe Strout |  | Yes |
PostScript |  | Magnus Lie Hetland | Chris Lee | No |
Illustrator |  | Bill Bedford |  | No |
piddleVCR |  | Joe Strout | Chris Lee | No |
OpenGL | PyOpenGL | David Ascher | (unmaintained) | Yes |
Tk | Tkinter | Perry Stoll | Chris Lee | No | [1]
wxWindows | wxPython | Kevin Jacobs | Kevin Jacobs | Yes |

Notes:

[1] piddleTK relies upon piddlePIL for the drawing of rotated strings.

The following backends are in various stages of development, and not yet fully compliant. They are now included in the official distribution to encourage experimentation and improvements

name | author | strings | images | interactive
--- | --- | --- | --- | ---
GTK+ | Fred L. Drake, Jr. | Y/N [6] | N | Y
Pythonwin | Andy Robinson | Y [5] | N | N
piddleSVG | Greg Landrum | ? | ? | ?
piddleFIG (XFig) | John Lee | Y/N [7] | Y [8] | N

Notes:

[5] winpiddle's string drawing is having some trouble with size and color attributes; also, the text background is not transparent as it should be. Unclear whether rotated strings are supported yet.

[6] piddleGTK doesn't yet draw rotated strings, but it is planned.

[7] piddleFIG string widths are wrong at the moment

[8] piddleFIG images must be stored separately from the .fig file itself since the .fig format only allows images to be included by referring to them by filename

### Usage Overview

PIDDLE is designed for vector graphics -- i.e., drawing of primitives such as lines and ellipses, rather than manipulation of individual pixels. Generally, one creates a PIDDLE drawing in four steps:

1. instantiate a class derived from piddle.Canvas
2. call drawing methods on that object, such as drawLine or drawString
3. flush the canvas's buffer (i.e., flush the graphics pipeline, update the screen, or whatever)
4. Save the canvas's current view to a file if one is desired.

Note that while PIDDLE is easiest to use in a noninteractive mode -- i.e., simply generating charts, pictures, or other static displays -- some backends support callback methods invoked when the mouse moves over or clicks on the drawing. This allows for some graphical interaction with the user. The canvas save() operation is most relevant to file-based backends (e.g. piddlePDF) while the flush() command is most relevant to backends that produce on-screen graphics.

### Developer's Overview

Creating a new PIDDLE backend is relatively easy. You must create a class derived from piddle.Canvas, and instantiate at least the following methods:

- drawLine
- drawPolygon
- drawImage
- drawString

All other drawing methods will have default implementations in terms of the functions above. However, you may wish to also override other drawing methods for the sake of efficiency or quality.

### Documentation

#### PIDDLE White Paper

#### PIDDLE Reference Manual

In addition, information specific to individual backends are placed in the docs/notes* directories

### Examples

This example illustrates a hodgepodge of PIDDLE drawing commands, including lines, curves, polygons, arcs, roundrects, and rotated text. The graphic shown here was rendered with the QuickDraw backend; other backends may vary, especially in the appearance of the text. |
This spectrum chart is actually a useful program; I needed to generate a spectrum for a scientific application, and this is the PIDDLE program I used to do it. In this program, I defined a factory function 'makeCanvas' at the top of the program to create the canvas. To use a backend other than QuickDraw, you'll only need to modify this function. |
A string test module puts PIDDLE's font and string handling through the paces. It illustrates the standard fonts which every backend should be able to understand (and hopefully display). |
A string rotation test module exercises the drawing of rotated strings at a variety of angles (in rainbow colors, no less). Example output is shown for both QuickDraw and PIL. Note that the two have somewhat different ideas about how big a 12-point (default) font should be; this sort of discrepancy is inevitable, at least for now. |

More examples are included with the distribution in the examples directory and in piddletest.py, a file which allows you to select any test, and pair it with any standard backend renderer.

### Credits & Feedback

PIDDLE was initially designed and implemented by a small international team of Python coders. There is a mailing list for discussion of PIDDLE at http://groups.yahoo.com/group/pythonpiddle . To get your feedback to the list send email to pythonpiddle@yahoogroups.com .

Hosted by: