PIKApp/plug-ins/gfig/README

Objects
+++++++

The plug-in allows you to draw the following shapes:-

Lines
Circles
Ellipses
n sided regular polygons (n >=3)
Curves (arcs)
Spirals
N pointed stars
Simple Beizer curves

An object is constructed as a number of control points and these are used 
to select the object on the drawing area once it has been created.

The drawing area preview is currently set to 

	MIN(650 x 650,img_width x img_height). 

You can change this altering the PREVIEW_SIZE item in the source code. 

Operations
++++++++++

The following operations can be performed on objects:-

The objects can either be moved independently around the drawing area or 
all together.

Each control point can be moved.

Objects can be copied.

Objects can be deleted.

N sided Polygons can be split into N line segments. This also works for N 
pointed stars.

The drawing area can be scaled.

Control points can be hidden.

To aid alignment of objects a "grid" can be placed on the drawing area.
This can be either a normal rectangular grid or a polar type grid centered 
in the drawing area. 
The spacings of the grid can be changed as well as the colors used to draw the
grid lines. When "Snap to grid" is checked then all operations will be 
constrained to fall on a grid intersection. (Fun when using the polar grid).
Additionally the third mouse button will constrain the point movement to be
on a horiz/vert (for rect grid) or radial/radius (for polar) only when 
"Snap to grid" is set.

The image that was selected when Gfig was started can also be shown (scaled) in
the drawing area. (Options tag).

Painting tab
++++++++++++

There are three possible mode when painting.

1) Brush
2) Selection
3) Selection+fill 

Brush
~~~~~
When the paint button is pressed each object will be rendered/drawn onto 
the image using the currently selected ink color. The objects can be drawn 
onto the original layer or onto a new layer (either a single layer or 
multiple layers - latter is good for animations). When new layers are 
created the background can either be:-
	
Transparent.
Background (the current BG color).
White.
Copy.

The last option means that the layer is duplicated from the previous layer 
before the draw operation is performed (re good for animations).

Lines can be drawn in reverse order. This means that reg polygons/curves/lines 
that are normally constructed of lines can be drawn starting at either "end". 
This is only noticeable when the current brush has fading turned on.
The "Approx Circles/Ellipses" toggle allows the same effects when drawing these
types of objects.

Note that in the current version any selections present in the image are first 
de-selected when Gfig starts up. This is because selections are used to 
draw circles and ellipses (unless the Approx. Circles & Ellipses toggle is set).

Selection
~~~~~~~~~
With this method closed selections are made of the objects. See selection
tab for more details.

Selections can only be made on the current layer.

Selection+Fill
~~~~~~~~~~~~~~
This method first selects the objects and then fills the selection area. The
selection tab gives more details on how the selections are filled.


Brush Tab
+++++++++

This tab now contains a preview of the selected brush in black ink. If the
brush is too large to fit in the preview use the mouse button to "move" it
around (as with the brush dialog in the main PIKA - until that brush 
patch went in!).

Four types of brush can be used:-

Normal brush
~~~~~~~~~~~~
Simply paints with the current brush - honors fading if any
The Fade option allows the "brush fading" to be selected. I am sure that some
nifty anims can be created with this option. 

Pencil brush
~~~~~~~~~~~~
Same as the PIKAS pencil. 

Airbrush
~~~~~~~~
As PIKAS airbrush. The "pressure" can be specified and this is reflected in the
preview window.

Pattern
~~~~~~~
The lines are drawn with the currently selected pattern. The preview will
show this pattern.

Note a patch to enable a couple of "hidden" paintbrush features was recently
posted to the PIKA developers list. The patch only allowed these features
to be called via the UI and not the PDB so they cannot be used by Gfig. If they were exported via the PDB then they would have probably broken a number of 
scripts and Gfig itself (number of args changes on the PDB call).

Select tab
++++++++++

This is enabled when using either Selection or Selection+fill types when
painting objects.

The anti aliasing and feather toggles apply to the selection made when 
"painting" the objects. The feather radius can be changed.

The default selection mode is to add to the current selection so each object
add to the overall selection. The other selection modes are also possible
but you must bear in mind the following:-

Subtraction/Intersection will not produce any selection if no selection is 
elect the area in the target window (AFTER starting Gfig up) and then paint 
using this method.

Replace will leave only the last object selection.

When the paint type is selection+fill then the objects will be selected 
and then filled. The opacity of the fill can be chosen. By default a fill
is performed after each section. If filling onto a single layer
then the fill will accumulate on the first objects painted. This will be 
noticeable when opacity != 100. To get around this then use replace mode
OR use a new layer for each selection/fill. (Paint tab). Additionally you can
set the fill to be performed after ALL objects have been selected (useful
for intersection type selections).

Selection of non-closed objects
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For objects that are not closed the first & last points will be joined 
together to form the closed selection. For arcs you can either fill
as segments or sectors. Note straight lines will not cause any selection to be
made. This can be a little confusing when filling since the whole canvas will
be filled if any straight lines are present on it.


Scaling
+++++++

When Gfig first comes up the selected group of objects are automatically scaled 
upwards to the image size. (If the source image is < 256*256 then no automatic 
scaling is performed - change PREVIEW_SIZE in source to alter this values).
By toggling the scale button the objects can then be scaled in the drawing 
area. This scaling will be reflected when the objects are drawn.
To reposition the objects on the drawing area use SHIFT + MOVE_OBJ operation.


Other ops
+++++++++

Double click on reg polygon object selection to get dialog with slider to 
selected the number of sides to draw.

Double click on star object selection to get dialog with slider to 
selected the number of points the star will have.

Double click on spiral object selection to get dialog with slider to 
selected the number of turns the spiral will have and it direction.

Double click on bezier object selection to get dialog which allows you to
control how the curve is displayed and if it is closed.

SHIFT + MOVE_PNT will break a reg polygon or star into a number of 
connected lines.

When drawing lines if the SHIFT modifier is used then connected lines 
can be drawn.

SHIFT + MOVE_OBJ will move all objects. Note if "snap to grid" is selected then
the new point will be constrained to fall on a grid intersection.

Mouse button 3 + "snap to grid" will constrain the point to fall on one of the
two gridlines it was originally on.

The ">" and "<" buttons allow you to selective move through each of the 
objects in the collection. The "==" returns the display to normal. If the
"paint" button is pressed then only the single object displayed will be 
drawn into the target window. Also when in this mode pressing the shift button
will temporarily show all the objects in the collection.

The the options tab there is now a toggle that allows you to turn the 
position display on and off.

Gfig objects
++++++++++++

The upper right part of gfig contains a scroll region when different 
collection of objects can be found. When button 1 is pressed on an entry 
the small preview window will be updated with the objects contained in 
the selected figure. These objects can then be loaded into the main window 
by using the "Edit" button or the "Merge" button. In the former case 
the objects area will first be cleared before the new objects
are added. In the latter case the objects will be merged into the drawing area.

When a collection of objects is altered to small image of a floppy disc 
will be placed next to the entry signifying that this collection needs to be 
saved. If a red cross appears here then the file associated with the 
entry is read only and cannot be saved to (it can be copied however).

Button 3 brings up a popup menu that allows collections to be saved away to 
different files. (Accel. keys also exist for some functions).

The buttons on the right of the list area allow the following operations:-

Rescan:-
This popus up a window which allows you to add directories to the internal 
gfig-path.  A (re)scan of these directories can the performed. Note any 
modification to the gfig-path will NOT be mirrored in your ~/.pika/pikarc file.

Load:-
Allows you to load a single collection of objects.

New:-
Create a new collection. Note that until this is saved away to a file then no
filename will be associated with it. (See status area).

Delete:-
Popups a dialog asking if you wish to delete the entry selected in the list 
box as well as on disc.

Additionally button 3 over the list area allows the following:-

Save as...:-
Save collection to new filename. The collections filename is also 
changed to this new name. The original name is NOT deleted from the disc 
but it is effectively removed from the list selection area (actually it 
is overwritten internally).

Save:-
Save the currently selected entry to disc.

Copy:-
Make a copy of the collection.

Edit:-
Same as the "Edit button".

Double click on entry with Button 1 popups up a dialog that allows you to 
modify the nme of an entry (similar to other list areas in PIKA).

Bezier
~~~~~~

OK my maths is a little rusty. The bezier stuff is only very simple. However...
I have tried to abstract as much as possible the bezier calculations from
the drawing of the control points / painting on the screen and in the target
window. 

The bezier function is defined as:-

void
DrawBezier (gdouble (*points)[2], gint np, gdouble mid, gint depth)
{
...
}

Points an array of pairs of doubles that define the control points
np is the number of points. Mid is always starts as 0.5 - and depth
defines how deep the recursion should go when calculating the line points.

The function should call fp_pnt_add() when a point on the curve has been
calculated. 

If anyone would like to produce a better/faster function then you
should be able to replace the DrawBezier function. (Only the first two args
are really needed). 

The algorithm the current code is based on was obtained by looking 
at the many many examples out on the web.
(Bezier drawing seems to be topic of the year for computer degrees 
and people learning java!!!)