-------------------------
                   freehand drawing tool
                    
                   Copyright 2012 L. Konneker
                   -------------------------

About
=====

A freehand drawing tool.
Where a tool is a user interface object, something a user uses.
A freehand drawing tool is a component of a vector graphics drawing app.

Input: pointer device (e.g. mouse) events, from the app
Output: graphic vector path (lines and splines) which the app (via a GUI toolkit) renders.

Includes a rudimentary GUI app for testing (draw with LMB, distort with key or Ctl-key)

Written in pure Python.
Emphasis on domain objects and class/responsibility/collaboration documentation.

Tags:
- freehand drawing.
- computational geometry.
- incremental (dynamic) line tracing.
- Python coroutines.
- pipe of filters.
- GUI toolkit Qt.

References:
- Derived from potrace by Peter Selinger.
- Object model somewhat similar to Shapely/GEOS

See much more technical discussion in the code.


Versions
========

See CHANGELOG.


Serialize/Deserialize
======================

The output SegmentString, a QGraphicsPathItem, does not pickle.
But QPainterPath implements << for serializing, and it's not hard to do (it's not in this package.)

Cuspness is not currently serializable/deserializable, only exists just after SegmentString creation.


Directory structure and distribution
====================================
The top directory freehandTool includes a demo app, freehandApp.py.
It also include other distribution artifacts e.g. setup.py.

The directory freehandTool.freehandTool is the main Python package of the tool.
In that package, freehand.py is the main program for the tool.
Also in the package are pointerEvent.py and ghostLine, glue between the tool and the app.

The directory freehandTool.freehandTool.generator is a Python package that the tool calls (the low-level implementation.)

The Python distribution (a zipped archive) includes only the package freehandTool.freehandTool and subpackages,
but not the demo app.


The demo app
============

Draw with the mouse left button down.
Any key modifies an arbitrary control point (the second one?)
A key with control key also down modifies said control point while maintaining cuspness.

A real app would have an alternate user interface for editing (dragging?) control points.


Installing
==========

If you clone the git repository, you can change directory to the project directory and simply execute freehandApp.py.

It is not useful to install as a Python package in the standard place, 
unless you have written your own app that uses the freehand tool.  
In that case, the setup.py scripts are in the project.
You should produce a distribution archive (>python setup.py sdist),
copy and upack the archive somewhere else,
cd to that directory,
and install it (>python setup.py install).
(The archive in the repository at dist/freehandTool-0.1.tar.gz
is only the tool and not the demo app,
and the archive may not be up to date.)