Kavlon Coloring Book 0.13
Michael McGlothlin <mogmios@mlug.missouri.edu>
4/25/04

This is an early version of this program and is still rough. It took my
spare time over about three days to put it together.. mostly spent
fixing dumb mistakes. Since then I've added new features and polish as
seemed fitting.

This is a simple coloring book program written in Python with Pygame. 
Python and Pygame must be present for this program to function. The
interface is simple. The user selects a page from the coloring book that
they'd like to paint. They then select a color they'd like to paint with
and click on the area of the picture they wish to paint. The user
proceeds this way until they are satisfied with the result. Next to the
color selection bar a small box shows the currently selected image. 
Along the left and right sides of the window are arrows that may be
clicked to page through the coloring book. At the bottom right is an
icon of a disk that when clicked will save the currently painted picture
in the snapshots directory. Next to the snapshot icon is an undo icon
that looks like a bomb.

After many requests I've added the ability to doodle freehand on the
coloring book. On the lower left of the screen is an icon for changing
tools. When you toggle the tool the cursor should change to indicate the
tool selected. In doodle mode hold down the left mouse button and drag
the cursor over the canvas to paint. To erase hold down the right mouse
button and drag.

The FPS might need tweaked to fit your system. You can set this with the
--fps=80 command-line option. Lower the value to use less CPU time and
raise the value to improve the response time. You may also want to
change the process priority in your OS to adjust the programs behavior.

To add new pages to the coloring book create a sample image and a Python
file of the same name ( eg 'ABC.py' and 'ABC.png' ) and put them in the
'books/<book>' subdirectory. If you create new pages you'd like to share
please email them to me.

Each page has a canvas of 600x400 on which an image can be composed. The 
image is composed using layers of image fragments. When being drawn the 
canvas draws from the first (bottom) layer to the last (top). When a 
user is painting the top layer found at the click point is chosen for painting 
and only that layer will be painted. All canvases will have a background 
layer as the bottom layer.

Every page uses a Python file to tell it what source image to use and 
how to map image fragments from the source image onto the canvas. Two 
variables hold this information. 'image' should be assigned a string 
with the source images file path. 'map' should be assigned a sequence. 
Each element of map represents one layer on the canvas. Each element 
is itself a sequence consisting of a rectangle of the area of the source 
image being used and a destination position on the canvas where the 
fragment should be placed.

The source image should consist of image fragments that will be
recomposed to produce the page image. Each fragment should consist of a
mask created with the LAYER_MASK color and the CANVAS_MASK color with
any desired extra colors used to add borders and accents.  These colors
are listed in 'locals.py' and by default are #EEEEEE and #777777. Areas
of the LAYER_MASK color will be paintable and areas of the CANVAS_MASK
color will be masked out when the image is recomposed.
